@smithers-orchestrator/db 0.20.3 → 0.20.4

package/src/adapter/SmithersDb.js

@@ -1,2317 +1,3 @@
-import { getTableName, sql } from "drizzle-orm";
-import { Effect, Exit, FiberId, Metric } from "effect";
-import { toSmithersError } from "@smithers-orchestrator/errors/toSmithersError";
-import { getSqlMessageStorage } from "../sql-message-storage.js";
-import { alertsAcknowledgedTotal, alertsFiredTotal, dbQueryDuration, dbTransactionDuration, dbTransactionRollbacks, } from "@smithers-orchestrator/observability/metrics";
-import { assertOptionalStringMaxLength, assertPositiveFiniteNumber, } from "../input-bounds.js";
-import { FRAME_KEYFRAME_INTERVAL, applyFrameDeltaJson, encodeFrameDelta, normalizeFrameEncoding, serializeFrameDelta, } from "../frame-codec.js";
-import { getKeyColumns } from "../output.js";
-import { withSqliteWriteRetryEffect } from "../write-retry.js";
-import { camelToSnake } from "../utils/camelToSnake.js";
-import { DB_ALERT_ID_MAX_LENGTH } from "./DB_ALERT_ID_MAX_LENGTH.js";
-import { DB_ALERT_POLICY_NAME_MAX_LENGTH } from "./DB_ALERT_POLICY_NAME_MAX_LENGTH.js";
-import { DB_ALERT_MESSAGE_MAX_LENGTH } from "./DB_ALERT_MESSAGE_MAX_LENGTH.js";
-import { DB_ALERT_ALLOWED_SEVERITIES } from "./DB_ALERT_ALLOWED_SEVERITIES.js";
-import { DB_ALERT_ALLOWED_STATUSES } from "./DB_ALERT_ALLOWED_STATUSES.js";
-import { DB_RUN_ID_MAX_LENGTH } from "./DB_RUN_ID_MAX_LENGTH.js";
-import { DB_RUN_WORKFLOW_NAME_MAX_LENGTH } from "./DB_RUN_WORKFLOW_NAME_MAX_LENGTH.js";
-import { DB_RUN_ALLOWED_STATUSES } from "./DB_RUN_ALLOWED_STATUSES.js";
-import { alertsActive } from "@smithers-orchestrator/observability/metrics";
-/** @typedef {import("./AlertRow.ts").AlertRow} AlertRow */
-/** @typedef {import("./AlertStatus.ts").AlertStatus} AlertStatus */
-/** @typedef {import("./AttemptRow.ts").AttemptRow} AttemptRow */
-/** @typedef {import("drizzle-orm/bun-sqlite").BunSQLiteDatabase} BunSQLiteDatabase */
-/** @typedef {import("./EventHistoryQuery.ts").EventHistoryQuery} EventHistoryQuery */
-/** @typedef {import("./HumanRequestRow.ts").HumanRequestRow} HumanRequestRow */
-/** @typedef {import("../output/OutputKey.ts").OutputKey} OutputKey */
-/**
- * @template A, E
- * @typedef {Effect.Effect<A, E> & PromiseLike<A>} RunnableEffect
- */
-/** @typedef {import("./SignalQuery.ts").SignalQuery} SignalQuery */
-/** @typedef {import("@smithers-orchestrator/errors/SmithersError").SmithersError} SmithersError */
-/**
- * @typedef {{ runId: string; frameNo: number; createdAtMs: number; xmlJson: string; xmlHash: string; encoding: string; mountedTaskIdsJson: string | null; taskIndexJson: string | null; note: string | null; }} FrameRow
- */
-/**
- * @typedef {{ runId: string; nodeId: string; iteration: number; baseRef: string; diffJson: string; computedAtMs: number; sizeBytes: number; }} NodeDiffCacheRow
- */
-/**
- * @typedef {{ count: number }} CountRow
- */
-/**
- * @typedef {{ ralphId: string; runId: string; done?: boolean }} RalphRow
- */
-/**
- * @typedef {{ cacheKey: string; createdAtMs?: number; nodeId: string; outputTable: string }} CacheRowLike
- */
-
-/**
- * @typedef {{ runId: string; frameNo: number; createdAtMs: number; xmlJson: string; xmlHash: string; encoding: string; mountedTaskIdsJson: string | null; taskIndexJson: string | null; note: string | null; }} FrameRow
- */
-/**
- * @typedef {{ runId: string; nodeId: string; iteration: number; baseRef: string; diffJson: string; computedAtMs: number; sizeBytes: number; }} NodeDiffCacheRow
- */
-/**
- * @typedef {{ count: number }} CountRow
- */
-/**
- * @typedef {{ ralphId: string; runId: string; done?: boolean }} RalphRow
- */
-/**
- * @typedef {{ cacheKey: string; createdAtMs?: number; nodeId: string; outputTable: string }} CacheRowLike
- */
-
-
-const FRAME_XML_CACHE_MAX = 512;
-const RAW_QUERY_ALLOWED_PREFIX = /^(?:select|with|explain|values)\b/i;
-const RAW_QUERY_FORBIDDEN_KEYWORDS = /\b(?:drop|delete|insert|update|alter|create|attach|detach|pragma)\b/i;
-const ACTIVE_ALERT_STATUSES = new Set([
-    "firing",
-    "acknowledged",
-    "silenced",
-]);
-/**
- * @param {string} queryString
- * @returns {string}
- */
-function stripSqlCommentsAndLiterals(queryString) {
-    let sanitized = "";
-    let index = 0;
-    while (index < queryString.length) {
-        const char = queryString[index];
-        const nextChar = queryString[index + 1];
-        if (char === "-" && nextChar === "-") {
-            sanitized += " ";
-            index += 2;
-            while (index < queryString.length && queryString[index] !== "\n") {
-                index += 1;
-            }
-            continue;
-        }
-        if (char === "/" && nextChar === "*") {
-            sanitized += " ";
-            index += 2;
-            while (index < queryString.length) {
-                if (queryString[index] === "*" && queryString[index + 1] === "/") {
-                    index += 2;
-                    break;
-                }
-                index += 1;
-            }
-            continue;
-        }
-        if (char === "'" || char === "\"" || char === "`") {
-            const quote = char;
-            sanitized += " ";
-            index += 1;
-            while (index < queryString.length) {
-                if (queryString[index] === quote) {
-                    if (queryString[index + 1] === quote) {
-                        index += 2;
-                        continue;
-                    }
-                    index += 1;
-                    break;
-                }
-                index += 1;
-            }
-            continue;
-        }
-        if (char === "[") {
-            sanitized += " ";
-            index += 1;
-            while (index < queryString.length) {
-                if (queryString[index] === "]") {
-                    index += 1;
-                    break;
-                }
-                index += 1;
-            }
-            continue;
-        }
-        sanitized += char;
-        index += 1;
-    }
-    return sanitized;
-}
-/**
- * @param {string} queryString
- * @returns {string}
- */
-function validateReadOnlyRawQuery(queryString) {
-    const trimmedQuery = queryString.trim();
-    if (!trimmedQuery) {
-        throw toSmithersError(new Error("Raw query must not be empty"), undefined, {
-            code: "INVALID_INPUT",
-            details: { operation: "raw query validation" },
-        });
-    }
-    const sanitizedQuery = stripSqlCommentsAndLiterals(trimmedQuery).trim();
-    if (!sanitizedQuery) {
-        throw toSmithersError(new Error("Raw query must not be empty"), undefined, {
-            code: "INVALID_INPUT",
-            details: { operation: "raw query validation" },
-        });
-    }
-    const singleStatementQuery = sanitizedQuery.replace(/;+\s*$/, "").trim();
-    if (singleStatementQuery.includes(";")) {
-        throw toSmithersError(new Error("Raw query must contain a single read-only SQL statement"), undefined, {
-            code: "INVALID_INPUT",
-            details: { operation: "raw query validation" },
-        });
-    }
-    const forbiddenKeyword = singleStatementQuery.match(RAW_QUERY_FORBIDDEN_KEYWORDS)?.[0];
-    if (forbiddenKeyword) {
-        throw toSmithersError(new Error(`Raw query cannot use ${forbiddenKeyword.toUpperCase()} statements`), undefined, {
-            code: "INVALID_INPUT",
-            details: {
-                operation: "raw query validation",
-                keyword: forbiddenKeyword.toUpperCase(),
-            },
-        });
-    }
-    if (!RAW_QUERY_ALLOWED_PREFIX.test(singleStatementQuery)) {
-        throw toSmithersError(new Error("Raw query only supports read-only SELECT, WITH, EXPLAIN, or VALUES statements"), undefined, {
-            code: "INVALID_INPUT",
-            details: { operation: "raw query validation" },
-        });
-    }
-    return trimmedQuery;
-}
-/**
- * @param {unknown} status
- */
-function validateRunStatus(status) {
-    if (typeof status !== "string" ||
-        !DB_RUN_ALLOWED_STATUSES.includes(status)) {
-        throw toSmithersError(new Error("Invalid run status"), `Run status must be one of: ${DB_RUN_ALLOWED_STATUSES.join(", ")}`, {
-            code: "INVALID_INPUT",
-            details: { status },
-        });
-    }
-}
-/**
- * @param {unknown} severity
- */
-function validateAlertSeverity(severity) {
-    if (typeof severity !== "string" ||
-        !DB_ALERT_ALLOWED_SEVERITIES.includes(severity)) {
-        throw toSmithersError(new Error("Invalid alert severity"), `Alert severity must be one of: ${DB_ALERT_ALLOWED_SEVERITIES.join(", ")}`, {
-            code: "INVALID_INPUT",
-            details: { severity },
-        });
-    }
-}
-/**
- * @param {unknown} status
- */
-function validateAlertStatus(status) {
-    if (typeof status !== "string" ||
-        !DB_ALERT_ALLOWED_STATUSES.includes(status)) {
-        throw toSmithersError(new Error("Invalid alert status"), `Alert status must be one of: ${DB_ALERT_ALLOWED_STATUSES.join(", ")}`, {
-            code: "INVALID_INPUT",
-            details: { status },
-        });
-    }
-}
-/**
- * @param {Record<string, unknown>} row
- * @param {string} field
- */
-function validateOptionalPositiveTimestamp(row, field) {
-    const value = row[field];
-    if (value === undefined || value === null)
-        return;
-    assertPositiveFiniteNumber(field, Number(value));
-}
-/**
- * @param {unknown} row
- * @returns {void}
- */
-function validateRunRow(row) {
-    if (!row || typeof row !== "object") {
-        throw toSmithersError(new Error("Invalid run row"), "Run row must be an object", {
-            code: "INVALID_INPUT",
-        });
-    }
-    const r = /** @type {Record<string, unknown>} */ (row);
-    assertOptionalStringMaxLength("runId", r.runId, DB_RUN_ID_MAX_LENGTH);
-    assertOptionalStringMaxLength("parentRunId", r.parentRunId, DB_RUN_ID_MAX_LENGTH);
-    assertOptionalStringMaxLength("workflowName", r.workflowName, DB_RUN_WORKFLOW_NAME_MAX_LENGTH);
-    validateRunStatus(r.status);
-    validateOptionalPositiveTimestamp(r, "createdAtMs");
-    validateOptionalPositiveTimestamp(r, "startedAtMs");
-    validateOptionalPositiveTimestamp(r, "finishedAtMs");
-    validateOptionalPositiveTimestamp(r, "heartbeatAtMs");
-    validateOptionalPositiveTimestamp(r, "cancelRequestedAtMs");
-    validateOptionalPositiveTimestamp(r, "hijackRequestedAtMs");
-}
-/**
- * @param {unknown} patch
- * @returns {void}
- */
-function validateRunPatch(patch) {
-    if (!patch || typeof patch !== "object")
-        return;
-    const p = /** @type {Record<string, unknown>} */ (patch);
-    if ("workflowName" in p) {
-        assertOptionalStringMaxLength("workflowName", p.workflowName, DB_RUN_WORKFLOW_NAME_MAX_LENGTH);
-    }
-    if ("status" in p) {
-        validateRunStatus(p.status);
-    }
-    validateOptionalPositiveTimestamp(p, "startedAtMs");
-    validateOptionalPositiveTimestamp(p, "finishedAtMs");
-    validateOptionalPositiveTimestamp(p, "heartbeatAtMs");
-    validateOptionalPositiveTimestamp(p, "cancelRequestedAtMs");
-    validateOptionalPositiveTimestamp(p, "hijackRequestedAtMs");
-}
-/**
- * @param {AlertRow} row
- */
-function validateAlertRow(row) {
-    if (!row || typeof row !== "object") {
-        throw toSmithersError(new Error("Invalid alert row"), "Alert row must be an object", { code: "INVALID_INPUT" });
-    }
-    assertOptionalStringMaxLength("alertId", row.alertId, DB_ALERT_ID_MAX_LENGTH);
-    assertOptionalStringMaxLength("runId", row.runId, DB_RUN_ID_MAX_LENGTH);
-    assertOptionalStringMaxLength("policyName", row.policyName, DB_ALERT_POLICY_NAME_MAX_LENGTH);
-    assertOptionalStringMaxLength("message", row.message, DB_ALERT_MESSAGE_MAX_LENGTH);
-    if (typeof row.alertId !== "string" || row.alertId.length === 0) {
-        throw toSmithersError(new Error("Invalid alert ID"), "Alert ID must be a non-empty string", { code: "INVALID_INPUT", details: { alertId: row.alertId } });
-    }
-    if (row.runId !== null && row.runId !== undefined && typeof row.runId !== "string") {
-        throw toSmithersError(new Error("Invalid alert run ID"), "Alert run ID must be a string or null", { code: "INVALID_INPUT", details: { runId: row.runId } });
-    }
-    if (typeof row.policyName !== "string" || row.policyName.length === 0) {
-        throw toSmithersError(new Error("Invalid alert policy name"), "Alert policy name must be a non-empty string", { code: "INVALID_INPUT", details: { policyName: row.policyName } });
-    }
-    if (typeof row.message !== "string" || row.message.length === 0) {
-        throw toSmithersError(new Error("Invalid alert message"), "Alert message must be a non-empty string", { code: "INVALID_INPUT", details: { message: row.message } });
-    }
-    if (row.detailsJson !== null &&
-        row.detailsJson !== undefined &&
-        typeof row.detailsJson !== "string") {
-        throw toSmithersError(new Error("Invalid alert details JSON"), "Alert details JSON must be a string or null", { code: "INVALID_INPUT", details: { detailsJson: row.detailsJson } });
-    }
-    validateAlertSeverity(row.severity);
-    validateAlertStatus(row.status);
-    validateOptionalPositiveTimestamp(row, "firedAtMs");
-    validateOptionalPositiveTimestamp(row, "resolvedAtMs");
-    validateOptionalPositiveTimestamp(row, "acknowledgedAtMs");
-}
-/**
- * @param {string | null | undefined} status
- * @returns {status is AlertStatus}
- */
-function isAlertActiveStatus(status) {
-    return status !== undefined && status !== null && ACTIVE_ALERT_STATUSES.has(status);
-}
-/**
- * Returns the row unchanged. Heartbeat-based classification now lives in
- * `deriveRunState`, which correctly returns "stale" / "orphaned" rather than
- * misusing "continued" (which means the run forked into a new run, and is
- * treated as a success by `deriveRunState`).
- *
- * @template T
- * @param {T} row
- * @returns {T}
- */
-function classifyRunRowStatus(row) {
-    return row;
-}
-/**
- * @template A, E
- * @param {Effect.Effect<A, E>} effect
- * @returns {RunnableEffect<A, E>}
- */
-function runnableEffect(effect) {
-    const runnable = effect;
-    if (typeof runnable.then !== "function") {
-        Object.defineProperty(runnable, "then", {
-            configurable: true,
-            value: (onfulfilled, onrejected) => Effect.runPromise(effect).then(onfulfilled, onrejected),
-        });
-    }
-    return runnable;
-}
-/**
- * @typedef {{ depth: number; ownerThread: string | null; tail: Promise<unknown> }} SqliteTransactionState
- */
-/** @type {WeakMap<object, SqliteTransactionState>} */
-// Cross-adapter coordination: one sqlite connection cannot run overlapping BEGIN IMMEDIATE statements.
-const sqliteTransactionStateByClient = (() => {
-    const key = Symbol.for("smithers.sqliteTransactionStateByClient");
-    const registry = /** @type {Record<PropertyKey, unknown>} */ (globalThis);
-    const existing = registry[key];
-    if (existing instanceof WeakMap) {
-        return /** @type {WeakMap<object, SqliteTransactionState>} */ (existing);
-    }
-    const stateByClient = new WeakMap();
-    Object.defineProperty(globalThis, key, {
-        configurable: false,
-        enumerable: false,
-        value: stateByClient,
-    });
-    return stateByClient;
-})();
-/**
- * @param {unknown} client
- * @returns {object}
- */
-function assertSqliteClientKey(client) {
-    if ((typeof client !== "object" && typeof client !== "function") ||
-        client === null) {
-        throw new Error("SmithersDb requires an object sqlite client for transaction coordination.");
-    }
-    return /** @type {object} */ (client);
-}
-/**
- * @param {unknown} db
- * @returns {object}
- */
-function resolveSqliteClientKey(db) {
-    const source = /** @type {{ session?: { client?: unknown }; $client?: unknown }} */ (db);
-    return assertSqliteClientKey(source?.session?.client ?? source?.$client ?? db);
-}
-/**
- * @param {unknown} client
- * @returns {SqliteTransactionState}
- */
-function getSqliteTransactionState(client) {
-    const key = assertSqliteClientKey(client);
-    let state = sqliteTransactionStateByClient.get(key);
-    if (!state) {
-        state = {
-            depth: 0,
-            ownerThread: null,
-            tail: Promise.resolve(),
-        };
-        sqliteTransactionStateByClient.set(key, state);
-    }
-    return state;
-}
-/**
- * @param {unknown} db
- * @returns {{ run: (sql: string) => unknown; query: (sql: string) => { run: (...args: unknown[]) => unknown; get: (...args: unknown[]) => Record<string, unknown> | null | undefined; all: () => Array<Record<string, unknown>> }; exec: (sql: string) => unknown; $client?: unknown }}
- */
-function resolveSqliteTransactionClient(db) {
-    const candidate = /** @type {{ run?: unknown; query?: unknown; exec?: unknown; $client?: unknown }} */ (resolveSqliteClientKey(db));
-    if (typeof candidate.run !== "function") {
-        throw new Error("SmithersDb.withTransaction requires Bun SQLite client transaction primitives.");
-    }
-    return /** @type {{ run: (sql: string) => unknown; query: (sql: string) => { run: (...args: unknown[]) => unknown; get: (...args: unknown[]) => Record<string, unknown> | null | undefined; all: () => Array<Record<string, unknown>> }; exec: (sql: string) => unknown; $client?: unknown }} */ (candidate);
-}
-export class SmithersDb {
-    /** @type {BunSQLiteDatabase<Record<string, unknown>>} */
-    db;
-    /** @type {ReturnType<typeof getSqlMessageStorage>} */
-    internalStorage;
-    /** @type {Map<string, string>} */
-    reconstructedFrameXmlCache = new Map();
-    transactionDepth = 0;
-    /** @type {string | null} */
-    transactionOwnerThread = null;
-    /** @type {Promise<unknown>} */
-    transactionTail = Promise.resolve();
-    /**
-   * @param {BunSQLiteDatabase<Record<string, unknown>>} db
-   */
-    constructor(db) {
-        this.db = db;
-        this.internalStorage = getSqlMessageStorage(db);
-    }
-    /**
-   * @param {string} runId
-   * @param {number} frameNo
-   * @returns {string}
-   */
-    frameCacheKey(runId, frameNo) {
-        return `${runId}:${frameNo}`;
-    }
-    /**
-   * @param {string} runId
-   * @param {number} frameNo
-   * @returns {string | undefined}
-   */
-    getCachedFrameXml(runId, frameNo) {
-        const key = this.frameCacheKey(runId, frameNo);
-        const value = this.reconstructedFrameXmlCache.get(key);
-        if (value === undefined)
-            return undefined;
-        // Keep recently-used entries hot.
-        this.reconstructedFrameXmlCache.delete(key);
-        this.reconstructedFrameXmlCache.set(key, value);
-        return value;
-    }
-    /**
-   * @param {string} runId
-   * @param {number} frameNo
-   * @param {string} xmlJson
-   */
-    rememberFrameXml(runId, frameNo, xmlJson) {
-        const key = this.frameCacheKey(runId, frameNo);
-        if (this.reconstructedFrameXmlCache.has(key)) {
-            this.reconstructedFrameXmlCache.delete(key);
-        }
-        else if (this.reconstructedFrameXmlCache.size >= FRAME_XML_CACHE_MAX) {
-            const oldest = this.reconstructedFrameXmlCache.keys().next().value;
-            if (oldest !== undefined) {
-                this.reconstructedFrameXmlCache.delete(oldest);
-            }
-        }
-        this.reconstructedFrameXmlCache.set(key, xmlJson);
-    }
-    /**
-   * @param {string} runId
-   */
-    clearFrameCacheForRun(runId) {
-        for (const key of this.reconstructedFrameXmlCache.keys()) {
-            if (key.startsWith(`${runId}:`)) {
-                this.reconstructedFrameXmlCache.delete(key);
-            }
-        }
-    }
-    /**
-   * @param {string} queryString
-   * @returns {RunnableEffect<unknown[], SmithersError>}
-   */
-    rawQuery(queryString) {
-        const self = this;
-        return runnableEffect(Effect.gen(function* () {
-            const validatedQuery = yield* Effect.try({
-                try: () => validateReadOnlyRawQuery(queryString),
-                catch: (cause) => toSmithersError(cause, "validate raw query", {
-                    code: "INVALID_INPUT",
-                    details: { operation: "raw query validation" },
-                }),
-            });
-            return yield* self.read(`raw query ${validatedQuery.slice(0, 20)}`, () => {
-                const client = self.db.session.client;
-                const stmt = client.query(validatedQuery);
-                return Promise.resolve(stmt.all());
-            });
-        }));
-    }
-    /**
-   * @param {string} currentFiberThread
-   * @returns {boolean}
-   */
-    ownsActiveTransaction(currentFiberThread) {
-        const state = getSqliteTransactionState(resolveSqliteClientKey(this.db));
-        this.transactionDepth = state.depth;
-        this.transactionOwnerThread = state.ownerThread;
-        this.transactionTail = state.tail;
-        return (state.depth > 0 &&
-            state.ownerThread === currentFiberThread);
-    }
-    /**
-   * @template A
-   * @param {string} label
-   * @param {() => PromiseLike<A>} operation
-   * @returns {RunnableEffect<A, SmithersError>}
-   */
-    read(label, operation) {
-        const self = this;
-        return runnableEffect(Effect.gen(function* () {
-            const start = performance.now();
-            const readOperation = Effect.tryPromise({
-                try: () => operation(),
-                catch: (cause) => toSmithersError(cause, label, {
-                    code: "DB_QUERY_FAILED",
-                    details: { operation: label },
-                }),
-            });
-            const currentFiberId = yield* Effect.fiberId;
-            const currentFiberThread = FiberId.threadName(currentFiberId);
-            let result;
-            if (self.ownsActiveTransaction(currentFiberThread)) {
-                result = yield* readOperation;
-            }
-            else {
-                const releaseTurn = yield* self.acquireTransactionTurn();
-                result = yield* readOperation.pipe(Effect.ensuring(Effect.sync(() => {
-                    releaseTurn();
-                })));
-            }
-            yield* Metric.update(dbQueryDuration, performance.now() - start);
-            return result;
-        }).pipe(Effect.annotateLogs({ dbOperation: label }), Effect.withLogSpan(`db:${label}`)));
-    }
-    /**
-   * @template A
-   * @param {string} label
-   * @param {() => PromiseLike<A>} operation
-   * @returns {RunnableEffect<A, SmithersError>}
-   */
-    write(label, operation) {
-        const self = this;
-        return runnableEffect(Effect.gen(function* () {
-            const start = performance.now();
-            const writeOperation = Effect.tryPromise({
-                try: () => operation(),
-                catch: (cause) => toSmithersError(cause, label, {
-                    code: "DB_WRITE_FAILED",
-                    details: { operation: label },
-                }),
-            });
-            const currentFiberId = yield* Effect.fiberId;
-            const currentFiberThread = FiberId.threadName(currentFiberId);
-            let result;
-            if (self.ownsActiveTransaction(currentFiberThread)) {
-                result = yield* writeOperation;
-            }
-            else {
-                const releaseTurn = yield* self.acquireTransactionTurn();
-                result = yield* withSqliteWriteRetryEffect(() => writeOperation, { label }).pipe(Effect.ensuring(Effect.sync(() => {
-                    releaseTurn();
-                })));
-            }
-            yield* Metric.update(dbQueryDuration, performance.now() - start);
-            return result;
-        }).pipe(Effect.annotateLogs({ dbOperation: label }), Effect.withLogSpan(`db:${label}`)));
-    }
-    /**
-    * @returns {Effect.Effect<{ run: (sql: string) => unknown; query: (sql: string) => { run: (...args: unknown[]) => unknown; get: (...args: unknown[]) => Record<string, unknown> | null | undefined; all: () => Array<Record<string, unknown>> }; exec: (sql: string) => unknown; $client?: unknown }, SmithersError, never>}
-    */
-    getSqliteTransactionClient() {
-        return Effect.try({
-            try: () => {
-                return resolveSqliteTransactionClient(this.db);
-            },
-            catch: (cause) => toSmithersError(cause, "resolve sqlite transaction client", {
-                code: "DB_WRITE_FAILED",
-                details: { operation: "resolve sqlite transaction client" },
-            }),
-        });
-    }
-    /**
-    * @returns {Effect.Effect<() => void, SmithersError, never>}
-    */
-    acquireTransactionTurn() {
-        return Effect.tryPromise({
-            try: async () => {
-                const state = getSqliteTransactionState(resolveSqliteClientKey(this.db));
-                let release;
-                const gate = new Promise((resolve) => {
-                    release = resolve;
-                });
-                const previous = state.tail.catch(() => undefined);
-                state.tail = previous.then(() => gate);
-                this.transactionTail = state.tail;
-                await previous;
-                return release;
-            },
-            catch: (cause) => toSmithersError(cause, "acquire sqlite transaction turn", {
-                code: "DB_WRITE_FAILED",
-                details: { operation: "acquire sqlite transaction turn" },
-            }),
-        });
-    }
-    /**
-   * @template A
-   * @param {string} writeGroup
-   * @param {Effect.Effect<A, SmithersError>} operation
-   * @returns {RunnableEffect<A, SmithersError>}
-   */
-    withTransactionEffect(writeGroup, operation) {
-        const self = this;
-        const label = `sqlite transaction ${writeGroup}`;
-        return runnableEffect(withSqliteWriteRetryEffect(() => Effect.gen(function* () {
-            const currentFiberId = yield* Effect.fiberId;
-            const currentFiberThread = FiberId.threadName(currentFiberId);
-            if (self.ownsActiveTransaction(currentFiberThread)) {
-                return yield* Effect.fail(toSmithersError(new Error(`Nested sqlite transactions are not supported (writeGroup: ${writeGroup}).`), label, {
-                    code: "DB_WRITE_FAILED",
-                    details: { writeGroup, nestedTransaction: true },
-                }));
-            }
-            const releaseTurn = yield* self.acquireTransactionTurn();
-            const transactionState = getSqliteTransactionState(resolveSqliteClientKey(self.db));
-            const start = performance.now();
-            return yield* Effect.gen(function* () {
-                const client = yield* self.getSqliteTransactionClient();
-                /**
-     * @param {"operation" | "commit"} phase
-     * @param {unknown} error
-     */
-                const rollback = (phase, error) => Effect.gen(function* () {
-                    yield* Metric.increment(dbTransactionRollbacks);
-                    yield* Effect.logWarning("transaction rollback").pipe(Effect.annotateLogs({
-                        writeGroup,
-                        phase,
-                        error: String(error),
-                    }));
-                    yield* Effect.sync(() => {
-                        try {
-                            client.run("ROLLBACK");
-                        }
-                        catch {
-                            // ignore rollback failures
-                        }
-                    });
-                });
-                yield* Effect.try({
-                    try: () => {
-                        client.run("BEGIN IMMEDIATE");
-                        transactionState.depth += 1;
-                        transactionState.ownerThread = currentFiberThread;
-                        self.transactionDepth = transactionState.depth;
-                        self.transactionOwnerThread = transactionState.ownerThread;
-                        self.transactionTail = transactionState.tail;
-                    },
-                    catch: (cause) => toSmithersError(cause, "begin sqlite transaction", {
-                        code: "DB_WRITE_FAILED",
-                        details: { writeGroup, phase: "begin" },
-                    }),
-                });
-                const operationExit = yield* Effect.exit(operation);
-                if (Exit.isFailure(operationExit)) {
-                    yield* rollback("operation", operationExit.cause);
-                    return yield* Effect.failCause(operationExit.cause);
-                }
-                const commitExit = yield* Effect.exit(Effect.try({
-                    try: () => {
-                        client.run("COMMIT");
-                    },
-                    catch: (cause) => toSmithersError(cause, "commit sqlite transaction", {
-                        code: "DB_WRITE_FAILED",
-                        details: { writeGroup, phase: "commit" },
-                    }),
-                }));
-                if (Exit.isFailure(commitExit)) {
-                    yield* rollback("commit", commitExit.cause);
-                    return yield* Effect.failCause(commitExit.cause);
-                }
-                return operationExit.value;
-            }).pipe(Effect.ensuring(Effect.gen(function* () {
-                transactionState.depth = Math.max(0, transactionState.depth - 1);
-                if (transactionState.depth === 0) {
-                    transactionState.ownerThread = null;
-                }
-                self.transactionDepth = transactionState.depth;
-                self.transactionOwnerThread = transactionState.ownerThread;
-                self.transactionTail = transactionState.tail;
-                yield* Metric.update(dbTransactionDuration, performance.now() - start);
-            }))).pipe(Effect.ensuring(Effect.sync(() => {
-                releaseTurn();
-            })));
-        }), { label }).pipe(Effect.annotateLogs({ writeGroup }), Effect.withLogSpan("db:transaction")));
-    }
-    /**
-   * @template A
-   * @param {string} writeGroup
-   * @param {Effect.Effect<A, SmithersError>} operation
-   * @returns {Promise<A>}
-   */
-    withTransaction(writeGroup, operation) {
-        return Effect.runPromise(this.withTransactionEffect(writeGroup, operation));
-    }
-    /**
-   * @param {Record<string, unknown>} row
-   * @returns {RunnableEffect<void, SmithersError>}
-   */
-    insertRun(row) {
-        validateRunRow(row);
-        return this.write("insert run", () => this.internalStorage.insertIgnore("_smithers_runs", row));
-    }
-    /**
-   * @param {string} runId
-   * @param {Record<string, unknown>} patch
-   * @returns {RunnableEffect<void, SmithersError>}
-   */
-    updateRun(runId, patch) {
-        validateRunPatch(patch);
-        return this.write(`update run ${runId}`, () => this.internalStorage.updateWhere("_smithers_runs", patch, "run_id = ?", [runId]));
-    }
-    /**
-   * @param {string} runId
-   * @param {Record<string, unknown>} patch
-   * @returns {RunnableEffect<void, SmithersError>}
-   */
-    updateRunEffect(runId, patch) {
-        return this.updateRun(runId, patch);
-    }
-    /**
-   * @param {string} runId
-   * @param {string} runtimeOwnerId
-   * @param {number} heartbeatAtMs
-   * @returns {RunnableEffect<void, SmithersError>}
-   */
-    heartbeatRun(runId, runtimeOwnerId, heartbeatAtMs) {
-        return this.write(`heartbeat run ${runId}`, () => this.internalStorage.updateWhere("_smithers_runs", { heartbeatAtMs }, "run_id = ? AND runtime_owner_id = ?", [runId, runtimeOwnerId]));
-    }
-    /**
-   * @param {string} runId
-   * @param {number} cancelRequestedAtMs
-   * @returns {RunnableEffect<void, SmithersError>}
-   */
-    requestRunCancel(runId, cancelRequestedAtMs) {
-        return this.write(`cancel run ${runId}`, () => this.internalStorage.updateWhere("_smithers_runs", { cancelRequestedAtMs }, "run_id = ?", [runId]));
-    }
-    /**
-   * @param {string} runId
-   * @param {number} hijackRequestedAtMs
-   * @param {string | null} [hijackTarget]
-   * @returns {RunnableEffect<void, SmithersError>}
-   */
-    requestRunHijack(runId, hijackRequestedAtMs, hijackTarget) {
-        return this.write(`hijack run ${runId}`, () => this.internalStorage.updateWhere("_smithers_runs", {
-            hijackRequestedAtMs,
-            hijackTarget: hijackTarget ?? null,
-        }, "run_id = ?", [runId]));
-    }
-    /**
-   * @param {string} runId
-   * @returns {RunnableEffect<void, SmithersError>}
-   */
-    clearRunHijack(runId) {
-        return this.write(`clear hijack run ${runId}`, () => this.internalStorage.updateWhere("_smithers_runs", {
-            hijackRequestedAtMs: null,
-            hijackTarget: null,
-        }, "run_id = ?", [runId]));
-    }
-    /**
-   * @param {string} runId
-   * @returns {RunnableEffect<RunRow | undefined, SmithersError>}
-   */
-    getRun(runId) {
-        return this.read(`get run ${runId}`, async () => {
-            const row = await this.internalStorage.queryOne(`SELECT *
-         FROM _smithers_runs
-         WHERE run_id = ?
-         LIMIT 1`, [runId]);
-            return row ? classifyRunRowStatus(row) : undefined;
-        });
-    }
-    /**
-   * @param {string} runId
-   * @returns {RunnableEffect<RunAncestryRow[], SmithersError>}
-   */
-    listRunAncestry(runId, limit = 1000) {
-        return this.read(`list run ancestry ${runId}`, () => this.internalStorage.queryAll(`WITH RECURSIVE ancestry(run_id, parent_run_id, depth) AS (
-           SELECT run_id, parent_run_id, 0
-           FROM _smithers_runs
-           WHERE run_id = ?
-           UNION ALL
-           SELECT child.run_id, child.parent_run_id, ancestry.depth + 1
-           FROM _smithers_runs child
-           JOIN ancestry ON child.run_id = ancestry.parent_run_id
-           WHERE ancestry.parent_run_id IS NOT NULL
-         )
-         SELECT
-           run_id,
-           parent_run_id,
-           depth
-         FROM ancestry
-         ORDER BY depth ASC
-         LIMIT ?`, [runId, limit]));
-    }
-    /**
-   * @param {string} parentRunId
-   * @returns {RunnableEffect<RunRow | undefined, SmithersError>}
-   */
-    getLatestChildRun(parentRunId) {
-        return this.read(`get latest child run ${parentRunId}`, () => this.internalStorage.queryOne(`SELECT *
-         FROM _smithers_runs
-         WHERE parent_run_id = ?
-         ORDER BY created_at_ms DESC
-         LIMIT 1`, [parentRunId]));
-    }
-    /**
-   * @param {string} [status]
-   * @returns {RunnableEffect<RunRow[], SmithersError>}
-   */
-    listRuns(limit = 50, status) {
-        return this.read(`list runs ${status ?? "all"}`, async () => {
-            const clauses = [];
-            const params = [];
-            if (status === "running") {
-                clauses.push("(status = ? OR status = ?)");
-                params.push("running", "continued");
-            }
-            else if (status) {
-                clauses.push("status = ?");
-                params.push(status);
-            }
-            const whereSql = clauses.length > 0 ? `WHERE ${clauses.join(" AND ")}` : "";
-            const rows = await this.internalStorage.queryAll(`SELECT *
-         FROM _smithers_runs
-         ${whereSql}
-         ORDER BY created_at_ms DESC
-         LIMIT ?`, [...params, limit]);
-            return rows.map((row) => classifyRunRowStatus(row));
-        });
-    }
-    /**
-   * @param {number} staleBeforeMs
-   * @returns {RunnableEffect<StaleRunRecord[], SmithersError>}
-   */
-    listStaleRunningRuns(staleBeforeMs, limit = 1000) {
-        return this.read(`list stale running runs before ${staleBeforeMs}`, () => this.internalStorage.queryAll(`SELECT
-             run_id,
-             workflow_path,
-             heartbeat_at_ms,
-             runtime_owner_id,
-             status
-           FROM _smithers_runs
-           WHERE status = 'running'
-             AND (heartbeat_at_ms IS NULL OR heartbeat_at_ms < ?)
-           ORDER BY COALESCE(heartbeat_at_ms, 0) ASC
-           LIMIT ?`, [staleBeforeMs, limit]));
-    }
-    /**
-   * @param {{ runId: string; expectedStatus?: string; expectedRuntimeOwnerId: string | null; expectedHeartbeatAtMs: number | null; staleBeforeMs: number; claimOwnerId: string; claimHeartbeatAtMs: number; requireStale?: boolean; }} params
-   * @returns {RunnableEffect<boolean, SmithersError>}
-   */
-    claimRunForResume(params) {
-        return this.write(`claim stale run ${params.runId}`, () => {
-            const client = this.db.session.client;
-            const expectedStatus = params.expectedStatus ?? "running";
-            const requireStale = params.requireStale ?? expectedStatus === "running";
-            client
-                .query(`UPDATE _smithers_runs
-           SET runtime_owner_id = ?, heartbeat_at_ms = ?
-           WHERE run_id = ?
-             AND status = ?
-             AND COALESCE(runtime_owner_id, '') = COALESCE(?, '')
-             AND COALESCE(heartbeat_at_ms, -1) = COALESCE(?, -1)
-             AND (? = 0 OR heartbeat_at_ms IS NULL OR heartbeat_at_ms < ?)`)
-                .run(params.claimOwnerId, params.claimHeartbeatAtMs, params.runId, expectedStatus, params.expectedRuntimeOwnerId, params.expectedHeartbeatAtMs, requireStale ? 1 : 0, params.staleBeforeMs);
-            return this.internalStorage
-                .queryOne("SELECT changes() AS count")
-                .then((row) => Number(row?.count ?? 0) > 0);
-        });
-    }
-    /**
-   * @param {{ runId: string; claimOwnerId: string; restoreRuntimeOwnerId: string | null; restoreHeartbeatAtMs: number | null; }} params
-   * @returns {RunnableEffect<void, SmithersError>}
-   */
-    releaseRunResumeClaim(params) {
-        return this.write(`release stale run claim ${params.runId}`, () => {
-            return this.internalStorage.execute(`UPDATE _smithers_runs
-         SET runtime_owner_id = ?, heartbeat_at_ms = ?
-         WHERE run_id = ? AND runtime_owner_id = ?`, [
-                params.restoreRuntimeOwnerId,
-                params.restoreHeartbeatAtMs,
-                params.runId,
-                params.claimOwnerId,
-            ]);
-        });
-    }
-    /**
-   * @param {{ runId: string; expectedRuntimeOwnerId: string; expectedHeartbeatAtMs: number | null; patch: Record<string, unknown>; }} params
-   * @returns {RunnableEffect<boolean, SmithersError>}
-   */
-    updateClaimedRun(params) {
-        validateRunPatch(params.patch);
-        return this.write(`update claimed run ${params.runId}`, () => {
-            const client = this.db.session.client;
-            const patchEntries = Object.entries(params.patch);
-            if (patchEntries.length === 0) {
-                return Promise.resolve(true);
-            }
-            const assignments = patchEntries.map(([key]) => `${camelToSnake(key)} = ?`);
-            client
-                .query(`UPDATE _smithers_runs
-           SET ${assignments.join(", ")}
-           WHERE run_id = ?
-             AND runtime_owner_id = ?
-             AND COALESCE(heartbeat_at_ms, -1) = COALESCE(?, -1)`)
-                .run(...patchEntries.map(([, value]) => value), params.runId, params.expectedRuntimeOwnerId, params.expectedHeartbeatAtMs);
-            return this.internalStorage
-                .queryOne("SELECT changes() AS count")
-                .then((row) => Number(row?.count ?? 0) > 0);
-        });
-    }
-    /**
-   * @param {Record<string, unknown>} row
-   * @returns {RunnableEffect<void, SmithersError>}
-   */
-    insertNode(row) {
-        return this.insertNodeEffect(row);
-    }
-    /**
-   * @param {Record<string, unknown>} row
-   * @returns {RunnableEffect<void, SmithersError>}
-   */
-    insertNodeEffect(row) {
-        return this.write(`insert node ${row.nodeId}`, () => this.internalStorage.upsert("_smithers_nodes", row, ["runId", "nodeId", "iteration"]));
-    }
-    /**
-   * @param {string} runId
-   * @param {string} nodeId
-   * @param {number} iteration
-   * @returns {RunnableEffect<NodeRow | undefined, SmithersError>}
-   */
-    getNode(runId, nodeId, iteration) {
-        return this.read(`get node ${nodeId}`, () => this.internalStorage.queryOne(`SELECT *
-         FROM _smithers_nodes
-         WHERE run_id = ? AND node_id = ? AND iteration = ?
-         LIMIT 1`, [runId, nodeId, iteration]));
-    }
-    /**
-   * @param {string} runId
-   * @param {string} nodeId
-   * @returns {RunnableEffect<NodeRow[], SmithersError>}
-   */
-    listNodeIterations(runId, nodeId) {
-        return this.read(`list node iterations ${nodeId}`, () => this.internalStorage.queryAll(`SELECT *
-         FROM _smithers_nodes
-         WHERE run_id = ? AND node_id = ?
-         ORDER BY iteration DESC`, [runId, nodeId]));
-    }
-    /**
-   * @param {string} runId
-   * @returns {RunnableEffect<NodeRow[], SmithersError>}
-   */
-    listNodes(runId) {
-        return this.read(`list nodes ${runId}`, () => this.internalStorage.queryAll(`SELECT *
-         FROM _smithers_nodes
-         WHERE run_id = ?`, [runId]));
-    }
-    /**
-   * @param {Table} table
-   * @param {OutputKey} key
-   * @param {Record<string, unknown>} payload
-   * @returns {RunnableEffect<unknown, SmithersError>}
-   */
-    upsertOutputRow(table, key, payload) {
-        const cols = getKeyColumns(table);
-        const values = { ...payload };
-        values.runId = key.runId;
-        values.nodeId = key.nodeId;
-        if (cols.iteration) {
-            values.iteration = key.iteration ?? 0;
-        }
-        const target = cols.iteration
-            ? [cols.runId, cols.nodeId, cols.iteration]
-            : [cols.runId, cols.nodeId];
-        const tableName = table?.["_"]?.name ?? "output";
-        return this.write(`upsert output ${tableName}`, () => this.db
-            .insert(table)
-            .values(values)
-            .onConflictDoUpdate({
-            target: target,
-            set: values,
-        }));
-    }
-    /**
-   * @param {Table} table
-   * @param {OutputKey} key
-   * @param {Record<string, unknown>} payload
-   * @returns {RunnableEffect<unknown, SmithersError>}
-   */
-    upsertOutputRowEffect(table, key, payload) {
-        return this.upsertOutputRow(table, key, payload);
-    }
-    /**
-   * @param {string} tableName
-   * @param {OutputKey} key
-   * @returns {RunnableEffect<void, SmithersError>}
-   */
-    deleteOutputRow(tableName, key) {
-        return this.write(`delete output ${tableName}`, () => {
-            const client = this.db.session.client;
-            let resolvedTableName = tableName;
-            let escapedTableName = resolvedTableName.replaceAll(`"`, `""`);
-            let tableInfo = client
-                .query(`PRAGMA table_info("${escapedTableName}")`)
-                .all();
-            if (tableInfo.length === 0) {
-                const schemaCandidates = [
-                    this.db?._?.fullSchema,
-                    this.db?._?.schema,
-                    this.db?.schema,
-                ];
-                for (const candidate of schemaCandidates) {
-                    if (!candidate || typeof candidate !== "object")
-                        continue;
-                    const table = candidate[tableName];
-                    if (!table)
-                        continue;
-                    try {
-                        resolvedTableName = getTableName(table);
-                        escapedTableName = resolvedTableName.replaceAll(`"`, `""`);
-                        tableInfo = client
-                            .query(`PRAGMA table_info("${escapedTableName}")`)
-                            .all();
-                        if (tableInfo.length > 0) {
-                            break;
-                        }
-                    }
-                    catch { }
-                }
-            }
-            const columnNames = new Set(tableInfo
-                .map((column) => column.name)
-                .filter((name) => typeof name === "string"));
-            const runIdColumn = columnNames.has("run_id")
-                ? "run_id"
-                : columnNames.has("runId")
-                    ? "runId"
-                    : null;
-            const nodeIdColumn = columnNames.has("node_id")
-                ? "node_id"
-                : columnNames.has("nodeId")
-                    ? "nodeId"
-                    : null;
-            const iterationColumn = columnNames.has("iteration")
-                ? "iteration"
-                : null;
-            if (!runIdColumn || !nodeIdColumn) {
-                throw new Error(`Output table ${tableName} is missing runId/nodeId columns`);
-            }
-            if (iterationColumn) {
-                client
-                    .query(`DELETE FROM "${escapedTableName}"
-             WHERE "${runIdColumn}" = ? AND "${nodeIdColumn}" = ? AND "${iterationColumn}" = ?`)
-                    .run(key.runId, key.nodeId, key.iteration ?? 0);
-            }
-            else {
-                client
-                    .query(`DELETE FROM "${escapedTableName}"
-             WHERE "${runIdColumn}" = ? AND "${nodeIdColumn}" = ?`)
-                    .run(key.runId, key.nodeId);
-            }
-            return Promise.resolve(undefined);
-        });
-    }
-    /**
-   * @param {string} tableName
-   * @param {OutputKey} key
-   * @returns {RunnableEffect<void, SmithersError>}
-   */
-    deleteOutputRowEffect(tableName, key) {
-        return this.deleteOutputRow(tableName, key);
-    }
-    /**
-   * @param {string} tableName
-   * @param {string} runId
-   * @param {string} nodeId
-   * @returns {RunnableEffect<Record<string, unknown> | null, SmithersError>}
-   */
-    getRawNodeOutput(tableName, runId, nodeId) {
-        return runnableEffect(this.read(`get raw node output ${tableName}`, () => {
-            const query = sql.raw(`SELECT * FROM "${tableName}" WHERE run_id = '${runId}' AND node_id = '${nodeId}' ORDER BY iteration DESC LIMIT 1`);
-            const res = this.db.get(query);
-            return Promise.resolve(res ?? null);
-        }).pipe(Effect.catchAll(() => Effect.succeed(null))));
-    }
-    /**
-   * @param {string} tableName
-   * @param {string} runId
-   * @param {string} nodeId
-   * @param {number} iteration
-   * @returns {RunnableEffect<Record<string, unknown> | null, SmithersError>}
-   */
-    getRawNodeOutputForIteration(tableName, runId, nodeId, iteration) {
-        return runnableEffect(this.read(`get raw node output ${tableName} iteration ${iteration}`, () => {
-            const escaped = tableName.replaceAll(`"`, `""`);
-            const client = this.db.session.client;
-            const stmt = client.query(`SELECT * FROM "${escaped}" WHERE run_id = ? AND node_id = ? AND iteration = ? LIMIT 1`);
-            const row = stmt.get(runId, nodeId, iteration);
-            return Promise.resolve(row ?? null);
-        }).pipe(Effect.catchAll(() => Effect.succeed(null))));
-    }
-    /**
-   * @param {Record<string, unknown>} row
-   * @returns {RunnableEffect<void, SmithersError>}
-   */
-    insertAttempt(row) {
-        return this.write(`insert attempt ${row.nodeId}#${row.attempt}`, () => this.internalStorage.upsert("_smithers_attempts", row, ["runId", "nodeId", "iteration", "attempt"]));
-    }
-    /**
-   * @param {Record<string, unknown>} row
-   * @returns {RunnableEffect<void, SmithersError>}
-   */
-    insertAttemptEffect(row) {
-        return this.insertAttempt(row);
-    }
-    /**
-   * @param {string} runId
-   * @param {string} nodeId
-   * @param {number} iteration
-   * @param {number} attempt
-   * @param {Record<string, unknown>} patch
-   * @returns {RunnableEffect<void, SmithersError>}
-   */
-    updateAttempt(runId, nodeId, iteration, attempt, patch) {
-        return this.write(`update attempt ${nodeId}#${attempt}`, () => this.internalStorage.updateWhere("_smithers_attempts", patch, "run_id = ? AND node_id = ? AND iteration = ? AND attempt = ?", [runId, nodeId, iteration, attempt]));
-    }
-    /**
-   * @param {string} runId
-   * @param {string} nodeId
-   * @param {number} iteration
-   * @param {number} attempt
-   * @param {Record<string, unknown>} patch
-   * @returns {RunnableEffect<void, SmithersError>}
-   */
-    updateAttemptEffect(runId, nodeId, iteration, attempt, patch) {
-        return this.updateAttempt(runId, nodeId, iteration, attempt, patch);
-    }
-    /**
-   * @param {string} runId
-   * @param {string} nodeId
-   * @param {number} iteration
-   * @param {number} attempt
-   * @param {number} heartbeatAtMs
-   * @param {string | null} heartbeatDataJson
-   * @returns {RunnableEffect<void, SmithersError>}
-   */
-    heartbeatAttempt(runId, nodeId, iteration, attempt, heartbeatAtMs, heartbeatDataJson) {
-        return this.write(`heartbeat attempt ${nodeId}#${attempt}`, () => this.internalStorage.updateWhere("_smithers_attempts", {
-            heartbeatAtMs,
-            heartbeatDataJson,
-        }, "run_id = ? AND node_id = ? AND iteration = ? AND attempt = ? AND state = ?", [runId, nodeId, iteration, attempt, "in-progress"]));
-    }
-    /**
-   * @param {string} runId
-   * @param {string} nodeId
-   * @param {number} iteration
-   * @returns {RunnableEffect<AttemptRow[], SmithersError>}
-   */
-    listAttempts(runId, nodeId, iteration) {
-        return this.read(`list attempts ${nodeId}`, () => this.internalStorage.queryAll(`SELECT *
-         FROM _smithers_attempts
-         WHERE run_id = ? AND node_id = ? AND iteration = ?
-         ORDER BY attempt DESC`, [runId, nodeId, iteration], { booleanColumns: ["cached"] }));
-    }
-    /**
-   * @param {string} runId
-   * @returns {RunnableEffect<AttemptRow[], SmithersError>}
-   */
-    listAttemptsForRun(runId) {
-        return this.read(`list attempts for run ${runId}`, () => this.internalStorage.queryAll(`SELECT *
-         FROM _smithers_attempts
-         WHERE run_id = ?
-         ORDER BY started_at_ms ASC, node_id ASC, iteration ASC, attempt ASC`, [runId], { booleanColumns: ["cached"] }));
-    }
-    /**
-   * @param {string} runId
-   * @param {string} nodeId
-   * @param {number} iteration
-   * @param {number} attempt
-   * @returns {RunnableEffect<AttemptRow | undefined, SmithersError>}
-   */
-    getAttempt(runId, nodeId, iteration, attempt) {
-        return this.read(`get attempt ${nodeId}#${attempt}`, () => this.internalStorage.queryOne(`SELECT *
-         FROM _smithers_attempts
-         WHERE run_id = ? AND node_id = ? AND iteration = ? AND attempt = ?
-         LIMIT 1`, [runId, nodeId, iteration, attempt], { booleanColumns: ["cached"] }));
-    }
-    /**
-   * @param {string} runId
-   * @returns {RunnableEffect<AttemptRow[], SmithersError>}
-   */
-    listInProgressAttempts(runId) {
-        return this.read(`list in-progress attempts ${runId}`, () => this.internalStorage.queryAll(`SELECT *
-         FROM _smithers_attempts
-         WHERE run_id = ? AND state = ?`, [runId, "in-progress"], { booleanColumns: ["cached"] }));
-    }
-    /**
-   * @returns {RunnableEffect<AttemptRow[], SmithersError>}
-   */
-    listAllInProgressAttempts() {
-        return this.read("list all in-progress attempts", () => this.internalStorage.queryAll(`SELECT *
-         FROM _smithers_attempts
-         WHERE state = ?`, ["in-progress"], { booleanColumns: ["cached"] }));
-    }
-    /**
-   * @param {string} runId
-   * @param {number} frameNo
-   * @param {number} [limit]
-   * @returns {RunnableEffect<FrameRow[], SmithersError>}
-   */
-    listFrameChainDesc(runId, frameNo, limit) {
-        return this.read(`list frame chain ${runId}:${frameNo}`, () => this.internalStorage.queryAll(`SELECT *
-         FROM _smithers_frames
-         WHERE run_id = ? AND frame_no <= ?
-         ORDER BY frame_no DESC${typeof limit === "number" ? " LIMIT ?" : ""}`, typeof limit === "number" ? [runId, frameNo, limit] : [runId, frameNo]));
-    }
-    /**
-   * @param {string} runId
-   * @param {number} frameNo
-   * @param {Map<number, string>} [localCache]
-   * @returns {Effect.Effect<string | undefined, SmithersError>}
-   */
-    reconstructFrameXml(runId, frameNo, localCache = new Map()) {
-        const self = this;
-        return Effect.gen(function* () {
-            const localHit = localCache.get(frameNo);
-            if (localHit !== undefined)
-                return localHit;
-            const cacheHit = self.getCachedFrameXml(runId, frameNo);
-            if (cacheHit !== undefined) {
-                localCache.set(frameNo, cacheHit);
-                return cacheHit;
-            }
-            let rows = (yield* self.listFrameChainDesc(runId, frameNo, FRAME_KEYFRAME_INTERVAL + 2));
-            if (rows.length === 0)
-                return undefined;
-            let anchorIndex = rows.findIndex((row) => normalizeFrameEncoding(row.encoding) !== "delta");
-            if (anchorIndex < 0) {
-                rows = (yield* self.listFrameChainDesc(runId, frameNo));
-                anchorIndex = rows.findIndex((row) => normalizeFrameEncoding(row.encoding) !== "delta");
-            }
-            if (anchorIndex < 0) {
-                return rows.find((row) => row.frameNo === frameNo)?.xmlJson;
-            }
-            const chain = rows.slice(0, anchorIndex + 1).reverse();
-            let currentXml = "";
-            for (const frameRow of chain) {
-                const rowEncoding = normalizeFrameEncoding(frameRow.encoding);
-                if (rowEncoding === "delta") {
-                    if (!currentXml) {
-                        currentXml = String(frameRow.xmlJson ?? "null");
-                    }
-                    else {
-                        currentXml = yield* Effect.try({
-                            try: () => applyFrameDeltaJson(currentXml, String(frameRow.xmlJson ?? "")),
-                            catch: (cause) => toSmithersError(cause, `apply frame delta ${runId}:${frameRow.frameNo}`, {
-                                code: "DB_QUERY_FAILED",
-                                details: { runId, frameNo: frameRow.frameNo },
-                            }),
-                        });
-                    }
-                }
-                else {
-                    currentXml = String(frameRow.xmlJson ?? "null");
-                }
-                localCache.set(frameRow.frameNo, currentXml);
-                self.rememberFrameXml(runId, frameRow.frameNo, currentXml);
-            }
-            return localCache.get(frameNo);
-        });
-    }
-    /**
-   * @param {FrameRow} row
-   * @param {Map<number, string>} [localCache]
-   * @returns {Effect.Effect<FrameRow, SmithersError>}
-   */
-    inflateFrameRow(row, localCache = new Map()) {
-        const self = this;
-        return Effect.gen(function* () {
-            const encoding = normalizeFrameEncoding(row?.encoding);
-            if (encoding !== "delta") {
-                const xmlJson = String(row?.xmlJson ?? "null");
-                localCache.set(row.frameNo, xmlJson);
-                self.rememberFrameXml(row.runId, row.frameNo, xmlJson);
-                return { ...row, encoding, xmlJson };
-            }
-            const xmlJson = yield* self.reconstructFrameXml(row.runId, row.frameNo, localCache);
-            return {
-                ...row,
-                encoding,
-                xmlJson: xmlJson ?? String(row?.xmlJson ?? "null"),
-            };
-        });
-    }
-    /**
-   * @param {Record<string, unknown>} row
-   * @returns {RunnableEffect<void, SmithersError>}
-   */
-    insertFrame(row) {
-        const self = this;
-        return runnableEffect(Effect.gen(function* () {
-            const runId = String(row.runId);
-            const frameNo = Number(row.frameNo);
-            const fullXmlJson = String(row.xmlJson ?? "null");
-            let encoding = "keyframe";
-            let persistedXmlJson = fullXmlJson;
-            if (frameNo > 0 && frameNo % FRAME_KEYFRAME_INTERVAL !== 0) {
-                const previousXmlJson = yield* self.reconstructFrameXml(runId, frameNo - 1);
-                if (typeof previousXmlJson === "string") {
-                    const delta = yield* Effect.try({
-                        try: () => encodeFrameDelta(previousXmlJson, fullXmlJson),
-                        catch: (cause) => toSmithersError(cause, `encode frame delta ${runId}:${frameNo}`, {
-                            code: "DB_WRITE_FAILED",
-                            details: { runId, frameNo },
-                        }),
-                    });
-                    const deltaJson = serializeFrameDelta(delta);
-                    if (deltaJson.length < fullXmlJson.length) {
-                        encoding = "delta";
-                        persistedXmlJson = deltaJson;
-                    }
-                }
-            }
-            const persistedRow = {
-                ...row,
-                xmlJson: persistedXmlJson,
-                encoding,
-            };
-            yield* self.write(`insert frame ${frameNo}`, () => self.internalStorage.upsert("_smithers_frames", persistedRow, ["runId", "frameNo"]));
-            self.clearFrameCacheForRun(runId);
-            self.rememberFrameXml(runId, frameNo, fullXmlJson);
-        }));
-    }
-    /**
-   * @param {Record<string, unknown>} row
-   * @returns {RunnableEffect<void, SmithersError>}
-   */
-    insertFrameEffect(row) {
-        return this.insertFrame(row);
-    }
-    /**
-   * @param {string} runId
-   * @returns {RunnableEffect<FrameRow | undefined, SmithersError>}
-   */
-    getLastFrame(runId) {
-        const self = this;
-        return runnableEffect(Effect.gen(function* () {
-            const row = yield* self.read(`get last frame ${runId}`, () => self.internalStorage.queryOne(`SELECT *
-           FROM _smithers_frames
-           WHERE run_id = ?
-           ORDER BY frame_no DESC
-           LIMIT 1`, [runId]));
-            if (!row)
-                return undefined;
-            return yield* self.inflateFrameRow(row);
-        }));
-    }
-    /**
-   * @param {Record<string, unknown>} row
-   * @returns {RunnableEffect<void, SmithersError>}
-   */
-    insertOrUpdateApproval(row) {
-        return this.write(`upsert approval ${row.nodeId}`, () => this.internalStorage.upsert("_smithers_approvals", row, ["runId", "nodeId", "iteration"]));
-    }
-    /**
-   * @param {string} runId
-   * @param {string} nodeId
-   * @param {number} iteration
-   * @returns {RunnableEffect<ApprovalRow | undefined, SmithersError>}
-   */
-    getApproval(runId, nodeId, iteration) {
-        return this.read(`get approval ${nodeId}`, () => this.internalStorage.queryOne(`SELECT *
-         FROM _smithers_approvals
-         WHERE run_id = ? AND node_id = ? AND iteration = ?
-         LIMIT 1`, [runId, nodeId, iteration], { booleanColumns: ["autoApproved"] }));
-    }
-    /**
-   * @param {HumanRequestRow} row
-   * @returns {RunnableEffect<void, SmithersError>}
-   */
-    insertHumanRequest(row) {
-        return this.write(`insert human request ${row.requestId}`, () => this.internalStorage.insertIgnore("_smithers_human_requests", row));
-    }
-    /**
-   * @param {string} requestId
-   * @returns {RunnableEffect<HumanRequestRow | undefined, SmithersError>}
-   */
-    getHumanRequest(requestId) {
-        return this.read(`get human request ${requestId}`, () => this.internalStorage.queryOne(`SELECT *
-         FROM _smithers_human_requests
-         WHERE request_id = ?
-         LIMIT 1`, [requestId]));
-    }
-    /**
-   * @param {string} requestId
-   * @returns {RunnableEffect<void, SmithersError>}
-   */
-    reopenHumanRequest(requestId) {
-        return this.write(`reopen human request ${requestId}`, () => this.internalStorage.updateWhere("_smithers_human_requests", {
-            status: "pending",
-            responseJson: null,
-            answeredAtMs: null,
-            answeredBy: null,
-        }, "request_id = ? AND status = ?", [requestId, "answered"]));
-    }
-    /**
-    * @param {number} [nowMs]
-    * @returns {RunnableEffect<void, SmithersError>}
-    */
-    expireStaleHumanRequests(nowMs = Date.now()) {
-        return this.write(`expire stale human requests before ${nowMs}`, () => this.internalStorage.updateWhere("_smithers_human_requests", {
-            status: "expired",
-            responseJson: null,
-            answeredAtMs: null,
-            answeredBy: null,
-        }, "status = ? AND timeout_at_ms IS NOT NULL AND timeout_at_ms <= ?", ["pending", nowMs]));
-    }
-    /**
-   * @param {number} [nowMs]
-   * @returns {RunnableEffect<PendingHumanRequestRow[], SmithersError>}
-   */
-    listPendingHumanRequests(nowMs = Date.now()) {
-        const self = this;
-        return runnableEffect(Effect.gen(function* () {
-            yield* self.expireStaleHumanRequests(nowMs);
-            return yield* self.read("list pending human requests", () => self.internalStorage.queryAll(`SELECT
-             h.request_id,
-             h.run_id,
-             h.node_id,
-             h.iteration,
-             h.kind,
-             h.status,
-             h.prompt,
-             h.schema_json,
-             h.options_json,
-             h.response_json,
-             h.requested_at_ms,
-             h.answered_at_ms,
-             h.answered_by,
-             h.timeout_at_ms,
-             r.workflow_name,
-             r.status AS run_status,
-             n.label AS node_label
-           FROM _smithers_human_requests h
-           LEFT JOIN _smithers_runs r ON h.run_id = r.run_id
-           LEFT JOIN _smithers_nodes n
-             ON h.run_id = n.run_id
-            AND h.node_id = n.node_id
-            AND h.iteration = n.iteration
-           WHERE h.status = ?
-           ORDER BY h.requested_at_ms ASC, h.run_id, h.node_id, h.iteration`, ["pending"]));
-        }));
-    }
-    /**
-   * @param {string} requestId
-   * @param {string} responseJson
-   * @param {number} answeredAtMs
-   * @param {string | null} [answeredBy]
-   * @returns {RunnableEffect<void, SmithersError>}
-   */
-    answerHumanRequest(requestId, responseJson, answeredAtMs, answeredBy) {
-        return this.write(`answer human request ${requestId}`, () => this.internalStorage.updateWhere("_smithers_human_requests", {
-            status: "answered",
-            responseJson,
-            answeredAtMs,
-            answeredBy: answeredBy ?? null,
-        }, "request_id = ? AND status = ?", [requestId, "pending"]));
-    }
-    /**
-   * @param {string} requestId
-   * @returns {RunnableEffect<void, SmithersError>}
-   */
-    cancelHumanRequest(requestId) {
-        return this.write(`cancel human request ${requestId}`, () => this.internalStorage.updateWhere("_smithers_human_requests", {
-            status: "cancelled",
-        }, "request_id = ? AND status = ?", [requestId, "pending"]));
-    }
-    /**
-   * @param {AlertRow} row
-   * @returns {Promise<AlertRow | undefined>}
-   */
-    insertAlert(row) {
-        validateAlertRow(row);
-        const self = this;
-        return this.withTransaction(`insert alert ${row.alertId}`, Effect.gen(function* () {
-            const existing = yield* self.getAlert(row.alertId);
-            if (existing) {
-                return existing;
-            }
-            yield* self.write(`insert alert ${row.alertId}`, () => self.internalStorage.insertIgnore("_smithers_alerts", row));
-            yield* Metric.increment(Metric.tagged(Metric.tagged(alertsFiredTotal, "policy", row.policyName), "severity", row.severity));
-            if (isAlertActiveStatus(row.status)) {
-                yield* Metric.update(alertsActive, 1);
-            }
-            return yield* self.getAlert(row.alertId);
-        }));
-    }
-    /**
-   * @param {string} alertId
-   * @returns {RunnableEffect<AlertRow | undefined, SmithersError>}
-   */
-    getAlert(alertId) {
-        return this.read(`get alert ${alertId}`, () => this.internalStorage.queryOne(`SELECT *
-         FROM _smithers_alerts
-         WHERE alert_id = ?
-         LIMIT 1`, [alertId]));
-    }
-    /**
-   * @param {readonly AlertStatus[]} [statuses]
-   * @returns {RunnableEffect<AlertRow[], SmithersError>}
-   */
-    listAlerts(limit = 100, statuses) {
-        if (statuses) {
-            for (const status of statuses) {
-                validateAlertStatus(status);
-            }
-        }
-        const normalizedLimit = Math.max(1, Math.floor(limit));
-        return this.read("list alerts", () => {
-            const clauses = [];
-            const params = [];
-            if (statuses && statuses.length > 0) {
-                clauses.push(`status IN (${statuses.map(() => "?").join(", ")})`);
-                params.push(...statuses);
-            }
-            const whereSql = clauses.length > 0 ? `WHERE ${clauses.join(" AND ")}` : "";
-            return this.internalStorage.queryAll(`SELECT *
-         FROM _smithers_alerts
-         ${whereSql}
-         ORDER BY
-           CASE status
-             WHEN 'firing' THEN 0
-             WHEN 'acknowledged' THEN 1
-             WHEN 'silenced' THEN 2
-             WHEN 'resolved' THEN 3
-             ELSE 4
-           END,
-           fired_at_ms DESC,
-           alert_id ASC
-         LIMIT ?`, [...params, normalizedLimit]);
-        });
-    }
-    /**
-   * @param {string} alertId
-   * @returns {Promise<AlertRow | undefined>}
-   */
-    acknowledgeAlert(alertId, acknowledgedAtMs = Date.now()) {
-        validateOptionalPositiveTimestamp({ acknowledgedAtMs }, "acknowledgedAtMs");
-        const self = this;
-        return this.withTransaction(`acknowledge alert ${alertId}`, Effect.gen(function* () {
-            const alert = yield* self.getAlert(alertId);
-            if (!alert) {
-                return undefined;
-            }
-            if (alert.status !== "firing") {
-                return alert;
-            }
-            yield* self.write(`acknowledge alert ${alertId}`, () => self.internalStorage.updateWhere("_smithers_alerts", {
-                status: "acknowledged",
-                acknowledgedAtMs,
-            }, "alert_id = ? AND status = ?", [alertId, "firing"]));
-            yield* Metric.increment(Metric.tagged(alertsAcknowledgedTotal, "policy", alert.policyName));
-            return yield* self.getAlert(alertId);
-        }));
-    }
-    /**
-   * @param {string} alertId
-   * @returns {Promise<AlertRow | undefined>}
-   */
-    resolveAlert(alertId, resolvedAtMs = Date.now()) {
-        validateOptionalPositiveTimestamp({ resolvedAtMs }, "resolvedAtMs");
-        const self = this;
-        return this.withTransaction(`resolve alert ${alertId}`, Effect.gen(function* () {
-            const alert = yield* self.getAlert(alertId);
-            if (!alert) {
-                return undefined;
-            }
-            if (alert.status === "resolved") {
-                return alert;
-            }
-            yield* self.write(`resolve alert ${alertId}`, () => self.internalStorage.updateWhere("_smithers_alerts", {
-                status: "resolved",
-                resolvedAtMs,
-            }, "alert_id = ? AND status != ?", [alertId, "resolved"]));
-            if (isAlertActiveStatus(alert.status)) {
-                yield* Metric.update(alertsActive, -1);
-            }
-            return yield* self.getAlert(alertId);
-        }));
-    }
-    /**
-   * @param {string} alertId
-   * @returns {Promise<AlertRow | undefined>}
-   */
-    silenceAlert(alertId) {
-        const self = this;
-        return this.withTransaction(`silence alert ${alertId}`, Effect.gen(function* () {
-            const alert = yield* self.getAlert(alertId);
-            if (!alert) {
-                return undefined;
-            }
-            if (alert.status === "resolved" || alert.status === "silenced") {
-                return alert;
-            }
-            yield* self.write(`silence alert ${alertId}`, () => self.internalStorage.updateWhere("_smithers_alerts", {
-                status: "silenced",
-            }, "alert_id = ? AND status != ? AND status != ?", [alertId, "resolved", "silenced"]));
-            return yield* self.getAlert(alertId);
-        }));
-    }
-    /**
-   * @param {{ runId: string; signalName: string; correlationId: string | null; payloadJson: string; receivedAtMs: number; receivedBy?: string | null; }} row
-   * @returns {RunnableEffect<number, SmithersError>}
-   */
-    insertSignalWithNextSeq(row) {
-        const label = `insert signal ${row.signalName}`;
-        const self = this;
-        return runnableEffect(withSqliteWriteRetryEffect(() => Effect.gen(function* () {
-            const existing = yield* self.read(label, () => self.internalStorage.queryOne(`SELECT seq
-               FROM _smithers_signals
-               WHERE run_id = ?
-                 AND signal_name = ?
-                 AND ${row.correlationId === null ? "correlation_id IS NULL" : "correlation_id = ?"}
-                 AND payload_json = ?
-                 AND received_at_ms = ?
-                 AND ${row.receivedBy == null ? "received_by IS NULL" : "received_by = ?"}
-               ORDER BY seq DESC
-               LIMIT 1`, [
-                row.runId,
-                row.signalName,
-                ...(row.correlationId === null ? [] : [row.correlationId]),
-                row.payloadJson,
-                row.receivedAtMs,
-                ...(row.receivedBy == null ? [] : [row.receivedBy]),
-            ]));
-            if (existing?.seq !== undefined) {
-                return existing.seq;
-            }
-            const client = /** @type {{ exec?: unknown; query?: unknown; run?: unknown }} */ (resolveSqliteClientKey(self.db));
-            if (typeof client.exec !== "function" ||
-                typeof client.query !== "function" ||
-                typeof client.run !== "function") {
-                const lastSeq = (yield* self.getLastSignalSeq(row.runId)) ?? -1;
-                const seq = lastSeq + 1;
-                yield* Effect.tryPromise({
-                    try: () => self.internalStorage.insertIgnore("_smithers_signals", {
-                        ...row,
-                        receivedBy: row.receivedBy ?? null,
-                        seq,
-                    }),
-                    catch: (cause) => toSmithersError(cause, "insert fallback signal row"),
-                });
-                return seq;
-            }
-            const releaseTurn = yield* self.acquireTransactionTurn();
-            return yield* Effect.try({
-                try: () => {
-                    client.run("BEGIN IMMEDIATE");
-                    try {
-                        const res = client
-                            .query("SELECT COALESCE(MAX(seq), -1) + 1 AS seq FROM _smithers_signals WHERE run_id = ?")
-                            .get(row.runId);
-                        const seq = Number(res?.seq ?? 0);
-                        client
-                            .query("INSERT INTO _smithers_signals (run_id, seq, signal_name, correlation_id, payload_json, received_at_ms, received_by) VALUES (?, ?, ?, ?, ?, ?, ?)")
-                            .run(row.runId, seq, row.signalName, row.correlationId, row.payloadJson, row.receivedAtMs, row.receivedBy ?? null);
-                        client.run("COMMIT");
-                        return seq;
-                    }
-                    catch (error) {
-                        try {
-                            client.run("ROLLBACK");
-                        }
-                        catch {
-                            // ignore rollback failures
-                        }
-                        throw error;
-                    }
-                },
-                catch: (cause) => toSmithersError(cause, "insert signal transaction"),
-            }).pipe(Effect.ensuring(Effect.sync(() => {
-                releaseTurn();
-            })));
-        }), { label }).pipe(Effect.annotateLogs({
-            runId: row.runId,
-            signalName: row.signalName,
-            correlationId: row.correlationId ?? null,
-        }), Effect.withLogSpan(`db:${label}`)));
-    }
-    /**
-   * @param {string} runId
-   * @returns {RunnableEffect<number | undefined, SmithersError>}
-   */
-    getLastSignalSeq(runId) {
-        return this.read(`get last signal seq ${runId}`, () => this.internalStorage.getLastSignalSeq(runId));
-    }
-    /**
-   * @param {string} runId
-   * @param {SignalQuery} [query]
-   * @returns {RunnableEffect<SignalRow[], SmithersError>}
-   */
-    listSignals(runId, query = {}) {
-        const limit = Math.max(1, Math.floor(query.limit ?? 200));
-        return this.read(`list signals ${runId}`, () => {
-            const clauses = ["run_id = ?"];
-            const params = [runId];
-            if (query.signalName) {
-                clauses.push("signal_name = ?");
-                params.push(query.signalName);
-            }
-            if (query.correlationId !== undefined) {
-                if (query.correlationId === null) {
-                    clauses.push("correlation_id IS NULL");
-                }
-                else {
-                    clauses.push("correlation_id = ?");
-                    params.push(query.correlationId);
-                }
-            }
-            if (typeof query.receivedAfterMs === "number") {
-                clauses.push("received_at_ms >= ?");
-                params.push(query.receivedAfterMs);
-            }
-            return this.internalStorage.queryAll(`SELECT *
-         FROM _smithers_signals
-         WHERE ${clauses.join(" AND ")}
-         ORDER BY seq ASC
-         LIMIT ?`, [...params, limit]);
-        });
-    }
-    /**
-   * @param {Record<string, unknown>} row
-   * @returns {RunnableEffect<void, SmithersError>}
-   */
-    insertToolCall(row) {
-        return this.write(`insert tool call ${row.toolName}`, () => this.internalStorage.insertIgnore("_smithers_tool_calls", row));
-    }
-    /**
-   * @param {Record<string, unknown>} row
-   * @returns {RunnableEffect<void, SmithersError>}
-   */
-    upsertSandbox(row) {
-        return this.write(`upsert sandbox ${row.sandboxId}`, () => this.internalStorage.upsert("_smithers_sandboxes", row, ["runId", "sandboxId"]));
-    }
-    /**
-   * @param {string} runId
-   * @param {string} sandboxId
-   * @returns {RunnableEffect<Record<string, unknown> | undefined, SmithersError>}
-   */
-    getSandbox(runId, sandboxId) {
-        return this.read(`get sandbox ${sandboxId}`, () => this.internalStorage.queryOne(`SELECT *
-         FROM _smithers_sandboxes
-         WHERE run_id = ? AND sandbox_id = ?
-         LIMIT 1`, [runId, sandboxId]));
-    }
-    /**
-   * @param {string} runId
-   * @returns {RunnableEffect<Array<Record<string, unknown>>, SmithersError>}
-   */
-    listSandboxes(runId) {
-        return this.read(`list sandboxes ${runId}`, () => this.internalStorage.queryAll(`SELECT *
-         FROM _smithers_sandboxes
-         WHERE run_id = ?`, [runId]));
-    }
-    /**
-   * @param {string} runId
-   * @param {string} nodeId
-   * @param {number} iteration
-   * @returns {RunnableEffect<Array<Record<string, unknown>>, SmithersError>}
-   */
-    listToolCalls(runId, nodeId, iteration) {
-        return this.read(`list tool calls ${nodeId}`, () => this.internalStorage.queryAll(`SELECT *
-         FROM _smithers_tool_calls
-         WHERE run_id = ? AND node_id = ? AND iteration = ?
-         ORDER BY attempt ASC, seq ASC`, [runId, nodeId, iteration]));
-    }
-    /**
-   * @param {Record<string, unknown>} row
-   * @returns {RunnableEffect<void, SmithersError>}
-   */
-    insertEvent(row) {
-        return this.write(`insert event ${row.type}`, () => this.internalStorage.insertIgnore("_smithers_events", row));
-    }
-    /**
-   * @param {{ runId: string; timestampMs: number; type: string; payloadJson: string; }} row
-   * @returns {RunnableEffect<number, SmithersError>}
-   */
-    insertEventWithNextSeq(row) {
-        const label = `insert event ${row.type}`;
-        const self = this;
-        return runnableEffect(withSqliteWriteRetryEffect(() => Effect.gen(function* () {
-            const existing = yield* self.read(label, () => self.internalStorage.queryOne(`SELECT seq
-               FROM _smithers_events
-               WHERE run_id = ?
-                 AND timestamp_ms = ?
-                 AND type = ?
-                 AND payload_json = ?
-               ORDER BY seq DESC
-               LIMIT 1`, [row.runId, row.timestampMs, row.type, row.payloadJson]));
-            if (existing?.seq !== undefined) {
-                return existing.seq;
-            }
-            const client = /** @type {{ exec?: unknown; query?: unknown; run?: unknown }} */ (resolveSqliteClientKey(self.db));
-            if (typeof client.exec !== "function" ||
-                typeof client.query !== "function" ||
-                typeof client.run !== "function") {
-                const lastSeq = (yield* self.getLastEventSeq(row.runId)) ?? -1;
-                const seq = lastSeq + 1;
-                yield* Effect.tryPromise({
-                    try: () => self.internalStorage.insertIgnore("_smithers_events", { ...row, seq }),
-                    catch: (cause) => toSmithersError(cause, "insert fallback event row"),
-                });
-                return seq;
-            }
-            const releaseTurn = yield* self.acquireTransactionTurn();
-            return yield* Effect.try({
-                try: () => {
-                    client.run("BEGIN IMMEDIATE");
-                    try {
-                        const res = client
-                            .query("SELECT COALESCE(MAX(seq), -1) + 1 AS seq FROM _smithers_events WHERE run_id = ?")
-                            .get(row.runId);
-                        const seq = Number(res?.seq ?? 0);
-                        client
-                            .query("INSERT INTO _smithers_events (run_id, seq, timestamp_ms, type, payload_json) VALUES (?, ?, ?, ?, ?)")
-                            .run(row.runId, seq, row.timestampMs, row.type, row.payloadJson);
-                        client.run("COMMIT");
-                        return seq;
-                    }
-                    catch (error) {
-                        try {
-                            client.run("ROLLBACK");
-                        }
-                        catch {
-                            // ignore rollback failures
-                        }
-                        throw error;
-                    }
-                },
-                catch: (cause) => toSmithersError(cause, "insert event transaction"),
-            }).pipe(Effect.ensuring(Effect.sync(() => {
-                releaseTurn();
-            })));
-        }), { label }).pipe(Effect.annotateLogs({ dbOperation: label }), Effect.withLogSpan(`db:${label}`)));
-    }
-    /**
-   * @param {string} runId
-   * @returns {RunnableEffect<number | undefined, SmithersError>}
-   */
-    getLastEventSeq(runId) {
-        return this.read(`get last event seq ${runId}`, () => this.internalStorage.getLastEventSeq(runId));
-    }
-    /**
-   * @param {string} runId
-   * @param {EventHistoryQuery} [query]
-   * @returns {{ whereSql: string; params: Array<string | number> }}
-   */
-    buildEventHistoryWhere(runId, query = {}) {
-        const clauses = ["run_id = ?", "seq > ?"];
-        const params = [runId, query.afterSeq ?? -1];
-        if (typeof query.sinceTimestampMs === "number") {
-            clauses.push("timestamp_ms >= ?");
-            params.push(query.sinceTimestampMs);
-        }
-        if (query.types && query.types.length > 0) {
-            clauses.push(`type IN (${query.types.map(() => "?").join(", ")})`);
-            params.push(...query.types);
-        }
-        if (query.nodeId) {
-            clauses.push("json_extract(payload_json, '$.nodeId') = ?");
-            params.push(query.nodeId);
-        }
-        return {
-            whereSql: clauses.join(" AND "),
-            params,
-        };
-    }
-    /**
-   * @param {string} runId
-   * @param {EventHistoryQuery} [query]
-   * @returns {RunnableEffect<Array<Record<string, unknown>>, SmithersError>}
-   */
-    listEventHistory(runId, query = {}) {
-        return this.read(`list event history ${runId}`, () => this.internalStorage.listEventHistory(runId, query));
-    }
-    /**
-   * @param {string} runId
-   * @param {EventHistoryQuery} [query]
-   * @returns {RunnableEffect<number, SmithersError>}
-   */
-    countEventHistory(runId, query = {}) {
-        return this.read(`count event history ${runId}`, () => this.internalStorage.countEventHistory(runId, query));
-    }
-    /**
-   * @param {string} runId
-   * @param {number} afterSeq
-   * @returns {RunnableEffect<Array<Record<string, unknown>>, SmithersError>}
-   */
-    listEvents(runId, afterSeq, limit = 200) {
-        return this.listEventHistory(runId, { afterSeq, limit });
-    }
-    /**
-   * @param {string} runId
-   * @param {string} type
-   * @returns {RunnableEffect<Array<Record<string, unknown>>, SmithersError>}
-   */
-    listEventsByType(runId, type) {
-        return this.read(`list events by type ${type}`, () => this.internalStorage.listEventsByType(runId, type));
-    }
-    /**
-   * @param {Record<string, unknown>} row
-   * @returns {RunnableEffect<void, SmithersError>}
-   */
-    insertOrUpdateRalph(row) {
-        return this.write(`upsert ralph ${row.ralphId}`, () => this.internalStorage.upsert("_smithers_ralph", row, ["runId", "ralphId"]));
-    }
-    /**
-   * @param {string} runId
-   * @returns {RunnableEffect<Array<Record<string, unknown>>, SmithersError>}
-   */
-    listRalph(runId) {
-        return this.read(`list ralph ${runId}`, () => this.internalStorage.queryAll(`SELECT *
-         FROM _smithers_ralph
-         WHERE run_id = ?`, [runId], { booleanColumns: ["done"] }));
-    }
-    /**
-   * @param {string} runId
-   * @returns {RunnableEffect<ApprovalRow[], SmithersError>}
-   */
-    listPendingApprovals(runId) {
-        return this.read(`list pending approvals ${runId}`, () => this.internalStorage.queryAll(`SELECT *
-         FROM _smithers_approvals
-         WHERE run_id = ? AND status = ?`, [runId, "requested"], { booleanColumns: ["autoApproved"] }));
-    }
-    /**
-   * @returns {RunnableEffect<Array<Record<string, unknown>>, SmithersError>}
-   */
-    listAllPendingApprovals() {
-        return this.read("list all pending approvals", () => this.internalStorage.queryAll(`SELECT
-           a.run_id,
-           a.node_id,
-           a.iteration,
-           a.status,
-           a.requested_at_ms,
-           a.note,
-           a.decided_by,
-           r.workflow_name,
-           r.status AS run_status,
-           n.label AS node_label
-         FROM _smithers_approvals a
-         LEFT JOIN _smithers_runs r ON a.run_id = r.run_id
-         LEFT JOIN _smithers_nodes n
-           ON a.run_id = n.run_id
-          AND a.node_id = n.node_id
-          AND a.iteration = n.iteration
-         WHERE a.status = ?
-         ORDER BY COALESCE(a.requested_at_ms, 0) ASC, a.run_id, a.node_id, a.iteration`, ["requested"]));
-    }
-    /**
-   * @param {string} workflowName
-   * @param {string} nodeId
-   * @returns {RunnableEffect<Array<Record<string, unknown>>, SmithersError>}
-   */
-    listApprovalHistoryForNode(workflowName, nodeId, limit = 50) {
-        return this.read(`list approval history ${workflowName}:${nodeId}`, () => this.internalStorage.queryAll(`SELECT
-           a.run_id,
-           a.node_id,
-           a.iteration,
-           a.status,
-           a.requested_at_ms,
-           a.decided_at_ms,
-           a.note,
-           a.decided_by,
-           a.request_json,
-           a.decision_json,
-           a.auto_approved,
-           r.workflow_name,
-           r.created_at_ms AS run_created_at_ms
-         FROM _smithers_approvals a
-         INNER JOIN _smithers_runs r ON a.run_id = r.run_id
-         WHERE r.workflow_name = ? AND a.node_id = ?
-         ORDER BY r.created_at_ms DESC, a.decided_at_ms DESC
-         LIMIT ?`, [workflowName, nodeId, limit], { booleanColumns: ["autoApproved"] }));
-    }
-    /**
-   * @param {string} runId
-   * @param {string} ralphId
-   * @returns {RunnableEffect<Record<string, unknown> | undefined, SmithersError>}
-   */
-    getRalph(runId, ralphId) {
-        return this.read(`get ralph ${ralphId}`, () => this.internalStorage.queryOne(`SELECT *
-         FROM _smithers_ralph
-         WHERE run_id = ? AND ralph_id = ?
-         LIMIT 1`, [runId, ralphId], { booleanColumns: ["done"] }));
-    }
-    /**
-   * @param {Record<string, unknown>} row
-   * @returns {RunnableEffect<void, SmithersError>}
-   */
-    insertCache(row) {
-        return this.write(`insert cache ${row.cacheKey}`, () => this.internalStorage.insertIgnore("_smithers_cache", row));
-    }
-    /**
-   * @param {Record<string, unknown>} row
-   * @returns {RunnableEffect<void, SmithersError>}
-   */
-    insertCacheEffect(row) {
-        return this.insertCache(row);
-    }
-    /**
-   * @param {string} cacheKey
-   * @returns {RunnableEffect<CacheRow | undefined, SmithersError>}
-   */
-    getCache(cacheKey) {
-        return this.read(`get cache ${cacheKey}`, () => this.internalStorage.queryOne(`SELECT *
-         FROM _smithers_cache
-         WHERE cache_key = ?
-         LIMIT 1`, [cacheKey]));
-    }
-    /**
-   * @param {string} nodeId
-   * @param {string} [outputTable]
-   * @returns {RunnableEffect<CacheRow[], SmithersError>}
-   */
-    listCacheByNode(nodeId, outputTable, limit = 20) {
-        return this.read(`list cache by node ${nodeId}`, () => this.internalStorage.queryAll(`SELECT *
-         FROM _smithers_cache
-         WHERE node_id = ?${outputTable ? " AND output_table = ?" : ""}
-         ORDER BY created_at_ms DESC
-         LIMIT ?`, outputTable ? [nodeId, outputTable, limit] : [nodeId, limit]));
-    }
-    /**
-   * @param {string} runId
-   * @param {number} frameNo
-   * @returns {RunnableEffect<void, SmithersError>}
-   */
-    deleteFramesAfter(runId, frameNo) {
-        const self = this;
-        return runnableEffect(Effect.gen(function* () {
-            yield* self.write(`delete frames after ${frameNo}`, () => self.internalStorage.deleteWhere("_smithers_frames", "run_id = ? AND frame_no > ?", [runId, frameNo]));
-            self.clearFrameCacheForRun(runId);
-        }));
-    }
-    /**
-   * @param {string} runId
-   * @param {number} limit
-   * @param {number} [afterFrameNo]
-   * @returns {RunnableEffect<FrameRow[], SmithersError>}
-   */
-    listFrames(runId, limit, afterFrameNo) {
-        const self = this;
-        return runnableEffect(Effect.gen(function* () {
-            const rows = (yield* self.read(`list frames ${runId}`, () => self.internalStorage.queryAll(`SELECT *
-           FROM _smithers_frames
-           WHERE run_id = ?${afterFrameNo !== undefined ? " AND frame_no > ?" : ""}
-           ORDER BY frame_no DESC
-           LIMIT ?`, afterFrameNo !== undefined
-                ? [runId, afterFrameNo, limit]
-                : [runId, limit])));
-            const localCache = new Map();
-            const expanded = [];
-            for (const row of rows) {
-                expanded.push(yield* self.inflateFrameRow(row, localCache));
-            }
-            return expanded;
-        }));
-    }
-    /**
-   * @param {string} runId
-   * @returns {RunnableEffect<Array<{ state: string; count: number }>, SmithersError>}
-   */
-    countNodesByState(runId) {
-        return this.read(`count nodes by state ${runId}`, () => this.internalStorage.queryAll(`SELECT state, COUNT(*) AS count
-         FROM _smithers_nodes
-         WHERE run_id = ?
-         GROUP BY state`, [runId]));
-    }
-    /**
-   * @param {Record<string, unknown>} row
-   * @returns {RunnableEffect<void, SmithersError>}
-   */
-    upsertCron(row) {
-        return this.write("upsert cron", () => this.internalStorage.upsert("_smithers_cron", row, ["cronId"], ["pattern", "workflowPath", "enabled", "nextRunAtMs"]));
-    }
-    /**
-    * @param {boolean} [enabledOnly]
-    * @returns {RunnableEffect<Array<Record<string, unknown>>, SmithersError>}
-    */
-    listCrons(enabledOnly = true) {
-        return this.read("list crons", () => this.internalStorage.queryAll(`SELECT *
-         FROM _smithers_cron${enabledOnly ? " WHERE enabled = ?" : ""}`, enabledOnly ? [true] : [], { booleanColumns: ["enabled"] }));
-    }
-    /**
-   * @param {string} cronId
-   * @param {number} lastRunAtMs
-   * @param {number} nextRunAtMs
-   * @param {string | null} [errorJson]
-   * @returns {RunnableEffect<void, SmithersError>}
-   */
-    updateCronRunTime(cronId, lastRunAtMs, nextRunAtMs, errorJson) {
-        return this.write(`update cron run time ${cronId}`, () => this.internalStorage.updateWhere("_smithers_cron", { lastRunAtMs, nextRunAtMs, errorJson: errorJson ?? null }, "cron_id = ?", [cronId]));
-    }
-    /**
-   * @param {string} cronId
-   * @returns {RunnableEffect<void, SmithersError>}
-   */
-    deleteCron(cronId) {
-        return this.write(`delete cron ${cronId}`, () => this.internalStorage.deleteWhere("_smithers_cron", "cron_id = ?", [cronId]));
-    }
-    // ---------------------------------------------------------------------------
-    // Scorer results
-    // ---------------------------------------------------------------------------
-    /**
-   * @param {Record<string, unknown>} row
-   * @returns {RunnableEffect<void, SmithersError>}
-   */
-    insertScorerResult(row) {
-        return this.write(`insert scorer result ${row.scorerId}`, () => this.internalStorage.insertIgnore("_smithers_scorers", row));
-    }
-    /**
-   * @param {string} runId
-   * @param {string} [nodeId]
-   * @returns {RunnableEffect<Array<Record<string, unknown>>, SmithersError>}
-   */
-    listScorerResults(runId, nodeId) {
-        return this.read(`list scorer results ${runId}`, () => this.internalStorage.queryAll(`SELECT *
-         FROM _smithers_scorers
-         WHERE run_id = ?${nodeId ? " AND node_id = ?" : ""}
-         ORDER BY scored_at_ms ASC`, nodeId ? [runId, nodeId] : [runId]));
-    }
-    /**
-   * @param {string} runId
-   * @returns {RunnableEffect<RunRow | undefined, SmithersError>}
-   */
-    getRunEffect(runId) {
-        return this.getRun(runId);
-    }
-    /**
-   * @param {string} [status]
-   * @returns {RunnableEffect<RunRow[], SmithersError>}
-   */
-    listRunsEffect(limit = 50, status) {
-        return this.listRuns(limit, status);
-    }
-    /**
-   * @param {number} staleBeforeMs
-   * @returns {RunnableEffect<StaleRunRecord[], SmithersError>}
-   */
-    listStaleRunningRunsEffect(staleBeforeMs, limit = 1000) {
-        return this.listStaleRunningRuns(staleBeforeMs, limit);
-    }
-    /**
-   * @param {Parameters<SmithersDb["claimRunForResume"]>[0]} params
-   * @returns {RunnableEffect<boolean, SmithersError>}
-   */
-    claimRunForResumeEffect(params) {
-        return this.claimRunForResume(params);
-    }
-    /**
-   * @param {Parameters<SmithersDb["releaseRunResumeClaim"]>[0]} params
-   * @returns {RunnableEffect<void, SmithersError>}
-   */
-    releaseRunResumeClaimEffect(params) {
-        return this.releaseRunResumeClaim(params);
-    }
-    /**
-   * @param {string} runId
-   * @param {string} nodeId
-   * @returns {RunnableEffect<NodeRow[], SmithersError>}
-   */
-    listNodeIterationsEffect(runId, nodeId) {
-        return this.listNodeIterations(runId, nodeId);
-    }
-    /**
-   * @param {string} runId
-   * @returns {RunnableEffect<NodeRow[], SmithersError>}
-   */
-    listNodesEffect(runId) {
-        return this.listNodes(runId);
-    }
-    /**
-   * @param {string} runId
-   * @param {string} nodeId
-   * @param {number} iteration
-   * @returns {RunnableEffect<AttemptRow[], SmithersError>}
-   */
-    listAttemptsEffect(runId, nodeId, iteration) {
-        return this.listAttempts(runId, nodeId, iteration);
-    }
-    /**
-   * @param {string} runId
-   * @returns {RunnableEffect<AttemptRow[], SmithersError>}
-   */
-    listAttemptsForRunEffect(runId) {
-        return this.listAttemptsForRun(runId);
-    }
-    /**
-   * @param {string} runId
-   * @param {string} nodeId
-   * @param {number} iteration
-   * @returns {RunnableEffect<Array<Record<string, unknown>>, SmithersError>}
-   */
-    listToolCallsEffect(runId, nodeId, iteration) {
-        return this.listToolCalls(runId, nodeId, iteration);
-    }
-    /**
-   * @param {string} tableName
-   * @param {string} runId
-   * @param {string} nodeId
-   * @param {number} iteration
-   * @returns {RunnableEffect<Record<string, unknown> | null, SmithersError>}
-   */
-    getRawNodeOutputForIterationEffect(tableName, runId, nodeId, iteration) {
-        return this.getRawNodeOutputForIteration(tableName, runId, nodeId, iteration);
-    }
-    /**
-   * @param {Parameters<SmithersDb["insertEventWithNextSeq"]>[0]} row
-   * @returns {RunnableEffect<number, SmithersError>}
-   */
-    insertEventWithNextSeqEffect(row) {
-        return this.insertEventWithNextSeq(row);
-    }
-    /**
-   * @param {string} runId
-   * @returns {RunnableEffect<number | undefined, SmithersError>}
-   */
-    getLastEventSeqEffect(runId) {
-        return this.getLastEventSeq(runId);
-    }
-    /**
-   * @param {string} runId
-   * @param {EventHistoryQuery} [query]
-   * @returns {RunnableEffect<Array<Record<string, unknown>>, SmithersError>}
-   */
-    listEventHistoryEffect(runId, query = {}) {
-        return this.listEventHistory(runId, query);
-    }
-    /**
-   * @param {string} runId
-   * @param {EventHistoryQuery} [query]
-   * @returns {RunnableEffect<number, SmithersError>}
-   */
-    countEventHistoryEffect(runId, query = {}) {
-        return this.countEventHistory(runId, query);
-    }
-    /**
-   * @param {string} runId
-   * @param {string} type
-   * @returns {RunnableEffect<Array<Record<string, unknown>>, SmithersError>}
-   */
-    listEventsByTypeEffect(runId, type) {
-        return this.listEventsByType(runId, type);
-    }
-    /**
-   * @param {string} runId
-   * @returns {RunnableEffect<ApprovalRow[], SmithersError>}
-   */
-    listPendingApprovalsEffect(runId) {
-        return this.listPendingApprovals(runId);
-    }
-    /**
-   * @param {string} runId
-   * @returns {RunnableEffect<FrameRow | undefined, SmithersError>}
-   */
-    getLastFrameEffect(runId) {
-        return this.getLastFrame(runId);
-    }
-    /**
-   * @param {string} nodeId
-   * @param {string} [outputTable]
-   * @returns {RunnableEffect<CacheRow[], SmithersError>}
-   */
-    listCacheByNodeEffect(nodeId, outputTable, limit = 20) {
-        return this.listCacheByNode(nodeId, outputTable, limit);
-    }
-    /**
-    * @param {boolean} [enabledOnly]
-    * @returns {RunnableEffect<Array<Record<string, unknown>>, SmithersError>}
-    */
-    listCronsEffect(enabledOnly = true) {
-        return this.listCrons(enabledOnly);
-    }
-    /**
-   * @param {string} cronId
-   * @param {number} lastRunAtMs
-   * @param {number} nextRunAtMs
-   * @param {string | null} [errorJson]
-   * @returns {RunnableEffect<void, SmithersError>}
-   */
-    updateCronRunTimeEffect(cronId, lastRunAtMs, nextRunAtMs, errorJson) {
-        return this.updateCronRunTime(cronId, lastRunAtMs, nextRunAtMs, errorJson);
-    }
-    /**
-   * @param {string} runId
-   * @param {string} [nodeId]
-   * @returns {RunnableEffect<Array<Record<string, unknown>>, SmithersError>}
-   */
-    listScorerResultsEffect(runId, nodeId) {
-        return this.listScorerResults(runId, nodeId);
-    }
-}
+// Keep the historical subpath import stable without maintaining a second copy
+// of the adapter implementation.
+export { SmithersDb } from "../adapter.js";