rcf-lite 0.26.0 → 0.28.0

package/blueprints/persistence-data-postgres/contributions/requirements/persistence-data-postgres-req-004.json

@@ -2,7 +2,7 @@
   "reqId": "persistence-data-postgres-REQ-004",
   "prdId": "PRD-001",
   "title": "Transactional atomicity: multi-statement writes through a transaction helper roll back on any error",
-  "description": "Multi-statement writes that require atomicity are issued through the facade's transaction helper, which wraps client.query('BEGIN') around a callback, awaits the callback's statements (each issued through pg.query with the prepared-statement discipline in REQ-003), and issues client.query('COMMIT') on the callback's successful completion. If any statement inside the callback throws (including a constraint violation the driver surfaces as an error), the helper issues client.query('ROLLBACK'), releases the client back to the pool, and emits a transactionRolledBack lifecycle event carrying the failing statement's zero-based index inside the callback. The helper does not swallow the underlying error; it re-throws after the rollback so the caller observes the failure and the facade's own error boundary constructs the internal error record.",
+  "description": "Multi-statement writes that require atomicity are issued through the facade's transaction helper owned on TAC-2803-persistence-data-postgres-transaction-helper.interfaces.withTransaction. The helper wraps the transaction-control primitives named there around a consumer callback, awaits the callback's statements (each issued through the prepared-statement discipline in REQ-003), commits on the callback's successful completion, and rolls back with a transactionRolledBack lifecycle event on any statement failure inside the callback (including a constraint violation the driver surfaces as an error). The lifecycle event carries the failing statement's zero-based index inside the callback. The helper does not swallow the underlying error; it re-throws after the rollback so the caller observes the failure and the facade's own error boundary constructs the internal error record.",
   "category": "functional",
   "domain": "persistence",
   "priority": "must",
@@ -11,8 +11,12 @@
     "blueprint:persistence-data-postgres",
     "category:04-transaction-helper"
   ],
-  "version": "1.0.0",
+  "version": "1.0.1",
   "status": "approved",
   "createdAt": "2026-09-06T15:47:00.000Z",
-  "updatedAt": "2026-09-06T15:47:00.000Z"
+  "updatedAt": "2026-09-10T00:00:00Z",
+  "deliveredBy": {
+    "tacId": "TAC-2803-persistence-data-postgres-transaction-helper",
+    "field": "responsibilities.transactionAtomicity"
+  }
 }

package/blueprints/persistence-data-postgres/contributions/requirements/persistence-data-postgres-req-005.json

@@ -2,7 +2,7 @@
   "reqId": "persistence-data-postgres-REQ-005",
   "prdId": "PRD-001",
   "title": "Two-path recovery: scheduled pg_dump artefact PLUS vendor point-in-time recovery, both elicited, both required",
-  "description": "The recovery model is two-path and both paths are required at v1.0.0: (a) a scheduled export runner drives pg_dump via child_process.execFile against the elicited connection URL, writes the artefact to the elicited destination (a filesystem path, an S3 URL, an operator-owned path), and emits a backupExported lifecycle event carrying the artefact path and a completion timestamp; (b) the deploy target's own point-in-time recovery is enabled and its cadence and retention window are elicited (a managed Postgres cluster's PITR window, a self-managed cluster's WAL-archive posture). Neither path is optional. A fresh Postgres primed from a pg_dump artefact reads the rows committed at or before the artefact's completion timestamp; a fresh Postgres restored to a PITR point reads the rows committed at or before that point.",
+  "description": "The recovery model is two-path and both paths are required at v1.0.0: (a) a scheduled export runner drives pg_dump via child_process.execFile against the elicited connection URL, writes the artefact to the elicited destination (a filesystem path, an S3 URL, an operator-owned path), and emits a backupExported lifecycle event carrying the artefact path and a completion timestamp; (b) the deploy target's own point-in-time recovery is enabled and its cadence and retention window are elicited (a managed Postgres cluster's PITR window, a self-managed cluster's WAL-archive posture). Neither path is optional. A fresh Postgres primed from a pg_dump artefact reads the rows committed at or before the artefact's completion timestamp; a fresh Postgres restored to a PITR point reads the rows committed at or before that point. The recovery-destination is elicited at apply time (a filesystem path, an S3 URL, or an operator-owned path). The recovery-cadence is elicited (daily is the shipped default; hourly is the higher-frequency alternative; weekly is the lower-frequency alternative, per ADR-2804). The pitr-provider path is elicited (hosted vendor PITR, or self-managed WAL archiving); both paths are required together at v1.0.0.",
   "category": "functional",
   "domain": "persistence",
   "priority": "must",
@@ -14,5 +14,9 @@
   "version": "1.0.0",
   "status": "approved",
   "createdAt": "2026-09-06T15:47:00.000Z",
-  "updatedAt": "2026-09-06T15:47:00.000Z"
+  "updatedAt": "2026-09-09T00:00:00Z",
+  "deliveredBy": {
+    "tacId": "TAC-2804-persistence-data-postgres-recovery-runner",
+    "field": "responsibilities.pg_dump"
+  }
 }

package/blueprints/persistence-data-postgres/contributions/requirements/persistence-data-postgres-req-006.json

@@ -2,7 +2,7 @@
   "reqId": "persistence-data-postgres-REQ-006",
   "prdId": "PRD-001",
   "title": "Connection-pool posture per deploy target: long-lived pool on Node, request-scoped isolation on container",
