@bluelibs/runner 5.1.0 → 5.2.1

package/dist/types/models/event/types.d.ts

@@ -0,0 +1,50 @@
+import { DependencyValuesType, EventHandlerType, IEventEmission } from "../../defs";
+import { IHook } from "../../types/hook";
+/**
+ * Default options for event handlers.
+ */
+export declare const HandlerOptionsDefaults: {
+    order: number;
+};
+/**
+ * Internal storage structure for event listeners.
+ */
+export interface IListenerStorage {
+    order: number;
+    filter?: (event: IEventEmission<any>) => boolean;
+    handler: EventHandlerType;
+    /** Optional listener id (from IEventHandlerOptions.id) */
+    id?: string;
+    /** True when this listener originates from addGlobalListener(). */
+    isGlobal: boolean;
+}
+/**
+ * Options for configuring event listeners.
+ */
+export interface IEventHandlerOptions<T = any> {
+    order?: number;
+    filter?: (event: IEventEmission<T>) => boolean;
+    /**
+     * Represents the listener ID. Use this to avoid a listener calling itself.
+     */
+    id?: string;
+}
+/**
+ * Interceptor for event emissions.
+ */
+export type EventEmissionInterceptor = (next: (event: IEventEmission<any>) => Promise<void>, event: IEventEmission<any>) => Promise<void>;
+/**
+ * Interceptor for hook execution.
+ */
+export type HookExecutionInterceptor = (next: (hook: IHook<any, any>, event: IEventEmission<any>) => Promise<any>, hook: IHook<any, any>, event: IEventEmission<any>) => Promise<any>;
+/**
+ * Shared contract for cycle-aware hook execution.
+ */
+export type HookExecutor = (hook: IHook<any, any>, event: IEventEmission<any>, computedDependencies: DependencyValuesType<any>) => Promise<any>;
+/**
+ * Utility shape representing an emission frame used for cycle detection.
+ */
+export interface IEmissionFrame {
+    id: string;
+    source: string;
+}

package/dist/types/models/index.d.ts

@@ -0,0 +1,13 @@
+export * from "./DependencyProcessor";
+export * from "./EventManager";
+export * from "./Logger";
+export * from "./Store";
+export * from "./TaskRunner";
+export * from "./ResourceInitializer";
+export * from "./MiddlewareManager";
+export { LogPrinter } from "./LogPrinter";
+export type { PrintableLog, ColorTheme, LogLevels as LogPrinterLevels, PrintStrategy as LogPrinterPrintStrategy, } from "./LogPrinter";
+export * from "./Semaphore";
+export * from "./Queue";
+export * from "./UnhandledError";
+export * from "./RunResult";

package/dist/types/models/middleware/InterceptorRegistry.d.ts

@@ -0,0 +1,56 @@
+import { TaskMiddlewareInterceptor, ResourceMiddlewareInterceptor } from "./types";
+/**
+ * Centralized registry for all interceptor types.
+ * Manages storage and retrieval of global and per-middleware interceptors.
+ */
+export declare class InterceptorRegistry {
+    #private;
+    private taskInterceptors;
+    private resourceInterceptors;
+    private perTaskMiddleware;
+    private perResourceMiddleware;
+    /**
+     * Gets the current lock status
+     */
+    get isLocked(): boolean;
+    /**
+     * Locks the registry, preventing any further modifications
+     */
+    lock(): void;
+    /**
+     * Throws an error if the registry is locked
+     */
+    private checkLock;
+    /**
+     * Adds a global task interceptor
+     */
+    addGlobalTaskInterceptor(interceptor: TaskMiddlewareInterceptor): void;
+    /**
+     * Adds a global resource interceptor
+     */
+    addGlobalResourceInterceptor(interceptor: ResourceMiddlewareInterceptor): void;
+    /**
+     * Adds an interceptor for a specific task middleware instance
+     */
+    addTaskMiddlewareInterceptor(middlewareId: string, interceptor: TaskMiddlewareInterceptor): void;
+    /**
+     * Adds an interceptor for a specific resource middleware instance
+     */
+    addResourceMiddlewareInterceptor(middlewareId: string, interceptor: ResourceMiddlewareInterceptor): void;
+    /**
+     * Gets all global task interceptors
+     */
+    getGlobalTaskInterceptors(): readonly TaskMiddlewareInterceptor[];
+    /**
+     * Gets all global resource interceptors
+     */
+    getGlobalResourceInterceptors(): readonly ResourceMiddlewareInterceptor[];
+    /**
+     * Gets interceptors for a specific task middleware
+     */
+    getTaskMiddlewareInterceptors(middlewareId: string): readonly TaskMiddlewareInterceptor[];
+    /**
+     * Gets interceptors for a specific resource middleware
+     */
+    getResourceMiddlewareInterceptors(middlewareId: string): readonly ResourceMiddlewareInterceptor[];
+}

