pgserve 2.5.0 → 2.6.1

package/src/gc/orphan-detection.js

@@ -0,0 +1,190 @@
+/**
+ * Pure orphan classification for `pgserve gc`.
+ *
+ * pgserve singleton (v2.4) — `pgserve-singleton-no-proxy` wish, Group 3.
+ *
+ * Splits the gc verb into two halves:
+ *   1. (this module)  decide which `pgserve_meta` rows refer to dead
+ *      consumers and which are still in use
+ *   2. (gc verb)      DROP the orphans + audit-log every drop
+ *
+ * Keeping classification pure means the gc verb can be tested
+ * deterministically (feed in synthetic input → assert the partition)
+ * without spinning up postgres, and the rules can be exercised at high
+ * fan-out by callers that want a `pgserve gc --dry-run`.
+ *
+ * Orphan signals (any one is sufficient):
+ *   1. The DB row exists in pgserve_meta but the database itself does
+ *      not exist in `pg_database` — leftover row from a manual DROP.
+ *   2. The row's `source_path` is set and that path no longer exists
+ *      on the filesystem — the consumer directory was removed.
+ *   3. The row's `last_used_at` is older than `staleAfterMs` AND the
+ *      database has zero active connections in `pg_stat_activity`.
+ *      The "no connections" guard prevents gc from dropping a DB that
+ *      a long-running consumer is actively using; a missing entry in
+ *      the activity map is treated as zero connections.
+ *
+ * Retention signals (none of the above + an explicit "in use" hit):
+ *   - `last_used_at` is within the staleness window, OR
+ *   - the database has at least one active connection.
+ *
+ * Inputs:
+ *   - `metaRows`         array of pgserve_meta row objects: { fingerprint,
+ *                        database_name, role_name, source_path, last_used_at }
+ *   - `existingDbs`      Set<string> of DB names from `pg_database`
+ *   - `activeDbs`        Set<string> of DB names that have ≥1 row in
+ *                        pg_stat_activity (or a Map<string, number> if
+ *                        callers want to record the count too — Set-like
+ *                        access is what we use)
+ *   - `pathExists(path)` callback returning truthy when the path is on
+ *                        disk. Caller injects fs.existsSync or a mock.
+ *   - `now`              Date — usually `new Date()`; injectable for tests.
+ *   - `staleAfterMs`     ms threshold past `last_used_at` to declare
+ *                        an idle DB stale. Default: 30 days.
+ *
+ * Outputs:
+ *   { orphans: [...], retained: [...] }
+ *   each row in `orphans` has `reason: 'missing_db' | 'missing_path' |
+ *   'idle_stale'`; each row in `retained` has `reason: 'active' |
+ *   'recent' | 'unknown_meta'`. The `unknown_meta` bucket exists for
+ *   rows that are missing `last_used_at` entirely — we never DROP one
+ *   of those without an operator decision.
+ */
+
+const DEFAULT_STALE_AFTER_MS = 30 * 24 * 60 * 60 * 1000; // 30 days
+
+/**
+ * @typedef {Object} MetaRow
+ * @property {string}   fingerprint
+ * @property {string}   database_name
+ * @property {string}   role_name
+ * @property {string=}  source_path
+ * @property {string|Date=} last_used_at
+ */
+
+/**
+ * @typedef {Object} OrphanFinding
+ * @property {MetaRow}  row
+ * @property {'missing_db'|'missing_path'|'idle_stale'} reason
+ * @property {string=}  detail
+ */
+
+/**
+ * @typedef {Object} RetainedFinding
+ * @property {MetaRow}  row
+ * @property {'active'|'recent'|'unknown_meta'} reason
+ * @property {string=}  detail
+ */
+
+function asTime(t) {
+  if (!t) return null;
+  if (t instanceof Date) {
+    const ms = t.getTime();
+    return Number.isFinite(ms) ? ms : null;
+  }
+  if (typeof t === 'string') {
+    const ms = Date.parse(t);
+    return Number.isFinite(ms) ? ms : null;
+  }
+  if (typeof t === 'number' && Number.isFinite(t)) return t;
+  return null;
+}
+
+/**
+ * Classify a single meta row. Exposed for unit tests so callers can
+ * exercise individual signals without composing a full input set.
+ *
+ * @returns {OrphanFinding | RetainedFinding}
+ */
+export function classifyRow(row, ctx) {
+  if (!row || typeof row.database_name !== 'string' || row.database_name.length === 0) {
+    throw new TypeError('classifyRow: row must have a non-empty database_name');
+  }
+  const {
+    existingDbs,
+    activeDbs,
+    pathExists,
+    now,
+    staleAfterMs,
+  } = ctx;
+
+  // 1. database is gone but the meta row is still here
+  if (!existingDbs.has(row.database_name)) {
+    return {
+      row,
+      reason: 'missing_db',
+      detail: `${row.database_name} not in pg_database`,
+    };
+  }
+
+  // 2. consumer directory was removed
+  if (typeof row.source_path === 'string' && row.source_path.length > 0) {
+    if (!pathExists(row.source_path)) {
+      return {
+        row,
+        reason: 'missing_path',
+        detail: `source_path ${row.source_path} no longer exists`,
+      };
+    }
+  }
+
+  // 3. idle + stale
+  const lastUsedMs = asTime(row.last_used_at);
+  if (lastUsedMs == null) {
+    return {
+      row,
+      reason: 'unknown_meta',
+      detail: 'last_used_at is missing or unparseable; refusing to gc without operator review',
+    };
+  }
+  const ageMs = now.getTime() - lastUsedMs;
+  const isStale = ageMs >= staleAfterMs;
+  const isActive = activeDbs.has(row.database_name);
+
+  if (isActive) {
+    return { row, reason: 'active', detail: `${row.database_name} has ≥1 active connection` };
+  }
+  if (isStale) {
+    return {
+      row,
+      reason: 'idle_stale',
+      detail: `last_used_at is ${Math.floor(ageMs / (24 * 60 * 60 * 1000))}d old, no active connections`,
+    };
+  }
+  return { row, reason: 'recent', detail: `last_used_at is within ${Math.floor(staleAfterMs / (24 * 60 * 60 * 1000))}d window` };
+}
+
+const ORPHAN_REASONS = new Set(['missing_db', 'missing_path', 'idle_stale']);
+
+/**
+ * Partition all rows into orphans + retained.
+ * @param {object} args
+ * @param {MetaRow[]} args.metaRows
+ * @param {Set<string>} args.existingDbs
+ * @param {Set<string>} args.activeDbs
+ * @param {(p: string) => boolean} [args.pathExists]
+ * @param {Date} [args.now]
+ * @param {number} [args.staleAfterMs]
+ * @returns {{ orphans: OrphanFinding[], retained: RetainedFinding[] }}
+ */
+export function classifyOrphans(args = {}) {
+  const {
+    metaRows = [],
+    existingDbs = new Set(),
+    activeDbs = new Set(),
+    pathExists = () => true,
+    now = new Date(),
+    staleAfterMs = DEFAULT_STALE_AFTER_MS,
+  } = args;
+  const ctx = { existingDbs, activeDbs, pathExists, now, staleAfterMs };
+  const orphans = [];
+  const retained = [];
+  for (const row of metaRows) {
+    const finding = classifyRow(row, ctx);
+    if (ORPHAN_REASONS.has(finding.reason)) orphans.push(finding);
+    else retained.push(finding);
+  }
+  return { orphans, retained };
+}
+
+export const __testInternals = Object.freeze({ DEFAULT_STALE_AFTER_MS, asTime });

