@codemation/core 0.13.2 → 0.15.0

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 {

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}`;
   }