@agent-native/core 0.145.7 → 0.146.0

package/dist/config.js

@@ -2,12 +2,12 @@
  * Public, non-secret configuration for an Agent-Native app.
  *
  * This module is intentionally free of Node and framework imports so it can be
- * used from a typed `agent-native.ts` file and from browser code after Vite
+ * used from a typed `agent-native.config.ts` file and from browser code after Vite
  * serializes the resolved config into the client bundle.
  */
 export const AGENT_NATIVE_CONFIG_VERSION = 1;
 /**
- * Type-safe authoring helper for `agent-native.ts`.
+ * Type-safe authoring helper for `agent-native.config.ts`.
  *
  * Like Next's typed config file, this is deliberately identity-like: the
  * framework evaluates the exported object or factory in the Vite config
@@ -27,6 +27,7 @@ export function normalizeAgentNativeConfig(input, source = "agent-native config"
     const onboardingValue = input.onboarding;
     const runtimeValue = input.runtime;
     const diagnosticsValue = input.diagnostics;
+    const instructionsValue = input.instructions;
     const normalized = {
         ...(input.version === undefined
             ? {}
@@ -45,6 +46,9 @@ export function normalizeAgentNativeConfig(input, source = "agent-native config"
     if (diagnosticsValue !== undefined) {
         normalized.diagnostics = normalizeDiagnosticsConfig(diagnosticsValue, `${source}.diagnostics`);
     }
+    if (instructionsValue !== undefined) {
+        normalized.instructions = normalizeInstructionsConfig(instructionsValue, `${source}.instructions`);
+    }
     return normalized;
 }
 export function mergeAgentNativeConfigs(base, override) {
@@ -91,6 +95,12 @@ export function mergeAgentNativeConfigs(base, override) {
                 ...override.diagnostics,
             }
             : undefined,
+        instructions: base.instructions || override.instructions
+            ? {
+                ...base.instructions,
+                ...override.instructions,
+            }
+            : undefined,
     };
 }
 export function resolveAgentNativeConfig(input, context) {
@@ -175,6 +185,32 @@ function normalizeDiagnosticsConfig(value, source) {
         ? {}
         : { failOnBuild: value.failOnBuild };
 }
+function normalizeInstructionsConfig(value, source) {
+    if (!isRecord(value)) {
+        throw new Error(`${source} must be an object`);
+    }
+    const result = {};
+    for (const audience of ["runtime", "development"]) {
+        const pathValue = value[audience];
+        if (pathValue === undefined)
+            continue;
+        if (typeof pathValue !== "string") {
+            throw new Error(`${source}.${audience} must be a relative file path`);
+        }
+        result[audience] = normalizeRelativeFilePath(pathValue, `${source}.${audience}`);
+    }
+    return result;
+}
+function normalizeRelativeFilePath(value, source) {
+    const normalized = value.trim().replaceAll("\\", "/");
+    if (!normalized ||
+        normalized.startsWith("/") ||
+        /^[A-Za-z]:\//.test(normalized) ||
+        normalized.split("/").some((segment) => segment === "..")) {
+        throw new Error(`${source} must be a non-empty relative file path inside the app root`);
+    }
+    return normalized;
+}
 function normalizeRequiredEnvKeys(value, source) {
     if (value === undefined)
         return undefined;

package/dist/db/client.d.ts

@@ -174,14 +174,20 @@ export declare function withDbTimeout<T>(op: string, run: () => Promise<T>, ms?:
  */
 export declare function isServerlessRuntime(): boolean;
 /**
- * postgres.js pool options tuned per runtime. idle_timeout is shortened on
- * serverless so a thawed-but-idle instance releases its connections quickly.
- * Long-lived Node servers keep the larger pool for throughput.
- *
- * The cap assumes {@link sharedDbPool}: one pool per URL for the whole
- * process, not one per consumer. See {@link neonPoolMax} for why the cap must
- * leave room for concurrency.
+ * True for production serverless execution contexts. Netlify also exposes
+ * `NETLIFY=true` in its build environment, so build-time code that owns
+ * migrations must use `withMigrationRuntime()` explicitly.
+ */
+export declare function isProductionServerlessFunctionRuntime(env?: NodeJS.ProcessEnv): boolean;
+/** True for statements that change database schema or database privileges. */
+export declare function isSchemaMutationStatement(statement: DbExecStatement): boolean;
+/**
+ * Request functions must never be able to prepare or mutate schema. Throwing
+ * here makes an unconverted ensureTable path fail loudly instead of silently
+ * reporting success against a missing table. The release migration wrapper
+ * is the only supported production opt-in.
  */