package/src/gc/queries.js

@@ -0,0 +1,193 @@
+/**
+ * psql query helpers for `pgserve gc`.
+ *
+ * pgserve singleton (v2.4) — `pgserve-singleton-no-proxy` wish, Group 3
+ * (the `pgserve gc` orchestration layer).
+ *
+ * This module composes the shared psql primitive (`pgQuery` /
+ * `quoteIdent` / `quoteLiteral` from `src/lib/pg-query.js`) into the
+ * specific SELECT / DROP queries gc runs against `pgserve_meta` +
+ * `pg_database` + `pg_stat_activity`.
+ *
+ * History: PR #91 inlined its own `pgQuery`; PR #92 extracted the
+ * canonical primitive to `src/lib/pg-query.js`; the
+ * `autopg-distribution-cutover-finalize` G2 dedup PR (#94) collapsed
+ * the gc-side copy into a re-exporter at `src/gc/pg-queries.js`. This
+ * file is the G2-followup destination — gc-specific helpers only,
+ * primitives consumed via direct imports from `src/lib/pg-query.js`.
+ *
+ * DROP DATABASE caveat: postgres refuses `DROP DATABASE <db>` when
+ * sessions are connected. We `pg_terminate_backend()` everything
+ * targeting the doomed database first, then DROP. The kill step is
+ * gated behind explicit `--apply` at the CLI layer; this module just
+ * exposes the primitives.
+ */
+
+import { pgQuery, quoteIdent, quoteLiteral, PG_QUERY_DEFAULTS } from '../lib/pg-query.js';
+import { PGSERVE_META_TABLE } from '../schema/pgserve-meta.js';
+
+const DEFAULT_PORT = PG_QUERY_DEFAULTS.port;
+const DEFAULT_DB = PG_QUERY_DEFAULTS.db;
+
+const SYSTEM_DBS = new Set(['template0', 'template1', 'postgres']);
+
+/**
+ * SELECT every row from `pgserve_meta`. Returns an array of plain
+ * objects matching the table shape from `src/schema/pgserve-meta.js`.
+ * Throws ENOPGSERVE_META if the table doesn't exist (caller decides
+ * whether that's a "no provisions yet" warn vs. a hard fail).
+ */
+export function selectMetaRows({ port = DEFAULT_PORT } = {}) {
+  // Single-line tab-separated form so a missing/null column still
+  // parses cleanly. ARRAY_AGG would lose null distinction.
+  const exists = pgQuery({
+    db: DEFAULT_DB,
+    port,
+    sql: `SELECT to_regclass('public.${PGSERVE_META_TABLE}') IS NOT NULL`,
+    captureStdout: true,
+  });
+  if (exists.trim() !== 't') {
+    const err = new Error(`pgserve_meta does not exist on this host`);
+    err.code = 'ENOPGSERVE_META';
+    throw err;
+  }
+  const out = pgQuery({
+    db: DEFAULT_DB,
+    port,
+    sql: [
+      'SELECT',
+      "  COALESCE(fingerprint, ''),",
+      "  COALESCE(database_name, ''),",
+      "  COALESCE(role_name, ''),",
+      "  COALESCE(publisher, ''),",
+      "  COALESCE(source_path, ''),",
+      "  COALESCE(to_char(last_used_at AT TIME ZONE 'UTC', 'YYYY-MM-DD\"T\"HH24:MI:SS.MS\"Z\"'), '')",
+      `FROM public.${PGSERVE_META_TABLE}`,
+      'ORDER BY fingerprint',
+    ].join('\n'),
+    captureStdout: true,
+  });
+  if (!out) return [];
+  return out.split('\n').filter(Boolean).map((line) => {
+    const [fingerprint, database_name, role_name, publisher, source_path, last_used_at] = line.split('\t');
+    return {
+      fingerprint: fingerprint || '',
+      database_name: database_name || '',
+      role_name: role_name || '',
+      publisher: publisher || '',
+      source_path: source_path || '',
+      // Empty string → undefined so orphan-detection's `unknown_meta`
+      // bucket triggers correctly when last_used_at was NULL on disk.
+      last_used_at: last_used_at && last_used_at.length > 0 ? last_used_at : undefined,
+    };
+  });
+}
+
+/**
+ * SELECT every non-template database name from pg_database. Excludes
+ * the postgres-system DBs ('template0', 'template1', 'postgres').
+ */
+export function selectExistingDbs({ port = DEFAULT_PORT } = {}) {
+  const out = pgQuery({
+    db: DEFAULT_DB,
+    port,
+    sql: 'SELECT datname FROM pg_database WHERE NOT datistemplate ORDER BY datname',
+    captureStdout: true,
+  });
+  if (!out) return new Set();
+  const arr = out.split('\n').filter(Boolean).filter((d) => !SYSTEM_DBS.has(d));
+  return new Set(arr);
+}
+
+/**
+ * Return the set of DB names that have ≥1 active connection in
+ * pg_stat_activity (excluding our own connection).
+ */
+export function selectActiveDbs({ port = DEFAULT_PORT } = {}) {
+  const out = pgQuery({
+    db: DEFAULT_DB,
+    port,
+    sql: [
+      'SELECT DISTINCT datname',
+      'FROM pg_stat_activity',
+      'WHERE datname IS NOT NULL',
+      '  AND pid <> pg_backend_pid()',
+    ].join('\n'),
+    captureStdout: true,
+  });
+  if (!out) return new Set();
+  return new Set(out.split('\n').filter(Boolean));
+}
+
+/**
+ * Terminate every backend connected to `database`, then `DROP DATABASE`
+ * + `DROP ROLE IF EXISTS`. Caller is responsible for orphan
+ * classification — this is the dumb side. We commit each drop in its
+ * own implicit transaction (psql -At -f - is autocommit) so a partial
+ * sweep leaves a consistent audit log.
+ *
+ * Returns `{ database, role }` for the audit writer.
+ */
+export function dropDatabase({ database, role, port = DEFAULT_PORT } = {}) {
+  if (typeof database !== 'string' || database.length === 0 || SYSTEM_DBS.has(database)) {
+    throw new Error(`dropDatabase: refusing to drop "${database}" (empty or system DB)`);
+  }
+  // 1. Disconnect everything from the doomed DB. SELECT-with-side-
+  //    effect form so we can run it from any other DB.
+  pgQuery({
+    db: DEFAULT_DB,
+    port,
+    sql: [
+      'SELECT pg_terminate_backend(pid)',
+      'FROM pg_stat_activity',
+      `WHERE datname = ${quoteLiteral(database)}`,
+      '  AND pid <> pg_backend_pid()',
+    ].join('\n'),
+  });
+  // 2. DROP DATABASE — postgres rejects parameterized DDL, so we have
+  //    to interpolate. database_name comes from pgserve_meta (which we
+  //    write ourselves via deriveProvisionedNames) and SYSTEM_DBS is
+  //    guarded above; the identifier surface is constrained.
+  pgQuery({
+    db: DEFAULT_DB,
+    port,
+    sql: `DROP DATABASE IF EXISTS ${quoteIdent(database)}`,
+  });
+  // 3. DROP ROLE — best-effort; a role may be shared across multiple
+  //    DBs in older non-cohort installs, so we use IF EXISTS and don't
+  //    fail the gc run if it can't be dropped (other DBs depend on it).
+  if (typeof role === 'string' && role.length > 0) {
+    try {
+      pgQuery({
+        db: DEFAULT_DB,
+        port,
+        sql: `DROP ROLE IF EXISTS ${quoteIdent(role)}`,
+      });
+    } catch {
+      /* role may be in use elsewhere; not fatal for gc's drop step */
+    }
+  }
+  return { database, role };
+}
+
+/**
+ * DELETE the row from `pgserve_meta`. Caller invokes after a successful
+ * `dropDatabase` so the next gc run doesn't re-find the same orphan.
+ */
+export function deleteMetaRow({ fingerprint, port = DEFAULT_PORT } = {}) {
+  if (typeof fingerprint !== 'string' || fingerprint.length === 0) {
+    throw new TypeError('deleteMetaRow: fingerprint must be a non-empty string');
+  }
+  pgQuery({
+    db: DEFAULT_DB,
+    port,
+    sql: `DELETE FROM public.${PGSERVE_META_TABLE} WHERE fingerprint = ${quoteLiteral(fingerprint)}`,
+  });
+}
+
+export const __testInternals = Object.freeze({
+  quoteIdent,
+  quoteLiteral,
+  SYSTEM_DBS,
+  DEFAULT_PORT,
+});

