@codemation/core 0.14.0 → 0.15.0

package/src/contracts/executionPersistenceContracts.ts

@@ -7,16 +7,12 @@ import type {
   RunStatus,
 } from "./runTypes";
 
-/** Canonical id for persisted execution rows (activation or connection invocation). */
 export type ExecutionInstanceId = string;
 
-/** Stable id for persisted work-queue rows. */
 export type WorkItemId = string;
 
-/** Batch grouping for planner activations. */
 export type BatchId = string;
 
-/** Optimistic concurrency on the run root. */
 export type RunRevision = number;
 
 export type PersistedRunWorkItemKind = "queue" | "pending";
@@ -29,10 +25,6 @@ export type ConnectionInvocationKind = "languageModel" | "tool" | "nestedAgent";
 
 export type PayloadStorageKind = "inline" | "external" | "omitted";
 
-/**
- * Persisted run-work-queue row (queue entry or pending activation).
- * Serialized to {@link RunWorkItem} in Prisma; engine still uses {@link PersistedRunState} queue + pending.
- */
 export interface PersistedRunWorkItemRecord {
   readonly workItemId: WorkItemId;
   readonly runId: RunId;
@@ -51,14 +43,10 @@ export interface PersistedRunWorkItemRecord {
   readonly sourceInstanceId?: ExecutionInstanceId;
   readonly parentInstanceId?: ExecutionInstanceId;
   readonly itemsIn: number;
-  /** Queue entry when kind is queue; pending activation when kind is pending. */
   readonly payloadJson: string;
   readonly error?: Readonly<NodeExecutionError>;
 }
 
-/**
- * Payload policy fields for large-batch externalization (optional on first rollout).
- */
 export interface ExecutionPayloadPolicyFields {
   readonly inputStorageKind: PayloadStorageKind;
   readonly outputStorageKind: PayloadStorageKind;
@@ -72,9 +60,6 @@ export interface ExecutionPayloadPolicyFields {
   readonly outputTruncated?: boolean;
 }
 
-/**
- * One persisted execution row (workflow node activation or connection invocation).
- */
 export interface PersistedExecutionInstanceRecord {
   readonly instanceId: ExecutionInstanceId;
   readonly runId: RunId;
@@ -110,9 +95,6 @@ export interface PersistedExecutionInstanceRecord {
   readonly payloadPolicy?: ExecutionPayloadPolicyFields;
 }
 
-/**
- * Cached slot projection for planner/debugger/UI (not canonical history).
- */
 export interface RunSlotProjectionState {
   readonly runId: RunId;
   readonly workflowId: WorkflowId;
@@ -151,12 +133,6 @@ export interface WorkflowRunDetailDto {
   readonly iterations?: ReadonlyArray<RunIterationDto>;
 }
 
-/**
- * Per-item iteration projected from connection invocations and node activations.
- *
- * One iteration = one item processed by an agent within an activation. Multiple invocations
- * (LLM rounds, tool calls) belonging to the same iteration share the iterationId.
- */
 export interface RunIterationDto {
   readonly iterationId: string;
   readonly agentNodeId: NodeId;
@@ -168,9 +144,7 @@ export interface RunIterationDto {
   readonly finishedAt?: string;
   readonly invocationIds: ReadonlyArray<string>;
   readonly parentInvocationId?: string;
-  /** Estimated cost rolled up from telemetry cost metric points, keyed by ISO currency code (e.g. "USD"). Values are minor units (cents-of-cents per the metric's `cost.currency_scale`). */
   readonly estimatedCostMinorByCurrency?: Readonly<Record<string, number>>;
-  /** Currency scale (denominator) per currency, when present on the metric points. Joined with `estimatedCostMinorByCurrency` to format human-readable amounts. */
   readonly estimatedCostCurrencyScaleByCurrency?: Readonly<Record<string, number>>;
 }
 
@@ -202,16 +176,9 @@ export interface ExecutionInstanceDto {
   readonly inputJson?: JsonValue;
   readonly outputJson?: JsonValue;
   readonly error?: Readonly<NodeExecutionError>;
-  /** Per-item iteration that produced this instance. Set on connectionInvocation rows produced inside per-item runnable loops. */
   readonly iterationId?: string;
-  /** Item index (0-based) of the iteration. */
   readonly itemIndex?: number;
-  /** Parent invocation id when this instance was emitted by a sub-agent triggered by an outer LLM/tool call. */
   readonly parentInvocationId?: string;
-  /**
-   * When this instance is a SubWorkflow node activation, the run id of the child run it spawned.
-   * Used by the UI to deep-link directly to the child execution.
-   */
   readonly childRunId?: string;
 }
 

package/src/contracts/hitlSeamTypes.ts

@@ -1,18 +1,10 @@
 import type { TypeToken } from "../di";
 
-/**
- * Seam interfaces for HITL collaborators that are implemented in `@codemation/host`
- * and injected into `NodeSuspensionHandler` at runtime. Core defines the interface only —
- * no HTTP, vendor SDK, or Prisma dependencies here.
- */
-
-/** Signs and hashes a HITL resume token. Core only needs the sign and hash operations. */
 export interface HitlResumeTokenSignerSeam {
   sign(args: { taskId: string; expiresAt: Date; schemaHash: string }): string;
   hashToken(token: string): string;
 }
 
-/** Schedules a delayed BullMQ job that drives the timeout path. */
 export interface HitlTimeoutJobSchedulerSeam {
   enqueueTimeoutJob(args: { taskId: string; expiresAt: Date }): Promise<void>;
 }
@@ -25,10 +17,4 @@ export const HitlTimeoutJobSchedulerToken = Symbol.for("codemation.core.HitlTime
   HitlTimeoutJobSchedulerSeam | undefined
 >;
 
-/**
- * Optional workspace ID injected into NodeSuspensionHandler in managed mode (T7 security fix).
- * Allows the handler to stamp the workspaceId on each HumanTaskRecord so HitlCallbackHandler
- * can assert workspace identity independently of the HMAC middleware.
- * Not registered in non-managed mode; NodeSuspensionHandler defaults to null.
- */
 export const HitlWorkspaceIdToken = Symbol.for("codemation.core.HitlWorkspaceId") as TypeToken<string | undefined>;

package/src/contracts/humanTaskStoreTypes.ts

@@ -4,7 +4,6 @@ import type { JsonValue } from "./workflowTypes";
 
 export type HumanTaskStatus = "pending" | "decided" | "timed_out" | "auto_accepted" | "cancelled";
 
-/** Persisted record for a single HITL task instance. */
 export interface HumanTaskRecord {
   readonly id: string;
   readonly runId: string;
@@ -34,7 +33,6 @@ export interface HumanTaskStore {
   findById(taskId: string): Promise<HumanTaskRecord | undefined>;
   findByResumeTokenHash(tokenHash: string): Promise<HumanTaskRecord | undefined>;
   findPendingForWorkspace(workspaceId: string): Promise<ReadonlyArray<HumanTaskRecord>>;
-  /** Returns all pending tasks regardless of workspace. Used by the local dev inbox (non-managed mode). */
   findAllPending(): Promise<ReadonlyArray<HumanTaskRecord>>;
   markDecided(args: { taskId: string; decision: JsonValue; decidedBy: HumanTaskActor; decidedAt: Date }): Promise<void>;
   markTimedOut(taskId: string): Promise<void>;

package/src/contracts/inboxChannelTypes.ts

@@ -2,10 +2,6 @@ import type { TypeToken } from "../di";
 import type { HumanTaskActor, HumanTaskHandle, HumanTaskSubject } from "./runtimeTypes";
 import type { Item } from "./workflowTypes";
 
-/**
- * A single inbox delivery channel.
- * Implementations: `LocalInboxChannel`, `ControlPlaneInboxChannel`.
- */
 export interface InboxChannel {
   readonly kind: "local" | "control-plane-inbox";
   deliver(args: InboxDeliverArgs): Promise<InboxDelivery>;
@@ -18,7 +14,6 @@ export type InboxDeliverArgs = Readonly<{
   subject: HumanTaskSubject;
   priority: "low" | "normal" | "high";
   item: Item;
-  /** Present in managed mode (from `PairingConfig.workspaceId`). */
   workspaceId?: string;
 }>;
 
@@ -37,10 +32,6 @@ export type InboxOnTimeoutArgs = Readonly<{
   policy: "halt" | "auto-accept";
 }>;
 
-/**
- * Resolves the correct `InboxChannel` for the current deployment mode
- * (local dev vs. managed/CP). Implemented in `@codemation/host`.
- */
 export interface InboxChannelResolverSeam {
   resolve(): { channel: InboxChannel; workspaceId?: string };
 }

package/src/contracts/index.ts

@@ -1,5 +1,7 @@
 export * from "./AgentBindError";
+export * from "./dispatchTypes";
 export * from "./agentMcpTypes";
+export * from "./deploymentManifestTypes";
 export * from "./hitlSeamTypes";
 export * from "./humanTaskStoreTypes";
 export * from "./inboxChannelTypes";
@@ -15,6 +17,7 @@ export * from "./itemMeta";
 export * from "./params";
 export * from "./itemExpr";
 export * from "./runtimeTypes";
+export * from "./triggerInvokerTypes";
 export * from "./telemetryTypes";
 export * from "./testTriggerTypes";
 export * from "./runFinishedAtFactory";

package/src/contracts/itemExpr.ts

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