Align user-engine intent with identity canon

INTENT.md

@@ -6,10 +6,11 @@
 
 ## Purpose
 
-`user-engine` exists to provide a reusable, headless user-domain service for
+`user-engine` exists to provide a reusable, headless user-domain and
-products and platforms that need account, profile, preference, membership, and
+identity-domain service for products and platforms that need account, profile,
-application-specific user attribute management without coupling those concerns
+preference, membership, identity-context, and application-specific user
-to a particular identity provider, authorization engine, or user interface.
+attribute management without coupling those concerns to a particular identity
+provider, authorization engine, security stack, or user interface.
 
 ## Primary Utility
 
@@ -21,6 +22,7 @@ It manages:
 
 - users and account state;
 - external identity links;
+- actor, principal, subject, and user-context mappings;
 - profile and preference data;
 - tenant, application, and team memberships;
 - application-registered customization attributes;
@@ -28,24 +30,58 @@ It manages:
 - profile projections for consuming applications;
 - lifecycle and profile-change events.
 
+## Strategic Direction
+
+`user-engine` is intended to become the NetKingdom identity-domain integration
+layer: a headless service that exposes canonical identity, user, account,
+membership, tenant, team, profile, lifecycle, and evidence-facing concepts to
+applications without requiring those applications to know the technical IAM,
+security, authorization, audit, or secret-management implementation details.
+
+NetKingdom infrastructure remains the source of truth for authentication,
+credential assurance, token issuance, policy decisions, security controls,
+runtime secrets, and platform audit infrastructure. `user-engine` consumes those
+capabilities through explicit adapters and presents a stable domain model
+aligned with identity-related InfoTechCanon concepts.
+
+In this role, `user-engine` should make identity-domain questions easy for
+applications and agents to answer:
+
+- who the current actor is in a domain context;
+- which user, account, external identity, principal, or subject references are
+  involved;
+- which tenant, team, application, and membership scopes apply;
+- which user-domain facts may be projected into runtime, admin, audit, agent, or
+  claims-enrichment contexts;
+- which lifecycle, access-review, evidence, or integration gaps need attention.
+
 ## Strategic Role
 
 `user-engine` separates user-domain management from authentication,
 authorization, credential lifecycle, and UI experience concerns.
 
-It is intended to integrate through standards-aligned interfaces with identity
+It is intended to integrate through standards-aligned interfaces with
-providers, provisioning sources, directories, authorization systems, event
+NetKingdom IAM, identity providers, provisioning sources, directories,
-sinks, and optional UI surfaces while remaining useful in simple standalone
+authorization systems, security controls, event sinks, audit infrastructure, and
-deployments.
+optional UI surfaces while remaining useful in simple standalone deployments.
+
+It may implement identity-canon entities when they are user-domain facts or
+identity-context mappings. It should reference, map to, or consume adjacent
+canon entities when their source of truth belongs to NetKingdom infrastructure,
+security, access-control, governance, or organization systems.
 
 ## Intended Users
 
 - application developers adding user/account functionality to a service;
-- platform teams managing users across multiple applications;
+- platform teams integrating NetKingdom identity infrastructure across multiple
+  applications;
 - product teams needing self-service account and preference capabilities;
 - operators and tenant administrators managing scoped user populations;
 - agentic systems that need structured access to user preferences and profile
-  context.
+  context;
+- domain services that need identity-canon aligned user, actor, principal,
+  subject, tenant, team, membership, and evidence references without depending
+  on technical IAM implementation details.
 
 ## Product Boundaries
 
@@ -56,11 +92,15 @@ It does not aim to be:
 - a full identity provider;
 - a password, passkey, session, or MFA system;
 - a fine-grained authorization engine;
+- the policy decision point for protected resources;
+- the owner of NetKingdom security controls or runtime secrets;
+- the full organization, HR, or directory authority;
 - a directory server;
 - a UI application.
 
-It provides the user-domain APIs, catalog metadata, projections, events, and
+It provides the user-domain and identity-domain APIs, mapping records, catalog
-audit records that those surrounding systems can consume.
+metadata, projections, events, evidence references, and audit records that those
+surrounding systems can consume.
 
 ## Design Principles
 
@@ -70,15 +110,25 @@ audit records that those surrounding systems can consume.
 - enterprise-integratable;
 - identity-provider agnostic;
 - authorization-engine agnostic;
+- NetKingdom-integrated without hiding source-of-truth boundaries;
+- canon-aligned through explicit entity and relationship mappings;
 - catalog-driven customization;
 - explicit ownership, visibility, mutability, and sensitivity of attributes;
 - layered profiles instead of one global metadata blob;
 - deterministic and inspectable effective profile resolution;
+- evidence and lifecycle awareness for identity-domain changes;
 - concrete user-domain focus with a possible future extraction path toward a
   generic profile engine.
 
 ## Success Definition
 
 `user-engine` succeeds when a repository or application can add robust
-user-domain capabilities with minimal coupling while keeping a clear path from
+user-domain and identity-domain capabilities with minimal coupling while keeping
-a simple local setup to a governed multi-tenant, multi-application deployment.
+a clear path from a simple local setup to a governed multi-tenant,
+multi-application NetKingdom deployment.
+
+It should also succeed as an implementation surface for identity-related canon
+intent: applications should be able to consume user, account, identity-link,
+actor, principal, subject, tenant, team, membership, profile, lifecycle, and
+evidence context through stable APIs and mappings without taking a direct
+dependency on the technical IAM, authorization, security, or audit substrate.

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

@@ -0,0 +1,179 @@
+---
+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