@codemation/core 0.14.0 → 0.15.0

package/src/contracts/workspaceFileTypes.ts

@@ -1,81 +1,26 @@
 import type { TypeToken } from "../di";
 
-/**
- * Metadata returned for a workspace file object.
- * Filename and contentType come from the S3 object's custom metadata
- * (stamped by the control plane at upload time — story 03).
- * The local-fs driver reads them from a companion .meta.json sidecar.
- */
 export interface WorkspaceFileMetadata {
-  /** Storage key: `<workspaceId>/files/<fileId>` */
   readonly key: string;
-  /** Last path segment of the storage key. */
   readonly fileId: string;
-  /** Original filename as stamped by the CP at upload time. Empty string if not yet stamped (pre-story-03). */
   readonly filename: string;
   readonly contentType: string;
   readonly size: number;
   readonly lastModified: Date;
 }
 
-/**
- * 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`, `writeFile`) instead.
- *
- * This adapter is SEPARATE from the run-scoped BinaryStorage — do not confuse the two.
- */
 export interface IWorkspaceFileStorage {
-  /**
-   * Lists all files in this workspace, sorted newest-first by lastModified.
-   * Optional case-insensitive substring filter on filename.
-   */
   listFiles(filenameFilter?: string): Promise<ReadonlyArray<WorkspaceFileMetadata>>;
 
-  /**
-   * Returns metadata for the newest file with the given filename in this workspace.
-   * @throws WorkspaceFileNotFoundError when no file with that name exists.
-   */
   getFileByName(filename: string): Promise<WorkspaceFileMetadata>;
 
-  /**
-   * Returns metadata for the file with the given fileId in this workspace.
-   * @throws WorkspaceFileNotFoundError when no file with that id exists.
-   */
   getFileById(fileId: string): Promise<WorkspaceFileMetadata>;
 
-  /**
-   * Returns a non-buffered stream of the stored object's bytes.
-   * Accepts a full storage key or a fileId (prefixes as needed).
-   * @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>;
 }
 
-/**
- * Error thrown when a requested workspace file key does not exist.
- */
 export class WorkspaceFileNotFoundError extends Error {
   constructor(readonly key: string) {
     super(`Workspace file not found: ${key}`);
@@ -83,31 +28,14 @@ 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(...)`.
- */
 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/contracts.ts

@@ -1,28 +1,23 @@
-// Pure-type-only re-exports. Use this for type-only consumers that should not drag in runtime DSL or factory code.
-// This subpath prevents unnecessary compile-graph bloat for packages that only need types like NodeId, Items, etc.
-
 export type * from "./contracts/agentMcpTypes";
+export type { WorkspaceId, DispatchItemMeta, WorkflowDispatch } from "./contracts/dispatchTypes";
+export { serializeDispatch, deserializeDispatch } from "./contracts/dispatchTypes";
 export * from "./contracts/AgentBindError";
 export * from "./contracts/NoOpAgentMcpIntegration";
 export type * from "./contracts/baseTypes";
 export type * from "./contracts/assertionTypes";
-// assertionTypes also exports a runtime helper for deriving pass/fail from a score+threshold.
-// We keep the type-only re-export above and surface the helper explicitly here so UI consumers
-// (next-host) don't need to re-implement the comparison.
 export { deriveAssertionPassed, DEFAULT_ASSERTION_PASS_THRESHOLD } from "./contracts/assertionTypes";
 export type * from "./contracts/params";
 export type * from "./contracts/retryPolicySpec.types";
 export type * from "./contracts/CostCatalogContract";
 export type * from "./contracts/executionPersistenceContracts";
 export type * from "./contracts/runtimeTypes";
+export type * from "./contracts/triggerInvokerTypes";
 export type * from "./contracts/telemetryTypes";
 export type * from "./contracts/testTriggerTypes";
 export type * from "./contracts/runTypes";
 export type * from "./contracts/webhookTypes";
 export type * from "./contracts/workflowTypes";
 
-// credentialTypes mixes types (Credential* interfaces) with runtime (CredentialUnboundError class).
-// Export type-only subset for pure type consumers.
 export type {
   CredentialTypeId,
   CredentialInstanceId,
@@ -44,6 +39,8 @@ export type {
   CredentialInstanceRecord,
   CredentialSessionFactoryArgs,
   CredentialSessionFactory,
+  CredentialAccessTokenSessionArgs,
+  CredentialAccessTokenSessionFactory,
   CredentialHealthTester,
   CredentialType,
   AnyCredentialType,
@@ -51,8 +48,6 @@ export type {
   CredentialTypeRegistry,
 } from "./contracts/credentialTypes";
 
-// CostTrackingTelemetryContract mixes types with const runtime values (metric/attribute names).
-// Export type-only subset for pure type consumers.
 export type {
   CostTrackingComponent,
   CostTrackingUsageRecord,
@@ -60,3 +55,16 @@ export type {
   CostTrackingTelemetry,
   CostTrackingTelemetryFactory,
 } from "./contracts/CostTrackingTelemetryContract";
+
+export type {
+  DeploymentManifestSchemaVersion,
+  ManifestTriggerConfig,
+  ManifestNodeCredentialShape,
+  WorkflowDeploymentManifest,
+} from "./contracts/deploymentManifestTypes";
+export {
+  DEPLOYMENT_MANIFEST_SCHEMA_VERSION,
+  serializeManifest,
+  deserializeManifest,
+  emitWorkflowManifest,
+} from "./contracts/deploymentManifestTypes";

package/src/credentials/CredentialMaterialProvider.types.ts

@@ -1,35 +1,12 @@
 import type { OAuthMaterial } from "./OAuthFlowExecutor.types";
 
-/**
- * Material provider seam — see `docs/design/credentials-oauth-unification.md`,
- * "Material provider seam" section. Sits beside the workspace's
- * `CredentialStore`; persistence of the row stays at the store, persistence of
- * the bytes goes through this provider so they can live at the control plane
- * in managed mode.
- */
-
-/**
- * Pointer to material bytes. For local rows `ref` is the workspace instance id
- * and the bytes co-locate with the row (existing `CredentialOAuth2Material` /
- * `CredentialSecretMaterial` tables). For control-plane rows `ref` is the
- * CP-side credential id; the workspace stores only the pointer.
- */
 export type CredentialMaterialRef = Readonly<{
   source: "local" | "control-plane";
   id: string;
 }>;
 
-/**
- * Decrypted material bytes returned by a provider. Shape matches
- * `OAuthMaterial` — every supported credential type today is OAuth-shaped.
- */
 export type MaterialBundle = OAuthMaterial;
 
-/**
- * Caller context recorded by the CP material endpoint per fetch (D5 in the
- * `credentials-vault` sprint README). The local provider accepts but ignores
- * it; standalone mode has no audit log.
- */
 export type CallerContext = Readonly<{
   workspaceId: string;
   caller:
@@ -45,11 +22,6 @@ export interface CredentialMaterialProvider {
   setMaterial(ref: CredentialMaterialRef, material: MaterialBundle): Promise<void>;
 }
 
-/**
- * Thrown by a provider when asked to operate on a `ref.source` it does not
- * handle (e.g. the local provider being asked to read `control-plane` bytes).
- * Exported so `instanceof`-checks work across the workspace boundary.
- */
 export class IllegalMaterialSourceError extends Error {
   constructor(
     public readonly source: CredentialMaterialRef["source"],

package/src/credentials/ManagedCredentialMaterialWriteError.ts

@@ -1,9 +1,3 @@
-/**
- * Thrown by managed-mode providers when `setMaterial` is called. Managed
- * credential bytes are owned by the control plane; the workspace must not
- * mutate them. See `docs/design/credentials-oauth-unification.md` and
- * `planning/sprints/credentials-vault/02-controlplane-material-provider.md`.
- */
 export class ManagedCredentialMaterialWriteError extends Error {
   constructor(
     message: string = "managed credentials are owned by the control plane; use the Connected apps page to create or modify them.",

package/src/credentials/ManagedMaterialFetchError.ts

@@ -1,9 +1,3 @@
-/**
- * Thrown by `ControlPlaneCredentialMaterialProvider` when the control-plane
- * material endpoint returns a non-2xx response or a malformed body. Exposes
- * the HTTP status and the raw error body so call sites can surface actionable
- * detail without parsing strings.
- */
 export class ManagedMaterialFetchError extends Error {
   constructor(
     public readonly status: number,

package/src/credentials/OAuthFlowExecutor.types.ts

@@ -1,13 +1,3 @@
-/**
- * Four-concept model for credentials (see docs/design/credentials-oauth-unification.md):
- *   1. CredentialType — schema for stored material (e.g. "oauth.google.gmail").
- *   2. Credential slot requirement — which types a node or MCP server accepts.
- *   3. CredentialInstance — a stored, usable token row in the host's credential store.
- *   4. OAuthFlowExecutor (this file) — the only concept that differs between deployment
- *      modes. DI selects one implementation at boot; the rest of the system programs
- *      against this interface alone.
- */
-
 export interface OAuthFlowStartArgs {
   readonly typeId: string;
   readonly scopes: ReadonlyArray<string>;
@@ -34,11 +24,6 @@ export interface OAuthMaterial {
 
 export interface OAuthFlowExecutor {
   start(args: OAuthFlowStartArgs): Promise<OAuthFlowStartResult>;
-  /**
-   * Returns the instanceId associated with a pending stateToken without consuming it.
-   * Used by callback routes to identify the target instance before calling completeCallback.
-   * Returns undefined when the stateToken is unknown or already consumed.
-   */
   lookupInstanceId(stateToken: string): string | undefined;
   completeCallback(args: OAuthFlowCallbackArgs): Promise<OAuthMaterial>;
   refresh(args: { typeId: string; instanceId: string; material: OAuthMaterial }): Promise<OAuthMaterial>;

package/src/di/CoreTokens.ts

@@ -21,6 +21,7 @@ import type {
   WorkflowRepository,
   WorkflowRunnerService,
 } from "../types";
+import type { TriggerInvoker } from "../contracts/triggerInvokerTypes";
 
 export const CoreTokens = {
   PersistedWorkflowTokenRegistry: Symbol.for(
@@ -51,17 +52,12 @@ export const CoreTokens = {
   RunEventBus: Symbol.for("codemation.core.RunEventBus") as TypeToken<RunEventBus>,
   BinaryStorage: Symbol.for("codemation.core.BinaryStorage") as TypeToken<BinaryStorage>,
   WebhookBasePath: Symbol.for("codemation.core.WebhookBasePath") as TypeToken<string>,
-  /** Engine execution limits (defaults + optional host overrides). Consumers may bind a custom instance to override. */
   EngineExecutionLimitsPolicy: Symbol.for(
     "codemation.core.EngineExecutionLimitsPolicy",
   ) as TypeToken<EngineExecutionLimitsPolicy>,
   WorkflowActivationPolicy: Symbol.for(
     "codemation.core.WorkflowActivationPolicy",
   ) as TypeToken<WorkflowActivationPolicy>,
-  /**
-   * Optional. When registered, AIAgentNode uses it to resolve mcpServers bindings,
-   * validate scopes, open pool connections, and prepare the MCP ToolSet map.
-   * Not registered in the default core bootstrap — the host provides the implementation.
-   */
   AgentMcpIntegration: Symbol.for("codemation.core.AgentMcpIntegration") as TypeToken<AgentMcpIntegration>,
+  TriggerInvoker: Symbol.for("codemation.core.TriggerInvoker") as TypeToken<TriggerInvoker>,
 } as const;

package/src/events/ConnectionInvocationEventPublisher.ts

@@ -2,13 +2,6 @@ import type { ConnectionInvocationRecord } from "../contracts/runTypes";
 import type { ParentExecutionRef } from "../types";
 import type { RunEventBus } from "./runEvents";
 
-/**
- * Publishes per-invocation lifecycle records onto the run {@link RunEventBus}.
- *
- * Surgical, per-invocation events let the UI update the right-side inspector
- * timeline as each LLM round / tool call transitions through `running` → `completed`
- * (or `failed`) without depending on a coarse `runSaved` poll.
- */
 export class ConnectionInvocationEventPublisher {
   constructor(
     private readonly eventBus: RunEventBus | undefined,

package/src/events/NodeEventPublisher.ts

@@ -1,7 +1,6 @@
 import type { RunEventBus } from "./runEvents";
 import type { NodeExecutionSnapshot } from "../types";
 
-/** Publishes node lifecycle snapshots onto the run {@link RunEventBus}. */
 export class NodeEventPublisher {
   constructor(private readonly eventBus: RunEventBus | undefined) {}
 

package/src/events/runEvents.ts

@@ -2,15 +2,7 @@ import type { TestSuiteRunId } from "../contracts/testTriggerTypes";
 import type { ConnectionInvocationRecord } from "../contracts/runTypes";
 import type { NodeExecutionSnapshot, ParentExecutionRef, PersistedRunState, RunId, WorkflowId } from "../types";
 
-/**
- * Outcome of a single test case (one workflow run dispatched by the test-suite orchestrator).
- * - `running`: workflow still in flight
- * - `succeeded`: workflow completed AND all assertions passed (or no assertions)
- * - `failed`: workflow failed OR (workflow completed but ≥1 assertion failed)
- * - `errored` / `cancelled`: workflow itself errored or was cancelled
- */
 export type TestCaseRunStatus = "running" | "succeeded" | "failed" | "errored" | "cancelled";
-/** Aggregate outcome of a TestSuiteRun. */
 export type TestSuiteRunStatus = "succeeded" | "failed" | "partial" | "errored" | "cancelled";
 
 export type RunEvent =

package/src/execution/ActivationEnqueueService.ts

@@ -47,15 +47,7 @@ export type ActivationEnqueueRequest = {
   planner: RunQueuePlanner;
   engineCounters?: EngineRunCounters;
   connectionInvocations?: ReadonlyArray<ConnectionInvocationRecord>;
-  /**
-   * Remaining suspension entries after consuming one for a HITL resume.
-   * When provided, saved alongside the new pending state so they survive the enqueue.
-   */
   suspension?: ReadonlyArray<PersistedSuspensionEntry>;
-  /**
-   * Resume context to attach to the re-activated node's execution context.
-   * Written here and consumed by `NodeExecutionRequestHandlerService` when building ctx.
-   */
   pendingResume?: PendingResumeEntry;
 };
 
@@ -126,8 +118,6 @@ export class ActivationEnqueueService {
         ...args.previousNodeSnapshotsByNodeId,
         [args.request.nodeId]: queuedSnapshot,
       },
-      // HITL: preserve suspension entries and resume context when re-activating a
-      // suspended node. Omit fields when not provided (avoids polluting normal enqueue).
       ...(args.suspension !== undefined ? { suspension: args.suspension } : {}),
       ...(args.pendingResume !== undefined ? { pendingResume: args.pendingResume } : {}),
     });

package/src/execution/ChildExecutionScopeFactory.ts

@@ -7,19 +7,6 @@ import type {
   TelemetrySpanScope,
 } from "../types";
 
-/**
- * Builds a re-rooted child execution context for sub-agent (and other deeply-nested) invocations.
- *
- * At the orchestrator's `agent.tool.call` boundary the inner runtime needs a ctx whose:
- * - `nodeId` is the tool's connection node id (so inner LLM/tool connection ids derive correctly),
- * - `activationId` is fresh (so its connection-invocation rows are uniquely identifiable),
- * - `telemetry` parents children under the tool-call span (not the orchestrator's node span),
- * - `binary` is scoped to the new (nodeId, activationId),
- * - `parentInvocationId` points back to the tool-call invocation for downstream lineage.
- *
- * Registered via factory in {@link EngineRuntimeRegistrar} so constructors stay free of parameter
- * decorators (Next/SWC and coverage tooling cannot parse them on in-repo sources).
- */
 export class ChildExecutionScopeFactory {
   constructor(private readonly activationIdFactory: ActivationIdFactory) {}
 

package/src/execution/FanInMergeByOriginMerger.ts

@@ -2,17 +2,6 @@ import type { InputPortKey, Item, Items, NodeInputsByPort } from "../types";
 
 import { getOriginIndexFromItem } from "../contracts/itemMeta";
 
-/**
- * Default fan-in: combine multi-port {@link NodeInputsByPort} into one {@link Items} batch for per-item nodes.
- *
- * This is used when a single-input per-item node has multiple inbound edges (for example, branch reconverge
- * after an `If` / `Switch`). The default behavior is **append / union** (preserving item payloads) with a
- * deterministic order:
- *
- * - When router origin metadata exists (`meta._cm.originIndex`), items are sorted by origin index so the
- *   downstream batch preserves original ordering across branches.
- * - Otherwise, items are appended by port-key order, preserving each port's local order.
- */
 export class FanInMergeByOriginMerger {
   merge(inputsByPort: NodeInputsByPort): Items {
     const portKeys = Object.keys(inputsByPort).sort();

package/src/execution/InProcessRetryRunner.ts

@@ -7,7 +7,6 @@ import type { AsyncSleeper } from "./asyncSleeper.types";
 
 export type { AsyncSleeper } from "./asyncSleeper.types";
 
-/** Maximum permitted retry attempts — workflow-declared values above this are clamped. */
 const HARD_MAX_RETRY_ATTEMPTS = 10;
 
 type NormalizedPolicy =

package/src/execution/ItemExprResolver.ts

@@ -1,9 +1,6 @@
 import { resolveItemExprsForExecution } from "../contracts/itemExpr";
 import type { Item, NodeExecutionContext, RunnableNodeConfig } from "../types";
 
-/**
- * Resolves {@link import("../contracts/itemExpr").ItemExpr} leaves on runnable config before {@link RunnableNode.execute}.
- */
 export class ItemExprResolver {
   async resolveConfigForItem<TConfig extends RunnableNodeConfig<any, any>>(
     ctx: NodeExecutionContext<TConfig>,

package/src/execution/NodeActivationRequestComposer.ts

@@ -46,9 +46,6 @@ export type PlannedNodeActivationRequest = NodeActivationContextArgs & {
   nodeDefinition: NodeExecutionDefinition;
 };
 
-/**
- * Builds {@link NodeActivationRequest} values shared by workflow starters and continuation.
- */
 export class NodeActivationRequestComposer {
   constructor(
     private readonly activationIdFactory: ActivationIdFactory,

package/src/execution/NodeActivationRequestInputPreparer.ts

@@ -5,11 +5,6 @@ import type { Item, NodeActivationRequest, RunnableNodeConfig, WorkflowNodeInsta
 import { FanInMergeByOriginMerger } from "./FanInMergeByOriginMerger";
 import { NodeInputContractError } from "./NodeInputContractError";
 
-/**
- * Validates per-item inputs for {@link RunnableNode} before enqueue persistence (Zod on `item.json`).
- * Does not rewrite `item.json` (wire stays as emitted upstream; engine passes parsed input via `execute` args).
- * Converts multi-input activations into a single-input batch when the node is per-item only (engine fan-in).
- */
 export class NodeActivationRequestInputPreparer {
   private readonly fanInMerger = new FanInMergeByOriginMerger();
 

package/src/execution/NodeExecutionSnapshotFactory.ts

@@ -71,7 +71,6 @@ export class NodeExecutionSnapshotFactory {
     inputsByPort: NodeInputsByPort;
     outputs: NodeOutputs;
     fromPinnedOutput?: boolean;
-    /** Override the terminal status for HITL outcomes (defaults to `"completed"`). */
     hitlStatus?: Extract<
       NodeExecutionStatus,
       "hitl-approved" | "hitl-rejected" | "hitl-timeout" | "hitl-auto-accepted" | "hitl-cancelled"

package/src/execution/NodeExecutor.ts

@@ -38,9 +38,7 @@ export class NodeExecutor {
     private readonly retryRunner: InProcessRetryRunner,
     itemExprResolver?: ItemExprResolver,
     outputBehaviorResolver?: RunnableOutputBehaviorResolver,
-    /** Required for HITL suspension support. When omitted, `SuspensionRequest` throws upward. */
     private readonly suspensionHandler?: NodeSuspensionHandler,
-    /** Required alongside `suspensionHandler`. */
     private readonly loadRunState?: (runId: RunId) => Promise<PersistedRunState | undefined>,
   ) {
     this.itemExprResolver = itemExprResolver ?? new ItemExprResolver();
@@ -190,8 +188,6 @@ export class NodeExecutor {
       const runnableCtx = request.ctx as NodeExecutionContext<RunnableNodeConfig>;
       const resolvedCtx = await this.itemExprResolver.resolveConfigForItem(runnableCtx, item, i, inputBatch);
       const baseCtx = this.pickExecutionContext(runnableCtx, resolvedCtx);
-      // Mint a per-item iteration id and stamp it (with the item index) onto the ctx so connection
-      // invocations and telemetry written from inside `node.execute` carry the per-item identity.
       const iterationCtx = {
         ...baseCtx,
         iterationId: NodeIterationIdFactory.create(),
@@ -208,9 +204,6 @@ export class NodeExecutor {
       try {
         raw = await Promise.resolve(node.execute(args));
       } catch (e) {
-        // Use both instanceof AND name check: under tsx/dev with mixed source/dist resolution,
-        // SuspensionRequest may load as two distinct class objects and instanceof fails. The
-        // name brand survives the duality because both copies set name="SuspensionRequest".
         const isSuspension =
           e instanceof SuspensionRequest ||
           (e instanceof Error &&
@@ -218,23 +211,17 @@ export class NodeExecutor {
             typeof (e as { request?: unknown }).request === "object");
         if (isSuspension) {
           if (!this.suspensionHandler || !this.loadRunState) {
-            // Suspension not supported in this executor configuration — propagate as a regular error.
             throw new Error(
               `Node ${request.nodeId} threw SuspensionRequest but this NodeExecutor has no suspensionHandler configured.`,
               { cause: e },
             );
           }
-          // Per-item suspension: load current state, persist the suspension entry, and
-          // continue processing remaining items. If deliver throws it propagates upward.
           const state = await this.loadRunState(request.runId);
           if (!state) {
             throw new Error(`NodeExecutor: run state not found for runId ${request.runId} during suspension`, {
               cause: e,
             });
           }
-          // handleSuspension throws RunSuspendedError after persisting — we re-throw it
-          // to exit the loop immediately. Partial byPort outputs are intentionally dropped
-          // (TODO: consider stashing outputs of non-suspended items alongside the suspension).
           await this.suspensionHandler.handle({
             runId: request.runId,
             nodeId: request.nodeId,
@@ -244,7 +231,7 @@ export class NodeExecutor {
             state,
             telemetry: iterationCtx.telemetry,
           });
-          hasSuspension = true; // unreachable — handler always throws, but satisfies TS control-flow
+          hasSuspension = true;
           continue;
         }
         throw e;
@@ -264,14 +251,11 @@ export class NodeExecutor {
       }
     }
     if (hasSuspension) {
-      // Unreachable in practice (suspensionHandler always throws RunSuspendedError) but
-      // guards against future refactors that might change handler behaviour.
       throw new RunSuspendedError(request.runId, "unknown");
     }
     return byPort as NodeOutputs;
   }
 
-  /** Use resolver ctx only when {@link NodeExecutionContext.config} is non-nullish. */
   private pickExecutionContext<TConfig extends RunnableNodeConfig<any, any>>(
     runnableCtx: NodeExecutionContext<TConfig>,
     resolvedCtx: NodeExecutionContext<TConfig> | null | undefined,

package/src/execution/NodeSuspensionHandler.ts

@@ -19,33 +19,12 @@ import { CodemationTelemetryAttributeNames } from "../contracts/CodemationTeleme
 import { RunSuspendedError } from "./RunSuspendedError";
 export { RunSuspendedError };
 
-/**
- * Handles per-item `SuspensionRequest` catches in the engine's item execution loop.
- *
- * Responsibilities:
- * 1. Generate a `taskId` (UUID v4).
- * 2. Persist a `HumanTask` row via `HumanTaskStore.create`.
- * 3. Sign a resume URL via `HitlResumeTokenSigner.sign`.
- * 4. Enqueue a delayed BullMQ timeout job via `HitlTimeoutJobScheduler.enqueue`.
- * 5. Build a `HumanTaskHandle` and call `deliver`.
- * 6. Append a `PersistedSuspensionEntry` to the run state and flip status to `"suspended"`.
- * 7. Persist via `WorkflowExecutionRepository.save`.
- * 8. Throw `RunSuspendedError` so the caller can exit cleanly.
- *
- * If `deliver` throws, the error propagates up to `NodeExecutionRequestHandlerService`
- * which routes it through `resumeFromNodeError` → run status becomes `"failed"`.
- *
- * `humanTaskStore`, `tokenSigner`, and `timeoutScheduler` are optional —
- * when not registered (e.g. in unit tests), the handler still suspends the run but
- * skips persistence, token signing, and job scheduling.
- */
 export class NodeSuspensionHandler {
   constructor(
     private readonly workflowExecutionRepository: WorkflowExecutionRepository,
     private readonly humanTaskStore?: HumanTaskStore,
     private readonly tokenSigner?: HitlResumeTokenSignerSeam,
     private readonly timeoutScheduler?: HitlTimeoutJobSchedulerSeam,
-    /** Workspace ID to stamp on HumanTaskRecord in managed mode (T7 security fix). Null in non-managed mode. */
     private readonly workspaceId?: string,
   ) {}
 
@@ -56,7 +35,6 @@ export class NodeSuspensionHandler {
     itemIndex: number;
     suspensionRequest: SuspensionRequest;
     state: PersistedRunState;
-    /** Telemetry scope of the node's per-item span. Used to emit `hitl.task.*` span events. */
     telemetry?: TelemetryScope;
   }): Promise<never> {
     const taskId = `htask_${globalThis.crypto.randomUUID()}`;
@@ -68,12 +46,11 @@ export class NodeSuspensionHandler {
     const decisionSchemaHash = this.hashSchema(decisionSchema);
     const decisionSchemaJson = this.schemaToJson(decisionSchema);
 
-    // Build resume token (when signer is available)
     let resumeUrl = "";
     let resumeTokenHash = "";
     if (this.tokenSigner) {
       const token = this.tokenSigner.sign({ taskId, expiresAt, schemaHash: decisionSchemaHash });
-      resumeUrl = token; // callers (deliver) receive the raw token; inbox layers wrap into a URL
+      resumeUrl = token;
       resumeTokenHash = this.tokenSigner.hashToken(token);
     }
 
@@ -86,7 +63,6 @@ export class NodeSuspensionHandler {
       ...(metadata !== undefined ? { metadata } : {}),
     };
 
-    // Emit hitl.task.created before calling deliver.
     const channel = (metadata as Record<string, unknown> | undefined)?.["channel"];
     await args.telemetry?.addSpanEvent?.({
       name: "hitl.task.created",
@@ -99,8 +75,6 @@ export class NodeSuspensionHandler {
       },
     });
 
-    // D5: deliver throws → emit hitl.task.delivery_failed, then propagate upward;
-    // caller routes to resumeFromNodeError → "failed"
     let deliveryRef: Awaited<ReturnType<typeof deliver>>;
     try {
       deliveryRef = await deliver(handle);
@@ -116,15 +90,11 @@ export class NodeSuspensionHandler {
       throw deliverError;
     }
 
-    // Persist HumanTask row
     if (this.humanTaskStore) {
       const record: HumanTaskRecord = {
         id: taskId,
         runId: args.runId,
         workflowId: args.state.workflowId,
-        // T7: stamp workspaceId in managed mode so HitlCallbackHandler can assert workspace identity.
-        // Non-managed mode leaves this undefined (null in DB) — the check in HitlCallbackHandler
-        // is guarded by `task.workspaceId !== undefined` and is a no-op when null.
         workspaceId: this.workspaceId ?? undefined,
         nodeId: args.nodeId,
         activationId: args.activationId,
@@ -144,7 +114,6 @@ export class NodeSuspensionHandler {
       await this.humanTaskStore.create(record);
     }
 
-    // Enqueue timeout job
     if (this.timeoutScheduler) {
       await this.timeoutScheduler.enqueueTimeoutJob({ taskId, expiresAt });
     }
@@ -172,13 +141,7 @@ export class NodeSuspensionHandler {
     throw new RunSuspendedError(args.runId, taskId);
   }
 
-  /**
-   * Parse a duration string into milliseconds.
-   * Accepts ISO 8601 durations ("PT24H", "PT30M") and shorthand ("24h", "30m", "1d").
-   * Throws for unrecognised formats.
-   */
   private parseDurationMs(duration: string): number {
-    // Shorthand: "24h", "30m", "7d", "3600s"
     const shorthand = /^(\d+(?:\.\d+)?)(s|m|h|d)$/i.exec(duration);
     if (shorthand) {
       const value = parseFloat(shorthand[1]!);
@@ -191,7 +154,6 @@ export class NodeSuspensionHandler {
       };
       return value * multipliers[unit]!;
     }
-    // ISO 8601 duration subset: PTnHnMnS (days handled via P1D)
     const iso = /^P(?:(\d+)D)?(?:T(?:(\d+)H)?(?:(\d+)M)?(?:(\d+(?:\.\d+)?)S)?)?$/.exec(duration);
     if (iso) {
       const days = parseFloat(iso[1] ?? "0");