@codemation/core 0.6.0 → 0.7.0

package/dist/testing.cjs

@@ -1,6 +1,6 @@
-const require_runtime = require('./runtime-DVBwxFvX.cjs');
+const require_runtime = require('./runtime-3YVDd2vY.cjs');
 const require_workflowActivationPolicy = require('./workflowActivationPolicy-6V3OJD3N.cjs');
-const require_bootstrap = require('./bootstrap-DVL2ue5v.cjs');
+const require_bootstrap = require('./bootstrap-D-TDU9Lu.cjs');
 let tsyringe = require("tsyringe");
 tsyringe = require_runtime.__toESM(tsyringe);
 

package/dist/testing.d.cts

@@ -1,5 +1,5 @@
-import { $n as WorkflowExecutionRepository, Bt as NodeExecutionRequest, E as NodeId, Er as Container, Gn as RunResult, Gr as EngineExecutionLimitsPolicy, Ht as NodeExecutionScheduler, J as WorkflowDefinition, Jr as RunEventBus, Jt as RunnableNode, L as RunDataFactory, Mr as TypeToken, O as NodeOffloadPolicy, P as ParentExecutionRef, Qt as TriggerNode, V as RunnableNodeConfig, W as TriggerNodeConfig, Yt as RunnableNodeExecuteArgs, en as TriggerSetupContext, et as WorkflowId, f as Items, k as NodeOutputs, kt as ExecutionContextFactory, n as InMemoryLiveWorkflowRepository, nn as TriggerSetupStateRepository, r as Engine, sn as WorkflowRunnerService, t as RunIntentService, u as Item, vr as CredentialSessionService, zt as NodeExecutionContext } from "./RunIntentService-B1Y3v1H6.cjs";
-import { a as WorkflowSnapshotCodec, n as EngineRuntimeRegistrationOptions, t as EngineWorkflowRunnerService } from "./EngineWorkflowRunnerService-Bf88QtwB.cjs";
+import { A as NodeOutputs, E as NodeId, F as ParentExecutionRef, G as TriggerNodeConfig, H as RunnableNodeConfig, Ht as NodeExecutionRequest, Or as Container, Pr as TypeToken, R as RunDataFactory, Vt as NodeExecutionContext, Wt as NodeExecutionScheduler, Xr as RunEventBus, Xt as RunnableNode, Y as WorkflowDefinition, Zt as RunnableNodeExecuteArgs, br as CredentialSessionService, en as TriggerNode, f as Items, in as TriggerSetupStateRepository, jt as ExecutionContextFactory, k as NodeOffloadPolicy, ln as WorkflowRunnerService, n as InMemoryLiveWorkflowRepository, nn as TriggerSetupContext, qn as RunResult, qr as EngineExecutionLimitsPolicy, r as Engine, t as RunIntentService, tr as WorkflowExecutionRepository, tt as WorkflowId, u as Item } from "./RunIntentService-5k0p-J67.cjs";
+import { a as WorkflowSnapshotCodec, n as EngineRuntimeRegistrationOptions, t as EngineWorkflowRunnerService } from "./EngineWorkflowRunnerService-D0Cwngv7.cjs";
 import { DependencyContainer, InjectionToken } from "tsyringe";
 import { ZodType } from "zod";
 

package/dist/testing.d.ts

