@blokjs/runner 0.2.1 → 0.4.0

package/dist/workflow/PersistenceHelper.d.ts

@@ -0,0 +1,46 @@
+import type { Context } from "@blokjs/shared";
+/**
+ * The shape of a step instance the helper needs to make a persistence
+ * decision. Both `BlokService` and `RuntimeAdapterNode` satisfy this.
+ *
+ * Read-only — the helper never mutates the step.
+ */
+export interface PersistableStep {
+    /** Step's stable identifier (today's `name` field on NodeBase). */
+    readonly name: string;
+    /** Optional alias — store at `state[as]` instead of `state[name]`. */
+    readonly as?: string;
+    /** When true, shallow-merge result.data keys into state. */
+    readonly spread?: boolean;
+    /** When true, skip persistence entirely. */
+    readonly ephemeral?: boolean;
+    /**
+     * Legacy v1 flag. `false` is interpreted as `ephemeral: true`. `true`
+     * is a no-op (the new default already persists).
+     */
+    readonly set_var?: boolean;
+}
+/**
+ * The shape of an execution result the helper needs to read. Both
+ * `ResponseContext` and `ExecutionResult` carry `.data`.
+ */
+export interface PersistableResult {
+    readonly data?: unknown;
+    readonly success?: boolean;
+}
+/**
+ * Apply a step's output to `ctx.state` according to the step's persistence
+ * knobs.
+ *
+ * **Rules** (in order):
+ * 1. `ephemeral: true` → no-op. Output is only available via `ctx.prev`.
+ * 2. Legacy `set_var: false` → treated as `ephemeral: true` (back-compat).
+ * 3. `spread: true` AND `data` is a plain object → shallow-merge data's
+ *    top-level keys into `ctx.state`.
+ * 4. Default → `ctx.state[as ?? name] = data`.
+ *
+ * Mutates `ctx.state` in place. Always safe to call (no-op on missing data
+ * unless `spread` is set, which is an authoring-time error to combine with
+ * non-object output and is detected at workflow load time, not here).
+ */
+export declare function applyStepOutput(ctx: Context, step: PersistableStep, result: PersistableResult): void;

package/dist/workflow/PersistenceHelper.js

@@ -0,0 +1,57 @@
+/**
+ * Apply a step's output to `ctx.state` according to the step's persistence
+ * knobs.
+ *
+ * **Rules** (in order):
+ * 1. `ephemeral: true` → no-op. Output is only available via `ctx.prev`.
+ * 2. Legacy `set_var: false` → treated as `ephemeral: true` (back-compat).
+ * 3. `spread: true` AND `data` is a plain object → shallow-merge data's
+ *    top-level keys into `ctx.state`.
+ * 4. Default → `ctx.state[as ?? name] = data`.
+ *
+ * Mutates `ctx.state` in place. Always safe to call (no-op on missing data
+ * unless `spread` is set, which is an authoring-time error to combine with
+ * non-object output and is detected at workflow load time, not here).
+ */
+export function applyStepOutput(ctx, step, result) {
+    // Rule 1 & 2 — opt-out paths
+    if (step.ephemeral === true)
+        return;
+    if (step.set_var === false)
+        return;
+    // Defensive: ensure state exists (TriggerBase initializes it, but
+    // some legacy code paths construct ctx by hand).
+    if (!ctx.state || typeof ctx.state !== "object") {
+        ctx.state = {};
+    }
+    const state = ctx.state;
+    const data = result?.data;
+    // Rule 3 — spread
+    if (step.spread === true) {
+        if (isPlainObject(data)) {
+            Object.assign(state, data);
+        }
+        // Non-object data with `spread: true` is silently ignored at
+        // runtime. The workflow normalizer warns at load time so the
+        // author is aware.
+        return;
+    }
+    // Rule 4 — default-store
+    if (data === undefined)
+        return;
+    const key = step.as ?? step.name;
+    if (!key)
+        return; // defensive: anonymous step (shouldn't happen post-normalizer)
+    state[key] = data;
+}
+function isPlainObject(value) {
+    if (value === null || value === undefined)
+        return false;
+    if (typeof value !== "object")
+        return false;
+    if (Array.isArray(value))
+        return false;
+    const proto = Object.getPrototypeOf(value);
+    return proto === null || proto === Object.prototype;
+}
+//# sourceMappingURL=PersistenceHelper.js.map

