user-engine/workplans/USER-WP-0007-identity-domain-canon-alignment.md

---
id: USER-WP-0007
type: workplan
title: "Identity Domain Canon Alignment"
domain: netkingdom
repo: user-engine
status: proposed
owner: codex
topic_slug: netkingdom
planning_priority: high
planning_order: 7
created: "2026-06-05"
updated: "2026-06-05"
depends_on:
  - USER-WP-0006
---

# 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: todo
priority: high
```

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: todo
priority: high
```

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: todo
priority: high
```

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: todo
priority: high
```

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: todo
priority: medium
```

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: todo
priority: medium
```

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: todo
priority: medium
```

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: todo
priority: low
```

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