@blokjs/runner 0.2.2 → 0.6.0

package/dist/tracing/PostgresRunStore.js

@@ -156,6 +156,172 @@ export class PostgresRunStore {
 						`);
                     },
                 },
+                {
+                    // Tier 2 follow-up · durable schema for Tier 1 idempotency
+                    // cache, Tier 2 #6 concurrency locks, and Tier 2 #5+#7
+                    // scheduled dispatches. Previously these all delegated to
+                    // the in-memory mirror only, so a process restart lost the
+                    // state. The hybrid pattern (sync memory + async PG mirror)
+                    // matches the existing workflow_runs/node_runs flow.
+                    version: 3,
+                    up: async () => {
+                        await client.query(`
+							CREATE TABLE IF NOT EXISTS idempotency_cache (
+								workflow_name TEXT NOT NULL,
+								step_id TEXT NOT NULL,
+								idempotency_key TEXT NOT NULL,
+								data_json JSONB NOT NULL,
+								cached_at BIGINT NOT NULL,
+								expires_at BIGINT,
+								source_run_id TEXT NOT NULL,
+								source_node_run_id TEXT NOT NULL,
+								PRIMARY KEY (workflow_name, step_id, idempotency_key)
+							)
+						`);
+                        await client.query("CREATE INDEX IF NOT EXISTS idx_idem_cache_expires ON idempotency_cache(expires_at)");
+                        await client.query(`
+							CREATE TABLE IF NOT EXISTS concurrency_locks (
+								workflow_name TEXT NOT NULL,
+								concurrency_key TEXT NOT NULL,
+								run_id TEXT NOT NULL,
+								acquired_at BIGINT NOT NULL,
+								expires_at BIGINT NOT NULL,
+								PRIMARY KEY (workflow_name, concurrency_key, run_id)
+							)
+						`);
+                        await client.query("CREATE INDEX IF NOT EXISTS idx_locks_expires ON concurrency_locks(expires_at)");
+                        await client.query("CREATE INDEX IF NOT EXISTS idx_locks_workflow_key ON concurrency_locks(workflow_name, concurrency_key)");
+                        await client.query(`
+							CREATE TABLE IF NOT EXISTS scheduled_dispatches (
+								run_id TEXT PRIMARY KEY,
+								workflow_name TEXT NOT NULL,
+								trigger_type TEXT NOT NULL,
+								scheduled_at BIGINT NOT NULL,
+								expires_at BIGINT,
+								dispatch_status TEXT NOT NULL,
+								payload_json JSONB NOT NULL,
+								created_at BIGINT NOT NULL
+							)
+						`);
+                        await client.query("CREATE INDEX IF NOT EXISTS idx_scheduled_dispatches_at ON scheduled_dispatches(scheduled_at)");
+                        await client.query("CREATE INDEX IF NOT EXISTS idx_scheduled_dispatches_trigger ON scheduled_dispatches(trigger_type, workflow_name)");
+                    },
+                },
+                {
+                    // PR 4 — wait.for / wait.until step primitive needs a
+                    // resume cursor so dispatchDeferred re-entry skips
+                    // already-completed pre-wait steps. Mirror sqlite v10.
+                    version: 4,
+                    up: async () => {
+                        await client.query("ALTER TABLE workflow_runs ADD COLUMN IF NOT EXISTS last_completed_step_index INTEGER");
+                    },
+                },
+                {
+                    // PR 1-5 polish · catch up to sqlite's workflow_runs columns.
+                    // PG migrations historically lagged: v3 added the cache /
+                    // locks / dispatches tables and v4 added
+                    // `last_completed_step_index`, but the columns sqlite added
+                    // across migrations 3 / 5 / 6 / 8 (`environment`,
+                    // `replay_of`, `parent_run_id`, `parent_node_run_id`,
+                    // `scheduled_at`, `expires_at`, `debounce_key`,
+                    // `debounce_mode`, `ping_count`) were never mirrored.
+                    // `saveRun`/`updateRun`/`rowToRun` silently dropped them
+                    // across restarts, so PG-backed deployments lost replay
+                    // lineage, sub-workflow lineage, and ALL Tier 2 #5+#7
+                    // scheduling state on every restart. This migration adds
+                    // the columns + indexes so PG matches sqlite. Pre-existing
+                    // rows get NULL on every new column (backward-compat;
+                    // `rowToRun` reads NULL `environment` as "production" to
+                    // match sqlite's legacy default).
+                    version: 5,
+                    up: async () => {
+                        await client.query("ALTER TABLE workflow_runs ADD COLUMN IF NOT EXISTS environment TEXT");
+                        await client.query("ALTER TABLE workflow_runs ADD COLUMN IF NOT EXISTS replay_of TEXT");
+                        await client.query("ALTER TABLE workflow_runs ADD COLUMN IF NOT EXISTS parent_run_id TEXT");
+                        await client.query("ALTER TABLE workflow_runs ADD COLUMN IF NOT EXISTS parent_node_run_id TEXT");
+                        await client.query("ALTER TABLE workflow_runs ADD COLUMN IF NOT EXISTS scheduled_at BIGINT");
+                        await client.query("ALTER TABLE workflow_runs ADD COLUMN IF NOT EXISTS expires_at BIGINT");
+                        await client.query("ALTER TABLE workflow_runs ADD COLUMN IF NOT EXISTS debounce_key TEXT");
+                        await client.query("ALTER TABLE workflow_runs ADD COLUMN IF NOT EXISTS debounce_mode TEXT");
+                        await client.query("ALTER TABLE workflow_runs ADD COLUMN IF NOT EXISTS ping_count INTEGER");
+                        await client.query("CREATE INDEX IF NOT EXISTS idx_runs_environment ON workflow_runs(environment)");
+                        await client.query("CREATE INDEX IF NOT EXISTS idx_runs_replay_of ON workflow_runs(replay_of)");
+                        await client.query("CREATE INDEX IF NOT EXISTS idx_runs_parent_run ON workflow_runs(parent_run_id)");
+                        await client.query("CREATE INDEX IF NOT EXISTS idx_runs_scheduled_at ON workflow_runs(scheduled_at)");
+                        await client.query("CREATE INDEX IF NOT EXISTS idx_runs_debounce_key ON workflow_runs(workflow_name, debounce_key)");
+                    },
+                },
+                {
+                    // Tier C #2 — cross-process scheduler coordination.
+                    //
+                    // Multi-process PG deployments risk double-firing the same
+                    // dispatch when both processes' `recoverDispatches()`
+                    // register timers against the same row. The claim columns
+                    // let processes atomically take ownership; the
+                    // `DeferredRunScheduler` heartbeats `claimed_at` while a
+                    // timer is registered; a dead process's claim expires
+                    // after `BLOK_SCHEDULER_CLAIM_LEASE_MS` and a surviving
+                    // process can take over on its next recovery.
+                    version: 6,
+                    up: async () => {
+                        await client.query("ALTER TABLE scheduled_dispatches ADD COLUMN IF NOT EXISTS claimed_by TEXT");
+                        await client.query("ALTER TABLE scheduled_dispatches ADD COLUMN IF NOT EXISTS claimed_at BIGINT");
+                        await client.query("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.
+                    // Matches the sqlite store's v14 schema. Hybrid pattern:
+                    // rehydrated into the in-memory mirror on boot via
+                    // `loadRecent`, mutated through the same `enqueueWrite`
+                    // fan-out used by dashboards.
+                    version: 7,
+                    up: async () => {
+                        await client.query(`
+							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 BIGINT NOT NULL,
+								updated_at BIGINT NOT NULL
+							)
+						`);
+                        await client.query("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. Matches the sqlite store's v15
+                    // schema. 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.
+                    version: 8,
+                    up: async () => {
+                        await client.query(`
+							CREATE TABLE IF NOT EXISTS trace_workflow_samples (
+								workflow_name TEXT PRIMARY KEY,
+								body_json JSONB NOT NULL,
+								source_run_id TEXT NOT NULL,
+								recorded_at BIGINT NOT NULL
+							)
+						`);
+                    },
+                },
+                {
+                    // v0.6 follow-up — bag column for Studio-visible step flags
+                    // (`wait`, `dispatch`, `subworkflowDepth`, `middleware`,
+                    // `iterationIndex`). Mirrors sqlite v16. Previously these
+                    // fields lived only on the in-memory NodeRun and vanished
+                    // on round-trip — rail badges disappeared after process
+                    // restart. JSONB so future flag additions don't need new
+                    // migrations.
+                    version: 9,
+                    up: async () => {
+                        await client.query("ALTER TABLE node_runs ADD COLUMN IF NOT EXISTS flags_json JSONB");
+                    },
+                },
             ];
             for (const m of migrations) {
                 if (!applied.has(m.version)) {
@@ -176,6 +342,20 @@ export class PostgresRunStore {
             client.release();
         }
     }
+    /**
+     * Review fix-up · CONCERN-2. Per-table cap on `loadRecent`'s rehydration
+     * queries. Without it, a deployment with 1M+ idempotency cache entries
+     * spends seconds + memory on every boot loading rows it'll never read
+     * before the Janitor sweeps them. Default 100K rows per table — well
+     * above any reasonable hot-set size yet bounded for boot latency.
+     */
+    getLoadRecentLimit() {
+        const raw = process.env.BLOK_PG_LOADRECENT_LIMIT;
+        if (!raw || !/^\d+$/.test(raw))
+            return 100_000;
+        const n = Number(raw);
+        return n > 0 ? n : 100_000;
+    }
     async loadRecent() {
         const client = await this.pool.connect();
         try {
@@ -207,6 +387,130 @@ export class PostgresRunStore {
             for (const row of dashRows) {
                 this.memory.saveDashboard(this.rowToDashboard(row));
             }
+            // E2 · rehydrate saved filters. Unbounded (operator-curated
+            // set, not a per-run table — typical fleet has < 100 entries).
+            try {
+                const { rows: filterRows } = await client.query("SELECT * FROM trace_saved_filters ORDER BY updated_at DESC");
+                for (const row of filterRows) {
+                    this.memory.upsertSavedFilter({
+                        id: row.id,
+                        name: row.name,
+                        status: row.status,
+                        tagsInput: row.tags_input,
+                        metadataInput: row.metadata_input,
+                        createdAt: Number(row.created_at),
+                        updatedAt: Number(row.updated_at),
+                    });
+                }
+            }
+            catch (err) {
+                // First-time deployments may not have run the v7 migration
+                // when this loadRecent fires (the migration is at boot;
+                // this should follow). Log + continue.
+                console.warn("[blok][pg] failed to load saved filters:", err.message);
+            }
+            // v0.6 · rehydrate recorded sample bodies. Cardinality
+            // bounded by the number of workflows in the deployment, not
+            // the run volume — unbounded SELECT is fine.
+            try {
+                const { rows: sampleRows } = await client.query("SELECT * FROM trace_workflow_samples");
+                for (const row of sampleRows) {
+                    this.memory.recordWorkflowSample({
+                        workflowName: row.workflow_name,
+                        body: typeof row.body_json === "string" ? JSON.parse(row.body_json) : row.body_json,
+                        sourceRunId: row.source_run_id,
+                        recordedAt: Number(row.recorded_at),
+                    });
+                }
+            }
+            catch (err) {
+                console.warn("[blok][pg] failed to load workflow samples:", err.message);
+            }
+            // Tier 2 follow-up · rehydrate idempotency cache (un-expired entries only).
+            //
+            // Review fix-up · CONCERN-2. Add `ORDER BY cached_at DESC LIMIT N`.
+            // Newest cache entries are most likely to be re-hit by the next
+            // idempotent step; older ones the Janitor will sweep on its next
+            // pass. Without this LIMIT, deployments with 1M+ rows OOM at boot.
+            const now = Date.now();
+            const loadRecentLimit = this.getLoadRecentLimit();
+            try {
+                const { rows: idemRows } = await client.query(`SELECT * FROM idempotency_cache
+					 WHERE expires_at IS NULL OR expires_at > $1
+					 ORDER BY cached_at DESC
+					 LIMIT $2`, [now, loadRecentLimit]);
+                for (const row of idemRows) {
+                    this.memory.setIdempotencyCache(row.workflow_name, row.step_id, row.idempotency_key, {
+                        data: typeof row.data_json === "string" ? JSON.parse(row.data_json) : row.data_json,
+                        cachedAt: Number(row.cached_at),
+                        expiresAt: row.expires_at !== null ? Number(row.expires_at) : null,
+                        sourceRunId: row.source_run_id,
+                        sourceNodeRunId: row.source_node_run_id,
+                    });
+                }
+            }
+            catch (err) {
+                // Pre-v3 PG schema may not have the table yet — fall through quietly.
+                if (!String(err.message).match(/relation .* does not exist/i)) {
+                    console.error("[PostgresRunStore] idempotency_cache load failed:", err.message);
+                }
+            }
+            // Tier 2 follow-up · rehydrate concurrency leases (un-expired only).
+            //
+            // Review fix-up · CONCERN-2. Add `ORDER BY expires_at DESC LIMIT N`.
+            // Locks with the longest remaining lease are most likely still
+            // active and worth restoring; expired ones are filtered already.
+            try {
+                const { rows: lockRows } = await client.query(`SELECT * FROM concurrency_locks
+					 WHERE expires_at > $1
+					 ORDER BY expires_at DESC
+					 LIMIT $2`, [now, loadRecentLimit]);
+                for (const row of lockRows) {
+                    this.memory.acquireConcurrencySlot(row.workflow_name, row.concurrency_key, Number.MAX_SAFE_INTEGER, // skip the limit check — we're restoring, not granting
+                    row.run_id, Number(row.expires_at));
+                }
+            }
+            catch (err) {
+                if (!String(err.message).match(/relation .* does not exist/i)) {
+                    console.error("[PostgresRunStore] concurrency_locks load failed:", err.message);
+                }
+            }
+            // Tier 2 follow-up · rehydrate scheduled dispatches.
+            // PR 2 A5 — ORDER BY scheduled_at ASC so past-due dispatches
+            // hydrate first. recoverDispatches's past-due → fire-immediately
+            // path benefits from the ordering.
+            //
+            // Review fix-up · CONCERN-2. Add LIMIT for defense-in-depth.
+            // Even with the 1MB payload cap (PR 2 A4), 100K dispatches × 1MB
+            // = 100GB of JSON-decode work at boot. Past-due first means the
+            // LIMIT caps how many recover per boot; the rest surface on the
+            // Janitor's next sweep or a subsequent boot.
+            try {
+                const { rows: dispatchRows } = await client.query("SELECT * FROM scheduled_dispatches ORDER BY scheduled_at ASC LIMIT $1", [loadRecentLimit]);
+                for (const row of dispatchRows) {
+                    this.memory.upsertScheduledDispatch({
+                        runId: row.run_id,
+                        workflowName: row.workflow_name,
+                        triggerType: row.trigger_type,
+                        scheduledAt: Number(row.scheduled_at),
+                        expiresAt: row.expires_at !== null ? Number(row.expires_at) : undefined,
+                        dispatchStatus: row.dispatch_status,
+                        payload: typeof row.payload_json === "string" ? JSON.parse(row.payload_json) : row.payload_json,
+                        createdAt: Number(row.created_at),
+                        // Tier C #2 — surface claim state across restart so
+                        // the trigger doesn't re-claim a row another process
+                        // already owns. PG columns may not exist on pre-v6
+                        // databases — guard with `?? undefined`.
+                        claimedBy: row.claimed_by !== null && row.claimed_by !== undefined ? row.claimed_by : undefined,
+                        claimedAt: row.claimed_at !== null && row.claimed_at !== undefined ? Number(row.claimed_at) : undefined,
+                    });
+                }
+            }
+            catch (err) {
+                if (!String(err.message).match(/relation .* does not exist/i)) {
+                    console.error("[PostgresRunStore] scheduled_dispatches load failed:", err.message);
+                }
+            }
         }
         finally {
             client.release();
@@ -215,12 +519,22 @@ export class PostgresRunStore {
     // === Writes (sync via memory + async queue to PG) ===
     saveRun(run) {
         this.memory.saveRun(run);
+        // PR 1-5 polish · column set mirrors sqlite saveRun (24 columns).
+        // PG migration v5 added the trailing 9 (environment / replay_of /
+        // parent_run_id / parent_node_run_id / scheduled_at / expires_at /
+        // debounce_key / debounce_mode / ping_count); PG migration v4 added
+        // last_completed_step_index. Without these the PG mirror silently
+        // dropped scheduling + lineage + resume-cursor state across restart.
         this.enqueueWrite(() => this.pool
             .query(`INSERT 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)