package/dist/workflow/PersistenceHelper.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"PersistenceHelper.js","sourceRoot":"","sources":["../../src/workflow/PersistenceHelper.ts"],"names":[],"mappings":"AAiCA;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,eAAe,CAAC,GAAY,EAAE,IAAqB,EAAE,MAAyB;IAC7F,6BAA6B;IAC7B,IAAI,IAAI,CAAC,SAAS,KAAK,IAAI;QAAE,OAAO;IACpC,IAAI,IAAI,CAAC,OAAO,KAAK,KAAK;QAAE,OAAO;IAEnC,kEAAkE;IAClE,iDAAiD;IACjD,IAAI,CAAC,GAAG,CAAC,KAAK,IAAI,OAAO,GAAG,CAAC,KAAK,KAAK,QAAQ,EAAE,CAAC;QAChD,GAA0C,CAAC,KAAK,GAAG,EAAE,CAAC;IACxD,CAAC;IAED,MAAM,KAAK,GAAG,GAAG,CAAC,KAAgC,CAAC;IACnD,MAAM,IAAI,GAAG,MAAM,EAAE,IAAI,CAAC;IAE1B,kBAAkB;IAClB,IAAI,IAAI,CAAC,MAAM,KAAK,IAAI,EAAE,CAAC;QAC1B,IAAI,aAAa,CAAC,IAAI,CAAC,EAAE,CAAC;YACzB,MAAM,CAAC,MAAM,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;QAC5B,CAAC;QACD,6DAA6D;QAC7D,6DAA6D;QAC7D,mBAAmB;QACnB,OAAO;IACR,CAAC;IAED,yBAAyB;IACzB,IAAI,IAAI,KAAK,SAAS;QAAE,OAAO;IAC/B,MAAM,GAAG,GAAG,IAAI,CAAC,EAAE,IAAI,IAAI,CAAC,IAAI,CAAC;IACjC,IAAI,CAAC,GAAG;QAAE,OAAO,CAAC,+DAA+D;IACjF,KAAK,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC;AACnB,CAAC;AAED,SAAS,aAAa,CAAC,KAAc;IACpC,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,KAAK,CAAC;IACxD,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IAC5C,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IACvC,MAAM,KAAK,GAAG,MAAM,CAAC,cAAc,CAAC,KAAK,CAAC,CAAC;IAC3C,OAAO,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,MAAM,CAAC,SAAS,CAAC;AACrD,CAAC"}

package/dist/workflow/WorkflowNormalizer.d.ts

