rcf-lite 0.20.0 → 0.22.0

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

@@ -0,0 +1,40 @@
+{
+  "tacId": "TAC-2802-persistence-data-postgres-migration-runner",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "approved",
+  "name": "Postgres migration runner",
+  "purpose": "The in-tree runner that reads numbered forward-only .sql files from the elicited migrations directory, applies each inside its own transaction against the elicited connection URL, and tracks applied filenames in a schema_version bookkeeping table it maintains inside the same database. The runner mode (atBoot or ciStep) is elicited on ADR-2803; the runner tool (bespoke Node runner, node-pg-migrate, sqitch, flyway) is elicited on ADR-2802; the shipped fixture provides a bespoke Node runner as the reference implementation.",
+  "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).",
+    "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.",
+  "interfaces": [
+    {
+      "name": "run",
+      "kind": "cli",
+      "description": "node migrate.mjs applies every un-applied file in order; exits 0 on success, non-zero on any failure with the failing filename in stderr."
+    },
+    {
+      "name": "applyAll",
+      "kind": "read-write-api",
+      "description": "applyAll({ connectionUrl, migrationsDir, bookkeepingTable, onEvent }) -> Promise<{ applied: string[] }>. Library entry point the facade may call in atBoot mode."
+    }
+  ],
+  "dependencies": [
+    {
+      "name": "Postgres facade",
+      "kind": "tac",
+      "tacId": "TAC-2801-persistence-data-postgres-facade",
+      "description": "The runner may share the facade's connection pool in atBoot mode; in ciStep mode it opens its own pg.Client directly against the elicited URL and disposes it on exit."
+    }
+  ],
+  "tradeoffs": "One file one transaction bounds the rollback surface cleanly but forbids a migration that spans two files atomically. Projects that need a schema change split across two files inside one transaction combine the change into one file. Numbered forward-only excludes down migrations by design; a rollback is a new numbered file inverting the earlier change, not a down step.",
+  "createdAt": "2026-09-06T15:47:00.000Z",
+  "updatedAt": "2026-09-06T15:47:00.000Z"
+}

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

