rcf-lite 0.20.0 → 0.22.0

package/blueprints/persistence-data-postgres/contributions/probes/probe-utils.mjs

@@ -0,0 +1,76 @@
+/**
+ * Shared helpers for persistence-data-postgres probes.
+ *
+ * Runtime-dependency posture: probes import pg via the sample-app
+ * fixture's store.mjs so pg resolves from the fixture's own
+ * node_modules and rcf-lite itself gains no new runtime dependency
+ * (round-5 spec section 5.5, brief section 4).
+ */
+
+import { mkdir, writeFile } from 'node:fs/promises';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+
+// Project root two levels above blueprints/persistence-data-postgres/
+export const PROJECT_ROOT = resolve(HERE, '..', '..', '..', '..');
+export const FIXTURE_DIR = resolve(PROJECT_ROOT, 'packages/rcf-lite/test/fixtures/infra-postgres');
+export const REPORT_DIR = resolve(PROJECT_ROOT, '.rcf/reports/blueprints/persistence-data-postgres');
+
+/**
+ * Compute the aggregate verdict per spec section 3.4:
+ * - fail if any result carries verdict fail
+ * - warn if any result carries verdict warn and no fail
+ * - pass otherwise
+ */
+export function aggregate(results) {
+  if (results.some((r) => r.verdict === 'fail')) return 'fail';
+  if (results.some((r) => r.verdict === 'warn')) return 'warn';
+  return 'pass';
+}
+
+/**
+ * Write the per-blueprint probe report at
+ * .rcf/reports/blueprints/persistence-data-postgres/<probeName>.json
+ * per spec section 3.4.
+ */
+export async function writeReport({ probeName, engine, results }) {
+  await mkdir(REPORT_DIR, { recursive: true });
+  const report = {
+    slug: 'persistence-data-postgres',
+    probeName,
+    runAt: new Date().toISOString(),
+    engine,
+    results,
+    aggregateVerdict: aggregate(results),
+  };
+  const path = resolve(REPORT_DIR, `${probeName}.json`);
+  await writeFile(path, JSON.stringify(report, null, 2), 'utf8');
+  return { report, path };
+}
+
+/**
+ * Drive an async main() and exit 0 on aggregate pass, 1 otherwise.
+ * Prints the report JSON to stdout for the gate-reviewer to read.
+ */
+export async function runShim(probeName, engine, mainFn) {
+  try {
+    const results = await mainFn();
+    const { report, path } = await writeReport({ probeName, engine, results });
+    process.stdout.write(JSON.stringify(report, null, 2) + '\n');
+    process.stdout.write(`report written to ${path}\n`);
+    process.exit(report.aggregateVerdict === 'pass' ? 0 : 1);
+  } catch (err) {
+    const results = [{
+      anchorAcId: 'unknown',
+      verdict: 'fail',
+      detail: `probe threw: ${err && err.message ? err.message : String(err)}`,
+    }];
+    const { report, path } = await writeReport({ probeName, engine, results });
+    process.stdout.write(JSON.stringify(report, null, 2) + '\n');
+    process.stderr.write(`probe error: ${err && err.stack ? err.stack : String(err)}\n`);
+    process.stderr.write(`report written to ${path}\n`);
+    process.exit(1);
+  }
+}

package/blueprints/persistence-data-postgres/contributions/probes/recovery-restore-round-trip.mjs

