@codemation/core 1.0.1 → 2.0.0

package/src/contracts/index.ts

@@ -1,3 +1,6 @@
+export * from "./baseTypes";
+export * from "./assertionTypes";
+export * from "./collectionTypes";
 export * from "./credentialTypes";
 export * from "./emitPorts";
 export * from "./executionPersistenceContracts";
@@ -6,6 +9,7 @@ export * from "./params";
 export * from "./itemExpr";
 export * from "./runtimeTypes";
 export * from "./telemetryTypes";
+export * from "./testTriggerTypes";
 export * from "./runFinishedAtFactory";
 export * from "./runTypes";
 export * from "./webhookTypes";

package/src/contracts/runTypes.ts

@@ -1,5 +1,5 @@
 import type { TypeToken } from "../di";
-import type { RunEventBus } from "../events/runEvents";
+import type { RunEventBus, TestCaseRunStatus } from "../events/runEvents";
 import type {
   Edge,
   InputPortKey,
@@ -20,6 +20,23 @@ import type {
   WorkflowNodeConnection,
 } from "./workflowTypes";
 
+/**
+ * Test-suite linkage for a run. When set, this run was started by a TestSuiteOrchestrator
+ * as one test case inside a TestSuiteRun. The `IsTestRun` node and host-side persisters key
+ * off the presence of this field. Subworkflow runs inherit it from their parent run.
+ */
+export interface RunTestContext {
+  readonly testSuiteRunId: string;
+  readonly testCaseIndex: number;
+  /**
+   * Optional human-friendly label for this test case (e.g. an email subject when fixtures
+   * are loaded from a mailbox). Resolved per item by `TestTrigger.caseLabel(item)` if set,
+   * persisted on `Run.test_case_label` so the Tests-tab tree-table can show "RFQ for batch 14"
+   * instead of "run_1777755971399_bbb86beac1396".
+   */
+  readonly testCaseLabel?: string;
+}
+
 export interface RunExecutionOptions {
   /** Run-intent override: force the inline scheduler and bypass node-level offload decisions. */
   localOnly?: boolean;
@@ -36,6 +53,8 @@ export interface RunExecutionOptions {
   maxNodeActivations?: number;
   /** Effective cap after engine policy merge (subworkflow nesting). */
   maxSubworkflowDepth?: number;
+  /** Present iff started by a TestSuiteOrchestrator; propagates to subworkflow runs via {@link ParentExecutionRef.testContext}. */
+  testContext?: RunTestContext;
 }
 
 /** Engine-owned counters persisted with the run (worker-safe). */
@@ -220,6 +239,13 @@ export interface RunSummary {
   workflowId: WorkflowId;
   startedAt: string;
   status: RunStatus;
+  /**
+   * Test-case status for runs dispatched as part of a TestSuiteRun. Carries the
+   * assertion-rollup-corrected outcome the test orchestrator persists onto the row, so the
+   * executions list can show "failed" for a run whose workflow completed cleanly but whose
+   * assertions caught regressions. Absent for non-test runs and legacy rows.
+   */
+  testCaseStatus?: TestCaseRunStatus;
   /** ISO timestamp when the run finished (derived from node snapshots or store `updatedAt`); omit while running/pending. */
   finishedAt?: string;
   parent?: ParentExecutionRef;

package/src/contracts/runtimeTypes.ts

@@ -2,6 +2,7 @@ import type { ReadableStream as BinaryReadableStream } from "node:stream/web";
 import type { TypeToken } from "../di";
 import type { RunEventBus } from "../events/runEvents";
 import type { CredentialSessionService } from "./credentialTypes";
+import type { CollectionsContext } from "./collectionTypes";
 import type { ExecutionTelemetry, ExecutionTelemetryFactory, NodeExecutionTelemetry } from "./telemetryTypes";
 import type {
   ConnectionInvocationAppendArgs,
@@ -11,6 +12,7 @@ import type {
   PersistedWorkflowTokenRegistryLike,
   RunExecutionOptions,
   RunResult,
+  RunTestContext,
   WorkflowExecutionRepository,
 } from "./runTypes";
 import type { WorkflowActivationPolicy } from "./workflowActivationPolicy";
@@ -162,6 +164,15 @@ export interface ExecutionContext {
   itemIndex?: number;
   /** When set, this ctx is executing inside a sub-agent triggered by the named parent invocation. */
   parentInvocationId?: ConnectionInvocationId;
+  /**
+   * Present iff the run was started by a TestSuiteOrchestrator. The {@link IsTestRunNode}
+   * branches on this; assertion-emitting nodes use it to decide whether to record results.
+   */
+  testContext?: RunTestContext;
+  /**
+   * Collections registered in the codemation config, keyed by collection name.
+   */
+  readonly collections?: CollectionsContext;
 }
 
 export interface ExecutionContextFactory {
@@ -177,6 +188,7 @@ export interface ExecutionContextFactory {
     nodeState?: NodeExecutionStatePublisher;
     telemetry?: ExecutionTelemetry;
     getCredential<TSession = unknown>(slotKey: string): Promise<TSession>;
+    testContext?: RunTestContext;
   }): ExecutionContext;
 }
 
@@ -188,6 +200,24 @@ export interface NodeExecutionContext<TConfig extends NodeConfigBase = NodeConfi
   binary: NodeBinaryAttachmentService;
 }
 
+export interface PollingTriggerHandle {
+  /**
+   * Start the polling loop. The runtime registers its own cleanup handle so callers do not need to
+   * call {@link TriggerSetupContext.registerCleanup} for the loop.
+   * @returns The state returned by the first cycle (or `undefined` when the overlap guard fired).
+   */
+  start<TState, TItem>(args: {
+    intervalMs: number;
+    seedState?: TState;
+    runCycle: (cycleCtx: {
+      previousState: TState | undefined;
+      signal: AbortSignal;
+    }) => Promise<{ items: Items<TItem>; nextState: TState }>;
+  }): Promise<TState | undefined>;
+  /** Convenience dedup-window helper. */
+  readonly dedup: import("../triggers/polling/PollingTriggerDedupWindow").PollingTriggerDedupWindow;
+}
+
 export interface TriggerSetupContext<
   TConfig extends TriggerNodeConfig<any, any> = TriggerNodeConfig<any, any>,
   TSetupState extends JsonValue | undefined = TriggerNodeSetupState<TConfig>,
@@ -197,6 +227,8 @@ export interface TriggerSetupContext<
   previousState: TSetupState;
   registerCleanup(cleanup: TriggerCleanupHandle): void;
   emit(items: Items): Promise<void>;
+  /** Generic polling-trigger surface. Pre-binds trigger id, emit, and registerCleanup. */
+  readonly polling: PollingTriggerHandle;
 }
 
 export interface TriggerTestItemsContext<
@@ -439,4 +471,6 @@ export interface EngineDeps {
   workflowPolicyRuntimeDefaults?: WorkflowPolicyRuntimeDefaults;
   /** When set, logs inactive-workflow skips at boot and trigger start/stop on activation changes. */
   triggerRuntimeDiagnostics?: TriggerRuntimeDiagnostics;
+  /** When set, the polling-trigger runtime uses this logger for cycle info/debug/error. */
+  pollingTriggerLogger?: import("../triggers/polling/PollingTriggerLogger").PollingTriggerLogger;
 }

package/src/contracts/testTriggerTypes.ts

@@ -0,0 +1,66 @@
+import type { Item, NodeId, WorkflowId } from "./workflowTypes";
+import type { TriggerNodeConfig } from "./workflowTypes";
+
+/**
+ * Identifier minted by the host (or in-memory test runner) for one execution of a test suite.
+ * One TestSuiteRun produces N child workflow runs, one per item yielded by `generateItems`.
+ */
+export type TestSuiteRunId = string;
+
+/**
+ * Setup context passed to a {@link TestTriggerNodeConfig.generateItems} callback. Distinct from
+ * {@link import("./runtimeTypes").TriggerSetupContext} on purpose: test triggers are not
+ * activated by the live trigger lifecycle (webhooks, cron, polling) and never call `emit` —
+ * the orchestrator pulls from the iterable they return and dispatches one run per item.
+ */
+export interface TestTriggerSetupContext<
+  TConfig extends TestTriggerNodeConfig<unknown> = TestTriggerNodeConfig<unknown>,
+> {
+  readonly workflowId: WorkflowId;
+  readonly nodeId: NodeId;
+  readonly config: TConfig;
+  readonly testSuiteRunId: TestSuiteRunId;
+  /**
+   * Resolves a credential session for a slot declared on this trigger's
+   * {@link import("./workflowTypes").NodeConfigBase.getCredentialRequirements}. Same contract as
+   * {@link import("./runtimeTypes").ExecutionContext.getCredential}.
+   */
+  getCredential<TSession = unknown>(slotKey: string): Promise<TSession>;
+  /** AbortSignal raised when the suite is cancelled — long-running pulls should bail out. */
+  readonly signal: AbortSignal;
+}
+
+/**
+ * A trigger config that emits **test cases**. Each item yielded by {@link generateItems}
+ * becomes one workflow run (with `executionOptions.testContext` set), so 10 yielded items
+ * → 10 runs marked under the same TestSuiteRun.
+ *
+ * The trigger is otherwise a normal {@link TriggerNodeConfig} (so the canvas treats it like
+ * any other trigger), but its `triggerKind` is `"test"` so the live activation policy skips it.
+ */
+export interface TestTriggerNodeConfig<TOutputJson = unknown> extends TriggerNodeConfig<TOutputJson, undefined> {
+  readonly triggerKind: "test";
+  /**
+   * Author-supplied async iterable of items, evaluated lazily. Implementations may fetch from
+   * credentialed APIs, read fixture files, or yield hard-coded items. The orchestrator iterates
+   * and dispatches one run per item, with concurrency capped by {@link concurrency} (default 4).
+   */
+  generateItems(ctx: TestTriggerSetupContext<TestTriggerNodeConfig<TOutputJson>>): AsyncIterable<Item<TOutputJson>>;
+  /** Per-suite-run cap on simultaneously-executing test cases. Default: 4. */
+  readonly concurrency?: number;
+  /**
+   * Free-form description of where the test cases come from — surfaced in the node properties
+   * panel and the suite-detail header so authors revisiting the workflow six months later
+   * remember which mailbox / folder / fixture file the cases originate from.
+   *
+   * Example: `"All emails in the Gmail label \"test/triage-fixtures\" — 14 messages as of 2026-05-03."`
+   */
+  readonly description?: string;
+  /**
+   * Resolves a human-readable label for one yielded test case (e.g. email subject). The
+   * orchestrator calls this once per yielded item, persists the result on the run, and the
+   * Tests-tab UI uses it to render the case row instead of the opaque runId. Return
+   * `undefined` to fall back to "Case #N".
+   */
+  caseLabel?(item: Item<TOutputJson>): string | undefined;
+}

package/src/contracts/workflowTypes.ts

@@ -3,13 +3,18 @@ import type { ZodType } from "zod";
 import type { TypeToken } from "../di";
 import type { CredentialRequirement } from "./credentialTypes";
 import type { RetryPolicySpec } from "./retryPolicySpec.types";
+import type { InputPortKey, NodeConnectionName, NodeId, OutputPortKey, WorkflowId } from "./baseTypes";
+
+export type {
+  InputPortKey,
+  NodeConnectionName,
+  NodeId,
+  OutputPortKey,
+  PersistedTokenId,
+  WorkflowId,
+} from "./baseTypes";
 
-export type WorkflowId = string;
-export type NodeId = string;
 export type NodeIdRef<TJson = unknown> = NodeId & Readonly<{ __codemationNodeJson?: TJson }>;
-export type OutputPortKey = string;
-export type InputPortKey = string;
-export type PersistedTokenId = string;
 
 export type NodeKind = "trigger" | "node";
 export type JsonPrimitive = string | number | boolean | null;
@@ -26,8 +31,6 @@ export interface Edge {
   to: { nodeId: NodeId; input: InputPortKey };
 }
 
-export type NodeConnectionName = string;
-
 /**
  * Named connection from a parent node to child nodes that exist in {@link WorkflowDefinition.nodes}
  * but are not traversed by the main execution graph. Parents are commonly executable nodes, but may
@@ -91,6 +94,14 @@ export interface NodeConfigBase {
   readonly declaredOutputPorts?: ReadonlyArray<OutputPortKey>;
   readonly declaredInputPorts?: ReadonlyArray<InputPortKey>;
   getCredentialRequirements?(): ReadonlyArray<CredentialRequirement>;
+  /**
+   * Marker: this node emits {@link import("./assertionTypes").AssertionResult}-shaped items on its
+   * `main` port. The TestSuiteOrchestrator (and host-side TestAssertionPersister) listen for
+   * `nodeCompleted` events from nodes with this flag set, and persist their output items as
+   * TestAssertion records (only when the run carries a `testContext`). Set on assertion node
+   * configs (e.g. `AssertionNodeConfig`, `StringEqualsAssertionNodeConfig`).
+   */
+  readonly emitsAssertions?: true;
 }
 
 export declare const runnableNodeInputType: unique symbol;
