pgserve 2.6.0 → 2.6.4

package/src/cli-install.cjs

@@ -24,9 +24,131 @@
 const { spawnSync, execFileSync } = require('node:child_process');
 const crypto = require('node:crypto');
 const fs = require('node:fs');
+const net = require('node:net');
 const os = require('node:os');
 const path = require('node:path');
 
+// pgserve v2.6.1 — `pgserve install --help` should print usage + exit 0,
+// not run the install (B2 HIGH from QA-RECIPE-B2.md). Single source of
+// truth for the help text so the autopg + pgserve bin invocations show
+// the same surface (Decision #7 of finalize wish).
+const INSTALL_USAGE = `Usage:
+  pgserve install [options]
+  autopg install [options]
+
+Register pgserve under pm2 (Tier A supervisor) with hardened defaults.
+
+Options:
+  --port <N>            TCP port for postgres (default: 5432)
+  --data <path>         Data directory (default: ~/.autopg/data)
+  --socket-dir <path>   Unix socket directory (default: $XDG_RUNTIME_DIR/pgserve)
+  --ui-port <N>         Port for the autopg UI process (default: 8433)
+  --ui-host <host>      Bind host for the UI (default: 127.0.0.1)
+  --no-ui               Skip the autopg-ui pm2 process (headless / CI)
+  --no-pm2              Skip pm2 registration entirely (Tier B / external supervisor)
+  --help, -h            Show this help and exit
+
+Idempotent: re-running with the same args is a no-op when the existing
+admin.json + pm2 state already matches.
+
+See \`pgserve --help\` for the full verb list.
+`;
+
+function printInstallUsage(stream = process.stdout) {
+  stream.write(INSTALL_USAGE);
+}
+
+// pgserve v2.6.1 — `pgserve install` on a host where the chosen port is
+// already in use must fail BEFORE pm2 / admin.json / data-dir side
+// effects (B3 HIGH from QA-RECIPE-B3.md). Pre-flight bind-test on the
+// canonical loopback the postmaster will use; on EADDRINUSE we fail
+// fast with an operator-readable hint pointing at `--port`.
+//
+// Synchronous wrapper around net.createServer().listen() — uses
+// child_process.spawnSync via a self-bind-then-close so the install
+// flow stays synchronous. Returns null on success; throws an Error
+// with `code='EADDRINUSE'` on collision.
+async function assertPortAvailable(port, host = '127.0.0.1') {
+  // Test-only escape hatch. Production never sets this env var. Used by
+  // tests that assert on `port: 5432` literal output where the host
+  // running the test happens to have 5432 bound (dev workstations
+  // running a real pgserve). The port-pre-flight contract itself is
+  // covered end-to-end by the B3-collision test which intentionally
+  // does NOT set this env var so the pre-flight fires.
+  if (process.env.PGSERVE_TEST_SKIP_PORT_PREFLIGHT === '1') return null;
+
+  // Layer 1: connect-probe BOTH IPv4 (127.0.0.1) and IPv6 (::1).
+  // Postgres binds both loopback families on startup; any listener on
+  // either is an EADDRINUSE for the postmaster. A pure listen()-bind
+  // probe can miss this when the conflicting service was started with
+  // SO_REUSEADDR or only-one-family, so connect() is the primary check.
+  // If connect() succeeds → something is listening → port is busy.
+  for (const probeHost of [host, '::1']) {
+    const busy = await probePortListening(port, probeHost);
+    if (busy) {
+      const e = new Error(
+        `pgserve install: port ${port} is already in use on ${probeHost} (something is listening).\n` +
+        `Specify a different port with \`pgserve install --port <free>\`,\n` +
+        `or stop the process bound to ${port} first and retry.`,
+      );
+      e.code = 'EADDRINUSE';
+      throw e;
+    }
+  }
+
+  // Layer 2: bind-probe to confirm we ourselves can bind without
+  // SO_REUSEADDR conflicts. Catches the case where another process
+  // bound the same port with SO_REUSEADDR but isn't currently listening
+  // (rare but possible for transitional services).
+  return new Promise((resolve, reject) => {
+    const server = net.createServer();
+    server.once('error', (err) => {
+      if (err.code === 'EADDRINUSE') {
+        const e = new Error(
+          `pgserve install: port ${port} is already in use on ${host} (EADDRINUSE).\n` +
+          `Specify a different port with \`pgserve install --port <free>\`,\n` +
+          `or stop the process bound to ${port} first and retry.`,
+        );
+        e.code = 'EADDRINUSE';
+        reject(e);
+        return;
+      }
+      // Non-EADDRINUSE errors (e.g. EACCES on privileged ports) — fail
+      // closed with the underlying message; no install side effects yet.
+      reject(err);
+    });
+    server.once('listening', () => {
+      server.close(() => resolve(null));
+    });
+    server.listen(port, host);
+  });
+}
+
+// Promise that resolves true when something is accepting connections at
+// host:port (port is busy), false on ECONNREFUSED (port is free), and
+// rejects on any other error so callers can fail closed.
+function probePortListening(port, host, timeoutMs = 500) {
+  return new Promise((resolve, reject) => {
+    const socket = new net.Socket();
+    let settled = false;
+    const finish = (value, err) => {
+      if (settled) return;
+      settled = true;
+      try { socket.destroy(); } catch { /* best-effort */ }
+      if (err) reject(err); else resolve(value);
+    };
+    socket.setTimeout(timeoutMs);
+    socket.once('connect', () => finish(true));
+    socket.once('timeout', () => finish(false)); // treat slow/no-response as free
+    socket.once('error', (err) => {
+      if (err.code === 'ECONNREFUSED') return finish(false);
+      if (err.code === 'EHOSTUNREACH' || err.code === 'EADDRNOTAVAIL') return finish(false); // IPv6 not configured, etc.
+      finish(false, err);
+    });
+    socket.connect(port, host);
+  });
+}
+
 // pgserve singleton (v2.4): the cohort-shared admin-json + socket-dir
 // helpers live in `src/lib/*.js` as ESM modules (project convention: new
 // modules ship as .js / ESM). cli-install.cjs runs under node — which
