pgserve 2.4.0 → 2.6.0

package/src/lib/runtime-json.js

@@ -0,0 +1,181 @@
+/**
+ * `<socketDir>/runtime.json` — runtime discovery file owned by the
+ * `autopg serve` postmaster wrapper (cutover wish G19).
+ *
+ * Schema:
+ *   {
+ *     socketDir:     "<absolute path>",
+ *     port:          <integer>,    // postgres TCP port
+ *     pid:           <integer>,    // postmaster pid
+ *     autopgPid:     <integer>,    // `autopg serve` wrapper pid
+ *     schemaVersion: 1
+ *   }
+ *
+ * Cohort contract — there is **no `supervisor` field**. The supervisor
+ * (pm2 / systemd-user / launchd / external) is recorded once at install
+ * time in `~/.autopg/admin.json`. Mixing the two creates a synchronization
+ * problem (which file is authoritative when the postmaster restarts under
+ * a new pid?). `writeRuntimeJson()` rejects records carrying a `supervisor`
+ * key so the contract can't drift via a future copy-paste.
+ *
+ * Lifecycle:
+ *   - `writeRuntimeJson()` after the postmaster greets healthy.
+ *   - `clearRuntimeJson()` on graceful shutdown (SIGTERM / SIGINT).
+ *   - On crash the file is left in place. Consumers detect a stale record
+ *     via `process.kill(record.autopgPid, 0)` (no-signal probe).
+ *
+ * Atomic semantics: write to `<file>.tmp.<pid>`, then `fs.renameSync()`.
+ * Mode 0644 so unprivileged peers can `cat <socketDir>/runtime.json`
+ * without sudo — the file carries no secrets, only public discovery info.
+ */
+
+import fs from 'fs';
+import path from 'path';
+
+export const RUNTIME_FILE_NAME = 'runtime.json';
+export const RUNTIME_FILE_MODE = 0o644;
+export const RUNTIME_SCHEMA_VERSION = 1;
+
+export function getRuntimeFilePath(socketDir) {
+  if (typeof socketDir !== 'string' || socketDir.length === 0) {
+    throw new TypeError('runtime-json: socketDir must be a non-empty string');
+  }
+  return path.join(socketDir, RUNTIME_FILE_NAME);
+}
+
+function isPlainObject(v) {
+  return v !== null && typeof v === 'object' && !Array.isArray(v);
+}
+
+function validateRecord(record) {
+  if (!isPlainObject(record)) {
+    throw new TypeError('runtime-json: record must be an object');
+  }
+  if (typeof record.socketDir !== 'string' || record.socketDir.length === 0) {
+    throw new TypeError('runtime-json: socketDir must be a non-empty string');
+  }
+  if (!Number.isInteger(record.port) || record.port < 1 || record.port > 65535) {
+    throw new TypeError(`runtime-json: port must be an integer in [1, 65535]; got ${record.port}`);
+  }
+  if (!Number.isInteger(record.pid) || record.pid < 1) {
+    throw new TypeError(`runtime-json: pid must be a positive integer; got ${record.pid}`);
+  }
+  if (!Number.isInteger(record.autopgPid) || record.autopgPid < 1) {
+    throw new TypeError(`runtime-json: autopgPid must be a positive integer; got ${record.autopgPid}`);
+  }
+  if (Object.prototype.hasOwnProperty.call(record, 'supervisor')) {
+    throw new TypeError(
+      'runtime-json: refusing to write `supervisor` into runtime.json — that field '
+      + 'lives only in `~/.autopg/admin.json` (cohort contract).',
+    );
+  }
+}
+
+/**
+ * Read `<socketDir>/runtime.json`. Returns the parsed object on success,
+ * `null` when the file is missing or unreadable. Never throws — callers
+ * treat "missing" and "broken" identically and fall back to admin.json.
+ */
+export function readRuntimeJson(socketDir) {
+  let file;
+  try {
+    file = getRuntimeFilePath(socketDir);
+  } catch {
+    return null;
+  }
+  let raw;
+  try {
+    raw = fs.readFileSync(file, 'utf8');
+  } catch {
+    return null;
+  }
+  try {
+    const parsed = JSON.parse(raw);
+    return isPlainObject(parsed) ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Atomic write of the runtime discovery record. Validates shape, refuses
+ * a `supervisor` key (the cohort contract — that field belongs in
+ * admin.json), ensures the parent directory exists, and stamps
+ * `schemaVersion: 1` if the caller didn't.
+ */
+export function writeRuntimeJson(input = {}) {
+  if (!isPlainObject(input)) {
+    throw new TypeError('runtime-json: writeRuntimeJson expects an object argument');
+  }
+  // Reject `supervisor` from the input directly — destructuring would
+  // silently drop it and that's a contract failure we want to surface.
+  if (Object.prototype.hasOwnProperty.call(input, 'supervisor')) {
+    throw new TypeError(
+      'runtime-json: refusing to write `supervisor` into runtime.json — that field '
+      + 'lives only in `~/.autopg/admin.json` (cohort contract).',
+    );
+  }
+  const { socketDir, port, pid, autopgPid, schemaVersion = RUNTIME_SCHEMA_VERSION } = input;
+  const record = { socketDir, port, pid, autopgPid, schemaVersion };
+  validateRecord(record);
+
+  if (!fs.existsSync(socketDir)) {
+    fs.mkdirSync(socketDir, { recursive: true, mode: 0o700 });
+  }
+
+  const file = getRuntimeFilePath(socketDir);
+  const tmp = `${file}.tmp.${process.pid}`;
+  const json = `${JSON.stringify(record, null, 2)}\n`;
+  fs.writeFileSync(tmp, json, { mode: RUNTIME_FILE_MODE });
+  fs.renameSync(tmp, file);
+  fs.chmodSync(file, RUNTIME_FILE_MODE);
+  return record;
+}
+
+/**
+ * Best-effort delete of `<socketDir>/runtime.json`. Used during graceful
+ * shutdown so consumers immediately observe "no live postmaster" instead
+ * of seeing a stale-pid record they have to probe with `process.kill()`.
+ *
+ * Returns `true` when the file was removed, `false` when it was already
+ * gone or removal failed. Never throws — graceful shutdown must not
+ * regress because of a permission glitch on the runtime file.
+ */
+export function clearRuntimeJson(socketDir) {
+  let file;
+  try {
+    file = getRuntimeFilePath(socketDir);
+  } catch {
+    return false;
+  }
+  try {
+    fs.unlinkSync(file);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Returns true when the runtime record points at a process that's alive
+ * on this host. `process.kill(pid, 0)` is a no-signal probe — it raises
+ * ESRCH when the pid is gone and EPERM when we can't signal a foreign
+ * uid (still alive, just not ours). Treat EPERM as "alive" so cross-uid
+ * supervisors (e.g. an operator probing a system-installed pgserve)
+ * don't false-negative.
+ */
+export function isLiveRuntime(record) {
+  if (!isPlainObject(record)) return false;
+  // process.kill(pid, 0) accepts a process group sentinel for pid <= 0
+  // (pid 0 = caller's group, pid -1 = every signalable process). Neither
+  // is a meaningful "live postmaster" answer, so reject anything below 1
+  // before we touch the syscall.
+  const pid = record.autopgPid;
+  if (!Number.isInteger(pid) || pid < 1) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    return err && err.code === 'EPERM';
+  }
+}

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

package/src/provision/db-naming.js

@@ -0,0 +1,130 @@
+/**
+ * Database + role naming for `pgserve provision`.
+ *
+ * pgserve singleton (v2.4) — `pgserve-singleton-no-proxy` wish, Group 3.
+ *
+ * Postgres identifiers max out at NAMEDATALEN-1 = 63 chars (default
+ * build). Our naming has to:
+ *   1. Be deterministic: same fingerprint → same name forever, so a
+ *      re-run of `pgserve provision` is idempotent and `pgserve gc`
+ *      can correlate `pg_database` rows back to `pgserve_meta` rows.
+ *   2. Be readable: include enough of the publisher slug that an
+ *      operator looking at `\l` in psql can figure out which consumer
+ *      a database belongs to.
+ *   3. Stay under 63 chars even when the publisher is long.
+ *   4. Avoid postgres reserved keywords and quoting requirements
+ *      (lowercase + [a-z0-9_] only).
+ *
+ * Layout (≤63 chars):
+ *
+ *   pgserve_<publisher-slug>_<fingerprint-hex-12>
+ *
+ *   - prefix:           "pgserve_" (8 chars) — fixed, used by gc to
+ *                       find candidate orphans without scanning every
+ *                       postgres DB.
+ *   - publisher-slug:   sanitized + truncated package.json name /
+ *                       pgserve.publisher. Effective max ≈ 37 chars
+ *                       (computed from min(dbSlugBudget, roleSlugBudget)
+ *                       so DB and role always share the same slug for
+ *                       operator UX in `\l` / `\du`).
+ *   - fingerprint hex:  first 12 hex chars of the fingerprint. Plenty
+ *                       of entropy to avoid collisions across consumers
+ *                       on the same host.
+ *
+ * Role name uses the same identifier with `_role` suffix. Because the
+ * publisher slug is already truncated to fit the database name, we
+ * recompute the role-side budget so the role also stays ≤63 chars.
+ *
+ * Pure function: no fs / network / pg.
+ */
+
+const POSTGRES_MAX_IDENTIFIER = 63;
+const PREFIX = 'pgserve_';
+const FINGERPRINT_HEX_LEN = 12;
+const ROLE_SUFFIX = '_role';
+
+/**
+ * Lowercase + replace any char that's not [a-z0-9] with '_'. Collapses
+ * runs of '_' to a single '_' and trims leading / trailing '_'.
+ */
+export function sanitizeSlug(input) {
+  if (typeof input !== 'string') return '';
+  return input
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '_')
+    .replace(/_+/g, '_')
+    .replace(/^_|_$/g, '');
+}
+
+/**
+ * @typedef {Object} ProvisionedNames
+ * @property {string} databaseName  ≤63 chars, [a-z0-9_]+
+ * @property {string} roleName      ≤63 chars, [a-z0-9_]+
+ * @property {string} slug          the sanitized publisher slug used
+ * @property {string} fingerprintHex first 12 chars of the fingerprint
+ */
+
+/**
+ * Derive the database + role name pair from a fingerprint + publisher.
+ *
+ * @param {object} args
+ * @param {string} args.fingerprint    sha256-hex from resolveFingerprint
+ * @param {string} args.publisher      e.g. '@automagik/genie' (may be '')
+ * @returns {ProvisionedNames}
+ */
+export function deriveProvisionedNames({ fingerprint, publisher } = {}) {
+  if (typeof fingerprint !== 'string' || fingerprint.length === 0) {
+    throw new TypeError('deriveProvisionedNames: fingerprint must be a non-empty string');
+  }
+  // Hex encoding is the typical case (sha256-hex). For pinned-string
+  // fingerprints (operator escape hatch) we still accept any chars, but
+  // we strip them through the same sanitizer so the database identifier
+  // stays valid.
+  const hexLike = /^[0-9a-f]+$/.test(fingerprint);
+  const fingerprintHex = hexLike
+    ? fingerprint.slice(0, FINGERPRINT_HEX_LEN)
+    : sanitizeSlug(fingerprint).slice(0, FINGERPRINT_HEX_LEN);
+  if (fingerprintHex.length === 0) {
+    throw new Error('deriveProvisionedNames: fingerprint produced an empty hex segment');
+  }
+
+  // Database identifier:
+  //   PREFIX + slug + '_' + fingerprintHex   ≤ 63
+  // → slug budget = 63 - len(PREFIX) - 1 - len(fingerprintHex)
+  const dbSlugBudget = POSTGRES_MAX_IDENTIFIER - PREFIX.length - 1 - fingerprintHex.length;
+
+  // Role identifier (separate budget — has to also fit ROLE_SUFFIX):
+  //   PREFIX + slug + '_' + fingerprintHex + ROLE_SUFFIX   ≤ 63
+  // → slug budget = 63 - len(PREFIX) - 1 - len(fingerprintHex) - len(ROLE_SUFFIX)
+  const roleSlugBudget = dbSlugBudget - ROLE_SUFFIX.length;
+
+  // We use the smaller of the two budgets so the same slug appears in
+  // both names — operators reading `\l` and `\du` in psql see matched
+  // pairs without surprise truncation.
+  const slugBudget = Math.max(0, Math.min(dbSlugBudget, roleSlugBudget));
+
+  const fullSlug = sanitizeSlug(publisher);
+  const slug = fullSlug.slice(0, slugBudget);
+
+  const databaseName = slug.length > 0
+    ? `${PREFIX}${slug}_${fingerprintHex}`
+    : `${PREFIX}${fingerprintHex}`;
+
+  const roleName = slug.length > 0
+    ? `${PREFIX}${slug}_${fingerprintHex}${ROLE_SUFFIX}`
+    : `${PREFIX}${fingerprintHex}${ROLE_SUFFIX}`;
+
+  return {
+    databaseName,
+    roleName,
+    slug,
+    fingerprintHex,
+  };
+}
+
+export const __testInternals = Object.freeze({
+  POSTGRES_MAX_IDENTIFIER,
+  PREFIX,
+  FINGERPRINT_HEX_LEN,
+  ROLE_SUFFIX,
+});

package/src/provision/fingerprint.js

@@ -0,0 +1,144 @@
+/**
+ * Fingerprint resolver for `pgserve provision`.
+ *
+ * pgserve singleton (v2.4) — `pgserve-singleton-no-proxy` wish, Group 3.
+ *
+ * Goal: deterministically map a consumer location (cwd / explicit path /
+ * package.json contents) to a stable fingerprint string + the metadata
+ * `pgserve provision` needs to write a row into `pgserve_meta`.
+ *
+ * Fingerprint precedence (matches Decision in WISH.md §2.4):
+ *   1. If a package.json is found and declares `pgserve.fingerprint`,
+ *      use that string verbatim. (Operator escape hatch — pinned across
+ *      moves.)
+ *   2. Else if a package.json declares `name` + `version`, fingerprint =
+ *      sha256(`<name>@<version>`).
+ *   3. Else if a package.json declares `name` only, fingerprint =
+ *      sha256(`<name>`).
+ *   4. Else (no package.json or empty), fingerprint = sha256(absolute
+ *      cwd path). This is the "fallback fingerprint" the wish describes.
+ *
+ * `publisher` resolution:
+ *   - prefers `package.json#pgserve.publisher`
+ *   - falls back to `package.json#name`
+ *   - empty string when no package.json was found
+ *
+ * `sourcePath` is always the absolute filesystem path (cwd or supplied)
+ * — used by gc to detect "directory removed" orphans.
+ *
+ * Side effects: synchronous filesystem read of `<cwd>/package.json`
+ * (one open + one read; no recursion). No postgres I/O, no network, no
+ * globals. Hot-loop callers should cache the result themselves.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+
+/**
+ * @typedef {Object} ResolvedFingerprint
+ * @property {string} fingerprint   sha256-hex (64 chars) OR a literal
+ *                                  string if pgserve.fingerprint was set.
+ * @property {string} sourcePath    absolute path that was inspected.
+ * @property {string} publisher     resolved publisher; '' when unknown.
+ * @property {string} kind          'pinned' | 'name+version' | 'name' | 'cwd'
+ * @property {object} packageJson   the parsed object; null when absent.
+ */
+
+function sha256Hex(input) {
+  return crypto.createHash('sha256').update(input, 'utf8').digest('hex');
+}
+
+function readPackageJson(absDir) {
+  const candidate = path.join(absDir, 'package.json');
+  let raw;
+  try {
+    raw = fs.readFileSync(candidate, 'utf8');
+  } catch (err) {
+    if (err.code === 'ENOENT') return null;
+    throw err;
+  }
+  try {
+    const parsed = JSON.parse(raw);
+    if (!parsed || typeof parsed !== 'object') return null;
+    return parsed;
+  } catch (err) {
+    const e = new Error(`pgserve provision: package.json at ${candidate} is not valid JSON: ${err.message}`);
+    e.code = 'EFINGERPRINTPKG';
+    throw e;
+  }
+}
+
+/**
+ * Resolve a fingerprint for the given directory (defaults to cwd).
+ * @param {object} opts
+ * @param {string} [opts.cwd]            absolute or relative path to inspect
+ * @param {string} [opts.explicit]       caller-supplied fingerprint; bypasses package.json
+ * @returns {ResolvedFingerprint}
+ */
+export function resolveFingerprint(opts = {}) {
+  const cwd = path.resolve(opts.cwd || process.cwd());
+  if (typeof opts.explicit === 'string' && opts.explicit.length > 0) {
+    // Caller passed an explicit fingerprint (CLI flag / config file).
+    // We still load package.json so callers get the full publisher
+    // metadata, but the fingerprint itself comes from the operator.
+    const pkg = readPackageJson(cwd);
+    return {
+      fingerprint: opts.explicit,
+      sourcePath: cwd,
+      publisher: derivePublisher(pkg),
+      kind: 'pinned',
+      packageJson: pkg,
+    };
+  }
+  const pkg = readPackageJson(cwd);
+  if (pkg && typeof pkg.pgserve === 'object' && pkg.pgserve !== null
+      && typeof pkg.pgserve.fingerprint === 'string'
+      && pkg.pgserve.fingerprint.length > 0) {
+    return {
+      fingerprint: pkg.pgserve.fingerprint,
+      sourcePath: cwd,
+      publisher: derivePublisher(pkg),
+      kind: 'pinned',
+      packageJson: pkg,
+    };
+  }
+  if (pkg && typeof pkg.name === 'string' && pkg.name.length > 0) {
+    if (typeof pkg.version === 'string' && pkg.version.length > 0) {
+      return {
+        fingerprint: sha256Hex(`${pkg.name}@${pkg.version}`),
+        sourcePath: cwd,
+        publisher: derivePublisher(pkg),
+        kind: 'name+version',
+        packageJson: pkg,
+      };
+    }
+    return {
+      fingerprint: sha256Hex(pkg.name),
+      sourcePath: cwd,
+      publisher: derivePublisher(pkg),
+      kind: 'name',
+      packageJson: pkg,
+    };
+  }
+  return {
+    fingerprint: sha256Hex(cwd),
+    sourcePath: cwd,
+    publisher: '',
+    kind: 'cwd',
+    packageJson: null,
+  };
+}
+
+function derivePublisher(pkg) {
+  if (!pkg || typeof pkg !== 'object') return '';
+  if (typeof pkg.pgserve === 'object' && pkg.pgserve !== null
+      && typeof pkg.pgserve.publisher === 'string'
+      && pkg.pgserve.publisher.length > 0) {
+    return pkg.pgserve.publisher;
+  }
+  if (typeof pkg.name === 'string' && pkg.name.length > 0) return pkg.name;
+  return '';
+}
+
+export const __testInternals = Object.freeze({ sha256Hex, derivePublisher, readPackageJson });

package/src/schema/pgserve-meta.js

@@ -0,0 +1,120 @@
+/**
+ * `pgserve_meta` table bootstrap.
+ *
+ * pgserve singleton (v2.4) — `pgserve-singleton-no-proxy` wish, Group 3
+ * (foundation for `pgserve provision` and `pgserve gc`).
+ *
+ * Schema rationale (Decision P4 — additive across the cohort):
+ *
+ *   `pgserve_meta` is the single source of truth for "which postgres
+ *   databases on this host belong to a known pgserve consumer."
+ *   `pgserve provision` writes a row when it idempotently CREATEs a DB +
+ *   role for a fingerprint. `pgserve gc` scans the table and DROPs DBs
+ *   whose `last_used_at` is older than the configured stale threshold or
+ *   whose source_path no longer exists. The cosign verify columns
+ *   (`verified_at`, `verified_identity`, `verified_tier`) are layered on
+ *   top via `src/cosign/schema.js#applyVerifiedColumns`; they ALTER this
+ *   table after CREATE.
+ *
+ * Why a separate module from cosign/schema.js: cosign owns the
+ * verification *delta*; this module owns the *base* table. Splitting
+ * them keeps the cosign migration genuinely additive (it's a no-op on
+ * fresh DBs that haven't bootstrapped, exactly as documented in
+ * cosign-meta-migration.js).
+ *
+ * Idempotency: every statement uses `IF NOT EXISTS` (table, columns,
+ * indexes). Re-running on an already-bootstrapped database is a no-op.
+ */
+
+export const PGSERVE_META_TABLE = 'pgserve_meta';
+
+/**
+ * Base columns owned by this module. Cosign columns are owned by
+ * src/cosign/schema.js and ALTERed in afterwards.
+ */
+export const PGSERVE_META_COLUMNS = Object.freeze([
+  'fingerprint',
+  'database_name',
+  'role_name',
+  'publisher',
+  'source_path',
+  'created_at',
+  'last_used_at',
+]);
+
+/**
+ * Idempotent statements that CREATE the table + supporting indexes.
+ * Returned as an array so callers can run each one individually for
+ * clear error reporting (mirrors cosign/schema.js#getMigrationStatements).
+ *
+ * Constraints:
+ *   - fingerprint:    PRIMARY KEY — the package.json sha256 fingerprint
+ *   - database_name:  UNIQUE NOT NULL — guards against accidental dupes
+ *   - role_name:      NOT NULL — every provisioned DB has a paired role
+ *   - publisher:      nullable — older path-tier installs may have none
+ *   - source_path:    nullable — fallback fingerprint may not have one
+ *   - created_at:     NOT NULL DEFAULT now() — set on insert
+ *   - last_used_at:   NOT NULL DEFAULT now() — touched by provision; gc
+ *                     uses it as the staleness signal
+ */
+// Schema-qualified name. The upgrade pipeline probes
+// `to_regclass('public.pgserve_meta')` (cosign-meta-migration.js); if a
+// non-default search_path is configured on the active role, an
+// unqualified CREATE TABLE could land the bootstrap in a non-public
+// schema while later migrations + gc continue to look in `public.`. The
+// only safe option is to qualify both halves consistently.
+const QUALIFIED = `public.${PGSERVE_META_TABLE}`;
+
+export function getBootstrapStatements() {
+  return [
+    [
+      `CREATE TABLE IF NOT EXISTS ${QUALIFIED} (`,
+      '  fingerprint   TEXT        PRIMARY KEY,',
+      '  database_name TEXT        NOT NULL UNIQUE,',
+      '  role_name     TEXT        NOT NULL,',
+      '  publisher     TEXT,',
+      '  source_path   TEXT,',
+      '  created_at    TIMESTAMPTZ NOT NULL DEFAULT now(),',
+      '  last_used_at  TIMESTAMPTZ NOT NULL DEFAULT now()',
+      ')',
+    ].join('\n'),
+    `CREATE INDEX IF NOT EXISTS ${PGSERVE_META_TABLE}_last_used_at_idx ON ${QUALIFIED} (last_used_at)`,
+    `CREATE INDEX IF NOT EXISTS ${PGSERVE_META_TABLE}_publisher_idx ON ${QUALIFIED} (publisher)`,
+  ];
+}
+
+/**
+ * Single SQL string variant — convenient for embedding the bootstrap in
+ * a transaction or pg-init script.
+ */
+export function getBootstrapSQL() {
+  return `${getBootstrapStatements().join(';\n\n')};\n`;
+}
+
+/**
+ * Apply the bootstrap via a node-postgres-compatible client. The client
+ * must expose an async `query(sql)` method (matches both `pg.Client` and
+ * `pg.PoolClient`). Returns the list of statements executed.
+ *
+ * Statements run sequentially so a failure on the index half doesn't
+ * masquerade as success after the table half ran.
+ */
+export async function bootstrapPgserveMeta(client) {
+  if (!client || typeof client.query !== 'function') {
+    throw new TypeError('bootstrapPgserveMeta: client must expose an async query() method');
+  }
+  const statements = getBootstrapStatements();
+  for (const sql of statements) {
+    await client.query(sql);
+  }
+  return statements;
+}
+
+/**
+ * Predicate the upgrade pipeline calls before deciding whether to run
+ * the cosign-verify ALTER chain. We avoid loading pg here — callers pass
+ * the result of `SELECT to_regclass('public.pgserve_meta') IS NOT NULL`.
+ */
+export function tableExistsFromRegclass(toRegclassResult) {
+  return toRegclassResult === true;
+}