@codemation/core 0.14.0 → 0.15.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/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/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 ?? {}) },

package/src/orchestration/TestSuiteOrchestrator.ts

@@ -21,10 +21,6 @@ import { TestSuiteRunIdFactory } from "./TestSuiteRunIdFactory";
 
 const DEFAULT_CONCURRENCY = 4;
 
-/**
- * Engine-facade subset the orchestrator needs. Kept narrow on purpose so unit tests can
- * substitute a fake without depending on the full Engine wiring.
- */
 export interface TestSuiteOrchestratorEngine {
   runWorkflow(
     wf: WorkflowDefinition,
@@ -61,15 +57,6 @@ export interface RunTestSuiteArgs {
   readonly signal?: AbortSignal;
 }
 
-/**
- * Drives a {@link TestTriggerNodeConfig.generateItems} iterable into one workflow run per item,
- * with bounded concurrency. Pure engine logic — no persistence, no HTTP, no UI. Hosts adapt by
- * subscribing to {@link RunEventBus} and writing rows on `testSuite*` / `testCase*` / `nodeCompleted`.
- *
- * Cancellation: the supplied `AbortSignal` aborts the source iterable (so credentialed pulls bail)
- * and stops scheduling further cases. In-flight cases are awaited; engine-level cancellation of
- * an already-dispatched run is not yet wired (Phase 2).
- */
 export class TestSuiteOrchestrator {
   constructor(
     private readonly engine: TestSuiteOrchestratorEngine,
@@ -282,10 +269,6 @@ export class TestSuiteOrchestrator {
       terminal = await this.engine.waitForCompletion(runId);
     }
 
-    // RunResult.status from the engine narrows to "completed" | "failed" | "halted" here; widening to
-    // "errored" / "cancelled" happens outside this code path (tracker downgrade for assertion
-    // failures; outer abort handling for cancelled). Halted runs are treated as "failed" for
-    // test case status purposes.
     const status: TestCaseRunStatus = terminal.status === "completed" ? "succeeded" : "failed";
     await this.publish({
       kind: "testCaseCompleted",
@@ -331,7 +314,6 @@ export class TestSuiteOrchestrator {
     return this.currentDate().toISOString();
   }
 
-  /** Defensive label resolver — author-supplied callbacks throw / return non-strings; we tolerate both. */
   private resolveCaseLabel(config: TestTriggerNodeConfig<unknown>, item: Item<unknown>): string | undefined {
     if (typeof config.caseLabel !== "function") return undefined;
     try {

package/src/orchestration/TestSuiteRunIdFactory.ts

@@ -1,9 +1,5 @@
 import type { TestSuiteRunId } from "../contracts/testTriggerTypes";
 
-/**
- * Mints unique TestSuiteRun identifiers. Separated from {@link import("../types").RunIdFactory}
- * so suite ids and per-case workflow run ids never alias.
- */
 export class TestSuiteRunIdFactory {
   makeTestSuiteRunId(): TestSuiteRunId {
     return `tsr_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 10)}`;

package/src/orchestration/TriggerRuntimeService.ts

@@ -26,7 +26,7 @@ import type { NodeRunStateWriterFactory } from "../execution/NodeRunStateWriterF
 import type { EngineExecutionLimitsPolicy } from "../policies/executionLimits/EngineExecutionLimitsPolicy";
 import type { PollingTriggerRuntime } from "../triggers/polling/PollingTriggerRuntime";
 import type { PollingTriggerDedupWindow } from "../triggers/polling/PollingTriggerDedupWindow";
-import type { PollingTriggerHandle } from "../contracts/runtimeTypes";
+import type { PollingTriggerHandle, TriggerPollingPort } from "../contracts/runtimeTypes";
 
 export interface TriggerEmitHandler {
   emit(workflow: WorkflowDefinition, triggerNodeId: NodeId, items: Items): Promise<void>;
@@ -268,7 +268,7 @@ export class TriggerRuntimeService {
 
   private buildPollingHandle(trigger: TriggerInstanceId, emit: (items: Items) => Promise<void>): PollingTriggerHandle {
     const runtime = this.pollingTriggerRuntime;
-    return {
+    const handle: PollingTriggerHandle = {
       dedup: this.pollingTriggerDedupWindow,
       start: async (args) => {
         this.registerTriggerCleanupHandle(trigger, {
@@ -279,6 +279,7 @@ export class TriggerRuntimeService {
         return runtime.start({ trigger, emit, ...args });
       },
     };
+    return handle satisfies TriggerPollingPort;
   }
 
   private isTestableTriggerNode(node: TriggerNode): node is TestableTriggerNode<TriggerNodeConfig> {

package/src/planning/CurrentStateFrontierPlanner.ts

@@ -19,7 +19,6 @@ import { WorkflowTopology } from "./WorkflowTopologyPlanner";
 export class CurrentStateFrontierPlanner {
   constructor(private readonly topology: WorkflowTopology) {}
 
-  /** Composition-root-friendly factory (avoids `new` at orchestration call sites under ESLint manual-DI rules). */
   static createFromTopology(topology: WorkflowTopology): CurrentStateFrontierPlanner {
     return new CurrentStateFrontierPlanner(topology);
   }

package/src/planning/RunQueuePlanner.ts

@@ -150,12 +150,6 @@ export class RunQueuePlanner {
     }
   }
 
-  /**
-   * Matches `CurrentStateFrontierPlanner.buildFrontierQueue`: anything that is not exactly one input
-   * port named `in` participates in multi-port collect (Merge after `If` branches, etc.). Routing must
-   * not depend solely on `nodeInstances.get(toNodeId)?.executeMulti`, or a Merge can be enqueued as a
-   * single-input job and `NodeExecutor` will call `execute` on a multi-input-only implementation.
-   */
   private usesTopologyCollectMerge(toNodeId: NodeId): boolean {
     const expectedInputs = this.topology.expectedInputsByNode.get(toNodeId) ?? [];
     if (expectedInputs.length !== 1 || expectedInputs[0] !== "in") {

package/src/policies/executionLimits/EngineExecutionLimitsPolicy.ts

@@ -7,7 +7,6 @@ export interface EngineExecutionLimitsPolicyConfig {
   readonly hardMaxSubworkflowDepth: number;
 }
 
-/** Framework defaults for {@link EngineExecutionLimitsPolicy} (merged with host `runtime.engineExecutionLimits`). */
 export const ENGINE_EXECUTION_LIMITS_DEFAULTS: EngineExecutionLimitsPolicyConfig = {
   defaultMaxNodeActivations: 100_000,
   hardMaxNodeActivations: 100_000,
@@ -15,16 +14,9 @@ export const ENGINE_EXECUTION_LIMITS_DEFAULTS: EngineExecutionLimitsPolicyConfig
   hardMaxSubworkflowDepth: 32,
 };
 
-/**
- * Resolves per-run execution limits: defaults, hard ceilings, and subworkflow depth for new runs.
- */
 export class EngineExecutionLimitsPolicy {
   constructor(private readonly config: EngineExecutionLimitsPolicyConfig = ENGINE_EXECUTION_LIMITS_DEFAULTS) {}
 
-  /**
-   * Effective options for a new root run (depth 0): defaults merged with engine ceilings.
-   * Replaces a separate one-method factory for root-run bootstrap.
-   */
   createRootExecutionOptions(): RunExecutionOptions {
     return this.mergeExecutionOptionsForNewRun(undefined, undefined);
   }

package/src/policies/executionLimits/EngineExecutionLimitsPolicyFactory.ts

@@ -4,9 +4,6 @@ import {
   type EngineExecutionLimitsPolicyConfig,
 } from "./EngineExecutionLimitsPolicy";
 
-/**
- * Builds {@link EngineExecutionLimitsPolicy} by merging {@link ENGINE_EXECUTION_LIMITS_DEFAULTS} with optional `overrides` (e.g. host `runtime.engineExecutionLimits`).
- */
 export class EngineExecutionLimitsPolicyFactory {
   create(overrides?: Partial<EngineExecutionLimitsPolicyConfig>): EngineExecutionLimitsPolicy {
     return new EngineExecutionLimitsPolicy({ ...ENGINE_EXECUTION_LIMITS_DEFAULTS, ...overrides });

package/src/runStorage/RunSummaryMapper.ts

@@ -1,7 +1,6 @@
 import { RunFinishedAtFactory } from "../contracts/runFinishedAtFactory";
 import type { PersistedRunState, RunSummary } from "../types";
 
-/** Maps persisted run state to API run summaries for listings. */
 export class RunSummaryMapper {
   static fromPersistedState(state: PersistedRunState): RunSummary {
     return {

package/src/runtime/EngineFactory.ts

@@ -5,6 +5,7 @@ import { PollingTriggerRuntime } from "../triggers/polling/PollingTriggerRuntime
 import { NoOpPollingTriggerLogger } from "../triggers/polling/PollingTriggerLogger";
 import { MissingRuntimeFallbacks } from "../workflowSnapshots/MissingRuntimeFallbacksFactory";
 import { MissingRuntimeExecutionMarker } from "../workflowSnapshots/MissingRuntimeExecutionMarker";
+import { MissingRuntimeParityGuard } from "../workflowSnapshots/MissingRuntimeParityGuard";
 import { WorkflowSnapshotCodec } from "../workflowSnapshots/WorkflowSnapshotCodec";
 import { WorkflowSnapshotResolver } from "../workflowSnapshots/WorkflowSnapshotResolver";
 import { ActivationEnqueueService } from "../execution/ActivationEnqueueService";
@@ -28,22 +29,12 @@ import { Engine } from "../orchestration/Engine";
 import { CredentialResolverFactory } from "../execution/CredentialResolverFactory";
 import { NodeRunStateWriterFactory } from "../execution/NodeRunStateWriterFactory";
 
-/**
- * {@link EngineDeps} plus optional overrides for workflow-snapshot materialization.
- * Overrides keep default construction in this factory while allowing tests or advanced wiring to inject instances.
- */
 export type EngineCompositionDeps = EngineDeps & {
   workflowSnapshotCodec?: WorkflowSnapshotCodec;
   missingRuntimeFallbacks?: MissingRuntimeFallbacks;
-  /** When set, used for run-start, trigger, and continuation limit defaults. */
   executionLimitsPolicy?: EngineExecutionLimitsPolicy;
 };
 
-/**
- * Composes the {@link Engine} graph from {@link EngineCompositionDeps}. Production wiring usually goes through
- * {@link import("../bootstrap/runtime/EngineRuntimeRegistrar").EngineRuntimeRegistrar}; this factory remains for tests and custom composition.
- * Exported from `@codemation/core/bootstrap` (not the main `@codemation/core` barrel).
- */
 export class EngineFactory {
   create(deps: EngineCompositionDeps): Engine {
     const waiters = new EngineWaiters();
@@ -65,7 +56,9 @@ export class EngineFactory {
       missingRuntimeFallbacks,
     );
 
-    const semantics = new RunStateSemantics(new MissingRuntimeExecutionMarker());
+    const missingRuntimeExecutionMarker = new MissingRuntimeExecutionMarker();
+    const semantics = new RunStateSemantics(missingRuntimeExecutionMarker);
+    const parityGuard = new MissingRuntimeParityGuard(missingRuntimeExecutionMarker);
     const nodeActivationRequestInputPreparer = new NodeActivationRequestInputPreparer(deps.workflowNodeInstanceFactory);
     const activationEnqueueService = new ActivationEnqueueService(
       deps.activationScheduler,
@@ -124,6 +117,7 @@ export class EngineFactory {
       policyErrorServices,
       terminalPersistence,
       executionLimitsPolicy,
+      parityGuard,
     );
     const nodeExecutionRequestHandler = new NodeExecutionRequestHandlerService(
       deps.workflowExecutionRepository,
@@ -135,6 +129,7 @@ export class EngineFactory {
       deps.nodeExecutor,
       runContinuationService,
       executionLimitsPolicy,
+      parityGuard,
     );
 
     const pollingTriggerLogger = deps.pollingTriggerLogger ?? new NoOpPollingTriggerLogger();

package/src/runtime/RunIntentService.ts

@@ -219,10 +219,6 @@ export class RunIntentService {
     ]);
   }
 
-  /**
-   * Webhook-triggered runs always force inline execution first.
-   * This is the highest-precedence scheduler override: it wins over node hints and container defaults.
-   */
   private createWebhookExecutionOptions(): RunExecutionOptions {
     return {
       localOnly: true,

package/src/runtime/WorkflowRepositoryWebhookTriggerMatcher.ts

@@ -12,10 +12,6 @@ import type {
   WorkflowRepository,
 } from "../types";
 
-/**
- * Resolves webhook HTTP routes from the live workflow repository (no trigger setup / registration).
- * Maintains an in-memory index keyed by user-defined endpoint path for O(1) lookups after reload.
- */
 export class WorkflowRepositoryWebhookTriggerMatcher implements WebhookTriggerMatcher {
   private readonly routeByPath = new Map<string, WebhookInvocationMatch>();
   private engineRoutesActive = false;

package/src/runtime-types/InjectableRuntimeDecoratorComposerRegistry.ts

@@ -7,10 +7,6 @@ import type {
   PersistedRuntimeTypeKind,
 } from "./persistedRuntimeTypeModelRegistry";
 
-/**
- * Applies both tsyringe injectability and persisted runtime metadata in one decorator.
- * This keeps runtime-type decorators thin while still recording enough data for snapshot hydration.
- */
 export class InjectableRuntimeDecoratorComposer {
   static compose(
     kind: PersistedRuntimeTypeKind,

package/src/runtime-types/PersistedRuntimeTypeMetadataStoreRegistry.ts

@@ -9,10 +9,6 @@ import {
 import { PersistedRuntimeTypeNameResolver } from "./PersistedRuntimeTypeNameResolver";
 import { StackTraceCallSitePathResolver } from "./StackTraceCallSitePathResolver";
 
-/**
- * Defines and retrieves persisted runtime metadata on decorated classes.
- * The metadata is attached as a non-enumerable property so runtime objects stay serializable.
- */
 export class PersistedRuntimeTypeMetadataStore {
   static define(
     target: DecoratedRuntimeType,

package/src/runtime-types/PersistedRuntimeTypeNameResolver.ts

@@ -1,6 +1,5 @@
 import type { DecoratedRuntimeType } from "./persistedRuntimeTypeModelRegistry";
 
-/** Resolves the persisted type name from either an explicit override or the class name itself. */
 export class PersistedRuntimeTypeNameResolver {
   static resolve(target: DecoratedRuntimeType, override: string | undefined): string {
     const resolved = override ?? target.name;

package/src/runtime-types/persistedRuntimeTypeModelRegistry.ts

@@ -1,9 +1,7 @@
-/** Shared metadata key used to attach persisted runtime-type information to decorated classes. */
 export const persistedRuntimeTypeMetadataKey = Symbol.for("codemation.core.persistedRuntimeTypeMetadata");
 
 export type DecoratedRuntimeType = Readonly<{ name?: string }> & object;
 
-/** Categories of runtime classes that can be discovered and rehydrated from persisted snapshots. */
 export type PersistedRuntimeTypeKind = "node" | "tool" | "chatModel";
 
 export interface PersistedRuntimeTypeDecoratorOptions {
@@ -12,7 +10,6 @@ export interface PersistedRuntimeTypeDecoratorOptions {
   readonly moduleUrl?: string;
 }
 
-/** Serialized metadata attached to a decorated runtime type. */
 export interface PersistedRuntimeTypeMetadata {
   readonly persistedName: string;
   readonly kind: PersistedRuntimeTypeKind;
@@ -20,7 +17,6 @@ export interface PersistedRuntimeTypeMetadata {
   readonly sourceHint?: string;
 }
 
-/** Normalizes decorator options so persistence metadata has stable defaults. */
 export class PersistedRuntimeTypeDecoratorDefaults {
   static readonly appPackageName = "app";
 

package/src/runtime-types/runtimeTypeDecorators.types.ts

@@ -6,36 +6,24 @@ import type {
 import { InjectableRuntimeDecoratorComposer } from "./InjectableRuntimeDecoratorComposerRegistry";
 import { PersistedRuntimeTypeMetadataStore } from "./PersistedRuntimeTypeMetadataStoreRegistry";
 
-/**
- * Public decorator entry points for runtime-discoverable classes.
- *
- * These exports intentionally stay as plain decorator factory functions because TypeScript's
- * `@decorator()` syntax expects callable values rather than instance methods. The helpers below
- * attach DI metadata and persisted-name metadata in one step so hosts can discover nodes, tools,
- * and chat models without duplicating registration boilerplate.
- */
 export type {
   PersistedRuntimeTypeDecoratorOptions,
   PersistedRuntimeTypeKind,
   PersistedRuntimeTypeMetadata,
 } from "./persistedRuntimeTypeModelRegistry";
 
-/** Reads persisted runtime metadata from a decorated class or object. */
 export function getPersistedRuntimeTypeMetadata(target: unknown): PersistedRuntimeTypeMetadata | undefined {
   return PersistedRuntimeTypeMetadataStore.get(target);
 }
 
-/** Marks a class as a persisted node runtime type and an injectable tsyringe service. */
 export function node(options: PersistedRuntimeTypeDecoratorOptions = {}): ClassDecorator {
   return InjectableRuntimeDecoratorComposer.compose("node", options, import.meta.url);
 }
 
-/** Marks a class as a persisted tool runtime type and an injectable tsyringe service. */
 export function tool(options: PersistedRuntimeTypeDecoratorOptions = {}): ClassDecorator {
   return InjectableRuntimeDecoratorComposer.compose("tool", options, import.meta.url);
 }
 
-/** Marks a class as a persisted chat-model runtime type and an injectable tsyringe service. */
 export function chatModel(options: PersistedRuntimeTypeDecoratorOptions = {}): ClassDecorator {
   return InjectableRuntimeDecoratorComposer.compose("chatModel", options, import.meta.url);
 }

package/src/scheduler/ConfigDrivenOffloadPolicy.ts

@@ -20,7 +20,6 @@ export class ConfigDrivenOffloadPolicy implements NodeOffloadPolicy {
     if (hint === "local") return { mode: "local" };
     if (hint === "worker") return { mode: "worker", queue };
 
-    // If a queue is specified, treat it as an implicit worker hint.
     if (queue) return { mode: "worker", queue };
 
     return { mode: this.defaultMode };

package/src/scheduler/DefaultDrivingScheduler.ts

@@ -60,12 +60,6 @@ export class DefaultDrivingScheduler implements NodeActivationScheduler {
     return await this.prepareInlineDispatch(request);
   }
 
-  /**
-   * Scheduler precedence is explicit:
-   * 1. run-intent override (`executionOptions.localOnly`)
-   * 2. node-level execution hint / queue policy
-   * 3. container-default scheduler policy fallback
-   */
   private async selectScheduler(request: NodeActivationRequest): Promise<SchedulerSelection> {
     if (request.executionOptions?.localOnly) {
       return {