@agent-native/core 0.77.8 → 0.77.10

package/corpus/core/src/provider-api/staged-datasets-store.ts

@@ -14,6 +14,7 @@
  */
 
 import { getDbExec, intType, isPostgres, type DbExec } from "../db/client.js";
+import { ensureTableExists, ensureIndexExists } from "../db/ddl-guard.js";
 
 // ---------------------------------------------------------------------------
 // Caps
@@ -32,7 +33,7 @@ async function ensureTables(): Promise<void> {
     _initPromise = (async () => {
       const db = getDbExec();
       const integerType = intType();
-      await db.execute(`
+      const createDatasetsSql = `
         CREATE TABLE IF NOT EXISTS staged_datasets (
           id TEXT NOT NULL,
           app_id TEXT NOT NULL,
@@ -45,18 +46,34 @@ async function ensureTables(): Promise<void> {
           updated_at ${integerType} NOT NULL,
           PRIMARY KEY (id)
         )
-      `);
-      await db.execute(`
+      `;
+      const createRowsSql = `
         CREATE TABLE IF NOT EXISTS staged_dataset_rows (
           dataset_id TEXT NOT NULL,
           row_index ${integerType} NOT NULL,
           row_data TEXT NOT NULL,
           PRIMARY KEY (dataset_id, row_index)
         )
-      `);
+      `;
       if (isPostgres()) {
-        await widenPostgresIntegerColumns(db);
+        // PG guard: probe via information_schema, only issue DDL if missing, bounded lock_timeout
+        await ensureTableExists("staged_datasets", createDatasetsSql);
+        await ensureTableExists("staged_dataset_rows", createRowsSql);
+        await widenPostgresIntegerColumns(db); // best-effort type widening — unchanged
+        await ensureIndexExists(
+          "staged_datasets_scope_idx",
+          `CREATE INDEX IF NOT EXISTS staged_datasets_scope_idx ON staged_datasets (app_id, owner_email)`,
+        );
+        await ensureIndexExists(
+          "staged_dataset_rows_dataset_idx",
+          `CREATE INDEX IF NOT EXISTS staged_dataset_rows_dataset_idx ON staged_dataset_rows (dataset_id)`,
+        );
+        return;
       }
+      // SQLite (local dev): keep existing behavior
+      await db.execute(createDatasetsSql);
+      await db.execute(createRowsSql);
+      // Note: widenPostgresIntegerColumns is Postgres-only, skip on SQLite
       for (const ddl of [
         `CREATE INDEX IF NOT EXISTS staged_datasets_scope_idx ON staged_datasets (app_id, owner_email)`,
         `CREATE INDEX IF NOT EXISTS staged_dataset_rows_dataset_idx ON staged_dataset_rows (dataset_id)`,

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

@@ -7,6 +7,7 @@ import {
   retryOnDdlRace,
   type DbExec,
 } from "../db/client.js";
+import { ensureColumnExists, ensureTableExists } from "../db/ddl-guard.js";
 import { widenIntColumnsToBigInt } from "../db/widen-columns.js";
 import {
   canUseLocalWorkspaceResourcePath,
@@ -751,37 +752,71 @@ async function ensureTable(): Promise<void> {
 
 async function _doEnsureTable(): Promise<void> {
   const client = getDbExec();
-  await retryOnDdlRace(() =>
-    client.execute(`
-      CREATE TABLE IF NOT EXISTS resources (
-        id TEXT PRIMARY KEY,
-        path TEXT NOT NULL,
-        owner TEXT NOT NULL,
-        content TEXT NOT NULL DEFAULT '',
-        mime_type TEXT NOT NULL DEFAULT 'text/markdown',
-        size ${intType()} NOT NULL DEFAULT 0,
-        created_at ${intType()} NOT NULL,
-        updated_at ${intType()} NOT NULL,
-        created_by TEXT NOT NULL DEFAULT 'user',
-        visibility TEXT NOT NULL DEFAULT 'workspace',
-        thread_id TEXT,
-        run_id TEXT,
-        expires_at ${intType()},
-        metadata TEXT,
-        UNIQUE(path, owner)
-      )
-    `),
-  );
-
-  await ensureResourceColumn(client, "created_by TEXT NOT NULL DEFAULT 'user'");
-  await ensureResourceColumn(
-    client,
-    "visibility TEXT NOT NULL DEFAULT 'workspace'",
-  );
-  await ensureResourceColumn(client, "thread_id TEXT");
-  await ensureResourceColumn(client, "run_id TEXT");
-  await ensureResourceColumn(client, `expires_at ${intType()}`);
-  await ensureResourceColumn(client, "metadata TEXT");
+  const createSql = `
+    CREATE TABLE IF NOT EXISTS resources (
+      id TEXT PRIMARY KEY,
+      path TEXT NOT NULL,
+      owner TEXT NOT NULL,
+      content TEXT NOT NULL DEFAULT '',
+      mime_type TEXT NOT NULL DEFAULT 'text/markdown',
+      size ${intType()} NOT NULL DEFAULT 0,
+      created_at ${intType()} NOT NULL,
+      updated_at ${intType()} NOT NULL,
+      created_by TEXT NOT NULL DEFAULT 'user',
+      visibility TEXT NOT NULL DEFAULT 'workspace',
+      thread_id TEXT,
+      run_id TEXT,
+      expires_at ${intType()},
+      metadata TEXT,
+      UNIQUE(path, owner)
+    )
+  `;
+
+  if (isPostgres()) {
+    // Hot path: the `resources` table and its additive columns are virtually
+    // always already present in production. Issuing `CREATE TABLE`/`ALTER
+    // TABLE` still takes an ACCESS EXCLUSIVE lock that, in a fresh
+    // background-worker process behind a concurrent connection on the shared
+    // Neon DB, can block ~indefinitely. The ensure* wrappers probe
+    // `information_schema` 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("resources", createSql);
+    // Additive columns — guarded so the hot path (columns already present)
+    // skips the ACCESS EXCLUSIVE ALTER entirely.
+    const pgColumns: Array<[string, string]> = [
+      ["created_by", "TEXT NOT NULL DEFAULT 'user'"],
+      ["visibility", "TEXT NOT NULL DEFAULT 'workspace'"],
+      ["thread_id", "TEXT"],
+      ["run_id", "TEXT"],
+      ["expires_at", intType()],
+      ["metadata", "TEXT"],
+    ];
+    for (const [col, def] of pgColumns) {
+      await ensureColumnExists(
+        "resources",
+        col,
+        `ALTER TABLE resources ADD COLUMN IF NOT EXISTS ${col} ${def}`,
+      );
+    }
+  } else {
+    // SQLite (local dev): no lock problem — keep the original behaviour using
+    // `retryOnDdlRace` + `ensureResourceColumn` (duplicate-column catch).
+    await retryOnDdlRace(() => client.execute(createSql));
+    await ensureResourceColumn(
+      client,
+      "created_by TEXT NOT NULL DEFAULT 'user'",
+    );
+    await ensureResourceColumn(
+      client,
+      "visibility TEXT NOT NULL DEFAULT 'workspace'",
+    );
+    await ensureResourceColumn(client, "thread_id TEXT");
+    await ensureResourceColumn(client, "run_id TEXT");
+    await ensureResourceColumn(client, `expires_at ${intType()}`);
+    await ensureResourceColumn(client, "metadata TEXT");
+  }
 
   // Older deployments have 32-bit timestamp columns; on Postgres the
   // `Date.now()` written on insert/update overflows int4. Widen in place

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

@@ -15,11 +15,7 @@
 import { randomUUID } from "node:crypto";
 
 import { getDbExec, isPostgres } from "../db/client.js";
-import {
-  pgColumnExists,
-  pgTableExists,
-  runGuardedDdl,
-} from "../db/ddl-guard.js";
+import { ensureColumnExists, ensureTableExists } from "../db/ddl-guard.js";
 import {
   encryptSecretValue as encryptValue,
   decryptSecretValue as decryptValue,
@@ -48,23 +44,23 @@ async function ensureTable(): Promise<void> {
         // virtually always already present. Issuing `CREATE`/`ALTER` would
         // still take an ACCESS EXCLUSIVE lock — which, in a fresh background
         // worker process behind a concurrent connection on the shared Neon DB,
-        // can block ~indefinitely. So check `information_schema` first (a plain
-        // read, no lock) and run DDL ONLY for what is actually missing. When
-        // DDL must run, `runGuardedDdl` wraps it in a transaction-scoped
-        // `lock_timeout` so a contended lock fails fast instead of hanging.
-        if (!(await pgTableExists("app_secrets"))) {
-          await runGuardedDdl(createSql);
-        }
-        if (!(await pgColumnExists("app_secrets", "description"))) {
-          await runGuardedDdl(
-            `ALTER TABLE app_secrets ADD COLUMN IF NOT EXISTS description TEXT`,
-          );
-        }
-        if (!(await pgColumnExists("app_secrets", "url_allowlist"))) {
-          await runGuardedDdl(
-            `ALTER TABLE app_secrets ADD COLUMN IF NOT EXISTS url_allowlist TEXT`,
-          );
-        }
+        // can block ~indefinitely. `ensureTableExists` / `ensureColumnExists`
+        // check `information_schema` first (a plain read, no lock) and run DDL
+        // ONLY for what is actually missing, wrapping any DDL that must run in a
+        // transaction-scoped `lock_timeout` so a contended lock fails fast. They
+        // also re-probe after a swallowed lock-timeout and THROW if the schema
+        // is still missing, so a timed-out DDL never poisons this init memo.
+        await ensureTableExists("app_secrets", createSql);
+        await ensureColumnExists(
+          "app_secrets",
+          "description",
+          `ALTER TABLE app_secrets ADD COLUMN IF NOT EXISTS description TEXT`,
+        );
+        await ensureColumnExists(
+          "app_secrets",
+          "url_allowlist",
+          `ALTER TABLE app_secrets ADD COLUMN IF NOT EXISTS url_allowlist TEXT`,
+        );
         return;
       }
 

package/corpus/core/src/server/agent-teams-run-queue.ts

@@ -14,7 +14,13 @@
  * for UI/status; this table only drives dispatch, idempotent claiming, and
  * cross-invocation continuation.
  */
-import { getDbExec, intType, retryOnDdlRace } from "../db/client.js";
+import {
+  getDbExec,
+  intType,
+  isPostgres,
+  retryOnDdlRace,
+} from "../db/client.js";
+import { ensureIndexExists, ensureTableExists } from "../db/ddl-guard.js";
 
 /** Max cross-invocation continuations for one sub-agent run. Each continuation
  * is one ~40s soft-timeout chunk, so ~60 ≈ ~40 minutes of wall-clock work. Two
@@ -77,8 +83,7 @@ async function ensureTable(): Promise<void> {
   if (!_initPromise) {
     _initPromise = (async () => {
       const client = getDbExec();
-      await retryOnDdlRace(() =>
-        client.execute(`
+      const createSql = `
           CREATE TABLE IF NOT EXISTS agent_team_run_queue (
             task_id TEXT PRIMARY KEY,
             thread_id TEXT NOT NULL,
@@ -92,13 +97,20 @@ async function ensureTable(): Promise<void> {
             created_at ${intType()} NOT NULL,
             updated_at ${intType()} NOT NULL
           )
-        `),
-      );
-      await retryOnDdlRace(() =>
-        client.execute(
-          `CREATE INDEX IF NOT EXISTS idx_agent_team_run_queue_status ON agent_team_run_queue (status, updated_at)`,
-        ),
-      );
+        `;
+      const indexSql = `CREATE INDEX IF NOT EXISTS idx_agent_team_run_queue_status ON agent_team_run_queue (status, updated_at)`;
+
+      // PG guard: probe information_schema / pg_indexes first (no lock), run
+      // DDL only when missing, bounded by a transaction-scoped lock_timeout.
+      if (isPostgres()) {
+        await ensureTableExists("agent_team_run_queue", createSql);
+        await ensureIndexExists("idx_agent_team_run_queue_status", indexSql);
+        return;
+      }
+
+      // SQLite (local dev): no lock problem — keep the original behaviour.
+      await retryOnDdlRace(() => client.execute(createSql));
+      await retryOnDdlRace(() => client.execute(indexSql));
     })().catch((err) => {
       _initPromise = undefined;
       throw err;

package/corpus/core/src/server/auth.ts

@@ -72,6 +72,7 @@ import {
   retryOnDdlRace,
   describeDbError,
 } from "../db/client.js";
+import { ensureColumnExists, ensureTableExists } from "../db/ddl-guard.js";
 import { widenIntColumnsToBigInt } from "../db/widen-columns.js";
 import { readBody } from "../server/h3-helpers.js";
 import { putSetting } from "../settings/store.js";
@@ -865,15 +866,32 @@ async function ensureSessionTable(): Promise<void> {
   if (!_sessionInitPromise) {
     _sessionInitPromise = (async () => {
       const client = getDbExec();
-      await retryOnDdlRace(() =>
-        client.execute(`
+      const createSql = `
           CREATE TABLE IF NOT EXISTS sessions (
             token TEXT PRIMARY KEY,
             email TEXT,
             created_at ${intType()} NOT NULL
           )
-        `),
-      );
+        `;
+
+      // PG guard: probe information_schema first (no lock), run DDL only when
+      // missing, bounded by a transaction-scoped lock_timeout.
+      if (isPostgres()) {
+        await ensureTableExists("sessions", createSql);
+        await ensureColumnExists(
+          "sessions",
+          "email",
+          `ALTER TABLE sessions ADD COLUMN IF NOT EXISTS email TEXT`,
+        );
+        // Older deployments have a 32-bit `created_at`; on Postgres the
+        // `Date.now()` written on session create overflows int4. Widen in place
+        // (no-op once done / on fresh DBs).
+        await widenIntColumnsToBigInt("sessions", ["created_at"]);
+        return;
+      }
+
+      // SQLite (local dev): no lock problem — keep the original behaviour.
+      await retryOnDdlRace(() => client.execute(createSql));
       try {
         await client.execute(`ALTER TABLE sessions ADD COLUMN email TEXT`);
       } catch {

package/corpus/core/src/server/better-auth-instance.ts

@@ -39,6 +39,7 @@ import {
   neonPoolMax,
   attachNeonPoolErrorLogger,
 } from "../db/client.js";
+import { ensureTableExists } from "../db/ddl-guard.js";
 import { saveOAuthTokens } from "../oauth-tokens/store.js";
 import { acceptPendingInvitationsForEmail } from "../org/accept-pending.js";
 import { autoJoinDomainMatchingOrgs } from "../org/auto-join-domain.js";
@@ -693,29 +694,62 @@ async function mirrorGoogleAccountToOAuthTokens(account: {
 
 async function ensureBetterAuthTables(): Promise<void> {
   const db = getDbExec();
-  const statements = isPostgres()
-    ? [
+
+  // PG guard: probe information_schema first (no lock) for each table; run
+  // DDL only when missing, bounded by a transaction-scoped lock_timeout.
+  // Probe names are UNQUOTED (what information_schema.tables.table_name stores);
+  // createSql keeps the QUOTED "user"/"session"/… form required by Postgres.
+  if (isPostgres()) {
+    const pgTables: Array<[name: string, createSql: string]> = [
+      [
+        "user",
         `CREATE TABLE IF NOT EXISTS "user" (id TEXT PRIMARY KEY, name TEXT NOT NULL, email TEXT NOT NULL UNIQUE, email_verified BOOLEAN NOT NULL DEFAULT FALSE, image TEXT, created_at TIMESTAMPTZ NOT NULL, updated_at TIMESTAMPTZ NOT NULL)`,
+      ],
+      [
+        "session",
         `CREATE TABLE IF NOT EXISTS "session" (id TEXT PRIMARY KEY, expires_at TIMESTAMPTZ NOT NULL, token TEXT NOT NULL UNIQUE, created_at TIMESTAMPTZ NOT NULL, updated_at TIMESTAMPTZ NOT NULL, ip_address TEXT, user_agent TEXT, user_id TEXT NOT NULL, active_organization_id TEXT)`,
+      ],
+      [
+        "account",
         `CREATE TABLE IF NOT EXISTS "account" (id TEXT PRIMARY KEY, account_id TEXT NOT NULL, provider_id TEXT NOT NULL, user_id TEXT NOT NULL, access_token TEXT, refresh_token TEXT, id_token TEXT, access_token_expires_at TIMESTAMPTZ, refresh_token_expires_at TIMESTAMPTZ, scope TEXT, password TEXT, created_at TIMESTAMPTZ NOT NULL, updated_at TIMESTAMPTZ NOT NULL)`,
+      ],
+      [
+        "verification",
         `CREATE TABLE IF NOT EXISTS "verification" (id TEXT PRIMARY KEY, identifier TEXT NOT NULL, value TEXT NOT NULL, expires_at TIMESTAMPTZ NOT NULL, created_at TIMESTAMPTZ NOT NULL, updated_at TIMESTAMPTZ NOT NULL)`,
+      ],
+      [
+        "organization",
         `CREATE TABLE IF NOT EXISTS "organization" (id TEXT PRIMARY KEY, name TEXT NOT NULL, slug TEXT NOT NULL UNIQUE, logo TEXT, metadata TEXT, created_at TIMESTAMPTZ NOT NULL, updated_at TIMESTAMPTZ NOT NULL)`,
+      ],
+      [
+        "member",
         `CREATE TABLE IF NOT EXISTS "member" (id TEXT PRIMARY KEY, organization_id TEXT NOT NULL, user_id TEXT NOT NULL, role TEXT NOT NULL DEFAULT 'member', created_at TIMESTAMPTZ NOT NULL, updated_at TIMESTAMPTZ NOT NULL)`,
+      ],
+      [
+        "invitation",
         `CREATE TABLE IF NOT EXISTS "invitation" (id TEXT PRIMARY KEY, organization_id TEXT NOT NULL, email TEXT NOT NULL, role TEXT, status TEXT NOT NULL DEFAULT 'pending', expires_at TIMESTAMPTZ NOT NULL, inviter_id TEXT NOT NULL, created_at TIMESTAMPTZ NOT NULL, updated_at TIMESTAMPTZ NOT NULL)`,
+      ],
+      [
+        "jwks",
         `CREATE TABLE IF NOT EXISTS "jwks" (id TEXT PRIMARY KEY, public_key TEXT NOT NULL, private_key TEXT NOT NULL, created_at TIMESTAMPTZ NOT NULL, expires_at TIMESTAMPTZ)`,
-      ]
-    : [
-        `CREATE TABLE IF NOT EXISTS user (id TEXT PRIMARY KEY, name TEXT NOT NULL, email TEXT NOT NULL UNIQUE, email_verified INTEGER NOT NULL DEFAULT 0, image TEXT, created_at INTEGER NOT NULL, updated_at INTEGER NOT NULL)`,
-        `CREATE TABLE IF NOT EXISTS session (id TEXT PRIMARY KEY, expires_at INTEGER NOT NULL, token TEXT NOT NULL UNIQUE, created_at INTEGER NOT NULL, updated_at INTEGER NOT NULL, ip_address TEXT, user_agent TEXT, user_id TEXT NOT NULL, active_organization_id TEXT)`,
-        `CREATE TABLE IF NOT EXISTS account (id TEXT PRIMARY KEY, account_id TEXT NOT NULL, provider_id TEXT NOT NULL, user_id TEXT NOT NULL, access_token TEXT, refresh_token TEXT, id_token TEXT, access_token_expires_at INTEGER, refresh_token_expires_at INTEGER, scope TEXT, password TEXT, created_at INTEGER NOT NULL, updated_at INTEGER NOT NULL)`,
-        `CREATE TABLE IF NOT EXISTS verification (id TEXT PRIMARY KEY, identifier TEXT NOT NULL, value TEXT NOT NULL, expires_at INTEGER NOT NULL, created_at INTEGER NOT NULL, updated_at INTEGER NOT NULL)`,
-        `CREATE TABLE IF NOT EXISTS organization (id TEXT PRIMARY KEY, name TEXT NOT NULL, slug TEXT NOT NULL UNIQUE, logo TEXT, metadata TEXT, created_at INTEGER NOT NULL, updated_at INTEGER NOT NULL)`,
-        `CREATE TABLE IF NOT EXISTS member (id TEXT PRIMARY KEY, organization_id TEXT NOT NULL, user_id TEXT NOT NULL, role TEXT NOT NULL DEFAULT 'member', created_at INTEGER NOT NULL, updated_at INTEGER NOT NULL)`,
-        `CREATE TABLE IF NOT EXISTS invitation (id TEXT PRIMARY KEY, organization_id TEXT NOT NULL, email TEXT NOT NULL, role TEXT, status TEXT NOT NULL DEFAULT 'pending', expires_at INTEGER NOT NULL, inviter_id TEXT NOT NULL, created_at INTEGER NOT NULL, updated_at INTEGER NOT NULL)`,
-        `CREATE TABLE IF NOT EXISTS jwks (id TEXT PRIMARY KEY, public_key TEXT NOT NULL, private_key TEXT NOT NULL, created_at INTEGER NOT NULL, expires_at INTEGER)`,
-      ];
-
-  for (const sql of statements) await db.execute(sql);
+      ],
+    ];
+    for (const [name, sql] of pgTables) await ensureTableExists(name, sql);
+    return;
+  }
+
+  // SQLite (local dev): no lock problem — keep the original behaviour.
+  const sqliteStatements = [
+    `CREATE TABLE IF NOT EXISTS user (id TEXT PRIMARY KEY, name TEXT NOT NULL, email TEXT NOT NULL UNIQUE, email_verified INTEGER NOT NULL DEFAULT 0, image TEXT, created_at INTEGER NOT NULL, updated_at INTEGER NOT NULL)`,
+    `CREATE TABLE IF NOT EXISTS session (id TEXT PRIMARY KEY, expires_at INTEGER NOT NULL, token TEXT NOT NULL UNIQUE, created_at INTEGER NOT NULL, updated_at INTEGER NOT NULL, ip_address TEXT, user_agent TEXT, user_id TEXT NOT NULL, active_organization_id TEXT)`,
+    `CREATE TABLE IF NOT EXISTS account (id TEXT PRIMARY KEY, account_id TEXT NOT NULL, provider_id TEXT NOT NULL, user_id TEXT NOT NULL, access_token TEXT, refresh_token TEXT, id_token TEXT, access_token_expires_at INTEGER, refresh_token_expires_at INTEGER, scope TEXT, password TEXT, created_at INTEGER NOT NULL, updated_at INTEGER NOT NULL)`,
+    `CREATE TABLE IF NOT EXISTS verification (id TEXT PRIMARY KEY, identifier TEXT NOT NULL, value TEXT NOT NULL, expires_at INTEGER NOT NULL, created_at INTEGER NOT NULL, updated_at INTEGER NOT NULL)`,
+    `CREATE TABLE IF NOT EXISTS organization (id TEXT PRIMARY KEY, name TEXT NOT NULL, slug TEXT NOT NULL UNIQUE, logo TEXT, metadata TEXT, created_at INTEGER NOT NULL, updated_at INTEGER NOT NULL)`,
+    `CREATE TABLE IF NOT EXISTS member (id TEXT PRIMARY KEY, organization_id TEXT NOT NULL, user_id TEXT NOT NULL, role TEXT NOT NULL DEFAULT 'member', created_at INTEGER NOT NULL, updated_at INTEGER NOT NULL)`,
+    `CREATE TABLE IF NOT EXISTS invitation (id TEXT PRIMARY KEY, organization_id TEXT NOT NULL, email TEXT NOT NULL, role TEXT, status TEXT NOT NULL DEFAULT 'pending', expires_at INTEGER NOT NULL, inviter_id TEXT NOT NULL, created_at INTEGER NOT NULL, updated_at INTEGER NOT NULL)`,
+    `CREATE TABLE IF NOT EXISTS jwks (id TEXT PRIMARY KEY, public_key TEXT NOT NULL, private_key TEXT NOT NULL, created_at INTEGER NOT NULL, expires_at INTEGER)`,
+  ];
+  for (const sql of sqliteStatements) await db.execute(sql);
 }
 
 /**

package/corpus/core/src/server/embed-session.ts

@@ -9,7 +9,8 @@ import {
   setResponseHeader,
 } from "h3";
 
-import { getDbExec, intType } from "../db/client.js";
+import { getDbExec, intType, isPostgres } from "../db/client.js";
+import { ensureTableExists } from "../db/ddl-guard.js";
 import {
   EMBED_MODE_QUERY_PARAM,
   EMBED_SESSION_COOKIE,
@@ -103,8 +104,10 @@ export type ResolvedEmbedSession = {
 async function ensureTable(): Promise<void> {
   if (!_initPromise) {
     _initPromise = (async () => {
-      const client = getDbExec();
-      await client.execute(`
+      // Build the CREATE SQL here (not at module scope) so intType() runs at
+      // RUNTIME, not import time — a module-scope call breaks any consumer whose
+      // db/client mock doesn't stub intType (e.g. db-admin specs).
+      const embedTicketsCreateSql = `
         CREATE TABLE IF NOT EXISTS agent_native_embed_tickets (
           ticket_hash TEXT PRIMARY KEY,
           owner_email TEXT NOT NULL,
@@ -115,7 +118,19 @@ async function ensureTable(): Promise<void> {
           expires_at ${intType()} NOT NULL,
           consumed_at ${intType()}
         )
-      `);
+      `;
+      if (isPostgres()) {
+        // PG guard: probe → guarded DDL → re-probe; skips lock on already-migrated path
+        await ensureTableExists(
+          "agent_native_embed_tickets",
+          embedTicketsCreateSql,
+        );
+        return;
+      }
+
+      // SQLite (local dev): no lock problem — keep the original behaviour.
+      const client = getDbExec();
+      await client.execute(embedTicketsCreateSql);
     })().catch((err) => {
       _initPromise = undefined;
       throw err;

package/corpus/core/src/server/identity-sso-store.ts

@@ -24,7 +24,13 @@
 
 import { randomBytes } from "node:crypto";
 
-import { getDbExec, isConnectionError, intType } from "../db/client.js";
+import {
+  getDbExec,
+  isConnectionError,
+  intType,
+  isPostgres,
+} from "../db/client.js";
+import { ensureTableExists } from "../db/ddl-guard.js";
 
 let _initPromise: Promise<void> | undefined;
 
@@ -98,13 +104,11 @@ export const SSO_STATE_TTL_MS = 10 * 60_000;
 export const SSO_LOGIN_MAX = 60;
 export const SSO_LOGIN_WINDOW_MS = 60_000;
 
-async function ensureTable(): Promise<void> {
-  if (!_initPromise) {
-    _initPromise = (async () => {
-      const client = getDbExec();
-      // Additive only. Never DROP / ALTER — this DB is shared across every
-      // deploy context (preview/branch/prod) for hosted templates.
-      await client.execute(`
+// Build the CREATE SQL lazily (not at module scope) so intType() runs at
+// RUNTIME, not import time — a module-scope call breaks any consumer whose
+// db/client mock doesn't stub intType (e.g. db-admin specs).
+function buildIdentitySsoStateCreateSql(): string {
+  return `
         CREATE TABLE IF NOT EXISTS identity_sso_state (
           state TEXT PRIMARY KEY,
           return_path TEXT,
@@ -112,13 +116,38 @@ async function ensureTable(): Promise<void> {
           expires_at ${intType()},
           consumed_at ${intType()}
         )
-      `);
-      await client.execute(`
+      `;
+}
+function buildIdentitySsoJtiCreateSql(): string {
+  return `
         CREATE TABLE IF NOT EXISTS identity_sso_jti (
           jti TEXT PRIMARY KEY,
           seen_at ${intType()}
         )
-      `);
+      `;
+}
+
+async function ensureTable(): Promise<void> {
+  if (!_initPromise) {
+    _initPromise = (async () => {
+      const client = getDbExec();
+      const identitySsoStateCreateSql = buildIdentitySsoStateCreateSql();
+      const identitySsoJtiCreateSql = buildIdentitySsoJtiCreateSql();
+      // Additive only. Never DROP / ALTER — this DB is shared across every
+      // deploy context (preview/branch/prod) for hosted templates.
+      if (isPostgres()) {
+        // PG guard: probe → guarded DDL → re-probe; skips lock on already-migrated path
+        await ensureTableExists(
+          "identity_sso_state",
+          identitySsoStateCreateSql,
+        );
+        await ensureTableExists("identity_sso_jti", identitySsoJtiCreateSql);
+        return;
+      }
+
+      // SQLite (local dev): no lock problem — keep the original behaviour.
+      await client.execute(identitySsoStateCreateSql);
+      await client.execute(identitySsoJtiCreateSql);
     })().catch((err) => {
       // Don't cache a rejection — let the next caller retry a fresh init.
       _initPromise = undefined;

package/corpus/core/src/server/recap-image-store.ts

@@ -19,7 +19,13 @@
  */
 import { randomBytes } from "node:crypto";
 
-import { getDbExec, intType, retryOnDdlRace } from "../db/client.js";
+import {
+  getDbExec,
+  intType,
+  isPostgres,
+  retryOnDdlRace,
+} from "../db/client.js";
+import { ensureTableExists } from "../db/ddl-guard.js";
 
 /** Maximum stored image size (~5 MB of raw PNG bytes). */
 export const RECAP_IMAGE_MAX_BYTES = 5 * 1024 * 1024;
@@ -44,12 +50,11 @@ const TOKEN_PATTERN = /^[0-9a-f]{32,128}$/;
 
 let _initPromise: Promise<void> | undefined;
 
-export async function ensureRecapImageTable(): Promise<void> {
-  if (!_initPromise) {
-    _initPromise = (async () => {
-      const client = getDbExec();
-      await retryOnDdlRace(() =>
-        client.execute(`
+// Build the CREATE SQL lazily (not at module scope) so intType() runs at
+// RUNTIME, not import time — a module-scope call breaks any consumer whose
+// db/client mock doesn't stub intType (e.g. db-admin specs).
+function buildRecapImagesCreateSql(): string {
+  return `
         CREATE TABLE IF NOT EXISTS recap_images (
           token TEXT PRIMARY KEY,
           png_base64 TEXT NOT NULL,
@@ -58,8 +63,22 @@ export async function ensureRecapImageTable(): Promise<void> {
           owner_email TEXT,
           created_at ${intType()} NOT NULL
         )
-      `),
-      );
+      `;
+}
+
+export async function ensureRecapImageTable(): Promise<void> {
+  if (!_initPromise) {
+    _initPromise = (async () => {
+      const recapImagesCreateSql = buildRecapImagesCreateSql();
+      if (isPostgres()) {
+        // PG guard: probe → guarded DDL → re-probe; skips lock on already-migrated path
+        await ensureTableExists("recap_images", recapImagesCreateSql);
+        return;
+      }
+
+      // SQLite (local dev): no lock problem — keep the original behaviour.
+      const client = getDbExec();
+      await retryOnDdlRace(() => client.execute(recapImagesCreateSql));
     })().catch((error) => {
       // Allow a later call to retry if the first init lost a DDL race.
       _initPromise = undefined;

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

@@ -1,11 +1,7 @@
 import { EventEmitter } from "events";
 
 import { getDbExec, isPostgres, intType } from "../db/client.js";
-import {
-  pgIndexExists,
-  pgTableExists,
-  runGuardedDdl,
-} from "../db/ddl-guard.js";
+import { ensureIndexExists, ensureTableExists } from "../db/ddl-guard.js";
 import { widenIntColumnsToBigInt } from "../db/widen-columns.js";
 
 let _initPromise: Promise<void> | undefined;
@@ -39,26 +35,25 @@ async function ensureTable(): Promise<void> {
         // `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). So check `information_schema`/
-        // `pg_indexes` first (plain reads, no lock) and run DDL ONLY for what
-        // is actually missing. `runGuardedDdl` bounds any DDL that must run
-        // with a transaction-scoped `lock_timeout` so a contended lock fails
-        // fast instead of hanging. `settingsTable()` is `public.settings` on
-        // Postgres; the existence checks use the unqualified table name.
-        if (!(await pgTableExists("settings"))) {
-          await runGuardedDdl(createSql);
-        }
+        // blocking SHARE lock for CREATE INDEX). `ensureTableExists` /
+        // `ensureIndexExists` probe `information_schema`/`pg_indexes` first
+        // (plain reads, no lock) and run DDL ONLY for what is actually missing,
+        // bounding any DDL with a transaction-scoped `lock_timeout`. They also
+        // re-probe after a swallowed lock-timeout and THROW if the schema is
+        // still missing, so a timed-out DDL never poisons this init memo with
+        // missing schema. `settingsTable()` is `public.settings` on Postgres;
+        // the existence checks use the unqualified table name.
+        await ensureTableExists("settings", createSql);
         // Older deployments (pre BIGINT-compat) have a 32-bit `updated_at`; on
         // Postgres the `Date.now()` written on every setSetting overflows int4.
         // widenIntColumnsToBigInt already probes information_schema and only
         // ALTERs columns that are still int4 — a no-op on fresh/widened DBs.
         await widenIntColumnsToBigInt("settings", ["updated_at"]);
         // Index for the poll watermark query: `SELECT MAX(updated_at)`.
-        if (!(await pgIndexExists("settings_updated_at_idx"))) {
-          await runGuardedDdl(
-            `CREATE INDEX IF NOT EXISTS settings_updated_at_idx ON ${table} (updated_at)`,
-          );
-        }
+        await ensureIndexExists(
+          "settings_updated_at_idx",
+          `CREATE INDEX IF NOT EXISTS settings_updated_at_idx ON ${table} (updated_at)`,
+        );
         return;
       }