generated from coulomb/repo-seed
182 lines
6.2 KiB
Markdown
182 lines
6.2 KiB
Markdown
---
|
|
id: NK-WP-0014
|
|
type: workplan
|
|
title: "User Engine Preparation And Boundary Contracts"
|
|
domain: netkingdom
|
|
repo: net-kingdom
|
|
status: finished
|
|
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.
|
|
|
|
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
|
|
|
|
```task
|
|
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.
|
|
|
|
```task
|
|
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.
|
|
|
|
```task
|
|
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.
|
|
|
|
```task
|
|
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.
|
|
|
|
```task
|
|
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.
|
|
|
|
```task
|
|
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`.
|