-  "description": "The facade opens a long-lived pg.Pool for the lifetime of the Node process on a long-lived-Node deploy target (a monolithic Node server, a container platform holding warm instances). On a request-scoped container platform (a serverless-container target that spins fresh instances per request, a Workers-adjacent target via the round-6 Hyperdrive adapter at ADR-2801), the facade opens a pool sized to the request budget and disposes it at request end, or delegates the pool to the round-6 Hyperdrive-managed connection pool without holding a Node-side long-lived pool. Pool size, idle timeout, and query timeout are elicited defaults that the operator overrides per target; the shipped defaults are pool size 10, idleTimeoutMillis 30000, connectionTimeoutMillis 5000, per the node-postgres pool defaults. The pool-posture-smoke probe drives twenty concurrent queries at pool size 5 and asserts all return with no timeout; the probe does not impose a sizing formula.",
+  "description": "The facade opens a long-lived pg.Pool for the lifetime of the Node process on a long-lived-Node deploy target (a monolithic Node server, a container platform holding warm instances). On a request-scoped container platform (a serverless-container target that spins fresh instances per request, a Workers-adjacent target via the round-6 Hyperdrive adapter at ADR-2801), the facade opens a pool sized to the request budget and disposes it at request end, or delegates the pool to the round-6 Hyperdrive-managed connection pool without holding a Node-side long-lived pool. Pool size, idle timeout, and query timeout are elicited defaults that the operator overrides per target; the shipped defaults are pool size 10, idleTimeoutMillis 30000, connectionTimeoutMillis 5000, per the node-postgres pool defaults. The pool-posture-smoke probe drives twenty concurrent queries at pool size 5 and asserts all return with no timeout; the probe does not impose a sizing formula. Runner-mode is elicited per ADR-2803: atBoot runs migrations on process boot before the facade opens (right for a long-lived Node target); ciStep runs migrations as a discrete CI step before the deploy (right for Workers-adjacent or container-scheduled targets). Pool posture reads the elicited idle-timeout-ms (default 30000 per node-postgres) and connection-timeout-ms (default 5000) at boot; a container target may set idle-timeout-ms to zero.",
   "category": "technical",
   "domain": "persistence",
   "priority": "must",
@@ -14,5 +14,9 @@
   "version": "1.0.0",
   "status": "approved",
   "createdAt": "2026-09-06T15:47:00.000Z",
-  "updatedAt": "2026-09-06T15:47:00.000Z"
+  "updatedAt": "2026-09-09T00:00:00Z",
+  "deliveredBy": {
+    "tacId": "TAC-2801-persistence-data-postgres-facade",
+    "field": "responsibilities.pool"
+  }
 }

package/blueprints/persistence-data-postgres/contributions/requirements/persistence-data-postgres-req-007.json

@@ -2,10 +2,10 @@
   "reqId": "persistence-data-postgres-REQ-007",
   "prdId": "PRD-001",
   "title": "Advisory-lock helper (optional): session or transaction level per the Postgres explicit-locking reference, elicited default off",
-  "description": "The facade exposes an optional advisory-lock helper that wraps pg_advisory_lock and pg_advisory_unlock for session-level locks, and pg_advisory_xact_lock for transaction-level locks. The helper takes an integer lock key, acquires the lock, runs a callback, and releases the lock via the paired unlock verb on the session-level shape (transaction-level locks release automatically at COMMIT or ROLLBACK per https://www.postgresql.org/docs/current/explicit-locking.html). Whether the helper ships in the applied surface is elicited (advisoryLockHelper: off, session, or transaction); default off per the ratified Q1 answer on the round-5 spec section 10. The elicited value is recorded on the applied sidecar so a later validation pass can flag surfaces that never activated the option.",
+  "description": "The facade exposes an optional advisory-lock helper that wraps pg_advisory_lock and pg_advisory_unlock for session-level locks, and pg_advisory_xact_lock for transaction-level locks. The helper takes an integer lock key, acquires the lock, runs a callback, and releases the lock via the paired unlock verb on the session-level shape (transaction-level locks release automatically at COMMIT or ROLLBACK per https://www.postgresql.org/docs/current/explicit-locking.html). Whether the helper ships in the applied surface is elicited (advisoryLockHelper: off, session, or transaction); default off per the ratified Q1 answer on the round-5 spec section 10. The elicited value is recorded on the applied sidecar so a later validation pass can flag surfaces that never activated the option. The advisory-lock helper is elicited off (default, no helper shipped in the applied surface), session (pg_advisory_lock at session scope) or transaction (pg_advisory_xact_lock at transaction scope).",
   "category": "functional",
   "domain": "persistence",
-  "priority": "should",
+  "priority": "must",
   "rationale": "Cross-process coordination on a shared Postgres (a migration coordinator, a lock-per-tenant workflow, a one-writer-per-partition pattern) is served cleanly by advisory locks; the alternative (a bespoke locks table) reinvents what the engine already gives. Shipping the helper in v1.0.0 pins the semantics before a project depends on a workaround; defaulting off keeps the applied surface small for projects that do not need it. The session-vs-transaction distinction is load-bearing: session-level locks survive rolled-back transactions per the explicit-locking reference, and pinning the choice in the ADR is what avoids the reader-side confusion.",
   "tags": [
     "blueprint:persistence-data-postgres",
@@ -14,5 +14,9 @@
   "version": "1.0.0",
   "status": "approved",
   "createdAt": "2026-09-06T15:47:00.000Z",
-  "updatedAt": "2026-09-06T15:47:00.000Z"
+  "updatedAt": "2026-09-09T00:00:00Z",
+  "deliveredBy": {
+    "adrId": "ADR-2801-persistence-data-postgres-driver",
+    "field": "decision.advisoryLock"
+  }
 }

