rcf-lite 0.21.0 → 0.23.0

package/blueprints/persistence-data-postgres/contributions/adrs/adr-2803-persistence-data-postgres-runner-mode.json

@@ -0,0 +1,25 @@
+{
+  "adrId": "ADR-2803-persistence-data-postgres-runner-mode",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "accepted",
+  "title": "Migration runner mode: atBoot on long-lived Node, ciStep on Workers-adjacent or container-scheduled targets; elicited",
+  "context": "A long-lived Node process can run migrations at boot before opening the first request; a Workers-adjacent or serverless target cannot because the boot happens per invocation and does not amortise the migration cost. A container platform running warm instances behaves like long-lived Node but a fresh-per-request container behaves like Workers.",
+  "decision": "The migration runner mode is elicited: atBoot (the facade invokes the runner on process start before opening the first query) or ciStep (the CI pipeline invokes the runner as a deploy step before promoting the artefact). Default atBoot for long-lived Node targets; default ciStep for Workers-adjacent, request-scoped container, or Hyperdrive-fronted (round-6) targets. The applying project answers the elicit at apply time; the sidecar records the answer.",
+  "consequences": "Long-lived Node targets get zero-config migrations that run before the first request; the operator sees the migrationsApplied event in the process log and knows the schema advanced. Workers-adjacent targets get a CI-step that runs against the deploy target's own connection before the artefact promotes; the operator sees the runner's stdout in the CI log. A project moving from long-lived Node to Workers-adjacent updates the elicit and re-applies; no code moves. Standards trace clause: generic enterprise practice.",
+  "alternativesConsidered": [
+    {
+      "name": "Always atBoot",
+      "summary": "Ship atBoot as the only mode; the operator schedules a boot on the CI runner for ciStep-like behaviour.",
+      "reasonNotChosen": "A Workers-adjacent deploy has no long-lived boot event to hang the runner on; the operator would have to build a boot shim just to run migrations, which is the ciStep in disguise. Eliciting the mode is cheaper."
+    },
+    {
+      "name": "Always ciStep",
+      "summary": "Ship ciStep as the only mode; a long-lived Node process reads schema_version at boot and refuses to open if it is behind.",
+      "reasonNotChosen": "Local development on long-lived Node loses zero-config migrations; every developer has to invoke the CI step by hand. atBoot as the default for long-lived Node keeps the developer flow ergonomic."
+    }
+  ],
+  "createdAt": "2026-09-06T15:47:00.000Z",
+  "updatedAt": "2026-09-06T15:47:00.000Z"
+}

package/blueprints/persistence-data-postgres/contributions/adrs/adr-2804-persistence-data-postgres-recovery.json

