@blokjs/runner 0.2.2 → 0.4.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,74 @@ 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;
 }
 export type NodeRunStatus = "pending" | "running" | "completed" | "failed" | "skipped";
 export interface NodeRun {
@@ -113,12 +214,199 @@ 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;
+    /**
+     * 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;
+}
+/**
+ * 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;
 }
 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;
@@ -170,6 +458,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 +504,18 @@ 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;
+    /**
+     * 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;
 }
 export type WidgetType = "stat-card" | "timeline" | "error-rate" | "duration-distribution" | "workflow-breakdown" | "node-performance" | "recent-runs" | "heatmap";
 export interface DashboardWidget {
@@ -212,6 +549,15 @@ export interface RunQuery {
     workflow?: string;
     status?: WorkflowRunStatus;
     tags?: string[];
+    /**
+     * Tier 2 quick-wins — filter by metadata key=value pairs. Multiple
+     * pairs combine with AND semantics (a run matches only when all
+     * declared keys match the requested values, compared via stringified
+     * equality). Backed by `json_extract` on SQLite + `Object` lookup
+     * on InMemory. Sequential scan (no index); acceptable given the
+     * `evictOldRuns` size cap on the runs table.
+     */
+    metadata?: Record<string, string>;
     limit?: number;
     offset?: number;
     sort?: "asc" | "desc";

package/dist/utils/createChildContext.d.ts

@@ -0,0 +1,32 @@
+import type { Context } from "@blokjs/shared";
+/**
+ * Construct a fresh `Context` for a sub-workflow invocation.
+ *
+ * **Isolation contract**: the child gets fresh `state`, fresh `response`,
+ * fresh `error`, and a fresh `id`. The child cannot read or mutate the
+ * parent's state — sub-workflows are referentially transparent at the
+ * state-passing boundary. Parent passes data in via `request.body`
+ * (mirrors HTTP semantics), child returns data via `ctx.response`.
+ *
+ * **Shared by reference (intentional)**: the `logger`, `env`, and
+ * `eventLogger` are shared with the parent — log routing stays
+ * consistent and ENV is process-global anyway. The runner's tracing
+ * layer (`_traceRunId`, `_traceNodeId`) is set separately by
+ * `SubworkflowNode` after this function returns.
+ *
+ * Mirrors `TriggerBase.createContext` shape one-for-one (same `req`/
+ * `prev` getters, same `state`/`vars` aliasing, same `publish`
+ * default). Kept as a standalone helper rather than a TriggerBase
+ * method so sub-workflow dispatch doesn't depend on having a
+ * TriggerBase instance.
+ */
+export declare function createChildContext(parent: Context, opts: {
+    /** The child workflow's `name:` field. */
+    workflowName: string;
+    /** Filesystem path or `"<inline>"` — used for trace + diagnostics. */
+    workflowPath: string;
+    /** Parent step's resolved inputs, becomes child's `request.body`. */
+    body: unknown;
+    /** Child's resolved `nodes` map (from child Configuration). Powers blueprint mapper. */
+    config: Context["config"];
+}): Context;

package/dist/utils/createChildContext.js

@@ -0,0 +1,113 @@
+import { v4 as uuid } from "uuid";
+/**
+ * Construct a fresh `Context` for a sub-workflow invocation.
+ *
+ * **Isolation contract**: the child gets fresh `state`, fresh `response`,
+ * fresh `error`, and a fresh `id`. The child cannot read or mutate the
+ * parent's state — sub-workflows are referentially transparent at the
+ * state-passing boundary. Parent passes data in via `request.body`
+ * (mirrors HTTP semantics), child returns data via `ctx.response`.
+ *
+ * **Shared by reference (intentional)**: the `logger`, `env`, and
+ * `eventLogger` are shared with the parent — log routing stays
+ * consistent and ENV is process-global anyway. The runner's tracing
+ * layer (`_traceRunId`, `_traceNodeId`) is set separately by
+ * `SubworkflowNode` after this function returns.
+ *
+ * Mirrors `TriggerBase.createContext` shape one-for-one (same `req`/
+ * `prev` getters, same `state`/`vars` aliasing, same `publish`
+ * default). Kept as a standalone helper rather than a TriggerBase
+ * method so sub-workflow dispatch doesn't depend on having a
+ * TriggerBase instance.
+ */
+export function createChildContext(parent, opts) {
+    const id = uuid();
+    const request = {
+        body: opts.body ?? {},
+        headers: {},
+        params: {},
+        query: {},
+    };
+    const response = {
+        data: "",
+        contentType: "",
+        success: true,
+        error: null,
+    };
+    const state = {};
+    // Tier 2 follow-up · cooperative cancellation. Child gets its own
+    // AbortController so it has independent lifecycle (cancellation of
+    // THIS sub-workflow doesn't propagate up to the parent). But we
+    // chain off the parent's signal: if the parent gets cancelled, the
+    // child should abort too — otherwise long-running sub-workflows
+    // would orphan when the parent exits.
+    //
+    // PR 1 follow-up · A3 fix. `addEventListener({once: true})` only
+    // auto-removes the listener when abort fires. If the parent never
+    // aborts AND the parent ctx outlives many child invocations, listeners
+    // accumulate and Node's MaxListenersExceededWarning fires at the 11th.
+    // Pass a child-scoped AbortSignal as the listener's `signal:` option
+    // so the listener auto-removes when the child completes (the
+    // SubworkflowNode dispatch path calls `listenerCleanup.abort()` in
+    // its finally block).
+    const childAbortController = new AbortController();
+    const listenerCleanup = new AbortController();
+    if (parent.signal) {
+        if (parent.signal.aborted) {
+            childAbortController.abort();
+        }
+        else {
+            parent.signal.addEventListener("abort", () => {
+                if (!childAbortController.signal.aborted)
+                    childAbortController.abort();
+            }, { once: true, signal: listenerCleanup.signal });
+        }
+    }
+    const ctx = {
+        id,
+        workflow_name: opts.workflowName,
+        workflow_path: opts.workflowPath,
+        config: opts.config,
+        request,
+        response,
+        error: { message: [] },
+        logger: parent.logger,
+        eventLogger: parent.eventLogger ?? null,
+        // Fresh state map — child runs in isolation. Aliased as `vars`
+        // for v1 back-compat, same shape as `TriggerBase.createContext`.
+        state,
+        vars: state,
+        env: parent.env,
+        signal: childAbortController.signal,
+        // Stash the controller in a child-specific _PRIVATE_ slot so the
+        // tracker can fire it via abortRunningRun on direct sub-run cancel.
+        // Don't mutate the parent's _PRIVATE_ (intentional isolation).
+        // `listenerCleanup` is exposed so SubworkflowNode can abort it on
+        // child completion, which removes the parent.signal listener (PR 1
+        // A3 fix — prevents listener accumulation on long-lived parents).
+        _PRIVATE_: { abortController: childAbortController, listenerCleanup },
+    };
+    // V2 read-only aliases — same object reference, no copy. Mirrors
+    // `TriggerBase.createContext`.
+    Object.defineProperty(ctx, "req", {
+        get() {
+            return ctx.request;
+        },
+        enumerable: true,
+    });
+    Object.defineProperty(ctx, "prev", {
+        get() {
+            return ctx.response;
+        },
+        enumerable: true,
+    });
+    // Default `publish` — writes to state, no side-channel event. The
+    // triggers' production createContext also wires Studio trace
+    // events; for sub-workflows we omit that (the child has its own
+    // trace run, events fire there).
+    ctx.publish = (name, value) => {
+        ctx.state[name] = value;
+    };
+    return ctx;
+}
+//# sourceMappingURL=createChildContext.js.map

package/dist/utils/createChildContext.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"createChildContext.js","sourceRoot":"","sources":["../../src/utils/createChildContext.ts"],"names":[],"mappings":"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"}