package/dist/types/models/middleware/MiddlewareResolver.d.ts

@@ -0,0 +1,31 @@
+import { ITask, IResource, ITaskMiddleware, IResourceMiddleware } from "../../defs";
+import { Store } from "../Store";
+/**
+ * Resolves which middlewares should be applied to tasks and resources.
+ * Handles global "everywhere" middlewares, local middlewares, and tunnel policies.
+ */
+export declare class MiddlewareResolver {
+    private readonly store;
+    constructor(store: Store);
+    /**
+     * Gets all applicable middlewares for a task (global + local, deduplicated)
+     */
+    getApplicableTaskMiddlewares(task: ITask<any, any, any>): ITaskMiddleware[];
+    /**
+     * Gets all applicable middlewares for a resource (global + local, deduplicated)
+     */
+    getApplicableResourceMiddlewares(resource: IResource<any, any, any, any>): IResourceMiddleware[];
+    /**
+     * For tunneled tasks, controls caller-side task middleware execution.
+     * Caller-side middleware is skipped by default and can be re-enabled via allowlist.
+     */
+    applyTunnelPolicyFilter(task: ITask<any, any, any>, middlewares: ITaskMiddleware[]): ITaskMiddleware[];
+    /**
+     * Gets all "everywhere" middlewares that apply to the given task
+     */
+    getEverywhereTaskMiddlewares(task: ITask<any, any, any>): ITaskMiddleware[];
+    /**
+     * Gets all "everywhere" middlewares that apply to the given resource
+     */
+    getEverywhereResourceMiddlewares(resource: IResource<any, any, any, any>): IResourceMiddleware[];
+}

package/dist/types/models/middleware/ResourceMiddlewareComposer.d.ts

@@ -0,0 +1,34 @@
+import { IResource, DependencyMapType } from "../../defs";
+import { Store } from "../Store";
+import { InterceptorRegistry } from "./InterceptorRegistry";
+import { MiddlewareResolver } from "./MiddlewareResolver";
+/**
+ * Composes resource initialization chains with validation, interceptors, and middlewares.
+ * Builds the onion-style wrapping of resource init functions.
+ */
+export declare class ResourceMiddlewareComposer {
+    private readonly store;
+    private readonly interceptorRegistry;
+    private readonly middlewareResolver;
+    constructor(store: Store, interceptorRegistry: InterceptorRegistry, middlewareResolver: MiddlewareResolver);
+    /**
+     * Runs resource initialization with all middleware and interceptors applied
+     */
+    runInit<TConfig, TValue extends Promise<any>, TDeps extends DependencyMapType, TContext>(resource: IResource<TConfig, TValue, TDeps, TContext>, config: TConfig, dependencies: any, context: TContext): Promise<TValue | undefined>;
+    /**
+     * Creates the base resource init runner with result validation
+     */
+    private createBaseInitRunner;
+    /**
+     * Applies resource middleware layers
+     */
+    private applyMiddlewares;
+    /**
+     * Applies global resource middleware interceptors
+     */
+    private applyGlobalInterceptors;
+    /**
+     * Wraps a middleware runner with its specific interceptors in onion style
+     */
+    private wrapWithInterceptors;
+}