@@ -0,0 +1,25 @@
+{
+  "adrId": "ADR-2804-persistence-data-postgres-recovery",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "accepted",
+  "title": "Two-path recovery: scheduled pg_dump artefact PLUS vendor point-in-time recovery, both required, cadence elicited",
+  "context": "A shipped Postgres project has to survive two failure classes: a corrupted or lost cluster (a managed-Postgres outage, a self-managed disk failure, a bad DBA operation) and a data-integrity incident an operator wants to unwind by minutes or hours (a bug that deleted rows, a bad migration a rollback file cannot invert). pg_dump gives a portable off-cluster artefact; vendor PITR (a managed cluster's window, a self-managed cluster's WAL-archive posture) gives fine-grained restore points. Neither alone covers both failure classes.",
+  "decision": "The shipped recovery model requires both paths: (a) a scheduled pg_dump runner (TAC-2804) writes an artefact to the elicited destination on an elicited cadence, and (b) the deploy target's own point-in-time recovery is enabled with an elicited PITR window (a managed cluster's retention setting; a self-managed cluster's WAL-archive retention). Neither path is optional; a project that answers off to either fails the ADR's apply-time check. A recovery drill (US-27110) periodically primes a fresh Postgres from the artefact and compares row-count and checksum against the source; the drill's cadence is elicited.",
+  "consequences": "The project survives both failure classes: a portable off-cluster artefact for cluster loss and a fine-grained PITR window for data-integrity incidents. Storage cost is two-path (artefact bytes off-cluster plus WAL retention on-cluster); the operator sizes both per RTO/RPO. The drill catches artefact-shape drift (a pg_dump on a new engine version producing a different plain-format shape) before an incident forces a live restore. Standards trace clause: generic enterprise practice.",
+  "alternativesConsidered": [
+    {
+      "name": "pg_dump only",
+      "summary": "Ship pg_dump as the sole recovery path; skip vendor PITR.",
+      "reasonNotChosen": "A pg_dump artefact taken hourly can lose up to 59 minutes of writes; an operator restoring after a bad migration loses everything committed between the last dump and the incident. PITR bounds that loss to the WAL-shipping cadence."
+    },
+    {
+      "name": "PITR only",
+      "summary": "Rely on the deploy target's own PITR window; skip the pg_dump runner.",
+      "reasonNotChosen": "PITR does not survive cluster loss: if the managed cluster is gone, the retention window is gone with it. A portable off-cluster artefact is what carries across cluster loss."
+    }
+  ],
+  "createdAt": "2026-09-06T15:47:00.000Z",
+  "updatedAt": "2026-09-06T15:47:00.000Z"
+}

package/blueprints/persistence-data-postgres/contributions/adrs/adr-2805-persistence-data-postgres-connection-pool-posture.json

@@ -0,0 +1,25 @@
+{
+  "adrId": "ADR-2805-persistence-data-postgres-connection-pool-posture",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "accepted",
+  "title": "Connection-pool posture per deploy target: long-lived pool on Node, request-scoped pool on container, delegated to Hyperdrive on Workers-adjacent (v1.1.0)",
+  "context": "Postgres has real connection cost per open (TCP handshake, TLS negotiation, authentication, role setup). A long-lived Node process wants one pool per process amortising that cost across every request. A request-scoped container platform (a serverless-container target spinning fresh instances per request) cannot hold a long-lived pool because the instance dies at request end; each instance opens a pool for its request budget. A Workers-adjacent target via the round-6 Hyperdrive v1.1.0 adapter delegates the pool entirely to Cloudflare's Hyperdrive-managed pool.",
+  "decision": "The pool posture is elicited per deploy target: longLivedNode (default: long-lived pg.Pool for the process lifetime), requestScopedContainer (a pool sized to the request budget, disposed at request end), or hyperdriveManaged (reserved for the round-6 v1.1.0 adapter). The shipped defaults per posture: longLivedNode pool size 10 with idleTimeoutMillis 30000 and connectionTimeoutMillis 5000 (matching pg's own defaults); requestScopedContainer pool size 2 with idleTimeoutMillis 5000 and connectionTimeoutMillis 3000; hyperdriveManaged inherits Hyperdrive's own pool settings and holds no Node-side pool. Every default is overridable by the operator via elicited pool-config fields at apply time.",
+  "consequences": "The project gets the pool posture appropriate to its deploy target without a code change: a longLivedNode app on Kubernetes and a longLivedNode app on a self-managed VM share the same shipped default; a requestScopedContainer app on a serverless-container platform gets a small per-request pool; a round-6 Workers app inherits Hyperdrive's pool. The pool-posture-smoke probe drives twenty concurrent queries at pool size 5 and asserts no timeout; the probe does not impose a sizing formula so operator overrides are safe. Standards trace clause: generic enterprise practice.",
+  "alternativesConsidered": [
+    {
+      "name": "One pool posture (longLivedNode) for every target",
+      "summary": "Ship the long-lived pool as the only posture; a request-scoped container platform holds the pool for the instance lifetime.",
+      "reasonNotChosen": "A fresh-per-request container that holds a long-lived pool re-pays the connection cost on every instance. Sizing the pool for a request-scoped instance is different from sizing it for a long-lived process; conflating them under one default surprises the operator."
+    },
+    {
+      "name": "Delegate every pool to Hyperdrive from v1.0.0",
+      "summary": "Ship Hyperdrive as the pool manager for every target.",
+      "reasonNotChosen": "Hyperdrive is a Cloudflare-account-bound service; forcing every project to bind to Cloudflare before applying the blueprint conflicts with the local-first posture (round-5 spec ruling 5, Baz decision 8). Round 6 lands Hyperdrive as an elicit for the operator who wants it."
+    }
+  ],
+  "createdAt": "2026-09-06T15:47:00.000Z",
+  "updatedAt": "2026-09-06T15:47:00.000Z"
+}

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

