@lostgradient/weft 0.2.0

package/dist/core/engine/index.d.ts

@@ -0,0 +1,311 @@
+import { type Storage as WeftStorage } from '../../storage/interface.ts';
+import { type ActivityMetadata, type ActivityRegistrationOptions, type RegisteredActivityFunction } from '../activity-registry.ts';
+import type { StoredStreamChunk } from '../context.ts';
+import type { Interceptor } from '../interceptor.ts';
+import { type ReviewRequest } from '../review/index.ts';
+import { Scheduler } from '../scheduler.ts';
+import { type AnyActivityDefinition, type AnyWorkflowDefinition, type AttributeFilterKey, type BulkCancelResult, type BulkDeleteResult, type BulkOperationCommitOptions, type BulkOperationDryRunOptions, type BulkOperationDryRunResult, type BulkSignalAllCommitOptions, type BulkSignalAllDryRunOptions, type BulkSignalResult, type BulkTagResult, type CheckpointState, type CheckpointSummary, type CoordinatedUpdateResult, type DefaultActivityTypes, type DefaultWorkflowRegistry, type ForkOptions, type InferActivityEntries, type InferActivityEntry, type InferWorkflowEntries, type InferWorkflowEntry, type ListFilter, type ListOptions, type PaginatedResult, type PurgeResult, type QueryDefinition, type RegisteredWorkflowDefinition, type RetentionOverview, type ReviewListEntry, type ReviewListFilter, type ScheduleDefinition, type ScheduleFilter, type ScheduleOptions, type ScheduleSpec, type ScheduleSummary, type SearchAttributeValue, type SignalDefinition, type SignalDeliveryOptions, type StartOptions, type SubmitReviewOptions, type TypedListFilter, type UpdateDefinition, type WorkflowEvent, type WorkflowInput, type WorkflowOutput, type WorkflowReplay, type WorkflowState, type WorkflowSummary, type WorkflowTimelineEntry } from '../types.ts';
+import type { TimerEntry } from '../types/checkpoint.ts';
+import type { WorkflowAlreadyRegistered } from '../types/workflow-builder.ts';
+import { type AggregateOptions, type AggregateResult } from './aggregate.ts';
+import { type EmptyActivityDefinitions, type EmptyWorkflowDefinitions, type KnownWorkflowNames } from './construction.ts';
+import { type ActivityDefinitionName, type EngineCreateOptions, type RegisteredActivityDefinitionExecute, type UnknownWorkflowNameWhenDefaultRegistryIsEmpty } from './engine-create-types.ts';
+import type { EngineConstructorOptions } from './engine-internal-types.ts';
+import type { EngineStateNamespace } from './engine-state-namespace.ts';
+import { HANDLE_RESULT_PROMISE, ScheduleHandle, WorkflowHandle } from './handles.ts';
+import { type RecoverAllOptions } from './lifecycle.ts';
+import { assertCompatiblePersistedDataVersion } from './persisted-data-version.ts';
+import { type WorkflowFeedListener, type WorkflowFeedRecord, type WorkflowFeedSelector } from './workflow-feed.ts';
+export { ActivityReconciliationCapabilityError, ActivityReconciliationConflictError, ActivityReconciliationIndeterminateError, } from './activity-reconciliation.ts';
+export { AsyncActivityTokenNotFoundError } from './async-activity-completion.ts';
+export type { PendingAsyncActivity } from './async-activity-completion.ts';
+export type { PendingTimelineEntry, RegistrationEntry, ResolvedOptions, TrackedWaiterKeys, WorkflowResultWaiter, } from './engine-internal-types.ts';
+export { ActivityResolutionError, BulkDeleteRequiresTerminalWorkflowsError, BulkOperationConfirmationError, EngineCreateNameMismatchError, EngineDisposedError, PersistedDataIncompatibleError, WorkflowAlreadyExistsError, WorkflowNotFoundError, WorkflowNotRegisteredError, WorkflowTypeNotRegisteredForRecoveryError, } from './errors.ts';
+export { HANDLE_RESULT_PROMISE, ScheduleHandle, WorkflowHandle } from './handles.ts';
+export type { RecoverAllOptions } from './lifecycle.ts';
+export type { WorkflowFeedListener, WorkflowFeedRecord, WorkflowFeedSelector, } from './workflow-feed.ts';
+export type { EngineCreateOptions } from './engine-create-types.ts';
+export { clearEngineLeakWarningTokenForTesting, getEngineLeakCollectionCountForTesting, hasEngineLeakWarningTokenForTesting, setEngineLeakWarningOverrideForTesting, setNextEngineLeakWarningTokenForTesting, shouldEmitEngineLeakWarningForTesting, } from './engine-leak-warnings.ts';
+export type { EngineStateNamespace } from './engine-state-namespace.ts';
+export { assertCompatiblePersistedDataVersion };
+export declare const ENGINE_PARKED_WORKFLOW_COUNT_FOR_TESTING: unique symbol;
+export declare const ENGINE_SIGNAL_WAITER_COUNT_FOR_TESTING: unique symbol;
+/**
+ * Durable execution engine.
+ *
+ * Register workflow and activity definitions with {@link Engine.register},
+ * start workflows with {@link Engine.start},
+ * and observe or cancel them via the returned {@link WorkflowHandle}. Each
+ * workflow is a generator that yields to a {@link Context}; the engine
+ * persists a checkpoint at every yield so the workflow survives crashes,
+ * restarts, and worker reassignment without losing progress.
+ *
+ * The default type parameters preserve the module-augmentation registry
+ * model. Use `new Engine<{}, {}>()` when you want an engine-local registry
+ * that only accepts definitions added through `register`.
+ *
+ * @example Run a workflow with an activity
+ * ```ts
+ * import { workflow, activity, Engine, type Context, type WorkflowContext } from '@lostgradient/weft';
+ * const fetchUser = activity({
+ *   name: 'fetchUser',
+ *   execute: async (input: unknown) => ({ name: 'Alice' }),
+ * });
+ * const engine = new Engine();
+ * engine.register(
+ *   workflow({ name: 'greet' }).execute(async function* (ctx: WorkflowContext, input: unknown) {
+ *     const user = yield* ctx.run(fetchUser, input);
+ *     return `Hello, ${user.name}`;
+ *   }),
+ * );
+ * const handle = await engine.start('greet', 'user-1');
+ * void handle;
+ * ```
+ *
+ * @example With a SQLite backend
+ * ```ts
+ * import { Engine } from '@lostgradient/weft';
+ * import { BunSQLiteStorage } from '@lostgradient/weft/storage/sqlite/bun';
+ * await using storage = new BunSQLiteStorage('./weft.db');
+ * await using engine = new Engine({ storage });
+ * await engine.recoverAll();
+ * void engine;
+ * ```
+ */
+export declare class Engine<TWorkflows extends object = DefaultWorkflowRegistry, TActivities extends object = DefaultActivityTypes> extends EventTarget implements Disposable, AsyncDisposable {
+    #private;
+    /**
+     * Construct and register an engine in one step. Activities are registered
+     * before workflows. Recovery runs by default after all definitions are
+     * installed; pass `recover: false` to opt out.
+     *
+     * @example
+     * ```ts
+     * import { activity, Engine, workflow } from '@lostgradient/weft';
+     *
+     * const greet = activity({ name: 'greet', execute: async (name: string) => `Hi ${name}` });
+     * const welcome = workflow({ name: 'welcome' }).execute(async function* (ctx, input: string) {
+     *   return yield* ctx.run(greet, input);
+     * });
+     *
+     * const engine = await Engine.create({
+     *   activities: { greet },
+     *   workflows: { welcome },
+     * });
+     * void engine;
+     * ```
+     */
+    static create(options: EngineCreateOptions<EmptyWorkflowDefinitions, EmptyActivityDefinitions> & {
+        activities?: undefined;
+        workflows?: undefined;
+    }): Promise<Engine>;
+    static create<TWorkflowDefinitions extends Record<string, AnyWorkflowDefinition>>(options: EngineCreateOptions<TWorkflowDefinitions, EmptyActivityDefinitions> & {
+        activities?: undefined;
+        workflows: TWorkflowDefinitions;
+    }): Promise<Engine<InferWorkflowEntries<TWorkflowDefinitions>>>;
+    static create<TActivityDefinitions extends Record<string, AnyActivityDefinition>>(options: EngineCreateOptions<EmptyWorkflowDefinitions, TActivityDefinitions> & {
+        activities: TActivityDefinitions;
+        workflows?: undefined;
+    }): Promise<Engine<DefaultWorkflowRegistry, InferActivityEntries<TActivityDefinitions>>>;
+    static create<TWorkflowDefinitions extends Record<string, AnyWorkflowDefinition>, TActivityDefinitions extends Record<string, AnyActivityDefinition>>(options: EngineCreateOptions<TWorkflowDefinitions, TActivityDefinitions> & {
+        activities: TActivityDefinitions;
+        workflows: TWorkflowDefinitions;
+    }): Promise<Engine<InferWorkflowEntries<TWorkflowDefinitions>, InferActivityEntries<TActivityDefinitions>>>;
+    constructor(options?: EngineConstructorOptions);
+    get state(): EngineStateNamespace;
+    /**
+     * Register a workflow by name or definition, or register an activity
+     * definition. Definition overloads return this same engine with the
+     * definition added to its phantom type registry. This is additive over the
+     * module-augmented default registry; construct `new Engine<{}, {}>()` for a
+     * strict local registry.
+     *
+     * @example
+     * ```ts
+     * import { Engine, workflow, type WorkflowContext } from '@lostgradient/weft';
+     *
+     * const engine = new Engine();
+     * engine.register(
+     *   workflow({ name: 'hello' }).execute(async function* (_ctx: WorkflowContext, name: string) {
+     *     return `Hello, ${name}`;
+     *   }),
+     * );
+     * ```
+     */
+    /**
+     * Builder-workflow registration with a parameter-position name-conflict
+     * guard. New names widen the engine's typed workflow registry; re-registering
+     * a name already present intersects the parameter type with
+     * {@link WorkflowAlreadyRegistered} — a branded marker no real
+     * `WorkflowDefinition` satisfies — so the call line itself fails to compile.
+     *
+     * Runtime is more lenient: registering the same `WorkflowDefinition` object
+     * reference again is idempotent (no-op); same-name-different-object throws.
+     * TypeScript cannot distinguish the two at the type level. Callers needing
+     * the runtime-idempotent path from TypeScript must use a documented escape
+     * hatch (e.g. `engine.register(welcome as never)`).
+     */
+    register<TDefinition extends AnyWorkflowDefinition>(workflow: TDefinition & (TDefinition['name'] extends keyof TWorkflows ? WorkflowAlreadyRegistered<TDefinition['name']> : unknown)): Engine<TWorkflows & InferWorkflowEntry<TDefinition>, TActivities>;
+    register<TDefinition extends AnyActivityDefinition, TName extends Extract<keyof TActivities, string> & ActivityDefinitionName<TDefinition>>(definition: TDefinition & {
+        readonly name: TName;
+        readonly execute: RegisteredActivityDefinitionExecute<TActivities, TName>;
+    }): Engine<TWorkflows, TActivities & InferActivityEntry<TDefinition>>;
+    register<TDefinition extends AnyActivityDefinition>(definition: ActivityDefinitionName<TDefinition> extends Extract<keyof TActivities, string> ? never : TDefinition): Engine<TWorkflows, TActivities & InferActivityEntry<TDefinition>>;
+    /**
+     * Register every workflow from an object map at once and return a typed
+     * engine view that exposes the newly added workflow names.
+     *
+     * Mirrors `Engine.create({ workflows })` for post-construction use. The map
+     * key is canonical: if a value's runtime `name` disagrees with its key, the
+     * call throws {@link EngineCreateNameMismatchError} before any partial
+     * registration completes (insertion order — earlier entries persist).
+     *
+     * @example
+     * ```ts
+     * import { Engine, workflow } from '@lostgradient/weft';
+     *
+     * const welcome = workflow({ name: 'welcome' })
+     *   .execute(async function* (_ctx, name: string) {
+     *     return `Hello, ${name}`;
+     *   });
+     *
+     * const engine = new Engine();
+     * const typedEngine = engine.registerWorkflows({ welcome });
+     * await typedEngine.start('welcome', 'Ada');
+     * ```
+     */
+    registerWorkflows<TWorkflowDefinitions extends Record<string, AnyWorkflowDefinition>>(workflows: TWorkflowDefinitions): Engine<TWorkflows & InferWorkflowEntries<TWorkflowDefinitions>, TActivities>;
+    addInterceptor(interceptor: Interceptor): void;
+    protected resolveRegisteredActivity(name: string): RegisteredActivityFunction | undefined;
+    protected registerActivityFunction(name: string, fn: Function, options?: ActivityRegistrationOptions): void;
+    protected unregisterRegisteredActivity(name: string): void;
+    getWorkflowDefinition(type: string): RegisteredWorkflowDefinition | undefined;
+    listWorkflowDefinitions(): RegisteredWorkflowDefinition[];
+    getActivityDefinition(name: string): ActivityMetadata | undefined;
+    listActivityDefinitions(): ActivityMetadata[];
+    start<TName extends KnownWorkflowNames<TWorkflows>>(type: TName, input: WorkflowInput<TWorkflows, TName>, options?: StartOptions): Promise<WorkflowHandle<WorkflowOutput<TWorkflows, TName>>>;
+    start<TName extends string>(type: UnknownWorkflowNameWhenDefaultRegistryIsEmpty<TWorkflows, TName>, input: unknown, options?: StartOptions): Promise<WorkflowHandle>;
+    getHandle(workflowId: string): WorkflowHandle;
+    list<const TAttributeKeys extends readonly AttributeFilterKey[] = readonly AttributeFilterKey[]>(filter?: TypedListFilter<TAttributeKeys>, options?: ListOptions): Promise<PaginatedResult<WorkflowSummary>>;
+    aggregate(filter: ListFilter | undefined, options: AggregateOptions): Promise<AggregateResult>;
+    getRetentionOverview(): RetentionOverview;
+    purge(filter?: ListFilter): Promise<PurgeResult>;
+    cancelAll(filter: ListFilter, options: BulkOperationDryRunOptions): Promise<BulkOperationDryRunResult>;
+    cancelAll(filter: ListFilter, options?: BulkOperationCommitOptions): Promise<BulkCancelResult>;
+    signalAll(filter: ListFilter, name: string, payload: unknown, options: BulkSignalAllDryRunOptions): Promise<BulkOperationDryRunResult>;
+    signalAll(filter: ListFilter, name: string, payload: unknown, options: BulkSignalAllCommitOptions): Promise<BulkSignalResult>;
+    signalAll(filter: ListFilter, name: string, payload?: unknown, options?: BulkOperationCommitOptions): Promise<BulkSignalResult>;
+    deleteAll(filter: ListFilter, options: BulkOperationDryRunOptions): Promise<BulkOperationDryRunResult>;
+    deleteAll(filter: ListFilter, options?: BulkOperationCommitOptions): Promise<BulkDeleteResult>;
+    tagAll(filter: ListFilter, tags: string[], options: BulkOperationDryRunOptions): Promise<BulkOperationDryRunResult>;
+    tagAll(filter: ListFilter, tags: string[], options?: BulkOperationCommitOptions): Promise<BulkTagResult>;
+    untagAll(filter: ListFilter, tags: string[], options: BulkOperationDryRunOptions): Promise<BulkOperationDryRunResult>;
+    untagAll(filter: ListFilter, tags: string[], options?: BulkOperationCommitOptions): Promise<BulkTagResult>;
+    schedule<TInput>(definition: ScheduleDefinition<TInput>): Promise<ScheduleHandle>;
+    schedule(type: string, input: unknown, spec: string | ScheduleSpec, options?: ScheduleOptions): Promise<ScheduleHandle>;
+    getSchedule(scheduleId: string): Promise<ScheduleSummary | null>;
+    listSchedules(filter?: ScheduleFilter): Promise<PaginatedResult<ScheduleSummary>>;
+    pauseSchedule(scheduleId: string): Promise<void>;
+    resumeSchedule(scheduleId: string): Promise<void>;
+    cancelSchedule(scheduleId: string): Promise<void>;
+    updateSchedule(scheduleId: string, newSpec: string | ScheduleSpec): Promise<void>;
+    [HANDLE_RESULT_PROMISE](workflowId: string): Promise<unknown>;
+    [ENGINE_PARKED_WORKFLOW_COUNT_FOR_TESTING](): number;
+    [ENGINE_SIGNAL_WAITER_COUNT_FOR_TESTING](): number;
+    signal(workflowId: string, name: SignalDefinition): Promise<void>;
+    signal<TInput>(workflowId: string, name: SignalDefinition<TInput>, payload: TInput, options?: SignalDeliveryOptions): Promise<void>;
+    signal(workflowId: string, name: string, payload?: unknown, options?: SignalDeliveryOptions): Promise<void>;
+    update(workflowId: string, name: UpdateDefinition, payload?: void, options?: {
+        timeout?: number;
+    }): Promise<unknown>;
+    update<TInput, TOutput>(workflowId: string, name: UpdateDefinition<TInput, TOutput>, payload: TInput, options?: {
+        timeout?: number;
+    }): Promise<TOutput>;
+    update(workflowId: string, name: string, payload?: unknown, options?: {
+        timeout?: number;
+    }): Promise<unknown>;
+    query<TOutput>(workflowId: string, name: QueryDefinition<void, TOutput>): Promise<TOutput>;
+    query<TInput, TOutput>(workflowId: string, name: QueryDefinition<TInput, TOutput>, input: TInput): Promise<TOutput>;
+    query(workflowId: string, name: string, input?: unknown): Promise<unknown>;
+    getStreamChunks(workflowId: string, key: string, options?: {
+        after?: number;
+    }): Promise<StoredStreamChunk[]>;
+    fork(sourceWorkflowId: string, options?: ForkOptions): Promise<WorkflowHandle>;
+    resume(workflowId: string): Promise<WorkflowHandle>;
+    /**
+     * Recover every running workflow found in storage. By default, recovery
+     * fails before doing any resume work if a stored running workflow has no
+     * registered workflow type on this engine.
+     *
+     * `acknowledgeUnknownWorkflowTypes` is a dangerous escape hatch for rolling
+     * deploys or explicit storage migrations.
+     * When set, unknown workflow types are skipped and reported through
+     * {@link WorkflowRecoverySkippedEvent}.
+     */
+    recoverAll(options?: RecoverAllOptions): Promise<WorkflowHandle[]>;
+    /**
+     * Complete a deferred activity out-of-band with `result`. The activity must
+     * have parked itself via `ActivityContext.completeAsync()`; pass the durable
+     * task token announced through the `activity:async-pending` event (or
+     * persisted by your callback dispatcher). The parked workflow resumes as
+     * though the activity had returned `result` inline.
+     *
+     * @throws {AsyncActivityTokenNotFoundError} when no pending activity matches
+     * the token (unknown, or already completed/failed — tokens are single-use).
+     */
+    completeAsyncActivity(token: string, result: unknown): Promise<void>;
+    /**
+     * Fail a deferred activity out-of-band with `error`. The error is thrown into
+     * the workflow generator at the parked step — identical to an inline activity
+     * that threw — so the workflow's own try/catch and any configured retry
+     * policy apply unchanged.
+     *
+     * @throws {AsyncActivityTokenNotFoundError} when no pending activity matches
+     * the token (unknown, or already completed/failed — tokens are single-use).
+     */
+    failAsyncActivity(token: string, error: unknown): Promise<void>;
+    cancel(workflowId: string): Promise<void>;
+    timeout(workflowId: string): Promise<void>;
+    get(workflowId: string): Promise<WorkflowState | null>;
+    getAttributes(workflowId: string): Promise<Record<string, SearchAttributeValue> | null>;
+    setAttributes(workflowId: string, attributes: Record<string, SearchAttributeValue>): Promise<void>;
+    addTags(workflowId: string, ...tags: string[]): Promise<void>;
+    removeTags(workflowId: string, ...tags: string[]): Promise<void>;
+    getEvents(workflowId: string): Promise<WorkflowEvent[]>;
+    replayWorkflowFeed(workflowId: string, selector: WorkflowFeedSelector, afterSequence: number): AsyncIterable<WorkflowFeedRecord>;
+    snapshotWorkflowFeedTail(workflowId: string, selector: WorkflowFeedSelector): Promise<number>;
+    subscribeWorkflowFeedCommits(workflowId: string, selector: WorkflowFeedSelector, listener: WorkflowFeedListener): () => void;
+    listCheckpoints(workflowId: string): Promise<CheckpointSummary[]>;
+    getCheckpointAt(workflowId: string, step: number): Promise<CheckpointState | null>;
+    getTimeline(workflowId: string): Promise<WorkflowTimelineEntry[]>;
+    replayTo(workflowId: string, step: number): Promise<WorkflowReplay | null>;
+    listReviews(filter?: ReviewListFilter): Promise<ReviewListEntry[]>;
+    getReview(workflowId: string, reviewId: string): Promise<ReviewRequest | null>;
+    submitReview(reviewId: string, options: SubmitReviewOptions): Promise<void>;
+    getUpdateResult(updateId: string): Promise<import('../updates.ts').UpdateResponse | null>;
+    submitCoordinatedUpdate(workflowId: string, name: string, payload?: unknown, options?: {
+        timeout?: number;
+        idempotencyKey?: string;
+    }): Promise<CoordinatedUpdateResult>;
+    [Symbol.dispose](): void;
+    [Symbol.asyncDispose](): Promise<void>;
+    get storage(): WeftStorage;
+    get scheduler(): Scheduler;
+    /**
+     * Fire a single timer entry directly. Intended for external schedulers
+     * (Service Worker, custom transports) that own timer dispatch but want
+     * the engine to actually resume the workflow associated with the entry.
+     *
+     * Most users do not call this directly. The internal `Scheduler` invokes
+     * the same code path automatically when its tick observes a due entry.
+     *
+     * @example
+     * ```ts
+     * import { Engine } from '@lostgradient/weft';
+     * declare const externalEntry: import('@lostgradient/weft').TimerEntry;
+     * const engine = new Engine();
+     * await engine.fireTimer(externalEntry);
+     * ```
+     */
+    fireTimer(entry: TimerEntry): Promise<void>;
+}