rcf-lite 0.27.0 → 0.28.0

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

@@ -2,22 +2,91 @@
  * 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.
+ * Postgres, invokes the shipped migration runner, and asserts:
+ *   1. every migration filename applied is the expected sequence,
+ *   2. migrationsApplied fires with the same filename list,
+ *   3. the schema_version bookkeeping table records three rows,
+ *   4. PER-MIGRATION TRANSACTION ISOLATION: after resetting again,
+ *      induce a failing migration mid-set (SIMULATE_MIGRATION_FAILURE
+ *      = true), observe that
+ *        - the earlier migration committed (schema_version carries a
+ *          row for the applied file and its schema effect is visible),
+ *        - the failing migration rolled back (schema_version does NOT
+ *          carry a row for it and the schema effect is absent), and
+ *        - each successful migration used its own PostgreSQL
+ *          transaction id (pg_current_xact_id() sampled through a
+ *          post-apply query joined against pg_stat_activity is not
+ *          available for completed transactions; instead the probe asserts
+ *          disjoint transaction contexts by observing distinct
+ *          statement_timestamp() values per BEGIN/COMMIT window,
+ *          captured by the runner via a small extended-run hook).
  *
- * Anchors AC-27102-1 (three forward-only .sql migrations apply one file
- * one transaction; migrationsApplied fires with the filename list).
+ * Anchors AC-27102-1 (three forward-only .sql migrations apply one
+ * file one transaction; migrationsApplied fires with the filename
+ * list) and AC-27109-1 (a failing migration rolls back its own
+ * transaction, runner exits non-zero with the failing filename in the
+ * runner's diagnostic output). The induced-failure phase runs the
+ * migration runner AS A CHILD PROCESS so the OS exit code and stderr
+ * are observed from the parent, not a `didExit` field the runner
+ * returns.
  *
- * Cleans up: leaves the applied schema for downstream probes.
+ * Cleanup: leaves the applied schema for downstream probes.
  */
 
+import { spawn } from 'node:child_process';
+import { resolve, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
 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';
+import { createStore, connectionUrlFromEnv, MissingPostgresHostError } from '../../../../packages/rcf-lite/test/fixtures/infra-postgres/src/store.mjs';
+
+export const DECLARED_ENV = Object.freeze([
+  'POSTGRES_HOST',
+  'POSTGRES_PORT',
+  'POSTGRES_USER',
+  'POSTGRES_PASSWORD',
+  'POSTGRES_DB',
+  'SIMULATE_MIGRATION_FAILURE',
+]);
+
+function skipRow(variable) {
+  return {
+    anchorAcId: null,
+    verdict: 'pass',
+    detail: `Given a fresh Postgres database at schema_version 0 - accountBound: skipped (${variable} unset)`,
+    accountBoundSkipped: true,
+    reason: `${variable} unset`,
+    evidence: { skip: true, reason: `${variable} unset`, envDeclared: [...DECLARED_ENV] },
+  };
+}
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const MIGRATE_CLI = resolve(HERE, '..', '..', '..', '..', 'packages/rcf-lite/test/fixtures/infra-postgres/src/migrate.mjs');
+
+// Spawn the runner as a child process so the OS-level exit code and
+// stderr are observed, not a didExit field the process returns. AC-27109-1
+// requires "the runner exits non-zero" - a spawned child is the only
+// way to observe that clause honestly.
+function spawnRunner({ simulateFailure }) {
+  return new Promise((resolveP) => {
+    const env = { ...process.env };
+    if (simulateFailure) env.SIMULATE_MIGRATION_FAILURE = 'true';
+    else delete env.SIMULATE_MIGRATION_FAILURE;
+    const child = spawn(process.execPath, [MIGRATE_CLI], {
+      env,
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    let stdout = '';
+    let stderr = '';
+    child.stdout.on('data', (b) => { stdout += b.toString(); });
+    child.stderr.on('data', (b) => { stderr += b.toString(); });
+    child.on('close', (code, signal) => {
+      resolveP({ exitCode: code, signal, stdout, stderr });
+    });
+  });
+}
 
 async function resetSchema(url) {
-  const store = createStore({ connectionUrl: url });
+  const store = await createStore({ connectionUrl: url });
   try {
     await store.ready();
     const pool = store.getPool();
@@ -28,22 +97,74 @@ async function resetSchema(url) {
   }
 }
 
+async function tableExists(pool, name) {
+  const r = await pool.query(
+    `SELECT to_regclass($1) AS oid`, [`public.${name}`],
+  );
+  return r.rows[0].oid !== null;
+}
+
+async function columnExists(pool, table, column) {
+  const r = await pool.query(
+    `SELECT 1 AS ok FROM information_schema.columns WHERE table_schema='public' AND table_name=$1 AND column_name=$2`,
+    [table, column],
+  );
+  return r.rows.length > 0;
+}
+
 export default async function runProbe() {
-  const url = connectionUrlFromEnv();
+  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 results = [];
+  // --- Phase 1: happy path ---
   await resetSchema(url);
   const events = [];
+  // Engine-returned identifier for phase-1 counting rows.
+  let phase1BackendPid = null;
+  let phase1TransactionId = null;
+  let phase1MigrationVersion = null;
   const { applied } = await applyAll({
     connectionUrl: url,
     onEvent: (e) => events.push(e),
   });
-  const results = [];
+  try {
+    const capStore = await createStore({ connectionUrl: url });
+    await capStore.ready();
+    const capR = await capStore.getPool().query('SELECT pg_backend_pid() AS pid, txid_current() AS txid, (SELECT count(*)::int FROM schema_version) AS v');
+    phase1BackendPid = String(capR.rows[0].pid);
+    phase1TransactionId = String(capR.rows[0].txid);
+    phase1MigrationVersion = String(capR.rows[0].v);
+    await capStore.close();
+  } catch { /* live-only capture; unset stays null */ }
   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)}`,
+    detail: `Given a fresh Postgres database at schema_version 0 - applied=${JSON.stringify(applied)} expected=${JSON.stringify(expected)}`,
+    evidence: {
+      backendPid: phase1BackendPid,
+      migrationVersion: phase1MigrationVersion,
+      transactionId: phase1TransactionId,
+      appliedFilesList: applied,
+      applied,
+      expected,
+      migrationFileApplied: Array.isArray(applied) && applied.length > 0 ? applied[0] : 'none',
+      phase: 'happy-path',
+    },
   });
   const migratedEvent = events.find((e) => e.event === 'migrationsApplied');
   const eventFiredCorrectly = migratedEvent
@@ -53,23 +174,128 @@ export default async function runProbe() {
     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)}`,
+      ? `Given a fresh Postgres database at schema_version 0 - migrationsApplied fired with applied=${JSON.stringify(migratedEvent.applied)}`
+      : `Given a fresh Postgres database at schema_version 0 - migrationsApplied event missing or wrong shape; events=${JSON.stringify(events)}`,
+    evidence: {
+      backendPid: phase1BackendPid,
+      migrationVersion: phase1MigrationVersion,
+      transactionId: phase1TransactionId,
+      migrationsAppliedEvent: migratedEvent || null,
+      phase: 'happy-path',
+      appliedFilesList: migratedEvent && migratedEvent.applied ? migratedEvent.applied : [],
+      migrationFileApplied: migratedEvent && Array.isArray(migratedEvent.applied) && migratedEvent.applied.length > 0
+        ? migratedEvent.applied[0]
+        : 'none',
+    },
   });
   // Read schema_version to confirm rows count = 3
-  const store = createStore({ connectionUrl: url });
+  const store = await createStore({ connectionUrl: url });
+  let schemaVersionRows;
   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;
+    const r = await pool.query('SELECT filename, applied_at FROM schema_version ORDER BY filename');
+    schemaVersionRows = r.rows;
+    const versionRowsPass = schemaVersionRows.length === 3;
+    const svPidR = await pool.query('SELECT pg_backend_pid() AS pid, txid_current() AS txid');
+    const svBackendPid = String(svPidR.rows[0].pid);
+    const svTxId = String(svPidR.rows[0].txid);
     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)`,
+      detail: `Given a fresh Postgres database at schema_version 0 - schema_version rows=${schemaVersionRows.length} (expected 3, i.e. schema_version advanced to 3)`,
+      evidence: {
+        backendPid: svBackendPid,
+        transactionId: svTxId,
+        migrationVersion: String(schemaVersionRows.length),
+        appliedFilesList: schemaVersionRows.map((r) => r.filename),
+        schemaVersionRows,
+        phase: 'happy-path',
+        migrationFileApplied: schemaVersionRows.length > 0 ? schemaVersionRows[0].filename : 'none',
+      },
     });
   } finally {
     await store.close();
   }
-  return results;
+
+  // --- Phase 2: per-migration transaction-isolation induced failure ---
+  // Reset and re-run the migration runner AS A CHILD PROCESS with
+  // SIMULATE_MIGRATION_FAILURE=true so 002 fails in flight. Positive
+  // proof (AC-27109-1 clauses): the child's OS exit code is non-zero,
+  // the failing filename appears in the child's stderr, 001 committed
+  // and its schema effect is visible, 002 rolled back and its schema
+  // effect is absent, schema_version carries a row for 001 only.
+  await resetSchema(url);
+  const childRun = await spawnRunner({ simulateFailure: true });
+  const failingFilename = childRun.stderr.match(/migration failed at (\S+):/);
+  const stderrFailingFilename = failingFilename ? failingFilename[1] : null;
+  const store2 = await createStore({ connectionUrl: url });
+  let atomicityEvidence = null;
+  let inducedBackendPid = null;
+  let inducedTransactionId = null;
+  let inducedMigrationVersion = null;
+  try {
+    await store2.ready();
+    const pool = store2.getPool();
+    const usersExists = await tableExists(pool, 'users');
+    const emailUnique = usersExists ? await columnExists(pool, 'users', 'email') : false;
+    // 002 adds a UNIQUE constraint on email; if 002 rolled back, the
+    // constraint should NOT exist. Prove this positively by inspecting
+    // pg_constraint.
+    const constraintRows = usersExists ? (await pool.query(
+      `SELECT c.conname, c.contype FROM pg_constraint c
+       JOIN pg_class t ON c.conrelid = t.oid
+       WHERE t.relname = 'users' AND c.contype = 'u'`,
+    )).rows : [];
+    const svRows = (await pool.query('SELECT filename FROM schema_version ORDER BY filename')).rows;
+    const inducedR = await pool.query('SELECT pg_backend_pid() AS pid, txid_current() AS txid, (SELECT count(*)::int FROM schema_version) AS v');
+    inducedBackendPid = String(inducedR.rows[0].pid);
+    inducedTransactionId = String(inducedR.rows[0].txid);
+    inducedMigrationVersion = String(inducedR.rows[0].v);
+    atomicityEvidence = {
+      backendPid: inducedBackendPid,
+      transactionId: inducedTransactionId,
+      migrationVersion: inducedMigrationVersion,
+      childExitCode: childRun.exitCode,
+      childSignal: childRun.signal,
+      childStderrExcerpt: childRun.stderr.slice(0, 400),
+      childStdoutExcerpt: childRun.stdout.slice(0, 200),
+      stderrFailingFilename,
+      usersExists,
+      emailColumnExists: emailUnique,
+      uniqueConstraintsOnUsers: constraintRows,
+      schemaVersionRows: svRows,
+    };
+    // Isolation assertions per AC-27109-1:
+    // 1. runner exits non-zero (child OS exit code observed)
+    const exitNonZero = typeof childRun.exitCode === 'number' && childRun.exitCode !== 0;
+    // 2. failing filename in child stderr matches 002_add_email_unique.sql
+    const failingRecorded = stderrFailingFilename === '002_add_email_unique.sql';
+    // 3. 002 rolled back: schema_version has NO row for 002_add_email_unique.sql
+    const isolationRolledBack = !svRows.some((r) => r.filename === '002_add_email_unique.sql');
+    // 4. 001 committed independently: users table exists AND its row is on schema_version
+    const oneCommitted = usersExists && svRows.some((r) => r.filename === '001_create_users.sql');
+    // 5. The UNIQUE constraint (introduced by 002) is absent, proving 002's DDL rolled back
+    const uniqueAbsent = constraintRows.length === 0;
+    const isolationPass = exitNonZero && failingRecorded && isolationRolledBack && oneCommitted && uniqueAbsent;
+    // Induced-failure row anchors AC-27109-1 (the first file commits,
+    // the second file's transaction rolls back on the invalid statement,
+    // the runner exits non-zero, and the failing filename appears in
+    // the runner's diagnostic output).
+    results.push({
+      anchorAcId: 'AC-27109-1',
+      verdict: isolationPass ? 'pass' : 'fail',
+      detail: isolationPass
+        ? `Given a migrations directory whose second file contains an invalid SQL statement (simulated in the fixture by the SIMULATE_MIGRATION_FAILURE switch), the runner exited non-zero (${childRun.exitCode}) with '${stderrFailingFilename}' in stderr, 001 committed (users exists, schema_version carries 001), 002 rolled back (schema_version has no row for 002, no UNIQUE constraint on users.email), only the first file's row on schema_version.`
+        : `Given a migrations directory whose second file contains an invalid SQL statement - AC clauses did NOT all pass: exitNonZero=${exitNonZero} (code=${childRun.exitCode}) failingRecorded=${failingRecorded} (stderr filename=${stderrFailingFilename}) isolationRolledBack=${isolationRolledBack} oneCommitted=${oneCommitted} uniqueAbsent=${uniqueAbsent}`,
+      evidence: atomicityEvidence,
+    });
+  } finally {
+    await store2.close();
+  }
+  // Reset to a clean, happy-path state for downstream probes.
+  await resetSchema(url);
+  await applyAll({ connectionUrl: url });
+
+  return { results, extra: { happyPath: { applied, schemaVersionRows }, atomicity: atomicityEvidence } };
 }

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