@@ -0,0 +1,35 @@
+{
+  "tacId": "TAC-2803-persistence-data-postgres-transaction-helper",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "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.",
+  "responsibilities": [
+    "Acquire a pg.PoolClient from the facade's pool; issue client.query('BEGIN') (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).",
+    "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.",
+  "interfaces": [
+    {
+      "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."
+    }
+  ],
+  "dependencies": [
+    {
+      "name": "Postgres facade",
+      "kind": "tac",
+      "tacId": "TAC-2801-persistence-data-postgres-facade",
+      "description": "The facade owns the pool the helper acquires from and the event sink the rollback event fires on."
+    }
+  ],
+  "tradeoffs": "Wrapping the client in a proxy adds one function-call hop per query; on a hot path this is negligible. Tracking statementIndex by counting calls does not survive nested withTransaction invocations (Postgres does not support nested transactions natively; savepoints would be a v1.1 minor). Consumers that need savepoints today drop to raw client.query('SAVEPOINT ...') inside the callback and accept that statementIndex points at the outer BEGIN sequence.",
+  "createdAt": "2026-09-06T15:47:00.000Z",
+  "updatedAt": "2026-09-06T15:47:00.000Z"
+}

package/blueprints/persistence-data-postgres/contributions/tacs/tac-2804-persistence-data-postgres-recovery-runner.json

@@ -0,0 +1,40 @@
+{
+  "tacId": "TAC-2804-persistence-data-postgres-recovery-runner",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "approved",
+  "name": "Postgres scheduled-export runner",
+  "purpose": "The scheduled export runner that drives pg_dump against the live database, writes the artefact to the elicited destination, and emits backupExported with the artefact path and completion timestamp. Pairs with the deploy target's own point-in-time recovery on ADR-2804; the runner covers the portable-artefact half of the two-path recovery model.",
+  "responsibilities": [
+    "Invoke pg_dump via child_process.execFile against the elicited connection URL with an elicited pg_dump argument set (default: --no-owner --no-acl --format=plain) (AC-27105-1).",
+    "Stream the pg_dump stdout to a temporary file, atomically rename to the elicited destination path (a filesystem path in the shipped fixture; an operator-owned path in production) (AC-27105-1).",
+    "On successful completion, emit backupExported on the injected event sink with { artefactPath, completedAt } (AC-27105-1).",
+    "On pg_dump non-zero exit, emit backupExportFailed with the exit code and stderr tail, delete the partial temp file, exit non-zero.",
+    "Cadence is elicited (a cron string, a systemd timer spec, or off for CI-only invocation); the runner does not schedule itself; a project-side scheduler invokes it."
+  ],
+  "internalStructure": "One Node module exporting an exportDatabase({ connectionUrl, destination, onEvent, pgDumpArgs }) async function. The module resolves pg_dump on PATH via child_process.execFile, streams stdout to a temp file inside the destination's directory, and atomically renames on success. The recovery-drill helper in the same module invokes exportDatabase, brings up a fresh Postgres via docker compose or podman, streams the artefact into psql, and compares row-count and checksum on both databases.",
+  "interfaces": [
+    {
+      "name": "exportDatabase",
+      "kind": "read-write-api",
+      "description": "await exportDatabase({ connectionUrl, destination, onEvent, pgDumpArgs }) -> { artefactPath, completedAt }. Runs pg_dump, writes the artefact, fires backupExported."
+    },
+    {
+      "name": "recoveryDrill",
+      "kind": "read-write-api",
+      "description": "await recoveryDrill({ sourceUrl, destination, onEvent }) -> { count, checksum }. Runs exportDatabase, primes a fresh Postgres from the artefact, compares row-count and checksum on the fixture table, fires recoveryDrillPassed."
+    }
+  ],
+  "dependencies": [
+    {
+      "name": "Postgres facade",
+      "kind": "tac",
+      "tacId": "TAC-2801-persistence-data-postgres-facade",
+      "description": "Shares the facade's event sink for backupExported and recoveryDrillPassed."
+    }
+  ],
+  "tradeoffs": "child_process.execFile against pg_dump requires the pg_dump binary to be on PATH (or a full path passed via config). On a container platform the runner ships a Postgres client image alongside the app for pg_dump availability; the guide names the CI-seam pattern. The runner does not implement WAL-shipping or a streaming backup; that path is the deploy target's own PITR obligation on ADR-2804.",
+  "createdAt": "2026-09-06T15:47:00.000Z",
+  "updatedAt": "2026-09-06T15:47:00.000Z"
+}

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

@@ -0,0 +1,34 @@
+{
+  "usId": "persistence-data-postgres-US-27101",
+  "prdId": "PRD-001",
+  "reqId": "persistence-data-postgres-REQ-001",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "One facade module opens a pg.Pool on boot and emits facadeReady with the database name",
+  "asA": "developer whose Node process needs a durable Postgres store behind a swappable boundary",
+  "iWant": "one facade module to hold the pg client and expose named domain verbs, with a facadeReady lifecycle event on the first successful pool ready-check",
+  "soThat": "the boundary between the domain and the pg vendor surface is the only place that has to move when the driver changes and the boot ordering is observable via the event",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-27101-1",
+      "description": "On process boot, the facade opens a pg.Pool against the elicited connection URL; once the first successful pool ready-check completes, a facadeReady event fires on the injected event sink carrying the database name.",
+      "given": "a Node process with the facade module imported and its factory invoked",
+      "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"
+    },
+    {
+      "id": "AC-27101-2",
+      "description": "Exactly one source-tree module inside the facade directory imports pg; every other module in the applied project's source tree that touches persistence imports the facade and calls its named domain verbs, verified by a targeted grep on the applied fixture.",
+      "given": "the applied project's source tree after apply",
+      "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"
+    }
+  ],
+  "tacIds": ["TAC-2801-persistence-data-postgres-facade"],
+  "createdAt": "2026-09-06T15:47:00.000Z",
+  "updatedAt": "2026-09-06T15:47:00.000Z"
+}

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