package/blueprints/persistence-data-postgres/contributions/tacs/tac-2802-persistence-data-postgres-migration-runner.json

@@ -9,8 +9,8 @@
   "responsibilities": [
     "Read the elicited migrations directory (default ./migrations/); enumerate .sql files sorted by their leading integer; reject a duplicate leading integer at load time (AC-27102-1).",
     "Ensure the schema_version bookkeeping table exists on first invocation; upsert only via the applied-filename row it inserts on each successful file (AC-27102-1).",
-    "For each un-applied file, in order, issue client.query('BEGIN'), read the file body, execute it, insert the applied-filename row into schema_version, issue client.query('COMMIT') (AC-27102-1).",
-    "On any statement failure inside a file's transaction, issue client.query('ROLLBACK'), emit migrationApplyFailed with the failing filename, stop the runner, exit non-zero (AC-27109-1).",
+    "For each un-applied file, in order, open the per-file transaction through the BEGIN primitive owned on TAC-2803-persistence-data-postgres-transaction-helper.interfaces.withTransaction, read the file body, execute it, insert the applied-filename row into schema_version, close through the COMMIT primitive owned on the same interface (AC-27102-1).",
+    "On any statement failure inside a file's transaction, unwind through the ROLLBACK primitive owned on TAC-2803-persistence-data-postgres-transaction-helper.interfaces.withTransaction, emit migrationApplyFailed with the failing filename, stop the runner, exit non-zero (AC-27109-1).",
     "On successful completion of every file, emit migrationsApplied with the applied-filename list."
   ],
   "internalStructure": "One CLI-invokable Node module plus a library entry point the facade may call from atBoot mode. The module reads its config (connection URL, migrations directory, bookkeeping table name) from an elicited config source; enumerates the directory; loops over un-applied files; issues one BEGIN/apply/COMMIT per file; writes the schema_version row inside the same transaction so a mid-COMMIT crash never leaves a row behind for a file whose body did not land.",

package/blueprints/persistence-data-postgres/contributions/tacs/tac-2803-persistence-data-postgres-transaction-helper.json

@@ -5,12 +5,12 @@
   "version": "1.0.0",
   "status": "approved",
   "name": "Postgres transaction helper",
-  "purpose": "The helper that wraps client.query('BEGIN') and client.query('COMMIT') around a consumer callback and issues client.query('ROLLBACK') with a transactionRolledBack event on any error, tracking the zero-based index of the failing statement inside the callback.",
+  "purpose": "The helper that wraps the transaction-control primitives around a consumer callback and rolls back with a transactionRolledBack event on any error, tracking the zero-based index of the failing statement inside the callback. The transaction-control shape is owned on `interfaces.withTransaction` below.",
   "responsibilities": [
-    "Acquire a pg.PoolClient from the facade's pool; issue client.query('BEGIN') (AC-27104-1).",
+    "Acquire a pg.PoolClient from the facade's pool; open the transaction through the BEGIN primitive owned on interfaces.withTransaction (AC-27104-1).",
     "Invoke the consumer callback with a wrapped client whose query(sql, params) delegates to the underlying client and increments a statement counter each time it is called (AC-27104-1).",
-    "On the callback's successful completion, issue client.query('COMMIT'), release the client, resolve the outer promise (AC-27104-1).",
-    "On any error thrown from a wrapped-client query or from the callback body, issue client.query('ROLLBACK'), fire transactionRolledBack on the injected event sink with { statementIndex, code }, release the client, re-throw the underlying error (AC-27104-1).",
+    "On the callback's successful completion, close the transaction through the COMMIT primitive owned on interfaces.withTransaction, release the client, resolve the outer promise (AC-27104-1).",
+    "On any error thrown from a wrapped-client query or from the callback body, unwind the transaction through the ROLLBACK primitive owned on interfaces.withTransaction, fire transactionRolledBack on the injected event sink with { statementIndex, code }, release the client, re-throw the underlying error (AC-27104-1).",
     "Preserve the underlying pg error object (code, detail, position, table, constraint) on the re-thrown error so the facade's own error boundary constructs the internal error record correctly."
   ],
   "internalStructure": "A single async function withTransaction({ pool, onEvent }) that returns a call helper. The helper wraps the pg.PoolClient in a proxy that intercepts .query() to increment the counter, forwards the arguments to the underlying client, and re-throws on error after firing the event.",