@@ -0,0 +1,56 @@
+/**
+ * Facade round-trip probe.
+ *
+ * Opens the fixture's facade against a running postgres:17-alpine
+ * container, drives a put-and-get through the named domain verbs,
+ * asserts facadeReady fires on the injected event sink and the
+ * round-trip returns the row written.
+ *
+ * Anchors AC-27101-1 (facade opens on boot and facadeReady fires with
+ * the database name).
+ *
+ * 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();
+    // Ensure a clean users table for this probe run
+    const pool = store.getPool();
+    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 facadeReadyFired = events.some((e) => e.event === 'facadeReady');
+    const facadeReadyDbName = facadeReadyFired ? events.find((e) => e.event === 'facadeReady').databaseName : null;
+    results.push({
+      anchorAcId: 'AC-27101-1',
+      verdict: facadeReadyFired && facadeReadyDbName === 'rcf_test' ? 'pass' : 'fail',
+      detail: facadeReadyFired
+        ? `facadeReady fired with databaseName=${facadeReadyDbName}`
+        : 'facadeReady did not fire before first query',
+    });
+    const id = await store.createUser('probe-facade-round-trip', 'facade-round-trip@rcf.test');
+    const row = await store.getUserById(id);
+    const roundTripPass = row && row.id === id && row.name === 'probe-facade-round-trip';
+    results.push({
+      anchorAcId: 'AC-27101-1',
+      verdict: roundTripPass ? 'pass' : 'fail',
+      detail: roundTripPass
+        ? `round-trip put id=${id} and got name=${row.name}`
+        : `round-trip failed: id=${id}, row=${JSON.stringify(row)}`,
+    });
+  } finally {
+    try {
+      await store.getPool().query('TRUNCATE users');
+    } catch { /* ignore */ }
+    await store.close();
+  }
+  return results;
+}

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

