@creatornader/agent-bridge 0.4.0 → 0.5.1

package/dist/postgres-production-preflight.js

@@ -0,0 +1,249 @@
+#!/usr/bin/env node
+import {
+  loadMigrationPlan,
+  migrationRecordMatches
+} from "./chunk-QNXHDOJ5.js";
+
+// src/postgres-production-preflight.ts
+import { fileURLToPath } from "url";
+import { TLSSocket } from "tls";
+import pg from "pg";
+var SUPPORTED_MAJORS = /* @__PURE__ */ new Set([15, 16, 17, 18]);
+var LEGACY_COLUMNS = /* @__PURE__ */ new Map([
+  ["id", "int8"],
+  ["source", "text"],
+  ["category", "text"],
+  ["content", "text"],
+  ["priority", "text"],
+  ["project", "text"],
+  ["metadata", "jsonb"],
+  ["created_at", "timestamptz"],
+  ["acked_by", "_text"]
+]);
+function check(name, ok, detail) {
+  return { name, ok, detail };
+}
+function migrationPrefix(applied, expected) {
+  return applied.length <= expected.length && applied.every(
+    (entry, index) => expected[index] !== void 0 && migrationRecordMatches(entry, expected[index])
+  );
+}
+async function legacyChecks(db, checks) {
+  const owner = await db.query(`
+    SELECT relation.relowner=current_user::regrole::oid AS "ownedByCaller"
+    FROM pg_catalog.pg_class relation
+    WHERE relation.oid='public.shared_context'::regclass`);
+  checks.push(check(
+    "legacy.owner",
+    owner.rows[0]?.ownedByCaller === true,
+    "the migration authority owns public.shared_context"
+  ));
+  const columns = await db.query(`
+    SELECT column_name AS "columnName",udt_name AS "typeName"
+    FROM information_schema.columns
+    WHERE table_schema='public' AND table_name='shared_context'`);
+  const actual = new Map(columns.rows.map((row) => [row.columnName, row.typeName]));
+  const compatible = [...LEGACY_COLUMNS].every(([name, type]) => actual.get(name) === type);
+  checks.push(check(
+    "legacy.columns",
+    compatible,
+    "public.shared_context has the columns required by migration 006"
+  ));
+  if (!compatible) return void 0;
+  const legacy = await db.query(`
+    WITH mapped AS (
+      SELECT CASE
+        WHEN metadata #>> '{message_envelope,message_id}' ~* '^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$'
+          THEN lower(metadata #>> '{message_envelope,message_id}')
+        ELSE 'legacy:' || id::text
+      END AS message_id
+      FROM public.shared_context
+    )
+    SELECT
+      (SELECT count(*)::text FROM mapped) AS "rowCount",
+      (SELECT count(*)::text FROM (
+        SELECT message_id FROM mapped GROUP BY message_id HAVING count(*)>1
+      ) duplicates) AS "duplicateMessageIds"`);
+  const result = legacy.rows[0];
+  const duplicates = result?.duplicateMessageIds ?? "unknown";
+  checks.push(check(
+    "legacy.message_ids",
+    duplicates === "0",
+    "legacy rows map to unique immutable message IDs"
+  ));
+  return result?.rowCount;
+}
+async function runPostgresProductionPreflight(db, migrationsDirectory, options = {}) {
+  const expected = await loadMigrationPlan(migrationsDirectory);
+  await db.query("BEGIN TRANSACTION READ ONLY");
+  try {
+    await db.query("SET LOCAL statement_timeout='15s'");
+    await db.query("SET LOCAL lock_timeout='2s'");
+    const authority = await db.query(`
+      SELECT
+        current_setting('server_version_num') AS "serverVersionNum",
+        pg_is_in_recovery() AS "inRecovery",
+        role.rolcanlogin AS "canLogin",
+        role.rolinherit AS inherits,
+        role.rolsuper AS "isSuperuser",
+        role.rolcreaterole AS "canCreateRole",
+        role.rolbypassrls AS "bypassesRls",
+        has_database_privilege(current_user,current_database(),'CREATE') AS "canCreateDatabaseObject",
+        to_regnamespace('agent_bridge')::text AS "bridgeSchema",
+        to_regclass('agent_bridge.schema_migrations')::text AS "migrationTable",
+        to_regclass('public.shared_context')::text AS "legacyTable",
+        coalesce((SELECT ssl FROM pg_catalog.pg_stat_ssl WHERE pid=pg_backend_pid()),false) AS ssl,
+        pg_database_size(current_database())::text AS "databaseBytes"
+      FROM pg_catalog.pg_roles role
+      WHERE role.rolname=current_user`);
+    const row = authority.rows[0];
+    if (!row) throw new Error("current PostgreSQL role could not be inspected");
+    const serverMajor = Math.floor(Number(row.serverVersionNum) / 1e4);
+    const ssl = row.ssl || options.clientTransportSsl === true;
+    const checks = [
+      check("postgres.version", SUPPORTED_MAJORS.has(serverMajor), "PostgreSQL major is supported"),
+      check("postgres.primary", !row.inRecovery, "connection targets a writable primary"),
+      check("authority.login", row.canLogin && row.inherits, "migration role can log in and inherits grants"),
+      check("authority.database_create", row.canCreateDatabaseObject, "migration role can create database objects"),
+      check("authority.roles", row.isSuperuser || row.canCreateRole, "migration role can administer restricted roles"),
+      check(
+        "authority.native_dr",
+        row.isSuperuser || row.bypassesRls,
+        "native DR source role can bypass row-level security"
+      ),
+      ...options.requireSsl ? [check(
+        "connection.ssl",
+        ssl,
+        row.ssl ? "PostgreSQL backend reports TLS" : options.clientTransportSsl ? "client transport uses TLS" : "connection does not use TLS"
+      )] : []
+    ];
+    let applied = [];
+    if (row.migrationTable) {
+      const result = await db.query(
+        "SELECT version,name,checksum FROM agent_bridge.schema_migrations ORDER BY version"
+      );
+      applied = result.rows.map((entry) => ({
+        version: Number(entry.version),
+        name: entry.name,
+        checksum: entry.checksum
+      }));
+    }
+    const prefix = migrationPrefix(applied, expected);
+    const unmanagedSchema = Boolean(row.bridgeSchema) && (!row.migrationTable || applied.length === 0);
+    const migrationState = unmanagedSchema || !prefix || !row.bridgeSchema && Boolean(row.migrationTable) ? "invalid" : applied.length === expected.length ? "current" : applied.length === 0 ? "uninitialized" : "upgradeable";
+    checks.push(check(
+      "schema.migrations",
+      migrationState !== "invalid",
+      migrationState === "invalid" ? "agent_bridge namespace or migration ledger conflicts with the release plan" : `migration state is ${migrationState}`
+    ));
+    if (!row.bridgeSchema) {
+      const collisions = await db.query(`
+        WITH names(role_name) AS (VALUES
+          ('agent_bridge_runtime_' || substr(md5(current_database()),1,16)),
+          ('agent_bridge_data_owner_' || substr(md5(current_database()),1,16)),
+          ('agent_bridge_context_reader_' || substr(md5(current_database()),1,16)),
+          ('agent_bridge_event_writer_' || substr(md5(current_database()),1,16)),
+          ('agent_bridge_control_owner_' || substr(md5(current_database()),1,16)),
+          ('agent_bridge_control_operator_' || substr(md5(current_database()),1,16)),
+          ('agent_bridge_control_auditor_' || substr(md5(current_database()),1,16)),
+          ('agent_bridge_archive_operator_' || substr(md5(current_database()),1,16)),
+          ('agent_bridge_backup_reader_' || substr(md5(current_database()),1,16))
+        )
+        SELECT count(*)::text AS count FROM names JOIN pg_catalog.pg_roles role
+          ON role.rolname=names.role_name`);
+      checks.push(check(
+        "schema.role_collisions",
+        collisions.rows[0]?.count === "0",
+        "no derived Agent Bridge roles predate the schema"
+      ));
+    }
+    let legacyRows;
+    if (row.legacyTable && applied.length < 6) {
+      legacyRows = await legacyChecks(db, checks);
+    }
+    await db.query("COMMIT");
+    return {
+      schema: "agent-bridge-postgres-production-preflight-v1",
+      ok: checks.every((entry) => entry.ok),
+      checks,
+      observations: {
+        serverMajor,
+        databaseBytes: row.databaseBytes,
+        migrationState,
+        appliedMigrationCount: applied.length,
+        requiredMigrationCount: expected.length,
+        legacyTable: Boolean(row.legacyTable),
+        ...legacyRows === void 0 ? {} : { legacyRows },
+        ssl
+      }
+    };
+  } catch (error) {
+    await db.query("ROLLBACK").catch(() => void 0);
+    throw error;
+  }
+}
+function parseArguments(args) {
+  const options = { json: false, help: false, requireSsl: false };
+  for (const argument of args) {
+    if (argument === "--json") options.json = true;
+    else if (argument === "--require-ssl") options.requireSsl = true;
+    else if (argument === "--help" || argument === "-h") options.help = true;
+    else throw new Error(`unknown argument: ${argument}`);
+  }
+  return options;
+}
+function safeError(error, secret) {
+  const message = error instanceof Error ? error.message : String(error);
+  return message.split(secret).join("[redacted]").replace(/postgres(?:ql)?:\/\/\S+/giu, "[redacted]");
+}
+async function main() {
+  const options = parseArguments(process.argv.slice(2));
+  if (options.help) {
+    process.stdout.write("Usage: npm run preflight:postgres:production -- [--json] [--require-ssl]\n");
+    return;
+  }
+  const databaseUrl = process.env.AGENT_BRIDGE_DATABASE_URL;
+  if (!databaseUrl) throw new Error("AGENT_BRIDGE_DATABASE_URL is required");
+  const client = new pg.Client({
+    connectionString: databaseUrl,
+    connectionTimeoutMillis: 1e4,
+    application_name: "agent-bridge-production-preflight"
+  });
+  try {
+    await client.connect();
+    const clientTransportSsl = client.connection.stream instanceof TLSSocket && client.connection.stream.encrypted;
+    const migrationsDirectory = fileURLToPath(new URL("../sql/migrations", import.meta.url));
+    const report = await runPostgresProductionPreflight({
+      query: (sql) => client.query(sql)
+    }, migrationsDirectory, {
+      requireSsl: options.requireSsl,
+      clientTransportSsl
+    });
+    if (options.json) process.stdout.write(`${JSON.stringify(report)}
+`);
+    else {
+      for (const entry of report.checks) {
+        process.stdout.write(`${entry.ok ? "OK" : "ERROR"} ${entry.name}: ${entry.detail}
+`);
+      }
+      process.stdout.write(`${report.ok ? "PostgreSQL production preflight passed" : "PostgreSQL production preflight failed"}
+`);
+    }
+    if (!report.ok) process.exitCode = 1;
+  } catch (error) {
+    throw new Error(safeError(error, databaseUrl));
+  } finally {
+    await client.end().catch(() => void 0);
+  }
+}
+if (process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1]) {
+  void main().catch((error) => {
+    process.stderr.write(`${error instanceof Error ? error.message : String(error)}
+`);
+    process.exitCode = 1;
+  });
+}
+export {
+  runPostgresProductionPreflight
+};
+//# sourceMappingURL=postgres-production-preflight.js.map