@@ -18,7 +18,7 @@
     {
       "name": "withTransaction",
       "kind": "read-write-api",
-      "description": "await store.withTransaction(async (tx) => { await tx.query(...); await tx.query(...); }). Commits on successful return, rolls back on any thrown error, fires transactionRolledBack with statementIndex on rollback."
+      "description": "await store.withTransaction(async (tx) => { await tx.query(...); await tx.query(...); }). The helper acquires a pg.PoolClient from the pool and issues the transaction-control primitives around the callback: `client.query('BEGIN')` before the first wrapped-client query, `client.query('COMMIT')` on the callback's successful return, and `client.query('ROLLBACK')` on any thrown error before releasing the client. On rollback the helper fires transactionRolledBack on the injected event sink with { statementIndex, code } and re-throws the underlying pg error."
     }
   ],
   "dependencies": [

package/blueprints/persistence-data-postgres/contributions/user-stories/persistence-data-postgres-us-27101.json

@@ -16,7 +16,8 @@
       "when": "the process boots and the facade's pool ready-check returns",
       "then": "a facadeReady event fires on the injected event sink with a payload containing databaseName, and the pool is ready to accept queries; the facade exposes named domain verbs and does not re-export the raw pg client",
       "testable": true,
-      "scope": "runtime"
+      "scope": "runtime",
+      "disposition": "template"
     },
     {
       "id": "AC-27101-2",
@@ -25,10 +26,27 @@
       "when": "grep 'from \\'pg\\'' or grep 'require(\\'pg\\')' walks the tree outside the facade directory",
       "then": "no match is found outside the facade directory; the facade's public surface exports named domain verbs only, no raw pg reference",
       "testable": true,
-      "scope": "runtime"
+      "scope": "runtime",
+      "disposition": "template"
+    },
+    {
+      "id": "AC-27101-3",
+      "description": "Credential missing at boot. Given the elicited connection-url resolves to a rejected value (an empty string or a secretRef the resolver refuses), when the facade opens on boot, then the facade refuses with a named error kind (missingConnectionUrl) and no facadeReady fires on the event sink; the error record carries no fragment of the connection URL substring.",
+      "given": "connection-url resolves to an empty string or the secretRef resolver refuses",
+      "when": "the facade opens on boot",
+      "then": "facade refuses with missingConnectionUrl; no facadeReady fires; the error record carries no URL substring",
+      "testable": true,
+      "scope": "runtime",
+      "ownerRef": {
+        "tacId": "TAC-2801-persistence-data-postgres-facade",
+        "field": "interfaces.createStore"
+      },
+      "disposition": "template"
     }
   ],
-  "tacIds": ["TAC-2801-persistence-data-postgres-facade"],
+  "tacIds": [
+    "TAC-2801-persistence-data-postgres-facade"
+  ],
   "createdAt": "2026-09-06T15:47:00.000Z",
-  "updatedAt": "2026-09-06T15:47:00.000Z"
+  "updatedAt": "2026-09-09T00:00:00Z"
 }

package/blueprints/persistence-data-postgres/contributions/user-stories/persistence-data-postgres-us-27102.json

@@ -16,10 +16,125 @@
       "when": "the migration runner applies the directory against the database",
       "then": "each file runs inside a BEGIN/COMMIT pair; after all three succeed a migrationsApplied event fires with the filename list ['001_*.sql', '002_*.sql', '003_*.sql'] and the schema_version table (or the runner's configured bookkeeping table name) carries a row per applied filename",
       "testable": true,