@@ -0,0 +1,75 @@
+/**
+ * Migration apply probe.
+ *
+ * Drops any prior schema (users, schema_version) from the fixture's
+ * Postgres, invokes the fixture's migration runner, and asserts every
+ * migration applied inside its own transaction, migrationsApplied fires
+ * with the filename list, and the schema_version bookkeeping table
+ * records three rows.
+ *
+ * Anchors AC-27102-1 (three forward-only .sql migrations apply one file
+ * one transaction; migrationsApplied fires with the filename list).
+ *
+ * Cleans up: leaves the applied schema for downstream probes.
+ */
+
+import { applyAll } from '../../../../packages/rcf-lite/test/fixtures/infra-postgres/src/migrate.mjs';
+import { createStore, connectionUrlFromEnv } from '../../../../packages/rcf-lite/test/fixtures/infra-postgres/src/store.mjs';
+
+async function resetSchema(url) {
+  const store = createStore({ connectionUrl: url });
+  try {
+    await store.ready();
+    const pool = store.getPool();
+    await pool.query('DROP TABLE IF EXISTS users CASCADE');
+    await pool.query('DROP TABLE IF EXISTS schema_version CASCADE');
+  } finally {
+    await store.close();
+  }
+}
+
+export default async function runProbe() {
+  const url = connectionUrlFromEnv();
+  await resetSchema(url);
+  const events = [];
+  const { applied } = await applyAll({
+    connectionUrl: url,
+    onEvent: (e) => events.push(e),
+  });
+  const results = [];
+  const expected = ['001_create_users.sql', '002_add_email_unique.sql', '003_add_created_at.sql'];
+  const listsEqual = applied.length === expected.length
+    && expected.every((f, i) => applied[i] === f);
+  results.push({
+    anchorAcId: 'AC-27102-1',
+    verdict: listsEqual ? 'pass' : 'fail',
+    detail: `applied=${JSON.stringify(applied)} expected=${JSON.stringify(expected)}`,
+  });
+  const migratedEvent = events.find((e) => e.event === 'migrationsApplied');
+  const eventFiredCorrectly = migratedEvent
+    && Array.isArray(migratedEvent.applied)
+    && migratedEvent.applied.length === expected.length;
+  results.push({
+    anchorAcId: 'AC-27102-1',
+    verdict: eventFiredCorrectly ? 'pass' : 'fail',
+    detail: eventFiredCorrectly
+      ? `migrationsApplied fired with applied=${JSON.stringify(migratedEvent.applied)}`
+      : `migrationsApplied event missing or wrong shape; events=${JSON.stringify(events)}`,
+  });
+  // Read schema_version to confirm rows count = 3
+  const store = createStore({ connectionUrl: url });
+  try {
+    await store.ready();
+    const pool = store.getPool();
+    const r = await pool.query('SELECT count(*)::int AS n FROM schema_version');
+    const versionRowsPass = r.rows[0].n === 3;
+    results.push({
+      anchorAcId: 'AC-27102-1',
+      verdict: versionRowsPass ? 'pass' : 'fail',
+      detail: `schema_version rows=${r.rows[0].n} (expected 3, i.e. schema_version advanced to 3)`,
+    });
+  } finally {
+    await store.close();
+  }
+  return results;
+}

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

@@ -0,0 +1,56 @@
+/**
+ * Pool posture smoke probe.
+ *
+ * Opens two facade instances against the same postgres:17-alpine
+ * container each configured at pool size 5, dispatches twenty
+ * concurrent SELECT queries across the two facades, asserts all
+ * twenty return with no timeout inside the shipped
+ * connectionTimeoutMillis budget.
+ *
+ * Anchors AC-27106-1.
+ *
+ * Cleans up: closes both pools.
+ */
+
+import { createStore, connectionUrlFromEnv } from '../../../../packages/rcf-lite/test/fixtures/infra-postgres/src/store.mjs';
+
+export default async function runProbe() {
+  const url = connectionUrlFromEnv();
+  const storeA = createStore({ connectionUrl: url, poolConfig: { max: 5 } });
+  const storeB = createStore({ connectionUrl: url, poolConfig: { max: 5 } });
+  const results = [];
+  try {
+    await Promise.all([storeA.ready(), storeB.ready()]);
+    const started = Date.now();
+    const promises = [];
+    for (let i = 0; i < 10; i++) {
+      promises.push(storeA.getPool().query('SELECT $1::int AS n, pg_sleep(0.05)', [i]));
+      promises.push(storeB.getPool().query('SELECT $1::int AS n, pg_sleep(0.05)', [10 + i]));
+    }
+    const settled = await Promise.allSettled(promises);
+    const elapsed = Date.now() - started;
+    const succeeded = settled.filter((s) => s.status === 'fulfilled').length;
+    const failed = settled.filter((s) => s.status === 'rejected').length;
+    results.push({
+      anchorAcId: 'AC-27106-1',
+      verdict: succeeded === 20 && failed === 0 ? 'pass' : 'fail',
+      detail: `20 concurrent queries dispatched across two pool-size-5 facades; ${succeeded} returned, ${failed} rejected, wall-clock ${elapsed}ms`,
+    });
+    // Observed max concurrent in-use per pool must be <= configured pool size
+    // pg's pg.Pool exposes totalCount / idleCount / waitingCount; peak in-use ~ totalCount - idleCount.
+    const poolA = storeA.getPool();
+    const poolB = storeB.getPool();
+    const maxA = poolA.options && poolA.options.max;
+    const maxB = poolB.options && poolB.options.max;
+    const inUseCap = maxA === 5 && maxB === 5;
+    results.push({
+      anchorAcId: 'AC-27106-1',
+      verdict: inUseCap ? 'pass' : 'fail',
+      detail: `pool.options.max on both facades: A=${maxA}, B=${maxB} (each configured to 5)`,
+    });
+  } finally {
+    await storeA.close();
+    await storeB.close();
+  }
+  return results;
+}

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

