@codemation/core 0.13.2 → 0.14.0

package/dist/testing.cjs

@@ -1,8 +1,8 @@
-const require_di = require('./di-LP2qSHkY.cjs');
+const require_di = require('./di-DhwtDRgs.cjs');
 require('./contracts-CK0x6w_G.cjs');
-const require_runtime = require('./runtime-_VdHwGkJ.cjs');
+const require_runtime = require('./runtime-n2tqRwaf.cjs');
 const require_InMemoryRunEventBusRegistry = require('./InMemoryRunEventBusRegistry-Sa86VxuV.cjs');
-const require_bootstrap = require('./bootstrap-DIv-vloi.cjs');
+const require_bootstrap = require('./bootstrap-Be0LB0nh.cjs');
 let tsyringe = require("tsyringe");
 tsyringe = require_di.__toESM(tsyringe);
 

package/dist/testing.d.cts

@@ -1,6 +1,6 @@
-import { $t as RunnableNodeConfig, Cr as TriggerSetupStateRepository, Ct as Item, H as WorkflowExecutionRepository, Ht as NodeOffloadPolicy, N as RunResult, Or as WorkflowRunnerService, Pi as CredentialSessionService, Tt as Items, U as Container, Un as ExecutionContextFactory, Ut as NodeOutputs, Xi as WorkflowId, Y as TypeToken, Yt as RunDataFactory, ct as EngineExecutionLimitsPolicy, dt as RunEventBus, hr as RunnableNodeExecuteArgs, ir as NodeExecutionRequest, mr as RunnableNode, nn as TriggerNodeConfig, on as WorkflowDefinition, or as NodeExecutionScheduler, qi as NodeId, qt as ParentExecutionRef, rr as NodeExecutionContext, xr as TriggerSetupContext, yr as TriggerNode } from "./agentMcpTypes-DGIwk6Ue.cjs";
-import { n as InMemoryLiveWorkflowRepository, r as Engine, t as RunIntentService } from "./RunIntentService-BitgkKaT.cjs";
-import { a as WorkflowSnapshotCodec, i as EngineWorkflowRunnerService, t as EngineRuntimeRegistrationOptions } from "./EngineRuntimeRegistration.types-CqcTWexS.cjs";
+import { $t as RunnableNodeConfig, Cr as TriggerSetupStateRepository, Ct as Item, H as WorkflowExecutionRepository, Ht as NodeOffloadPolicy, N as RunResult, Or as WorkflowRunnerService, Pi as CredentialSessionService, Tt as Items, U as Container, Un as ExecutionContextFactory, Ut as NodeOutputs, Xi as WorkflowId, Y as TypeToken, Yt as RunDataFactory, ct as EngineExecutionLimitsPolicy, dt as RunEventBus, hr as RunnableNodeExecuteArgs, ir as NodeExecutionRequest, mr as RunnableNode, nn as TriggerNodeConfig, on as WorkflowDefinition, or as NodeExecutionScheduler, qi as NodeId, qt as ParentExecutionRef, rr as NodeExecutionContext, xr as TriggerSetupContext, yr as TriggerNode } from "./agentMcpTypes-B11B3Hd-.cjs";
+import { n as InMemoryLiveWorkflowRepository, r as Engine, t as RunIntentService } from "./RunIntentService-0f3ICjAz.cjs";
+import { a as WorkflowSnapshotCodec, i as EngineWorkflowRunnerService, t as EngineRuntimeRegistrationOptions } from "./EngineRuntimeRegistration.types-BYAmGMdS.cjs";
 import { ZodType } from "zod";
 import { DependencyContainer, InjectionToken } from "tsyringe";
 

package/dist/testing.d.ts