-				VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, $13, $14)
+				 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 ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, $13, $14,
+				        $15, $16, $17, $18, $19, $20, $21, $22, $23, $24)
 				ON CONFLICT (id) DO UPDATE SET
 				 status = EXCLUDED.status,
 				 finished_at = EXCLUDED.finished_at,
@@ -228,7 +542,17 @@ export class PostgresRunStore {
 				 error_json = EXCLUDED.error_json,
 				 tags_json = EXCLUDED.tags_json,
 				 metadata_json = EXCLUDED.metadata_json,
-				 completed_nodes = EXCLUDED.completed_nodes`, [
+				 completed_nodes = EXCLUDED.completed_nodes,
+				 environment = EXCLUDED.environment,
+				 replay_of = EXCLUDED.replay_of,
+				 parent_run_id = EXCLUDED.parent_run_id,
+				 parent_node_run_id = EXCLUDED.parent_node_run_id,
+				 scheduled_at = EXCLUDED.scheduled_at,
+				 expires_at = EXCLUDED.expires_at,
+				 debounce_key = EXCLUDED.debounce_key,
+				 debounce_mode = EXCLUDED.debounce_mode,
+				 ping_count = EXCLUDED.ping_count,
+				 last_completed_step_index = EXCLUDED.last_completed_step_index`, [
             run.id,
             run.workflowName,
             run.workflowPath,
@@ -243,6 +567,16 @@ export class PostgresRunStore {
             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,
         ])
             .then(() => { }));
     }
