@blokjs/runner 0.2.2 → 0.6.0

package/dist/tracing/types.d.ts

@@ -1,4 +1,37 @@
-export type WorkflowRunStatus = "pending" | "running" | "completed" | "failed" | "cancelled";
+/**
+ * Lifecycle status of a workflow run.
+ *
+ * - `pending`: created but not yet started.
+ * - `running`: currently executing.
+ * - `completed`: finished successfully.
+ * - `failed`: a step threw or the run aborted with an error.
+ * - `cancelled`: stopped externally before completion.
+ * - `throttled` (Tier 2 #6): rejected at run-entry because the
+ *   concurrency limit for the resolved `concurrencyKey` was reached.
+ *   Distinct from `failed` — no step ran; nothing produced an error.
+ * - `delayed` (Tier 2 #5): scheduled to start at a future time. The
+ *   run record exists; the dispatch is pending. Transitions to
+ *   `running` when the timer fires.
+ * - `expired` (Tier 2 #5): TTL exceeded before dispatch. Auto-cancelled
+ *   without execution. Distinct from `cancelled` (which is operator-
+ *   initiated) and `failed` (which implies a step ran).
+ * - `debounced` (Tier 2 #7): coalesced into another run via the
+ *   `debounce.key` mechanism. The "loser" of a leading-mode coalesce;
+ *   in trailing mode this state is transient (run flips to `running`
+ *   when the debounce timer fires).
+ * - `crashed` (Tier 2 quick-wins): the runner itself crashed (uncaught
+ *   exception, OOM, signal). Distinct from `failed` (which implies a
+ *   step's `process()` threw cleanly). Currently MANUAL — call
+ *   `tracker.markRunCrashed(runId, {error})` from custom triggers /
+ *   ops harnesses. Auto-flip on uncaught TriggerBase errors is a
+ *   deferred follow-up.
+ * - `timedOut` (Tier 2 quick-wins): a step's final retry attempt
+ *   exceeded its `maxDuration` cap. Distinct from `failed` so SLA
+ *   dashboards can separate timeout-driven failures (network /
+ *   capacity) from logic failures (bugs). Auto-flipped by
+ *   `RunnerSteps` on final-attempt `StepTimeoutError`.
+ */
+export type WorkflowRunStatus = "pending" | "running" | "completed" | "failed" | "cancelled" | "throttled" | "delayed" | "expired" | "debounced" | "queued" | "crashed" | "timedOut";
 /**
  * Structured failure detail attached to a {@link WorkflowRun} or
  * {@link NodeRun}. When the failure source threw a typed `BlokError`
@@ -60,6 +93,107 @@ export interface WorkflowRun {
      * SQLite databases still work because the column is optional.
      */
     environment?: string;
