@codemation/core 0.2.1 → 0.3.0

package/src/authoring/defineNode.types.ts

@@ -4,10 +4,11 @@ import type {
   CredentialRequirement,
   CredentialTypeId,
 } from "../contracts/credentialTypes";
-import type { Node, NodeExecutionContext } from "../contracts/runtimeTypes";
-import type { Items, NodeOutputs, RunnableNodeConfig } from "../contracts/workflowTypes";
+import type { ItemNode, Node, NodeExecutionContext } from "../contracts/runtimeTypes";
+import type { Item, ItemInputMapper, Items, NodeOutputs, RunnableNodeConfig } from "../contracts/workflowTypes";
 import type { TypeToken } from "../di";
 import { node as persistedNode } from "../runtime-types/runtimeTypeDecorators.types";
+import type { ZodType } from "zod";
 import { z } from "zod";
 import { DefinedNodeRegistry } from "./DefinedNodeRegistry";
 
@@ -54,27 +55,46 @@ export interface DefinedNodeRunContext<
   readonly execution: NodeExecutionContext<RunnableNodeConfig<TConfig, unknown>>;
 }
 
+/**
+ * Arguments for {@link defineNode} `executeOne` (engine `ctx` matches {@link ItemNode.executeOne};
+ * the second callback parameter adds {@link DefinedNodeRunContext} for credential accessors).
+ */
+export type DefineNodeExecuteOneArgs<TConfig extends CredentialJsonRecord, TInputJson, TWireJson> = Readonly<{
+  input: TInputJson;
+  item: Item;
+  itemIndex: number;
+  items: Items;
+  ctx: NodeExecutionContext<RunnableNodeConfig<TInputJson, unknown, TWireJson> & Readonly<{ config: TConfig }>>;
+}>;
+
 export interface DefinedNode<
   TKey extends string,
   TConfig extends CredentialJsonRecord,
   TInputJson,
   TOutputJson,
   _TBindings extends DefinedNodeCredentialBindings | undefined = undefined,
+  TWireJson = TInputJson,
 > {
   readonly kind: "defined-node";
   readonly key: TKey;
   readonly title: string;
   readonly description?: string;
-  create(config: TConfig, name?: string, id?: string): RunnableNodeConfig<TInputJson, TOutputJson>;
+  create(config: TConfig, name?: string, id?: string): RunnableNodeConfig<TInputJson, TOutputJson, TWireJson>;
   register(context: { registerNode<TValue>(token: TypeToken<TValue>, implementation?: TypeToken<TValue>): void }): void;
 }
 
+/**
+ * Plugin / DSL-friendly node: **one item in, one item out** per engine activation step.
+ * The engine applies {@link RunnableNodeConfig.mapInput} (if any) + {@link RunnableNodeConfig.inputSchema}
+ * before `executeOne`. Use {@link defineBatchNode} for legacy batch `run(items, …)` semantics.
+ */
 export interface DefineNodeOptions<
   TKey extends string,
   TConfig extends CredentialJsonRecord,
   TInputJson,
   TOutputJson,
   TBindings extends DefinedNodeCredentialBindings | undefined = undefined,
