@codemation/core 0.2.3 → 0.4.0

package/src/ai/AiHost.ts

@@ -1,6 +1,7 @@
 import type { TypeToken } from "../di";
 
 import type { CredentialRequirement } from "../contracts/credentialTypes";
+import type { ItemValue } from "../contracts/itemValue";
 
 import type {
   Item,
@@ -91,6 +92,7 @@ export type AgentMessageLine<TInputJson = unknown> = AgentMessageDto | AgentMess
  * Use the object form only when you need `buildMessages` to append messages after optional `prompt` lines.
  */
 export type AgentMessageConfig<TInputJson = unknown> =
+  | ItemValue<ReadonlyArray<AgentMessageLine<TInputJson>>, TInputJson>
   | ReadonlyArray<AgentMessageLine<TInputJson>>
   | {
       readonly prompt?: ReadonlyArray<AgentMessageLine<TInputJson>>;
@@ -150,7 +152,7 @@ export interface ChatModelFactory<TConfig extends ChatModelConfig = ChatModelCon
 }
 
 export type NodeBackedToolInputMapperArgs<
-  TNodeConfig extends RunnableNodeConfig<any, any, any>,
+  TNodeConfig extends RunnableNodeConfig<any, any>,
   TToolInput = unknown,
 > = Readonly<{
   input: TToolInput;
@@ -162,7 +164,7 @@ export type NodeBackedToolInputMapperArgs<
 }>;
 
 export type NodeBackedToolOutputMapperArgs<
-  TNodeConfig extends RunnableNodeConfig<any, any, any>,
+  TNodeConfig extends RunnableNodeConfig<any, any>,
   TToolInput = unknown,
 > = Readonly<{
   input: TToolInput;
@@ -174,18 +176,18 @@ export type NodeBackedToolOutputMapperArgs<
   outputs: NodeOutputs;
 }>;
 
-export type NodeBackedToolInputMapper<TNodeConfig extends RunnableNodeConfig<any, any, any>, TToolInput = unknown> = (
+export type NodeBackedToolInputMapper<TNodeConfig extends RunnableNodeConfig<any, any>, TToolInput = unknown> = (
   args: NodeBackedToolInputMapperArgs<TNodeConfig, TToolInput>,
 ) => Item<RunnableNodeInputJson<TNodeConfig>> | RunnableNodeInputJson<TNodeConfig>;
 
 export type NodeBackedToolOutputMapper<
-  TNodeConfig extends RunnableNodeConfig<any, any, any>,
+  TNodeConfig extends RunnableNodeConfig<any, any>,
   TToolInput = unknown,
   TToolOutput = unknown,
 > = (args: NodeBackedToolOutputMapperArgs<TNodeConfig, TToolInput>) => TToolOutput;
 
 export type NodeBackedToolConfigOptions<
-  TNodeConfig extends RunnableNodeConfig<any, any, any>,
+  TNodeConfig extends RunnableNodeConfig<any, any>,
   TInputSchema extends ZodSchemaAny,
   TOutputSchema extends ZodSchemaAny,
 > = Readonly<{
@@ -197,11 +199,10 @@ export type NodeBackedToolConfigOptions<
   mapOutput?: NodeBackedToolOutputMapper<TNodeConfig, ZodInput<TInputSchema>, ZodOutput<TOutputSchema>>;
 }>;
 
-export interface AgentNodeConfig<
-  TInputJson = unknown,
-  TOutputJson = unknown,
-  TWireJson = TInputJson,
-> extends RunnableNodeConfig<TInputJson, TOutputJson, TWireJson> {
+export interface AgentNodeConfig<TInputJson = unknown, TOutputJson = unknown> extends RunnableNodeConfig<
+  TInputJson,
+  TOutputJson
+> {
   readonly messages: AgentMessageConfig<TInputJson>;
   readonly chatModel: ChatModelConfig;
   readonly tools?: ReadonlyArray<ToolConfig>;

package/src/ai/NodeBackedToolConfig.ts

@@ -14,7 +14,7 @@ import type {
 } from "./AiHost";
 
 export class NodeBackedToolConfig<
-  TNodeConfig extends RunnableNodeConfig<any, any, any>,
+  TNodeConfig extends RunnableNodeConfig<any, any>,
   TInputSchema extends ZodSchemaAny,
   TOutputSchema extends ZodSchemaAny,
 > implements ToolConfig {

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 { RunnableNode, RunnableNodeExecuteArgs, NodeExecutionContext } from "../contracts/runtimeTypes";
+import type { Item, Items, 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,6 +55,18 @@ export interface DefinedNodeRunContext<
   readonly execution: NodeExecutionContext<RunnableNodeConfig<TConfig, unknown>>;
 }
 
+/**
+ * Arguments for {@link defineNode} `execute` (engine `ctx` matches {@link RunnableNode.execute};
+ * the second callback parameter adds {@link DefinedNodeRunContext} for credential accessors).
+ */
+export type DefineNodeExecuteArgs<TConfig extends CredentialJsonRecord, TInputJson> = Readonly<{
+  input: TInputJson;
+  item: Item;
+  itemIndex: number;
+  items: Items;
+  ctx: NodeExecutionContext<RunnableNodeConfig<TInputJson, unknown> & Readonly<{ config: TConfig }>>;
+}>;
+
 export interface DefinedNode<
   TKey extends string,
   TConfig extends CredentialJsonRecord,
@@ -69,6 +82,9 @@ export interface DefinedNode<
   register(context: { registerNode<TValue>(token: TypeToken<TValue>, implementation?: TypeToken<TValue>): void }): void;
 }
 
+/**
+ * Plugin / DSL-friendly node: per-item `execute` with optional {@link RunnableNodeConfig.inputSchema}.
+ */
 export interface DefineNodeOptions<
   TKey extends string,
   TConfig extends CredentialJsonRecord,
@@ -84,6 +100,34 @@ 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`** (engine also accepts `inputSchema` on the node class).
+   */
+  readonly inputSchema?: ZodType<TInputJson>;
+  execute(
+    args: DefineNodeExecuteArgs<TConfig, TInputJson>,
+    context: DefinedNodeRunContext<TConfig, TBindings>,
+  ): MaybePromise<TOutputJson>;
+}
+
+/**
+ * Batch-oriented defined node: `run` receives all item JSON once (last item in activation); emits one output per input row.
+ */
+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 +189,7 @@ const definedNodeCredentialRequirementFactory = {
 const definedNodeCredentialAccessorFactory = {
   create<TBindings extends DefinedNodeCredentialBindings | undefined>(
     bindings: TBindings,
-    ctx: NodeExecutionContext<RunnableNodeConfig<any, any, any>>,
+    ctx: NodeExecutionContext<RunnableNodeConfig<any, any>>,
   ): DefinedNodeCredentialAccessors<TBindings> {
     if (!bindings) {
       return {} as DefinedNodeCredentialAccessors<TBindings>;
@@ -167,32 +211,107 @@ export function defineNode<
   const credentialRequirements = definedNodeCredentialRequirementFactory.create(options.credentials);
   type DefinedRunnableNodeConfigShape = RunnableNodeConfig<TInputJson, TOutputJson> & Readonly<{ config: TConfig }>;
 
-  const DefinedNodeRuntime = class implements Node<DefinedRunnableNodeConfigShape> {
+  const DefinedNodeRuntime = class implements RunnableNode<DefinedRunnableNodeConfigShape, TInputJson, TOutputJson> {
     readonly kind = "node" as const;
     readonly outputPorts = ["main"] as const;
+    readonly inputSchema = options.inputSchema;
 
-    async execute(items: Items, ctx: NodeExecutionContext<DefinedRunnableNodeConfigShape>): Promise<NodeOutputs> {
-      const outputs = await options.run(
-        items.map((item) => item.json as TInputJson),
-        {
-          config: ctx.config.config,
-          credentials: definedNodeCredentialAccessorFactory.create(
-            options.credentials,
-            ctx,
-          ) as DefinedNodeCredentialAccessors<TBindings>,
-          execution: ctx as unknown as NodeExecutionContext<RunnableNodeConfig<TConfig, unknown>>,
-        },
-      );
+    async execute(
+      args: Readonly<RunnableNodeExecuteArgs<DefinedRunnableNodeConfigShape, TInputJson>>,
+    ): Promise<unknown> {
+      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: DefineNodeExecuteArgs<TConfig, TInputJson> = {
+        input: args.input,
+        item: args.item,
+        itemIndex: args.itemIndex,
+        items: args.items,
+        ctx,
+      };
+      return await options.execute(payload, context);
+    }
+  };
 
-      return {
-        main: outputs.map((json, index) => {
-          const existing = items[index];
-          if (!existing) {
-            return { json };
-          }
-          return { ...existing, json };
-        }),
+  persistedNode({ name: options.key })(DefinedNodeRuntime);
+
+  const DefinedRunnableNodeConfig = class implements RunnableNodeConfig<TInputJson, TOutputJson> {
+    readonly kind = "node" as const;
+    readonly type: TypeToken<unknown> = DefinedNodeRuntime;
+    readonly icon = options.icon;
+    readonly inputSchema = options.inputSchema;
+
+    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> = {
+    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>);
+
+  return definition;
+}
+
+export function defineBatchNode<
+  TKey extends string,
+  TConfig extends CredentialJsonRecord,
+  TInputJson,
+  TOutputJson,
+  TBindings extends DefinedNodeCredentialBindings | undefined = undefined,
+>(
+  options: DefineBatchNodeOptions<TKey, TConfig, TInputJson, TOutputJson, TBindings>,
+): DefinedNode<TKey, TConfig, TInputJson, TOutputJson, TBindings> {
+  const credentialRequirements = definedNodeCredentialRequirementFactory.create(options.credentials);
+  type DefinedRunnableNodeConfigShape = RunnableNodeConfig<TInputJson, TOutputJson> & Readonly<{ config: TConfig }>;
+
+  const DefinedNodeRuntime = class implements RunnableNode<DefinedRunnableNodeConfigShape, TInputJson, TOutputJson> {
+    readonly kind = "node" as const;
+    readonly outputPorts = ["main"] as const;
+
+    async execute(
+      args: Readonly<RunnableNodeExecuteArgs<DefinedRunnableNodeConfigShape, TInputJson>>,
+    ): Promise<unknown> {
+      if (args.itemIndex !== args.items.length - 1) {
+        return [];
+      }
+      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 outputs = await options.run(
+        args.items.map((item) => item.json as TInputJson),
+        context,
+      );
+      return [...outputs];
     }
   };
 
@@ -227,7 +346,7 @@ 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>);
 
   return definition;
 }

package/src/authoring/index.ts

@@ -5,8 +5,10 @@ export type {
   DefinedNodeCredentialBinding,
   DefinedNodeCredentialBindings,
   DefinedNodeRunContext,
+  DefineBatchNodeOptions,
+  DefineNodeExecuteArgs,
   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/bootstrap/runtime/EngineRuntimeRegistrar.ts

@@ -4,9 +4,11 @@ import { EngineExecutionLimitsPolicyFactory } from "../../policies/executionLimi
 import {
   DefaultAsyncSleeper,
   InProcessRetryRunnerFactory,
+  ItemValueResolver,
   NodeExecutor,
   NodeExecutorFactory,
   NodeInstanceFactoryFactory,
+  NodeOutputNormalizer,
 } from "../../execution";
 import {
   EngineFactory,
@@ -38,6 +40,12 @@ export class EngineRuntimeRegistrar {
   }
 
   private registerSupportFactories(container: DependencyContainer): void {
+    if (!container.isRegistered(ItemValueResolver, true)) {
+      container.registerSingleton(ItemValueResolver, ItemValueResolver);
+    }
+    if (!container.isRegistered(NodeOutputNormalizer, true)) {
+      container.registerSingleton(NodeOutputNormalizer, NodeOutputNormalizer);
+    }
     container.register(EngineExecutionLimitsPolicyFactory, { useClass: EngineExecutionLimitsPolicyFactory });
     container.register(NodeInstanceFactoryFactory, { useClass: NodeInstanceFactoryFactory });
     container.register(DefaultAsyncSleeper, { useClass: DefaultAsyncSleeper });

package/src/contracts/emitPorts.ts

@@ -0,0 +1,27 @@
+import type { Items, JsonNonArray, OutputPortKey } from "./workflowTypes";
+
+const EMIT_PORTS_BRAND = Symbol.for("codemation.emitPorts");
+
+export type PortsEmission = Readonly<{
+  readonly [EMIT_PORTS_BRAND]: true;
+  readonly ports: Readonly<Partial<Record<OutputPortKey, Items | ReadonlyArray<JsonNonArray>>>>;
+}>;
+
+export function emitPorts(
+  ports: Readonly<Partial<Record<OutputPortKey, Items | ReadonlyArray<JsonNonArray>>>>,
+): PortsEmission {
+  return { [EMIT_PORTS_BRAND]: true, ports };
+}
+
+export function isPortsEmission(value: unknown): value is PortsEmission {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    EMIT_PORTS_BRAND in value &&
+    (value as Record<symbol, unknown>)[EMIT_PORTS_BRAND] === true
+  );
+}
+
+export function isUnbrandedPortsEmissionShape(value: unknown): value is Readonly<{ ports: unknown }> {
+  return typeof value === "object" && value !== null && "ports" in value && !isPortsEmission(value);
+}

package/src/contracts/index.ts

@@ -1,5 +1,8 @@
 export * from "./credentialTypes";
+export * from "./emitPorts";
 export * from "./executionPersistenceContracts";
+export * from "./itemMeta";
+export * from "./itemValue";
 export * from "./runtimeTypes";
 export * from "./runFinishedAtFactory";
 export * from "./runTypes";

package/src/contracts/itemMeta.ts

@@ -0,0 +1,11 @@
+import type { Item } from "./workflowTypes";
+
+/**
+ * Reads `meta._cm.originIndex` when present (used for fan-in merge-by-origin and Merge routing).
+ */
+export function getOriginIndexFromItem(item: Item): number | undefined {
+  const meta = item.meta as Record<string, unknown> | undefined;
+  const cm = meta?._cm as Record<string, unknown> | undefined;
+  const v = cm?.originIndex;
+  return typeof v === "number" && Number.isFinite(v) ? v : undefined;
+}

package/src/contracts/itemValue.ts

@@ -0,0 +1,147 @@
+import type { NodeExecutionContext } from "./runtimeTypes";
+import type { Item, Items, NodeActivationId, NodeId, RunDataSnapshot, RunId, WorkflowId } from "./workflowTypes";
+
+const ITEM_VALUE_BRAND = Symbol.for("codemation.itemValue");
+
+export type ItemValueResolvedContext = Readonly<{
+  runId: RunId;
+  workflowId: WorkflowId;
+  nodeId: NodeId;
+  activationId: NodeActivationId;
+  data: RunDataSnapshot;
+}>;
+
+/**
+ * Context aligned with former {@link ItemInputMapperContext} — use **`data`** to read any completed upstream node.
+ */
+export type ItemValueContext = ItemValueResolvedContext;
+
+export type ItemValueArgs<TItemJson = unknown> = Readonly<{
+  item: Item<TItemJson>;
+  itemIndex: number;
+  items: Items<TItemJson>;
+  ctx: ItemValueContext;
+}>;
+
+export type ItemValueCallback<T, TItemJson = unknown> = (args: ItemValueArgs<TItemJson>) => T | Promise<T>;
+
+export type ItemValue<T, TItemJson = unknown> = Readonly<{
+  readonly [ITEM_VALUE_BRAND]: true;
+  readonly fn: ItemValueCallback<T, TItemJson>;
+}>;
+
+export function itemValue<T, TItemJson = unknown>(fn: ItemValueCallback<T, TItemJson>): ItemValue<T, TItemJson> {
+  return { [ITEM_VALUE_BRAND]: true, fn };
+}
+
+export function isItemValue<T, TItemJson = unknown>(value: unknown): value is ItemValue<T, TItemJson> {
+  if (typeof value !== "object" || value === null) {
+    return false;
+  }
+  const v = value as Record<PropertyKey, unknown>;
+  if (v[ITEM_VALUE_BRAND] === true) {
+    return true;
+  }
+  // Support snapshot-hydrated itemValue wrappers where the symbol brand was lost but the callback survived.
+  // Workflow snapshot hydration currently restores function-valued fields (like `fn`) but may drop symbol-keyed brands.
+  // We treat the minimal `{ fn: Function }` shape as an itemValue wrapper to keep runnable configs working.
+  const keys = Object.keys(v);
+  if (keys.length === 1 && keys[0] === "fn" && typeof (v as { fn?: unknown }).fn === "function") {
+    return true;
+  }
+  // Support legacy module-local Symbol("codemation.itemValue") brands (e.g. duplicate module graphs).
+  for (const sym of Object.getOwnPropertySymbols(v)) {
+    if (sym.description === "codemation.itemValue" && v[sym] === true) {
+      return true;
+    }
+  }
+  return false;
+}
+
+function containsItemValueInUnknown(value: unknown, seen: WeakSet<object> = new WeakSet()): boolean {
+  if (isItemValue(value)) {
+    return true;
+  }
+  if (value === null || typeof value !== "object") {
+    return false;
+  }
+  if (seen.has(value as object)) {
+    return false;
+  }
+  seen.add(value as object);
+  if (Array.isArray(value)) {
+    return value.some((entry) => containsItemValueInUnknown(entry, seen));
+  }
+  for (const entry of Object.values(value as Record<string, unknown>)) {
+    if (containsItemValueInUnknown(entry, seen)) {
+      return true;
+    }
+  }
+  return false;
+}
+
+/**
+ * Deep-resolves {@link itemValue} leaves. Returns a new graph (does not mutate the original config object).
+ */
+export async function resolveItemValuesInUnknown(
+  value: unknown,
+  args: ItemValueArgs,
+  seen: WeakSet<object> = new WeakSet(),
+): Promise<unknown> {
+  if (isItemValue(value)) {
+    return await Promise.resolve(value.fn(args));
+  }
+  if (value === null || typeof value !== "object") {
+    return value;
+  }
+  if (seen.has(value as object)) {
+    return value;
+  }
+  seen.add(value as object);
+  if (Array.isArray(value)) {
+    const out: unknown[] = [];
+    for (let i = 0; i < value.length; i++) {
+      out.push(await resolveItemValuesInUnknown(value[i], args, seen));
+    }
+    return out;
+  }
+  const rec = value as Record<string, unknown>;
+  const entries = Object.entries(rec);
+  const proto = Object.getPrototypeOf(value);
+  if (proto !== Object.prototype && proto !== null && entries.length === 0) {
+    return value;
+  }
+  const out = Object.create(proto) as Record<string, unknown>;
+  for (const [k, v] of entries) {
+    out[k] = await resolveItemValuesInUnknown(v, args, seen);
+  }
+  return out;
+}
+
+/**
+ * Clones runnable config (best-effort) so per-item {@link itemValue} resolution never mutates shared instances.
+ */
+export async function resolveItemValuesForExecution(
+  config: unknown,
+  nodeCtx: NodeExecutionContext,
+  item: Item,
+  itemIndex: number,
+  items: Items,
+): Promise<unknown | undefined> {
+  const ivArgs: ItemValueArgs = {
+    item,
+    itemIndex,
+    items,
+    ctx: {
+      runId: nodeCtx.runId,
+      workflowId: nodeCtx.workflowId,
+      nodeId: nodeCtx.nodeId,
+      activationId: nodeCtx.activationId,
+      data: nodeCtx.data,
+    },
+  };
+  if (!containsItemValueInUnknown(config)) {
+    return undefined;
+  }
+  return await resolveItemValuesInUnknown(config, ivArgs);
+}

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