@@ -0,0 +1,79 @@
+interface RetryConfig {
+    maxAttempts: number;
+    minTimeoutInMs?: number;
+    maxTimeoutInMs?: number;
+    factor?: number;
+}
+interface InternalStep {
+    name: string;
+    node: string;
+    type: string;
+    active?: boolean;
+    stop?: boolean;
+    set_var?: boolean;
+    as?: string;
+    spread?: boolean;
+    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 {
+    inputs?: Record<string, unknown>;
+    conditions?: InternalCondition[];
+    steps?: InternalStep[];
+    [key: string]: unknown;
+}
+interface InternalCondition {
+    type: "if" | "else";
+    condition?: string;
+    steps: InternalStep[];
+}
+export interface InternalWorkflow {
+    name: string;
+    version: string;
+    description?: string;
+    trigger: Record<string, unknown>;
+    steps: InternalStep[];
+    nodes: Record<string, InternalNodeConfig>;
+}
+/**
+ * Convert any accepted workflow shape into the canonical internal shape.
+ *
+ * Mutates a deep copy — the caller's object is never modified.
+ *
+ * @param raw - parsed workflow object (from JSON.parse, dynamic import,
+ *              or the v1 builder pipeline)
+ * @param sourcePath - optional path used in deprecation warnings
+ */
+export declare function normalizeWorkflow(raw: unknown, sourcePath?: string): InternalWorkflow;
+/**
+ * Test-only — reset the per-process wildcard warning cache.
+ *
+ * @internal
+ */
+export declare function _resetWildcardWarningCache(): void;
+export {};

package/dist/workflow/WorkflowNormalizer.js

@@ -0,0 +1,486 @@
+import { parseDuration } from "@blokjs/helper";
+/**
+ * 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.
+ */
+const IF_ELSE_NODE_REF = "@blokjs/if-else";
+let _wildcardWarnedFiles = new Set();
+/**
+ * Convert any accepted workflow shape into the canonical internal shape.
+ *
+ * Mutates a deep copy — the caller's object is never modified.
+ *
+ * @param raw - parsed workflow object (from JSON.parse, dynamic import,
+ *              or the v1 builder pipeline)
+ * @param sourcePath - optional path used in deprecation warnings
+ */
+export function normalizeWorkflow(raw, sourcePath) {
+    if (!isPlainObject(raw)) {
+        const suffix = sourcePath ? ` (file: ${sourcePath})` : "";
+        throw new Error(`[blok] WorkflowNormalizer: expected an object, got ${typeof raw}${suffix}`);
+    }
+    // Unwrap v2 builder envelopes — `workflow()` returns `{_blokV2: true, _config: {...}}`.
+    // The legacy `Workflow()` builder also produces a `_config` field; both shapes
+    // carry their workflow definition under that key.
+    let wf = raw;
+    if (wf._blokV2 === true && isPlainObject(wf._config)) {
+        wf = wf._config;
+    }
+    else if (isPlainObject(wf._config) && wf.name === undefined && wf.steps === undefined) {
+        // Legacy builder shape — same unwrap.
+        wf = wf._config;
+    }
+    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;
+    // --- Trigger normalization (method "*" → "ANY") ---
+    const trigger = normalizeTrigger(wf.trigger, sourcePath);
+    // --- Steps normalization ---
+    const stepsInput = Array.isArray(wf.steps) ? wf.steps : [];
+    const nodesInput = isPlainObject(wf.nodes) ? wf.nodes : {};
+    const internalSteps = [];
+    const internalNodes = {};
+    for (let i = 0; i < stepsInput.length; i++) {
+        const rawStep = stepsInput[i];
+        if (!isPlainObject(rawStep))
+            continue;
+        const step = rawStep;
+        // v2 branch — { id, branch: { when, then, else? } }
+        if (isPlainObject(step.branch)) {
+            const { internalStep, nodeConfig } = normalizeBranchStep(step, i);
+            internalSteps.push(internalStep);
+            internalNodes[internalStep.name] = nodeConfig;
+            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;
+        }
+        // v2 regular — { id, use, inputs?, as?, spread?, ephemeral?, ... }
+        // or v1 regular — { name, node, type } + nodes[name].inputs
+        const { internalStep, nodeConfig } = normalizeRegularStep(step, nodesInput, i);
+        internalSteps.push(internalStep);
+        if (nodeConfig)
+            internalNodes[internalStep.name] = nodeConfig;
+    }
+    // --- Carry over any v1 nodes that didn't have a matching step ---
+    // (rare, but possible for legacy workflows with helper sub-flows
+    // declared at the top level)
+    for (const key of Object.keys(nodesInput)) {
+        if (internalNodes[key] !== undefined)
+            continue;
+        const value = nodesInput[key];
+        if (isPlainObject(value)) {
+            internalNodes[key] = value;
+        }
+    }
+    return {
+        name,
+        version,
+        description,
+        trigger,
+        steps: internalSteps,
+        nodes: internalNodes,
+    };
+}
+// =============================================================================
+// Internals
+// =============================================================================
+function normalizeRegularStep(step, nodesInput, index) {
+    // Identity — `id` (v2) wins, fallback to `name` (v1).
+    const id = pickString(step.id) ?? pickString(step.name);
+    if (!id) {
+        throw new Error(`[blok] WorkflowNormalizer: step at index ${index} has neither \`id\` (v2) nor \`name\` (v1).`);
+    }
+    // Node reference — `use` (v2) wins, fallback to `node` (v1).
+    const nodeRef = pickString(step.use) ?? pickString(step.node);
+    if (!nodeRef) {
+        throw new Error(`[blok] WorkflowNormalizer: step "${id}" has neither \`use\` (v2) nor \`node\` (v1).`);
+    }
+    // Type — explicit `type` wins; otherwise inferred from the node ref.
+    const explicitType = pickString(step.type);
+    const type = explicitType ?? inferStepType(nodeRef);
+    // Inputs — v2 inlines on the step; v1 lives at workflow.nodes[name].inputs.
+    const inlineInputs = isPlainObject(step.inputs) ? step.inputs : null;
+    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;
+    const as = pickString(step.as);
+    const spread = step.spread === true;
+    // `as` and `spread` are mutually exclusive — caught at schema level too,
+    // repeated here so JSON workflows that bypass Zod still fail loudly.
+    if (as && spread) {
+        throw new Error(`[blok] WorkflowNormalizer: step "${id}" sets both \`as\` and \`spread\` — they are mutually exclusive.`);
+    }
+    const internalStep = {
+        name: id,
+        node: nodeRef,
+        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) {
+        nodeConfig = { inputs };
+        // Carry over any legacy v1 node-config fields that aren't `inputs`
+        // (some workflows attach `outputs`, `mapper`, etc.).
+        if (v1NodeConfig) {
+            for (const k of Object.keys(v1NodeConfig)) {
+                if (k === "inputs")
+                    continue;
+                nodeConfig[k] = v1NodeConfig[k];
+            }
+        }
+    }
+    else if (v1NodeConfig) {
+        nodeConfig = { ...v1NodeConfig };
+    }
+    return { internalStep, nodeConfig };
+}
+function normalizeBranchStep(step, index) {
+    const id = pickString(step.id);
+    if (!id) {
+        throw new Error(`[blok] WorkflowNormalizer: branch step at index ${index} is missing \`id\`.`);
+    }
+    const branch = step.branch;
+    const when = pickString(branch.when);
+    if (!when) {
+        throw new Error(`[blok] WorkflowNormalizer: branch step "${id}" is missing \`when\` (must be a non-empty string).`);
+    }
+    const thenSteps = Array.isArray(branch.then) ? branch.then : [];
+    const elseSteps = Array.isArray(branch.else) ? branch.else : [];
+    // Normalize each branch's nested steps recursively. Use empty
+    // `nodesInput` because v2 branches inline `inputs` on each nested step.
+    const thenInternal = [];
+    const elseInternal = [];
+    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);
+            continue;
+        }
+        const { internalStep, 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;
+        }
+        thenInternal.push(internalStep);
+    }
+    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);
+            continue;
+        }
+        const { internalStep, nodeConfig } = normalizeRegularStep(s, {}, i);
+        if (nodeConfig?.inputs) {
+            internalStep.inputs = nodeConfig.inputs;
+        }
+        elseInternal.push(internalStep);
+    }
+    const conditions = [{ type: "if", condition: when, steps: thenInternal }];
+    if (elseInternal.length > 0) {
+        conditions.push({ type: "else", steps: elseInternal });
+    }
+    const internalStep = {
+        name: id,
+        node: IF_ELSE_NODE_REF,
+        type: "module",
+        active: step.active === undefined ? true : Boolean(step.active),
+        stop: step.stop === true,
+        flow: true,
+    };
+    const nodeConfig = { conditions };
+    return { internalStep, nodeConfig };
+}
+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;
+    }
+    // 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,
+    };
+}
+function normalizeTrigger(rawTrigger, sourcePath) {
+    if (!isPlainObject(rawTrigger))
+        return {};
+    const out = {};
+    for (const [kind, cfg] of Object.entries(rawTrigger)) {
+        if (kind === "http" && isPlainObject(cfg)) {
+            const httpCfg = { ...cfg };
+            if (httpCfg.method === "*") {
+                httpCfg.method = "ANY";
+                warnWildcardOnce(sourcePath);
+            }
+            out[kind] = httpCfg;
+        }
+        else {
+            out[kind] = cfg;
+        }
+    }
+    return out;
+}
+function inferStepType(nodeRef) {
+    // Explicit runtime prefixes — `runtime.python3:my-node` style.
+    if (nodeRef.startsWith("runtime.")) {
+        const dotIdx = nodeRef.indexOf(":");
+        if (dotIdx > 0)
+            return nodeRef.slice(0, dotIdx);
+        return nodeRef;
+    }
+    // Default to module — covers `@blokjs/*` and most user-defined nodes.
+    return "module";
+}
+function warnWildcardOnce(sourcePath) {
+    const key = sourcePath ?? "<unknown>";
+    if (_wildcardWarnedFiles.has(key))
+        return;
+    _wildcardWarnedFiles.add(key);
+    console.warn(`[blok] trigger.http.method "*" is deprecated; use "ANY" instead. (workflow: ${key}). Run \`blokctl migrate workflows\` to update.`);
+}
+function isPlainObject(value) {
+    if (value === null || value === undefined)
+        return false;
+    if (typeof value !== "object")
+        return false;
+    if (Array.isArray(value))
+        return false;
+    const proto = Object.getPrototypeOf(value);
+    return proto === null || proto === Object.prototype;
+}
+function pickString(value) {
+    return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+/**
+ * Test-only — reset the per-process wildcard warning cache.
+ *
+ * @internal
+ */
+export function _resetWildcardWarningCache() {
+    _wildcardWarnedFiles = new Set();
+}
+//# sourceMappingURL=WorkflowNormalizer.js.map