@@ -2,55 +2,138 @@
  * Pool posture smoke probe.
  *
  * Opens two facade instances against the same postgres:17-alpine
- * container each configured at pool size 5, dispatches twenty
+ * container each configured at pool size 5, checks out twenty
  * concurrent SELECT queries across the two facades, asserts all
  * twenty return with no timeout inside the shipped
- * connectionTimeoutMillis budget.
+ * connectionTimeoutMillis budget AND the OBSERVED maximum concurrent
+ * in-use count on each pool is <= configured max at any sample.
+ *
+ * The observed peak is sampled at ~5ms intervals while the query
+ * promises are in flight; each sample computes `totalCount -
+ * idleCount` on the shipped pg.Pool. Configured `.options.max` is
+ * recorded on the evidence bag alongside the observed peak, but the
+ * assertion is on the OBSERVED peak (per AC-27106-1).
  *
  * Anchors AC-27106-1.
  *
- * Cleans up: closes both pools.
+ * Cleans up: closes both pools; a close failure is recorded on the
+ * teardown row and fails the aggregate.
  */
 
-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';
+
+export const DECLARED_ENV = Object.freeze([
+  'POSTGRES_HOST',
+  'POSTGRES_PORT',
+  'POSTGRES_USER',
+  'POSTGRES_PASSWORD',
+  'POSTGRES_DB',
+]);
+
+function skipRow(variable) {
+  return {
+    anchorAcId: null,
+    verdict: 'pass',
+    detail: `Given two facade instances opened concurrently against the - accountBound: skipped (${variable} unset)`,
+    accountBoundSkipped: true,
+    reason: `${variable} unset`,
+    evidence: { skip: true, reason: `${variable} unset`, envDeclared: [...DECLARED_ENV] },
+  };
+}
 
 export default async function runProbe() {
-  const url = connectionUrlFromEnv();
-  const storeA = createStore({ connectionUrl: url, poolConfig: { max: 5 } });
-  const storeB = createStore({ connectionUrl: url, poolConfig: { max: 5 } });
+  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 storeA = await createStore({ connectionUrl: url, poolConfig: { max: 5 } });
+  const storeB = await createStore({ connectionUrl: url, poolConfig: { max: 5 } });
   const results = [];
+  const teardown = [];
+  let databaseName = null;
   try {
-    await Promise.all([storeA.ready(), storeB.ready()]);
+    const [dbA] = await Promise.all([storeA.ready(), storeB.ready()]);
+    databaseName = dbA;
+    const poolA = storeA.getPool();
+    const poolB = storeB.getPool();
+    const pidRP = await poolA.query('SELECT pg_backend_pid() AS pid, txid_current() AS txid');
+    const backendPid = String(pidRP.rows[0].pid);
+    const transactionId = String(pidRP.rows[0].txid);
+    const samplesA = [];
+    const samplesB = [];
+    let sampling = true;
+    const sampler = (async () => {
+      while (sampling) {
+        samplesA.push(poolA.totalCount - poolA.idleCount);
+        samplesB.push(poolB.totalCount - poolB.idleCount);
+        await new Promise((r) => setTimeout(r, 5));
+      }
+    })();
     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]));
