@adonis-agora/durable 1.0.0-rc.15 → 1.0.0-rc.17

package/dist/src/stores/lucid.js

@@ -7,9 +7,10 @@ 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
@@ -27,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
@@ -72,6 +84,7 @@ export class LucidStateStore {
     hotReads(hot) {
         this.hotReadStatements ??= hot
             .rows(COLUMNS_PRESENT_SQL, [
+            this.schema ?? null,
             [DURABLE_TABLES.runs, DURABLE_TABLES.checkpoints],
             [...RUN_OPTIONAL_COLUMNS, ...CHECKPOINT_OPTIONAL_COLUMNS],
         ])
@@ -86,7 +99,7 @@ export class LucidStateStore {
                 ...CHECKPOINT_BASE_COLUMNS,
                 ...CHECKPOINT_OPTIONAL_COLUMNS.filter(has(DURABLE_TABLES.checkpoints)),
             ];
-            return hotReadSql(runCols.map(quote).join(', '), checkpointCols.map(quote).join(', '));
+            return this.sql.reads(runCols.map(quote).join(', '), checkpointCols.map(quote).join(', '));
         })
             .catch((error) => {
             this.hotReadStatements = undefined; // a failed probe is retried, never cached
@@ -96,10 +109,58 @@ export class LucidStateStore {
     }
     /** 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
@@ -114,21 +175,21 @@ export class LucidStateStore {
             if (hot) {
                 const row = runToRow(run);
                 const keys = Object.keys(row);
-                const inserted = await hot.rows(insertRunIfAbsentSql(keys), keys.map((k) => row[k]));
+                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(DELETE_ATTRIBUTES_SQL, [run.id]);
+                await hot.run(this.sql.deleteAttributes, [run.id]);
                 return;
             }
             const client = this.client();
-            if (!(await insertIfAbsent(client, DURABLE_TABLES.runs, runToRow(run), ['id']))) {
+            if (!(await insertIfAbsent(client, this.t.runs, runToRow(run), ['id']))) {
                 throw new RunAlreadyExistsError(run.id);
             }
-            await client.from(DURABLE_TABLES.attributes).where('run_id', run.id).delete();
+            await client.from(this.t.attributes).where('run_id', run.id).delete();
             return;
         }
         await this.client().transaction(async (trx) => {
-            if (!(await insertIfAbsent(trx, DURABLE_TABLES.runs, runToRow(run), ['id']))) {
+            if (!(await insertIfAbsent(trx, this.t.runs, runToRow(run), ['id']))) {
                 throw new RunAlreadyExistsError(run.id);
             }
             await this.reindexAttributes(trx, run.id, run.searchAttributes);
@@ -150,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;
         }
@@ -158,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);
@@ -171,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,
@@ -189,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);
@@ -199,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();
@@ -226,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))
@@ -236,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;
         });
@@ -273,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());
@@ -287,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)}"%`]);
@@ -311,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;
         });
@@ -331,14 +390,14 @@ export class LucidStateStore {
                 : 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) {
@@ -346,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) {
@@ -361,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();
             }
         });
     }
@@ -376,7 +435,7 @@ export class LucidStateStore {
             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();
@@ -387,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));
@@ -398,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);
@@ -406,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));
@@ -423,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');
@@ -452,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) {
@@ -468,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;
         });
@@ -479,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')
@@ -492,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',
@@ -521,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]);
@@ -544,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;
@@ -569,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]));
@@ -634,16 +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;
+            return (await hot.rows(this.sql.insertCheckpointIfAbsent(keys), values)).length > 0;
         }
-        return insertIfAbsent(client, DURABLE_TABLES.checkpoints, row, ['run_id', 'seq']);
+        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({
@@ -661,7 +720,7 @@ 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();
@@ -669,7 +728,7 @@ export class LucidStateStore {
     // --- recovery / dispatch queries ----------------------------------------
     async listIncompleteRuns(namespace) {
         const q = this.fenced(this.client()
-            .from(DURABLE_TABLES.runs)
+            .from(this.t.runs)
             .whereIn('status', [...RECOVERABLE_RUN_STATUSES]));
         if (namespace !== undefined)
             q.whereIn('namespace', namespaceFilterValues(namespace));
@@ -682,7 +741,7 @@ 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)
+            .from(this.t.runs)
             .whereIn('status', [...RECOVERABLE_RUN_STATUSES])
             .andWhere((sub) => {
             sub.whereNull('locked_until').orWhere('locked_until', '<=', nowMs);
@@ -695,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
@@ -722,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('*'));
@@ -733,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));
@@ -764,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));
@@ -787,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);
@@ -815,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);
@@ -836,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 });
@@ -855,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 });
@@ -875,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());
@@ -883,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;
         });
@@ -894,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;
         });
@@ -905,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 });
@@ -920,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,
@@ -935,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);
@@ -947,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) {
@@ -962,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)}%`]);
@@ -985,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,
@@ -999,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();
@@ -1009,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)
@@ -1022,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)
@@ -1031,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')
@@ -1045,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));
@@ -1061,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();
         }
@@ -1072,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();
@@ -1082,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 {
@@ -1093,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,
@@ -1104,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);
@@ -1123,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')
@@ -1131,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();
@@ -1140,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) -------------
@@ -1175,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. */
@@ -1205,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)
@@ -1213,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));
         }
@@ -1300,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) {
@@ -1404,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;
         }
@@ -1415,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);
@@ -1431,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));
@@ -1446,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'));
@@ -1462,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')
@@ -1473,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)
@@ -1487,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)
@@ -1504,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)
@@ -1524,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')
@@ -1570,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) {
@@ -1605,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,
@@ -1704,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')
@@ -1747,8 +1793,6 @@ 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(', ');
 /**
  * The runs columns every schema has. The hot path names its columns instead of `*`: a named prepared
@@ -1794,65 +1838,69 @@ const CHECKPOINT_BASE_COLUMNS = [
     ...CHECKPOINT_COLUMNS_BUT_INPUT.filter((c) => !CHECKPOINT_OPTIONAL_COLUMNS.includes(c)),
     'input',
 ];
-const COLUMNS_PRESENT_SQL = `select "table_name", "column_name" from information_schema.columns where "table_schema" = current_schema() and "table_name" = any(?) and "column_name" = any(?)`;
+/** 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(', ');
-/** {@link HotReads} for the runs column list `cols` and checkpoints column list `checkpointCols`
- *  (each quoted, comma-joined). */
-function hotReadSql(cols, checkpointCols) {
-    return {
-        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}`),
-    };
+/** 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);
 }
-const RUN_IN_STATUSES_SQL = `select 1 from ${RUNS_T} where "id" = ? and "status" = any(?) limit 1`;
-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 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 ${BUFFERED_SIGNAL_LIST} 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 ${BUFFERED_EVENT_LIST} 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 run that writes nothing when its id is taken, returning the id it wrote. */
-function insertRunIfAbsentSql(keys) {
-    return shapedSql(`insert-run-if-absent:${keys.join(',')}`, () => `${insertSql(DURABLE_TABLES.runs, keys)} on conflict ("id") do nothing returning "id"`);
-}
-/** {@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"`);
-}
-/** `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 …) …
@@ -1860,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) {
@@ -1874,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,
@@ -1883,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`;
@@ -1941,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')
@@ -1962,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')