package/dist/types/models/middleware/TaskMiddlewareComposer.d.ts

@@ -0,0 +1,44 @@
+import { ITask, DependencyMapType } from "../../defs";
+import { Store } from "../Store";
+import { InterceptorRegistry } from "./InterceptorRegistry";
+import { MiddlewareResolver } from "./MiddlewareResolver";
+import type { ExecutionJournal } from "../../types/executionJournal";
+/**
+ * Composes task execution chains with validation, interceptors, and middlewares.
+ * Builds the onion-style wrapping of task runners.
+ */
+export declare class TaskMiddlewareComposer {
+    private readonly store;
+    private readonly interceptorRegistry;
+    private readonly middlewareResolver;
+    constructor(store: Store, interceptorRegistry: InterceptorRegistry, middlewareResolver: MiddlewareResolver);
+    /**
+     * Composes a complete task runner with all middleware and interceptors applied
+     */
+    compose<TInput, TOutput extends Promise<any>, TDeps extends DependencyMapType>(task: ITask<TInput, TOutput, TDeps>): (input: TInput, parentJournal?: ExecutionJournal) => Promise<Awaited<TOutput>>;
+    /**
+     * Creates the base task runner with input/result validation
+     */
+    private createBaseRunner;
+    /**
+     * Determines which task definition to use for execution
+     * Prefers store definition when task is tunneled (tunnel overrides apply)
+     */
+    private resolveTaskDefinition;
+    /**
+     * Applies local per-task interceptors (closest to the task)
+     */
+    private applyLocalInterceptors;
+    /**
+     * Applies global task middleware interceptors
+     */
+    private applyGlobalInterceptors;
+    /**
+     * Applies task middleware layers (global first, then local)
+     */
+    private applyMiddlewares;
+    /**
+     * Wraps a middleware runner with its specific interceptors in onion style
+     */
+    private wrapWithInterceptors;
+}

package/dist/types/models/middleware/ValidationHelper.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Centralized validation logic for inputs and results across tasks and resources.
+ * Provides consistent error handling and messaging.
+ */
+export declare class ValidationHelper {
+    /**
+     * Validates input using the provided schema
+     * @throws ValidationError if validation fails
+     */
+    static validateInput<T>(value: any, schema: {
+        parse: (v: any) => T;
+    } | undefined, id: string, type: "Task" | "Resource"): T;
+    /**
+     * Validates result using the provided schema
+     * @throws ValidationError if validation fails
+     */
+    static validateResult<T>(value: any, schema: {
+        parse: (v: any) => T;
+    } | undefined, id: string, type: "Task" | "Resource"): T;
+}

package/dist/types/models/middleware/index.d.ts

@@ -0,0 +1,6 @@
+export { InterceptorRegistry } from "./InterceptorRegistry";
+export { MiddlewareResolver } from "./MiddlewareResolver";
+export { TaskMiddlewareComposer } from "./TaskMiddlewareComposer";
+export { ResourceMiddlewareComposer } from "./ResourceMiddlewareComposer";
+export { ValidationHelper } from "./ValidationHelper";
+export type { TaskMiddlewareInterceptor, ResourceMiddlewareInterceptor, } from "./types";

package/dist/types/models/middleware/types.d.ts

@@ -0,0 +1,10 @@
+import { ITaskMiddlewareExecutionInput } from "../../types/taskMiddleware";
+import { IResourceMiddlewareExecutionInput } from "../../types/resourceMiddleware";
+/**
+ * Interceptor for task middleware execution
+ */
+export type TaskMiddlewareInterceptor = (next: (input: ITaskMiddlewareExecutionInput<any>) => Promise<any>, input: ITaskMiddlewareExecutionInput<any>) => Promise<any>;
+/**
+ * Interceptor for resource middleware execution
+ */
+export type ResourceMiddlewareInterceptor = (next: (input: IResourceMiddlewareExecutionInput<any>) => Promise<any>, input: IResourceMiddlewareExecutionInput<any>) => Promise<any>;

