@codemation/core 0.3.0 → 0.4.0

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,

package/src/execution/NodeExecutor.ts

@@ -1,80 +1,249 @@
+import { z } from "zod";
+import { isPortsEmission, isUnbrandedPortsEmissionShape } from "../contracts/emitPorts";
+
 import type {
   Item,
+  LineageCarryPolicy,
   MultiInputNode,
-  Node,
   NodeActivationRequest,
+  NodeConfigBase,
+  NodeExecutionContext,
   NodeOutputs,
+  RunnableNode,
+  RunnableNodeConfig,
+  RunnableNodeExecuteArgs,
+  TriggerNode,
   WorkflowNodeInstanceFactory,
 } from "../types";
 
+import { FanInMergeByOriginMerger } from "./FanInMergeByOriginMerger";
+import { ItemValueResolver } from "./ItemValueResolver";
 import { InProcessRetryRunner } from "./InProcessRetryRunner";
+import { NodeOutputNormalizer } from "./NodeOutputNormalizer";
 
 export class NodeExecutor {
+  private readonly fanInMerger = new FanInMergeByOriginMerger();
+  private readonly outputNormalizer = new NodeOutputNormalizer();
+  private readonly itemValueResolver: ItemValueResolver;
+
   constructor(
     private readonly nodeInstanceFactory: WorkflowNodeInstanceFactory,
     private readonly retryRunner: InProcessRetryRunner,
-  ) {}
+    itemValueResolver?: ItemValueResolver,
+  ) {
+    this.itemValueResolver = itemValueResolver ?? new ItemValueResolver();
+  }
 
   async execute(request: NodeActivationRequest): Promise<NodeOutputs> {
     const policy = request.ctx.config.retryPolicy;
     return await this.retryRunner.run(policy, async () => {
       const nodeInstance = this.nodeInstanceFactory.createByType(request.ctx.config.type);
       if (request.kind === "multi") {
-        return await this.executeMultiInputNode(request, nodeInstance);
+        return await this.executeMultiInputActivation(request, nodeInstance);
       }
       return await this.executeSingleInputNode(request, nodeInstance);
     });
   }
 
