rcf-lite 0.27.0 → 0.28.0

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

@@ -1,28 +1,58 @@
 /**
  * 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.
+ * Drives the shipped fixture recovery runner (src/recovery.mjs
+ * exportDatabase, TAC-2804) to produce the dump artefact and asserts
+ * the runner emits `backupExported` per AC-27105-1. Because pg_dump is
+ * not on the host PATH in every CI runner, the probe supplies the
+ * runPgDump override on `exportDatabase` that shells out to
+ * `docker exec <sourceContainer> pg_dump ...`. The shipped runner is
+ * still the code path under test; only the pg_dump invocation is
+ * container-hosted.
+ *
+ * Brings up a second postgres:17-alpine container on a spare port,
+ * pipes the artefact through psql into that container (via the same
+ * docker exec pattern), and asserts row-count and md5 checksum
+ * equality between source and restored databases.
  *
  * Anchors AC-27105-1 (recovery exported, restore round-trips the row
- * set).
+ * set, backupExported event fires).
  *
- * Cleans up: TRUNCATE users on source; stops the restore container and
- * removes its volume; deletes the artefact file.
+ * Cleanup: TRUNCATE users on source; stops the restore container and
+ * removes its volume; deletes the artefact directory. Every teardown
+ * step records its exit status in the report's `teardown` bag; a
+ * teardown failure FAILS the verdict per authoring-standard rule 5.
  */
 
 import { spawn, execFile } from 'node:child_process';
 import { promisify } from 'node:util';
-import { mkdir, writeFile, unlink, rm } from 'node:fs/promises';
+import { mkdir, writeFile, rm, stat } 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';
+import { createStore, connectionUrlFromEnv, MissingPostgresHostError } from '../../../../packages/rcf-lite/test/fixtures/infra-postgres/src/store.mjs';
+import { exportDatabase } from '../../../../packages/rcf-lite/test/fixtures/infra-postgres/src/recovery.mjs';
+
+export const DECLARED_ENV = Object.freeze([
+  'POSTGRES_HOST',
+  'POSTGRES_PORT',
+  'POSTGRES_USER',
+  'POSTGRES_PASSWORD',
+  'POSTGRES_DB',
+  'POSTGRES_SOURCE_CONTAINER',
+  'POSTGRES_RESTORE_CONTAINER',
+  'POSTGRES_RESTORE_PORT',
+]);
+
+function skipRow(variable) {
+  return {
+    anchorAcId: null,
+    verdict: 'pass',
+    detail: `Given a live Postgres containing a small fixture rowset - accountBound: skipped (${variable} unset)`,
+    accountBoundSkipped: true,
+    reason: `${variable} unset`,
+    evidence: { skip: true, reason: `${variable} unset`, envDeclared: [...DECLARED_ENV] },
+  };
+}
 
 const execFileAsync = promisify(execFile);
 const HERE = dirname(fileURLToPath(import.meta.url));
