Add user-engine architecture workplans

2026-05-22 19:28:00 +02:00
parent 6aec040046
commit 28da204cf2
7 changed files with 1076 additions and 0 deletions
--- a/docs/reviews/2026-05-22T19-19-59+0200-user-engine-architecture-review.md
+++ b/docs/reviews/2026-05-22T19-19-59+0200-user-engine-architecture-review.md
@@ -0,0 +1,205 @@
+# User Engine Architecture Review
+
+Timestamp: 2026-05-22T19:19:59+0200
+Reviewer: codex
+Subject: `/home/worsch/user-engine/wiki/ArchitectureBlueprint.md`
+Context: user-engine integration with NetKingdom IAM Profile, key-cape,
+Keycloak, flex-auth, Railiance platform services, and future user-account /
+user-manager UI surfaces.
+
+## Executive Assessment
+
+The proposed architecture is directionally sound. `user-engine` fills a real
+gap: a headless user-domain, profile, preference, membership, catalog, and
+projection service that does not try to become an identity provider, MFA
+system, authorization engine, runtime secret store, or UI.
+
+The central improvement area is contract precision at the boundaries. The
+architecture has the right separation in prose, but implementation will create
+duplicate truths unless we explicitly define how identity claims, user-engine
+memberships, flex-auth subject facts, application registrations, OIDC clients,
+protected-system registrations, and profile projections relate to each other.
+
+## Main Findings
+
+### 1. Membership Ownership Is The Hottest Overlap
+
+`user-engine` wants to own tenant, application, team, and membership facts.
+IAM providers expose groups and roles. flex-auth also models subjects, groups,
+teams, and tenants for policy decisions.
+
+This overlap is healthy only if the source of truth is explicit:
+
+- IAM owns authentication-time identity facts and coarse claims.
+- user-engine owns product-domain memberships and profile facts.
+- flex-auth owns policy interpretation and final authorization decisions.
+- exported subject facts are read models or policy inputs, not competing
+  masters.
+
+Recommended action: create a source-of-truth matrix and a membership
+synchronization contract before implementation starts.
+
+### 2. Application Registration Is Overloaded
+
+An "application" can mean several things:
+
+- a user-engine profile consumer;
+- an OIDC client in key-cape or Keycloak;
+- a flex-auth protected system;
+- a catalog namespace owner;
+- a deployed workload in Railiance.
+
+These should not collapse into one record. user-engine should own the profile
+consumer record and hold explicit bindings to OIDC clients, flex-auth protected
+systems, catalog namespaces, and deployment metadata.
+
+Recommended action: define an application onboarding contract that maps these
+records without merging their ownership.
+
+### 3. OIDC-Compatible Projections Need A Strong Boundary
+
+OIDC-compatible profile projections are useful, but user-engine should not
+become part of the token issuance critical path by accident. Token issuance
+belongs to key-cape or Keycloak. If user-engine profile data is needed in
+claims, it should be delivered through an explicit claims-enrichment adapter
+with caching, freshness, and failure-mode rules.
+
+Recommended action: treat claims enrichment as an adapter boundary, not a core
+runtime dependency for login.
+
+### 4. Synchronous Authorization Checks Can Become A Bottleneck
+
+The flow "user-engine calls flex-auth for every protected action" is clean but
+can become expensive for list screens, bulk admin operations, and high-volume
+profile reads.
+
+Recommended mitigations:
+
+- request-scoped memoization;
+- batch authorization checks for list/admin screens;
+- short-lived decision caching only where safe;
+- explicit fail-closed behavior for sensitive writes;
+- local policy fixtures only for standalone development and tests.
+
+### 5. Effective Profile Resolution Can Become The Hidden Performance Center
+
+Layered profiles plus catalog defaults plus tenant, application, team, and
+admin overrides are powerful, but they are also expensive and easy to
+implement as repeated joins or repeated resolver calls.
+
+Recommended action: design versioned effective-profile materialization or
+caching early. Invalidation should be driven by profile, catalog, membership,
+and application outbox events.
+
+### 6. Audit Is Correctly Placed But Needs One Correlation Model
+
+user-engine audit, flex-auth decision audit, and platform audit sinks all have
+valid roles. Without shared correlation IDs, operators will struggle to
+reconstruct one administrative action across systems.
+
+Recommended action: define an audit correlation contract with request ID,
+actor identity, user-engine audit ID, flex-auth decision ID, outbox event ID,
+tenant, application, and sensitivity-aware redaction rules.
+
+## Information Flow Assessment
+
+Good flows:
+
+- IAM Profile -> user-engine actor envelope: correct abstraction.
+- user-engine -> flex-auth authorization check: correct decision boundary.
+- user-engine -> outbox -> platform event/audit sinks: correct durability
+  pattern.
+- catalog metadata -> future UIs: correct headless-first UI support.
+
+Unclear or inefficient flows:
+
+- user-engine membership facts -> flex-auth subject manifests: source of truth
+  and freshness need definition.
+- user-engine profile projection -> OIDC claims: must not make token issuance
+  depend synchronously on user-engine.
+- admin list/search -> per-row flex-auth checks -> profile resolver: likely
+  inefficient unless batched and cached.
+- catalog activation -> profile migration -> projection invalidation: needs a
+  versioning and migration flow.
+
+## Expected Bottlenecks
+
+| Bottleneck | Why it happens | Mitigation |
+| --- | --- | --- |
+| flex-auth checks | Per-action synchronous decisions | Batch checks, memoize per request, cache low-risk decisions, keep writes fail-closed |
+| Effective profile resolution | Layered scopes and catalog defaults | Materialized effective profiles, version stamps, targeted invalidation |
+| Catalog governance | Every app wants custom attributes | Governance tiers, namespace ownership, automated compatibility checks |
+| Audit volume | Profile and membership changes can be frequent | Redacted summaries, outbox compaction where allowed, correlation IDs |
+| Application onboarding | Crosses IAM, user-engine, flex-auth, Railiance | Application onboarding contract and checklist |
+| Claims enrichment | Login path can become dependent on user-engine | Async/cache-backed enrichment and graceful claim omission rules |
+
+## SWOT Digest
+
+### Strengths
+
+- Clear headless product boundary.
+- Good separation from identity provider, MFA, secrets, UI, and PDP concerns.
+- Strong fit with NetKingdom IAM Profile and flex-auth.
+- Catalog-driven profile governance addresses real metadata entropy.
+- Supports standalone adoption without abandoning platform integration.
+
+### Weaknesses
+
+- Membership, group, role, and subject facts can drift across systems.
+- Application registration is currently overloaded.
+- Projection freshness and caching rules are not yet defined.
+- Standalone mode could grow unsafe auth shortcuts unless constrained.
+- Audit correlation is not yet formalized.
+
+### Opportunities
+
+- user-engine can become the reusable user-domain/profile layer for many repos.
+- Catalog metadata can power `user-account` and `user-manager` without
+  separate UI-specific backends.
+- Subject/membership exports can make flex-auth richer without turning
+  flex-auth into a profile store.
+- A clean app onboarding contract can make multi-application integration
+  repeatable.
+- Agent-context projections can give agentic systems governed user context.
+
+### Threats
+
+- Duplicate truth between IAM, user-engine, and flex-auth.
+- Login/token flows becoming dependent on user-engine availability.
+- Profile data leakage through broad admin or agent projections.
+- Catalog approval becoming a central bottleneck.
+- Tenant admins accidentally gaining platform-scale authority.
+
+## Promising Improvements
+
+1. Add a source-of-truth matrix for identity claims, user records, accounts,
+   memberships, groups, roles, app registrations, protected systems, catalogs,
+   profile values, and audit records.
+2. Define an application onboarding contract across IAM OIDC client,
+   user-engine application, flex-auth protected system, catalog namespace, and
+   deployment metadata.
+3. Define a membership synchronization contract with ownership, import,
+   export, conflict handling, and freshness rules.
+4. Split projection definitions into runtime, UI, claims-enrichment, audit,
+   and agent-context projections.
+5. Add an authorization performance model for synchronous checks, batching,
+   caching, fail-closed writes, and standalone development policy fixtures.
+6. Add effective-profile cache/materialization design using catalog/profile
+   version stamps and outbox-driven invalidation.
+7. Define audit correlation across user-engine, flex-auth, and platform audit
+   sinks.
+8. Add catalog governance tiers so low-sensitivity app-owned attributes can
+   move quickly while sensitive or cross-tenant attributes require review.
+9. Make claims enrichment explicitly optional and adapter-owned.
+10. Define tenant/admin scope rules before building `user-manager`.
+
+## Workplan Follow-Up
+
+The review is translated into the following NetKingdom workplans:
+
+- `NK-WP-0014` - user-engine preparation and boundary contracts
+- `NK-WP-0015` - isolated MVP implementation
+- `NK-WP-0016` - multi-tenancy support
+- `NK-WP-0017` - multi-application and catalog support
+- `NK-WP-0018` - integrated test scenario expansion
+- `NK-WP-0019` - implementation assessment, finalization, and polish
--- a/workplans/NK-WP-0014-user-engine-preparation-boundary-contracts.md
+++ b/workplans/NK-WP-0014-user-engine-preparation-boundary-contracts.md
@@ -0,0 +1,153 @@
+---
+id: NK-WP-0014
+type: workplan
+title: "User Engine Preparation And Boundary Contracts"
+domain: netkingdom
+repo: net-kingdom
+status: ready
+owner: codex
+topic_slug: netkingdom
+planning_priority: high
+planning_order: 14
+created: "2026-05-22"
+updated: "2026-05-22"
+depends_on:
+  - NK-WP-0012
+  - NK-WP-0013
+state_hub_workstream_id: "b9bf56bc-7ef6-43eb-badc-fa0f4896c63c"
+---
+
+# NK-WP-0014 - User Engine Preparation And Boundary Contracts
+
+## Goal
+
+Prepare implementation of `/home/worsch/user-engine` by turning the current
+architecture review into concrete contracts. This workplan must be completed
+before production code is started, so the MVP does not duplicate IAM,
+authorization, application registration, membership, audit, or deployment
+responsibilities already owned by NetKingdom-aligned components.
+
+## Context
+
+The user-engine PRD and architecture blueprint define a headless user-domain
+service for users, accounts, profiles, preferences, memberships, application
+catalogs, projections, audit, and events.
+
+The architecture review in
+`docs/reviews/2026-05-22T19-19-59+0200-user-engine-architecture-review.md`
+identified the main risk: duplicate truth across IAM providers, user-engine,
+flex-auth, application registrations, OIDC clients, protected systems, and
+profile projections.
+
+## Scope
+
+In scope:
+
+- source-of-truth matrix;
+- membership synchronization contract;
+- application onboarding contract;
+- projection boundary split;
+- authorization performance model;
+- audit correlation contract;
+- user-engine repo preparation artifacts.
+
+Out of scope:
+
+- implementing user-engine production code;
+- implementing UI repos;
+- implementing SCIM or enterprise federation adapters;
+- changing the NetKingdom IAM Profile.
+
+## Tasks
+
+```task
+id: NK-WP-0014-T1
+status: todo
+priority: high
+state_hub_task_id: "4e941174-ac55-4f6e-8568-40f45b1ed821"
+```
+
+**Source-of-truth matrix.** Define which system owns each resource kind:
+identity claims, human subjects, local user records, account lifecycle,
+groups, roles, memberships, tenants, applications, OIDC clients,
+flex-auth protected systems, catalog namespaces, profile values,
+effective-profile projections, audit records, and events.
+
+```task
+id: NK-WP-0014-T2
+status: todo
+priority: high
+state_hub_task_id: "5ddc46bb-6238-4944-a023-d8b46b410c76"
+```
+
+**Membership synchronization contract.** Specify which memberships are mastered
+in user-engine, which are imported from IAM or provisioning systems, which are
+exported to flex-auth, and how freshness, conflict handling, deletes, and
+tenant boundaries are represented.
+
+```task
+id: NK-WP-0014-T3
+status: todo
+priority: high
+state_hub_task_id: "696bc65b-0f8d-47b5-bccc-65ed285b42e6"
+```
+
+**Application onboarding contract.** Define the binding between a user-engine
+application, IAM OIDC client, flex-auth protected system, catalog namespace,
+event/audit identity, and Railiance deployment metadata. Include a checklist
+for adding one new application safely.
+
+```task
+id: NK-WP-0014-T4
+status: todo
+priority: high
+state_hub_task_id: "99ab4535-cbbf-4e13-a2c5-adfc814d5aeb"
+```
+
+**Projection and claims-enrichment boundaries.** Split projection types into
+runtime, self-service UI, admin UI, audit, agent context, and optional claims
+enrichment. Explicitly state that user-engine does not issue tokens and that
+claims enrichment is adapter-owned and cache/freshness governed.
+
+```task
+id: NK-WP-0014-T5
+status: todo
+priority: medium
+state_hub_task_id: "d35a1356-a9fe-4cf3-8fb0-6f45cfbbccee"
+```
+
+**Authorization and audit contracts.** Define the user-engine resource/action
+vocabulary for flex-auth, when checks are synchronous, when they may be
+batched or cached, and how user-engine audit records correlate with flex-auth
+decision IDs and platform audit sinks.
+
+```task
+id: NK-WP-0014-T6
+status: todo
+priority: medium
+state_hub_task_id: "04fd2f92-3aa4-468d-9e9e-9b092890507e"
+```
+
+**Prepare the user-engine repo.** Add or update user-engine `SCOPE.md`,
+architecture notes, repo layout decision, local development contract, and
+initial implementation readiness checklist. Do not add NetKingdom
+orchestration relationships to user-engine `INTENT.md`; those belong in
+NetKingdom documents per ADR-0010.
+
+## Acceptance Criteria
+
+- Boundary contracts exist and are reviewed against the PRD and architecture
+  review.
+- user-engine responsibilities are distinct from key-cape, Keycloak,
+  flex-auth, OpenBao, Railiance, user-account, and user-manager.
+- The first implementation slice can start without unresolved ownership of
+  memberships, applications, projections, authorization checks, or audit
+  correlation.
+- NetKingdom responsibility-map updates are either applied or explicitly
+  deferred until user-engine becomes a shared platform service.
+
+## Dependencies And Sequencing
+
+- Depends on NK-WP-0012 for IAM Profile consumption rules.
+- Depends on NK-WP-0013 for NetKingdom meta-orchestration conventions.
+- Gates NK-WP-0015.
--- a/workplans/NK-WP-0015-user-engine-isolated-mvp.md
+++ b/workplans/NK-WP-0015-user-engine-isolated-mvp.md
@@ -0,0 +1,151 @@
+---
+id: NK-WP-0015
+type: workplan
+title: "User Engine Isolated MVP"
+domain: netkingdom
+repo: net-kingdom
+status: ready
+owner: codex
+topic_slug: netkingdom
+planning_priority: high
+planning_order: 15
+created: "2026-05-22"
+updated: "2026-05-22"
+depends_on:
+  - NK-WP-0014
+state_hub_workstream_id: "343e035d-41e1-4fc4-b209-6872e4a5fdc8"
+---
+
+# NK-WP-0015 - User Engine Isolated MVP
+
+## Goal
+
+Implement the smallest useful isolated user-engine in `/home/worsch/user-engine`
+with automated tests for all MVP use cases: users, accounts, external identity
+links, application registration, customization catalogs, profile values,
+effective profile resolution, projections, audit records, and domain events.
+
+The MVP must run without the full NetKingdom platform while preserving the
+same boundaries used by platform mode.
+
+## Scope
+
+In scope:
+
+- repo skeleton and local development workflow;
+- domain core independent of HTTP;
+- local persistence and migrations;
+- headless API for MVP resources;
+- local IAM Profile fixture or local-identity integration;
+- pluggable flex-auth check interface with a local test adapter;
+- audit and transactional outbox;
+- automated unit and integration tests.
+
+Out of scope:
+
+- multi-tenant production operation beyond one explicit tenant context;
+- multi-application governance beyond one or two demo applications;
+- SCIM server or enterprise provisioning;
+- UI implementation;
+- production deployment through Railiance.
+
+## Tasks
+
+```task
+id: NK-WP-0015-T1
+status: todo
+priority: high
+state_hub_task_id: "81a88eaa-df2e-4b9f-85f4-a1570c9c9f86"
+```
+
+**Repo scaffold and implementation stack.** Choose the initial implementation
+stack, create the repository layout, define commands for lint/test/run, and
+keep the domain core separate from HTTP handlers and infrastructure adapters.
+
+```task
+id: NK-WP-0015-T2
+status: todo
+priority: high
+state_hub_task_id: "fc4172f7-e7f1-4ad9-98c3-37ccb08c7386"
+```
+
+**Domain model and persistence.** Implement users, accounts, identity links,
+applications, catalogs, attribute definitions, profile values, audit records,
+and outbox events with migrations and test fixtures.
+
+```task
+id: NK-WP-0015-T3
+status: todo
+priority: high
+state_hub_task_id: "8aa5a9e9-3f23-4124-aa3b-01c099ce88bc"
+```
+
+**Identity and authorization adapters.** Implement an IAM Profile actor
+adapter using fixtures or local-identity for isolated mode. Implement a
+flex-auth check port with a local deterministic test adapter. Ensure
+production code paths can later swap to real flex-auth without changing
+domain logic.
+
+```task
+id: NK-WP-0015-T4
+status: todo
+priority: high
+state_hub_task_id: "cedd6319-e4c2-460c-888c-d0d95d7bdbef"
+```
+
+**Headless MVP API.** Add API endpoints for health/readiness, `me`, users,
+account lifecycle transitions, identity links, application registration,
+catalog registration/activation, profile updates, effective profile
+resolution, projections, and audit inspection.
+
+```task
+id: NK-WP-0015-T5
+status: todo
+priority: high
+state_hub_task_id: "62ecafaa-237a-4cae-ac78-1ed79ca881a1"
+```
+
+**Catalog and profile resolver.** Implement JSON/YAML catalog registration,
+attribute validation, default values, global plus application profile layers,
+basic precedence rules, and inspectable effective profile resolution.
+
+```task
+id: NK-WP-0015-T6
+status: todo
+priority: high
+state_hub_task_id: "d627db12-2019-4870-a255-354fc77a1d22"
+```
+
+**Projection, audit, and event outbox.** Implement self-service, admin,
+application runtime, audit, and agent-context projection skeletons with
+sensitivity-aware redaction. Persist audit records and outbox events in the
+same transaction as mutations.
+
+```task
+id: NK-WP-0015-T7
+status: todo
+priority: high
+state_hub_task_id: "803e979d-a83a-43d8-a93d-ce97c83015ec"
+```
+
+**MVP test suite.** Cover user/account lifecycle, identity linking, catalog
+validation failures, profile update authorization, effective profile
+resolution, projection redaction, audit/outbox atomicity, local issuer
+handling, and deny paths from the authorization adapter.
+
+## Acceptance Criteria
+
+- The user-engine repo can be checked out and tested in isolation.
+- A demo application can register, register a catalog, update profile values,
+  and request an effective profile projection.
+- A current user can read/update allowed self-service profile fields.
+- An admin-like actor can perform allowed scoped user operations through the
+  test authorization adapter.
+- Sensitive attributes are redacted from non-eligible projections.
+- Mutations produce audit and outbox records atomically.
+- Tests cover positive and negative MVP use cases.
+
+## Dependencies And Sequencing
+
+- Gated by NK-WP-0014 boundary contracts.
+- Enables NK-WP-0016 and NK-WP-0017.
--- a/workplans/NK-WP-0016-user-engine-multi-tenancy.md
+++ b/workplans/NK-WP-0016-user-engine-multi-tenancy.md
@@ -0,0 +1,142 @@
+---
+id: NK-WP-0016
+type: workplan
+title: "User Engine Multi-Tenancy"
+domain: netkingdom
+repo: net-kingdom
+status: ready
+owner: codex
+topic_slug: netkingdom
+planning_priority: high
+planning_order: 16
+created: "2026-05-22"
+updated: "2026-05-22"
+depends_on:
+  - NK-WP-0015
+state_hub_workstream_id: "2d592e18-e63d-4856-97a1-f8c3e019e150"
+---
+
+# NK-WP-0016 - User Engine Multi-Tenancy
+
+## Goal
+
+Extend the isolated MVP into a tenant-aware service that follows the
+NetKingdom recursive platform model: `tenant:platform` is distinct from
+tenant planes such as `tenant:coulomb`, and tenant administration must not
+grant platform-root authority.
+
+## Scope
+
+In scope:
+
+- tenant model and context propagation;
+- tenant-scoped profiles and memberships;
+- tenant admin scopes;
+- tenant-aware authorization checks;
+- tenant isolation in persistence and APIs;
+- tenant-aware audit/events;
+- tenant onboarding diagnostics and tests.
+
+Out of scope:
+
+- multi-application catalog governance beyond what NK-WP-0017 owns;
+- enterprise SCIM provisioning;
+- UI implementation;
+- changing the NetKingdom tenant claim standard.
+
+## Tasks
+
+```task
+id: NK-WP-0016-T1
+status: todo
+priority: high
+state_hub_task_id: "d4bb49a9-dffe-4317-aea2-761d737c5627"
+```
+
+**Tenant model and context.** Implement tenant identifiers aligned with
+NetKingdom conventions, request tenant context resolution, tenant validation,
+and explicit platform-vs-tenant plane handling.
+
+```task
+id: NK-WP-0016-T2
+status: todo
+priority: high
+state_hub_task_id: "4a9083c0-f0bd-4dad-b221-c4563ed53209"
+```
+
+**Tenant-scoped data model.** Add tenant-scoped account state, tenant profile
+values, tenant memberships, and database constraints that prevent accidental
+cross-tenant joins or updates.
+
+```task
+id: NK-WP-0016-T3
+status: todo
+priority: high
+state_hub_task_id: "4fd57616-53dc-4c10-bf95-553319186005"
+```
+
+**Tenant administration boundary.** Implement scope-admin operations for
+tenant users and memberships while denying platform-root operations to tenant
+admins. Model break-glass and platform operator paths as separate policy
+cases.
+
+```task
+id: NK-WP-0016-T4
+status: todo
+priority: high
+state_hub_task_id: "dc0fc00a-5228-4b99-9fa1-6a7f6b557aac"
+```
+
+**flex-auth tenant integration.** Extend authorization requests with tenant,
+resource, action, target user, membership, assurance, and scope facts. Add
+resource/action manifests or fixtures for tenant user management operations.
+
+```task
+id: NK-WP-0016-T5
+status: todo
+priority: medium
+state_hub_task_id: "17460786-7af0-4e67-8169-80c2c29934e6"
+```
+
+**Tenant-aware events and audit.** Ensure audit records and outbox events
+carry tenant context, correlation IDs, actor tenant, target tenant, and
+redacted change summaries.
+
+```task
+id: NK-WP-0016-T6
+status: todo
+priority: high
+state_hub_task_id: "a899832f-63e6-4417-bc1d-ca3c5ea89061"
+```
+
+**Tenant test scenarios.** Add tests for cross-tenant denial, tenant admin
+allowed actions, tenant admin platform-root denial, tenant profile precedence,
+tenant membership changes, local issuer rejection in production mode, and
+audit correlation.
+
+```task
+id: NK-WP-0016-T7
+status: todo
+priority: medium
+state_hub_task_id: "187cdc5d-7cba-432e-8201-34bb437ba8e8"
+```
+
+**Tenant onboarding diagnostics.** Add a diagnostic command or endpoint that
+reports whether a tenant has required applications, memberships, policy
+bindings, catalog scopes, and audit readiness.
+
+## Acceptance Criteria
+
+- Tenant context is explicit on every tenant-scoped operation.
+- Tenant data is isolated by schema constraints and authorization checks.
+- Tenant admins cannot modify platform-root resources or global policy
+  boundaries.
+- Profile resolution includes global and tenant layers deterministically.
+- Tenant audit and event records are correlated and redacted.
+- Tenant tests include both allowed and denied paths.
+
+## Dependencies And Sequencing
+
+- Depends on the isolated MVP in NK-WP-0015.
+- Can run partly in parallel with NK-WP-0017 after shared app and catalog
+  interfaces are stable.
--- a/workplans/NK-WP-0017-user-engine-multi-application-catalogs.md
+++ b/workplans/NK-WP-0017-user-engine-multi-application-catalogs.md
@@ -0,0 +1,143 @@
+---
+id: NK-WP-0017
+type: workplan
+title: "User Engine Multi-Application And Catalog Support"
+domain: netkingdom
+repo: net-kingdom
+status: ready
+owner: codex
+topic_slug: netkingdom
+planning_priority: high
+planning_order: 17
+created: "2026-05-22"
+updated: "2026-05-22"
+depends_on:
+  - NK-WP-0015
+state_hub_workstream_id: "08398d26-cadf-44bc-97ee-67da790040e6"
+---
+
+# NK-WP-0017 - User Engine Multi-Application And Catalog Support
+
+## Goal
+
+Extend user-engine from a single-app MVP into a governed multi-application
+profile and customization service. Applications should be able to register as
+profile consumers, own catalog namespaces, publish versioned customization
+catalogs, and receive application-specific projections without attribute
+collisions or data leakage.
+
+## Scope
+
+In scope:
+
+- application registry and bindings;
+- catalog namespace ownership;
+- catalog lifecycle and migration checks;
+- application-specific profile layers;
+- application runtime projections;
+- optional claims-enrichment boundary;
+- multi-app tests and examples.
+
+Out of scope:
+
+- UI implementation;
+- full marketplace or plugin ecosystem;
+- enterprise SCIM server;
+- making user-engine a token issuer.
+
+## Tasks
+
+```task
+id: NK-WP-0017-T1
+status: todo
+priority: high
+state_hub_task_id: "9363492d-49af-4929-bb64-576ed8c47ddb"
+```
+
+**Application registry split.** Implement user-engine application records as
+profile-consumer records with explicit bindings to IAM OIDC clients,
+flex-auth protected systems, catalog namespaces, event identities, and
+deployment metadata.
+
+```task
+id: NK-WP-0017-T2
+status: todo
+priority: high
+state_hub_task_id: "cd9dff26-d570-4f9f-9ebf-6f20eddf3ef0"
+```
+
+**Catalog namespace governance.** Implement namespace ownership, catalog
+semantic versions, lifecycle states, compatibility checks, sensitivity
+downgrade prevention, and activation/deprecation flows.
+
+```task
+id: NK-WP-0017-T3
+status: todo
+priority: high
+state_hub_task_id: "6bbe4250-a6e7-4ecf-b916-7e79eddd76f6"
+```
+
+**Application profile layer.** Add application-specific profile values,
+preferences, defaults, and effective-profile precedence rules that compose
+with global and tenant layers.
+
+```task
+id: NK-WP-0017-T4
+status: todo
+priority: high
+state_hub_task_id: "29012ed5-f6c2-455f-8999-037a653d14e1"
+```
+
+**Application runtime projections.** Implement app-specific projection
+requests with allowed projection types, attribute-level visibility,
+mutability, sensitivity, and redaction rules.
+
+```task
+id: NK-WP-0017-T5
+status: todo
+priority: medium
+state_hub_task_id: "a3226c20-1278-409e-a49d-965e4783dc7a"
+```
+
+**Claims-enrichment adapter boundary.** Specify and, if appropriate, prototype
+an optional cache-backed projection used by IAM-side claims enrichment. The
+implementation must not place user-engine synchronously in the default token
+issuance path.
+
+```task
+id: NK-WP-0017-T6
+status: todo
+priority: high
+state_hub_task_id: "ada5a9f5-19f6-4e9e-a176-b1b47ec36ca7"
+```
+
+**Multi-app tests.** Add tests for namespace collisions, catalog activation
+failure, application-specific profile values, projection redaction,
+application access denial, catalog migration checks, and onboarding two demo
+applications side by side.
+
+```task
+id: NK-WP-0017-T7
+status: todo
+priority: medium
+state_hub_task_id: "09f38d5c-af6c-4d95-a570-e5a5c25d7cfe"
+```
+
+**Developer-facing integration examples.** Provide examples or fixtures that
+show how a new application registers, owns a catalog namespace, requests
+runtime projections, and handles profile-change events.
+
+## Acceptance Criteria
+
+- Multiple applications can register without attribute collisions.
+- Catalog ownership and lifecycle are enforced.
+- Application-specific profile values resolve consistently with global and
+  tenant layers.
+- Runtime projections expose only eligible attributes.
+- Claims enrichment is explicitly optional and adapter-owned.
+- Tests cover multi-app positive, negative, and migration paths.
+
+## Dependencies And Sequencing
+
+- Depends on NK-WP-0015.
+- Coordinates with NK-WP-0016 where application behavior is tenant-scoped.
--- a/workplans/NK-WP-0018-user-engine-integrated-test-scenarios.md
+++ b/workplans/NK-WP-0018-user-engine-integrated-test-scenarios.md
@@ -0,0 +1,140 @@
+---
+id: NK-WP-0018
+type: workplan
+title: "User Engine Integrated Test Scenarios"
+domain: netkingdom
+repo: net-kingdom
+status: ready
+owner: codex
+topic_slug: netkingdom
+planning_priority: high
+planning_order: 18
+created: "2026-05-22"
+updated: "2026-05-22"
+depends_on:
+  - NK-WP-0016
+  - NK-WP-0017
+state_hub_workstream_id: "6f75035a-e056-4eab-8fdb-00a18bacdf87"
+---
+
+# NK-WP-0018 - User Engine Integrated Test Scenarios
+
+## Goal
+
+Extend user-engine test coverage from isolated MVP tests to realistic
+standalone, platform, multi-tenant, multi-application, audit, and performance
+scenarios. The test suite should prove the architecture boundaries rather than
+only individual functions.
+
+## Scope
+
+In scope:
+
+- scenario matrix;
+- local identity and IAM Profile fixtures;
+- flex-auth authorization harness;
+- multi-tenant and multi-application integration tests;
+- audit/outbox/correlation tests;
+- effective-profile performance tests;
+- CI/readiness gates.
+
+Out of scope:
+
+- full production Railiance deployment;
+- full enterprise SCIM conformance;
+- UI end-to-end tests for future UI repos.
+
+## Tasks
+
+```task
+id: NK-WP-0018-T1
+status: todo
+priority: high
+state_hub_task_id: "6da86ef6-ea8b-49b9-8897-cbed00f6e61d"
+```
+
+**Scenario matrix.** Define canonical scenarios: standalone single-app,
+standalone denied access, platform local-identity fixture, tenant admin,
+platform operator, cross-tenant denial, two applications with separate
+catalogs, sensitive projection redaction, and event/audit replay.
+
+```task
+id: NK-WP-0018-T2
+status: todo
+priority: high
+state_hub_task_id: "e3424148-90d6-4c43-8f15-988f2a21d166"
+```
+
+**Identity fixtures.** Add IAM Profile claim fixtures for human, service,
+agent, delegated agent, tenant admin, platform operator, break-glass, local
+development issuer, and invalid/expired/missing-tenant tokens.
+
+```task
+id: NK-WP-0018-T3
+status: todo
+priority: high
+state_hub_task_id: "23fa4617-e7ce-4cdc-b753-489ec361757b"
+```
+
+**Authorization harness.** Add a deterministic flex-auth-compatible test
+harness that supports allow, deny, obligation, tenant-boundary, assurance, and
+bulk decision scenarios.
+
+```task
+id: NK-WP-0018-T4
+status: todo
+priority: high
+state_hub_task_id: "33c53479-7856-42ee-b9ee-8795aa73c39a"
+```
+
+**End-to-end domain scenarios.** Test full flows from actor claims through
+authorization, mutation, profile resolution, projection, audit write, and
+outbox event creation.
+
+```task
+id: NK-WP-0018-T5
+status: todo
+priority: medium
+state_hub_task_id: "fc2d73e4-1f45-4891-9c31-1a4dc2f3a002"
+```
+
+**Performance and cache tests.** Add tests or benchmarks for effective-profile
+resolution, projection rendering, authorization batching, request-scoped
+memoization, and cache invalidation on catalog/profile/membership changes.
+
+```task
+id: NK-WP-0018-T6
+status: todo
+priority: high
+state_hub_task_id: "26b63aa0-deb6-4b4d-9388-6b7e531bd4ff"
+```
+
+**Security and privacy negative tests.** Cover local issuer rejection in
+production, sensitive attribute leakage, cross-tenant reads/writes, admin
+overreach, catalog sensitivity downgrade, namespace hijack, stale membership
+facts, and missing audit correlation.
+
+```task
+id: NK-WP-0018-T7
+status: todo
+priority: medium
+state_hub_task_id: "a46e6e78-71a1-4518-881f-85b39269f4a8"
+```
+
+**CI and readiness gates.** Add repeatable commands for unit, integration,
+scenario, and conformance-style tests. Document what must pass before a
+platform deployment or UI consumer can depend on user-engine.
+
+## Acceptance Criteria
+
+- The test suite proves standalone, tenant, multi-app, authorization, profile,
+  projection, audit, and event behavior.
+- Negative tests cover the architecture review risks.
+- Scenario fixtures are readable enough for future agents and developers to
+  extend.
+- CI/readiness commands are documented and deterministic.
+
+## Dependencies And Sequencing
+
+- Depends on NK-WP-0016 and NK-WP-0017.
+- Feeds the final implementation assessment in NK-WP-0019.
--- a/workplans/NK-WP-0019-user-engine-finalization-polish.md
+++ b/workplans/NK-WP-0019-user-engine-finalization-polish.md
@@ -0,0 +1,142 @@
+---
+id: NK-WP-0019
+type: workplan
+title: "User Engine Implementation Assessment And Polish"
+domain: netkingdom
+repo: net-kingdom
+status: ready
+owner: codex
+topic_slug: netkingdom
+planning_priority: medium
+planning_order: 19
+created: "2026-05-22"
+updated: "2026-05-22"
+depends_on:
+  - NK-WP-0018
+state_hub_workstream_id: "d2daa8b4-8ecf-4377-b382-492e653735f7"
+---
+
+# NK-WP-0019 - User Engine Implementation Assessment And Polish
+
+## Goal
+
+Assess the implemented user-engine against its PRD, architecture blueprint,
+NetKingdom boundary contracts, and integrated test scenarios. Finalize
+documentation, operational readiness, release packaging, and handoff criteria
+for future `user-account` and `user-manager` UI work.
+
+## Scope
+
+In scope:
+
+- implementation review against PRD and blueprint;
+- boundary review against NetKingdom IAM Profile, flex-auth, key-cape,
+  Keycloak, OpenBao, and Railiance responsibilities;
+- API/schema polish;
+- operability and documentation polish;
+- release readiness;
+- State Hub and responsibility-map reconciliation;
+- UI handoff readiness.
+
+Out of scope:
+
+- building user-account or user-manager UIs;
+- adding new major product capabilities;
+- enterprise provisioning beyond documented adapter boundaries.
+
+## Tasks
+
+```task
+id: NK-WP-0019-T1
+status: todo
+priority: high
+state_hub_task_id: "116b5362-ebbf-4d21-83e8-bbc82e80a71a"
+```
+
+**Implementation assessment.** Review implemented behavior against
+`INTENT.md`, the PRD, the architecture blueprint, the architecture review,
+and NK-WP-0014 boundary contracts. Record gaps, accepted deviations, and
+follow-up work.
+
+```task
+id: NK-WP-0019-T2
+status: todo
+priority: high
+state_hub_task_id: "08bd8ca3-dd7e-41c9-b8d2-c9b7c72ceb0a"
+```
+
+**Boundary and responsibility review.** Verify that user-engine has not
+absorbed identity provider, MFA, credential, PDP, UI, or deployment
+responsibilities. Update NetKingdom responsibility-map classification if
+user-engine is now a shared platform service holding NetKingdom-orchestrated
+resources.
+
+```task
+id: NK-WP-0019-T3
+status: todo
+priority: medium
+state_hub_task_id: "b8ff89a1-cdfb-445a-ae4d-ca4fd4a455eb"
+```
+
+**API and schema polish.** Stabilize endpoint names, error taxonomy, catalog
+descriptor schemas, projection responses, audit event shapes, and migration
+contracts. Remove accidental implementation details from public contracts.
+
+```task
+id: NK-WP-0019-T4
+status: todo
+priority: medium
+state_hub_task_id: "f57d87d7-fdc8-485c-ba93-86c5a8342f04"
+```
+
+**Operability polish.** Add readiness diagnostics, metrics, structured logs,
+audit correlation checks, outbox drain diagnostics, cache status, and
+runbooks for common failure modes.
+
+```task
+id: NK-WP-0019-T5
+status: todo
+priority: medium
+state_hub_task_id: "42a01f4e-c646-4551-bd94-e122c9c16226"
+```
+
+**Documentation and examples.** Finalize developer docs for standalone setup,
+application onboarding, catalog authoring, projection consumption, tenant
+administration boundaries, and event/audit integration.
+
+```task
+id: NK-WP-0019-T6
+status: todo
+priority: medium
+state_hub_task_id: "7838d62b-94eb-437a-8418-7a900cde9716"
+```
+
+**Release readiness.** Decide versioning, packaging, image/build artifacts,
+SBOM/security scan requirements, migration policy, and compatibility
+guarantees for future consumers.
+
+```task
+id: NK-WP-0019-T7
+status: todo
+priority: low
+state_hub_task_id: "19569b30-c8df-441a-b815-c9217a82abaf"
+```
+
+**UI handoff readiness.** Produce the API, projection, catalog metadata, and
+test fixtures needed for future user-account and user-manager repos to start
+without inventing separate backends.
+
+## Acceptance Criteria
+
+- A final assessment document records what was implemented, what changed, and
+  what remains open.
+- Public API/schema/catalog/projection contracts are coherent and documented.
+- Operability and release-readiness checks pass.
+- NetKingdom State Hub and responsibility-map records are reconciled.
+- Future UI work has a clear backend contract.
+
+## Dependencies And Sequencing
+
+- Depends on NK-WP-0018 integrated scenario tests.
+- Closes the initial user-engine implementation program and feeds future UI
+  workplans.