@codemation/core 0.13.2 → 0.15.0

package/src/contracts/itemExpr.ts

@@ -1,8 +1,6 @@
 import type { NodeExecutionContext } from "./runtimeTypes";
 import type { Item, Items, NodeActivationId, NodeId, RunDataSnapshot, RunId, WorkflowId } from "./workflowTypes";
 
-const ITEM_EXPR_BRAND = Symbol.for("codemation.itemExpr");
-
 export type ItemExprResolvedContext = Readonly<{
   runId: RunId;
   workflowId: WorkflowId;
@@ -11,9 +9,6 @@ export type ItemExprResolvedContext = Readonly<{
   data: RunDataSnapshot;
 }>;
 
-/**
- * Context aligned with former {@link ItemInputMapperContext} — use **`data`** to read any completed upstream node.
- */
 export type ItemExprContext = ItemExprResolvedContext;
 
 export type ItemExprArgs<TItemJson = unknown> = Readonly<{
@@ -26,12 +21,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,14 +34,7 @@ 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") {
+  if (v["__codemationItemExpr"] === "codemation.itemExpr" && typeof v["fn"] === "function") {
     return true;
   }
   for (const sym of Object.getOwnPropertySymbols(v)) {
@@ -54,6 +42,10 @@ export function isItemExpr<T, TItemJson = unknown>(value: unknown): value is Ite
       return true;
     }
   }
+  const keys = Object.keys(v);
+  if (keys.length === 1 && keys[0] === "fn" && typeof (v as { fn?: unknown }).fn === "function") {
+    return true;
+  }
   return false;
 }
 
@@ -79,9 +71,6 @@ function containsItemExprInUnknown(value: unknown, seen: WeakSet<object> = new W
   return false;
 }
 
