@blokjs/runner 0.2.2 → 0.6.0

package/dist/workflow/WorkflowNormalizer.js

@@ -1,3 +1,4 @@
+import { parseDuration } from "@blokjs/helper";
 /**
  * WorkflowNormalizer — accepts v1 or v2 workflow shapes and projects both
  * to the single canonical internal shape that `Configuration.getSteps` /
@@ -9,7 +10,7 @@
  * ```
  * {
  *   name, version, trigger,
- *   steps: [{ name, node, type, active?, stop?, set_var? }],
+ *   steps: [{ name, node, type, active?, stop? }],
  *   nodes: { [stepName]: { inputs?, conditions? } }
  * }
  * ```
@@ -29,7 +30,7 @@
  * ```
  * {
  *   name, version, trigger,           // method "*" normalized to "ANY"
- *   steps: [{ name, node, type, active, stop, set_var, as, spread, ephemeral, ... }],
+ *   steps: [{ name, node, type, active, stop, as, spread, ephemeral, ... }],
  *   nodes: { [stepName]: { inputs?, conditions? } }
  * }
  * ```
@@ -66,9 +67,33 @@ export function normalizeWorkflow(raw, sourcePath) {
         // Legacy builder shape — same unwrap.
         wf = wf._config;
     }
+    // `set_var` removed in v0.5. Reject at load time with a migration hint
+    // — silently dropping the field would produce subtly different runtime
+    // behaviour (every step now default-stores; legacy `set_var: false`
+    // was the only opt-out and is replaced by `ephemeral: true`).
+    if (Array.isArray(wf.steps)) {
+        assertNoSetVar(wf.steps, sourcePath);
+    }
     const name = typeof wf.name === "string" ? wf.name : "";
     const version = typeof wf.version === "string" ? wf.version : "1.0.0";
     const description = typeof wf.description === "string" ? wf.description : undefined;
+    // `middleware` is overloaded:
+    //   - `true`            → marker bit, this workflow IS a middleware
+    //   - `string[]`        → workflow-level middleware chain (these run on
+    //                         every request to this workflow, before any
+    //                         trigger-level middleware)
+    // The two are mutually exclusive — refuse the conflict at load time
+    // rather than letting one silently win.
+    const middleware = wf.middleware === true ? true : undefined;
+    let appliedMiddleware;
+    if (Array.isArray(wf.middleware)) {
+        const list = wf.middleware.filter((s) => typeof s === "string" && s.length > 0);
+        appliedMiddleware = list.length > 0 ? list : undefined;
+    }
+    if (middleware === true && appliedMiddleware !== undefined) {
+        const suffix = sourcePath ? ` (file: ${sourcePath})` : "";
+        throw new Error(`[blok] WorkflowNormalizer: workflow "${name}" sets both \`middleware: true\` (marker) and \`middleware: [...]\` (chain). These are mutually exclusive — pick one.${suffix}`);
+    }
     // --- Trigger normalization (method "*" → "ANY") ---
     const trigger = normalizeTrigger(wf.trigger, sourcePath);
     // --- Steps normalization ---
@@ -83,9 +108,67 @@ export function normalizeWorkflow(raw, sourcePath) {
         const step = rawStep;
         // v2 branch — { id, branch: { when, then, else? } }
         if (isPlainObject(step.branch)) {
-            const { internalStep, nodeConfig } = normalizeBranchStep(step, i);
+            const { internalStep, nodeConfig, innerNodes } = normalizeBranchStep(step, i);
             internalSteps.push(internalStep);
             internalNodes[internalStep.name] = nodeConfig;
+            // Promote every inner step's nodeConfig into the top-level nodes map
+            // so BlokService.run can find `ctx.config[innerStep.name].inputs`
+            // when the runner descends into the matching arm. Without this,
+            // inner steps with `inputs:` defined inline crash with
+            // `opts.inputs undefined` because their config was only attached
+            // to the inner step instance, not the global lookup map.
+            Object.assign(internalNodes, innerNodes);
+            continue;
+        }
+        // v2 sub-workflow — { id, subworkflow: "<name>", inputs?, wait? }
+        // Discriminator is the presence of a non-empty `subworkflow` string.
+        // Resolves to a SubworkflowNode that looks up the child in the
+        // WorkflowRegistry at run time.
+        if (typeof step.subworkflow === "string" && step.subworkflow.length > 0) {
+            const { internalStep, nodeConfig } = normalizeSubworkflowStep(step, i);
+            internalSteps.push(internalStep);
+            if (nodeConfig)
+                internalNodes[internalStep.name] = nodeConfig;
+            continue;
+        }
+        // v2 wait — { id, wait: { for?, until? } } (PR 4).
+        // Discriminator: `wait` is an object (sub-workflow uses `wait: boolean`).
+        if (isPlainObject(step.wait) &&
+            (step.wait.for !== undefined || step.wait.until !== undefined)) {
+            const internalStep = normalizeWaitStep(step, i);
+            internalSteps.push(internalStep);
+            continue;
+        }
+        // v0.5 forEach — { id, forEach: { in, as, mode?, concurrency?, do: [...] } }
+        if (isPlainObject(step.forEach)) {
+            const { internalStep, nodeConfig, innerNodes } = normalizeForEachStep(step, i);
+            internalSteps.push(internalStep);
+            internalNodes[internalStep.name] = nodeConfig;
+            Object.assign(internalNodes, innerNodes);
+            continue;
+        }
+        // v0.5 loop — { id, loop: { while, maxIterations?, do: [...] } }
+        if (isPlainObject(step.loop)) {
+            const { internalStep, nodeConfig, innerNodes } = normalizeLoopStep(step, i);
+            internalSteps.push(internalStep);
+            internalNodes[internalStep.name] = nodeConfig;
+            Object.assign(internalNodes, innerNodes);
+            continue;
+        }
+        // v0.5 switch — { id, switch: { on, cases: [{when, do}], default? } }
+        if (isPlainObject(step.switch)) {
+            const { internalStep, nodeConfig, innerNodes } = normalizeSwitchStep(step, i);
+            internalSteps.push(internalStep);
+            internalNodes[internalStep.name] = nodeConfig;
+            Object.assign(internalNodes, innerNodes);
+            continue;
+        }
+        // v0.5 tryCatch — { id, tryCatch: { try, catch, finally? } }
+        if (isPlainObject(step.tryCatch)) {
+            const { internalStep, nodeConfig, innerNodes } = normalizeTryCatchStep(step, i);
+            internalSteps.push(internalStep);
+            internalNodes[internalStep.name] = nodeConfig;
+            Object.assign(internalNodes, innerNodes);
             continue;
         }
         // v2 regular — { id, use, inputs?, as?, spread?, ephemeral?, ... }
@@ -113,6 +196,8 @@ export function normalizeWorkflow(raw, sourcePath) {
         trigger,
         steps: internalSteps,
         nodes: internalNodes,
+        ...(middleware ? { middleware } : {}),
+        ...(appliedMiddleware ? { appliedMiddleware } : {}),
     };
 }
 // =============================================================================
@@ -137,10 +222,9 @@ function normalizeRegularStep(step, nodesInput, index) {
     const v1NodeConfig = isPlainObject(nodesInput[id]) ? nodesInput[id] : null;
     const v1Inputs = v1NodeConfig?.inputs && isPlainObject(v1NodeConfig.inputs) ? v1NodeConfig.inputs : null;
     const inputs = inlineInputs ?? v1Inputs;
-    // Persistence knobs — v2 first, legacy `set_var` mapped second.
-    const ephemeralExplicit = step.ephemeral === true;
-    const ephemeralFromLegacy = step.set_var === false;
-    const ephemeral = ephemeralExplicit || ephemeralFromLegacy;
+    // Persistence knobs — v2 only. Legacy `set_var` is rejected upstream
+    // in `normalizeWorkflow` via `assertNoSetVar`.
+    const ephemeral = step.ephemeral === true;
     const as = pickString(step.as);
     const spread = step.spread === true;
     // `as` and `spread` are mutually exclusive — caught at schema level too,
@@ -154,13 +238,38 @@ function normalizeRegularStep(step, nodesInput, index) {
         type,
         active: step.active === undefined ? true : Boolean(step.active),
         stop: step.stop === true,
-        set_var: typeof step.set_var === "boolean" ? step.set_var : undefined,
         as,
         spread,
         ephemeral,
     };
     if (typeof step.stream_logs === "boolean")
         internalStep.stream_logs = step.stream_logs;
+    // Idempotency cache + retry — pass through verbatim. The runner reads
+    // these in RunnerSteps to wrap step.process() with cache-check + retry-
+    // loop. They never reach PersistenceHelper.applyStepOutput; caching
+    // layers ABOVE that.
+    if (typeof step.idempotencyKey === "string" && step.idempotencyKey.length > 0) {
+        internalStep.idempotencyKey = step.idempotencyKey;
+    }
+    if (typeof step.idempotencyKeyTTL === "number" && Number.isFinite(step.idempotencyKeyTTL)) {
+        internalStep.idempotencyKeyTTL = step.idempotencyKeyTTL;
+    }
+    if (isPlainObject(step.retry)) {
+        const r = step.retry;
+        if (typeof r.maxAttempts === "number" && Number.isInteger(r.maxAttempts)) {
+            const retry = { maxAttempts: r.maxAttempts };
+            if (typeof r.minTimeoutInMs === "number")
+                retry.minTimeoutInMs = r.minTimeoutInMs;
+            if (typeof r.maxTimeoutInMs === "number")
+                retry.maxTimeoutInMs = r.maxTimeoutInMs;
+            if (typeof r.factor === "number")
+                retry.factor = r.factor;
+            internalStep.retry = retry;
+        }
+    }
+    if (typeof step.maxDuration === "number" || typeof step.maxDuration === "string") {
+        internalStep.maxDuration = step.maxDuration;
+    }
     // Build node config — only include `inputs` if present.
     let nodeConfig = null;
     if (inputs) {
@@ -196,37 +305,49 @@ function normalizeBranchStep(step, index) {
     // `nodesInput` because v2 branches inline `inputs` on each nested step.
     const thenInternal = [];
     const elseInternal = [];
+    const innerNodes = {};
     for (let i = 0; i < thenSteps.length; i++) {
         const s = thenSteps[i];
         if (!isPlainObject(s))
             continue;
         if (isPlainObject(s.branch)) {
-            const { internalStep } = normalizeBranchStep(s, i);
-            thenInternal.push(internalStep);
+            const { internalStep: nestedStep, nodeConfig: nestedConfig, innerNodes: nestedInner, } = normalizeBranchStep(s, i);
+            thenInternal.push(nestedStep);
+            innerNodes[nestedStep.name] = nestedConfig;
+            Object.assign(innerNodes, nestedInner);
             continue;
         }
-        const { internalStep, nodeConfig } = normalizeRegularStep(s, {}, i);
+        const { internalStep: regularStep, nodeConfig } = normalizeRegularStep(s, {}, i);
         // Inline inputs on the step itself so nested-flow execution finds them.
         // (RunnerSteps recursively executes flow nodes' inner steps.)
         if (nodeConfig?.inputs) {
-            internalStep.inputs = nodeConfig.inputs;
+            regularStep.inputs = nodeConfig.inputs;
         }
-        thenInternal.push(internalStep);
+        // Also surface the nodeConfig in the bubbled-up innerNodes map so
+        // BlokService.run can read inputs via `ctx.config[step.name]` when
+        // the inner step actually executes.
+        if (nodeConfig)
+            innerNodes[regularStep.name] = nodeConfig;
+        thenInternal.push(regularStep);
     }
     for (let i = 0; i < elseSteps.length; i++) {
         const s = elseSteps[i];
         if (!isPlainObject(s))
             continue;
         if (isPlainObject(s.branch)) {
-            const { internalStep } = normalizeBranchStep(s, i);
-            elseInternal.push(internalStep);
+            const { internalStep: nestedStep, nodeConfig: nestedConfig, innerNodes: nestedInner, } = normalizeBranchStep(s, i);
+            elseInternal.push(nestedStep);
+            innerNodes[nestedStep.name] = nestedConfig;
+            Object.assign(innerNodes, nestedInner);
             continue;
         }
-        const { internalStep, nodeConfig } = normalizeRegularStep(s, {}, i);
+        const { internalStep: regularStep, nodeConfig } = normalizeRegularStep(s, {}, i);
         if (nodeConfig?.inputs) {
-            internalStep.inputs = nodeConfig.inputs;
+            regularStep.inputs = nodeConfig.inputs;
         }
-        elseInternal.push(internalStep);
+        if (nodeConfig)
+            innerNodes[regularStep.name] = nodeConfig;
+        elseInternal.push(regularStep);
     }
     const conditions = [{ type: "if", condition: when, steps: thenInternal }];
     if (elseInternal.length > 0) {
@@ -241,8 +362,460 @@ function normalizeBranchStep(step, index) {
         flow: true,
     };
     const nodeConfig = { conditions };
+    return { internalStep, nodeConfig, innerNodes };
+}
+const SUBWORKFLOW_NODE_REF = "@blokjs/subworkflow";
+/**
+ * Normalize a v2 sub-workflow step into the canonical InternalStep
+ * shape. Resolves to a `SubworkflowNode` at run time
+ * (Configuration.nodeTypes.subworkflow).
+ *
+ * Inputs are placed on `nodeConfig.inputs` so the existing
+ * blueprint-mapper resolution path resolves `$.state.<id>` /
+ * `$.req.body.<key>` refs into concrete values BEFORE the
+ * sub-workflow node runs (mirrors how regular steps work).
+ */
+function normalizeSubworkflowStep(step, index) {
+    const id = pickString(step.id);
+    if (!id) {
+        throw new Error(`[blok] WorkflowNormalizer: sub-workflow step at index ${index} is missing \`id\`.`);
+    }
+    const subworkflow = pickString(step.subworkflow);
+    if (!subworkflow) {
+        throw new Error(`[blok] WorkflowNormalizer: sub-workflow step "${id}" is missing \`subworkflow\` (workflow name to invoke).`);
+    }
+    // `wait: false` (fire-and-forget) is now supported. The async dispatch
+    // branch lives in SubworkflowNode.run; the field is threaded through
+    // onto InternalStep below for the resolver to copy onto the
+    // SubworkflowNode instance.
+    // Persistence + retry + idempotency knobs — pass through verbatim
+    // (mirrors normalizeRegularStep). `as` and `spread` mutual exclusion
+    // is also enforced at the schema level; defensive check here.
+    const ephemeral = step.ephemeral === true;
+    const as = pickString(step.as);
+    const spread = step.spread === true;
+    if (as && spread) {
+        throw new Error(`[blok] WorkflowNormalizer: sub-workflow step "${id}" sets both \`as\` and \`spread\` — they are mutually exclusive.`);
+    }
+    const internalStep = {
+        name: id,
+        node: SUBWORKFLOW_NODE_REF,
+        type: "subworkflow",
+        active: step.active === undefined ? true : Boolean(step.active),
+        stop: step.stop === true,
+        as,
+        spread,
+        ephemeral,
+        subworkflow,
+        // Default `wait: true` when omitted. `wait: false` triggers the
+        // async dispatch branch in SubworkflowNode.run.
+        wait: step.wait === undefined ? true : Boolean(step.wait),
+    };
+    if (typeof step.idempotencyKey === "string" && step.idempotencyKey.length > 0) {
+        internalStep.idempotencyKey = step.idempotencyKey;
+    }
+    if (typeof step.idempotencyKeyTTL === "number" && Number.isFinite(step.idempotencyKeyTTL)) {
+        internalStep.idempotencyKeyTTL = step.idempotencyKeyTTL;
+    }
+    if (isPlainObject(step.retry)) {
+        const r = step.retry;
+        if (typeof r.maxAttempts === "number" && Number.isInteger(r.maxAttempts)) {
+            const retry = { maxAttempts: r.maxAttempts };
+            if (typeof r.minTimeoutInMs === "number")
+                retry.minTimeoutInMs = r.minTimeoutInMs;
+            if (typeof r.maxTimeoutInMs === "number")
+                retry.maxTimeoutInMs = r.maxTimeoutInMs;
+            if (typeof r.factor === "number")
+                retry.factor = r.factor;
+            internalStep.retry = retry;
+        }
+    }
+    if (typeof step.maxDuration === "number" || typeof step.maxDuration === "string") {
+        internalStep.maxDuration = step.maxDuration;
+    }
+    // G3 polymorphic-dispatch safety net — narrow the registry lookup to a
+    // fixed set when `subworkflow` is an expression (or just to harden a
+    // literal). Filter to non-empty strings here so SubworkflowNode can
+    // trust the shape and skip a defensive check on the hot path.
+    if (Array.isArray(step.allowList)) {
+        const cleaned = step.allowList.filter((s) => typeof s === "string" && s.length > 0);
+        if (cleaned.length > 0) {
+            internalStep.allowList = cleaned;
+        }
+    }
+    // G2 (v0.6) — dispatch strategy. Unknown / missing values fall
+    // through as "in-process" inside SubworkflowNode.run, but pass the
+    // raw string so the resolver can validate + threading bugs surface
+    // at config load instead of at run time.
+    if (step.dispatch === "in-process" || step.dispatch === "http-self") {
+        internalStep.dispatch = step.dispatch;
+    }
+    // Inputs land on nodeConfig so the blueprint mapper resolves
+    // $.<path> / js/... refs before SubworkflowNode reads them via
+    // `ctx.config[step.name]`.
+    const inlineInputs = isPlainObject(step.inputs) ? step.inputs : null;
+    const nodeConfig = inlineInputs ? { inputs: inlineInputs } : null;
     return { internalStep, nodeConfig };
 }