-      "scope": "runtime"
+      "scope": "runtime",
+      "disposition": "template"
+    },
+    {
+      "id": "AC-27102-2",
+      "description": "Malformed migration filename. Given a file under the elicited migrations directory whose name does not match the numbered forward-only pattern (for example a file without the numeric prefix, or a duplicate number), when the migration runner walks the directory, then the runner refuses with a named error kind (malformedMigrationName), the run exits non-zero, and schema_version does not advance.",
+      "given": "a file in the elicited migrations directory that does not match the numbered forward-only pattern",
+      "when": "the migration runner walks the directory",
+      "then": "the runner refuses with malformedMigrationName; the run exits non-zero; schema_version does not advance",
+      "testable": true,
+      "scope": "runtime",
+      "ownerRef": {
+        "tacId": "TAC-2802-persistence-data-postgres-migration-runner",
+        "field": "interfaces.applyAll"
+      },
+      "disposition": "template"
+    },
+    {
+      "id": "AC-27102-3",
+      "description": "Repeat-apply idempotency. Given the migrations set already applied to the target database, when the runner is invoked a second time against the same set, then no migration file re-runs, schema_version is unchanged and the run exits zero.",
+      "given": "the migrations set already applied to the target database",
+      "when": "the runner is invoked again",
+      "then": "no migration re-runs; schema_version unchanged; run exits zero",
+      "testable": true,
+      "scope": "runtime",
+      "ownerRef": {
+        "tacId": "TAC-2802-persistence-data-postgres-migration-runner",
+        "field": "interfaces.applyAll"
+      },
+      "disposition": "template"
+    },
+    {
+      "id": "AC-27102-4",
+      "description": "Migration runner tool node-pg-migrate. Given the elicited migration-runner-tool answers node-pg-migrate, when the sidecar records the answer and the CI or boot step invokes the runner, then the invocation shape is `node-pg-migrate up --database-url-var DATABASE_URL --migrations-dir <migrations-directory>` and the schema_version bookkeeping table advances once per applied .sql file recorded by node-pg-migrate's own pgmigrations table.",
+      "given": "migration-runner-tool = node-pg-migrate",
+      "when": "the sidecar records the answer and the runner is invoked",
+      "then": "the invocation is `node-pg-migrate up --database-url-var DATABASE_URL --migrations-dir <migrations-directory>` and pgmigrations records one row per applied file",
+      "testable": true,
+      "scope": "runtime",
+      "ownerRef": {
+        "adrId": "ADR-2802-persistence-data-postgres-migration-shape",
+        "field": "decision"
+      },
+      "disposition": "template"
+    },
+    {
+      "id": "AC-27102-5",
+      "description": "Migration runner tool sqitch. Given the elicited migration-runner-tool answers sqitch, when the sidecar records the answer and the CI or boot step invokes the runner, then the invocation shape is `sqitch deploy <target>` reading the elicited migrations-directory as the sqitch plan root, and the sqitch changes table advances one row per deployed change.",
+      "given": "migration-runner-tool = sqitch",
+      "when": "the sidecar records the answer and the runner is invoked",
+      "then": "the invocation is `sqitch deploy <target>` and the sqitch changes table advances one row per deployed change",
+      "testable": true,
+      "scope": "runtime",
+      "ownerRef": {
+        "adrId": "ADR-2802-persistence-data-postgres-migration-shape",
+        "field": "decision"
+      },
+      "disposition": "template"
+    },
+    {
+      "id": "AC-27102-6",
+      "description": "Migration runner tool flyway. Given the elicited migration-runner-tool answers flyway, when the sidecar records the answer and the CI or boot step invokes the runner, then the invocation shape is `flyway -url=<jdbc:postgresql://...> -locations=filesystem:<migrations-directory> migrate` and the flyway_schema_history table advances one row per applied .sql file.",
+      "given": "migration-runner-tool = flyway",
+      "when": "the sidecar records the answer and the runner is invoked",
+      "then": "the invocation is `flyway -url=<jdbc> -locations=filesystem:<migrations-directory> migrate` and flyway_schema_history advances one row per file",
+      "testable": true,
+      "scope": "runtime",
+      "ownerRef": {
+        "adrId": "ADR-2802-persistence-data-postgres-migration-shape",
+        "field": "decision"
+      },
+      "disposition": "template"
+    },
+    {
+      "id": "AC-27102-7",
+      "description": "Migration runner tool custom. Given the elicited migration-runner-tool answers custom, when the sidecar records the answer and the CI or boot step invokes the runner, then the invocation shape is the bespoke Node runner shipped in the fixture (`node ./scripts/migrate.mjs` reading the elicited migrations-directory) and the schema_version bookkeeping table it owns advances one row per applied filename inside the same transaction as the file body.",
+      "given": "migration-runner-tool = custom",
+      "when": "the sidecar records the answer and the runner is invoked",
+      "then": "the invocation is `node ./scripts/migrate.mjs` and schema_version advances one row per applied filename inside the same transaction as the file body",
+      "testable": true,
+      "scope": "runtime",
+      "ownerRef": {
+        "tacId": "TAC-2802-persistence-data-postgres-migration-runner",
+        "field": "interfaces.applyAll"
+      },
+      "disposition": "template"
+    },
+    {
+      "id": "AC-27102-8",
+      "description": "Runner mode atBoot. Given the elicited runner-mode answers atBoot, when the facade opens on process boot, then the runner's applyAll executes before the facade emits facadeReady; a fake migration that adds one row observably completes before the first domain-verb call returns; migrationsApplied fires exactly once with the applied filename list per boot.",
+      "given": "runner-mode = atBoot and one pending migration",
+      "when": "the facade opens on boot",
+      "then": "the runner applies before facadeReady fires; migrationsApplied fires exactly once per boot before the first domain-verb call returns",
+      "testable": true,
+      "scope": "runtime",
+      "ownerRef": {
+        "tacId": "TAC-2802-persistence-data-postgres-migration-runner",
+        "field": "interfaces.applyAll"
+      },
+      "disposition": "template"
+    },
+    {
+      "id": "AC-27102-9",
+      "description": "Runner mode ciStep. Given the elicited runner-mode answers ciStep, when the facade opens on process boot, then the facade does NOT invoke the runner and no migrationsApplied fires on boot; the CI pipeline's discrete migrate step (invoked before the artefact promotes) runs the same runner against the target's own connection URL and emits migrationsApplied out-of-process; a facade boot with schema_version behind the CI-applied set exits with schemaVersionBehind and refuses facadeReady.",
+      "given": "runner-mode = ciStep",
+      "when": "the facade opens on boot after or before the CI migrate step",
+      "then": "the facade does not invoke the runner on boot; migrationsApplied fires from the CI step, not the boot; a boot with schema_version behind the CI-applied set refuses facadeReady with schemaVersionBehind",
+      "testable": true,
+      "scope": "runtime",
+      "ownerRef": {
+        "adrId": "ADR-2803-persistence-data-postgres-runner-mode",
+        "field": "decision"
+      },
+      "disposition": "template"
     }
   ],
-  "tacIds": ["TAC-2802-persistence-data-postgres-migration-runner"],
+  "tacIds": [
+    "TAC-2802-persistence-data-postgres-migration-runner"
+  ],
   "createdAt": "2026-09-06T15:47:00.000Z",
-  "updatedAt": "2026-09-06T15:47:00.000Z"
+  "updatedAt": "2026-09-09T00:00:00Z"
 }

package/blueprints/persistence-data-postgres/contributions/user-stories/persistence-data-postgres-us-27103.json

@@ -16,10 +16,27 @@
       "when": "a Node built-in AST parser walks every call expression whose callee is 'pg.query' or resolves to a method named 'query' on a pg.Client, pg.Pool, or pg.PoolClient reference",
       "then": "every first-argument node is a Literal with typeof value === 'string'; no first-argument node is a TemplateLiteral or a string-concatenation expression",
       "testable": true,
-      "scope": "runtime"
+      "scope": "runtime",
+      "disposition": "template"
+    },
+    {
+      "id": "AC-27103-2",
+      "description": "Consumer-supplied SQL rejected at the facade edge. Given a facade verb whose parameter is a raw SQL string (or a general query object), when the verb is called from consumer code, then the facade refuses at the boundary with a named error kind (rejectedRawSql) and no pg.query call issues; a source-tree grep finds no pg.query first argument outside a static string literal in the facade module.",
+      "given": "a facade verb called with a raw SQL string as its parameter",
+      "when": "the verb runs",
+      "then": "the facade refuses at the boundary with rejectedRawSql; no pg.query issues; the source-tree grep is clean",
+      "testable": true,
+      "scope": "runtime",
+      "ownerRef": {
+        "tacId": "TAC-2801-persistence-data-postgres-facade",
+        "field": "interfaces.store.verbs"
+      },
+      "disposition": "fixed"
     }
   ],