package/dist/types/models/utils/findCircularDependencies.d.ts

@@ -0,0 +1,16 @@
+/**
+ * A node that has dependencies.
+ */
+export interface IDependentNode {
+    id: string;
+    dependencies: Record<string, IDependentNode>;
+}
+interface FindCircularDependenciesResult {
+    cycles: string[];
+    missingDependencies: Array<{
+        nodeId: string;
+        dependencyId: string;
+    }>;
+}
+export declare function findCircularDependencies(nodes: IDependentNode[]): FindCircularDependenciesResult;
+export {};

package/dist/types/models/utils/safeStringify.d.ts

@@ -0,0 +1,3 @@
+export declare function safeStringify(value: unknown, space?: number, options?: {
+    maxDepth?: number;
+}): string;

package/dist/types/node/durable/bus/MemoryEventBus.d.ts

@@ -0,0 +1,7 @@
+import type { BusEvent, BusEventHandler, IEventBus } from "../core/interfaces/bus";
+export declare class MemoryEventBus implements IEventBus {
+    private handlers;
+    publish(channel: string, event: BusEvent): Promise<void>;
+    subscribe(channel: string, handler: BusEventHandler): Promise<void>;
+    unsubscribe(channel: string): Promise<void>;
+}

package/dist/types/node/durable/bus/NoopEventBus.d.ts

@@ -0,0 +1,6 @@
+import type { BusEvent, BusEventHandler, IEventBus } from "../core/interfaces/bus";
+export declare class NoopEventBus implements IEventBus {
+    publish(_channel: string, _event: BusEvent): Promise<void>;
+    subscribe(_channel: string, _handler: BusEventHandler): Promise<void>;
+    unsubscribe(_channel: string): Promise<void>;
+}

package/dist/types/node/durable/bus/RedisEventBus.d.ts

@@ -0,0 +1,30 @@
+import type { BusEvent, BusEventHandler, IEventBus } from "../core/interfaces/bus";
+export interface RedisEventBusConfig {
+    prefix?: string;
+    redis?: RedisEventBusClient | string;
+}
+export interface RedisEventBusClient {
+    publish(channel: string, payload: string): Promise<unknown>;
+    subscribe(channel: string): Promise<unknown>;
+    unsubscribe(channel: string): Promise<unknown>;
+    on(event: "message", fn: (channel: string, message: string) => void): unknown;
+    quit(): Promise<unknown>;
+    duplicate(): RedisEventBusClient;
+}
+export declare class RedisEventBus implements IEventBus {
+    private pub;
+    private sub;
+    private prefix;
+    private readonly channels;
+    private readonly serializer;
+    constructor(config: RedisEventBusConfig);
+    private k;
+    private tryParse;
+    private coerceTimestamp;
+    private toBusEvent;
+    private deserializeEvent;
+    publish(channel: string, event: BusEvent): Promise<void>;
+    subscribe(channel: string, handler: BusEventHandler): Promise<void>;
+    unsubscribe(channel: string): Promise<void>;
+    dispose(): Promise<void>;
+}

package/dist/types/node/durable/core/CronParser.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Cron helper used by `ScheduleManager`.
+ *
+ * Prefers the optional `cron-parser` dependency when available, but provides a
+ * deterministic fallback implementation so durable scheduling works even when
+ * optional deps are not installed (important for the multi-platform packaging
+ * and optionalDependency setup).
+ */
+export declare class CronParser {
+    static getNextRun(cron: string, from?: Date): Date;
+    static isValid(cron: string): boolean;
+    private static tryGetExternalParser;
+    private static parseFallback;
+    private static getNextRunFallback;
+}

