@blokjs/runner 0.4.0 → 0.6.0

package/dist/tracing/SqliteRunStore.js

@@ -1,22 +1,63 @@
 import { createRequire } from "node:module";
+import { isValidMetadataKey, normaliseMetadataFilters, translateFilterToSql } from "./metadataFilter";
 const esmRequire = createRequire(import.meta.url);
+function encodeNodeRunFlags(nodeRun) {
+    const flags = {};
+    if (nodeRun.wait !== undefined)
+        flags.wait = nodeRun.wait;
+    if (nodeRun.dispatch !== undefined)
+        flags.dispatch = nodeRun.dispatch;
+    if (nodeRun.subworkflowDepth !== undefined)
+        flags.subworkflowDepth = nodeRun.subworkflowDepth;
+    if (nodeRun.middleware !== undefined)
+        flags.middleware = nodeRun.middleware;
+    if (nodeRun.iterationIndex !== undefined)
+        flags.iterationIndex = nodeRun.iterationIndex;
+    const empty = Object.keys(flags).length === 0;
+    return empty ? null : JSON.stringify(flags);
+}
+function decodeNodeRunFlags(raw) {
+    if (!raw)
+        return {};
+    try {
+        const parsed = JSON.parse(raw);
+        if (parsed && typeof parsed === "object")
+            return parsed;
+    }
+    catch {
+        // Corrupt JSON (concurrent write race, manual edit, etc.) — fall
+        // through to empty flags rather than failing the whole rowToNodeRun.
+    }
+    return {};
+}
 const isBun = "Bun" in globalThis;
 /**
- * SQLite-backed RunStore supporting both bun:sqlite and better-sqlite3.
- *
- * When running under Bun, uses the built-in bun:sqlite module for
- * optimal performance. Falls back to better-sqlite3 under Node.js.
- *
- * Provides persistent trace storage that survives process restarts.
- * All operations are synchronous.
- *
- * Schema is auto-migrated on construction via a versioned migration system.
+ * F1 — read `BLOK_INDEXED_METADATA_KEYS=tier,region` from the env.
+ * Empty / unset = no F1 indexing. Exposed for test seams; production
+ * code reads through the `SqliteRunStore` constructor.
  */