package/dist/postgres-production-preflight.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/postgres-production-preflight.ts"],"sourcesContent":["import { fileURLToPath } from \"node:url\";\nimport { TLSSocket } from \"node:tls\";\nimport pg from \"pg\";\nimport { loadMigrationPlan, migrationRecordMatches, type AppliedMigration } from \"./migrations.js\";\n\nconst SUPPORTED_MAJORS = new Set([15, 16, 17, 18]);\nconst LEGACY_COLUMNS = new Map([\n  [\"id\", \"int8\"],\n  [\"source\", \"text\"],\n  [\"category\", \"text\"],\n  [\"content\", \"text\"],\n  [\"priority\", \"text\"],\n  [\"project\", \"text\"],\n  [\"metadata\", \"jsonb\"],\n  [\"created_at\", \"timestamptz\"],\n  [\"acked_by\", \"_text\"],\n]);\n\ninterface Check {\n  name: string;\n  ok: boolean;\n  detail: string;\n}\n\ninterface ProductionPreflightDatabase {\n  query<T extends Record<string, unknown> = Record<string, unknown>>(\n    sql: string,\n  ): Promise<{ rows: T[]; rowCount: number | null }>;\n}\n\ninterface AuthorityRow extends Record<string, unknown> {\n  serverVersionNum: string;\n  inRecovery: boolean;\n  canLogin: boolean;\n  inherits: boolean;\n  isSuperuser: boolean;\n  canCreateRole: boolean;\n  bypassesRls: boolean;\n  canCreateDatabaseObject: boolean;\n  bridgeSchema: string | null;\n  migrationTable: string | null;\n  legacyTable: string | null;\n  ssl: boolean;\n  databaseBytes: string;\n}\n\ninterface LegacyColumnRow extends Record<string, unknown> {\n  columnName: string;\n  typeName: string;\n}\n\nexport interface PostgresProductionPreflightReport {\n  schema: \"agent-bridge-postgres-production-preflight-v1\";\n  ok: boolean;\n  checks: Check[];\n  observations: {\n    serverMajor: number;\n    databaseBytes: string;\n    migrationState: \"uninitialized\" | \"upgradeable\" | \"current\" | \"invalid\";\n    appliedMigrationCount: number;\n    requiredMigrationCount: number;\n    legacyTable: boolean;\n    legacyRows?: string;\n    ssl: boolean;\n  };\n}\n\nfunction check(name: string, ok: boolean, detail: string): Check {\n  return { name, ok, detail };\n}\n\nfunction migrationPrefix(\n  applied: AppliedMigration[],\n  expected: ReadonlyArray<AppliedMigration>,\n): boolean {\n  return applied.length <= expected.length && applied.every((entry, index) =>\n    expected[index] !== undefined && migrationRecordMatches(entry, expected[index])\n  );\n}\n\nasync function legacyChecks(\n  db: ProductionPreflightDatabase,\n  checks: Check[],\n): Promise<string | undefined> {\n  const owner = await db.query<{ ownedByCaller: boolean }>(`\n    SELECT relation.relowner=current_user::regrole::oid AS \"ownedByCaller\"\n    FROM pg_catalog.pg_class relation\n    WHERE relation.oid='public.shared_context'::regclass`);\n  checks.push(check(\n    \"legacy.owner\",\n    owner.rows[0]?.ownedByCaller === true,\n    \"the migration authority owns public.shared_context\",\n  ));\n\n  const columns = await db.query<LegacyColumnRow>(`\n    SELECT column_name AS \"columnName\",udt_name AS \"typeName\"\n    FROM information_schema.columns\n    WHERE table_schema='public' AND table_name='shared_context'`);\n  const actual = new Map(columns.rows.map((row) => [row.columnName, row.typeName]));\n  const compatible = [...LEGACY_COLUMNS].every(([name, type]) => actual.get(name) === type);\n  checks.push(check(\n    \"legacy.columns\",\n    compatible,\n    \"public.shared_context has the columns required by migration 006\",\n  ));\n\n  if (!compatible) return undefined;\n  const legacy = await db.query<{ rowCount: string; duplicateMessageIds: string }>(`\n    WITH mapped AS (\n      SELECT CASE\n        WHEN metadata #>> '{message_envelope,message_id}' ~* '^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$'\n          THEN lower(metadata #>> '{message_envelope,message_id}')\n        ELSE 'legacy:' || id::text\n      END AS message_id\n      FROM public.shared_context\n    )\n    SELECT\n      (SELECT count(*)::text FROM mapped) AS \"rowCount\",\n      (SELECT count(*)::text FROM (\n        SELECT message_id FROM mapped GROUP BY message_id HAVING count(*)>1\n      ) duplicates) AS \"duplicateMessageIds\"`);\n  const result = legacy.rows[0];\n  const duplicates = result?.duplicateMessageIds ?? \"unknown\";\n  checks.push(check(\n    \"legacy.message_ids\",\n    duplicates === \"0\",\n    \"legacy rows map to unique immutable message IDs\",\n  ));\n  return result?.rowCount;\n}\n\nexport async function runPostgresProductionPreflight(\n  db: ProductionPreflightDatabase,\n  migrationsDirectory: string,\n  options: { requireSsl?: boolean; clientTransportSsl?: boolean } = {},\n): Promise<PostgresProductionPreflightReport> {\n  const expected = await loadMigrationPlan(migrationsDirectory);\n  await db.query(\"BEGIN TRANSACTION READ ONLY\");\n  try {\n    await db.query(\"SET LOCAL statement_timeout='15s'\");\n    await db.query(\"SET LOCAL lock_timeout='2s'\");\n    const authority = await db.query<AuthorityRow>(`\n      SELECT\n        current_setting('server_version_num') AS \"serverVersionNum\",\n        pg_is_in_recovery() AS \"inRecovery\",\n        role.rolcanlogin AS \"canLogin\",\n        role.rolinherit AS inherits,\n        role.rolsuper AS \"isSuperuser\",\n        role.rolcreaterole AS \"canCreateRole\",\n        role.rolbypassrls AS \"bypassesRls\",\n        has_database_privilege(current_user,current_database(),'CREATE') AS \"canCreateDatabaseObject\",\n        to_regnamespace('agent_bridge')::text AS \"bridgeSchema\",\n        to_regclass('agent_bridge.schema_migrations')::text AS \"migrationTable\",\n        to_regclass('public.shared_context')::text AS \"legacyTable\",\n        coalesce((SELECT ssl FROM pg_catalog.pg_stat_ssl WHERE pid=pg_backend_pid()),false) AS ssl,\n        pg_database_size(current_database())::text AS \"databaseBytes\"\n      FROM pg_catalog.pg_roles role\n      WHERE role.rolname=current_user`);\n    const row = authority.rows[0];\n    if (!row) throw new Error(\"current PostgreSQL role could not be inspected\");\n\n    const serverMajor = Math.floor(Number(row.serverVersionNum) / 10_000);\n    const ssl = row.ssl || options.clientTransportSsl === true;\n    const checks: Check[] = [\n      check(\"postgres.version\", SUPPORTED_MAJORS.has(serverMajor), \"PostgreSQL major is supported\"),\n      check(\"postgres.primary\", !row.inRecovery, \"connection targets a writable primary\"),\n      check(\"authority.login\", row.canLogin && row.inherits, \"migration role can log in and inherits grants\"),\n      check(\"authority.database_create\", row.canCreateDatabaseObject, \"migration role can create database objects\"),\n      check(\"authority.roles\", row.isSuperuser || row.canCreateRole, \"migration role can administer restricted roles\"),\n      check(\n        \"authority.native_dr\",\n        row.isSuperuser || row.bypassesRls,\n        \"native DR source role can bypass row-level security\",\n      ),\n      ...(options.requireSsl\n        ? [check(\n          \"connection.ssl\",\n          ssl,\n          row.ssl\n            ? \"PostgreSQL backend reports TLS\"\n            : options.clientTransportSsl\n              ? \"client transport uses TLS\"\n              : \"connection does not use TLS\",\n        )]\n        : []),\n    ];\n\n    let applied: AppliedMigration[] = [];\n    if (row.migrationTable) {\n      const result = await db.query<{ version: number; name: string; checksum: string }>(\n        \"SELECT version,name,checksum FROM agent_bridge.schema_migrations ORDER BY version\",\n      );\n      applied = result.rows.map((entry) => ({\n        version: Number(entry.version),\n        name: entry.name,\n        checksum: entry.checksum,\n      }));\n    }\n    const prefix = migrationPrefix(applied, expected);\n    const unmanagedSchema = Boolean(row.bridgeSchema) && (\n      !row.migrationTable || applied.length === 0\n    );\n    const migrationState = unmanagedSchema || !prefix || (!row.bridgeSchema && Boolean(row.migrationTable))\n      ? \"invalid\"\n      : applied.length === expected.length\n        ? \"current\"\n        : applied.length === 0\n          ? \"uninitialized\"\n          : \"upgradeable\";\n    checks.push(check(\n      \"schema.migrations\",\n      migrationState !== \"invalid\",\n      migrationState === \"invalid\"\n        ? \"agent_bridge namespace or migration ledger conflicts with the release plan\"\n        : `migration state is ${migrationState}`,\n    ));\n\n    if (!row.bridgeSchema) {\n      const collisions = await db.query<{ count: string }>(`\n        WITH names(role_name) AS (VALUES\n          ('agent_bridge_runtime_' || substr(md5(current_database()),1,16)),\n          ('agent_bridge_data_owner_' || substr(md5(current_database()),1,16)),\n          ('agent_bridge_context_reader_' || substr(md5(current_database()),1,16)),\n          ('agent_bridge_event_writer_' || substr(md5(current_database()),1,16)),\n          ('agent_bridge_control_owner_' || substr(md5(current_database()),1,16)),\n          ('agent_bridge_control_operator_' || substr(md5(current_database()),1,16)),\n          ('agent_bridge_control_auditor_' || substr(md5(current_database()),1,16)),\n          ('agent_bridge_archive_operator_' || substr(md5(current_database()),1,16)),\n          ('agent_bridge_backup_reader_' || substr(md5(current_database()),1,16))\n        )\n        SELECT count(*)::text AS count FROM names JOIN pg_catalog.pg_roles role\n          ON role.rolname=names.role_name`);\n      checks.push(check(\n        \"schema.role_collisions\",\n        collisions.rows[0]?.count === \"0\",\n        \"no derived Agent Bridge roles predate the schema\",\n      ));\n    }\n\n    let legacyRows: string | undefined;\n    if (row.legacyTable && applied.length < 6) {\n      legacyRows = await legacyChecks(db, checks);\n    }\n\n    await db.query(\"COMMIT\");\n    return {\n      schema: \"agent-bridge-postgres-production-preflight-v1\",\n      ok: checks.every((entry) => entry.ok),\n      checks,\n      observations: {\n        serverMajor,\n        databaseBytes: row.databaseBytes,\n        migrationState,\n        appliedMigrationCount: applied.length,\n        requiredMigrationCount: expected.length,\n        legacyTable: Boolean(row.legacyTable),\n        ...(legacyRows === undefined ? {} : { legacyRows }),\n        ssl,\n      },\n    };\n  } catch (error) {\n    await db.query(\"ROLLBACK\").catch(() => undefined);\n    throw error;\n  }\n}\n\nfunction parseArguments(args: string[]): { json: boolean; help: boolean; requireSsl: boolean } {\n  const options = { json: false, help: false, requireSsl: false };\n  for (const argument of args) {\n    if (argument === \"--json\") options.json = true;\n    else if (argument === \"--require-ssl\") options.requireSsl = true;\n    else if (argument === \"--help\" || argument === \"-h\") options.help = true;\n    else throw new Error(`unknown argument: ${argument}`);\n  }\n  return options;\n}\n\nfunction safeError(error: unknown, secret: string): string {\n  const message = error instanceof Error ? error.message : String(error);\n  return message.split(secret).join(\"[redacted]\").replace(/postgres(?:ql)?:\\/\\/\\S+/giu, \"[redacted]\");\n}\n\nasync function main(): Promise<void> {\n  const options = parseArguments(process.argv.slice(2));\n  if (options.help) {\n    process.stdout.write(\"Usage: npm run preflight:postgres:production -- [--json] [--require-ssl]\\n\");\n    return;\n  }\n  const databaseUrl = process.env.AGENT_BRIDGE_DATABASE_URL;\n  if (!databaseUrl) throw new Error(\"AGENT_BRIDGE_DATABASE_URL is required\");\n  const client = new pg.Client({\n    connectionString: databaseUrl,\n    connectionTimeoutMillis: 10_000,\n    application_name: \"agent-bridge-production-preflight\",\n  });\n  try {\n    await client.connect();\n    const clientTransportSsl = client.connection.stream instanceof TLSSocket &&\n      client.connection.stream.encrypted;\n    const migrationsDirectory = fileURLToPath(new URL(\"../sql/migrations\", import.meta.url));\n    const report = await runPostgresProductionPreflight({\n      query: (sql) => client.query(sql),\n    }, migrationsDirectory, {\n      requireSsl: options.requireSsl,\n      clientTransportSsl,\n    });\n    if (options.json) process.stdout.write(`${JSON.stringify(report)}\\n`);\n    else {\n      for (const entry of report.checks) {\n        process.stdout.write(`${entry.ok ? \"OK\" : \"ERROR\"} ${entry.name}: ${entry.detail}\\n`);\n      }\n      process.stdout.write(`${report.ok ? \"PostgreSQL production preflight passed\" : \"PostgreSQL production preflight failed\"}\\n`);\n    }\n    if (!report.ok) process.exitCode = 1;\n  } catch (error) {\n    throw new Error(safeError(error, databaseUrl));\n  } finally {\n    await client.end().catch(() => undefined);\n  }\n}\n\nif (process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1]) {\n  void main().catch((error) => {\n    process.stderr.write(`${error instanceof Error ? error.message : String(error)}\\n`);\n    process.exitCode = 1;\n  });\n}\n"],"mappings":"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","names":[]}