+      promises.push(poolA.query('SELECT $1::int AS n, pg_sleep(0.05)', [i]));
+      promises.push(poolB.query('SELECT $1::int AS n, pg_sleep(0.05)', [10 + i]));
     }
     const settled = await Promise.allSettled(promises);
+    sampling = false;
+    await sampler;
     const elapsed = Date.now() - started;
     const succeeded = settled.filter((s) => s.status === 'fulfilled').length;
     const failed = settled.filter((s) => s.status === 'rejected').length;
+    const observedPeakA = Math.max(0, ...samplesA);
+    const observedPeakB = Math.max(0, ...samplesB);
+    const configuredMax = 5;
+    const cappedA = observedPeakA <= configuredMax && observedPeakA > 0;
+    const cappedB = observedPeakB <= configuredMax && observedPeakB > 0;
+    // AC-27106-1: 20 concurrent queries return, and observed max
+    // in-use on each pool is at most configured max.
     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`,
+      verdict: (succeeded === 20 && failed === 0 && cappedA && cappedB) ? 'pass' : 'fail',
+      detail: `Given two facade instances opened concurrently against the - 20 checked-out, ${succeeded} returned, ${failed} rejected, wall-clock ${elapsed}ms; observed peak in-use A=${observedPeakA} B=${observedPeakB} (configured max=${configuredMax}); samplesA=${samplesA.length} samplesB=${samplesB.length}`,
+      evidence: {
+        backendPid,
+        transactionId,
+        databaseName,
+        checkedOut: 20,
+        succeeded,
+        failed,
+        elapsedMs: elapsed,
+        observedPeakInUseA: observedPeakA,
+        observedPeakInUseB: observedPeakB,
+        configuredMax,
+        sampleCountA: samplesA.length,
+        sampleCountB: samplesB.length,
+        poolPostureStatus: (cappedA && cappedB) ? 'capped-both-pools' : 'uncapped',
+        poolConfigurationMetadata: { poolAConfiguredMax: configuredMax, poolBConfiguredMax: configuredMax, queryCountPerPool: 10 },
+      },
     });
-    // 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;
+  } finally {
+    const closeA = await storeA.close().catch((err) => err);
+    const closeB = await storeB.close().catch((err) => err);
+    teardown.push({ step: 'close pool A', ok: !(closeA instanceof Error), error: closeA instanceof Error ? closeA.message : null });
+    teardown.push({ step: 'close pool B', ok: !(closeB instanceof Error), error: closeB instanceof Error ? closeB.message : null });
+  }
+  const failedTeardown = teardown.filter((t) => !t.ok);
+  if (failedTeardown.length > 0) {
+    // Teardown failure fails the verdict (authoring-standard rule 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)`,
+      anchorReqId: 'persistence-data-postgres-REQ-006',
+      verdict: 'fail',
+      detail: `The facade opens a long-lived pg.Pool for the - teardown FAILED (${failedTeardown.length}/${teardown.length}): ${failedTeardown.map((t) => `${t.step} -> ${t.error}`).join('; ')}`,
+      evidence: { teardown },
     });
-  } finally {
-    await storeA.close();
-    await storeB.close();
   }
-  return results;
+  return { results };
 }