@@ -1,5 +1,5 @@
-import { $i as RunEventBus, $n as RunnableNode, $t as WorkflowDefinition, Ci as CredentialSessionService, Gn as NodeExecutionRequest, Ht as RunDataFactory, Kt as RunnableNodeConfig, Li as TypeToken, Nt as NodeOffloadPolicy, Pn as ExecutionContextFactory, Pt as NodeOutputs, Wn as NodeExecutionContext, Xi as EngineExecutionLimitsPolicy, Xr as RunResult, Yt as TriggerNodeConfig, _t as Items, an as WorkflowId, ar as TriggerSetupContext, er as RunnableNodeExecuteArgs, fr as WorkflowRunnerService, ht as Item, ii as WorkflowExecutionRepository, ji as Container, jt as NodeId, l as WorkflowSnapshotCodec, n as InMemoryLiveWorkflowRepository, qn as NodeExecutionScheduler, r as EngineWorkflowRunnerService, rr as TriggerNode, sr as TriggerSetupStateRepository, t as RunIntentService, u as Engine, zt as ParentExecutionRef } from "./RunIntentService-BDiodxhf.js";
-import { t as EngineRuntimeRegistrationOptions } from "./EngineRuntimeRegistration.types-Dm129RJ6.js";
+import { $t as TriggerNodeConfig, Hi as TypeToken, Ii as Container, Kt as RunDataFactory, Lt as NodeOffloadPolicy, Oi as CredentialSessionService, Pt as NodeId, Qn as NodeExecutionScheduler, Rt as NodeOutputs, Ut as ParentExecutionRef, Xn as NodeExecutionRequest, Xt as RunnableNodeConfig, Yn as NodeExecutionContext, _r as WorkflowRunnerService, ar as RunnableNodeExecuteArgs, bt as Items, cr as TriggerNode, fr as TriggerSetupStateRepository, ia as RunEventBus, ir as RunnableNode, l as WorkflowSnapshotCodec, li as WorkflowExecutionRepository, ln as WorkflowId, n as InMemoryLiveWorkflowRepository, r as EngineWorkflowRunnerService, rn as WorkflowDefinition, t as RunIntentService, ta as EngineExecutionLimitsPolicy, ti as RunResult, u as Engine, ur as TriggerSetupContext, vt as Item, zn as ExecutionContextFactory } from "./RunIntentService-CuXAIO6_.js";
+import { t as EngineRuntimeRegistrationOptions } from "./EngineRuntimeRegistration.types-_M7KFD3D.js";
 import { DependencyContainer, InjectionToken } from "tsyringe";
 import { ZodType } from "zod";
 

package/dist/testing.js

@@ -1,6 +1,6 @@
-import { A as NodeExecutor, B as DefaultAsyncSleeper, D as PersistedWorkflowTokenRegistry, E as WorkflowSnapshotCodec, P as emitPorts, R as InProcessRetryRunner, T as NodeInstanceFactory, _t as CoreTokens, a as InMemoryLiveWorkflowRepository, b as HintOnlyOffloadPolicy, d as InMemoryRunDataFactory, i as RunIntentService, l as Engine, x as DefaultDrivingScheduler, y as InlineDrivingScheduler, z as DefaultExecutionContextFactory } from "./runtime-7Xh9z3dw.js";
+import { A as NodeExecutor, B as DefaultAsyncSleeper, D as PersistedWorkflowTokenRegistry, E as WorkflowSnapshotCodec, P as emitPorts, R as InProcessRetryRunner, T as NodeInstanceFactory, _t as CoreTokens, a as InMemoryLiveWorkflowRepository, b as HintOnlyOffloadPolicy, d as InMemoryRunDataFactory, i as RunIntentService, l as Engine, x as DefaultDrivingScheduler, y as InlineDrivingScheduler, z as DefaultExecutionContextFactory } from "./runtime-CJnObwsU.js";
 import { n as InMemoryRunEventBus, r as WorkflowBuilder, t as AllWorkflowsActiveWorkflowActivationPolicy } from "./workflowActivationPolicy-Td9HTOuD.js";
-import { n as InMemoryWorkflowExecutionRepository, t as EngineRuntimeRegistrar } from "./bootstrap-DdeiJ8cd.js";
+import { n as InMemoryWorkflowExecutionRepository, t as EngineRuntimeRegistrar } from "./bootstrap-BhYxSivA.js";
 import { container } from "tsyringe";
 
 //#region src/testing/RejectingCredentialSessionService.ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codemation/core",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "publishConfig": {
     "access": "public"
   },