@@ -693,6 +815,13 @@ function cmdAuthDispatch(args) {
  * wrapper before this module is required (avoids re-resolving here).
  */
 async function cmdInstall(args, ctx) {
+  // B2 (v2.6.1): `--help` / `-h` MUST short-circuit before any side
+  // effects (no pm2 spawn, no admin.json write, no data-dir create).
+  if (args.includes('--help') || args.includes('-h')) {
+    printInstallUsage();
+    process.exit(0);
+  }
+
   const { adminJson, socketDirMod, blockedVersions } = await loadCohortModules();
 
   // pgserve singleton (v2.4) — `pgserve-singleton-no-proxy` wish, Group 5.
@@ -732,6 +861,40 @@ async function cmdInstall(args, ctx) {
   }
 
   const port = parsePort(args) ?? readConfig()?.port ?? DEFAULT_PORT;
+
+  // B3 (v2.6.1): pre-flight bind-test the chosen port BEFORE creating
+  // pm2 entries / admin.json / data dir. Without this, an operator on
+  // a host where 5432 is already occupied gets pm2 reporting `online`
+  // while the postmaster crashes silently — divergence between
+  // supervisor state and data-plane state. Fail fast with a clear hint.
+  try {
+    await assertPortAvailable(port);
+  } catch (err) {
+    if (err.code === 'EADDRINUSE') {
+      process.stderr.write(`${err.message}\n`);
+      // CV103-2 (v2.6.2): drop the synchronous `process.exit(1)` here.
+      // QA's 9-variant repro on v2.6.1 isolated a stdio-pipe race:
+      // when stdout is piped (e.g. `pgserve install | cat`) but
+      // stderr is inherited, `process.exit(1)` runs Node's shutdown
+      // sequence faster than the libuv stderr buffer can flush, and
+      // Node has been observed to terminate with exit code 0 instead
+      // of 1. Node's own docs flag this:
+      //
+      //   process.exit() will force the process to exit as quickly as
+      //   possible … including I/O operations to process.stdout and
+      //   process.stderr.
+      //   (https://nodejs.org/api/process.html#processexitcode_1)
+      //
+      // Recommended pattern: set process.exitCode and let Node exit
+      // gracefully on its own once the event loop drains. We also
+      // throw so the wrapper's rejection handler can suppress its
+      // duplicate stderr write — see bin/pgserve-wrapper.cjs.
+      process.exitCode = 1;
+      throw err;
+    }
+    throw err;
+  }
+
   const dataDir = parseDataDir(args) ?? readConfig()?.dataDir ?? getDataDir();
 
   // Set up the canonical socket directory before pm2 launches the
@@ -1145,6 +1308,13 @@ function dispatch(subcommand, args, ctx) {
       // idempotency-driven serialization (see provision.js header for
       // why no advisory lock). Pure node + psql shellout.
       return import('./commands/provision.js').then((mod) => mod.runProvision(args));
+    case 'create-app':
+      // autopg-distribution-cutover-finalize (v2.6) — wish Group 3.
+      // Registers a consumer slug + writes admin.json/manifest.json,
+      // freezing TRUSTED_IDENTITIES into autopg_meta.locked_roots at
+      // create time. Idempotent: re-runs touch last_updated only and
+      // preserve the original locked_roots snapshot (BRIEF v5 A6).
+      return import('./commands/create-app.js').then((mod) => mod.runCreateApp(args));
     default:
       throw new Error(`pgserve: dispatch called with unknown subcommand "${subcommand}"`);
   }
@@ -1153,6 +1323,11 @@ function dispatch(subcommand, args, ctx) {
 module.exports = {
   // Public API for the wrapper.
   dispatch,
+  // B2 + B3: surfaced so unit tests can drive helpers without the
+  // full install side-effect chain.
+  printInstallUsage,
+  assertPortAvailable,
+  INSTALL_USAGE,
   // Auth surface used by cli-ui.cjs.
   verifyAdminPassword,
   getAdminFilePath,

package/src/commands/create-app.js

@@ -0,0 +1,387 @@
+/**
+ * `pgserve create-app <slug>` — autopg-distribution-cutover-finalize G3 verb.
+ *
+ * Registers a consumer app with pgserve:
+ *   1. Bootstraps the `public.autopg_meta` table (idempotent IF NOT EXISTS).
+ *   2. INSERTs a row keyed by sanitized slug, freezing the current
+ *      `TRUSTED_IDENTITIES` snapshot into `locked_roots` JSONB at the
+ *      moment of creation (the LOCK).
+ *   3. Writes the per-consumer cache pair to disk:
+ *        ~/.autopg/<slug>/admin.json      (mode 0600)
+ *        ~/.autopg/<slug>/manifest.json   (mode 0600)
+ *      under a 0700 directory.
+ *
+ * Idempotency contract (BRIEF v5 A6):
+ *   On re-run with the same slug, the verb touches `last_updated` only.
+ *   It does NOT re-lock `locked_roots` to the current TRUSTED_IDENTITIES
+ *   — the original snapshot from first-create is preserved. This is what
+ *   makes the upgrade-after-trust-rotation invariant pass: an existing
+ *   slug's verifier continues to use its frozen lock even after operators
+ *   mutate the live trust list via `pgserve trust add` / `remove`.
+ *
+ * Composes:
+ *   - src/schema/autopg-meta.js          → bootstrapAutopgMeta + columns
+ *   - src/admin/admin-bootstrap.js       → bootstrapConsumerAdmin
+ *   - src/cosign/trust-list.js           → TRUSTED_IDENTITIES (the lock)
+ *   - src/lib/admin-json.js              → readAdminJson (port discovery)
+ *   - src/lib/pg-query.js                → pgQuery + quoteLiteral
+ *
+ * Exit codes:
+ *   0  registered (or no-op idempotent re-run)
+ *   1  user error (bad flags, empty slug, slug sanitizes to empty)
+ *   2  pgserve postmaster unreachable / cannot bootstrap autopg_meta
+ *   3  postgres error during create / select / update sequence
+ */
+
+import { readAdminJson } from '../lib/admin-json.js';
+import { bootstrapAutopgMeta } from '../schema/autopg-meta.js';
+import { bootstrapConsumerAdmin } from '../admin/admin-bootstrap.js';
+import { TRUSTED_IDENTITIES } from '../cosign/trust-list.js';
+import { pgQuery, quoteLiteral } from '../lib/pg-query.js';
+import { sanitizeSlug } from '../provision/db-naming.js';
+
+const USAGE = `Usage: pgserve create-app <slug> [options]
+
+  <slug>                   consumer slug (sanitized via sanitizeSlug;
+                           e.g. "@demo/app" -> "demo_app").
+
+  --port <N>               override the postgres port (default: read
+                           ~/.autopg/admin.json or 5432).
+  --json                   emit a JSON summary on stdout.
+  -h, --help               show this help.
+
+Idempotent: re-running with the same slug touches last_updated only.
+The locked_roots snapshot from first-create is preserved — this is what
+keeps existing consumers verifiable after operator-driven trust rotation.
+
+Source-of-truth split:
+  public.autopg_meta is authoritative.
+  The per-consumer admin.json + manifest.json are derived caches.
+  On divergence, re-run \`pgserve create-app <slug>\` to regenerate them
+  from the table (the v2.4 read-only doctor surface flags divergence;
+  --fix tiered modes are deferred to a future wave).`;
+
+function parseFlags(argv) {
+  const out = { json: false, port: undefined, positional: [] };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    switch (a) {
+      case '--json':
+        out.json = true;
+        break;
+      case '--help':
+      case '-h':
+        out.help = true;
+        break;
+      case '--port':
+      case '-p': {
+        const v = Number(argv[++i]);
+        if (!Number.isInteger(v) || v <= 0 || v > 65535) {
+          throw new Error('--port requires an integer in [1, 65535]');
+        }
+        out.port = v;
+        break;
+      }
+      default:
+        if (a.startsWith('--')) {
+          throw new Error(`unknown flag: ${a}`);
+        }
+        out.positional.push(a);
+    }
+  }
+  return out;
+}
+
+function resolvePort(opts) {
+  if (typeof opts.port === 'number') return opts.port;
+  try {
+    const admin = readAdminJson();
+    if (admin && Number.isInteger(admin.port) && admin.port > 0) return admin.port;
+  } catch {
+    /* admin.json absent — fall through */
+  }
+  return 5432;
+}
+
+/**
+ * Adapter: shape `pgQuery` to the node-postgres-compatible
+ * `client.query(sql)` contract that bootstrapAutopgMeta expects.
+ * Mirrors src/commands/provision.js#makePsqlClient.
+ */
+function makePsqlClient({ port, db }) {
+  return {
+    query: async (sql) => pgQuery({ sql, port, db }),
+  };
+}
+
+async function ensureAutopgMetaSchema({ port }) {
+  const client = makePsqlClient({ port, db: 'postgres' });
+  await bootstrapAutopgMeta(client);
+}
+
+/**
+ * Look up an existing autopg_meta row for the slug. Returns
+ * `{ slug, manifestPath, lockedRoots, createdAt, lastUpdated }` or null.
+ *
+ * `locked_roots` is JSONB; psql returns it as a JSON string, parsed
+ * here. Timestamps are returned as ISO 8601 (psql `TIMESTAMPTZ` default
+ * format); we re-emit them through `new Date().toISOString()` so the
+ * cache-write side gets a stable shape.
+ */
+function selectAutopgMetaRow({ port, slug }) {
+  const out = pgQuery({
+    sql: [
+      'SELECT',
+      "  slug,",
+      "  manifest_path,",
+      "  locked_roots::text,",
+      "  to_char(created_at AT TIME ZONE 'UTC', 'YYYY-MM-DD\"T\"HH24:MI:SS.MS\"Z\"'),",
+      "  to_char(last_updated AT TIME ZONE 'UTC', 'YYYY-MM-DD\"T\"HH24:MI:SS.MS\"Z\"')",
+      'FROM public.autopg_meta',
+      `WHERE slug = ${quoteLiteral(slug)}`,
+      'LIMIT 1',
+    ].join('\n'),
+    port,
+    captureStdout: true,
+  });
+  if (!out) return null;
+  const [foundSlug, manifestPath, lockedRootsJson, createdAt, lastUpdated] = out.split('\t');
+  if (!foundSlug) return null;
+  let lockedRoots;
+  try {
+    lockedRoots = JSON.parse(lockedRootsJson);
+  } catch (err) {
+    const wrap = new Error(
+      `pgserve create-app: failed to parse locked_roots for slug "${foundSlug}": ${err.message}`,
+    );
+    wrap.cause = err;
+    throw wrap;
+  }
+  return {
+    slug: foundSlug,
+    manifestPath,
+    lockedRoots,
+    createdAt,
+    lastUpdated,
+  };
+}
+
+function insertAutopgMetaRow({ port, slug, manifestPath, lockedRoots, nowIso }) {
+  pgQuery({
+    sql: [
+      'INSERT INTO public.autopg_meta',
+      '  (slug, manifest_path, locked_roots, created_at, last_updated)',
+      'VALUES (',
+      `  ${quoteLiteral(slug)},`,
+      `  ${quoteLiteral(manifestPath)},`,
+      `  ${quoteLiteral(JSON.stringify(lockedRoots))}::jsonb,`,
+      `  ${quoteLiteral(nowIso)}::timestamptz,`,
+      `  ${quoteLiteral(nowIso)}::timestamptz`,
+      ')',
+    ].join('\n'),
+    port,
+  });
+}
+
+function touchAutopgMetaRow({ port, slug, manifestPath, nowIso }) {
+  // Update `last_updated` + `manifest_path` (the latter may have shifted
+  // if the operator re-ran with a different AUTOPG_CONFIG_DIR). Crucially
+  // does NOT touch `locked_roots` — that's the lock-preservation
+  // invariant per BRIEF v5 A6.
+  pgQuery({
+    sql: [
+      'UPDATE public.autopg_meta SET',
+      `  manifest_path = ${quoteLiteral(manifestPath)},`,
+      `  last_updated = ${quoteLiteral(nowIso)}::timestamptz`,
+      `WHERE slug = ${quoteLiteral(slug)}`,
+    ].join('\n'),
+    port,
+  });
+}
+
+function deepCloneRoots(lockedRoots) {
+  return JSON.parse(JSON.stringify(lockedRoots));
+}
+
+function emit({ json, summary, humanLines }) {
+  if (json) {
+    process.stdout.write(`${JSON.stringify(summary)}\n`);
+  } else {
+    for (const line of humanLines) process.stdout.write(`${line}\n`);
+  }
+}
+
+export async function runCreateApp(argv = []) {
+  let opts;
+  try {
+    opts = parseFlags(argv);
+  } catch (err) {
+    process.stderr.write(`pgserve create-app: ${err.message}\n\n${USAGE}\n`);
+    return 1;
+  }
+  if (opts.help) {
+    process.stdout.write(`${USAGE}\n`);
+    return 0;
+  }
+  const inputSlug = opts.positional[0];
+  if (typeof inputSlug !== 'string' || inputSlug.trim().length === 0) {
+    process.stderr.write(`pgserve create-app: <slug> is required\n\n${USAGE}\n`);
+    return 1;
+  }
+  const sanitized = sanitizeSlug(inputSlug);
+  if (sanitized.length === 0) {
+    process.stderr.write(
+      `pgserve create-app: slug "${inputSlug}" sanitizes to empty; pick a slug `
+      + 'with at least one alphanumeric character\n',
+    );
+    return 1;
+  }
+
+  const port = resolvePort(opts);
+  const summary = {
+    slug: sanitized,
+    inputSlug,
+    port,
+    action: 'unknown',
+  };
+
+  // Step 1 — bootstrap the autopg_meta table.
+  try {
+    await ensureAutopgMetaSchema({ port });
+  } catch (err) {
+    process.stderr.write(`pgserve create-app: cannot bootstrap autopg_meta: ${err.message}\n`);
+    summary.action = 'error';
+    summary.error = err.message;
+    if (opts.json) emit({ json: true, summary });
+    return 2;
+  }
+
+  // Step 2 — look for an existing row.
+  let existing;
+  try {
+    existing = selectAutopgMetaRow({ port, slug: sanitized });
+  } catch (err) {
+    process.stderr.write(`pgserve create-app: ${err.message}\n`);
+    summary.action = 'error';
+    summary.error = err.message;
+    if (opts.json) emit({ json: true, summary });
+    return 3;
+  }
+
+  const nowIso = new Date().toISOString();
+
+  if (existing) {
+    // Idempotent re-run path. Preserve `locked_roots` from the table
+    // (do NOT re-snapshot live TRUSTED_IDENTITIES — BRIEF v5 A6 lock
+    // preservation). Touch last_updated; rewrite the cache files.
+    let writeResult;
+    try {
+      writeResult = bootstrapConsumerAdmin({
+        slug: inputSlug,
+        lockedRoots: existing.lockedRoots,
+        createdAt: existing.createdAt,
+        lastUpdated: nowIso,
+      });
+    } catch (err) {
+      process.stderr.write(`pgserve create-app: failed to write cache files: ${err.message}\n`);
+      summary.action = 'error';
+      summary.error = err.message;
+      if (opts.json) emit({ json: true, summary });
+      return 1;
+    }
+
+    try {
+      touchAutopgMetaRow({
+        port,
+        slug: sanitized,
+        manifestPath: writeResult.manifestPath,
+        nowIso,
+      });
+    } catch (err) {
+      process.stderr.write(`pgserve create-app: ${err.message}\n`);
+      summary.action = 'error';
+      summary.error = err.message;
+      if (opts.json) emit({ json: true, summary });
+      return 3;
+    }
+
+    summary.action = 'touched';
+    summary.createdAt = existing.createdAt;
+    summary.lastUpdated = nowIso;
+    summary.lockedRoots = existing.lockedRoots;
+    summary.adminPath = writeResult.adminPath;
+    summary.manifestPath = writeResult.manifestPath;
+    emit({
+      json: opts.json,
+      summary,
+      humanLines: [
+        `pgserve create-app: slug "${sanitized}" already registered (touched).`,
+        `  locked_roots preserved (${existing.lockedRoots.length} entries from createdAt=${existing.createdAt})`,
+        `  admin:    ${writeResult.adminPath}`,
+        `  manifest: ${writeResult.manifestPath}`,
+      ],
+    });
+    return 0;
+  }
+
+  // Step 3 — fresh registration. Snapshot TRUSTED_IDENTITIES into the
+  // table + cache files. The deep-clone strips Object.freeze wrappers
+  // so the JSONB write is plain JSON.
+  const lockedRoots = deepCloneRoots(TRUSTED_IDENTITIES);
+
+  let writeResult;
+  try {
+    writeResult = bootstrapConsumerAdmin({
+      slug: inputSlug,
+      lockedRoots,
+      createdAt: nowIso,
+      lastUpdated: nowIso,
+    });
+  } catch (err) {
+    process.stderr.write(`pgserve create-app: failed to write cache files: ${err.message}\n`);
+    summary.action = 'error';
+    summary.error = err.message;
+    if (opts.json) emit({ json: true, summary });
+    return 1;
+  }
+
+  try {
+    insertAutopgMetaRow({
+      port,
+      slug: sanitized,
+      manifestPath: writeResult.manifestPath,
+      lockedRoots,
+      nowIso,
+    });
+  } catch (err) {
+    process.stderr.write(`pgserve create-app: ${err.message}\n`);
+    summary.action = 'error';
+    summary.error = err.message;
+    if (opts.json) emit({ json: true, summary });
+    return 3;
+  }
+
+  summary.action = 'created';
+  summary.createdAt = nowIso;
+  summary.lastUpdated = nowIso;
+  summary.lockedRoots = lockedRoots;
+  summary.adminPath = writeResult.adminPath;
+  summary.manifestPath = writeResult.manifestPath;
+  emit({
+    json: opts.json,
+    summary,
+    humanLines: [
+      `pgserve create-app: registered slug "${sanitized}".`,
+      `  locked_roots: snapshotted ${lockedRoots.length} entries from TRUSTED_IDENTITIES`,
+      `  admin:    ${writeResult.adminPath}`,
+      `  manifest: ${writeResult.manifestPath}`,
+    ],
+  });
+  return 0;
+}
+
+export const __testInternals = Object.freeze({
+  parseFlags,
+  resolvePort,
+  deepCloneRoots,
+});

package/src/commands/doctor.js

@@ -42,6 +42,7 @@ import { getAdminFilePath, readAdminJson, SUPERVISOR_VALUES } from '../lib/admin
 import { resolveSocketDir } from '../lib/socket-dir.js';
 import { readRuntimeJson, isLiveRuntime } from '../lib/runtime-json.js';
 import { findBlocked } from '../security/blocked-versions.js';
+import { pgQuery } from '../lib/pg-query.js';
 
 const SEVERITY = Object.freeze({ PASS: 'PASS', WARN: 'WARN', FAIL: 'FAIL' });
 
@@ -374,6 +375,68 @@ function checkTcpReachable(admin) {
   });
 }
 
+/**
+ * B7 (v2.6.3): surface the audit posture as a doctor finding so operators
+ * know whether their postmaster is running pgaudit (structured audit
+ * classes) or the log_statement=all fallback (capture-everything via
+ * postgres-native logging). Pre-fix the fallback fired silently — the
+ * WARN appeared once at startup in pm2 logs and was lost to operators
+ * who didn't tail the logs at the right moment.
+ *
+ * PASS  pgaudit shows up in shared_preload_libraries on the live postmaster
+ * WARN  pgaudit absent (fallback active) OR cannot probe (postmaster
+ *       unreachable / psql missing)
+ *
+ * The check fires SQL via the cohort-canonical pgQuery (psql shellout),
+ * so it inherits its env contract (PGPASSWORD literal-postgres fallback
+ * for fresh-install hosts per CV-1) and times out via psql's own
+ * connection timeout. Failure modes are mapped to WARN, never FAIL —
+ * this is a posture diagnostic, not a connectivity gate.
+ */
+function checkPgauditLoaded(admin) {
+  if (!admin || !Number.isInteger(admin.port) || admin.port <= 0) {
+    return check(
+      'pgaudit_loaded',
+      'audit posture not probed',
+      SEVERITY.WARN,
+      'admin.json missing or has no port; cannot connect to postmaster to probe SHOW shared_preload_libraries',
+      'run `pgserve install` (Tier A) or `autopg service install` (Tier B) first',
+    );
+  }
+  let preloadLibs;
+  try {
+    preloadLibs = pgQuery({
+      sql: 'SHOW shared_preload_libraries',
+      port: admin.port,
+      captureStdout: true,
+    });
+  } catch (err) {
+    return check(
+      'pgaudit_loaded',
+      'audit posture probe failed',
+      SEVERITY.WARN,
+      `psql shellout failed: ${err?.stderr?.trim?.() || err?.message || err}`,
+      'verify postmaster is up (`pgserve status`) and psql is on PATH',
+    );
+  }
+  const value = (preloadLibs || '').trim();
+  if (/(^|,)\s*pgaudit\s*(,|$)/i.test(value)) {
+    return check(
+      'pgaudit_loaded',
+      'pgaudit loaded — structured audit posture',
+      SEVERITY.PASS,
+      `shared_preload_libraries=${value || '(empty)'}`,
+    );
+  }
+  return check(
+    'pgaudit_loaded',
+    'pgaudit NOT loaded — fallback to log_statement=all',
+    SEVERITY.WARN,
+    `shared_preload_libraries=${value || '(empty)'}; audit data captured via log_statement=all (postgres-native), not pgaudit's structured classes`,
+    'bundle pgaudit.so with the embedded postgres binaries (Branch A in QA-RECIPE-B7.md) to switch the postmaster onto pgaudit; the current fallback is functional for compliance but noisier than pgaudit',
+  );
+}
+
 // ─── orchestration ────────────────────────────────────────────────────
 
 /**
@@ -392,6 +455,7 @@ export async function runChecks() {
   findings.push(checkSupervisorLiveness(admin));
   findings.push(checkRuntimeJson(admin));
   findings.push(await checkUdsReachable(admin));
+  findings.push(checkPgauditLoaded(admin));
   findings.push(await checkTcpReachable(admin));
 
   return findings;
@@ -460,6 +524,7 @@ export const __testInternals = Object.freeze({
   checkAdminJsonShape,
   checkRuntimeJson,
   checkSupervisorLiveness,
+  checkPgauditLoaded,
   exitCodeFor,
   SEVERITY,
 });