+export declare function assertSchemaMutationAllowed(statement: DbExecStatement): void;
 export declare function pgPoolOptions(url: string): Record<string, unknown>;
 /**
  * Shared options for every Neon serverless pool. The startup parameter is
@@ -221,7 +227,19 @@ export declare function isBackgroundFunctionPoolContext(): boolean;
  * actual context.
  */
 export declare function describeDbError(err: unknown): string;
-export declare function attachNeonPoolErrorLogger(pool: unknown, label?: string): void;
+/**
+ * Thrown INSTEAD of attempting, while an endpoint is in cooldown.
+ *
+ * The refused attempt's error is described in the message and deliberately NOT
+ * attached as `cause`: isConnectionError() walks `cause.code`/`cause.message`,
+ * so a cause would reclassify this as retryable and retryOnConnectionError
+ * would drive the storm straight back.
+ */
+export declare class DbConnectCooldownError extends Error {
+    code: string;
+    constructor(remainingMs: number, refusedBy: string);
+}
+export declare function guardNeonPool(pool: unknown, url: string, label?: string): void;
 interface ClosablePool {
     end(): Promise<unknown>;
 }

package/dist/db/client.js

@@ -613,6 +613,9 @@ export function isTransientDatabaseError(err) {
     const error = err;
     const code = String(error?.code ?? error?.cause?.code ?? "");
     if (code === "ECHECKOUTTIMEOUT" ||
+        // Shed load during a connect cooldown is transient by construction — the
+        // endpoint refused, we chose not to re-ask yet. Surfaces as 503, not 500.
+        code === "DB_CONNECT_COOLDOWN" ||
         code === "EMAXCONN" ||
         code === "53300" ||
         code === "57014" ||
@@ -765,6 +768,47 @@ export function isServerlessRuntime() {
         !!process.env.LAMBDA_TASK_ROOT ||
         !!process.env.CF_PAGES);
 }
+/**
+ * True for production serverless execution contexts. Netlify also exposes
+ * `NETLIFY=true` in its build environment, so build-time code that owns
+ * migrations must use `withMigrationRuntime()` explicitly.
+ */
+export function isProductionServerlessFunctionRuntime(env = process.env) {
+    if (env.NODE_ENV !== "production" || env.NETLIFY_LOCAL === "true") {
+        return false;
+    }
+    return Boolean(env.NETLIFY === "true" ||
+        env.NETLIFY_FUNCTION_NAME ||
+        env.AWS_LAMBDA_FUNCTION_NAME ||
+        env.AWS_LAMBDA_FUNCTION_VERSION ||
+        env.LAMBDA_TASK_ROOT ||
+        env.AWS_EXECUTION_ENV?.startsWith("AWS_Lambda") === true ||
+        env.VERCEL_FUNCTION_ID ||
+        env.VERCEL_REGION ||
+        env.VERCEL === "1");
+}
+const SCHEMA_MUTATION_STATEMENT = /^\s*(?:CREATE|ALTER|DROP|TRUNCATE|COMMENT|REINDEX|GRANT|REVOKE)\b/i;
+function rawSql(statement) {
+    return typeof statement === "string" ? statement : statement.sql;
+}
+/** True for statements that change database schema or database privileges. */
+export function isSchemaMutationStatement(statement) {
+    return SCHEMA_MUTATION_STATEMENT.test(rawSql(statement));
+}
+/**
+ * Request functions must never be able to prepare or mutate schema. Throwing
+ * here makes an unconverted ensureTable path fail loudly instead of silently
+ * reporting success against a missing table. The release migration wrapper
+ * is the only supported production opt-in.
+ */
+export function assertSchemaMutationAllowed(statement) {
+    const migrationRuntime = globalThis.__AGENT_NATIVE_MIGRATION_RUNTIME__ === true;
+    if (isProductionServerlessFunctionRuntime() &&
+        !migrationRuntime &&
+        isSchemaMutationStatement(statement)) {
+        throw new Error("Schema mutation attempted in a production serverless request. Run migrations in the release job instead.");
+    }
+}
 /**
  * postgres.js pool options tuned per runtime. idle_timeout is shortened on
  * serverless so a thawed-but-idle instance releases its connections quickly.
@@ -774,10 +818,27 @@ export function isServerlessRuntime() {
  * process, not one per consumer. See {@link neonPoolMax} for why the cap must
  * leave room for concurrency.
  */
+/**
+ * Identifies the connection in `pg_stat_activity.application_name`.
+ *
+ * Without it every backend reports `pgbouncer` and a runaway query is
+ * anonymous. A 58 MB `SELECT id, config FROM dashboards` ran 20-wide against
+ * production and could not be traced to a caller: it appears nowhere in the
+ * repo or any built bundle, and `pg_stat_statements` is not installed. This is
+ * the cheapest thing that would have named it.
+ */
+function poolApplicationName() {
+    const site = process.env.SITE_NAME ??
+        process.env.NETLIFY_SITE_NAME ??
+        process.env.AGENT_NATIVE_APP_NAME ??
+        "app";
+    return `agent-native:${site}`.slice(0, 63);
+}
 export function pgPoolOptions(url) {
     const serverless = isServerlessRuntime();
     return {
         onnotice: () => { },
+        connection: { application_name: poolApplicationName() },
         max: serverless ? serverlessPoolMax() : 20,
         idle_timeout: serverless ? 20 : 240,
         max_lifetime: 60 * 30,
@@ -785,6 +846,7 @@ export function pgPoolOptions(url) {
         ...(serverless
             ? {
                 connection: {
+                    application_name: poolApplicationName(),
                     idle_in_transaction_session_timeout: 30_000,
                 },
             }
@@ -901,7 +963,77 @@ export function describeDbError(err) {
     }
     return String(err);
 }
-export function attachNeonPoolErrorLogger(pool, label = "db/neon") {
+/**
+ * How long one endpoint stops ATTEMPTING to connect after an attempt failed.
+ * Jittered so concurrent function instances do not re-probe in lockstep.
+ */
+function connectCooldownMs() {
+    const raw = Number(process.env.DB_CONNECT_COOLDOWN_MS);
+    const base = Number.isFinite(raw) && raw > 0 ? raw : 2_000;
+    return Math.round(base * (0.5 + Math.random()));
+}
+/**
+ * Thrown INSTEAD of attempting, while an endpoint is in cooldown.
+ *
+ * The refused attempt's error is described in the message and deliberately NOT
+ * attached as `cause`: isConnectionError() walks `cause.code`/`cause.message`,
+ * so a cause would reclassify this as retryable and retryOnConnectionError
+ * would drive the storm straight back.
+ */
+export class DbConnectCooldownError extends Error {
+    code = "DB_CONNECT_COOLDOWN";
+    constructor(remainingMs, refusedBy) {
+        super(`Database is refusing connection attempts; not attempting again for ${remainingMs}ms. Last failure: ${refusedBy}`);
+        this.name = "DbConnectCooldownError";
+    }
+}
+const connectCooldowns = new Map();
+/**
+ * Neon rejects a connection ATTEMPT, not a connection: "Failed to acquire
+ * permit to connect to the database. Too many database connection attempts are
+ * currently ongoing." A failed acquire leaves the pool with zero idle clients,
+ * so the next execute() calls connect() again — and retryOnConnectionError
+ * backs off only 100ms. The process answers a refusal by manufacturing the next
+ * attempt, which is what keeps the refusal true. Production sat in this loop
+ * until the compute was restarted by hand.
+ *
+ * Hold a short cooldown per endpoint so a refused attempt cannot produce the
+ * next one. Checking out an ALREADY-IDLE client is not an attempt and passes
+ * through, so a cooldown degrades throughput instead of taking the process
+ * offline.
+ */
+function gateNeonConnect(pool, url, label) {
+    const connect = pool.connect;
+    if (typeof connect !== "function")
+        return;
+    const gated = function gatedConnect(...args) {
+        const idle = typeof pool.idleCount === "number" ? pool.idleCount : 0;
+        const gate = connectCooldowns.get(url);
+        if (idle === 0 && gate && Date.now() < gate.until) {
+            return Promise.reject(new DbConnectCooldownError(gate.until - Date.now(), gate.refusedBy));
+        }
+        return Promise.resolve(connect.apply(this, args)).then((client) => {
+            connectCooldowns.delete(url);
+            return client;
+        }, (err) => {
+            const refusedBy = describeDbError(err);
+            const ms = connectCooldownMs();
+            // One line per cooldown window, not per shed request.
+            if (!gate || Date.now() >= gate.until) {
+                console.warn(`[${label}] connection attempt refused; pausing attempts ${ms}ms:`, refusedBy);
+            }
+            connectCooldowns.set(url, { until: Date.now() + ms, refusedBy });
+            throw err;
+        });
+    };
+    // Carry the wrapped function's own properties onto the wrapper. A pool's
+    // `connect` may be instrumented — metrics, tracing, a test spy — and
+    // replacing it with a bare closure would silently drop that instrumentation
+    // along with any assertions built on it.
+    Object.assign(gated, connect);
+    pool.connect = gated;
+}
+export function guardNeonPool(pool, url, label = "db/neon") {
     if (!pool || typeof pool !== "object")
         return;
     if (loggedNeonPools.has(pool))
@@ -910,6 +1042,7 @@ export function attachNeonPoolErrorLogger(pool, label = "db/neon") {
     if (typeof withEvents.on !== "function")
         return;
     loggedNeonPools.add(pool);
+    gateNeonConnect(pool, url, label);
     withEvents.on("error", (err) => {
         console.warn(`[${label}] pool error (will reconnect on next query):`, describeDbError(err));
     });
@@ -1118,7 +1251,7 @@ async function createDbExecInternal(config = {}, trackSingletonResources = false
             const pool = trackSingletonResources
                 ? sharedDbPool("neon", url, makePool)
                 : makePool();
-            attachNeonPoolErrorLogger(pool);
+            guardNeonPool(pool, url);
             const httpSql = bgHttp ? neon(url, { fullResults: true }) : null;
             async function queryNeonClient(client, sql, timeoutOverrideMs) {
                 const { rawSql, args } = sqlAndArgs(sql);
@@ -1504,7 +1637,36 @@ async function createDbExecInternal(config = {}, trackSingletonResources = false
     };
 }
 export async function createDbExec(config = {}) {
-    return createDbExecInternal(config, false);
+    const exec = await createDbExecInternal(config, false);
+    return guardSchemaMutations(exec);
+}
+function guardSchemaMutations(exec) {
+    const guarded = {
+        async execute(statement) {
+            assertSchemaMutationAllowed(statement);
+            return exec.execute(statement);
+        },
+    };
+    if (exec.atomicBatch) {
+        guarded.atomicBatch = async (statements) => {
+            for (const statement of statements) {
+                assertSchemaMutationAllowed(statement);
+            }
+            return exec.atomicBatch(statements);
+        };
+    }
+    if (exec.transaction) {
+        guarded.transaction = (fn) => exec.transaction((tx) => fn({
+            ...tx,
+            execute: async (statement) => {
+                assertSchemaMutationAllowed(statement);
+                return tx.execute(statement);
+            },
+        }));
+    }
+    if (exec.close)
+        guarded.close = () => exec.close();
+    return guarded;
 }
 async function initClient() {
     if (_exec)
@@ -1561,6 +1723,7 @@ export function getDbExec() {
         return sql;
     }
     async function execAnnotated(s) {
+        assertSchemaMutationAllowed(s);
         try {
             return await _exec.execute(sanitize(s));
         }
@@ -1571,6 +1734,7 @@ export function getDbExec() {
     // Return a proxy that lazy-inits on first call
     const proxy = {
         async execute(sql) {
+            assertSchemaMutationAllowed(sql);
             if (!_initPromise)
                 _initPromise = initClient();
             try {
@@ -1588,11 +1752,19 @@ export function getDbExec() {
             const wrapper = {
                 execute: (s) => execAnnotated(s),
                 atomicBatch: _exec.atomicBatch
-                    ? (statements) => _exec.atomicBatch(statements.map((s) => sanitize(s)))
+                    ? async (statements) => {
+                        for (const statement of statements) {
+                            assertSchemaMutationAllowed(statement);
+                        }
+                        return _exec.atomicBatch(statements.map((s) => sanitize(s)));
+                    }
                     : undefined,
                 transaction: _exec.transaction
                     ? (fn) => _exec.transaction((tx) => fn({
-                        execute: (s) => tx.execute(sanitize(s)),
+                        execute: (s) => {
+                            assertSchemaMutationAllowed(s);
+                            return tx.execute(sanitize(s));
+                        },
                         transaction: tx.transaction,
                     }))
                     : undefined,
@@ -1614,11 +1786,19 @@ export function getDbExec() {
             const wrapper = {
                 execute: (s) => execAnnotated(s),
                 atomicBatch: _exec.atomicBatch
-                    ? (statements) => _exec.atomicBatch(statements.map((s) => sanitize(s)))
+                    ? async (statements) => {
+                        for (const statement of statements) {
+                            assertSchemaMutationAllowed(statement);
+                        }
+                        return _exec.atomicBatch(statements.map((s) => sanitize(s)));
+                    }
                     : undefined,
                 transaction: _exec.transaction
                     ? (innerFn) => _exec.transaction((tx) => innerFn({
-                        execute: (s) => tx.execute(sanitize(s)),
+                        execute: (s) => {
+                            assertSchemaMutationAllowed(s);
+                            return tx.execute(sanitize(s));
+                        },
                         transaction: tx.transaction,
                     }))
                     : undefined,
@@ -1626,7 +1806,10 @@ export function getDbExec() {
             Object.assign(proxy, wrapper);
             if (_exec.transaction) {
                 return _exec.transaction((tx) => fn({
-                    execute: (s) => tx.execute(sanitize(s)),
+                    execute: (s) => {
+                        assertSchemaMutationAllowed(s);
+                        return tx.execute(sanitize(s));
+                    },
                     transaction: tx.transaction,
                 }));
             }
@@ -1636,6 +1819,9 @@ export function getDbExec() {
             return explicitTransaction(wrapper.execute)(fn);
         },
         async atomicBatch(statements) {
+            for (const statement of statements) {
+                assertSchemaMutationAllowed(statement);
+            }
             if (!_initPromise)
                 _initPromise = initClient();
             try {
@@ -1649,7 +1835,12 @@ export function getDbExec() {
             if (!_exec.atomicBatch) {
                 throw new Error("This database does not support atomic batches.");
             }
-            const batch = (items) => _exec.atomicBatch(items.map((item) => sanitize(item)));
+            const batch = async (items) => {
+                for (const item of items) {
+                    assertSchemaMutationAllowed(item);
+                }
+                return _exec.atomicBatch(items.map((item) => sanitize(item)));
+            };
             Object.assign(proxy, { atomicBatch: batch });
             return batch(statements);
         },

package/dist/db/create-get-db.js

@@ -1,6 +1,6 @@
 import { AsyncLocalStorage } from "node:async_hooks";
 import { drizzle as drizzleD1 } from "drizzle-orm/d1";
-import { getDialect, getCloudflareD1Binding, getDatabaseUrl, getDatabaseAuthToken, isLocalSqliteUrl, isPgliteUrl, isConnectionError, getPgliteClient, loadPgliteDrizzle, prepareLocalSqliteUrl, sqliteFilenameFromUrl, pgPoolOptions, neonPoolOptions, attachNeonPoolErrorLogger, withDbTimeout, retryOnConnectionError, dbOpTimeoutMs, sharedDbPool, onSharedDbPoolsClosed, onSharedDbPoolReplaced, } from "./client.js";
+import { getDialect, getCloudflareD1Binding, getDatabaseUrl, getDatabaseAuthToken, isLocalSqliteUrl, isPgliteUrl, isConnectionError, getPgliteClient, loadPgliteDrizzle, prepareLocalSqliteUrl, sqliteFilenameFromUrl, pgPoolOptions, neonPoolOptions, guardNeonPool, withDbTimeout, retryOnConnectionError, dbOpTimeoutMs, sharedDbPool, onSharedDbPoolsClosed, onSharedDbPoolReplaced, } from "./client.js";
 // Lazy driver loaders — cached promises so dynamic import only runs once.
 let _pgDrizzle;
 function getPgDrizzle() {
@@ -408,7 +408,7 @@ export function createGetDb(schema) {
                     // schema module. See `sharedDbPool` in client.ts.
                     resetOnPoolClose("neon", url);
                     const rawPool = sharedDbPool("neon", url, () => new Pool({ connectionString: url, ...neonPoolOptions() }));
-                    attachNeonPoolErrorLogger(rawPool);
+                    guardNeonPool(rawPool, url);
                     // Wrap the pool with the resilience layer so Drizzle queries get the
                     // same withDbTimeout + retryOnConnectionError protection as the raw
                     // DbExec path in client.ts. Reads retry freely; writes only retry on

package/dist/db/ddl-guard.js

@@ -28,7 +28,7 @@
  * (local dev) there is no such lock problem, so callers keep their existing
  * behaviour there.
  */
-import { isPostgres, getDbExec } from "./client.js";
+import { getDbExec, isPostgres, isProductionServerlessFunctionRuntime, } from "./client.js";
 const PLAIN_IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_]*$/;
 /**
  * Skip on-demand schema DDL entirely. For deployments that run real migrations,
@@ -45,6 +45,8 @@ const PLAIN_IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_]*$/;
  * down the DDL path this flag exists to avoid.
  */
 function schemaEnsureDisabled() {
+    if (isProductionServerlessFunctionRuntime())
+        return true;
     const raw = process.env.AGENT_NATIVE_SKIP_ENSURE_TABLES?.trim();
     return !!raw && ["1", "true", "yes", "on"].includes(raw.toLowerCase());
 }

package/dist/db/ensure-additive-columns.d.ts

@@ -67,6 +67,8 @@ export interface EnsureAdditiveColumnsOptions {
     logger?: EnsureAdditiveColumnsLogger;
 }
 export interface EnsureAdditiveColumnsResult {
+    /** Whether this invocation actually inspected the live schema. */
+    mode: "checked" | "skipped-serverless";
     /** `"table.column"` entries that were successfully added. */
     applied: string[];
     /** Declared columns that were intentionally left unpatched, with why. */

package/dist/db/ensure-additive-columns.js

@@ -54,7 +54,7 @@
  *   unreadable) must never crash boot — the caller decides whether/how to
  *   surface `errors` in the returned summary.
  */
-import { isPostgres } from "./client.js";
+import { isPostgres, isProductionServerlessFunctionRuntime, } from "./client.js";
 const PLAIN_IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_]*$/;
 const defaultLogger = {
     info: (message) => console.log(message),
@@ -62,7 +62,7 @@ const defaultLogger = {
     error: (message) => console.error(message),
 };
 function emptyResult() {
-    return { applied: [], skipped: [], errors: [] };
+    return { mode: "checked", applied: [], skipped: [], errors: [] };
 }
 /**
  * Resolve `getTableConfig` for the dialect currently in effect. Both
@@ -246,6 +246,9 @@ function describeSchemaDriftError(err) {
  */
 export async function ensureAdditiveColumns(options) {
     const { db, tables, logger = defaultLogger } = options;
+    if (isProductionServerlessFunctionRuntime()) {
+        return { ...emptyResult(), mode: "skipped-serverless" };
+    }
     const result = emptyResult();
     let getTableConfig;
     try {

package/dist/db/index.d.ts

@@ -21,7 +21,7 @@ export declare function createDb(config: DbConfig): Promise<(import("drizzle-orm
 })>;
 export type DrizzleDb = Awaited<ReturnType<typeof createDb>>;
 export { createGetDb } from "./create-get-db.js";
-export { deferMigration, MIGRATION_DEFERRED, runMigrations, type MigrationEntry, type MigrationRunResult, type MigrationSql, } from "./migrations.js";
-export { getDbExec, createDbExec, getDatabaseUrl, getDialect, isLocalDatabase, isPostgres, intType, closeDbExec, type DbExec, type DbExecConfig, type DbExecQuery, type DbExecStatement, type Dialect, } from "./client.js";
+export { deferMigration, MIGRATION_DEFERRED, runMigrations, withMigrationRuntime, type MigrationEntry, type MigrationRunResult, type MigrationSql, } from "./migrations.js";
+export { getDbExec, createDbExec, getDatabaseUrl, getDialect, isLocalDatabase, isPostgres, assertSchemaMutationAllowed, isSchemaMutationStatement, isProductionServerlessFunctionRuntime, intType, closeDbExec, type DbExec, type DbExecConfig, type DbExecQuery, type DbExecStatement, type Dialect, } from "./client.js";
 export { table, text, integer, now } from "./schema.js";
 export { ensureAdditiveColumns, type EnsureAdditiveColumnsOptions, type EnsureAdditiveColumnsResult, type EnsureAdditiveColumnsLogger, } from "./ensure-additive-columns.js";

package/dist/db/index.js

@@ -20,7 +20,7 @@ export async function createDb(config) {
     throw new Error(`Unsupported driver: ${config.driver}`);
 }
 export { createGetDb } from "./create-get-db.js";
-export { deferMigration, MIGRATION_DEFERRED, runMigrations, } from "./migrations.js";
-export { getDbExec, createDbExec, getDatabaseUrl, getDialect, isLocalDatabase, isPostgres, intType, closeDbExec, } from "./client.js";
+export { deferMigration, MIGRATION_DEFERRED, runMigrations, withMigrationRuntime, } from "./migrations.js";
+export { getDbExec, createDbExec, getDatabaseUrl, getDialect, isLocalDatabase, isPostgres, assertSchemaMutationAllowed, isSchemaMutationStatement, isProductionServerlessFunctionRuntime, intType, closeDbExec, } from "./client.js";
 export { table, text, integer, now } from "./schema.js";
 export { ensureAdditiveColumns, } from "./ensure-additive-columns.js";

package/dist/db/migrations.d.ts

@@ -19,6 +19,13 @@ export declare function isDuplicateColumnError(err: unknown): boolean;
  */
 export declare function isPermissionError(err: unknown): boolean;
 export interface RunMigrationsOptions {
+    /**
+     * Run migrations even inside a serverless request runtime. Off by default:
+     * see the guard in {@link runMigrations} for why request-path DDL is what
+     * took analytics down. Only set this when the caller has no scheduled or
+     * background runtime that could migrate instead.
+     */
+    runInServerlessRequest?: boolean;
     /**
      * Name of the migrations bookkeeping table. REQUIRED — there is intentionally
      * no default. Two templates that share a database (e.g. via the same Neon URL)
@@ -85,61 +92,11 @@ export interface MigrationEntry {
     run?: () => Promise<MigrationRunResult>;
 }
 /**
- * Runs a list of migrations against the configured database, gated by a
- * per-table bookkeeping row (`options.table`) so repeated boots only apply
- * new migrations.
- *
- * ## Name-based tracking (why it exists)
- *
- * The legacy gate is purely numeric: `SELECT MAX(version)` from the
- * bookkeeping table, then apply every entry whose `version` is greater. That
- * scheme silently breaks down when **two independent branches each extend the
- * same migration list with different DDL under the same version numbers** —
- * exactly what happened to the analytics template's v75-v83 range. Branch A
- * shipped alert-rule tables as v75-v78; branch B shipped unrelated DDL as its
- * own v75-v83. Whichever branch deployed first recorded "v75..v83 applied"
- * in the bookkeeping table. When the other branch merged and deployed, its
- * migrations at those same version numbers were never applied — `MAX(version)`
- * was already ≥ their version, so the gate treated them as done even though
- * their actual DDL had never run. The result: `analytics_migrations` showed
- * rows for 1..83 with no gaps, yet `analytics_alert_rules`,
- * `analytics_alert_incidents`, and `session_recordings.network_error_count`
- * did not exist in production. Version numbers are not a stable identity —
- * they're just sequence position, and sequence position collides across
- * branches.
- *
- * Name-based tracking fixes this by keying application on a stable, unique
- * **string slug** instead of a position in a shared integer sequence:
- *
- * - Entries with a `name` are recorded in a companion table,
- *   `${table}_named` (`name TEXT PRIMARY KEY`), and APPLY IFF their name is
- *   absent from that table — completely independent of version numbers or
- *   the legacy `MAX(version)` gate. Two branches can both ship a migration
- *   named `"analytics-alert-rules-table"` at version 75, or one at version 75
- *   and the other at version 90 after a rebase — either way it applies
- *   exactly once per database, keyed on the name.
- * - Entries WITHOUT a `name` keep the exact legacy behavior
- *   (`version > MAX(recorded version)`), so nothing changes for existing
- *   unnamed migrations.
- * - Named migrations still execute in list order, interleaved with unnamed
- *   ones exactly as written.
- * - When a named migration's DDL runs, we record BOTH the named row (always)
- *   and — if its `version` is greater than the current legacy max — the
- *   legacy version row too, in the SAME atomic batch/transaction as the DDL.
- *   This keeps the legacy `MAX(version)` gate monotonically advancing for
- *   any unnamed migrations that come after it in the list, while ensuring a
- *   named migration is never "double recorded" in a way that would let it
- *   re-apply.
- * - A duplicate `name` across the migration list throws at startup — that's
- *   a programmer error (copy-paste or merge mistake), not a runtime data
- *   problem, and failing loud beats silently tracking the wrong row.
+ * Run an explicit release-time migration job with migration duty enabled.
  *
- * New migrations should always set a `name`. Legacy unnamed migrations don't
- * need to be renamed retroactively — the two gating strategies coexist in the
- * same list — but if a table is EVER at risk of being shared across parallel
- * branches (any template's own migrations qualify, since branches routinely
- * extend the same list concurrently), giving new entries a name is what makes
- * them immune to the collision class described above.
+ * The flag is process-local and restored even when the job fails, so a build
+ * step can opt in without creating a permanent escape hatch for request code.
  */
+export declare function withMigrationRuntime<T>(run: () => Promise<T>): Promise<T>;
 export declare function runMigrations(migrations: Array<MigrationEntry>, options: RunMigrationsOptions): NitroPluginDef;
 export {};