@codemation/core 1.0.0 → 2.0.0

package/src/orchestration/TestSuiteOrchestrator.ts

@@ -0,0 +1,350 @@
+import type { CredentialResolverFactory } from "../execution/CredentialResolverFactory";
+import type { RunEventBus, TestCaseRunStatus, TestSuiteRunStatus } from "../events/runEvents";
+import type {
+  Item,
+  Items,
+  NodeId,
+  ParentExecutionRef,
+  RunExecutionOptions,
+  RunId,
+  RunResult,
+  TestSuiteRunId,
+  TestTriggerNodeConfig,
+  TestTriggerSetupContext,
+  TriggerNodeConfig,
+  WorkflowDefinition,
+  WorkflowId,
+} from "../types";
+
+import type { AbortControllerFactory } from "./AbortControllerFactory";
+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,
+    startAt: NodeId,
+    items: Items,
+    parent?: ParentExecutionRef,
+    executionOptions?: RunExecutionOptions,
+  ): Promise<RunResult>;
+  waitForCompletion(runId: RunId): Promise<Extract<RunResult, { status: "completed" | "failed" }>>;
+}
+
+export interface TestSuiteCaseOutcome {
+  readonly testCaseIndex: number;
+  readonly runId: RunId;
+  readonly status: TestCaseRunStatus;
+}
+
+export interface TestSuiteRunResult {
+  readonly testSuiteRunId: TestSuiteRunId;
+  readonly workflowId: WorkflowId;
+  readonly triggerNodeId: NodeId;
+  readonly status: TestSuiteRunStatus;
+  readonly totalCases: number;
+  readonly passedCases: number;
+  readonly failedCases: number;
+  readonly cases: ReadonlyArray<TestSuiteCaseOutcome>;
+}
+
+export interface RunTestSuiteArgs {
+  readonly workflow: WorkflowDefinition;
+  readonly triggerNodeId: NodeId;
+  readonly testSuiteRunId?: TestSuiteRunId;
+  readonly concurrency?: number;
+  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,
+    private readonly testSuiteRunIdFactory: TestSuiteRunIdFactory,
+    private readonly credentialResolverFactory: CredentialResolverFactory,
+    private readonly abortControllerFactory: AbortControllerFactory,
+    private readonly eventBus: RunEventBus | undefined,
+    private readonly currentDate: () => Date = () => new Date(),
+  ) {}
+
+  async runSuite(args: RunTestSuiteArgs): Promise<TestSuiteRunResult> {
+    const triggerNodeId = args.triggerNodeId;
+    const definition = args.workflow.nodes.find((n) => n.id === triggerNodeId);
+    if (!definition) {
+      throw new Error(`Unknown trigger nodeId: ${triggerNodeId}`);
+    }
+    if (definition.kind !== "trigger") {
+      throw new Error(`Node ${triggerNodeId} is not a trigger`);
+    }
+    const triggerConfig = definition.config as TriggerNodeConfig;
+    if (triggerConfig.triggerKind !== "test") {
+      throw new Error(
+        `Node ${triggerNodeId} is not a test trigger (triggerKind="${triggerConfig.triggerKind ?? "live"}")`,
+      );
+    }
+    const testTriggerConfig = triggerConfig as TestTriggerNodeConfig<unknown>;
+    if (typeof testTriggerConfig.generateItems !== "function") {
+      throw new Error(`Test trigger ${triggerNodeId} is missing a generateItems implementation`);
+    }
+
+    const testSuiteRunId = args.testSuiteRunId ?? this.testSuiteRunIdFactory.makeTestSuiteRunId();
+    const concurrency = Math.max(1, args.concurrency ?? testTriggerConfig.concurrency ?? DEFAULT_CONCURRENCY);
+    const externalSignal = args.signal;
+    const internalAbort = this.abortControllerFactory.create();
+    const onExternalAbort = () => internalAbort.abort(externalSignal?.reason);
+    if (externalSignal) {
+      if (externalSignal.aborted) {
+        internalAbort.abort(externalSignal.reason);
+      } else {
+        externalSignal.addEventListener("abort", onExternalAbort, { once: true });
+      }
+    }
+
+    const triggerNodeName = definition.name ?? testTriggerConfig.name;
+
+    await this.publish({
+      kind: "testSuiteStarted",
+      testSuiteRunId,
+      workflowId: args.workflow.id,
+      triggerNodeId,
+      ...(triggerNodeName ? { triggerNodeName } : {}),
+      concurrency,
+      at: this.now(),
+    });
+
+    const setupContext: TestTriggerSetupContext = {
+      workflowId: args.workflow.id,
+      nodeId: triggerNodeId,
+      config: testTriggerConfig,
+      testSuiteRunId,
+      getCredential: this.credentialResolverFactory.create(args.workflow.id, triggerNodeId, testTriggerConfig),
+      signal: internalAbort.signal,
+    };
+
+    const cases: TestSuiteCaseOutcome[] = [];
+    let nextIndex = 0;
+    let inFlight = 0;
+    let waitForSlot: Promise<void> | undefined;
+    let releaseSlot: (() => void) | undefined;
+    const queue: Array<Promise<void>> = [];
+    let generationError: Error | undefined;
+
+    const acquireSlot = async (): Promise<void> => {
+      while (inFlight >= concurrency) {
+        if (!waitForSlot) {
+          waitForSlot = new Promise<void>((resolve) => {
+            releaseSlot = resolve;
+          });
+        }
+        await waitForSlot;
+      }
+      inFlight += 1;
+    };
+
+    const release = (): void => {
+      inFlight -= 1;
+      if (releaseSlot) {
+        const fn = releaseSlot;
+        releaseSlot = undefined;
+        waitForSlot = undefined;
+        fn();
+      }
+    };
+
+    try {
+      for await (const item of testTriggerConfig.generateItems(setupContext) as AsyncIterable<Item<unknown>>) {
+        if (internalAbort.signal.aborted) {
+          break;
+        }
+        await acquireSlot();
+        if (internalAbort.signal.aborted) {
+          release();
+          break;
+        }
+        const testCaseIndex = nextIndex++;
+        const testCaseLabel = this.resolveCaseLabel(testTriggerConfig, item);
+        queue.push(
+          this.runOneCase({
+            workflow: args.workflow,
+            triggerNodeId,
+            testSuiteRunId,
+            testCaseIndex,
+            testCaseLabel,
+            item,
+          })
+            .then((outcome) => {
+              cases.push(outcome);
+            })
+            .finally(release),
+        );
+      }
+    } catch (err) {
+      generationError = err instanceof Error ? err : new Error(String(err));
+    } finally {
+      if (externalSignal) {
+        externalSignal.removeEventListener("abort", onExternalAbort);
+      }
+    }
+
+    await Promise.all(queue);
+
+    cases.sort((a, b) => a.testCaseIndex - b.testCaseIndex);
+    const totalCases = cases.length;
+    const passedCases = cases.filter((c) => c.status === "succeeded").length;
+    const failedCases = cases.filter((c) => c.status === "failed").length;
+    const status: TestSuiteRunStatus = this.deriveSuiteStatus({
+      generationError,
+      cancelled: internalAbort.signal.aborted,
+      totalCases,
+      passedCases,
+      failedCases,
+    });
+
+    await this.publish({
+      kind: "testSuiteFinished",
+      testSuiteRunId,
+      workflowId: args.workflow.id,
+      status,
+      totalCases,
+      passedCases,
+      failedCases,
+      at: this.now(),
+    });
+
+    if (generationError && status === "errored") {
+      throw generationError;
+    }
+
+    return {
+      testSuiteRunId,
+      workflowId: args.workflow.id,
+      triggerNodeId,
+      status,
+      totalCases,
+      passedCases,
+      failedCases,
+      cases,
+    };
+  }
+
+  private async runOneCase(args: {
+    workflow: WorkflowDefinition;
+    triggerNodeId: NodeId;
+    testSuiteRunId: TestSuiteRunId;
+    testCaseIndex: number;
+    testCaseLabel: string | undefined;
+    item: Item<unknown>;
+  }): Promise<TestSuiteCaseOutcome> {
+    const executionOptions: RunExecutionOptions = {
+      testContext: {
+        testSuiteRunId: args.testSuiteRunId,
+        testCaseIndex: args.testCaseIndex,
+        ...(args.testCaseLabel !== undefined ? { testCaseLabel: args.testCaseLabel } : {}),
+      },
+    };
+
+    const initial = await this.engine.runWorkflow(
+      args.workflow,
+      args.triggerNodeId,
+      [args.item],
+      undefined,
+      executionOptions,
+    );
+
+    const runId = initial.runId;
+    await this.publish({
+      kind: "testCaseStarted",
+      testSuiteRunId: args.testSuiteRunId,
+      testCaseIndex: args.testCaseIndex,
+      runId,
+      workflowId: args.workflow.id,
+      at: this.now(),
+      ...(args.testCaseLabel !== undefined ? { testCaseLabel: args.testCaseLabel } : {}),
+    });
+
+    let terminal: Extract<RunResult, { status: "completed" | "failed" }>;
+    if (initial.status === "completed" || initial.status === "failed") {
+      terminal = initial;
+    } else {
+      terminal = await this.engine.waitForCompletion(runId);
+    }
+
+    // RunResult.status from the engine narrows to "completed" | "failed" here; widening to
+    // "errored" / "cancelled" happens outside this code path (tracker downgrade for assertion
+    // failures; outer abort handling for cancelled).
+    const status: TestCaseRunStatus = terminal.status === "completed" ? "succeeded" : "failed";
+    await this.publish({
+      kind: "testCaseCompleted",
+      testSuiteRunId: args.testSuiteRunId,
+      testCaseIndex: args.testCaseIndex,
+      runId,
+      workflowId: args.workflow.id,
+      status,
+      at: this.now(),
+    });
+    return { testCaseIndex: args.testCaseIndex, runId, status };
+  }
+
+  private deriveSuiteStatus(args: {
+    generationError: Error | undefined;
+    cancelled: boolean;
+    totalCases: number;
+    passedCases: number;
+    failedCases: number;
+  }): TestSuiteRunStatus {
+    if (args.generationError && args.totalCases === 0) {
+      return "errored";
+    }
+    if (args.cancelled) {
+      return "cancelled";
+    }
+    if (args.generationError) {
+      return "errored";
+    }
+    if (args.totalCases === 0) {
+      return "succeeded";
+    }
+    if (args.failedCases === 0) {
+      return "succeeded";
+    }
+    if (args.passedCases === 0) {
+      return "failed";
+    }
+    return "partial";
+  }
+
+  private now(): string {
+    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 {
+      const result = config.caseLabel(item);
+      if (typeof result !== "string") return undefined;
+      const trimmed = result.trim();
+      return trimmed.length === 0 ? undefined : trimmed;
+    } catch {
+      return undefined;
+    }
+  }
+
+  private async publish(event: Parameters<RunEventBus["publish"]>[0]): Promise<void> {
+    if (!this.eventBus) return;
+    await this.eventBus.publish(event);
+  }
+}

