@codemation/core 0.3.0 → 0.4.0

package/src/execution/NodeOutputNormalizer.ts

@@ -0,0 +1,90 @@
+import { isPortsEmission, isUnbrandedPortsEmissionShape } from "../contracts/emitPorts";
+import type { PortsEmission } from "../contracts/emitPorts";
+import type { Item, JsonNonArray, LineageCarryPolicy, NodeOutputs, OutputPortKey, Items } from "../types";
+
+export class NodeOutputNormalizer {
+  normalizeExecuteResult(
+    args: Readonly<{
+      baseItem: Item;
+      raw: unknown;
+      carry: LineageCarryPolicy;
+    }>,
+  ): NodeOutputs {
+    const { baseItem, raw, carry } = args;
+    if (isPortsEmission(raw)) {
+      return this.emitPortsToOutputs(baseItem, raw, carry);
+    }
+    if (isUnbrandedPortsEmissionShape(raw)) {
+      throw new Error(
+        "execute() returned an unbranded `{ ports: ... }` object. Use emitPorts(...) for multi-port runnable outputs.",
+      );
+    }
+    if (Array.isArray(raw)) {
+      return this.arrayFanOutToMain(baseItem, raw, carry);
+    }
+    if (this.isItemLike(raw)) {
+      return { main: [this.applyLineage(baseItem, raw, carry)] };
+    }
+    return {
+      main: [this.applyLineage(baseItem, { json: raw as JsonNonArray }, carry)],
+    };
+  }
+
+  private arrayFanOutToMain(baseItem: Item, raw: readonly unknown[], carry: LineageCarryPolicy): NodeOutputs {
+    for (const el of raw) {
+      if (Array.isArray(el)) {
+        throw new Error(
+          "execute() fan-out arrays must contain only non-array JSON elements (nested arrays belong inside objects).",
+        );
+      }
+    }
+    const main: Item[] = raw.map((json) => this.applyLineage(baseItem, { json: json as JsonNonArray }, carry));
+    return { main };
+  }
+
+  private emitPortsToOutputs(baseItem: Item, emission: PortsEmission, carry: LineageCarryPolicy): NodeOutputs {
+    const out: NodeOutputs = {};
+    for (const [port, payload] of Object.entries(emission.ports)) {
+      if (payload === undefined) {
+        continue;
+      }
+      out[port as OutputPortKey] = this.normalizePortPayload(baseItem, payload, carry);
+    }
+    return out;
+  }
+
+  private normalizePortPayload(
+    baseItem: Item,
+    payload: Items | ReadonlyArray<JsonNonArray>,
+    carry: LineageCarryPolicy,
+  ): Items {
+    if (payload.length === 0) {
+      return [];
+    }
+    const el0 = payload[0] as unknown;
+    if (this.isItemLike(el0)) {
+      return (payload as Items).map((it) => this.applyLineage(baseItem, it, carry));
+    }
+    return (payload as readonly JsonNonArray[]).map((json) => this.applyLineage(baseItem, { json }, carry));
+  }
+
+  private isItemLike(value: unknown): value is Item {
+    return typeof value === "object" && value !== null && "json" in value;
+  }
+
+  private applyLineage(baseItem: Item, next: Item, carry: LineageCarryPolicy): Item {
+    if (carry === "carryThrough") {
+      return {
+        ...baseItem,
+        ...next,
+        json: next.json,
+      };
+    }
+    return {
+      json: next.json,
+      ...(next.binary ? { binary: next.binary } : {}),
+      ...(next.meta ? { meta: next.meta } : {}),
+      ...(next.paired ? { paired: next.paired } : {}),
+    };
+  }
+}

package/src/execution/index.ts

@@ -5,6 +5,8 @@ export { CredentialResolverFactory } from "./CredentialResolverFactory";
 export { DefaultAsyncSleeper } from "./DefaultAsyncSleeper";
 export { DefaultExecutionContextFactory } from "./DefaultExecutionContextFactory";
 export { InProcessRetryRunner } from "./InProcessRetryRunner";
+export { ItemValueResolver } from "./ItemValueResolver";
+export { NodeOutputNormalizer } from "./NodeOutputNormalizer";
 export { InProcessRetryRunnerFactory } from "./InProcessRetryRunnerFactory";
 export { NodeActivationRequestComposer } from "./NodeActivationRequestComposer";
 export { NodeExecutionSnapshotFactory } from "./NodeExecutionSnapshotFactory";

