@codemation/node-example 0.0.43 → 0.0.45

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # @codemation/node-example
 
+## 0.0.45
+
+### Patch Changes
+
+- Updated dependencies [[`60f23a3`](https://github.com/MadeRelevant/codemation/commit/60f23a37660cdda34e3d61acca8b2bf581a9db0e), [`a5457bb`](https://github.com/MadeRelevant/codemation/commit/a5457bb58edafec01e85cdcf6d30f9ca54521e27), [`510e0d8`](https://github.com/MadeRelevant/codemation/commit/510e0d8a5f137a4fe10f43cbf46e40d05fea4977), [`d5f49f7`](https://github.com/MadeRelevant/codemation/commit/d5f49f7f80deafc109dbc29f16ff0d571ee8591a), [`364507a`](https://github.com/MadeRelevant/codemation/commit/364507a9fba45fd66cb208d5a41ee1f3bdc68311), [`0dc8a9d`](https://github.com/MadeRelevant/codemation/commit/0dc8a9def376e4cd1821f3b92b0f887720e0c842), [`3facadf`](https://github.com/MadeRelevant/codemation/commit/3facadf3bc09d21f33e698213a521fb64168d5dd), [`c08cf33`](https://github.com/MadeRelevant/codemation/commit/c08cf33ead44fec64d3d43b9294fccfdf6674156), [`597fa8f`](https://github.com/MadeRelevant/codemation/commit/597fa8f697300d8d861a02c11e9819892f7947fa), [`b15f8c6`](https://github.com/MadeRelevant/codemation/commit/b15f8c68125e3ec3082bab8d79414871f942e409), [`bfdd759`](https://github.com/MadeRelevant/codemation/commit/bfdd7590b4903676b223c2f302b9bcd0f4a4583c), [`0a681b3`](https://github.com/MadeRelevant/codemation/commit/0a681b357afd7b15ba3925788c732fd439d8e6b0), [`ab5185a`](https://github.com/MadeRelevant/codemation/commit/ab5185a839118868eda1aab42b82f7a921037f37), [`fd188a2`](https://github.com/MadeRelevant/codemation/commit/fd188a2bac65c86dd62cf2f540034769c5bc0ac7), [`f2aa0c4`](https://github.com/MadeRelevant/codemation/commit/f2aa0c42b2f9d2e9eb7bc4f3393f74342f7ef460), [`cf2b146`](https://github.com/MadeRelevant/codemation/commit/cf2b146b452317e1ccaa1dfeaaa1a0e153181e30)]:
+  - @codemation/core@0.15.0
+
+## 0.0.44
+
+### Patch Changes
+
+- Updated dependencies [[`675260a`](https://github.com/MadeRelevant/codemation/commit/675260aa7a30c55a34b5a6107ad2222937f4a769), [`13f9f11`](https://github.com/MadeRelevant/codemation/commit/13f9f11454855f44cd0849ea7e8f0c60f4a28964), [`675260a`](https://github.com/MadeRelevant/codemation/commit/675260aa7a30c55a34b5a6107ad2222937f4a769), [`675260a`](https://github.com/MadeRelevant/codemation/commit/675260aa7a30c55a34b5a6107ad2222937f4a769), [`0881b46`](https://github.com/MadeRelevant/codemation/commit/0881b4676d2db29f36415d9b47709128d4c15e0e)]:
+  - @codemation/core@0.14.0
+
 ## 0.0.43
 
 ### Patch Changes

package/dist/index.d.cts

@@ -3,11 +3,6 @@ import { InjectionToken as TypeToken } from "tsyringe";
 import { ReadableStream } from "node:stream/web";
 
 //#region ../core/src/contracts/baseTypes.d.ts
-/**
- * Minimal base types that have no dependencies on other contracts.
- * Used by credentialTypes, workflowTypes, and other contract layers
- * to avoid circular dependencies.
- */
 type WorkflowId = string;
 type NodeId = string;
 type OutputPortKey = string;
@@ -92,13 +87,6 @@ interface TelemetrySpanScope extends TelemetryScope {
   readonly traceId: string;
   readonly spanId: string;
   end(args?: TelemetrySpanEnd): Promise<void> | void;
-  /**
-   * Lift this span into a {@link NodeExecutionTelemetry} scoped to a different (nodeId, activationId).
-   * Children created via the returned telemetry's `startChildSpan` get this span as their parent.
-   *
-   * Used at the sub-agent boundary so that nested runtime telemetry parents under the agent.tool.call
-   * span instead of the orchestrator's node-level span.
-   */
   asNodeTelemetry(args: Readonly<{
     nodeId: NodeId;
     activationId: NodeActivationId;
@@ -117,30 +105,21 @@ interface ExecutionTelemetry extends TelemetryScope {
 }
 //#endregion
 //#region ../core/src/contracts/retryPolicySpec.types.d.ts
-/**
- * In-process retry policy for runnable nodes. Serialized configs use the same
- * `kind` discriminator (`JSON.stringify` / persisted workflows).
- *
- * `maxAttempts` is the total number of tries including the first (e.g. 3 means up to 2 delays after failures).
- */
 type RetryPolicySpec = NoneRetryPolicySpec | FixedRetryPolicySpec | ExponentialRetryPolicySpec;
 interface NoneRetryPolicySpec {
   readonly kind: "none";
 }
 interface FixedRetryPolicySpec {
   readonly kind: "fixed";
-  /** Total attempts including the first execution. Must be >= 1. */
   readonly maxAttempts: number;
   readonly delayMs: number;
 }
 interface ExponentialRetryPolicySpec {
   readonly kind: "exponential";
-  /** Total attempts including the first execution. Must be >= 1. */
   readonly maxAttempts: number;
   readonly initialDelayMs: number;
   readonly multiplier: number;
   readonly maxDelayMs?: number;
-  /** When true, each delay is multiplied by a random factor in [1, 1.2). */
   readonly jitter?: boolean;
 }
 //#endregion
@@ -156,38 +135,22 @@ type CredentialRequirement = Readonly<{
 }>;
 //#endregion
 //#region ../core/src/contracts/collectionTypes.d.ts
-/**
- * Represents a typed store for a single collection.
- * All rows include auto-managed id, created_at, and updated_at fields.
- */
 interface CollectionStore<TRow extends Record<string, unknown> = Record<string, unknown>> {
-  /**
-   * Insert a new row. id, created_at, and updated_at are auto-populated.
-   */
   insert(row: TRow): Promise<TRow & {
     id: string;
     created_at: Date;
     updated_at: Date;
   }>;
-  /**
-   * Get a single row by id.
-   */
   get(id: string): Promise<(TRow & {
     id: string;
     created_at: Date;
     updated_at: Date;
   }) | null>;
-  /**
-   * Find a single row matching the provided filter.
-   */
   findOne(filter: Partial<TRow>): Promise<(TRow & {
     id: string;
     created_at: Date;
     updated_at: Date;
   }) | null>;
-  /**
-   * List rows with optional pagination and filtering.
-   */
   list(opts?: {
     limit?: number;
     offset?: number;
@@ -200,41 +163,21 @@ interface CollectionStore<TRow extends Record<string, unknown> = Record<string,
     }>;
     total: number;
   }>;
-  /**
-   * Update a row by id with partial data.
-   */
   update(id: string, patch: Partial<TRow>): Promise<TRow & {
     id: string;
     created_at: Date;
     updated_at: Date;
   }>;
-  /**
-   * Delete a row by id. Hard delete only (no soft delete).
-   */
   delete(id: string): Promise<{
     deleted: boolean;
   }>;
 }
-/**
- * Runtime collections context: keyed by collection name.
- */
 type CollectionsContext = Readonly<Record<string, CollectionStore>>;
 //#endregion
 //#region ../core/src/contracts/runTypes.d.ts
-/**
- * Test-suite linkage for a run. When set, this run was started by a TestSuiteOrchestrator
- * as one test case inside a TestSuiteRun. The `IsTestRun` node and host-side persisters key
- * off the presence of this field. Subworkflow runs inherit it from their parent run.
- */
 interface RunTestContext {
   readonly testSuiteRunId: string;
   readonly testCaseIndex: number;
-  /**
-   * Optional human-friendly label for this test case (e.g. an email subject when fixtures
-   * are loaded from a mailbox). Resolved per item by `TestTrigger.caseLabel(item)` if set,
-   * persisted on `Run.test_case_label` so the Tests-tab tree-table can show "RFQ for batch 14"
-   * instead of "run_1777755971399_bbb86beac1396".
-   */
   readonly testCaseLabel?: string;
 }
 type NodeInputsByPort = Readonly<Record<InputPortKey, Items>>;
@@ -245,9 +188,7 @@ interface NodeExecutionError {
   stack?: string;
   details?: JsonValue;
 }
-/** Stable id for a single connection invocation row in {@link ConnectionInvocationRecord}. */
 type ConnectionInvocationId = string;
-/** Arguments for appending a {@link ConnectionInvocationRecord} (engine fills run/workflow ids and timestamps). */
 type ConnectionInvocationAppendArgs = Readonly<{
   invocationId: ConnectionInvocationId;
   connectionNodeId: NodeId;
@@ -284,76 +225,31 @@ interface NodeConfigBase {
   readonly name?: string;
   readonly id?: NodeId;
   readonly icon?: string;
+  readonly description?: string;
   readonly execution?: Readonly<{
     hint?: "local" | "worker";
     queue?: string;
   }>;
-  /** In-process execute retries (runnable nodes). Triggers typically omit this. */
   readonly retryPolicy?: RetryPolicySpec;
-  /** Recover from execute failures; return outputs to continue, or rethrow to fail the node. */
   readonly nodeErrorHandler?: NodeErrorHandlerSpec;
-  /**
-   * When true, edges carrying zero items on an output port still schedule single-input downstream nodes.
-   * Decided from the **source** node that produced the (empty) output. Default (false/undefined): empty
-   * main batches skip downstream execution and propagate the empty path.
-   */
   readonly continueWhenEmptyOutput?: boolean;
-  /**
-   * Declared I/O port names for canvas authoring (unioned with ports inferred from edges).
-   * Use for dynamic routers (Switch) and future error ports.
-   */
   readonly declaredOutputPorts?: ReadonlyArray<OutputPortKey>;
   readonly declaredInputPorts?: ReadonlyArray<InputPortKey>;
   getCredentialRequirements?(): ReadonlyArray<CredentialRequirement>;
-  /**
-   * Marker: this node emits {@link import("./assertionTypes").AssertionResult}-shaped items on its
-   * `main` port. The TestSuiteOrchestrator (and host-side TestAssertionPersister) listen for
-   * `nodeCompleted` events from nodes with this flag set, and persist their output items as
-   * TestAssertion records (only when the run carries a `testContext`). Set on assertion node
-   * configs (e.g. `AssertionNodeConfig`, `StringEqualsAssertionNodeConfig`).
-   */
   readonly emitsAssertions?: true;
-  /**
-   * Static configuration summary surfaced in the workflow inspector — the design-time
-   * "what does this node do" panel that renders before any run telemetry exists.
-   *
-   * Return 2–6 short label/value pairs derived from this config (method + url for an HTTP
-   * call, model + tool list for an agent, schedule + timezone for a cron trigger, etc.).
-   * Values are truncated by the UI; aim for one line each. Return `undefined` to opt out
-   * — the inspector hides the section when no rows are produced.
-   *
-   * Implement on the config class instance so the function can read sibling config fields.
-   * `defineNode({ inspectorSummary })` plumbs through to this.
-   */
   inspectorSummary?(): ReadonlyArray<NodeInspectorSummaryRow> | undefined;
 }
-/**
- * One row of a node's static configuration summary. See {@link NodeConfigBase.inspectorSummary}.
- */
 interface NodeInspectorSummaryRow {
   readonly label: string;
   readonly value: string;
 }
 declare const runnableNodeInputType: unique symbol;
 declare const runnableNodeOutputType: unique symbol;
-/**
- * Runnable node: **`TInputJson`** is what **`inputSchema`** validates on **`item.json`** (the wire payload).
- * **`TOutputJson`** is emitted `item.json` on outputs.
- */
 interface RunnableNodeConfig<TInputJson$1 = unknown, TOutputJson$1 = unknown> extends NodeConfigBase {
   readonly kind: "node";
   readonly [runnableNodeInputType]?: TInputJson$1;
   readonly [runnableNodeOutputType]?: TOutputJson$1;
-  /**
-   * Optional Zod input contract for {@link RunnableNode} when not set on the node class.
-   * Resolution order: node instance `inputSchema`, then config `inputSchema`, then `z.unknown()`.
-   */
   readonly inputSchema?: ZodType<TInputJson$1>;
-  /**
-   * When an activation receives **zero** input items, the engine normally runs `execute` zero times.
-   * Set to **`runOnce`** to run `execute` once with an empty `items` batch (and a synthetic wire item for schema parsing).
-   * Used by batch-style callback nodes (built-in `Callback`) so `callback([], ctx)` still runs.
-   */
   readonly emptyBatchExecution?: "skip" | "runOnce";
 }
 type PairedItemRef = Readonly<{
@@ -388,27 +284,14 @@ type Items<TJson = unknown> = ReadonlyArray<Item<TJson>>;
 type NodeOutputs = Partial<Record<OutputPortKey, Items>>;
 type RunId = string;
 type NodeActivationId = string;
-/**
- * One per-item iteration of a runnable node's execute loop. Refines `NodeActivationId` for
- * per-item connection invocations and telemetry. Undefined when the executing node is a batch
- * node or trigger that does not iterate items.
- */
 type NodeIterationId = string;
 interface ParentExecutionRef {
   runId: RunId;
   workflowId: WorkflowId;
   nodeId: NodeId;
-  /** Subworkflow depth of the **spawning** run (0 = root). Passed when starting a child run. */
   subworkflowDepth?: number;
-  /** Effective max node activations from the parent run (propagated to child policy merge). */
   engineMaxNodeActivations?: number;
-  /** Effective max subworkflow depth from the parent run (propagated to child policy merge). */
   engineMaxSubworkflowDepth?: number;
-  /**
-   * Test-suite linkage inherited by the child subworkflow run. Set by whichever node
-   * spawns the subworkflow when its own `ctx.testContext` is present, so assertions
-   * emitted inside a subworkflow land under the correct parent test case.
-   */
   testContext?: RunTestContext;
 }
 interface RunDataSnapshot {
@@ -429,36 +312,19 @@ interface NodeErrorHandler {
 type NodeErrorHandlerSpec = TypeToken<NodeErrorHandler> | NodeErrorHandler;
 //#endregion
 //#region ../core/src/contracts/runtimeTypes.d.ts
-/** Opaque unique identifier for a single HumanTask instance. */
 type HumanTaskId = string;
-/**
- * Minimal handle handed to the `deliver` callback so it can route to the correct
- * inbox channel.
- */
 interface HumanTaskHandle {
   readonly taskId: HumanTaskId;
   readonly runId: string;
   readonly nodeId: string;
   readonly expiresAt: Date;
-  /** TODO: real signed URL; placeholder empty string for now. */
   readonly resumeUrl: string;
-  /**
-   * Arbitrary JSON metadata copied from `SuspensionRequest.request.metadata` at suspension time.
-   * Used by the agent runtime to round-trip the `agentCheckpoint` back to the
-   * resumed node via `ctx.resumeContext.task.metadata`.
-   */
   readonly metadata?: Readonly<Record<string, JsonValue>>;
 }
-/** Identity of the person who made a decision on the task. */
 interface HumanTaskActor {
   readonly actorId: string;
   readonly displayName?: string;
 }
-/**
- * Resume context injected into `NodeExecutionContext` when the engine re-activates
- * a previously suspended node. `defineHumanApprovalNode` wraps this with parsed
- * `TDecision`; at the engine layer `decision.value` is `unknown`.
- */
 interface ResumeContext {
   readonly decision: Readonly<{
     kind: "decided";
@@ -499,11 +365,6 @@ interface NodeExecutionStatePublisher {
     error: Error;
   }): Promise<void>;
   appendConnectionInvocation(args: ConnectionInvocationAppendArgs): Promise<void>;
-  /**
-   * Annotates the current snapshot for `nodeId` with the id of the child run spawned by a
-   * SubWorkflow invocation. Called from `SubWorkflowNode.execute` after `runById` resolves.
-   * The engine's subsequent `markCompleted` call preserves the value via `previous.childRunId`.
-   */
   setChildRunId?(args: {
     nodeId: NodeId;
     childRunId: RunId;
@@ -531,32 +392,16 @@ interface ExecutionBinaryService {
     activationId: NodeActivationId;
   }): NodeBinaryAttachmentService;
   openReadStream(attachment: BinaryAttachment): Promise<BinaryStorageReadResult | undefined>;
-  /**
-   * Reads all bytes from the attachment into a contiguous `Uint8Array`.
-   * Checks `attachment.size` against `maxBytes` *before* any allocation; throws a bounded-read
-   * error when exceeded (no OOM). Throws if the stream is unavailable or the byte count mismatches.
-   */
   getBytes(attachment: BinaryAttachment, maxBytes?: number): Promise<Uint8Array>;
-  /**
-   * Reads the attachment and decodes the bytes as UTF-8 text.
-   * Subject to the same bounded-read safety as `getBytes`.
-   */
   getText(attachment: BinaryAttachment, maxBytes?: number): Promise<string>;
-  /**
-   * Reads the attachment, decodes as UTF-8 text, and parses as JSON.
-   * Throws a clear error on invalid JSON. Subject to the same bounded-read safety.
-   */
   getJson<T = unknown>(attachment: BinaryAttachment, maxBytes?: number): Promise<T>;
 }
 interface ExecutionContext {
   runId: RunId;
   workflowId: WorkflowId;
   parent?: ParentExecutionRef;
-  /** This run's subworkflow depth (0 = root). */
   subworkflowDepth: number;
-  /** Effective activation budget cap for this run (after policy merge). */
   engineMaxNodeActivations: number;
-  /** Effective subworkflow nesting cap for this run (after policy merge). */
   engineMaxSubworkflowDepth: number;
   now: () => Date;
   data: RunDataSnapshot;
@@ -564,28 +409,11 @@ interface ExecutionContext {
   telemetry: ExecutionTelemetry;
   binary: ExecutionBinaryService;
   getCredential<TSession = unknown>(slotKey: string): Promise<TSession>;
-  /** Per-item iteration id, set by {@link NodeExecutor} on the ctx passed into runnable `execute`. */
   iterationId?: NodeIterationId;
-  /** Item index (0-based) within the current activation's batch; set alongside {@link iterationId}. */
   itemIndex?: number;
-  /** When set, this ctx is executing inside a sub-agent triggered by the named parent invocation. */
   parentInvocationId?: ConnectionInvocationId;
-  /**
-   * Present iff the run was started by a TestSuiteOrchestrator. The {@link IsTestRunNode}
-   * branches on this; assertion-emitting nodes use it to decide whether to record results.
-   */
   testContext?: RunTestContext;
-  /**
-   * Collections registered in the codemation config, keyed by collection name.
-   */
   readonly collections?: CollectionsContext;
-  /**
-   * Resolve a DI token from the host container.
-   * Allows nodes to reach host-side services (e.g. `InboxChannelResolverToken`)
-   * without importing host code. Wired by `DefaultExecutionContextFactory`; throws
-   * a clear error when no resolver is configured (e.g. in unit tests that don't
-   * set up the full container).
-   */
   resolve<T>(token: TypeToken<T>): T;
 }
 interface NodeExecutionContext<TConfig extends NodeConfigBase = NodeConfigBase> extends ExecutionContext {
@@ -594,18 +422,8 @@ interface NodeExecutionContext<TConfig extends NodeConfigBase = NodeConfigBase>
   config: TConfig;
   telemetry: NodeExecutionTelemetry;
   binary: NodeBinaryAttachmentService;
-  /**
-   * Present when this node activation is a HITL resume.
-   * The node checks `ctx.resumeContext !== undefined` and takes the resume branch.
-   */
   resumeContext?: ResumeContext;
 }
-/**
- * Per-item runnable node: return JSON, an array to fan-out on `main`, an explicit `Item`, 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). Transform helpers may opt into binary preservation, while routers and
- * pass-through nodes should return explicit items when they need to preserve full item state.
- */
 interface RunnableNodeExecuteArgs<TConfig extends RunnableNodeConfig<any, any> = RunnableNodeConfig<any, any>, TInputJson$1 = unknown> {
   readonly input: TInputJson$1;
   readonly item: Item;
@@ -615,14 +433,7 @@ interface RunnableNodeExecuteArgs<TConfig extends RunnableNodeConfig<any, any> =
 }
 interface RunnableNode<TConfig extends RunnableNodeConfig<any, any> = RunnableNodeConfig<any, any>, TInputJson$1 = unknown, _TOutputJson = unknown> {
   readonly kind: "node";
-  /**
-   * 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$1>;
   execute(args: RunnableNodeExecuteArgs<TConfig, TInputJson$1>): Promise<unknown> | unknown;
 }

package/dist/index.d.ts

@@ -3,11 +3,6 @@ import { InjectionToken as TypeToken } from "tsyringe";
 import { ReadableStream } from "node:stream/web";
 
 //#region ../core/src/contracts/baseTypes.d.ts
-/**
- * Minimal base types that have no dependencies on other contracts.
- * Used by credentialTypes, workflowTypes, and other contract layers
- * to avoid circular dependencies.
- */
 type WorkflowId = string;
 type NodeId = string;
 type OutputPortKey = string;
@@ -92,13 +87,6 @@ interface TelemetrySpanScope extends TelemetryScope {
   readonly traceId: string;
   readonly spanId: string;
   end(args?: TelemetrySpanEnd): Promise<void> | void;
-  /**
-   * Lift this span into a {@link NodeExecutionTelemetry} scoped to a different (nodeId, activationId).
-   * Children created via the returned telemetry's `startChildSpan` get this span as their parent.
-   *
-   * Used at the sub-agent boundary so that nested runtime telemetry parents under the agent.tool.call
-   * span instead of the orchestrator's node-level span.
-   */
   asNodeTelemetry(args: Readonly<{
     nodeId: NodeId;
     activationId: NodeActivationId;
@@ -117,30 +105,21 @@ interface ExecutionTelemetry extends TelemetryScope {
 }
 //#endregion
 //#region ../core/src/contracts/retryPolicySpec.types.d.ts
-/**
- * In-process retry policy for runnable nodes. Serialized configs use the same
- * `kind` discriminator (`JSON.stringify` / persisted workflows).
- *
- * `maxAttempts` is the total number of tries including the first (e.g. 3 means up to 2 delays after failures).
- */
 type RetryPolicySpec = NoneRetryPolicySpec | FixedRetryPolicySpec | ExponentialRetryPolicySpec;
 interface NoneRetryPolicySpec {
   readonly kind: "none";
 }
 interface FixedRetryPolicySpec {
   readonly kind: "fixed";
-  /** Total attempts including the first execution. Must be >= 1. */
   readonly maxAttempts: number;
   readonly delayMs: number;
 }
 interface ExponentialRetryPolicySpec {
   readonly kind: "exponential";
-  /** Total attempts including the first execution. Must be >= 1. */
   readonly maxAttempts: number;
   readonly initialDelayMs: number;
   readonly multiplier: number;
   readonly maxDelayMs?: number;
-  /** When true, each delay is multiplied by a random factor in [1, 1.2). */
   readonly jitter?: boolean;
 }
 //#endregion
@@ -156,38 +135,22 @@ type CredentialRequirement = Readonly<{
 }>;
 //#endregion
 //#region ../core/src/contracts/collectionTypes.d.ts
-/**
- * Represents a typed store for a single collection.
- * All rows include auto-managed id, created_at, and updated_at fields.
- */
 interface CollectionStore<TRow extends Record<string, unknown> = Record<string, unknown>> {
-  /**
-   * Insert a new row. id, created_at, and updated_at are auto-populated.
-   */
   insert(row: TRow): Promise<TRow & {
     id: string;
     created_at: Date;
     updated_at: Date;
   }>;
-  /**
-   * Get a single row by id.
-   */
   get(id: string): Promise<(TRow & {
     id: string;
     created_at: Date;
     updated_at: Date;
   }) | null>;
-  /**
-   * Find a single row matching the provided filter.
-   */
   findOne(filter: Partial<TRow>): Promise<(TRow & {
     id: string;
     created_at: Date;
     updated_at: Date;
   }) | null>;
-  /**
-   * List rows with optional pagination and filtering.
-   */
   list(opts?: {
     limit?: number;
     offset?: number;
@@ -200,41 +163,21 @@ interface CollectionStore<TRow extends Record<string, unknown> = Record<string,
     }>;
     total: number;
   }>;
-  /**
-   * Update a row by id with partial data.
-   */
   update(id: string, patch: Partial<TRow>): Promise<TRow & {
     id: string;
     created_at: Date;
     updated_at: Date;
   }>;
-  /**
-   * Delete a row by id. Hard delete only (no soft delete).
-   */
   delete(id: string): Promise<{
     deleted: boolean;
   }>;
 }
-/**
- * Runtime collections context: keyed by collection name.
- */
 type CollectionsContext = Readonly<Record<string, CollectionStore>>;
 //#endregion
 //#region ../core/src/contracts/runTypes.d.ts
-/**
- * Test-suite linkage for a run. When set, this run was started by a TestSuiteOrchestrator
- * as one test case inside a TestSuiteRun. The `IsTestRun` node and host-side persisters key
- * off the presence of this field. Subworkflow runs inherit it from their parent run.
- */
 interface RunTestContext {
   readonly testSuiteRunId: string;
   readonly testCaseIndex: number;
-  /**
-   * Optional human-friendly label for this test case (e.g. an email subject when fixtures
-   * are loaded from a mailbox). Resolved per item by `TestTrigger.caseLabel(item)` if set,
-   * persisted on `Run.test_case_label` so the Tests-tab tree-table can show "RFQ for batch 14"
-   * instead of "run_1777755971399_bbb86beac1396".
-   */
   readonly testCaseLabel?: string;
 }
 type NodeInputsByPort = Readonly<Record<InputPortKey, Items>>;
@@ -245,9 +188,7 @@ interface NodeExecutionError {
   stack?: string;
   details?: JsonValue;
 }
-/** Stable id for a single connection invocation row in {@link ConnectionInvocationRecord}. */
 type ConnectionInvocationId = string;
-/** Arguments for appending a {@link ConnectionInvocationRecord} (engine fills run/workflow ids and timestamps). */
 type ConnectionInvocationAppendArgs = Readonly<{
   invocationId: ConnectionInvocationId;
   connectionNodeId: NodeId;
@@ -284,76 +225,31 @@ interface NodeConfigBase {
   readonly name?: string;
   readonly id?: NodeId;
   readonly icon?: string;
+  readonly description?: string;
   readonly execution?: Readonly<{
     hint?: "local" | "worker";
     queue?: string;
   }>;
-  /** In-process execute retries (runnable nodes). Triggers typically omit this. */
   readonly retryPolicy?: RetryPolicySpec;
-  /** Recover from execute failures; return outputs to continue, or rethrow to fail the node. */
   readonly nodeErrorHandler?: NodeErrorHandlerSpec;
-  /**
-   * When true, edges carrying zero items on an output port still schedule single-input downstream nodes.
-   * Decided from the **source** node that produced the (empty) output. Default (false/undefined): empty
-   * main batches skip downstream execution and propagate the empty path.
-   */
   readonly continueWhenEmptyOutput?: boolean;
-  /**
-   * Declared I/O port names for canvas authoring (unioned with ports inferred from edges).
-   * Use for dynamic routers (Switch) and future error ports.
-   */
   readonly declaredOutputPorts?: ReadonlyArray<OutputPortKey>;
   readonly declaredInputPorts?: ReadonlyArray<InputPortKey>;
   getCredentialRequirements?(): ReadonlyArray<CredentialRequirement>;
-  /**
-   * Marker: this node emits {@link import("./assertionTypes").AssertionResult}-shaped items on its
-   * `main` port. The TestSuiteOrchestrator (and host-side TestAssertionPersister) listen for
-   * `nodeCompleted` events from nodes with this flag set, and persist their output items as
-   * TestAssertion records (only when the run carries a `testContext`). Set on assertion node
-   * configs (e.g. `AssertionNodeConfig`, `StringEqualsAssertionNodeConfig`).
-   */
   readonly emitsAssertions?: true;
-  /**
-   * Static configuration summary surfaced in the workflow inspector — the design-time
-   * "what does this node do" panel that renders before any run telemetry exists.
-   *
-   * Return 2–6 short label/value pairs derived from this config (method + url for an HTTP
-   * call, model + tool list for an agent, schedule + timezone for a cron trigger, etc.).
-   * Values are truncated by the UI; aim for one line each. Return `undefined` to opt out
-   * — the inspector hides the section when no rows are produced.
-   *
-   * Implement on the config class instance so the function can read sibling config fields.
-   * `defineNode({ inspectorSummary })` plumbs through to this.
-   */
   inspectorSummary?(): ReadonlyArray<NodeInspectorSummaryRow> | undefined;
 }
-/**
- * One row of a node's static configuration summary. See {@link NodeConfigBase.inspectorSummary}.
- */
 interface NodeInspectorSummaryRow {
   readonly label: string;
   readonly value: string;
 }
 declare const runnableNodeInputType: unique symbol;
 declare const runnableNodeOutputType: unique symbol;
-/**
- * Runnable node: **`TInputJson`** is what **`inputSchema`** validates on **`item.json`** (the wire payload).
- * **`TOutputJson`** is emitted `item.json` on outputs.
- */
 interface RunnableNodeConfig<TInputJson$1 = unknown, TOutputJson$1 = unknown> extends NodeConfigBase {
   readonly kind: "node";
   readonly [runnableNodeInputType]?: TInputJson$1;
   readonly [runnableNodeOutputType]?: TOutputJson$1;
-  /**
-   * Optional Zod input contract for {@link RunnableNode} when not set on the node class.
-   * Resolution order: node instance `inputSchema`, then config `inputSchema`, then `z.unknown()`.
-   */
   readonly inputSchema?: ZodType<TInputJson$1>;
-  /**
-   * When an activation receives **zero** input items, the engine normally runs `execute` zero times.
-   * Set to **`runOnce`** to run `execute` once with an empty `items` batch (and a synthetic wire item for schema parsing).
-   * Used by batch-style callback nodes (built-in `Callback`) so `callback([], ctx)` still runs.
-   */
   readonly emptyBatchExecution?: "skip" | "runOnce";
 }
 type PairedItemRef = Readonly<{
@@ -388,27 +284,14 @@ type Items<TJson = unknown> = ReadonlyArray<Item<TJson>>;
 type NodeOutputs = Partial<Record<OutputPortKey, Items>>;
 type RunId = string;
 type NodeActivationId = string;
-/**
- * One per-item iteration of a runnable node's execute loop. Refines `NodeActivationId` for
- * per-item connection invocations and telemetry. Undefined when the executing node is a batch
- * node or trigger that does not iterate items.
- */
 type NodeIterationId = string;
 interface ParentExecutionRef {
   runId: RunId;
   workflowId: WorkflowId;
   nodeId: NodeId;
-  /** Subworkflow depth of the **spawning** run (0 = root). Passed when starting a child run. */
   subworkflowDepth?: number;
-  /** Effective max node activations from the parent run (propagated to child policy merge). */
   engineMaxNodeActivations?: number;
-  /** Effective max subworkflow depth from the parent run (propagated to child policy merge). */
   engineMaxSubworkflowDepth?: number;
-  /**
-   * Test-suite linkage inherited by the child subworkflow run. Set by whichever node
-   * spawns the subworkflow when its own `ctx.testContext` is present, so assertions
-   * emitted inside a subworkflow land under the correct parent test case.
-   */
   testContext?: RunTestContext;
 }
 interface RunDataSnapshot {
@@ -429,36 +312,19 @@ interface NodeErrorHandler {
 type NodeErrorHandlerSpec = TypeToken<NodeErrorHandler> | NodeErrorHandler;
 //#endregion
 //#region ../core/src/contracts/runtimeTypes.d.ts
-/** Opaque unique identifier for a single HumanTask instance. */
 type HumanTaskId = string;
-/**
- * Minimal handle handed to the `deliver` callback so it can route to the correct
- * inbox channel.
- */
 interface HumanTaskHandle {
   readonly taskId: HumanTaskId;
   readonly runId: string;
   readonly nodeId: string;
   readonly expiresAt: Date;
-  /** TODO: real signed URL; placeholder empty string for now. */
   readonly resumeUrl: string;
-  /**
-   * Arbitrary JSON metadata copied from `SuspensionRequest.request.metadata` at suspension time.
-   * Used by the agent runtime to round-trip the `agentCheckpoint` back to the
-   * resumed node via `ctx.resumeContext.task.metadata`.
-   */
   readonly metadata?: Readonly<Record<string, JsonValue>>;
 }
-/** Identity of the person who made a decision on the task. */
 interface HumanTaskActor {
   readonly actorId: string;
   readonly displayName?: string;
 }
-/**
- * Resume context injected into `NodeExecutionContext` when the engine re-activates
- * a previously suspended node. `defineHumanApprovalNode` wraps this with parsed
- * `TDecision`; at the engine layer `decision.value` is `unknown`.
- */
 interface ResumeContext {
   readonly decision: Readonly<{
     kind: "decided";
@@ -499,11 +365,6 @@ interface NodeExecutionStatePublisher {
     error: Error;
   }): Promise<void>;
   appendConnectionInvocation(args: ConnectionInvocationAppendArgs): Promise<void>;
-  /**
-   * Annotates the current snapshot for `nodeId` with the id of the child run spawned by a
-   * SubWorkflow invocation. Called from `SubWorkflowNode.execute` after `runById` resolves.
-   * The engine's subsequent `markCompleted` call preserves the value via `previous.childRunId`.
-   */
   setChildRunId?(args: {
     nodeId: NodeId;
     childRunId: RunId;
@@ -531,32 +392,16 @@ interface ExecutionBinaryService {
     activationId: NodeActivationId;
   }): NodeBinaryAttachmentService;
   openReadStream(attachment: BinaryAttachment): Promise<BinaryStorageReadResult | undefined>;
-  /**
-   * Reads all bytes from the attachment into a contiguous `Uint8Array`.
-   * Checks `attachment.size` against `maxBytes` *before* any allocation; throws a bounded-read
-   * error when exceeded (no OOM). Throws if the stream is unavailable or the byte count mismatches.
-   */
   getBytes(attachment: BinaryAttachment, maxBytes?: number): Promise<Uint8Array>;
-  /**
-   * Reads the attachment and decodes the bytes as UTF-8 text.
-   * Subject to the same bounded-read safety as `getBytes`.
-   */
   getText(attachment: BinaryAttachment, maxBytes?: number): Promise<string>;
-  /**
-   * Reads the attachment, decodes as UTF-8 text, and parses as JSON.
-   * Throws a clear error on invalid JSON. Subject to the same bounded-read safety.
-   */
   getJson<T = unknown>(attachment: BinaryAttachment, maxBytes?: number): Promise<T>;
 }
 interface ExecutionContext {
   runId: RunId;
   workflowId: WorkflowId;
   parent?: ParentExecutionRef;
-  /** This run's subworkflow depth (0 = root). */
   subworkflowDepth: number;
-  /** Effective activation budget cap for this run (after policy merge). */
   engineMaxNodeActivations: number;
-  /** Effective subworkflow nesting cap for this run (after policy merge). */
   engineMaxSubworkflowDepth: number;
   now: () => Date;
   data: RunDataSnapshot;
@@ -564,28 +409,11 @@ interface ExecutionContext {
   telemetry: ExecutionTelemetry;
   binary: ExecutionBinaryService;
   getCredential<TSession = unknown>(slotKey: string): Promise<TSession>;
-  /** Per-item iteration id, set by {@link NodeExecutor} on the ctx passed into runnable `execute`. */
   iterationId?: NodeIterationId;
-  /** Item index (0-based) within the current activation's batch; set alongside {@link iterationId}. */
   itemIndex?: number;
-  /** When set, this ctx is executing inside a sub-agent triggered by the named parent invocation. */
   parentInvocationId?: ConnectionInvocationId;
-  /**
-   * Present iff the run was started by a TestSuiteOrchestrator. The {@link IsTestRunNode}
-   * branches on this; assertion-emitting nodes use it to decide whether to record results.
-   */
   testContext?: RunTestContext;
-  /**
-   * Collections registered in the codemation config, keyed by collection name.
-   */
   readonly collections?: CollectionsContext;
-  /**
-   * Resolve a DI token from the host container.
-   * Allows nodes to reach host-side services (e.g. `InboxChannelResolverToken`)
-   * without importing host code. Wired by `DefaultExecutionContextFactory`; throws
-   * a clear error when no resolver is configured (e.g. in unit tests that don't
-   * set up the full container).
-   */
   resolve<T>(token: TypeToken<T>): T;
 }
 interface NodeExecutionContext<TConfig extends NodeConfigBase = NodeConfigBase> extends ExecutionContext {
@@ -594,18 +422,8 @@ interface NodeExecutionContext<TConfig extends NodeConfigBase = NodeConfigBase>
   config: TConfig;
   telemetry: NodeExecutionTelemetry;
   binary: NodeBinaryAttachmentService;
-  /**
-   * Present when this node activation is a HITL resume.
-   * The node checks `ctx.resumeContext !== undefined` and takes the resume branch.
-   */
   resumeContext?: ResumeContext;
 }
-/**
- * Per-item runnable node: return JSON, an array to fan-out on `main`, an explicit `Item`, 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). Transform helpers may opt into binary preservation, while routers and
- * pass-through nodes should return explicit items when they need to preserve full item state.
- */
 interface RunnableNodeExecuteArgs<TConfig extends RunnableNodeConfig<any, any> = RunnableNodeConfig<any, any>, TInputJson$1 = unknown> {
   readonly input: TInputJson$1;
   readonly item: Item;
@@ -615,14 +433,7 @@ interface RunnableNodeExecuteArgs<TConfig extends RunnableNodeConfig<any, any> =
 }
 interface RunnableNode<TConfig extends RunnableNodeConfig<any, any> = RunnableNodeConfig<any, any>, TInputJson$1 = unknown, _TOutputJson = unknown> {
   readonly kind: "node";
-  /**
-   * 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$1>;
   execute(args: RunnableNodeExecuteArgs<TConfig, TInputJson$1>): Promise<unknown> | unknown;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codemation/node-example",
-  "version": "0.0.43",
+  "version": "0.0.45",
   "publishConfig": {
     "access": "public"
   },
@@ -28,7 +28,7 @@
     }
   },
   "dependencies": {
-    "@codemation/core": "0.13.2"
+    "@codemation/core": "0.15.0"
   },
   "devDependencies": {
     "@types/node": "^25.3.5",