-  "tacIds": ["TAC-2801-persistence-data-postgres-facade"],
+  "tacIds": [
+    "TAC-2801-persistence-data-postgres-facade"
+  ],
   "createdAt": "2026-09-06T15:47:00.000Z",
-  "updatedAt": "2026-09-06T15:47:00.000Z"
+  "updatedAt": "2026-09-09T00:00:00Z"
 }

package/blueprints/persistence-data-postgres/contributions/user-stories/persistence-data-postgres-us-27104.json

@@ -11,15 +11,36 @@
   "acceptanceCriteria": [
     {
       "id": "AC-27104-1",
-      "description": "Given the transaction helper wrapping a callback that issues two INSERTs where the second violates a UNIQUE constraint, when the helper runs, then client.query('BEGIN') is issued, the first INSERT lands on the transaction, the second INSERT throws a constraint error the helper catches, client.query('ROLLBACK') is issued, a transactionRolledBack event fires with statementIndex 1, the client is released back to the pool, and the underlying error is re-thrown to the caller. The database after rollback carries neither row from the aborted transaction.",
+      "description": "Given the transaction helper wrapping a callback that issues two INSERTs where the second violates a UNIQUE constraint, when the helper runs, then the transaction-control primitives owned on TAC-2803-persistence-data-postgres-transaction-helper.interfaces.withTransaction fire in order (BEGIN before the first INSERT, ROLLBACK after the failing INSERT), a transactionRolledBack event fires with statementIndex 1, the client is released back to the pool, and the underlying error is re-thrown to the caller. The database after rollback carries neither row from the aborted transaction.",
       "given": "the facade's withTransaction helper, a table with a UNIQUE constraint on a column, and a callback issuing two INSERTs with the same value for that column",
       "when": "await withTransaction(callback) runs",
-      "then": "BEGIN is issued, the first INSERT lands inside the transaction, the second INSERT throws, ROLLBACK is issued, transactionRolledBack fires on the event sink with { statementIndex: 1, code: '<pg error code>' }, the client is released, the promise rejects with the underlying error, and a subsequent SELECT against the table returns no rows from the aborted transaction",
+      "then": "the BEGIN primitive owned on TAC-2803-persistence-data-postgres-transaction-helper.interfaces.withTransaction is issued, the first INSERT lands inside the transaction, the second INSERT throws, the ROLLBACK primitive owned on the same interface is issued, transactionRolledBack fires on the event sink with { statementIndex: 1, code: '<pg error code>' }, the client is released, the promise rejects with the underlying error, and a subsequent SELECT against the table returns no rows from the aborted transaction",
       "testable": true,
-      "scope": "runtime"
+      "scope": "runtime",
+      "ownerRef": {
+        "tacId": "TAC-2803-persistence-data-postgres-transaction-helper",
+        "field": "interfaces.withTransaction"
+      },
+      "disposition": "fixed"
+    },
+    {
+      "id": "AC-27104-2",
+      "description": "Mid-transaction error rolls back. Given a two-statement withTransaction callback where the second statement throws, when the helper catches the throw, then the ROLLBACK primitive owned on TAC-2803-persistence-data-postgres-transaction-helper.interfaces.withTransaction fires before the client is released, transactionRolledBack fires with the failing statement index on the event sink, and a subsequent SELECT on the transaction's target rows shows the pre-transaction state.",
+      "given": "a two-statement withTransaction callback whose second statement throws",
+      "when": "the helper catches the throw",
+      "then": "the ROLLBACK primitive owned on TAC-2803-persistence-data-postgres-transaction-helper.interfaces.withTransaction runs; transactionRolledBack fires with failing statement index; target rows show pre-transaction state",
+      "testable": true,
+      "scope": "runtime",
+      "ownerRef": {
+        "tacId": "TAC-2803-persistence-data-postgres-transaction-helper",
+        "field": "interfaces.withTransaction"
+      },
+      "disposition": "fixed"
     }
   ],
-  "tacIds": ["TAC-2803-persistence-data-postgres-transaction-helper"],
+  "tacIds": [
+    "TAC-2803-persistence-data-postgres-transaction-helper"
+  ],
   "createdAt": "2026-09-06T15:47:00.000Z",
-  "updatedAt": "2026-09-06T15:47:00.000Z"
+  "updatedAt": "2026-09-09T00:00:00Z"
 }

package/blueprints/persistence-data-postgres/contributions/user-stories/persistence-data-postgres-us-27105.json

@@ -16,10 +16,69 @@
       "when": "the recovery runner runs pg_dump against the source and a second Postgres is primed from the artefact",
       "then": "the runner exits 0, backupExported fires with the artefact path and completion timestamp, the artefact file exists at the elicited destination, and a query against the restored Postgres returns the same row count and same checksum of the fixture rowset as the source",
       "testable": true,
