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