package/src/ai/AgentConfigInspectorFactory.ts

@@ -1,5 +1,5 @@
 import type { NodeConfigBase } from "../types";
-import { isItemValue } from "../contracts/itemValue";
+import { isItemExpr } from "../contracts/itemExpr";
 import type { AgentNodeConfig } from "./AiHost";
 
 export class AgentConfigInspector {
@@ -18,7 +18,7 @@ export class AgentConfigInspector {
       return messages.length > 0;
     }
     if (typeof messages === "object") {
-      if (isItemValue(messages)) {
+      if (isItemExpr(messages)) {
         return true;
       }
       const o = messages as { prompt?: unknown; buildMessages?: unknown };

package/src/ai/AgentMessageConfigNormalizerFactory.ts

@@ -1,4 +1,4 @@
-import { isItemValue } from "../contracts/itemValue";
+import { isItemExpr } from "../contracts/itemExpr";
 
 import type {
   AgentMessageBuildArgs,
@@ -69,9 +69,9 @@ export class AgentMessageConfigNormalizer {
     config: AgentMessageConfig<TInputJson>,
     args: AgentMessageBuildArgs<TInputJson>,
   ): ReadonlyArray<AgentMessageDto> {
-    if (isItemValue(config)) {
+    if (isItemExpr(config)) {
       throw new Error(
-        "AIAgent messages wrapped in itemValue(...) must be resolved by the engine before prompt normalization.",
+        "AIAgent messages wrapped in itemExpr(...) must be resolved by the engine before prompt normalization.",
       );
     }
     if (Array.isArray(config)) {

package/src/ai/AiHost.ts

@@ -1,7 +1,7 @@
 import type { TypeToken } from "../di";
 
 import type { CredentialRequirement } from "../contracts/credentialTypes";
-import type { ItemValue } from "../contracts/itemValue";
+import type { Expr } from "../contracts/params";
 
 import type {
   Item,
@@ -92,7 +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>
+  | Expr<ReadonlyArray<AgentMessageLine<TInputJson>>, TInputJson>
   | ReadonlyArray<AgentMessageLine<TInputJson>>
   | {
       readonly prompt?: ReadonlyArray<AgentMessageLine<TInputJson>>;

package/src/authoring/defineNode.types.ts

@@ -4,6 +4,7 @@ import type {
   CredentialRequirement,
   CredentialTypeId,
 } from "../contracts/credentialTypes";
+import type { ParamDeep } from "../contracts/params";
 import type { RunnableNode, RunnableNodeExecuteArgs, NodeExecutionContext } from "../contracts/runtimeTypes";
 import type { Item, Items, RunnableNodeConfig } from "../contracts/workflowTypes";
 import type { TypeToken } from "../di";
@@ -67,6 +68,11 @@ export type DefineNodeExecuteArgs<TConfig extends CredentialJsonRecord, TInputJs
   ctx: NodeExecutionContext<RunnableNodeConfig<TInputJson, unknown> & Readonly<{ config: TConfig }>>;
 }>;
 
+export type DefinedNodeConfigInput<TConfigResolved extends CredentialJsonRecord, TItemJson> = ParamDeep<
+  TConfigResolved,
+  TItemJson
+>;
+
 export interface DefinedNode<
   TKey extends string,
   TConfig extends CredentialJsonRecord,
@@ -78,7 +84,11 @@ export interface DefinedNode<
   readonly key: TKey;
   readonly title: string;
   readonly description?: string;
-  create(config: TConfig, name?: string, id?: string): RunnableNodeConfig<TInputJson, TOutputJson>;
+  create<TConfigItemJson = TInputJson>(
+    config: DefinedNodeConfigInput<TConfig, TConfigItemJson>,
+    name?: string,
+    id?: string,
+  ): RunnableNodeConfig<TInputJson, TOutputJson>;
   register(context: { registerNode<TValue>(token: TypeToken<TValue>, implementation?: TypeToken<TValue>): void }): void;
 }
 
@@ -252,9 +262,13 @@ export function defineNode<
 
     constructor(
       public readonly name: string,
-      public readonly config: TConfig,
+      config: DefinedNodeConfigInput<TConfig, unknown>,
       public readonly id?: string,
-    ) {}
+    ) {
+      this.config = config as unknown as TConfig;
+    }
+
+    public readonly config: TConfig;
 
     getCredentialRequirements(): ReadonlyArray<CredentialRequirement> {
       return credentialRequirements;
@@ -266,8 +280,12 @@ export function defineNode<
     key: options.key,
     title: options.title,
     description: options.description,
-    create(config, name = options.title, id) {
-      return new DefinedRunnableNodeConfig(name, config, id);
+    create<TConfigItemJson = TInputJson>(
+      config: DefinedNodeConfigInput<TConfig, TConfigItemJson>,
+      name = options.title,
+      id?: string,
+    ) {
+      return new DefinedRunnableNodeConfig(name, config as DefinedNodeConfigInput<TConfig, unknown>, id);
     },
     register(context) {
       context.registerNode(DefinedNodeRuntime);
@@ -327,9 +345,13 @@ export function defineBatchNode<
 
     constructor(
       public readonly name: string,
-      public readonly config: TConfig,
+      config: DefinedNodeConfigInput<TConfig, unknown>,
       public readonly id?: string,
-    ) {}
+    ) {
+      this.config = config as unknown as TConfig;
+    }
+
+    public readonly config: TConfig;
 
     getCredentialRequirements(): ReadonlyArray<CredentialRequirement> {
       return credentialRequirements;
@@ -341,8 +363,12 @@ export function defineBatchNode<
     key: options.key,
     title: options.title,
     description: options.description,
-    create(config, name = options.title, id) {
-      return new DefinedRunnableNodeConfig(name, config, id);
+    create<TConfigItemJson = TInputJson>(
+      config: DefinedNodeConfigInput<TConfig, TConfigItemJson>,
+      name = options.title,
+      id?: string,
+    ) {
+      return new DefinedRunnableNodeConfig(name, config as DefinedNodeConfigInput<TConfig, unknown>, id);
     },
     register(context) {
       context.registerNode(DefinedNodeRuntime);

package/src/authoring/index.ts

@@ -1,6 +1,7 @@
 export { DefinedNodeRegistry } from "./DefinedNodeRegistry";
 export type {
   DefinedNode,
+  DefinedNodeConfigInput,
   DefinedNodeCredentialAccessors,
   DefinedNodeCredentialBinding,
   DefinedNodeCredentialBindings,

package/src/bootstrap/runtime/EngineRuntimeRegistrar.ts

@@ -4,7 +4,7 @@ import { EngineExecutionLimitsPolicyFactory } from "../../policies/executionLimi
 import {
   DefaultAsyncSleeper,
   InProcessRetryRunnerFactory,
-  ItemValueResolver,
+  ItemExprResolver,
   NodeExecutor,
   NodeExecutorFactory,
   NodeInstanceFactoryFactory,
@@ -41,8 +41,8 @@ export class EngineRuntimeRegistrar {
   }
 
   private registerSupportFactories(container: DependencyContainer): void {
-    if (!container.isRegistered(ItemValueResolver, true)) {
-      container.registerSingleton(ItemValueResolver, ItemValueResolver);
+    if (!container.isRegistered(ItemExprResolver, true)) {
+      container.registerSingleton(ItemExprResolver, ItemExprResolver);
     }
     if (!container.isRegistered(NodeOutputNormalizer, true)) {
       container.registerSingleton(NodeOutputNormalizer, NodeOutputNormalizer);

package/src/contracts/index.ts

@@ -2,7 +2,8 @@ export * from "./credentialTypes";
 export * from "./emitPorts";
 export * from "./executionPersistenceContracts";
 export * from "./itemMeta";
-export * from "./itemValue";
+export * from "./params";
+export * from "./itemExpr";
 export * from "./runtimeTypes";
 export * from "./runFinishedAtFactory";
 export * from "./runTypes";

package/src/contracts/{itemValue.ts → itemExpr.ts}

@@ -1,9 +1,9 @@
 import type { NodeExecutionContext } from "./runtimeTypes";
 import type { Item, Items, NodeActivationId, NodeId, RunDataSnapshot, RunId, WorkflowId } from "./workflowTypes";
 
-const ITEM_VALUE_BRAND = Symbol.for("codemation.itemValue");
+const ITEM_EXPR_BRAND = Symbol.for("codemation.itemExpr");
 
-export type ItemValueResolvedContext = Readonly<{
+export type ItemExprResolvedContext = Readonly<{
   runId: RunId;
   workflowId: WorkflowId;
   nodeId: NodeId;
@@ -14,52 +14,51 @@ export type ItemValueResolvedContext = Readonly<{
 /**
  * Context aligned with former {@link ItemInputMapperContext} — use **`data`** to read any completed upstream node.
  */
-export type ItemValueContext = ItemValueResolvedContext;
+export type ItemExprContext = ItemExprResolvedContext;
 
-export type ItemValueArgs<TItemJson = unknown> = Readonly<{
+export type ItemExprArgs<TItemJson = unknown> = Readonly<{
   item: Item<TItemJson>;
   itemIndex: number;
   items: Items<TItemJson>;
-  ctx: ItemValueContext;
+  ctx: ItemExprContext;
 }>;
 
-export type ItemValueCallback<T, TItemJson = unknown> = (args: ItemValueArgs<TItemJson>) => T | Promise<T>;
+export type ItemExprCallback<T, TItemJson = unknown> = (args: ItemExprArgs<TItemJson>) => T | Promise<T>;
 
-export type ItemValue<T, TItemJson = unknown> = Readonly<{
-  readonly [ITEM_VALUE_BRAND]: true;
-  readonly fn: ItemValueCallback<T, TItemJson>;
+export type ItemExpr<T, TItemJson = unknown> = Readonly<{
+  readonly [ITEM_EXPR_BRAND]: true;
+  readonly fn: ItemExprCallback<T, TItemJson>;
 }>;
 
-export function itemValue<T, TItemJson = unknown>(fn: ItemValueCallback<T, TItemJson>): ItemValue<T, TItemJson> {
-  return { [ITEM_VALUE_BRAND]: true, fn };
+export function itemExpr<T, TItemJson = unknown>(fn: ItemExprCallback<T, TItemJson>): ItemExpr<T, TItemJson> {
+  return { [ITEM_EXPR_BRAND]: true, fn };
 }
 
-export function isItemValue<T, TItemJson = unknown>(value: unknown): value is ItemValue<T, TItemJson> {
+export function isItemExpr<T, TItemJson = unknown>(value: unknown): value is ItemExpr<T, TItemJson> {
   if (typeof value !== "object" || value === null) {
     return false;
   }
   const v = value as Record<PropertyKey, unknown>;
-  if (v[ITEM_VALUE_BRAND] === true) {
+  if (v[ITEM_EXPR_BRAND] === true) {
     return true;
   }
-  // Support snapshot-hydrated itemValue wrappers where the symbol brand was lost but the callback survived.
+  // Support snapshot-hydrated itemExpr 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.
+  // We treat the minimal `{ fn: Function }` shape as an itemExpr 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) {
+    if (sym.description === "codemation.itemExpr" && v[sym] === true) {
       return true;
     }
   }
   return false;
 }
 
-function containsItemValueInUnknown(value: unknown, seen: WeakSet<object> = new WeakSet()): boolean {
-  if (isItemValue(value)) {
+function containsItemExprInUnknown(value: unknown, seen: WeakSet<object> = new WeakSet()): boolean {
+  if (isItemExpr(value)) {
     return true;
   }
   if (value === null || typeof value !== "object") {
@@ -70,10 +69,10 @@ function containsItemValueInUnknown(value: unknown, seen: WeakSet<object> = new
   }
   seen.add(value as object);
   if (Array.isArray(value)) {
-    return value.some((entry) => containsItemValueInUnknown(entry, seen));
+    return value.some((entry) => containsItemExprInUnknown(entry, seen));
   }
   for (const entry of Object.values(value as Record<string, unknown>)) {
-    if (containsItemValueInUnknown(entry, seen)) {
+    if (containsItemExprInUnknown(entry, seen)) {
       return true;
     }
   }
@@ -81,14 +80,14 @@ function containsItemValueInUnknown(value: unknown, seen: WeakSet<object> = new
 }
 
 /**
- * Deep-resolves {@link itemValue} leaves. Returns a new graph (does not mutate the original config object).
+ * Deep-resolves {@link itemExpr} leaves. Returns a new graph (does not mutate the original config object).
  */
-export async function resolveItemValuesInUnknown(
+export async function resolveItemExprsInUnknown(
   value: unknown,
-  args: ItemValueArgs,
+  args: ItemExprArgs,
   seen: WeakSet<object> = new WeakSet(),
 ): Promise<unknown> {
-  if (isItemValue(value)) {
+  if (isItemExpr(value)) {
     return await Promise.resolve(value.fn(args));
   }
   if (value === null || typeof value !== "object") {
@@ -101,7 +100,7 @@ export async function resolveItemValuesInUnknown(
   if (Array.isArray(value)) {
     const out: unknown[] = [];
     for (let i = 0; i < value.length; i++) {
-      out.push(await resolveItemValuesInUnknown(value[i], args, seen));
+      out.push(await resolveItemExprsInUnknown(value[i], args, seen));
     }
     return out;
   }
@@ -113,22 +112,22 @@ export async function resolveItemValuesInUnknown(
   }
   const out = Object.create(proto) as Record<string, unknown>;
   for (const [k, v] of entries) {
-    out[k] = await resolveItemValuesInUnknown(v, args, seen);
+    out[k] = await resolveItemExprsInUnknown(v, args, seen);
   }
   return out;
 }
 
 /**
- * Clones runnable config (best-effort) so per-item {@link itemValue} resolution never mutates shared instances.
+ * Clones runnable config (best-effort) so per-item {@link itemExpr} resolution never mutates shared instances.
  */
-export async function resolveItemValuesForExecution(
+export async function resolveItemExprsForExecution(
   config: unknown,
   nodeCtx: NodeExecutionContext,
   item: Item,
   itemIndex: number,
   items: Items,
 ): Promise<unknown | undefined> {
-  const ivArgs: ItemValueArgs = {
+  const exprArgs: ItemExprArgs = {
     item,
     itemIndex,
     items,
@@ -140,8 +139,8 @@ export async function resolveItemValuesForExecution(
       data: nodeCtx.data,
     },
   };
-  if (!containsItemValueInUnknown(config)) {
+  if (!containsItemExprInUnknown(config)) {
     return undefined;
   }
-  return await resolveItemValuesInUnknown(config, ivArgs);
+  return await resolveItemExprsInUnknown(config, exprArgs);
 }

package/src/contracts/params.ts

@@ -0,0 +1,10 @@
+import type { ItemExpr } from "./itemExpr";
+
+export type Expr<T, TItemJson = unknown> = ItemExpr<T, TItemJson>;
+
+export type Param<T, TItemJson = unknown> = T | Expr<T, TItemJson>;
+
+export type ParamDeep<T, TItemJson = unknown> =
+  | Expr<T, TItemJson>
+  | (T extends readonly (infer U)[] ? ReadonlyArray<ParamDeep<U, TItemJson>> : never)
+  | (T extends object ? { [K in keyof T]: ParamDeep<T[K], TItemJson> } : T);

package/src/contracts/workflowTypes.ts

@@ -6,6 +6,7 @@ import type { RetryPolicySpec } from "./retryPolicySpec.types";
 
 export type WorkflowId = string;
 export type NodeId = string;
+export type NodeIdRef<TJson = unknown> = NodeId & Readonly<{ __codemationNodeJson?: TJson }>;
 export type OutputPortKey = string;
 export type InputPortKey = string;
 export type PersistedTokenId = string;
@@ -154,6 +155,10 @@ export interface NodeRef {
   name?: string;
 }
 
+export function nodeRef<TJson>(nodeId: NodeId): NodeIdRef<TJson> {
+  return nodeId as NodeIdRef<TJson>;
+}
+
 export type PairedItemRef = Readonly<{ nodeId: NodeId; output: OutputPortKey; itemIndex: number }>;
 
 export type BinaryPreviewKind = "image" | "audio" | "video" | "download";
@@ -204,8 +209,12 @@ export interface ParentExecutionRef {
 
 export interface RunDataSnapshot {
   getOutputs(nodeId: NodeId): NodeOutputs | undefined;
-  getOutputItems(nodeId: NodeId, output?: OutputPortKey): Items;
-  getOutputItem(nodeId: NodeId, itemIndex: number, output?: OutputPortKey): Item | undefined;
+  getOutputItems<TJson = unknown>(nodeId: NodeId | NodeIdRef<TJson>, output?: OutputPortKey): Items<TJson>;
+  getOutputItem<TJson = unknown>(
+    nodeId: NodeId | NodeIdRef<TJson>,
+    itemIndex: number,
+    output?: OutputPortKey,
+  ): Item<TJson> | undefined;
 }
 
 export interface MutableRunData extends RunDataSnapshot {

package/src/execution/{ItemValueResolver.ts → ItemExprResolver.ts}

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

package/src/execution/NodeExecutor.ts

@@ -15,7 +15,7 @@ import type {
 } from "../types";
 
 import { FanInMergeByOriginMerger } from "./FanInMergeByOriginMerger";
-import { ItemValueResolver } from "./ItemValueResolver";
+import { ItemExprResolver } from "./ItemExprResolver";
 import { InProcessRetryRunner } from "./InProcessRetryRunner";
 import { NodeOutputNormalizer } from "./NodeOutputNormalizer";
 import { RunnableOutputBehaviorResolver } from "./RunnableOutputBehaviorResolver";
@@ -23,16 +23,16 @@ import { RunnableOutputBehaviorResolver } from "./RunnableOutputBehaviorResolver
 export class NodeExecutor {
   private readonly fanInMerger = new FanInMergeByOriginMerger();
   private readonly outputNormalizer = new NodeOutputNormalizer();
-  private readonly itemValueResolver: ItemValueResolver;
+  private readonly itemExprResolver: ItemExprResolver;
   private readonly outputBehaviorResolver: RunnableOutputBehaviorResolver;
 
   constructor(
     private readonly nodeInstanceFactory: WorkflowNodeInstanceFactory,
     private readonly retryRunner: InProcessRetryRunner,
-    itemValueResolver?: ItemValueResolver,
+    itemExprResolver?: ItemExprResolver,
     outputBehaviorResolver?: RunnableOutputBehaviorResolver,
   ) {
-    this.itemValueResolver = itemValueResolver ?? new ItemValueResolver();
+    this.itemExprResolver = itemExprResolver ?? new ItemExprResolver();
     this.outputBehaviorResolver = outputBehaviorResolver ?? new RunnableOutputBehaviorResolver();
   }
 
@@ -135,7 +135,7 @@ export class NodeExecutor {
       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 resolvedCtx = await this.itemExprResolver.resolveConfigForItem(runnableCtx, syntheticItem, 0, inputBatch);
       const ctx = this.pickExecutionContext(runnableCtx, resolvedCtx);
       const args: RunnableNodeExecuteArgs = {
         input: parsed,
@@ -157,7 +157,7 @@ export class NodeExecutor {
       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 resolvedCtx = await this.itemExprResolver.resolveConfigForItem(runnableCtx, item, i, inputBatch);
       const ctx = this.pickExecutionContext(runnableCtx, resolvedCtx);
       const args: RunnableNodeExecuteArgs = {
         input: parsed,

package/src/execution/index.ts

@@ -5,7 +5,7 @@ export { CredentialResolverFactory } from "./CredentialResolverFactory";
 export { DefaultAsyncSleeper } from "./DefaultAsyncSleeper";
 export { DefaultExecutionContextFactory } from "./DefaultExecutionContextFactory";
 export { InProcessRetryRunner } from "./InProcessRetryRunner";
-export { ItemValueResolver } from "./ItemValueResolver";
+export { ItemExprResolver } from "./ItemExprResolver";
 export { NodeOutputNormalizer } from "./NodeOutputNormalizer";
 export { RunnableOutputBehaviorResolver } from "./RunnableOutputBehaviorResolver";
 export { InProcessRetryRunnerFactory } from "./InProcessRetryRunnerFactory";

package/src/index.ts

@@ -18,7 +18,7 @@ export {
   DefaultAsyncSleeper,
   DefaultExecutionContextFactory,
   InProcessRetryRunner,
-  ItemValueResolver,
+  ItemExprResolver,
   NodeOutputNormalizer,
   RunnableOutputBehaviorResolver,
 } from "./execution";

package/src/runStorage/InMemoryRunData.ts

@@ -1,4 +1,4 @@
-import type { Items, MutableRunData, NodeId, NodeOutputs, OutputPortKey } from "../types";
+import type { Items, MutableRunData, NodeId, NodeIdRef, NodeOutputs, OutputPortKey, Item } from "../types";
 
 export class InMemoryRunData implements MutableRunData {
   private readonly byNode = new Map<NodeId, NodeOutputs>();
@@ -17,12 +17,16 @@ export class InMemoryRunData implements MutableRunData {
     return this.byNode.get(nodeId);
   }
 
-  getOutputItems(nodeId: NodeId, output: OutputPortKey = "main"): Items {
-    return this.byNode.get(nodeId)?.[output] ?? [];
+  getOutputItems<TJson = unknown>(nodeId: NodeId | NodeIdRef<TJson>, output: OutputPortKey = "main"): Items<TJson> {
+    return (this.byNode.get(nodeId)?.[output] ?? []) as Items<TJson>;
   }
 
-  getOutputItem(nodeId: NodeId, itemIndex: number, output: OutputPortKey = "main") {
-    return this.getOutputItems(nodeId, output)[itemIndex];
+  getOutputItem<TJson = unknown>(
+    nodeId: NodeId | NodeIdRef<TJson>,
+    itemIndex: number,
+    output: OutputPortKey = "main",
+  ): Item<TJson> | undefined {
+    return this.getOutputItems<TJson>(nodeId, output)[itemIndex];
   }
 
   dump(): Record<NodeId, NodeOutputs> {

package/src/types/index.ts

@@ -1,6 +1,7 @@
 export * from "../contracts/emitPorts";
 export * from "../contracts/itemMeta";
-export * from "../contracts/itemValue";
+export * from "../contracts/params";
+export * from "../contracts/itemExpr";
 export * from "../contracts/retryPolicySpec.types";
 export * from "../contracts/NoRetryPolicy";
 export * from "../contracts/RetryPolicy";

package/src/workflowSnapshots/WorkflowSnapshotCodec.ts

@@ -134,7 +134,7 @@ export class WorkflowSnapshotCodec {
         hydrated[key] = value;
       }
     }
-    // Preserve symbol-keyed brands (e.g. itemValue / emitPorts) and other runtime-only keys.
+    // Preserve symbol-keyed brands (e.g. itemExpr / emitPorts) and other runtime-only keys.
     for (const sym of Object.getOwnPropertySymbols(liveRecord)) {
       hydrated[sym] = liveRecord[sym];
     }