@blokjs/runner 0.2.2 → 0.6.0

package/dist/Configuration.js

@@ -1,12 +1,16 @@
+// import { NodeBase } from "@blokjs/shared";
+// import { z } from "zod";
+import { sep as pathSep, resolve as resolvePath } from "node:path";
+import { tryParseDuration } from "@blokjs/helper";
 import ConfigurationResolver from "./ConfigurationResolver";
 import RunnerNode from "./RunnerNode";
 import { RuntimeAdapterNode } from "./RuntimeAdapterNode";
 import { RuntimeRegistry } from "./RuntimeRegistry";
-import { HttpRuntimeAdapter } from "./adapters/HttpRuntimeAdapter";
 import { NodeJsRuntimeAdapter } from "./adapters/NodeJsRuntimeAdapter";
 import { GrpcRuntimeAdapter } from "./adapters/grpc/GrpcRuntimeAdapter";
 import { DEFAULT_GRPC_PORTS, GRPC_DEFAULTS } from "./adapters/grpc/types";
-import { isLoopbackHost, isStreamLogsEnabled, isStrictTlsEnabled, loadTlsConfigForKind, resolveHealthCheckFailureThreshold, resolveHealthCheckIntervalMs, resolveTransportForKind, } from "./adapters/transport";
+import { assertGrpcOnlyTransport, isLoopbackHost, isStreamLogsEnabled, isStrictTlsEnabled, loadTlsConfigForKind, resolveHealthCheckFailureThreshold, resolveHealthCheckIntervalMs, } from "./adapters/transport";
+import { RuntimeVersionValidator } from "./version/RuntimeVersionValidator";
 export default class Configuration {
     workflow = {};
     name;
@@ -14,6 +18,14 @@ export default class Configuration {
     steps;
     nodes;
     trigger;
+    /**
+     * v0.5.2 — workflow-level middleware chain. Populated from the
+     * normalized workflow's `appliedMiddleware` field. HTTP and Worker
+     * triggers prepend this list to their own `trigger.<kind>.middleware`
+     * before invoking the chain, so workflow-level entries run BEFORE
+     * trigger-level entries on every request.
+     */
+    appliedMiddleware;
     static loaded_nodes = {};
     globalOptions;
     constructor() {
@@ -22,87 +34,40 @@ export default class Configuration {
         this.version = "";
         this.name = "";
         this.trigger = {};
+        this.appliedMiddleware = [];
         this.initializeRuntimeRegistry();
     }
     /**
      * Initialize the RuntimeRegistry with built-in adapters.
      *
-     * Registers `NodeJsRuntimeAdapter` for in-process JS nodes, then for each
-     * SDK language picks `HttpRuntimeAdapter` or `GrpcRuntimeAdapter` based on
-     * {@link resolveTransportForKind} (env-driven). This is the single point
-     * of transport selection — no other file branches on transport.
+     * Registers `NodeJsRuntimeAdapter` for in-process JS nodes, then a
+     * `GrpcRuntimeAdapter` per SDK language. gRPC is the sole transport
+     * since v0.5 — `assertGrpcOnlyTransport` throws if the operator still
+     * has `RUNTIME_TRANSPORT=http` set.
      */
     initializeRuntimeRegistry() {
+        assertGrpcOnlyTransport();
         const registry = RuntimeRegistry.getInstance();
         if (!registry.has("nodejs")) {
             registry.register(new NodeJsRuntimeAdapter());
         }
         const sdkLanguages = [
-            {
-                kind: "go",
-                hostEnv: "RUNTIME_GO_HOST",
-                httpPortEnv: "RUNTIME_GO_PORT",
-                grpcPortEnv: "RUNTIME_GO_GRPC_PORT",
-                defaultHttpPort: 9001,
-            },
-            {
-                kind: "rust",
-                hostEnv: "RUNTIME_RUST_HOST",
-                httpPortEnv: "RUNTIME_RUST_PORT",
-                grpcPortEnv: "RUNTIME_RUST_GRPC_PORT",
-                defaultHttpPort: 9002,
-            },
-            {
-                kind: "java",
-                hostEnv: "RUNTIME_JAVA_HOST",
-                httpPortEnv: "RUNTIME_JAVA_PORT",
-                grpcPortEnv: "RUNTIME_JAVA_GRPC_PORT",
-                defaultHttpPort: 9003,
-            },
-            {
-                kind: "csharp",
-                hostEnv: "RUNTIME_CSHARP_HOST",
-                httpPortEnv: "RUNTIME_CSHARP_PORT",
-                grpcPortEnv: "RUNTIME_CSHARP_GRPC_PORT",
-                defaultHttpPort: 9004,
-            },
-            {
-                kind: "php",
-                hostEnv: "RUNTIME_PHP_HOST",
-                httpPortEnv: "RUNTIME_PHP_PORT",
-                grpcPortEnv: "RUNTIME_PHP_GRPC_PORT",
-                defaultHttpPort: 9005,
-            },
-            {
-                kind: "ruby",
-                hostEnv: "RUNTIME_RUBY_HOST",
-                httpPortEnv: "RUNTIME_RUBY_PORT",
-                grpcPortEnv: "RUNTIME_RUBY_GRPC_PORT",
-                defaultHttpPort: 9006,
-            },
-            {
-                kind: "python3",
-                hostEnv: "RUNTIME_PYTHON3_HOST",
-                httpPortEnv: "RUNTIME_PYTHON3_PORT",
-                grpcPortEnv: "RUNTIME_PYTHON3_GRPC_PORT",
-                defaultHttpPort: 9007,
-            },
+            { kind: "go", hostEnv: "RUNTIME_GO_HOST", grpcPortEnv: "RUNTIME_GO_GRPC_PORT" },
+            { kind: "rust", hostEnv: "RUNTIME_RUST_HOST", grpcPortEnv: "RUNTIME_RUST_GRPC_PORT" },
+            { kind: "java", hostEnv: "RUNTIME_JAVA_HOST", grpcPortEnv: "RUNTIME_JAVA_GRPC_PORT" },
+            { kind: "csharp", hostEnv: "RUNTIME_CSHARP_HOST", grpcPortEnv: "RUNTIME_CSHARP_GRPC_PORT" },
+            { kind: "php", hostEnv: "RUNTIME_PHP_HOST", grpcPortEnv: "RUNTIME_PHP_GRPC_PORT" },
+            { kind: "ruby", hostEnv: "RUNTIME_RUBY_HOST", grpcPortEnv: "RUNTIME_RUBY_GRPC_PORT" },
+            { kind: "python3", hostEnv: "RUNTIME_PYTHON3_HOST", grpcPortEnv: "RUNTIME_PYTHON3_GRPC_PORT" },
         ];
         for (const lang of sdkLanguages) {
             if (registry.has(lang.kind))
                 continue;
-            const transport = resolveTransportForKind(lang.kind);
             const host = process.env[lang.hostEnv] || "localhost";
-            const adapter = transport === "grpc"
-                ? this.buildGrpcAdapter(lang.kind, host, lang.grpcPortEnv)
-                : this.buildHttpAdapter(lang.kind, host, lang.httpPortEnv, lang.defaultHttpPort);
+            const adapter = this.buildGrpcAdapter(lang.kind, host, lang.grpcPortEnv);
             registry.register(adapter);
         }
     }
-    buildHttpAdapter(kind, host, portEnv, defaultPort) {
-        const port = process.env[portEnv] ? Number.parseInt(process.env[portEnv], 10) : defaultPort;
-        return new HttpRuntimeAdapter(kind, host, port);
-    }
     buildGrpcAdapter(kind, host, portEnv) {
         const defaultPort = DEFAULT_GRPC_PORTS[kind];
         const port = process.env[portEnv] ? Number.parseInt(process.env[portEnv], 10) : defaultPort;
@@ -156,9 +121,17 @@ export default class Configuration {
         if (preloaded !== undefined) {
             // Boot-time scan path — workflow object already loaded, just
             // normalize it through the same v1→v2 pipeline as disk-loaded
-            // workflows.
+            // workflows. **Deep-clone first** so per-request mutations
+            // (`NodeBase.blueprintMapper` → `mapper.replaceObjectStrings`
+            // resolves `js/...` expressions in place) don't bleed across
+            // requests by baking the first request's resolved values into
+            // the shared route-table workflow object. JSON-clone is safe:
+            // workflow definitions are pure data, and helper proxies like
+            // `$.req.body` serialize to their `js/...` string form via
+            // `Symbol.toPrimitive` / `toJSON`.
             const { normalizeWorkflow } = await import("./workflow/WorkflowNormalizer");
-            this.workflow = normalizeWorkflow(preloaded, workflowNameInPath);
+            const fresh = JSON.parse(JSON.stringify(preloaded));
+            this.workflow = normalizeWorkflow(fresh, workflowNameInPath);
         }
         else {
             const resolver = new ConfigurationResolver(opts);
@@ -173,6 +146,11 @@ export default class Configuration {
         this.version = this.workflow.version;
         this.name = this.workflow.name;
         this.trigger = this.workflow.trigger;
+        // Workflow-level middleware list (v0.5.2). Lives on the normalized
+        // workflow as `appliedMiddleware` — see WorkflowNormalizer for the
+        // schema overload (`middleware: string[]` at the top level).
+        const wfWithApplied = this.workflow;
+        this.appliedMiddleware = Array.isArray(wfWithApplied.appliedMiddleware) ? wfWithApplied.appliedMiddleware : [];
     }
     async getSteps(blueprint_steps) {
         const nodes = [];
@@ -191,13 +169,6 @@ export default class Configuration {
             node.name = step.name;
             node.active = step.active !== undefined ? step.active : true;
             node.stop = step.stop !== undefined ? step.stop : false;
-            // Pass `set_var` through verbatim — DO NOT default to `false`. The
-            // `false` value short-circuits PersistenceHelper.applyStepOutput
-            // and silently disables v2's default-store rule. Legacy v1
-            // workflows that explicitly set `set_var: false` are normalized
-            // to `ephemeral: true` upstream by WorkflowNormalizer.
-            if (step.set_var !== undefined)
-                node.set_var = step.set_var;
             // V2 persistence knobs — read by PersistenceHelper.applyStepOutput.
             // `as` renames the state key; `spread` flattens result.data into
             // state; `ephemeral: true` skips persistence entirely. Default
@@ -205,6 +176,27 @@ export default class Configuration {
             node.as = step.as;
             node.spread = step.spread === true;
             node.ephemeral = step.ephemeral === true;
+            // V2 idempotency cache + retry knobs — read by RunnerSteps before
+            // delegating to step.process(). Caching layers ABOVE
+            // PersistenceHelper; retry wraps the same call site.
+            const v2Idem = step;
+            if (v2Idem.idempotencyKey !== undefined)
+                node.idempotencyKey = v2Idem.idempotencyKey;
+            if (v2Idem.idempotencyKeyTTL !== undefined)
+                node.idempotencyKeyTTL = v2Idem.idempotencyKeyTTL;
+            if (v2Idem.retry !== undefined)
+                node.retry = v2Idem.retry;
+            // V2 sub-workflow knobs — read by SubworkflowNode at run time.
+            if (v2Idem.subworkflow !== undefined)
+                node.subworkflow = v2Idem.subworkflow;
+            if (v2Idem.wait !== undefined)
+                node.wait = v2Idem.wait;
+            // Tier 2 quick-wins — parse maxDuration string/number → ms.
+            if (v2Idem.maxDuration !== undefined) {
+                const parsed = tryParseDuration(v2Idem.maxDuration);
+                if (parsed !== null)
+                    node.maxDurationMs = parsed;
+            }
             nodes.push(node);
         }
         return nodes;
@@ -222,10 +214,17 @@ export default class Configuration {
                 const hasOutputs = currentNode.mapper !== undefined;
                 if (isFlowWithProperties) {
                     const steps = currentNode.steps;
-                    nodes[key] = await this.getFlow(steps);
-                    const copyBlueprintNode = { ...workflow_nodes[key] };
-                    copyBlueprintNode.steps = [];
-                    nodes[key] = { ...nodes[key], ...copyBlueprintNode };
+                    const flow = await this.getFlow(steps);
+                    // Spread the metadata FIRST, then the resolved flow — this
+                    // keeps the resolved NodeBase[] in `flow.steps` and lets
+                    // the metadata (e.g. forEach's in/as/mode/concurrency,
+                    // loop's while/maxIterations) survive on the merged config.
+                    // The earlier code spread metadata AFTER flow with a
+                    // `copyBlueprintNode.steps = []` reset, which clobbered
+                    // the resolved steps array — broken for any node config
+                    // that needed both inner steps AND sibling fields.
+                    const { steps: _drop, ...metadata } = workflow_nodes[key];
+                    nodes[key] = { ...metadata, ...flow };
                 }
                 else if (isFlow) {
                     const steps = currentNode.steps;
@@ -251,6 +250,47 @@ export default class Configuration {
                         catch: await this.getFlow(currentNode.catch.steps),
                     };
                 }
+                else if (typeof workflow_nodes[key] === "object" &&
+                    Array.isArray(currentNode.try) &&
+                    Array.isArray(currentNode.catch)) {
+                    // v0.5 · tryCatch step. `try`, `catch`, and optional `finally`
+                    // each carry their own inner-step array (set by
+                    // `normalizeTryCatchStep`). Resolve each block as its own Flow
+                    // so TryCatchNode.run() can dispatch them through child Runners.
+                    const raw = workflow_nodes[key];
+                    const merged = {
+                        try: (await this.getFlow(raw.try)).steps,
+                        catch: (await this.getFlow(raw.catch)).steps,
+                    };
+                    if (Array.isArray(raw.finally)) {
+                        merged.finally = (await this.getFlow(raw.finally)).steps;
+                    }
+                    nodes[key] = merged;
+                }
+                else if (typeof workflow_nodes[key] === "object" &&
+                    currentNode.cases !== undefined &&
+                    Array.isArray(currentNode.cases)) {
+                    // v0.5 · switch step. Each case carries its own inner-step
+                    // list at `case.steps` (set by `normalizeSwitchStep`); resolve
+                    // each independently via getFlow. Optional `default` is its
+                    // own resolved Flow. The merged config preserves the `on`
+                    // expression so the blueprint mapper can rewrite it before
+                    // SwitchNode.run() reads ctx.config[name].on at run time.
+                    const raw = workflow_nodes[key];
+                    const rawCases = raw.cases;
+                    const resolvedCases = await Promise.all(rawCases.map(async (c) => ({
+                        when: c.when,
+                        steps: (await this.getFlow(c.steps)).steps,
+                    })));
+                    const merged = {
+                        on: raw.on,
+                        cases: resolvedCases,
+                    };
+                    if (Array.isArray(raw.default)) {
+                        merged.default = (await this.getFlow(raw.default)).steps;
+                    }
+                    nodes[key] = merged;
+                }
                 else {
                     nodes[key] = { ...workflow_nodes[key] };
                 }
@@ -276,13 +316,32 @@ export default class Configuration {
             node.name = step.name;
             node.active = step.active !== undefined ? step.active : true;
             node.stop = step.stop !== undefined ? step.stop : false;
-            // Pass `set_var` through verbatim — DO NOT default to `false`. The
-            // `false` value short-circuits PersistenceHelper.applyStepOutput
-            // and silently disables v2's default-store rule. Legacy v1
-            // workflows that explicitly set `set_var: false` are normalized
-            // to `ephemeral: true` upstream by WorkflowNormalizer.
-            if (step.set_var !== undefined)
-                node.set_var = step.set_var;
+            // V2 persistence + idempotency + retry knobs flow through nested
+            // flow steps too. Without this, a `branch.then[0]` step with
+            // `idempotencyKey` set would NOT be cached on rerun. Mirrors the
+            // same trio Configuration.getSteps copies onto top-level steps.
+            const v2Flow = step;
+            if (v2Flow.as !== undefined)
+                node.as = v2Flow.as;
+            node.spread = v2Flow.spread === true;
+            node.ephemeral = v2Flow.ephemeral === true;
+            if (v2Flow.idempotencyKey !== undefined)
+                node.idempotencyKey = v2Flow.idempotencyKey;
+            if (v2Flow.idempotencyKeyTTL !== undefined)
+                node.idempotencyKeyTTL = v2Flow.idempotencyKeyTTL;
+            if (v2Flow.retry !== undefined)
+                node.retry = v2Flow.retry;
+            // V2 sub-workflow knobs — also flow through nested branches so a
+            // `branch.then[0]` step that invokes a sub-workflow works.
+            if (v2Flow.subworkflow !== undefined)
+                node.subworkflow = v2Flow.subworkflow;
+            if (v2Flow.wait !== undefined)
+                node.wait = v2Flow.wait;
+            if (v2Flow.maxDuration !== undefined) {
+                const parsed = tryParseDuration(v2Flow.maxDuration);
+                if (parsed !== null)
+                    node.maxDurationMs = parsed;
+            }
             // const validator = z.instanceof(NodeBase);
             // validator.parse(node);
             flows.steps.push(node);
@@ -325,6 +384,34 @@ export default class Configuration {
             "runtime.ruby": {
                 resolver: async (node) => await this.runtimeResolver(node),
             },
+            subworkflow: {
+                resolver: async (node) => await this.subworkflowResolver(node),
+            },
+            // PR 4 · `wait.for(duration)` / `wait.until(date)` step. Resolves
+            // to a stub node — RunnerSteps intercepts before step.process()
+            // runs, so the stub's `run()` should never fire in practice.
+            // Without this entry, getSteps() throws `Node type wait not found`
+            // at workflow load.
+            wait: {
+                resolver: async (node) => await this.waitResolver(node),
+            },
+            // v0.5 · `forEach({...})` step — iterate a collection running
+            // inner steps per item. Sequential or parallel-bounded.
+            forEach: {
+                resolver: async (node) => await this.forEachResolver(node),
+            },
+            // v0.5 · `loop({...})` step — while-loop with maxIterations cap.
+            loop: {
+                resolver: async (node) => await this.loopResolver(node),
+            },
+            // v0.5 · `switchOn({...})` step — N-way branch; first matching case wins.
+            switch: {
+                resolver: async (node) => await this.switchResolver(node),
+            },
+            // v0.5 · `tryCatch({...})` step — JS-like try/catch/finally semantics.
+            tryCatch: {
+                resolver: async (node) => await this.tryCatchResolver(node),
+            },
         };
     }
     async runtimeResolver(node) {
@@ -354,21 +441,28 @@ export default class Configuration {
         targetNode.runtime = runtimeKind;
         targetNode.active = node.active !== undefined ? node.active : true;
         targetNode.stop = node.stop !== undefined ? node.stop : false;
-        // Pass `set_var` through verbatim — DO NOT default to `false`. The v2
-        // default-store rule in PersistenceHelper persists `result.data` at
-        // `state[name]` unless `set_var === false` is explicit. Defaulting to
-        // `false` here silently disabled persistence for every SDK step,
-        // breaking `js/ctx.state['<id>']` reads in v2 workflows
-        // (cross-runtime-chain regressed: `state['go']` was undefined even
-        // though the GO step ran fine).
-        if (node.set_var !== undefined)
-            targetNode.set_var = node.set_var;
         // V2 persistence knobs — flow through to PersistenceHelper.
         const v2 = node;
         if (v2.as !== undefined)
             targetNode.as = v2.as;
         targetNode.spread = v2.spread === true;
         targetNode.ephemeral = v2.ephemeral === true;
+        // V2 idempotency cache + retry knobs — copied here so the targetNode
+        // surfaces them for any future code that inspects the inner SDK node
+        // directly. The OUTER RuntimeAdapterNode also carries them via
+        // getSteps/getFlow so RunnerSteps' cache-check + retry-loop wrapper
+        // works regardless of which side it reads.
+        if (v2.idempotencyKey !== undefined)
+            targetNode.idempotencyKey = v2.idempotencyKey;
+        if (v2.idempotencyKeyTTL !== undefined)
+            targetNode.idempotencyKeyTTL = v2.idempotencyKeyTTL;
+        if (v2.retry !== undefined)
+            targetNode.retry = v2.retry;
+        if (v2.maxDuration !== undefined) {
+            const parsed = tryParseDuration(v2.maxDuration);
+            if (parsed !== null)
+                targetNode.maxDurationMs = parsed;
+        }
         // Wrap in RuntimeAdapterNode to integrate with existing Runner.
         // Per-step `stream_logs: true|false` overrides the global
         // `BLOK_STREAM_LOGS` env flag (master plan §17 Phase 5 follow-up).
@@ -379,11 +473,70 @@ export default class Configuration {
         const streamLogs = stepStreamLogs !== undefined ? stepStreamLogs : isStreamLogsEnabled();
         return new RuntimeAdapterNode(adapter, targetNode, { streamLogs });
     }
+    /**
+     * Resolve a `subworkflow` step into a fully-wired `SubworkflowNode` —
+     * the dispatch class that looks up the named child workflow in the
+     * `WorkflowRegistry` and runs it inline with isolated state.
+     *
+     * The returned node carries the parent's `globalOptions` so the
+     * child `Configuration.init()` can resolve `module` step references
+     * against the same node registry.
+     */
+    async subworkflowResolver(node) {
+        const v2 = node;
+        if (typeof v2.subworkflow !== "string" || v2.subworkflow.length === 0) {
+            throw new Error(`[blok] subworkflowResolver: step "${node.name}" is missing the \`subworkflow\` field after normalization.`);
+        }
+        // Lazy import to avoid a circular dep (SubworkflowNode imports
+        // Configuration to construct the child).
+        const { SubworkflowNode } = await import("./SubworkflowNode");
+        const subworkflowNode = new SubworkflowNode();
+        subworkflowNode.node = node.node;
+        subworkflowNode.name = node.name;
+        subworkflowNode.type = node.type;
+        subworkflowNode.active = node.active !== undefined ? node.active : true;
+        subworkflowNode.stop = node.stop !== undefined ? node.stop : false;
+        subworkflowNode.subworkflow = v2.subworkflow;
+        // `wait: false` triggers the fire-and-forget branch in SubworkflowNode.run.
+        // Default to `true` (synchronous) when unset.
+        subworkflowNode.wait = v2.wait !== false;
+        // v0.7 PR 4 — polymorphic sub-workflow dispatch carries the
+        // parent workflow's `trigger.webhook.namespace` so a resolved
+        // event-type name (e.g. `"invoice.paid"`) gets prefixed into a
+        // full registry name (e.g. `"stripe.invoice.paid"`). Static
+        // names are unaffected.
+        const triggerCfg = this.workflow?.trigger;
+        if (typeof triggerCfg?.webhook?.namespace === "string" && triggerCfg.webhook.namespace.length > 0) {
+            subworkflowNode.namespace = triggerCfg.webhook.namespace;
+        }
+        // G3 polymorphic dispatch — pass the per-step allowList (cleaned to
+        // non-empty strings by `normalizeSubworkflowStep`) onto the node so
+        // `resolveSubworkflowName` can reject unauthorized lookups at
+        // dispatch time without re-walking the workflow shape.
+        const allowListSource = node.allowList;
+        if (Array.isArray(allowListSource) && allowListSource.length > 0) {
+            subworkflowNode.allowList = Object.freeze(allowListSource.filter((s) => typeof s === "string" && s.length > 0));
+        }
+        // G2 (v0.6) — dispatch strategy. `in-process` (default) preserves
+        // the v0.5 behaviour; `http-self` routes the child via a fresh
+        // HTTP request to the deployment's own base URL so multi-process
+        // deployments can isolate child execution from the parent.
+        const dispatchRaw = node.dispatch;
+        if (dispatchRaw === "http-self" || dispatchRaw === "in-process") {
+            subworkflowNode.dispatch = dispatchRaw;
+        }
+        // `globalOptions` is the runner's node registry — child Configuration.init
+        // needs it for `module:` step resolution.
+        subworkflowNode.globalOptions = this.globalOptions;
+        return subworkflowNode;
+    }
     async moduleResolver(node, opts) {
         const nodeHandler = opts?.nodes?.getNode(node.node);
         if (!nodeHandler) {
             throw new Error(`Node ${node.node} not found`);
         }
+        // Validate runtime requirements if the node declares them
+        this.validateNodeRuntimeRequirements(nodeHandler);
         const clone = Object.assign(Object.create(Object.getPrototypeOf(nodeHandler)), nodeHandler);
         // Copy step-level metadata from the workflow JSON onto the clone.
         // Without this, `step.type` is undefined for module nodes and
@@ -398,13 +551,130 @@ export default class Configuration {
             clone.active = node.active;
         if (node.stop !== undefined)
             clone.stop = node.stop;
-        if (node.set_var !== undefined)
-            clone.set_var = node.set_var;
         return clone;
     }
+    /**
+     * PR 4 · resolve a `wait` step to a stub node. The runner's wait
+     * primitive (`wait.for`/`wait.until`) is implemented at the
+     * RunnerSteps level — this resolver exists only to satisfy
+     * getSteps() at workflow load time so `Node type wait not found`
+     * doesn't fire on otherwise-valid wait steps.
+     */
+    async waitResolver(node) {
+        const { WaitNode } = await import("./WaitNode");
+        const stub = new WaitNode();
+        stub.node = node.node;
+        stub.name = node.name;
+        stub.type = node.type;
+        stub.active = node.active !== undefined ? node.active : true;
+        stub.stop = node.stop !== undefined ? node.stop : false;
+        const v2 = node;
+        if (v2.waitForMs !== undefined)
+            stub.waitForMs = v2.waitForMs;
+        if (v2.waitUntil !== undefined)
+            stub.waitUntil = v2.waitUntil;
+        return stub;
+    }
+    /**
+     * v0.5 · resolve a `forEach` step. The actual iteration logic lives
+     * in `ForEachNode.run()`; the inner `steps` array is pre-resolved by
+     * the existing isFlowWithProperties path in `getNodes()`.
+     */
+    async forEachResolver(node) {
+        const { ForEachNode } = await import("./ForEachNode");
+        const n = new ForEachNode();
+        n.node = node.node;
+        n.name = node.name;
+        n.type = node.type;
+        n.active = node.active !== undefined ? node.active : true;
+        n.stop = node.stop !== undefined ? node.stop : false;
+        return n;
+    }
+    /**
+     * v0.5 · resolve a `loop` step. While-loop semantics live in
+     * `LoopNode.run()`. Inner `steps` resolved by isFlowWithProperties.
+     */
+    async loopResolver(node) {
+        const { LoopNode } = await import("./LoopNode");
+        const n = new LoopNode();
+        n.node = node.node;
+        n.name = node.name;
+        n.type = node.type;
+        n.active = node.active !== undefined ? node.active : true;
+        n.stop = node.stop !== undefined ? node.stop : false;
+        return n;
+    }
+    /**
+     * v0.5 · resolve a `switch` step. The N-way match logic lives in
+     * `SwitchNode.run()`. Cases + default each carry their own resolved
+     * inner-step list — see the dedicated `cases` branch in `getNodes()`.
+     */
+    async switchResolver(node) {
+        const { SwitchNode } = await import("./SwitchNode");
+        const n = new SwitchNode();
+        n.node = node.node;
+        n.name = node.name;
+        n.type = node.type;
+        n.active = node.active !== undefined ? node.active : true;
+        n.stop = node.stop !== undefined ? node.stop : false;
+        return n;
+    }
+    /**
+     * v0.5 · resolve a `tryCatch` step. JS-like try/catch/finally semantics
+     * live in `TryCatchNode.run()`. Each block (try, catch, finally) is
+     * pre-resolved by the dedicated tryCatch branch in `getNodes()` so
+     * the runtime can dispatch them through child Runners on-demand.
+     */
+    async tryCatchResolver(node) {
+        const { TryCatchNode } = await import("./TryCatchNode");
+        const n = new TryCatchNode();
+        n.node = node.node;
+        n.name = node.name;
+        n.type = node.type;
+        n.active = node.active !== undefined ? node.active : true;
+        n.stop = node.stop !== undefined ? node.stop : false;
+        return n;
+    }
+    /**
+     * Check if a resolved node has runtimeRequirements and validate them
+     * against the currently known runtime versions in the RuntimeRegistry.
+     */
+    validateNodeRuntimeRequirements(node) {
+        const fnNode = node;
+        if (!fnNode.runtimeRequirements)
+            return;
+        const registry = RuntimeRegistry.getInstance();
+        const runtimeVersions = {};
+        for (const kind of registry.getRegisteredKinds()) {
+            const version = registry.getVersion(kind);
+            if (version) {
+                runtimeVersions[kind] = version;
+            }
+        }
+        // If no runtime versions are known yet, skip validation
+        // (versions are populated when health checks succeed)
+        if (Object.keys(runtimeVersions).length === 0)
+            return;
+        const validator = new RuntimeVersionValidator(runtimeVersions);
+        const results = validator.validateNode({
+            name: fnNode.name || "unknown",
+            runtimeRequirements: fnNode.runtimeRequirements,
+        });
+        const failures = results.filter((r) => !r.valid);
+        if (failures.length > 0) {
+            throw new Error(RuntimeVersionValidator.formatErrors(failures));
+        }
+    }
     async localResolver(node) {
-        const path = `${process.env.NODES_PATH}/${node.node}`;
-        return new (await import(path)).default();
+        // Security review FW-3 — canonicalize the resolved path against
+        // NODES_PATH so a node.node value like "../../malicious" can't
+        // walk the filesystem outside the configured directory.
+        const base = resolvePath(process.env.NODES_PATH || ".");
+        const target = resolvePath(base, node.node);
+        if (target !== base && !target.startsWith(base + pathSep)) {
+            throw new Error(`[blok] local node path escapes NODES_PATH: '${node.node}' resolves outside ${base}`);
+        }
+        return new (await import(target)).default();
     }
 }
 //# sourceMappingURL=Configuration.js.map