package/dist/workflow/WorkflowNormalizer.d.ts

@@ -1,44 +1,9 @@
-/**
- * WorkflowNormalizer — accepts v1 or v2 workflow shapes and projects both
- * to the single canonical internal shape that `Configuration.getSteps` /
- * `Configuration.getNodes` already consume.
- *
- * **Input shapes accepted**
- *
- * v1 (legacy):
- * ```
- * {
- *   name, version, trigger,
- *   steps: [{ name, node, type, active?, stop?, set_var? }],
- *   nodes: { [stepName]: { inputs?, conditions? } }
- * }
- * ```
- *
- * v2 (canonical):
- * ```
- * {
- *   name, version, trigger,
- *   steps: [
- *     { id, use, type?, inputs?, as?, spread?, ephemeral?, active?, stop? }
- *   | { id, branch: { when, then, else? } }
- *   ]
- * }
- * ```
- *
- * **Output shape** (always v1-compatible internal):
- * ```
- * {
- *   name, version, trigger,           // method "*" normalized to "ANY"
- *   steps: [{ name, node, type, active, stop, set_var, as, spread, ephemeral, ... }],
- *   nodes: { [stepName]: { inputs?, conditions? } }
- * }
- * ```
- *
- * **Why a single internal shape?** The runner core (RunnerSteps,
- * Configuration, Blok.run, etc.) is unchanged. Normalization is purely
- * an authoring-layer concern. Old workflows keep running; new authoring
- * shapes get translated transparently.
- */
+interface RetryConfig {
+    maxAttempts: number;
+    minTimeoutInMs?: number;
+    maxTimeoutInMs?: number;
+    factor?: number;
+}
 interface InternalStep {
     name: string;
     node: string;
@@ -51,6 +16,29 @@ interface InternalStep {
     ephemeral?: boolean;
     stream_logs?: boolean;
     flow?: boolean;
+    idempotencyKey?: string;
+    idempotencyKeyTTL?: number;
+    retry?: RetryConfig;
+    subworkflow?: string;
+    wait?: boolean;
+    /**
+     * Tier 2 quick-wins — per-attempt execution timeout. Number (ms) or
+     * duration string (`"30s"`, etc.). Configuration thread-through
+     * normalizes to milliseconds via `parseDuration`.
+     */
+    maxDuration?: number | string;
+    /**
+     * PR 4 — `wait.for(duration)` / `wait.until(date)` step.
+     *
+     * Discriminates by `type === "wait"` and the presence of either
+     * `waitForMs` (numeric ms after parseDuration) or `waitUntil` (number
+     * ms-since-epoch OR string for $-proxy / ISO).
+     *
+     * `wait?: boolean` above is the sub-workflow `wait: true|false` flag
+     * — separate concern, separate field.
+     */
+    waitForMs?: number;
+    waitUntil?: number | string;
     [key: string]: unknown;
 }
 interface InternalNodeConfig {