@@ -1,6 +1,6 @@
-import { Eo as NodeId, Er as ParentExecutionRef, Fr as TriggerNodeConfig, Ii as NodeExecutionContext, Ji as RunnableNodeExecuteArgs, Li as NodeExecutionRequest, Mr as RunnableNodeConfig, On as TypeToken, Or as RunDataFactory, Qi as TriggerNode, Si as ExecutionContextFactory, Sn as Container, Sr as NodeOutputs, Vn as EngineExecutionLimitsPolicy, Wn as RunEventBus, ea as TriggerSetupContext, fn as RunResult, ir as Items, ko as WorkflowId, na as TriggerSetupStateRepository, nr as Item, po as CredentialSessionService, qi as RunnableNode, sa as WorkflowRunnerService, xn as WorkflowExecutionRepository, xr as NodeOffloadPolicy, zi as NodeExecutionScheduler, zr as WorkflowDefinition } from "./index-rllWL4r-.js";
-import { i as WorkflowSnapshotCodec, n as InMemoryLiveWorkflowRepository, r as EngineWorkflowRunnerService, t as RunIntentService, u as Engine } from "./RunIntentService-DYpqfu6D.js";
-import { t as EngineRuntimeRegistrationOptions } from "./EngineRuntimeRegistration.types-Cr75cSfL.js";
+import { An as TypeToken, Ar as RunDataFactory, Cn as WorkflowExecutionRepository, Cr as NodeOffloadPolicy, Kn as RunEventBus, Lr as TriggerNodeConfig, Oo as NodeId, Or as ParentExecutionRef, Pr as RunnableNodeConfig, Ri as NodeExecutionContext, Un as EngineExecutionLimitsPolicy, Vi as NodeExecutionScheduler, Vr as WorkflowDefinition, Xi as RunnableNodeExecuteArgs, Yi as RunnableNode, ea as TriggerNode, ho as CredentialSessionService, ia as TriggerSetupStateRepository, ir as Item, jo as WorkflowId, la as WorkflowRunnerService, mn as RunResult, na as TriggerSetupContext, or as Items, wi as ExecutionContextFactory, wn as Container, wr as NodeOutputs, zi as NodeExecutionRequest } from "./index-CbJdbIHe.js";
+import { i as WorkflowSnapshotCodec, n as InMemoryLiveWorkflowRepository, r as EngineWorkflowRunnerService, t as RunIntentService, u as Engine } from "./RunIntentService-Dx_HHxDX.js";
+import { t as EngineRuntimeRegistrationOptions } from "./EngineRuntimeRegistration.types-CVLI8DsJ.js";
 import { DependencyContainer, InjectionToken } from "tsyringe";
 import { ZodType } from "zod";
 

package/dist/testing.js

@@ -1,8 +1,8 @@
-import { d as CoreTokens } from "./di-tom0pM2h.js";
+import { d as CoreTokens } from "./di-CEV6wTc4.js";
 import "./contracts-DXdfTdpW.js";
-import { A as PersistedWorkflowTokenRegistry, C as DefaultDrivingScheduler, G as AllWorkflowsActiveWorkflowActivationPolicy, N as NodeExecutor, O as NodeInstanceFactory, S as HintOnlyOffloadPolicy, V as DefaultExecutionContextFactory, a as InMemoryLiveWorkflowRepository, i as RunIntentService, it as emitPorts, k as WorkflowSnapshotCodec, l as Engine, p as InMemoryRunDataFactory, st as DefaultAsyncSleeper, x as InlineDrivingScheduler, yt as WorkflowBuilder, z as InProcessRetryRunner } from "./runtime-CWPdvJpC.js";
+import { A as PersistedWorkflowTokenRegistry, C as DefaultDrivingScheduler, G as AllWorkflowsActiveWorkflowActivationPolicy, N as NodeExecutor, O as NodeInstanceFactory, S as HintOnlyOffloadPolicy, V as DefaultExecutionContextFactory, a as InMemoryLiveWorkflowRepository, i as RunIntentService, it as emitPorts, k as WorkflowSnapshotCodec, l as Engine, p as InMemoryRunDataFactory, st as DefaultAsyncSleeper, x as InlineDrivingScheduler, yt as WorkflowBuilder, z as InProcessRetryRunner } from "./runtime-CSunvf7A.js";
 import { t as InMemoryRunEventBus } from "./InMemoryRunEventBusRegistry-Bwunvt1T.js";
-import { a as InMemoryWorkflowExecutionRepository, t as EngineRuntimeRegistrar } from "./bootstrap-Bkd-Nfbn.js";
+import { a as InMemoryWorkflowExecutionRepository, t as EngineRuntimeRegistrar } from "./bootstrap-pSQdsMfa.js";
 import { container } from "tsyringe";
 
 //#region src/testing/RejectingCredentialSessionService.ts

package/package.json

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

package/src/authoring/defineNode.types.ts

@@ -12,6 +12,7 @@ import { node as persistedNode } from "../runtime-types/runtimeTypeDecorators.ty
 import type { ZodType } from "zod";
 import { z } from "zod";
 import { DefinedNodeRegistry } from "./DefinedNodeRegistry";
+import type { NodeBaseOptions } from "./nodeBaseOptions.types";
 
 type MaybePromise<TValue> = TValue | Promise<TValue>;
 