+const WAIT_NODE_REF = "@blokjs/wait";
+/**
+ * PR 4 — normalize a v2 wait step.
+ *
+ * Wait steps are intercepted by `RunnerSteps` BEFORE `step.process` is
+ * invoked (the wait IS the runner-level deferral); the resolved node is
+ * a no-op placeholder. The runner reads `waitForMs` / `waitUntil` off
+ * the InternalStep to decide how long to wait.
+ *
+ * `wait.for` (duration string or number) is parsed to milliseconds via
+ * `parseDuration`. `wait.until` is left as-is — the runner resolves
+ * $-proxy expressions against the live ctx at first-pass invocation.
+ */
+function normalizeWaitStep(step, index) {
+    const id = pickString(step.id);
+    if (!id) {
+        throw new Error(`[blok] WorkflowNormalizer: wait step at index ${index} is missing \`id\`.`);
+    }
+    const waitObj = step.wait;
+    const hasFor = waitObj.for !== undefined;
+    const hasUntil = waitObj.until !== undefined;
+    if (hasFor === hasUntil) {
+        throw new Error(`[blok] WorkflowNormalizer: wait step "${id}" must set exactly one of \`wait.for\` or \`wait.until\`.`);
+    }
+    let waitForMs;
+    let waitUntil;
+    if (hasFor) {
+        const raw = waitObj.for;
+        if (typeof raw === "number") {
+            waitForMs = raw;
+        }
+        else if (typeof raw === "string") {
+            // parseDuration may throw on invalid grammar — let it surface.
+            waitForMs = parseDuration(raw);
+        }
+        else {
+            throw new Error(`[blok] WorkflowNormalizer: wait step "${id}" has invalid \`wait.for\` (must be number ms or duration string).`);
+        }
+    }
+    if (hasUntil) {
+        const raw = waitObj.until;
+        if (typeof raw !== "number" && typeof raw !== "string") {
+            throw new Error(`[blok] WorkflowNormalizer: wait step "${id}" has invalid \`wait.until\` (must be number ms or string).`);
+        }
+        waitUntil = raw;
+    }
+    const ephemeral = step.ephemeral === true;
+    const as = pickString(step.as);
+    return {
+        name: id,
+        node: WAIT_NODE_REF,
+        type: "wait",
+        active: step.active === undefined ? true : step.active === true,
+        stop: step.stop === true,
+        as,
+        ephemeral,
+        waitForMs,
+        waitUntil,
+    };
+}
+// v0.5 forEach reference for the internal step's `node` field.
+const FOR_EACH_NODE_REF = "@blokjs/forEach";
+const LOOP_NODE_REF = "@blokjs/loop";
+const SWITCH_NODE_REF = "@blokjs/switch";
+const TRY_CATCH_NODE_REF = "@blokjs/tryCatch";
+/**
+ * Normalize a v0.5 forEach step into the internal shape. Inner steps
+ * are recursively normalized via `normalizeRegularStep` so they get
+ * their inputs inlined; their nodeConfigs bubble up via `innerNodes`
+ * for the top-level `internalNodes` map (same pattern as branch).
+ */
+function normalizeForEachStep(step, index) {
+    const id = pickString(step.id);
+    if (!id) {
+        throw new Error(`[blok] WorkflowNormalizer: forEach step at index ${index} is missing \`id\`.`);
+    }
+    const fe = step.forEach;
+    const inField = fe.in;
+    if (inField === undefined) {
+        throw new Error(`[blok] WorkflowNormalizer: forEach step "${id}" is missing \`in\`.`);
+    }
+    const as = pickString(fe.as);
+    if (!as) {
+        throw new Error(`[blok] WorkflowNormalizer: forEach step "${id}" is missing \`as\` (per-iteration variable name).`);
+    }
+    const mode = fe.mode === "parallel" ? "parallel" : "sequential";
+    const concurrency = typeof fe.concurrency === "number" && fe.concurrency > 0 ? fe.concurrency : 10;
+    const doSteps = Array.isArray(fe.do) ? fe.do : [];
+    // v0.6 Phase 3 — parallel forEach + wait composition warning. When
+    // a wait fires inside a parallel iteration, peer in-flight iterations
+    // are cancelled and re-launched on resume. Re-launches re-execute
+    // side effects unless inner steps have `idempotencyKey` (or are
+    // naturally side-effect-free). This is a per-author-contract gotcha
+    // (see `docs/c/devtools/parallel-foreach-wait-spec.mdx#author-contract`).
+    // Warn at load time so authors notice; don't BLOCK the workflow —
+    // some authors deliberately accept the retry behavior (e.g. pure
+    // fetches) or have their own idempotency layer.
+    if (mode === "parallel" && doStepsContainWait(doSteps)) {
+        const nonIdempotentInnerSteps = doSteps
+            .filter((s) => isPlainObject(s))
+            .filter((s) => !isWaitStep(s) && s.idempotencyKey === undefined)
+            .map((s) => pickString(s.id) ?? "(unnamed)");
+        if (nonIdempotentInnerSteps.length > 0) {
+            const stepList = nonIdempotentInnerSteps.map((n) => `"${n}"`).join(", ");
+            console.warn(`[blok][normalizer] forEach "${id}" runs in parallel mode with a wait inside the iteration body. When the wait fires, peer iterations are cancelled and re-launched from scratch on resume. Inner steps without an \`idempotencyKey\` will re-execute their side effects on each re-launch: ${stepList}. Add \`idempotencyKey\` to side-effecting steps, OR confirm the steps are side-effect-free. See docs/c/devtools/parallel-foreach-wait-spec.mdx for the author contract.`);
+        }
+    }
+    const { innerInternal, innerNodes } = normalizeStepBlock(doSteps);
+    const internalStep = {
+        name: id,
+        node: FOR_EACH_NODE_REF,
+        type: "forEach",
+        active: step.active === undefined ? true : Boolean(step.active),
+        stop: step.stop === true,
+    };
+    // nodeConfig — top-level `steps` triggers Configuration's
+    // isFlowWithProperties path which materializes into NodeBase[].
+    const nodeConfig = {
+        in: inField,
+        as,
+        mode,
+        concurrency,
+        steps: innerInternal,
+    };
+    return { internalStep, nodeConfig, innerNodes };
+}
+/**
+ * v0.6 Phase 3 — recognise a wait step in the raw (pre-normalization)
+ * shape. Two encodings: v0.5 `{ id, wait: {for|until} }` OR legacy
+ * `{ id, type: "wait", waitForMs|waitUntil }`. Used by
+ * `normalizeForEachStep` to emit the parallel + wait warning.
+ */
+function isWaitStep(step) {
+    if (isPlainObject(step.wait))
+        return true;
+    if (step.type === "wait")
+        return true;
+    return false;
+}
+/**
+ * v0.6 Phase 3 — scan the doSteps array (one level deep) for a wait
+ * step. Doesn't recurse into nested primitives (forEach inside forEach,
+ * tryCatch inside forEach) — those are out of scope for this warning;
+ * Phase 4 nested-primitive work will extend.
+ */
+function doStepsContainWait(doSteps) {
+    for (const s of doSteps) {
+        if (isPlainObject(s) && isWaitStep(s))
+            return true;
+    }
+    return false;
+}
+/**
+ * Normalize a v0.5 loop step into the internal shape. Same inner-step
+ * propagation pattern as forEach.
+ */
+function normalizeLoopStep(step, index) {
+    const id = pickString(step.id);
+    if (!id) {
+        throw new Error(`[blok] WorkflowNormalizer: loop step at index ${index} is missing \`id\`.`);
+    }
+    const lp = step.loop;
+    const whileExpr = pickString(lp.while);
+    if (!whileExpr) {
+        throw new Error(`[blok] WorkflowNormalizer: loop step "${id}" is missing \`while\` (the JS condition string).`);
+    }
+    const maxIterations = typeof lp.maxIterations === "number" && lp.maxIterations > 0 ? lp.maxIterations : 1000;
+    const doSteps = Array.isArray(lp.do) ? lp.do : [];
+    const { innerInternal, innerNodes } = normalizeStepBlock(doSteps);
+    const internalStep = {
+        name: id,
+        node: LOOP_NODE_REF,
+        type: "loop",
+        active: step.active === undefined ? true : Boolean(step.active),
+        stop: step.stop === true,
+    };
+    const nodeConfig = {
+        while: whileExpr,
+        maxIterations,
+        steps: innerInternal,
+    };
+    return { internalStep, nodeConfig, innerNodes };
+}
+/**
+ * Helper used by `normalizeSwitchStep` — converts an array of authored
+ * step shapes (the `do` block of a case or the `default` block) into
+ * resolved InternalSteps + a merged innerNodes map. Mirrors the inner
+ * loop in `normalizeForEachStep` / `normalizeLoopStep`, recursing into
+ * nested branch / forEach / loop / switch as needed.
+ */
+function normalizeStepBlock(rawSteps) {
+    const innerInternal = [];
+    const innerNodes = {};
+    for (let i = 0; i < rawSteps.length; i++) {
+        const s = rawSteps[i];
+        if (!isPlainObject(s))
+            continue;
+        if (isPlainObject(s.branch)) {
+            const { internalStep: nestedStep, nodeConfig: nestedConfig, innerNodes: nestedInner, } = normalizeBranchStep(s, i);
+            innerInternal.push(nestedStep);
+            innerNodes[nestedStep.name] = nestedConfig;
+            Object.assign(innerNodes, nestedInner);
+            continue;
+        }
+        if (isPlainObject(s.wait)) {
+            const nestedStep = normalizeWaitStep(s, i);
+            innerInternal.push(nestedStep);
+            continue;
+        }
+        if (isPlainObject(s.forEach)) {
+            const { internalStep: nestedStep, nodeConfig: nestedConfig, innerNodes: nestedInner, } = normalizeForEachStep(s, i);
+            innerInternal.push(nestedStep);
+            innerNodes[nestedStep.name] = nestedConfig;
+            Object.assign(innerNodes, nestedInner);
+            continue;
+        }
+        if (isPlainObject(s.loop)) {
+            const { internalStep: nestedStep, nodeConfig: nestedConfig, innerNodes: nestedInner, } = normalizeLoopStep(s, i);
+            innerInternal.push(nestedStep);
+            innerNodes[nestedStep.name] = nestedConfig;
+            Object.assign(innerNodes, nestedInner);
+            continue;
+        }
+        if (isPlainObject(s.switch)) {
+            const { internalStep: nestedStep, nodeConfig: nestedConfig, innerNodes: nestedInner, } = normalizeSwitchStep(s, i);
+            innerInternal.push(nestedStep);
+            innerNodes[nestedStep.name] = nestedConfig;
+            Object.assign(innerNodes, nestedInner);
+            continue;
+        }
+        if (isPlainObject(s.tryCatch)) {
+            const { internalStep: nestedStep, nodeConfig: nestedConfig, innerNodes: nestedInner, } = normalizeTryCatchStep(s, i);
+            innerInternal.push(nestedStep);
+            innerNodes[nestedStep.name] = nestedConfig;
+            Object.assign(innerNodes, nestedInner);
+            continue;
+        }
+        if (typeof s.subworkflow === "string") {
+            const { internalStep: nestedStep, nodeConfig: nestedConfig } = normalizeSubworkflowStep(s, i);
+            innerInternal.push(nestedStep);
+            if (nestedConfig)
+                innerNodes[nestedStep.name] = nestedConfig;
+            continue;
+        }
+        const { internalStep: regularStep, nodeConfig } = normalizeRegularStep(s, {}, i);
+        if (nodeConfig?.inputs) {
+            regularStep.inputs = nodeConfig.inputs;
+        }
+        if (nodeConfig)
+            innerNodes[regularStep.name] = nodeConfig;
+        innerInternal.push(regularStep);
+    }
+    return { innerInternal, innerNodes };
+}
+/**
+ * Normalize a v0.5 switch step into the internal shape. The cases and
+ * optional default each carry their own inner-step list — Configuration
+ * resolves them via a dedicated branch in `getNodes()` (mirrors the
+ * tryCatch path: each sub-block becomes its own resolved Flow).
+ *
+ * SwitchNode at run time reads the resolved nodeConfig:
+ *   { on, cases: [{when, steps: NodeBase[]}], default?: NodeBase[] }
+ * and runs the matched case (or default) through a child Runner.
+ */
+function normalizeSwitchStep(step, index) {
+    const id = pickString(step.id);
+    if (!id) {
+        throw new Error(`[blok] WorkflowNormalizer: switch step at index ${index} is missing \`id\`.`);
+    }
+    const sw = step.switch;
+    if (sw.on === undefined) {
+        throw new Error(`[blok] WorkflowNormalizer: switch step "${id}" is missing \`on\` (the value to match against).`);
+    }
+    const rawCases = Array.isArray(sw.cases) ? sw.cases : [];
+    if (rawCases.length === 0) {
+        throw new Error(`[blok] WorkflowNormalizer: switch step "${id}" has no \`cases\` (need at least one).`);
+    }
+    const cases = [];
+    const innerNodes = {};
+    for (let ci = 0; ci < rawCases.length; ci++) {
+        const c = rawCases[ci];
+        if (!isPlainObject(c)) {
+            throw new Error(`[blok] WorkflowNormalizer: switch step "${id}" cases[${ci}] is not an object.`);
+        }
+        const cobj = c;
+        if (cobj.when === undefined) {
+            throw new Error(`[blok] WorkflowNormalizer: switch step "${id}" cases[${ci}] is missing \`when\`.`);
+        }
+        const doSteps = Array.isArray(cobj.do) ? cobj.do : [];
+        const { innerInternal, innerNodes: caseInner } = normalizeStepBlock(doSteps);
+        Object.assign(innerNodes, caseInner);
+        cases.push({ when: cobj.when, steps: innerInternal });
+    }
+    let defaultSteps;
+    if (Array.isArray(sw.default)) {
+        const { innerInternal, innerNodes: defaultInner } = normalizeStepBlock(sw.default);
+        Object.assign(innerNodes, defaultInner);
+        defaultSteps = innerInternal;
+    }
+    const internalStep = {
+        name: id,
+        node: SWITCH_NODE_REF,
+        type: "switch",
+        active: step.active === undefined ? true : Boolean(step.active),
+        stop: step.stop === true,
+    };
+    const nodeConfig = {
+        on: sw.on,
+        cases,
+        ...(defaultSteps !== undefined ? { default: defaultSteps } : {}),
+    };
+    return { internalStep, nodeConfig, innerNodes };
+}
+/**
+ * Normalize a v0.5 tryCatch step into the internal shape. Each of `try`,
+ * `catch`, and optional `finally` carries its own inner-step list —
+ * Configuration resolves them via a dedicated branch in `getNodes()` so
+ * each block becomes its own resolved Flow (steps: NodeBase[]).
+ *
+ * TryCatchNode at run time reads the resolved nodeConfig:
+ *   { try: NodeBase[], catch: NodeBase[], finally?: NodeBase[] }
+ * and runs them according to JS-like try/catch/finally semantics.
+ */
+function normalizeTryCatchStep(step, index) {
+    const id = pickString(step.id);
+    if (!id) {
+        throw new Error(`[blok] WorkflowNormalizer: tryCatch step at index ${index} is missing \`id\`.`);
+    }
+    const tc = step.tryCatch;
+    if (!Array.isArray(tc.try) || tc.try.length === 0) {
+        throw new Error(`[blok] WorkflowNormalizer: tryCatch step "${id}" requires a non-empty \`try\` block.`);
+    }
+    if (!Array.isArray(tc.catch) || tc.catch.length === 0) {
+        throw new Error(`[blok] WorkflowNormalizer: tryCatch step "${id}" requires a non-empty \`catch\` block.`);
+    }
+    const innerNodes = {};
+    const tryBlock = normalizeStepBlock(tc.try);
+    Object.assign(innerNodes, tryBlock.innerNodes);
+    const catchBlock = normalizeStepBlock(tc.catch);
+    Object.assign(innerNodes, catchBlock.innerNodes);
+    let finallyBlock;
+    if (Array.isArray(tc.finally)) {
+        finallyBlock = normalizeStepBlock(tc.finally);
+        Object.assign(innerNodes, finallyBlock.innerNodes);
+    }
+    const internalStep = {
+        name: id,
+        node: TRY_CATCH_NODE_REF,
+        type: "tryCatch",
+        active: step.active === undefined ? true : Boolean(step.active),
+        stop: step.stop === true,
+    };
+    const nodeConfig = {
+        try: tryBlock.innerInternal,
+        catch: catchBlock.innerInternal,
+        ...(finallyBlock !== undefined ? { finally: finallyBlock.innerInternal } : {}),
+    };
+    return { internalStep, nodeConfig, innerNodes };
+}
 function normalizeTrigger(rawTrigger, sourcePath) {
     if (!isPlainObject(rawTrigger))
         return {};
@@ -301,4 +874,63 @@ function pickString(value) {
 export function _resetWildcardWarningCache() {
     _wildcardWarnedFiles = new Set();
 }
+/**
+ * `set_var` is no longer accepted on workflow steps. Walk the raw step
+ * tree (top-level steps + every nested sub-pipeline) and throw with a
+ * migration hint on the first occurrence. The walk handles branch,
+ * forEach, loop, switch, and tryCatch sub-pipelines so a rejected
+ * field at any depth is caught at load time rather than after the
+ * partial-normalization point.
+ */
+function assertNoSetVar(steps, sourcePath) {
+    for (const raw of steps) {
+        if (!isPlainObject(raw))
+            continue;
+        const step = raw;
+        if (Object.prototype.hasOwnProperty.call(step, "set_var")) {
+            const id = pickString(step.id) ?? pickString(step.name) ?? "<unnamed>";
+            const suffix = sourcePath ? ` (file: ${sourcePath})` : "";
+            throw new Error(`[blok] WorkflowNormalizer: step "${id}" uses \`set_var\`, which was removed in v0.5. Replace \`set_var: false\` with \`ephemeral: true\` and drop \`set_var: true\` (v2 default-stores every step's output). Run \`blokctl migrate workflows\` to convert v1 workflows automatically.${suffix}`);
+        }
+        // Recurse into nested sub-pipelines.
+        if (isPlainObject(step.branch)) {
+            const branch = step.branch;
+            if (Array.isArray(branch.then))
+                assertNoSetVar(branch.then, sourcePath);
+            if (Array.isArray(branch.else))
+                assertNoSetVar(branch.else, sourcePath);
+        }
+        if (isPlainObject(step.forEach)) {
+            const fe = step.forEach;
+            if (Array.isArray(fe.do))
+                assertNoSetVar(fe.do, sourcePath);
+        }
+        if (isPlainObject(step.loop)) {
+            const lp = step.loop;
+            if (Array.isArray(lp.do))
+                assertNoSetVar(lp.do, sourcePath);
+        }
+        if (isPlainObject(step.switch)) {
+            const sw = step.switch;
+            if (Array.isArray(sw.cases)) {
+                for (const c of sw.cases) {
+                    if (isPlainObject(c) && Array.isArray(c.do)) {
+                        assertNoSetVar(c.do, sourcePath);
+                    }
+                }
+            }
+            if (Array.isArray(sw.default))
+                assertNoSetVar(sw.default, sourcePath);
+        }
+        if (isPlainObject(step.tryCatch)) {
+            const tc = step.tryCatch;
+            if (Array.isArray(tc.try))
+                assertNoSetVar(tc.try, sourcePath);
+            if (Array.isArray(tc.catch))
+                assertNoSetVar(tc.catch, sourcePath);
+            if (Array.isArray(tc.finally))
+                assertNoSetVar(tc.finally, sourcePath);
+        }
+    }
+}
 //# sourceMappingURL=WorkflowNormalizer.js.map