package/dist/server.js

@@ -4,16 +4,16 @@ import {
   configFromEnv,
   createAgentBridgeServer,
   startServer
-} from "./chunk-SYGONYMM.js";
+} from "./chunk-HUHG7XTB.js";
 import "./chunk-2EVLG3YA.js";
-import "./chunk-MCKKVNCE.js";
-import "./chunk-LAHNQZDN.js";
-import "./chunk-SV3SVBYS.js";
-import "./chunk-DQOZJJZ2.js";
+import "./chunk-QPC6JHA3.js";
+import "./chunk-Z6JP6MYD.js";
+import "./chunk-SN7PIVDF.js";
+import "./chunk-IVG4XWWS.js";
 import "./chunk-GTK4KOED.js";
 import "./chunk-VOQIDTCJ.js";
-import "./chunk-4VB44KJU.js";
-import "./chunk-IHZFI7TH.js";
+import "./chunk-AWE3DFZV.js";
+import "./chunk-E4OWHGUE.js";
 import "./chunk-BZLMF5O5.js";
 export {
   MCP_IMPLEMENTATION_VERSION,

package/dist/{sqlite-edge-store-Bc15DvpX.d.ts → sqlite-edge-store-CdMIOrho.d.ts}

@@ -1,5 +1,5 @@
 import { b as BridgeMessage, c as BridgePrincipal } from './bridge-domain-CBX3IVqC.js';
-import { d as MessageQuery, M as MessagePage } from './bridge-store-Boaj-ZbO.js';
+import { d as MessageQuery, M as MessagePage } from './bridge-store-ByJ6CaJk.js';
 
 type PendingMessage = Omit<BridgeMessage, "sequence" | "createdAt">;
 interface EdgeScope {

package/dist/sqlite.d.ts

@@ -1,7 +1,7 @@
 import { c as BridgePrincipal, B as BridgeDelivery, g as DeliveryState, R as RetryPolicy, A as AgentPresence, b as BridgeMessage, a as BridgeDeliveryEvent } from './bridge-domain-CBX3IVqC.js';
-import { M as MessagePage, B as BridgeDiagnostics, I as InsertMessageResult, a as BridgeStore, d as MessageQuery, C as ClaimOptions, c as DeliveryQuery, b as DeliveryPage, D as DeliveryEventPage } from './bridge-store-Boaj-ZbO.js';
-import { e as EdgeMigrationGateState, S as SQLiteEdgeStore, a as EdgeDrainLease, P as PendingMessage } from './sqlite-edge-store-Bc15DvpX.js';
-export { E as EdgeConflictError, b as EdgeEnqueueResult, c as EdgeMigrationDrainingError, d as EdgeMigrationGate, f as EdgeMigrationLeaseError, g as EdgeMigrationRetiredError, h as EdgeOutboxRecord, i as EdgeReadOnlyInspection, j as EdgeScope, k as EdgeStats, l as edgeMessageFingerprint, m as edgeScopeKey, n as inspectEdgeScopeReadOnly, s as stableIdempotency } from './sqlite-edge-store-Bc15DvpX.js';
+import { M as MessagePage, B as BridgeDiagnostics, I as InsertMessageResult, a as BridgeStore, d as MessageQuery, C as ClaimOptions, c as DeliveryQuery, b as DeliveryPage, D as DeliveryEventPage } from './bridge-store-ByJ6CaJk.js';
+import { e as EdgeMigrationGateState, S as SQLiteEdgeStore, a as EdgeDrainLease, P as PendingMessage } from './sqlite-edge-store-CdMIOrho.js';
+export { E as EdgeConflictError, b as EdgeEnqueueResult, c as EdgeMigrationDrainingError, d as EdgeMigrationGate, f as EdgeMigrationLeaseError, g as EdgeMigrationRetiredError, h as EdgeOutboxRecord, i as EdgeReadOnlyInspection, j as EdgeScope, k as EdgeStats, l as edgeMessageFingerprint, m as edgeScopeKey, n as inspectEdgeScopeReadOnly, s as stableIdempotency } from './sqlite-edge-store-CdMIOrho.js';
 
 interface SyncInsertResult extends InsertMessageResult {
     disposition: "committed" | "queued";

package/dist/sqlite.js

@@ -11,10 +11,10 @@ import {
   inspectEdgeScopeReadOnly,
   isRetryableSyncError,
   stableIdempotency
-} from "./chunk-SV3SVBYS.js";
+} from "./chunk-SN7PIVDF.js";
 import {
   SQLiteBridgeStore
-} from "./chunk-DQOZJJZ2.js";
+} from "./chunk-IVG4XWWS.js";
 import "./chunk-GTK4KOED.js";
 import "./chunk-VOQIDTCJ.js";
 import "./chunk-BZLMF5O5.js";

package/docs/architecture-v2.md

@@ -40,6 +40,22 @@ receives no schema-owner authority. Its readiness check fails on an incomplete
 migration plan, unsupported PostgreSQL major, row-isolation drift, protected catalog
 drift, or an invalid owner-control membership graph.
 
+Runtime bootstrap runs in one transaction. Before it changes an existing login, it
+rejects every database-derived Agent Bridge authority name, unexpected role edge, and
+object owner. PostgreSQL 16 and newer may add one managed-provider administrator edge
+when the schema owner creates the login. The bootstrap validates that edge exactly. It
+does not adopt a `NOLOGIN` shell restored by native DR.
+
+The schema owner can be a true superuser or a managed-provider administrator with
+`CREATEROLE`. That authority is sufficient for migrations. Native backup requires the
+schema owner to be a true superuser or hold `BYPASSRLS`. A restore target validates the
+intentionally suspended restored schema-owner shell through its superuser session. PostgreSQL 16 and newer may
+split its authority over an internal role between a bootstrap administrator row and a
+schema-owner inherit-and-set row. Native DR may restore the same effective authority as
+one combined bootstrap-superuser row. Security checks aggregate the effective options
+but also validate each allowed physical grant shape. Registered operator and archive
+memberships remain single, schema-owner-granted edges without the admin option.
+
 The repository Compose stack publishes the gateway and PostgreSQL on loopback for
 development. Production deployments put PostgreSQL on a private network, terminate TLS
 before every non-loopback gateway, and source credentials from the platform's secret
@@ -168,9 +184,24 @@ server major, an exact-major `pg_restore`, and superuser authority. It restores
 shells as `NOLOGIN`, then schema objects, memberships, and default privileges. Claimed
 deliveries become retrying deliveries with cleared leases. The restore checks migrations,
 counts, role inventory, and every readiness attestation before success. External
-principals remain `NOLOGIN`. A failure after target mutation begins disables new target
-connections. If that offlining step fails, the command reports the target as unsafe and
-lists residual role shells.
+principals remain `NOLOGIN`. Runtime memberships are omitted. Active control and archive
+memberships are omitted and receive explicit revocation events after their prior history.
+A matching schema-owner role may be reused only when it is the target session user and
+a true superuser. Every other role collision fails. A failure after target mutation
+begins disables new target connections. If that offlining step fails, the command
+reports the target as unsafe and lists residual role shells.
+
+Managed schema owners need read access to protected ledgers and sequences before
+`pg_dump` can produce a complete native backup. A database-derived `NOLOGIN`
+backup-reader role receives only that access and is granted only to the schema owner.
+Native backup requires that schema owner to be a true superuser or hold `BYPASSRLS`.
+During restore, the target superuser may validate the intentionally suspended restored
+schema-owner shell. A restricted runtime login cannot substitute for that authority.
+`CREATEROLE` alone can apply migrations but cannot produce a complete native backup.
+Native-backup readiness attests the role, authority, membership, and object ACLs. The
+gateway and external operator roles cannot inherit the reader. This backup gate is
+separate from gateway runtime readiness, so drift in an owner-only backup object cannot
+take a healthy gateway out of service.
 
 PostgreSQL source and target URLs come only from
 `AGENT_BRIDGE_DR_SOURCE_DATABASE_URL` and
@@ -208,7 +239,7 @@ A receipt records that a principal read a message.
 
 A publisher stores an immutable `deliveryPolicy` with each message. Untargeted messages default to mailbox mode. Targeted messages default to leased mode with `maxAttempts: 5`, `retryBaseDelayMs: 1000`, `retryMaxDelayMs: 60000`, and `retryJitterRatio: 0.2`. Leased policy may also set `notBefore`. Mailbox messages create no deliveries, and legacy mode rejects leased policy.
 
-A leased delivery records executable work for a recipient. Its state is one of `pending`, `claimed`, `acked`, `retrying`, `dead`, or `cancelled`. `attempt` is lifetime-monotonic, while `cycleAttempt` resets on publisher requeue and `requeueCount` increments. Stored policy owns retry and exhaustion. Claims order due work by urgent, high, then info priority, followed by availability, message creation time, and the stable delivery ID tie-break.
+A leased delivery records executable work for a recipient. Its state is one of `pending`, `claimed`, `acked`, `retrying`, `dead`, or `cancelled`. `attempt` is lifetime-monotonic, while `cycleAttempt` resets on publisher requeue and `requeueCount` increments. Stored policy owns retry and exhaustion. Claims order due work by urgent, high, then info priority, followed by availability, message creation time, and the stable delivery ID tie-break. HTTP 2.1, MCP, and CLI may optionally identify one message. That form atomically selects only the eligible delivery for the authenticated recipient and scopes claim-time expiry and exhaustion maintenance to the same message. Omitting the filter preserves claim-next behavior. The frozen HTTP 2.0 request rejects the additive field.
 
 Consumer-side `maxAttempts` on claim and `retryPolicy` on nack are compatibility inputs for one release. The service validates them and ignores them. This keeps older clients working without letting a consumer change immutable publisher intent.
 
@@ -512,7 +543,7 @@ must already satisfy that final policy. Node identity and file-type checks run b
 and after the native policy check. Native reparse attributes
 reject symlinks, junctions, and other reparse objects before and after DACL work.
 
-The schema owner is the trusted offline role administrator. It holds all three control roles with the admin option and registers eligible login roles through `register_control_member`; `revoke_control_member` removes them. Those functions are not available through HTTP or MCP. Each call is idempotent by request UUID and appends the database session actor to the membership ledger. Runtime readiness compares the active registry with the full `pg_has_role` closure and the direct `pg_auth_members` edges. It rejects unregistered operator or auditor holders, every external owner holder, missing registered grants, unsafe login attributes, extra roles inherited by a registered member, and roles that inherit a registered member. Direct edges must retain their expected grantor, admin, inherit, and set options. Only the schema owner is exempt from the broad closure check because a PostgreSQL superuser reports membership across roles. A direct `GRANT` is never a valid deployment shortcut.
+The schema owner is the trusted offline role administrator. It holds all three control roles with effective admin, inherit, and set authority and registers eligible login roles through `register_control_member`; `revoke_control_member` removes them. Those functions are not available through HTTP or MCP. Each call is idempotent by request UUID and appends the database session actor to the membership ledger. Runtime readiness compares the active registry with the full `pg_has_role` closure and normalized direct `pg_auth_members` edges. It also checks the raw grant origins and option shapes. It rejects unregistered operator or auditor holders, every external owner holder, missing registered grants, unsafe login attributes, extra roles inherited by a registered member, and roles that inherit a registered member. Only the schema owner is exempt from the broad closure check because a PostgreSQL superuser reports membership across roles. A direct `GRANT` is never a valid deployment shortcut.
 
 Every protected operation first locks a member-global key for `session_user`, followed by capability keys in operator-before-auditor order. It then checks the active registry, direct membership edge, safe login attributes, and complete upstream and downstream role closure. Inventory accepts either registered capability. Registration and revocation use the same global-first lock hierarchy. Opposite operator and auditor changes for one member therefore cannot deadlock. A revocation waits for an operation that already passed authorization, while every operation begun after revocation observes the new state. A session that remains in a revoked role through `SET ROLE` cannot use that stale authorization.
 

package/docs/deployment.md

@@ -119,6 +119,26 @@ Keep these authorities separate:
 | Archive operator | Portable PostgreSQL archive operations | Never |
 | Backup and restore | Native DR backup or restore | Never |
 
+The schema owner may be a true PostgreSQL superuser or a managed-provider
+administrator with `CREATEROLE` and the database privileges reported by the production
+preflight. `CREATEROLE` is sufficient for migrations. Native backup requires the
+schema owner to be a true superuser or hold `BYPASSRLS`. A restore target validates the
+intentionally suspended restored schema-owner shell through its superuser session. Migrations create internal
+roles with safe defaults and reject unsafe preexisting roles instead of trying to demote
+them. PostgreSQL 16 and newer may store the schema owner's effective admin, inherit,
+and set authority in two physical grant rows. A native DR restore may recreate it as one
+combined bootstrap-superuser grant. Agent Bridge validates both forms and their
+effective authority. The restricted runtime login must never receive either schema-owner
+authority or `BYPASSRLS`.
+
+Migration 021 creates a database-derived `NOLOGIN` backup-reader role. It receives
+`SELECT` on Agent Bridge tables and sequences and is granted only to the schema owner.
+This lets a managed schema owner retain `BYPASSRLS` while producing a complete native
+backup. Do not grant the reader to the runtime login, control members, archive members,
+or another external principal. Native backup and restore require this attestation.
+Gateway runtime readiness does not, so an owner-only backup fault cannot stop normal
+gateway traffic.
+
 Use the platform's secret manager or private mounted secret files. Do not put raw
 passwords, tokens, or complete database URLs in image layers, source control, command
 arguments, deployment logs, or shared client config. Rotate each authority on its own
@@ -127,6 +147,143 @@ schedule and after any suspected exposure.
 The runtime database password must contain at least 32 characters. The bootstrap job
 fails before role creation or alteration when the mounted value is shorter.
 
+## Fly.io reference hosting
+
+[`deploy/fly.toml`](../deploy/fly.toml) is the maintained Fly gateway contract. It has
+no app name, region, or release command. The operator chooses the account, app, region,
+PostgreSQL service, and public hostname. Fly terminates HTTPS and forwards to port
+8787. The service keeps at least one `shared-cpu-1x` machine with 512 MB running, checks
+`GET /readyz`, and gives the Node process 30 seconds after SIGTERM to close listeners
+and database pools.
+
+Run the repository check before any Fly action:
+
+```bash
+npm run preflight:fly -- --json
+```
+
+The local check verifies Node, the Dockerfile, and the static Fly contract. If the app
+already exists, add its name:
+
+```bash
+npm run preflight:fly -- --app <app> --json
+```
+
+With `--app`, the command invokes only read-only Fly commands. It observes the active
+account, app status, effective config, machines, and secret names. Its JSON includes
+names and check results but never environment-variable values. A passing local check
+does not prove that an external resource exists or that deployment is safe.
+
+The long-running Fly machine may receive only the restricted
+`AGENT_BRIDGE_RUNTIME_DATABASE_URL` database authority and the public CA bundle in
+`AGENT_BRIDGE_RUNTIME_DATABASE_CA_BASE64`. The gateway decodes the CA in memory,
+removes `sslmode` and `sslrootcert` from the URL, and enables certificate and hostname
+verification. It rejects the `ssl` parameter and client-certificate file parameters.
+Do not give it
+`AGENT_BRIDGE_DATABASE_URL`, `AGENT_BRIDGE_OPERATOR_DATABASE_URL`,
+`AGENT_BRIDGE_RUNTIME_PASSWORD`, a client bearer token, or a Supabase client key. The
+preflight rejects those names. Keep schema-owner, control-operator, archive, and DR
+authority in separate operator jobs.
+
+Import both runtime secrets through stdin so neither value appears in command
+arguments or a temporary file:
+
+```bash
+{
+  printf 'AGENT_BRIDGE_RUNTIME_DATABASE_URL=%s\n' "$(tr -d '\r\n' < runtime-url)"
+  printf 'AGENT_BRIDGE_RUNTIME_DATABASE_CA_BASE64=%s\n' "$(base64 < database-ca.pem | tr -d '\r\n')"
+} | fly secrets import --stage --app <app>
+```
+
+### Operator order and gates
+
+The following actions change external state and require an operator gate. The
+repository does not perform them:
+
+1. Create or select the Fly app and PostgreSQL authority. Keep PostgreSQL private.
+2. Run the read-only production database preflight before any backup or migration:
+
+   ```bash
+   AGENT_BRIDGE_DATABASE_URL="..." npm run preflight:postgres:production -- --json --require-ssl
+   ```
+
+   The command opens a read-only transaction and reports only nonsecret capability
+   and schema facts. `authority.roles` reports migration authority. `authority.native_dr`
+   reports whether the source schema owner is a true superuser or has `BYPASSRLS`. A
+   `CREATEROLE` role can pass the migration check while failing the native DR check.
+   The command also checks supported server majors, migration-ledger drift, derived-role
+   collisions, and the legacy import shape. The PostgreSQL 15 through 18 test matrix
+   separately applies the full migration plan as both a superuser and a
+   managed-provider-style `CREATEROLE` administrator. `--require-ssl` is required for a
+   public database endpoint. The preflight cannot prove that later DDL will succeed. For
+   a session pooler, it checks the client TLS socket because PostgreSQL reports the
+   pooler's separate database connection.
+3. Take and verify a native DR backup when upgrading an existing authority.
+4. Run `agent-bridge migrate` once in an isolated job with
+   `AGENT_BRIDGE_DATABASE_URL`. Drain old gateways first when the migration notes
+   require it.
+5. Run [`deploy/bootstrap-runtime.sql`](../deploy/bootstrap-runtime.sql) through a
+   separate trusted PostgreSQL session. Supply the schema-owner connection and the
+   runtime password to that job only. The bootstrap is transactional and changes an
+   existing login only when its attributes, ownership, and membership graph already
+   match the recorded runtime contract. It never adopts a restored `NOLOGIN` shell.
+6. Construct the restricted runtime URL. Import it and the base64-encoded PostgreSQL CA
+   as the two runtime secrets shown above, then run the app-aware read-only preflight.
+7. Deploy the immutable image with `fly deploy --config deploy/fly.toml --app <app>`.
+   Require `/readyz` before routing clients.
+8. Run authenticated capability and status probes, then publish, pull, claim, and
+   settle a disposable targeted delivery.
+9. Move clients only after the gateway proof passes. Preserve every source edge store
+   until its outbox is empty.
+
+App creation, database provisioning, secret writes, migration, bootstrap, deployment,
+traffic changes, and client cutover are all gated external actions. The preflight is
+read-only and cannot authorize any of them.
+
+### Fly rollback boundary
+
+Before migration, stop a failed deployment and keep the prior image and authority. A
+failed image rollout after a compatible migration can return traffic to the prior
+image only if that image accepts the current schema. Never assume that an older image
+can run against newer migrations.
+
+After clients publish through the new gateway, preserve both authorities and every
+edge database. Stop the cutover, drain queued outboxes, and reconcile authoritative
+messages before choosing one authority. If schema or data recovery is required,
+restore the verified native DR bundle into a fresh target and switch authority once.
+Do not run the source and restored database as active authorities at the same time.
+
+The manual `gateway production proof` GitHub Actions workflow runs this acceptance
+proof against an existing HTTPS gateway. GitHub restricts it to `main`, and every job
+uses the approval-protected `agent-bridge-production-proof` environment. Configure
+`PROOF_SENDER_TOKEN`, `PROOF_RECEIVER_TOKEN`, `PROOF_HOST_SALT`, and `FLY_API_TOKEN` as
+environment secrets. The sender and receiver credentials must bind the requested
+workspace to the dedicated `proof-sender` and `proof-receiver` principals. The
+sender credential needs `messages:write` and `messages:read`. The receiver needs
+`messages:read`, `deliveries:claim`, `deliveries:settle`, and `deliveries:read`.
+
+Run the workflow only when the Fly app has exactly one gateway machine. The cycle job
+restarts that machine and queries the Fly Machines API before and after. It fails
+unless the machine ID stays fixed, the runtime `instance_id` changes, the machine
+returns to `started`, and `/readyz` succeeds. This changes production compute and
+requires environment approval. It does not migrate the database or change secrets.
+
+The sender first uses an unreachable loopback origin to force a leased publication
+into its private SQLite outbox. It then synchronizes that row to the supplied gateway
+and repeats the publication with the same idempotency key. A separate host finds the
+exact message through `proof-receiver`, claims its delivery, and acknowledges it.
+After the Fly machine cycle, the verifier uses a fresh instance key, edge database,
+and cursor. It reads the immutable message and confirms that the prior delivery is
+still `acked`.
+
+Each phase writes an `agent-bridge-production-proof-v1` receipt. The runner rejects
+unknown fields at the phase boundary and checks every receipt before use. Receipts may
+record IDs, timestamps, principal and workspace labels, the gateway origin, boolean
+checks, and salted SHA-256 host evidence. They never record bearer values, database
+URLs, environment values, message content, lease tokens, cursor files, or edge
+databases. Download all four workflow artifacts for the operator record. A passing
+repository test still does not replace a completed external workflow run.
+
 ### Persistent data and backup
 
 A database volume or managed PostgreSQL disk keeps runtime state. It does not protect

package/llms.txt

@@ -43,7 +43,7 @@ services can call the CLI or HTTPS API or embed the Node library without a host
 - `agent-bridge doctor`: active named checks; exits 0 ok, 2 degraded, 1 failed. Blocked outbox rows cannot be healthy.
 - agent-bridge pending
 - agent-bridge send, inbox, history, acknowledge
-- agent-bridge claim, extend, ack, nack, deliveries, delivery-events, cancel, requeue
+- agent-bridge claim [--message-id <uuid>], extend, ack, nack, deliveries, delivery-events, cancel, requeue
 - agent-bridge sync, watch, join, presence
 - agent-bridge clients install <runtime> --identity <principal>
 - agent-bridge clients inspect <runtime> --identity <principal> --instance <stable-key> --backend-config <absolute path>
@@ -131,6 +131,7 @@ one logical authority across restore but does not fence a live clone.
 
 Compatibility: post_context, get_context, ack_context.
 Reliable messaging: send, history, claim, extend, acknowledge, negative_acknowledge, heartbeat, presence, sync.
+Claim selects the next due delivery unless HTTP 2.1, MCP, or CLI supplies one messageId. The exact form atomically selects and maintains only that eligible recipient delivery. HTTP 2.0 rejects the additive field.
 Publisher delivery intent: `deliveryPolicy` mode `mailbox|leased` with `maxAttempts`, `retryBaseDelayMs`, `retryMaxDelayMs`, `retryJitterRatio`, and optional `notBefore`. MCP delivery controls: `list_deliveries`, `list_delivery_events`, `cancel_delivery`, `requeue_delivery`. Consumer `maxAttempts` and `retryPolicy` are validated but ignored for one compatibility release.
 
 Gateway MCP clients sync automatically and expose manual sync for bounded outbox replay and inbox cache refresh. Offline unacknowledged results are degraded candidates with unknown acknowledgement state, not proof that messages are unread or that no remote work exists.

package/openapi/agent-bridge-v2.openapi.json

@@ -4776,7 +4776,7 @@
     "/v2/deliveries/claim": {
       "post": {
         "operationId": "claim_delivery",
-        "summary": "Atomically claim the next targeted delivery.",
+        "summary": "Atomically claim the next targeted delivery, or one eligible message when requested.",
         "security": [
           {
             "bearerAuth": []
@@ -4810,6 +4810,10 @@
                   "leaseMs": {
                     "type": "number"
                   },
+                  "messageId": {
+                    "type": "string",
+                    "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$"
+                  },
                   "maxAttempts": {
                     "type": "number"
                   }