package/dist/types/node/durable/core/DurableContext.d.ts

@@ -0,0 +1,64 @@
+import type { IEventBus } from "./interfaces/bus";
+import type { EmitOptions, IDurableContext, IStepBuilder, SignalOptions, SleepOptions, StepOptions, SwitchBranch } from "./interfaces/context";
+import type { IDurableStore } from "./interfaces/store";
+import type { IEventDefinition } from "../../../types/event";
+import type { DurableStepId } from "./ids";
+import { type DurableAuditEmitter } from "./audit";
+import { type ImplicitInternalStepIdsPolicy } from "./durable-context/DurableContext.determinism";
+/**
+ * Per-execution workflow toolkit used by durable tasks.
+ *
+ * `DurableContext` is created by `ExecutionManager` for each execution attempt and
+ * made available to user code via `DurableResource.use()` (AsyncLocalStorage).
+ *
+ * It provides deterministic "save points" (`step()`), durable suspension primitives
+ * (`sleep()`, `waitForSignal()`), and best-effort side-channel notifications (`emit()`).
+ * The durable store is the source of truth; this class is intentionally thin state
+ * around indexes/guards to keep a single in-memory attempt deterministic.
+ */
+export declare class DurableContext implements IDurableContext {
+    private readonly store;
+    private readonly bus;
+    readonly executionId: string;
+    readonly attempt: number;
+    private readonly sleepIndexRef;
+    private readonly signalIndexes;
+    private readonly emitIndexes;
+    private noteIndex;
+    private readonly implicitInternalStepIdsWarned;
+    private readonly seenStepIds;
+    private readonly compensations;
+    private readonly audit;
+    private readonly determinism;
+    private readonly auditEnabled;
+    private readonly auditEmitter;
+    private readonly implicitInternalStepIdsPolicy;
+    constructor(store: IDurableStore, bus: IEventBus, executionId: string, attempt: number, options?: {
+        auditEnabled?: boolean;
+        auditEmitter?: DurableAuditEmitter;
+        implicitInternalStepIds?: ImplicitInternalStepIdsPolicy;
+    });
+    private assertNotCancelled;
+    private getStepId;
+    private internalStep;
+    step<T>(stepId: string): IStepBuilder<T>;
+    step<T>(stepId: DurableStepId<T>): IStepBuilder<T>;
+    step<T>(stepId: string | DurableStepId<T>, fn: () => Promise<T>): Promise<T>;
+    step<T>(stepId: string | DurableStepId<T>, options: StepOptions, fn: () => Promise<T>): Promise<T>;
+    _executeStep<T>(stepId: string, options: StepOptions, upFn: () => Promise<T>, downFn?: (result: T) => Promise<void>): Promise<T>;
+    rollback(): Promise<void>;
+    sleep(durationMs: number, options?: SleepOptions): Promise<void>;
+    waitForSignal<TPayload>(signal: IEventDefinition<TPayload>): Promise<TPayload>;
+    waitForSignal<TPayload>(signal: IEventDefinition<TPayload>, options: SignalOptions & {
+        timeoutMs: number;
+    }): Promise<{
+        kind: "signal";
+        payload: TPayload;
+    } | {
+        kind: "timeout";
+    }>;
+    waitForSignal<TPayload>(signal: IEventDefinition<TPayload>, options: SignalOptions): Promise<TPayload>;
+    emit<TPayload>(event: IEventDefinition<TPayload>, payload: TPayload, options?: EmitOptions): Promise<void>;
+    switch<TValue, TResult>(stepId: string, value: TValue, branches: SwitchBranch<TValue, TResult>[], defaultBranch?: Omit<SwitchBranch<TValue, TResult>, "match">): Promise<TResult>;
+    note(message: string, meta?: Record<string, unknown>): Promise<void>;
+}

package/dist/types/node/durable/core/DurableOperator.d.ts

