feat: implement access profiles and hats

docs/contracts.md

@@ -12,6 +12,8 @@ HTTP or RPC adapters should preserve these operation names:
 - `prepare_account`, `update_prepared_account`, `list_prepared_accounts`,
   `revoke_prepared_account`, `expire_prepared_account`,
   `claim_prepared_account`
+- `register_access_profile`, `list_access_profiles`, `select_active_hat`,
+  `export_access_control_facts`, `access_profile_diagnostics`
 - `me`, `create_user`, `set_account_status`, `link_identity`
 - `resolve_tenant_context`, `set_tenant_account_status`, `add_membership`,
   `tenant_diagnostics`
@@ -62,13 +64,36 @@ approval-required packages fail closed. Denied claim decisions are audited
 without outbox events. Mutation outbox payloads include ids, counts, statuses,
 factor types, and journey names, but not normalized factor values.
 
+## Access Profile And Hat Contract
+
+Access profiles are tenant-scoped templates for selecting an active hat across
+tenant, realm, service, asset, or group contexts. A profile combines required
+memberships, required verified factor types, profile defaults, projection
+claims, optional group references, and explicit realm/service/asset scope ids.
+
+`select_active_hat` requires an active tenant account, satisfied membership
+requirements, unexpired verified factor evidence, and authorization-port
+approval. The selected hat is persisted as `ActiveAccessContext` and is exposed
+through `identity_context` and claims-enrichment projections.
+
+`export_access_control_facts` returns adapter-neutral `AccessControlFact`
+records for authorization engines and ACL systems. These facts include direct
+membership facts, group-derived facts, and active-context facts, but
+user-engine still does not make final access decisions or enforce protected
+service runtime policy.
+
+Access-profile diagnostics report counts, factor requirement types, and
+approval-required issues without exposing profile default values, projection
+claim values, or raw factor values.
+
 ## Identity Context Contract
 
 `identity_context` is the first canon-facing read model for NetKingdom
 identity-domain consumers. It resolves a verified actor into the local user,
 account, external identity links, tenant scope, memberships, optional
-application scope, optional effective profile, canon entity references,
-relationship references, grant-like membership facts, and evidence references.
+application scope, optional effective profile, optional active access context,
+exportable access-control facts, canon entity references, relationship
+references, grant-like membership facts, and evidence references.
 
 The method keeps these concepts distinct: