@blokjs/runner 0.2.2 → 0.6.0

package/dist/tracing/TraceRouter.js

@@ -1,5 +1,191 @@
 import http from "node:http";
+import { DebounceCoordinator } from "../scheduling/DebounceCoordinator";
+import { DeferredRunScheduler } from "../scheduling/DeferredRunScheduler";
+import { WorkflowRegistry } from "../workflow/WorkflowRegistry";
+import { inferSampleBody } from "../workflow/sampleBody";
+import { RoutingDiagnostics } from "./RoutingDiagnostics";
 import { RunTracker } from "./RunTracker";
+import { METADATA_OPERATORS, isValidMetadataKey } from "./metadataFilter";
+/**
+ * Security review FW-2 — sensitive headers that are NEVER honored when
+ * supplied via the replay endpoint's `overrides.headers`. Combined with
+ * the FW-1 trace-auth gate, this blocks the replay-as-auth-bypass attack
+ * where an unauthenticated client posts to `/__blok/runs/:id/replay`
+ * with an attacker-controlled `Authorization` header that the runner
+ * would otherwise dispatch verbatim to the user-authored route.
+ */
+const REPLAY_HEADER_DENYLIST = new Set([
+    "authorization",
+    "cookie",
+    "set-cookie",
+    "x-api-key",
+    "x-auth-token",
+    "proxy-authorization",
+]);
+function filterReplayHeaders(headers) {
+    if (!headers)
+        return {};
+    const filtered = {};
+    for (const [k, v] of Object.entries(headers)) {
+        if (REPLAY_HEADER_DENYLIST.has(k.toLowerCase()))
+            continue;
+        filtered[k] = v;
+    }
+    return filtered;
+}
+/**
+ * Coerce a query-string `?limit=...` / `?offset=...` value to a clamped
+ * integer. Strings parse via `Number.parseInt`; anything non-finite (or
+ * outside `[min, max]`) falls back to `fallback`. Used by paginated GET
+ * endpoints so Studio queries can't pin the event loop with absurd
+ * window sizes.
+ */
+function clampInt(raw, min, max, fallback) {
+    if (typeof raw !== "string" || raw.length === 0)
+        return fallback;
+    const n = Number.parseInt(raw, 10);
+    if (!Number.isFinite(n) || Number.isNaN(n))
+        return fallback;
+    if (n < min)
+        return min;
+    if (n > max)
+        return max;
+    return n;
+}
+/**
+ * F2 (v0.5) — parse `metadata.<key>[__op]=<value>` query params into
+ * the operator-aware `MetadataFilter[]` shape.
+ *
+ * Supported suffixes (`__op`): `eq` (default), `ne`, `gt`, `gte`,
+ * `lt`, `lte`, `like`, `in`, `nin`. Unknown suffixes silently drop —
+ * preserves the v0.4 contract that unrecognised query keys are ignored
+ * rather than rejected (operators got the same treatment as the v0.4
+ * key-shape validation).
+ *
+ * `in` / `nin` values are comma-split:
+ *   `metadata.region__in=us,eu,ap` → value: ["us", "eu", "ap"]
+ *
+ * Keys outside `^[a-zA-Z0-9_-]+$` silently drop — same SQL-injection
+ * guard the v0.4 parser already applied.
+ */
+function parseMetadataFiltersFromQuery(query) {
+    let filters;
+    const opSet = new Set(METADATA_OPERATORS);
+    for (const [rawKey, value] of Object.entries(query)) {
+        if (!rawKey.startsWith("metadata."))
+            continue;
+        if (typeof value !== "string" || value.length === 0)
+            continue;
+        const remainder = rawKey.slice("metadata.".length);
+        if (remainder.length === 0)
+            continue;
+        // Suffix split — accepts `key`, `key__op`. Multiple `__` in a
+        // key name are tolerated; only the FINAL `__op` is interpreted
+        // as the operator when it matches the operator set.
+        const opIdx = remainder.lastIndexOf("__");
+        let metaKey;
+        let op;
+        if (opIdx > 0 && opSet.has(remainder.slice(opIdx + 2))) {
+            metaKey = remainder.slice(0, opIdx);
+            op = remainder.slice(opIdx + 2);
+        }
+        else {
+            metaKey = remainder;
+            op = "eq";
+        }
+        if (!isValidMetadataKey(metaKey))
+            continue;
+        const parsedValue = op === "in" || op === "nin"
+            ? value
+                .split(",")
+                .map((s) => s.trim())
+                .filter((s) => s.length > 0)
+            : value;
+        if (Array.isArray(parsedValue) && parsedValue.length === 0)
+            continue;
+        if (!filters)
+            filters = [];
+        filters.push({ key: metaKey, op, value: parsedValue });
+    }
+    return filters;
+}
+/**
+ * Strip sensitive request headers from a scheduled-dispatch payload
+ * before serving it to Studio. `extractDispatchPayload` already strips
+ * these at PERSIST time (see `HttpTrigger.extractDispatchPayload`); we
+ * re-apply the denylist on read as a belt-and-braces guard against
+ * older sqlite rows that pre-date that strip path.
+ */
+function sanitizeDispatchPayload(payload) {
+    if (!payload || typeof payload !== "object" || Array.isArray(payload))
+        return payload;
+    const obj = payload;
+    const headers = obj.headers;
+    if (!headers || typeof headers !== "object" || Array.isArray(headers))
+        return payload;
+    const filtered = {};
+    for (const [k, v] of Object.entries(headers)) {
+        if (REPLAY_HEADER_DENYLIST.has(k.toLowerCase()))
+            continue;
+        filtered[k] = v;
+    }
+    return { ...obj, headers: filtered };
+}
+/**
+ * Synthesize a zero-stat `WorkflowSummary` from a `WorkflowRegistry`
+ * entry that has never run. Studio's sidebar consumes `/__blok/workflows`,
+ * so without this merge a workflow that's registered + bound to a URL
+ * but hasn't been triggered yet is invisible to the operator — they
+ * have no row to click into, can't open the Graph tab, and (the bug
+ * that motivated this) can't even tell the workflow exists.
+ *
+ * Returns `null` for middleware-only workflows (`isMiddleware: true`)
+ * and for entries without a recognised trigger kind — both are
+ * non-user-facing.
+ */
+function synthesizeRegistryOnlySummary(reg) {
+    if (reg.isMiddleware)
+        return null;
+    const wf = reg.workflow;
+    if (!wf || typeof wf !== "object")
+        return null;
+    const trigger = wf.trigger;
+    if (!trigger || typeof trigger !== "object")
+        return null;
+    const triggerTypes = [];
+    let primaryPath;
+    for (const [kind, raw] of Object.entries(trigger)) {
+        if (!raw || typeof raw !== "object")
+            continue;
+        triggerTypes.push(kind);
+        if (primaryPath !== undefined)
+            continue;
+        // Pick the first identifying field that exists. Mirrors the
+        // `workflow_path` column the SQL summaries return — that's the
+        // runtime-set URL, here we approximate with the trigger config.
+        const r = raw;
+        if (typeof r.path === "string")
+            primaryPath = r.path;
+        else if (typeof r.queue === "string")
+            primaryPath = r.queue;
+        else if (typeof r.schedule === "string")
+            primaryPath = r.schedule;
+        else if (typeof r.topic === "string")
+            primaryPath = r.topic;
+    }
+    if (triggerTypes.length === 0)
+        return null;
+    return {
+        name: reg.name,
+        path: primaryPath ?? "/",
+        triggerTypes,
+        totalRuns: 0,
+        recentRuns: 0,
+        errorRate: 0,
+        avgDurationMs: 0,
+        p95DurationMs: 0,
+    };
+}
 /**
  * Register trace API routes on an Express-compatible router.
  *
@@ -12,22 +198,64 @@ import { RunTracker } from "./RunTracker";
  * import { Router } from "express";
  * import { registerTraceRoutes } from "@blokjs/runner";
  * const traceRouter = Router();
- * registerTraceRoutes(traceRouter);
+ * registerTraceRoutes(traceRouter, undefined, { authorize: myAuthFn });
  * app.use("/__blok", traceRouter);
  * ```
  */
