user-engine/workplans/USER-WP-0009-postgres-durable-store-requirements.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
USER-WP-0009	workplan	Postgres Durable Store Consumer Requirements	netkingdom	user-engine	finished	codex	netkingdom	high	9	2026-06-05	2026-06-15	USER-WP-0007	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

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.

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.

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.

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.

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.

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:

make test
Ran 42 tests in 0.134s
OK