@@ -0,0 +1,186 @@
+/**
+ * Prepared-statement scan probe.
+ *
+ * Walks every .js / .mjs / .ts file under the applied fixture's facade
+ * directory (packages/rcf-lite/test/fixtures/infra-postgres/src/) and
+ * asserts every .query(...) call's first argument is a static string
+ * literal (single or double-quoted string, or a backtick template
+ * literal with no ${...} expressions).
+ *
+ * Anchors AC-27103-1 (prepared-statement discipline).
+ *
+ * The scan is a hand-rolled tokenising walker, not a full AST parser:
+ * this avoids adding acorn or babel as a rcf-lite dependency (round-5
+ * spec section 5.5, brief section 4). The tokeniser handles strings,
+ * template literals, comments, and nested parentheses. Runs
+ * build-observable; the facade-round-trip probe carries the runtime
+ * observable that the surface actually works.
+ */
+
+import { readdir, readFile } from 'node:fs/promises';
+import { join, resolve, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const FACADE_DIR = resolve(HERE, '..', '..', '..', '..', 'packages/rcf-lite/test/fixtures/infra-postgres/src');
+
+async function walk(dir) {
+  const entries = await readdir(dir, { withFileTypes: true });
+  const files = [];
+  for (const e of entries) {
+    if (e.isDirectory()) {
+      files.push(...(await walk(join(dir, e.name))));
+    } else if (e.isFile() && /\.(mjs|js|ts)$/.test(e.name)) {
+      files.push(join(dir, e.name));
+    }
+  }
+  return files;
+}
+
+/**
+ * Strip block and line comments from source. Simple stripper: preserves
+ * string bodies (in ' " and `) so `/* not a comment *\/` inside a string
+ * survives. Good enough for the discipline scan.
+ */
+function stripCommentsPreserveStrings(src) {
+  const out = [];
+  let i = 0;
+  while (i < src.length) {
+    const c = src[i];
+    const c2 = src[i + 1];
+    if (c === '/' && c2 === '/') {
+      while (i < src.length && src[i] !== '\n') i++;
+      out.push(' ');
+      continue;
+    }
+    if (c === '/' && c2 === '*') {
+      i += 2;
+      while (i < src.length && !(src[i] === '*' && src[i + 1] === '/')) i++;
+      i += 2;
+      out.push(' ');
+      continue;
+    }
+    if (c === "'" || c === '"') {
+      const q = c;
+      out.push(c);
+      i++;
+      while (i < src.length && src[i] !== q) {
+        if (src[i] === '\\' && i + 1 < src.length) {
+          out.push(src[i], src[i + 1]);
+          i += 2;
+          continue;
+        }
+        out.push(src[i]);
+        i++;
+      }
+      if (i < src.length) {
+        out.push(src[i]);
+        i++;
+      }
+      continue;
+    }
+    if (c === '`') {
+      out.push(c);
+      i++;
+      while (i < src.length && src[i] !== '`') {
+        if (src[i] === '\\' && i + 1 < src.length) {
+          out.push(src[i], src[i + 1]);
+          i += 2;
+          continue;
+        }
+        if (src[i] === '$' && src[i + 1] === '{') {
+          out.push(src[i], src[i + 1]);
+          i += 2;
+          let depth = 1;
+          while (i < src.length && depth > 0) {
+            if (src[i] === '{') depth++;
+            else if (src[i] === '}') depth--;
+            out.push(src[i]);
+            i++;
+          }
+          continue;
+        }
+        out.push(src[i]);
+        i++;
+      }
+      if (i < src.length) {
+        out.push(src[i]);
+        i++;
+      }
+      continue;
+    }
+    out.push(c);
+    i++;
+  }
+  return out.join('');
+}
+
+/**
+ * Find every .query(...) call site and classify its first argument.
+ * Returns [{ line, firstArgKind }] where firstArgKind is 'stringLiteral',
+ * 'templateStatic', 'templateWithExpression', 'stringConcat', or
+ * 'other'.
+ */
+function scanQueryCalls(src) {
+  const cleaned = stripCommentsPreserveStrings(src);
+  const calls = [];
+  const rx = /\.query\s*\(/g;
+  let m;
+  while ((m = rx.exec(cleaned)) !== null) {
+    const start = m.index + m[0].length;
+    const line = cleaned.slice(0, start).split('\n').length;
+    // Find the first argument by scanning forward, respecting parens/braces/strings
+    let i = start;
+    while (i < cleaned.length && /\s/.test(cleaned[i])) i++;
+    const first = cleaned[i];
+    if (first === "'" || first === '"') {
+      calls.push({ line, firstArgKind: 'stringLiteral', preview: cleaned.slice(i, i + 60) });
+    } else if (first === '`') {
+      // Check if backtick body has ${...}
+      let j = i + 1;
+      let hasExpr = false;
+      while (j < cleaned.length && cleaned[j] !== '`') {
+        if (cleaned[j] === '$' && cleaned[j + 1] === '{') { hasExpr = true; break; }
+        if (cleaned[j] === '\\') j++;
+        j++;
+      }
+      calls.push({ line, firstArgKind: hasExpr ? 'templateWithExpression' : 'templateStatic', preview: cleaned.slice(i, i + 60) });
+    } else if (/[A-Za-z_$]/.test(first)) {
+      // Identifier or expression: could be a variable holding a static string, but that defeats the scan discipline
+      calls.push({ line, firstArgKind: 'other', preview: cleaned.slice(i, i + 60) });
+    } else {
+      calls.push({ line, firstArgKind: 'other', preview: cleaned.slice(i, i + 60) });
+    }
+  }
+  return calls;
+}
+
+export default async function runProbe() {
+  const files = await walk(FACADE_DIR);
+  const results = [];
+  const violations = [];
+  let totalCalls = 0;
+  for (const file of files) {
+    const src = await readFile(file, 'utf8');
+    const calls = scanQueryCalls(src);
+    for (const c of calls) {
+      totalCalls++;
+      if (c.firstArgKind === 'templateWithExpression' || c.firstArgKind === 'stringConcat') {
+        violations.push({ file, ...c });
+      }
+    }
+  }
+  results.push({
+    anchorAcId: 'AC-27103-1',
+    verdict: violations.length === 0 ? 'pass' : 'fail',
+    detail: violations.length === 0
+      ? `${totalCalls} .query call sites scanned across ${files.length} facade file(s); every first argument is a static string literal or a template with no expressions`
+      : `${violations.length} violation(s): ${JSON.stringify(violations)}`,
+  });
+  results.push({
+    anchorAcId: 'AC-27103-1',
+    verdict: totalCalls >= 5 ? 'pass' : 'warn',
+    detail: `total .query call sites scanned: ${totalCalls} (minimum 5 to consider the facade meaningfully covered by this scan)`,
+  });
+  return results;
+}

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);
+  }
+}