@adonis-agora/durable 0.59.0 → 0.60.0

package/dist/src/stores/lucid.js

@@ -1,3 +1,4 @@
+import { SETTLEABLE_RUN_STATUSES } from '../interfaces.js';
 import { namespaceFilterValues, normalizeNamespace } from '../namespaces.js';
 import { mergeRunFacetRows } from '../run-facets.js';
 import { runPageWindow } from '../run-pagination.js';
@@ -5,6 +6,7 @@ import { axisIsRunColumn, mergeRunValueFacetRows, RUN_VALUE_FACET_LIMIT, RUN_VAL
 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 { 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';
 /**
  * A production-grade, persistent `StateStore` backed by AdonisJS **Lucid** (Knex). Runs, checkpoints,
@@ -47,6 +49,16 @@ export class LucidStateStore {
     client() {
         return this.connectionName ? this.db.connection(this.connectionName) : this.db.connection();
     }
+    /**
+     * 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.
+     */
+    hot() {
+        return LucidPgHotPath.for(this.client(), {
+            preparedStatements: this.options.preparedStatements,
+        });
+    }
     /** 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 } : {});
@@ -56,6 +68,14 @@ export class LucidStateStore {
         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,
             // as two statements. The insert goes first, so a run that already exists keeps its rows.
+            const hot = this.hot();
+            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]);
+                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();
@@ -77,6 +97,15 @@ export class LucidStateStore {
         return this.client().transaction((trx) => write(trx));
     }
     async updateRun(runId, patch) {
+        const hot = this.hotFor(patch);
+        if (hot) {
+            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]);
+            }
+            return;
+        }
         await this.writeRun(patch, async (trx) => {
             const row = await this.releaseSlot(trx, runId, patch);
             // Knex throws on an empty `.update({})`; skip the UPDATE when no mapped column changed.
@@ -89,6 +118,21 @@ export class LucidStateStore {
         });
     }
     async updateRunIf(runId, expectedStatuses, patch) {
+        const hot = this.hotFor(patch);
+        if (hot) {
+            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]);
+                return found.length > 0;
+            }
+            const { count } = await hot.run(updateRunSql(keys, true), [
+                ...keys.map((k) => row[k]),
+                runId,
+                expectedStatuses,
+            ]);
+            return count === 1;
+        }
         return this.writeRun(patch, async (trx) => {
             const row = await this.releaseSlot(trx, runId, patch);
             let applied;
@@ -119,6 +163,15 @@ export class LucidStateStore {
             return applied;
         });
     }
+    /**
+     * The hot path for a run write of `patch`: one that needs no transaction (see {@link writeRun}),
+     * on a connection that takes it.
+     */
+    hotFor(patch) {
+        if (settlesTerminally(patch) || 'searchAttributes' in patch)
+            return undefined;
+        return this.hot();
+    }
     async pullRunWakesIn(runIds, wakeAt) {
         if (runIds.length === 0)
             return;
@@ -222,6 +275,13 @@ export class LucidStateStore {
         });
     }
     async getRun(runId) {
+        const hot = this.hot();
+        if (hot) {
+            const rows = this.scopeNamespace === undefined
+                ? await hot.rows(GET_RUN_SQL, [runId])
+                : await hot.rows(GET_RUN_SCOPED_SQL, [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();
         return row ? rowToRun(row) : null;
     }
@@ -261,6 +321,11 @@ export class LucidStateStore {
     }
     // --- checkpoints --------------------------------------------------------
     async getCheckpoint(runId, seq) {
+        const hot = this.hot();
+        if (hot) {
+            const rows = await hot.rows(GET_CHECKPOINT_SQL, [runId, seq]);
+            return rows[0] ? rowToCheckpoint(rows[0]) : null;
+        }
         const row = await this.client()
             .from(DURABLE_TABLES.checkpoints)
             .where('run_id', runId)
@@ -282,6 +347,13 @@ export class LucidStateStore {
     }
     async getCheckpointsForSettle(runId, seqs) {
         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]);
+            return rows
+                .map(rowToCheckpoint)
+                .sort((a, b) => a.seq - b.seq);
+        }
         const out = [];
         for (let at = 0; at < unique.length; at += CHECKPOINT_BATCH) {
             const rows = (await this.client()
@@ -408,6 +480,135 @@ export class LucidStateStore {
             return wrote;
         });
     }
+    async settleResultsIfPending(results) {
+        if (results.length === 0)
+            return [];
+        // A later entry for a row an earlier one claims loses, before anything is written.
+        const seen = new Set();
+        const first = results.map((r) => {
+            const k = checkpointKey(r.runId, r.seq);
+            if (seen.has(k))
+                return false;
+            seen.add(k);
+            return true;
+        });
+        const live = results.filter((_, i) => first[i]);
+        const client = this.client();
+        const settled = client.dialect.name === 'postgres'
+            ? await settleResultsReturningPg(client, this.hot(), live)
+            : await this.settleResultsPlain(live);
+        const out = [];
+        let k = 0;
+        for (let i = 0; i < results.length; i += 1) {
+            if (!first[i]) {
+                out.push(null);
+                continue;
+            }
+            const r = live[k];
+            k += 1;
+            out.push(settled.get(checkpointKey(r.runId, r.seq)) ?? null);
+        }
+        return out;
+    }
+    /**
+     * {@link settleResultsIfPending} on a dialect without `UPDATE … RETURNING` in one statement
+     * (MySQL, SQLite): the runs' statuses, the rows, then the settle (one conditional UPDATE for a
+     * single result, the batched transaction for several). The same three statements the engine's
+     * read-first path costs.
+     */
+    async settleResultsPlain(results) {
+        const out = new Map();
+        const client = this.client();
+        const runRows = (await client
+            .from(DURABLE_TABLES.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]));
+        const settleable = results.filter((r) => SETTLEABLE_RUN_STATUSES.includes(runs.get(r.runId)?.status));
+        if (settleable.length === 0)
+            return out;
+        // What the result does not carry keeps its stored value, so the rows are read first.
+        const stored = new Map();
+        const byRun = new Map();
+        for (const r of settleable)
+            byRun.set(r.runId, [...(byRun.get(r.runId) ?? []), r.seq]);
+        for (const [runId, seqs] of byRun) {
+            for (const cp of await this.getCheckpointsForSettle(runId, seqs)) {
+                stored.set(checkpointKey(cp.runId, cp.seq), cp);
+            }
+        }
+        const settlements = settleable.flatMap((r) => {
+            const cp = stored.get(checkpointKey(r.runId, r.seq));
+            if (!cp)
+                return [];
+            return [
+                {
+                    runId: r.runId,
+                    seq: r.seq,
+                    status: r.status,
+                    output: r.status === 'completed' ? r.output : cp.output,
+                    error: r.error,
+                    events: r.events ?? cp.events,
+                    startedAt: r.startedAt ?? cp.startedAt,
+                    finishedAt: r.finishedAt,
+                },
+            ];
+        });
+        const wrote = await this.settleCheckpointsIfPending(settlements);
+        // The rows as they now read: the stored row with the settlement written over it (the settle is a
+        // compare-and-set on `pending`, so nothing else wrote it in between).
+        settlements.forEach((settlement, i) => {
+            if (!wrote[i])
+                return;
+            const k = checkpointKey(settlement.runId, settlement.seq);
+            const { runId: _runId, seq: _seq, ...written } = settlement;
+            const checkpoint = { ...stored.get(k), ...written };
+            for (const key of ['output', 'error', 'events']) {
+                if (checkpoint[key] === undefined)
+                    delete checkpoint[key];
+            }
+            const run = runs.get(settlement.runId);
+            out.set(k, {
+                checkpoint,
+                run: {
+                    status: run.status,
+                    wakeAt: run.wake_at == null ? undefined : Number(run.wake_at),
+                },
+            });
+        });
+        return out;
+    }
+    async insertCheckpointIfAbsent(checkpoint) {
+        const client = this.client();
+        const row = checkpointToRow(checkpoint);
+        const hot = this.hot();
+        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;
+        }
+    }
     /** 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. */
@@ -472,6 +673,63 @@ export class LucidStateStore {
             .limit(limit);
         return rows.map(rowToRun);
     }
+    async claimPendingRuns(limit, owner, leaseUntilMs, nowMs, namespace) {
+        if (limit <= 0)
+            return [];
+        const client = this.client();
+        const dialect = client.dialect.name;
+        const free = (q) => {
+            q.where('status', 'pending').andWhere((w) => {
+                w.whereNull('locked_until').orWhere('locked_until', '<=', nowMs);
+            });
+            if (namespace !== undefined)
+                q.whereIn('namespace', namespaceFilterValues(namespace));
+            return this.fenced(q);
+        };
+        const oldest = (q) => free(q).select('id').orderBy('created_at', 'asc').orderBy('id', 'asc').limit(limit);
+        let rows;
+        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();
+            rows = (await client
+                .from(DURABLE_TABLES.runs)
+                .whereIn('id', pick)
+                .update({ locked_by: owner, locked_until: leaseUntilMs })
+                .returning('*'));
+        }
+        else if (dialect === 'mysql') {
+            // 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);
+                if (ids.length === 0)
+                    return [];
+                await trx
+                    .from(DURABLE_TABLES.runs)
+                    .whereIn('id', ids)
+                    .update({ locked_by: owner, locked_until: leaseUntilMs });
+                return (await trx.from(DURABLE_TABLES.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))
+                .orderBy('created_at', 'asc')
+                .orderBy('id', 'asc')
+                .limit(limit));
+            for (const run of candidates.map(rowToRun)) {
+                if (await this.tryLockRun(run.id, owner, leaseUntilMs, nowMs)) {
+                    claimed.push({ ...run, lockedBy: owner, lockedUntil: leaseUntilMs });
+                }
+            }
+            return claimed;
+        }
+        return rows
+            .map(rowToRun)
+            .sort((a, b) => a.createdAt.getTime() - b.createdAt.getTime() || a.id.localeCompare(b.id));
+    }
     async listDueTimers(nowMs, namespace, limit) {
         const marker = await this.hasWakeMarkerColumn();
         const q = this.fenced(this.client()
@@ -506,7 +764,51 @@ export class LucidStateStore {
             .update({ locked_by: owner, locked_until: leaseUntilMs });
         return rowsAffected(affected) === 1;
     }
+    async tryLockRunAndGet(runId, owner, leaseUntilMs, nowMs) {
+        const hot = this.hot();
+        if (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, [
+                    owner,
+                    leaseUntilMs,
+                    runId,
+                    nowMs,
+                    namespaceFilterValues(this.scopeNamespace),
+                ]);
+            return rows[0] ? rowToRun(rows[0]) : null;
+        }
+        const client = this.client();
+        if (client.dialect.name === 'postgres') {
+            // 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)
+                .where('id', runId)
+                .andWhere((q) => {
+                q.whereNull('locked_until').orWhere('locked_until', '<=', nowMs);
+            }))
+                .update({ locked_by: owner, locked_until: leaseUntilMs })
+                .returning('*'));
+            return rows[0] ? rowToRun(rows[0]) : null;
+        }
+        if (!(await this.tryLockRun(runId, owner, leaseUntilMs, nowMs)))
+            return null;
+        const run = await this.getRun(runId);
+        // Outside the store's read scope: give the lease back.
+        if (!run)
+            await this.releaseRunLock(runId, owner);
+        return run;
+    }
     async releaseRunLock(runId, owner) {
+        const hot = this.hot();
+        if (hot) {
+            if (owner === undefined)
+                await hot.run(RELEASE_LOCK_SQL, [runId]);
+            else
+                await hot.run(RELEASE_OWN_LOCK_SQL, [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.
@@ -519,6 +821,17 @@ export class LucidStateStore {
         // One conditional UPDATE: a marker a refused wake set after the holder's last look keeps the
         // lease where it is, and the holder runs another turn.
         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,
+            ]);
+            if (released.count === 1)
+                return true;
+            const rows = await hot.rows(LOCKED_BY_SQL, [runId]);
+            return rows[0]?.locked_by !== owner;
+        }
         const q = this.client()
             .from(DURABLE_TABLES.runs)
             .where('id', runId)
@@ -558,6 +871,9 @@ export class LucidStateStore {
         return this.wakeMarkerColumn;
     }
     async renewRunLock(runId, owner, leaseUntilMs) {
+        const hot = this.hot();
+        if (hot)
+            return (await hot.run(RENEW_LOCK_SQL, [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)
@@ -722,16 +1038,21 @@ export class LucidStateStore {
         // The oldest signal is ours only if our DELETE removed it, so two takers never get the same one;
         // that needs no transaction, and a token with nothing buffered (the common case) costs one read.
         const client = this.client();
-        const row = await client
-            .from(DURABLE_TABLES.bufferedSignals)
-            .where('token', token)
-            .orderBy('id', 'asc')
-            .first();
+        const hot = this.hot();
+        const row = hot
+            ? (await hot.rows(OLDEST_BUFFERED_SIGNAL_SQL, [token]))[0]
+            : await client
+                .from(DURABLE_TABLES.bufferedSignals)
+                .where('token', token)
+                .orderBy('id', 'asc')
+                .first();
         if (!row)
             return null;
         const r = row;
-        const deleted = await client.from(DURABLE_TABLES.bufferedSignals).where('id', r.id).delete();
-        if (rowsAffected(deleted) !== 1)
+        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());
+        if (deleted !== 1)
             return null;
         return {
             payload: parseJsonColumn(r.payload, `${DURABLE_TABLES.bufferedSignals}.payload`, String(r.id)),
@@ -749,11 +1070,14 @@ export class LucidStateStore {
         });
     }
     async listBufferedEvents(name, limit) {
-        const rows = await this.client()
-            .from(DURABLE_TABLES.bufferedEvents)
-            .where('name', name)
-            .orderBy('published_at', 'asc') // oldest first
-            .limit(limit);
+        const hot = this.hot();
+        const rows = hot
+            ? await hot.rows(BUFFERED_EVENTS_SQL, [name, limit])
+            : await this.client()
+                .from(DURABLE_TABLES.bufferedEvents)
+                .where('name', name)
+                .orderBy('published_at', 'asc') // oldest first
+                .limit(limit);
         return rows.map((r) => ({
             id: r.id,
             payload: parseJsonColumn(r.payload, `${DURABLE_TABLES.bufferedEvents}.payload`, r.id),
@@ -1056,11 +1380,14 @@ export class LucidStateStore {
         return rows.map(rowToCheckpoint);
     }
     async listCheckpointsForReplay(runId) {
-        const rows = (await this.client()
-            .from(DURABLE_TABLES.checkpoints)
-            .where('run_id', runId)
-            .orderBy('seq', 'asc')
-            .select(...CHECKPOINT_COLUMNS_BUT_INPUT));
+        const hot = this.hot();
+        const rows = (hot
+            ? await hot.rows(REPLAY_CHECKPOINTS_SQL, [runId])
+            : await this.client()
+                .from(DURABLE_TABLES.checkpoints)
+                .where('run_id', runId)
+                .orderBy('seq', 'asc')
+                .select(...CHECKPOINT_COLUMNS_BUT_INPUT));
         // The input of every row but a completed one, read by seq: a row that completed since the read
         // above still gets its input, as that read reported it unsettled.
         const unsettled = rows
@@ -1109,6 +1436,11 @@ export class LucidStateStore {
     async countCheckpoints(runId, fromSeq, toSeq, statuses) {
         if (statuses.length === 0)
             return 0;
+        const hot = this.hot();
+        if (hot) {
+            const rows = await hot.rows(COUNT_CHECKPOINTS_SQL, [runId, fromSeq, toSeq, statuses]);
+            return Number(rows[0]?.count ?? 0);
+        }
         const rows = await this.client()
             .from(DURABLE_TABLES.checkpoints)
             .where('run_id', runId)
@@ -1328,6 +1660,113 @@ function nameKindSql(dialect) {
 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"`);
+}
+/** `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}`;
+    });
+}
+/**
+ * {@link LucidStateStore.settleResultsIfPending} on Postgres: one `UPDATE … FROM (VALUES …) …
+ * RETURNING` for the whole batch (entries already deduplicated by row). The run's status is checked
+ * 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) {
+    const values = [];
+    const bindings = [];
+    for (const r of results) {
+        const row = settlementToRow({
+            ...r,
+            startedAt: r.startedAt ?? new Date(0),
+        });
+        values.push('(?::text, ?::int, ?::text, ?::text, ?::text, ?::boolean, ?::text, ?::bigint, ?::bigint)');
+        bindings.push(r.runId, r.seq, r.status, r.status === 'completed' ? row.output : null, row.error, r.events !== undefined, row.events, r.startedAt ? row.started_at : null, row.finished_at);
+    }
+    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
+      status = v.status,
+      output = case when v.status = 'completed' then v.output else c.output end,
+      error = v.error,
+      events = case when v.has_events then v.events else c.events end,
+      started_at = coalesce(v.started_at, c.started_at),
+      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
+    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`;
+    const { rows } = (hot ? { rows: await hot.rows(sql, bindings) } : await client.rawQuery(sql, bindings));
+    const out = new Map();
+    for (const row of rows) {
+        const checkpoint = rowToCheckpoint(row);
+        out.set(checkpointKey(checkpoint.runId, checkpoint.seq), {
+            checkpoint,
+            run: {
+                status: row.run_status,
+                wakeAt: row.run_wake_at == null ? undefined : Number(row.run_wake_at),
+            },
+        });
+    }
+    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');
+}
 function checkpointKey(runId, seq) {
     return `${runId}\u0000${seq}`;
 }