@adonis-agora/durable 1.0.0-rc.2 → 1.0.0-rc.21

package/dist/src/stores/lucid.js

@@ -1,13 +1,16 @@
-import { SETTLEABLE_RUN_STATUSES } from '../interfaces.js';
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { RunAlreadyExistsError } from '../errors.js';
+import { RECOVERABLE_RUN_STATUSES, SETTLEABLE_RUN_STATUSES } from '../interfaces.js';
 import { namespaceFilterValues, normalizeNamespace } from '../namespaces.js';
 import { mergeRunFacetRows } from '../run-facets.js';
 import { runPageWindow } from '../run-pagination.js';
 import { axisIsRunColumn, mergeRunValueFacetRows, RUN_VALUE_FACET_LIMIT, RUN_VALUE_FACET_SCAN, runValueFacetsFromRuns, } from '../run-value-facets.js';
 import { attributeColumnFor, attributeOperand, attributeOperands, normalizeAttributeRows, sqlComparator, } from '../search-attributes.js';
 import { SINGLETON_ACTIVE_STATUSES, SINGLETON_ADMITTED_TAG, settlesTerminally, singletonAdmissionDenialPatch, singletonAdmissionTags, withoutAdmission, } from '../singleton-admission.js';
+import { assertSchemaSupported, hasColumn, hasTable, qualify, qualifyAll, schemaExists as schemaExistsIn, validateSchemaName, } from '../sql-schema.js';
 import { CHECKPOINT_COLUMNS_BUT_INPUT, checkpointToRow, parseJsonColumn, rowToCheckpoint, rowToRun, rowToSignalWaiter, runPatchToRow, runToRow, SETTLED_CHECKPOINT_COLUMNS, settlementToRow, } from './lucid-mappers.js';
 import { LucidPgHotPath, quote } from './lucid-pg-hot-path.js';
-import { createDurableTables, DURABLE_TABLES } from './lucid-schema.js';
+import { createDurableTables, DURABLE_SCHEMA_META_TABLE, DURABLE_TABLES } from './lucid-schema.js';
 /**
  * A production-grade, persistent `StateStore` backed by AdonisJS **Lucid** (Knex). Runs, checkpoints,
  * timers, signal waiters, run attributes and recovery leases live in SQL, so durable state survives
@@ -25,11 +28,22 @@ export class LucidStateStore {
     options;
     /** The namespace run reads are fenced to, or undefined for the operator view. */
     scopeNamespace;
+    /** The schema the tables live in, or undefined for the connection's current one. */
+    schema;
+    /** The durable table names, qualified with {@link schema}, for the query builder. */
+    t;
+    /** The Postgres hot path's statements over {@link t}. */
+    sql;
     constructor(db, options = {}) {
         this.db = db;
         this.connectionName = options.connectionName;
         this.options = options;
         this.scopeNamespace = options.scope?.namespace;
+        this.schema = validateSchemaName(options.schema, 'stores.lucid');
+        if (this.schema !== undefined)
+            assertSchemaSupported(this.client(), this.schema, 'stores.lucid');
+        this.t = qualifyAll(DURABLE_TABLES, this.schema);
+        this.sql = hotStatements(this.schema);
     }
     /**
      * A store over the same `Database` whose run reads are confined to `scope.namespace` (see
@@ -51,19 +65,108 @@ export class LucidStateStore {
     }
     /**
      * The Postgres hot path (see `lucid-pg-hot-path.ts`): the statements a turn and a step result run
-     * on every step, as constant SQL. `undefined` on any other dialect, or with Lucid's `debug` on.
-     * Resolved per call, like {@link client}: under a global transaction it is the transaction's.
+     * on every step, as constant SQL. `undefined` on any other dialect, with Lucid's `debug` on, or
+     * under a (global) transaction. Resolved per call, like {@link client}.
      */
     hot() {
+        // Not on a transaction (an app's global one): see `LucidPgHotPath.for`.
         return LucidPgHotPath.for(this.client(), {
             preparedStatements: this.options.preparedStatements,
         });
     }
+    /**
+     * The hot reads with explicit column lists: each table's base columns plus the later-wave ones it
+     * has, probed once (an older schema without them keeps working) and again after this store's own
+     * {@link ensureSchema}. A column another process adds later is not read until the next probe, and a
+     * statement already prepared keeps its shape.
+     */
+    hotReadStatements;
+    hotReads(hot) {
+        this.hotReadStatements ??= hot
+            .rows(COLUMNS_PRESENT_SQL, [
+            this.schema ?? null,
+            [DURABLE_TABLES.runs, DURABLE_TABLES.checkpoints],
+            [...RUN_OPTIONAL_COLUMNS, ...CHECKPOINT_OPTIONAL_COLUMNS],
+        ])
+            .then((rows) => {
+            const present = new Set(rows.map((r) => `${String(r.table_name)}.${String(r.column_name)}`));
+            const has = (table) => (c) => present.has(`${table}.${c}`);
+            const runCols = [
+                ...RUN_BASE_COLUMNS,
+                ...RUN_OPTIONAL_COLUMNS.filter(has(DURABLE_TABLES.runs)),
+            ];
+            const checkpointCols = [
+                ...CHECKPOINT_BASE_COLUMNS,
+                ...CHECKPOINT_OPTIONAL_COLUMNS.filter(has(DURABLE_TABLES.checkpoints)),
+            ];
+            return this.sql.reads(runCols.map(quote).join(', '), checkpointCols.map(quote).join(', '));
+        })
+            .catch((error) => {
+            this.hotReadStatements = undefined; // a failed probe is retried, never cached
+            throw error;
+        });
+        return this.hotReadStatements;
+    }
     /** Idempotently provision the durable tables (called on boot when `autoSchema` is on). */
     async ensureSchema() {
-        await createDurableTables(this.db, this.connectionName, this.options.collation !== undefined ? { collation: this.options.collation } : {});
+        await createDurableTables(this.db, this.connectionName, {
+            ...(this.options.collation !== undefined ? { collation: this.options.collation } : {}),
+            ...(this.schema !== undefined ? { schema: this.schema } : {}),
+        });
+        // The tables may have gained columns: the next hot read probes them again.
+        this.hotReadStatements = undefined;
+    }
+    /** The database schema the store's tables live in, or `undefined` for the connection's current one. */
+    get schemaName() {
+        return this.schema;
+    }
+    /**
+     * What `agora:doctor` reports for a store with a `schema`: whether the schema exists, which durable
+     * tables are missing from it, which of `optionalTables` (tables other pieces create when they first
+     * run, like the db transport's) are in it, and whether the connection can write there (a probe row
+     * inserted into the schema marker table, in a transaction that is rolled back).
+     */
+    async inspectSchema(optionalTables = []) {
+        const client = this.client();
+        const schema = this.schema;
+        const schemaExists = schema === undefined || (await schemaExistsIn(client, schema));
+        const missingTables = [];
+        for (const table of [...Object.values(DURABLE_TABLES), DURABLE_SCHEMA_META_TABLE]) {
+            if (!schemaExists || !(await hasTable(client, schema, table)))
+                missingTables.push(table);
+        }
+        const optionalPresent = [];
+        if (schemaExists) {
+            for (const table of optionalTables) {
+                if (await hasTable(client, schema, table))
+                    optionalPresent.push(table);
+            }
+        }
+        let writeError;
+        if (!missingTables.includes(DURABLE_SCHEMA_META_TABLE)) {
+            const rollback = new Error('durable doctor probe rollback');
+            try {
+                await client.transaction(async (trx) => {
+                    await trx
+                        .insertQuery()
+                        .table(qualify(schema, DURABLE_SCHEMA_META_TABLE))
+                        .insert({ id: '__doctor_probe__', fingerprint: 'probe', applied_at: Date.now() });
+                    throw rollback;
+                });
+            }
+            catch (error) {
+                if (error !== rollback)
+                    writeError = error instanceof Error ? error.message : String(error);
+            }
+        }
+        return { schema, schemaExists, missingTables, optionalPresent, writeError };
     }
     // --- runs ---------------------------------------------------------------