+    /**
+     * Tier 1 · replay lineage. When this run was started via
+     * `POST /__blok/runs/:id/replay`, this carries the original run's id.
+     * Studio renders a "Replay of #..." breadcrumb that links back to the
+     * source run. Absent on first-class triggered runs.
+     *
+     * Plumbed end-to-end via the `X-Blok-Replay-Of` HTTP header that the
+     * replay endpoint sets on the dispatched request. TriggerBase reads
+     * the header and threads it into `tracker.startRun({ replayOf })`.
+     */
+    replayOf?: string;
+    /**
+     * Tier 2 · sub-workflow lineage. When this run was started by a
+     * `subworkflow:` step in another workflow, this carries the parent
+     * run's id. Studio renders a "called from #..." breadcrumb that
+     * links back to the parent run. Absent on first-class triggered runs.
+     */
+    parentRunId?: string;
+    /**
+     * Tier 2 · sub-workflow lineage. The specific NodeRun within the
+     * parent run that invoked this sub-workflow — lets Studio jump to
+     * the exact sub-workflow step on the parent's run-detail page.
+     */
+    parentNodeRunId?: string;
+    /**
+     * Tier 2 #5 · scheduled dispatch time (ms since epoch). Set when the
+     * run is created with `delay` on the trigger config, OR when the
+     * debounce coordinator parks a coalescing run. Absent on immediate
+     * runs.
+     */
+    scheduledAt?: number;
+    /**
+     * Tier 2 #5 · TTL deadline (ms since epoch). When `now > expiresAt`
+     * at dispatch time, the run is marked `expired` and skipped. Set
+     * from `trigger.ttl` plus the original submission timestamp. Absent
+     * when no TTL is configured.
+     */
+    expiresAt?: number;
+    /**
+     * Tier 2 #7 · resolved debounce key (`debounce.key` after
+     * `js/...`-expression evaluation). Pings sharing this key + workflow
+     * name coalesce into the same `WorkflowRun`. Absent on non-debounced
+     * runs.
+     */
+    debounceKey?: string;
+    /**
+     * Tier 2 #7 · debounce mode that produced this run. Surfaces in
+     * Studio's run detail so users can tell `leading` (immediate-fire)
+     * vs `trailing` (silence-then-fire) at a glance.
+     */
+    debounceMode?: "leading" | "trailing";
+    /**
+     * Tier 2 #7 · number of pings absorbed by this run before dispatch.
+     * Starts at 1 (the first ping). Subsequent same-key pings increment
+     * this rather than creating new run records. Surfaces on Studio's
+     * run row as "Pings: N".
+     */
+    pingCount?: number;
+    /**
+     * PR 4 · `wait.for(duration)` / `wait.until(date)` resume cursor.
+     *
+     * Set after each non-wait step completes. On
+     * `dispatchDeferred` re-entry from a wait step, the runner skips
+     * steps with `stepIndex <= lastCompletedStepIndex` to avoid
+     * re-running pre-wait steps. Undefined for runs that never
+     * encountered a wait step (preserves existing semantics).
+     */
+    lastCompletedStepIndex?: number;
+    /**
+     * v0.6 prerequisite for wait-inside-primitives Phase 2.
+     *
+     * JSON-serialized snapshot of `ctx.state` taken immediately before
+     * `RunnerSteps` throws `WaitDispatchRequest`. On `dispatchDeferred`
+     * re-entry — including the cross-process recovery path where the
+     * scheduler re-builds a fresh ctx from the persisted dispatch row —
+     * `TriggerBase.run` rehydrates `ctx.state` (and its `ctx.vars`
+     * alias) from this column so subsequent steps see the same
+     * pre-wait state regardless of process restart.
+     *
+     * Without this column, only the in-process timer-fire path would
+     * preserve state (state still lives on the original ctx). The
+     * cross-process path would resume with empty `ctx.state`, breaking
+     * Phase 2's iteration-state-persistence promise (a forEach
+     * iteration whose body fired the wait would lose its index, the
+     * loop's accumulator, etc.).
+     *
+     * Capped by `BLOK_STATE_SNAPSHOT_MAX_BYTES` (default 1MB,
+     * matching `BLOK_DISPATCH_PAYLOAD_MAX_BYTES`) — when the
+     * serialized state exceeds the cap, the runner logs a warning and
+     * skips the snapshot (the wait still defers; resumption is
+     * best-effort). Authors can opt out entirely via
+     * `BLOK_STATE_SNAPSHOT_DISABLED=1`. Sensitive keys aren't filtered
+     * here — the snapshot only persists what the workflow has already
+     * computed into `state`, so apply your own redaction in nodes that
+     * write secrets there.
+     *
+     * Undefined for runs that never threw `WaitDispatchRequest`, which
+     * is the vast majority. Persisted column is `state_snapshot`
+     * (sqlite migration v11).
+     */
+    stateSnapshot?: string;
 }
 export type NodeRunStatus = "pending" | "running" | "completed" | "failed" | "skipped";
 export interface NodeRun {
@@ -113,12 +247,369 @@ export interface NodeRun {
         /** Bytes received from the SDK in the response. */
         response_bytes?: number;
     };
+    /**
+     * Tier 1 idempotency cache lineage. Populated by `RunTracker.markNodeCached`
+     * when the step short-circuited via a cache hit instead of running. Studio
+     * renders a "CACHED" badge with a click-through to the source run/node.
+     * Absent on regular completed nodes.
+     */
+    cached?: {
+        sourceRunId: string;
+        sourceNodeRunId: string;
+        cachedAt: number;
+    };
+    /**
+     * Tier 1 retry attempts. One entry per `NODE_ATTEMPT_FAILED` event the
+     * step emitted before either succeeding or exhausting `retry.maxAttempts`.
+     * Capped at 10 entries (`MAX_STORED_ATTEMPTS`) — extreme retry counts
+     * are bounded so a runaway loop can't bloat the run store.
+     *
+     * Studio renders this as a collapsible "Attempts (N)" disclosure on the
+     * step's panel. The final outcome lives on the node's status / error
+     * fields; this array carries only the failed attempts that came before.
+     */
+    attempts?: Array<{
+        attempt: number;
+        error: RunErrorDetail;
+        timestamp: number;
+    }>;
+    /**
+     * Tier 2 #4 sub-workflow mode — only set for `nodeType === "subworkflow"`.
+     * - `true` (default) — synchronous: parent step blocks on child completion.
+     * - `false` — fire-and-forget: parent returns dispatch metadata immediately;
+     *   child runs asynchronously via `setImmediate`. Studio renders a distinct
+     *   `↳ async` badge in StepRail to differentiate from synchronous siblings.
+     *
+     * Captured at `tracker.startNode()` time so it survives the trace and is
+     * visible to Studio without recomputing from outputs heuristics.
+     */
+    wait?: boolean;
+    /**
+     * G2 (v0.6) sub-workflow dispatch strategy — only set for
+     * `nodeType === "subworkflow"`. Mirrors the step config's `dispatch`
+     * field so Studio can distinguish in-process invocations from HTTP
+     * self-call dispatches at a glance.
+     *
+     * - `"in-process"` (default; also represented by `undefined` on legacy
+     *   traces) — child runs in the same Node process via the in-process
+     *   `Runner`.
+     * - `"http-self"` — child is dispatched as a fresh HTTP request to
+     *   `BLOK_SELF_BASE_URL`, potentially landing on a different process
+     *   in a horizontally-scaled deployment.
+     *
+     * Captured at `tracker.startNode()` time alongside `wait` so the rail
+     * badge can compose them (`↳ async` orange + `http` sky for an
+     * async http-self dispatch).
+     */
+    dispatch?: "in-process" | "http-self";
+    /**
+     * PR 5 E3 — sub-workflow nesting depth surfaced for Studio.
+     *
+     * Set on subworkflow node runs. Top-level workflow's sub-workflow
+     * step has `subworkflowDepth = 1`; that child's sub-workflow step
+     * has `subworkflowDepth = 2`; etc. Bounded by
+     * `BLOK_MAX_SUBWORKFLOW_DEPTH` (default 10).
+     *
+     * Studio renders `↳ async (N)` / `↳ sub (N)` only when N >= 2 to
+     * keep top-level invocations un-cluttered.
+     */
+    subworkflowDepth?: number;
+    /**
+     * v0.5 — origin middleware name when the trigger's
+     * `runMiddlewareChain` produced this NodeRun. The trigger sets a
+     * `_blokMiddlewareName` sentinel on ctx before dispatching each
+     * middleware; RunnerSteps reads it and propagates here so Studio's
+     * StepRail can surface a `mw:<name>` badge on the inner steps a
+     * middleware produced (otherwise indistinguishable from regular
+     * depth-1 nested steps).
+     */
+    middleware?: string;
+    /**
+     * v0.5.3 — iteration index for steps inside a `forEach` or `loop`
+     * primitive. Set per-iteration by ForEachNode / LoopNode on the
+     * cloned child ctx (`_blokIterationIndex` sentinel); RunnerSteps
+     * reads it and propagates here. Studio's StepRail groups consecutive
+     * sibling rows that share an iterationIndex into a collapsible
+     * "iteration N" header so a 5-iteration forEach with 3 inner steps
+     * renders as 5 grouped sections instead of 15 flat rows with
+     * duplicate names. Undefined for top-level steps, for steps inside
+     * non-iteration primitives (`tryCatch`, `switch`), and for legacy
+     * traces written before v0.5.3.
+     */
+    iterationIndex?: number;
+    /**
+     * v0.6 wait-inside-primitives — iteration cursor. Set on a primitive
+     * iterator's NodeRun (e.g. forEach, loop) by RunnerSteps when an
+     * INNER step throws `WaitDispatchRequest` mid-iteration. Read by
+     * `TriggerBase.run` on dispatchDeferred re-entry and stamped onto
+     * `ctx._blokIterationResume` so the primitive can pick it up.
+     * Persisted column is `iteration_context` (sqlite migration v12).
+     *
+     * Two encodings via a `mode` discriminator:
+     *
+     *   - `mode: "sequential"` (or omitted for back-compat): the Phase 2
+     *     sequential forEach + wait cursor (also reused by Phase 3 loop).
+     *     Records the in-flight iteration index, the inner step index
+     *     where the wait fired, and an in-order `completedResults`
+     *     accumulator covering iterations `[0..iteration-1]`. ForEachNode
+     *     and LoopNode read this on resume to skip the completed prefix.
+     *
+     *   - `mode: "parallel"` (PR follow-up to Phase 3): the parallel
+     *     forEach + wait cursor. Records which iteration's wait fired
+     *     (`waitFiringIteration`), where inside its body
+     *     (`innerStepIndex`), a SPARSE `completedResults` array (slot `i`
+     *     populated iff iteration `i` finished before the wait fired —
+     *     `null` for "ran but returned undefined", JSON-undefined hole
+     *     for "not present"), and the explicit `cancelledIterations`
+     *     list (in-flight + queued indices that need re-launch on
+     *     resume). See `docs/c/devtools/parallel-foreach-wait-spec.mdx`
+     *     for the full contract.
+     *
+     * Undefined on regular NodeRuns and on primitives that completed
+     * without ever throwing a wait.
+     */
+    iterationContext?: IterationContext;
+}
+/**
+ * Discriminated union for the iteration cursor persisted into
+ * `node_runs.iteration_context`. See `NodeRun.iterationContext` for
+ * field-level semantics. The runtime selection lives in:
+ *
+ *   - Write side: `core/runner/src/RunnerSteps.ts` wait-throw site
+ *     (sequential) and `ForEachNode.run` parallel-branch error handler
+ *     (parallel).
+ *   - Read side: `TriggerBase.run` rehydrate stamps the cursor onto
+ *     `ctx._blokIterationResume`; the primitive itself (ForEachNode,
+ *     LoopNode) dispatches on `mode` to the right resume path.
+ */
+export type IterationContext = SequentialIterationContext | ParallelIterationContext | SwitchIterationContext;
+/**
+ * Sequential forEach + wait OR loop + wait cursor. The pre-existing
+ * Phase 2/3 shape — `mode` is optional and defaults to "sequential" on
+ * read so cursors written before the discriminator landed (i.e., main
+ * before this PR) keep being interpreted correctly.
+ */
+export interface SequentialIterationContext {
+    mode?: "sequential";
+    /** Iteration index (0-based) the wait fired in. */
+    iteration: number;
+    /** Inner step index within iteration's body where the wait fired. */
+    innerStepIndex: number;
+    /** Accumulator for iterations [0..iteration-1]; pre-populates `results[]` on resume. */
+    completedResults: unknown[];
+}
+/**
+ * v0.6 Phase 4 — switch + wait cursor. Records which case arm matched
+ * (so on re-entry SwitchNode walks back into the same arm) plus the
+ * inner step within that arm where the wait fired.
+ *
+ * `caseIndex` semantics:
+ *   - `>= 0` — index into the workflow's `cases[]` array.
+ *   - `-1`   — the `default` arm matched.
+ *
+ * `completedResults` is unused for switch (it doesn't iterate) but the
+ * field is kept on the IterationContext union for cross-schema parity.
+ * Always `[]` on switch.
+ */
+export interface SwitchIterationContext {
+    mode: "switch";
+    /** Resolved case index; `-1` denotes the `default` arm. */
+    caseIndex: number;
+    /** Inner step index within the matched arm where the wait fired. */
+    innerStepIndex: number;
+    /** Unused for switch; preserved at schema level for parity. Always `[]`. */
+    completedResults: never[];
+}
+/**
+ * Parallel forEach + wait cursor. The headline contract: persist
+ * completed iteration results, retry incomplete ones on resume. See
+ * `docs/c/devtools/parallel-foreach-wait-spec.mdx` for the full design.
+ */
+export interface ParallelIterationContext {
+    mode: "parallel";
+    /** Index of the iteration whose inner step threw the wait. */
+    waitFiringIteration: number;
+    /** Inner step index within the wait-firing iteration's body. */
+    innerStepIndex: number;
+    /**
+     * Sparse array indexed by iteration number. Slot `i` is populated
+     * iff iteration `i` finished before the wait fired. `null` means
+     * "ran but returned undefined" (distinct from the JSON-undefined
+     * hole = "not present in cursor, re-launch on resume").
+     */
+    completedResults: (unknown | null)[];
+    /**
+     * Iteration indices that were in-flight OR queued at wait-throw
+     * moment. ForEachNode re-launches these from inner step 0 on
+     * resume. The wait-firing iteration is NOT in this list — it
+     * resumes via `innerStepIndex`. Sorted ascending for trace-dump
+     * readability.
+     */
+    cancelledIterations: number[];
+}
+/**
+ * Stored result of a previously-successful step execution, keyed by
+ * `(workflowName, step.id, idempotencyKey)`. On cache hit, RunnerSteps
+ * skips `step.process()` and replays the cached `data` through the same
+ * `PersistenceHelper.applyStepOutput` rules — caching layers ABOVE
+ * persistence, never within it.
+ */
+export interface CachedStepResult {
+    /** The data the step originally returned. */
+    data: unknown;
+    /** ms since epoch when the entry was written. */
+    cachedAt: number;
+    /** ms since epoch when the entry expires; null = no expiry. */
+    expiresAt: number | null;
+    /** Run that originally produced this result. */
+    sourceRunId: string;
+    /** Node run that originally produced this result. */
+    sourceNodeRunId: string;
+}
+/**
+ * Outcome of an `acquireConcurrencySlot` attempt (Tier 2 #6).
+ *
+ * The store's gate decides whether the run is allowed to proceed by
+ * comparing the current in-flight count for the (workflow, key) pair
+ * against the requested limit.
+ */
+export interface ConcurrencySlotResult {
+    /** True when the slot was granted; false when the run should be throttled. */
+    acquired: boolean;
+    /**
+     * Number of in-flight runs (including the just-acquired one when
+     * `acquired === true`) sharing the same (workflowName, concurrencyKey).
+     * Useful for observability — Studio surfaces this on `RUN_THROTTLED`.
+     */
+    currentInFlight: number;
+}
+/**
+ * A persisted scheduled dispatch — one row per pending HTTP-trigger
+ * deferral. Written by `DeferredRunScheduler.schedule()` when a
+ * `persist` payload is provided; deleted on cancel or fire.
+ *
+ * Boot recovery (HttpTrigger.recoverDispatches) scans this table,
+ * marks past-due+TTL-expired rows as `"expired"`, and re-registers
+ * timers for live dispatches.
+ */
+export interface ScheduledDispatchRow {
+    runId: string;
+    workflowName: string;
+    /** `"http"` for v1; future triggers can opt in. */
+    triggerType: string;
+    /** ms since epoch when to dispatch. */
+    scheduledAt: number;
+    /** ms since epoch TTL deadline (undefined = no TTL). */
+    expiresAt?: number;
+    /** Mirrors the run record's status — `"delayed" | "queued" | "debounced"`. */
+    dispatchStatus: "delayed" | "queued" | "debounced";
+    /**
+     * JSON-serialized minimal Context subset, trigger-defined.
+     * For HTTP: `{method, path, headers, body, params, query, workflowPath}`
+     * with sensitive header keys stripped (authorization, cookie, x-api-key).
+     */
+    payload: unknown;
+    /** ms since epoch when the row was first written. */
+    createdAt: number;
+    /**
+     * Tier C #2 — cross-process scheduler coordination. Set when a
+     * process claims this dispatch during boot recovery. Unset on
+     * unclaimed rows.
+     *
+     * Multi-process PG deployments use the claim to prevent the same
+     * dispatch from being fired by two processes that both ran
+     * `recoverDispatches()` against the shared table. Single-process
+     * and per-process sqlite deployments see no observable difference
+     * (the same process always wins the claim).
+     */
+    claimedBy?: string;
+    /**
+     * Tier C #2 — last heartbeat timestamp (ms since epoch). The
+     * holder of `claimedBy` periodically refreshes `claimedAt` while
+     * the timer is registered. Stale claims (now > claimedAt + leaseMs)
+     * are eligible for takeover by another process — protects against
+     * crashed holders blocking recovery indefinitely.
+     */
+    claimedAt?: number;
 }
 export type RunEventType = "RUN_STARTED" | "RUN_COMPLETED" | "RUN_FAILED" | "NODE_STARTED" | "NODE_COMPLETED" | "NODE_FAILED" | "NODE_SKIPPED" | "VARS_UPDATED" | "LOG_ENTRY"
 /** §17 Phase 5: streaming `Progress` frame from the SDK. */
  | "NODE_PROGRESS"
 /** §17 Phase 5: streaming `PartialResult` frame from the SDK. */