-/**
- * Deep-resolves {@link itemExpr} leaves. Returns a new graph (does not mutate the original config object).
- */
 export async function resolveItemExprsInUnknown(
   value: unknown,
   args: ItemExprArgs,
@@ -117,9 +106,6 @@ export async function resolveItemExprsInUnknown(
   return out;
 }
 
-/**
- * Clones runnable config (best-effort) so per-item {@link itemExpr} resolution never mutates shared instances.
- */
 export async function resolveItemExprsForExecution(
   config: unknown,
   nodeCtx: NodeExecutionContext,

package/src/contracts/itemMeta.ts

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

package/src/contracts/mcpTypes.ts

@@ -1,29 +1,13 @@
 export type McpServerTransport = "http";
-// "stdio" is a self-host-only escape hatch (CODEMATION_ALLOW_STDIO_MCP=true); not typed here for managed.
 
 export interface McpServerDeclaration {
-  /** Globally unique slug, e.g. "gmail". Workflow authors reference this. */
   id: string;
   displayName: string;
   description: string;
   transport: McpServerTransport;
   url: string;
-  /**
-   * Credential types accepted by this MCP server, matching CredentialRequirement.acceptedTypes.
-   * Absent or empty means no credential is required.
-   */
   acceptedCredentialTypes?: ReadonlyArray<string>;
-  /**
-   * Documentation only in MVP. The bind-time validator checks
-   * requiredScopes ⊆ CredentialInstance.scopesGranted.
-   */
   requiredScopes?: string[];
-  /** Non-secret static headers merged onto every MCP request. */
   staticHeaders?: Record<string, string>;
-  /**
-   * Overrides for tool descriptions advertised by the MCP server.
-   * Applied by the connection pool after tools/list.
-   * Key: exact tool name as returned by the server.
-   */
   toolDescriptionOverrides?: Record<string, string>;
 }

package/src/contracts/retryPolicySpec.types.ts

@@ -1,10 +1,3 @@
-/**
- * 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).
- */
-
 export type RetryPolicySpec = NoneRetryPolicySpec | FixedRetryPolicySpec | ExponentialRetryPolicySpec;
 
 export interface NoneRetryPolicySpec {
@@ -13,18 +6,15 @@ export interface NoneRetryPolicySpec {
 
 export interface FixedRetryPolicySpec {
   readonly kind: "fixed";
-  /** Total attempts including the first execution. Must be >= 1. */
   readonly maxAttempts: number;
   readonly delayMs: number;
 }
 
 export 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;
 }

package/src/contracts/runFinishedAtFactory.ts

@@ -2,7 +2,6 @@ import type { PersistedRunState } from "./runTypes";
 
 type RunFinishedAtSource = Pick<PersistedRunState, "status" | "nodeSnapshotsByNodeId" | "finishedAt">;
 
-/** Derives workflow end time from persisted run root or node snapshots for run listings. */
 export class RunFinishedAtFactory {
   static resolveIso(state: RunFinishedAtSource): string | undefined {
     if (state.finishedAt && state.status !== "running" && state.status !== "pending") {

package/src/contracts/runTypes.ts

@@ -20,44 +20,26 @@ import type {
   WorkflowNodeConnection,
 } from "./workflowTypes";
 
-/**
- * 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.
- */
 export 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;
 }
 
 export interface RunExecutionOptions {
-  /** Run-intent override: force the inline scheduler and bypass node-level offload decisions. */
   localOnly?: boolean;
-  /** Marks runs started from webhook handling so orchestration can apply webhook-specific continuation rules. */
   webhook?: boolean;
   mode?: "manual" | "debug";
   sourceWorkflowId?: WorkflowId;
   sourceRunId?: RunId;
   derivedFromRunId?: RunId;
   isMutable?: boolean;
-  /** Set by the engine for this run: 0 = root, 1 = first child subworkflow, … */
   subworkflowDepth?: number;
-  /** Effective cap after engine policy merge (successful node completions per run). */
   maxNodeActivations?: number;
-  /** Effective cap after engine policy merge (subworkflow nesting). */
   maxSubworkflowDepth?: number;
-  /** Present iff started by a TestSuiteOrchestrator; propagates to subworkflow runs via {@link ParentExecutionRef.testContext}. */
   testContext?: RunTestContext;
 }
 
-/** Engine-owned counters persisted with the run (worker-safe). */
 export interface EngineRunCounters {
   completedNodeActivations: number;
 }
@@ -88,7 +70,6 @@ export interface PersistedWorkflowSnapshotNode {
   tokenName?: string;
   configTokenName?: string;
   config: unknown;
-  /** Pre-computed static configuration summary; populated by WorkflowSnapshotCodec. */
   inspectorSummary?: ReadonlyArray<Readonly<{ label: string; value: string }>>;
 }
 
@@ -97,9 +78,7 @@ export interface PersistedWorkflowSnapshot {
   name: string;
   nodes: ReadonlyArray<PersistedWorkflowSnapshotNode>;
   edges: ReadonlyArray<Edge>;
-  /** When the snapshot was built from a live workflow definition that configured a workflow error handler. */
   workflowErrorHandlerConfigured?: boolean;
-  /** Connection metadata for child nodes not in the execution graph (e.g. AI agent attachments). */
   connections?: ReadonlyArray<WorkflowNodeConnection>;
 }
 
@@ -163,20 +142,11 @@ export interface NodeExecutionSnapshot {
   inputsByPort?: NodeInputsByPort;
   outputs?: NodeOutputs;
   error?: NodeExecutionError;
-  /**
-   * When the node is a SubWorkflow invocation, the run id of the child run it spawned.
-   * Populated after the child run completes so the UI can deep-link to that specific execution.
-   */
   childRunId?: RunId;
 }
 
-/** Stable id for a single connection invocation row in {@link ConnectionInvocationRecord}. */
 export type ConnectionInvocationId = string;
 
-/**
- * One logical LLM or tool call under an owning workflow node (e.g. AI agent).
- * The owning node defines what {@link managedInput} and {@link managedOutput} contain.
- */
 export interface ConnectionInvocationRecord {
   readonly invocationId: ConnectionInvocationId;
   readonly runId: RunId;
@@ -187,24 +157,18 @@ export interface ConnectionInvocationRecord {
   readonly status: NodeExecutionStatus;
   readonly managedInput?: JsonValue;
   readonly managedOutput?: JsonValue;
-  /** Short human-readable description of what this invocation is doing right now (e.g. `"calling search_messages"`). Rendered as a sub-line on the canvas node card. */
   readonly statusLabel?: string;
-  /** Stable identifier for the thing this invocation acts on (e.g. an MCP tool name like `"search_messages"`). Persists across status transitions so the inspector can show it on completed/failed entries too. Connection nodes that ARE the tool (e.g. node-backed agent tools) leave this unset — the parent node id already identifies the subject. */
   readonly subjectName?: string;
   readonly error?: NodeExecutionError;
   readonly queuedAt?: string;
   readonly startedAt?: string;
   readonly finishedAt?: string;
   readonly updatedAt: string;
-  /** Per-item iteration id minted by the engine when this invocation occurred inside a runnable node's per-item loop. */
   readonly iterationId?: NodeIterationId;
-  /** Item index (0-based) of the iteration that produced this invocation. */
   readonly itemIndex?: number;
-  /** When set, this invocation was produced inside a sub-agent triggered by the named parent invocation. */
   readonly parentInvocationId?: ConnectionInvocationId;
 }
 
-/** Arguments for appending a {@link ConnectionInvocationRecord} (engine fills run/workflow ids and timestamps). */
 export type ConnectionInvocationAppendArgs = Readonly<{
   invocationId: ConnectionInvocationId;
   connectionNodeId: NodeId;
@@ -227,7 +191,6 @@ export type ConnectionInvocationAppendArgs = Readonly<{
 export interface RunCurrentState {
   outputsByNode: Record<NodeId, NodeOutputs>;
   nodeSnapshotsByNodeId: Record<NodeId, NodeExecutionSnapshot>;
-  /** Append-only history of connection-scoped invocations (LLM/tool) for inspector and canvas. */
   connectionInvocations?: ReadonlyArray<ConnectionInvocationRecord>;
   mutableState?: PersistedMutableRunState;
 }
@@ -258,7 +221,6 @@ export interface ExecutionFrontierPlan {
 
 export type RunStatus = "running" | "pending" | "completed" | "failed" | "suspended" | "halted";
 
-/** Reason a run transitioned to {@link RunStatus} `"halted"`. */
 export type RunHaltReason = "hitl-rejected" | "hitl-timeout" | "hitl-cancelled";
 
 export interface RunSummary {
@@ -266,14 +228,7 @@ export interface RunSummary {
   workflowId: WorkflowId;
   startedAt: string;
   status: RunStatus;
-  /**
-   * Test-case status for runs dispatched as part of a TestSuiteRun. Carries the
-   * assertion-rollup-corrected outcome the test orchestrator persists onto the row, so the
-   * executions list can show "failed" for a run whose workflow completed cleanly but whose
-   * assertions caught regressions. Absent for non-test runs and legacy rows.
-   */
   testCaseStatus?: TestCaseRunStatus;
-  /** ISO timestamp when the run finished (derived from node snapshots or store `updatedAt`); omit while running/pending. */
   finishedAt?: string;
   parent?: ParentExecutionRef;
   executionOptions?: RunExecutionOptions;
@@ -297,34 +252,20 @@ export interface PersistedRunSchedulingState {
   queue: RunQueueEntry[];
 }
 
-/** One persisted suspension entry per suspended item. */
 export interface PersistedSuspensionEntry {
-  /** Opaque task identifier (UUID v4). */
   readonly taskId: string;
   readonly nodeId: NodeId;
   readonly activationId: NodeActivationId;
   readonly itemIndex: number;
-  /** SHA-256 hex digest of the decision schema JSON (for schema-drift detection). */
   readonly decisionSchemaHash: string;
-  /** Serialized return value from `SuspensionRequest.deliver` (stored on the HumanTask row). */
   readonly deliveryRef: JsonValue;
-  /** ISO timestamp when the task expires. */
   readonly timeoutAt: string;
   readonly onTimeout: "halt" | "auto-accept";
 }
 
-/**
- * When a node is re-activated after suspension, the engine writes the resume context here
- * so `NodeExecutionRequestHandlerService` can splice `resumeContext` into ctx.
- * Cleared once the re-activation is consumed.
- */
 export interface PendingResumeEntry {
   readonly activationId: NodeActivationId;
   readonly nodeId: NodeId;
-  /**
-   * Typed as `unknown` here to avoid a circular import between runTypes ↔ runtimeTypes.
-   * `NodeExecutionRequestHandlerService` casts this to `ResumeContext` from runtimeTypes.
-   */
   readonly resumeContext: unknown;
 }
 
@@ -332,37 +273,23 @@ export interface PersistedRunState {
   runId: RunId;
   workflowId: WorkflowId;
   startedAt: string;
-  /** Canonical terminal time for listings and retention when persisted on the run root. */
   finishedAt?: string;
-  /** Optimistic concurrency / CAS on the run aggregate (repository may increment on save). */
   revision?: number;
   parent?: ParentExecutionRef;
   executionOptions?: RunExecutionOptions;
   control?: PersistedRunControlState;
   workflowSnapshot?: PersistedWorkflowSnapshot;
   mutableState?: PersistedMutableRunState;
-  /** Frozen at createRun from workflow + runtime defaults for prune/storage decisions. */
   policySnapshot?: PersistedRunPolicySnapshot;
-  /** Successful node completions so far (for activation budget). */
   engineCounters?: EngineRunCounters;
   status: RunStatus;
-  /** Populated when `status === "halted"` to discriminate why the run was halted. */
   reason?: RunHaltReason;
   pending?: PendingNodeExecution;
   queue: RunQueueEntry[];
   outputsByNode: Record<NodeId, NodeOutputs>;
   nodeSnapshotsByNodeId: Record<NodeId, NodeExecutionSnapshot>;
-  /** Append-only history of connection invocations (LLM/tool) nested under owning nodes. */
   connectionInvocations?: ReadonlyArray<ConnectionInvocationRecord>;
-  /**
-   * One entry per outstanding HITL suspension (per-item).
-   * Present and non-empty iff `status === "suspended"`.
-   */
   suspension?: ReadonlyArray<PersistedSuspensionEntry>;
-  /**
-   * Written by `resumeRun()` so `NodeExecutionRequestHandlerService` can splice `resumeContext`
-   * into the ctx when re-executing the suspended node. Cleared once consumed.
-   */
   pendingResume?: PendingResumeEntry;
 }
 
@@ -389,7 +316,6 @@ export interface WorkflowExecutionListingRepository {
   listRuns(args?: Readonly<{ workflowId?: WorkflowId; limit?: number }>): Promise<ReadonlyArray<RunSummary>>;
 }
 
-/** Runs eligible for retention-based pruning (completed or failed, older than cutoff). */
 export interface RunPruneCandidate {
   readonly runId: RunId;
   readonly workflowId: WorkflowId;

package/src/contracts/runtimeTypes.ts

@@ -19,56 +19,30 @@ import type { WorkflowActivationPolicy } from "./workflowActivationPolicy";
 import type { TriggerInstanceId, WebhookTriggerMatcher } from "./webhookTypes";
 import type { ZodType } from "zod";
 
-// ---------------------------------------------------------------------------
-// HITL primitives
-// ---------------------------------------------------------------------------
-
-/** Opaque unique identifier for a single HumanTask instance. */
 export type HumanTaskId = string;
 
-/**
- * Duration string — ISO 8601 duration ("PT24H") or shorthand ("24h").
- * Parsed by the timeout job; stored as-is in the suspension record.
- */
 export type Duration = string;
 
-/**
- * Minimal handle handed to the `deliver` callback so it can route to the correct
- * inbox channel.
- */
 export 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, import("./workflowTypes").JsonValue>>;
 }
 
-/** Human-readable description surface shown to the reviewer. */
 export interface HumanTaskSubject {
   readonly title: string;
   readonly summary: string;
   readonly attributes?: import("./workflowTypes").JsonValue;
 }
 
-/** Identity of the person who made a decision on the task. */
 export 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`.
- */
 export interface ResumeContext {
   readonly decision:
     | Readonly<{ kind: "decided"; value: unknown; actor: HumanTaskActor; decidedAt: Date }>
@@ -78,25 +52,6 @@ export interface ResumeContext {
   readonly task: HumanTaskHandle;
 }
 
-/**
- * Thrown by a node's `execute()` to request durable suspension of the current item.
- * The engine catches this, persists the suspension entry, calls `deliver`, and
- * continues to the next item (per-item semantics).
- *
- * @example
- * ```ts
- * throw new SuspensionRequest({
- *   decisionSchema: z.object({ approved: z.boolean() }),
- *   timeout: "PT24H",
- *   onTimeout: "halt",
- *   subject: { title: "Approve invoice", summary: "Invoice #1234 needs approval" },
- *   deliver: async (handle) => {
- *     await notifySlack(handle);
- *     return { channel: "slack", ts: "..." };
- *   },
- * });
- * ```
- */
 export class SuspensionRequest<
   TDecision = unknown,
   TDelivery extends import("./workflowTypes").JsonValue = import("./workflowTypes").JsonValue,
@@ -111,8 +66,6 @@ export class SuspensionRequest<
       deliver: (handle: HumanTaskHandle) => Promise<TDelivery>;
     }>,
   ) {
-    // Extending Error so wrappers like InProcessRetryRunner preserve identity
-    // (`instanceof SuspensionRequest`) instead of coercing via String(thrown).
     super(`SuspensionRequest(${request.subject?.title ?? "untitled"})`);
     this.name = "SuspensionRequest";
   }
@@ -190,11 +143,6 @@ export 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 }): Promise<void>;
 }
 
@@ -227,9 +175,7 @@ export interface BinaryStorage {
   openReadStream(storageKey: string): Promise<BinaryStorageReadResult | undefined>;
   stat(storageKey: string): Promise<BinaryStorageStatResult>;
   delete(storageKey: string): Promise<void>;
-  /** Deletes multiple objects in bulk. Keys are batched internally. */
   deleteMany(storageKeys: ReadonlyArray<string>): Promise<void>;
-  /** Lists all keys sharing a common prefix. Returns keys in arbitrary order. */
   listByPrefix(prefix: string): Promise<ReadonlyArray<string>>;
 }
 
@@ -246,27 +192,13 @@ export interface NodeBinaryAttachmentService extends ExecutionBinaryService {
   withAttachment<TJson>(item: Item<TJson>, name: string, attachment: BinaryAttachment): Item<TJson>;
 }
 
-/** Default maximum bytes read into memory by the bounded helpers (50 MiB). */
 export const BINARY_DEFAULT_MAX_BYTES = 50 * 1024 * 1024;
 
 export interface ExecutionBinaryService {
   forNode(args: { nodeId: NodeId; 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>;
 }
 
@@ -274,11 +206,8 @@ export 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;
@@ -286,28 +215,11 @@ export 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;
 }
 
@@ -334,19 +246,10 @@ export interface NodeExecutionContext<TConfig extends NodeConfigBase = NodeConfi
   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;
 }
 
-export interface PollingTriggerHandle {
-  /**
-   * Start the polling loop. The runtime registers its own cleanup handle so callers do not need to
-   * call {@link TriggerSetupContext.registerCleanup} for the loop.
-   * @returns The state returned by the first cycle (or `undefined` when the overlap guard fired).
-   */
+export interface TriggerPollingPort {
   start<TState, TItem>(args: {
     intervalMs: number;
     seedState?: TState;
@@ -355,7 +258,9 @@ export interface PollingTriggerHandle {
       signal: AbortSignal;
     }) => Promise<{ items: Items<TItem>; nextState: TState }>;
   }): Promise<TState | undefined>;
-  /** Convenience dedup-window helper. */
+}
+
+export interface PollingTriggerHandle extends TriggerPollingPort {
   readonly dedup: import("../triggers/polling/PollingTriggerDedupWindow").PollingTriggerDedupWindow;
 }
 
@@ -368,7 +273,6 @@ export interface TriggerSetupContext<
   previousState: TSetupState;
   registerCleanup(cleanup: TriggerCleanupHandle): void;
   emit(items: Items): Promise<void>;
-  /** Generic polling-trigger surface. Pre-binds trigger id, emit, and registerCleanup. */
   readonly polling: PollingTriggerHandle;
 }
 
@@ -382,12 +286,6 @@ export interface TriggerTestItemsContext<
   previousState: TSetupState;
 }
 
-/**
- * Trigger setup state is intentionally engine-owned so future ownership and
- * leader-election metadata can be coordinated centrally rather than pushed into
- * package-level setup code.
- */
-
 export interface PersistedTriggerSetupState<TState extends JsonValue | undefined = JsonValue | undefined> {
   trigger: TriggerInstanceId;
   updatedAt: string;
@@ -409,12 +307,6 @@ export interface EngineHost {
   workflows?: WorkflowRunnerService;
 }
 
-/**
- * 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.
- */
 export interface RunnableNodeExecuteArgs<
   TConfig extends RunnableNodeConfig<any, any> = RunnableNodeConfig<any, any>,
   TInputJson = unknown,
@@ -432,19 +324,11 @@ export interface RunnableNode<
   _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>;
   execute(args: RunnableNodeExecuteArgs<TConfig, TInputJson>): Promise<unknown> | unknown;
 }
 
-/** @deprecated Use {@link RunnableNode} */
 export type ItemNode<
   TConfig extends RunnableNodeConfig<any, any> = RunnableNodeConfig<any, any>,
   TInputJson = unknown,
@@ -453,12 +337,6 @@ export type ItemNode<
 
 export interface MultiInputNode<TConfig extends NodeConfigBase = NodeConfigBase> {
   kind: "node";
-  /**
-   * Declared output ports (typically `["main"]`).
-   *
-   * Prefer describing ports for authoring/canvas via {@link NodeConfigBase.declaredOutputPorts}.
-   * Engine defaults to `["main"]` when omitted.
-   */
   outputPorts?: ReadonlyArray<OutputPortKey>;
   executeMulti(inputsByPort: NodeInputsByPort, ctx: NodeExecutionContext<TConfig>): Promise<NodeOutputs>;
 }
@@ -582,7 +460,6 @@ export interface WorkflowSnapshotResolver {
   }): WorkflowDefinition | undefined;
 }
 
-/** Optional host wiring for trigger lifecycle logs (boot skip + activation sync). */
 export interface TriggerRuntimeDiagnostics {
   info(message: string): void;
   warn(message: string): void;
@@ -592,7 +469,6 @@ export interface EngineDeps {
   credentialSessions: CredentialSessionService;
   liveWorkflowRepository: LiveWorkflowRepository;
   workflowRepository: WorkflowRepository;
-  /** When {@link AllWorkflowsActiveWorkflowActivationPolicy}, all workflows behave as active (tests). */
   workflowActivationPolicy: WorkflowActivationPolicy;
   nodeResolver: NodeResolver;
   triggerSetupStateRepository: TriggerSetupStateRepository;
@@ -608,10 +484,7 @@ export interface EngineDeps {
   eventBus?: RunEventBus;
   tokenRegistry: PersistedWorkflowTokenRegistryLike;
   workflowNodeInstanceFactory: WorkflowNodeInstanceFactory;
-  /** Defaults for prune/storage snapshot when workflow omits explicit policy fields. */
   workflowPolicyRuntimeDefaults?: WorkflowPolicyRuntimeDefaults;
-  /** When set, logs inactive-workflow skips at boot and trigger start/stop on activation changes. */
   triggerRuntimeDiagnostics?: TriggerRuntimeDiagnostics;
-  /** When set, the polling-trigger runtime uses this logger for cycle info/debug/error. */
   pollingTriggerLogger?: import("../triggers/polling/PollingTriggerLogger").PollingTriggerLogger;
 }