---
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
```