+  TWireJson = TInputJson,
 > {
   readonly key: TKey;
   readonly title: string;
@@ -84,6 +104,38 @@ export interface DefineNodeOptions<
    * The Next host resolves Lucide (`lucide:…`), built-in SVGs (`builtin:…`), Simple Icons (`si:…`), and image URLs (`https:`, `data:`, `/…`).
    */
   readonly icon?: string;
+  /** Default values / form hints for **static** node configuration (credentials, retry, IDs), not per-item payload. */
+  readonly input?: Readonly<Record<keyof TConfig & string, unknown>>;
+  readonly configSchema?: z.ZodType<TConfig>;
+  readonly credentials?: TBindings;
+  /**
+   * Validates **`input`** after optional {@link mapInput} (engine also accepts `inputSchema` on the node class).
+   */
+  readonly inputSchema?: ZodType<TInputJson>;
+  /**
+   * Maps wire JSON (`item.json` from upstream) to execute input before validation.
+   */
+  readonly mapInput?: ItemInputMapper<TWireJson, TInputJson>;
+  executeOne(
+    args: DefineNodeExecuteOneArgs<TConfig, TInputJson, TWireJson>,
+    context: DefinedNodeRunContext<TConfig, TBindings>,
+  ): MaybePromise<TOutputJson>;
+}
+
+/**
+ * Batch-oriented defined node (legacy): receives all items at once via `run`.
+ */
+export interface DefineBatchNodeOptions<
+  TKey extends string,
+  TConfig extends CredentialJsonRecord,
+  TInputJson,
+  TOutputJson,
+  TBindings extends DefinedNodeCredentialBindings | undefined = undefined,
+> {
+  readonly key: TKey;
+  readonly title: string;
+  readonly description?: string;
+  readonly icon?: string;
   readonly input?: Readonly<Record<keyof TConfig & string, unknown>>;
   readonly configSchema?: z.ZodType<TConfig>;
   readonly credentials?: TBindings;
@@ -145,7 +197,7 @@ const definedNodeCredentialRequirementFactory = {
 const definedNodeCredentialAccessorFactory = {
   create<TBindings extends DefinedNodeCredentialBindings | undefined>(
     bindings: TBindings,
-    ctx: NodeExecutionContext<RunnableNodeConfig<any, any>>,
+    ctx: NodeExecutionContext<RunnableNodeConfig<any, any, any>>,
   ): DefinedNodeCredentialAccessors<TBindings> {
     if (!bindings) {
       return {} as DefinedNodeCredentialAccessors<TBindings>;
@@ -161,11 +213,100 @@ export function defineNode<
   TInputJson,
   TOutputJson,
   TBindings extends DefinedNodeCredentialBindings | undefined = undefined,
+  TWireJson = TInputJson,
+>(
+  options: DefineNodeOptions<TKey, TConfig, TInputJson, TOutputJson, TBindings, TWireJson>,
+): DefinedNode<TKey, TConfig, TInputJson, TOutputJson, TBindings, TWireJson> {
+  const credentialRequirements = definedNodeCredentialRequirementFactory.create(options.credentials);
+  type DefinedRunnableNodeConfigShape = RunnableNodeConfig<TInputJson, TOutputJson, TWireJson> &
+    Readonly<{ config: TConfig }>;
+
+  const DefinedNodeRuntime = class implements ItemNode<DefinedRunnableNodeConfigShape, TInputJson, TOutputJson> {
+    readonly kind = "node" as const;
+    readonly outputPorts = ["main"] as const;
+    readonly inputSchema = options.inputSchema;
+
+    async executeOne(
+      args: Readonly<{
+        input: TInputJson;
+        item: Item;
+        itemIndex: number;
+        items: Items;
+        ctx: NodeExecutionContext<DefinedRunnableNodeConfigShape>;
+      }>,
+    ): Promise<TOutputJson> {
+      const ctx = args.ctx;
+      const context: DefinedNodeRunContext<TConfig, TBindings> = {
+        config: ctx.config.config,
+        credentials: definedNodeCredentialAccessorFactory.create(
+          options.credentials,
+          ctx,
+        ) as DefinedNodeCredentialAccessors<TBindings>,
+        execution: ctx as unknown as NodeExecutionContext<RunnableNodeConfig<TConfig, unknown>>,
+      };
+      const payload: DefineNodeExecuteOneArgs<TConfig, TInputJson, TWireJson> = {
+        input: args.input,
+        item: args.item,
+        itemIndex: args.itemIndex,
+        items: args.items,
+        ctx,
+      };
+      return await options.executeOne(payload, context);
+    }
+  };
+
+  persistedNode({ name: options.key })(DefinedNodeRuntime);
+
+  const DefinedRunnableNodeConfig = class implements RunnableNodeConfig<TInputJson, TOutputJson, TWireJson> {
+    readonly kind = "node" as const;
+    readonly type: TypeToken<unknown> = DefinedNodeRuntime;
+    readonly icon = options.icon;
+    readonly inputSchema = options.inputSchema;
+    readonly mapInput = options.mapInput;
+
+    constructor(
+      public readonly name: string,
+      public readonly config: TConfig,
+      public readonly id?: string,
+    ) {}
+
+    getCredentialRequirements(): ReadonlyArray<CredentialRequirement> {
+      return credentialRequirements;
+    }
+  };
+
+  const definition: DefinedNode<TKey, TConfig, TInputJson, TOutputJson, TBindings, TWireJson> = {
+    kind: "defined-node",
+    key: options.key,
+    title: options.title,
+    description: options.description,
+    create(config, name = options.title, id) {
+      return new DefinedRunnableNodeConfig(name, config, id);
+    },
+    register(context) {
+      context.registerNode(DefinedNodeRuntime);
+    },
+  };
+
+  DefinedNodeRegistry.register(
+    definition as DefinedNode<string, Record<string, unknown>, unknown, unknown, undefined, unknown>,
+  );
+
+  return definition;
+}
+
+export function defineBatchNode<
+  TKey extends string,
+  TConfig extends CredentialJsonRecord,
+  TInputJson,
+  TOutputJson,
+  TBindings extends DefinedNodeCredentialBindings | undefined = undefined,
 >(
-  options: DefineNodeOptions<TKey, TConfig, TInputJson, TOutputJson, TBindings>,
-): DefinedNode<TKey, TConfig, TInputJson, TOutputJson, TBindings> {
+  options: DefineBatchNodeOptions<TKey, TConfig, TInputJson, TOutputJson, TBindings>,
+): DefinedNode<TKey, TConfig, TInputJson, TOutputJson, TBindings, TInputJson> {
   const credentialRequirements = definedNodeCredentialRequirementFactory.create(options.credentials);
-  type DefinedRunnableNodeConfigShape = RunnableNodeConfig<TInputJson, TOutputJson> & Readonly<{ config: TConfig }>;
+  type DefinedRunnableNodeConfigShape = RunnableNodeConfig<TInputJson, TOutputJson, TInputJson> &
+    Readonly<{ config: TConfig }>;
 
   const DefinedNodeRuntime = class implements Node<DefinedRunnableNodeConfigShape> {
     readonly kind = "node" as const;
@@ -198,7 +339,7 @@ export function defineNode<
 
   persistedNode({ name: options.key })(DefinedNodeRuntime);
 
-  const DefinedRunnableNodeConfig = class implements RunnableNodeConfig<TInputJson, TOutputJson> {
+  const DefinedRunnableNodeConfig = class implements RunnableNodeConfig<TInputJson, TOutputJson, TInputJson> {
     readonly kind = "node" as const;
     readonly type: TypeToken<unknown> = DefinedNodeRuntime;
     readonly icon = options.icon;
@@ -214,7 +355,7 @@ export function defineNode<
     }
   };
 
-  const definition: DefinedNode<TKey, TConfig, TInputJson, TOutputJson, TBindings> = {
+  const definition: DefinedNode<TKey, TConfig, TInputJson, TOutputJson, TBindings, TInputJson> = {
     kind: "defined-node",
     key: options.key,
     title: options.title,
@@ -227,7 +368,9 @@ export function defineNode<
     },
   };
 
-  DefinedNodeRegistry.register(definition as DefinedNode<string, Record<string, unknown>, unknown, unknown>);
+  DefinedNodeRegistry.register(
+    definition as DefinedNode<string, Record<string, unknown>, unknown, unknown, undefined, unknown>,
+  );
 
   return definition;
 }

package/src/authoring/index.ts

@@ -5,8 +5,10 @@ export type {
   DefinedNodeCredentialBinding,
   DefinedNodeCredentialBindings,
   DefinedNodeRunContext,
+  DefineBatchNodeOptions,
+  DefineNodeExecuteOneArgs,
   DefineNodeOptions,
 } from "./defineNode.types";
-export { defineNode } from "./defineNode.types";
+export { defineBatchNode, defineNode } from "./defineNode.types";
 export type { DefineCredentialOptions } from "./defineCredential.types";
 export { defineCredential } from "./defineCredential.types";

package/src/contracts/runtimeTypes.ts

@@ -13,6 +13,8 @@ import type {
 } from "./runTypes";
 import type { WorkflowActivationPolicy } from "./workflowActivationPolicy";
 import type { TriggerInstanceId, WebhookTriggerMatcher } from "./webhookTypes";
+import type { ZodType } from "zod";
+
 import type {
   ActivationIdFactory,
   BinaryAttachment,
@@ -225,6 +227,30 @@ export interface Node<TConfig extends NodeConfigBase = NodeConfigBase> {
   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`.
+ */
+export interface ItemNode<
+  TConfig extends NodeConfigBase = NodeConfigBase,
+  TInputJson = unknown,
+  TOutputJson = unknown,
+> {
+  readonly kind: "node";
+  readonly outputPorts: readonly ["main"];
+  /** 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;
+}
+
 export interface MultiInputNode<TConfig extends NodeConfigBase = NodeConfigBase> {
   kind: "node";
   outputPorts: ReadonlyArray<OutputPortKey>;

package/src/contracts/workflowTypes.ts

@@ -1,3 +1,5 @@
+import type { ZodType } from "zod";
+
 import type { TypeToken } from "../di";
 import type { CredentialRequirement } from "./credentialTypes";
 import type { RetryPolicySpec } from "./retryPolicySpec.types";
@@ -84,12 +86,69 @@ export interface NodeConfigBase {
 
 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;
 
-export interface RunnableNodeConfig<TInputJson = unknown, TOutputJson = unknown> extends NodeConfigBase {
+/**
+ * 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;
+}
+
+/**
+ * Arguments for optional per-item input mapping applied by the engine before Zod validation.
+ */
+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 {
   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.
+   * 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.
+   */
+  readonly mapInput?: ItemInputMapper<TWireJson, TInputJson>;
 }
 
 export declare const triggerNodeSetupStateType: unique symbol;
@@ -103,11 +162,14 @@ export interface TriggerNodeConfig<
   readonly [triggerNodeSetupStateType]?: TSetupState;
 }
 
-export type RunnableNodeInputJson<TConfig extends RunnableNodeConfig<any, any>> =
-  TConfig extends RunnableNodeConfig<infer TInputJson, any> ? TInputJson : never;
+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 RunnableNodeOutputJson<TConfig extends RunnableNodeConfig<any, any>> =
-  TConfig extends RunnableNodeConfig<any, infer TOutputJson> ? TOutputJson : never;
+export type RunnableNodeOutputJson<TConfig extends RunnableNodeConfig<any, any, any>> =
+  TConfig extends RunnableNodeConfig<any, infer TOutputJson, any> ? TOutputJson : never;
 
 export type TriggerNodeOutputJson<TConfig extends TriggerNodeConfig<any, any>> =
   TConfig extends TriggerNodeConfig<infer TOutputJson, any> ? TOutputJson : never;

package/src/execution/ActivationEnqueueService.ts

@@ -21,6 +21,7 @@ import type {
 import { RunQueuePlanner } from "../planning/RunQueuePlanner";
 
 import { NodeEventPublisher } from "../events/NodeEventPublisher";
+import type { NodeActivationRequestInputPreparer } from "./NodeActivationRequestInputPreparer";
 import { NodeExecutionSnapshotFactory } from "./NodeExecutionSnapshotFactory";
 import { NodeInputsByPortFactory } from "./NodeInputsByPortFactory";
 
@@ -51,6 +52,7 @@ export class ActivationEnqueueService {
     private readonly activationScheduler: ActivationSchedulerPort,
     private readonly workflowExecutionRepository: WorkflowExecutionRepository,
     private readonly nodeEventPublisher: NodeEventPublisher,
+    private readonly nodeActivationRequestInputPreparer: NodeActivationRequestInputPreparer,
   ) {}
 
   async enqueueActivation(args: ActivationEnqueueRequest): Promise<RunResult> {
@@ -62,12 +64,13 @@ export class ActivationEnqueueService {
   async enqueueActivationWithSnapshot(
     args: ActivationEnqueueRequest,
   ): Promise<{ result: RunResult; queuedSnapshot: NodeExecutionSnapshot }> {
-    const preparedDispatch = await this.activationScheduler.prepareDispatch(args.request);
-    const inputsByPort = NodeInputsByPortFactory.fromRequest(args.request);
+    const preparedRequest = await this.nodeActivationRequestInputPreparer.prepare(args.request);
+    const preparedDispatch = await this.activationScheduler.prepareDispatch(preparedRequest);
+    const inputsByPort = NodeInputsByPortFactory.fromRequest(preparedRequest);
     const itemsIn =
-      args.request.kind === "multi"
-        ? args.planner.sumItemsByPort(args.request.inputsByPort)
-        : args.request.input.length;
+      preparedRequest.kind === "multi"
+        ? args.planner.sumItemsByPort(preparedRequest.inputsByPort)
+        : preparedRequest.input.length;
     const enqueuedAt = new Date().toISOString();
     const pending: PendingNodeExecution = {
       runId: args.runId,

package/src/execution/NodeActivationRequestInputPreparer.ts

@@ -0,0 +1,89 @@
+import { z, ZodError } from "zod";
+
+import type { Item, NodeActivationRequest, RunnableNodeConfig, WorkflowNodeInstanceFactory } from "../types";
+
+import { NodeInputContractError } from "./NodeInputContractError";
+
+/**
+ * Maps and validates per-item inputs for {@link ItemNode} before enqueue persistence.
+ */
+export class NodeActivationRequestInputPreparer {
+  constructor(private readonly workflowNodeInstanceFactory: WorkflowNodeInstanceFactory) {}
+
+  async prepare(request: NodeActivationRequest): Promise<NodeActivationRequest> {
+    if (request.kind !== "single") {
+      return request;
+    }
+    const nodeInstance: unknown = this.workflowNodeInstanceFactory.createByType(request.ctx.config.type);
+    if (!this.hasExecuteOne(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;
+      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 });
+      } catch (cause) {
+        const message = this.formatContractFailure(cause);
+        throw new NodeInputContractError(
+          `Node ${request.nodeId} activation ${request.activationId}: input contract failed: ${message}`,
+          request.nodeId,
+          request.activationId,
+          cause,
+        );
+      }
+    }
+    return {
+      ...request,
+      input: mappedItems,
+    };
+  }
+
+  private hasExecuteOne(nodeInstance: unknown): boolean {
+    return (
+      typeof nodeInstance === "object" &&
+      nodeInstance !== null &&
+      typeof (nodeInstance as { executeOne?: unknown }).executeOne === "function"
+    );
+  }
+
+  private resolveInputSchema(
+    nodeInstance: unknown,
+    config: RunnableNodeConfig,
+  ): {
+    parse: (data: unknown) => unknown;
+  } {
+    const fromInstance = (nodeInstance as { inputSchema?: unknown }).inputSchema;
+    if (fromInstance && typeof (fromInstance as { parse?: unknown }).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 formatContractFailure(cause: unknown): string {
+    if (cause instanceof ZodError) {
+      return cause.issues.map((i) => `${i.path.join(".") || "<root>"}: ${i.message}`).join("; ");
+    }
+    if (cause instanceof Error) {
+      return cause.message;
+    }
+    return String(cause);
+  }
+}

package/src/execution/NodeExecutor.ts

@@ -1,4 +1,11 @@
-import type { MultiInputNode, Node, NodeActivationRequest, NodeOutputs, WorkflowNodeInstanceFactory } from "../types";
+import type {
+  Item,
+  MultiInputNode,
+  Node,
+  NodeActivationRequest,
+  NodeOutputs,
+  WorkflowNodeInstanceFactory,
+} from "../types";
 
 import { InProcessRetryRunner } from "./InProcessRetryRunner";
 
@@ -34,10 +41,40 @@ export class NodeExecutor {
     request: Extract<NodeActivationRequest, { kind: "single" }>,
     node: unknown,
   ): Promise<NodeOutputs> {
+    if (this.hasExecuteOne(node)) {
+      return await this.executeItemNode(request, node);
+    }
     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`);
     }
     return await singleInputNode.execute(request.input, request.ctx as any);
   }
+
+  private hasExecuteOne(node: unknown): node is { executeOne: (args: unknown) => unknown | Promise<unknown> } {
+    return (
+      typeof node === "object" && node !== null && typeof (node as { executeOne?: unknown }).executeOne === "function"
+    );
+  }
+
+  private async executeItemNode(
+    request: Extract<NodeActivationRequest, { kind: "single" }>,
+    node: { executeOne: (args: unknown) => unknown | Promise<unknown> },
+  ): 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,
+        }),
+      );
+      out.push({ ...item, json: outputJson });
+    }
+    return { main: out };
+  }
 }

package/src/execution/NodeInputContractError.ts

@@ -0,0 +1,13 @@
+import type { NodeActivationId, NodeId } from "../types";
+
+export class NodeInputContractError extends Error {
+  constructor(
+    message: string,
+    public readonly nodeId: NodeId,
+    public readonly activationId: NodeActivationId,
+    public readonly cause?: unknown,
+  ) {
+    super(message);
+    this.name = "NodeInputContractError";
+  }
+}

package/src/execution/index.ts

@@ -1,4 +1,6 @@
 export { ActivationEnqueueService } from "./ActivationEnqueueService";
+export { NodeActivationRequestInputPreparer } from "./NodeActivationRequestInputPreparer";
+export { NodeInputContractError } from "./NodeInputContractError";
 export { CredentialResolverFactory } from "./CredentialResolverFactory";
 export { DefaultAsyncSleeper } from "./DefaultAsyncSleeper";
 export { DefaultExecutionContextFactory } from "./DefaultExecutionContextFactory";