Implement registration identity model

docs/contracts.md

@@ -6,6 +6,9 @@
 HTTP or RPC adapters should preserve these operation names:
 
 - `health`, `readiness`, `operability_snapshot`, `outbox_diagnostics`
+- `start_registration`, `attach_registration_factor`, `complete_registration`,
+  `abandon_registration`, `expire_registration`, `resume_registration`,
+  `registration_diagnostics`
 - `me`, `create_user`, `set_account_status`, `link_identity`
 - `resolve_tenant_context`, `set_tenant_account_status`, `add_membership`,
   `tenant_diagnostics`
@@ -16,6 +19,27 @@ HTTP or RPC adapters should preserve these operation names:
   `accept_family_invitation`
 - `audit_records`, `outbox_events`
 
+## Registration Contract
+
+Registration is a headless user-entry facade. It creates a
+`RegistrationSession`, accepts safe `FactorVerification` evidence from external
+proofing adapters, records persisted `IdentityFactor` metadata, and completes
+the session into a stable NetKingdom ID.
+
+The first NetKingdom ID contract is `User.user_id`: an opaque, stable user
+identifier that must not encode IAM issuer/subject pairs, email addresses,
+phone numbers, postal addresses, eID payloads, tenant names, or other proofing
+data.
+
+Registration completion creates or resolves a `User`, `Account`,
+`TenantAccount`, and `ExternalIdentity` link for the verified actor, attaches
+verified factors to that user, emits audit/outbox records, and returns
+`identity_context`.
+
+user-engine does not verify factors itself, issue credentials, perform MFA,
+run eID proofing, or issue tokens. Those remain external IAM/proofing adapter
+responsibilities.
+
 ## Identity Context Contract
 
 `identity_context` is the first canon-facing read model for NetKingdom

docs/registration-identity-and-factor-model.md

@@ -0,0 +1,116 @@
+# Registration Identity And Factor Model
+
+Status: implemented headless slice
+Date: 2026-06-15
+Related workplan: USER-WP-0010
+
+## Purpose
+
+This document defines the first NetKingdom registration slice in
+`user-engine`. The slice lets a caller start a registration session, attach
+externally verified identity-factor evidence, complete registration into a
+stable NetKingdom user/account, and inspect safe diagnostics.
+
+The design keeps user-engine in its identity-domain lane:
+
+- IAM and proofing providers verify credentials, email, phone, eID, invite, or
+  SSO evidence.
+- user-engine stores the registration session, normalized factor metadata,
+  user/account records, external identity links, audit records, and outbox
+  events.
+- Authorization systems continue to make final policy and ACL decisions.
+
+## NetKingdom ID
+
+For this slice, the NetKingdom ID is the existing stable `User.user_id`.
+
+That choice keeps the first implementation simple and avoids adding a second
+identifier before a concrete public-ID requirement exists. Consumers should
+treat the ID as opaque. It must not encode identity-provider issuer/subject
+pairs, factor values, tenant names, email addresses, phone numbers, or eID
+payloads.
+
+If NetKingdom later needs a public alias, vanity handle, or migration-safe
+external identifier, that can be added as a separate mapped identifier without
+changing the registration facade's `netkingdom_id` contract.
+
+## Domain Model
+
+`RegistrationSession` tracks the workflow:
+
+- `started`
+- `factor_pending`
+- `factor_verified`
+- `completed`
+- `abandoned`
+- `expired`
+- `rejected`
+
+`FactorVerification` is adapter output from an external proofing system. It is
+safe metadata: factor type, normalized value, optional display value, source
+system, assurance metadata, evidence references, verification time, and
+optional expiry.
+
+`IdentityFactor` is the persisted user-engine record. During registration it
+is attached to a registration session. After completion it is also attached to
+the canonical user.
+
+Supported factor types are:
+
+- `email`
+- `phone`
+- `postal_address`
+- `eid`
+- `invite`
+- `sso`
+
+## Public Facade
+
+`UserEngineService` exposes:
+
+- `start_registration(...)`
+- `attach_registration_factor(...)`
+- `complete_registration(...)`
+- `abandon_registration(...)`
+- `expire_registration(...)`
+- `resume_registration(...)`
+- `registration_diagnostics(...)`
+
+The completion result includes the completed session, user, account,
+`netkingdom_id`, and `identity_context`.
+
+## Factor Adapter Boundary
+
+`FactorVerificationAdapter` normalizes external proofing results into
+`FactorVerification`. A caller may also pass an already-normalized
+`FactorVerification` directly.
+
+Adapters must strip secret challenge material, proofing payloads, provider
+tokens, and raw documents before data reaches user-engine.
+
+## Audit, Outbox, And Redaction
+
+Registration mutations emit local audit records and outbox events:
+
+- `registration.started`
+- `registration.factor_verified`
+- `registration.completed`
+- `registration.abandoned`
+- `registration.expired`
+
+Outbox payloads include registration ids, factor ids, factor types, source
+systems, status, and user ids. They deliberately do not include normalized
+factor values such as email addresses, phone numbers, postal addresses, or eID
+payloads.
+
+Diagnostics report counts by status and total verified factors. They do not
+return factor values.
+
+## Current Limits
+
+- Prepared account claiming is intentionally left to USER-WP-0011.
+- Hats, realms, services, assets, and access profiles are left to
+  USER-WP-0012.
+- Welcome protocols and onboarding journeys are left to USER-WP-0013.
+- Registration UI is left to USER-WP-0014.
+- Provider-backed proofing and credential flows remain external adapters.