-  private async executeMultiInputNode(
+  private async executeMultiInputActivation(
     request: Extract<NodeActivationRequest, { kind: "multi" }>,
     node: unknown,
   ): Promise<NodeOutputs> {
     const multiInputNode = node as MultiInputNode;
-    if (typeof (multiInputNode as { executeMulti?: unknown }).executeMulti !== "function") {
-      throw new Error(`Node ${request.nodeId} does not support executeMulti but received multi-input activation`);
+    if (typeof (multiInputNode as { executeMulti?: unknown }).executeMulti === "function") {
+      const raw = await multiInputNode.executeMulti(request.inputsByPort, request.ctx as never);
+      this.assertNoPortEnvelopeBypass(request.nodeId, raw, "executeMulti()");
+      return raw;
     }
-    return await multiInputNode.executeMulti(request.inputsByPort, request.ctx as any);
+    if (this.isRunnableNode(node)) {
+      const merged = this.fanInMerger.merge(request.inputsByPort);
+      const single: Extract<NodeActivationRequest, { kind: "single" }> = {
+        ...request,
+        kind: "single",
+        input: merged,
+      };
+      return await this.executeRunnableActivation(single, node);
+    }
+    throw new Error(
+      `Node ${request.nodeId} does not support executeMulti or RunnableNode.execute but received multi-input activation`,
+    );
   }
 
   private async executeSingleInputNode(
     request: Extract<NodeActivationRequest, { kind: "single" }>,
     node: unknown,
   ): Promise<NodeOutputs> {
-    if (this.hasExecuteOne(node)) {
-      return await this.executeItemNode(request, node);
+    if (this.isTriggerNode(node)) {
+      const raw = await (node as TriggerNode).execute(request.input, request.ctx as never);
+      this.assertNoPortEnvelopeBypass(request.nodeId, raw, "trigger execute()");
+      return raw;
     }
-    const singleInputNode = node as Node;
-    if (typeof (singleInputNode as { execute?: unknown }).execute !== "function") {
-      throw new Error(`Node ${request.nodeId} does not support execute but received single-input activation`);
+    if (this.isRunnableNode(node)) {
+      return await this.executeRunnableActivation(request, node);
     }
-    return await singleInputNode.execute(request.input, request.ctx as any);
+    if (this.hasExecuteMulti(node)) {
+      return await this.executeMultiInputActivation(this.asMultiFromSingleActivation(request), node);
+    }
+    throw new Error(`Node ${request.nodeId} does not support trigger or RunnableNode execution`);
+  }
+
+  private isTriggerNode(node: unknown): node is TriggerNode {
+    return typeof node === "object" && node !== null && (node as { kind?: string }).kind === "trigger";
   }
 
-  private hasExecuteOne(node: unknown): node is { executeOne: (args: unknown) => unknown | Promise<unknown> } {
+  private isRunnableNode(node: unknown): node is RunnableNode {
     return (
-      typeof node === "object" && node !== null && typeof (node as { executeOne?: unknown }).executeOne === "function"
+      typeof node === "object" &&
+      node !== null &&
+      (node as { kind?: string }).kind === "node" &&
+      typeof (node as { execute?: unknown }).execute === "function"
     );
   }
 
-  private async executeItemNode(
+  private hasExecuteMulti(node: unknown): boolean {
+    return typeof (node as { executeMulti?: unknown })?.executeMulti === "function";
+  }
+
+  private asMultiFromSingleActivation(
     request: Extract<NodeActivationRequest, { kind: "single" }>,
-    node: { executeOne: (args: unknown) => unknown | Promise<unknown> },
+  ): Extract<NodeActivationRequest, { kind: "multi" }> {
+    return {
+      kind: "multi",
+      runId: request.runId,
+      activationId: request.activationId,
+      workflowId: request.workflowId,
+      nodeId: request.nodeId,
+      parent: request.parent,
+      executionOptions: request.executionOptions,
+      batchId: request.batchId,
+      ctx: request.ctx,
+      inputsByPort: { in: request.input ?? [] },
+    };
+  }
+
+  private async executeRunnableActivation(
+    request: Extract<NodeActivationRequest, { kind: "single" }>,
+    node: RunnableNode,
   ): Promise<NodeOutputs> {
-    const out: Item[] = [];
-    for (let i = 0; i < request.input.length; i++) {
-      const item = request.input[i] as Item;
-      const outputJson = await Promise.resolve(
-        node.executeOne({
-          input: item.json,
-          item,
-          itemIndex: i,
-          items: request.input,
-          ctx: request.ctx,
-        }),
+    const runnableConfig = request.ctx.config as RunnableNodeConfig;
+    const carry = this.resolveLineageCarry(node, runnableConfig);
+    const inputSchema = this.resolveInputSchema(node, runnableConfig);
+    const inputBatch = request.input ?? [];
+    if (inputBatch.length === 0 && runnableConfig.emptyBatchExecution === "runOnce") {
+      const syntheticItem: Item = { json: {} };
+      const parsed = inputSchema.parse(syntheticItem.json);
+      const runnableCtx = request.ctx as NodeExecutionContext<RunnableNodeConfig>;
+      const resolvedCtx = await this.itemValueResolver.resolveConfigForItem(runnableCtx, syntheticItem, 0, inputBatch);
+      const ctx = this.pickExecutionContext(runnableCtx, resolvedCtx);
+      const args: RunnableNodeExecuteArgs = {
+        input: parsed,
+        item: syntheticItem,
+        itemIndex: 0,
+        items: inputBatch,
+        ctx,
+      };
+      const raw = await Promise.resolve(node.execute(args));
+      return this.outputNormalizer.normalizeExecuteResult({
+        baseItem: syntheticItem,
+        raw,
+        carry,
+      }) as NodeOutputs;
+    }
+    const byPort: Partial<Record<string, Item[]>> = {};
+    for (let i = 0; i < inputBatch.length; i++) {
+      const item = inputBatch[i] as Item;
+      this.assertItemJsonNotTopLevelArray(request.nodeId, item);
+      const parsed = inputSchema.parse(item.json);
+      const runnableCtx = request.ctx as NodeExecutionContext<RunnableNodeConfig>;
+      const resolvedCtx = await this.itemValueResolver.resolveConfigForItem(runnableCtx, item, i, inputBatch);
+      const ctx = this.pickExecutionContext(runnableCtx, resolvedCtx);
+      const args: RunnableNodeExecuteArgs = {
+        input: parsed,
+        item,
+        itemIndex: i,
+        items: inputBatch,
+        ctx,
+      };
+      const raw = await Promise.resolve(node.execute(args));
+      const normalized = this.outputNormalizer.normalizeExecuteResult({
+        baseItem: item,
+        raw,
+        carry,
+      });
+      for (const [port, batch] of Object.entries(normalized)) {
+        if (!batch || batch.length === 0) {
+          continue;
+        }
+        const list = byPort[port] ?? [];
+        list.push(...batch);
+        byPort[port] = list;
+      }
+    }
+    return byPort as NodeOutputs;
+  }
+
+  /** Use resolver ctx only when {@link NodeExecutionContext.config} is non-nullish. */
+  private pickExecutionContext<TConfig extends RunnableNodeConfig<any, any>>(
+    runnableCtx: NodeExecutionContext<TConfig>,
+    resolvedCtx: NodeExecutionContext<TConfig> | null | undefined,
+  ): NodeExecutionContext<TConfig> {
+    if (resolvedCtx != null && resolvedCtx.config != null) {
+      return resolvedCtx;
+    }
+    return runnableCtx;
+  }
+
+  private resolveInputSchema(
+    nodeInstance: RunnableNode,
+    config: RunnableNodeConfig,
+  ): {
+    parse: (data: unknown) => unknown;
+  } {
+    const fromInstance = nodeInstance.inputSchema;
+    if (fromInstance && typeof fromInstance.parse === "function") {
+      return fromInstance as { parse: (data: unknown) => unknown };
+    }
+    const fromConfig = config.inputSchema;
+    if (fromConfig && typeof fromConfig.parse === "function") {
+      return fromConfig as { parse: (data: unknown) => unknown };
+    }
+    return z.unknown();
+  }
+
+  private assertItemJsonNotTopLevelArray(nodeId: string, item: Item): void {
+    if (Array.isArray(item.json)) {
+      throw new Error(`Node ${nodeId}: item.json must not be a top-level JSON array`);
+    }
+  }
+
+  private assertNoPortEnvelopeBypass(nodeId: string, value: unknown, methodName: string): void {
+    if (isPortsEmission(value)) {
+      throw new Error(`Node ${nodeId}: ${methodName} must return NodeOutputs, not emitPorts(...).`);
+    }
+    if (isUnbrandedPortsEmissionShape(value)) {
+      throw new Error(
+        `Node ${nodeId}: ${methodName} returned an unbranded \`{ ports: ... }\` object. Return NodeOutputs instead.`,
       );
-      out.push({ ...item, json: outputJson });
     }
-    return { main: out };
+  }
+
+  private resolveLineageCarry(node: unknown, config: RunnableNodeConfig): LineageCarryPolicy {
+    if (config.lineageCarry) {
+      return config.lineageCarry;
+    }
+
+    const base = config as NodeConfigBase;
+    const declared = base.declaredOutputPorts;
+    const ports =
+      declared && declared.length > 0
+        ? [...new Set([...(declared as readonly string[]), ...(base.nodeErrorHandler ? ["error"] : [])])]
+        : base.nodeErrorHandler
+          ? (["main", "error"] as const)
+          : (["main"] as const);
+
+    if (ports.length > 1) {
+      return "carryThrough";
+    }
+    return "emitOnly";
   }
 }