@decaf-ts/integrations 0.10.8 → 0.12.0

package/lib/cjs/graph/engine/execution/GraphExecutionEngine.cjs

@@ -1,854 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.GraphExecutionEngine = void 0;
-const constants_js_1 = require("./../constants.cjs");
-const graph_1 = require("@decaf-ts/ui-decorators/graph");
-const index_js_1 = require("./../errors/index.cjs");
-const GraphExecutionEventEmitter_js_1 = require("./../events/GraphExecutionEventEmitter.cjs");
-const GraphExecutionEventFactory_js_1 = require("./../events/GraphExecutionEventFactory.cjs");
-const GraphExecutionPlanner_js_1 = require("./../planning/GraphExecutionPlanner.cjs");
-const GraphWorkflowDocumentValidator_js_1 = require("./../validation/GraphWorkflowDocumentValidator.cjs");
-const GraphParameterValidator_js_1 = require("./../validation/GraphParameterValidator.cjs");
-const GraphValidationErrors_js_1 = require("./../validation/GraphValidationErrors.cjs");
-const InMemoryGraphValueStoreAdapter_js_1 = require("./../store/InMemoryGraphValueStoreAdapter.cjs");
-const GraphValueStore_js_1 = require("./../store/GraphValueStore.cjs");
-const GraphPinningService_js_1 = require("./../pinning/GraphPinningService.cjs");
-const GraphPinningPolicy_js_1 = require("./../pinning/GraphPinningPolicy.cjs");
-const GraphPinningDependencyResolver_js_1 = require("./../pinning/GraphPinningDependencyResolver.cjs");
-const GraphExecutionContext_js_1 = require("./GraphExecutionContext.cjs");
-const GraphExecutionFrame_js_1 = require("./GraphExecutionFrame.cjs");
-const GraphExecutionResult_js_1 = require("./GraphExecutionResult.cjs");
-/**
- * Reference graph execution engine.
- *
- * Executes a canonical {@link GraphWorkflowDocument} by:
- * 1. Validating it through the nine-stage gate and resolving it against the
- *    backend catalogue (§4.8).
- * 2. Planning the resolved workflow into topological layers (§4.9).
- * 3. Seeding workflow inputs into the value store.
- * 4. Executing nodes layer-by-layer with configurable concurrency, honouring
- *    disabled-node semantics.
- * 5. Building node inputs from routed edges, literal bindings, allowed
- *    expressions, and manifest defaults; keeping configuration (parameters,
- *    credentials) separate from input data.
- * 6. Validating executor outputs against the effective output manifest.
- * 7. Routing values along data edges.
- * 8. Emitting structured events through Decaf's Observable pipeline.
- * 9. Returning a complete {@link GraphExecutionResult}.
- */
-class GraphExecutionEngine {
-    constructor(config) {
-        this.emitter = config.eventEmitter ?? new GraphExecutionEventEmitter_js_1.GraphExecutionEventEmitter();
-        this.planner = config.planner ?? new GraphExecutionPlanner_js_1.GraphExecutionPlanner();
-        this.valueStoreAdapter =
-            config.valueStoreAdapter ?? new InMemoryGraphValueStoreAdapter_js_1.InMemoryGraphValueStoreAdapter();
-        this.defaultOptions = config.defaultOptions ?? {};
-        this.codeSandboxEvaluator = config.codeSandboxEvaluator;
-        this.config = config;
-        this.documentValidator =
-            config.documentValidator ??
-                new GraphWorkflowDocumentValidator_js_1.GraphWorkflowDocumentValidator({
-                    catalogue: config.catalogue ?? config.registry.catalog,
-                    limits: config.documentLimits,
-                    credentialAuthorizer: config.credentialAuthorizer,
-                });
-        config.onEngineCreated?.(this);
-    }
-    /**
-     * Registers an observer on the engine's event pipeline.
-     *
-     * @param observer - The observer to register.
-     * @returns An unsubscribe function that removes the observer.
-     */
-    observe(observer) {
-        return this.emitter.observe(observer);
-    }
-    /**
-     * Unregisters an observer from the engine's event pipeline.
-     *
-     * @param observer - The observer to remove.
-     */
-    unObserve(observer) {
-        this.emitter.unObserve(observer);
-    }
-    /**
-     * Dispatches an event to all registered observers.
-     *
-     * @param event - The event to distribute.
-     */
-    async updateObservers(event) {
-        await this.emitter.updateObservers(event);
-    }
-    /**
-     * Executes a canonical workflow document with the given inputs and options.
-     *
-     * Resolution happens internally (DECAF-50 §4.9): the document is validated
-     * through the nine-stage gate and resolved against the backend catalogue
-     * before planning. Decorated `GraphWorkflowDefinition` objects are NOT
-     * accepted — compile them with the §4.18 transition compiler first.
-     *
-     * @param document - The canonical workflow document to execute.
-     * @param inputs - Workflow input values keyed by input port id.
-     * @param options - Optional execution overrides (merged over the defaults).
-     * @returns The complete execution result, including a `runId`, per-node
-     *   results, and workflow outputs (or the failure payload).
-     * @throws {GraphDocumentValidationError} when the document fails the
-     *   nine-stage validation gate (carries every structured issue).
-     */
-    async execute(document, inputs = {}, options = {}) {
-        const opts = this.mergeOptions(options);
-        this.assertNotAborted(opts);
-        const runId = opts.runId ?? this.generateRunId();
-        const path = opts.path ?? [];
-        const eventFactory = new GraphExecutionEventFactory_js_1.GraphExecutionEventFactory();
-        const valueStore = new GraphValueStore_js_1.GraphValueStore(this.valueStoreAdapter);
-        valueStore.seedWorkflowInputs(this.withWorkflowInputDefaults(document, inputs));
-        const emitFn = async (partial) => {
-            await this.emitEvent(frame, {
-                type: partial.type ?? graph_1.GraphExecutionEventType.NODE_OUTPUT,
-                runId,
-                parentRunId: opts.parentRunId,
-                workflowId: document.id || document.name,
-                nodeId: partial.nodeId,
-                path: partial.path ?? path,
-                ...partial,
-            });
-        };
-        const emitValidationEvent = async (partial) => {
-            const event = eventFactory.create({
-                id: "",
-                sequence: 0,
-                timestamp: new Date(),
-                runId,
-                parentRunId: opts.parentRunId,
-                workflowId: document.id || document.name,
-                path,
-                ...partial,
-            });
-            await this.emitter.updateObservers(event);
-        };
-        // ------------------------------------------------------------------
-        // Validation + resolution (nine-stage gate, §4.8) — internal.
-        // ------------------------------------------------------------------
-        await emitValidationEvent({
-            type: graph_1.GraphExecutionEventType.VALIDATION_STARTED,
-            status: graph_1.GraphExecutionStatus.PLANNING,
-        });
-        const validation = await this.documentValidator.validate(document);
-        if (!validation.valid || !validation.resolved) {
-            await emitValidationEvent({
-                type: graph_1.GraphExecutionEventType.VALIDATION_FAILED,
-                status: graph_1.GraphExecutionStatus.FAILED,
-                payload: { issues: validation.issues },
-            });
-            throw new GraphValidationErrors_js_1.GraphDocumentValidationError(`Graph workflow document '${document.id}' failed validation with ${validation.issues.length} issue(s)`, validation.issues);
-        }
-        await emitValidationEvent({
-            type: graph_1.GraphExecutionEventType.VALIDATION_COMPLETED,
-            status: graph_1.GraphExecutionStatus.PLANNING,
-            payload: { issues: validation.issues.length },
-        });
-        this.assertNotAborted(opts);
-        const plan = this.planner.plan(validation.resolved);
-        const frame = new GraphExecutionFrame_js_1.GraphExecutionFrame(runId, plan, valueStore, eventFactory);
-        await this.emitEvent(frame, {
-            type: graph_1.GraphExecutionEventType.WORKFLOW_STARTED,
-            runId,
-            parentRunId: opts.parentRunId,
-            workflowId: plan.workflowId,
-            path,
-            status: graph_1.GraphExecutionStatus.RUNNING,
-            payload: { inputs },
-        });
-        await this.emitEvent(frame, {
-            type: graph_1.GraphExecutionEventType.WORKFLOW_PLANNED,
-            runId,
-            parentRunId: opts.parentRunId,
-            workflowId: plan.workflowId,
-            path,
-            status: graph_1.GraphExecutionStatus.PLANNING,
-            payload: { layers: plan.layers.length, nodes: plan.nodes.length },
-        });
-        try {
-            for (const layer of plan.layers) {
-                this.assertNotAborted(opts);
-                await this.executeLayer(frame, plan, layer.nodes, opts, emitFn);
-            }
-            this.assertNotAborted(opts);
-            const firstFailure = [...frame.nodeResults.values()].find((result) => result.status === graph_1.GraphExecutionStatus.FAILED);
-            if (firstFailure?.error) {
-                throw new index_js_1.GraphExecutionError(firstFailure.error.message, firstFailure.error.code ?? "GRAPH_EXECUTION_ERROR", firstFailure.error.details);
-            }
-            frame.finish();
-            await this.emitEvent(frame, {
-                type: graph_1.GraphExecutionEventType.WORKFLOW_COMPLETED,
-                runId,
-                parentRunId: opts.parentRunId,
-                workflowId: plan.workflowId,
-                path,
-                status: graph_1.GraphExecutionStatus.SUCCEEDED,
-                payload: { outputs: valueStore.getWorkflowValues() },
-            });
-            return (0, GraphExecutionResult_js_1.buildGraphExecutionResult)(frame, document, inputs, graph_1.GraphExecutionStatus.SUCCEEDED, opts.metadata);
-        }
-        catch (error) {
-            frame.finish();
-            const errorPayload = this.toErrorPayload(error);
-            if (error instanceof index_js_1.GraphRunCancelledError ||
-                opts.abortSignal?.aborted === true) {
-                await this.emitEvent(frame, {
-                    type: graph_1.GraphExecutionEventType.WORKFLOW_CANCELLED,
-                    runId,
-                    parentRunId: opts.parentRunId,
-                    workflowId: plan.workflowId,
-                    path,
-                    status: graph_1.GraphExecutionStatus.CANCELLED,
-                    error: errorPayload,
-                });
-                return (0, GraphExecutionResult_js_1.buildGraphExecutionResult)(frame, document, inputs, graph_1.GraphExecutionStatus.CANCELLED, opts.metadata);
-            }
-            await this.emitEvent(frame, {
-                type: graph_1.GraphExecutionEventType.WORKFLOW_FAILED,
-                runId,
-                parentRunId: opts.parentRunId,
-                workflowId: plan.workflowId,
-                path,
-                status: graph_1.GraphExecutionStatus.FAILED,
-                error: errorPayload,
-            });
-            return (0, GraphExecutionResult_js_1.buildGraphExecutionResult)(frame, document, inputs, graph_1.GraphExecutionStatus.FAILED, opts.metadata);
-        }
-    }
-    /**
-     * Pins a node and its upstream dependencies after a completed run.
-     *
-     * Delegates to {@link GraphPinningService}. The plan and result must come
-     * from a prior successful execution of the same workflow.
-     */
-    async pinNode(options) {
-        const service = this.createPinningService();
-        await service.pinNode(options);
-        await this.emitPinningEvent(options.nodeId, graph_1.GraphExecutionEventType.NODE_PINNED);
-    }
-    /**
-     * Unpins a node by its fingerprint.
-     */
-    async unpinNode(options) {
-        const service = this.createPinningService();
-        await service.unpinNode(options);
-        await this.emitPinningEvent(options.nodeId, graph_1.GraphExecutionEventType.NODE_UNPINNED);
-    }
-    /**
-     * Creates a {@link GraphPinningService} backed by this engine's value store
-     * adapter.
-     */
-    createPinningService() {
-        const store = new GraphValueStore_js_1.GraphValueStore(this.valueStoreAdapter);
-        return new GraphPinningService_js_1.GraphPinningService(store, new GraphPinningPolicy_js_1.GraphPinningPolicy(), new GraphPinningDependencyResolver_js_1.GraphPinningDependencyResolver());
-    }
-    /**
-     * Emits a pinning-related event to all observers.
-     */
-    async emitPinningEvent(nodeId, type) {
-        const factory = new GraphExecutionEventFactory_js_1.GraphExecutionEventFactory();
-        const event = factory.create({
-            id: "",
-            sequence: 0,
-            timestamp: new Date(),
-            runId: "pinning",
-            workflowId: "",
-            type,
-            nodeId,
-            path: [],
-        });
-        await this.emitter.updateObservers(event);
-    }
-    /**
-     * Fills unprovided workflow inputs with their declared port defaults.
-     */
-    withWorkflowInputDefaults(document, inputs) {
-        const seeded = { ...inputs };
-        for (const port of document.inputs) {
-            if (seeded[port.id] === undefined &&
-                port.defaultValue !== undefined) {
-                seeded[port.id] = port.defaultValue;
-            }
-        }
-        return seeded;
-    }
-    /**
-     * Executes a layer of nodes with the configured concurrency.
-     */
-    async executeLayer(frame, plan, nodes, opts, emitFn) {
-        const concurrency = Math.max(1, opts.concurrency ?? constants_js_1.GRAPH_DEFAULT_CONCURRENCY);
-        const queue = [...nodes];
-        while (queue.length > 0) {
-            const batch = queue.splice(0, concurrency);
-            await Promise.all(batch.map((node) => this.executeNode(frame, plan, node, opts, emitFn)));
-        }
-    }
-    /**
-     * Executes a single node, honouring disabled-node semantics (§4.9).
-     */
-    async executeNode(frame, plan, planNode, opts, emitFn) {
-        this.assertNotAborted(opts);
-        if (!this.isNodeActivated(frame, plan, planNode)) {
-            await this.skipInactiveNode(frame, plan, planNode, opts);
-            return;
-        }
-        if (planNode.instance.disabled === true) {
-            await this.executeDisabledNode(frame, plan, planNode, opts);
-            return;
-        }
-        const startedAt = new Date();
-        const nodePath = [...(opts.path ?? []), planNode.id];
-        await this.emitEvent(frame, {
-            type: graph_1.GraphExecutionEventType.NODE_STARTED,
-            runId: frame.runId,
-            workflowId: plan.workflowId,
-            nodeId: planNode.id,
-            path: nodePath,
-            status: graph_1.GraphExecutionStatus.RUNNING,
-        });
-        this.emitNodeStateChanged(frame, plan, planNode, nodePath, graph_1.GraphVisualState.RUNNING, graph_1.GraphExecutionStatus.RUNNING);
-        const inputs = await this.resolveNodeInputs(frame, plan, planNode, opts);
-        // Cache-hit: check for a pinned value before executing the node
-        if (opts.usePinnedValues) {
-            const cached = await this.tryPinnedValue(frame, plan, planNode, inputs);
-            if (cached) {
-                frame.valueStore.setNodeOutputs(planNode.id, cached.outputs);
-                this.routeOutgoingEdges(frame, plan, planNode, cached.outputs);
-                const finishedAt = new Date();
-                const result = {
-                    nodeId: planNode.id,
-                    status: graph_1.GraphExecutionStatus.CACHED,
-                    inputs,
-                    outputs: cached.outputs,
-                    startedAt,
-                    finishedAt,
-                    fromCache: true,
-                    pinned: true,
-                    events: [],
-                };
-                frame.recordNodeResult(result);
-                await this.emitEvent(frame, {
-                    type: graph_1.GraphExecutionEventType.NODE_CACHE_HIT,
-                    runId: frame.runId,
-                    workflowId: plan.workflowId,
-                    nodeId: planNode.id,
-                    path: nodePath,
-                    status: graph_1.GraphExecutionStatus.CACHED,
-                    payload: { outputs: cached.outputs },
-                });
-                await this.emitEvent(frame, {
-                    type: graph_1.GraphExecutionEventType.NODE_COMPLETED,
-                    runId: frame.runId,
-                    workflowId: plan.workflowId,
-                    nodeId: planNode.id,
-                    path: nodePath,
-                    status: graph_1.GraphExecutionStatus.SUCCEEDED,
-                    payload: { outputs: cached.outputs, fromCache: true },
-                });
-                this.emitNodeStateChanged(frame, plan, planNode, nodePath, graph_1.GraphVisualState.SUCCEEDED, graph_1.GraphExecutionStatus.SUCCEEDED);
-                return;
-            }
-        }
-        try {
-            const context = new GraphExecutionContext_js_1.GraphExecutionContext(frame.runId, opts.parentRunId, plan.workflowId, plan.resolved.document, planNode.instance, planNode.manifest, nodePath, emitFn, opts.metadata, this);
-            const request = {
-                nodeId: planNode.id,
-                kind: planNode.kind,
-                inputs,
-                parameters: planNode.instance.parameters ?? {},
-                credentials: this.collectCredentials(planNode),
-                metadata: planNode.instance.metadata,
-            };
-            const rawOutputs = await this.invokeExecutor(planNode, request, context);
-            const outputs = this.validateNodeOutputs(planNode, rawOutputs ?? {});
-            frame.valueStore.setNodeOutputs(planNode.id, outputs);
-            this.routeOutgoingEdges(frame, plan, planNode, outputs);
-            const finishedAt = new Date();
-            const result = {
-                nodeId: planNode.id,
-                status: graph_1.GraphExecutionStatus.SUCCEEDED,
-                inputs,
-                outputs,
-                startedAt,
-                finishedAt,
-                events: [],
-            };
-            frame.recordNodeResult(result);
-            await this.emitEvent(frame, {
-                type: graph_1.GraphExecutionEventType.NODE_COMPLETED,
-                runId: frame.runId,
-                workflowId: plan.workflowId,
-                nodeId: planNode.id,
-                path: nodePath,
-                status: graph_1.GraphExecutionStatus.SUCCEEDED,
-                payload: { outputs },
-            });
-            this.emitNodeStateChanged(frame, plan, planNode, nodePath, graph_1.GraphVisualState.SUCCEEDED, graph_1.GraphExecutionStatus.SUCCEEDED);
-        }
-        catch (error) {
-            const finishedAt = new Date();
-            const errorPayload = this.toErrorPayload(error);
-            const result = {
-                nodeId: planNode.id,
-                status: graph_1.GraphExecutionStatus.FAILED,
-                inputs,
-                error: errorPayload,
-                startedAt,
-                finishedAt,
-                events: [],
-            };
-            frame.recordNodeResult(result);
-            await this.emitEvent(frame, {
-                type: graph_1.GraphExecutionEventType.NODE_FAILED,
-                runId: frame.runId,
-                workflowId: plan.workflowId,
-                nodeId: planNode.id,
-                path: nodePath,
-                status: graph_1.GraphExecutionStatus.FAILED,
-                error: errorPayload,
-            });
-            this.emitNodeStateChanged(frame, plan, planNode, nodePath, graph_1.GraphVisualState.FAILED, graph_1.GraphExecutionStatus.FAILED);
-            if (opts.failFast ?? true)
-                throw error;
-        }
-    }
-    /**
-     * Resolves whether a plan node is activated for execution under the
-     * DECAF-50 §4.9 branch semantics. A node with no incoming data edges is
-     * a root/source node and always runs. A node fed by one or more data
-     * edges runs only when at least one of those edges was activated by a
-     * routed upstream output port — a branch the upstream switch (or any
-     * partial-output node) did not select leaves its downstream edges
-     * unactivated, so the branch is never executed. Workflow-boundary edges
-     * are active from the start because workflow inputs are seeded before
-     * execution begins.
-     */
-    isNodeActivated(frame, plan, planNode) {
-        const incoming = (plan.incomingByNode.get(planNode.id) ?? []).filter((edge) => edge.type === "data");
-        if (incoming.length === 0)
-            return true;
-        return incoming.some((edge) => edge.sourceNodeId === constants_js_1.GRAPH_WORKFLOW_BOUNDARY ||
-            frame.isDataEdgeActive(edge.id));
-    }
-    /**
-     * Skips a node whose incoming data edges were all left unactivated by an
-     * upstream branch selection. The node is not executed and its outputs are
-     * never routed or collected into workflow outputs (DECAF-50 §4.9).
-     */
-    async skipInactiveNode(frame, plan, planNode, opts) {
-        const startedAt = new Date();
-        const nodePath = [...(opts.path ?? []), planNode.id];
-        await this.emitEvent(frame, {
-            type: graph_1.GraphExecutionEventType.NODE_SKIPPED,
-            runId: frame.runId,
-            workflowId: plan.workflowId,
-            nodeId: planNode.id,
-            path: nodePath,
-            status: graph_1.GraphExecutionStatus.SKIPPED,
-            payload: { reason: "branchNotSelected" },
-        });
-        const result = {
-            nodeId: planNode.id,
-            status: graph_1.GraphExecutionStatus.SKIPPED,
-            inputs: {},
-            startedAt,
-            finishedAt: new Date(),
-            events: [],
-        };
-        frame.recordNodeResult(result);
-        this.emitNodeStateChanged(frame, plan, planNode, nodePath, graph_1.GraphVisualState.SKIPPED, graph_1.GraphExecutionStatus.SKIPPED);
-    }
-    /**
-     * Applies the explicit disabled-node semantics (§4.9):
-     * `skip`, `passThroughFirstInput`, or `emitDefaults`, resolved from the
-     * instance metadata, document settings, and the default.
-     */
-    async executeDisabledNode(frame, plan, planNode, opts) {
-        const startedAt = new Date();
-        const nodePath = [...(opts.path ?? []), planNode.id];
-        const behavior = GraphParameterValidator_js_1.GraphParameterValidator.disabledBehaviorOf(planNode.instance, plan.resolved.document.settings);
-        await this.emitEvent(frame, {
-            type: graph_1.GraphExecutionEventType.NODE_SKIPPED,
-            runId: frame.runId,
-            workflowId: plan.workflowId,
-            nodeId: planNode.id,
-            path: nodePath,
-            status: graph_1.GraphExecutionStatus.SKIPPED,
-            payload: { disabled: true, behavior },
-        });
-        if (behavior === "skip") {
-            const result = {
-                nodeId: planNode.id,
-                status: graph_1.GraphExecutionStatus.SKIPPED,
-                inputs: {},
-                startedAt,
-                finishedAt: new Date(),
-                events: [],
-            };
-            frame.recordNodeResult(result);
-            this.emitNodeStateChanged(frame, plan, planNode, nodePath, graph_1.GraphVisualState.SKIPPED, graph_1.GraphExecutionStatus.SKIPPED);
-            return;
-        }
-        const inputs = await this.resolveNodeInputs(frame, plan, planNode, opts);
-        let outputs;
-        if (behavior === "passThroughFirstInput") {
-            const firstIncoming = (plan.incomingByNode.get(planNode.id) ?? []).find((edge) => edge.type === "data");
-            const firstOutput = planNode.manifest.outputs[0]?.id ?? "value";
-            const value = firstIncoming
-                ? frame.valueStore.getPort(firstIncoming.sourceNodeId, firstIncoming.sourcePort)
-                : Object.values(inputs)[0];
-            outputs = { [firstOutput]: value };
-        }
-        else {
-            // emitDefaults — every declared output port is emitted with its
-            // declared default (absent a declared default, undefined).
-            outputs = {};
-            for (const port of planNode.manifest.outputs) {
-                outputs[port.id] = port.metadata?.["defaultValue"];
-            }
-        }
-        frame.valueStore.setNodeOutputs(planNode.id, outputs);
-        this.routeOutgoingEdges(frame, plan, planNode, outputs);
-        const result = {
-            nodeId: planNode.id,
-            status: graph_1.GraphExecutionStatus.SUCCEEDED,
-            inputs,
-            outputs,
-            startedAt,
-            finishedAt: new Date(),
-            events: [],
-        };
-        frame.recordNodeResult(result);
-        this.emitNodeStateChanged(frame, plan, planNode, nodePath, graph_1.GraphVisualState.SUCCEEDED, graph_1.GraphExecutionStatus.SUCCEEDED);
-    }
-    /**
-     * Invokes the node's catalogue-resolved executor (§4.9 request contract,
-     * post-cutover: every executor receives the full request with
-     * configuration and input data separated).
-     */
-    async invokeExecutor(planNode, request, context) {
-        return await planNode.executor.execute(request, context);
-    }
-    /**
-     * Validates executor outputs against the effective output manifest
-     * (§4.9): unknown outputs are rejected by default; missing required
-     * outputs fail the node. Lenient transition manifests (legacy
-     * executor-only registrations) are exempt until cutover.
-     */
-    validateNodeOutputs(planNode, outputs) {
-        const manifest = planNode.manifest;
-        if (manifest.policies?.allowUnknownOutputs === true) {
-            return outputs;
-        }
-        const declaredOutputs = new Set(manifest.outputs.map((port) => port.id));
-        const unknownOutputs = Object.keys(outputs).filter((key) => !declaredOutputs.has(key));
-        if (unknownOutputs.length > 0) {
-            throw new index_js_1.GraphExecutionError(`Node '${planNode.id}' of kind '${planNode.kind}' produced unknown output(s): ${unknownOutputs.join(", ")}`, "GRAPH_OUTPUT_VALIDATION_FAILED", { nodeId: planNode.id, unknownOutputs });
-        }
-        const missingRequired = manifest.outputs
-            .filter((port) => port.required === true && !(port.id in outputs))
-            .map((port) => port.id);
-        if (missingRequired.length > 0) {
-            throw new index_js_1.GraphExecutionError(`Node '${planNode.id}' of kind '${planNode.kind}' did not produce required output(s): ${missingRequired.join(", ")}`, "GRAPH_OUTPUT_VALIDATION_FAILED", { nodeId: planNode.id, missingRequired });
-        }
-        return outputs;
-    }
-    /**
-     * Collects the resolved credential references for a node: credential-type
-     * parameter values plus the `credentials` record in instance metadata.
-     * Documents carry references only — secret material never enters requests.
-     */
-    collectCredentials(planNode) {
-        const credentials = {};
-        for (const parameter of planNode.manifest.parameters) {
-            if (parameter.type !== "credential")
-                continue;
-            const value = (planNode.instance.parameters ?? {})[parameter.id];
-            if (typeof value === "string" && value.length > 0) {
-                credentials[parameter.id] = {
-                    credentialId: value,
-                    credentialType: parameter.credentialType ?? "",
-                };
-            }
-            else if ((0, GraphParameterValidator_js_1.isGraphCredentialReferenceLike)(value)) {
-                credentials[parameter.id] = {
-                    credentialId: value.credentialId,
-                    credentialType: value.credentialType,
-                };
-            }
-        }
-        const extra = (planNode.instance.metadata ?? {})["credentials"];
-        if (extra && typeof extra === "object" && !Array.isArray(extra)) {
-            for (const [key, raw] of Object.entries(extra)) {
-                const value = raw;
-                if (typeof value === "string" && value.length > 0) {
-                    credentials[key] = { credentialId: value, credentialType: "" };
-                }
-                else if ((0, GraphParameterValidator_js_1.isGraphCredentialReferenceLike)(value)) {
-                    credentials[key] = {
-                        credentialId: value.credentialId,
-                        credentialType: value.credentialType,
-                    };
-                }
-            }
-        }
-        return credentials;
-    }
-    /**
-     * Resolves a node's input values from routed data edges, literal bindings,
-     * allowed expression bindings, and manifest port defaults (§4.9).
-     *
-     * When multiple edges target the same port, their values are spread into the
-     * top-level inputs keyed by each edge's `sourcePort`. This allows multiple
-     * workflow input badges to connect to a single port (e.g. the Code node's
-     * `data` port) and have all values accessible directly as
-     * `$input.{sourcePort}` (e.g. `$input.count`, `$input.text`).
-     */
-    async resolveNodeInputs(frame, plan, planNode, opts) {
-        const inputs = {};
-        const incoming = (plan.incomingByNode.get(planNode.id) ?? []).filter((edge) => edge.type === "data");
-        const edgesByTarget = new Map();
-        for (const edge of incoming) {
-            const list = edgesByTarget.get(edge.targetPort) ?? [];
-            list.push(edge);
-            edgesByTarget.set(edge.targetPort, list);
-        }
-        for (const [targetPort, edges] of edgesByTarget) {
-            if (edges.length === 1) {
-                inputs[targetPort] = frame.valueStore.getPort(edges[0].sourceNodeId, edges[0].sourcePort);
-            }
-            else {
-                for (const edge of edges) {
-                    inputs[edge.sourcePort] = frame.valueStore.getPort(edge.sourceNodeId, edge.sourcePort);
-                }
-            }
-        }
-        // Literal bindings, expression bindings, and manifest defaults.
-        const bindings = planNode.instance.inputBindings ?? {};
-        for (const port of planNode.manifest.inputs) {
-            const binding = bindings[port.id];
-            if (binding?.mode === "literal") {
-                inputs[port.id] = binding.value;
-            }
-            else if (binding?.mode === "expression") {
-                inputs[port.id] = await this.evaluateExpressionBinding(planNode, binding.expression, inputs, opts);
-            }
-            else if (inputs[port.id] === undefined) {
-                const defaultValue = port.metadata?.["defaultValue"];
-                if (defaultValue !== undefined) {
-                    inputs[port.id] = defaultValue;
-                }
-            }
-        }
-        return inputs;
-    }
-    /**
-     * Evaluates an expression binding with the EXISTING allowed-expression
-     * machinery only (the pluggable {@link CodeSandboxEvaluator}, DECAF-32
-     * §22.4) — no new evaluator. The expression sees the already-routed input
-     * values as `$input` and the run metadata as context.
-     */
-    async evaluateExpressionBinding(planNode, expression, inputs, opts) {
-        const evaluator = this.codeSandboxEvaluator;
-        if (!evaluator) {
-            throw new index_js_1.GraphExecutionError(`Expression binding on node '${planNode.id}' requires a CodeSandboxEvaluator to be registered in GraphExecutionEngineConfig.codeSandboxEvaluator`, "GRAPH_CODE_SANDBOX_NOT_CONFIGURED", { nodeId: planNode.id, expression });
-        }
-        const md = opts.metadata;
-        return await evaluator.evaluate({
-            code: expression,
-            language: "javascript",
-            input: inputs,
-            vars: md?.vars ?? undefined,
-            item: md?.item,
-            index: md?.index,
-        });
-    }
-    /**
-     * Attempts to read a pinned value for the node. Returns the cached outputs
-     * when a valid pinned value exists, or `undefined` to proceed with normal
-     * execution.
-     */
-    async tryPinnedValue(frame, plan, planNode, inputs) {
-        const policy = new GraphPinningPolicy_js_1.GraphPinningPolicy();
-        if (!policy.shouldUsePinnedValue(planNode))
-            return undefined;
-        const service = this.createPinningService();
-        const depFingerprints = this.computeDependencyFingerprints(frame, plan, planNode.id);
-        return service.readPinnedValue(plan.workflowId, planNode, inputs, depFingerprints);
-    }
-    /**
-     * Recursively computes fingerprints for all upstream dependencies of a node
-     * using the results already accumulated in the frame.
-     */
-    computeDependencyFingerprints(frame, plan, nodeId) {
-        const service = this.createPinningService();
-        const depResolver = new GraphPinningDependencyResolver_js_1.GraphPinningDependencyResolver();
-        const deps = depResolver.getDependencies(plan, nodeId);
-        const fingerprints = {};
-        for (const dep of deps) {
-            const node = plan.nodes.find((n) => n.id === dep);
-            if (node) {
-                const depResult = frame.nodeResults.get(dep);
-                const inputs = depResult?.inputs ?? {};
-                const nestedDeps = this.computeDependencyFingerprints(frame, plan, dep);
-                fingerprints[dep] = service.computeFingerprint(plan.workflowId, node, inputs, nestedDeps);
-            }
-        }
-        return fingerprints;
-    }
-    /**
-     * Routes a node's outputs to downstream inputs and workflow outputs along
-     * data edges (connection edges are structural and never route values).
-     *
-     * An edge is traversed only when the source node actually emitted the
-     * edge's `sourcePort` (DECAF-50 §4.9 branch semantics). A node that
-     * emitted a subset of its declared outputs — e.g. a switch that selected
-     * one case — therefore activates only the downstream branch edges of the
-     * emitted ports; unselected branch edges are left unactivated, so their
-     * downstream nodes are skipped and never contribute to workflow outputs.
-     * Emitting an output port explicitly with `undefined` still counts as
-     * activated (the port was produced by the executor).
-     */
-    routeOutgoingEdges(frame, plan, planNode, outputs) {
-        const outgoing = (plan.outgoingByNode.get(planNode.id) ?? []).filter((edge) => edge.type === "data");
-        for (const edge of outgoing) {
-            if (!Object.prototype.hasOwnProperty.call(outputs, edge.sourcePort)) {
-                // The source node did not emit this output port: the edge's branch
-                // was not selected, so no value is routed.
-                continue;
-            }
-            const value = outputs[edge.sourcePort];
-            frame.activateDataEdge(edge.id);
-            if (edge.targetNodeId === constants_js_1.GRAPH_WORKFLOW_BOUNDARY) {
-                frame.valueStore.setWorkflowOutput(edge.targetPort, value);
-            }
-            this.emitEdgeStateChanged(frame, plan, planNode, edge, graph_1.GraphVisualState.SUCCEEDED, graph_1.GraphExecutionStatus.SUCCEEDED);
-            this.emitEvent(frame, {
-                type: graph_1.GraphExecutionEventType.EDGE_VALUE_ROUTED,
-                runId: frame.runId,
-                workflowId: plan.workflowId,
-                edgeId: edge.id,
-                nodeId: planNode.id,
-                path: [],
-                payload: { edge, value },
-            }).catch(() => {
-                // observer failures must not crash
-            });
-        }
-    }
-    /**
-     * Emits an event, records it in the frame, and dispatches to observers.
-     */
-    async emitEvent(frame, partial) {
-        const event = frame.eventFactory.create({
-            id: "",
-            sequence: 0,
-            timestamp: new Date(),
-            ...partial,
-        });
-        frame.appendEvent(event);
-        await this.emitter.updateObservers(event);
-    }
-    /**
-     * Emits a `NODE_STATE_CHANGED` event (DECAF-48 §4.4) carrying the given
-     * visual state for the node. Rides the existing Observable pipeline; no
-     * second out-of-band channel.
-     */
-    emitNodeStateChanged(frame, plan, planNode, nodePath, state, status) {
-        this.emitEvent(frame, {
-            type: graph_1.GraphExecutionEventType.NODE_STATE_CHANGED,
-            runId: frame.runId,
-            workflowId: plan.workflowId,
-            nodeId: planNode.id,
-            path: nodePath,
-            status,
-            payload: {
-                nodeId: planNode.id,
-                state,
-                runId: frame.runId,
-                workflowId: plan.workflowId,
-                status,
-            },
-        }).catch(() => {
-            // observer failures must not crash execution
-        });
-    }
-    /**
-     * Emits an `EDGE_STATE_CHANGED` event (DECAF-48 §4.4) carrying the given
-     * visual state for a routed edge.
-     */
-    emitEdgeStateChanged(frame, plan, planNode, edge, state, status) {
-        this.emitEvent(frame, {
-            type: graph_1.GraphExecutionEventType.EDGE_STATE_CHANGED,
-            runId: frame.runId,
-            workflowId: plan.workflowId,
-            edgeId: edge.id,
-            nodeId: planNode.id,
-            path: [],
-            status,
-            payload: {
-                edgeId: edge.id,
-                state,
-                runId: frame.runId,
-                workflowId: plan.workflowId,
-                nodeId: planNode.id,
-                status,
-            },
-        }).catch(() => {
-            // observer failures must not crash execution
-        });
-    }
-    /**
-     * Merges default options with the given options.
-     */
-    mergeOptions(options) {
-        return {
-            concurrency: constants_js_1.GRAPH_DEFAULT_CONCURRENCY,
-            failFast: true,
-            validateInputs: true,
-            validateOutputs: true,
-            usePinnedValues: true,
-            writeThroughCache: false,
-            path: [],
-            metadata: {},
-            ...this.defaultOptions,
-            ...options,
-        };
-    }
-    assertNotAborted(opts) {
-        if (opts.abortSignal?.aborted === true) {
-            throw new index_js_1.GraphRunCancelledError(opts.runId ?? "unknown");
-        }
-    }
-    /**
-     * Generates a unique run id.
-     */
-    generateRunId() {
-        return (globalThis.crypto?.randomUUID?.() ??
-            `graph-run-${Date.now()}-${Math.random().toString(36).slice(2)}`);
-    }
-    /**
-     * Converts an error into a serialized payload.
-     */
-    toErrorPayload(error) {
-        if (error instanceof Error) {
-            return {
-                name: error.name,
-                message: error.message,
-                stack: error.stack,
-                code: error.graphCode ??
-                    (typeof error.code === "number"
-                        ? String(error.code)
-                        : error.code),
-            };
-        }
-        return { name: "UnknownError", message: String(error) };
-    }
-}
-exports.GraphExecutionEngine = GraphExecutionEngine;
-//# sourceMappingURL=GraphExecutionEngine.js.map
-//# sourceMappingURL=GraphExecutionEngine.cjs.map