@decaf-ts/integrations 0.10.8 → 0.11.0

package/lib/esm/graph/engine/execution/GraphExecutionEngine.js

@@ -1,849 +0,0 @@
-import { GRAPH_DEFAULT_CONCURRENCY, GRAPH_WORKFLOW_BOUNDARY, } from "./../constants.js";
-import { GraphExecutionEventType, GraphExecutionStatus, GraphVisualState, } from "@decaf-ts/ui-decorators/graph";
-import { GraphExecutionError, GraphRunCancelledError } from "./../errors/index.js";
-import { GraphExecutionEventEmitter } from "./../events/GraphExecutionEventEmitter.js";
-import { GraphExecutionEventFactory } from "./../events/GraphExecutionEventFactory.js";
-import { GraphExecutionPlanner } from "./../planning/GraphExecutionPlanner.js";
-import { GraphWorkflowDocumentValidator, } from "./../validation/GraphWorkflowDocumentValidator.js";
-import { GraphParameterValidator, isGraphCredentialReferenceLike, } from "./../validation/GraphParameterValidator.js";
-import { GraphDocumentValidationError } from "./../validation/GraphValidationErrors.js";
-import { InMemoryGraphValueStoreAdapter } from "./../store/InMemoryGraphValueStoreAdapter.js";
-import { GraphValueStore } from "./../store/GraphValueStore.js";
-import { GraphPinningService } from "./../pinning/GraphPinningService.js";
-import { GraphPinningPolicy } from "./../pinning/GraphPinningPolicy.js";
-import { GraphPinningDependencyResolver } from "./../pinning/GraphPinningDependencyResolver.js";
-import { GraphExecutionContext } from "./GraphExecutionContext.js";
-import { GraphExecutionFrame } from "./GraphExecutionFrame.js";
-import { buildGraphExecutionResult } from "./GraphExecutionResult.js";
-/**
- * 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}.
- */
-export class GraphExecutionEngine {
-    constructor(config) {
-        this.emitter = config.eventEmitter ?? new GraphExecutionEventEmitter();
-        this.planner = config.planner ?? new GraphExecutionPlanner();
-        this.valueStoreAdapter =
-            config.valueStoreAdapter ?? new InMemoryGraphValueStoreAdapter();
-        this.defaultOptions = config.defaultOptions ?? {};
-        this.codeSandboxEvaluator = config.codeSandboxEvaluator;
-        this.config = config;
-        this.documentValidator =
-            config.documentValidator ??
-                new 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();
-        const valueStore = new GraphValueStore(this.valueStoreAdapter);
-        valueStore.seedWorkflowInputs(this.withWorkflowInputDefaults(document, inputs));
-        const emitFn = async (partial) => {
-            await this.emitEvent(frame, {
-                type: partial.type ?? 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: GraphExecutionEventType.VALIDATION_STARTED,
-            status: GraphExecutionStatus.PLANNING,
-        });
-        const validation = await this.documentValidator.validate(document);
-        if (!validation.valid || !validation.resolved) {
-            await emitValidationEvent({
-                type: GraphExecutionEventType.VALIDATION_FAILED,
-                status: GraphExecutionStatus.FAILED,
-                payload: { issues: validation.issues },
-            });
-            throw new GraphDocumentValidationError(`Graph workflow document '${document.id}' failed validation with ${validation.issues.length} issue(s)`, validation.issues);
-        }
-        await emitValidationEvent({
-            type: GraphExecutionEventType.VALIDATION_COMPLETED,
-            status: GraphExecutionStatus.PLANNING,
-            payload: { issues: validation.issues.length },
-        });
-        this.assertNotAborted(opts);
-        const plan = this.planner.plan(validation.resolved);
-        const frame = new GraphExecutionFrame(runId, plan, valueStore, eventFactory);
-        await this.emitEvent(frame, {
-            type: GraphExecutionEventType.WORKFLOW_STARTED,
-            runId,
-            parentRunId: opts.parentRunId,
-            workflowId: plan.workflowId,
-            path,
-            status: GraphExecutionStatus.RUNNING,
-            payload: { inputs },
-        });
-        await this.emitEvent(frame, {
-            type: GraphExecutionEventType.WORKFLOW_PLANNED,
-            runId,
-            parentRunId: opts.parentRunId,
-            workflowId: plan.workflowId,
-            path,
-            status: 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 === GraphExecutionStatus.FAILED);
-            if (firstFailure?.error) {
-                throw new GraphExecutionError(firstFailure.error.message, firstFailure.error.code ?? "GRAPH_EXECUTION_ERROR", firstFailure.error.details);
-            }
-            frame.finish();
-            await this.emitEvent(frame, {
-                type: GraphExecutionEventType.WORKFLOW_COMPLETED,
-                runId,
-                parentRunId: opts.parentRunId,
-                workflowId: plan.workflowId,
-                path,
-                status: GraphExecutionStatus.SUCCEEDED,
-                payload: { outputs: valueStore.getWorkflowValues() },
-            });
-            return buildGraphExecutionResult(frame, document, inputs, GraphExecutionStatus.SUCCEEDED, opts.metadata);
-        }
-        catch (error) {
-            frame.finish();
-            const errorPayload = this.toErrorPayload(error);
-            if (error instanceof GraphRunCancelledError ||
-                opts.abortSignal?.aborted === true) {
-                await this.emitEvent(frame, {
-                    type: GraphExecutionEventType.WORKFLOW_CANCELLED,
-                    runId,
-                    parentRunId: opts.parentRunId,
-                    workflowId: plan.workflowId,
-                    path,
-                    status: GraphExecutionStatus.CANCELLED,
-                    error: errorPayload,
-                });
-                return buildGraphExecutionResult(frame, document, inputs, GraphExecutionStatus.CANCELLED, opts.metadata);
-            }
-            await this.emitEvent(frame, {
-                type: GraphExecutionEventType.WORKFLOW_FAILED,
-                runId,
-                parentRunId: opts.parentRunId,
-                workflowId: plan.workflowId,
-                path,
-                status: GraphExecutionStatus.FAILED,
-                error: errorPayload,
-            });
-            return buildGraphExecutionResult(frame, document, inputs, 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, 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, GraphExecutionEventType.NODE_UNPINNED);
-    }
-    /**
-     * Creates a {@link GraphPinningService} backed by this engine's value store
-     * adapter.
-     */
-    createPinningService() {
-        const store = new GraphValueStore(this.valueStoreAdapter);
-        return new GraphPinningService(store, new GraphPinningPolicy(), new GraphPinningDependencyResolver());
-    }
-    /**
-     * Emits a pinning-related event to all observers.
-     */
-    async emitPinningEvent(nodeId, type) {
-        const factory = new 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 ?? 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: GraphExecutionEventType.NODE_STARTED,
-            runId: frame.runId,
-            workflowId: plan.workflowId,
-            nodeId: planNode.id,
-            path: nodePath,
-            status: GraphExecutionStatus.RUNNING,
-        });
-        this.emitNodeStateChanged(frame, plan, planNode, nodePath, GraphVisualState.RUNNING, 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: GraphExecutionStatus.CACHED,
-                    inputs,
-                    outputs: cached.outputs,
-                    startedAt,
-                    finishedAt,
-                    fromCache: true,
-                    pinned: true,
-                    events: [],
-                };
-                frame.recordNodeResult(result);
-                await this.emitEvent(frame, {
-                    type: GraphExecutionEventType.NODE_CACHE_HIT,
-                    runId: frame.runId,
-                    workflowId: plan.workflowId,
-                    nodeId: planNode.id,
-                    path: nodePath,
-                    status: GraphExecutionStatus.CACHED,
-                    payload: { outputs: cached.outputs },
-                });
-                await this.emitEvent(frame, {
-                    type: GraphExecutionEventType.NODE_COMPLETED,
-                    runId: frame.runId,
-                    workflowId: plan.workflowId,
-                    nodeId: planNode.id,
-                    path: nodePath,
-                    status: GraphExecutionStatus.SUCCEEDED,
-                    payload: { outputs: cached.outputs, fromCache: true },
-                });
-                this.emitNodeStateChanged(frame, plan, planNode, nodePath, GraphVisualState.SUCCEEDED, GraphExecutionStatus.SUCCEEDED);
-                return;
-            }
-        }
-        try {
-            const context = new 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: GraphExecutionStatus.SUCCEEDED,
-                inputs,
-                outputs,
-                startedAt,
-                finishedAt,
-                events: [],
-            };
-            frame.recordNodeResult(result);
-            await this.emitEvent(frame, {
-                type: GraphExecutionEventType.NODE_COMPLETED,
-                runId: frame.runId,
-                workflowId: plan.workflowId,
-                nodeId: planNode.id,
-                path: nodePath,
-                status: GraphExecutionStatus.SUCCEEDED,
-                payload: { outputs },
-            });
-            this.emitNodeStateChanged(frame, plan, planNode, nodePath, GraphVisualState.SUCCEEDED, GraphExecutionStatus.SUCCEEDED);
-        }
-        catch (error) {
-            const finishedAt = new Date();
-            const errorPayload = this.toErrorPayload(error);
-            const result = {
-                nodeId: planNode.id,
-                status: GraphExecutionStatus.FAILED,
-                inputs,
-                error: errorPayload,
-                startedAt,
-                finishedAt,
-                events: [],
-            };
-            frame.recordNodeResult(result);
-            await this.emitEvent(frame, {
-                type: GraphExecutionEventType.NODE_FAILED,
-                runId: frame.runId,
-                workflowId: plan.workflowId,
-                nodeId: planNode.id,
-                path: nodePath,
-                status: GraphExecutionStatus.FAILED,
-                error: errorPayload,
-            });
-            this.emitNodeStateChanged(frame, plan, planNode, nodePath, GraphVisualState.FAILED, 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 === 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: GraphExecutionEventType.NODE_SKIPPED,
-            runId: frame.runId,
-            workflowId: plan.workflowId,
-            nodeId: planNode.id,
-            path: nodePath,
-            status: GraphExecutionStatus.SKIPPED,
-            payload: { reason: "branchNotSelected" },
-        });
-        const result = {
-            nodeId: planNode.id,
-            status: GraphExecutionStatus.SKIPPED,
-            inputs: {},
-            startedAt,
-            finishedAt: new Date(),
-            events: [],
-        };
-        frame.recordNodeResult(result);
-        this.emitNodeStateChanged(frame, plan, planNode, nodePath, GraphVisualState.SKIPPED, 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.disabledBehaviorOf(planNode.instance, plan.resolved.document.settings);
-        await this.emitEvent(frame, {
-            type: GraphExecutionEventType.NODE_SKIPPED,
-            runId: frame.runId,
-            workflowId: plan.workflowId,
-            nodeId: planNode.id,
-            path: nodePath,
-            status: GraphExecutionStatus.SKIPPED,
-            payload: { disabled: true, behavior },
-        });
-        if (behavior === "skip") {
-            const result = {
-                nodeId: planNode.id,
-                status: GraphExecutionStatus.SKIPPED,
-                inputs: {},
-                startedAt,
-                finishedAt: new Date(),
-                events: [],
-            };
-            frame.recordNodeResult(result);
-            this.emitNodeStateChanged(frame, plan, planNode, nodePath, GraphVisualState.SKIPPED, 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: GraphExecutionStatus.SUCCEEDED,
-            inputs,
-            outputs,
-            startedAt,
-            finishedAt: new Date(),
-            events: [],
-        };
-        frame.recordNodeResult(result);
-        this.emitNodeStateChanged(frame, plan, planNode, nodePath, GraphVisualState.SUCCEEDED, 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 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 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 (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 (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 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();
-        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();
-        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 === GRAPH_WORKFLOW_BOUNDARY) {
-                frame.valueStore.setWorkflowOutput(edge.targetPort, value);
-            }
-            this.emitEdgeStateChanged(frame, plan, planNode, edge, GraphVisualState.SUCCEEDED, GraphExecutionStatus.SUCCEEDED);
-            this.emitEvent(frame, {
-                type: 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: 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: 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: 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 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) };
-    }
-}
-//# sourceMappingURL=GraphExecutionEngine.js.map