@@ -0,0 +1,173 @@
+/**
+ * Recovery restore round-trip probe.
+ *
+ * Seeds the running postgres:17-alpine fixture with a small rowset,
+ * runs pg_dump via `docker exec` against the source container (pg_dump
+ * ships inside the postgres:17-alpine image; on a shipped project the
+ * fixture's src/recovery.mjs drives pg_dump on PATH per TAC-2804),
+ * brings up a second postgres:17-alpine container on a spare port,
+ * pipes the artefact through psql into the second container, and
+ * asserts row-count and checksum equality between source and restored
+ * databases.
+ *
+ * Anchors AC-27105-1 (recovery exported, restore round-trips the row
+ * set).
+ *
+ * Cleans up: TRUNCATE users on source; stops the restore container and
+ * removes its volume; deletes the artefact file.
+ */
+
+import { spawn, execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { mkdir, writeFile, unlink, rm } from 'node:fs/promises';
+import { dirname, relative, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createStore, connectionUrlFromEnv } from '../../../../packages/rcf-lite/test/fixtures/infra-postgres/src/store.mjs';
+
+const execFileAsync = promisify(execFile);
+const HERE = dirname(fileURLToPath(import.meta.url));
+const PROJECT_ROOT = resolve(HERE, '..', '..', '..', '..');
+const ARTEFACT_DIR = resolve(PROJECT_ROOT, '.rcf/reports/blueprints/persistence-data-postgres/recovery');
+const ARTEFACT = resolve(ARTEFACT_DIR, 'backup.sql');
+const ARTEFACT_REL = relative(PROJECT_ROOT, ARTEFACT);
+const SOURCE_CONTAINER = 'infra-postgres-postgres-1';
+const RESTORE_CONTAINER = 'infra-postgres-restore';
+const RESTORE_PORT = '55432';
+
+async function dockerExec(container, cmd, opts = {}) {
+  return execFileAsync('docker', ['exec', container, ...cmd], { maxBuffer: 64 * 1024 * 1024, ...opts });
+}
+
+/**
+ * Pipe an in-process buffer into docker exec's stdin. execFile does not
+ * accept stdin buffers, so use spawn.
+ */
+async function dockerExecStdin(container, cmd, stdinBuffer) {
+  return new Promise((resolve2, reject) => {
+    const child = spawn('docker', ['exec', '-i', container, ...cmd]);
+    const chunks = [];
+    const errChunks = [];
+    child.stdout.on('data', (d) => chunks.push(d));
+    child.stderr.on('data', (d) => errChunks.push(d));
+    child.on('error', reject);
+    child.on('exit', (code) => {
+      if (code === 0) return resolve2({ stdout: Buffer.concat(chunks).toString('utf8'), stderr: Buffer.concat(errChunks).toString('utf8') });
+      reject(new Error(`docker exec exit ${code}: ${Buffer.concat(errChunks).toString('utf8')}`));
+    });
+    child.stdin.write(stdinBuffer);
+    child.stdin.end();
+  });
+}
+
+async function waitHealthy(container, maxSeconds = 30) {
+  for (let i = 0; i < maxSeconds; i++) {
+    try {
+      const r = await execFileAsync('docker', ['inspect', '--format', '{{.State.Health.Status}}', container]);
+      const status = r.stdout.trim();
+      if (status === 'healthy') return;
+    } catch { /* container not up yet */ }
+    await new Promise((r) => setTimeout(r, 1000));
+  }
+  throw new Error(`container ${container} did not become healthy within ${maxSeconds}s`);
+}
+
+async function bringUpRestore() {
+  // Remove any prior instance
+  await execFileAsync('docker', ['rm', '-f', RESTORE_CONTAINER]).catch(() => {});
+  await execFileAsync('docker', [
+    'run', '-d',
+    '--name', RESTORE_CONTAINER,
+    '-e', 'POSTGRES_USER=rcf',
+    '-e', 'POSTGRES_PASSWORD=rcf-dev-only',
+    '-e', 'POSTGRES_DB=rcf_test',
+    '-p', `${RESTORE_PORT}:5432`,
+    '--health-cmd', 'pg_isready -U rcf -d rcf_test',
+    '--health-interval', '2s',
+    '--health-retries', '20',
+    'postgres:17-alpine',
+  ]);
+  await waitHealthy(RESTORE_CONTAINER, 30);
+}
+
+async function tearDownRestore() {
+  await execFileAsync('docker', ['rm', '-f', '-v', RESTORE_CONTAINER]).catch(() => {});
+}
+
+export default async function runProbe() {
+  const events = [];
+  const store = createStore({
+    connectionUrl: connectionUrlFromEnv(),
+    onEvent: (e) => events.push(e),
+  });
+  const results = [];
+  try {
+    await store.ready();
+    const pool = store.getPool();
+
+    // Seed a known rowset on the source
+    await pool.query('CREATE TABLE IF NOT EXISTS users (id SERIAL PRIMARY KEY, name TEXT NOT NULL, email TEXT UNIQUE, created_at TIMESTAMPTZ NOT NULL DEFAULT now())');
+    await pool.query('TRUNCATE users RESTART IDENTITY');
+    const seed = [
+      ['alice', 'alice@rcf.test'],
+      ['bob', 'bob@rcf.test'],
+      ['carol', 'carol@rcf.test'],
+      ['dan', 'dan@rcf.test'],
+      ['eve', 'eve@rcf.test'],
+    ];
+    for (const [name, email] of seed) {
+      await pool.query('INSERT INTO users(name, email) VALUES ($1, $2)', [name, email]);
+    }
+
+    // Compute source row-count and checksum (md5 over concatenated name|email ordered by id)
+    const srcCount = (await pool.query('SELECT count(*)::int AS n FROM users')).rows[0].n;
+    const srcCk = (await pool.query('SELECT md5(string_agg(name || $1 || email, $2 ORDER BY id))::text AS ck FROM users', ['|', ','])).rows[0].ck;
+
+    // pg_dump inside the source container to stdout, capture as artefact
+    await mkdir(ARTEFACT_DIR, { recursive: true });
+    const dump = await dockerExec(SOURCE_CONTAINER, ['pg_dump', '-U', 'rcf', '-d', 'rcf_test', '--no-owner', '--no-acl', '--format=plain']);
+    await writeFile(ARTEFACT, dump.stdout, 'utf8');
+    const bytes = Buffer.byteLength(dump.stdout, 'utf8');
+
+    // Bring up restore container
+    await bringUpRestore();
+
+    // Pipe artefact into psql on restore
+    await dockerExecStdin(RESTORE_CONTAINER, ['psql', '-U', 'rcf', '-d', 'rcf_test', '-v', 'ON_ERROR_STOP=1'], Buffer.from(dump.stdout, 'utf8'));
+
+    // Read row-count and checksum on restored
+    const dstStore = createStore({ connectionUrl: `postgres://rcf:${encodeURIComponent('rcf-dev-only')}@localhost:${RESTORE_PORT}/rcf_test` });
+    let dstCount = -1;
+    let dstCk = 'unset';
+    try {
+      await dstStore.ready();
+      const dstPool = dstStore.getPool();
+      dstCount = (await dstPool.query('SELECT count(*)::int AS n FROM users')).rows[0].n;
+      dstCk = (await dstPool.query('SELECT md5(string_agg(name || $1 || email, $2 ORDER BY id))::text AS ck FROM users', ['|', ','])).rows[0].ck;
+    } finally {
+      await dstStore.close();
+    }
+
+    results.push({
+      anchorAcId: 'AC-27105-1',
+      verdict: bytes > 0 ? 'pass' : 'fail',
+      detail: `pg_dump artefact written to ${ARTEFACT_REL} (${bytes} bytes)`,
+    });
+    results.push({
+      anchorAcId: 'AC-27105-1',
+      verdict: srcCount === dstCount ? 'pass' : 'fail',
+      detail: `row-count source=${srcCount} restored=${dstCount}`,
+    });
+    results.push({
+      anchorAcId: 'AC-27105-1',
+      verdict: srcCk === dstCk && srcCk != null ? 'pass' : 'fail',
+      detail: `checksum source=${srcCk} restored=${dstCk}`,
+    });
+  } finally {
+    // Cleanup: truncate source, tear down restore, delete artefact
+    try { await store.getPool().query('TRUNCATE users RESTART IDENTITY'); } catch { /* ignore */ }
+    await store.close();
+    await tearDownRestore();
+    await rm(ARTEFACT_DIR, { recursive: true, force: true }).catch(() => {});
+  }
+  return results;
+}

package/blueprints/persistence-data-postgres/contributions/probes/run-facade-round-trip.mjs

@@ -0,0 +1,10 @@
+/**
+ * Shim: run facade-round-trip against the sample-app fixture and write
+ * the per-blueprint report at .rcf/reports/blueprints/persistence-data-postgres/facade-round-trip.json.
+ */
+
+import runProbe from './facade-round-trip.mjs';
+import { runShim } from './probe-utils.mjs';
+
+const engine = { kind: 'postgres', image: 'postgres:17-alpine', healthy: true };
+runShim('facade-round-trip', engine, runProbe);

package/blueprints/persistence-data-postgres/contributions/probes/run-migration-apply.mjs

@@ -0,0 +1,10 @@
+/**
+ * Shim: run migration-apply against the sample-app fixture and write
+ * the per-blueprint report at .rcf/reports/blueprints/persistence-data-postgres/migration-apply.json.
+ */
+
+import runProbe from './migration-apply.mjs';
+import { runShim } from './probe-utils.mjs';
+
+const engine = { kind: 'postgres', image: 'postgres:17-alpine', healthy: true };
+runShim('migration-apply', engine, runProbe);

package/blueprints/persistence-data-postgres/contributions/probes/run-pool-posture-smoke.mjs

@@ -0,0 +1,9 @@
+/**
+ * Shim: run pool-posture-smoke.
+ */
+
+import runProbe from './pool-posture-smoke.mjs';
+import { runShim } from './probe-utils.mjs';
+
+const engine = { kind: 'postgres', image: 'postgres:17-alpine', healthy: true };
+runShim('pool-posture-smoke', engine, runProbe);

package/blueprints/persistence-data-postgres/contributions/probes/run-prepared-statement-scan.mjs

@@ -0,0 +1,10 @@
+/**
+ * Shim: run prepared-statement-scan against the fixture facade
+ * directory and write the report.
+ */
+
+import runProbe from './prepared-statement-scan.mjs';
+import { runShim } from './probe-utils.mjs';
+
+const engine = { kind: 'source-scan', target: 'infra-postgres/src', healthy: true };
+runShim('prepared-statement-scan', engine, runProbe);

package/blueprints/persistence-data-postgres/contributions/probes/run-recovery-restore-round-trip.mjs

@@ -0,0 +1,9 @@
+/**
+ * Shim: run recovery-restore-round-trip.
+ */
+
+import runProbe from './recovery-restore-round-trip.mjs';
+import { runShim } from './probe-utils.mjs';
+
+const engine = { kind: 'postgres', image: 'postgres:17-alpine', healthy: true };
+runShim('recovery-restore-round-trip', engine, runProbe);

package/blueprints/persistence-data-postgres/contributions/probes/run-transaction-atomicity.mjs

@@ -0,0 +1,10 @@
+/**
+ * Shim: run transaction-atomicity against the sample-app fixture and
+ * write the per-blueprint report.
+ */
+
+import runProbe from './transaction-atomicity.mjs';
+import { runShim } from './probe-utils.mjs';
+
+const engine = { kind: 'postgres', image: 'postgres:17-alpine', healthy: true };
+runShim('transaction-atomicity', engine, runProbe);

package/blueprints/persistence-data-postgres/contributions/probes/transaction-atomicity.mjs

@@ -0,0 +1,79 @@
+/**
+ * Transaction atomicity probe.
+ *
+ * Opens the fixture facade's transaction helper against the running
+ * postgres:17-alpine container, issues two INSERTs where the second
+ * violates the UNIQUE constraint on email, asserts:
+ *   - the transaction rolls back
+ *   - transactionRolledBack event fires with statementIndex 1
+ *   - the first row does not persist after rollback
+ *
+ * Anchors AC-27104-1.
+ *
+ * Cleans up: TRUNCATE users on exit; closes the pool.
+ */
+
+import { createStore, connectionUrlFromEnv } from '../../../../packages/rcf-lite/test/fixtures/infra-postgres/src/store.mjs';
+
+export default async function runProbe() {
+  const events = [];
+  const store = createStore({
+    connectionUrl: connectionUrlFromEnv(),
+    onEvent: (e) => events.push(e),
+  });
+  const results = [];
+  try {
+    await store.ready();
+    const pool = store.getPool();
+    // Ensure schema and empty state
+    await pool.query('CREATE TABLE IF NOT EXISTS users (id SERIAL PRIMARY KEY, name TEXT NOT NULL, email TEXT UNIQUE, created_at TIMESTAMPTZ NOT NULL DEFAULT now())');
+    await pool.query('TRUNCATE users');
+
+    const email = 'transaction-atomicity@rcf.test';
+    let caught = null;
+    try {
+      await store.withTransaction(async (tx) => {
+        await tx.query('INSERT INTO users(name, email) VALUES ($1, $2)', ['first-user', email]);
+        // Same email violates UNIQUE constraint on the second insert
+        await tx.query('INSERT INTO users(name, email) VALUES ($1, $2)', ['second-user', email]);
+      });
+    } catch (err) {
+      caught = err;
+    }
+
+    const errorThrown = caught !== null;
+    results.push({
+      anchorAcId: 'AC-27104-1',
+      verdict: errorThrown ? 'pass' : 'fail',
+      detail: errorThrown
+        ? `withTransaction re-threw underlying error code=${caught.code}`
+        : 'withTransaction did not throw on the constraint violation',
+    });
+
+    const rolledBackEvent = events.find((e) => e.event === 'transactionRolledBack');
+    const indexIsOne = rolledBackEvent && rolledBackEvent.statementIndex === 1;
+    results.push({
+      anchorAcId: 'AC-27104-1',
+      verdict: indexIsOne ? 'pass' : 'fail',
+      detail: rolledBackEvent
+        ? `transactionRolledBack fired with statementIndex=${rolledBackEvent.statementIndex} code=${rolledBackEvent.code}`
+        : `transactionRolledBack did not fire; events=${JSON.stringify(events)}`,
+    });
+
+    const count = await store.countUsers();
+    const noRowsPersist = count === 0;
+    results.push({
+      anchorAcId: 'AC-27104-1',
+      verdict: noRowsPersist ? 'pass' : 'fail',
+      detail: noRowsPersist
+        ? 'users table empty after rollback (no partial commit landed)'
+        : `users table carries ${count} row(s) after rollback (partial commit leaked)`,
+    });
+  } finally {
+    try {
+      await store.getPool().query('TRUNCATE users');
+    } catch { /* ignore */ }
+    await store.close();
+  }
+  return results;
+}

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

@@ -0,0 +1,18 @@
+{
+  "reqId": "persistence-data-postgres-REQ-001",
+  "prdId": "PRD-001",
+  "title": "One facade module is the sole reader of the pg client and opens on boot",
+  "description": "The application accesses Postgres through a single facade module in the project's source tree that is the ONLY module in the tree that imports and reads the pg (node-postgres) client. Every other module that touches persistence imports the facade and calls its named domain verbs; no other module holds the raw pg client, a pg.Pool reference, or a pg.PoolClient reference. On process boot, the facade opens a pg.Pool against the elicited connection URL and, once the first successful ready-check completes, emits a facadeReady lifecycle event carrying the database name. The connection URL is elicited (project-config file by default; a security-secrets-management-applied project passes a secretRef).",
+  "category": "functional",
+  "domain": "persistence",
+  "priority": "must",
+  "rationale": "A single facade is what turns the raw pg driver surface into an application-side surface with domain-shaped verbs. Multiple call sites reaching into the driver directly produces a codebase where the shape of the store, the parameter-binding discipline, the event-emission discipline, and the pool posture are all diffused across the tree. One facade means one place to test, one place to swap (the round-6 Hyperdrive adapter slots in here without a facade re-shape), and one place where the persistence code paths are discoverable.",
+  "tags": [
+    "blueprint:persistence-data-postgres",
+    "category:01-facade"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-09-06T15:47:00.000Z",
+  "updatedAt": "2026-09-06T15:47:00.000Z"
+}

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

@@ -0,0 +1,18 @@
+{
+  "reqId": "persistence-data-postgres-REQ-002",
+  "prdId": "PRD-001",
+  "title": "Schema evolution ships as numbered forward-only .sql migrations applied one file one transaction",
+  "description": "Schema evolution is expressed as a directory of numbered .sql migration files under the elicited migrations directory (default ./migrations/). Each filename begins with a monotonically increasing integer that is unique across the directory; the file body is engine-native SQL. An in-tree migration runner applies each file inside its own transaction (BEGIN, run the file body, COMMIT on success or ROLLBACK on error); the runner tracks applied filenames in a schema_version bookkeeping table it maintains inside the same database. There are no down migrations. Which runner tool the project reaches for is elicited (a node-pg-migrate wrap, a sqitch invocation, a flyway process, or a bespoke Node runner over pg); the discipline is what is fixed here, not the tool.",
+  "category": "technical",
+  "domain": "persistence",
+  "priority": "must",
+  "rationale": "Numbered forward-only migrations are the general-enterprise-practice shape for schema evolution over Postgres. One file one transaction gives the runner a clean rollback surface on any statement failure; the schema_version table gives the project a single source of truth on what has been applied to the deployed database. Refusing to bless one migration tool keeps the shelf out of the maintenance stance of a tool it does not build; the runner mode is elicited so a long-lived Node process may run migrations at boot while a Workers-adjacent deployment runs them as a CI step.",
+  "tags": [
+    "blueprint:persistence-data-postgres",
+    "category:02-migration-runner"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-09-06T15:47:00.000Z",
+  "updatedAt": "2026-09-06T15:47:00.000Z"
+}

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

@@ -0,0 +1,18 @@
+{
+  "reqId": "persistence-data-postgres-REQ-003",
+  "prdId": "PRD-001",
+  "title": "Prepared-statement discipline: every pg.query first argument is a static string literal with $N parameters",
+  "description": "Every call to pg.query (whether via the pool, a client, or a transaction helper) inside the facade module passes a static string literal as its first argument and supplies parameters as an array of values that the driver binds to $1, $2, ... $N placeholders in the string, per the node-postgres parameterised-queries contract at https://node-postgres.com/features/queries. No call site inside the facade passes a template literal with an interpolated expression as the first argument; no call site builds a query string via string concatenation or template-literal interpolation with consumer-supplied values. A call site that violates the discipline refuses at author-side review; the prepared-statement-scan probe surfaces the violation at gate time via a source-tree AST scan (per the persistence-data-d1 pattern).",
+  "category": "technical",
+  "domain": "persistence",
+  "priority": "must",
+  "rationale": "Static string literals with $N parameters is what stops SQL injection at the driver boundary. The pg client's parameter-binding surface is safe; string concatenation with consumer-supplied values is not. The discipline is testable at build time by an AST scan without a running database, which is the shape a shelf blueprint can prove without shipping a test file (mechanism-reach principle, blueprint-authoring section 7); the runtime facade-round-trip probe carries the runtime observable that the surface works end to end.",
+  "tags": [
+    "blueprint:persistence-data-postgres",
+    "category:03-prepared-statements"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-09-06T15:47:00.000Z",
+  "updatedAt": "2026-09-06T15:47:00.000Z"
+}

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

@@ -0,0 +1,18 @@
+{
+  "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.",
+  "category": "functional",
+  "domain": "persistence",
+  "priority": "must",
+  "rationale": "Postgres MVCC gives transactions a clean rollback surface; the helper's job is to make the rollback observable and to guarantee no partial commit lands on the shipped database. The zero-based statement index on the event is what lets the calling code (or a log line, or an error boundary) name which statement failed inside a batch of five without a stack-trace decode.",
+  "tags": [
+    "blueprint:persistence-data-postgres",
+    "category:04-transaction-helper"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-09-06T15:47:00.000Z",
+  "updatedAt": "2026-09-06T15:47:00.000Z"
+}

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

@@ -0,0 +1,18 @@
+{
+  "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.",
+  "category": "functional",
+  "domain": "persistence",
+  "priority": "must",
+  "rationale": "pg_dump gives a portable artefact the operator can move off the deploy target; PITR gives the fine-grained restore point pg_dump cannot. Neither alone covers the two failure classes a shipped Postgres project has to survive: a corrupted managed cluster (PITR helps only if the corruption pre-dates the retention floor; a pg_dump artefact off-cluster survives cluster loss) and a data-integrity incident an operator wants to unwind by minutes (PITR restore point; a nightly pg_dump loses too much). Two paths, both required, is the general-enterprise-practice shape.",
+  "tags": [
+    "blueprint:persistence-data-postgres",
+    "category:05-recovery"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-09-06T15:47:00.000Z",
+  "updatedAt": "2026-09-06T15:47:00.000Z"
+}

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

@@ -0,0 +1,18 @@
+{
+  "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.",
+  "category": "technical",
+  "domain": "persistence",
+  "priority": "must",
+  "rationale": "Postgres has real connection cost per open, and the pool is what amortises it. A long-lived Node process wants one pool per process; a request-scoped container platform wants a pool per request (or delegated to Hyperdrive when the round-6 adapter lands). The shipped defaults are the pg driver's own defaults; the elicit surface lets an operator move them per target without moving any AC on this blueprint.",
+  "tags": [
+    "blueprint:persistence-data-postgres",
+    "category:06-pool-posture"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-09-06T15:47:00.000Z",
+  "updatedAt": "2026-09-06T15:47:00.000Z"
+}

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

@@ -0,0 +1,18 @@
+{
+  "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.",
+  "category": "functional",
+  "domain": "persistence",
+  "priority": "should",
+  "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",
+    "category:07-advisory-lock"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-09-06T15:47:00.000Z",
+  "updatedAt": "2026-09-06T15:47:00.000Z"
+}

package/blueprints/persistence-data-postgres/contributions/tacs/tac-2801-persistence-data-postgres-facade.json

@@ -0,0 +1,58 @@
+{
+  "tacId": "TAC-2801-persistence-data-postgres-facade",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "approved",
+  "name": "Postgres store facade",
+  "purpose": "The single project-side module that imports the pg driver, exposes narrow named domain verbs to consumer code, issues every query as a static string literal with $N parameters, and emits structured lifecycle events to the injected event sink. Consumers never destructure the pg driver outside this module; the facade is the one place the vendor surface lives. The driver reference is opaque at this boundary so the round-6 Hyperdrive v1.1.0 adapter (ADR-2801) can swap the client without a facade re-shape.",
+  "responsibilities": [
+    "Open a pg.Pool on boot against the elicited connection URL; hold no other reference to the pg vendor surface; export no symbol that leaks the raw pool or client (AC-27101-1, AC-27101-2).",
+    "Expose named domain verbs (getUserById, createUser, listUsers, ...) as named exports with typed parameters; refuse a general-purpose raw-SQL passthrough on the public surface (AC-27101-1, AC-27103-1).",
+    "Issue every read and write through pg.query with a static string literal as the first argument and parameters as an array bound to $1, $2, ... $N per the node-postgres parameterised-queries contract (AC-27103-1).",
+    "Expose the transaction helper (TAC-2803) as a named verb; consumers pass a callback, the helper wraps BEGIN and COMMIT, ROLLBACK on error, and fires transactionRolledBack on the sink with the failing statement index (AC-27104-1).",
+    "Emit facadeReady exactly once per facade instance on the injected event sink with the database name; serialise pre-ready consumer queries behind the pool's ready-check (AC-27101-1, AC-27108-1).",
+    "Expose the optional advisory-lock helper only when the elicited answer is session or transaction; the surface is absent when the answer is off (AC-27107-1)."
+  ],
+  "internalStructure": "One module exporting a createStore({ connectionUrl, onEvent, poolConfig, advisoryLockHelper }) factory returning a Store whose methods are the named CRUD verbs plus withTransaction and (optionally) withAdvisoryLock. The pg import lives at the top of this module; the factory captures a pg.Pool and the injected sink and hands back closures. Consumers destructure the verbs they need at their top level and hold the facade reference for the process lifetime (or, on a request-scoped container platform, for the request lifetime).",
+  "interfaces": [
+    {
+      "name": "createStore",
+      "kind": "factory",
+      "description": "createStore({ connectionUrl, onEvent, poolConfig, advisoryLockHelper }) -> Store. The sole entry point every consumer calls. Opens a pg.Pool against connectionUrl; wires the sink; hands back a Store whose methods are the named CRUD verbs plus withTransaction and (optionally) withAdvisoryLock."
+    },
+    {
+      "name": "onEvent",
+      "kind": "callback",
+      "description": "Structured-event sink invoked with { event, ts, ... } for facadeReady, migrationsApplied, transactionRolledBack, backupExported, recoveryDrillPassed, queryFailed events. Never invoked with domain-row values."
+    },
+    {
+      "name": "store.verbs",
+      "kind": "read-write-api",
+      "description": "The named domain CRUD verbs the facade exposes. Each verb has typed parameters; no verb accepts a raw SQL string or a general query object from consumer code."
+    }
+  ],
+  "dependencies": [
+    {
+      "name": "Migration runner",
+      "kind": "tac",
+      "tacId": "TAC-2802-persistence-data-postgres-migration-runner",
+      "description": "The runner the facade or the CI step invokes to apply forward-only migrations before the facade opens its first query."
+    },
+    {
+      "name": "Transaction helper",
+      "kind": "tac",
+      "tacId": "TAC-2803-persistence-data-postgres-transaction-helper",
+      "description": "The helper wrapping BEGIN and COMMIT around a consumer callback; exposed as store.withTransaction."
+    },
+    {
+      "name": "Recovery runner",
+      "kind": "tac",
+      "tacId": "TAC-2804-persistence-data-postgres-recovery-runner",
+      "description": "Shares the facade's event sink for backupExported and recoveryDrillPassed events; invoked from the ops or CI surface, not from request code."
+    }
+  ],
+  "tradeoffs": "The facade holds a long-lived pool on Node targets and a request-scoped pool on container targets; the round-6 Hyperdrive adapter (ADR-2801) delegates the pool entirely to the Hyperdrive-managed pool. That flexibility costs a per-target pool decision the operator makes via ADR-2805; the facade's outward interface stays unchanged across all three postures.",
+  "createdAt": "2026-09-06T15:47:00.000Z",
+  "updatedAt": "2026-09-06T15:47:00.000Z"
+}