@codemation/core 0.3.0 → 0.5.0

package/src/contracts/runtimeTypes.ts

@@ -25,6 +25,7 @@ import type {
   NodeConfigBase,
   NodeId,
   NodeOutputs,
+  RunnableNodeConfig,
   OutputPortKey,
   ParentExecutionRef,
   RunDataFactory,
@@ -221,39 +222,55 @@ export interface EngineHost {
   workflows?: WorkflowRunnerService;
 }
 
-export interface Node<TConfig extends NodeConfigBase = NodeConfigBase> {
-  kind: "node";
-  outputPorts: ReadonlyArray<OutputPortKey>;
-  execute(items: Items, ctx: NodeExecutionContext<TConfig>): Promise<NodeOutputs>;
-}
-
 /**
- * Single-input runnable node with per-item execution on `main` only (1→1 default).
- * Engine applies {@link RunnableNodeConfig.mapInput} (if any) + `inputSchema.parse` before `executeOne`.
+ * Per-item runnable node: return JSON, an array to fan-out on `main`, or {@link emitPorts} for multi-port emission.
+ * Engine applies `inputSchema.parse(item.json)` and passes the result as `args.input` (wire `item.json` is unchanged).
  */
-export interface ItemNode<
-  TConfig extends NodeConfigBase = NodeConfigBase,
+export interface RunnableNodeExecuteArgs<
+  TConfig extends RunnableNodeConfig<any, any> = RunnableNodeConfig<any, any>,
   TInputJson = unknown,
-  TOutputJson = unknown,
+> {
+  readonly input: TInputJson;
+  readonly item: Item;
+  readonly itemIndex: number;
+  readonly items: Items;
+  readonly ctx: NodeExecutionContext<TConfig>;
+}
+
+export interface RunnableNode<
+  TConfig extends RunnableNodeConfig<any, any> = RunnableNodeConfig<any, any>,
+  TInputJson = unknown,
+  _TOutputJson = unknown,
 > {
   readonly kind: "node";
-  readonly outputPorts: readonly ["main"];
+  /**
+   * Declared output ports (e.g. `["main"]`).
+   *
+   * Prefer describing dynamic router ports (Switch) and fixed multi-ports (If true/false)
+   * via {@link NodeConfigBase.declaredOutputPorts}. Engine defaults to `["main"]` when omitted.
+   */
+  readonly outputPorts?: ReadonlyArray<OutputPortKey>;
   /** When omitted, engine uses {@link RunnableNodeConfig.inputSchema} or `z.unknown()`. */
   readonly inputSchema?: ZodType<TInputJson>;
-  executeOne(
-    args: Readonly<{
-      input: TInputJson;
-      item: Item;
-      itemIndex: number;
-      items: Items;
-      ctx: NodeExecutionContext<TConfig>;
-    }>,
-  ): Promise<TOutputJson> | TOutputJson;
+  execute(args: RunnableNodeExecuteArgs<TConfig, TInputJson>): Promise<unknown> | unknown;
 }
 
+/** @deprecated Use {@link RunnableNode} */
+export type ItemNode<
+  TConfig extends RunnableNodeConfig<any, any> = RunnableNodeConfig<any, any>,
+  TInputJson = unknown,
+  TOutputJson = unknown,
+> = RunnableNode<TConfig, TInputJson, TOutputJson>;
+
 export interface MultiInputNode<TConfig extends NodeConfigBase = NodeConfigBase> {
   kind: "node";
-  outputPorts: ReadonlyArray<OutputPortKey>;
+  /**
+   * Declared output ports (typically `["main"]`).
+   *
+   * Prefer describing ports for authoring/canvas via {@link NodeConfigBase.declaredOutputPorts}.
+   * Engine defaults to `["main"]` when omitted.
+   */
+  outputPorts?: ReadonlyArray<OutputPortKey>;
   executeMulti(inputsByPort: NodeInputsByPort, ctx: NodeExecutionContext<TConfig>): Promise<NodeOutputs>;
 }
 

package/src/contracts/workflowTypes.ts

@@ -17,6 +17,8 @@ export interface JsonObject {
 }
 export type JsonValue = JsonPrimitive | JsonObject | JsonArray;
 export type JsonArray = ReadonlyArray<JsonValue>;
+/** JSON value that is not a top-level array (nested arrays inside objects are allowed). */
+export type JsonNonArray = JsonPrimitive | JsonObject;
 
 export interface Edge {
   from: { nodeId: NodeId; output: OutputPortKey };
@@ -81,74 +83,45 @@ export interface NodeConfigBase {
    * main batches skip downstream execution and propagate the empty path.
    */
   readonly continueWhenEmptyOutput?: boolean;
+  /**
+   * Declared I/O port names for canvas authoring (unioned with ports inferred from edges).
+   * Use for dynamic routers (Switch) and future error ports.
+   */
+  readonly declaredOutputPorts?: ReadonlyArray<OutputPortKey>;
+  readonly declaredInputPorts?: ReadonlyArray<InputPortKey>;
   getCredentialRequirements?(): ReadonlyArray<CredentialRequirement>;
 }
 
 export declare const runnableNodeInputType: unique symbol;
 export declare const runnableNodeOutputType: unique symbol;
-/** Phantom: JSON shape on the wire from upstream before {@link RunnableNodeConfig.mapInput}. */
-export declare const runnableNodeWireType: unique symbol;
 export declare const triggerNodeOutputType: unique symbol;
 
-/**
- * Read-only execution slice passed to {@link RunnableNodeConfig.mapInput} (aligned with the engine’s
- * node execution context for `runId`, `data`, etc.). Use **`ctx.data`** to read **any completed** upstream
- * node’s outputs in this run (e.g. `ctx.data.getOutputItems(nodeIdA, "main")` while mapping at D), not only
- * the immediate predecessor’s {@link ItemInputMapperArgs.item}.
- */
-export interface ItemInputMapperContext {
-  readonly runId: RunId;
-  readonly workflowId: WorkflowId;
-  /** Node whose activation is being prepared (the consumer of `mapInput`). */
-  readonly nodeId: NodeId;
-  readonly activationId: NodeActivationId;
-  readonly parent?: ParentExecutionRef;
-  readonly data: RunDataSnapshot;
-}
+export type LineageCarryPolicy = "emitOnly" | "carryThrough";
 
 /**
- * Arguments for optional per-item input mapping applied by the engine before Zod validation.
+ * Runnable node: **`TInputJson`** is what **`inputSchema`** validates on **`item.json`** (the wire payload).
+ * **`TOutputJson`** is emitted `item.json` on outputs.
  */
-export interface ItemInputMapperArgs<TWireJson = unknown> {
-  readonly item: Item<TWireJson>;
-  readonly itemIndex: number;
-  readonly items: Items<TWireJson>;
-  readonly ctx: ItemInputMapperContext;
-}
-
-/**
- * Per-item mapper before Zod validation. Uses a **bivariant** method signature so concrete
- * `ItemInputMapper<SpecificWire, TIn>` remains assignable to `RunnableNodeConfig` fields typed as
- * `ItemInputMapper<unknown, unknown>` (same pattern as React-style callbacks).
- */
-export type ItemInputMapper<TWireJson = unknown, TInputJson = unknown> = {
-  bivarianceHack(args: ItemInputMapperArgs<TWireJson>): TInputJson | Promise<TInputJson>;
-}["bivarianceHack"];
-
-/**
- * Runnable node: **`TInputJson`** is the payload after `mapInput` (if any) + Zod validation — what {@link ItemNode}
- * `executeOne` receives. **`TOutputJson`** is emitted `item.json` on outputs. **`TWireJson`** is `item.json` from
- * upstream **before** `mapInput`; it defaults to **`TInputJson`** when there is no mapper or wire differs from execute input.
- */
-export interface RunnableNodeConfig<
-  TInputJson = unknown,
-  TOutputJson = unknown,
-  TWireJson = TInputJson,
-> extends NodeConfigBase {
+export interface RunnableNodeConfig<TInputJson = unknown, TOutputJson = unknown> extends NodeConfigBase {
   readonly kind: "node";
   readonly [runnableNodeInputType]?: TInputJson;
   readonly [runnableNodeOutputType]?: TOutputJson;
-  readonly [runnableNodeWireType]?: TWireJson;
   /**
-   * Optional Zod input contract for {@link ItemNode} when not set on the node class.
+   * Optional Zod input contract for {@link RunnableNode} when not set on the node class.
    * Resolution order: node instance `inputSchema`, then config `inputSchema`, then `z.unknown()`.
    */
   readonly inputSchema?: ZodType<TInputJson>;
   /**
-   * Optional per-item mapper: engine applies it before validating against the node’s `inputSchema`.
-   * When omitted, the engine validates `item.json` directly.
+   * Overrides default lineage propagation for `execute` outputs (binary/meta/paired).
+   * Routers with multiple {@link RunnableNode#outputPorts} default to **`carryThrough`**; others default to **`emitOnly`**.
+   */
+  readonly lineageCarry?: LineageCarryPolicy;
+  /**
+   * When an activation receives **zero** input items, the engine normally runs `execute` zero times.
+   * Set to **`runOnce`** to run `execute` once with an empty `items` batch (and a synthetic wire item for schema parsing).
+   * Used by batch-style callback nodes (built-in `Callback`) so `callback([], ctx)` still runs.
    */
-  readonly mapInput?: ItemInputMapper<TWireJson, TInputJson>;
+  readonly emptyBatchExecution?: "skip" | "runOnce";
 }
 
 export declare const triggerNodeSetupStateType: unique symbol;
@@ -162,14 +135,11 @@ export interface TriggerNodeConfig<
   readonly [triggerNodeSetupStateType]?: TSetupState;
 }
 
-export type RunnableNodeInputJson<TConfig extends RunnableNodeConfig<any, any, any>> =
-  TConfig extends RunnableNodeConfig<infer TInputJson, any, any> ? TInputJson : never;
-
-export type RunnableNodeWireJson<TConfig extends RunnableNodeConfig<any, any, any>> =
-  TConfig extends RunnableNodeConfig<any, any, infer TWireJson> ? TWireJson : never;
+export type RunnableNodeInputJson<TConfig extends RunnableNodeConfig<any, any>> =
+  TConfig extends RunnableNodeConfig<infer TInputJson, any> ? TInputJson : never;
 
-export type RunnableNodeOutputJson<TConfig extends RunnableNodeConfig<any, any, any>> =
-  TConfig extends RunnableNodeConfig<any, infer TOutputJson, any> ? TOutputJson : never;
+export type RunnableNodeOutputJson<TConfig extends RunnableNodeConfig<any, any>> =
+  TConfig extends RunnableNodeConfig<any, infer TOutputJson> ? TOutputJson : never;
 
 export type TriggerNodeOutputJson<TConfig extends TriggerNodeConfig<any, any>> =
   TConfig extends TriggerNodeConfig<infer TOutputJson, any> ? TOutputJson : never;

package/src/execution/FanInMergeByOriginMerger.ts

@@ -0,0 +1,67 @@
+import type { InputPortKey, Item, Items, NodeInputsByPort } from "../types";
+
+import { getOriginIndexFromItem } from "../contracts/itemMeta";
+
+/**
+ * Default fan-in: combine multi-port {@link NodeInputsByPort} into one {@link Items} batch for per-item nodes.
+ *
+ * This is used when a single-input per-item node has multiple inbound edges (for example, branch reconverge
+ * after an `If` / `Switch`). The default behavior is **append / union** (preserving item payloads) with a
+ * deterministic order:
+ *
+ * - When router origin metadata exists (`meta._cm.originIndex`), items are sorted by origin index so the
+ *   downstream batch preserves original ordering across branches.
+ * - Otherwise, items are appended by port-key order, preserving each port's local order.
+ */
+export class FanInMergeByOriginMerger {
+  merge(inputsByPort: NodeInputsByPort): Items {
+    const portKeys = Object.keys(inputsByPort).sort();
+    if (portKeys.length === 0) {
+      return [];
+    }
+    if (portKeys.length === 1) {
+      const only = portKeys[0]!;
+      return [...(inputsByPort[only] ?? [])];
+    }
+
+    type Entry = Readonly<{
+      portKey: InputPortKey;
+      portIndex: number;
+      item: Item;
+      originIndex: number | undefined;
+    }>;
+
+    const entries: Entry[] = [];
+    let anyOrigin = false;
+
+    for (let p = 0; p < portKeys.length; p++) {
+      const portKey = portKeys[p]!;
+      const items = inputsByPort[portKey] ?? [];
+      for (let i = 0; i < items.length; i++) {
+        const item = items[i] as Item;
+        const originIndex = getOriginIndexFromItem(item);
+        if (originIndex !== undefined) {
+          anyOrigin = true;
+        }
+        entries.push({ portKey, portIndex: i, item, originIndex });
+      }
+    }
+
+    if (!anyOrigin) {
+      return entries.map((e) => e.item);
+    }
+
+    const missingOriginRank = Number.MAX_SAFE_INTEGER;
+    return entries
+      .slice()
+      .sort((a, b) => {
+        const ao = a.originIndex ?? missingOriginRank;
+        const bo = b.originIndex ?? missingOriginRank;
+        if (ao !== bo) return ao - bo;
+        const pk = a.portKey.localeCompare(b.portKey);
+        if (pk !== 0) return pk;
+        return a.portIndex - b.portIndex;
+      })
+      .map((e) => e.item);
+  }
+}

package/src/execution/ItemValueResolver.ts

@@ -0,0 +1,27 @@
+import { resolveItemValuesForExecution } from "../contracts/itemValue";
+import type { Item, NodeExecutionContext, RunnableNodeConfig } from "../types";
+
+/**
+ * Resolves {@link import("../contracts/itemValue").ItemValue} leaves on runnable config before {@link RunnableNode.execute}.
+ */
+export class ItemValueResolver {
+  async resolveConfigForItem<TConfig extends RunnableNodeConfig<any, any>>(
+    ctx: NodeExecutionContext<TConfig>,
+    item: Item,
+    itemIndex: number,
+    items: ReadonlyArray<Item>,
+  ): Promise<NodeExecutionContext<TConfig>> {
+    if (!ctx) {
+      throw new Error("ItemValueResolver.resolveConfigForItem: ctx is required");
+    }
+    const resolvedConfig = await resolveItemValuesForExecution(ctx.config, ctx, item, itemIndex, items);
+    const merged = resolvedConfig !== undefined && resolvedConfig !== null ? resolvedConfig : ctx.config;
+    if (merged === undefined || merged === null) {
+      return ctx;
+    }
+    return {
+      ...ctx,
+      config: merged as TConfig,
+    };
+  }
+}

package/src/execution/NodeActivationRequestComposer.ts

@@ -6,6 +6,7 @@ import type {
   NodeActivationRequest,
   NodeExecutionContext,
   NodeId,
+  NodeInputsByPort,
   ParentExecutionRef,
   RunDataFactory,
   RunExecutionOptions,
@@ -34,6 +35,12 @@ export type SingleDefinitionActivationRequest = NodeActivationContextArgs & {
   input: Items;
 };
 
+export type MultiDefinitionActivationRequest = NodeActivationContextArgs & {
+  definition: NodeExecutionDefinition;
+  batchId: string;
+  inputsByPort: NodeInputsByPort;
+};
+
 export type PlannedNodeActivationRequest = NodeActivationContextArgs & {
   next: PlannedActivation;
   nodeDefinition: NodeExecutionDefinition;
@@ -75,6 +82,24 @@ export class NodeActivationRequestComposer {
     };
   }
 
+  createMultiFromDefinitionWithActivation(
+    args: MultiDefinitionActivationRequest & Readonly<{ activationId: NodeActivationId }>,
+  ): Extract<NodeActivationRequest, { kind: "multi" }> {
+    const ctx = this.createNodeExecutionContext(args, args.definition, args.activationId);
+    return {
+      kind: "multi",
+      runId: args.runId,
+      activationId: args.activationId,
+      workflowId: args.workflowId,
+      nodeId: args.definition.id,
+      parent: args.parent,
+      executionOptions: args.executionOptions,
+      batchId: args.batchId,
+      inputsByPort: args.inputsByPort,
+      ctx,
+    };
+  }
+
   createFromPlannedActivation(args: PlannedNodeActivationRequest): NodeActivationRequest {
     const activationId = this.activationIdFactory.makeActivationId();
     const ctx = this.createNodeExecutionContext(args, args.nodeDefinition, activationId);

package/src/execution/NodeActivationRequestInputPreparer.ts

@@ -2,40 +2,62 @@ import { z, ZodError } from "zod";
 
 import type { Item, NodeActivationRequest, RunnableNodeConfig, WorkflowNodeInstanceFactory } from "../types";
 
+import { FanInMergeByOriginMerger } from "./FanInMergeByOriginMerger";
 import { NodeInputContractError } from "./NodeInputContractError";
 
 /**
- * Maps and validates per-item inputs for {@link ItemNode} before enqueue persistence.
+ * Validates per-item inputs for {@link RunnableNode} before enqueue persistence (Zod on `item.json`).
+ * Does not rewrite `item.json` (wire stays as emitted upstream; engine passes parsed input via `execute` args).
+ * Converts multi-input activations into a single-input batch when the node is per-item only (engine fan-in).
  */
 export class NodeActivationRequestInputPreparer {
+  private readonly fanInMerger = new FanInMergeByOriginMerger();
+
   constructor(private readonly workflowNodeInstanceFactory: WorkflowNodeInstanceFactory) {}
 
   async prepare(request: NodeActivationRequest): Promise<NodeActivationRequest> {
-    if (request.kind !== "single") {
+    if (request.kind === "multi") {
+      return await this.prepareMulti(request);
+    }
+    return await this.prepareSingle(request);
+  }
+
+  private async prepareMulti(
+    request: Extract<NodeActivationRequest, { kind: "multi" }>,
+  ): Promise<NodeActivationRequest> {
+    const nodeInstance: unknown = this.workflowNodeInstanceFactory.createByType(request.ctx.config.type);
+    if (
+      !this.hasRunnableExecute(nodeInstance) ||
+      this.hasExecuteMulti(nodeInstance) ||
+      this.isTriggerNode(nodeInstance)
+    ) {
       return request;
     }
+    const merged = this.fanInMerger.merge(request.inputsByPort);
+    const single: Extract<NodeActivationRequest, { kind: "single" }> = {
+      ...request,
+      kind: "single",
+      input: merged,
+    };
+    return await this.prepareSingle(single);
+  }
+
+  private async prepareSingle(
+    request: Extract<NodeActivationRequest, { kind: "single" }>,
+  ): Promise<NodeActivationRequest> {
     const nodeInstance: unknown = this.workflowNodeInstanceFactory.createByType(request.ctx.config.type);
-    if (!this.hasExecuteOne(nodeInstance)) {
+    if (!this.hasRunnableExecute(nodeInstance) || this.isTriggerNode(nodeInstance)) {
       return request;
     }
     const inputSchema = this.resolveInputSchema(nodeInstance, request.ctx.config as RunnableNodeConfig);
-    const config = request.ctx.config as RunnableNodeConfig;
-    const mappedItems: Item[] = [];
-    for (let i = 0; i < request.input.length; i++) {
-      const item = request.input[i] as Item;
+    const inputBatch = request.input ?? [];
+    for (let i = 0; i < inputBatch.length; i++) {
+      const item = inputBatch[i] as Item;
       try {
-        const mappedRaw = config.mapInput
-          ? await Promise.resolve(
-              config.mapInput({
-                item,
-                itemIndex: i,
-                items: request.input,
-                ctx: request.ctx,
-              }),
-            )
-          : item.json;
-        const parsed = inputSchema.parse(mappedRaw);
-        mappedItems.push({ ...item, json: parsed });
+        if (Array.isArray(item.json)) {
+          throw new Error("Item JSON must not be a top-level array");
+        }
+        inputSchema.parse(item.json);
       } catch (cause) {
         const message = this.formatContractFailure(cause);
         throw new NodeInputContractError(
@@ -46,20 +68,30 @@ export class NodeActivationRequestInputPreparer {
         );
       }
     }
-    return {
-      ...request,
-      input: mappedItems,
-    };
+    return request.input === undefined ? { ...request, input: inputBatch } : request;
   }
 
-  private hasExecuteOne(nodeInstance: unknown): boolean {
+  private isTriggerNode(nodeInstance: unknown): boolean {
     return (
       typeof nodeInstance === "object" &&
       nodeInstance !== null &&
-      typeof (nodeInstance as { executeOne?: unknown }).executeOne === "function"
+      (nodeInstance as { kind?: string }).kind === "trigger"
     );
   }
 
+  private hasRunnableExecute(nodeInstance: unknown): boolean {
+    return (
+      typeof nodeInstance === "object" &&
+      nodeInstance !== null &&
+      (nodeInstance as { kind?: string }).kind === "node" &&
+      typeof (nodeInstance as { execute?: unknown }).execute === "function"
+    );
+  }
+
+  private hasExecuteMulti(nodeInstance: unknown): boolean {
+    return typeof (nodeInstance as { executeMulti?: unknown }).executeMulti === "function";
+  }
+
   private resolveInputSchema(
     nodeInstance: unknown,
     config: RunnableNodeConfig,