package/src/lib/pg-query.js

@@ -0,0 +1,145 @@
+/**
+ * Shared psql shellout primitive.
+ *
+ * pgserve singleton (v2.4) — `pgserve-singleton-no-proxy` wish, Group 3
+ * (foundation for the gc + provision orchestration verbs).
+ *
+ * Why psql shellout vs. node-postgres:
+ *   - matches the existing pattern in
+ *     `src/upgrade/steps/cosign-meta-migration.js` (PR #79).
+ *   - avoids the runtime cost of loading the `pg` driver in a CLI
+ *     verb that runs once and exits.
+ *   - no shell expansion: SQL goes through stdin, not a template
+ *     string, so postgres-style `$$` blocks survive intact.
+ *
+ * Caller-supplied `db` defaults to `postgres`. The connection-discovery
+ * layer (admin.json + runtime.json) is the caller's responsibility —
+ * this module does not assume a host shape.
+ */
+
+import { spawnSync } from 'node:child_process';
+
+export const PG_QUERY_DEFAULTS = Object.freeze({
+  port: 5432,
+  host: '127.0.0.1',
+  user: 'postgres',
+  db: 'postgres',
+});
+
+/**
+ * Resolve the PGPASSWORD value for a psql shell-out. Precedence:
+ *
+ *   1. caller-supplied `password` (explicit override; tests, callers
+ *      that read from a known-secret store)
+ *   2. `process.env.PGPASSWORD` (operator-set env override; this is
+ *      what `.pgpass`-style hosts already use today via shell wrappers)
+ *   3. literal `'postgres'` — matches the bootstrap password
+ *      `pgserve install` configures on the local-loopback postgres.
+ *      Required for fresh-install hosts where the env is unset and
+ *      no `.pgpass` file exists yet (CV-1, 2026-05-09).
+ *
+ * Hardcoding the literal `'postgres'` fallback was deliberately AVOIDED
+ * in PR #92 (bot-review HIGH) on the reasoning that it would defeat
+ * `.pgpass` / peer-auth integration. CV-1 reframed that tradeoff:
+ *
+ *   - peer-auth hosts use `host=<unix-socket-path>` which postgres
+ *     treats as auth-method `peer` (or `trust` depending on `pg_hba`),
+ *     so the PGPASSWORD value is ignored entirely; the literal default
+ *     does no harm there.
+ *   - `.pgpass`-using hosts can still override with explicit
+ *     `PGPASSWORD=…` shell env, OR pass `password` explicitly through
+ *     the function call. Their upstream wrapping is unchanged.
+ *   - Fresh-install + TCP-loopback (the path CV-1 exercises) gets the
+ *     literal that `pgserve install` already configured, instead of
+ *     a `password authentication failed for user "postgres"` FATAL.
+ */
+export function resolvePgPassword({ password, envPassword = process.env.PGPASSWORD } = {}) {
+  if (password !== undefined) return password;
+  if (envPassword !== undefined) return envPassword;
+  return 'postgres';
+}
+
+/**
+ * Run a single SQL statement (or batch) via psql, fed through stdin
+ * (no shell expansion). Throws on non-zero exit. Returns stdout
+ * (trimmed when `captureStdout`).
+ *
+ * @param {object} args
+ * @param {string} args.sql                      SQL to execute
+ * @param {string} [args.db='postgres']          target database
+ * @param {number} [args.port=5432]              postgres port
+ * @param {string} [args.host='127.0.0.1']       postgres host
+ * @param {string} [args.user='postgres']        postgres user
+ * @param {string} [args.password]               PGPASSWORD; resolves via
+ *                                               `resolvePgPassword()` —
+ *                                               caller > env > 'postgres'
+ * @param {boolean} [args.captureStdout=false]   trim + return stdout
+ * @returns {string} stdout (trimmed when `captureStdout`)
+ */
+export function pgQuery({
+  sql,
+  db = PG_QUERY_DEFAULTS.db,
+  port = PG_QUERY_DEFAULTS.port,
+  host = PG_QUERY_DEFAULTS.host,
+  user = PG_QUERY_DEFAULTS.user,
+  password,
+  captureStdout = false,
+} = {}) {
+  if (typeof sql !== 'string' || sql.length === 0) {
+    throw new TypeError('pgQuery: sql must be a non-empty string');
+  }
+  // PGPASSWORD is always set; defaults to 'postgres' on fresh-install
+  // hosts where neither env nor caller supplied one (CV-1 fix). See
+  // `resolvePgPassword` docstring for the precedence rules + the
+  // updated reasoning about .pgpass / peer-auth host coexistence.
+  const env = { ...process.env, PGPASSWORD: resolvePgPassword({ password }) };
+  const result = spawnSync(
+    'psql',
+    [
+      '-h', host,
+      '-p', String(port),
+      '-U', user,
+      '-d', db,
+      // -At: tuples-only + unaligned. -F: explicit tab field separator
+      // (psql defaults to '|' for unaligned mode; callers split rows on
+      // '\t' so the separator MUST be '\t'). Bot review CRITICAL.
+      '-At', '-F', '\t',
+      // ON_ERROR_STOP=1: in script mode (-f), psql by default continues
+      // past statement errors and STILL exits 0. A failed CREATE
+      // DATABASE / GRANT could otherwise be invisible to the caller.
+      // Bot review CRITICAL P1.
+      '-v', 'ON_ERROR_STOP=1',
+      '-f', '-',
+    ],
+    { env, input: sql, stdio: ['pipe', 'pipe', 'pipe'] },
+  );
+  if (result.status !== 0) {
+    const stderr = (result.stderr || Buffer.from('')).toString();
+    const err = new Error(`psql exited ${result.status}: ${stderr.trim()}`);
+    err.status = result.status;
+    err.stderr = stderr;
+    throw err;
+  }
+  const stdout = (result.stdout || Buffer.from('')).toString();
+  return captureStdout ? stdout.trim() : stdout;
+}
+
+/**
+ * Postgres identifier quoting: wrap in "..." and escape internal ".
+ * Used by callers that interpolate identifiers (DDL doesn't accept
+ * parameter binding for table / role / database names).
+ */
+export function quoteIdent(name) {
+  return `"${String(name).replace(/"/g, '""')}"`;
+}
+
+/**
+ * Postgres literal quoting: wrap in '...' and escape internal '.
+ * Use this for any string literal that ends up in a DDL string;
+ * regular DML should bind parameters instead, but psql's stdin form
+ * doesn't accept those, so the safe path for our shellout is to
+ * always quoteLiteral defensively.
+ */
+export function quoteLiteral(value) {
+  return `'${String(value).replace(/'/g, "''")}'`;
+}

