# Canon Mapping

Status: candidate
Updated: 2026-06-05

This document maps current `user-engine` implementation concepts to
identity-canon and InfoTechCanon concepts. It is intentionally explicit about
owned facts, consumed facts, references, and gaps.

## Mapping Stance

`identity-canon` treats `User` as a convenience term, not the root concept.
`user-engine` keeps the existing `User` implementation class for compatibility,
but exposes canon-facing context through `identity_context` so consumers can see
the distinct account, actor, subject, principal, tenant, membership, profile,
and evidence references.

## Entity Mapping

| user-engine concept | Canon concept | Ownership | Notes |
| --- | --- | --- | --- |
| `Actor` | Actor | consumed/reference | Normalized from verified IAM claims; not persisted as source of truth. |
| `Actor.issuer + Actor.subject` | Authenticated Subject / Scoped Identifier | consumed/reference | Protocol-level identity after authentication. |
| `User` | User convenience term / profile holder | owned local record | Not treated as Natural Person unless a future mapping proves that relationship. |
| `Account` | Account | owned | Operational account state for the user-engine scope. |
| `TenantAccount` | Account scoped to Tenant | owned | Tenant-local account lifecycle state. |
| `ExternalIdentity` | Identity Record / Scoped Identifier / Synonymity Assertion seed | owned link | Links issuer-subject pairs to local user records without destructive merge. |
| `Application` | Scope / Application Service reference | owned local registry | Application-specific profile consumer and catalog owner. |
| `ApplicationBinding` | Trust Relationship / integration binding | owned local registry | Binds user-engine app IDs to external clients, protected systems, events, and catalogs. |
| `Membership` | Membership Relationship | owned when created here | Relationship from user/account context to tenant, team, application, group, or other scope. |
| `Membership.kind` | Role label / grant-like fact | owned local label | Role-like string is not a final authorization decision. |
| `ProfileValue` | Profile | owned | Scoped presentation or preference value. |
| `Catalog` / `AttributeDefinition` | Profile schema / governance metadata | owned | Attribute ownership, sensitivity, visibility, and mutability metadata. |
| `AuthorizationRequest` | Authorization request | emitted/consumed | Sent to authorization port; policy decision remains external. |
| `AuthorizationDecision` | Authorization decision | consumed/reference | Enforced locally; decision authority remains external. |
| `AuditRecord` | Evidence Source | owned local evidence, exportable | Local operational evidence; durable platform audit is external. |
| `OutboxEvent` | Lifecycle event / evidence source | owned local event | Integration event queue for downstream systems. |

## Relationship Mapping

| Relationship | Source | Target | Implementation source |
| --- | --- | --- | --- |
| `identity_link` | Identity Record | User | `ExternalIdentity.user_id` |
| `belongs_to_tenant` | User or Account | Tenant | `TenantAccount` and tenant-scoped operations |
| `authenticates_as` | Account | Authenticated Subject | normalized IAM claims |
| `evaluated_as` | Authenticated Subject | Authorization Principal | `identity_context` principal projection |
| `member_of` | User | Team / Group / Scope | `Membership(scope_type, scope_id)` |
| `role_label` | Membership Relationship | Role | `Membership.kind` |
| `scoped_to` | Access Grant or grant-like fact | Tenant / Scope | `Membership.tenant` and operation tenant |
| `governed_by` | Grant-like fact / decision | Policy reference | external policy/control resolver gap |
| `implemented_by` | Policy reference | Control reference | external policy/control resolver gap |
| `evidenced_by` | Identity-domain claim or grant-like fact | Evidence Source | local audit or external evidence exporter |
| `creates_task` | Evidence gap / integration gap | lifecycle task reference | lifecycle task sink gap |

## Read Model

`UserEngineService.identity_context(...)` returns the current implementation
surface for canon-facing identity context. It includes:

- the normalized actor;
- local user and account records;
- external identity links;
- tenant and optional application scope;
- membership facts;
- entity references for User, Account, Actor, Authenticated Subject,
  Authorization Principal, Tenant, Identity Record, Scoped Identifier, Team,
  Scope, Membership Relationship, and Role;
- relationship references for identity link, tenant scope, authentication,
  principal evaluation, membership, role label, and grant-like scope;
- access grant-like references derived from memberships;
- evidence references derived from audit records;
- an optional effective profile projection;
- explicit gaps when evidence is missing.

## Current Gaps

- `Natural Person` is not modeled directly. A user record may represent a human
  profile holder, but that relationship is not currently asserted.
- `Synonymity Assertion` is implicit in identity linking. Strong/weak link
  confidence, verification method, privacy scope, and revocation state are not
  first-class yet.
- `Organization`, `Customer`, `Vendor`, and `Legal Entity` are referenced only
  through tenant, team, owner, or external system identifiers.
- `AccessReview`, `Policy`, `Control`, `Exception`, and lifecycle `Task`
  references depend on external NetKingdom systems or future adapter
  implementations.
- `Access Grant` is currently an exported grant-like reference derived from
  memberships. It is not a durable authorization grant table.
- Evidence references currently derive from local audit records unless an
  `EvidenceReferenceExporter` is supplied.

## Validation Hooks

The first executable checks live in `tests/test_identity_canon_alignment.py`.
They verify that:

- user, account, authenticated subject, authorization principal, tenant, team,
  membership, and grant-like references remain distinct;
- service accounts project into service principals without becoming natural
  persons;
- cross-tenant identity context is denied without platform scope;
- claims-enrichment context can be read without implying token issuance
  ownership.