net-kingdom/workplans/NK-WP-0014-user-engine-preparation-boundary-contracts.md

id, type, title, domain, repo, status, owner, topic_slug, planning_priority, planning_order, created, updated, depends_on, state_hub_workstream_id

id	type	title	domain	repo	status	owner	topic_slug	planning_priority	planning_order	created	updated	depends_on	state_hub_workstream_id
NK-WP-0014	workplan	User Engine Preparation And Boundary Contracts	netkingdom	net-kingdom	finished	codex	netkingdom	high	14	2026-05-22	2026-05-22	NK-WP-0012 NK-WP-0013	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.

NetKingdom keeps this workplan because it owns cross-repo boundary and orchestration guidance. Implementation work now lives in the user-engine repository as USER-WP-0001 through USER-WP-0006.

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.
• NetKingdom/user-engine interface guidance.

Out of scope:

• implementing user-engine production code, which belongs in the user-engine repository workplans;
• implementing UI repos;
• implementing SCIM or enterprise federation adapters;
• changing the NetKingdom IAM Profile.

Tasks

id: NK-WP-0014-T1
status: done
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.

Initial guidance lives in docs/user-engine-interface-guidance.md and should be hardened into versioned contracts as implementation feedback arrives.

id: NK-WP-0014-T2
status: done
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.

id: NK-WP-0014-T3
status: done
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.

id: NK-WP-0014-T4
status: done
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.

id: NK-WP-0014-T5
status: done
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.

id: NK-WP-0014-T6
status: done
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.
• user-engine repo-local workplans carry implementation tasks, while NetKingdom retains only boundary, orchestration, and responsibility-map work.
• NetKingdom responsibility-map updates are either applied or explicitly deferred until user-engine becomes a shared platform service.

Completion Notes

Completed on 2026-05-22:

• Added the canonical versioned contract at canon/standards/user-engine-boundary-contract_v0.1.md.
• Promoted docs/user-engine-interface-guidance.md to an implementation guide that points at the canonical contract.
• Confirmed docs/responsibility-map.md already includes user-engine as an orchestrated repository and names NetKingdom's boundary responsibilities.
• Confirmed /home/worsch/user-engine already carries the required repo-local preparation artifacts: SCOPE.md, wiki/ArchitectureBlueprint.md, docs/development.md, docs/configuration.md, docs/interfaces/netkingdom-integration.md, and USER-WP-0001 through USER-WP-0006.

Dependencies And Sequencing

• Depends on NK-WP-0012 for IAM Profile consumption rules.
• Depends on NK-WP-0013 for NetKingdom meta-orchestration conventions.
• Gates implementation work in /home/worsch/user-engine, now tracked as USER-WP-0001 through USER-WP-0006.