package/src/index.ts

@@ -18,6 +18,8 @@ export {
   DefaultAsyncSleeper,
   DefaultExecutionContextFactory,
   InProcessRetryRunner,
+  ItemValueResolver,
+  NodeOutputNormalizer,
 } from "./execution";
 export { EngineExecutionLimitsPolicy, type EngineExecutionLimitsPolicyConfig } from "./policies";
 export { InMemoryBinaryStorage, InMemoryRunDataFactory } from "./runStorage";

package/src/orchestration/NodeExecutionRequestHandlerService.ts

@@ -66,7 +66,6 @@ export class NodeExecutionRequestHandlerService implements NodeExecutionRequestH
     const resolvedParent = request.parent ?? state.parent;
     const data = this.runDataFactory.create(state.outputsByNode);
     const limits = this.resolveEngineLimitsFromState(state);
-    const persistedInput = pendingExecution.inputsByPort.in ?? request.input;
     const base = this.runExecutionContextFactory.create({
       runId: state.runId,
       workflowId: state.workflowId,
@@ -78,21 +77,43 @@ export class NodeExecutionRequestHandlerService implements NodeExecutionRequestH
       data,
       nodeState: this.nodeStatePublisherFactory.create(state.runId, state.workflowId, resolvedParent),
     });
-    const activationRequest = this.nodeActivationRequestComposer.createSingleFromDefinitionWithActivation({
-      activationId: request.activationId,
-      runId: request.runId,
-      workflowId: request.workflowId,
-      parent: resolvedParent,
-      executionOptions: request.executionOptions ?? state.executionOptions,
-      base,
-      data,
-      definition: {
-        id: definition.id,
-        config: definition.config,
-      },
-      batchId: pendingExecution.batchId ?? "batch_1",
-      input: persistedInput,
-    });
+
+    const inputsByPort = pendingExecution.inputsByPort;
+    const portKeys = Object.keys(inputsByPort);
+    const kind = portKeys.length === 1 && portKeys[0] === "in" ? ("single" as const) : ("multi" as const);
+    const batchId = pendingExecution.batchId ?? "batch_1";
+    const activationRequest =
+      kind === "multi"
+        ? this.nodeActivationRequestComposer.createMultiFromDefinitionWithActivation({
+            activationId: request.activationId,
+            runId: request.runId,
+            workflowId: request.workflowId,
+            parent: resolvedParent,
+            executionOptions: request.executionOptions ?? state.executionOptions,
+            base,
+            data,
+            definition: {
+              id: definition.id,
+              config: definition.config,
+            },
+            batchId,
+            inputsByPort,
+          })
+        : this.nodeActivationRequestComposer.createSingleFromDefinitionWithActivation({
+            activationId: request.activationId,
+            runId: request.runId,
+            workflowId: request.workflowId,
+            parent: resolvedParent,
+            executionOptions: request.executionOptions ?? state.executionOptions,
+            base,
+            data,
+            definition: {
+              id: definition.id,
+              config: definition.config,
+            },
+            batchId,
+            input: inputsByPort.in ?? request.input ?? [],
+          });
 
     await this.continuation.markNodeRunning({
       runId: activationRequest.runId,
@@ -131,7 +152,7 @@ export class NodeExecutionRequestHandlerService implements NodeExecutionRequestH
   }
 
   private async resumeAfterExecutionResult(
-    request: ReturnType<NodeActivationRequestComposer["createSingleFromDefinitionWithActivation"]>,
+    request: Readonly<{ runId: string; activationId: string; nodeId: string }>,
     outputs: unknown,
   ): Promise<void> {
     try {
@@ -147,7 +168,7 @@ export class NodeExecutionRequestHandlerService implements NodeExecutionRequestH
   }
 
   private async resumeAfterExecutionError(
-    request: ReturnType<NodeActivationRequestComposer["createSingleFromDefinitionWithActivation"]>,
+    request: Readonly<{ runId: string; activationId: string; nodeId: string }>,
     error: Error,
   ): Promise<void> {
     try {

package/src/orchestration/RunContinuationService.ts

@@ -335,7 +335,7 @@ export class RunContinuationService {
         nextNodeId: next.nodeId,
         request,
         completedSnapshot,
-        nextNodeSnapshotsByNodeId,
+        nextNodeSnapshotsByNodeId: nextNodeSnapshotsByNodeId,
         outputsByNode: data.dump(),
         engineCounters,
         error,
@@ -653,6 +653,12 @@ export class RunContinuationService {
     planner.applyOutputs(queue, { fromNodeId: args.args.nodeId, outputs: triggerOutputs as any, batchId });
     const next = planner.nextActivation(queue);
 
+    const finishedAt = completedSnapshot.finishedAt ?? completedSnapshot.updatedAt;
+    const mergedSnapshots = {
+      ...(args.state.nodeSnapshotsByNodeId ?? {}),
+      [args.args.nodeId]: completedSnapshot,
+    };
+
     if (!next) {
       const lastNodeId = WorkflowExecutableNodeClassifierFactory.create(
         args.workflow,
@@ -664,11 +670,8 @@ export class RunContinuationService {
         status: "completed",
         queue: [],
         outputsByNode: data.dump(),
-        nodeSnapshotsByNodeId: {
-          ...(args.state.nodeSnapshotsByNodeId ?? {}),
-          [args.args.nodeId]: completedSnapshot,
-        },
-        finishedAtIso: completedSnapshot.finishedAt ?? completedSnapshot.updatedAt,
+        nodeSnapshotsByNodeId: mergedSnapshots,
+        finishedAtIso: finishedAt,
       });
       await this.workflowExecutionRepository.save(completedState);
       await this.nodeEventPublisher.publish("nodeCompleted", completedSnapshot);
@@ -705,11 +708,8 @@ export class RunContinuationService {
         status: "failed",
         queue: queue.map((q) => ({ ...q })),
         outputsByNode: data.dump(),
-        nodeSnapshotsByNodeId: {
-          ...(args.state.nodeSnapshotsByNodeId ?? {}),
-          [args.args.nodeId]: completedSnapshot,
-        },
-        finishedAtIso: completedSnapshot.finishedAt ?? completedSnapshot.updatedAt,
+        nodeSnapshotsByNodeId: mergedSnapshots,
+        finishedAtIso: finishedAt,
       });
       await this.workflowExecutionRepository.save(failedState);
       await this.nodeEventPublisher.publish("nodeCompleted", completedSnapshot);
@@ -765,11 +765,6 @@ export class RunContinuationService {
       nodeDefinition: nextDefinition,
     });
 
-    const mergedSnapshots = {
-      ...(args.state.nodeSnapshotsByNodeId ?? {}),
-      [args.args.nodeId]: completedSnapshot,
-    };
-
     try {
       const { queuedSnapshot, result } = await this.activationEnqueueService.enqueueActivationWithSnapshot({
         runId: args.state.runId,
@@ -800,7 +795,6 @@ export class RunContinuationService {
       return result;
     } catch (cause) {
       const error = cause instanceof Error ? cause : new Error(String(cause));
-      const finishedAt = completedSnapshot.finishedAt ?? completedSnapshot.updatedAt;
       const result = await this.terminateRunAfterActivationEnqueueRejected({
         wf: args.workflow,
         state: args.state,

package/src/planning/CurrentStateFrontierPlanner.ts

@@ -200,7 +200,7 @@ export class CurrentStateFrontierPlanner {
         continue;
       }
       const incomingEdges = this.topology.incomingByNode.get(nodeId) ?? [];
-      const isFrontier = incomingEdges.every((edge) => this.isEdgeSatisfied(currentState, nodeId, edge.input));
+      const isFrontier = incomingEdges.every((edge) => this.isEdgeSatisfied(currentState, nodeId, edge.collectKey));
       if (isFrontier) {
         frontierNodeIds.push(nodeId);
       }
@@ -235,7 +235,7 @@ export class CurrentStateFrontierPlanner {
     requiredNodeIds.add(nodeId);
     for (const edge of this.topology.incomingByNode.get(nodeId) ?? []) {
       if (
-        !this.isEdgeSatisfied(currentState, nodeId, edge.input) ||
+        !this.isEdgeSatisfied(currentState, nodeId, edge.collectKey) ||
         this.isNodeSatisfiedByOutputsOnly(currentState, edge.from.nodeId)
       ) {
         this.collectRequiredNode(requiredNodeIds, currentState, edge.from.nodeId);
@@ -249,7 +249,7 @@ export class CurrentStateFrontierPlanner {
       return [];
     }
     const expectedInputs = this.topology.expectedInputsByNode.get(nodeId) ?? [];
-    const usesCollect = expectedInputs.length !== 1 || expectedInputs[0] !== "in";
+    const usesCollect = this.usesCollect(nodeId);
     if (usesCollect) {
       const received: Record<InputPortKey, Items> = {};
       for (const input of expectedInputs) {
@@ -268,7 +268,7 @@ export class CurrentStateFrontierPlanner {
       ];
     }
     const input = expectedInputs[0] ?? "in";
-    const incomingEdge = incomingEdges.find((edge) => edge.input === input);
+    const incomingEdge = incomingEdges.find((edge) => edge.collectKey === input);
     return [
       {
         nodeId,
@@ -298,26 +298,31 @@ export class CurrentStateFrontierPlanner {
     return this.hasOutputs(currentState, nodeId) && !this.hasCompletedSnapshot(currentState, nodeId);
   }
 
-  private isEdgeSatisfied(currentState: RunCurrentState, nodeId: NodeId, input: InputPortKey): boolean {
-    const incomingEdge = (this.topology.incomingByNode.get(nodeId) ?? []).find((edge) => edge.input === input);
+  private isEdgeSatisfied(currentState: RunCurrentState, nodeId: NodeId, collectKey: InputPortKey): boolean {
+    const incomingEdge = (this.topology.incomingByNode.get(nodeId) ?? []).find(
+      (edge) => edge.collectKey === collectKey,
+    );
     if (!incomingEdge) {
       return false;
     }
-    if (!this.hasOutputPort(currentState, incomingEdge.from.nodeId, incomingEdge.from.output)) {
+    const fromNodeId = incomingEdge.from.nodeId;
+    if (!this.isNodeSatisfied(currentState, fromNodeId)) {
       return false;
     }
     if (this.usesCollect(nodeId)) {
       return true;
     }
-    const items = this.resolveOutputItems(currentState, incomingEdge.from.nodeId, incomingEdge.from.output);
+    const items = this.resolveOutputItems(currentState, fromNodeId, incomingEdge.from.output);
     if (items.length > 0) {
       return true;
     }
-    return this.shouldContinueAfterEmptyOutputFromSource(incomingEdge.from.nodeId);
+    return this.shouldContinueAfterEmptyOutputFromSource(fromNodeId);
   }
 
-  private resolveInput(currentState: RunCurrentState, nodeId: NodeId, input: InputPortKey): Items {
-    const incomingEdge = (this.topology.incomingByNode.get(nodeId) ?? []).find((edge) => edge.input === input);
+  private resolveInput(currentState: RunCurrentState, nodeId: NodeId, collectKey: InputPortKey): Items {
+    const incomingEdge = (this.topology.incomingByNode.get(nodeId) ?? []).find(
+      (edge) => edge.collectKey === collectKey,
+    );
     if (!incomingEdge) {
       return [];
     }
@@ -333,21 +338,16 @@ export class CurrentStateFrontierPlanner {
     return snapshot?.status === "completed" || snapshot?.status === "skipped";
   }
 
-  private hasOutputPort(currentState: RunCurrentState, nodeId: NodeId, output: OutputPortKey): boolean {
-    const outputs = currentState.outputsByNode[nodeId];
-    if (!outputs) {
-      return false;
-    }
-    return Object.prototype.hasOwnProperty.call(outputs, output);
-  }
-
   private resolveOutputItems(currentState: RunCurrentState, nodeId: NodeId, output: OutputPortKey): Items {
     return currentState.outputsByNode[nodeId]?.[output] ?? [];
   }
 
   private usesCollect(nodeId: NodeId): boolean {
     const expectedInputs = this.topology.expectedInputsByNode.get(nodeId) ?? [];
-    return expectedInputs.length !== 1 || expectedInputs[0] !== "in";
+    if (expectedInputs.length !== 1 || expectedInputs[0] !== "in") {
+      return true;
+    }
+    return (this.topology.incomingByNode.get(nodeId) ?? []).length > 1;
   }
 
   private shouldContinueAfterEmptyOutputFromSource(nodeId: NodeId): boolean {

package/src/planning/RunQueuePlanner.ts

@@ -1,6 +1,7 @@
 import type { InputPortKey, Items, NodeId, OutputPortKey, RunQueueEntry } from "../types";
 
 import { WorkflowTopology } from "./WorkflowTopologyPlanner";
+import type { TopologyOutgoingEdge } from "./WorkflowTopologyPlanner";
 
 export type PlannedActivation =
   | Readonly<{ kind: "single"; nodeId: NodeId; input: Items; batchId: string }>
@@ -25,9 +26,9 @@ export class RunQueuePlanner {
       }
 
       const inst = this.nodeInstances.get(toNodeId);
-      if (!this.isMultiInputNode(inst)) {
+      if (!this.isMultiInputNode(inst) && !this.supportsEngineFanInMerge(inst)) {
         throw new Error(
-          `Node ${toNodeId} has ${inputs.length} inbound edges. Insert a Merge node to combine branches.`,
+          `Node ${toNodeId} has ${inputs.length} inbound edges but does not support multi-input execution.`,
         );
       }
     }
@@ -39,7 +40,7 @@ export class RunQueuePlanner {
       if (e.output !== "main") continue;
       this.enqueueEdge(queue, {
         batchId: args.batchId,
-        to: e.to,
+        to: this.toEnqueueTarget(e),
         from: { nodeId: args.startNodeId, output: "main" },
         items: args.items,
       });
@@ -55,7 +56,7 @@ export class RunQueuePlanner {
       const outItems = (args.outputs as any)[e.output] ?? [];
       this.enqueueEdge(queue, {
         batchId: args.batchId,
-        to: e.to,
+        to: this.toEnqueueTarget(e),
         from: { nodeId: args.fromNodeId, output: e.output },
         items: outItems,
       });
@@ -157,40 +158,54 @@ export class RunQueuePlanner {
    */
   private usesTopologyCollectMerge(toNodeId: NodeId): boolean {
     const expectedInputs = this.topology.expectedInputsByNode.get(toNodeId) ?? [];
-    return expectedInputs.length !== 1 || expectedInputs[0] !== "in";
+    if (expectedInputs.length !== 1 || expectedInputs[0] !== "in") {
+      return true;
+    }
+    return (this.topology.incomingByNode.get(toNodeId) ?? []).length > 1;
+  }
+
+  private toEnqueueTarget(edge: TopologyOutgoingEdge): Readonly<{
+    nodeId: NodeId;
+    input: InputPortKey;
+    collectKey: InputPortKey;
+  }> {
+    return edge.to;
   }
 
   private enqueueEdge(
     queue: RunQueueEntry[],
     args: Readonly<{
       batchId: string;
-      to: { nodeId: NodeId; input: InputPortKey };
+      to: { nodeId: NodeId; input: InputPortKey; collectKey: InputPortKey };
       from: { nodeId: NodeId; output: OutputPortKey };
       items: Items;
     }>,
+    emptyPathSourceNodeId?: NodeId,
   ): void {
     const target = this.nodeInstances.get(args.to.nodeId);
     const isMulti = this.usesTopologyCollectMerge(args.to.nodeId) || this.isMultiInputNode(target);
 
     if (!isMulti) {
       if (args.items.length === 0) {
-        if (this.shouldContinueAfterEmptyOutputFromSource(args.from.nodeId)) {
+        const continueSourceNodeId = emptyPathSourceNodeId ?? args.from.nodeId;
+        if (this.shouldContinueAfterEmptyOutputFromSource(continueSourceNodeId)) {
           queue.push({
             nodeId: args.to.nodeId,
             input: args.items,
-            toInput: args.to.input,
+            toInput: args.to.collectKey,
             batchId: args.batchId,
             from: args.from,
           });
           return;
         }
-        this.propagateEmptyPath(queue, args.to.nodeId, args.batchId);
+        const source = emptyPathSourceNodeId ?? args.from.nodeId;
+        this.propagateEmptyPath(queue, args.to.nodeId, args.batchId, source);
         return;
       }
       queue.push({
         nodeId: args.to.nodeId,
         input: args.items,
-        toInput: args.to.input,
+        toInput: args.to.collectKey,
         batchId: args.batchId,
         from: args.from,
       });
@@ -212,7 +227,7 @@ export class RunQueuePlanner {
     }
 
     const received = (collect.collect as any).received as Record<InputPortKey, Items>;
-    received[args.to.input] = args.items;
+    received[args.to.collectKey] = args.items;
   }
 
   private shouldContinueAfterEmptyOutputFromSource(fromNodeId: NodeId): boolean {
@@ -223,14 +238,23 @@ export class RunQueuePlanner {
     return def.config.continueWhenEmptyOutput === true;
   }
 
-  private propagateEmptyPath(queue: RunQueueEntry[], nodeId: NodeId, batchId: string): void {
+  private propagateEmptyPath(
+    queue: RunQueueEntry[],
+    nodeId: NodeId,
+    batchId: string,
+    emptyPathSourceNodeId: NodeId,
+  ): void {
     for (const edge of this.topology.outgoingByNode.get(nodeId) ?? []) {
-      this.enqueueEdge(queue, {
-        batchId,
-        to: edge.to,
-        from: { nodeId, output: edge.output },
-        items: [],
-      });
+      this.enqueueEdge(
+        queue,
+        {
+          batchId,
+          to: edge.to,
+          from: { nodeId, output: edge.output },
+          items: [],
+        },
+        emptyPathSourceNodeId,
+      );
     }
   }
 
@@ -238,6 +262,19 @@ export class RunQueuePlanner {
     return typeof (n as any)?.executeMulti === "function";
   }
 
+  private hasRunnableExecute(n: unknown): boolean {
+    return (
+      typeof n === "object" &&
+      n !== null &&
+      (n as { kind?: string }).kind === "node" &&
+      typeof (n as { execute?: unknown }).execute === "function"
+    );
+  }
+
+  private supportsEngineFanInMerge(n: unknown): boolean {
+    return this.hasRunnableExecute(n) && !this.isMultiInputNode(n);
+  }
+
   private describeUnsatisfiedCollect(queueEntry: RunQueueEntry): string {
     const batchId = queueEntry.batchId ?? "batch_1";
     const expectedInputs = queueEntry.collect?.expectedInputs ?? [];
@@ -287,7 +324,7 @@ export class RunQueuePlanner {
     const matches: string[] = [];
     for (const [sourceNodeId, edges] of this.topology.outgoingByNode.entries()) {
       for (const edge of edges) {
-        if (edge.to.nodeId === nodeId && edge.to.input === input) {
+        if (edge.to.nodeId === nodeId && edge.to.collectKey === input) {
           matches.push(this.formatNodeLabel(sourceNodeId));
         }
       }

package/src/planning/WorkflowTopologyPlanner.ts

@@ -3,17 +3,22 @@ import { WorkflowExecutableNodeClassifierFactory } from "../workflow/definition/
 
 type NodeDef = WorkflowDefinition["nodes"][number];
 
+export type TopologyIncomingEdge = Readonly<{
+  from: Readonly<{ nodeId: NodeId; output: OutputPortKey }>;
+  input: InputPortKey;
+  collectKey: InputPortKey;
+}>;
+
+export type TopologyOutgoingEdge = Readonly<{
+  output: OutputPortKey;
+  to: Readonly<{ nodeId: NodeId; input: InputPortKey; collectKey: InputPortKey }>;
+}>;
+
 export class WorkflowTopology {
   private constructor(
     public readonly defsById: ReadonlyMap<NodeId, NodeDef>,
-    public readonly outgoingByNode: ReadonlyMap<
-      NodeId,
-      ReadonlyArray<Readonly<{ output: OutputPortKey; to: Readonly<{ nodeId: NodeId; input: InputPortKey }> }>>
-    >,
-    public readonly incomingByNode: ReadonlyMap<
-      NodeId,
-      ReadonlyArray<Readonly<{ from: Readonly<{ nodeId: NodeId; output: OutputPortKey }>; input: InputPortKey }>>
-    >,
+    public readonly outgoingByNode: ReadonlyMap<NodeId, ReadonlyArray<TopologyOutgoingEdge>>,
+    public readonly incomingByNode: ReadonlyMap<NodeId, ReadonlyArray<TopologyIncomingEdge>>,
     public readonly expectedInputsByNode: ReadonlyMap<NodeId, ReadonlyArray<InputPortKey>>,
     public readonly rootNodeIds: ReadonlyArray<NodeId>,
   ) {}
@@ -25,46 +30,65 @@ export class WorkflowTopology {
       if (classifier.isExecutableNodeId(n.id)) defs.set(n.id, n);
     }
 
-    const outgoing = new Map<
-      NodeId,
-      Array<Readonly<{ output: OutputPortKey; to: Readonly<{ nodeId: NodeId; input: InputPortKey }> }>>
-    >();
+    const incomingByNode = new Map<NodeId, TopologyIncomingEdge[]>();
     for (const e of wf.edges) {
       if (!classifier.isExecutableNodeId(e.from.nodeId) || !classifier.isExecutableNodeId(e.to.nodeId)) {
         continue;
       }
-      const list = outgoing.get(e.from.nodeId) ?? [];
-      list.push({ output: e.from.output, to: { nodeId: e.to.nodeId, input: e.to.input } });
-      outgoing.set(e.from.nodeId, list);
+      const list = incomingByNode.get(e.to.nodeId) ?? [];
+      list.push({
+        from: { nodeId: e.from.nodeId, output: e.from.output },
+        input: e.to.input,
+        collectKey: e.to.input,
+      });
+      incomingByNode.set(e.to.nodeId, list);
+    }
+
+    const duplicateInputCounts = new Map<NodeId, Map<InputPortKey, number>>();
+    for (const [toNodeId, edges] of incomingByNode.entries()) {
+      const counts = new Map<InputPortKey, number>();
+      for (const edge of edges) {
+        counts.set(edge.input, (counts.get(edge.input) ?? 0) + 1);
+      }
+      duplicateInputCounts.set(toNodeId, counts);
     }
 
-    const incomingByNode = new Map<
-      NodeId,
-      Array<Readonly<{ from: Readonly<{ nodeId: NodeId; output: OutputPortKey }>; input: InputPortKey }>>
-    >();
+    for (const [toNodeId, edges] of incomingByNode.entries()) {
+      const counts = duplicateInputCounts.get(toNodeId) ?? new Map();
+      for (let i = 0; i < edges.length; i++) {
+        const edge = edges[i]!;
+        const dup = (counts.get(edge.input) ?? 0) > 1;
+        const collectKey = dup ? `${edge.from.nodeId}:${edge.from.output}` : edge.input;
+        edges[i] = { ...edge, collectKey };
+      }
+    }
+
+    const outgoing = new Map<NodeId, TopologyOutgoingEdge[]>();
     for (const e of wf.edges) {
       if (!classifier.isExecutableNodeId(e.from.nodeId) || !classifier.isExecutableNodeId(e.to.nodeId)) {
         continue;
       }
-      const list = incomingByNode.get(e.to.nodeId) ?? [];
-      list.push({ from: { nodeId: e.from.nodeId, output: e.from.output }, input: e.to.input });
-      incomingByNode.set(e.to.nodeId, list);
+      const counts = duplicateInputCounts.get(e.to.nodeId) ?? new Map();
+      const dup = (counts.get(e.to.input) ?? 0) > 1;
+      const collectKey = dup ? `${e.from.nodeId}:${e.from.output}` : e.to.input;
+      const list = outgoing.get(e.from.nodeId) ?? [];
+      list.push({
+        output: e.from.output,
+        to: { nodeId: e.to.nodeId, input: e.to.input, collectKey },
+      });
+      outgoing.set(e.from.nodeId, list);
     }
 
     const expected = new Map<NodeId, InputPortKey[]>();
-    for (const [toNodeId, inputs] of incomingByNode.entries()) {
-      const counts = new Map<InputPortKey, number>();
-      for (const edge of inputs) counts.set(edge.input, (counts.get(edge.input) ?? 0) + 1);
-      for (const [k, n] of counts.entries()) {
-        if (n > 1) throw new Error(`Node ${toNodeId} has multiple edges into input '${k}'. Use a Merge node upstream.`);
-      }
-
+    for (const [toNodeId, edges] of incomingByNode.entries()) {
       const order: InputPortKey[] = [];
       const seen = new Set<InputPortKey>();
-      for (const edge of inputs) {
-        if (seen.has(edge.input)) continue;
-        seen.add(edge.input);
-        order.push(edge.input);
+      for (const edge of edges) {
+        if (seen.has(edge.collectKey)) {
+          continue;
+        }
+        seen.add(edge.collectKey);
+        order.push(edge.collectKey);
       }
       expected.set(toNodeId, order);
     }