@codemation/core 0.3.0 → 0.5.0

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);
     }

package/src/testing/ItemHarnessNode.ts

@@ -1,24 +1,18 @@
-import type { Item, ItemNode, Items, NodeExecutionContext } from "../types";
+import type { Item, RunnableNode, RunnableNodeExecuteArgs } from "../types";
 
 import type { ItemHarnessNodeConfig } from "./ItemHarnessNodeConfig";
 
 /**
  * Item-mode harness node for engine tests (see {@link ItemHarnessNodeConfig}).
  */
-export class ItemHarnessNode implements ItemNode<ItemHarnessNodeConfig<any, any, any>, unknown, unknown> {
+export class ItemHarnessNode implements RunnableNode<ItemHarnessNodeConfig<any, any>> {
   readonly kind = "node" as const;
   readonly outputPorts = ["main"] as const;
 
-  async executeOne(args: {
-    input: unknown;
-    item: Item;
-    itemIndex: number;
-    items: Items;
-    ctx: NodeExecutionContext<ItemHarnessNodeConfig<any, any, any>>;
-  }): Promise<unknown> {
+  async execute(args: RunnableNodeExecuteArgs<ItemHarnessNodeConfig<any, any>>): Promise<unknown> {
     return await args.ctx.config.runOne({
       input: args.input as never,
-      item: args.item,
+      item: args.item as Item,
       itemIndex: args.itemIndex,
       items: args.items,
       ctx: args.ctx,

package/src/testing/ItemHarnessNodeConfig.ts

@@ -1,19 +1,15 @@
 import type { ZodType } from "zod";
 
 import type { TypeToken } from "../di";
-import type { Item, ItemInputMapper, Items, NodeExecutionContext, RunnableNodeConfig } from "../types";
+import type { Item, Items, NodeExecutionContext, RunnableNodeConfig } from "../types";
 
 import { ItemHarnessNode } from "./ItemHarnessNode";
 
 /**
- * Item-mode harness node config for engine tests: engine applies {@link RunnableNodeConfig.inputSchema} +
- * optional {@link RunnableNodeConfig.mapInput}, then {@link ItemHarnessNode.executeOne} per item.
+ * Item-mode harness node config for engine tests: engine applies {@link RunnableNodeConfig.inputSchema},
+ * then {@link ItemHarnessNode.execute} per item.
  */
-export class ItemHarnessNodeConfig<TIn = unknown, TOut = unknown, TWire = TIn> implements RunnableNodeConfig<
-  TIn,
-  TOut,
-  TWire
-> {
+export class ItemHarnessNodeConfig<TIn = unknown, TOut = unknown> implements RunnableNodeConfig<TIn, TOut> {
   readonly kind = "node" as const;
   readonly type: TypeToken<unknown> = ItemHarnessNode;
 
@@ -22,21 +18,16 @@ export class ItemHarnessNodeConfig<TIn = unknown, TOut = unknown, TWire = TIn> i
     public readonly inputSchema: ZodType<TIn>,
     public readonly runOne: (args: {
       input: TIn;
-      item: Item<TWire>;
+      item: Item<TIn>;
       itemIndex: number;
-      items: Items<TWire>;
-      ctx: NodeExecutionContext<ItemHarnessNodeConfig<TIn, TOut, TWire>>;
+      items: Items<TIn>;
+      ctx: NodeExecutionContext<ItemHarnessNodeConfig<TIn, TOut>>;
     }) => TOut | Promise<TOut>,
     public readonly opts: Readonly<{
       id?: string;
-      mapInput?: ItemInputMapper<TWire, TIn>;
     }> = {},
   ) {}
 
-  get mapInput(): ItemInputMapper<TWire, TIn> | undefined {
-    return this.opts.mapInput;
-  }
-
   get id(): string | undefined {
     return this.opts.id;
   }

package/src/testing/RegistrarEngineTestKitFactory.ts

@@ -32,6 +32,7 @@ import type { RegistrarEngineTestKitHandle, RegistrarEngineTestKitOptions } from
 import { ItemHarnessNode } from "./ItemHarnessNode";
 import { SubWorkflowRunnerNode } from "./SubWorkflowRunnerTestNode";
 import { WorkflowTestHarnessManualTriggerNode } from "./WorkflowTestHarnessManualTrigger";
+import { SwitchHarnessNode } from "./SwitchHarnessNode";
 
 export class RegistrarEngineTestKitFactory {
   static create(options: RegistrarEngineTestKitOptions = {}): RegistrarEngineTestKitHandle {
@@ -110,6 +111,7 @@ export class RegistrarEngineTestKitFactory {
       new SubWorkflowRunnerNode(workflowRunner as WorkflowRunnerService),
     );
     dependencyContainer.registerInstance(ItemHarnessNode, new ItemHarnessNode());
+    dependencyContainer.registerInstance(SwitchHarnessNode, new SwitchHarnessNode());
     dependencyContainer.registerInstance(
       WorkflowTestHarnessManualTriggerNode,
       new WorkflowTestHarnessManualTriggerNode(),

package/src/testing/SubWorkflowRunnerTestNode.ts

@@ -1,16 +1,8 @@
 /* eslint-disable codemation/single-class-per-file -- Runnable config and implementation share a TypeToken pairing. */
 import type { WorkflowRunnerService } from "../contracts/runtimeTypes";
 import type { TypeToken } from "../di";
-import type {
-  Item,
-  Items,
-  NodeExecutionContext,
-  NodeId,
-  NodeOutputs,
-  Node,
-  RunnableNodeConfig,
-  WorkflowId,
-} from "../types";
+import type { Item, NodeId, RunnableNode, RunnableNodeConfig, RunnableNodeExecuteArgs, WorkflowId } from "../types";
+import { emitPorts } from "../contracts/emitPorts";
 
 /**
  * Test harness subworkflow runner (mirrors integration patterns; lives under {@link "@codemation/core/testing"}).
@@ -22,6 +14,9 @@ export class SubWorkflowRunnerConfig<TInputJson = unknown, TOutputJson = unknown
   readonly kind = "node" as const;
   readonly type: TypeToken<unknown> = SubWorkflowRunnerNode;
 
+  readonly workflowId: WorkflowId;
+  readonly startAt: NodeId | undefined;
+
   constructor(
     public readonly name: string,
     public readonly args: Readonly<{
@@ -30,7 +25,10 @@ export class SubWorkflowRunnerConfig<TInputJson = unknown, TOutputJson = unknown
       id?: string;
       execution?: Readonly<{ hint?: "local" | "worker"; queue?: string }>;
     }>,
-  ) {}
+  ) {
+    this.workflowId = args.workflowId;
+    this.startAt = args.startAt;
+  }
 
   get id(): string | undefined {
     return this.args.id;
@@ -39,45 +37,32 @@ export class SubWorkflowRunnerConfig<TInputJson = unknown, TOutputJson = unknown
   get execution(): Readonly<{ hint?: "local" | "worker"; queue?: string }> | undefined {
     return this.args.execution;
   }
-
-  get workflowId(): WorkflowId {
-    return this.args.workflowId;
-  }
-
-  get startAt(): NodeId | undefined {
-    return this.args.startAt;
-  }
 }
 
-export class SubWorkflowRunnerNode implements Node<SubWorkflowRunnerConfig<any, any>> {
+export class SubWorkflowRunnerNode implements RunnableNode<SubWorkflowRunnerConfig<any, any>> {
   readonly kind = "node" as const;
   readonly outputPorts = ["main"] as const;
 
   constructor(private readonly workflows: WorkflowRunnerService) {}
 
-  async execute(items: Items, ctx: NodeExecutionContext<SubWorkflowRunnerConfig<any, any>>): Promise<NodeOutputs> {
-    const out: Item[] = [];
-    for (let i = 0; i < items.length; i++) {
-      const current = items[i]!;
-      const result = await this.workflows.runById({
-        workflowId: ctx.config.workflowId,
-        startAt: ctx.config.startAt,
-        items: [current],
-        parent: {
-          runId: ctx.runId,
-          workflowId: ctx.workflowId,
-          nodeId: ctx.nodeId,
-          subworkflowDepth: ctx.subworkflowDepth,
-          engineMaxNodeActivations: ctx.engineMaxNodeActivations,
-          engineMaxSubworkflowDepth: ctx.engineMaxSubworkflowDepth,
-        },
-      });
-      if (result.status !== "completed") {
-        throw new Error(`Subworkflow ${ctx.config.workflowId} did not complete (status=${result.status})`);
-      }
-      out.push(...result.outputs);
+  async execute(args: RunnableNodeExecuteArgs<SubWorkflowRunnerConfig<any, any>>): Promise<unknown> {
+    const current = args.item as Item;
+    const result = await this.workflows.runById({
+      workflowId: args.ctx.config.workflowId,
+      startAt: args.ctx.config.startAt,
+      items: [current],
+      parent: {
+        runId: args.ctx.runId,
+        workflowId: args.ctx.workflowId,
+        nodeId: args.ctx.nodeId,
+        subworkflowDepth: args.ctx.subworkflowDepth,
+        engineMaxNodeActivations: args.ctx.engineMaxNodeActivations,
+        engineMaxSubworkflowDepth: args.ctx.engineMaxSubworkflowDepth,
+      },
+    });
+    if (result.status !== "completed") {
+      throw new Error(`Subworkflow ${args.ctx.config.workflowId} did not complete (status=${result.status})`);
     }
-
-    return { main: out };
+    return emitPorts({ main: result.outputs });
   }
 }

package/src/testing/SwitchHarnessNode.ts

@@ -0,0 +1,54 @@
+import type { TypeToken } from "../di";
+import type {
+  Item,
+  Items,
+  NodeExecutionContext,
+  RunnableNode,
+  RunnableNodeConfig,
+  RunnableNodeExecuteArgs,
+} from "../types";
+import { emitPorts } from "../contracts/emitPorts";
+
+export class SwitchHarnessNode implements RunnableNode<SwitchHarnessNodeConfig<any>> {
+  readonly kind = "node" as const;
+  readonly outputPorts = [] as const;
+
+  async execute(args: RunnableNodeExecuteArgs<SwitchHarnessNodeConfig<any>>): Promise<unknown> {
+    const key = await Promise.resolve(
+      args.ctx.config.cfg.resolveCaseKey(args.item as Item, args.itemIndex, args.items, args.ctx),
+    );
+    const { cases, defaultCase } = args.ctx.config.cfg;
+    const port = cases.includes(key) ? key : defaultCase;
+    return emitPorts({
+      [port]: [args.item],
+    });
+  }
+}
+
+export class SwitchHarnessNodeConfig<TInputJson = unknown> implements RunnableNodeConfig<TInputJson, TInputJson> {
+  readonly kind = "node" as const;
+  readonly type: TypeToken<unknown> = SwitchHarnessNode;
+  readonly lineageCarry = "carryThrough" as const;
+  readonly declaredOutputPorts: ReadonlyArray<string>;
+
+  constructor(
+    public readonly name: string,
+    public readonly cfg: Readonly<{
+      cases: readonly string[];
+      defaultCase: string;
+      resolveCaseKey: (
+        item: Item<TInputJson>,
+        index: number,
+        items: Items<TInputJson>,
+        ctx: NodeExecutionContext<SwitchHarnessNodeConfig<TInputJson>>,
+      ) => string | Promise<string>;
+    }>,
+    public readonly opts: Readonly<{ id?: string }> = {},
+  ) {
+    this.declaredOutputPorts = [...new Set([...cfg.cases, cfg.defaultCase])].sort();
+  }
+
+  get id(): string | undefined {
+    return this.opts.id;
+  }
+}

package/src/types/index.ts

@@ -1,3 +1,6 @@
+export * from "../contracts/emitPorts";
+export * from "../contracts/itemMeta";
+export * from "../contracts/itemValue";
 export * from "../contracts/retryPolicySpec.types";
 export * from "../contracts/NoRetryPolicy";
 export * from "../contracts/RetryPolicy";