user-engine/docs/canon-interface-card.yaml

subsystem: user-engine
description: >
  NetKingdom identity-domain integration layer for user, account, identity-link,
  tenant, membership, profile, lifecycle, and evidence-facing context.
status: candidate
owner: codex
updated: "2026-08-19"

implements:
  - identity-canon conceptual model as an implementation-facing domain facade
  - InfoTechCanon user-engine evaluation pack
  - small-saas user-management alignment surface

produces:
  - User
  - Account
  - Identity Record
  - Scoped Identifier
  - Profile
  - Tenant
  - Membership Relationship
  - Authenticated Subject reference
  - Authorization Principal reference
  - Evidence Source reference
  - Access Grant or grant-like membership fact

consumes:
  - NetKingdom IAM Profile v0.3 claims
  - verified issuer and subject identifiers
  - assurance and principal type claims
  - optional tenant_roles forwarded to flex-auth only
  - authorization decisions and obligations
  - policy, control, review, exception, and evidence references
  - lifecycle task references from downstream task systems
  - platform audit and event sinks

owned_concepts:
  user_record: User-engine local user record mapped to identity-canon User as a convenience term.
  account_record: Operational account state for a user-engine scope.
  external_identity_link: Source-specific issuer and subject link to a user record.
  profile_value: Scoped profile or preference value.
  membership_fact: User-domain relationship to tenant, team, application, or scope.
  identity_context: Canon-facing read model over user, account, actor, subject, principal, scope, memberships, profile, and evidence references.

mapped_not_owned:
  Actor: Consumed from verified identity claims and represented as canon reference.
  Authenticated Subject: Projected from issuer and subject after authentication.
  Authorization Principal: Projected for the authorization system; final decisions remain outside user-engine.
  Policy: Referenced from authorization/governance systems.
  Control: Referenced from security/governance systems.
  Evidence Source: Referenced from audit, review, approval, or verification systems.
  AccessReview: Referenced from governance or review systems.
  Organization: Referenced when tenants, teams, or users map to organization systems.
  Credential: Explicitly not stored or lifecycle-managed by user-engine.

accepted_relationships:
  - identity_link
  - belongs_to_tenant
  - authenticates_as
  - evaluated_as
  - member_of
  - role_label
  - scoped_to
  - governed_by
  - implemented_by
  - evidenced_by
  - creates_task

emitted_events:
  - user.created
  - account.status_changed
  - tenant_account.status_changed
  - identity.linked
  - membership.added
  - profile.value_set
  - application.registered
  - catalog.published

required_identifiers:
  actor_key: "issuer + subject"
  user_id: "opaque user-engine user id"
  account_id: "opaque user-engine account id"
  identity_id: "opaque user-engine external identity id"
  tenant: "NetKingdom-aligned tenant or platform scope"
  application_id: "registered application id when projection is application-scoped"
  correlation_id: "operation-level audit and event correlation id"

mapping_rules:
  - Resolve source terms such as user, group, role, tenant, subject, and principal into identity-canon layers before exposing them as implementation concepts.
  - Keep account records, authenticated subjects, and authorization principals distinct even when they share issuer or subject identifiers.
  - Treat memberships as relationship facts that may produce grant-like access facts, not as final authorization decisions.
  - Preserve source system, scope, lifecycle state, and evidence reference whenever a relationship affects access, privacy, or lifecycle.
  - Link policy, control, review, exception, and task concepts by reference unless user-engine is the actual source of truth.

validation_rules:
  - User, Account, Actor, Authenticated Subject, Authorization Principal, Tenant, Team, Membership, and Profile must remain distinguishable in the identity context read model.
  - Tenant-scoped privileged membership must expose scope and evidence or an explicit evidence gap.
  - Cross-tenant context must be denied unless the actor is a platform operator.
  - Claims enrichment projections must not imply token issuance ownership.
  - Credential, MFA, policy decision, and durable platform audit ownership must remain outside user-engine.

source_of_truth:
  user_records: user-engine
  account_state: user-engine
  external_identity_links: user-engine
  profile_values: user-engine
  membership_facts_created_here: user-engine
  authentication: NetKingdom IAM infrastructure
  credential_assurance: NetKingdom IAM/security infrastructure
  authorization_decisions: NetKingdom authorization infrastructure
  policy_and_control_definitions: NetKingdom governance/security infrastructure
  durable_platform_audit: NetKingdom audit infrastructure
  organization_authority: NetKingdom organization or directory systems

known_deviations:
  - User remains a local implementation class even though identity-canon treats user as a non-root convenience term; mappings must state whether it represents actor-facing profile holder, account owner, or local user record.
  - Access Grant is currently a grant-like reference derived from memberships, not a durable authorization grant table.
  - Evidence Source references currently derive from local audit records unless an external evidence exporter is supplied.
  - AccessReview, Policy, Control, Exception, and lifecycle Task are references or gaps, not first-class owned records.