package/src/orchestration/TestSuiteRunIdFactory.ts

@@ -0,0 +1,11 @@
+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

@@ -24,6 +24,9 @@ import type {
 import { CredentialResolverFactory } from "../execution/CredentialResolverFactory";
 import type { NodeRunStateWriterFactory } from "../execution/NodeRunStateWriterFactory";
 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";
 
 export interface TriggerEmitHandler {
   emit(workflow: WorkflowDefinition, triggerNodeId: NodeId, items: Items): Promise<void>;
@@ -45,7 +48,9 @@ export class TriggerRuntimeService {
     private readonly triggerSetupStateRepository: TriggerSetupStateRepository,
     private readonly emitHandler: TriggerEmitHandler,
     private readonly executionLimitsPolicy: EngineExecutionLimitsPolicy,
-    private readonly diagnostics?: TriggerRuntimeDiagnostics,
+    private readonly diagnostics: TriggerRuntimeDiagnostics | undefined,
+    private readonly pollingTriggerRuntime: PollingTriggerRuntime,
+    private readonly pollingTriggerDedupWindow: PollingTriggerDedupWindow,
   ) {
     this.credentialResolverFactory = credentialResolverFactory;
   }
@@ -124,12 +129,16 @@ export class TriggerRuntimeService {
   private async startTriggersForWorkflow(wf: WorkflowDefinition): Promise<void> {
     for (const def of wf.nodes) {
       if (def.kind !== "trigger") continue;
+      if ((def.config as TriggerNodeConfig).triggerKind === "test") continue;
       const node = this.nodeResolver.resolve(def.type) as TriggerNode;
       const data = this.runDataFactory.create();
       const triggerRunId = this.runIdFactory.makeRunId();
       const trigger = { workflowId: wf.id, nodeId: def.id } as const;
       await this.stopTrigger(trigger);
       const previousState = await this.triggerSetupStateRepository.load(trigger);
+      const emit = this.emitHandler.emit.bind(this.emitHandler, wf, def.id);
+      const registerCleanup = this.registerTriggerCleanupHandle.bind(this, trigger);
+      const polling = this.buildPollingHandle(trigger, emit);
       let nextState: unknown;
       try {
         nextState = await node.setup({
@@ -142,12 +151,9 @@ export class TriggerRuntimeService {
           trigger,
           config: def.config as TriggerNodeConfig,
           previousState: previousState?.state as never,
-          registerCleanup: (cleanup) => {
-            this.registerTriggerCleanupHandle(trigger, cleanup);
-          },
-          emit: async (items) => {
-            await this.emitHandler.emit(wf, def.id, items);
-          },
+          registerCleanup,
+          emit,
+          polling,
         } satisfies TriggerSetupContext<TriggerNodeConfig>);
       } catch (triggerError: unknown) {
         await this.stopTrigger(trigger);
@@ -172,6 +178,9 @@ export class TriggerRuntimeService {
       if (node.kind !== "trigger") {
         continue;
       }
+      if ((node.config as TriggerNodeConfig).triggerKind === "test") {
+        continue;
+      }
       await this.stopTrigger({
         workflowId: workflow.id,
         nodeId: node.id,
@@ -226,6 +235,9 @@ export class TriggerRuntimeService {
       if (def.kind !== "trigger") {
         continue;
       }
+      if ((def.config as TriggerNodeConfig).triggerKind === "test") {
+        continue;
+      }
       out.push(this.describeTriggerNode(def));
     }
     return out;
@@ -254,6 +266,21 @@ export class TriggerRuntimeService {
     }
   }
 
+  private buildPollingHandle(trigger: TriggerInstanceId, emit: (items: Items) => Promise<void>): PollingTriggerHandle {
+    const runtime = this.pollingTriggerRuntime;
+    return {
+      dedup: this.pollingTriggerDedupWindow,
+      start: async (args) => {
+        this.registerTriggerCleanupHandle(trigger, {
+          stop: async () => {
+            await runtime.stop(trigger);
+          },
+        });
+        return runtime.start({ trigger, emit, ...args });
+      },
+    };
+  }
+
   private isTestableTriggerNode(node: TriggerNode): node is TestableTriggerNode<TriggerNodeConfig> {
     return typeof (node as Partial<TestableTriggerNode<TriggerNodeConfig>>).getTestItems === "function";
   }

package/src/orchestration/index.ts

@@ -1,5 +1,14 @@
+export { AbortControllerFactory } from "./AbortControllerFactory";
 export { Engine } from "./Engine";
 export { EngineWaiters } from "./EngineWaiters";
 export { RunContinuationService } from "./RunContinuationService";
 export { RunStartService } from "./RunStartService";
+export { TestSuiteOrchestrator } from "./TestSuiteOrchestrator";
+export type {
+  TestSuiteOrchestratorEngine,
+  TestSuiteRunResult,
+  TestSuiteCaseOutcome,
+  RunTestSuiteArgs,
+} from "./TestSuiteOrchestrator";
+export { TestSuiteRunIdFactory } from "./TestSuiteRunIdFactory";
 export { TriggerRuntimeService } from "./TriggerRuntimeService";

package/src/runtime/EngineFactory.ts

@@ -1,5 +1,8 @@
 import type { EngineDeps } from "../types";
 
+import { PollingTriggerDedupWindow } from "../triggers/polling/PollingTriggerDedupWindow";
+import { PollingTriggerRuntime } from "../triggers/polling/PollingTriggerRuntime";
+import { NoOpPollingTriggerLogger } from "../triggers/polling/PollingTriggerLogger";
 import { MissingRuntimeFallbacks } from "../workflowSnapshots/MissingRuntimeFallbacksFactory";
 import { MissingRuntimeExecutionMarker } from "../workflowSnapshots/MissingRuntimeExecutionMarker";
 import { WorkflowSnapshotCodec } from "../workflowSnapshots/WorkflowSnapshotCodec";
@@ -49,6 +52,7 @@ export class EngineFactory {
     const nodeStatePublisherFactory = new NodeRunStateWriterFactory(
       deps.workflowExecutionRepository,
       nodeEventPublisher,
+      deps.eventBus,
     );
     const planningFactory = new EngineWorkflowPlanningFactory(deps.workflowNodeInstanceFactory);
     const executionLimitsPolicy = deps.executionLimitsPolicy ?? new EngineExecutionLimitsPolicy();
@@ -99,6 +103,8 @@ export class EngineFactory {
       waiters,
       deps.workflowPolicyRuntimeDefaults,
       executionLimitsPolicy,
+      nodeEventPublisher,
+      persistedRunStateTerminalBuilder,
     );
     const runContinuationService = new RunContinuationService(
       deps.activationIdFactory,
@@ -131,6 +137,10 @@ export class EngineFactory {
       executionLimitsPolicy,
     );
 
+    const pollingTriggerLogger = deps.pollingTriggerLogger ?? new NoOpPollingTriggerLogger();
+    const pollingTriggerDedupWindow = new PollingTriggerDedupWindow();
+    const pollingTriggerRuntime = new PollingTriggerRuntime(deps.triggerSetupStateRepository, pollingTriggerLogger);
+
     const triggerRuntime = new TriggerRuntimeService(
       deps.workflowRepository,
       deps.workflowActivationPolicy,
@@ -148,6 +158,8 @@ export class EngineFactory {
       },
       executionLimitsPolicy,
       deps.triggerRuntimeDiagnostics,
+      pollingTriggerRuntime,
+      pollingTriggerDedupWindow,
     );
 
     const engine = new Engine({

package/src/triggers/polling/PollingTriggerDedupWindow.ts

@@ -0,0 +1,23 @@
+/**
+ * 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;
+
+  merge(
+    previous: ReadonlyArray<string>,
+    incoming: ReadonlyArray<string>,
+    capN: number = PollingTriggerDedupWindow.defaultCapN,
+  ): ReadonlyArray<string> {
+    const merged = new Set(previous);
+    for (const id of incoming) {
+      merged.add(id);
+    }
+    const result = [...merged];
+    if (result.length <= capN) {
+      return result;
+    }
+    return result.slice(result.length - capN);
+  }
+}

package/src/triggers/polling/PollingTriggerLogger.ts

@@ -0,0 +1,18 @@
+/**
+ * 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;
+  error(message: string, exception?: Error): void;
+  debug(message: string): void;
+}
+
+export class NoOpPollingTriggerLogger implements PollingTriggerLogger {
+  info(): void {}
+  warn(): void {}
+  error(): void {}
+  debug(): void {}
+}

package/src/triggers/polling/PollingTriggerRuntime.ts

@@ -0,0 +1,122 @@
+import type { Items, TriggerInstanceId, TriggerSetupStateRepository } from "../../types";
+import type { PollingTriggerLogger } from "./PollingTriggerLogger";
+
+export interface PollingRunCycleArgs<TState> {
+  previousState: TState | undefined;
+  signal: AbortSignal;
+}
+
+export interface PollingRunCycleResult<TState, TItem> {
+  items: Items<TItem>;
+  nextState: TState;
+}
+
+export interface PollingTriggerStartArgs<TState, TItem> {
+  trigger: TriggerInstanceId;
+  intervalMs: number;
+  seedState?: TState;
+  runCycle: (cycleCtx: PollingRunCycleArgs<TState>) => Promise<PollingRunCycleResult<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>>();
+  private readonly busyTriggers = new Set<string>();
+
+  constructor(
+    private readonly triggerSetupStateRepository: TriggerSetupStateRepository,
+    private readonly logger: PollingTriggerLogger,
+  ) {}
+
+  async start<TState, TItem>(args: PollingTriggerStartArgs<TState, TItem>): Promise<TState | undefined> {
+    let first: TState | undefined;
+    try {
+      first = await this.runCycle(args, { seedState: args.seedState });
+    } catch (err: unknown) {
+      this.logError(`Polling trigger initial cycle failed for ${this.describe(args.trigger)}`, err);
+    }
+    this.ensureLoop(args);
+    return first;
+  }
+
+  async stop(trigger: TriggerInstanceId): Promise<void> {
+    const key = this.toKey(trigger);
+    const interval = this.intervalsByTrigger.get(key);
+    if (interval !== undefined) {
+      clearInterval(interval);
+      this.intervalsByTrigger.delete(key);
+    }
+    this.busyTriggers.delete(key);
+    this.activeTriggers.delete(key);
+    this.logger.debug(`Polling trigger stopped for ${this.describe(trigger)}`);
+  }
+
+  private ensureLoop<TState, TItem>(args: PollingTriggerStartArgs<TState, TItem>): void {
+    const key = this.toKey(args.trigger);
+    if (this.activeTriggers.has(key)) {
+      this.logger.debug(`Polling trigger already active for ${this.describe(args.trigger)}`);
+      return;
+    }
+    this.activeTriggers.add(key);
+    const intervalMs = Math.max(args.intervalMs, 25);
+    const interval = setInterval(() => {
+      void this.runCycle(args, { seedState: undefined }).catch((err: unknown) => {
+        this.logError(`Polling trigger cycle failed for ${this.describe(args.trigger)}`, err);
+      });
+    }, intervalMs);
+    this.intervalsByTrigger.set(key, interval);
+    this.logger.info(`Polling trigger started for ${this.describe(args.trigger)} (interval ${intervalMs}ms)`);
+  }
+
+  private async runCycle<TState, TItem>(
+    args: PollingTriggerStartArgs<TState, TItem>,
+    opts: { seedState: TState | undefined },
+  ): Promise<TState | undefined> {
+    const key = this.toKey(args.trigger);
+    if (this.busyTriggers.has(key)) {
+      this.logger.debug(`Polling trigger skipping overlapping tick for ${this.describe(args.trigger)}`);
+      return undefined;
+    }
+    this.busyTriggers.add(key);
+    try {
+      const loaded = await this.triggerSetupStateRepository.load(args.trigger);
+      const previousState = loaded !== undefined ? (loaded.state as TState | undefined) : opts.seedState;
+      const controller = new AbortController();
+      const { items, nextState } = await args.runCycle({ previousState, signal: controller.signal });
+      await this.triggerSetupStateRepository.save({
+        trigger: args.trigger,
+        updatedAt: new Date().toISOString(),
+        state: nextState as never,
+      });
+      if (items.length > 0) {
+        this.logger.info(`Polling trigger emitting ${items.length} item(s) for ${this.describe(args.trigger)}`);
+        await args.emit(items);
+      }
+      return nextState;
+    } finally {
+      this.busyTriggers.delete(key);
+    }
+  }
+
+  private toKey(trigger: TriggerInstanceId): string {
+    return `${trigger.workflowId}:${trigger.nodeId}`;
+  }
+
+  private describe(trigger: TriggerInstanceId): string {
+    return `${trigger.workflowId}.${trigger.nodeId}`;
+  }
+
+  private logError(message: string, error: unknown): void {
+    if (error instanceof Error) {
+      this.logger.error(message, error);
+      return;
+    }
+    this.logger.error(`${message}: ${String(error)}`);
+  }
+}

package/src/triggers/polling/index.ts

@@ -0,0 +1,5 @@
+export { PollingTriggerDedupWindow } from "./PollingTriggerDedupWindow";
+export { PollingTriggerRuntime } from "./PollingTriggerRuntime";
+export type { PollingTriggerLogger } from "./PollingTriggerLogger";
+export { NoOpPollingTriggerLogger } from "./PollingTriggerLogger";
+export type { PollingRunCycleArgs, PollingRunCycleResult, PollingTriggerStartArgs } from "./PollingTriggerRuntime";