@codemation/core 0.13.2 → 0.15.0

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/NodeOutputNormalizer.ts

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

package/src/execution/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");

package/src/execution/PersistedRunStateTerminalBuilder.ts

@@ -1,19 +1,14 @@
 import type { EngineRunCounters, PersistedRunState, RunHaltReason, RunQueueEntry } from "../types";
 
-/**
- * Merges common terminal-run fields onto a loaded {@link PersistedRunState} without repeating object literals.
- */
 export class PersistedRunStateTerminalBuilder {
   mergeTerminal(args: {
     state: PersistedRunState;
     engineCounters: EngineRunCounters;
     status: "completed" | "failed" | "halted";
-    /** Populated when `status === "halted"`. */
     reason?: RunHaltReason;
     queue: RunQueueEntry[];
     outputsByNode: PersistedRunState["outputsByNode"];
     nodeSnapshotsByNodeId: NonNullable<PersistedRunState["nodeSnapshotsByNodeId"]>;
-    /** When set, persisted on the run root for listings and retention pruning. */
     finishedAtIso?: string;
   }): PersistedRunState {
     return {

package/src/execution/RunSuspendedError.ts

@@ -1,15 +1,5 @@
 import type { RunId } from "../types";
 
-/**
- * Internal sentinel thrown by {@link NodeSuspensionHandler} after persisting a suspension
- * entry. `NodeExecutionRequestHandlerService` catches this specifically and returns cleanly —
- * no continuation call, preventing `resumeFromNodeResult` / `resumeFromNodeError` from
- * overwriting the `"suspended"` run status.
- *
- * The `Error` suffix satisfies the ESLint `no-manual-di-new` allowlist. This is NOT a
- * user-facing error — it is an engine-internal control-flow primitive and should NOT be
- * exported from the public barrel.
- */
 export class RunSuspendedError extends Error {
   constructor(
     readonly runId: RunId,

package/src/execution/RunnableOutputBehaviorResolver.ts

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

package/src/execution/WorkflowRunExecutionContextFactory.ts

@@ -11,9 +11,6 @@ import type {
 
 import { CredentialResolverFactory } from "./CredentialResolverFactory";
 
-/**
- * Shared {@link ExecutionContextFactory#create} wiring for workflow runners (base context before node-specific fields).
- */
 export class WorkflowRunExecutionContextFactory {
   constructor(
     private readonly executionContextFactory: ExecutionContextFactory,

package/src/index.ts

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

package/src/orchestration/AbortControllerFactory.ts

@@ -1,7 +1,3 @@
-/**
- * Mints fresh {@link AbortController}s. Injected (rather than direct `new`) to honor the
- * codebase's no-direct-construction rule and to give tests a seam for substituting a fake.
- */
 export class AbortControllerFactory {
   create(): AbortController {
     return new AbortController();

package/src/orchestration/Engine.ts

@@ -98,11 +98,6 @@ export interface EngineFacadeDeps {
   nodeExecutionRequestHandler: EngineNodeExecutionRequestHandler;
 }
 
-/**
- * Runtime facade for orchestration, continuation, triggers, and webhook routing.
- * Prefer {@link import("../intents/RunIntentService").RunIntentService} for host/HTTP invocation boundaries.
- * The class token is exported from `@codemation/core/bootstrap` (not the main `@codemation/core` barrel).
- */
 export class Engine implements NodeActivationContinuation, NodeExecutionRequestHandler {
   constructor(private readonly deps: EngineFacadeDeps) {}
 
@@ -236,10 +231,6 @@ export class Engine implements NodeActivationContinuation, NodeExecutionRequestH
     return await this.deps.runContinuationService.waitForWebhookResponse(runId);
   }
 
-  /**
-   * Re-activate a suspended run item with a human decision (HITL).
-   * The HTTP resume endpoint calls this; this method exposes the engine primitive.
-   */
   async resumeRun(args: { runId: RunId; taskId: string; resumeContext: ResumeContext }): Promise<RunResult> {
     return await this.deps.runContinuationService.resumeRun(args);
   }

package/src/orchestration/NodeExecutionRequestHandlerService.ts

@@ -15,6 +15,7 @@ import { RunSuspendedError } from "../execution/RunSuspendedError";
 import { NodeActivationRequestComposer } from "../execution/NodeActivationRequestComposer";
 import { NodeRunStateWriterFactory } from "../execution/NodeRunStateWriterFactory";
 import { WorkflowRunExecutionContextFactory } from "../execution/WorkflowRunExecutionContextFactory";
+import { MissingRuntimeParityGuard } from "../workflowSnapshots/MissingRuntimeParityGuard";
 
 type PersistedWorkflowLike = Readonly<{
   workflowId: PersistedRunState["workflowId"];
@@ -32,6 +33,7 @@ export class NodeExecutionRequestHandlerService implements NodeExecutionRequestH
     private readonly nodeExecutor: NodeExecutor,
     private readonly continuation: NodeActivationContinuation,
     private readonly executionLimitsPolicy: EngineExecutionLimitsPolicy,
+    private readonly parityGuard: MissingRuntimeParityGuard,
   ) {}
 
   async handleNodeExecutionRequest(request: NodeExecutionRequest): Promise<void> {
@@ -86,7 +88,6 @@ export class NodeExecutionRequestHandlerService implements NodeExecutionRequestH
     const portKeys = Object.keys(inputsByPort);
     const kind = portKeys.length === 1 && portKeys[0] === "in" ? ("single" as const) : ("multi" as const);
     const batchId = pendingExecution.batchId ?? "batch_1";
-    // Splice resumeContext from pendingResume if this activation is a HITL resume.
     const pendingResume = state.pendingResume;
     const resumeContext: ResumeContext | undefined =
       pendingResume?.activationId === request.activationId && pendingResume?.nodeId === request.nodeId
@@ -127,7 +128,6 @@ export class NodeExecutionRequestHandlerService implements NodeExecutionRequestH
             input: inputsByPort.in ?? request.input ?? [],
           });
 
-    // Clear pendingResume from state now that we have consumed it.
     if (resumeContext != null) {
       const clearedState = await this.workflowExecutionRepository.load(request.runId);
       if (clearedState?.pendingResume?.activationId === request.activationId) {
@@ -144,11 +144,10 @@ export class NodeExecutionRequestHandlerService implements NodeExecutionRequestH
 
     let outputs;
     try {
+      this.parityGuard.assertNone(workflow, [request.nodeId]);
       outputs = await this.nodeExecutor.execute(activationRequest);
     } catch (error) {
       if (error instanceof RunSuspendedError) {
-        // The node threw SuspensionRequest; NodeSuspensionHandler already persisted the
-        // suspension entry and flipped status to "suspended". Nothing more to do here.
         return;
       }
       await this.resumeAfterExecutionError(activationRequest, this.asError(error));

package/src/orchestration/RunContinuationService.ts

@@ -46,6 +46,7 @@ import { NodeActivationRequestComposer } from "../execution/NodeActivationReques
 import { PersistedRunStateTerminalBuilder } from "../execution/PersistedRunStateTerminalBuilder";
 import { RunStateSemantics } from "../execution/RunStateSemantics";
 import { WorkflowRunExecutionContextFactory } from "../execution/WorkflowRunExecutionContextFactory";
+import { MissingRuntimeParityGuard } from "../workflowSnapshots/MissingRuntimeParityGuard";
 
 export class RunContinuationService {
   constructor(
@@ -66,6 +67,7 @@ export class RunContinuationService {
     private readonly policyErrorServices: WorkflowPolicyErrorServices,
     private readonly terminalPersistence: RunTerminalPersistenceCoordinator,
     private readonly executionLimitsPolicy: EngineExecutionLimitsPolicy,
+    private readonly parityGuard: MissingRuntimeParityGuard,
   ) {}
 
   async markNodeRunning(args: {
@@ -151,9 +153,6 @@ export class RunContinuationService {
     data.setOutputs(args.nodeId, args.outputs);
     const completedAt = new Date().toISOString();
 
-    // Resolve HITL status from the node's decision output.
-    // Only fires when the output carries `item.json.decision.status` written by a
-    // defineHumanApprovalNode-based node. Non-HITL nodes never have this field.
     const hitlResolution = this.resolveHitlStatus(args.outputs);
 
     const completedSnapshot = this.semantics.createFinishedSnapshot({
@@ -170,7 +169,6 @@ export class RunContinuationService {
       hitlStatus: hitlResolution?.nodeStatus,
     });
 
-    // Halt the run for HITL rejection / timeout outcomes.
     if (hitlResolution?.halt) {
       const haltedState = this.persistedRunStateTerminalBuilder.mergeTerminal({
         state,
@@ -355,6 +353,7 @@ export class RunContinuationService {
     });
 
     try {
+      this.parityGuard.assertNone(wf, [next.nodeId]);
       const { queuedSnapshot, result } = await this.activationEnqueueService.enqueueActivationWithSnapshot({
         runId: state.runId,
         workflowId: state.workflowId,
@@ -461,9 +460,7 @@ export class RunContinuationService {
             nodeId: args.nodeId,
             outputs: recovered,
           });
-        } catch {
-          // fall through to workflow-level failure
-        }
+        } catch {}
       }
     }
 
@@ -591,20 +588,6 @@ export class RunContinuationService {
     return await this.waiters.waitForWebhookResponse(runId);
   }
 
-  /**
-   * Re-activate a previously suspended run item with a human decision.
-   *
-   * Called by the HITL resume endpoint. This method:
-   * 1. Loads `PersistedRunState` and locates the suspension entry by `taskId`.
-   * 2. Removes the entry from the `suspension` array; if empty, run stays `"suspended"` until
-   *    enqueue flips it to `"pending"`.
-   * 3. Writes `pendingResume` onto the state so `NodeExecutionRequestHandlerService` can
-   *    splice `resumeContext` into the node's execution context.
-   * 4. Reconstructs the original input from `outputsByNode` of the upstream node and
-   *    enqueues a new activation via `activationEnqueueService`.
-   *
-   * @throws if the run is not found, not suspended, or the `taskId` is unknown.
-   */
   async resumeRun(args: { runId: RunId; taskId: string; resumeContext: ResumeContext }): Promise<RunResult> {
     const state = await this.workflowExecutionRepository.load(args.runId);
     if (!state) throw new Error(`Unknown runId: ${args.runId}`);
@@ -626,8 +609,6 @@ export class RunContinuationService {
       throw new Error(`Node ${suspensionEntry.nodeId} is not a runnable node`);
     }
 
-    // Reconstruct input: find the parent node that fed this node and use its main output.
-    // The single-item input corresponds to `itemIndex` in the original activation batch.
     const data = this.runDataFactory.create(state.outputsByNode);
     const limits = this.resolveEngineLimitsFromState(state);
     const base = this.runExecutionContextFactory.create({
@@ -644,13 +625,10 @@ export class RunContinuationService {
       testContext: state.executionOptions?.testContext,
     });
 
-    // Find the original input items for this node from upstream outputs.
-    // Use the workflow edges to resolve the parent node. If no parent found, fall back to empty.
     const parentEdges = wf.edges.filter((e) => e.to.nodeId === suspensionEntry.nodeId);
     const parentNodeId = parentEdges[0]?.from.nodeId;
     const parentOutputPort = parentEdges[0]?.from.output ?? "main";
     const allParentItems = parentNodeId ? (data.getOutputItems(parentNodeId, parentOutputPort) ?? []) : [];
-    // Each suspended item gets its own resume; pass the single item at itemIndex.
     const resumeInput =
       allParentItems.length > suspensionEntry.itemIndex ? [allParentItems[suspensionEntry.itemIndex]!] : allParentItems;
 
@@ -663,10 +641,6 @@ export class RunContinuationService {
 
     const remainingSuspensions = (state.suspension ?? []).filter((s) => s.taskId !== args.taskId);
 
-    // Thread resumeContext into the execution context so the inline scheduler path
-    // (InlineDrivingScheduler) delivers it directly to the node's ctx.resumeContext.
-    // On the worker path (BullMQ), NodeExecutionRequestHandlerService re-derives it
-    // from state.pendingResume — passing it here is additive and harmless.
     const baseWithResume = { ...base, resumeContext: args.resumeContext };
 
     const batchId = `resume_${newActivationId}`;
@@ -683,6 +657,8 @@ export class RunContinuationService {
       input: resumeInput,
     });
 
+    this.parityGuard.assertNone(wf, [suspensionEntry.nodeId]);
+
     const { result, queuedSnapshot } = await this.activationEnqueueService.enqueueActivationWithSnapshot({
       runId: state.runId,
       workflowId: state.workflowId,
@@ -944,6 +920,7 @@ export class RunContinuationService {
     });
 
     try {
+      this.parityGuard.assertNone(args.workflow, [next.nodeId]);
       const { queuedSnapshot, result } = await this.activationEnqueueService.enqueueActivationWithSnapshot({
         runId: args.state.runId,
         workflowId: args.state.workflowId,
@@ -1084,10 +1061,6 @@ export class RunContinuationService {
     };
   }
 
-  /**
-   * Next activation could not be enqueued (e.g. input contract / mapping failed in the preparer).
-   * Marks the target node failed and terminates the run.
-   */
   private async terminateRunAfterActivationEnqueueRejected(
     args: Readonly<{
       wf: WorkflowDefinition;
@@ -1166,11 +1139,6 @@ export class RunContinuationService {
     return result;
   }
 
-  /**
-   * Inspects node outputs for a `decision.status` written by `defineHumanApprovalNode`.
-   * Returns the first-class HITL node status and halt classification, or `undefined`
-   * when the node is not a HITL approval node.
-   */
   private resolveHitlStatus(outputs: NodeOutputs):
     | {
         nodeStatus: Extract<

package/src/orchestration/RunStartService.ts

@@ -277,13 +277,6 @@ export class RunStartService {
     currentState: RunCurrentState | undefined,
     mutableState: NonNullable<Awaited<ReturnType<WorkflowExecutionRepository["load"]>>>["mutableState"],
   ): RunCurrentState {
-    // Each `ConnectionInvocationRecord` represents a single, auditable LLM/tool call
-    // that must belong to exactly one run. Reruns start from a fresh invocation
-    // ledger so the new run only records what it actually invokes. The prior run's
-    // invocations remain queryable on that run's persisted state (their true owner).
-    // Carrying them over here would write duplicate `ExecutionInstance` rows whose
-    // primary key (`invocationId`) already exists under the previous run, causing a
-    // `Unique constraint failed on the fields: (instance_id)` violation on first save.
     return {
       outputsByNode: { ...(currentState?.outputsByNode ?? {}) },
       nodeSnapshotsByNodeId: { ...(currentState?.nodeSnapshotsByNodeId ?? {}) },