@@ -0,0 +1,47 @@
+import { IDurableStore } from "./interfaces/store";
+import { Execution } from "./types";
+import type { DurableAuditEntry } from "./audit";
+import type { StepResult } from "./types";
+import type { ListExecutionsOptions } from "./interfaces/store";
+/**
+ * Administrative / operator API for durable workflows.
+ *
+ * This class is intentionally store-backed and side-effect free with respect to
+ * "running" workflows: it reads execution details and, when supported by the store,
+ * can perform operator actions (retry rollback, skip a step, force fail, patch state).
+ *
+ * Used by dashboards / CLIs / tooling to inspect and recover executions.
+ */
+export declare class DurableOperator {
+    private readonly store;
+    constructor(store: IDurableStore);
+    listExecutions(options?: ListExecutionsOptions): Promise<Execution[]>;
+    getExecutionDetail(executionId: string): Promise<{
+        execution: Execution | null;
+        steps: StepResult[];
+        audit: DurableAuditEntry[];
+    }>;
+    /**
+     * Resets an execution from `compensation_failed` (or other states) to `pending`.
+     * This effectively retries the workflow from the last memoized step.
+     */
+    retryRollback(executionId: string): Promise<void>;
+    /**
+     * Manually marks a step as completed with a specific result.
+     * Useful for skipping broken steps or providing a manual fix.
+     */
+    skipStep(executionId: string, stepId: string): Promise<void>;
+    /**
+     * Forces an execution to the `failed` state.
+     */
+    forceFail(executionId: string, reason: string): Promise<void>;
+    /**
+     * Manually patches the result of a step.
+     * Useful when a step failed to save its result but the side effect occurred.
+     */
+    editState(executionId: string, stepId: string, newState: unknown): Promise<void>;
+    /**
+     * Lists all executions that require manual intervention.
+     */
+    listStuckExecutions(): Promise<Execution[]>;
+}

package/dist/types/node/durable/core/DurableResource.d.ts

