generated from coulomb/repo-seed
181 lines
6.7 KiB
Markdown
181 lines
6.7 KiB
Markdown
---
|
|
id: USER-WP-0009
|
|
type: workplan
|
|
title: "Postgres Durable Store Consumer Requirements"
|
|
domain: netkingdom
|
|
repo: user-engine
|
|
status: finished
|
|
owner: codex
|
|
topic_slug: netkingdom
|
|
planning_priority: high
|
|
planning_order: 9
|
|
created: "2026-06-05"
|
|
updated: "2026-06-15"
|
|
depends_on:
|
|
- USER-WP-0007
|
|
state_hub_workstream_id: "b5c85993-4aa2-4a8d-98b6-d174ab1b4538"
|
|
---
|
|
|
|
# USER-WP-0009 - Postgres Durable Store Consumer Requirements
|
|
|
|
## Goal
|
|
|
|
Define, from the `user-engine` consumer perspective, what a durable
|
|
Postgres-backed store must provide before user-engine depends on it in
|
|
NetKingdom. The 2026-06-15 review also identified and closed one missing
|
|
durable-store contract in this repository: `UserEngineService` now consumes an
|
|
adapter-neutral store protocol instead of the concrete in-memory store. This
|
|
workplan still does not implement the Postgres adapter, provision databases,
|
|
create tenant infrastructure, or choose the final provider repository design.
|
|
|
|
## Scope Direction
|
|
|
|
`user-engine` should be able to consume a NetKingdom-provided, tenant-aware,
|
|
security-integrated Postgres capability through an adapter boundary. The
|
|
future Postgres/provider repository should own provisioning, credentials,
|
|
network policy, tenant isolation primitives, backup/restore, platform
|
|
observability, and operational security. `user-engine` should own its domain
|
|
schema, migrations for its own tables, store semantics, and conformance tests.
|
|
|
|
## Non-Goals
|
|
|
|
- Do not implement a Postgres store adapter in this workplan.
|
|
- Do not add database dependencies to the package in this workplan.
|
|
- Do not provision Postgres, schemas, roles, credentials, certificates, or
|
|
network access from this repository.
|
|
- Do not decide the final independent infrastructure repository layout.
|
|
- Do not move audit-platform, IAM, secrets, or authorization ownership into
|
|
user-engine.
|
|
- Do not change the public service surface unless the requirements reveal a
|
|
missing durable-store contract.
|
|
|
|
## Tasks
|
|
|
|
```task
|
|
id: USER-WP-0009-T1
|
|
status: done
|
|
priority: high
|
|
state_hub_task_id: "64c578e1-e2a1-48d4-8da9-659d4f881ef3"
|
|
```
|
|
|
|
Inventory the current in-memory store behavior and document the durable
|
|
persistence semantics user-engine consumers already rely on: users, accounts,
|
|
tenant accounts, external identities, applications, bindings, catalogs,
|
|
profile values, memberships, audit records, outbox events, readiness, and
|
|
schema version reporting.
|
|
|
|
```task
|
|
id: USER-WP-0009-T2
|
|
status: done
|
|
priority: high
|
|
state_hub_task_id: "19cfd23e-8a87-416d-b948-c727e8c5a11c"
|
|
```
|
|
|
|
Create a consumer-facing requirements document for a Postgres durable store.
|
|
Cover connection handoff, tenant context, schema ownership, migrations,
|
|
transactions, isolation, constraints, query behavior, audit/outbox durability,
|
|
security, observability, backup/restore expectations, and acceptance tests.
|
|
|
|
```task
|
|
id: USER-WP-0009-T3
|
|
status: done
|
|
priority: high
|
|
state_hub_task_id: "d3b388de-bb79-41d5-805e-d2def88ac926"
|
|
```
|
|
|
|
Define the boundary between user-engine and the future NetKingdom Postgres
|
|
provider repository. Specify which responsibilities belong to the provider,
|
|
which belong to the user-engine adapter, and which must remain external IAM,
|
|
secrets, authorization, or audit-platform concerns.
|
|
|
|
```task
|
|
id: USER-WP-0009-T4
|
|
status: done
|
|
priority: medium
|
|
state_hub_task_id: "d0e05af7-d777-4948-b072-79f1ffb9fc3a"
|
|
```
|
|
|
|
Identify required changes, if any, to the existing store protocol or migration
|
|
contract so durable implementations can satisfy the same service behavior as
|
|
the isolated MVP without leaking Postgres concepts into domain code.
|
|
|
|
```task
|
|
id: USER-WP-0009-T5
|
|
status: done
|
|
priority: medium
|
|
state_hub_task_id: "3c428960-be5b-411e-bd9b-7cba833abba8"
|
|
```
|
|
|
|
Define conformance scenarios and failure-mode tests the future Postgres store
|
|
must pass. Include transaction rollback, duplicate identity prevention,
|
|
tenant-boundary enforcement, outbox exactly-once handoff semantics, migration
|
|
readiness, and redacted diagnostics.
|
|
|
|
```task
|
|
id: USER-WP-0009-T6
|
|
status: done
|
|
priority: medium
|
|
state_hub_task_id: "d606094a-254c-46d5-9bb8-a3449ce61c2c"
|
|
```
|
|
|
|
Record open questions for the independent provider repository, including
|
|
tenant isolation model, credential lease model, schema-per-service or
|
|
database-per-tenant strategy, migration runner ownership, backup unit, PITR
|
|
expectations, encryption, and operational runbooks.
|
|
|
|
## Acceptance Criteria
|
|
|
|
- `docs/postgres-durable-store-consumer-requirements.md` exists and is clear
|
|
enough for an independent NetKingdom Postgres provider repo to implement
|
|
against.
|
|
- The document describes user-engine as a consumer of a secure Postgres
|
|
capability, not as the owner of Postgres provisioning or platform security.
|
|
- Requirements cover domain persistence, transactions, migrations, tenant
|
|
isolation, security, audit/outbox durability, operability, and acceptance
|
|
tests.
|
|
- The provider-repo boundary is explicit and avoids duplicating IAM, secrets,
|
|
authorization, audit-platform, or infrastructure ownership.
|
|
- `UserEngineService` depends on an adapter-neutral store protocol with
|
|
readiness, query, transaction, audit, outbox, and diagnostics semantics.
|
|
- No Postgres implementation code is added as part of this workplan.
|
|
|
|
## Expected Outputs
|
|
|
|
- `docs/postgres-durable-store-consumer-requirements.md`
|
|
- Store-boundary notes suitable for a future provider repo.
|
|
- `UserEngineStore` protocol and local-store conformance behavior.
|
|
- Follow-up implementation workplan inputs for a Postgres adapter.
|
|
|
|
## Implementation Notes
|
|
|
|
Implemented on 2026-06-15:
|
|
|
|
- Added `UserEngineStore` in `src/user_engine/ports.py` as the durable
|
|
persistence boundary for service behavior.
|
|
- Moved `UserEngineService` from the concrete in-memory store type to the
|
|
store protocol.
|
|
- Replaced service reads of local dict/list fields with protocol accessors for
|
|
users, identities, applications, bindings, catalogs, audit, outbox, and
|
|
diagnostics.
|
|
- Added store transaction boundaries around mutating writes so domain changes,
|
|
local audit records, and outbox events commit or roll back together.
|
|
- Kept authorization-denial audit records durable without emitting outbox
|
|
events, including when a denial happens inside a composed outer transaction.
|
|
- Extended `InMemoryUserEngineStore` as the reference adapter with query
|
|
helpers, record counts, pending outbox access, audit-log access, and nested
|
|
transaction rollback semantics.
|
|
- Added conformance tests for protocol-only store consumption, failed-mutation
|
|
rollback, and denial-audit persistence across rollback.
|
|
- Updated the durable-store and public contract docs to describe the new
|
|
adapter boundary.
|
|
- No Postgres adapter, database dependency, provisioning, credentials, or
|
|
infrastructure ownership was added.
|
|
|
|
Verification:
|
|
|
|
```text
|
|
make test
|
|
Ran 42 tests in 0.134s
|
|
OK
|
|
```
|