@@ -127,6 +138,12 @@ export interface TriggerNodeConfig<
   readonly kind: "trigger";
   readonly [triggerNodeOutputType]?: TOutputJson;
   readonly [triggerNodeSetupStateType]?: TSetupState;
+  /**
+   * Distinguishes triggers driven by the live activation policy (webhooks, cron, polling) from
+   * triggers driven only by the {@link TestSuiteOrchestrator}. `WorkflowActivation` skips
+   * `"test"` triggers; the orchestrator skips `"live"` triggers. Defaults to `"live"` when omitted.
+   */
+  readonly triggerKind?: "live" | "test";
 }
 
 export type RunnableNodeInputJson<TConfig extends RunnableNodeConfig<any, any>> =
@@ -211,6 +228,12 @@ export interface ParentExecutionRef {
   engineMaxNodeActivations?: number;
   /** Effective max subworkflow depth from the parent run (propagated to child policy merge). */
   engineMaxSubworkflowDepth?: number;
+  /**
+   * Test-suite linkage inherited by the child subworkflow run. Set by whichever node
+   * spawns the subworkflow when its own `ctx.testContext` is present, so assertions
+   * emitted inside a subworkflow land under the correct parent test case.
+   */
+  testContext?: import("./runTypes").RunTestContext;
 }
 
 export interface RunDataSnapshot {

package/src/contracts.ts

@@ -0,0 +1,59 @@
+// Pure-type-only re-exports. Use this for type-only consumers that should not drag in runtime DSL or factory code.
+// This subpath prevents unnecessary compile-graph bloat for packages that only need types like NodeId, Items, etc.
+
+export type * from "./contracts/baseTypes";
+export type * from "./contracts/assertionTypes";
+// assertionTypes also exports a runtime helper for deriving pass/fail from a score+threshold.
+// We keep the type-only re-export above and surface the helper explicitly here so UI consumers
+// (next-host) don't need to re-implement the comparison.
+export { deriveAssertionPassed, DEFAULT_ASSERTION_PASS_THRESHOLD } from "./contracts/assertionTypes";
+export type * from "./contracts/params";
+export type * from "./contracts/retryPolicySpec.types";
+export type * from "./contracts/CostCatalogContract";
+export type * from "./contracts/executionPersistenceContracts";
+export type * from "./contracts/runtimeTypes";
+export type * from "./contracts/telemetryTypes";
+export type * from "./contracts/testTriggerTypes";
+export type * from "./contracts/runTypes";
+export type * from "./contracts/webhookTypes";
+export type * from "./contracts/workflowTypes";
+
+// credentialTypes mixes types (Credential* interfaces) with runtime (CredentialUnboundError class).
+// Export type-only subset for pure type consumers.
+export type {
+  CredentialTypeId,
+  CredentialInstanceId,
+  CredentialMaterialSourceKind,
+  CredentialSetupStatus,
+  CredentialHealthStatus,
+  CredentialFieldSchema,
+  CredentialRequirement,
+  CredentialBindingKey,
+  CredentialBinding,
+  CredentialHealth,
+  OAuth2ProviderFromPublicConfig,
+  CredentialOAuth2ScopesFromPublicConfig,
+  CredentialOAuth2AuthDefinition,
+  CredentialAuthDefinition,
+  CredentialAdvancedSectionPresentation,
+  CredentialTypeDefinition,
+  CredentialJsonRecord,
+  CredentialInstanceRecord,
+  CredentialSessionFactoryArgs,
+  CredentialSessionFactory,
+  CredentialHealthTester,
+  CredentialType,
+  AnyCredentialType,
+  CredentialSessionService,
+  CredentialTypeRegistry,
+} from "./contracts/credentialTypes";
+
+// CostTrackingTelemetryContract mixes types with const runtime values (metric/attribute names).
+// Export type-only subset for pure type consumers.
+export type {
+  CostTrackingComponent,
+  CostTrackingUsageRecord,
+  CostTrackingPriceQuote,
+  CostTrackingTelemetry,
+  CostTrackingTelemetryFactory,
+} from "./contracts/CostTrackingTelemetryContract";

package/src/events/runEvents.ts

@@ -1,6 +1,18 @@
+import type { TestSuiteRunId } from "../contracts/testTriggerTypes";
 import type { ConnectionInvocationRecord } from "../contracts/runTypes";
 import type { NodeExecutionSnapshot, ParentExecutionRef, PersistedRunState, RunId, WorkflowId } from "../types";
 
+/**
+ * Outcome of a single test case (one workflow run dispatched by the test-suite orchestrator).
+ * - `running`: workflow still in flight
+ * - `succeeded`: workflow completed AND all assertions passed (or no assertions)
+ * - `failed`: workflow failed OR (workflow completed but ≥1 assertion failed)
+ * - `errored` / `cancelled`: workflow itself errored or was cancelled
+ */
+export type TestCaseRunStatus = "running" | "succeeded" | "failed" | "errored" | "cancelled";
+/** Aggregate outcome of a TestSuiteRun. */
+export type TestSuiteRunStatus = "succeeded" | "failed" | "partial" | "errored" | "cancelled";
+
 export type RunEvent =
   | Readonly<{ kind: "runCreated"; runId: RunId; workflowId: WorkflowId; parent?: ParentExecutionRef; at: string }>
   | Readonly<{
@@ -66,6 +78,43 @@ export type RunEvent =
       parent?: ParentExecutionRef;
       at: string;
       record: ConnectionInvocationRecord;
+    }>
+  | Readonly<{
+      kind: "testSuiteStarted";
+      testSuiteRunId: TestSuiteRunId;
+      workflowId: WorkflowId;
+      triggerNodeId: string;
+      triggerNodeName?: string;
+      concurrency: number;
+      at: string;
+    }>
+  | Readonly<{
+      kind: "testSuiteFinished";
+      testSuiteRunId: TestSuiteRunId;
+      workflowId: WorkflowId;
+      status: TestSuiteRunStatus;
+      totalCases: number;
+      passedCases: number;
+      failedCases: number;
+      at: string;
+    }>
+  | Readonly<{
+      kind: "testCaseStarted";
+      testSuiteRunId: TestSuiteRunId;
+      testCaseIndex: number;
+      runId: RunId;
+      workflowId: WorkflowId;
+      testCaseLabel?: string;
+      at: string;
+    }>
+  | Readonly<{
+      kind: "testCaseCompleted";
+      testSuiteRunId: TestSuiteRunId;
+      testCaseIndex: number;
+      runId: RunId;
+      workflowId: WorkflowId;
+      status: TestCaseRunStatus;
+      at: string;
     }>;
 
 export interface RunEventSubscription {

package/src/execution/ChildExecutionScopeFactory.ts

@@ -1,5 +1,3 @@
-import { CoreTokens } from "../di/CoreTokens";
-import { inject, injectable } from "../di";
 import type {
   ActivationIdFactory,
   ConnectionInvocationId,
@@ -18,13 +16,12 @@ import type {
  * - `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).
  */
-@injectable()
 export class ChildExecutionScopeFactory {
-  constructor(
-    @inject(CoreTokens.ActivationIdFactory)
-    private readonly activationIdFactory: ActivationIdFactory,
-  ) {}
+  constructor(private readonly activationIdFactory: ActivationIdFactory) {}
 
   forSubAgent<TConfig extends RunnableNodeConfig<any, any>>(
     args: Readonly<{

package/src/execution/DefaultExecutionContextFactory.ts

@@ -1,5 +1,6 @@
 import type {
   BinaryStorage,
+  CollectionsContext,
   CostTrackingTelemetryFactory,
   ExecutionContext,
   ExecutionContextFactory,
@@ -8,6 +9,7 @@ import type {
   ParentExecutionRef,
   RunDataSnapshot,
   RunId,
+  RunTestContext,
   WorkflowId,
 } from "../types";
 import { NoOpCostTrackingTelemetryFactory, NoOpExecutionTelemetryFactory } from "../types";
@@ -26,6 +28,7 @@ export class DefaultExecutionContextFactory implements ExecutionContextFactory {
     private readonly telemetryFactory: ExecutionTelemetryFactory = new NoOpExecutionTelemetryFactory(),
     private readonly costTrackingFactory: CostTrackingTelemetryFactory = new NoOpCostTrackingTelemetryFactory(),
     private readonly currentDate: () => Date = () => new Date(),
+    private readonly collections?: CollectionsContext,
   ) {}
 
   create(args: {
@@ -40,6 +43,7 @@ export class DefaultExecutionContextFactory implements ExecutionContextFactory {
     nodeState?: NodeExecutionStatePublisher;
     telemetry?: ExecutionContext["telemetry"];
     getCredential<TSession = unknown>(slotKey: string): Promise<TSession>;
+    testContext?: RunTestContext;
   }): ExecutionContext {
     const baseTelemetry =
       args.telemetry ??
@@ -66,6 +70,8 @@ export class DefaultExecutionContextFactory implements ExecutionContextFactory {
       telemetry,
       binary: new DefaultExecutionBinaryService(this.binaryStorage, args.workflowId, args.runId, this.currentDate),
       getCredential: args.getCredential,
+      testContext: args.testContext,
+      collections: this.collections,
     };
   }
 }

package/src/execution/NodeInstanceFactory.ts

@@ -4,6 +4,7 @@ import type { NodeId, NodeResolver, WorkflowDefinition, WorkflowNodeInstanceFact
 import { MissingRuntimeNode, MissingRuntimeTrigger } from "../workflowSnapshots";
 import { MissingRuntimeNodeToken } from "../workflowSnapshots/MissingRuntimeNodeToken";
 import { MissingRuntimeTriggerToken } from "../workflowSnapshots/MissingRuntimeTriggerToken";
+import { NodeInstantiationError } from "./NodeInstantiationError";
 
 export class NodeInstanceFactory implements WorkflowNodeInstanceFactory {
   constructor(private readonly nodeResolver: NodeResolver) {}
@@ -11,7 +12,18 @@ export class NodeInstanceFactory implements WorkflowNodeInstanceFactory {
   createNodes(workflow: WorkflowDefinition): Map<NodeId, unknown> {
     const nodeInstances = new Map<NodeId, unknown>();
     for (const definition of workflow.nodes) {
-      nodeInstances.set(definition.id, this.createNode(definition));
+      try {
+        nodeInstances.set(definition.id, this.createNode(definition));
+      } catch (err) {
+        if (err instanceof NodeInstantiationError) {
+          throw err;
+        }
+        throw new NodeInstantiationError(
+          definition.id,
+          typeof definition.type === "function" ? definition.type.name : String(definition.type),
+          err instanceof Error ? err : new Error(String(err)),
+        );
+      }
     }
     return nodeInstances;
   }

package/src/execution/NodeInstantiationError.ts

@@ -0,0 +1,16 @@
+import type { NodeId } from "../types";
+
+export class NodeInstantiationError extends Error {
+  readonly name = "NodeInstantiationError";
+  readonly originalError: Error;
+
+  constructor(
+    readonly nodeId: NodeId,
+    readonly nodeType: string,
+    originalError: Error,
+  ) {
+    super(`Failed to instantiate node "${nodeId}" (type ${nodeType}): ${originalError.message}`);
+    this.originalError = originalError;
+    this.stack = originalError.stack;
+  }
+}

package/src/execution/WorkflowRunExecutionContextFactory.ts

@@ -5,6 +5,7 @@ import type {
   ParentExecutionRef,
   RunDataFactory,
   RunId,
+  RunTestContext,
   WorkflowId,
 } from "../types";
 
@@ -30,6 +31,7 @@ export class WorkflowRunExecutionContextFactory {
     engineMaxSubworkflowDepth: number;
     data: ReturnType<RunDataFactory["create"]>;
     nodeState?: NodeExecutionStatePublisher;
+    testContext?: RunTestContext;
   }) {
     return this.executionContextFactory.create({
       runId: args.runId,
@@ -42,6 +44,7 @@ export class WorkflowRunExecutionContextFactory {
       data: args.data,
       nodeState: args.nodeState,
       getCredential: this.credentialResolverFactory.create(args.workflowId, args.nodeId),
+      testContext: args.testContext,
     });
   }
 }

package/src/execution/index.ts

@@ -2,6 +2,7 @@ export { ActivationEnqueueService } from "./ActivationEnqueueService";
 export { ChildExecutionScopeFactory } from "./ChildExecutionScopeFactory";
 export { NodeActivationRequestInputPreparer } from "./NodeActivationRequestInputPreparer";
 export { NodeInputContractError } from "./NodeInputContractError";
+export { NodeInstantiationError } from "./NodeInstantiationError";
 export { CredentialResolverFactory } from "./CredentialResolverFactory";
 export { DefaultAsyncSleeper } from "./DefaultAsyncSleeper";
 export { DefaultExecutionContextFactory } from "./DefaultExecutionContextFactory";

package/src/index.ts

@@ -27,3 +27,10 @@ export { EngineExecutionLimitsPolicy, type EngineExecutionLimitsPolicyConfig } f
 export { InMemoryBinaryStorage, InMemoryRunDataFactory } from "./runStorage";
 export { InMemoryLiveWorkflowRepository, RunIntentService } from "./runtime";
 export * from "./types";
+export { PollingTriggerRuntime, PollingTriggerDedupWindow, NoOpPollingTriggerLogger } from "./triggers/polling";
+export type {
+  PollingTriggerLogger,
+  PollingRunCycleArgs,
+  PollingRunCycleResult,
+  PollingTriggerStartArgs,
+} from "./triggers/polling";

package/src/orchestration/AbortControllerFactory.ts

@@ -0,0 +1,9 @@
+/**
+ * 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/NodeExecutionRequestHandlerService.ts

@@ -77,6 +77,7 @@ export class NodeExecutionRequestHandlerService implements NodeExecutionRequestH
       engineMaxSubworkflowDepth: limits.engineMaxSubworkflowDepth,
       data,
       nodeState: this.nodeStatePublisherFactory.create(state.runId, state.workflowId, resolvedParent),
+      testContext: state.executionOptions?.testContext,
     });
 
     const inputsByPort = pendingExecution.inputsByPort;

package/src/orchestration/RunContinuationService.ts

@@ -141,6 +141,7 @@ export class RunContinuationService {
       engineMaxSubworkflowDepth: limits.engineMaxSubworkflowDepth,
       data,
       nodeState: this.nodeStatePublisherFactory.create(state.runId, state.workflowId, state.parent),
+      testContext: state.executionOptions?.testContext,
     });
 
     data.setOutputs(args.nodeId, args.outputs);
@@ -755,6 +756,7 @@ export class RunContinuationService {
       engineMaxSubworkflowDepth: webhookLimits.engineMaxSubworkflowDepth,
       data,
       nodeState: this.nodeStatePublisherFactory.create(args.state.runId, args.state.workflowId, args.state.parent),
+      testContext: args.state.executionOptions?.testContext,
     });
     const request = this.nodeActivationRequestComposer.createFromPlannedActivation({
       next,
@@ -859,6 +861,7 @@ export class RunContinuationService {
       engineMaxSubworkflowDepth: limits.engineMaxSubworkflowDepth,
       data,
       nodeState: this.nodeStatePublisherFactory.create(state.runId, state.workflowId, state.parent),
+      testContext: state.executionOptions?.testContext,
     });
     const activationId = pendingExecution.activationId;
     return {