+    /**
+     * Insert the run, or reject with {@link RunAlreadyExistsError} when its id is taken. The insert
+     * writes nothing on a conflict instead of failing, so a run that already exists never aborts a
+     * surrounding transaction (an app's test `wrapInGlobalTransaction`, on Postgres).
+     */
     async createRun(run) {
         if (normalizeAttributeRows(run.id, run.searchAttributes).length === 0) {
             // Nothing to index: the insert, then clear any attribute rows a deleted run of this id left,
@@ -72,17 +175,23 @@ export class LucidStateStore {
             if (hot) {
                 const row = runToRow(run);
                 const keys = Object.keys(row);
-                await hot.run(insertSql(DURABLE_TABLES.runs, keys), keys.map((k) => row[k]));
-                await hot.run(DELETE_ATTRIBUTES_SQL, [run.id]);
+                const inserted = await hot.rows(this.sql.insertRunIfAbsent(keys), keys.map((k) => row[k]));
+                if (inserted.length === 0)
+                    throw new RunAlreadyExistsError(run.id);
+                await hot.run(this.sql.deleteAttributes, [run.id]);
                 return;
             }
             const client = this.client();
-            await client.table(DURABLE_TABLES.runs).insert(runToRow(run));
-            await client.from(DURABLE_TABLES.attributes).where('run_id', run.id).delete();
+            if (!(await insertIfAbsent(client, this.t.runs, runToRow(run), ['id']))) {
+                throw new RunAlreadyExistsError(run.id);
+            }
+            await client.from(this.t.attributes).where('run_id', run.id).delete();
             return;
         }
         await this.client().transaction(async (trx) => {
-            await trx.table(DURABLE_TABLES.runs).insert(runToRow(run));
+            if (!(await insertIfAbsent(trx, this.t.runs, runToRow(run), ['id']))) {
+                throw new RunAlreadyExistsError(run.id);
+            }
             await this.reindexAttributes(trx, run.id, run.searchAttributes);
         });
     }
@@ -102,7 +211,7 @@ export class LucidStateStore {
             const row = await this.releaseSlot(this.client(), runId, patch);
             const keys = Object.keys(row);
             if (keys.length) {
-                await hot.run(updateRunSql(keys, false), [...keys.map((k) => row[k]), runId]);
+                await hot.run(this.sql.updateRun(keys, false), [...keys.map((k) => row[k]), runId]);
             }
             return;
         }
@@ -110,7 +219,7 @@ export class LucidStateStore {
             const row = await this.releaseSlot(trx, runId, patch);
             // Knex throws on an empty `.update({})`; skip the UPDATE when no mapped column changed.
             if (Object.keys(row).length) {
-                await trx.from(DURABLE_TABLES.runs).where('id', runId).update(row);
+                await trx.from(this.t.runs).where('id', runId).update(row);
             }
             if ('searchAttributes' in patch) {
                 await this.reindexAttributes(trx, runId, patch.searchAttributes);
@@ -123,10 +232,10 @@ export class LucidStateStore {
             const row = await this.releaseSlot(this.client(), runId, patch);
             const keys = Object.keys(row);
             if (keys.length === 0) {
-                const found = await hot.rows(RUN_IN_STATUSES_SQL, [runId, expectedStatuses]);
+                const found = await hot.rows(this.sql.runInStatuses, [runId, expectedStatuses]);
                 return found.length > 0;
             }
-            const { count } = await hot.run(updateRunSql(keys, true), [
+            const { count } = await hot.run(this.sql.updateRun(keys, true), [
                 ...keys.map((k) => row[k]),
                 runId,
                 expectedStatuses,
@@ -141,7 +250,7 @@ export class LucidStateStore {
                 // structure — the database arbitrates, not a prior JS read. Two racing writers can never both
                 // report `true` for the same row.
                 const affected = await trx
-                    .from(DURABLE_TABLES.runs)
+                    .from(this.t.runs)
                     .where('id', runId)
                     .whereIn('status', expectedStatuses)
                     .update(row);
@@ -151,7 +260,7 @@ export class LucidStateStore {
                 // Knex throws on an empty `.update({})`. Nothing to write, but the predicate's outcome is
                 // still observable: report whether it would have matched, without mutating anything.
                 const current = await trx
-                    .from(DURABLE_TABLES.runs)
+                    .from(this.t.runs)
                     .where('id', runId)
                     .whereIn('status', expectedStatuses)
                     .first();
@@ -178,7 +287,7 @@ export class LucidStateStore {
         // Sorted, so two batches sharing runs take their row locks in the same order.
         const ids = [...new Set(runIds)].sort();
         await this.client()
-            .from(DURABLE_TABLES.runs)
+            .from(this.t.runs)
             .whereIn('id', ids)
             .where('status', 'suspended')
             .andWhere((w) => w.whereNull('wake_at').orWhere('wake_at', '>', wakeAt))
@@ -188,9 +297,7 @@ export class LucidStateStore {
     decisionMarkerColumn;
     hasDecisionMarkerColumn(trx) {
         // Probed on the caller's transaction: a single-connection pool (SQLite) has no other to use.
-        this.decisionMarkerColumn ??= trx.schema
-            .hasColumn(DURABLE_TABLES.runs, 'awaiting_decision_task_id')
-            .catch(() => {
+        this.decisionMarkerColumn ??= hasColumn(trx, this.schema, DURABLE_TABLES.runs, 'awaiting_decision_task_id').catch(() => {
             this.decisionMarkerColumn = undefined; // a failed probe is retried, never cached
             return true;
         });
@@ -225,7 +332,7 @@ export class LucidStateStore {
             tags = patch.tags;
         }
         else {
-            const q = trx.from(DURABLE_TABLES.runs).where('id', runId).select('tags');
+            const q = trx.from(this.t.runs).where('id', runId).select('tags');
             if (locksRows(trx))
                 q.forUpdate();
             const current = (await q.first());
@@ -239,7 +346,7 @@ export class LucidStateStore {
             // Every active run sharing the key. The tag LIKE may over-match (it is only a lock-scope
             // narrowing); the decision re-filters exactly.
             const sharing = () => trx
-                .from(DURABLE_TABLES.runs)
+                .from(this.t.runs)
                 .where('workflow', workflow)
                 .whereIn('status', SINGLETON_ACTIVE_STATUSES)
                 .whereRaw(`tags like ? escape '!'`, [`%"${escapeLike(tag)}"%`]);
@@ -263,13 +370,13 @@ export class LucidStateStore {
             if (!tags) {
                 const parked = singletonAdmissionDenialPatch(runs, runId, tag, workflow, retryWakeAt);
                 if (parked) {
-                    await trx.from(DURABLE_TABLES.runs).where('id', runId).update(runPatchToRow(parked));
+                    await trx.from(this.t.runs).where('id', runId).update(runPatchToRow(parked));
                 }
                 return false;
             }
             // Already a holder (a resumed turn): nothing to write.
             if (!runs.find((r) => r.id === runId)?.tags?.includes(SINGLETON_ADMITTED_TAG)) {
-                await trx.from(DURABLE_TABLES.runs).where('id', runId).update(runPatchToRow({ tags }));
+                await trx.from(this.t.runs).where('id', runId).update(runPatchToRow({ tags }));
             }
             return true;
         });
@@ -277,19 +384,20 @@ export class LucidStateStore {
     async getRun(runId) {
         const hot = this.hot();
         if (hot) {
+            const sql = await this.hotReads(hot);
             const rows = this.scopeNamespace === undefined
-                ? await hot.rows(GET_RUN_SQL, [runId])
-                : await hot.rows(GET_RUN_SCOPED_SQL, [runId, namespaceFilterValues(this.scopeNamespace)]);
+                ? await hot.rows(sql.get, [runId])
+                : await hot.rows(sql.getScoped, [runId, namespaceFilterValues(this.scopeNamespace)]);
             return rows[0] ? rowToRun(rows[0]) : null;
         }
-        const row = await this.fenced(this.client().from(DURABLE_TABLES.runs).where('id', runId)).first();
+        const row = await this.fenced(this.client().from(this.t.runs).where('id', runId)).first();
         return row ? rowToRun(row) : null;
     }
     async getRuns(runIds) {
         const ids = [...new Set(runIds)];
         if (ids.length === 0)
             return [];
-        const rows = await this.fenced(this.client().from(DURABLE_TABLES.runs).whereIn('id', ids));
+        const rows = await this.fenced(this.client().from(this.t.runs).whereIn('id', ids));
         return rows.map(rowToRun);
     }
     async deleteRun(runId) {
@@ -297,10 +405,10 @@ export class LucidStateStore {
         // transaction so a crash can't leave a half-deleted run. (Buffered signals are token-keyed,
         // not run-scoped, so they are not swept here.)
         await this.client().transaction(async (trx) => {
-            await trx.from(DURABLE_TABLES.checkpoints).where('run_id', runId).delete();
-            await trx.from(DURABLE_TABLES.signalWaiters).where('run_id', runId).delete();
-            await trx.from(DURABLE_TABLES.attributes).where('run_id', runId).delete();
-            await trx.from(DURABLE_TABLES.runs).where('id', runId).delete();
+            await trx.from(this.t.checkpoints).where('run_id', runId).delete();
+            await trx.from(this.t.signalWaiters).where('run_id', runId).delete();
+            await trx.from(this.t.attributes).where('run_id', runId).delete();
+            await trx.from(this.t.runs).where('id', runId).delete();
         });
     }
     async deleteRuns(runIds) {
@@ -312,10 +420,10 @@ export class LucidStateStore {
         await this.client().transaction(async (trx) => {
             for (let at = 0; at < ids.length; at += DELETE_RUNS_CHUNK) {
                 const chunk = ids.slice(at, at + DELETE_RUNS_CHUNK);
-                await trx.from(DURABLE_TABLES.checkpoints).whereIn('run_id', chunk).delete();
-                await trx.from(DURABLE_TABLES.signalWaiters).whereIn('run_id', chunk).delete();
-                await trx.from(DURABLE_TABLES.attributes).whereIn('run_id', chunk).delete();
-                await trx.from(DURABLE_TABLES.runs).whereIn('id', chunk).delete();
+                await trx.from(this.t.checkpoints).whereIn('run_id', chunk).delete();
+                await trx.from(this.t.signalWaiters).whereIn('run_id', chunk).delete();
+                await trx.from(this.t.attributes).whereIn('run_id', chunk).delete();
+                await trx.from(this.t.runs).whereIn('id', chunk).delete();
             }
         });
     }
@@ -323,11 +431,11 @@ export class LucidStateStore {
     async getCheckpoint(runId, seq) {
         const hot = this.hot();
         if (hot) {
-            const rows = await hot.rows(GET_CHECKPOINT_SQL, [runId, seq]);
+            const rows = await hot.rows((await this.hotReads(hot)).getCheckpoint, [runId, seq]);
             return rows[0] ? rowToCheckpoint(rows[0]) : null;
         }
         const row = await this.client()
-            .from(DURABLE_TABLES.checkpoints)
+            .from(this.t.checkpoints)
             .where('run_id', runId)
             .andWhere('seq', seq)
             .first();
@@ -338,7 +446,7 @@ export class LucidStateStore {
         const out = [];
         for (let at = 0; at < unique.length; at += CHECKPOINT_BATCH) {
             const rows = (await this.client()
-                .from(DURABLE_TABLES.checkpoints)
+                .from(this.t.checkpoints)
                 .where('run_id', runId)
                 .whereIn('seq', unique.slice(at, at + CHECKPOINT_BATCH)));
             out.push(...rows.map(rowToCheckpoint));
@@ -349,7 +457,7 @@ export class LucidStateStore {
         const unique = [...new Set(seqs)];
         const hot = this.hot();
         if (hot && unique.length <= CHECKPOINT_BATCH) {
-            const rows = await hot.rows(CHECKPOINTS_FOR_SETTLE_SQL, [runId, unique]);
+            const rows = await hot.rows(this.sql.checkpointsForSettle, [runId, unique]);
             return rows
                 .map(rowToCheckpoint)
                 .sort((a, b) => a.seq - b.seq);
@@ -357,7 +465,7 @@ export class LucidStateStore {
         const out = [];
         for (let at = 0; at < unique.length; at += CHECKPOINT_BATCH) {
             const rows = (await this.client()
-                .from(DURABLE_TABLES.checkpoints)
+                .from(this.t.checkpoints)
                 .where('run_id', runId)
                 .whereIn('seq', unique.slice(at, at + CHECKPOINT_BATCH))
                 .select(...CHECKPOINT_COLUMNS_BUT_INPUT));
@@ -374,18 +482,18 @@ export class LucidStateStore {
         // One multi-row upsert per chunk, in one transaction: a rejection writes nothing.
         await this.client().transaction(async (trx) => {
             for (let at = 0; at < checkpoints.length; at += CHECKPOINT_UPSERT_BATCH) {
-                await upsertCheckpointRows(trx, checkpoints.slice(at, at + CHECKPOINT_UPSERT_BATCH));
+                await upsertCheckpointRows(trx, this.t.checkpoints, checkpoints.slice(at, at + CHECKPOINT_UPSERT_BATCH));
             }
         });
     }
     async saveCheckpointIfPending(checkpoint) {
-        return updateCheckpointIfPending(this.client(), checkpoint);
+        return updateCheckpointIfPending(this.client(), this.t.checkpoints, checkpoint);
     }
     async renewCheckpointLease(runId, seq, expectedWakeAt, wakeAt) {
         // One guarded UPDATE: the row-level compare-and-set is atomic on every dialect, so a result or a
         // re-dispatch committed since the caller's read makes this match nothing.
         const query = this.client()
-            .from(DURABLE_TABLES.checkpoints)
+            .from(this.t.checkpoints)
             .where('run_id', runId)
             .andWhere('seq', seq)
             .andWhere('status', 'pending');
@@ -403,7 +511,7 @@ export class LucidStateStore {
         // for a row is compared against the first one's write), then write every winner with one
         // multi-row upsert per chunk.
         return this.client().transaction(async (trx) => {
-            const pending = await lockPendingCheckpoints(trx, checkpoints, ['seq']);
+            const pending = await lockPendingCheckpoints(trx, this.t.checkpoints, checkpoints, ['seq']);
             const wrote = [];
             const writes = new Map();
             for (const cp of checkpoints) {
@@ -419,7 +527,7 @@ export class LucidStateStore {
             }
             const rows = [...writes.values()];
             for (let at = 0; at < rows.length; at += CHECKPOINT_UPSERT_BATCH) {
-                await upsertCheckpointRows(trx, rows.slice(at, at + CHECKPOINT_UPSERT_BATCH));
+                await upsertCheckpointRows(trx, this.t.checkpoints, rows.slice(at, at + CHECKPOINT_UPSERT_BATCH));
             }
             return wrote;
         });
@@ -430,7 +538,7 @@ export class LucidStateStore {
             return [];
         if (settlements.length === 1) {
             const affected = await this.client()
-                .from(DURABLE_TABLES.checkpoints)
+                .from(this.t.checkpoints)
                 .where('run_id', only.runId)
                 .andWhere('seq', only.seq)
                 .andWhere('status', 'pending')
@@ -443,7 +551,7 @@ export class LucidStateStore {
         // locked, so the upsert never inserts: its row carries just the columns an insert would require,
         // and `input` is neither sent nor rewritten.
         return this.client().transaction(async (trx) => {
-            const pending = await lockPendingCheckpoints(trx, settlements, [
+            const pending = await lockPendingCheckpoints(trx, this.t.checkpoints, settlements, [
                 'seq',
                 'name',
                 'kind',
@@ -472,7 +580,7 @@ export class LucidStateStore {
             for (let at = 0; at < rows.length; at += CHECKPOINT_UPSERT_BATCH) {
                 await trx
                     .insertQuery()
-                    .table(DURABLE_TABLES.checkpoints)
+                    .table(this.t.checkpoints)
                     .knexQuery.insert(rows.slice(at, at + CHECKPOINT_UPSERT_BATCH))
                     .onConflict(['run_id', 'seq'])
                     .merge([...SETTLED_CHECKPOINT_COLUMNS]);
@@ -495,7 +603,7 @@ export class LucidStateStore {
         const live = results.filter((_, i) => first[i]);
         const client = this.client();
         const settled = client.dialect.name === 'postgres'
-            ? await settleResultsReturningPg(client, this.hot(), live)
+            ? await settleResultsReturningPg(client, this.hot(), this.schema, live)
             : await this.settleResultsPlain(live);
         const out = [];
         let k = 0;
@@ -520,7 +628,7 @@ export class LucidStateStore {
         const out = new Map();
         const client = this.client();
         const runRows = (await client
-            .from(DURABLE_TABLES.runs)
+            .from(this.t.runs)
             .whereIn('id', [...new Set(results.map((r) => r.runId))])
             .select('id', 'status', 'wake_at'));
         const runs = new Map(runRows.map((row) => [row.id, row]));
@@ -585,36 +693,16 @@ export class LucidStateStore {
         if (hot) {
             const keys = Object.keys(row);
             const values = keys.map((k) => row[k] ?? null);
-            return (await hot.rows(insertCheckpointIfAbsentSql(keys), values)).length > 0;
-        }
-        if (client.dialect.name === 'postgres') {
-            const inserted = (await client
-                .insertQuery()
-                .table(DURABLE_TABLES.checkpoints)
-                .knexQuery.insert(row)
-                .onConflict(['run_id', 'seq'])
-                .ignore()
-                .returning('seq'));
-            return inserted.length > 0;
-        }
-        // MySQL and SQLite: a plain INSERT, whose duplicate-key error is the "already there" answer (an
-        // `INSERT IGNORE` would also swallow every other error, and reports no row count through Knex).
-        try {
-            await client.table(DURABLE_TABLES.checkpoints).insert(row);
-            return true;
-        }
-        catch (err) {
-            if (isDuplicateKey(err))
-                return false;
-            throw err;
+            return (await hot.rows(this.sql.insertCheckpointIfAbsent(keys), values)).length > 0;
         }
+        return insertIfAbsent(client, this.t.checkpoints, row, ['run_id', 'seq']);
     }
     /** Persist the latest worker heartbeat on the step's checkpoint row (see the interface doc).
      *  A targeted two-column UPDATE — never an upsert: a beat racing the checkpoint's own insert (or
      *  outliving a deleted run) matches zero rows and is a silent no-op, by design. */
     async recordStepHeartbeat(runId, seq, at, progress) {
         await this.client()
-            .from(DURABLE_TABLES.checkpoints)
+            .from(this.t.checkpoints)
             .where('run_id', runId)
             .andWhere('seq', seq)
             .update({
@@ -632,14 +720,16 @@ export class LucidStateStore {
         const row = checkpointToRow(checkpoint);
         await client
             .insertQuery()
-            .table(DURABLE_TABLES.checkpoints)
+            .table(this.t.checkpoints)
             .knexQuery.insert(row)
             .onConflict(['run_id', 'seq'])
             .merge();
     }
     // --- recovery / dispatch queries ----------------------------------------
     async listIncompleteRuns(namespace) {
-        const q = this.fenced(this.client().from(DURABLE_TABLES.runs).where('status', 'running'));
+        const q = this.fenced(this.client()
+            .from(this.t.runs)
+            .whereIn('status', [...RECOVERABLE_RUN_STATUSES]));
         if (namespace !== undefined)
             q.whereIn('namespace', namespaceFilterValues(namespace));
         const rows = await q;
@@ -651,8 +741,8 @@ export class LucidStateStore {
         // running run — and issues ~zero lock-probe UPDATEs. `owner` adds the runs still leased to that
         // instance id (a rebooted instance's own leftovers; the engine filters what it is executing).
         const q = this.fenced(this.client()
-            .from(DURABLE_TABLES.runs)
-            .where('status', 'running')
+            .from(this.t.runs)
+            .whereIn('status', [...RECOVERABLE_RUN_STATUSES])
             .andWhere((sub) => {
             sub.whereNull('locked_until').orWhere('locked_until', '<=', nowMs);
             if (owner !== undefined)
@@ -664,7 +754,7 @@ export class LucidStateStore {
         return rows.map(rowToRun);
     }
     async listPendingRuns(limit, namespace) {
-        const q = this.fenced(this.client().from(DURABLE_TABLES.runs).where('status', 'pending'));
+        const q = this.fenced(this.client().from(this.t.runs).where('status', 'pending'));
         if (namespace !== undefined)
             q.whereIn('namespace', namespaceFilterValues(namespace));
         const rows = await q
@@ -691,9 +781,9 @@ export class LucidStateStore {
         if (dialect === 'postgres') {
             // One statement: pick the oldest free pending rows, skipping any another claimer holds locked
             // right now, and lease them. Several pollers at once each get a different slice.
-            const pick = oldest(client.from(DURABLE_TABLES.runs)).forUpdate().skipLocked();
+            const pick = oldest(client.from(this.t.runs)).forUpdate().skipLocked();
             rows = (await client
-                .from(DURABLE_TABLES.runs)
+                .from(this.t.runs)
                 .whereIn('id', pick)
                 .update({ locked_by: owner, locked_until: leaseUntilMs })
                 .returning('*'));
@@ -702,20 +792,20 @@ export class LucidStateStore {
             // No UPDATE … RETURNING: lock the batch (skipping rows another claimer holds), lease it and read
             // it back, in one transaction.
             rows = await client.transaction(async (trx) => {
-                const ids = (await oldest(trx.from(DURABLE_TABLES.runs)).forUpdate().skipLocked()).map((r) => r.id);
+                const ids = (await oldest(trx.from(this.t.runs)).forUpdate().skipLocked()).map((r) => r.id);
                 if (ids.length === 0)
                     return [];
                 await trx
-                    .from(DURABLE_TABLES.runs)
+                    .from(this.t.runs)
                     .whereIn('id', ids)
                     .update({ locked_by: owner, locked_until: leaseUntilMs });
-                return (await trx.from(DURABLE_TABLES.runs).whereIn('id', ids));
+                return (await trx.from(this.t.runs).whereIn('id', ids));
             });
         }
         else {
             // SQLite has no row locks to skip: each run is taken with the lease's own compare-and-set.
             const claimed = [];
-            const candidates = (await free(client.from(DURABLE_TABLES.runs))
+            const candidates = (await free(client.from(this.t.runs))
                 .orderBy('created_at', 'asc')
                 .orderBy('id', 'asc')
                 .limit(limit));
@@ -733,7 +823,7 @@ export class LucidStateStore {
     async listDueTimers(nowMs, namespace, limit) {
         const marker = await this.hasWakeMarkerColumn();
         const q = this.fenced(this.client()
-            .from(DURABLE_TABLES.runs)
+            .from(this.t.runs)
             .where('status', 'suspended')
             .where((w) => {
             w.where((d) => d.whereNotNull('wake_at').andWhere('wake_at', '<=', nowMs));
@@ -756,7 +846,7 @@ export class LucidStateStore {
         // Atomic compare-and-set: acquire ONLY if currently unlocked or the lease has expired. The single
         // conditional UPDATE is the concurrency guard — two instances racing can never both report `true`.
         const affected = await this.client()
-            .from(DURABLE_TABLES.runs)
+            .from(this.t.runs)
             .where('id', runId)
             .andWhere((q) => {
             q.whereNull('locked_until').orWhere('locked_until', '<=', nowMs);
@@ -767,9 +857,10 @@ export class LucidStateStore {
     async tryLockRunAndGet(runId, owner, leaseUntilMs, nowMs) {
         const hot = this.hot();
         if (hot) {
+            const sql = await this.hotReads(hot);
             const rows = this.scopeNamespace === undefined
-                ? await hot.rows(LOCK_AND_GET_SQL, [owner, leaseUntilMs, runId, nowMs])
-                : await hot.rows(LOCK_AND_GET_SCOPED_SQL, [
+                ? await hot.rows(sql.lockAndGet, [owner, leaseUntilMs, runId, nowMs])
+                : await hot.rows(sql.lockAndGetScoped, [
                     owner,
                     leaseUntilMs,
                     runId,
@@ -783,7 +874,7 @@ export class LucidStateStore {
             // One statement: the lease's compare-and-set and the read of the row it locked. The scope
             // fence sits in the WHERE clause, so a run outside it is neither locked nor read.
             const rows = (await this.fenced(client
-                .from(DURABLE_TABLES.runs)
+                .from(this.t.runs)
                 .where('id', runId)
                 .andWhere((q) => {
                 q.whereNull('locked_until').orWhere('locked_until', '<=', nowMs);
@@ -804,15 +895,15 @@ export class LucidStateStore {
         const hot = this.hot();
         if (hot) {
             if (owner === undefined)
-                await hot.run(RELEASE_LOCK_SQL, [runId]);
+                await hot.run(this.sql.releaseLock, [runId]);
             else
-                await hot.run(RELEASE_OWN_LOCK_SQL, [runId, owner]);
+                await hot.run(this.sql.releaseOwnLock, [runId, owner]);
             return;
         }
         // Owner-scoped release (when `owner` is given): the `locked_by` predicate lives in the UPDATE's
         // WHERE clause, so a stale executor whose lease was taken over matches zero rows and cannot
         // wipe the new owner's lease — same conditional-write shape as renewRunLock.
-        const q = this.client().from(DURABLE_TABLES.runs).where('id', runId);
+        const q = this.client().from(this.t.runs).where('id', runId);
         if (owner !== undefined)
             q.andWhere('locked_by', owner);
         await q.update({ locked_by: null, locked_until: null });
@@ -823,19 +914,13 @@ export class LucidStateStore {
         const marker = await this.hasWakeMarkerColumn();
         const hot = this.hot();
         if (hot) {
-            const released = await hot.run(marker ? RELEASE_UNLESS_WAKE_SQL : RELEASE_OWN_LOCK_SQL, [
-                runId,
-                owner,
-            ]);
+            const released = await hot.run(marker ? this.sql.releaseUnlessWake : this.sql.releaseOwnLock, [runId, owner]);
             if (released.count === 1)
                 return true;
-            const rows = await hot.rows(LOCKED_BY_SQL, [runId]);
+            const rows = await hot.rows(this.sql.lockedBy, [runId]);
             return rows[0]?.locked_by !== owner;
         }
-        const q = this.client()
-            .from(DURABLE_TABLES.runs)
-            .where('id', runId)
-            .andWhere('locked_by', owner);
+        const q = this.client().from(this.t.runs).where('id', runId).andWhere('locked_by', owner);
         if (marker)
             q.whereNull('wake_requested_at');
         const affected = await q.update({ locked_by: null, locked_until: null });
@@ -843,7 +928,7 @@ export class LucidStateStore {
             return true;
         // Nothing matched: the lease is not ours (any more), or a turn was asked for.
         const row = (await this.client()
-            .from(DURABLE_TABLES.runs)
+            .from(this.t.runs)
             .where('id', runId)
             .select('locked_by')
             .first());
@@ -851,9 +936,7 @@ export class LucidStateStore {
     }
     /** {@link hasWakeMarkerColumn} on the caller's transaction (a single-connection pool has no other). */
     hasWakeMarkerColumnIn(trx) {
-        this.wakeMarkerColumn ??= trx.schema
-            .hasColumn(DURABLE_TABLES.runs, 'wake_requested_at')
-            .catch(() => {
+        this.wakeMarkerColumn ??= hasColumn(trx, this.schema, DURABLE_TABLES.runs, 'wake_requested_at').catch(() => {
             this.wakeMarkerColumn = undefined;
             return false;
         });
@@ -862,9 +945,7 @@ export class LucidStateStore {
     /** Whether the runs table has `wake_requested_at`, probed once per store and cached. */
     wakeMarkerColumn;
     hasWakeMarkerColumn() {
-        this.wakeMarkerColumn ??= this.client()
-            .schema.hasColumn(DURABLE_TABLES.runs, 'wake_requested_at')
-            .catch(() => {
+        this.wakeMarkerColumn ??= hasColumn(this.client(), this.schema, DURABLE_TABLES.runs, 'wake_requested_at').catch(() => {
             this.wakeMarkerColumn = undefined;
             return false;
         });
@@ -873,10 +954,10 @@ export class LucidStateStore {
     async renewRunLock(runId, owner, leaseUntilMs) {
         const hot = this.hot();
         if (hot)
-            return (await hot.run(RENEW_LOCK_SQL, [leaseUntilMs, runId, owner])).count === 1;
+            return (await hot.run(this.sql.renewLock, [leaseUntilMs, runId, owner])).count === 1;
         // Extend ONLY if `owner` still holds the lease — a dead worker's lease still expires & is reclaimed.
         const affected = await this.client()
-            .from(DURABLE_TABLES.runs)
+            .from(this.t.runs)
             .where('id', runId)
             .andWhere('locked_by', owner)
             .update({ locked_until: leaseUntilMs });
@@ -888,7 +969,7 @@ export class LucidStateStore {
         // runs once per wait registration, i.e. on every signal/child/event suspension).
         await this.client()
             .insertQuery()
-            .table(DURABLE_TABLES.signalWaiters)
+            .table(this.t.signalWaiters)
             .knexQuery.insert({
             token: waiter.token,
             run_id: waiter.runId,
@@ -903,10 +984,10 @@ export class LucidStateStore {
         // the same waiter to two callers. The DELETE arbitrates, so no transaction is needed around it,
         // and a token with no waiter (the common case) costs one read.
         const client = this.client();
-        const row = await client.from(DURABLE_TABLES.signalWaiters).where('token', token).first();
+        const row = await client.from(this.t.signalWaiters).where('token', token).first();
         if (!row)
             return null;
-        const deleted = await client.from(DURABLE_TABLES.signalWaiters).where('token', token).delete();
+        const deleted = await client.from(this.t.signalWaiters).where('token', token).delete();
         if (rowsAffected(deleted) !== 1)
             return null;
         return rowToSignalWaiter(row);
@@ -915,14 +996,14 @@ export class LucidStateStore {
         // The prefix embeds caller-supplied names (event names via eventPrefix) — escape their LIKE
         // metacharacters so a name containing `%`/`_` can't scan (or match) other tokens.
         const rows = await this.client()
-            .from(DURABLE_TABLES.signalWaiters)
+            .from(this.t.signalWaiters)
             .whereRaw(`token like ? escape '!'`, [`${escapeLike(prefix)}%`]);
         return rows.map(rowToSignalWaiter);
     }
     async listSignalWaitersByRunIds(runIds) {
         if (runIds.length === 0)
             return [];
-        const rows = await this.client().from(DURABLE_TABLES.signalWaiters).whereIn('run_id', runIds);
+        const rows = await this.client().from(this.t.signalWaiters).whereIn('run_id', runIds);
         return rows.map(rowToSignalWaiter);
     }
     async hasSignalWaiter(runId, tokenPrefix) {
@@ -930,7 +1011,7 @@ export class LucidStateStore {
         // MySQL's default collations ignore case), so a hit is confirmed in JS. Only a match that is not
         // a real prefix match pays for reading the run's whole matching set.
         const matching = () => this.client()
-            .from(DURABLE_TABLES.signalWaiters)
+            .from(this.t.signalWaiters)
             .select('token')
             .where('run_id', runId)
             .andWhereRaw(`token like ? escape '!'`, [`${escapeLike(tokenPrefix)}%`]);
@@ -953,7 +1034,7 @@ export class LucidStateStore {
                 const chunk = entries.slice(at, at + CHILD_WAIT_ROWS);
                 await trx
                     .insertQuery()
-                    .table(DURABLE_TABLES.signalWaiters)
+                    .table(this.t.signalWaiters)
                     .knexQuery.insert(chunk.map(({ waiter }) => ({
                     token: waiter.token,
                     run_id: waiter.runId,
@@ -967,7 +1048,7 @@ export class LucidStateStore {
                 const chunk = entries.slice(at, at + CHILD_WAIT_ROWS);
                 await trx
                     .insertQuery()
-                    .table(DURABLE_TABLES.checkpoints)
+                    .table(this.t.checkpoints)
                     .knexQuery.insert(chunk.map(({ checkpoint }) => checkpointToRow(checkpoint)))
                     .onConflict(['run_id', 'seq'])
                     .merge();
@@ -977,7 +1058,7 @@ export class LucidStateStore {
     async compactCheckpoints(runId, fromSeq, toSeq, into) {
         await this.client().transaction(async (trx) => {
             await trx
-                .from(DURABLE_TABLES.checkpoints)
+                .from(this.t.checkpoints)
                 .where('run_id', runId)
                 .andWhere('seq', '>=', fromSeq)
                 .andWhere('seq', '<=', toSeq)
@@ -990,7 +1071,7 @@ export class LucidStateStore {
         // primary key, so a later putSignalWaiter for the same token may have replaced the row with a
         // different run's waiter — the run_id/seq predicate leaves that one untouched. No-op if absent.
         await this.client()
-            .from(DURABLE_TABLES.signalWaiters)
+            .from(this.t.signalWaiters)
             .where('token', waiter.token)
             .andWhere('run_id', waiter.runId)
             .andWhere('seq', waiter.seq)
@@ -999,12 +1080,12 @@ export class LucidStateStore {
     // --- buffered signals (FIFO per token) ----------------------------------
     async bufferSignal(token, payload) {
         await this.client()
-            .table(DURABLE_TABLES.bufferedSignals)
+            .table(this.t.bufferedSignals)
             .insert({ token, payload: payload === undefined ? null : JSON.stringify(payload) });
     }
     async listBufferedSignalTokens(prefix, limit) {
         const rows = (await this.client()
-            .from(DURABLE_TABLES.bufferedSignals)
+            .from(this.t.bufferedSignals)
             .whereRaw(`token like ? escape '!'`, [`${escapeLike(prefix)}%`])
             .distinct('token')
             .orderBy('token', 'asc')
@@ -1013,7 +1094,7 @@ export class LucidStateStore {
     }
     async listBufferedSignals(tokenPrefix, afterId, limit) {
         const q = this.client()
-            .from(DURABLE_TABLES.bufferedSignals)
+            .from(this.t.bufferedSignals)
             .whereRaw(`token like ? escape '!'`, [`${escapeLike(tokenPrefix)}%`]);
         if (afterId !== undefined)
             q.where('id', '>', Number(afterId));
@@ -1029,7 +1110,7 @@ export class LucidStateStore {
     async deleteBufferedSignals(ids) {
         for (let at = 0; at < ids.length; at += 500) {
             await this.client()
-                .from(DURABLE_TABLES.bufferedSignals)
+                .from(this.t.bufferedSignals)
                 .whereIn('id', ids.slice(at, at + 500).map((id) => Number(id)))
                 .delete();
         }
@@ -1040,9 +1121,9 @@ export class LucidStateStore {
         const client = this.client();
         const hot = this.hot();
         const row = hot
-            ? (await hot.rows(OLDEST_BUFFERED_SIGNAL_SQL, [token]))[0]
+            ? (await hot.rows(this.sql.oldestBufferedSignal, [token]))[0]
             : await client
-                .from(DURABLE_TABLES.bufferedSignals)
+                .from(this.t.bufferedSignals)
                 .where('token', token)
                 .orderBy('id', 'asc')
                 .first();
@@ -1050,8 +1131,8 @@ export class LucidStateStore {
             return null;
         const r = row;
         const deleted = hot
-            ? (await hot.run(DELETE_BUFFERED_SIGNAL_SQL, [r.id])).count
-            : rowsAffected(await client.from(DURABLE_TABLES.bufferedSignals).where('id', r.id).delete());
+            ? (await hot.run(this.sql.deleteBufferedSignal, [r.id])).count
+            : rowsAffected(await client.from(this.t.bufferedSignals).where('id', r.id).delete());
         if (deleted !== 1)
             return null;
         return {
@@ -1061,7 +1142,7 @@ export class LucidStateStore {
     // --- buffered events (name-keyed, match-based consumption) ---------------
     async bufferEvent(input) {
         await this.client()
-            .table(DURABLE_TABLES.bufferedEvents)
+            .table(this.t.bufferedEvents)
             .insert({
             id: input.id,
             name: input.name,
@@ -1072,9 +1153,9 @@ export class LucidStateStore {
     async listBufferedEvents(name, limit) {
         const hot = this.hot();
         const rows = hot
-            ? await hot.rows(BUFFERED_EVENTS_SQL, [name, limit])
+            ? await hot.rows(this.sql.bufferedEvents, [name, limit])
             : await this.client()
-                .from(DURABLE_TABLES.bufferedEvents)
+                .from(this.t.bufferedEvents)
                 .where('name', name)
                 .orderBy('published_at', 'asc') // oldest first
                 .limit(limit);
@@ -1091,7 +1172,7 @@ export class LucidStateStore {
         // IN subquery. The age predicate is repeated on the DELETE so a row re-published under the same
         // id meanwhile is left alone.
         const rows = (await this.client()
-            .from(DURABLE_TABLES.bufferedEvents)
+            .from(this.t.bufferedEvents)
             .select('id')
             .where('published_at', '<', publishedBefore)
             .orderBy('published_at', 'asc')
@@ -1099,7 +1180,7 @@ export class LucidStateStore {
         if (rows.length === 0)
             return 0;
         const deleted = await this.client()
-            .from(DURABLE_TABLES.bufferedEvents)
+            .from(this.t.bufferedEvents)
             .whereIn('id', rows.map((r) => r.id))
             .andWhere('published_at', '<', publishedBefore)
             .delete();
@@ -1108,10 +1189,7 @@ export class LucidStateStore {
     async removeBufferedEvent(id) {
         // Atomic claim: whoever's delete affects the row (returns 1) is the one that gets to deliver;
         // a concurrent claimant sees 0 and backs off. `id` is the primary key.
-        const deleted = await this.client()
-            .from(DURABLE_TABLES.bufferedEvents)
-            .where('id', id)
-            .delete();
+        const deleted = await this.client().from(this.t.bufferedEvents).where('id', id).delete();
         return rowsAffected(deleted) === 1;
     }
     // --- transaction (exactly-once business write + checkpoint) -------------
@@ -1143,13 +1221,13 @@ export class LucidStateStore {
         const row = scheduleToRow(record);
         await this.client()
             .insertQuery()
-            .table(DURABLE_TABLES.schedules)
+            .table(this.t.schedules)
             .knexQuery.insert(row)
             .onConflict('id')
             .merge();
     }
     async getSchedule(id) {
-        const row = await this.client().from(DURABLE_TABLES.schedules).where('id', id).first();
+        const row = await this.client().from(this.t.schedules).where('id', id).first();
         return row ? rowToSchedule(row) : null;
     }
     /** One conditional UPDATE: the compare-and-set on `next_fire_at` lives in its WHERE clause. */
@@ -1173,7 +1251,7 @@ export class LucidStateStore {
             set.updated_at = patch.updatedAt.getTime();
         if (!Object.keys(set).length)
             return (await this.getSchedule(id)) !== null;
-        const q = this.client().from(DURABLE_TABLES.schedules).where('id', id);
+        const q = this.client().from(this.t.schedules).where('id', id);
         if (expectedNextFireAt === null)
             q.whereNull('next_fire_at');
         else if (expectedNextFireAt !== undefined)
@@ -1181,11 +1259,11 @@ export class LucidStateStore {
         return rowsAffected(await q.update(set)) > 0;
     }
     async deleteSchedule(id) {
-        const affected = await this.client().from(DURABLE_TABLES.schedules).where('id', id).delete();
+        const affected = await this.client().from(this.t.schedules).where('id', id).delete();
         return rowsAffected(affected) > 0;
     }
     async listSchedules(query) {
-        const q = this.client().from(DURABLE_TABLES.schedules);
+        const q = this.client().from(this.t.schedules);
         if (query.namespace !== undefined) {
             q.whereIn('namespace', namespaceFilterValues(query.namespace));
         }
@@ -1246,7 +1324,7 @@ export class LucidStateStore {
                 q.limit(scan);
             return runValueFacetsFromRuns((await q).map(rowToRun), axis, opts);
         }
-        const column = axis.field;
+        const column = axis.field === 'tenant' ? 'tenant_id' : axis.field;
         const needle = opts?.search?.trim().toLowerCase();
         // One pass over the matching runs (the shape `runFacets` uses), not a self semi-join on `id`.
         const q = this.scopedRuns(query)
@@ -1268,7 +1346,7 @@ export class LucidStateStore {
      * exactly the set the list would show.
      */
     scopedRuns(query) {
-        const q = this.fenced(this.client().from(DURABLE_TABLES.runs));
+        const q = this.fenced(this.client().from(this.t.runs));
         if (query.workflow)
             q.where('workflow', query.workflow);
         if (query.workflows) {
@@ -1292,6 +1370,23 @@ export class LucidStateStore {
         }
         if (query.origin)
             q.where('origin', query.origin);
+        if (query.tenantId !== undefined)
+            q.where('tenant_id', query.tenantId);
+        if (query.tenantIds) {
+            // `tenant_id IN (...)`, with `null` standing for "no tenant"; an empty set matches nothing.
+            const ids = query.tenantIds.filter((id) => id !== null);
+            const withNull = query.tenantIds.includes(null);
+            if (ids.length === 0 && !withNull)
+                q.whereRaw('1 = 0');
+            else {
+                q.andWhere((or) => {
+                    if (ids.length)
+                        or.orWhereIn('tenant_id', ids);
+                    if (withNull)
+                        or.orWhereNull('tenant_id');
+                });
+            }
+        }
         if (query.status)
             q.where('status', query.status);
         if (query.statuses) {
@@ -1355,10 +1450,10 @@ export class LucidStateStore {
             }
             q.whereExists((sub) => {
                 sub
-                    .from(DURABLE_TABLES.attributes)
-                    .whereRaw(`${DURABLE_TABLES.attributes}.run_id = ${DURABLE_TABLES.runs}.id`)
-                    .andWhere(`${DURABLE_TABLES.attributes}.key`, f.key)
-                    .whereIn(`${DURABLE_TABLES.attributes}.${col}`, operands);
+                    .from(this.t.attributes)
+                    .whereRaw('?? = ??', [`${this.t.attributes}.run_id`, `${this.t.runs}.id`])
+                    .andWhere(`${this.t.attributes}.key`, f.key)
+                    .whereIn(`${this.t.attributes}.${col}`, operands);
             });
             return;
         }
@@ -1366,15 +1461,15 @@ export class LucidStateStore {
         const operand = attributeOperand(f);
         q.whereExists((sub) => {
             sub
-                .from(DURABLE_TABLES.attributes)
-                .whereRaw(`${DURABLE_TABLES.attributes}.run_id = ${DURABLE_TABLES.runs}.id`)
-                .andWhere(`${DURABLE_TABLES.attributes}.key`, f.key)
-                .andWhere(`${DURABLE_TABLES.attributes}.${col}`, cmp, operand);
+                .from(this.t.attributes)
+                .whereRaw('?? = ??', [`${this.t.attributes}.run_id`, `${this.t.runs}.id`])
+                .andWhere(`${this.t.attributes}.key`, f.key)
+                .andWhere(`${this.t.attributes}.${col}`, cmp, operand);
         });
     }
     async listCheckpoints(runId) {
         const rows = await this.client()
-            .from(DURABLE_TABLES.checkpoints)
+            .from(this.t.checkpoints)
             .where('run_id', runId)
             .orderBy('seq', 'asc');
         return rows.map(rowToCheckpoint);
@@ -1382,9 +1477,9 @@ export class LucidStateStore {
     async listCheckpointsForReplay(runId) {
         const hot = this.hot();
         const rows = (hot
-            ? await hot.rows(REPLAY_CHECKPOINTS_SQL, [runId])
+            ? await hot.rows(this.sql.replayCheckpoints, [runId])
             : await this.client()
-                .from(DURABLE_TABLES.checkpoints)
+                .from(this.t.checkpoints)
                 .where('run_id', runId)
                 .orderBy('seq', 'asc')
                 .select(...CHECKPOINT_COLUMNS_BUT_INPUT));
@@ -1397,7 +1492,7 @@ export class LucidStateStore {
             const inputs = new Map();
             for (let at = 0; at < unsettled.length; at += CHECKPOINT_BATCH) {
                 const found = (await this.client()
-                    .from(DURABLE_TABLES.checkpoints)
+                    .from(this.t.checkpoints)
                     .where('run_id', runId)
                     .whereIn('seq', unsettled.slice(at, at + CHECKPOINT_BATCH))
                     .select('seq', 'input'));
@@ -1413,7 +1508,7 @@ export class LucidStateStore {
     }
     async getLatestCheckpointByName(runId, name) {
         const row = await this.client()
-            .from(DURABLE_TABLES.checkpoints)
+            .from(this.t.checkpoints)
             .where('run_id', runId)
             .andWhere('name', name)
             .orderBy('seq', 'desc')
@@ -1424,7 +1519,7 @@ export class LucidStateStore {
         if (prefixes.length === 0)
             return [];
         const rows = await this.client()
-            .from(DURABLE_TABLES.checkpoints)
+            .from(this.t.checkpoints)
             .where('run_id', runId)
             .andWhere((q) => {
             for (const p of prefixes)
@@ -1438,11 +1533,11 @@ export class LucidStateStore {
             return 0;
         const hot = this.hot();
         if (hot) {
-            const rows = await hot.rows(COUNT_CHECKPOINTS_SQL, [runId, fromSeq, toSeq, statuses]);
+            const rows = await hot.rows(this.sql.countCheckpoints, [runId, fromSeq, toSeq, statuses]);
             return Number(rows[0]?.count ?? 0);
         }
         const rows = await this.client()
-            .from(DURABLE_TABLES.checkpoints)
+            .from(this.t.checkpoints)
             .where('run_id', runId)
             .andWhere('seq', '>=', fromSeq)
             .andWhere('seq', '<=', toSeq)
@@ -1455,7 +1550,7 @@ export class LucidStateStore {
         if (statuses.length === 0)
             return false;
         const row = await this.client()
-            .from(DURABLE_TABLES.checkpoints)
+            .from(this.t.checkpoints)
             .select('seq')
             .where('run_id', runId)
             .andWhere('seq', '>=', fromSeq)
@@ -1475,7 +1570,7 @@ export class LucidStateStore {
         const client = this.client();
         const kind = nameKindSql(client.dialect.name);
         const q = client
-            .from(DURABLE_TABLES.checkpoints)
+            .from(this.t.checkpoints)
             .select('parallel_group as grp', 'status')
             .select(client.raw(`${kind} as name_kind`))
             .count('* as n')
@@ -1521,7 +1616,7 @@ export class LucidStateStore {
         if (query.statuses?.length === 0 || query.namePrefixes?.length === 0)
             return [];
         const client = this.client();
-        const q = client.from(DURABLE_TABLES.checkpoints).where('run_id', runId);
+        const q = client.from(this.t.checkpoints).where('run_id', runId);
         if (query.group !== undefined)
             q.andWhere('parallel_group', query.group);
         if (query.excludeGroups?.length) {
@@ -1556,10 +1651,10 @@ export class LucidStateStore {
     /** Rewrite a run's normalized attribute rows: delete the old set, insert the current one. Mirrors
      *  the in-memory store's reindex so the side-table always reflects the run's live searchAttributes. */
     async reindexAttributes(client, runId, attributes) {
-        await client.from(DURABLE_TABLES.attributes).where('run_id', runId).delete();
+        await client.from(this.t.attributes).where('run_id', runId).delete();
         const rows = normalizeAttributeRows(runId, attributes);
         if (rows.length) {
-            await client.table(DURABLE_TABLES.attributes).multiInsert(rows.map((r) => ({
+            await client.table(this.t.attributes).multiInsert(rows.map((r) => ({
                 run_id: r.runId,
                 key: r.key,
                 str_value: r.strValue,
@@ -1568,6 +1663,43 @@ export class LucidStateStore {
         }
     }
 }
+/**
+ * Serialize the store's work on a transaction client. A transaction is ONE connection: two store
+ * calls in flight at once (a background run pickup next to a request's own write, under an app's test
+ * `wrapInGlobalTransaction`) would send overlapping queries down it, which `pg` deprecates (and 9.0
+ * removes), and a statement could land inside a savepoint the other call is rolling back. So while
+ * the store's client is a transaction, each call waits for the previous one on that transaction to
+ * finish. Re-entrant: a store method calling another one in the same call does not wait for itself.
+ * A store on a plain connection is untouched (its pool hands each query its own connection).
+ */
+const transactionTails = new WeakMap();
+const holdingTransaction = new AsyncLocalStorage();
+function serializeOnTransactions(proto) {
+    const AsyncFunction = (async () => { }).constructor;
+    for (const name of Object.getOwnPropertyNames(proto)) {
+        if (name === 'constructor')
+            continue;
+        const descriptor = Object.getOwnPropertyDescriptor(proto, name);
+        const original = descriptor?.value;
+        if (typeof original !== 'function' || !(original instanceof AsyncFunction))
+            continue;
+        const method = original;
+        Object.defineProperty(proto, name, {
+            ...descriptor,
+            value: function (...args) {
+                const client = this.client();
+                if (!client.isTransaction || holdingTransaction.getStore() === client) {
+                    return method.apply(this, args);
+                }
+                const previous = transactionTails.get(client) ?? Promise.resolve();
+                const run = previous.then(() => holdingTransaction.run(client, () => method.apply(this, args)), () => holdingTransaction.run(client, () => method.apply(this, args)));
+                transactionTails.set(client, run.catch(() => undefined));
+                return run;
+            },
+        });
+    }
+}
+serializeOnTransactions(LucidStateStore.prototype);
 /**
  * Escape LIKE metacharacters (`%`, `_`) — and the escape character itself — using `!` as the ESCAPE
  * char. `!` because a backslash inside a SQL string literal is dialect-divergent (MySQL treats it as
@@ -1618,20 +1750,20 @@ const CHECKPOINT_BATCH = 500;
 /** Most checkpoint rows one multi-row upsert writes (kept under every dialect's bind limit). */
 const CHECKPOINT_UPSERT_BATCH = 200;
 /** One multi-row `INSERT … ON CONFLICT (run_id, seq) DO UPDATE` (MySQL: `ON DUPLICATE KEY`). */
-async function upsertCheckpointRows(client, checkpoints) {
+async function upsertCheckpointRows(client, checkpointsTable, checkpoints) {
     if (checkpoints.length === 0)
         return;
     await client
         .insertQuery()
-        .table(DURABLE_TABLES.checkpoints)
+        .table(checkpointsTable)
         .knexQuery.insert(checkpoints.map(checkpointToRow))
         .onConflict(['run_id', 'seq'])
         .merge();
 }
-async function updateCheckpointIfPending(client, checkpoint) {
+async function updateCheckpointIfPending(client, checkpointsTable, checkpoint) {
     const { run_id: _runId, seq: _seq, ...row } = checkpointToRow(checkpoint);
     const affected = await client
-        .from(DURABLE_TABLES.checkpoints)
+        .from(checkpointsTable)
         .where('run_id', checkpoint.runId)
         .andWhere('seq', checkpoint.seq)
         .andWhere('status', 'pending')
@@ -1661,55 +1793,114 @@ function escapeLike(value) {
     return value.replace(/[!%_]/g, (c) => `!${c}`);
 }
 // --- the Postgres hot path's statements (see `lucid-pg-hot-path.ts`) --------------------------------
-const RUNS_T = quote(DURABLE_TABLES.runs);
-const CHECKPOINTS_T = quote(DURABLE_TABLES.checkpoints);
 const CHECKPOINT_LIST = CHECKPOINT_COLUMNS_BUT_INPUT.map(quote).join(', ');
-const GET_RUN_SQL = `select * from ${RUNS_T} where "id" = ? limit 1`;
-const GET_RUN_SCOPED_SQL = `select * from ${RUNS_T} where "id" = ? and "namespace" = any(?) limit 1`;
-const RUN_IN_STATUSES_SQL = `select 1 from ${RUNS_T} where "id" = ? and "status" = any(?) limit 1`;
-const LOCK_AND_GET_SQL = `update ${RUNS_T} set "locked_by" = ?, "locked_until" = ? where "id" = ? and ("locked_until" is null or "locked_until" <= ?) returning *`;
-const LOCK_AND_GET_SCOPED_SQL = `update ${RUNS_T} set "locked_by" = ?, "locked_until" = ? where "id" = ? and ("locked_until" is null or "locked_until" <= ?) and "namespace" = any(?) returning *`;
-const RELEASE_LOCK_SQL = `update ${RUNS_T} set "locked_by" = null, "locked_until" = null where "id" = ?`;
-const RELEASE_OWN_LOCK_SQL = `update ${RUNS_T} set "locked_by" = null, "locked_until" = null where "id" = ? and "locked_by" = ?`;
-const RELEASE_UNLESS_WAKE_SQL = `update ${RUNS_T} set "locked_by" = null, "locked_until" = null where "id" = ? and "locked_by" = ? and "wake_requested_at" is null`;
-const LOCKED_BY_SQL = `select "locked_by" from ${RUNS_T} where "id" = ? limit 1`;
-const RENEW_LOCK_SQL = `update ${RUNS_T} set "locked_until" = ? where "id" = ? and "locked_by" = ?`;
-const DELETE_ATTRIBUTES_SQL = `delete from ${quote(DURABLE_TABLES.attributes)} where "run_id" = ?`;
-const GET_CHECKPOINT_SQL = `select * from ${CHECKPOINTS_T} where "run_id" = ? and "seq" = ? limit 1`;
-const CHECKPOINTS_FOR_SETTLE_SQL = `select ${CHECKPOINT_LIST} from ${CHECKPOINTS_T} where "run_id" = ? and "seq" = any(?)`;
-const REPLAY_CHECKPOINTS_SQL = `select ${CHECKPOINT_LIST} from ${CHECKPOINTS_T} where "run_id" = ? order by "seq" asc`;
-const COUNT_CHECKPOINTS_SQL = `select count(*) as "count" from ${CHECKPOINTS_T} where "run_id" = ? and "seq" >= ? and "seq" <= ? and "status" = any(?)`;
-const OLDEST_BUFFERED_SIGNAL_SQL = `select * from ${quote(DURABLE_TABLES.bufferedSignals)} where "token" = ? order by "id" asc limit 1`;
-const DELETE_BUFFERED_SIGNAL_SQL = `delete from ${quote(DURABLE_TABLES.bufferedSignals)} where "id" = ?`;
-const BUFFERED_EVENTS_SQL = `select * from ${quote(DURABLE_TABLES.bufferedEvents)} where "name" = ? order by "published_at" asc limit ?`;
-/** Statements whose column list is the row's own keys, built once per key set. */
-const shaped = new Map();
-function shapedSql(key, build) {
-    let text = shaped.get(key);
-    if (text === undefined) {
-        text = build();
-        shaped.set(key, text);
-    }
-    return text;
-}
-/** `INSERT` of one row of `table` with the columns `keys`. */
-function insertSql(table, keys) {
-    return shapedSql(`insert:${table}:${keys.join(',')}`, () => {
-        const cols = keys.map(quote).join(', ');
-        return `insert into ${quote(table)} (${cols}) values (${keys.map(() => '?').join(', ')})`;
-    });
-}
-/** {@link insertSql} of a checkpoint that writes nothing when its position is taken. */
-function insertCheckpointIfAbsentSql(keys) {
-    return shapedSql(`insert-if-absent:${keys.join(',')}`, () => `${insertSql(DURABLE_TABLES.checkpoints, keys)} on conflict ("run_id", "seq") do nothing returning "seq"`);
+/**
+ * The runs columns every schema has. The hot path names its columns instead of `*`: a named prepared
+ * statement's result type is fixed when it is parsed, so a `*` statement fails ("cached plan must
+ * not change result type") once a column is added under it — another pod's `ensureSchema` during a
+ * rolling upgrade.
+ */
+const RUN_BASE_COLUMNS = [
+    'id',
+    'workflow',
+    'workflow_version',
+    'status',
+    'namespace',
+    'input',
+    'output',
+    'error',
+    'wake_at',
+    'locked_by',
+    'locked_until',
+    'recovery_attempts',
+    'tags',
+    'search_attributes',
+    'priority',
+    'created_at',
+    'updated_at',
+];
+/** Runs columns that arrived in later schema waves: read only when the table has them. */
+const RUN_OPTIONAL_COLUMNS = [
+    'origin',
+    'awaiting_decision_task_id',
+    'wake_requested_at',
+    'tenant_id',
+    'tenant_kind',
+];
+/** Checkpoint columns that arrived in later schema waves: read only when the table has them. */
+const CHECKPOINT_OPTIONAL_COLUMNS = [
+    'queue',
+    'parallel_group',
+    'last_heartbeat_at',
+    'heartbeat_progress',
+];
+const CHECKPOINT_BASE_COLUMNS = [
+    ...CHECKPOINT_COLUMNS_BUT_INPUT.filter((c) => !CHECKPOINT_OPTIONAL_COLUMNS.includes(c)),
+    'input',
+];
+/** The later-wave columns present, in the configured schema (`?` first) or the current one. */
+const COLUMNS_PRESENT_SQL = `select "table_name", "column_name" from information_schema.columns where "table_schema" = coalesce(?, current_schema()) and "table_name" = any(?) and "column_name" = any(?)`;
+const BUFFERED_SIGNAL_LIST = ['id', 'token', 'payload'].map(quote).join(', ');
+const BUFFERED_EVENT_LIST = ['id', 'name', 'payload', 'published_at'].map(quote).join(', ');
+/** A quoted, schema-qualified table name for raw SQL: `"schema"."table"`, or `"table"`. */
+function quotedTable(schema, table) {
+    return schema ? `${quote(schema)}.${quote(table)}` : quote(table);
 }
-/** `UPDATE` of one run's columns `keys`, with a status predicate when `conditional`. */
-function updateRunSql(keys, conditional) {
-    return shapedSql(`update-run:${conditional}:${keys.join(',')}`, () => {
-        const set = keys.map((k) => `${quote(k)} = ?`).join(', ');
-        const where = conditional ? `"id" = ? and "status" = any(?)` : `"id" = ?`;
-        return `update ${RUNS_T} set ${set} where ${where}`;
-    });
+const hotStatementsBySchema = new Map();
+/** {@link HotStatements} for `schema` (the connection's current schema when unset). */
+function hotStatements(schema) {
+    const cacheKey = schema ?? '';
+    const cached = hotStatementsBySchema.get(cacheKey);
+    if (cached)
+        return cached;
+    const RUNS_T = quotedTable(schema, DURABLE_TABLES.runs);
+    const CHECKPOINTS_T = quotedTable(schema, DURABLE_TABLES.checkpoints);
+    const ATTRIBUTES_T = quotedTable(schema, DURABLE_TABLES.attributes);
+    const SIGNALS_T = quotedTable(schema, DURABLE_TABLES.bufferedSignals);
+    const EVENTS_T = quotedTable(schema, DURABLE_TABLES.bufferedEvents);
+    /** Statements whose column list is the row's own keys, built once per key set. */
+    const shaped = new Map();
+    const shapedSql = (key, build) => {
+        let text = shaped.get(key);
+        if (text === undefined) {
+            text = build();
+            shaped.set(key, text);
+        }
+        return text;
+    };
+    /** `INSERT` of one row of `table` (quoted) with the columns `keys`. */
+    const insertSql = (table, keys) => `insert into ${table} (${keys.map(quote).join(', ')}) values (${keys.map(() => '?').join(', ')})`;
+    const statements = {
+        reads: (cols, checkpointCols) => ({
+            getCheckpoint: shapedSql(`checkpoint-get:${checkpointCols}`, () => `select ${checkpointCols} from ${CHECKPOINTS_T} where "run_id" = ? and "seq" = ? limit 1`),
+            get: shapedSql(`run-get:${cols}`, () => `select ${cols} from ${RUNS_T} where "id" = ? limit 1`),
+            getScoped: shapedSql(`run-get-scoped:${cols}`, () => `select ${cols} from ${RUNS_T} where "id" = ? and "namespace" = any(?) limit 1`),
+            lockAndGet: shapedSql(`run-lock:${cols}`, () => `update ${RUNS_T} set "locked_by" = ?, "locked_until" = ? where "id" = ? and ("locked_until" is null or "locked_until" <= ?) returning ${cols}`),
+            lockAndGetScoped: shapedSql(`run-lock-scoped:${cols}`, () => `update ${RUNS_T} set "locked_by" = ?, "locked_until" = ? where "id" = ? and ("locked_until" is null or "locked_until" <= ?) and "namespace" = any(?) returning ${cols}`),
+        }),
+        runInStatuses: `select 1 from ${RUNS_T} where "id" = ? and "status" = any(?) limit 1`,
+        releaseLock: `update ${RUNS_T} set "locked_by" = null, "locked_until" = null where "id" = ?`,
+        releaseOwnLock: `update ${RUNS_T} set "locked_by" = null, "locked_until" = null where "id" = ? and "locked_by" = ?`,
+        releaseUnlessWake: `update ${RUNS_T} set "locked_by" = null, "locked_until" = null where "id" = ? and "locked_by" = ? and "wake_requested_at" is null`,
+        lockedBy: `select "locked_by" from ${RUNS_T} where "id" = ? limit 1`,
+        renewLock: `update ${RUNS_T} set "locked_until" = ? where "id" = ? and "locked_by" = ?`,
+        deleteAttributes: `delete from ${ATTRIBUTES_T} where "run_id" = ?`,
+        checkpointsForSettle: `select ${CHECKPOINT_LIST} from ${CHECKPOINTS_T} where "run_id" = ? and "seq" = any(?)`,
+        replayCheckpoints: `select ${CHECKPOINT_LIST} from ${CHECKPOINTS_T} where "run_id" = ? order by "seq" asc`,
+        countCheckpoints: `select count(*) as "count" from ${CHECKPOINTS_T} where "run_id" = ? and "seq" >= ? and "seq" <= ? and "status" = any(?)`,
+        oldestBufferedSignal: `select ${BUFFERED_SIGNAL_LIST} from ${SIGNALS_T} where "token" = ? order by "id" asc limit 1`,
+        deleteBufferedSignal: `delete from ${SIGNALS_T} where "id" = ?`,
+        bufferedEvents: `select ${BUFFERED_EVENT_LIST} from ${EVENTS_T} where "name" = ? order by "published_at" asc limit ?`,
+        insertRunIfAbsent: (keys) => shapedSql(`insert-run-if-absent:${keys.join(',')}`, () => `${insertSql(RUNS_T, keys)} on conflict ("id") do nothing returning "id"`),
+        insertCheckpointIfAbsent: (keys) => shapedSql(`insert-if-absent:${keys.join(',')}`, () => `${insertSql(CHECKPOINTS_T, keys)} on conflict ("run_id", "seq") do nothing returning "seq"`),
+        updateRun: (keys, conditional) => shapedSql(`update-run:${conditional}:${keys.join(',')}`, () => {
+            const set = keys.map((k) => `${quote(k)} = ?`).join(', ');
+            const where = conditional ? `"id" = ? and "status" = any(?)` : `"id" = ?`;
+            return `update ${RUNS_T} set ${set} where ${where}`;
+        }),
+    };
+    hotStatementsBySchema.set(cacheKey, statements);
+    return statements;
 }
 /**
  * {@link LucidStateStore.settleResultsIfPending} on Postgres: one `UPDATE … FROM (VALUES …) …
@@ -1717,7 +1908,7 @@ function updateRunSql(keys, conditional) {
  * in the same statement, and read back with its `wake_at`. What a result does not carry keeps its
  * stored value: `output` unless it completed, `events` and `started_at` unless present.
  */
-async function settleResultsReturningPg(client, hot, results) {
+async function settleResultsReturningPg(client, hot, schema, results) {
     const values = [];
     const bindings = [];
     for (const r of results) {
@@ -1731,7 +1922,7 @@ async function settleResultsReturningPg(client, hot, results) {
     const cols = CHECKPOINT_COLUMNS_BUT_INPUT.map((c) => `c.${c}`).join(', ');
     const statuses = SETTLEABLE_RUN_STATUSES.map(() => '?').join(', ');
     bindings.push(...SETTLEABLE_RUN_STATUSES);
-    const sql = `update ${DURABLE_TABLES.checkpoints} as c set
+    const sql = `update ${quotedTable(schema, DURABLE_TABLES.checkpoints)} as c set
       status = v.status,
       output = case when v.status = 'completed' then v.output else c.output end,
       error = v.error,
@@ -1740,7 +1931,7 @@ async function settleResultsReturningPg(client, hot, results) {
       finished_at = v.finished_at
     from (values ${values.join(', ')})
       as v(run_id, seq, status, output, error, has_events, events, started_at, finished_at),
-      ${DURABLE_TABLES.runs} as r
+      ${quotedTable(schema, DURABLE_TABLES.runs)} as r
     where c.run_id = v.run_id and c.seq = v.seq and c.status = 'pending'
       and r.id = c.run_id and r.status in (${statuses})
     returning ${cols}, r.status as run_status, r.wake_at as run_wake_at`;
@@ -1758,14 +1949,36 @@ async function settleResultsReturningPg(client, hot, results) {
     }
     return out;
 }
-/** A duplicate-key violation, as MySQL and SQLite report it through Knex. */
-function isDuplicateKey(err) {
-    const e = err;
-    return (e?.code === 'ER_DUP_ENTRY' ||
-        e?.errno === 1062 ||
-        e?.code === 'SQLITE_CONSTRAINT_PRIMARYKEY' ||
-        e?.code === 'SQLITE_CONSTRAINT_UNIQUE' ||
-        e?.code === '23505');
+/**
+ * Insert `row` into `table` unless a row with the same `key` exists, as a statement that never
+ * fails on the conflict, and say whether it wrote. A failing statement would abort a surrounding
+ * Postgres transaction, so the conflict is never detected by catching a duplicate-key error.
+ *
+ * - Postgres and SQLite: `INSERT … ON CONFLICT (key) DO NOTHING RETURNING key`, a row back when it wrote.
+ * - MySQL: `INSERT … ON DUPLICATE KEY UPDATE key = IF(LAST_INSERT_ID(1), key, key)`, which leaves an
+ *   existing row as it is and reports `insertId` 1 for it, 0 for a row it wrote (`table` has no
+ *   AUTO_INCREMENT). The affected-row count cannot tell them apart (mysql2 counts found rows), and
+ *   `INSERT IGNORE` would turn a value the column cannot hold into a silent truncation.
+ */
+async function insertIfAbsent(client, table, row, key) {
+    if (client.dialect.name === 'mysql') {
+        const first = key[0];
+        const knex = client.getWriteClient();
+        const { sql, bindings } = client
+            .insertQuery()
+            .table(table)
+            .knexQuery.insert(row)
+            .onConflict(key)
+            .merge({ [first]: knex.raw('if(last_insert_id(1), ??, ??)', [first, first]) })
+            .toSQL()
+            .toNative();
+        const result = (await client.rawQuery(sql, bindings));
+        const header = (Array.isArray(result) ? result[0] : result);
+        return Number(header?.insertId ?? 0) === 0;
+    }
+    const insert = client.insertQuery().table(table).knexQuery.insert(row).onConflict(key);
+    const inserted = (await insert.ignore().returning(key[0]));
+    return inserted.length > 0;
 }
 function checkpointKey(runId, seq) {
     return `${runId}\u0000${seq}`;
@@ -1776,11 +1989,11 @@ function checkpointKey(runId, seq) {
  * so the database write lock is taken FIRST with a no-op write, and no other connection or process
  * settles a row between the read and the caller's writes.
  */
-async function lockPendingCheckpoints(trx, entries, columns) {
+async function lockPendingCheckpoints(trx, checkpointsTable, entries, columns) {
     const first = entries[0];
     if (first && !locksRows(trx)) {
         await trx
-            .from(DURABLE_TABLES.checkpoints)
+            .from(checkpointsTable)
             .where('run_id', first.runId)
             .andWhere('seq', first.seq)
             .andWhere('status', 'pending')
@@ -1797,7 +2010,7 @@ async function lockPendingCheckpoints(trx, entries, columns) {
         const seqs = [...seqSet];
         for (let at = 0; at < seqs.length; at += CHECKPOINT_BATCH) {
             const q = trx
-                .from(DURABLE_TABLES.checkpoints)
+                .from(checkpointsTable)
                 .where('run_id', runId)
                 .whereIn('seq', seqs.slice(at, at + CHECKPOINT_BATCH))
                 .andWhere('status', 'pending')
@@ -1834,6 +2047,10 @@ function scheduleToRow(r) {
         tags: r.tags?.length ? JSON.stringify(r.tags) : null,
         spec: JSON.stringify(r.spec),
         state: JSON.stringify(r.state),
+        // Only when set: a schedule with no tenant saves on a schema without the columns.
+        ...(r.tenantId !== undefined
+            ? { tenant_id: r.tenantId, tenant_kind: r.tenantKind ?? null }
+            : {}),
         created_at: r.createdAt.getTime(),
         updated_at: r.updatedAt.getTime(),
     };
@@ -1850,6 +2067,8 @@ function rowToSchedule(row) {
         paused: row.paused === true || row.paused === 1 || row.paused === '1' || row.paused === 'true',
         nextFireAt: row.next_fire_at == null ? null : Number(row.next_fire_at),
         ...(tags?.length ? { tags } : {}),
+        ...(row.tenant_id != null ? { tenantId: row.tenant_id } : {}),
+        ...(row.tenant_kind != null ? { tenantKind: row.tenant_kind } : {}),
         spec: parseJsonColumn(row.spec, `${DURABLE_TABLES.schedules}.spec`, row.id) ?? {},
         state: parseJsonColumn(row.state, `${DURABLE_TABLES.schedules}.state`, row.id) ?? {},
         createdAt: new Date(Number(row.created_at)),