@@ -0,0 +1,25 @@
+{
+  "usId": "persistence-data-postgres-US-27102",
+  "prdId": "PRD-001",
+  "reqId": "persistence-data-postgres-REQ-002",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "Numbered forward-only .sql migrations apply one file one transaction; schema_version advances",
+  "asA": "operator who needs deploys reproducible from a git ref with no schema state outside version control",
+  "iWant": "every schema change to be a new numbered .sql file under the elicited migrations directory, applied by the in-tree runner one file at a time inside its own transaction",
+  "soThat": "the schema shape at any deployed version can be read from committed files, each apply either commits or leaves the schema exactly as it was, and the schema_version bookkeeping table is the one source of truth on what has been applied",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-27102-1",
+      "description": "Given a fresh Postgres database at schema_version 0 and three numbered forward-only .sql migration files (001, 002, 003), when the migration runner opens the store and applies them, then each file applies inside its own transaction (BEGIN, file body, COMMIT), a migrationsApplied event fires with the applied filename list, and the schema_version bookkeeping table records three rows keyed by filename.",
+      "given": "a fresh Postgres instance and a migrations directory with 001_*.sql, 002_*.sql, 003_*.sql each a single statement inside an implicit transaction",
+      "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"
+    }
+  ],
+  "tacIds": ["TAC-2802-persistence-data-postgres-migration-runner"],
+  "createdAt": "2026-09-06T15:47:00.000Z",
+  "updatedAt": "2026-09-06T15:47:00.000Z"
+}

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

@@ -0,0 +1,25 @@
+{
+  "usId": "persistence-data-postgres-US-27103",
+  "prdId": "PRD-001",
+  "reqId": "persistence-data-postgres-REQ-003",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "Every pg.query call site inside the facade passes a static string literal as its first argument",
+  "asA": "reviewer of an rcf-lite Postgres project auditing for SQL injection risk at the driver boundary",
+  "iWant": "an AST scan over the facade directory to prove every pg.query first argument is a static string literal with $N parameters, per the node-postgres parameterised-queries contract",
+  "soThat": "a call site that concatenates or template-literal-interpolates consumer values into SQL text is caught at build time before it ships",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-27103-1",
+      "description": "An AST scan over every .ts/.js/.mjs file under the applied fixture's facade directory finds every call to pg.query and asserts each first-argument node is a StringLiteral (Literal node with a string value), not a TemplateLiteral, not a BinaryExpression whose operator is '+' with a string operand. Parameters are supplied as an array whose values bind to $1, $2, ... $N placeholders in the string.",
+      "given": "the applied fixture's src/store.mjs and any sibling module inside the facade directory",
+      "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"
+    }
+  ],
+  "tacIds": ["TAC-2801-persistence-data-postgres-facade"],
+  "createdAt": "2026-09-06T15:47:00.000Z",
+  "updatedAt": "2026-09-06T15:47:00.000Z"
+}

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

@@ -0,0 +1,25 @@
+{
+  "usId": "persistence-data-postgres-US-27104",
+  "prdId": "PRD-001",
+  "reqId": "persistence-data-postgres-REQ-004",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "Transaction helper rolls back on any statement error and fires transactionRolledBack with the failing index",
+  "asA": "developer whose domain requires atomic multi-statement writes",
+  "iWant": "a transaction helper that wraps BEGIN and COMMIT around a callback and issues ROLLBACK on any error",
+  "soThat": "no partial commit lands on the shipped database and the failing statement's index is observable on the event sink",
+  "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.",
+      "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",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": ["TAC-2803-persistence-data-postgres-transaction-helper"],
+  "createdAt": "2026-09-06T15:47:00.000Z",
+  "updatedAt": "2026-09-06T15:47:00.000Z"
+}

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

