---
id: USER-WP-0007
type: workplan
title: "Identity Domain Canon Alignment"
domain: communication
repo: user-engine
status: finished
owner: codex
topic_slug: netkingdom
planning_priority: high
planning_order: 7
created: "2026-06-05"
updated: "2026-06-05"
depends_on:
  - USER-WP-0006
state_hub_workstream_id: "ae9d3683-817e-439a-94e6-29989cb3221d"
---

# USER-WP-0007 - Identity Domain Canon Alignment

## Goal

Bring `user-engine` scope into alignment with its revised intent: make it the
NetKingdom identity-domain integration layer that exposes identity-canon aligned
user, account, actor, principal, subject, tenant, team, membership, profile,
lifecycle, and evidence context without absorbing identity provider,
credential, authorization, security-control, audit-platform, or organization
authority responsibilities.

## Scope Direction

`user-engine` should implement identity-canon entities when they are
user-domain facts or identity-context mappings. It should consume or reference
NetKingdom-owned entities when the source of truth belongs to IAM, security,
authorization, governance, audit, secrets, or organization systems.

The target integration question is:

```text
For this domain request, who is the actor, which user/account/principal/subject
context applies, which tenant/team/application scopes are relevant, which
identity-domain facts may be projected, and what evidence or lifecycle work
exists for that context?
```

## Non-Goals

- Do not turn `user-engine` into an identity provider.
- Do not implement passwords, passkeys, sessions, MFA, token issuance, or
  credential lifecycle.
- Do not become the policy decision point or final authorization authority.
- Do not own NetKingdom security controls, runtime secrets, or durable platform
  audit infrastructure.
- Do not become the full organization, HR, directory, or governance authority.
- Do not rename the repository as part of this workplan without a separate
  naming decision record.

## Tasks

```task
id: USER-WP-0007-T1
status: done
priority: high
state_hub_task_id: "09bf2de5-0dab-4c21-845a-ff7dbde4cbd8"
```

Create a Canon Interface Card for `user-engine` that declares produced,
consumed, owned, mapped, and explicitly non-owned InfoTechCanon concepts. Cover
User, Account, ExternalIdentity, Actor, Principal, Subject, Tenant, Team,
Membership, Organization Role reference, AccessRole reference, Policy reference,
Control reference, Evidence reference, AccessReview reference, and lifecycle
work.

```task
id: USER-WP-0007-T2
status: done
priority: high
state_hub_task_id: "8d10eaf7-12ac-4a7c-bf90-ded6fc59eeb4"
```

Create entity and edge mapping exports for current domain objects. Map existing
models and service operations to canon concepts and relationships including
`member_of`, `belongs_to_tenant`, `authenticates_as`, `evaluated_as`,
`assigned_role`, `scoped_to`, `governed_by`, `implemented_by`,
`evidenced_by`, and `creates_task`.

```task
id: USER-WP-0007-T3
status: done
priority: high
state_hub_task_id: "c3839ae6-5d82-4cfd-819a-79b3bdf6efa6"
```

Define the first identity-context read model. It should resolve a verified
NetKingdom actor into domain-facing user, account, identity link, principal,
subject, tenant, team, membership, application, and profile projection context
without requiring consumers to know IAM provider details.

```task
id: USER-WP-0007-T4
status: done
priority: high
state_hub_task_id: "2d29ceec-2d0b-4753-82cc-3fd87a252ba1"
```

Add explicit canon-facing distinctions where current code only has implicit
fields. In particular, distinguish User, Actor, Principal, Subject, Account,
ExternalIdentity, Organization Role reference, AccessRole reference,
Membership, and Grant or grant-like membership facts.

```task
id: USER-WP-0007-T5
status: done
priority: medium
state_hub_task_id: "1ad927a2-eca7-4904-a666-600617cb7519"
```

Add NetKingdom adapter contracts for identity-domain implementation. Preserve
the existing ports while adding or documenting adapters for IAM Profile claims,
authorization decisions and obligations, membership fact export, evidence or
audit reference export, policy/control references, and lifecycle task handoff.

```task
id: USER-WP-0007-T6
status: done
priority: medium
state_hub_task_id: "cb0dbd53-fb9a-4b84-87d8-e7cc3ce4ab40"
```

Add evidence and review references without taking over governance ownership.
Identity-domain mutations, privileged memberships, delegated agent context,
break-glass context, and tenant admin grants should be traceable to audit,
review, approval, exception, remediation, or explicit evidence gaps.

```task
id: USER-WP-0007-T7
status: done
priority: medium
state_hub_task_id: "973bf3c5-e407-4441-a2e6-c9c8d5e55135"
```

Add small-SaaS canon conformance scenarios. Cover Ada Admin, Acme, Globex,
tenant isolation policy, namespace-per-tenant control, access review evidence,
tenant onboarding work, explicit grant scope, and integration gaps that become
tracked work rather than silent scope drift.

```task
id: USER-WP-0007-T8
status: done
priority: low
state_hub_task_id: "e6285175-7b71-4a57-9183-dab8274f19a6"
```

Create a naming decision record after the alignment artifacts exist. Compare
keeping `user-engine` with renaming to `identity-engine`,
`identity-domain-engine`, or another name. Decide based on actual implemented
scope, consumer expectations, and risk of implying ownership of full IAM or
organization responsibilities.

## Acceptance Criteria

- `INTENT.md`, `SCOPE.md`, and public docs consistently describe
  `user-engine` as the NetKingdom identity-domain integration layer.
- A completed Canon Interface Card exists for `user-engine`.
- Entity and edge mapping exports cover current user-engine models and mark
  gaps explicitly.
- Consumers can ask for identity-domain context without knowing the concrete IAM
  provider, authorization system, audit sink, or security-control
  implementation.
- User, Actor, Principal, Subject, Account, ExternalIdentity, Tenant, Team,
  Membership, Organization Role reference, AccessRole reference, Grant or
  grant-like fact, Policy reference, Control reference, Evidence reference, and
  AccessReview reference are distinct or explicitly mapped gaps.
- Tenant-scoped privileged access can be traced to scope, decision, policy or
  control reference, and evidence or evidence-gap record.
- Small-SaaS conformance scenarios pass or produce explicit, owned gap records.
- The repository name remains unchanged unless a separate naming decision is
  accepted.

## Expected Outputs

- `docs/canon-interface-card.yaml`
- `docs/canon-mapping.md` or generated equivalent
- identity-context read model and tests
- NetKingdom adapter contract updates
- small-SaaS canon conformance tests
- evidence-gap and lifecycle task examples
- naming decision record

## Implementation Notes

Implemented on 2026-06-05:

- Added `CanonEntityReference` and `CanonRelationshipReference` domain shapes.
- Added `UserEngineService.identity_context(...)` as the first canon-facing
  identity-domain read model.
- Added adapter contracts for evidence export, policy/control references, and
  lifecycle task handoff.
- Added `docs/canon-interface-card.yaml`, `docs/canon-mapping.md`,
  `docs/evidence-gap-examples.md`, and
  `docs/identity-domain-naming-decision.md`.
- Updated scope, contracts, NetKingdom integration docs, README, and scenarios.
- Added executable identity-canon alignment tests for distinct user/account/
  subject/principal context, service-account projection, small-SaaS tenant
  isolation, and claims-enrichment context.

Verification:

```text
make test
Ran 35 tests in 0.175s
OK
```