@blokjs/runner 0.2.2 → 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() {
@@ -159,6 +244,302 @@ export class SqliteRunStore {
 					CREATE INDEX IF NOT EXISTS idx_runs_environment ON workflow_runs(environment);
 				`,
             },
+            {
+                // Tier 1 · idempotency caching. Adds:
+                //  - `node_runs.cached_json` for cache-hit lineage on a node
+                //    that short-circuited rather than ran.
+                //  - `idempotency_cache` table for the cache backend keyed
+                //    on (workflow_name, step_id, idempotency_key). Existing
+                //    `node_runs` rows get NULL `cached_json` (a non-cached
+                //    historical execution).
+                version: 4,
+                sql: `
+					ALTER TABLE node_runs ADD COLUMN cached_json TEXT;
+
+					CREATE TABLE IF NOT EXISTS idempotency_cache (
+						workflow_name TEXT NOT NULL,
+						step_id TEXT NOT NULL,
+						idempotency_key TEXT NOT NULL,
+						data_json TEXT NOT NULL,
+						cached_at INTEGER NOT NULL,
+						expires_at INTEGER,
+						source_run_id TEXT NOT NULL,
+						source_node_run_id TEXT NOT NULL,
+						PRIMARY KEY (workflow_name, step_id, idempotency_key)
+					);
+
+					CREATE INDEX IF NOT EXISTS idx_idem_expires ON idempotency_cache(expires_at);
+				`,
+            },
+            {
+                // Tier 1 · retry loop + replay lineage. Adds:
+                //  - `node_runs.attempts_json` for the per-attempt failure
+                //    history before the node ultimately succeeded or was
+                //    fail-noded (capped at MAX_STORED_ATTEMPTS by RunTracker).
+                //  - `workflow_runs.replay_of` for the source run id when a
+                //    run is started via `POST /__blok/runs/:id/replay`.
+                // Existing rows: NULL on both → "no retries; not a replay".
+                version: 5,
+                sql: `
+					ALTER TABLE node_runs ADD COLUMN attempts_json TEXT;
+					ALTER TABLE workflow_runs ADD COLUMN replay_of TEXT;
+					CREATE INDEX IF NOT EXISTS idx_runs_replay_of ON workflow_runs(replay_of);
+				`,
+            },
+            {
+                // Tier 2 · sub-workflow lineage. Adds parent/child run linkage:
+                //  - `workflow_runs.parent_run_id` — the parent run that
+                //    invoked this run via a `subworkflow:` step.
+                //  - `workflow_runs.parent_node_run_id` — the specific
+                //    NodeRun within the parent that was the sub-workflow
+                //    step (lets Studio jump to the exact invocation site).
+                // Index on parent_run_id for efficient `getRunsByParent` queries.
+                // Existing rows: NULL on both → "first-class triggered run".
+                version: 6,
+                sql: `
+					ALTER TABLE workflow_runs ADD COLUMN parent_run_id TEXT;
+					ALTER TABLE workflow_runs ADD COLUMN parent_node_run_id TEXT;
+					CREATE INDEX IF NOT EXISTS idx_runs_parent_run ON workflow_runs(parent_run_id);
+				`,
+            },
+            {
+                // Tier 2 #6 · concurrency keys. Adds a per-(workflow, key)
+                // in-flight slot table. Composite PK on (workflow_name,
+                // concurrency_key, run_id) lets a single run hold at most
+                // one slot per bucket while still permitting the
+                // `concurrencyLimit` runs to coexist within a bucket.
+                // `expires_at` is the lease upper bound — covers
+                // crash-safety when a process dies before releasing.
+                version: 7,
+                sql: `
+					CREATE TABLE IF NOT EXISTS concurrency_locks (
+						workflow_name TEXT NOT NULL,
+						concurrency_key TEXT NOT NULL,
+						run_id TEXT NOT NULL,
+						acquired_at INTEGER NOT NULL,
+						expires_at INTEGER NOT NULL,
+						PRIMARY KEY (workflow_name, concurrency_key, run_id)
+					);
+					CREATE INDEX IF NOT EXISTS idx_locks_expires ON concurrency_locks(expires_at);
+					CREATE INDEX IF NOT EXISTS idx_locks_workflow_key ON concurrency_locks(workflow_name, concurrency_key);
+				`,
+            },
+            {
+                // Tier 2 #5 + #7 · scheduling fields on workflow_runs:
+                //  - `scheduled_at` — dispatch time (ms since epoch) for
+                //    runs deferred via `trigger.delay`. NULL on immediate
+                //    runs.
+                //  - `expires_at` — TTL deadline (ms since epoch). When
+                //    `now > expires_at` at dispatch time, the run is
+                //    marked `expired` and skipped.
+                //  - `debounce_key` — resolved key for runs that absorbed
+                //    pings via `trigger.debounce`. NULL on non-debounced
+                //    runs.
+                //  - `debounce_mode` — `leading` | `trailing`.
+                //  - `ping_count` — number of pings absorbed by this run.
+                // Indexes:
+                //  - `idx_runs_scheduled_at` for "list scheduled runs"
+                //    queries (Studio surface).
+                //  - `idx_runs_debounce_key` for the debounce coordinator's
+                //    "is there an active run for this key?" lookup
+                //    (in-memory map is the hot path; SQLite is the
+                //    fallback / restart-recovery).
+                // Existing rows: NULL on every new column. Backward-compat.
+                version: 8,
+                sql: `
+					ALTER TABLE workflow_runs ADD COLUMN scheduled_at INTEGER;
+					ALTER TABLE workflow_runs ADD COLUMN expires_at INTEGER;
+					ALTER TABLE workflow_runs ADD COLUMN debounce_key TEXT;
+					ALTER TABLE workflow_runs ADD COLUMN debounce_mode TEXT;
+					ALTER TABLE workflow_runs ADD COLUMN ping_count INTEGER;
+					CREATE INDEX IF NOT EXISTS idx_runs_scheduled_at ON workflow_runs(scheduled_at);
+					CREATE INDEX IF NOT EXISTS idx_runs_debounce_key ON workflow_runs(workflow_name, debounce_key);
+				`,
+            },
+            {
+                // Tier 2 #5+#7 follow-up · durable scheduler.
+                //
+                // `scheduled_dispatches` persists the minimum payload needed
+                // to re-fire a deferred dispatch after a process crash. The
+                // `DeferredRunScheduler` writes a row when a dispatch is
+                // scheduled, deletes it when the dispatch fires or is
+                // cancelled. On boot, HttpTrigger.recoverDispatches scans
+                // the table, marks past-due+TTL-expired rows as `expired`,
+                // and re-registers timers for live dispatches.
+                //
+                // Workers don't need this — broker (BullMQ/NATS) already
+                // owns delayed delivery.
+                //
+                // Columns:
+                //  - `run_id` — PK, FK-style reference to `workflow_runs.id`.
+                //  - `workflow_name` — used by trigger boot recovery to
+                //    filter rows it owns (when multiple HTTP triggers
+                //    share the same store).
+                //  - `trigger_type` — `"http"` for v1; future triggers
+                //    can opt in by writing this column.
+                //  - `scheduled_at` — ms since epoch when to fire.
+                //  - `expires_at` — TTL deadline (NULL = no TTL).
+                //  - `dispatch_status` — `"delayed"` | `"queued"` |
+                //    `"debounced"`. Mirrors the run record's status.
+                //  - `payload_json` — JSON-serialized minimal Context
+                //    subset (HTTP: method, path, headers, body, params,
+                //    query, workflow_path). Headers are pre-stripped of
+                //    sensitive keys (authorization, cookie, x-api-key).
+                //  - `created_at` — when the row was first written.
+                version: 9,
+                sql: `
+					CREATE TABLE IF NOT EXISTS scheduled_dispatches (
+						run_id TEXT PRIMARY KEY,
+						workflow_name TEXT NOT NULL,
+						trigger_type TEXT NOT NULL,
+						scheduled_at INTEGER NOT NULL,
+						expires_at INTEGER,
+						dispatch_status TEXT NOT NULL,
+						payload_json TEXT NOT NULL,
+						created_at INTEGER NOT NULL
+					);
+					CREATE INDEX IF NOT EXISTS idx_scheduled_dispatches_at ON scheduled_dispatches(scheduled_at);
+					CREATE INDEX IF NOT EXISTS idx_scheduled_dispatches_trigger ON scheduled_dispatches(trigger_type, workflow_name);
+				`,
+            },
+            {
+                // PR 4 — wait.for(duration) / wait.until(date) step primitive.
+                //
+                // On dispatchDeferred re-entry, the runner needs to know which
+                // steps already completed in the previous pass so it can skip
+                // past them. last_completed_step_index is the canonical
+                // resume cursor — runner increments after each non-wait
+                // step, then on re-entry skips steps with
+                // stepIndex <= last_completed_step_index. Default NULL (= no
+                // resume cursor; runner starts at step 0 as today).
+                version: 10,
+                sql: `
+					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);
@@ -183,9 +564,12 @@ export class SqliteRunStore {
 			INSERT OR REPLACE INTO workflow_runs
 			(id, workflow_name, workflow_path, trigger_type, trigger_summary,
 			 status, started_at, finished_at, duration_ms, error_json,
-			 tags_json, metadata_json, node_count, completed_nodes, environment)
-			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);
+			 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, 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 = [];
@@ -218,6 +602,50 @@ export class SqliteRunStore {
             setClauses.push("metadata_json = ?");
             values.push(JSON.stringify(updates.metadata));
         }
+        if (updates.replayOf !== undefined) {
+            setClauses.push("replay_of = ?");
+            values.push(updates.replayOf);
+        }
+        if (updates.parentRunId !== undefined) {
+            setClauses.push("parent_run_id = ?");
+            values.push(updates.parentRunId);
+        }
+        if (updates.parentNodeRunId !== undefined) {
+            setClauses.push("parent_node_run_id = ?");
+            values.push(updates.parentNodeRunId);
+        }
+        if (updates.scheduledAt !== undefined) {
+            setClauses.push("scheduled_at = ?");
+            values.push(updates.scheduledAt);
+        }
+        if (updates.expiresAt !== undefined) {
+            setClauses.push("expires_at = ?");
+            values.push(updates.expiresAt);
+        }
+        if (updates.debounceKey !== undefined) {
+            setClauses.push("debounce_key = ?");
+            values.push(updates.debounceKey);
+        }
+        if (updates.debounceMode !== undefined) {
+            setClauses.push("debounce_mode = ?");
+            values.push(updates.debounceMode);
+        }
+        if (updates.pingCount !== undefined) {
+            setClauses.push("ping_count = ?");
+            values.push(updates.pingCount);
+        }
+        if (updates.lastCompletedStepIndex !== undefined) {
+            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);
+        }
         if (setClauses.length === 0)
             return;
         values.push(runId);
