Add user-engine architecture workplans

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.