@@ -87,7 +88,7 @@ export interface DefinedNode<
   create<TConfigItemJson = TInputJson>(
     config: DefinedNodeConfigInput<TConfig, TConfigItemJson>,
     name?: string,
-    id?: string,
+    idOrOptions?: string | NodeBaseOptions,
   ): RunnableNodeConfig<TInputJson, TOutputJson>;
   register(context: { registerNode<TValue>(token: TypeToken<TValue>, implementation?: TypeToken<TValue>): void }): void;
 }
@@ -271,12 +272,17 @@ export function defineNode<
     readonly icon = options.icon;
     readonly inputSchema = options.inputSchema;
     readonly keepBinaries = options.keepBinaries ?? false;
+    readonly id?: string;
+    readonly description?: string;
 
     constructor(
       public readonly name: string,
       config: DefinedNodeConfigInput<TConfig, unknown>,
-      public readonly id?: string,
+      idOrOptions?: string | NodeBaseOptions,
     ) {
+      const resolved = typeof idOrOptions === "string" ? { id: idOrOptions } : idOrOptions;
+      this.id = resolved?.id;
+      this.description = resolved?.description;
       this.config = config as unknown as TConfig;
     }
 
@@ -299,9 +305,9 @@ export function defineNode<
     create<TConfigItemJson = TInputJson>(
       config: DefinedNodeConfigInput<TConfig, TConfigItemJson>,
       name = options.title,
-      id?: string,
+      idOrOptions?: string | NodeBaseOptions,
     ) {
-      return new DefinedRunnableNodeConfig(name, config as DefinedNodeConfigInput<TConfig, unknown>, id);
+      return new DefinedRunnableNodeConfig(name, config as DefinedNodeConfigInput<TConfig, unknown>, idOrOptions);
     },
     register(context) {
       context.registerNode(DefinedNodeRuntime);
@@ -358,12 +364,17 @@ export function defineBatchNode<
     readonly kind = "node" as const;
     readonly type: TypeToken<unknown> = DefinedNodeRuntime;
     readonly icon = options.icon;
+    readonly id?: string;
+    readonly description?: string;
 
     constructor(
       public readonly name: string,
       config: DefinedNodeConfigInput<TConfig, unknown>,
-      public readonly id?: string,
+      idOrOptions?: string | NodeBaseOptions,
     ) {
+      const resolved = typeof idOrOptions === "string" ? { id: idOrOptions } : idOrOptions;
+      this.id = resolved?.id;
+      this.description = resolved?.description;
       this.config = config as unknown as TConfig;
     }
 
@@ -386,9 +397,9 @@ export function defineBatchNode<
     create<TConfigItemJson = TInputJson>(
       config: DefinedNodeConfigInput<TConfig, TConfigItemJson>,
       name = options.title,
-      id?: string,
+      idOrOptions?: string | NodeBaseOptions,
     ) {
-      return new DefinedRunnableNodeConfig(name, config as DefinedNodeConfigInput<TConfig, unknown>, id);
+      return new DefinedRunnableNodeConfig(name, config as DefinedNodeConfigInput<TConfig, unknown>, idOrOptions);
     },
     register(context) {
       context.registerNode(DefinedNodeRuntime);

package/src/authoring/definePollingTrigger.types.ts

@@ -21,6 +21,7 @@ import type {
 } from "..";
 import type { CredentialJsonRecord, CredentialRequirement } from "../contracts/credentialTypes";
 import type { DefinedNodeCredentialAccessors, DefinedNodeCredentialBindings } from "./defineNode.types";
+import type { NodeBaseOptions } from "./nodeBaseOptions.types";
 import { node as persistedNode } from "../runtime-types/runtimeTypeDecorators.types";
 import {
   definedNodeCredentialRequirementFactory,
@@ -170,9 +171,14 @@ export interface DefinedPollingTrigger<
    * Create the trigger config for use in workflow definitions.
    * @param cfg - User-facing trigger configuration.
    * @param name - Display name (defaults to `title`).
-   * @param id - Optional stable node id.
+   * @param idOrOptions - Optional stable node id, or `{ id?, description? }` authoring options
+   *   (a bare string id still works — back-compat).
    */
-  create(cfg: TConfig, name?: string, id?: string): DefinedPollingTriggerConfig<TConfig, TItemJson>;
+  create(
+    cfg: TConfig,
+    name?: string,
+    idOrOptions?: string | NodeBaseOptions,
+  ): DefinedPollingTriggerConfig<TConfig, TItemJson>;
   /**
    * Test seam: call `poll` directly without starting the runtime.
    * Returns `{ items, nextState }` just like the real runtime receives.
@@ -203,6 +209,8 @@ export class DefinedPollingTriggerConfig<TConfig extends CredentialJsonRecord, T
   readonly kind = "trigger" as const;
   readonly type: TypeToken<unknown>;
   readonly icon: string | undefined;
+  readonly id?: string;
+  readonly description?: string;
 
   constructor(
     public readonly name: string,
@@ -210,13 +218,16 @@ export class DefinedPollingTriggerConfig<TConfig extends CredentialJsonRecord, T
     typeToken: TypeToken<unknown>,
     icon: string | undefined,
     private readonly credentialRequirements: ReadonlyArray<CredentialRequirement>,
-    public readonly id?: string,
+    idOrOptions?: string | NodeBaseOptions,
     private readonly inspectorSummaryFn?: (
       args: Readonly<{ config: TConfig }>,
     ) => ReadonlyArray<NodeInspectorSummaryRow> | undefined,
   ) {
     this.type = typeToken;
     this.icon = icon;
+    const resolved = typeof idOrOptions === "string" ? { id: idOrOptions } : idOrOptions;
+    this.id = resolved?.id;
+    this.description = resolved?.description;
   }
 
   getCredentialRequirements(): ReadonlyArray<CredentialRequirement> {
@@ -385,14 +396,18 @@ export function definePollingTrigger<
     title: options.title,
     description: options.description,
 
-    create(cfg: TConfig, name = options.title, id?: string): DefinedPollingTriggerConfig<TConfig, TItemJson> {
+    create(
+      cfg: TConfig,
+      name = options.title,
+      idOrOptions?: string | NodeBaseOptions,
+    ): DefinedPollingTriggerConfig<TConfig, TItemJson> {
       return new DefinedPollingTriggerConfig<TConfig, TItemJson>(
         name,
         cfg,
         DefinedPollingTriggerRuntime,
         options.icon,
         credentialRequirements,
-        id,
+        idOrOptions,
         options.inspectorSummary as
           | ((args: Readonly<{ config: TConfig }>) => ReadonlyArray<NodeInspectorSummaryRow> | undefined)
           | undefined,

package/src/authoring/index.ts

@@ -1,4 +1,5 @@
 export { DefinedNodeRegistry } from "./DefinedNodeRegistry";
+export type { NodeBaseOptions } from "./nodeBaseOptions.types";
 export type {
   DefinedNode,
   DefinedNodeConfigInput,

package/src/authoring/nodeBaseOptions.types.ts

@@ -0,0 +1,18 @@
+/**
+ * Core-local copy of the per-instance authoring options every `define*` factory's `create(...)`
+ * accepts in its trailing argument: a stable `id` plus a plain-language `description` (the
+ * non-technical "what does this step do" line surfaced in the node sidebar).
+ *
+ * `description` is a first-class option — passed inline exactly like `id` — and is threaded onto
+ * the config instance as an OWN ENUMERABLE field so it flows into the persisted workflow snapshot
+ * (`WorkflowSnapshotCodec` serializes via `JSON.parse(JSON.stringify(config))`, which only captures
+ * own enumerable properties — never a getter).
+ *
+ * `@codemation/core-nodes` declares an identical `NodeBaseOptions` for its bare-id built-in nodes;
+ * core keeps its own copy because core must not depend on `@codemation/core-nodes` (dependency
+ * direction). The two types are structurally identical by design.
+ */
+export interface NodeBaseOptions {
+  readonly id?: string;
+  readonly description?: string;
+}

package/src/contracts/itemExpr.ts

@@ -1,7 +1,11 @@
 import type { NodeExecutionContext } from "./runtimeTypes";
 import type { Item, Items, NodeActivationId, NodeId, RunDataSnapshot, RunId, WorkflowId } from "./workflowTypes";
 
-const ITEM_EXPR_BRAND = Symbol.for("codemation.itemExpr");
+// Structural string-literal brand (NOT a `unique symbol`): independently-bundled copies of
+// `ItemExpr` across node packages must be STRUCTURALLY identical to stay cross-assignable. A
+// `unique symbol` makes each bundled copy a nominally-distinct type, which breaks passing an
+// `itemExpr()` into a node-config field whose package resolved a different (duplicated) copy of
+// core. A plain string-literal property is identical across copies and also survives JSON.
 
 export type ItemExprResolvedContext = Readonly<{
   runId: RunId;
@@ -26,12 +30,12 @@ export type ItemExprArgs<TItemJson = unknown> = Readonly<{
 export type ItemExprCallback<T, TItemJson = unknown> = (args: ItemExprArgs<TItemJson>) => T | Promise<T>;
 
 export type ItemExpr<T, TItemJson = unknown> = Readonly<{
-  readonly [ITEM_EXPR_BRAND]: true;
+  readonly __codemationItemExpr: "codemation.itemExpr";
   readonly fn: ItemExprCallback<T, TItemJson>;
 }>;
 
 export function itemExpr<T, TItemJson = unknown>(fn: ItemExprCallback<T, TItemJson>): ItemExpr<T, TItemJson> {
-  return { [ITEM_EXPR_BRAND]: true, fn };
+  return { __codemationItemExpr: "codemation.itemExpr", fn };
 }
 
 export function isItemExpr<T, TItemJson = unknown>(value: unknown): value is ItemExpr<T, TItemJson> {
@@ -39,21 +43,21 @@ export function isItemExpr<T, TItemJson = unknown>(value: unknown): value is Ite
     return false;
   }
   const v = value as Record<PropertyKey, unknown>;
-  if (v[ITEM_EXPR_BRAND] === true) {
-    return true;
-  }
-  // 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 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") {
+  // Current structural brand (a plain string property; survives JSON serialization).
+  if (v["__codemationItemExpr"] === "codemation.itemExpr" && typeof v["fn"] === "function") {
     return true;
   }
+  // Legacy: the old `Symbol.for("codemation.itemExpr")` brand (configs from an older core build).
   for (const sym of Object.getOwnPropertySymbols(v)) {
     if (sym.description === "codemation.itemExpr" && v[sym] === true) {
       return true;
     }
   }
+  // Snapshot-hydrated wrappers where the brand was dropped but the callback survived.
+  const keys = Object.keys(v);
+  if (keys.length === 1 && keys[0] === "fn" && typeof (v as { fn?: unknown }).fn === "function") {
+    return true;
+  }
   return false;
 }
 

package/src/contracts/workflowTypes.ts

@@ -76,6 +76,13 @@ export interface NodeConfigBase {
   readonly name?: string;
   readonly id?: NodeId;
   readonly icon?: string;
+  /**
+   * Plain-language, non-technical explanation of what this node does, surfaced in the workflow
+   * inspector / node properties sidebar. A first-class config option every authorable node accepts
+   * directly (alongside `id`), so it flows into the persisted config the mappers read. Distinct from
+   * {@link inspectorSummary} (config-derived label/value rows).
+   */
+  readonly description?: string;
   readonly execution?: Readonly<{ hint?: "local" | "worker"; queue?: string }>;
   /** In-process execute retries (runnable nodes). Triggers typically omit this. */
   readonly retryPolicy?: RetryPolicySpec;

package/src/contracts/workspaceFileTypes.ts

@@ -19,11 +19,11 @@ export interface WorkspaceFileMetadata {
 }
 
 /**
- * Read-only, workspace-scoped port for accessing the shared workspace file pool.
+ * Workspace-scoped port for accessing the shared workspace file pool.
  * Implemented in `@codemation/host`; nodes reach it via `ctx.resolve(WorkspaceFileStorageToken)`.
  *
  * Key scheme: `<workspaceId>/files/<fileId>` — but nodes never construct raw keys.
- * Use the workspace-level helpers (`listFiles`, `getFileByName`, `getFileById`) instead.
+ * Use the workspace-level helpers (`listFiles`, `getFileByName`, `getFileById`, `writeFile`) instead.
  *
  * This adapter is SEPARATE from the run-scoped BinaryStorage — do not confuse the two.
  */
@@ -52,6 +52,25 @@ export interface IWorkspaceFileStorage {
    * @throws WorkspaceFileNotFoundError when the key does not exist.
    */
   getStream(key: string): Promise<ReadableStream<Uint8Array>>;
+
+  /**
+   * Writes a file into the workspace's shared file pool.
+   *
+   * Generates a new fileId internally; the caller never constructs a raw key.
+   * Stamps the filename into object metadata so read-side adapters can resolve
+   * files by name without querying a registry.
+   *
+   * Returns the stored file's metadata (fileId, key, filename, contentType, size,
+   * lastModified). Callers that need concierge visibility must also register a
+   * WorkspaceFile row on the CP side via the HMAC-paired
+   * `POST /internal/workspace-files/register` endpoint — see the host-side
+   * `WorkspaceFileRegistrarClient`.
+   *
+   * @param filename    Original filename; stored in object metadata.
+   * @param body        Bytes to write (contiguous — required for presigned PUT Content-Length).
+   * @param contentType MIME type.
+   */
+  writeFile(filename: string, body: Uint8Array, contentType: string): Promise<WorkspaceFileMetadata>;
 }
 
 /**
@@ -64,6 +83,17 @@ export class WorkspaceFileNotFoundError extends Error {
   }
 }
 
+/**
+ * Port for registering a workflow-written file in the CP's WorkspaceFile table.
+ * Optional: only wired when the host is paired with a control plane.
+ * Implemented by `WorkspaceFileRegistrarClient` in `@codemation/host`.
+ * Nodes call this after `writeFile` so the concierge can see the file via
+ * `list_files` / `get_file`.
+ */
+export interface IWorkspaceFileRegistrar {
+  register(meta: WorkspaceFileMetadata): Promise<void>;
+}
+
 /**
  * DI token for the workspace-scoped file storage adapter.
  * Registered by `@codemation/host`; resolved by workspace-file nodes via `ctx.resolve(...)`.
@@ -71,3 +101,13 @@ export class WorkspaceFileNotFoundError extends Error {
 export const WorkspaceFileStorageToken = Symbol.for("codemation.core.WorkspaceFileStorage") as TypeToken<
   IWorkspaceFileStorage | undefined
 >;
+
+/**
+ * DI token for the optional CP registry hook.
+ * Present only when the host is paired (managed mode). Standalone / local-fs
+ * deployments leave this undefined — workflow-written files will be in S3/local
+ * but will not appear in the concierge's list_files.
+ */
+export const WorkspaceFileRegistrarToken = Symbol.for("codemation.core.WorkspaceFileRegistrar") as TypeToken<
+  IWorkspaceFileRegistrar | undefined
+>;

package/src/execution/NodeOutputNormalizer.ts

@@ -73,10 +73,17 @@ export class NodeOutputNormalizer {
     return typeof value === "object" && value !== null && "json" in value;
   }
 
+  private isPlainJsonObject(value: unknown): value is Record<string, unknown> {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+  }
+
   private applyOutput(baseItem: Item, next: Item, behavior: RunnableOutputBehavior): Item {
     const explicitBinary = next.binary;
     return {
-      json: next.json,
+      json:
+        behavior.mergeJson && this.isPlainJsonObject(baseItem.json) && this.isPlainJsonObject(next.json)
+          ? { ...baseItem.json, ...next.json }
+          : next.json,
       ...(explicitBinary !== undefined
         ? { binary: explicitBinary }
         : behavior.keepBinaries && baseItem.binary

package/src/execution/RunnableOutputBehaviorResolver.ts

@@ -5,14 +5,21 @@ type BinaryKeepingRunnableNodeConfig = RunnableNodeConfig &
     keepBinaries?: boolean;
   }>;
 
+type MergeJsonRunnableNodeConfig = RunnableNodeConfig &
+  Readonly<{
+    mergeJson?: boolean;
+  }>;
+
 export type RunnableOutputBehavior = Readonly<{
   keepBinaries: boolean;
+  mergeJson: boolean;
 }>;
 
 export class RunnableOutputBehaviorResolver {
   resolve(config: RunnableNodeConfig): RunnableOutputBehavior {
     return {
       keepBinaries: this.isKeepBinariesEnabled(config),
+      mergeJson: this.isMergeJsonEnabled(config),
     };
   }
 
@@ -20,4 +27,9 @@ export class RunnableOutputBehaviorResolver {
     const candidate = config as BinaryKeepingRunnableNodeConfig;
     return candidate.keepBinaries === true;
   }
+
+  private isMergeJsonEnabled(config: RunnableNodeConfig): boolean {
+    const candidate = config as MergeJsonRunnableNodeConfig;
+    return candidate.mergeJson === true;
+  }
 }

package/src/index.ts

@@ -84,5 +84,13 @@ export type {
 export { IllegalMaterialSourceError } from "./credentials/CredentialMaterialProvider.types";
 export { ManagedCredentialMaterialWriteError } from "./credentials/ManagedCredentialMaterialWriteError";
 export { ManagedMaterialFetchError } from "./credentials/ManagedMaterialFetchError";
-export type { IWorkspaceFileStorage, WorkspaceFileMetadata } from "./contracts/workspaceFileTypes";
-export { WorkspaceFileNotFoundError, WorkspaceFileStorageToken } from "./contracts/workspaceFileTypes";
+export type {
+  IWorkspaceFileStorage,
+  IWorkspaceFileRegistrar,
+  WorkspaceFileMetadata,
+} from "./contracts/workspaceFileTypes";
+export {
+  WorkspaceFileNotFoundError,
+  WorkspaceFileStorageToken,
+  WorkspaceFileRegistrarToken,
+} from "./contracts/workspaceFileTypes";

package/src/workflow/dsl/ChainCursorResolver.ts

@@ -19,6 +19,7 @@ import type {
   BranchStepsArg,
   StepSequenceOutput,
 } from "./workflowBuilderTypes";
+import { mergeForward } from "./workflowBuilderTypes";
 
 type ChainCursorEndpoint = Readonly<{ node: NodeRef; output: OutputPortKey; inputPortHint?: InputPortKey }>;
 
@@ -56,6 +57,18 @@ export class ChainCursor<TCurrentJson> {
     ]);
   }
 
+  /**
+   * Append a step whose output is MERGED onto `item.json` (shallow, output-wins) instead of
+   * replacing it — so earlier fields (e.g. trigger metadata) survive a transform/OCR/extraction
+   * node. Use for any node in a pipeline where you need data from before it.
+   */
+  thenMerge<TOutputJson, TConfig extends RunnableNodeConfig<TCurrentJson, TOutputJson>>(
+    config: TConfig,
+  ): ChainCursor<TCurrentJson & RunnableNodeOutputJson<TConfig>> {
+    mergeForward(config);
+    return this.then(config) as unknown as ChainCursor<TCurrentJson & RunnableNodeOutputJson<TConfig>>;
+  }
+
   thenIntoInputHints<TOutputJson, TConfig extends RunnableNodeConfig<any, TOutputJson>>(
     config: TConfig,
   ): ChainCursor<RunnableNodeOutputJson<TConfig>> {

package/src/workflow/dsl/WhenBuilder.ts

@@ -1,13 +1,33 @@
-import type { NodeId, NodeRef, OutputPortKey, UpstreamRefPlaceholder, WorkflowDefinition } from "../../types";
+import type {
+  InputPortKey,
+  NodeId,
+  NodeRef,
+  OutputPortKey,
+  RunnableNodeConfig,
+  RunnableNodeOutputJson,
+  UpstreamRefPlaceholder,
+  WorkflowDefinition,
+} from "../../types";
 
+import type { DefinedNodeCredentialBindings } from "../../authoring/defineNode.types";
+import type { DefinedHumanApprovalNode, HumanApprovalOutputJson } from "../../authoring/defineHumanApprovalNode.types";
 import { WorkflowBuilder } from "./WorkflowBuilder";
+import { ChainCursor } from "./ChainCursorResolver";
 import type { AnyRunnableNodeConfig, BooleanWhenOverloads, ValidStepSequence } from "./workflowBuilderTypes";
 
+/** Structurally identical to ChainCursorResolver's (unexported) ChainCursorEndpoint. */
+type WhenEndpoint = Readonly<{ node: NodeRef; output: OutputPortKey; inputPortHint?: InputPortKey }>;
+
 export class WhenBuilder<TCurrentJson> {
+  /** Tail endpoint of the arm this builder added (set by addBranch). */
+  private armEndpoint: WhenEndpoint | undefined;
+
   constructor(
     private readonly wf: WorkflowBuilder,
     private readonly from: NodeRef,
     private readonly branchPort: OutputPortKey,
+    /** Tails of arms added by earlier `.when(...)` calls in this chain. */
+    private readonly priorEndpoints: ReadonlyArray<WhenEndpoint> = [],
   ) {}
 
   addBranch<TSteps extends ReadonlyArray<AnyRunnableNodeConfig>>(
@@ -36,6 +56,12 @@ export class WhenBuilder<TCurrentJson> {
       });
     }
 
+    // An empty arm rejoins straight from the `from` node's branch port (mirrors the
+    // object-form `buildBranch` returning `{ end: cursor, endOutput: port }`).
+    this.armEndpoint = prev
+      ? { node: prev, output: "main", inputPortHint: this.branchPort }
+      : { node: this.from, output: this.branchPort, inputPortHint: this.branchPort };
+
     return this;
   }
 
@@ -46,12 +72,50 @@ export class WhenBuilder<TCurrentJson> {
   ): WhenBuilder<TCurrentJson> => {
     const list = Array.isArray(steps) ? steps : [steps, ...more];
     const port: OutputPortKey = branch ? "true" : "false";
-    const b = new WhenBuilder<TCurrentJson>(this.wf, this.from, port);
+    const b = new WhenBuilder<TCurrentJson>(this.wf, this.from, port, this.accumulatedEndpoints);
     b.addBranch(list);
     return b;
   };
 
+  /**
+   * Continue the trunk after a boolean `.when(...)` branch chain, auto-merging EVERY branch
+   * tail accumulated across the chain into the next node — the same fan-in the object form
+   * produces. Typed as `ChainCursor<TCurrentJson>` (the pre-branch item type): boolean arms
+   * carry no output guard so the merged item type is underdetermined — use the object form
+   * `.when({ true: [...], false: [...] })` when you need a precise merged type inline.
+   */
+  then<TOutputJson, TConfig extends RunnableNodeConfig<TCurrentJson, TOutputJson>>(
+    config: TConfig,
+  ): ChainCursor<RunnableNodeOutputJson<TConfig>> {
+    return this.toCursor().then(config);
+  }
+
+  /**
+   * Chainable human-approval step after a boolean `.when(...)` branch chain — merges every
+   * branch tail into the approval node. Mirrors `ChainCursor.humanApproval`.
+   */
+  humanApproval<
+    TKey extends string,
+    TConfig extends Record<string, unknown>,
+    TBindings extends DefinedNodeCredentialBindings | undefined = undefined,
+  >(
+    node: DefinedHumanApprovalNode<TKey, TConfig, TCurrentJson & Record<string, unknown>, TBindings>,
+    config: TConfig,
+    metadata?: { name?: string; nodeId?: string },
+  ): ChainCursor<HumanApprovalOutputJson<TCurrentJson & Record<string, unknown>>> {
+    return this.toCursor().humanApproval(node, config, metadata);
+  }
+
   build(): WorkflowDefinition {
     return this.wf.build();
   }
+
+  /** Endpoints of every arm added so far in this chain (prior arms + this one). */
+  private get accumulatedEndpoints(): ReadonlyArray<WhenEndpoint> {
+    return this.armEndpoint ? [...this.priorEndpoints, this.armEndpoint] : this.priorEndpoints;
+  }
+
+  private toCursor(): ChainCursor<TCurrentJson> {
+    return new ChainCursor<TCurrentJson>(this.wf, this.accumulatedEndpoints);
+  }
 }

package/src/workflow/dsl/workflowBuilderTypes.ts

@@ -1,5 +1,34 @@
 import type { RunnableNodeConfig, RunnableNodeOutputJson, TriggerNodeConfig } from "../../types";
 
+/**
+ * Flags a node's config so its output is MERGED onto `item.json` (shallow, output-wins) instead of
+ * replacing it — the config-level twin of {@link ChainCursor.thenMerge}.
+ *
+ * Unlike `.thenMerge` (a cursor method that only works on the trunk), `mergeForward` operates on a
+ * bare config, so it is usable in ANY position — including inside a `.when({ true: [...] })` branch
+ * arm, where the steps are a flat array of configs (not a cursor). Wrap a payload-REPLACING node
+ * (e.g. an extractor) in `mergeForward(node.create(...))` so prior fields survive into the next step.
+ *
+ * The OUTPUT type becomes `TIn & TOut` (the intersection), mirroring `.thenMerge`'s return type at
+ * the config level — so the next step in the branch array sees both the prior fields and the node's
+ * output. The INPUT type stays `TIn` (the node still receives the pre-merge item).
+ *
+ * @example
+ * ```ts
+ * workflow
+ *   .trigger(...)
+ *   .when({
+ *     true: [mergeForward(extractor.create(...))], // output merges onto item.json; { a } survives
+ *     false: [...],
+ *   })
+ *   .build();
+ * ```
+ */
+export function mergeForward<TIn, TOut>(config: RunnableNodeConfig<TIn, TOut>): RunnableNodeConfig<TIn, TIn & TOut> {
+  (config as { mergeJson?: boolean }).mergeJson = true;
+  return config as unknown as RunnableNodeConfig<TIn, TIn & TOut>;
+}
+
 export type AnyRunnableNodeConfig = RunnableNodeConfig<any, any>;
 
 export type AnyTriggerNodeConfig = TriggerNodeConfig<any>;

package/src/workflowSnapshots/WorkflowSnapshotCodec.ts

@@ -64,6 +64,7 @@ export class WorkflowSnapshotCodec {
         name: config.name,
         id: config.id,
         icon: config.icon,
+        description: config.description,
         execution: config.execution,
       };
       this.injectTokenIds(fallback, config as unknown as Record<string, unknown>);