@@ -0,0 +1,80 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import type { Store } from "../../../models/Store";
+import type { IEventDefinition } from "../../../types/event";
+import type { ITask } from "../../../types/task";
+import type { IDurableContext } from "./interfaces/context";
+import type { DurableTask, ExecuteOptions, IDurableService, ScheduleOptions } from "./interfaces/service";
+import type { Schedule } from "./types";
+import type { IDurableStore } from "./interfaces/store";
+import { DurableOperator } from "./DurableOperator";
+import { type DurableFlowShape } from "./flowShape";
+export interface DurableResourceConfig {
+    worker?: boolean;
+}
+export interface IDurableResource extends Pick<IDurableService, "startExecution" | "cancelExecution" | "wait" | "execute" | "executeStrict" | "schedule" | "ensureSchedule" | "pauseSchedule" | "resumeSchedule" | "getSchedule" | "listSchedules" | "updateSchedule" | "removeSchedule" | "recover" | "signal"> {
+    /**
+     * Reads the durable context for the currently running workflow execution.
+     * Throws if called outside of a durable execution.
+     */
+    use(): IDurableContext;
+    /**
+     * Describe a durable workflow task using real runtime dependencies.
+     *
+     * - Non-durable deps are kept as-is (so pre-step control flow can use them).
+     * - Durable deps are shimmed so `durable.use()` returns the recorder context.
+     *
+     * The task must be registered in the runtime store (ie. part of the app tree).
+     *
+     * Accepts any Runner `ITask`. Generic `TInput` is inferred from the task,
+     * or can be specified explicitly: `describe<MyInput>(task, input)`.
+     */
+    describe<TInput>(task: ITask<TInput, any, any, any, any, any>, input?: TInput): Promise<DurableFlowShape>;
+    /**
+     * Store-backed operator API to inspect and administrate executions
+     * (steps/audit/history and operator actions where supported by the store).
+     */
+    readonly operator: DurableOperator;
+}
+/**
+ * A Runner-facing wrapper around `DurableService` that exposes a per-instance
+ * context store and the public durable API (`execute`, `signal`, `wait`, etc.).
+ *
+ * This enables tasks to depend on a specific durable instance and call
+ * `durable.use()` to access the per-execution durable context.
+ */
+export declare class DurableResource implements IDurableResource {
+    readonly service: IDurableService;
+    private readonly contextStorage;
+    private readonly store?;
+    private readonly runnerStore?;
+    private operatorInstance;
+    constructor(service: IDurableService, contextStorage: AsyncLocalStorage<IDurableContext>, store?: IDurableStore | undefined, runnerStore?: Store | undefined);
+    get operator(): DurableOperator;
+    use(): IDurableContext;
+    describe<TInput>(task: ITask<TInput, any, any, any, any, any>, input?: TInput): Promise<DurableFlowShape>;
+    private injectRecorderIntoDurableDeps;
+    startExecution<TInput>(task: DurableTask<TInput, unknown>, input?: TInput, options?: ExecuteOptions): Promise<string>;
+    cancelExecution(executionId: string, reason?: string): Promise<void>;
+    wait<TResult>(executionId: string, options?: {
+        timeout?: number;
+        waitPollIntervalMs?: number;
+    }): Promise<TResult>;
+    execute<TInput, TResult>(task: DurableTask<TInput, TResult>, input?: TInput, options?: ExecuteOptions): Promise<TResult>;
+    executeStrict<TInput, TResult>(task: undefined extends TResult ? never : DurableTask<TInput, TResult>, input?: TInput, options?: ExecuteOptions): Promise<TResult>;
+    schedule<TInput>(task: DurableTask<TInput, unknown>, input: TInput | undefined, options: ScheduleOptions): Promise<string>;
+    ensureSchedule<TInput>(task: DurableTask<TInput, unknown>, input: TInput | undefined, options: ScheduleOptions & {
+        id: string;
+    }): Promise<string>;
+    pauseSchedule(scheduleId: string): Promise<void>;
+    resumeSchedule(scheduleId: string): Promise<void>;
+    getSchedule(scheduleId: string): Promise<Schedule | null>;
+    listSchedules(): Promise<Schedule[]>;
+    updateSchedule(scheduleId: string, updates: {
+        cron?: string;
+        interval?: number;
+        input?: unknown;
+    }): Promise<void>;
+    removeSchedule(scheduleId: string): Promise<void>;
+    recover(): Promise<void>;
+    signal<TPayload>(executionId: string, signal: IEventDefinition<TPayload>, payload: TPayload): Promise<void>;
+}

package/dist/types/node/durable/core/DurableService.d.ts

