Implement durable store contract and registration roadmap

docs/postgres-durable-store-consumer-requirements.md

@@ -1,7 +1,7 @@
 # Postgres Durable Store Consumer Requirements
 
-Status: requirements
-Date: 2026-06-05
+Status: requirements + store contract boundary
+Date: 2026-06-15
 Related workplan: USER-WP-0009
 
 ## Purpose
@@ -13,6 +13,12 @@ NetKingdom infrastructure repository provides a tenant-aware, security
 integrated Postgres capability, and `user-engine` consumes that capability
 through a durable store adapter.
 
+The consumer-side contract is now represented in code by
+`user_engine.ports.UserEngineStore`. The protocol is intentionally
+adapter-neutral: it names the service behavior a durable store must satisfy
+without adding a Postgres dependency or giving this repository ownership of
+database provisioning.
+
 ## Consumer Story
 
 As a `user-engine` consumer, I want the service to persist identity-domain
@@ -85,6 +91,22 @@ the isolated store:
 - Support the same service-level exceptions for not found, conflict,
   validation, and authorization-denied flows.
 
+### Store Protocol Boundary
+
+`UserEngineService` consumes the `UserEngineStore` protocol rather than local
+in-memory collections. A future Postgres adapter must provide:
+
+- Schema readiness through `schema_version`, `ready`, and `migrate`.
+- A `transaction` context that makes each mutating write unit atomic.
+- Logical read/write methods for users, accounts, tenant accounts, external
+  identities, memberships, applications, bindings, catalogs, family
+  invitations, and profile values.
+- Audit and outbox append/read methods that preserve write order.
+- Adapter-neutral record counts for diagnostics and operability snapshots.
+
+Concrete tables, SQL, connection pools, and row locks remain adapter details.
+Service and domain code should not depend on Postgres-specific concepts.
+
 ### Identity And Account Constraints
 
 - `(issuer, subject)` must uniquely identify one external identity link.
@@ -157,6 +179,9 @@ the isolated store:
   them to `ConflictError` where appropriate.
 - Migration and outbox claiming should use explicit locking strategies that do
   not require consumers to understand Postgres internals.
+- Authorization-denial audit records must persist without outbox events even
+  when the denied operation occurs inside a composed transaction that rolls
+  back domain writes.
 
 ### Migration Requirements
 
@@ -253,10 +278,16 @@ A future Postgres adapter should pass conformance tests for:
 
 ## First Implementation Follow-Ups
 
-After this requirements work is accepted, likely follow-up work should be:
+The first consumer-side follow-up is complete: `UserEngineStore` defines the
+adapter boundary and the in-memory store acts as the reference implementation
+for service-level behavior.
+
+Likely future follow-up work should be:
 
-- Define the durable store protocol changes, if any.
 - Add a Postgres adapter behind the existing store boundary.
 - Add migration files for user-engine tables.
+- Add provider-backed conformance tests for locking, uniqueness races,
+  migration readiness, outbox claiming, redacted diagnostics, and restore
+  validation.
 - Add conformance tests that run against both in-memory and Postgres stores.
 - Integrate the adapter with the future NetKingdom Postgres provider repo.