@codemation/core 0.14.0 → 0.15.0

package/src/scheduler/InlineDrivingScheduler.ts

@@ -24,14 +24,6 @@ export class InlineDrivingScheduler implements NodeActivationScheduler {
     this.continuation = continuation;
   }
 
-  /**
-   * Prevents new drain cycles from being scheduled and waits for all currently-running
-   * drains to complete. Call before closing the DB connection or rolling back test transactions
-   * to ensure no in-flight writes hit a closed/rolled-back connection.
-   *
-   * Bounded: only the drains already in-flight at call time are awaited. Runs that keep
-   * re-scheduling will not schedule new work once stopped is set.
-   */
   async stop(): Promise<void> {
     this.stopped = true;
     if (this.activeDrainPromises.size > 0) {
@@ -58,9 +50,6 @@ export class InlineDrivingScheduler implements NodeActivationScheduler {
     this.scheduledRuns.delete(runId);
     try {
       const q = this.queuesByRunId.get(runId) ?? [];
-      // Process exactly one activation per drain so the event loop gets a full cycle
-      // (poll phase → I/O) between activations. Synchronous SQLite writes otherwise
-      // block HTTP responses and WS frames for the entire run duration.
       if (q.length === 0) return;
       const next = q.shift()!;
       const { request } = next;
@@ -98,8 +87,6 @@ export class InlineDrivingScheduler implements NodeActivationScheduler {
       return;
     }
     this.scheduledRuns.add(runId);
-    // Use setImmediate so the activation fires in the check phase (after poll/I/O),
-    // giving queued HTTP writes and WS frames a chance to flush between activations.
     setImmediate(() => {
       this.scheduledRuns.delete(runId);
       if (this.stopped) return;

package/src/serialization/ItemsInputNormalizer.ts

@@ -1,11 +1,6 @@
 import type { Item, Items } from "../contracts/workflowTypes";
 import { injectable } from "../di";
 
-/**
- * Normalizes external inputs into the engine's canonical `Items` shape.
- * Used at host and builder boundaries where callers may provide either a raw value,
- * a single item-like object, or an array of item-like values.
- */
 @injectable()
 export class ItemsInputNormalizer {
   normalize(raw: unknown): Items {

package/src/testing/CapturingScheduler.ts

@@ -1,8 +1,5 @@
 import type { NodeExecutionRequest, NodeExecutionScheduler } from "../types";
 
-/**
- * Test scheduler that records enqueue requests without executing a real queue.
- */
 export class CapturingScheduler implements NodeExecutionScheduler {
   lastRequest: NodeExecutionRequest | undefined;
   requests: NodeExecutionRequest[] = [];

package/src/testing/EngineTestKitRunIdFactory.ts

@@ -1,8 +1,5 @@
 import type { RunIdFactory } from "../types";
 
-/**
- * @internal Test harness id factory shared by registrar kit wiring.
- */
 export class EngineTestKitRunIdFactory implements RunIdFactory {
   private runCounter = 0;
   private activationCounter = 0;

package/src/testing/ItemHarnessNode.ts

@@ -2,9 +2,6 @@ import type { Item, RunnableNode, RunnableNodeExecuteArgs } from "../types";
 
 import type { ItemHarnessNodeConfig } from "./ItemHarnessNodeConfig";
 
-/**
- * Item-mode harness node for engine tests (see {@link ItemHarnessNodeConfig}).
- */
 export class ItemHarnessNode implements RunnableNode<ItemHarnessNodeConfig<any, any>> {
   readonly kind = "node" as const;
   readonly outputPorts = ["main"] as const;

package/src/testing/ItemHarnessNodeConfig.ts

@@ -5,10 +5,6 @@ import type { Item, Items, NodeExecutionContext, RunnableNodeConfig } from "../t
 
 import { ItemHarnessNode } from "./ItemHarnessNode";
 
-/**
- * Item-mode harness node config for engine tests: engine applies {@link RunnableNodeConfig.inputSchema},
- * then {@link ItemHarnessNode.execute} per item.
- */
 export class ItemHarnessNodeConfig<TIn = unknown, TOut = unknown> implements RunnableNodeConfig<TIn, TOut> {
   readonly kind = "node" as const;
   readonly type: TypeToken<unknown> = ItemHarnessNode;

package/src/testing/PrefixedSequentialIdGenerator.ts

@@ -1,6 +1,3 @@
-/**
- * Deterministic `run_1`, `act_1`-style ids for test harness factories.
- */
 export class PrefixedSequentialIdGenerator {
   private n = 0;
 

package/src/testing/RegistrarEngineTestKit.types.ts

@@ -39,12 +39,10 @@ export type EngineTestKitOptions = Partial<{
   makeRunId: () => string;
   makeActivationId: () => string;
   workflowRunner: EngineWorkflowRunnerService;
-  /** Passed to engine factory so integration tests can assert host-configured limits propagate. */
   executionLimitsPolicy: EngineExecutionLimitsPolicy;
 }>;
 
 export type RegistrarEngineTestKitOptions = EngineTestKitOptions & {
-  /** Passed to {@link EngineRuntimeRegistrar.register}. */
   registrarOptions?: EngineRuntimeRegistrationOptions;
 };
 

package/src/testing/RejectingCredentialSessionService.ts

@@ -1,9 +1,5 @@
 import type { CredentialSessionService } from "../contracts/credentialTypes";
 
-/**
- * Test harness default: rejects any credential lookup so missing bindings fail loudly.
- * Prefer registering a real {@link CredentialSessionService} in integration scenarios.
- */
 export class RejectingCredentialSessionService implements CredentialSessionService {
   async getSession<TSession = unknown>(
     args: Readonly<{ workflowId: string; nodeId: string; slotKey: string }>,

package/src/testing/SubWorkflowRunnerTestNode.ts

@@ -4,9 +4,6 @@ import type { TypeToken } from "../di";
 import type { Item, NodeId, RunnableNode, RunnableNodeConfig, RunnableNodeExecuteArgs, WorkflowId } from "../types";
 import { emitPorts } from "../contracts/emitPorts";
 
-/**
- * Test harness subworkflow runner (mirrors integration patterns; lives under {@link "@codemation/core/testing"}).
- */
 export class SubWorkflowRunnerConfig<TInputJson = unknown, TOutputJson = unknown> implements RunnableNodeConfig<
   TInputJson,
   TOutputJson

package/src/testing/WorkflowTestHarnessManualTrigger.ts

@@ -9,9 +9,6 @@ import type {
   TriggerSetupContext,
 } from "../types";
 
-/**
- * Minimal pass-through manual trigger for {@link WorkflowTestKit.runNode}; emits input items unchanged.
- */
 export class WorkflowTestHarnessManualTriggerConfig implements TriggerNodeConfig<unknown> {
   readonly kind = "trigger" as const;
   readonly type: TypeToken<unknown> = WorkflowTestHarnessManualTriggerNode;

package/src/testing/WorkflowTestKitBuilder.ts

@@ -41,10 +41,6 @@ export class WorkflowTestKit {
     return this.handle.runStore;
   }
 
-  /**
-   * Registers {@link import("../authoring/defineNode.types").DefinedNode} implementations on the same DI container used by the engine
-   * (same pattern as `plugin.register({ registerNode })` in the host).
-   */
   registerDefinedNodes(definitions: ReadonlyArray<DefinedNodeRegistration>): void {
     const ctx = this.nodeRegistrationContextFactory.create(this.handle.dependencyContainer);
     for (const def of definitions) {

package/src/testing/WorkflowTestKitRunNodeWorkflowFactory.ts

@@ -6,9 +6,6 @@ import { WorkflowTestHarnessManualTriggerConfig } from "./WorkflowTestHarnessMan
 const defaultInlineWorkflowId = "codemation.testing.workflowkit.inline" as WorkflowId;
 const defaultInlineWorkflowName = "WorkflowTestKit inline";
 
-/**
- * Builds the minimal trigger → runnable workflow used by {@link import("./WorkflowTestKit").WorkflowTestKit.runNode}.
- */
 export class WorkflowTestKitRunNodeWorkflowFactory {
   build(args: { node: RunnableNodeConfig; workflowId?: WorkflowId; workflowName?: string }): WorkflowDefinition {
     const workflowId = args.workflowId ?? defaultInlineWorkflowId;

package/src/testing.ts

@@ -1,6 +1,3 @@
-/**
- * Test-only adapters and helpers. Not part of the supported production public API.
- */
 export { InMemoryLiveWorkflowRepository } from "./runtime/InMemoryLiveWorkflowRepository";
 export { WorkflowSnapshotCodec as PersistedWorkflowSnapshotFactory } from "./workflowSnapshots/WorkflowSnapshotCodec";
 export { RejectingCredentialSessionService } from "./testing/RejectingCredentialSessionService";

package/src/triggers/polling/PollingTriggerDedupWindow.ts

@@ -1,7 +1,3 @@
-/**
- * Merges processed-ID windows for polling triggers, capping the total to avoid unbounded growth.
- * Plugin code receives an instance of this class via {@link PollingTriggerHandle.dedup}.
- */
 export class PollingTriggerDedupWindow {
   static readonly defaultCapN = 2000;
 

package/src/triggers/polling/PollingTriggerLogger.ts

@@ -1,8 +1,3 @@
-/**
- * Minimal logger surface for the polling-trigger runtime.
- * Hosts supply this via {@link EngineDeps.pollingTriggerLogger};
- * when absent the runtime is silent.
- */
 export interface PollingTriggerLogger {
   info(message: string): void;
   warn(message: string): void;

package/src/triggers/polling/PollingTriggerRuntime.ts

@@ -19,11 +19,6 @@ export interface PollingTriggerStartArgs<TState, TItem> {
   emit: (items: Items) => Promise<void>;
 }
 
-/**
- * Generic polling-trigger runtime. Owns the set-interval loop, overlap guard, and persistence.
- * Constructed by {@link import("../../runtime/EngineFactory").EngineFactory} and exposed to plugin
- * authors via {@link import("../../contracts/runtimeTypes").TriggerSetupContext}.polling.
- */
 export class PollingTriggerRuntime {
   private readonly activeTriggers = new Set<string>();
   private readonly intervalsByTrigger = new Map<string, ReturnType<typeof setInterval>>();

package/src/types/index.ts

@@ -1,9 +1,7 @@
-// Re-export pure-type contracts first (available via @codemation/core/contracts subpath)
 export * from "../contracts";
 export * from "../contracts/mcpTypes";
 export type { CollectionStore, CollectionsContext } from "../contracts/collectionTypes";
 
-// Additional runtime exports not included in contracts (factory classes, DSL builders, etc.)
 export * from "../contracts/emitPorts";
 export * from "../contracts/itemMeta";
 export * from "../contracts/itemExpr";
@@ -17,10 +15,6 @@ export * from "../contracts/NoOpCostTrackingTelemetryFactory";
 export * from "../contracts/NoOpExecutionTelemetryFactory";
 export * from "../contracts/runFinishedAtFactory";
 export * from "../contracts/workflowActivationPolicy";
-// telemetryTypes and workflowTypes also have runtime exports (No-Op telemetry classes,
-// attribute-name registries, `nodeRef` factory, unique-symbol type tags) — `contracts.ts`
-// already re-exports them with `export type *` for the slim subpath; re-export with the
-// full `export *` here so back-compat for `@codemation/core` (root) consumers is preserved.
 export * from "../contracts/telemetryTypes";
 export * from "../contracts/workflowTypes";
 export * from "../workflow";

package/src/validation/WorkflowEdgePortValidator.ts

@@ -34,10 +34,6 @@ export class WorkflowEdgePortValidator {
     return { valid: errors.length === 0, errors };
   }
 
-  /**
-   * Returns the declared output ports for a node, or null if the node is
-   * unknown / has no declared ports (legacy nodes — treat as unconstrained).
-   */
   private allowedOutputPorts(node: NodeDefinition | undefined): ReadonlyArray<string> | null {
     if (!node) {
       return null;
@@ -46,7 +42,6 @@ export class WorkflowEdgePortValidator {
     if (declared && declared.length > 0) {
       return declared as string[];
     }
-    // No declared ports — treat as unconstrained (legacy nodes default to "main").
     return null;
   }
 }

package/src/workflow/definition/ConnectionInvocationIdFactory.ts

@@ -1,17 +1,10 @@
 import type { NodeId } from "../../types";
 
-/**
- * Unique ids for persisted connection invocation history rows (LLM/tool calls under an owning node).
- *
- * Uses Web Crypto's `randomUUID` so this module is safe in browser-bundle contexts —
- * paired with `NodeIterationIdFactory` which had the same `node:crypto` regression.
- */
 export class ConnectionInvocationIdFactory {
   static create(): string {
     return `cinv_${globalThis.crypto.randomUUID()}`;
   }
 
-  /** Deterministic id for tests when a stable sequence is needed. */
   static createForTest(runId: string, connectionNodeId: NodeId, sequence: number): string {
     return `cinv_${runId}_${connectionNodeId}_${sequence}`;
   }

package/src/workflow/definition/ConnectionNodeIdFactory.ts

@@ -1,9 +1,5 @@
 import type { NodeId } from "../../types";
 
-/**
- * Deterministic ids for workflow connection-owned child nodes (LLM slot, tools, etc.).
- * These are stable across loads.
- */
 export class ConnectionNodeIdFactory {
   static readonly connectionSegment = "__conn__" as const;
 
@@ -77,12 +73,10 @@ export class ConnectionNodeIdFactory {
     return { parentNodeId, normalizedToolName };
   }
 
-  /** True when `nodeId` is a connection-owned child of `parentNodeId` (LLM or tool slot). */
   static isConnectionOwnedDescendantOf(parentNodeId: NodeId, nodeId: NodeId): boolean {
     return nodeId.startsWith(`${parentNodeId}${this.connectionSegment}`);
   }
 
-  /** Normalizes a tool display name to a stable id segment. */
   static normalizeToolName(toolName: string): string {
     return (
       toolName

package/src/workflow/definition/NodeIterationIdFactory.ts

@@ -1,27 +1,14 @@
 import type { NodeId } from "../../types";
 
-/**
- * Unique ids for one per-item iteration of a runnable node's execute loop.
- *
- * Activations are per-batch (one scheduled execution of a node, possibly with N items).
- * Iterations refine that to one identifier per item-index inside the batch loop, so per-item
- * connection invocations and telemetry can be grouped without time-window heuristics.
- *
- * Uses Web Crypto's `randomUUID` (Node 19+ and all modern browsers) so this module is safe
- * to include in the browser entry. Importing `node:crypto` here previously leaked into the
- * canvas client bundle through `browser.ts` and OOM'd consumers' Turbopack builds.
- */
 export class NodeIterationIdFactory {
   static create(): string {
     return `iter_${globalThis.crypto.randomUUID()}`;
   }
 
-  /** Deterministic id for tests when a stable sequence is needed. */
   static createForTest(seed: string, sequence: number): string {
     return `iter_${seed}_${sequence}`;
   }
 
-  /** Deterministic id derived from a connection node id (for sub-agent / tool-call scopes). */
   static createForConnection(connectionNodeId: NodeId, sequence: number): string {
     return `iter_${connectionNodeId}_${sequence}`;
   }

package/src/workflow/definition/WorkflowExecutableNodeClassifier.ts

@@ -1,8 +1,5 @@
 import type { NodeDefinition, NodeId, WorkflowDefinition } from "../../types";
 
-/**
- * Derives which workflow nodes participate in the main execution graph vs connection-only children.
- */
 export class WorkflowExecutableNodeClassifier {
   private readonly connectionOwnedIds: ReadonlySet<NodeId>;
 
@@ -32,9 +29,6 @@ export class WorkflowExecutableNodeClassifier {
     return ids;
   }
 
-  /**
-   * Resolves the default start node: first trigger, else first executable node with no incoming edges from executable nodes.
-   */
   findDefaultExecutableStartNodeId(workflow: WorkflowDefinition): NodeId {
     const firstTrigger = workflow.nodes.find((n) => n.kind === "trigger" && this.isExecutableNodeId(n.id))?.id;
     if (firstTrigger) return firstTrigger;

package/src/workflow/dsl/ChainCursorResolver.ts

@@ -57,11 +57,6 @@ export class ChainCursor<TCurrentJson> {
     ]);
   }
 
-  /**
-   * Append a step whose output is MERGED onto `item.json` (shallow, output-wins) instead of
-   * replacing it — so earlier fields (e.g. trigger metadata) survive a transform/OCR/extraction
-   * node. Use for any node in a pipeline where you need data from before it.
-   */
   thenMerge<TOutputJson, TConfig extends RunnableNodeConfig<TCurrentJson, TOutputJson>>(
     config: TConfig,
   ): ChainCursor<TCurrentJson & RunnableNodeOutputJson<TConfig>> {
@@ -150,21 +145,6 @@ export class ChainCursor<TCurrentJson> {
     return new ChainCursor<TNextJson>(this.wf, nextEndpoints);
   }
 
-  /**
-   * Chainable shorthand for `.then(node.create(config, metadata?.name, metadata?.nodeId))`.
-   *
-   * Signals to readers that this step suspends the run and waits for a human decision.
-   * Throws at workflow-build time if `node` was not created via `defineHumanApprovalNode`.
-   *
-   * @example
-   * ```ts
-   * workflow
-   *   .trigger(...)
-   *   .humanApproval(inboxApproval, { title: "Approve?", body: "...", priority: "normal" })
-   *   .then(nextStep.create(...))
-   *   .build();
-   * ```
-   */
   humanApproval<
     TKey extends string,
     TConfig extends Record<string, unknown>,

package/src/workflow/dsl/NodeIdSlugifier.ts

@@ -1,12 +1,3 @@
-/**
- * Converts a human-readable node label into a stable, URL-safe identifier segment.
- *
- * Rules:
- * - Lowercase the entire string.
- * - Replace every run of characters outside `[a-z0-9]` with a single `-`.
- * - Strip any leading or trailing `-` characters.
- * - Return `""` for blank/empty input.
- */
 export const NodeIdSlugifier = {
   slugify(label: string): string {
     if (!label) return "";

package/src/workflow/dsl/WhenBuilder.ts

@@ -15,18 +15,15 @@ import { WorkflowBuilder } from "./WorkflowBuilder";
 import { ChainCursor } from "./ChainCursorResolver";
 import type { AnyRunnableNodeConfig, BooleanWhenOverloads, ValidStepSequence } from "./workflowBuilderTypes";
 
-/** Structurally identical to ChainCursorResolver's (unexported) ChainCursorEndpoint. */
 type WhenEndpoint = Readonly<{ node: NodeRef; output: OutputPortKey; inputPortHint?: InputPortKey }>;
 
 export class WhenBuilder<TCurrentJson> {
-  /** Tail endpoint of the arm this builder added (set by addBranch). */
   private armEndpoint: WhenEndpoint | undefined;
 
   constructor(
     private readonly wf: WorkflowBuilder,
     private readonly from: NodeRef,
     private readonly branchPort: OutputPortKey,
-    /** Tails of arms added by earlier `.when(...)` calls in this chain. */
     private readonly priorEndpoints: ReadonlyArray<WhenEndpoint> = [],
   ) {}
 
@@ -56,8 +53,6 @@ export class WhenBuilder<TCurrentJson> {
       });
     }
 
-    // An empty arm rejoins straight from the `from` node's branch port (mirrors the
-    // object-form `buildBranch` returning `{ end: cursor, endOutput: port }`).
     this.armEndpoint = prev
       ? { node: prev, output: "main", inputPortHint: this.branchPort }
       : { node: this.from, output: this.branchPort, inputPortHint: this.branchPort };
@@ -77,23 +72,12 @@ export class WhenBuilder<TCurrentJson> {
     return b;
   };
 
-  /**
-   * Continue the trunk after a boolean `.when(...)` branch chain, auto-merging EVERY branch
-   * tail accumulated across the chain into the next node — the same fan-in the object form
-   * produces. Typed as `ChainCursor<TCurrentJson>` (the pre-branch item type): boolean arms
-   * carry no output guard so the merged item type is underdetermined — use the object form
-   * `.when({ true: [...], false: [...] })` when you need a precise merged type inline.
-   */
   then<TOutputJson, TConfig extends RunnableNodeConfig<TCurrentJson, TOutputJson>>(
     config: TConfig,
   ): ChainCursor<RunnableNodeOutputJson<TConfig>> {
     return this.toCursor().then(config);
   }
 
-  /**
-   * Chainable human-approval step after a boolean `.when(...)` branch chain — merges every
-   * branch tail into the approval node. Mirrors `ChainCursor.humanApproval`.
-   */
   humanApproval<
     TKey extends string,
     TConfig extends Record<string, unknown>,
@@ -110,7 +94,6 @@ export class WhenBuilder<TCurrentJson> {
     return this.wf.build();
   }
 
-  /** Endpoints of every arm added so far in this chain (prior arms + this one). */
   private get accumulatedEndpoints(): ReadonlyArray<WhenEndpoint> {
     return this.armEndpoint ? [...this.priorEndpoints, this.armEndpoint] : this.priorEndpoints;
   }

package/src/workflow/dsl/WorkflowDefinitionError.ts

@@ -1,12 +1,3 @@
-/**
- * Thrown by {@link WorkflowBuilder.build} when the workflow definition is structurally invalid.
- *
- * Common causes:
- * - A node has an empty effective id (label is blank and no explicit `id` was given).
- * - Two or more nodes share the same effective id (label slugs collide or explicit ids clash).
- *
- * Fix: provide an explicit `id:` on the offending node configs.
- */
 export class WorkflowDefinitionError extends Error {
   constructor(message: string) {
     super(message);

package/src/workflow/dsl/workflowBuilderTypes.ts

@@ -1,29 +1,5 @@
 import type { RunnableNodeConfig, RunnableNodeOutputJson, TriggerNodeConfig } from "../../types";
 
-/**
- * Flags a node's config so its output is MERGED onto `item.json` (shallow, output-wins) instead of
- * replacing it — the config-level twin of {@link ChainCursor.thenMerge}.
- *
- * Unlike `.thenMerge` (a cursor method that only works on the trunk), `mergeForward` operates on a
- * bare config, so it is usable in ANY position — including inside a `.when({ true: [...] })` branch
- * arm, where the steps are a flat array of configs (not a cursor). Wrap a payload-REPLACING node
- * (e.g. an extractor) in `mergeForward(node.create(...))` so prior fields survive into the next step.
- *
- * The OUTPUT type becomes `TIn & TOut` (the intersection), mirroring `.thenMerge`'s return type at
- * the config level — so the next step in the branch array sees both the prior fields and the node's
- * output. The INPUT type stays `TIn` (the node still receives the pre-merge item).
- *
- * @example
- * ```ts
- * workflow
- *   .trigger(...)
- *   .when({
- *     true: [mergeForward(extractor.create(...))], // output merges onto item.json; { a } survives
- *     false: [...],
- *   })
- *   .build();
- * ```
- */
 export function mergeForward<TIn, TOut>(config: RunnableNodeConfig<TIn, TOut>): RunnableNodeConfig<TIn, TIn & TOut> {
   (config as { mergeJson?: boolean }).mergeJson = true;
   return config as unknown as RunnableNodeConfig<TIn, TIn & TOut>;

package/src/workflowSnapshots/MissingRuntimeParityGuard.ts

@@ -0,0 +1,24 @@
+import type { NodeId, WorkflowDefinition } from "../types";
+
+import { MissingRuntimeExecutionMarker } from "./MissingRuntimeExecutionMarker";
+import { type MissingRuntimeNodeDetail, WorkflowParityMismatchError } from "./WorkflowParityMismatchError";
+
+export class MissingRuntimeParityGuard {
+  constructor(private readonly marker: MissingRuntimeExecutionMarker) {}
+
+  assertNone(workflow: WorkflowDefinition, nodeIds?: ReadonlyArray<NodeId>): void {
+    const candidates = nodeIds ? workflow.nodes.filter((n) => nodeIds.includes(n.id)) : workflow.nodes;
+
+    const missing: MissingRuntimeNodeDetail[] = candidates
+      .filter((n) => this.marker.isMarked(n.config))
+      .map((n) => ({
+        nodeId: n.id,
+        kind: n.kind as "node" | "trigger",
+        missingTokenId: (n.config as Partial<{ missingTokenId: string }>).missingTokenId,
+      }));
+
+    if (missing.length > 0) {
+      throw new WorkflowParityMismatchError(missing);
+    }
+  }
+}

package/src/workflowSnapshots/PersistedWorkflowTokenRegistry.ts

@@ -8,9 +8,6 @@ export class PersistedWorkflowTokenRegistry {
   private readonly tokensById = new Map<PersistedTokenId, TypeToken<unknown>>();
   private readonly tokenIdsByToken = new Map<TypeToken<unknown>, PersistedTokenId>();
 
-  /**
-   * Register a token with its package ID. Token ID is inferred as `packageId::tokenName`.
-   */
   register(type: TypeToken<unknown>, packageId: string, persistedNameOverride?: string): PersistedTokenId {
     const tokenName = persistedNameOverride ?? this.displayNameForTypeToken(type);
     const tokenId = `${packageId}::${tokenName}` as PersistedTokenId;
@@ -19,9 +16,6 @@ export class PersistedWorkflowTokenRegistry {
     return tokenId;
   }
 
-  /**
-   * Register all decorated runtime types discovered in workflows.
-   */
   registerFromWorkflows(workflows: ReadonlyArray<WorkflowDefinition>): void {
     for (const workflow of workflows) {
       for (const node of workflow.nodes) {

package/src/workflowSnapshots/WorkflowParityMismatchError.ts

@@ -0,0 +1,18 @@
+import type { NodeId } from "../types";
+
+export type MissingRuntimeNodeDetail = {
+  nodeId: NodeId;
+  kind: "node" | "trigger";
+  missingTokenId: string | undefined;
+};
+
+export class WorkflowParityMismatchError extends Error {
+  readonly name = "WorkflowParityMismatchError";
+  readonly missingNodes: ReadonlyArray<MissingRuntimeNodeDetail>;
+
+  constructor(missingNodes: ReadonlyArray<MissingRuntimeNodeDetail>) {
+    const labels = missingNodes.map((n) => `${n.nodeId} (token: ${n.missingTokenId ?? "unknown"})`).join(", ");
+    super(`Workflow parity mismatch: nodes resolve to MissingRuntime and cannot execute: ${labels}`);
+    this.missingNodes = missingNodes;
+  }
+}

package/src/workflowSnapshots/WorkflowSnapshotCodec.ts

@@ -72,10 +72,6 @@ export class WorkflowSnapshotCodec {
     }
   }
 
-  /**
-   * Safely call `config.inspectorSummary()` and return a plain JSON-safe array, or undefined.
-   * Returns undefined if the method is absent, throws, or produces no valid rows.
-   */
   private safeInspectorSummary(
     config: NodeConfigBase,
   ): ReadonlyArray<Readonly<{ label: string; value: string }>> | undefined {
@@ -167,7 +163,6 @@ export class WorkflowSnapshotCodec {
         hydrated[key] = value;
       }
     }
-    // Preserve symbol-keyed brands (e.g. itemExpr / emitPorts) and other runtime-only keys.
     for (const sym of Object.getOwnPropertySymbols(liveRecord)) {
       hydrated[sym] = liveRecord[sym];
     }

package/src/workflowSnapshots/index.ts

@@ -3,10 +3,13 @@ export { MissingRuntimeFallbacks } from "./MissingRuntimeFallbacksFactory";
 export { MissingRuntimeNode } from "./MissingRuntimeNode";
 export { MissingRuntimeNodeConfig } from "./MissingRuntimeNodeConfig";
 export { MissingRuntimeNodeToken } from "./MissingRuntimeNodeToken";
+export { MissingRuntimeParityGuard } from "./MissingRuntimeParityGuard";
 export { MissingRuntimeTrigger } from "./MissingRuntimeTrigger";
 export { MissingRuntimeTriggerConfig } from "./MissingRuntimeTriggerConfig";
 export { MissingRuntimeTriggerToken } from "./MissingRuntimeTriggerToken";
 export { PersistedRuntimeTypeIdFactory } from "./PersistedRuntimeTypeIdFactory";
 export { PersistedWorkflowTokenRegistry } from "./PersistedWorkflowTokenRegistryFactory";
+export { WorkflowParityMismatchError } from "./WorkflowParityMismatchError";
+export type { MissingRuntimeNodeDetail } from "./WorkflowParityMismatchError";
 export { WorkflowSnapshotCodec } from "./WorkflowSnapshotCodec";
 export { WorkflowSnapshotResolver } from "./WorkflowSnapshotResolver";