@@ -0,0 +1,25 @@
+{
+  "usId": "persistence-data-postgres-US-27105",
+  "prdId": "PRD-001",
+  "reqId": "persistence-data-postgres-REQ-005",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "Scheduled pg_dump lands an artefact and a fresh Postgres primed from it round-trips the row set",
+  "asA": "operator responsible for restoring a Postgres project after a cluster loss or a data-integrity incident",
+  "iWant": "a scheduled export runner that drives pg_dump against the live database and writes an artefact to the elicited destination",
+  "soThat": "a fresh Postgres primed from the artefact returns the row set the source held at the artefact's completion timestamp",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-27105-1",
+      "description": "Given a live Postgres containing a small fixture rowset, when the scheduled export runner runs, then it invokes pg_dump via child_process.execFile against the elicited connection URL, writes the artefact to the elicited destination, and emits backupExported with { artefactPath, completedAt }. A fresh Postgres primed by psql-restoring the artefact returns the same rowset (row count and row checksum both equal) as the source.",
+      "given": "a live Postgres seeded with a fixture rowset and the recovery runner configured to write to a temporary destination",
+      "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"
+    }
+  ],
+  "tacIds": ["TAC-2804-persistence-data-postgres-recovery-runner"],
+  "createdAt": "2026-09-06T15:47:00.000Z",
+  "updatedAt": "2026-09-06T15:47:00.000Z"
+}

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

@@ -0,0 +1,25 @@
+{
+  "usId": "persistence-data-postgres-US-27106",
+  "prdId": "PRD-001",
+  "reqId": "persistence-data-postgres-REQ-006",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "Two facades at pool size 5 handle twenty concurrent queries with no timeout",
+  "asA": "developer running a long-lived Node process with a warm pg pool",
+  "iWant": "the shipped pool defaults to handle a burst of twenty concurrent queries across two facade instances at pool size 5 without timing out",
+  "soThat": "the pool posture per deploy target is proven at the shape the shipped defaults name, not just at the single-query level",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-27106-1",
+      "description": "Given two facade instances opened concurrently against the same Postgres at pool size 5 each, when twenty concurrent SELECT queries are issued across the two facades, then all twenty return with no timeout inside the shipped connectionTimeoutMillis (5000) and idleTimeoutMillis (30000) defaults, and the pool metric on each facade reports at most 5 in-use connections at any point.",
+      "given": "two facade instances opened against the same postgres:17-alpine container at pool size 5 each",
+      "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"
+    }
+  ],
+  "tacIds": ["TAC-2801-persistence-data-postgres-facade"],
+  "createdAt": "2026-09-06T15:47:00.000Z",
+  "updatedAt": "2026-09-06T15:47:00.000Z"
+}

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

@@ -0,0 +1,25 @@
+{
+  "usId": "persistence-data-postgres-US-27107",
+  "prdId": "PRD-001",
+  "reqId": "persistence-data-postgres-REQ-007",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "Advisory-lock helper is elicited off by default; when enabled it wraps pg_advisory_lock or pg_advisory_xact_lock per the elicited scope",
+  "asA": "developer building a workflow that needs cross-process coordination on a shared Postgres",
+  "iWant": "an optional advisory-lock helper on the facade that acquires and releases a session-level or transaction-level lock per an elicited key",
+  "soThat": "cross-process ordering is expressible through the engine's own primitive without a bespoke locks table",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-27107-1",
+      "description": "The elicited advisoryLockHelper parameter has one of three values (off, session, transaction) with default off; when off the facade does not expose the helper on its public surface. When session or transaction, the facade exposes a withAdvisoryLock(key, callback) verb that acquires pg_advisory_lock (session) or pg_advisory_xact_lock (transaction) with the integer key, runs the callback, and releases the lock via pg_advisory_unlock on the session-level shape; the transaction-level shape releases automatically at COMMIT or ROLLBACK per the Postgres explicit-locking reference.",
+      "given": "the facade's public surface after apply, with the advisoryLockHelper elicit answered on each of the three permitted values",
+      "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"
+    }
+  ],
+  "tacIds": ["TAC-2801-persistence-data-postgres-facade"],
+  "createdAt": "2026-09-06T15:47:00.000Z",
+  "updatedAt": "2026-09-06T15:47:00.000Z"
+}

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