-      "scope": "runtime"
+      "scope": "runtime",
+      "disposition": "template"
+    },
+    {
+      "id": "AC-27105-2",
+      "description": "pg_dump upstream failure. Given the pg_dump process exits non-zero (for example the elicited connection-url is unreachable or the destination path is not writable), when the recovery runner runs, then the runner refuses with the pg_dump exit code and a named error kind (recoveryExportFailed), no partial artefact is left at the destination path, and backupExported does not fire on the event sink.",
+      "given": "pg_dump exits non-zero",
+      "when": "the recovery runner runs",
+      "then": "the runner refuses with recoveryExportFailed carrying the pg_dump exit code; no partial artefact remains; backupExported does not fire",
+      "testable": true,
+      "scope": "runtime",
+      "ownerRef": {
+        "tacId": "TAC-2804-persistence-data-postgres-recovery-runner",
+        "field": "interfaces.exportDatabase"
+      },
+      "disposition": "template"
+    },
+    {
+      "id": "AC-27105-3",
+      "description": "Recovery cadence daily. Given the elicited recovery-cadence answers daily, when the sidecar records the answer, then the recorded schedule descriptor the project-side scheduler consumes is `0 3 * * *` (a cron string firing once per day at 03:00 in the elicited timezone) and one backupExported event fires per day on the sink carrying { artefactPath, completedAt } inside the daily window.",
+      "given": "recovery-cadence = daily",
+      "when": "the sidecar records the answer and the scheduler ticks over a 24-hour window",
+      "then": "the recorded schedule is `0 3 * * *` and exactly one backupExported fires per 24-hour window",
+      "testable": true,
+      "scope": "runtime",
+      "ownerRef": {
+        "adrId": "ADR-2804-persistence-data-postgres-recovery",
+        "field": "decision"
+      },
+      "disposition": "template"
+    },
+    {
+      "id": "AC-27105-4",
+      "description": "Recovery cadence hourly. Given the elicited recovery-cadence answers hourly, when the sidecar records the answer, then the recorded schedule descriptor is `0 * * * *` (a cron string firing at minute zero of every hour) and backupExported fires 24 times per 24-hour window on the sink, each carrying a distinct completedAt inside its hour.",
+      "given": "recovery-cadence = hourly",
+      "when": "the sidecar records the answer and the scheduler ticks over a 24-hour window",
+      "then": "the recorded schedule is `0 * * * *` and 24 backupExported events fire per 24-hour window",
+      "testable": true,
+      "scope": "runtime",
+      "ownerRef": {
+        "adrId": "ADR-2804-persistence-data-postgres-recovery",
+        "field": "decision"
+      },
+      "disposition": "template"
+    },
+    {
+      "id": "AC-27105-5",
+      "description": "Recovery cadence weekly. Given the elicited recovery-cadence answers weekly, when the sidecar records the answer, then the recorded schedule descriptor is `0 3 * * 0` (a cron string firing at 03:00 every Sunday) and exactly one backupExported fires per seven-day window on the sink carrying { artefactPath, completedAt } inside that window.",
+      "given": "recovery-cadence = weekly",
+      "when": "the sidecar records the answer and the scheduler ticks over a seven-day window",
+      "then": "the recorded schedule is `0 3 * * 0` and exactly one backupExported fires per seven-day window",
+      "testable": true,
+      "scope": "runtime",
+      "ownerRef": {
+        "adrId": "ADR-2804-persistence-data-postgres-recovery",
+        "field": "decision"
+      },
+      "disposition": "template"
     }
   ],
-  "tacIds": ["TAC-2804-persistence-data-postgres-recovery-runner"],
+  "tacIds": [
+    "TAC-2804-persistence-data-postgres-recovery-runner"
+  ],
   "createdAt": "2026-09-06T15:47:00.000Z",
-  "updatedAt": "2026-09-06T15:47:00.000Z"
+  "updatedAt": "2026-09-09T00:00:00Z"
 }

package/blueprints/persistence-data-postgres/contributions/user-stories/persistence-data-postgres-us-27106.json

@@ -16,10 +16,27 @@
       "when": "twenty SELECT queries are dispatched concurrently across the two facades via Promise.all",
       "then": "all twenty promises resolve inside the connectionTimeoutMillis budget; no query throws; the observed maximum concurrent in-use pool connections on either facade is at most the configured pool size (5)",
       "testable": true,
-      "scope": "runtime"
+      "scope": "runtime",
+      "disposition": "fixed"
+    },
+    {
+      "id": "AC-27106-2",
+      "description": "Pool exhaustion is bounded. Given two facades at elicited pool-size 5 and thirty concurrent query calls, when the twenty-first through thirtieth calls contend for a client, then each call either acquires within the elicited connection-timeout-ms or refuses with a named error kind (poolAcquireTimeout); no call hangs indefinitely; the observability sink records connectionTimeout events with the elapsed time.",
+      "given": "two facades at pool-size 5 and 30 concurrent query calls",
+      "when": "the 21st through 30th calls contend for a client",
+      "then": "each call acquires within connection-timeout-ms or refuses with poolAcquireTimeout; no call hangs; the sink records connectionTimeout with elapsed time",
+      "testable": true,
+      "scope": "runtime",
+      "ownerRef": {
+        "tacId": "TAC-2801-persistence-data-postgres-facade",
+        "field": "interfaces.createStore"
+      },
+      "disposition": "template"
     }
   ],
-  "tacIds": ["TAC-2801-persistence-data-postgres-facade"],
+  "tacIds": [
+    "TAC-2801-persistence-data-postgres-facade"
+  ],
   "createdAt": "2026-09-06T15:47:00.000Z",
-  "updatedAt": "2026-09-06T15:47:00.000Z"
+  "updatedAt": "2026-09-09T00:00:00Z"
 }