@@ -30,9 +60,15 @@ 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';
+// Source container defaults to the fixture's docker-compose service
+// name; a CI runner (or a positive-evidence run) may override via
+// POSTGRES_SOURCE_CONTAINER. Restore container name and port are
+// similarly overridable so parallel runs and non-default docker
+// networks can pick free ports; both env vars are declared on the
+// fixture's Declared env vars table.
+const SOURCE_CONTAINER = process.env.POSTGRES_SOURCE_CONTAINER || 'infra-postgres-postgres-1';
+const RESTORE_CONTAINER = process.env.POSTGRES_RESTORE_CONTAINER || 'infra-postgres-restore';
+const RESTORE_PORT = process.env.POSTGRES_RESTORE_PORT || '55432';
 
 async function dockerExec(container, cmd, opts = {}) {
   return execFileAsync('docker', ['exec', container, ...cmd], { maxBuffer: 64 * 1024 * 1024, ...opts });
@@ -43,7 +79,7 @@ async function dockerExec(container, cmd, opts = {}) {
  * accept stdin buffers, so use spawn.
  */
 async function dockerExecStdin(container, cmd, stdinBuffer) {
-  return new Promise((resolve2, reject) => {
+  return new Promise((resolveP, reject) => {
     const child = spawn('docker', ['exec', '-i', container, ...cmd]);
     const chunks = [];
     const errChunks = [];
@@ -51,7 +87,7 @@ async function dockerExecStdin(container, cmd, stdinBuffer) {
     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') });
+      if (code === 0) return resolveP({ 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);
@@ -71,14 +107,43 @@ async function waitHealthy(container, maxSeconds = 30) {
   throw new Error(`container ${container} did not become healthy within ${maxSeconds}s`);
 }
 
+/**
+ * Positively assert `container` is absent by asking docker to inspect
+ * it. Absent = docker exits non-zero WITH `No such object` on stderr.
+ * Any other error (daemon unreachable, permission denied) fails the
+ * assertion; the caller can then FAIL the row rather than treat it as
+ * "no problem here".
+ */
+async function assertContainerAbsent(container) {
+  try {
+    await execFileAsync('docker', ['inspect', container]);
+    throw new Error(`container ${container} still exists`);
+  } catch (err) {
+    if (err && err.stderr && /[Nn]o such object|[Ee]rror: [Nn]o such/i.test(err.stderr)) return { absent: true };
+    if (err && err.message && err.message.includes('still exists')) throw err;
+    // Unrecognized inspect failure - do NOT treat as absent.
+    throw new Error(`docker inspect on ${container} produced an unrecognized error: ${err && (err.stderr || err.message) || 'unknown'}`);
+  }
+}
+
 async function bringUpRestore() {
-  // Remove any prior instance
-  await execFileAsync('docker', ['rm', '-f', RESTORE_CONTAINER]).catch(() => {});
+  // Pre-run cleanup: remove any prior instance, THEN positively assert
+  // the container is gone. If the pre-run rm fails for a reason other
+  // than "container did not exist", let the run fail loudly rather
+  // than proceed to a `docker run` that would collide.
+  try {
+    await execFileAsync('docker', ['rm', '-f', RESTORE_CONTAINER]);
+  } catch (err) {
+    if (!(err && err.stderr && /[Nn]o such container|[Ee]rror: [Nn]o such/i.test(err.stderr))) {
+      throw new Error(`pre-run rm of ${RESTORE_CONTAINER} failed and did not name a No-such-container reason: ${err && (err.stderr || err.message) || 'unknown'}`);
+    }
+  }
+  await assertContainerAbsent(RESTORE_CONTAINER);
   await execFileAsync('docker', [
     'run', '-d',
     '--name', RESTORE_CONTAINER,
     '-e', 'POSTGRES_USER=rcf',
-    '-e', 'POSTGRES_PASSWORD=rcf-dev-only',
+    '-e', 'POSTGRES_PASSWORD',
     '-e', 'POSTGRES_DB=rcf_test',
     '-p', `${RESTORE_PORT}:5432`,
     '--health-cmd', 'pg_isready -U rcf -d rcf_test',
@@ -89,20 +154,57 @@ async function bringUpRestore() {
   await waitHealthy(RESTORE_CONTAINER, 30);
 }
 
-async function tearDownRestore() {
-  await execFileAsync('docker', ['rm', '-f', '-v', RESTORE_CONTAINER]).catch(() => {});
+/**
+ * Attempt one teardown step; record its outcome on the accumulator.
+ * The step is the literal command reported so a reader sees exactly
+ * what ran.
+ */
+async function recordTeardown(accumulator, label, fn) {
+  const entry = { step: label, ok: false, exitCode: null, error: null };
+  try {
+    const out = await fn();
+    entry.ok = true;
+    entry.exitCode = 0;
+    if (out && typeof out === 'object' && 'exitCode' in out) entry.exitCode = out.exitCode;
+  } catch (err) {
+    entry.error = err && err.message ? err.message : String(err);
+    entry.exitCode = err && typeof err.code === 'number' ? err.code : 1;
+  }
+  accumulator.push(entry);
+  return entry;
 }
 
 export default async function runProbe() {
+  let url;
+  try {
+    url = connectionUrlFromEnv();
+  } catch (err) {
+    if (err instanceof MissingPostgresHostError) {
+      return {
+        results: [skipRow(err.variable)],
+        accountBoundSkipped: true,
+        reason: `${err.variable} unset`,
+        envDeclared: [...DECLARED_ENV],
+      };
+    }
+    throw err;
+  }
   const events = [];
-  const store = createStore({
-    connectionUrl: connectionUrlFromEnv(),
+  const store = await createStore({
+    connectionUrl: url,
     onEvent: (e) => events.push(e),
   });
   const results = [];
+  const teardown = [];
+  let restoreBrought = false;
+  let artefactWritten = false;
+  let databaseName = null;
   try {
-    await store.ready();
+    databaseName = await store.ready();
     const pool = store.getPool();
+    const pidRR = await pool.query('SELECT pg_backend_pid() AS pid, txid_current() AS txid');
+    const backendPidSrc = String(pidRR.rows[0].pid);
+    const transactionIdSrc = String(pidRR.rows[0].txid);
 
     // 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())');
@@ -118,56 +220,167 @@ export default async function runProbe() {
       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)
+    // Compute source row-count and checksum
     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
+    // Drive the shipped exportDatabase runner (TAC-2804) with a
+    // runPgDump override that shells out to docker exec inside the
+    // source container. The shipped runner still writes the artefact
+    // and emits backupExported; the probe proves both.
+    //
+    // Pre-run: assert the destination directory is absent, then create
+    // it. If a prior run left a stale artefact, remove it and
+    // positively re-check absence. Any failure here (permission
+    // denied, filesystem error) fails the row loudly.
+    try {
+      const preExist = await stat(ARTEFACT_DIR).catch((err) => {
+        if (err && err.code === 'ENOENT') return null;
+        throw err;
+      });
+      if (preExist) {
+        await rm(ARTEFACT_DIR, { recursive: true, force: true });
+        const after = await stat(ARTEFACT_DIR).catch((err) => {
+          if (err && err.code === 'ENOENT') return null;
+          throw err;
+        });
+        if (after) throw new Error(`pre-run: destination ${ARTEFACT_REL} still exists after rm -rf`);
+      }
+    } catch (err) {
+      if (!/still exists/.test(err && err.message)) throw new Error(`pre-run destination cleanup failed unrecognizably: ${err && (err.message || String(err))}`);
+      throw err;
+    }
     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');
+    const runnerEvents = [];
+    const exported = await exportDatabase({
+      destination: ARTEFACT,
+      onEvent: (e) => runnerEvents.push(e),
+      runPgDump: async ({ pgDumpArgs }) => {
+        const dump = await dockerExec(SOURCE_CONTAINER, ['pg_dump', '-U', 'rcf', '-d', 'rcf_test', ...pgDumpArgs]);
+        return dump.stdout;
+      },
+    });
+    artefactWritten = true;
+    const artefactStat = await stat(ARTEFACT);
+
+    // Assert the runner emitted backupExported per AC-27105-1.
+    // Sanitize the event's artefactPath (recovery.mjs records it as
+    // the absolute destination) to a project-relative path so a
+    // machine path does not land in the persisted evidence record.
+    const backupEvent = runnerEvents.find((e) => e.event === 'backupExported');
+    const backupEventSanitized = backupEvent
+      ? { ...backupEvent, artefactPath: relative(PROJECT_ROOT, backupEvent.artefactPath) }
+      : null;
+    results.push({
+      anchorAcId: 'AC-27105-1',
+      verdict: (backupEvent && typeof backupEvent.artefactPath === 'string' && typeof backupEvent.completedAt === 'string') ? 'pass' : 'fail',
+      detail: backupEvent
+        ? `Given a live Postgres containing a small fixture rowset - shipped exportDatabase emitted backupExported with artefactPath=${relative(PROJECT_ROOT, backupEvent.artefactPath)} completedAt=${backupEvent.completedAt}`
+        : `Given a live Postgres containing a small fixture rowset - expected backupExported event on the shipped exportDatabase runner; observed events=${runnerEvents.map((e) => e.event).join(',')}`,
+      evidence: {
+        backendPid: backendPidSrc,
+        transactionId: transactionIdSrc,
+        databaseName,
+        artefactPath: ARTEFACT_REL,
+        artefactBytesOnDisk: artefactStat.size,
+        bytesReportedByRunner: exported.bytes,
+        backupExportedEvent: backupEventSanitized,
+      },
+    });
 
     // Bring up restore container
     await bringUpRestore();
+    restoreBrought = true;
 
-    // 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'));
+    // Pipe artefact into psql on restore (the container ships psql).
+    await dockerExecStdin(RESTORE_CONTAINER, ['psql', '-U', 'rcf', '-d', 'rcf_test', '-v', 'ON_ERROR_STOP=1'], Buffer.from(await import('node:fs').then((fs) => fs.promises.readFile(ARTEFACT))));
 
-    // Read row-count and checksum on restored
-    const dstStore = createStore({ connectionUrl: `postgres://rcf:${encodeURIComponent('rcf-dev-only')}@localhost:${RESTORE_PORT}/rcf_test` });
+    // Read row-count and checksum on restored via a connection to the
+    // restore container's published port. Host is taken from
+    // POSTGRES_HOST (the docker host the restore container publishes
+    // its port on); no literal host default lives in shipped probe
+    // code.
+    // Password read from the declared POSTGRES_PASSWORD variable
+    // only; no literal password value in shipped probe source.
+    const dstStore = await createStore({ connectionUrl: `postgres://${process.env.POSTGRES_USER || 'rcf'}:${encodeURIComponent(process.env.POSTGRES_PASSWORD || '')}@${process.env.POSTGRES_HOST}:${RESTORE_PORT}/${process.env.POSTGRES_DB || 'rcf_test'}` });
     let dstCount = -1;
     let dstCk = 'unset';
+    let backendPidDst = null;
+    let transactionIdDst = null;
     try {
       await dstStore.ready();
       const dstPool = dstStore.getPool();
+      const pidRD = await dstPool.query('SELECT pg_backend_pid() AS pid, txid_current() AS txid');
+      backendPidDst = String(pidRD.rows[0].pid);
+      transactionIdDst = String(pidRD.rows[0].txid);
       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}`,
+      detail: `Given a live Postgres containing a small fixture rowset - row-count source=${srcCount} restored=${dstCount}`,
+      evidence: { backendPid: backendPidDst, transactionId: transactionIdDst, databaseName, srcCount, dstCount, restoreContainer: RESTORE_CONTAINER, restorePort: RESTORE_PORT },
     });
     results.push({
       anchorAcId: 'AC-27105-1',
       verdict: srcCk === dstCk && srcCk != null ? 'pass' : 'fail',
-      detail: `checksum source=${srcCk} restored=${dstCk}`,
+      detail: `Given a live Postgres containing a small fixture rowset - checksum source=${srcCk} restored=${dstCk}`,
+      evidence: { backendPid: backendPidDst, transactionId: transactionIdDst, srcChecksumMd5: srcCk, dstChecksumMd5: dstCk, checksumMatchStatus: (srcCk && dstCk && srcCk === dstCk) ? 'equal' : 'differ' },
     });
   } 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(() => {});
+    // Teardown, every step recorded. A failure here becomes a FAIL row
+    // on the results per authoring-standard rule 5.
+    await recordTeardown(teardown, 'TRUNCATE users on source', async () => {
+      try {
+        await store.getPool().query('TRUNCATE users RESTART IDENTITY');
+      } catch (err) {
+        // If the source is unreachable the probe still needs the store closed;
+        // rethrow so the accumulator records the failure.
+        throw err;
+      }
+    });
+    await recordTeardown(teardown, 'close source pool', async () => {
+      await store.close();
+    });
+    if (restoreBrought) {
+      await recordTeardown(teardown, `docker rm -f -v ${RESTORE_CONTAINER}`, async () => {
+        await execFileAsync('docker', ['rm', '-f', '-v', RESTORE_CONTAINER]);
+      });
+      // Positively confirm the container is gone. Any inspect outcome
+      // other than a "No such object" error fails the step so an
+      // unrecognized daemon-side error is not laundered into success.
+      await recordTeardown(teardown, `docker inspect ${RESTORE_CONTAINER} (expected: absent)`, async () => {
+        await assertContainerAbsent(RESTORE_CONTAINER);
+        return { exitCode: 0 };
+      });
+    }
+    if (artefactWritten) {
+      await recordTeardown(teardown, `rm -rf ${ARTEFACT_REL}`, async () => {
+        await rm(ARTEFACT_DIR, { recursive: true, force: true });
+      });
+    }
   }
-  return results;
+  // Fold teardown outcomes into the result set (authoring-standard rule 5).
+  const failedTeardown = teardown.filter((t) => !t.ok);
+  // AC-27105-1 states rowset round-trip + backupExported. It does not
+  // state scratch-resource teardown, so this row is CONFORMANCE-ONLY:
+  // it records the operational teardown of the scratch restore
+  // container and artefact so a reader can see the run left no state
+  // behind, without claiming the AC's rowset property.
+  const AC27105_TEARDOWN_LIMITATION = 'AC-27105-1: Given a live Postgres containing a small fixture rowset, when the shipped recovery runner exports a backup, then backupExported fires with an artefact path and completedAt timestamp and a subsequent restore against a throwaway container yields byte-equal rowset content. Not observed on this row: this row records only the operational teardown (docker rm of the throwaway restore container plus removal of the pg_dump artefact tree) that follows the AC observing rows; the AC observing evidence is on the earlier rows in this same probe.';
+  results.push({
+    anchorAcId: null,
+    conformanceOnly: true,
+    limitation: AC27105_TEARDOWN_LIMITATION,
+    verdict: failedTeardown.length === 0 ? 'pass' : 'fail',
+    detail: failedTeardown.length === 0
+      ? `conformanceOnly (AC-27105-1: Given a live Postgres containing a small fixture) - teardown ok: ${teardown.map((t) => `${t.step} (exit=${t.exitCode})`).join('; ')}`
+      : `conformanceOnly (AC-27105-1: Given a live Postgres containing a small fixture) - teardown FAILED (${failedTeardown.length}/${teardown.length}): ${failedTeardown.map((t) => `${t.step} -> ${t.error}`).join('; ')}`,
+    evidence: { teardown },
+  });
+  return { results, extra: { teardown, restoreContainer: RESTORE_CONTAINER, restorePort: RESTORE_PORT } };
 }

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

@@ -10,70 +10,126 @@
  *
  * Anchors AC-27104-1.
  *
- * Cleans up: TRUNCATE users on exit; closes the pool.
+ * Cleans up: TRUNCATE users on exit; closes the pool. A teardown
+ * failure emits its own row (authoring-standard rule 5).
  */
 
-import { createStore, connectionUrlFromEnv } from '../../../../packages/rcf-lite/test/fixtures/infra-postgres/src/store.mjs';
+import { createStore, connectionUrlFromEnv, MissingPostgresHostError } from '../../../../packages/rcf-lite/test/fixtures/infra-postgres/src/store.mjs';
+
+const AC = 'Given the transaction helper wrapping a callback that';
+
+export const DECLARED_ENV = Object.freeze([
+  'POSTGRES_HOST',
+  'POSTGRES_PORT',
+  'POSTGRES_USER',
+  'POSTGRES_PASSWORD',
+  'POSTGRES_DB',
+  'SIMULATE_CONSTRAINT_VIOLATION',
+]);
+
+function skipRow(variable) {
+  return {
+    anchorAcId: null,
+    verdict: 'pass',
+    detail: `${AC} - accountBound: skipped (${variable} unset)`,
+    accountBoundSkipped: true,
+    reason: `${variable} unset`,
+    evidence: { skip: true, reason: `${variable} unset`, envDeclared: [...DECLARED_ENV] },
+  };
+}
 
 export default async function runProbe() {
+  let url;
+  try {
+    url = connectionUrlFromEnv();
+  } catch (err) {
+    if (err instanceof MissingPostgresHostError) {
+      return {
+        results: [skipRow(err.variable)],
+        accountBoundSkipped: true,
+        reason: `${err.variable} unset`,
+        envDeclared: [...DECLARED_ENV],
+      };
+    }
+    throw err;
+  }
   const events = [];
-  const store = createStore({
-    connectionUrl: connectionUrlFromEnv(),
+  const store = await createStore({
+    connectionUrl: url,
     onEvent: (e) => events.push(e),
   });
   const results = [];
+  let databaseName = null;
   try {
-    await store.ready();
+    databaseName = 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 pidRT = await pool.query('SELECT pg_backend_pid() AS pid, txid_current() AS txid');
+    const backendPid = String(pidRT.rows[0].pid);
+    const transactionId = String(pidRT.rows[0].txid);
     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',
+        ? `${AC} - withTransaction re-threw underlying error code=${caught.code}`
+        : `${AC} - withTransaction did not throw on the constraint violation`,
+      evidence: { backendPid, transactionId, databaseName, thrownErrorCode: caught && caught.code, thrownMessage: caught && caught.message },
     });
-
     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)}`,
+        ? `${AC} - transactionRolledBack fired with statementIndex=${rolledBackEvent.statementIndex} code=${rolledBackEvent.code}`
+        : `${AC} - transactionRolledBack did not fire; events=${events.map((e) => e.event).join(',')}`,
+      evidence: { backendPid, transactionId, databaseName, transactionRolledBackEvent: rolledBackEvent || null, allEvents: events, rolledBackTimestamp: rolledBackEvent ? new Date(rolledBackEvent.ts).toISOString() : null, rolledBackVerificationOk: !!rolledBackEvent && rolledBackEvent.statementIndex === 1 },
     });
-
     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)`,
+        ? `${AC} - users table empty after rollback (no partial commit landed)`
+        : `${AC} - users table carries ${count} row(s) after rollback (partial commit leaked)`,
+      evidence: { backendPid, transactionId, databaseName, postRollbackUserCount: count, postRollbackVerificationOk: count === 0 },
     });
   } finally {
+    const teardown = [];
     try {
       await store.getPool().query('TRUNCATE users');
-    } catch { /* ignore */ }
-    await store.close();
+      teardown.push({ step: 'TRUNCATE users on close', ok: true });
+    } catch (err) {
+      teardown.push({ step: 'TRUNCATE users on close', ok: false, error: err && err.message });
+    }
+    try {
+      await store.close();
+      teardown.push({ step: 'close pool', ok: true });
+    } catch (err) {
+      teardown.push({ step: 'close pool', ok: false, error: err && err.message });
+    }
+    const failed = teardown.filter((t) => !t.ok);
+    if (failed.length > 0) {
+      results.push({
+        anchorReqId: 'persistence-data-postgres-REQ-004',
+        verdict: 'fail',
+        detail: `The facade exposes a transaction helper - teardown FAILED: ${failed.map((t) => `${t.step} -> ${t.error}`).join('; ')}`,
+        evidence: { teardown },
+      });
+    }
   }
-  return results;
+  return { results };
 }

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

@@ -2,7 +2,7 @@
   "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).",
+  "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 the author-side check; 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",

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

@@ -60,7 +60,7 @@ This table is maintained shelf-wide across every blueprint's `docs/topics.md`. R
 | platform-docker-compose-host | 38101-38899 | 39xx | shipped v1.0.0 | `containerHostContract` |
 | edge-cloudflare-tunnel | 39101-39899 | 40xx | shipped v1.0.0 | `edgeIngressBridge` |
 
-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.
+US 27101-27110 sit at the LOW end of the 27101-27899 band on purpose. 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).
 

package/blueprints/persistence-data-sqlite/CHANGELOG.md

@@ -1,14 +1,28 @@
 # Changelog
 
+## 1.1.5 - 2026-09-11
+
+Strengthens the shared probe anatomy helper the seven core-shelf blueprints all lean on: rows whose only signal is a parsed log object with a message, a linesExcerpt array, a parsed component list, a rendered-state or -order list, a perFile / entries / commitEntries list, or a locally invented callTrackingId are refused as identifier evidence; retained anchor ids are checked against the applicable blueprint's shipped AC set; the WARN row shortcut that accepted a bare unobservableReason is removed and every WARN must now satisfy exact-skip, notObservableHere (browser-only) or identifier-plus-derived. No SQLite probe change was needed; SQLite remains GREEN.
+
+## 1.1.4 - 2026-09-11
+
+wal-checkpoint AC-5105-3 anchor now observes the complete durability posture (PRAGMA journal_mode=wal + PRAGMA synchronous>=NORMAL + consumer-source grep) with a real integer rowId from a seed put through the facade; boot-open-migrate AC-5101-3 also carries a real rowId. Fixture store.mjs sets PRAGMA synchronous=NORMAL at open time and exposes synchronousNow(). Shared anatomy helper tightened per the strict-evidence contract (strict identifier set, existence check for shipped-AC limitation and notObservableHere.ac, exact-variable skip reason wire-up in all seven anatomy tests, notObservableHere is now refused for non-browser-only ACs, acceptedProfile removed from identifier lists, single JSON log-line string is derived only).
+
+## 1.1.3 - 2026-09-11
+
+Adds a contributions/probes/ pack (boot-open-migrate, facade-round-trip, wal-checkpoint) with a fixture-side node:sqlite store facade under packages/rcf-lite/test/fixtures/probe-pack-persistence-data-sqlite/. Probes run against the real node:sqlite engine on Node 24; record real integer row ids, applied-migration lists, and wal_checkpoint(TRUNCATE) counters with the WAL sidecar shrink after truncate. No account gate.
+
+Anchoring: boot-open-migrate anchors AC-5101-3 (open returns only after migrations run); the AC-5101-1 export-order row and the AC-5101-2 path-from-config row are de-claimed (conformanceOnly, anchorAcId=null) with limitations naming their respective ACs; the reopen row de-claims from AC-5101-3. wal-checkpoint anchors AC-5105-3 (durability posture set at open); the size-transition row and the walCheckpoint event row de-claim from AC-5105-1 and AC-5106-1 respectively. facade-round-trip anchors AC-5107-2 as its module anchor with the runtime CRUD rows de-claiming from AC-5107-2 (facade surface not exhaustively scanned) and the event row de-claiming from AC-5106-1. probe-utils normalisation and thrown-error rows carry an evidence object; the fallback anchorAcId is null (harnessError marks the row) rather than any placeholder id.
+
 ## 1.1.1 (register-sweep patch, 2026-09-10)
 
 - Register: neutral wording in shipped prose (no capability change).
 
 ## 1.1.0 - 2026-09-09
-Adds deliveredBy on REQ-001. Adds ownerRef on AC-5106-1 and AC-5110-2 (onEvent). Closes chain-contradiction specimen F-1: US-5109 AC-5109-3 now recovers a defective committed migration via a new numbered forward-only file (never editing the committed file in place), aligning with TAC-603 and the migration catalog's forward-only rule. Adds disposition to every AC.
+Adds deliveredBy on REQ-001. Adds ownerRef on AC-5106-1 and AC-5110-2 (onEvent). US-5109 AC-5109-3 recovers a defective committed migration via a new numbered forward-only file (never editing the committed file in place), aligning with TAC-603 and the migration catalog's forward-only rule. Adds disposition to every AC.
 
 
 
-Review-fix (2026-09-09): Version bumped from 1.0.1 to 1.1.0 to reflect the net-added AC contributions on existing stories (permission-denied and concurrent-WAL failure paths added under US-5101; disk-full mid-migration added under US-5104). Prior 1.0.1 entry reclassified as prose-only; this bump covers the AC additions per section 8.
+Version bumped from 1.0.1 to 1.1.0 to reflect the net-added AC contributions on existing stories (permission-denied and concurrent-WAL failure paths added under US-5101; disk-full mid-migration added under US-5104).
 
 Adds deliveredBy on REQ-002 through REQ-011 (ten of eleven mandatory REQs).

package/blueprints/persistence-data-sqlite/README.md

@@ -27,9 +27,9 @@ The doc set is contributions (copied into the project tree by `rcf define bluepr
 
 ## What it contributes, and what it deliberately does not
 
-Contributed kinds: REQ, US (with inline ACs), TAC, ADR. Adherence is expressed as ACs; the blueprint ships no test files (ratified decision 5) and no code.
+Contributed kinds: REQ, US (with inline ACs), TAC, ADR. Adherence is expressed as ACs; the blueprint ships no test files (shipped policy 5) and no code.
 
-No FBS contributions, as a matter of principle (ratified policy 2026-08-19): FBSs are the work of the implementing agent, not the blueprint; project constraints have to be applied at the time of creation. The blueprint contributes the WHAT (the store facade contract, the migration runner contract, the migration catalog shape, the backup runner contract, the event log discipline); the implementing agent derives the HOW-tasks (FBS) in the host project, where the ACs contributed here get picked up by the project's own build sequencing.
+No FBS contributions, as a matter of principle (policy): FBSs are the work of the implementing agent, not the blueprint; project constraints have to be applied at the time of creation. The blueprint contributes the WHAT (the store facade contract, the migration runner contract, the migration catalog shape, the backup runner contract, the event log discipline); the implementing agent derives the HOW-tasks (FBS) in the host project, where the ACs contributed here get picked up by the project's own build sequencing.
 
 Deliberately not contributed: the domain schema (the tables the project's own entities live in are project-authored, not blueprint-authored; the blueprint governs the store facade and the migration discipline, not the domain shape); ORMs, query builders, and any framework-shaped abstraction above the named CRUD verbs (the facade is a project-authored surface; how it internally implements its verbs is not blueprint-owned); a Postgres engine TAC (deferred; see ADR-601's alternatives and the guide 'when it does not fit'); logical schema-aware dumps (out of scope; see ADR-605's alternatives); connection pooling (an implementation detail of the facade when a project selects an engine that benefits from it, not a blueprint contribution).
 

package/blueprints/persistence-data-sqlite/blueprint.json

@@ -1,6 +1,6 @@
 {
   "slug": "persistence-data-sqlite",
-  "version": "1.1.1",
+  "version": "1.1.5",
   "category": "persistence",
   "contributions": [
     {
@@ -162,5 +162,6 @@
       "kind": "adr",
       "path": "adrs/adr-605-persistence-data-sqlite-backup-model.json"
     }
-  ]
+  ],
+  "updatedAt": "2026-09-11"
 }