@@ -279,6 +613,55 @@ export class PostgresRunStore {
             setClauses.push(`metadata_json = $${paramIdx++}`);
             values.push(JSON.stringify(updates.metadata));
         }
+        // PR 1-5 polish · scheduling, lineage, and resume-cursor fields
+        // updateRun must mirror sqlite. Each marker tracker method
+        // (markRunDelayed / markRunQueued / markRunDebounced / markRunExpired
+        // / recordDebouncePing / transitionRunToRunning / RunnerSteps wait
+        // branch) updates one or more of these. Without these clauses the
+        // in-memory mirror has the value but PG keeps the original (or
+        // NULL).
+        if (updates.replayOf !== undefined) {
+            setClauses.push(`replay_of = $${paramIdx++}`);
+            values.push(updates.replayOf);
+        }
+        if (updates.parentRunId !== undefined) {
+            setClauses.push(`parent_run_id = $${paramIdx++}`);
+            values.push(updates.parentRunId);
+        }
+        if (updates.parentNodeRunId !== undefined) {
+            setClauses.push(`parent_node_run_id = $${paramIdx++}`);
+            values.push(updates.parentNodeRunId);
+        }
+        if (updates.scheduledAt !== undefined) {
+            setClauses.push(`scheduled_at = $${paramIdx++}`);
+            values.push(updates.scheduledAt);
+        }
+        if (updates.expiresAt !== undefined) {
+            setClauses.push(`expires_at = $${paramIdx++}`);
+            values.push(updates.expiresAt);
+        }
+        if (updates.debounceKey !== undefined) {
+            setClauses.push(`debounce_key = $${paramIdx++}`);
+            values.push(updates.debounceKey);
+        }
+        if (updates.debounceMode !== undefined) {
+            setClauses.push(`debounce_mode = $${paramIdx++}`);
+            values.push(updates.debounceMode);
+        }
+        if (updates.pingCount !== undefined) {
+            setClauses.push(`ping_count = $${paramIdx++}`);
+            values.push(updates.pingCount);
+        }
+        if (updates.lastCompletedStepIndex !== undefined) {
+            setClauses.push(`last_completed_step_index = $${paramIdx++}`);
+            values.push(updates.lastCompletedStepIndex);
+        }
+        // `transitionRunToRunning` (Tier 2 #5+#7) preserves the original
+        // startedAt by updating it. Mirror sqlite, which also accepts it.
+        if (updates.startedAt !== undefined) {
+            setClauses.push(`started_at = $${paramIdx++}`);
+            values.push(updates.startedAt);
+        }
         if (setClauses.length === 0)
             return;
         values.push(runId);
