@codemation/core 0.3.0 → 0.5.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,8 +4,8 @@ import type {
   CredentialRequirement,
   CredentialTypeId,
 } from "../contracts/credentialTypes";
-import type { ItemNode, Node, NodeExecutionContext } from "../contracts/runtimeTypes";
-import type { Item, ItemInputMapper, 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";
@@ -56,15 +56,15 @@ export interface DefinedNodeRunContext<
 }
 
 /**
- * Arguments for {@link defineNode} `executeOne` (engine `ctx` matches {@link ItemNode.executeOne};
+ * Arguments for {@link defineNode} `execute` (engine `ctx` matches {@link RunnableNode.execute};
  * the second callback parameter adds {@link DefinedNodeRunContext} for credential accessors).
  */
-export type DefineNodeExecuteOneArgs<TConfig extends CredentialJsonRecord, TInputJson, TWireJson> = Readonly<{
+export type DefineNodeExecuteArgs<TConfig extends CredentialJsonRecord, TInputJson> = Readonly<{
   input: TInputJson;
   item: Item;
   itemIndex: number;
   items: Items;
-  ctx: NodeExecutionContext<RunnableNodeConfig<TInputJson, unknown, TWireJson> & Readonly<{ config: TConfig }>>;
+  ctx: NodeExecutionContext<RunnableNodeConfig<TInputJson, unknown> & Readonly<{ config: TConfig }>>;
 }>;
 
 export interface DefinedNode<
@@ -73,20 +73,17 @@ export interface DefinedNode<
   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, TWireJson>;
+  create(config: TConfig, name?: string, id?: string): RunnableNodeConfig<TInputJson, TOutputJson>;
   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.
+ * Plugin / DSL-friendly node: per-item `execute` with optional {@link RunnableNodeConfig.inputSchema}.
  */
 export interface DefineNodeOptions<
   TKey extends string,
@@ -94,7 +91,6 @@ export interface DefineNodeOptions<
   TInputJson,
   TOutputJson,
   TBindings extends DefinedNodeCredentialBindings | undefined = undefined,
-  TWireJson = TInputJson,
 > {
   readonly key: TKey;
   readonly title: string;
@@ -109,21 +105,17 @@ export interface DefineNodeOptions<
   readonly configSchema?: z.ZodType<TConfig>;
   readonly credentials?: TBindings;
   /**
-   * Validates **`input`** after optional {@link mapInput} (engine also accepts `inputSchema` on the node class).
+   * Validates **`input`** (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>,
+  execute(
+    args: DefineNodeExecuteArgs<TConfig, TInputJson>,
     context: DefinedNodeRunContext<TConfig, TBindings>,
   ): MaybePromise<TOutputJson>;
 }
 
 /**
- * Batch-oriented defined node (legacy): receives all items at once via `run`.
+ * 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,
@@ -197,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>;
@@ -213,28 +205,20 @@ 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> {
+  options: DefineNodeOptions<TKey, TConfig, TInputJson, TOutputJson, TBindings>,
+): DefinedNode<TKey, TConfig, TInputJson, TOutputJson, TBindings> {
   const credentialRequirements = definedNodeCredentialRequirementFactory.create(options.credentials);
-  type DefinedRunnableNodeConfigShape = RunnableNodeConfig<TInputJson, TOutputJson, TWireJson> &
-    Readonly<{ config: TConfig }>;
+  type DefinedRunnableNodeConfigShape = RunnableNodeConfig<TInputJson, TOutputJson> & Readonly<{ config: TConfig }>;
 
-  const DefinedNodeRuntime = class implements ItemNode<DefinedRunnableNodeConfigShape, TInputJson, TOutputJson> {
+  const DefinedNodeRuntime = class implements RunnableNode<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> {
+    async execute(
+      args: Readonly<RunnableNodeExecuteArgs<DefinedRunnableNodeConfigShape, TInputJson>>,
+    ): Promise<unknown> {
       const ctx = args.ctx;
       const context: DefinedNodeRunContext<TConfig, TBindings> = {
         config: ctx.config.config,
@@ -244,25 +228,24 @@ export function defineNode<
         ) as DefinedNodeCredentialAccessors<TBindings>,
         execution: ctx as unknown as NodeExecutionContext<RunnableNodeConfig<TConfig, unknown>>,
       };
-      const payload: DefineNodeExecuteOneArgs<TConfig, TInputJson, TWireJson> = {
+      const payload: DefineNodeExecuteArgs<TConfig, TInputJson> = {
         input: args.input,
         item: args.item,
         itemIndex: args.itemIndex,
         items: args.items,
         ctx,
       };
-      return await options.executeOne(payload, context);
+      return await options.execute(payload, context);
     }
   };
 
   persistedNode({ name: options.key })(DefinedNodeRuntime);
 
-  const DefinedRunnableNodeConfig = class implements RunnableNodeConfig<TInputJson, TOutputJson, TWireJson> {
+  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;
-    readonly mapInput = options.mapInput;
 
     constructor(
       public readonly name: string,
@@ -275,7 +258,7 @@ export function defineNode<
     }
   };
 
-  const definition: DefinedNode<TKey, TConfig, TInputJson, TOutputJson, TBindings, TWireJson> = {
+  const definition: DefinedNode<TKey, TConfig, TInputJson, TOutputJson, TBindings> = {
     kind: "defined-node",
     key: options.key,
     title: options.title,
@@ -288,9 +271,7 @@ export function defineNode<
     },
   };
 
-  DefinedNodeRegistry.register(
-    definition as DefinedNode<string, Record<string, unknown>, unknown, unknown, undefined, unknown>,
-  );
+  DefinedNodeRegistry.register(definition as DefinedNode<string, Record<string, unknown>, unknown, unknown, undefined>);
 
   return definition;
 }
@@ -303,43 +284,40 @@ export function defineBatchNode<
   TBindings extends DefinedNodeCredentialBindings | undefined = undefined,
 >(
   options: DefineBatchNodeOptions<TKey, TConfig, TInputJson, TOutputJson, TBindings>,
-): DefinedNode<TKey, TConfig, TInputJson, TOutputJson, TBindings, TInputJson> {
+): DefinedNode<TKey, TConfig, TInputJson, TOutputJson, TBindings> {
   const credentialRequirements = definedNodeCredentialRequirementFactory.create(options.credentials);
-  type DefinedRunnableNodeConfigShape = RunnableNodeConfig<TInputJson, TOutputJson, TInputJson> &
-    Readonly<{ config: TConfig }>;
+  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;
 
-    async execute(items: Items, ctx: NodeExecutionContext<DefinedRunnableNodeConfigShape>): Promise<NodeOutputs> {
+    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(
-        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>>,
-        },
+        args.items.map((item) => item.json as TInputJson),
+        context,
       );
-
-      return {
-        main: outputs.map((json, index) => {
-          const existing = items[index];
-          if (!existing) {
-            return { json };
-          }
-          return { ...existing, json };
-        }),
-      };
+      return [...outputs];
     }
   };
 
   persistedNode({ name: options.key })(DefinedNodeRuntime);
 
-  const DefinedRunnableNodeConfig = class implements RunnableNodeConfig<TInputJson, TOutputJson, TInputJson> {
+  const DefinedRunnableNodeConfig = class implements RunnableNodeConfig<TInputJson, TOutputJson> {
     readonly kind = "node" as const;
     readonly type: TypeToken<unknown> = DefinedNodeRuntime;
     readonly icon = options.icon;
@@ -355,7 +333,7 @@ export function defineBatchNode<
     }
   };
 
-  const definition: DefinedNode<TKey, TConfig, TInputJson, TOutputJson, TBindings, TInputJson> = {
+  const definition: DefinedNode<TKey, TConfig, TInputJson, TOutputJson, TBindings> = {
     kind: "defined-node",
     key: options.key,
     title: options.title,
@@ -368,9 +346,7 @@ export function defineBatchNode<
     },
   };
 
-  DefinedNodeRegistry.register(
-    definition as DefinedNode<string, Record<string, unknown>, unknown, unknown, undefined, unknown>,
-  );
+  DefinedNodeRegistry.register(definition as DefinedNode<string, Record<string, unknown>, unknown, unknown, undefined>);
 
   return definition;
 }

package/src/authoring/index.ts

@@ -6,7 +6,7 @@ export type {
   DefinedNodeCredentialBindings,
   DefinedNodeRunContext,
   DefineBatchNodeOptions,
-  DefineNodeExecuteOneArgs,
+  DefineNodeExecuteArgs,
   DefineNodeOptions,
 } from "./defineNode.types";
 export { defineBatchNode, defineNode } from "./defineNode.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/credentialTypes.ts

@@ -61,11 +61,19 @@ export type OAuth2ProviderFromPublicConfig = Readonly<{
   userInfoUrlFieldKey?: string;
 }>;
 
+export type CredentialOAuth2ScopesFromPublicConfig = Readonly<{
+  presetFieldKey: string;
+  presetScopes: Readonly<Record<string, ReadonlyArray<string>>>;
+  customPresetKey?: string;
+  customScopesFieldKey?: string;
+}>;
+
 export type CredentialOAuth2AuthDefinition = Readonly<
   | {
       kind: "oauth2";
       providerId: string;
       scopes: ReadonlyArray<string>;
+      scopesFromPublicConfig?: CredentialOAuth2ScopesFromPublicConfig;
       clientIdFieldKey?: string;
       clientSecretFieldKey?: string;
     }
@@ -73,6 +81,7 @@ export type CredentialOAuth2AuthDefinition = Readonly<
       kind: "oauth2";
       providerFromPublicConfig: OAuth2ProviderFromPublicConfig;
       scopes: ReadonlyArray<string>;
+      scopesFromPublicConfig?: CredentialOAuth2ScopesFromPublicConfig;
       clientIdFieldKey?: string;
       clientSecretFieldKey?: string;
     }

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