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:
 

docs/hats-realms-services-assets-access-profiles.md

@@ -0,0 +1,106 @@
+# Hats, Realms, Services, Assets, And Access Profiles
+
+Status: implemented headless slice
+Date: 2026-06-15
+Related workplan: USER-WP-0012
+
+## Purpose
+
+This slice models how a NetKingdom user can wear different hats across tenant,
+realm, service, asset, and group contexts. It gives authorization systems and
+service runtimes explicit access-control facts and claims-enrichment context
+without moving final policy decisions into user-engine.
+
+## Vocabulary
+
+The USER-WP-0012 vocabulary maps onto existing user-engine facts:
+
+- tenant: isolation boundary and tenant account state;
+- realm: broad domain or community scope represented by membership scope
+  `realm`;
+- service: protected application or service scope represented by membership
+  scope `service` or an access profile `service_id`;
+- asset: protected resource scope represented by membership scope `asset` or
+  an access profile `asset_id`;
+- group: group membership represented by membership scope `group`;
+- hat: active role persona selected from an access profile;
+- access profile: template that combines membership requirements, factor
+  requirements, profile defaults, and projection claim rules.
+
+## Domain Model
+
+`AccessProfile` defines a claimable hat for a tenant context. It stores the
+hat name, scope type/id, optional realm/service/asset ids, required membership
+facts, required factor types, profile defaults, claims, group ids, and an
+approval flag.
+
+`ActiveAccessContext` records the user's currently selected hat for a tenant.
+It stores the selected access profile, active scope, matched membership ids,
+verified factor ids, group ids, projection claims, and profile defaults.
+
+`AccessControlFact` is the export shape for policy and ACL systems. Facts can
+represent direct user memberships, group-derived facts, and active-context
+facts over realm, service, or asset scopes.
+
+## Public Facade
+
+`UserEngineService` exposes:
+
+- `register_access_profile(...)`
+- `list_access_profiles(...)`
+- `select_active_hat(...)`
+- `export_access_control_facts(...)`
+- `access_profile_diagnostics(...)`
+
+All mutating and read/export operations pass through the authorization port.
+
+## Selection Rules
+
+Hat selection fails closed unless all of these are true:
+
+- the actor is allowed to operate in the tenant context;
+- the target user has an active tenant account;
+- the access profile belongs to the tenant and is not approval-required;
+- every profile membership requirement is satisfied by existing memberships;
+- every required factor type has unexpired verified user evidence;
+- the authorization port allows the active-context selection.
+
+Selecting a hat records an `ActiveAccessContext`, emits
+`active_access_context.selected`, and keeps raw factor values out of events and
+projections.
+
+## Identity Context And Projections
+
+`identity_context` now includes:
+
+- `active_access_context`;
+- `access_control_facts`;
+- canon references for active hat, access profile, realm, service area, asset
+  scope, and groups;
+- relationship references such as `wears_hat` and
+  `selected_access_profile`.
+
+Claims-enrichment projections include an `access_context` mapping when the
+active context applies to the requested application/service. Service-specific
+contexts are omitted from projections for other applications.
+
+## Export Boundary
+
+`export_access_control_facts` returns an adapter-neutral manifest plus facts.
+External authorization engines or ACL systems can consume these facts, but
+they remain responsible for final policy decisions and runtime enforcement.
+
+## Redaction And Diagnostics
+
+Diagnostics report counts, required factor types, and approval-required issues.
+They deliberately do not return profile default values, projection claim
+values, factor values, phone numbers, postal addresses, eID payloads, or other
+proofing data.
+
+## Current Limits
+
+- user-engine does not implement a policy engine or ACL evaluator.
+- Approval workflows for privileged hats remain a later slice.
+- Access profile profile-default values are carried into active context and
+  projections, but this slice does not persist them as catalog profile values.
+- UI selection flows are left to USER-WP-0014.

docs/netkingdom-registration-onboarding-vision.md

@@ -235,9 +235,9 @@ once.
 
 ## Recommended Workplans
 
-As of 2026-06-15, `USER-WP-0010` and `USER-WP-0011` are implemented as
-headless user-engine slices. The later workplans remain recommended follow-on
-work.
+As of 2026-06-15, `USER-WP-0010`, `USER-WP-0011`, and `USER-WP-0012` are
+implemented as headless user-engine slices. The later workplans remain
+recommended follow-on work.
 
 | Workplan | Title | Purpose |
 | --- | --- | --- |

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

@@ -110,8 +110,9 @@ return factor values.
 
 - Prepared account claiming is implemented by USER-WP-0011 and documented in
   `docs/prepared-accounts-and-entitlement-claims.md`.
-- Hats, realms, services, assets, and access profiles are left to
-  USER-WP-0012.
+- Hats, realms, services, assets, and access profiles are implemented by
+  USER-WP-0012 and documented in
+  `docs/hats-realms-services-assets-access-profiles.md`.
 - 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.