- | "NODE_PARTIAL_RESULT";
+ | "NODE_PARTIAL_RESULT"
+/**
+ * Tier 1 idempotency cache hit: the step short-circuited via the
+ * idempotency cache instead of running. Payload carries
+ * `{ durationMs, source: { sourceRunId, sourceNodeRunId, cachedAt } }`.
+ * Studio renders a CACHED badge on the affected node.
+ */
+ | "NODE_CACHED"
+/**
+ * Tier 1 retry: a step attempt failed and another retry will follow.
+ * Payload carries `{ attempt, error }`. Final attempt failure (after
+ * exhausting `retry.maxAttempts`) emits `NODE_FAILED` instead.
+ */
+ | "NODE_ATTEMPT_FAILED"
+/**
+ * Tier 2 #6 concurrency gate denied a run before any step executed.
+ * Payload carries `{ concurrencyKey, concurrencyLimit, currentInFlight }`.
+ * The run's status flips to `"throttled"` (distinct from `"failed"` —
+ * no step ran). Studio surfaces a Throttled badge.
+ */
+ | "RUN_THROTTLED"
+/**
+ * Tier 2 #5 — run scheduled for later dispatch via `trigger.delay`.
+ * Payload `{scheduledAt, delayMs, expiresAt?}`. Status flips to
+ * `"delayed"`; transitions to `"running"` when the timer fires.
+ */
+ | "RUN_DELAYED"
+/**
+ * Tier 2 #5 — TTL exceeded; run auto-cancelled before dispatch.
+ * Payload `{expiresAt, expiredAt, lateBy}`. Status flips to `"expired"`.
+ */
+ | "RUN_EXPIRED"
+/**
+ * Tier 2 #7 — run coalesced into a debounce window. Payload
+ * `{debounceKey, mode, intoRunId?, pingCount?}`. Status flips to
+ * `"debounced"`. In leading mode this is terminal (the run never
+ * executes — execution went to a sibling). In trailing mode this is
+ * transient and the same run flips to `"running"` when the window
+ * closes.
+ */
+ | "RUN_DEBOUNCED"
+/**
+ * Tier 2 #6 follow-up — concurrency gate denied a run AND the trigger
+ * is configured with `onLimit: "queue"`. Instead of throwing, the run
+ * is deferred via `DeferredRunScheduler` and re-attempts acquisition
+ * after a 1s delay. Payload `{concurrencyKey, concurrencyLimit,
+ * currentInFlight, scheduledAt}`. Status flips to `"queued"`;
+ * transitions to `"running"` when the timer fires (and may flip back
+ * to `"queued"` on re-denial).
+ */
+ | "RUN_QUEUED"
+/**
+ * Tier 2 polish — operator cancelled a pending (delayed/debounced/
+ * queued) run via `POST /__blok/runs/:runId/cancel`. Payload
+ * `{durationMs, previousStatus}`. Status flips to `"cancelled"`.
+ * Currently only pre-execution states are cancellable; running runs
+ * require cooperative `AbortSignal` (deferred follow-up).
+ */
+ | "RUN_CANCELLED"
+/**
+ * Tier 2 quick-wins — run crashed (uncaught exception / OOM /
+ * signal). Payload `{durationMs, error}`. Distinct from `RUN_FAILED`
+ * (which implies a step's `process()` threw cleanly). Currently
+ * manual via `tracker.markRunCrashed(runId, {error})`.
+ */
+ | "RUN_CRASHED"
+/**
+ * Tier 2 quick-wins — a step's final retry attempt exceeded its
+ * `maxDuration` cap. Payload `{durationMs, stepId, maxDurationMs,
+ * attemptsExhausted}`. Auto-emitted by `RunnerSteps` when the
+ * timeout fires on the last attempt. Run status flips to
+ * `"timedOut"`.
+ */
+ | "RUN_TIMED_OUT";
 export interface RunEvent {
     id: string;
     type: RunEventType;
@@ -155,6 +646,26 @@ export interface WorkflowDetail extends WorkflowSummary {
     definition?: unknown;
     nodeNames: string[];
     runtimes: string[];
+    /**
+     * Sample-body for the Studio empty-state curl. `source` lets the
+     * UI optionally distinguish author-declared examples from the
+     * synthesized ones (it doesn't today, but could in the future).
+     * Always populated for object-shaped workflows; `body` is `{}`
+     * when no body references were detected.
+     */
+    examples?: {
+        body: unknown;
+        /**
+         * Provenance of the body. `author` = declared in the workflow's
+         * `trigger.http.examples.body`. `recorded` = captured from the
+         * first successful run when `recordSample: true` is set on the
+         * trigger. `inferred` = synthesized from static analysis of step
+         * inputs. `empty` = no body references + no recording + no
+         * author override (the literal `{}`). Studio surfaces this in
+         * the Runs-tab empty-state curl snippet label.
+         */
+        source: "author" | "recorded" | "inferred" | "empty";
+    };
 }
 export interface PaginatedResult<T> {
     data: T[];
@@ -170,6 +681,43 @@ export interface StartRunOptions {
     nodeCount: number;
     tags?: string[];
     metadata?: Record<string, unknown>;
+    /**
+     * Tier 1 · replay lineage. When a run is started via the replay endpoint,
+     * this carries the original run's id so Studio can render a "Replay of #..."
+     * breadcrumb. Plumbed end-to-end via the `X-Blok-Replay-Of` HTTP header.
+     */
+    replayOf?: string;
+    /**
+     * Tier 2 · sub-workflow lineage. Populated by `SubworkflowNode` when
+     * invoking a child workflow inline. Studio uses this to render a
+     * "called from #..." breadcrumb on the child's run detail.
+     */
+    parentRunId?: string;
+    parentNodeRunId?: string;
+    /**
+     * Tier 2 #5 · scheduled dispatch time (ms since epoch). When set, the
+     * run is created with status `"delayed"` instead of `"running"`.
+     */
+    scheduledAt?: number;
+    /**
+     * Tier 2 #5 · TTL deadline (ms since epoch). Persists onto the run
+     * for the dispatcher to consult.
+     */
+    expiresAt?: number;
+    /**
+     * Tier 2 #7 · resolved debounce key. When set, pings sharing this
+     * key + workflow name coalesce.
+     */
+    debounceKey?: string;
+    /**
+     * Tier 2 #7 · debounce mode that produced this run.
+     */
+    debounceMode?: "leading" | "trailing";
+    /**
+     * Tier 2 #7 · initial ping count for the run (typically 1 — the
+     * first ping). Subsequent pings increment via direct store update.
+     */
+    pingCount?: number;
 }
 export interface StartNodeOptions {
     nodeName: string;
@@ -179,6 +727,42 @@ export interface StartNodeOptions {
     parentNodeId?: string;
     depth: number;
     stepIndex: number;
+    /**
+     * Tier 2 #4 sub-workflow mode. Only meaningful when `nodeType === "subworkflow"`.
+     * Persisted onto `NodeRun.wait` so Studio can render `↳ async` vs `↳ sub`.
+     */
+    wait?: boolean;
+    /**
+     * G2 (v0.6) sub-workflow dispatch strategy. Only meaningful when
+     * `nodeType === "subworkflow"`. Persisted onto `NodeRun.dispatch` so
+     * Studio can render an extra `http` badge alongside `↳ async`/`↳ sub`
+     * for HTTP self-call dispatches.
+     */
+    dispatch?: "in-process" | "http-self";
+    /**
+     * PR 5 E3 — sub-workflow nesting depth. Only meaningful when
+     * `nodeType === "subworkflow"`. The runner computes
+     * `parentDepth + 1` from `ctx._subworkflowDepth` at start-time and
+     * passes here so Studio can render `↳ sub (N)` for N >= 2.
+     */
+    subworkflowDepth?: number;
+    /**
+     * v0.5 — origin middleware name. Set when the parent ctx carries
+     * `_blokMiddlewareName` (HttpTrigger.runMiddlewareChain stash).
+     * Propagates onto `NodeRun.middleware` so Studio's StepRail can
+     * surface a `mw:<name>` badge.
+     */
+    middleware?: string;
+    /**
+     * v0.5.3 — iteration index for steps inside a `forEach` or `loop`
+     * primitive. Set when the parent ctx carries `_blokIterationIndex`
+     * (ForEachNode + LoopNode stash on each per-iteration child ctx).
+     * Studio's StepRail uses this to group consecutive sibling rows
+     * into "iteration N" sections instead of showing them flat with
+     * duplicated step names. Undefined for top-level steps and for
+     * inner steps of non-iteration primitives (`tryCatch`, `switch`).
+     */
+    iterationIndex?: number;
 }
 export type WidgetType = "stat-card" | "timeline" | "error-rate" | "duration-distribution" | "workflow-breakdown" | "node-performance" | "recent-runs" | "heatmap";
 export interface DashboardWidget {
@@ -208,10 +792,96 @@ export interface Dashboard {
     updatedAt: number;
     widgets: DashboardWidget[];
 }
+/**
+ * E2 — server-side saved filter for the runs list. Mirrors the
+ * earlier localStorage shape (`apps/studio/src/lib/savedFilters.ts`)
+ * with `id` + timestamps added. Filter names are UNIQUE across the
+ * deployment — re-saving overwrites the existing row. Studio applies
+ * them by setting the run-list filter UI from the stored values.
+ */
+export interface SavedFilter {
+    id: string;
+    name: string;
+    /** Workflow run status (`""` for "all"). */
+    status: string;
+    /**
+     * Free-form tag input as the user typed it ("env:prod,team:billing").
+     * Server stores it verbatim; the run-list URL parser interprets it.
+     */
+    tagsInput: string;
+    /**
+     * Free-form metadata input as the user typed it
+     * ("tier=premium,region__in=us,eu"). Same parsing contract as the
+     * runs-page URL — `MetadataFilter[]` once parsed.
+     */
+    metadataInput: string;
+    createdAt: number;
+    updatedAt: number;
+}
+/**
+ * Sample-body recording (v0.6 follow-up to #100). When a workflow's
+ * HTTP trigger declares `recordSample: true`, the trigger captures
+ * the request body of the FIRST successful run and persists it
+ * here. Studio's `examples.body` resolution prefers a recorded
+ * sample over static inference but always defers to an author-
+ * declared `trigger.http.examples.body`.
+ *
+ * One row per workflow — re-recording is intentionally skipped
+ * after the first capture so storage stays bounded + the
+ * operator-visible example stays stable. Authors can re-trigger a
+ * recording by deleting the row (no Studio surface for this yet;
+ * call `tracker.deleteWorkflowSample(name)` from a script).
+ */
+export interface WorkflowSample {
+    workflowName: string;
+    body: unknown;
+    /** Run id whose request body was captured. */
+    sourceRunId: string;
+    /** Wall-clock when the sample was recorded. */
+    recordedAt: number;
+}
+/**
+ * F2 (v0.5) — operators accepted on metadata filters. `eq` is the
+ * default (and the only one available before v0.5). Each operator
+ * coerces values the way an operator typically would: numerical
+ * comparisons cast to number, `like` is SQL `LIKE` (with `%` /
+ * `_` wildcards), `in`/`nin` accept array values.
+ */
+export type MetadataOp = "eq" | "ne" | "gt" | "gte" | "lt" | "lte" | "like" | "in" | "nin";
+/**
+ * F2 (v0.5) — operator-aware metadata filter. Combines with other
+ * filters in the same `RunQuery.metadata` array via AND semantics.
+ *
+ * `value` is `string` for scalar operators (`eq` / `ne` / `gt` / `lt` /
+ * `gte` / `lte` / `like`), `string[]` for set operators (`in` / `nin`).
+ * Numeric comparisons treat the stored metadata value as a number when
+ * possible (the underlying JSON store preserves the native type).
+ */
+export interface MetadataFilter {
+    key: string;
+    op: MetadataOp;
+    value: string | string[];
+}
 export interface RunQuery {
     workflow?: string;
     status?: WorkflowRunStatus;
     tags?: string[];
+    /**
+     * Filter by metadata key/value pairs. Multiple entries combine with
+     * AND semantics (a run matches only when every declared filter is
+     * satisfied).
+     *
+     * **Two accepted shapes** — `Record<string, string>` is back-compat
+     * sugar for an array of `{key, op: "eq", value}` filters. Pass an
+     * array to use operators beyond `=` (F2: `ne` / `gt` / `gte` / `lt`
+     * / `lte` / `like` / `in` / `nin`). Both shapes route through the
+     * same evaluator after normalisation.
+     *
+     * **Performance** — sequential JSON-extract scan by default;
+     * declare hot keys via `BLOK_INDEXED_METADATA_KEYS=tier,region` to
+     * get an indexed column + index on the SqliteRunStore side (F1).
+     */
+    metadata?: Record<string, string> | MetadataFilter[];
     limit?: number;
     offset?: number;
     sort?: "asc" | "desc";