package/src/provision/advisory-lock.js

@@ -0,0 +1,91 @@
+/**
+ * `pg_advisory_lock` key derivation for `pgserve provision`.
+ *
+ * pgserve singleton (v2.4) — `pgserve-singleton-no-proxy` wish, Group 3.
+ *
+ * The wish locks the concurrency story: 10 simultaneous `pgserve
+ * provision <fingerprint>` calls must produce exactly 1 database. The
+ * server-side coordination is `pg_advisory_lock(key)`; this module
+ * derives the integer key from a fingerprint string deterministically.
+ *
+ * Why two forms:
+ *   - `pg_advisory_lock(bigint)`        — single 64-bit key
+ *   - `pg_advisory_lock(int4, int4)`    — two 32-bit keys (older
+ *     postgres major versions on hosts the cohort still supports)
+ *
+ * Both are derived from the same sha256 of the fingerprint, so two
+ * provision processes against the same fingerprint will always pick
+ * the same lock regardless of which advisory-lock variant they call.
+ *
+ * Key derivation:
+ *   - sha256(fingerprint) → 32 bytes
+ *   - bigint key:  reinterpret the first 8 bytes as a signed 64-bit
+ *                  integer, big-endian. The bigint form is what we
+ *                  recommend; the int4 form is provided for parity with
+ *                  callers that need it.
+ *   - int4 pair:   high 32 bits → key1, low 32 bits → key2 (both
+ *                  signed). This matches postgres's two-arg overload.
+ *
+ * Pure function: no postgres I/O, no network, no globals.
+ */
+
+import crypto from 'node:crypto';
+
+const PGSERVE_NAMESPACE_TAG = 'pgserve-provision-v1:';
+
+function sha256Bytes(input) {
+  return crypto.createHash('sha256').update(input, 'utf8').digest();
+}
+
+/**
+ * Derive the bigint advisory-lock key from a fingerprint string.
+ * Returned as a JS BigInt; postgres bigint accepts any signed 64-bit
+ * integer (range: -2^63 .. 2^63 - 1).
+ * @returns {BigInt}
+ */
+export function deriveBigintKey(fingerprint) {
+  if (typeof fingerprint !== 'string' || fingerprint.length === 0) {
+    throw new TypeError('deriveBigintKey: fingerprint must be a non-empty string');
+  }
+  const bytes = sha256Bytes(PGSERVE_NAMESPACE_TAG + fingerprint);
+  // Read first 8 bytes big-endian, signed.
+  const key = bytes.readBigInt64BE(0);
+  return key;
+}
+
+/**
+ * Derive the (int4, int4) advisory-lock key pair. Returns plain Numbers
+ * in the signed 32-bit range so the caller can pass them straight to
+ * pg-cstring/pg-promise without BigInt coercion plumbing.
+ * @returns {{ key1: number, key2: number }}
+ */
+export function deriveInt4Pair(fingerprint) {
+  if (typeof fingerprint !== 'string' || fingerprint.length === 0) {
+    throw new TypeError('deriveInt4Pair: fingerprint must be a non-empty string');
+  }
+  const bytes = sha256Bytes(PGSERVE_NAMESPACE_TAG + fingerprint);
+  // High 32 bits → key1; low 32 bits → key2; both signed.
+  const key1 = bytes.readInt32BE(0);
+  const key2 = bytes.readInt32BE(4);
+  return { key1, key2 };
+}
+
+/**
+ * Convenience: returns the SQL fragment that acquires the lock with
+ * pg_advisory_xact_lock. pgserve provision wraps a transaction around
+ * its CREATE DATABASE / CREATE ROLE / INSERT, and xact-scoped locks
+ * release automatically when that transaction commits or rolls back —
+ * no risk of a dangling session-scoped lock surviving a crashed
+ * provision.
+ *
+ * Returns: `{ sql: '...', params: [BigInt] }`
+ */
+export function buildAdvisoryLockSql(fingerprint) {
+  const key = deriveBigintKey(fingerprint);
+  return {
+    sql: 'SELECT pg_advisory_xact_lock($1::bigint)',
+    params: [key],
+  };
+}
+
+export const __testInternals = Object.freeze({ sha256Bytes, PGSERVE_NAMESPACE_TAG });