+export function readIndexedMetadataKeysFromEnv(env = process.env) {
+    const raw = env.BLOK_INDEXED_METADATA_KEYS;
+    if (typeof raw !== "string" || raw.length === 0)
+        return [];
+    return raw
+        .split(",")
+        .map((k) => k.trim())
+        .filter((k) => k.length > 0);
+}
 export class SqliteRunStore {
     db;
     // Prepared statements (lazy-initialized)
     stmts = {};
-    constructor(dbPath = ".blok/trace.db") {
+    /**
+     * F1 — the validated, frozen set of metadata keys that have an
+     * indexed generated column on `workflow_runs`. Read at query time
+     * to decide whether a filter's LHS is `metadata_<key>_idx`
+     * (indexed path) or `json_extract(metadata_json, '$.<key>')`
+     * (sequential path).
+     */
+    indexedMetadataKeys;
+    constructor(dbPath = ".blok/trace.db", opts) {
         if (isBun) {
             // Use Bun's built-in SQLite (3-6x faster than better-sqlite3)
             const bunMod = "bun:sqlite";
@@ -43,6 +84,50 @@ export class SqliteRunStore {
         this.db.exec("PRAGMA synchronous = NORMAL");
         this.db.exec("PRAGMA foreign_keys = ON");
         this.migrate();
+        // F1 — resolve declared indexed keys (constructor option wins over
+        // env var) and ensure each one has a generated column + index.
+        // Runs AFTER `migrate()` so the base `workflow_runs` table exists.
+        const declared = opts?.indexedMetadataKeys ?? readIndexedMetadataKeysFromEnv();
+        this.indexedMetadataKeys = new Set(declared.filter((k) => isValidMetadataKey(k)));
+        this.ensureIndexedMetadataColumns(this.indexedMetadataKeys);
+    }
+    /**
+     * F1 — for each declared key, ensure (a) the `metadata_<key>_idx`
+     * virtual generated column exists on `workflow_runs`, and (b) an
+     * index on that column exists. Both are idempotent — pre-existing
+     * columns are detected via `PRAGMA table_info` since SQLite doesn't
+     * support `ALTER TABLE ADD COLUMN IF NOT EXISTS`.
+     *
+     * Generated columns are `VIRTUAL` rather than `STORED` so they can
+     * be added to a non-empty table (STORED columns can't, per SQLite's
+     * `ALTER TABLE` rules). The query planner can still use a btree
+     * index built on a VIRTUAL column — that's the F1 win.
+     */
+    ensureIndexedMetadataColumns(keys) {
+        if (keys.size === 0)
+            return;
+        // Use `table_xinfo` rather than `table_info` — virtual generated
+        // columns are HIDDEN columns and `PRAGMA table_info` deliberately
+        // omits them. `table_xinfo` returns hidden columns too (with
+        // `hidden=2` for virtual generated columns specifically), so the
+        // idempotency check actually works against a previously-added
+        // column on a re-opened db.
+        const existingColumns = new Set(this.db
+            .prepare("PRAGMA table_xinfo(workflow_runs)")
+            .all()
+            .map((r) => r.name));
+        for (const key of keys) {
+            const columnName = `metadata_${key}_idx`;
+            const indexName = `idx_workflow_runs_metadata_${key}`;
+            if (!existingColumns.has(columnName)) {
+                // TEXT type-hint is explicit so the planner has a stable
+                // expectation; the actual stored type still matches
+                // whatever `json_extract` returns at evaluation time
+                // (SQLite uses dynamic type affinity).
+                this.db.exec(`ALTER TABLE workflow_runs ADD COLUMN ${columnName} TEXT GENERATED ALWAYS AS (json_extract(metadata_json, '$.${key}')) VIRTUAL`);
+            }
+            this.db.exec(`CREATE INDEX IF NOT EXISTS ${indexName} ON workflow_runs(${columnName})`);
+        }
     }
     // === Schema Migration ===
     migrate() {
@@ -332,6 +417,129 @@ export class SqliteRunStore {
 					ALTER TABLE workflow_runs ADD COLUMN last_completed_step_index INTEGER;
 				`,
             },
+            {
+                // v0.6 prerequisite for wait-inside-primitives Phase 2.
+                //
+                // state_snapshot is a JSON blob of `ctx.state` taken
+                // immediately before RunnerSteps throws WaitDispatchRequest.
+                // On dispatchDeferred re-entry — especially the cross-process
+                // recovery path where a fresh ctx is rebuilt from the
+                // persisted scheduled_dispatches row — TriggerBase.run reads
+                // this column and rehydrates ctx.state so subsequent steps
+                // see the same pre-wait state regardless of restart.
+                //
+                // Default NULL (= no snapshot; runner doesn't rehydrate,
+                // preserving exact pre-v0.6 behaviour for runs that never
+                // hit a wait).
+                version: 11,
+                sql: `
+					ALTER TABLE workflow_runs ADD COLUMN state_snapshot TEXT;
+				`,
+            },
+            {
+                // v0.6 wait-inside-primitives Phase 2 — sequential forEach
+                // iteration cursor.
+                //
+                // iteration_context is a JSON blob written to the FOREACH'S
+                // NodeRun (not the inner-step NodeRun) when an inner step
+                // throws WaitDispatchRequest mid-iteration. Records:
+                //   - `iteration`: which iteration of the forEach was in flight
+                //   - `innerStepIndex`: which inner step within that iteration
+                //     fired the wait
+                //   - `completedResults`: the partial accumulator for
+                //     iterations [0..iteration-1], so the post-resume final
+                //     result array covers EVERY iteration
+                //
+                // Read on dispatchDeferred re-entry by TriggerBase.run, which
+                // rehydrates the column onto ctx as `_blokIterationResume`;
+                // ForEachNode picks it up to resume at the right iteration +
+                // inner step. Default NULL preserves pre-v0.6 behaviour for
+                // NodeRuns that never threw a wait (the vast majority).
+                //
+                // Phase 2 wires this for SEQUENTIAL forEach only. Future
+                // phases reuse the column with primitive-specific shapes
+                // (parallel forEach, loop, switch).
+                version: 12,
+                sql: `
+					ALTER TABLE node_runs ADD COLUMN iteration_context TEXT;
+				`,
+            },
+            {
+                // Tier C #2 — cross-process scheduler coordination.
+                //
+                // Multi-process deployments sharing one PG / sqlite file risk
+                // double-firing the same dispatch when each process's
+                // `recoverDispatches()` independently registers timers. The
+                // claim columns let processes atomically take ownership of
+                // rows during recovery; the heartbeat keeps the claim fresh
+                // while the timer is registered; a dead holder's claim
+                // expires after `BLOK_SCHEDULER_CLAIM_LEASE_MS` and a
+                // surviving process can take over on its next recovery.
+                //
+                // Single-process sqlite deployments see no observable
+                // behavior change (the same process always wins the claim).
+                // Additive — pre-existing rows get NULL claim columns and
+                // become claimable on the next recovery.
+                version: 13,
+                sql: `
+					ALTER TABLE scheduled_dispatches ADD COLUMN claimed_by TEXT;
+					ALTER TABLE scheduled_dispatches ADD COLUMN claimed_at INTEGER;
+					CREATE INDEX IF NOT EXISTS idx_scheduled_dispatches_claim ON scheduled_dispatches(claimed_by, claimed_at);
+				`,
+            },
+            {
+                // E2 · server-side saved filters for the runs list. Replaces
+                // the prior `localStorage` impl in Studio so filter presets
+                // survive a fresh browser. `name` is UNIQUE — saving with an
+                // existing name overwrites the row (matches the localStorage
+                // "replace by name" semantics callers already rely on).
+                version: 14,
+                sql: `
+					CREATE TABLE IF NOT EXISTS trace_saved_filters (
+						id TEXT PRIMARY KEY,
+						name TEXT NOT NULL UNIQUE,
+						status TEXT NOT NULL DEFAULT '',
+						tags_input TEXT NOT NULL DEFAULT '',
+						metadata_input TEXT NOT NULL DEFAULT '',
+						created_at INTEGER NOT NULL,
+						updated_at INTEGER NOT NULL
+					);
+					CREATE INDEX IF NOT EXISTS idx_saved_filters_updated_at ON trace_saved_filters(updated_at);
+				`,
+            },
+            {
+                // v0.6 follow-up to #100 — recorded sample bodies for the
+                // Studio empty-state curl. Opt-in per HTTP trigger via
+                // `recordSample: true`. ONE row per workflow (PK on
+                // workflow_name); the trigger only writes the FIRST
+                // successful run's body so the operator-visible curl stays
+                // stable. Author overrides + static inference still apply
+                // when no row exists.
+                version: 15,
+                sql: `
+					CREATE TABLE IF NOT EXISTS trace_workflow_samples (
+						workflow_name TEXT PRIMARY KEY,
+						body_json TEXT NOT NULL,
+						source_run_id TEXT NOT NULL,
+						recorded_at INTEGER NOT NULL
+					);
+				`,
+            },
+            {
+                // v0.6 follow-up — bag column for Studio-visible step flags.
+                // Until now `wait`, `subworkflowDepth`, `middleware`,
+                // `iterationIndex` lived only on the in-memory NodeRun and
+                // silently dropped on sqlite/PG round-trip — the rail badges
+                // vanished on browser refresh or process restart. The new
+                // G2 `dispatch` field would have inherited the same gap.
+                // One opaque JSON column holds whichever of the five fields
+                // are set; pre-v16 rows get NULL (which decodes back to all
+                // fields undefined — matches the previous behaviour exactly).
+                version: 16,
+                sql: `
+					ALTER TABLE node_runs ADD COLUMN flags_json TEXT;
+				`,
+            },
         ];
         const applyMigration = this.db.transaction((m) => {
             this.db.exec(m.sql);
@@ -359,9 +567,9 @@ export class SqliteRunStore {
 			 tags_json, metadata_json, node_count, completed_nodes, environment, replay_of,
 			 parent_run_id, parent_node_run_id,
 			 scheduled_at, expires_at, debounce_key, debounce_mode, ping_count,
-			 last_completed_step_index)
-			VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
-		`).run(run.id, run.workflowName, run.workflowPath, run.triggerType, run.triggerSummary, run.status, run.startedAt, run.finishedAt ?? null, run.durationMs ?? null, run.error ? JSON.stringify(run.error) : null, JSON.stringify(run.tags || []), run.metadata ? JSON.stringify(run.metadata) : null, run.nodeCount, run.completedNodes, run.environment ?? null, run.replayOf ?? null, run.parentRunId ?? null, run.parentNodeRunId ?? null, run.scheduledAt ?? null, run.expiresAt ?? null, run.debounceKey ?? null, run.debounceMode ?? null, run.pingCount ?? null, run.lastCompletedStepIndex ?? null);
+			 last_completed_step_index, state_snapshot)
+			VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+		`).run(run.id, run.workflowName, run.workflowPath, run.triggerType, run.triggerSummary, run.status, run.startedAt, run.finishedAt ?? null, run.durationMs ?? null, run.error ? JSON.stringify(run.error) : null, JSON.stringify(run.tags || []), run.metadata ? JSON.stringify(run.metadata) : null, run.nodeCount, run.completedNodes, run.environment ?? null, run.replayOf ?? null, run.parentRunId ?? null, run.parentNodeRunId ?? null, run.scheduledAt ?? null, run.expiresAt ?? null, run.debounceKey ?? null, run.debounceMode ?? null, run.pingCount ?? null, run.lastCompletedStepIndex ?? null, run.stateSnapshot ?? null);
     }
     updateRun(runId, updates) {
         const setClauses = [];
@@ -430,6 +638,10 @@ export class SqliteRunStore {
             setClauses.push("last_completed_step_index = ?");
             values.push(updates.lastCompletedStepIndex);
         }
+        if (updates.stateSnapshot !== undefined) {
+            setClauses.push("state_snapshot = ?");
+            values.push(updates.stateSnapshot);
+        }
         if (updates.startedAt !== undefined) {
             setClauses.push("started_at = ?");
             values.push(updates.startedAt);
@@ -445,9 +657,10 @@ export class SqliteRunStore {
 			(id, run_id, node_name, node_type, runtime_kind,
 			 status, started_at, finished_at, duration_ms,
 			 inputs_json, outputs_json, error_json,
-			 parent_node_id, depth, step_index, metrics_json, cached_json, attempts_json)
-			VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
-		`).run(nodeRun.id, nodeRun.runId, nodeRun.nodeName, nodeRun.nodeType, nodeRun.runtimeKind ?? null, nodeRun.status, nodeRun.startedAt, nodeRun.finishedAt ?? null, nodeRun.durationMs ?? null, nodeRun.inputs !== undefined ? JSON.stringify(nodeRun.inputs) : null, nodeRun.outputs !== undefined ? JSON.stringify(nodeRun.outputs) : null, nodeRun.error ? JSON.stringify(nodeRun.error) : null, nodeRun.parentNodeId ?? null, nodeRun.depth, nodeRun.stepIndex, nodeRun.metrics ? JSON.stringify(nodeRun.metrics) : null, nodeRun.cached ? JSON.stringify(nodeRun.cached) : null, nodeRun.attempts ? JSON.stringify(nodeRun.attempts) : null);
+			 parent_node_id, depth, step_index, metrics_json, cached_json, attempts_json,
+			 iteration_context, flags_json)
+			VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+		`).run(nodeRun.id, nodeRun.runId, nodeRun.nodeName, nodeRun.nodeType, nodeRun.runtimeKind ?? null, nodeRun.status, nodeRun.startedAt, nodeRun.finishedAt ?? null, nodeRun.durationMs ?? null, nodeRun.inputs !== undefined ? JSON.stringify(nodeRun.inputs) : null, nodeRun.outputs !== undefined ? JSON.stringify(nodeRun.outputs) : null, nodeRun.error ? JSON.stringify(nodeRun.error) : null, nodeRun.parentNodeId ?? null, nodeRun.depth, nodeRun.stepIndex, nodeRun.metrics ? JSON.stringify(nodeRun.metrics) : null, nodeRun.cached ? JSON.stringify(nodeRun.cached) : null, nodeRun.attempts ? JSON.stringify(nodeRun.attempts) : null, nodeRun.iterationContext ? JSON.stringify(nodeRun.iterationContext) : null, encodeNodeRunFlags(nodeRun));
     }
     updateNodeRun(nodeRunId, updates) {
         const setClauses = [];
@@ -484,6 +697,10 @@ export class SqliteRunStore {
             setClauses.push("attempts_json = ?");
             values.push(JSON.stringify(updates.attempts));
         }
+        if (updates.iterationContext !== undefined) {
+            setClauses.push("iteration_context = ?");
+            values.push(JSON.stringify(updates.iterationContext));
+        }
         if (setClauses.length === 0)
             return;
         values.push(nodeRunId);
@@ -517,21 +734,30 @@ export class SqliteRunStore {
             conditions.push("status = ?");
             params.push(opts.status);
         }
-        // Tier 2 quick-wins — metadata key=value filter via json_extract.
-        // Multiple key=value pairs combine with AND semantics. Indexed scans
-        // aren't possible against arbitrary JSON keys; sequential scan is
-        // acceptable given the runs table has size cap via evictOldRuns.
+        // F2 (v0.5) — metadata filter with operator support
+        // (eq / ne / gt / gte / lt / lte / like / in / nin) via
+        // `translateFilterToSql`. F1 (v0.5) — declared indexed keys
+        // (`BLOK_INDEXED_METADATA_KEYS=tier,region`) reference
+        // `metadata_<key>_idx` (the generated column ensured at
+        // construction time) so the query planner uses the btree
+        // index instead of a sequential `json_extract` scan.
+        //
+        // `normaliseMetadataFilters` accepts both the legacy
+        // `Record<string, string>` shape (v0.4) AND the new
+        // `MetadataFilter[]` shape (v0.5) — keys outside
+        // `/^[a-zA-Z0-9_-]+$/` are silently dropped for JSON-path
+        // injection safety.
         if (opts?.metadata) {
-            const entries = Object.entries(opts.metadata);
-            for (const [k, v] of entries) {
-                // Use prefixed paths for safety: only allow keys matching
-                // /^[a-zA-Z0-9_-]+$/ to prevent JSON path injection. Keys with
-                // special characters silently skip filtering — caller can
-                // always fall back to client-side filter for those.
-                if (!/^[a-zA-Z0-9_-]+$/.test(k))
+            const filters = normaliseMetadataFilters(opts.metadata);
+            for (const f of filters) {
+                const lhs = this.indexedMetadataKeys.has(f.key)
+                    ? `metadata_${f.key}_idx`
+                    : `json_extract(metadata_json, '$.${f.key}')`;
+                const translated = translateFilterToSql(f, lhs);
+                if (!translated)
                     continue;
-                conditions.push(`json_extract(metadata_json, '$.${k}') = ?`);
-                params.push(v);
+                conditions.push(translated.fragment);
+                params.push(...translated.params);
             }
         }
         const tags = opts?.tags;
@@ -845,6 +1071,84 @@ export class SqliteRunStore {
         values.push(dashboardId);
         this.db.prepare(`UPDATE dashboards SET ${setClauses.join(", ")} WHERE id = ?`).run(...values);
     }
+    // === Saved filters (E2) ===
+    upsertSavedFilter(filter) {
+        // UNIQUE(name) lets us collapse "create or overwrite" into one
+        // UPSERT — preserves the existing `id` + `created_at` when the
+        // name matches, bumps `updated_at` to now. Matches the legacy
+        // localStorage replace-by-name semantics callers depend on.
+        const persisted = this.db.transaction((f) => {
+            const existing = this.db.prepare("SELECT id, created_at FROM trace_saved_filters WHERE name = ?").get(f.name);
+            const id = existing?.id ?? f.id;
+            const createdAt = existing?.created_at ?? f.createdAt;
+            const updatedAt = f.updatedAt;
+            this.db
+                .prepare(`
+					INSERT INTO trace_saved_filters
+						(id, name, status, tags_input, metadata_input, created_at, updated_at)
+					VALUES (?, ?, ?, ?, ?, ?, ?)
+					ON CONFLICT(name) DO UPDATE SET
+						status = excluded.status,
+						tags_input = excluded.tags_input,
+						metadata_input = excluded.metadata_input,
+						updated_at = excluded.updated_at
+				`)
+                .run(id, f.name, f.status, f.tagsInput, f.metadataInput, createdAt, updatedAt);
+            return {
+                id,
+                name: f.name,
+                status: f.status,
+                tagsInput: f.tagsInput,
+                metadataInput: f.metadataInput,
+                createdAt,
+                updatedAt,
+            };
+        })(filter);
+        return persisted;
+    }
+    listSavedFilters() {
+        const rows = this.db
+            .prepare("SELECT * FROM trace_saved_filters ORDER BY updated_at DESC")
+            .all();
+        return rows.map((r) => rowToSavedFilter(r));
+    }
+    deleteSavedFilter(name) {
+        const result = this.db.prepare("DELETE FROM trace_saved_filters WHERE name = ?").run(name);
+        return result.changes > 0;
+    }
+    // === Sample-body recording (option C follow-up to #100) ===
+    recordWorkflowSample(sample) {
+        // First-record-wins. INSERT OR IGNORE skips the row when the
+        // PRIMARY KEY (workflow_name) already exists; we then SELECT to
+        // return whatever's actually persisted. Keeps the operator-
+        // visible sample stable across re-runs.
+        const insert = this.db.prepare("INSERT OR IGNORE INTO trace_workflow_samples (workflow_name, body_json, source_run_id, recorded_at) VALUES (?, ?, ?, ?)");
+        insert.run(sample.workflowName, JSON.stringify(sample.body), sample.sourceRunId, sample.recordedAt);
+        const existing = this.getWorkflowSample(sample.workflowName);
+        return existing ?? sample;
+    }
+    getWorkflowSample(workflowName) {
+        const row = this.db.prepare("SELECT * FROM trace_workflow_samples WHERE workflow_name = ?").get(workflowName);
+        if (!row)
+            return undefined;
+        let body;
+        try {
+            body = JSON.parse(row.body_json);
+        }
+        catch {
+            body = null;
+        }
+        return {
+            workflowName: row.workflow_name,
+            body,
+            sourceRunId: row.source_run_id,
+            recordedAt: row.recorded_at,
+        };
+    }
+    deleteWorkflowSample(workflowName) {
+        const result = this.db.prepare("DELETE FROM trace_workflow_samples WHERE workflow_name = ?").run(workflowName);
+        return result.changes > 0;
+    }
     // === Cleanup ===
     clearAll() {
         const count = this.db.prepare("SELECT COUNT(*) as c FROM workflow_runs").get()?.c ?? 0;
@@ -945,6 +1249,9 @@ export class SqliteRunStore {
     }
     // === Durable scheduling (Tier 2 #5+#7 follow-up) ===
     upsertScheduledDispatch(row) {
+        // On CONFLICT we deliberately PRESERVE claimed_by + claimed_at —
+        // debounce reset / queue re-defer updates the scheduling fields
+        // but ownership stays with whoever currently holds the claim.
         this.stmt("upsertScheduledDispatch", `INSERT INTO scheduled_dispatches
 				(run_id, workflow_name, trigger_type, scheduled_at, expires_at, dispatch_status, payload_json, created_at)
 			VALUES (?, ?, ?, ?, ?, ?, ?, ?)
@@ -974,25 +1281,57 @@ export class SqliteRunStore {
         const where = clauses.length > 0 ? `WHERE ${clauses.join(" AND ")}` : "";
         const sql = `SELECT * FROM scheduled_dispatches ${where} ORDER BY scheduled_at ASC`;
         const rows = this.db.prepare(sql).all(...args);
-        return rows.map((r) => {
-            let parsedPayload = null;
-            try {
-                parsedPayload = JSON.parse(r.payload_json);
-            }
-            catch {
-                parsedPayload = null;
-            }
-            return {
-                runId: r.run_id,
-                workflowName: r.workflow_name,
-                triggerType: r.trigger_type,
-                scheduledAt: r.scheduled_at,
-                expiresAt: r.expires_at ?? undefined,
-                dispatchStatus: r.dispatch_status,
-                payload: parsedPayload,
-                createdAt: r.created_at,
-            };
-        });
+        return rows.map((r) => this.rowToScheduledDispatch(r));
+    }
+    // === Tier C #2 — cross-process scheduler coordination ===
+    claimDispatches(processId, leaseMs, now, opts) {
+        // Atomic claim: UPDATE rows that are unclaimed OR whose lease has
+        // expired, set the claim, return the affected rows.
+        // SQLite supports `UPDATE ... RETURNING *` since v3.35.0 (2021);
+        // better-sqlite3 ships a modern sqlite so this is safe.
+        const triggerClause = opts?.triggerType ? "AND trigger_type = ?" : "";
+        const sql = `
+			UPDATE scheduled_dispatches
+			SET claimed_by = ?, claimed_at = ?
+			WHERE (claimed_by IS NULL OR claimed_at + ? < ?) ${triggerClause}
+			RETURNING *
+		`;
+        const args = [processId, now, leaseMs, now];
+        if (opts?.triggerType)
+            args.push(opts.triggerType);
+        const claimed = this.db.prepare(sql).all(...args);
+        const out = claimed.map((r) => this.rowToScheduledDispatch(r));
+        out.sort((a, b) => a.scheduledAt - b.scheduledAt);
+        return out;
+    }
+    heartbeatClaims(processId, now) {
+        const result = this.stmt("heartbeatClaims", "UPDATE scheduled_dispatches SET claimed_at = ? WHERE claimed_by = ?").run(now, processId);
+        return result.changes;
+    }
+    releaseClaim(runId) {
+        const result = this.stmt("releaseClaim", "UPDATE scheduled_dispatches SET claimed_by = NULL, claimed_at = NULL WHERE run_id = ? AND claimed_by IS NOT NULL").run(runId);
+        return result.changes > 0;
+    }
+    rowToScheduledDispatch(r) {
+        let parsedPayload = null;
+        try {
+            parsedPayload = JSON.parse(r.payload_json);
+        }
+        catch {
+            parsedPayload = null;
+        }
+        return {
+            runId: r.run_id,
+            workflowName: r.workflow_name,
+            triggerType: r.trigger_type,
+            scheduledAt: r.scheduled_at,
+            expiresAt: r.expires_at ?? undefined,
+            dispatchStatus: r.dispatch_status,
+            payload: parsedPayload,
+            createdAt: r.created_at,
+            claimedBy: r.claimed_by ?? undefined,
+            claimedAt: r.claimed_at ?? undefined,
+        };
     }
     purgeExpiredScheduledDispatches(now) {
         const result = this.stmt("purgeExpiredScheduledDispatches", "DELETE FROM scheduled_dispatches WHERE expires_at IS NOT NULL AND expires_at < ?").run(now);
@@ -1055,9 +1394,11 @@ export class SqliteRunStore {
             debounceMode: (row.debounce_mode ?? undefined),
             pingCount: row.ping_count ?? undefined,
             lastCompletedStepIndex: row.last_completed_step_index ?? undefined,
+            stateSnapshot: row.state_snapshot ?? undefined,
         };
     }
     rowToNodeRun(row) {
+        const flags = decodeNodeRunFlags(row.flags_json);
         return {
             id: row.id,
             runId: row.run_id,
@@ -1077,6 +1418,14 @@ export class SqliteRunStore {
             metrics: row.metrics_json ? JSON.parse(row.metrics_json) : undefined,
             cached: row.cached_json ? JSON.parse(row.cached_json) : undefined,
             attempts: row.attempts_json ? JSON.parse(row.attempts_json) : undefined,
+            iterationContext: row.iteration_context
+                ? JSON.parse(row.iteration_context)
+                : undefined,
+            wait: flags.wait,
+            dispatch: flags.dispatch,
+            subworkflowDepth: flags.subworkflowDepth,
+            middleware: flags.middleware,
+            iterationIndex: flags.iterationIndex,
         };
     }
     rowToEvent(row) {
@@ -1115,4 +1464,15 @@ export class SqliteRunStore {
         };
     }
 }
+function rowToSavedFilter(row) {
+    return {
+        id: row.id,
+        name: row.name,
+        status: row.status,
+        tagsInput: row.tags_input,
+        metadataInput: row.metadata_input,
+        createdAt: row.created_at,
+        updatedAt: row.updated_at,
+    };
+}
 //# sourceMappingURL=SqliteRunStore.js.map