-export function registerTraceRoutes(router, tracker) {
+export function registerTraceRoutes(router, tracker, options) {
     const t = tracker || RunTracker.getInstance();
     // --- CORS for cross-origin Studio UI ---
+    // Security review FW-4 — `BLOK_TRACE_CORS_ORIGIN` overrides the
+    // permissive `*` default. Set to a single allow-listed origin in
+    // production to prevent cross-origin reads of trace data.
+    const corsOrigin = process.env.BLOK_TRACE_CORS_ORIGIN || "*";
+    // Security review FW-1 — production-default-deny on /__blok/* unless
+    // the operator either registers an authorize hook (preferred) or
+    // explicitly opts out via BLOK_TRACE_AUTH_DISABLED=1.
+    const isProd = process.env.BLOK_ENV === "production" || process.env.NODE_ENV === "production";
+    const authDisabled = process.env.BLOK_TRACE_AUTH_DISABLED === "1";
+    const authorize = options?.authorize;
     router.use((req, res, next) => {
-        res.setHeader("Access-Control-Allow-Origin", "*");
+        res.setHeader("Access-Control-Allow-Origin", corsOrigin);
         res.setHeader("Access-Control-Allow-Methods", "GET, POST, DELETE, OPTIONS");
         res.setHeader("Access-Control-Allow-Headers", "Content-Type, Last-Event-ID");
         if (req.method === "OPTIONS") {
             res.sendStatus(204);
             return;
         }
-        next();
+        // Dev OR explicit opt-out → pass through (preserves previous behaviour).
+        if (!isProd || authDisabled) {
+            next();
+            return;
+        }
+        // Production WITHOUT an authorize hook → 503 with a hint.
+        if (!authorize) {
+            res.status(503).json({
+                error: "Trace endpoints require auth in production",
+                hint: "Register an authorize hook before listen() — `trigger.setTraceAuth(req => ...)` — or set BLOK_TRACE_AUTH_DISABLED=1 to opt out (typically because /__blok/* is already firewalled).",
+                docs: "https://github.com/deskree-inc/blok/blob/main/docs/d/security/cookbook.mdx#secure-the-trace-api-and-studio",
+            });
+            return;
+        }
+        // Production WITH an authorize hook → consult it. Wrap in
+        // `Promise.resolve().then(...)` so a SYNC throw inside the
+        // authorize function is caught the same as an async rejection.
+        Promise.resolve()
+            .then(() => authorize(req))
+            .then((ok) => {
+            if (ok) {
+                next();
+            }
+            else {
+                res.status(401).json({ error: "Unauthorized" });
+            }
+        })
+            .catch((err) => {
+            // Don't leak the underlying error message — log it once,
+            // return a generic 401.
+            console.error("[blok][trace-auth] authorize() threw:", err?.message ?? err);
+            res.status(401).json({ error: "Unauthorized" });
+        });
     });
     // === Utility Endpoints ===
     router.get("/health", (_req, res) => {
@@ -47,12 +275,43 @@ export function registerTraceRoutes(router, tracker) {
     // === Workflow Endpoints ===
     router.get("/workflows", (_req, res) => {
         const summaries = t.getWorkflowSummaries();
+        // E4 follow-up — `getWorkflowSummaries()` derives only from the
+        // `workflow_runs` table, so workflows that have been registered
+        // but never run don't show up. Studio uses this endpoint to power
+        // the sidebar; without merging the registry the user has no way
+        // to navigate to a workflow before it executes, including no way
+        // to see its static DAG. Synthesize a zero-stat summary for
+        // every registered workflow not already present.
+        const seen = new Set(summaries.map((s) => s.name));
+        for (const reg of WorkflowRegistry.getInstance().list()) {
+            if (seen.has(reg.name))
+                continue;
+            const synthesized = synthesizeRegistryOnlySummary(reg);
+            if (synthesized)
+                summaries.push(synthesized);
+        }
         res.json(summaries);
     });
     router.get("/workflows/:name", (req, res) => {
         const { name } = req.params;
         const summaries = t.getWorkflowSummaries();
-        const summary = summaries.find((s) => s.name === name);
+        let summary = summaries.find((s) => s.name === name);
+        // E4 — surface the raw workflow JSON (pre-normalization) from
+        // the registry so Studio can render the static DAG. Triggers
+        // feed the registry at boot; if the workflow was registered
+        // inline (e.g. tests with no source file) it's still here.
+        const registered = WorkflowRegistry.getInstance().get(name);
+        // Sidebar follow-up (#99) — if the workflow is registered but
+        // has never run, `getWorkflowSummaries()` won't return a row
+        // for it (SQL aggregation derives from `workflow_runs`). Fall
+        // back to a synthesized zero-stat summary so Studio's detail
+        // page renders + the Graph tab AND the empty-state curl example
+        // are reachable on first sight.
+        if (!summary && registered) {
+            const synthesized = synthesizeRegistryOnlySummary(registered);
+            if (synthesized)
+                summary = synthesized;
+        }
         if (!summary) {
             res.status(404).json({ error: `Workflow '${name}' not found` });
             return;
@@ -69,12 +328,70 @@ export function registerTraceRoutes(router, tracker) {
                     runtimes.add(node.runtimeKind);
             }
         }
+        // Sample-body resolution. Priority (highest first):
+        //   1. Author override: `trigger.http.examples.body` in the
+        //      workflow JSON (#100). Source of truth — never overridden.
+        //   2. Recorded sample: captured from the first successful run
+        //      when `trigger.http.recordSample: true` (option C / v0.6).
+        //      Real-world body that exercised the workflow.
+        //   3. Static inference: walk step references for
+        //      `ctx.request.body.<path>` (#100). Heuristic placeholder.
+        //   4. Empty `{}` — fallback when nothing else exists.
+        // The `inferSampleBody()` helper already handles #1 vs #3; we
+        // slot the recorded sample in between by overriding the `source`
+        // + `body` when one exists AND the helper didn't fall through to
+        // an author override.
+        const inferred = registered?.workflow ? inferSampleBody(registered.workflow) : null;
+        const recorded = t.getWorkflowSample(name);
+        let examples;
+        if (inferred?.source === "author") {
+            examples = { body: inferred.body, source: "author" };
+        }
+        else if (recorded) {
+            examples = { body: recorded.body, source: "recorded" };
+        }
+        else if (inferred) {
+            examples = { body: inferred.body, source: inferred.source };
+        }
         res.json({
             ...summary,
             nodeNames: Array.from(nodeNames),
             runtimes: Array.from(runtimes),
+            definition: registered?.workflow,
+            examples,
         });
     });
+    // E4 follow-up — surface boot-time route-build errors (collisions,
+    // missing paths) so Studio can render a banner on the Workflows page
+    // rather than burying the issue in terminal logs. The trigger
+    // populates `RoutingDiagnostics` at boot via `buildRouteTable` in
+    // tolerant mode.
+    router.get("/routing", (_req, res) => {
+        const diagnostics = RoutingDiagnostics.getInstance();
+        res.json({
+            diagnostics: diagnostics.list(),
+            count: diagnostics.count(),
+            now: Date.now(),
+        });
+    });
+    // #103 follow-up — operator-facing escape hatch for the
+    // first-record-wins semantic. When the captured body is wrong / stale
+    // / contains a one-off payload, deleting the sample lets the next
+    // successful run re-record (only if the workflow's HTTP trigger has
+    // `recordSample: true`). Studio's workflow detail page wires a
+    // "Re-record sample" button to this endpoint. Returns `{ deleted:
+    // true }` on success, `404` when no sample exists for the workflow.
+    // JSON-rather-than-204 keeps `fetchJson()` on the client side simple
+    // and mirrors the saved-filters DELETE shape.
+    router.delete("/workflows/:name/sample", (req, res) => {
+        const { name } = req.params;
+        const removed = t.deleteWorkflowSample(name);
+        if (!removed) {
+            res.status(404).json({ error: `No recorded sample for workflow '${name}'` });
+            return;
+        }
+        res.json({ deleted: true });
+    });
     router.get("/workflows/:name/runs", (req, res) => {
         const { name } = req.params;
         const status = req.query.status;
@@ -489,6 +806,21 @@ export function registerTraceRoutes(router, tracker) {
         const workflow = req.query.workflow;
         const status = req.query.status;
         const tags = req.query.tags ? req.query.tags.split(",").map((t) => t.trim()) : undefined;
+        // F2 (v0.5) — `metadata.<key>[__op]=<value>` query params parsed
+        // into a `MetadataFilter[]` for the RunQuery filter. Multiple
+        // pairs combine with AND semantics.
+        //
+        // Examples:
+        //   metadata.tier=premium             → {key: "tier", op: "eq", value: "premium"}
+        //   metadata.tier__ne=free            → {key: "tier", op: "ne", value: "free"}
+        //   metadata.count__gt=10             → {key: "count", op: "gt", value: "10"}
+        //   metadata.region__in=us,eu         → {key: "region", op: "in", value: ["us","eu"]}
+        //   metadata.name__like=test%         → {key: "name", op: "like", value: "test%"}
+        //
+        // Keys are restricted by the SqliteRunStore implementation
+        // (`/^[a-zA-Z0-9_-]+$/`) for JSON path safety; non-matching keys
+        // or unknown operators silently drop.
+        const metadata = parseMetadataFiltersFromQuery(req.query);
         const limit = Number.parseInt(req.query.limit || "50", 10);
         const offset = Number.parseInt(req.query.offset || "0", 10);
         const sort = req.query.sort || "desc";
@@ -520,6 +852,7 @@ export function registerTraceRoutes(router, tracker) {
             workflow,
             status: status,
             tags,
+            metadata,
             limit: needsPostFilter ? Math.max(limit, 1000) : limit,
             offset: needsPostFilter ? 0 : offset,
             sort,
@@ -570,6 +903,21 @@ export function registerTraceRoutes(router, tracker) {
         const events = t.getEvents(runId, since);
         res.json(events);
     });
+    /**
+     * Tier 2 · sub-workflow lineage. Returns the runs that were started
+     * by `subworkflow:` steps inside the given parent run. Studio renders
+     * these as a "Sub-runs" list on the parent's run detail page.
+     */
+    router.get("/runs/:runId/subruns", (req, res) => {
+        const { runId } = req.params;
+        const run = t.getRun(runId);
+        if (!run) {
+            res.status(404).json({ error: `Run '${runId}' not found` });
+            return;
+        }
+        const subruns = t.getRunsByParent(runId);
+        res.json(subruns);
+    });
     router.delete("/runs", (_req, res) => {
         const deleted = t.clearAll();
         res.json({ deleted });
@@ -602,9 +950,18 @@ export function registerTraceRoutes(router, tracker) {
         const overrides = (req.body || {});
         const finalMethod = (overrides.method || method).toUpperCase();
         const finalUrl = overrides.path ? `${protocol}://${host}${overrides.path}` : url;
+        // Security review FW-2 — strip sensitive headers from overrides
+        // BEFORE merging, then layer the framework-controlled headers
+        // LAST so an attacker can't replace `X-Blok-Replay-Of`.
+        const safeOverrideHeaders = filterReplayHeaders(overrides.headers);
         const customHeaders = {
             "Content-Type": "application/json",
-            ...(overrides.headers || {}),
+            ...safeOverrideHeaders,
+            // Tier 1 · replay lineage. TriggerBase reads this header and threads
+            // it into `tracker.startRun({ replayOf })`, which persists onto the
+            // new run's WorkflowRun.replayOf field. Studio renders a
+            // "Replay of #..." breadcrumb that links back to the source run.
+            "X-Blok-Replay-Of": runId,
         };
         const body = overrides.body !== undefined ? JSON.stringify(overrides.body) : undefined;
         // Listen for the next RUN_STARTED event matching this workflow
@@ -624,6 +981,10 @@ export function registerTraceRoutes(router, tracker) {
                 newRunId: event.runId,
                 originalRunId: runId,
                 workflowName: run.workflowName,
+                // Tier 1 · explicit lineage in the API response so Studio
+                // doesn't have to fetch the new run separately to confirm
+                // the replay relationship.
+                replayOf: runId,
             });
         };
         t.on("RUN_STARTED", onRunStarted);
@@ -656,6 +1017,200 @@ export function registerTraceRoutes(router, tracker) {
         // Cleanup if client disconnects
         req.on("close", cleanup);
     });
+    // === Concurrency observability (Tier 2 follow-up) ===
+    /**
+     * Concurrency backend health probe. Returns the configured backend
+     * (`"in-process"` when none) and basic state. Useful for k8s-style
+     * health checks AND Studio's "Backend status" tile.
+     *
+     * GET /__blok/concurrency/health
+     */
+    router.get("/concurrency/health", (_req, res) => {
+        const backend = t.getConcurrencyBackend();
+        res.json({
+            backend: backend?.name ?? "in-process",
+            disabled: process.env.BLOK_CONCURRENCY_DISABLED === "1",
+            leaseMs: process.env.BLOK_CONCURRENCY_LEASE_MS ? Number(process.env.BLOK_CONCURRENCY_LEASE_MS) : 60 * 60 * 1000,
+        });
+    });
+    /**
+     * Snapshot of currently in-flight concurrency slots, grouped by
+     * (workflowName, concurrencyKey) bucket. Powers Studio's per-key
+     * in-flight tile.
+     *
+     * GET /__blok/concurrency/state
+     */
+    router.get("/concurrency/state", (_req, res) => {
+        const buckets = t.getStore().getConcurrencySnapshot(Date.now());
+        const totalLeases = buckets.reduce((sum, b) => sum + b.leases.length, 0);
+        res.json({
+            totalBuckets: buckets.length,
+            totalLeases,
+            buckets: buckets.map((b) => ({
+                workflowName: b.workflowName,
+                concurrencyKey: b.concurrencyKey,
+                inFlight: b.leases.length,
+                leases: b.leases,
+            })),
+        });
+    });
+    /**
+     * List pending scheduled dispatches — rows from `scheduled_dispatches`
+     * that haven't fired yet (delayed / queued / debounced). Powers
+     * Studio's "Scheduled runs" view (E1) so operators can see + cancel
+     * inbound dispatches BEFORE they execute.
+     *
+     * Already-fired runs are pruned from this table the moment
+     * `dispatchDeferred` re-enters; expired runs are pruned by the
+     * Janitor sweep. To see those, use `/__blok/runs?status=expired` /
+     * `?status=completed` / etc. against `workflow_runs`.
+     *
+     * GET /__blok/scheduled
+     *
+     * Query params:
+     *   - `status` — comma-separated list of `delayed`/`queued`/`debounced`.
+     *     When omitted, returns all three.
+     *   - `workflowName` — exact-match filter.
+     *   - `limit` — pagination cap (default 100, max 500).
+     *   - `offset` — pagination offset (default 0).
+     *
+     * Returns:
+     *   `{ rows: ScheduledDispatchRow[], total: number, now: number }`
+     *   `now` is the server-side `Date.now()` snapshot so the client can
+     *   render accurate "fires in 27s" countdowns without clock skew.
+     */
+    router.get("/scheduled", (req, res) => {
+        const query = (req.query ?? {});
+        const validStatuses = new Set(["delayed", "queued", "debounced"]);
+        const requestedStatuses = (query.status ?? "")
+            .split(",")
+            .map((s) => s.trim())
+            .filter((s) => s.length > 0 && validStatuses.has(s));
+        const statusesToReturn = requestedStatuses.length > 0 ? requestedStatuses : ["delayed", "queued", "debounced"];
+        // Pull each requested status separately — the underlying
+        // `getScheduledDispatches({status})` only accepts a single status
+        // string. Concatenate + sort by scheduledAt ASC so the soonest
+        // next-fire is at the top of the table.
+        const store = t.getStore();
+        const allRows = statusesToReturn.flatMap((status) => store.getScheduledDispatches({ status: status }));
+        const workflowFilter = typeof query.workflowName === "string" ? query.workflowName : undefined;
+        const filtered = workflowFilter ? allRows.filter((r) => r.workflowName === workflowFilter) : allRows;
+        filtered.sort((a, b) => a.scheduledAt - b.scheduledAt);
+        // Pagination — the underlying store does full scans today; cap at
+        // 500 so a runaway query can't pin the event loop.
+        const limit = clampInt(query.limit, 1, 500, 100);
+        const offset = clampInt(query.offset, 0, Number.MAX_SAFE_INTEGER, 0);
+        const page = filtered.slice(offset, offset + limit);
+        // Sensitive headers are already stripped at persist time
+        // (see `extractDispatchPayload` in HttpTrigger). Re-strip on read
+        // too as a belt-and-braces measure — operators should never see
+        // `authorization` / `cookie` / `x-api-key` in the Studio UI.
+        const sanitized = page.map((row) => ({ ...row, payload: sanitizeDispatchPayload(row.payload) }));
+        res.json({
+            rows: sanitized,
+            total: filtered.length,
+            now: Date.now(),
+        });
+    });
+    // === Cancellation (Tier 2 polish) ===
+    /**
+     * Cancel a pending (delayed/debounced/queued) run before it executes.
+     *
+     * `POST /__blok/runs/:runId/cancel`
+     *
+     * Returns:
+     * - `200 { cancelled: true, runId, previousStatus, newStatus: "cancelled" }` on success
+     * - `400 { error }` when the run isn't in a cancellable state
+     *   (running/completed/failed/throttled/expired/crashed/timedOut/cancelled)
+     * - `404 { error }` when the runId doesn't exist
+     *
+     * Cancels the underlying scheduler entry (`DeferredRunScheduler` for
+     * delayed/queued runs; `DebounceCoordinator` for debounced trailing-mode
+     * runs) AND flips the run's status to `"cancelled"` via
+     * `tracker.cancelRun(runId)`. Both scheduler `.cancel()` methods are
+     * idempotent so calling them on a runId that doesn't have a pending
+     * timer is a safe no-op.
+     */
+    router.post("/runs/:runId/cancel", (req, res) => {
+        const { runId } = req.params;
+        const run = t.getRun(runId);
+        if (!run) {
+            res.status(404).json({ error: `Run '${runId}' not found` });
+            return;
+        }
+        // Tier 2 follow-up · "running" added so cooperative AbortSignal
+        // cancellation can flip in-flight runs to `cancelled` via
+        // `tracker.abortRunningRun(runId)`. Other terminal states
+        // (completed/failed/throttled/expired/crashed/timedOut) remain
+        // non-cancellable.
+        const cancellable = ["delayed", "debounced", "queued", "running"];
+        if (!cancellable.includes(run.status)) {
+            res.status(400).json({
+                error: `Cannot cancel run in '${run.status}' state. Only runs in 'delayed', 'debounced', 'queued', or 'running' state can be cancelled.`,
+                runId,
+                status: run.status,
+            });
+            return;
+        }
+        // Capture previousStatus BEFORE cancelRun mutates the run record.
+        const previousStatus = run.status;
+        // Tier 2 follow-up · running runs use cooperative AbortSignal.
+        // `abortRunningRun` fires the controller AND flips status via
+        // cancelRun in one atomic-feeling call. Returns 200 — the
+        // in-flight step's between-step check will throw shortly.
+        if (run.status === "running") {
+            const aborted = t.abortRunningRun(runId);
+            if (!aborted) {
+                // No registered controller — likely a stale state where
+                // the run is mid-finalization. Still return success since
+                // the run is on its way to terminal anyway.
+                res.json({
+                    cancelled: true,
+                    runId,
+                    previousStatus,
+                    newStatus: "cancelled",
+                    note: "No active AbortController; run will reach terminal state naturally.",
+                });
+                return;
+            }
+            res.json({
+                cancelled: true,
+                runId,
+                previousStatus,
+                newStatus: "cancelled",
+                note: "Cancellation initiated via AbortSignal; in-flight step will abort cooperatively.",
+            });
+            return;
+        }
+        // Best-effort scheduler cleanup (both methods are idempotent).
+        DeferredRunScheduler.getInstance().cancel(runId);
+        if (run.debounceKey) {
+            // Tier C #1 — `cancel()` is now async because the coordinator may
+            // route through a cross-process backend. Fire-and-forget: the
+            // HTTP response shouldn't block on broker cleanup, and the
+            // run-status flip below is the source of truth for the caller.
+            void DebounceCoordinator.getInstance()
+                .cancel(run.workflowName, run.debounceKey)
+                .catch((err) => {
+                console.warn(`[blok][scheduling] debounce cancel failed for ${run.workflowName}:${run.debounceKey}: ${err instanceof Error ? err.message : String(err)}`);
+            });
+        }
+        const cancelled = t.cancelRun(runId);
+        if (!cancelled) {
+            // Race: status changed between our check and the call.
+            res.status(409).json({
+                error: `Could not cancel run '${runId}'. It may have just transitioned to a non-cancellable state.`,
+                runId,
+            });
+            return;
+        }
+        res.json({
+            cancelled: true,
+            runId,
+            previousStatus,
+            newStatus: "cancelled",
+        });
+    });
     // === AI Error Explanation ===
     /**
      * Explain a run or node error using an LLM.
@@ -841,6 +1396,57 @@ export function registerTraceRoutes(router, tracker) {
         t.saveDashboard(copy);
         res.status(201).json(copy);
     });
+    // === Saved filters (E2) ===
+    /**
+     * List every saved filter. Newest-updated first so the dropdown
+     * surfaces recently-edited presets at the top.
+     * GET /__blok/saved-filters
+     */
+    router.get("/saved-filters", (_req, res) => {
+        res.json({ filters: t.listSavedFilters() });
+    });
+    /**
+     * Upsert a saved filter. `name` is the unique key — re-posting with
+     * the same name overwrites the existing entry (preserves `id` +
+     * `createdAt`). Studio uses this to replace the localStorage
+     * `saveFilter()` call.
+     * POST /__blok/saved-filters
+     * Body: { name, status, tagsInput, metadataInput }
+     */
+    router.post("/saved-filters", (req, res) => {
+        const body = (req.body || {});
+        const name = typeof body.name === "string" ? body.name.trim() : "";
+        if (name.length === 0) {
+            res.status(400).json({ error: "Saved-filter `name` is required" });
+            return;
+        }
+        const now = Date.now();
+        const persisted = t.upsertSavedFilter({
+            id: `sf_${now.toString(36)}_${Math.random().toString(36).slice(2, 8)}`,
+            name,
+            status: typeof body.status === "string" ? body.status : "",
+            tagsInput: typeof body.tagsInput === "string" ? body.tagsInput : "",
+            metadataInput: typeof body.metadataInput === "string" ? body.metadataInput : "",
+            createdAt: now,
+            updatedAt: now,
+        });
+        res.status(201).json(persisted);
+    });
+    /**
+     * Delete a saved filter by name. Returns `404` when the row didn't
+     * exist (so the Studio mutation can disambiguate). Uses the name
+     * (not the id) so the Studio component — which knows the name from
+     * the dropdown — doesn't need a round-trip to learn the id first.
+     * DELETE /__blok/saved-filters/:name
+     */
+    router.delete("/saved-filters/:name", (req, res) => {
+        const removed = t.deleteSavedFilter(req.params.name);
+        if (!removed) {
+            res.status(404).json({ error: `Saved filter '${req.params.name}' not found` });
+            return;
+        }
+        res.json({ deleted: true });
+    });
     // === SSE Endpoints ===
     /**
      * SSE stream for a specific run.