@agent-native/core 0.77.7 → 0.77.10

package/corpus/core/src/application-state/store.ts

@@ -4,6 +4,7 @@ import {
   isPostgres,
   intType,
 } from "../db/client.js";
+import { ensureIndexExists, ensureTableExists } from "../db/ddl-guard.js";
 import { widenIntColumnsToBigInt } from "../db/widen-columns.js";
 import type { StoreWriteOptions } from "../settings/store.js";
 import { emitAppStateChange, emitAppStateDelete } from "./emitter.js";
@@ -22,7 +23,7 @@ async function ensureTable(): Promise<void> {
   if (!_initPromise) {
     _initPromise = (async () => {
       const client = getDbExec();
-      await client.execute(`
+      const createSql = `
         CREATE TABLE IF NOT EXISTS application_state (
           session_id TEXT NOT NULL,
           key TEXT NOT NULL,
@@ -30,7 +31,40 @@ async function ensureTable(): Promise<void> {
           updated_at ${intType()} NOT NULL,
           PRIMARY KEY (session_id, key)
         )
-      `);
+      `;
+
+      if (isPostgres()) {
+        // Hot path: the `application_state` table and its poll indexes are
+        // virtually always already present in production. Issuing `CREATE
+        // TABLE`/ `CREATE INDEX` still takes a lock that, in a fresh
+        // background-worker process behind a concurrent connection on the
+        // shared Neon DB, can block ~indefinitely (ACCESS EXCLUSIVE for CREATE
+        // TABLE; a write-blocking SHARE lock for CREATE INDEX). The ensure*
+        // wrappers probe `information_schema`/`pg_indexes` first (plain reads,
+        // no lock) and run DDL ONLY for what is actually missing, bounded by a
+        // transaction-scoped `lock_timeout`. If a swallowed lock-timeout leaves
+        // the schema still missing they RE-PROBE and THROW rather than letting
+        // init memoize success against absent schema.
+        await ensureTableExists("application_state", createSql);
+        // Older deployments created `updated_at` as 32-bit `INTEGER`; on Postgres
+        // the `Date.now()` written by appStatePut() on every turn overflows int4.
+        // Widen it in place (no-op once done / on fresh BIGINT databases).
+        await widenIntColumnsToBigInt("application_state", ["updated_at"]);
+        // Indexes for the two hot poll paths. Probe pg_indexes first (no lock)
+        // and skip the SHARE-locking CREATE INDEX when already present.
+        await ensureIndexExists(
+          "app_state_updated_at_idx",
+          `CREATE INDEX IF NOT EXISTS app_state_updated_at_idx ON application_state (updated_at)`,
+        );
+        await ensureIndexExists(
+          "app_state_key_updated_idx",
+          `CREATE INDEX IF NOT EXISTS app_state_key_updated_idx ON application_state (key, updated_at)`,
+        );
+        return;
+      }
+
+      // SQLite (local dev): no lock problem — keep the original behaviour.
+      await client.execute(createSql);
       // Older deployments created `updated_at` as 32-bit `INTEGER`; on Postgres
       // the `Date.now()` written by appStatePut() on every turn overflows int4.
       // Widen it in place (no-op once done / on fresh BIGINT databases).

package/corpus/core/src/audit/store.ts

@@ -7,7 +7,8 @@
  * `agent_audit_log`; reads are scoped to the caller's identity in SQL (no
  * shares table — audit rows are never individually shared).
  */
-import { getDbExec, intType, retryOnDdlRace } from "../db/client.js";
+import { getDbExec, intType, isPostgres } from "../db/client.js";
+import { ensureTableExists, ensureIndexExists } from "../db/ddl-guard.js";
 import type {
   AuditEvent,
   AuditQueryFilters,
@@ -20,9 +21,7 @@ export async function ensureAuditTables(): Promise<void> {
   if (!_initPromise) {
     _initPromise = (async () => {
       const client = getDbExec();
-
-      await retryOnDdlRace(() =>
-        client.execute(`
+      const createSql = `
         CREATE TABLE IF NOT EXISTS agent_audit_log (
           id TEXT PRIMARY KEY,
           created_at ${intType()} NOT NULL,
@@ -42,9 +41,41 @@ export async function ensureAuditTables(): Promise<void> {
           owner_email TEXT,
           visibility TEXT NOT NULL DEFAULT 'private'
         )
-      `),
-      );
+      `;
+
+      if (isPostgres()) {
+        // PG-guard: probe information_schema / pg_indexes before issuing DDL to
+        // avoid ACCESS EXCLUSIVE lock contention in fresh background-worker processes.
+        await ensureTableExists("agent_audit_log", createSql);
+        await ensureIndexExists(
+          "idx_audit_owner",
+          `CREATE INDEX IF NOT EXISTS idx_audit_owner ON agent_audit_log (owner_email, created_at)`,
+        );
+        await ensureIndexExists(
+          "idx_audit_org",
+          `CREATE INDEX IF NOT EXISTS idx_audit_org ON agent_audit_log (org_id, created_at)`,
+        );
+        await ensureIndexExists(
+          "idx_audit_target",
+          `CREATE INDEX IF NOT EXISTS idx_audit_target ON agent_audit_log (target_type, target_id, created_at)`,
+        );
+        await ensureIndexExists(
+          "idx_audit_turn",
+          `CREATE INDEX IF NOT EXISTS idx_audit_turn ON agent_audit_log (turn_id)`,
+        );
+        await ensureIndexExists(
+          "idx_audit_actor",
+          `CREATE INDEX IF NOT EXISTS idx_audit_actor ON agent_audit_log (actor_email, created_at)`,
+        );
+        await ensureIndexExists(
+          "idx_audit_created",
+          `CREATE INDEX IF NOT EXISTS idx_audit_created ON agent_audit_log (created_at)`,
+        );
+        return;
+      }
 
+      // SQLite (local dev): no lock problem — keep the original behaviour.
+      await client.execute(createSql);
       const indexes = [
         `CREATE INDEX IF NOT EXISTS idx_audit_owner ON agent_audit_log (owner_email, created_at)`,
         `CREATE INDEX IF NOT EXISTS idx_audit_org ON agent_audit_log (org_id, created_at)`,

package/corpus/core/src/browser-sessions/store.ts

@@ -5,6 +5,7 @@ import {
   retryOnDdlRace,
   safeJsonParse,
 } from "../db/client.js";
+import { ensureIndexExists, ensureTableExists } from "../db/ddl-guard.js";
 import type {
   AgentNativeBrowserSession,
   AgentNativeBrowserSessionAction,
@@ -38,8 +39,7 @@ async function ensureTables(): Promise<void> {
   if (!initPromise) {
     initPromise = (async () => {
       const client = getDbExec();
-      await retryOnDdlRace(() =>
-        client.execute(`
+      const createSessionsSql = `
           CREATE TABLE IF NOT EXISTS ${SESSION_TABLE} (
             owner_email TEXT NOT NULL,
             session_id TEXT NOT NULL,
@@ -53,16 +53,8 @@ async function ensureTables(): Promise<void> {
             expires_at ${intType()} NOT NULL,
             PRIMARY KEY (owner_email, session_id)
           )
-        `),
-      );
-      await retryOnDdlRace(() =>
-        client.execute(`
-          CREATE INDEX IF NOT EXISTS agent_native_browser_sessions_owner_seen_idx
-          ON ${SESSION_TABLE} (owner_email, last_seen_at)
-        `),
-      );
-      await retryOnDdlRace(() =>
-        client.execute(`
+        `;
+      const createRequestsSql = `
           CREATE TABLE IF NOT EXISTS ${REQUEST_TABLE} (
             owner_email TEXT NOT NULL,
             session_id TEXT NOT NULL,
@@ -80,8 +72,35 @@ async function ensureTables(): Promise<void> {
             error TEXT,
             PRIMARY KEY (owner_email, request_id)
           )
+        `;
+
+      if (isPostgres()) {
+        // PG-guard: probe information_schema / pg_indexes first (no lock) and
+        // only issue DDL when the table/index is actually missing, wrapped in
+        // a transaction-scoped lock_timeout so a contended lock fails fast.
+        await ensureTableExists(SESSION_TABLE, createSessionsSql);
+        await ensureIndexExists(
+          "agent_native_browser_sessions_owner_seen_idx",
+          `CREATE INDEX IF NOT EXISTS agent_native_browser_sessions_owner_seen_idx ON ${SESSION_TABLE} (owner_email, last_seen_at)`,
+        );
+        await ensureTableExists(REQUEST_TABLE, createRequestsSql);
+        await ensureIndexExists(
+          "agent_native_browser_session_requests_pending_idx",
+          `CREATE INDEX IF NOT EXISTS agent_native_browser_session_requests_pending_idx ON ${REQUEST_TABLE} (owner_email, session_id, status, created_at)`,
+        );
+        return;
+      }
+
+      // SQLite (local dev): no ACCESS EXCLUSIVE lock problem — keep existing
+      // retryOnDdlRace behaviour.
+      await retryOnDdlRace(() => client.execute(createSessionsSql));
+      await retryOnDdlRace(() =>
+        client.execute(`
+          CREATE INDEX IF NOT EXISTS agent_native_browser_sessions_owner_seen_idx
+          ON ${SESSION_TABLE} (owner_email, last_seen_at)
         `),
       );
+      await retryOnDdlRace(() => client.execute(createRequestsSql));
       await retryOnDdlRace(() =>
         client.execute(`
           CREATE INDEX IF NOT EXISTS agent_native_browser_session_requests_pending_idx

package/corpus/core/src/chat-threads/store.ts

@@ -5,7 +5,12 @@ import {
   normalizeThreadRepository,
   normalizeThreadTitle,
 } from "../agent/thread-data-builder.js";
-import { getDbExec, intType } from "../db/client.js";
+import { getDbExec, intType, isPostgres } from "../db/client.js";
+import {
+  ensureColumnExists,
+  ensureIndexExists,
+  ensureTableExists,
+} from "../db/ddl-guard.js";
 import { widenIntColumnsToBigInt } from "../db/widen-columns.js";
 import { emitChatThreadChange } from "./emitter.js";
 
@@ -53,7 +58,7 @@ async function ensureTable(): Promise<void> {
   if (!_initPromise) {
     _initPromise = (async () => {
       const client = getDbExec();
-      await client.execute(`
+      const createSql = `
         CREATE TABLE IF NOT EXISTS chat_threads (
           id TEXT PRIMARY KEY,
           owner_email TEXT NOT NULL,
@@ -69,7 +74,66 @@ async function ensureTable(): Promise<void> {
           pinned_at ${intType()},
           archived_at ${intType()}
         )
-      `);
+      `;
+
+      if (isPostgres()) {
+        // Hot path: the `chat_threads` table and its indexes are virtually
+        // always already present in production. Issuing `CREATE TABLE`/
+        // `CREATE INDEX` still takes a lock that, in a fresh background-worker
+        // process behind a concurrent connection on the shared Neon DB, can
+        // block ~indefinitely (ACCESS EXCLUSIVE for CREATE TABLE; a write-
+        // blocking SHARE lock for CREATE INDEX). The ensure* wrappers probe
+        // `information_schema`/`pg_indexes` first (plain reads, no lock) and
+        // run DDL ONLY for what is actually missing, bounded by a transaction-
+        // scoped `lock_timeout`. If a swallowed lock-timeout leaves the schema
+        // still missing they RE-PROBE and THROW rather than letting init
+        // memoize success against absent schema. `chat_threads` is the
+        // unqualified name even though the table lives in `public`.
+        await ensureTableExists("chat_threads", createSql);
+        // Additive columns — guarded so the hot path (columns already present)
+        // skips the ACCESS EXCLUSIVE ALTER entirely.
+        for (const [col, type] of [
+          ["scope_type", "TEXT"],
+          ["scope_id", "TEXT"],
+          ["scope_label", "TEXT"],
+          ["pinned_at", intType()],
+          ["archived_at", intType()],
+        ] as const) {
+          await ensureColumnExists(
+            "chat_threads",
+            col,
+            `ALTER TABLE chat_threads ADD COLUMN IF NOT EXISTS ${col} ${type}`,
+          );
+        }
+        // Widen millisecond-timestamp columns that older deployments created as
+        // 32-bit `INTEGER`; on Postgres the `Date.now()` written on every turn
+        // overflows int4. No-op once widened / on fresh BIGINT databases.
+        await widenIntColumnsToBigInt("chat_threads", [
+          "created_at",
+          "updated_at",
+          "pinned_at",
+          "archived_at",
+        ]);
+        // Indexes for the hot read paths. Both the sidebar list and the
+        // scoped/per-resource list filter on owner_email (and optionally
+        // scope) and sort by updated_at. Probe pg_indexes first (no lock)
+        // and skip the SHARE-locking CREATE INDEX when already present.
+        await ensureIndexExists(
+          "chat_threads_owner_updated_idx",
+          `CREATE INDEX IF NOT EXISTS chat_threads_owner_updated_idx ON chat_threads (owner_email, updated_at)`,
+        );
+        await ensureIndexExists(
+          "chat_threads_scope_updated_idx",
+          `CREATE INDEX IF NOT EXISTS chat_threads_scope_updated_idx ON chat_threads (scope_type, scope_id, updated_at)`,
+        );
+        // One-time backfill of message_count for legacy rows written before
+        // the column was maintained.
+        await backfillLegacyMessageCounts(client);
+        return;
+      }
+
+      // SQLite (local dev): no lock problem — keep the original behaviour.
+      await client.execute(createSql);
       // Additive migration for existing tables. Both SQLite and Postgres
       // accept `ALTER TABLE ADD COLUMN` and will raise when the column
       // already exists; the try/catch makes the call idempotent across

package/corpus/core/src/checkpoints/store.ts

@@ -1,4 +1,5 @@
-import { getDbExec, intType } from "../db/client.js";
+import { getDbExec, intType, isPostgres } from "../db/client.js";
+import { ensureTableExists } from "../db/ddl-guard.js";
 
 let _initPromise: Promise<void> | undefined;
 
@@ -6,7 +7,7 @@ async function ensureCheckpointTable(): Promise<void> {
   if (!_initPromise) {
     _initPromise = (async () => {
       const client = getDbExec();
-      await client.execute(`
+      const createSql = `
         CREATE TABLE IF NOT EXISTS agent_checkpoints (
           id TEXT PRIMARY KEY,
           thread_id TEXT NOT NULL,
@@ -15,7 +16,17 @@ async function ensureCheckpointTable(): Promise<void> {
           message TEXT NOT NULL DEFAULT '',
           created_at ${intType()} NOT NULL
         )
-      `);
+      `;
+
+      if (isPostgres()) {
+        // PG-guard: probe information_schema before issuing DDL to avoid ACCESS
+        // EXCLUSIVE lock contention in fresh background-worker processes.
+        await ensureTableExists("agent_checkpoints", createSql);
+        return;
+      }
+
+      // SQLite (local dev): no lock problem — keep the original behaviour.
+      await client.execute(createSql);
     })().catch((err) => {
       // Retry init on the next call after a failed startup.
       _initPromise = undefined;

package/corpus/core/src/cli/create.ts

@@ -29,7 +29,16 @@ const STANDALONE_EXACT_DEPENDENCY_OVERRIDES: Record<string, string> = {
 };
 const SENTRY_MINIMUM_RELEASE_AGE_EXCLUDES = [
   '"@sentry/browser"',
+  '"@sentry/browser-utils"',
+  '"@sentry/conventions"',
+  '"@sentry/core"',
+  '"@sentry/feedback"',
   '"@sentry/node"',
+  '"@sentry/node-core"',
+  '"@sentry/opentelemetry"',
+  '"@sentry/replay"',
+  '"@sentry/replay-canvas"',
+  '"@sentry/server-utils"',
 ];
 const FIRST_PARTY_TARBALL_SYMLINK_EXCLUDES = [
   "*/CLAUDE.md",

package/corpus/core/src/collab/storage.ts

@@ -6,6 +6,7 @@
  */
 
 import { getDbExec, isPostgres } from "../db/client.js";
+import { ensureTableExists, ensureColumnExists } from "../db/ddl-guard.js";
 
 let _initPromise: Promise<void> | undefined;
 
@@ -14,7 +15,7 @@ async function ensureTable(): Promise<void> {
     _initPromise = (async () => {
       const client = getDbExec();
       const nowDefault = isPostgres() ? "NOW()::text" : "datetime('now')";
-      await client.execute(`
+      const createSql = `
         CREATE TABLE IF NOT EXISTS _collab_docs (
           doc_id TEXT PRIMARY KEY,
           yjs_state TEXT NOT NULL,
@@ -22,7 +23,24 @@ async function ensureTable(): Promise<void> {
           version INTEGER NOT NULL DEFAULT 0,
           updated_at TEXT NOT NULL DEFAULT (${nowDefault})
         )
-      `);
+      `;
+
+      if (isPostgres()) {
+        // PG-guard: probe information_schema first (no lock) and only issue
+        // DDL when the table/column is actually missing, wrapped in a
+        // transaction-scoped lock_timeout so a contended lock fails fast.
+        await ensureTableExists("_collab_docs", createSql);
+        await ensureColumnExists(
+          "_collab_docs",
+          "version",
+          `ALTER TABLE _collab_docs ADD COLUMN IF NOT EXISTS version INTEGER NOT NULL DEFAULT 0`,
+        );
+        return;
+      }
+
+      // SQLite (local dev): no ACCESS EXCLUSIVE lock problem — keep existing
+      // create-then-additive-alter behaviour.
+      await client.execute(createSql);
       try {
         await client.execute(
           `ALTER TABLE _collab_docs ADD COLUMN version INTEGER NOT NULL DEFAULT 0`,

package/corpus/core/src/db/ddl-guard.ts

@@ -0,0 +1,302 @@
+/**
+ * Guards for on-demand `ensureTable()` DDL so the common already-migrated path
+ * takes NO `ACCESS EXCLUSIVE` lock on Postgres.
+ *
+ * Lives in its own module (like `./widen-columns.js`) so stores can import it
+ * without every `vi.mock("../db/client.js")` test needing to stub it: the
+ * helpers resolve `isPostgres()` / `getDbExec()` through `client.js`, so a test
+ * that mocks the client to SQLite (`isPostgres: () => false`) makes the
+ * Postgres-only existence checks no-ops automatically.
+ *
+ * ## Why
+ *
+ * `ensureTable()` runs once per process on first DB touch. In a long-lived Node
+ * server the cost is paid once and is invisible. In a Netlify `-background`
+ * function the process is fresh, so this is the FIRST touch — and the
+ * `CREATE TABLE`/`ALTER TABLE ... ADD COLUMN` DDL it issues takes an
+ * `ACCESS EXCLUSIVE` lock on the shared Neon Postgres database. Behind a
+ * concurrent connection that already holds a conflicting lock, that DDL can
+ * block ~indefinitely (observed >16s hangs in the bg worker vs ~1s inline).
+ *
+ * The tables/columns are essentially always already present in production, so
+ * the DDL is redundant in the hot path. These helpers let a store cheaply check
+ * `information_schema` first and only issue DDL when something is actually
+ * missing — and when DDL must run, wrap it in a short `lock_timeout` so a
+ * contended lock fails fast instead of hanging.
+ *
+ * All of this is Postgres-only behaviour gated on `isPostgres()`. On SQLite
+ * (local dev) there is no such lock problem, so callers keep their existing
+ * behaviour there.
+ */
+
+import { isPostgres, getDbExec, type DbExec } from "./client.js";
+
+const PLAIN_IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_]*$/;
+
+/**
+ * True when running against Postgres AND the given table already exists in the
+ * `public` schema. Returns `false` on SQLite (callers gate their own behaviour
+ * there), for invalid identifiers, or when `information_schema` is unreadable —
+ * the conservative answer "not known to exist" makes the caller fall through to
+ * its idempotent `CREATE TABLE IF NOT EXISTS`, preserving today's behaviour.
+ *
+ * This is a plain read (no lock), so it never blocks on an `ACCESS EXCLUSIVE`
+ * lock the way `CREATE`/`ALTER` would.
+ */
+export async function pgTableExists(
+  table: string,
+  injectedClient?: DbExec,
+): Promise<boolean> {
+  if (!isPostgres() || !PLAIN_IDENTIFIER.test(table)) return false;
+  const client = injectedClient ?? getDbExec();
+  try {
+    const { rows } = await client.execute({
+      sql: `SELECT 1 FROM information_schema.tables
+            WHERE table_schema = 'public' AND table_name = ? LIMIT 1`,
+      args: [table],
+    });
+    return rows.length > 0;
+  } catch {
+    // information_schema unreadable (permissions / non-standard backend) —
+    // report "unknown" so the caller falls back to IF NOT EXISTS.
+    return false;
+  }
+}
+
+/**
+ * True when running against Postgres AND the given column already exists on the
+ * given table in the `public` schema. Returns `false` on SQLite, for invalid
+ * identifiers, or when `information_schema` is unreadable.
+ *
+ * Plain read — no lock taken.
+ */
+export async function pgColumnExists(
+  table: string,
+  column: string,
+  injectedClient?: DbExec,
+): Promise<boolean> {
+  if (!isPostgres()) return false;
+  if (!PLAIN_IDENTIFIER.test(table) || !PLAIN_IDENTIFIER.test(column)) {
+    return false;
+  }
+  const client = injectedClient ?? getDbExec();
+  try {
+    const { rows } = await client.execute({
+      sql: `SELECT 1 FROM information_schema.columns
+            WHERE table_schema = 'public' AND table_name = ? AND column_name = ?
+            LIMIT 1`,
+      args: [table, column],
+    });
+    return rows.length > 0;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * True when running against Postgres AND an index with the given name already
+ * exists in the `public` schema. Returns `false` on SQLite, for invalid
+ * identifiers, or when `pg_indexes` is unreadable.
+ *
+ * `CREATE INDEX` (without CONCURRENTLY) takes a `SHARE` lock that blocks
+ * writes, so on a fresh background-worker process behind a concurrent
+ * connection this can hang just like a `CREATE`/`ALTER` would; checking first
+ * skips the lock on the already-migrated hot path.
+ */
+export async function pgIndexExists(
+  indexName: string,
+  injectedClient?: DbExec,
+): Promise<boolean> {
+  if (!isPostgres() || !PLAIN_IDENTIFIER.test(indexName)) return false;
+  const client = injectedClient ?? getDbExec();
+  try {
+    const { rows } = await client.execute({
+      sql: `SELECT 1 FROM pg_indexes
+            WHERE schemaname = 'public' AND indexname = ? LIMIT 1`,
+      args: [indexName],
+    });
+    return rows.length > 0;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Probe → guarded-DDL → re-probe sequence for one piece of on-demand schema.
+ *
+ * This is the single safe primitive every `ensureTable()` should use so a
+ * swallowed `lock_timeout` can NEVER poison a store's init memo with missing
+ * schema. The flow:
+ *
+ *   1. `probe()` — cheap, lock-free existence check (pgTableExists / etc.).
+ *      Already present → return `false` (nothing to do; the hot path takes NO
+ *      lock).
+ *   2. Missing → run `ddl` through `runGuardedDdl` (bounded `lock_timeout`).
+ *      - DDL completed → return `true`.
+ *      - DDL was swallowed by a lock-timeout (`runGuardedDdl` returned `false`)
+ *        → RE-PROBE. A concurrent connection virtually always created the
+ *        object meanwhile, so the re-probe usually now reports it present →
+ *        return `true`. But if it is STILL missing, the required schema does
+ *        NOT exist and we must NOT let the caller memoize success — so THROW.
+ *        The caller's `_initPromise` rejects and the next call retries instead
+ *        of running forever against absent schema.
+ *
+ * On SQLite the probe is always `false` (helpers no-op there) and the SQLite
+ * branch of each store keeps its own create-then-catch behaviour, so this is a
+ * Postgres-path primitive in practice. Returns `true` when the object exists
+ * after this call (either pre-existing-after-timeout-race or freshly created),
+ * `false` only when it already existed up front (no DDL issued).
+ */
+export async function ensureSchemaObject(options: {
+  /** Lock-free existence check; `true` ⇒ already present, skip DDL. */
+  probe: () => Promise<boolean>;
+  /** DDL to run only when `probe()` reports the object missing. */
+  ddl: string;
+  /** Human-readable name of what's being ensured, for the error message. */
+  label: string;
+  /** Forwarded to `runGuardedDdl`. */
+  lockTimeout?: string;
+  /** Injectable client for tests. */
+  injectedClient?: DbExec;
+}): Promise<boolean> {
+  const { probe, ddl, label, lockTimeout, injectedClient } = options;
+  if (await probe()) return false;
+  const ran = await runGuardedDdl(ddl, { lockTimeout, injectedClient });
+  if (ran) return true;
+  // The DDL was swallowed by a lock-timeout. The object is virtually always
+  // already correct by the time a contended boot retries (a concurrent
+  // connection created it), so re-probe before giving up.
+  if (await probe()) return true;
+  // Still missing after a swallowed timeout: do NOT memoize success with absent
+  // schema. Throw so the caller's init promise rejects and the next call
+  // retries, rather than leaving ensureTable "initialized" against a table/
+  // column/index that does not exist.
+  throw new Error(
+    `ensureSchemaObject: required schema "${label}" is still missing after a ` +
+      `lock-timed-out DDL; refusing to memoize init success. The next call will retry.`,
+  );
+}
+
+/**
+ * Convenience wrapper: ensure a TABLE exists (probe via `pgTableExists`).
+ * No-op-returns `false` on SQLite (probe is always false there) — callers run
+ * the SQLite create on their own branch, so this is used on the Postgres path.
+ */
+export async function ensureTableExists(
+  table: string,
+  createSql: string,
+  options: { lockTimeout?: string; injectedClient?: DbExec } = {},
+): Promise<boolean> {
+  return ensureSchemaObject({
+    probe: () => pgTableExists(table, options.injectedClient),
+    ddl: createSql,
+    label: `table ${table}`,
+    lockTimeout: options.lockTimeout,
+    injectedClient: options.injectedClient,
+  });
+}
+
+/**
+ * Convenience wrapper: ensure a COLUMN exists (probe via `pgColumnExists`).
+ * `addColumnSql` should be the full `ALTER TABLE … ADD COLUMN IF NOT EXISTS …`.
+ */
+export async function ensureColumnExists(
+  table: string,
+  column: string,
+  addColumnSql: string,
+  options: { lockTimeout?: string; injectedClient?: DbExec } = {},
+): Promise<boolean> {
+  return ensureSchemaObject({
+    probe: () => pgColumnExists(table, column, options.injectedClient),
+    ddl: addColumnSql,
+    label: `column ${table}.${column}`,
+    lockTimeout: options.lockTimeout,
+    injectedClient: options.injectedClient,
+  });
+}
+
+/**
+ * Convenience wrapper: ensure an INDEX exists (probe via `pgIndexExists`).
+ * `createIndexSql` should be the full `CREATE INDEX IF NOT EXISTS <name> …`.
+ */
+export async function ensureIndexExists(
+  indexName: string,
+  createIndexSql: string,
+  options: { lockTimeout?: string; injectedClient?: DbExec } = {},
+): Promise<boolean> {
+  return ensureSchemaObject({
+    probe: () => pgIndexExists(indexName, options.injectedClient),
+    ddl: createIndexSql,
+    label: `index ${indexName}`,
+    lockTimeout: options.lockTimeout,
+    injectedClient: options.injectedClient,
+  });
+}
+
+/** True when an error looks like a Postgres `lock_timeout` (SQLSTATE 55P03). */
+export function isLockTimeoutError(err: unknown): boolean {
+  const anyErr = err as { code?: unknown; message?: unknown } | null;
+  if (anyErr?.code === "55P03") return true;
+  const msg = String(anyErr?.message ?? anyErr ?? "");
+  return /lock[_ ]?timeout|canceling statement due to lock timeout/i.test(msg);
+}
+
+/**
+ * Run a DDL statement that MUST execute (the schema is actually missing), with
+ * a short `lock_timeout` so a contended `ACCESS EXCLUSIVE` lock fails fast
+ * instead of hanging the whole process.
+ *
+ * Postgres path: wrap the DDL in an explicit transaction and set
+ * `SET LOCAL lock_timeout` so the timeout is scoped to THIS transaction only
+ * and reset automatically on COMMIT/ROLLBACK — it never leaks onto the pooled
+ * (session-reused) connection the way a bare `SET lock_timeout` would. If the
+ * DbExec has no `transaction` (shouldn't happen for Postgres, but defensively),
+ * fall back to a session `SET` + `RESET` in a finally. A lock-timeout error is
+ * swallowed: the table/column is virtually always already correct by the time a
+ * contended boot retries, and the caller's memoization should still resolve so
+ * the path isn't retried in a tight loop. Any non-lock-timeout error rethrows.
+ *
+ * SQLite path: no lock problem — just run the DDL directly.
+ *
+ * @returns `true` if the DDL ran to completion, `false` if it was skipped due to
+ *          a lock-timeout (so the caller can decide whether to log).
+ */
+export async function runGuardedDdl(
+  ddl: string,
+  options: { lockTimeout?: string; injectedClient?: DbExec } = {},
+): Promise<boolean> {
+  const client = options.injectedClient ?? getDbExec();
+  if (!isPostgres()) {
+    await client.execute(ddl);
+    return true;
+  }
+
+  const lockTimeout = options.lockTimeout ?? "3s";
+  try {
+    if (typeof client.transaction === "function") {
+      await client.transaction(async (tx) => {
+        // SET LOCAL is transaction-scoped: it reverts on COMMIT/ROLLBACK and
+        // never persists on the pooled connection.
+        await tx.execute(`SET LOCAL lock_timeout = '${lockTimeout}'`);
+        await tx.execute(ddl);
+      });
+    } else {
+      // Defensive fallback: no transaction support. Use a session SET and
+      // guarantee a RESET so the timeout never leaks onto a reused connection.
+      try {
+        await client.execute(`SET lock_timeout = '${lockTimeout}'`);
+        await client.execute(ddl);
+      } finally {
+        await client.execute(`RESET lock_timeout`).catch(() => {});
+      }
+    }
+    return true;
+  } catch (err) {
+    if (isLockTimeoutError(err)) {
+      // Contended lock — the schema is virtually always already correct by now.
+      // Proceed; the caller's memoization still resolves so we don't loop.
+      return false;
+    }
+    throw err;
+  }
+}