@@ -0,0 +1,25 @@
+{
+  "usId": "persistence-data-postgres-US-27108",
+  "prdId": "PRD-001",
+  "reqId": "persistence-data-postgres-REQ-001",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "Facade boot survives a first-connect race and does not double-emit facadeReady",
+  "asA": "developer whose process may issue queries against the facade before its pool's first ready-check completes",
+  "iWant": "the facade to serialise consumer queries behind the pool's ready-check without dropping any and to emit facadeReady exactly once per facade instance",
+  "soThat": "boot-time races do not surface as unhandled promise rejections and the ready event is not double-counted by an observability sink",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-27108-1",
+      "description": "Given a facade instance and five concurrent domain-verb calls issued before the pool's first ready-check completes, when the pool becomes ready, then all five calls succeed against the pool once ready, the facadeReady event fires exactly once with the database name, and no consumer sees a NotReady error.",
+      "given": "a fresh facade instance and five concurrent getUserById calls issued immediately after construction",
+      "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"
+    }
+  ],
+  "tacIds": ["TAC-2801-persistence-data-postgres-facade"],
+  "createdAt": "2026-09-06T15:47:00.000Z",
+  "updatedAt": "2026-09-06T15:47:00.000Z"
+}

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

@@ -0,0 +1,25 @@
+{
+  "usId": "persistence-data-postgres-US-27109",
+  "prdId": "PRD-001",
+  "reqId": "persistence-data-postgres-REQ-002",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "A failing migration rolls back its own transaction and the runner exits non-zero without advancing schema_version",
+  "asA": "operator running migrations at boot on a long-lived Node process",
+  "iWant": "a failing migration to roll back its own transaction and stop the runner with a non-zero exit and the failing filename in the diagnostic",
+  "soThat": "the runner never leaves a partially-applied migration on the database and the operator can name the failing file to un-jam the deploy",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-27109-1",
+      "description": "Given a migrations directory whose second file contains an invalid SQL statement (simulated in the fixture by the SIMULATE_MIGRATION_FAILURE switch), when the migration runner runs, then the first file commits, the second file's transaction rolls back on the invalid statement, the runner exits non-zero, and the failing filename appears in the runner's diagnostic output. The schema_version bookkeeping table records only the first file's row.",
+      "given": "a Postgres at schema_version 0 and three migration files where the second is intentionally broken",
+      "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"
+    }
+  ],
+  "tacIds": ["TAC-2802-persistence-data-postgres-migration-runner"],
+  "createdAt": "2026-09-06T15:47:00.000Z",
+  "updatedAt": "2026-09-06T15:47:00.000Z"
+}

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

@@ -0,0 +1,25 @@
+{
+  "usId": "persistence-data-postgres-US-27110",
+  "prdId": "PRD-001",
+  "reqId": "persistence-data-postgres-REQ-005",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "A recovery drill primes a fresh Postgres from the pg_dump artefact and the row-count and checksum match the source",
+  "asA": "operator running a recovery drill on a schedule to prove the pg_dump path works",
+  "iWant": "the drill to prime a fresh Postgres from the artefact and compare the restored dataset against the source by row-count and checksum",
+  "soThat": "the recovery path is proven end to end and drift on the artefact shape is caught before an incident forces a live restore",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-27110-1",
+      "description": "Given a live Postgres with a fixture rowset and a pg_dump artefact produced by the scheduled runner, when the drill primes a fresh Postgres from the artefact and computes the row-count and checksum of the fixture table on both databases, then the row-count and checksum on the restored Postgres equal those on the source and a recoveryDrillPassed event fires on the event sink carrying the two matched values.",
+      "given": "a source Postgres seeded with a fixture rowset and a pg_dump artefact at the elicited destination",
+      "when": "the drill primes a fresh Postgres from the artefact and runs SELECT count(*) and a checksum aggregate on the fixture table against both databases",
+      "then": "the two counts are equal; the two checksums are equal; recoveryDrillPassed fires on the event sink with { count, checksum }; the fresh Postgres and its artefact primer are torn down on exit",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": ["TAC-2804-persistence-data-postgres-recovery-runner"],
+  "createdAt": "2026-09-06T15:47:00.000Z",
+  "updatedAt": "2026-09-06T15:47:00.000Z"
+}