@@ -0,0 +1,73 @@
+import { NoopEventBus } from "../bus/NoopEventBus";
+import type { DurableServiceConfig, DurableTask, ExecuteOptions, IDurableService, ScheduleOptions } from "./interfaces/service";
+import { type Schedule } from "./types";
+import type { IEventDefinition } from "../../../types/event";
+import { ExecutionManager, PollingManager } from "./managers";
+export { DurableExecutionError } from "./utils";
+/**
+ * High-level facade for the Durable Workflows subsystem.
+ *
+ * `DurableService` glues together the durable backends (store/queue/event bus) and
+ * the specialized managers that implement durable semantics:
+ *
+ * - `ExecutionManager` runs workflow attempts and injects `DurableContext`
+ * - `SignalHandler` delivers external signals to waiting steps
+ * - `WaitManager` waits for results (event-bus first, polling fallback)
+ * - `ScheduleManager` creates/updates schedules and their timers
+ * - `PollingManager` drives timers (sleep, retries, signal timeouts, schedules)
+ * - `AuditLogger` emits/persists an audit trail (best-effort)
+ *
+ * `DurableResource` wraps this service for Runner integration and provides
+ * `durable.use()` to read the per-execution `DurableContext`.
+ */
+export declare class DurableService implements IDurableService {
+    private readonly config;
+    private readonly taskRegistry;
+    private readonly auditLogger;
+    private readonly waitManager;
+    private readonly scheduleManager;
+    private readonly signalHandler;
+    private readonly executionManager;
+    private readonly pollingManager;
+    /** Unique worker ID for distributed timer coordination */
+    private readonly workerId;
+    constructor(config: DurableServiceConfig);
+    registerTask<TInput, TResult>(task: DurableTask<TInput, TResult>): void;
+    findTask(taskId: string): DurableTask<any, any> | undefined;
+    startExecution<TInput>(task: DurableTask<TInput, unknown>, input?: TInput, options?: ExecuteOptions): Promise<string>;
+    cancelExecution(executionId: string, reason?: string): Promise<void>;
+    execute<TInput, TResult>(task: DurableTask<TInput, TResult>, input?: TInput, options?: ExecuteOptions): Promise<TResult>;
+    executeStrict<TInput, TResult>(task: undefined extends TResult ? never : DurableTask<TInput, TResult>, input?: TInput, options?: ExecuteOptions): Promise<TResult>;
+    wait<TResult>(executionId: string, options?: {
+        timeout?: number;
+        waitPollIntervalMs?: number;
+    }): Promise<TResult>;
+    schedule<TInput>(task: DurableTask<TInput, unknown>, input: TInput | undefined, options: ScheduleOptions): Promise<string>;
+    ensureSchedule<TInput>(task: DurableTask<TInput, unknown>, input: TInput | undefined, options: ScheduleOptions & {
+        id: string;
+    }): Promise<string>;
+    recover(): Promise<void>;
+    start(): void;
+    stop(): Promise<void>;
+    pauseSchedule(id: string): Promise<void>;
+    resumeSchedule(id: string): Promise<void>;
+    getSchedule(id: string): Promise<Schedule | null>;
+    listSchedules(): Promise<Schedule[]>;
+    updateSchedule(id: string, updates: {
+        cron?: string;
+        interval?: number;
+        input?: unknown;
+    }): Promise<void>;
+    removeSchedule(id: string): Promise<void>;
+    signal<TPayload>(executionId: string, signal: IEventDefinition<TPayload>, payload: TPayload): Promise<void>;
+    processExecution(executionId: string): Promise<void>;
+    getEventBus(): NoopEventBus;
+    /** @internal - exposed for unit testing */
+    get _pollingManager(): PollingManager;
+    /** @internal - exposed for unit testing */
+    get _executionManager(): ExecutionManager;
+    /** @internal - exposed for unit testing (delegates to pollingManager) */
+    handleTimer(timer: import("./types").Timer): Promise<void>;
+}
+export declare function initDurableService(config: DurableServiceConfig): Promise<DurableService>;
+export declare function disposeDurableService(service: IDurableService, config: DurableServiceConfig): Promise<void>;

package/dist/types/node/durable/core/DurableWorker.d.ts

@@ -0,0 +1,19 @@
+import type { IDurableQueue } from "./interfaces/queue";
+import type { IDurableExecutionProcessor } from "./interfaces/service";
+/**
+ * Durable queue consumer (worker process role).
+ *
+ * The worker listens to the durable queue and turns queue messages into
+ * `processExecution(executionId)` calls on the service layer (`ExecutionManager`
+ * behind `IDurableExecutionProcessor`). This is how "resume" work is distributed
+ * horizontally: the store is the source of truth, the queue provides delivery.
+ */
+export declare class DurableWorker {
+    private readonly service;
+    private readonly queue;
+    constructor(service: IDurableExecutionProcessor, queue: IDurableQueue);
+    start(): Promise<void>;
+    private handleMessage;
+    private extractExecutionId;
+}
+export declare function initDurableWorker(service: IDurableExecutionProcessor, queue: IDurableQueue): Promise<DurableWorker>;