@@ -229,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)
-			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);
+			 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 = [];
@@ -260,6 +689,18 @@ export class SqliteRunStore {
             setClauses.push("metrics_json = ?");
             values.push(JSON.stringify(updates.metrics));
         }
+        if (updates.cached !== undefined) {
+            setClauses.push("cached_json = ?");
+            values.push(JSON.stringify(updates.cached));
+        }
+        if (updates.attempts !== undefined) {
+            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);
@@ -293,6 +734,32 @@ export class SqliteRunStore {
             conditions.push("status = ?");
             params.push(opts.status);
         }
+        // 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 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(translated.fragment);
+                params.push(...translated.params);
+            }
+        }
         const tags = opts?.tags;
         if (tags && tags.length > 0) {
             // For each tag, check that it exists in the JSON array
@@ -370,6 +837,10 @@ export class SqliteRunStore {
         const row = this.stmt("getNodeRun", "SELECT * FROM node_runs WHERE id = ?").get(nodeRunId);
         return row ? this.rowToNodeRun(row) : undefined;
     }
+    getRunsByParent(parentRunId) {
+        const rows = this.stmt("getRunsByParent", "SELECT * FROM workflow_runs WHERE parent_run_id = ? ORDER BY started_at ASC").all(parentRunId);
+        return rows.map((r) => this.rowToRun(r));
+    }
     getEvents(runId, since) {
         if (since) {
             return this.stmt("getEventsSince", "SELECT * FROM run_events WHERE run_id = ? AND timestamp > ? ORDER BY timestamp").all(runId, since).map((r) => this.rowToEvent(r));
@@ -600,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;
@@ -608,8 +1157,186 @@ export class SqliteRunStore {
         this.db.exec("DELETE FROM node_runs");
         this.db.exec("DELETE FROM workflow_runs");
         this.db.exec("DELETE FROM dashboards");
+        this.db.exec("DELETE FROM idempotency_cache");
+        this.db.exec("DELETE FROM concurrency_locks");
         return count;
     }
+    // === Idempotency cache ===
+    getIdempotencyCache(workflowName, stepId, key) {
+        const row = this.stmt("getIdempotencyCache", "SELECT * FROM idempotency_cache WHERE workflow_name = ? AND step_id = ? AND idempotency_key = ?").get(workflowName, stepId, key);
+        if (!row)
+            return null;
+        if (row.expires_at !== null && row.expires_at <= Date.now()) {
+            // Lazy purge — remove the expired entry inline so subsequent
+            // reads don't even pay for the row materialization.
+            this.stmt("deleteExpiredIdempotency", "DELETE FROM idempotency_cache WHERE workflow_name = ? AND step_id = ? AND idempotency_key = ?").run(workflowName, stepId, key);
+            return null;
+        }
+        return {
+            data: JSON.parse(row.data_json),
+            cachedAt: row.cached_at,
+            expiresAt: row.expires_at,
+            sourceRunId: row.source_run_id,
+            sourceNodeRunId: row.source_node_run_id,
+        };
+    }
+    setIdempotencyCache(workflowName, stepId, key, entry) {
+        this.stmt("setIdempotencyCache", `
+			INSERT OR REPLACE INTO idempotency_cache
+			(workflow_name, step_id, idempotency_key, data_json, cached_at, expires_at,
+			 source_run_id, source_node_run_id)
+			VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+			`).run(workflowName, stepId, key, JSON.stringify(entry.data), entry.cachedAt, entry.expiresAt, entry.sourceRunId, entry.sourceNodeRunId);
+    }
+    purgeExpiredIdempotencyCache(now) {
+        const result = this.stmt("purgeExpiredIdempotency", "DELETE FROM idempotency_cache WHERE expires_at IS NOT NULL AND expires_at <= ?").run(now);
+        return result.changes;
+    }
+    // === Concurrency gating (Tier 2 #6) ===
+    acquireConcurrencySlot(workflowName, concurrencyKey, concurrencyLimit, runId, leaseExpiresAt) {
+        // Wrap the read-modify-write in a transaction so two concurrent
+        // `acquireConcurrencySlot` calls can't both see N < limit and
+        // both grant a slot. better-sqlite3 / bun:sqlite serialize within
+        // a single connection; the transaction is the safety net for any
+        // future multi-connection setup.
+        const txn = this.db.transaction(() => {
+            const now = Date.now();
+            // Lazy-purge expired leases for THIS bucket so we don't deny
+            // based on a slot held by a process that crashed mid-run.
+            this.stmt("deleteExpiredLocksForBucket", "DELETE FROM concurrency_locks WHERE workflow_name = ? AND concurrency_key = ? AND expires_at <= ?").run(workflowName, concurrencyKey, now);
+            // Idempotent re-acquire — if the same runId already holds a
+            // slot, refresh its lease (UPSERT on PK) and report success
+            // without growing the count.
+            const existing = this.stmt("getLockForRun", "SELECT 1 FROM concurrency_locks WHERE workflow_name = ? AND concurrency_key = ? AND run_id = ?").get(workflowName, concurrencyKey, runId);
+            if (existing) {
+                this.stmt("refreshLockLease", "UPDATE concurrency_locks SET expires_at = ? WHERE workflow_name = ? AND concurrency_key = ? AND run_id = ?").run(leaseExpiresAt, workflowName, concurrencyKey, runId);
+                const count = this.stmt("countLocksForBucket", "SELECT COUNT(*) as c FROM concurrency_locks WHERE workflow_name = ? AND concurrency_key = ?").get(workflowName, concurrencyKey)?.c ?? 0;
+                return { acquired: true, currentInFlight: count };
+            }
+            const currentCount = this.stmt("countLocksForBucket", "SELECT COUNT(*) as c FROM concurrency_locks WHERE workflow_name = ? AND concurrency_key = ?").get(workflowName, concurrencyKey)?.c ?? 0;
+            if (currentCount >= concurrencyLimit) {
+                return { acquired: false, currentInFlight: currentCount };
+            }
+            this.stmt("insertLock", `INSERT INTO concurrency_locks
+				(workflow_name, concurrency_key, run_id, acquired_at, expires_at)
+				VALUES (?, ?, ?, ?, ?)`).run(workflowName, concurrencyKey, runId, now, leaseExpiresAt);
+            return { acquired: true, currentInFlight: currentCount + 1 };
+        });
+        return txn();
+    }
+    releaseConcurrencySlot(workflowName, concurrencyKey, runId) {
+        this.stmt("releaseLock", "DELETE FROM concurrency_locks WHERE workflow_name = ? AND concurrency_key = ? AND run_id = ?").run(workflowName, concurrencyKey, runId);
+    }
+    purgeExpiredConcurrencySlots(now) {
+        const result = this.stmt("purgeExpiredLocks", "DELETE FROM concurrency_locks WHERE expires_at <= ?").run(now);
+        return result.changes;
+    }
+    getConcurrencySnapshot(now) {
+        const rows = this.db
+            .prepare("SELECT workflow_name, concurrency_key, run_id, expires_at FROM concurrency_locks WHERE expires_at > ?")
+            .all(now);
+        const buckets = new Map();
+        for (const r of rows) {
+            const key = `${r.workflow_name}\x1f${r.concurrency_key}`;
+            let bucket = buckets.get(key);
+            if (!bucket) {
+                bucket = { workflowName: r.workflow_name, concurrencyKey: r.concurrency_key, leases: [] };
+                buckets.set(key, bucket);
+            }
+            bucket.leases.push({ runId: r.run_id, expiresAt: r.expires_at });
+        }
+        return Array.from(buckets.values());
+    }
+    // === 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 (?, ?, ?, ?, ?, ?, ?, ?)
+			ON CONFLICT(run_id) DO UPDATE SET
+				scheduled_at = excluded.scheduled_at,
+				expires_at = excluded.expires_at,
+				dispatch_status = excluded.dispatch_status,
+				payload_json = excluded.payload_json`).run(row.runId, row.workflowName, row.triggerType, row.scheduledAt, row.expiresAt ?? null, row.dispatchStatus, JSON.stringify(row.payload ?? null), row.createdAt);
+    }
+    deleteScheduledDispatch(runId) {
+        const result = this.stmt("deleteScheduledDispatch", "DELETE FROM scheduled_dispatches WHERE run_id = ?").run(runId);
+        return result.changes > 0;
+    }
+    getScheduledDispatches(opts) {
+        const triggerType = opts?.triggerType;
+        const status = opts?.status;
+        const clauses = [];
+        const args = [];
+        if (triggerType) {
+            clauses.push("trigger_type = ?");
+            args.push(triggerType);
+        }
+        if (status) {
+            clauses.push("dispatch_status = ?");
+            args.push(status);
+        }
+        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) => 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);
+        return result.changes;
+    }
     deleteRunsBefore(timestamp) {
         // Foreign key CASCADE handles child tables
         const result = this.db
@@ -658,9 +1385,20 @@ export class SqliteRunStore {
             // "production" so the EnvChip default-scope still surfaces
             // historical data without a backfill.
             environment: row.environment ?? "production",
+            replayOf: row.replay_of ?? undefined,
+            parentRunId: row.parent_run_id ?? undefined,
+            parentNodeRunId: row.parent_node_run_id ?? undefined,
+            scheduledAt: row.scheduled_at ?? undefined,
+            expiresAt: row.expires_at ?? undefined,
+            debounceKey: row.debounce_key ?? undefined,
+            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,
@@ -678,6 +1416,16 @@ export class SqliteRunStore {
             depth: row.depth,
             stepIndex: row.step_index,
             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) {
@@ -716,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