package/blueprints/persistence-data-postgres/docs/topics.md

@@ -0,0 +1,64 @@
+# persistence-data-postgres blueprint coordination vocabulary
+
+This file is the persistence-data-postgres half of the cross-blueprint contract. The Phase 1 conflict detector matches scope:global ADR topics by EXACT string equality, and AC ids are unnamespaced by the 0.4.4 grammar. Any blueprint intended to compose with this one must reuse these exact strings and respect these bands.
+
+## Global ADR topics this blueprint contributes (exact strings)
+
+| Topic string | persistence-data-postgres contribution | Origin | Composition note |
+|---|---|---|---|
+| `persistenceStore` | ADR-2801-persistence-data-postgres-driver | Reused from persistence-data-sqlite and persistence-data-d1 (both contribute the same topic string). This blueprint contributes a Postgres store on the same topic string on purpose. | The one project-wide decision on the primary durable store engine. Composing this blueprint with persistence-data-sqlite or persistence-data-d1 conflicts here by design; expected resolution is one project-level ADR that fixes the engine end to end |
+| `migrationDiscipline` | ADR-2802-persistence-data-postgres-migration-shape | Reused from persistence-data-sqlite (boot-time forward-only runner discipline) and persistence-data-d1 (wrangler-CLI-owned deploy-pipeline discipline). This blueprint contributes numbered forward-only .sql migrations applied by an in-tree runner one file one transaction. | The one project-wide schema-evolution discipline. Composing this blueprint with persistence-data-sqlite or persistence-data-d1 conflicts here by design; expected resolution is one project-level ADR |
+
+The persistence-data-postgres blueprint claims two global topics. Every other contribution is scope-local (ADR-2803 runner mode, ADR-2804 recovery, ADR-2805 connection-pool posture do not contribute global topics; a composing blueprint that holds an opinion on any of them authors its own project-level ADR).
+
+Note on the round-6 reserved Hyperdrive adapter slot: the v1.0.0 facade holds the driver reference OPAQUE at ADR-2801 boundary so the round-6 v1.1.0 Hyperdrive adapter slots in as an additive minor without a topic conflict. See infra round 5 spec section 5.7 for the reserved-slot register.
+
+Rules for new topics: lower camel case, one concept per topic, no version suffixes. A topic names the decision area, not the chosen answer.
+
+## Id number bands (registry bootstrap)
+
+This table is maintained shelf-wide across every blueprint's `docs/topics.md`. Rows are recorded at ship, never predicted.
+
+| Blueprint | US band | ADR/TAC suffix block | Status | Global topics |
+|---|---|---|---|---|
+| application-spa | 1101-1899 | 2xx | shipped v1.3.0 | `clientRouting`, `theming`, `clientState`, `errorEnvelope`, `authModel` |
+| application-api-rest | 2101-2899 | 3xx | shipped v1.0.0 | `errorEnvelope`, `authModel`, `apiVersioning`, `logging` |
+| security-auth-magic-link | 3101-3899 | 5xx | shipped v1.0.0 | `authModel` |
+| email-smtp-resend | 4101-4899 | 4xx | shipped v1.0.0 | none |
+| hello-panel (walkthrough exemplar) | 4101-4899 | 4xx | doc-reserved; teaching exemplar in `packages/rcf-lite/docs/blueprint-authoring-walkthrough.md`, not shipped as a blueprint directory | `operatorPanel` |
+| persistence-data-sqlite | 5101-5899 | 6xx | shipped v1.0.0 | `persistenceStore`, `migrationDiscipline` |
+| delivery-ci-workflows | 6101-6899 | 7xx | shipped v2.0.0 (renamed from ci-pipeline) | `ciGates`, `strictCoverageGate`, `releaseArtefacts` |
+| observability-essentials | 7101-7899 | 8xx | shipped v2.0.0 | `statusPageContract` |
+| security-secrets-management | 8101-8899 | 9xx | shipped v1.0.1 | `secretsSource` |
+| security-auth-clerk | 9101-9899 | 10xx | shipped v1.0.0 | `authModel` |
+| security-auth-oauth2 | 10101-10899 | 11xx | shipped v1.0.0 | `authModel` |
+| security-auth-keycloak | 11101-11899 | 12xx | shipped v1.0.0 | `authModel` |
+| deploy-cloudflare-workers | 12101-12899 | 13xx | shipped v1.0.0 | `deploymentTarget` |
+| persistence-data-d1 | 13101-13899 | 14xx | shipped v1.0.0 | `persistenceStore`, `migrationDiscipline` |
+| observability-probe-endpoints | 14101-14899 | 15xx | shipped v1.1.0 | `healthProbes`, `readinessSemantics` |
+| observability-logging | 15101-15899 | 16xx | shipped v1.0.0 | `logging` |
+| application-error-handling | 16101-16899 | 17xx | shipped v1.0.0 | `errorHandling` |
+| application-datatable | 17101-17899 | 18xx | shipped v1.0.0 | none |
+| application-charts | 18101-18899 | 19xx | shipped v1.0.0 | none |
+| application-dashboard | 19101-19899 | 20xx | shipped v1.0.0 | none |
+| application-notifications-in-app | 20101-20899 | 21xx | shipped v1.0.0 | none |
+| application-admin-console | 21101-21899 | 22xx | shipped v1.0.0 | none |
+| application-forms-wizard | 24101-24899 | 25xx | shipped v1.0.0 | none |
+| application-account-settings | 25101-25899 | 26xx | shipped v1.0.0 | none |
+| application-onboarding-tour | 26101-26899 | 27xx | shipped v1.0.0 | none |
+| persistence-data-postgres | 27101-27899 | 28xx | shipped v1.0.0 | `persistenceStore`, `migrationDiscipline` |
+| object-storage-s3 | 28101-28899 | 29xx | shipped v1.0.0 | `objectStorageContract` |
+
+US 27101-27110 sit at the LOW end of the 27101-27899 band on purpose (watchpost run-4 lesson). A project-side story mechanically derived from a persistence-data-postgres REQ id into the number 27110 would collide against the shipped US-27110; band headroom (27111-27899) leaves that space.
+
+Postgres suffixes for this blueprint use the 2801-2899 block, continuing the widening pattern (persistence-data-sqlite 6xx, persistence-data-d1 14xx, and persistence-data-postgres 28xx).
+
+## Shared expectations for future composing blueprints
+
+- Reuse `persistenceStore` exactly as spelled here when your blueprint holds an opinion on the project's primary durable store engine; contribute your own scope:global ADR on that string and let composition surface the pairing.
+- Reuse `migrationDiscipline` exactly as spelled here when your blueprint holds an opinion on schema evolution.
+- Round-6 reserved slot: the Hyperdrive adapter inside `persistence-data-postgres` v1.1.0 wraps the same facade contract with the Cloudflare Hyperdrive connection-pool and query-cache surface. No topic conflict, no facade re-shape; the driver reference is opaque at the ADR-2801 boundary.
+
+## Deliberate-conflict statement
+
+This blueprint's ADR-2801 on `persistenceStore` and ADR-2802 on `migrationDiscipline` are a Postgres-committed vendor sibling to persistence-data-sqlite (ADR-601, ADR-602) and persistence-data-d1 (ADR-1401, ADR-1402) on the same two topic strings. Applying two of the three on one project raises two `globalAdrTopic` conflicts the operator resolves via one of the four documented resolutions per topic (adopt one, keep the existing one, author a project-level supersede ADR, or `--resolve <topic>=project:<ADR-id>` on the add).