package/blueprints/persistence-data-postgres/contributions/user-stories/persistence-data-postgres-us-27107.json

@@ -16,10 +16,27 @@
       "when": "the surface is inspected and the helper is invoked with a valid integer key on a supported answer",
       "then": "the surface exposes withAdvisoryLock only when the answer is session or transaction; the helper acquires the correct lock verb per the answer, runs the callback, and releases (session) or lets COMMIT release (transaction); the sidecar records the elicited answer for later validation",
       "testable": true,
-      "scope": "runtime"
+      "scope": "runtime",
+      "disposition": "template"
+    },
+    {
+      "id": "AC-27107-2",
+      "description": "Off default: helper genuinely absent. Given the elicited advisory-lock-helper answer off, when the facade opens, then no advisory-lock helper is exposed on the facade's public surface (a call site that attempts to reach for it fails at the module surface, not at a lock acquisition); a source-tree grep finds no pg_advisory_lock or pg_advisory_xact_lock call outside a helper module gated by the elicited enabled value.",
+      "given": "advisory-lock-helper = off",
+      "when": "the facade opens",
+      "then": "no advisory-lock helper appears on the facade surface; grep finds no pg_advisory_lock outside a gated helper",
+      "testable": true,
+      "scope": "runtime",
+      "ownerRef": {
+        "tacId": "TAC-2801-persistence-data-postgres-facade",
+        "field": "interfaces.store.verbs"
+      },
+      "disposition": "template"
     }
   ],
-  "tacIds": ["TAC-2801-persistence-data-postgres-facade"],
+  "tacIds": [
+    "TAC-2801-persistence-data-postgres-facade"
+  ],
   "createdAt": "2026-09-06T15:47:00.000Z",
-  "updatedAt": "2026-09-06T15:47:00.000Z"
+  "updatedAt": "2026-09-09T00:00:00Z"
 }

package/blueprints/persistence-data-postgres/contributions/user-stories/persistence-data-postgres-us-27108.json

@@ -16,10 +16,27 @@
       "when": "the pool completes its first ready-check",
       "then": "all five calls resolve successfully; facadeReady fires exactly once on the event sink; no unhandled rejection is raised",
       "testable": true,
-      "scope": "runtime"
+      "scope": "runtime",
+      "disposition": "fixed"
+    },
+    {
+      "id": "AC-27108-2",
+      "description": "First-connect race: no double emission. Given two concurrent boot paths racing to open the facade at the same time (an atypical but reachable init ordering), when both paths call createStore, then only one facadeReady fires on the event sink and both paths observe the same facade reference; a mutation SIMULATE_DOUBLE_BOOT=true forces a second createStore call within the boot window and the sink observer FAILS on a second facadeReady.",
+      "given": "two concurrent boot paths racing to open the facade",
+      "when": "both paths call createStore",
+      "then": "only one facadeReady fires; both paths observe the same facade reference; the double-boot mutation FAILS the run",
+      "testable": true,
+      "scope": "runtime",
+      "ownerRef": {
+        "tacId": "TAC-2801-persistence-data-postgres-facade",
+        "field": "responsibilities.pool"
+      },
+      "disposition": "fixed"
     }
   ],
-  "tacIds": ["TAC-2801-persistence-data-postgres-facade"],
+  "tacIds": [
+    "TAC-2801-persistence-data-postgres-facade"
+  ],
   "createdAt": "2026-09-06T15:47:00.000Z",
-  "updatedAt": "2026-09-06T15:47:00.000Z"
+  "updatedAt": "2026-09-09T00:00:00Z"
 }

package/blueprints/persistence-data-postgres/contributions/user-stories/persistence-data-postgres-us-27109.json

@@ -16,10 +16,27 @@
       "when": "the migration runner applies the directory with SIMULATE_MIGRATION_FAILURE=true",
       "then": "the first file's transaction commits and its row lands in the bookkeeping table; the second file's transaction rolls back; the runner exits non-zero with the failing filename in its stderr; the third file is not attempted; the bookkeeping table shows exactly one applied row",
       "testable": true,
-      "scope": "runtime"
+      "scope": "runtime",
+      "disposition": "template"
+    },
+    {
+      "id": "AC-27109-2",
+      "description": "On-disk store unchanged after a failing migration. Given a two-migration set where the second migration's body raises a Postgres error mid-statement, when the runner applies the set, then the second migration's transaction rolls back completely (schema_version reflects the first migration only), the runner exits non-zero with the pg error code named in stderr, and a subsequent '\\d' schema inspection shows no partial artefact from the failing migration.",
+      "given": "a two-migration set whose second migration raises mid-statement",
+      "when": "the runner applies the set",
+      "then": "the second migration rolls back; schema_version reflects the first only; run exits non-zero with the pg error code; schema shows no partial artefact",
+      "testable": true,
+      "scope": "runtime",
+      "ownerRef": {
+        "tacId": "TAC-2802-persistence-data-postgres-migration-runner",
+        "field": "interfaces.applyAll"
+      },
+      "disposition": "fixed"
     }
   ],
-  "tacIds": ["TAC-2802-persistence-data-postgres-migration-runner"],
+  "tacIds": [
+    "TAC-2802-persistence-data-postgres-migration-runner"
+  ],
   "createdAt": "2026-09-06T15:47:00.000Z",
-  "updatedAt": "2026-09-06T15:47:00.000Z"
+  "updatedAt": "2026-09-09T00:00:00Z"
 }