@@ -288,20 +671,22 @@ export class PostgresRunStore {
     }
     saveNodeRun(nodeRun) {
         this.memory.saveNodeRun(nodeRun);
+        const flagsJson = encodeNodeRunFlagsForPg(nodeRun);
         this.enqueueWrite(() => this.pool
             .query(`INSERT INTO node_runs
 				(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 ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, $13, $14, $15, $16)
+				 parent_node_id, depth, step_index, metrics_json, flags_json)
+				VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, $13, $14, $15, $16, $17)
 				ON CONFLICT (id) DO UPDATE SET
 				 status = EXCLUDED.status,
 				 finished_at = EXCLUDED.finished_at,
 				 duration_ms = EXCLUDED.duration_ms,
 				 outputs_json = EXCLUDED.outputs_json,
 				 error_json = EXCLUDED.error_json,
-				 metrics_json = EXCLUDED.metrics_json`, [
+				 metrics_json = EXCLUDED.metrics_json,
+				 flags_json = EXCLUDED.flags_json`, [
             nodeRun.id,
             nodeRun.runId,
             nodeRun.nodeName,
@@ -318,6 +703,7 @@ export class PostgresRunStore {
             nodeRun.depth,
             nodeRun.stepIndex,
             nodeRun.metrics ? JSON.stringify(nodeRun.metrics) : null,
+            flagsJson,
         ])
             .then(() => { }));
     }
@@ -402,6 +788,12 @@ export class PostgresRunStore {
     getNodeRun(nodeRunId) {
         return this.memory.getNodeRun(nodeRunId);
     }
+    getRunsByParent(parentRunId) {
+        // Tier 2 sub-workflow lineage. Same in-memory delegation strategy
+        // as the idempotency cache — durable PG schema for parent_run_id
+        // is deferred to a follow-up.
+        return this.memory.getRunsByParent(parentRunId);
+    }
     getEvents(runId, since) {
         return this.memory.getEvents(runId, since);
     }
@@ -480,6 +872,62 @@ export class PostgresRunStore {
         values.push(dashboardId);
         this.enqueueWrite(() => this.pool.query(`UPDATE dashboards SET ${setClauses.join(", ")} WHERE id = $${paramIdx}`, values).then(() => { }));
     }
+    // === Saved filters (E2) ===
+    upsertSavedFilter(filter) {
+        const persisted = this.memory.upsertSavedFilter(filter);
+        this.enqueueWrite(() => this.pool
+            .query(`INSERT INTO trace_saved_filters
+						(id, name, status, tags_input, metadata_input, created_at, updated_at)
+					 VALUES ($1, $2, $3, $4, $5, $6, $7)
+					 ON CONFLICT (name) DO UPDATE SET
+						status = EXCLUDED.status,
+						tags_input = EXCLUDED.tags_input,
+						metadata_input = EXCLUDED.metadata_input,
+						updated_at = EXCLUDED.updated_at`, [
+            persisted.id,
+            persisted.name,
+            persisted.status,
+            persisted.tagsInput,
+            persisted.metadataInput,
+            persisted.createdAt,
+            persisted.updatedAt,
+        ])
+            .then(() => { }));
+        return persisted;
+    }
+    listSavedFilters() {
+        return this.memory.listSavedFilters();
+    }
+    deleteSavedFilter(name) {
+        const removed = this.memory.deleteSavedFilter(name);
+        if (removed) {
+            this.enqueueWrite(() => this.pool.query("DELETE FROM trace_saved_filters WHERE name = $1", [name]).then(() => { }));
+        }
+        return removed;
+    }
+    // === Sample-body recording (option C) ===
+    recordWorkflowSample(sample) {
+        // First-record-wins. Memory holds the canonical sample (sync
+        // reads). PG INSERT uses ON CONFLICT DO NOTHING — same
+        // "first-record sticks" semantic as the sqlite store.
+        const persisted = this.memory.recordWorkflowSample(sample);
+        this.enqueueWrite(() => this.pool
+            .query(`INSERT INTO trace_workflow_samples (workflow_name, body_json, source_run_id, recorded_at)
+					 VALUES ($1, $2, $3, $4)
+					 ON CONFLICT (workflow_name) DO NOTHING`, [persisted.workflowName, JSON.stringify(persisted.body), persisted.sourceRunId, persisted.recordedAt])
+            .then(() => { }));
+        return persisted;
+    }
+    getWorkflowSample(workflowName) {
+        return this.memory.getWorkflowSample(workflowName);
+    }
+    deleteWorkflowSample(workflowName) {
+        const removed = this.memory.deleteWorkflowSample(workflowName);
+        if (removed) {
+            this.enqueueWrite(() => this.pool.query("DELETE FROM trace_workflow_samples WHERE workflow_name = $1", [workflowName]).then(() => { }));
+        }
+        return removed;
+    }
     // === Cleanup ===
     clearAll() {
         const count = this.memory.clearAll();
@@ -489,6 +937,23 @@ export class PostgresRunStore {
             await this.pool.query("DELETE FROM node_runs");
             await this.pool.query("DELETE FROM workflow_runs");
             await this.pool.query("DELETE FROM dashboards");
+            // Tier 2 follow-up — wipe durable tables too. Wrapped in
+            // individual try blocks so a missing table (pre-v3 schema) on
+            // one doesn't abort the others.
+            for (const sql of [
+                "DELETE FROM idempotency_cache",
+                "DELETE FROM concurrency_locks",
+                "DELETE FROM scheduled_dispatches",
+            ]) {
+                try {
+                    await this.pool.query(sql);
+                }
+                catch (err) {
+                    if (!String(err.message).match(/relation .* does not exist/i)) {
+                        console.error(`[PostgresRunStore] ${sql} failed:`, err.message);
+                    }
+                }
+            }
         });
         return count;
     }
@@ -513,6 +978,204 @@ export class PostgresRunStore {
         });
         this.closed = true;
     }
+    // === Idempotency cache (Tier 1) ===
+    //
+    // PG durable cache is out of scope for this PR — delegate to the
+    // in-memory layer this store already uses for hot reads. Same-process
+    // hits work exactly like the SQLite store; cross-process / cross-restart
+    // hits are deferred to a follow-up PG schema migration. Operators
+    // running PG today retain pre-Phase-3 behaviour (no caching) on a fresh
+    // process and gain in-memory caching within a single process lifetime.
+    //
+    // Tier 2 follow-up (migration v3) — sync reads stay on the in-memory
+    // mirror; writes async-persist to PG. On boot, `loadRecent()` rehydrates
+    // the in-memory cache from PG so deferred dispatches + idempotency
+    // entries + concurrency leases survive restarts.
+    getIdempotencyCache(workflowName, stepId, key) {
+        return this.memory.getIdempotencyCache(workflowName, stepId, key);
+    }
+    setIdempotencyCache(workflowName, stepId, key, entry) {
+        this.memory.setIdempotencyCache(workflowName, stepId, key, entry);
+        this.enqueueWrite(() => this.pool
+            .query(`INSERT INTO idempotency_cache
+					(workflow_name, step_id, idempotency_key, data_json,
+					 cached_at, expires_at, source_run_id, source_node_run_id)
+					VALUES ($1, $2, $3, $4, $5, $6, $7, $8)
+					ON CONFLICT (workflow_name, step_id, idempotency_key) DO UPDATE SET
+					 data_json = EXCLUDED.data_json,
+					 cached_at = EXCLUDED.cached_at,
+					 expires_at = EXCLUDED.expires_at,
+					 source_run_id = EXCLUDED.source_run_id,
+					 source_node_run_id = EXCLUDED.source_node_run_id`, [
+            workflowName,
+            stepId,
+            key,
+            JSON.stringify(entry.data),
+            entry.cachedAt,
+            entry.expiresAt,
+            entry.sourceRunId,
+            entry.sourceNodeRunId,
+        ])
+            .then(() => { }));
+    }
+    purgeExpiredIdempotencyCache(now) {
+        const removed = this.memory.purgeExpiredIdempotencyCache(now);
+        this.enqueueWrite(() => this.pool
+            .query("DELETE FROM idempotency_cache WHERE expires_at IS NOT NULL AND expires_at <= $1", [now])
+            .then(() => { }));
+        return removed;
+    }
+    // === Concurrency gating (Tier 2 #6) ===
+    // Sync grants happen on the in-memory mirror; PG mirror is async-only.
+    // Cross-process coordination via the gate itself requires the dedicated
+    // `BLOK_CONCURRENCY_BACKEND=nats-kv` backend (Tier 2 #6 follow-up).
+    // PG persistence here is purely for crash-recovery — boot loads active
+    // (un-expired) leases back into memory so a process restart doesn't
+    // over-grant.
+    acquireConcurrencySlot(workflowName, concurrencyKey, concurrencyLimit, runId, leaseExpiresAt) {
+        const result = this.memory.acquireConcurrencySlot(workflowName, concurrencyKey, concurrencyLimit, runId, leaseExpiresAt);
+        if (result.acquired) {
+            this.enqueueWrite(() => this.pool
+                .query(`INSERT INTO concurrency_locks
+						(workflow_name, concurrency_key, run_id, acquired_at, expires_at)
+						VALUES ($1, $2, $3, $4, $5)
+						ON CONFLICT (workflow_name, concurrency_key, run_id) DO UPDATE SET
+						 expires_at = EXCLUDED.expires_at`, [workflowName, concurrencyKey, runId, Date.now(), leaseExpiresAt])
+                .then(() => { }));
+        }
+        return result;
+    }
+    releaseConcurrencySlot(workflowName, concurrencyKey, runId) {
+        this.memory.releaseConcurrencySlot(workflowName, concurrencyKey, runId);
+        this.enqueueWrite(() => this.pool
+            .query("DELETE FROM concurrency_locks WHERE workflow_name = $1 AND concurrency_key = $2 AND run_id = $3", [
+            workflowName,
+            concurrencyKey,
+            runId,
+        ])
+            .then(() => { }));
+    }
+    purgeExpiredConcurrencySlots(now) {
+        const removed = this.memory.purgeExpiredConcurrencySlots(now);
+        this.enqueueWrite(() => this.pool.query("DELETE FROM concurrency_locks WHERE expires_at <= $1", [now]).then(() => { }));
+        return removed;
+    }
+    getConcurrencySnapshot(now) {
+        return this.memory.getConcurrencySnapshot(now);
+    }
+    // === Durable scheduling (Tier 2 #5+#7 follow-up) ===
+    // Tier 2 follow-up (migration v3) — PG mirror is now real durable
+    // storage. Boot recovery (`HttpTrigger.recoverDispatches`) reads the
+    // in-memory mirror, which is rehydrated from PG on init.
+    upsertScheduledDispatch(row) {
+        this.memory.upsertScheduledDispatch(row);
+        // Tier C #2 — preserve claimed_by + claimed_at on conflict, same
+        // invariant as sqlite. Re-upserts (debounce reset, queue re-defer)
+        // MUST NOT release the claim or peers would re-claim the same row.
+        this.enqueueWrite(() => this.pool
+            .query(`INSERT INTO scheduled_dispatches
+					(run_id, workflow_name, trigger_type, scheduled_at, expires_at,
+					 dispatch_status, payload_json, created_at)
+					VALUES ($1, $2, $3, $4, $5, $6, $7, $8)
+					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`, [
+            row.runId,
+            row.workflowName,
+            row.triggerType,
+            row.scheduledAt,
+            row.expiresAt ?? null,
+            row.dispatchStatus,
+            JSON.stringify(row.payload ?? null),
+            row.createdAt,
+        ])
+            .then(() => { }));
+    }
+    // === Tier C #2 — cross-process scheduler coordination ===
+    //
+    // These methods bypass the in-memory mirror and hit PG directly —
+    // claim atomicity REQUIRES the database to be the single source of
+    // truth. The mirror is refreshed lazily as queries return.
+    async claimDispatchesAsync(processId, leaseMs, now, opts) {
+        const triggerClause = opts?.triggerType ? "AND trigger_type = $4" : "";
+        const args = [processId, now, leaseMs];
+        if (opts?.triggerType)
+            args.push(opts.triggerType);
+        const sql = `
+			UPDATE scheduled_dispatches
+			SET claimed_by = $1, claimed_at = $2
+			WHERE (claimed_by IS NULL OR claimed_at + $3 < $2) ${triggerClause}
+			RETURNING *
+		`;
+        const { rows } = await this.pool.query(sql, args);
+        const out = rows.map((r) => ({
+            runId: r.run_id,
+            workflowName: r.workflow_name,
+            triggerType: r.trigger_type,
+            scheduledAt: Number(r.scheduled_at),
+            expiresAt: r.expires_at !== null && r.expires_at !== undefined ? Number(r.expires_at) : undefined,
+            dispatchStatus: r.dispatch_status,
+            payload: typeof r.payload_json === "string" ? JSON.parse(r.payload_json) : r.payload_json,
+            createdAt: Number(r.created_at),
+            claimedBy: r.claimed_by !== null && r.claimed_by !== undefined ? r.claimed_by : undefined,
+            claimedAt: r.claimed_at !== null && r.claimed_at !== undefined ? Number(r.claimed_at) : undefined,
+        }));
+        // Refresh the mirror so subsequent sync reads see the claim.
+        for (const row of out)
+            this.memory.upsertScheduledDispatch(row);
+        out.sort((a, b) => a.scheduledAt - b.scheduledAt);
+        return out;
+    }
+    /**
+     * Sync wrapper required by the `RunStore` interface. PG's claim API
+     * is fundamentally async (network round-trip); the sync wrapper
+     * returns the LAST snapshot from the in-memory mirror.
+     *
+     * **For cross-process correctness, callers MUST use
+     * `claimDispatchesAsync()` directly.** The sync wrapper exists so
+     * the interface contract is satisfied for sqlite + in-memory
+     * callers; PG users opt into the async path via the trigger's
+     * recovery code (`HttpTrigger.recoverDispatches()` calls the
+     * async version when the store is a `PostgresRunStore`).
+     */
+    claimDispatches(processId, leaseMs, now, opts) {
+        // Fire the async claim; return whatever the mirror has right now
+        // (won't include rows claimed in this call until the async query
+        // resolves and refreshes the mirror).
+        void this.claimDispatchesAsync(processId, leaseMs, now, opts);
+        return this.memory.claimDispatches(processId, leaseMs, now, opts);
+    }
+    heartbeatClaims(processId, now) {
+        const count = this.memory.heartbeatClaims(processId, now);
+        this.enqueueWrite(() => this.pool
+            .query("UPDATE scheduled_dispatches SET claimed_at = $1 WHERE claimed_by = $2", [now, processId])
+            .then(() => { }));
+        return count;
+    }
+    releaseClaim(runId) {
+        const removed = this.memory.releaseClaim(runId);
+        this.enqueueWrite(() => this.pool
+            .query("UPDATE scheduled_dispatches SET claimed_by = NULL, claimed_at = NULL WHERE run_id = $1 AND claimed_by IS NOT NULL", [runId])
+            .then(() => { }));
+        return removed;
+    }
+    deleteScheduledDispatch(runId) {
+        const removed = this.memory.deleteScheduledDispatch(runId);
+        this.enqueueWrite(() => this.pool.query("DELETE FROM scheduled_dispatches WHERE run_id = $1", [runId]).then(() => { }));
+        return removed;
+    }
+    getScheduledDispatches(opts) {
+        return this.memory.getScheduledDispatches(opts);
+    }
+    purgeExpiredScheduledDispatches(now) {
+        const removed = this.memory.purgeExpiredScheduledDispatches(now);
+        this.enqueueWrite(() => this.pool
+            .query("DELETE FROM scheduled_dispatches WHERE expires_at IS NOT NULL AND expires_at < $1", [now])
+            .then(() => { }));
+        return removed;
+    }
     // === Write Queue ===
     enqueueWrite(fn) {
         if (this.closed)
@@ -565,9 +1228,25 @@ export class PostgresRunStore {
             metadata: row.metadata_json ? parseJson(row.metadata_json) : undefined,
             nodeCount: Number(row.node_count),
             completedNodes: Number(row.completed_nodes),
+            // PR 1-5 polish · pre-v5 PG rows have NULL on the columns added
+            // by migration v5. Mirror sqlite's `rowToRun`: NULL `environment`
+            // reads as "production" (the legacy default scope) so historical
+            // data still surfaces under the EnvChip default. Every other new
+            // column maps NULL → undefined.
+            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 != null ? Number(row.scheduled_at) : undefined,
+            expiresAt: row.expires_at != null ? Number(row.expires_at) : undefined,
+            debounceKey: row.debounce_key ?? undefined,
+            debounceMode: (row.debounce_mode ?? undefined),
+            pingCount: row.ping_count != null ? Number(row.ping_count) : undefined,
+            lastCompletedStepIndex: row.last_completed_step_index != null ? Number(row.last_completed_step_index) : undefined,
         };
     }
     rowToNodeRun(row) {
+        const flags = (row.flags_json ? parseJson(row.flags_json) : undefined);
         return {
             id: row.id,
             runId: row.run_id,
@@ -585,6 +1264,11 @@ export class PostgresRunStore {
             depth: Number(row.depth),
             stepIndex: Number(row.step_index),
             metrics: row.metrics_json ? parseJson(row.metrics_json) : undefined,
+            wait: flags?.wait,
+            dispatch: flags?.dispatch,
+            subworkflowDepth: flags?.subworkflowDepth,
+            middleware: flags?.middleware,
+            iterationIndex: flags?.iterationIndex,
         };
     }
     rowToEvent(row) {
@@ -637,4 +1321,25 @@ function parseJson(value) {
     }
     return value;
 }
+/**
+ * Serialize the in-memory NodeRun flag bag for the `flags_json` JSONB
+ * column. Mirrors `encodeNodeRunFlags` in SqliteRunStore. Returns null
+ * when no flags are set so the column stays NULL on the common case.
+ */
+function encodeNodeRunFlagsForPg(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;
+    if (Object.keys(flags).length === 0)
+        return null;
+    return JSON.stringify(flags);
+}
 //# sourceMappingURL=PostgresRunStore.js.map