@lostgradient/weft 0.2.0 → 0.3.0

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

@@ -1,9 +1,12 @@
-import type { QueryDefinition, ScheduleSpec, ScheduleSummary, SearchAttributeValue, SignalDefinition, SignalDeliveryOptions, UpdateDefinition, WorkflowState } from '../types.ts';
+import type { LaunchMetadata, QueryDefinition, SearchAttributeValue, SignalDefinition, SignalDeliveryOptions, UpdateDefinition, WorkflowState } from '../types.ts';
+import type { WorkflowSnapshot } from '../types/workflow-snapshot.ts';
 export declare function getWorkflowExecutionStartedAt(state: Pick<WorkflowState, 'createdAt' | 'startedAt'>): number;
 export declare const HANDLE_RESULT_PROMISE: unique symbol;
 export interface WorkflowHandleEngine extends EventTarget {
     [HANDLE_RESULT_PROMISE](workflowId: string): Promise<unknown>;
     cancel(workflowId: string): Promise<void>;
+    suspend(workflowId: string): Promise<void>;
+    resume(workflowId: string): Promise<WorkflowHandle>;
     signal(workflowId: string, name: string, payload?: unknown, options?: SignalDeliveryOptions): Promise<void>;
     update(workflowId: string, name: string, payload?: unknown, options?: {
         timeout?: number;
@@ -14,13 +17,13 @@ export interface WorkflowHandleEngine extends EventTarget {
     addTags(workflowId: string, ...tags: string[]): Promise<void>;
     removeTags(workflowId: string, ...tags: string[]): Promise<void>;
     get(workflowId: string): Promise<WorkflowState | null>;
-}
-export interface ScheduleHandleEngine {
-    pauseSchedule(scheduleId: string): Promise<void>;
-    resumeSchedule(scheduleId: string): Promise<void>;
-    cancelSchedule(scheduleId: string): Promise<void>;
-    updateSchedule(scheduleId: string, newSpec: string | ScheduleSpec): Promise<void>;
-    getSchedule(scheduleId: string): Promise<ScheduleSummary | null>;
+    /**
+     * Current checkpoint step (the run's cursor) for a workflow, or `null` when no
+     * checkpoint exists. Reads the in-memory checkpoint when the run is live in
+     * this engine, otherwise the durably persisted checkpoint — so it is correct
+     * for both an in-flight run and one recovered or inspected in a fresh process.
+     */
+    getCurrentCheckpointStep(workflowId: string): Promise<number | null>;
 }
 /**
  * Handle to a running or completed workflow. Returned by {@link Engine.start}
@@ -72,6 +75,84 @@ export declare class WorkflowHandle<TResult = unknown> extends EventTarget imple
     constructor(id: string, engine: WorkflowHandleEngine);
     result(): Promise<TResult>;
     cancel(): Promise<void>;
+    /**
+     * Suspend this workflow without terminating it: it transitions to the
+     * non-terminal `'suspended'` status, keeps its durable checkpoint, and is
+     * later resumable via {@link WorkflowHandle.resume}. Unlike `cancel()`, this
+     * does not run cancel handlers and does not settle `result()` — the result
+     * promise stays pending until a later `resume()` completes the run. A
+     * suspended workflow is NOT auto-recovered by `engine.recoverAll()`; resume it
+     * explicitly. Suspending a workflow that is not running is a no-op.
+     */
+    suspend(): Promise<void>;
+    /**
+     * Resume this workflow from its persisted checkpoint after it was suspended
+     * (or left `'running'` by a prior process). The run is re-driven on this
+     * engine; `result()` on this handle resolves when the resumed run completes.
+     * Throws if the workflow is in a status that cannot be resumed (terminal,
+     * pending, or not found).
+     */
+    resume(): Promise<void>;
+    /**
+     * Reconstruct this workflow's launch context — its original `input` and the
+     * launch options recoverable from durable state — from the persisted
+     * {@link WorkflowState}. Resolves `null` if the workflow no longer exists
+     * (never started, or purged).
+     *
+     * Designed for the post-`recoverAll()` case: a recovered handle can recover
+     * the input a run was started with (and its `id`/`tags`) without the caller
+     * keeping a side table correlating recovered workflows back to their launch
+     * context. This is an async read (it loads state) so it behaves identically
+     * on handles from `start()`, `recoverAll()`, and `getHandle()` — none of which
+     * is special-cased — rather than a sync property that would be `undefined` on
+     * a handle created without a state load.
+     *
+     * @example
+     * ```ts
+     * import { Engine } from '@lostgradient/weft';
+     *
+     * const engine = new Engine();
+     * const handles = await engine.recoverAll();
+     * for (const handle of handles) {
+     *   const metadata = await handle.getLaunchMetadata();
+     *   if (metadata) {
+     *     // rebuild this run's dependencies from metadata.input
+     *     void metadata.input;
+     *   }
+     * }
+     * ```
+     */
+    getLaunchMetadata(): Promise<LaunchMetadata | null>;
+    /**
+     * A point-in-time view of this workflow's progress: its status and current
+     * checkpoint step (cursor). Resolves `null` if the workflow no longer exists.
+     * The `status` matches `engine.get(id)` — notably it reports `'pending'` for a
+     * run whose inline start is still queued, even though its persisted status is
+     * `'running'`.
+     *
+     * Designed for observing a recovered run: after `engine.recoverAll()`, a
+     * caller can read where a resumed run currently is — and rebuild its own
+     * progress adapter to re-register the run on a live surface — without waiting
+     * for the run's final `result()`. It is an async read (loads state +
+     * checkpoint), so it behaves identically on handles from `start()`,
+     * `recoverAll()`, and `getHandle()`.
+     *
+     * @example
+     * ```ts
+     * import { Engine } from '@lostgradient/weft';
+     *
+     * const engine = new Engine();
+     * const handles = await engine.recoverAll();
+     * for (const handle of handles) {
+     *   const snapshot = await handle.snapshot();
+     *   if (snapshot) {
+     *     // re-register a progress adapter at snapshot.step
+     *     void snapshot.step;
+     *   }
+     * }
+     * ```
+     */
+    snapshot(): Promise<WorkflowSnapshot | null>;
     signal(name: SignalDefinition): Promise<void>;
     signal<TInput>(name: SignalDefinition<TInput>, payload: TInput, options?: SignalDeliveryOptions): Promise<void>;
     signal(name: string, payload?: unknown, options?: SignalDeliveryOptions): Promise<void>;
@@ -103,35 +184,3 @@ export declare class WorkflowHandle<TResult = unknown> extends EventTarget imple
     };
     [Symbol.asyncDispose](): Promise<void>;
 }
-/**
- * Handle to a recurring schedule created by {@link Engine.schedule}. Use
- * `handle.pause()`, `handle.resume()`, `handle.cancel()`, or
- * `handle.update(cronExpression)` to manage the schedule lifecycle.
- * `handle.describe()` returns the current {@link ScheduleSummary}.
- *
- * @example
- * ```ts
- * import { workflow, Engine, ScheduleHandle } from '@lostgradient/weft';
- *
- * const engine = new Engine();
- * engine.register(workflow({ name: 'daily-report' }).execute(async function* () { return 'ok'; }));
- *
- * const handle = await engine.schedule('daily-report', null, '0 9 * * *');
- * const typedHandle: ScheduleHandle = handle;
- * await handle.pause();
- * const summary = await handle.describe();
- * void typedHandle;
- * console.log(summary.status); // 'paused'
- * await handle.cancel();
- * ```
- */
-export declare class ScheduleHandle {
-    #private;
-    readonly id: string;
-    constructor(id: string, engine: ScheduleHandleEngine);
-    pause(): Promise<void>;
-    resume(): Promise<void>;
-    cancel(): Promise<void>;
-    update(newSpec: string | ScheduleSpec): Promise<void>;
-    describe(): Promise<ScheduleSummary>;
-}

package/dist/core/engine/handles.js

@@ -51,6 +51,31 @@ export class WorkflowHandle extends EventTarget {
   async cancel() {
     return this.#engine.cancel(this.id);
   }
+  async suspend() {
+    return this.#engine.suspend(this.id);
+  }
+  async resume() {
+    await this.#engine.resume(this.id);
+  }
+  async getLaunchMetadata() {
+    const state = await this.#engine.get(this.id);
+    if (state === null)
+      return null;
+    return {
+      input: state.input,
+      launchOptions: {
+        id: state.id,
+        ...state.tags !== void 0 && state.tags.length > 0 && { tags: state.tags }
+      }
+    };
+  }
+  async snapshot() {
+    const state = await this.#engine.get(this.id);
+    if (state === null)
+      return null;
+    const step = await this.#engine.getCurrentCheckpointStep(this.id);
+    return { status: state.status, step: step ?? 0 };
+  }
   async signal(nameOrDefinition, payload, options) {
     return this.#engine.signal(this.id, messageName(nameOrDefinition), payload, options);
   }
@@ -144,30 +169,3 @@ export class WorkflowHandle extends EventTarget {
   }
   async[Symbol.asyncDispose]() {}
 }
-
-export class ScheduleHandle {
-  id;
-  #engine;
-  constructor(id, engine) {
-    this.id = id;
-    this.#engine = engine;
-  }
-  async pause() {
-    await this.#engine.pauseSchedule(this.id);
-  }
-  async resume() {
-    await this.#engine.resumeSchedule(this.id);
-  }
-  async cancel() {
-    await this.#engine.cancelSchedule(this.id);
-  }
-  async update(newSpec) {
-    await this.#engine.updateSchedule(this.id, newSpec);
-  }
-  async describe() {
-    const schedule = await this.#engine.getSchedule(this.id);
-    if (!schedule)
-      throw Error(`Schedule "${this.id}" not found`);
-    return schedule;
-  }
-}

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

@@ -4,7 +4,7 @@ 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 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 StartOrSignalSignal, 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';
@@ -12,17 +12,19 @@ import { type EmptyActivityDefinitions, type EmptyWorkflowDefinitions, type Know
 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 { HANDLE_RESULT_PROMISE, WorkflowHandle } from './handles.ts';
 import { type RecoverAllOptions } from './lifecycle.ts';
 import { assertCompatiblePersistedDataVersion } from './persisted-data-version.ts';
+import { ScheduleHandle } from './schedule-handle.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 { ActivityResolutionError, BulkDeleteRequiresTerminalWorkflowsError, BulkOperationConfirmationError, EngineCreateNameMismatchError, EngineDisposedError, IdempotencyKeyPurgedError, PersistedDataIncompatibleError, StartOrSignalConflictError, WorkflowAlreadyExistsError, WorkflowNotFoundError, WorkflowNotRegisteredError, WorkflowSuspendNotSupportedError, WorkflowTypeNotRegisteredForRecoveryError, } from './errors.ts';
+export { HANDLE_RESULT_PROMISE, WorkflowHandle } from './handles.ts';
 export type { RecoverAllOptions } from './lifecycle.ts';
+export { ScheduleHandle } from './schedule-handle.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';
@@ -30,6 +32,7 @@ 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;
+export declare const ENGINE_SLEEP_RESOLVER_COUNT_FOR_TESTING: unique symbol;
 /**
  * Durable execution engine.
  *
@@ -185,6 +188,25 @@ export declare class Engine<TWorkflows extends object = DefaultWorkflowRegistry,
     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>;
+    /**
+     * Atomically start a workflow or signal it if it already exists
+     * (signal-with-start). With an absent target, the workflow record and the
+     * first signal commit in one batch and the freshly-launched run consumes the
+     * signal on its first drive. A non-terminal target (running, pending, or
+     * suspended) is signalled through the normal signal path; a terminal target
+     * throws {@link StartOrSignalConflictError} rather than starting a new run or
+     * dropping the signal.
+     *
+     * Concurrent callers converge on one workflow and one delivered signal. Pass
+     * `options.idempotencyKey` to dedup independent callers (e.g. retried
+     * webhooks); the signal id derives from the key when `signal.signalId` is
+     * omitted, so callers that share only the key still converge. `signal.signalId`
+     * and `options.idempotencyKey` are mutually exclusive (provide exactly one), as
+     * are `options.id` and `options.idempotencyKey`. Requires a storage backend
+     * with `conditionalBatch`.
+     */
+    startOrSignal<TName extends KnownWorkflowNames<TWorkflows>>(type: TName, input: WorkflowInput<TWorkflows, TName>, signal: StartOrSignalSignal, options?: StartOptions): Promise<WorkflowHandle<WorkflowOutput<TWorkflows, TName>>>;
+    startOrSignal<TName extends string>(type: UnknownWorkflowNameWhenDefaultRegistryIsEmpty<TWorkflows, TName>, input: unknown, signal: StartOrSignalSignal, 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>;
@@ -201,6 +223,37 @@ export declare class Engine<TWorkflows extends object = DefaultWorkflowRegistry,
     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>;
+    /**
+     * Register a recurring schedule that starts a workflow on a cron expression or
+     * fixed interval. Returns a {@link ScheduleHandle} for pausing, resuming,
+     * updating, or cancelling the schedule.
+     *
+     * Two call forms:
+     * - A {@link ScheduleDefinition} object: `engine.schedule({ workflow, cron, input })`.
+     *   Carries the workflow (definition or type name), the `cron`/`every` spec,
+     *   optional `input`, `id`, `overlapPolicy`, and `backfill`.
+     * - Positional: `engine.schedule(type, input, spec, options?)` where `spec` is
+     *   a cron string or a {@link ScheduleSpec} (`{ cron }` or `{ every }`).
+     *
+     * The {@link ScheduleOptions.overlap} policy governs what happens when a tick
+     * fires while the previous run is still in flight.
+     *
+     * @example
+     * ```ts
+     * import { workflow, Engine } from '@lostgradient/weft';
+     *
+     * const engine = new Engine();
+     * engine.register(workflow({ name: 'sweep' }).execute(async function* () { return 'ok'; }));
+     *
+     * // Definition form: every day at 09:00, skip a tick if the prior run is still running.
+     * const handle = await engine.schedule({
+     *   workflow: 'sweep',
+     *   cron: '0 9 * * *',
+     *   overlapPolicy: 'skip',
+     * });
+     * await handle.pause();
+     * ```
+     */
     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>;
@@ -212,6 +265,7 @@ export declare class Engine<TWorkflows extends object = DefaultWorkflowRegistry,
     [HANDLE_RESULT_PROMISE](workflowId: string): Promise<unknown>;
     [ENGINE_PARKED_WORKFLOW_COUNT_FOR_TESTING](): number;
     [ENGINE_SIGNAL_WAITER_COUNT_FOR_TESTING](): number;
+    [ENGINE_SLEEP_RESOLVER_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>;
@@ -230,7 +284,40 @@ export declare class Engine<TWorkflows extends object = DefaultWorkflowRegistry,
     getStreamChunks(workflowId: string, key: string, options?: {
         after?: number;
     }): Promise<StoredStreamChunk[]>;
+    /**
+     * Read a value a workflow offloaded with `ctx.offload(key, ...)` back out of
+     * storage by `workflowId` + `key`.
+     *
+     * This is the external, post-completion reader for offloaded artifacts — the
+     * missing sibling of {@link getStreamChunks} and {@link getEvents}. Offloaded
+     * values survive normal completion (`completeWorkflow`/`failWorkflow` preserve
+     * them) so a consumer can read a finished workflow's offloaded output after
+     * `handle.result()` resolves. They are swept only when a workflow is
+     * terminated, cancelled, or times out.
+     *
+     * @returns The decoded offload value, or `null` when no value is stored under
+     *   that key (key was never written, workflow ID unknown, or artifact swept).
+     *
+     * @example
+     * ```ts
+     * import { Engine } from '@lostgradient/weft';
+     *
+     * async function readReport(engine: Engine, workflowId: string): Promise<unknown> {
+     *   // `null` when the workflow offloaded nothing under this key, or after a
+     *   // terminated workflow swept its output artifacts.
+     *   return engine.getOffload(workflowId, 'report');
+     * }
+     * ```
+     */
+    getOffload(workflowId: string, key: string): Promise<unknown>;
     fork(sourceWorkflowId: string, options?: ForkOptions): Promise<WorkflowHandle>;
+    /**
+     * Re-drive a workflow from its persisted checkpoint and return a live handle.
+     * Accepts a workflow left `'running'` (e.g. recovered after a process restart)
+     * or one explicitly `'suspended'` via {@link Engine.suspend} — a suspended
+     * workflow is durably flipped back to `'running'` as part of resuming. Throws
+     * if the workflow is in any other status (terminal, pending) or not found.
+     */
     resume(workflowId: string): Promise<WorkflowHandle>;
     /**
      * Recover every running workflow found in storage. By default, recovery
@@ -265,8 +352,23 @@ export declare class Engine<TWorkflows extends object = DefaultWorkflowRegistry,
      */
     failAsyncActivity(token: string, error: unknown): Promise<void>;
     cancel(workflowId: string): Promise<void>;
+    /**
+     * Suspend a running workflow without terminating it. The workflow transitions
+     * to the non-terminal `'suspended'` status, keeps its durable checkpoint, and
+     * is later resumable via {@link Engine.resume} (or `handle.resume()`). Unlike
+     * {@link Engine.cancel}, this does not run cancel handlers and does not settle
+     * the result promise — `handle.result()` stays pending until a later `resume()`
+     * drives the run to completion.
+     *
+     * Suspension is client-driven preemption, so a suspended workflow is NOT
+     * auto-recovered by {@link Engine.recoverAll}; resume it explicitly. Calling
+     * `suspend` on a workflow that is not running (already terminal, or never
+     * started) is a no-op.
+     */
+    suspend(workflowId: string): Promise<void>;
     timeout(workflowId: string): Promise<void>;
     get(workflowId: string): Promise<WorkflowState | null>;
+    getCurrentCheckpointStep(workflowId: string): Promise<number | 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>;
@@ -287,7 +389,23 @@ export declare class Engine<TWorkflows extends object = DefaultWorkflowRegistry,
         timeout?: number;
         idempotencyKey?: string;
     }): Promise<CoordinatedUpdateResult>;
+    /**
+     * Synchronous teardown (`using engine = ...`). Pending inline launches that
+     * have not yet run are **discarded**, not executed. When you need queued
+     * starts to complete before teardown — or want a clean event loop with no
+     * dangling deferred-launch macrotask — prefer {@link Engine[Symbol.asyncDispose]}
+     * via `await using`.
+     */
     [Symbol.dispose](): void;
+    /**
+     * Async teardown (`await using engine = ...`). Drains pending inline launches
+     * so each queued workflow completes its first turn before disposal, leaving no
+     * deferred-launch macrotask to fire against torn-down state. The drain is
+     * bounded (a pass cap and the abort signal); in the pathological case where it
+     * cannot converge, anything still queued is discarded by the synchronous
+     * teardown that always follows. Prefer this over the synchronous
+     * {@link Engine[Symbol.dispose]} in async contexts and tests.
+     */
     [Symbol.asyncDispose](): Promise<void>;
     get storage(): WeftStorage;
     get scheduler(): Scheduler;

package/dist/core/engine/index.js

@@ -3,6 +3,7 @@ import {
   ActivityRegistry
 } from "../activity-registry.js";
 import { AtomicState } from "../atomic-state.js";
+import { deserializeCheckpoint } from "../checkpoint.js";
 import { createHandleCacheFinalizer } from "../engine-helpers.js";
 import { ReviewCoordinator } from "../review/index.js";
 import { Scheduler } from "../scheduler.js";
@@ -63,6 +64,8 @@ import {
 import {
   createCleanupIntervalTick,
   createQueuedInlineWorkflowStartHandler,
+  createSecondInstanceDetectorResolver,
+  drainQueuedInlineWorkflowStartsForEngine,
   isActivityDefinition
 } from "./engine-runtime-helpers.js";
 import { EngineCreateNameMismatchError } from "./errors.js";
@@ -70,7 +73,7 @@ import {
   createWorkflowHandleWithResultPromise as createWorkflowHandleWithResultPromiseFromInternals,
   getWorkflowResultPromise as getWorkflowResultPromiseFromInternals
 } from "./handle-result.js";
-import { HANDLE_RESULT_PROMISE, ScheduleHandle, WorkflowHandle } from "./handles.js";
+import { HANDLE_RESULT_PROMISE, WorkflowHandle } from "./handles.js";
 import { hasQueuedInlineWorkflowStart } from "./inline-launch-queue.js";
 import {
   handleStrategyMessage as handleStrategyMessageFromInternals,
@@ -81,6 +84,8 @@ import {
   fork as forkFromLifecycle,
   recoverAll as recoverAllFromLifecycle,
   resume as resumeFromLifecycle,
+  startOrSignal as startOrSignalFromLifecycle,
+  startWithIdempotency as startWithIdempotencyFromLifecycle,
   startWorkflow as startWorkflowFromLifecycle
 } from "./lifecycle.js";
 import {
@@ -90,6 +95,7 @@ import {
   removeTags as removeWorkflowTags,
   setAttributes as setWorkflowAttributes
 } from "./listing.js";
+import { getOffloadFromInternals } from "./operations-data.js";
 import { getStreamChunksFromInternals } from "./operations-stream.js";
 import {
   handleTimerFired as handleTimerFiredFromInternals
@@ -113,6 +119,7 @@ import {
   listReviews as listReviewsFromInternals,
   submitReview as submitReviewFromInternals
 } from "./reviews.js";
+import { ScheduleHandle } from "./schedule-handle.js";
 import {
   cancelSchedule as cancelScheduleFromInternals,
   listSchedules as listSchedulesFromInternals,
@@ -122,6 +129,10 @@ import {
   toScheduleSummary,
   updateSchedule as updateScheduleFromInternals
 } from "./schedules.js";
+import {
+  createSecondInstanceDetectionTick,
+  createSecondInstanceDetector
+} from "./second-instance-detector.js";
 import { signal as signalWorkflow } from "./signals.js";
 import { loadScheduleState, loadWorkflowState } from "./storage-io.js";
 import {
@@ -133,6 +144,7 @@ import {
   cancelWorkflow as cancelWorkflowFromTermination,
   cleanupWaiters as cleanupWaitersFromTermination,
   finalizePendingTimelineEntry,
+  suspendWorkflow as suspendWorkflowFromTermination,
   timeoutWorkflow as timeoutWorkflowFromTermination
 } from "./termination.js";
 import {
@@ -158,13 +170,17 @@ export {
   BulkOperationConfirmationError,
   EngineCreateNameMismatchError,
   EngineDisposedError,
+  IdempotencyKeyPurgedError,
   PersistedDataIncompatibleError,
+  StartOrSignalConflictError,
   WorkflowAlreadyExistsError,
   WorkflowNotFoundError,
   WorkflowNotRegisteredError,
+  WorkflowSuspendNotSupportedError,
   WorkflowTypeNotRegisteredForRecoveryError
 } from "./errors.js";
-export { HANDLE_RESULT_PROMISE, ScheduleHandle, WorkflowHandle } from "./handles.js";
+export { HANDLE_RESULT_PROMISE, WorkflowHandle } from "./handles.js";
+export { ScheduleHandle } from "./schedule-handle.js";
 export {
   clearEngineLeakWarningTokenForTesting,
   getEngineLeakCollectionCountForTesting,
@@ -174,13 +190,13 @@ export {
   shouldEmitEngineLeakWarningForTesting
 } from "./engine-leak-warnings.js";
 export { assertCompatiblePersistedDataVersion };
-export const ENGINE_PARKED_WORKFLOW_COUNT_FOR_TESTING = Symbol("engineParkedWorkflowCountForTesting"), ENGINE_SIGNAL_WAITER_COUNT_FOR_TESTING = Symbol("engineSignalWaiterCountForTesting");
+export const ENGINE_PARKED_WORKFLOW_COUNT_FOR_TESTING = Symbol("engineParkedWorkflowCountForTesting"), ENGINE_SIGNAL_WAITER_COUNT_FOR_TESTING = Symbol("engineSignalWaiterCountForTesting"), ENGINE_SLEEP_RESOLVER_COUNT_FOR_TESTING = Symbol("engineSleepResolverCountForTesting");
 
 export class Engine extends EventTarget {
   static async create(options) {
     const engine = new Engine(options);
     try {
-      await assertCompatiblePersistedDataVersion(getInternals(engine).storage, options.allowLegacyData === void 0 ? {} : { allowLegacyData: options.allowLegacyData });
+      await assertCompatiblePersistedDataVersion(getInternals(engine).storage);
       for (const [name, definition] of definitionEntries(options.activities)) {
         if (name !== definition.name)
           throw new EngineCreateNameMismatchError("activity", name, definition.name);
@@ -213,7 +229,8 @@ export class Engine extends EventTarget {
       getRegistration: getInternals(this).registrations.get.bind(getInternals(this).registrations),
       getComposedWorkflowInterceptor: () => getComposedWorkflowInterceptor(getInternals(this)),
       resolveWorkflowType: this.#resolveWorkflowTypeTarget.bind(this),
-      registerCancelHandler: (workflowId, handler) => registerCancelHandler(getInternals(this), workflowId, handler)
+      registerCancelHandler: (workflowId, handler) => registerCancelHandler(getInternals(this), workflowId, handler),
+      getWorkflowServices: (workflowId) => getInternals(this).workflowServices.get(workflowId)
     });
     getInternals(this).storage = storage;
     getInternals(this).abortController = new AbortController;
@@ -261,6 +278,7 @@ export class Engine extends EventTarget {
     if (queuedInlineWorkflowStartChannel !== null)
       queuedInlineWorkflowStartChannel.port1.onmessage = createQueuedInlineWorkflowStartHandler(weakEngine, queuedInlineWorkflowStartChannel);
     getInternals(this).heartbeatDetails = new Map;
+    getInternals(this).workflowServices = new Map;
     getInternals(this).pendingAsyncActivities = new Map;
     getInternals(this).pendingStarts = new Set;
     getInternals(this).pendingScheduleCreations = new Set;
@@ -280,6 +298,7 @@ export class Engine extends EventTarget {
     const cleanupIntervalDisposalTracker = {
       disposed: !1,
       cleanupInterval: null,
+      secondInstanceDetectionInterval: null,
       testToken: consumeNextEngineLeakWarningTokenForTesting()
     }, cleanupInterval = setInterval(createCleanupIntervalTick(weakEngine, cleanupIntervalDisposalTracker), 60000);
     cleanupIntervalDisposalTracker.cleanupInterval = cleanupInterval;
@@ -289,6 +308,8 @@ export class Engine extends EventTarget {
     getInternals(this).retentionSweepInterval = null;
     getInternals(this).retentionSweepInFlight = null;
     getInternals(this).nextRetentionSweepAt = null;
+    getInternals(this).secondInstanceDetectionInterval = null;
+    getInternals(this).secondInstanceDetector = null;
     getInternals(this).eventLogHeads = new Map;
     getInternals(this).workflowFeedListeners = new Map;
     getInternals(this).workflowVersionTuples = new Map;
@@ -296,6 +317,25 @@ export class Engine extends EventTarget {
     getInternals(this).strategy.onMessage(this.#handleStrategyMessage.bind(this));
     getInternals(this).alertManager = createAlertManagerForEngine(this, options?.alerts, getNow);
     this.#ensureRetentionSweepInterval();
+    this.#startSecondInstanceDetection();
+  }
+  #startSecondInstanceDetection() {
+    const internals = getInternals(this);
+    if (!internals.options.secondInstanceDetectionEnabled)
+      return;
+    const detector = createSecondInstanceDetector({
+      storage: internals.storage,
+      instanceId: crypto.randomUUID(),
+      getNow: internals.options.getNow,
+      intervalMs: internals.options.secondInstanceHeartbeatIntervalMs
+    });
+    internals.secondInstanceDetector = detector;
+    const tracker = internals.cleanupIntervalDisposalTracker;
+    if (tracker === null)
+      return;
+    const weakEngine = new WeakRef(this), detectionInterval = setInterval(createSecondInstanceDetectionTick(createSecondInstanceDetectorResolver(weakEngine), tracker), internals.options.secondInstanceHeartbeatIntervalMs);
+    internals.secondInstanceDetectionInterval = detectionInterval;
+    tracker.secondInstanceDetectionInterval = detectionInterval;
   }
   #hasConfiguredRetention() {
     return hasConfiguredRetention(getInternals(this));
@@ -397,8 +437,19 @@ export class Engine extends EventTarget {
     return getInternals(this).activityRegistry.listDefinitions();
   }
   async start(type, input, options) {
+    if (options?.idempotencyKey !== void 0)
+      return startWithIdempotencyFromLifecycle(getInternals(this), type, input, options, this.#createLifecycleCallbacks());
     return startWorkflowFromLifecycle(getInternals(this), type, input, options, void 0, this.#createLifecycleCallbacks());
   }
+  async startOrSignal(type, input, signal, options) {
+    return startOrSignalFromLifecycle(getInternals(this), type, input, signal, options, this.#createStartOrSignalCallbacks());
+  }
+  #createStartOrSignalCallbacks() {
+    return {
+      ...this.#createLifecycleCallbacks(),
+      signalExistingWorkflow: (workflowId, signalName, payload, signalId) => this.signal(workflowId, signalName, payload, { signalId })
+    };
+  }
   getHandle(workflowId) {
     const entry = getInternals(this).handleCache.get(workflowId);
     if (entry) {
@@ -478,6 +529,9 @@ export class Engine extends EventTarget {
   [ENGINE_SIGNAL_WAITER_COUNT_FOR_TESTING]() {
     return getInternals(this).signalWaiters.size;
   }
+  [ENGINE_SLEEP_RESOLVER_COUNT_FOR_TESTING]() {
+    return getInternals(this).sleepResolvers.size;
+  }
   async signal(workflowId, nameOrDefinition, payload, options) {
     return signalWorkflow(getInternals(this), workflowId, messageName(nameOrDefinition), payload, {
       loadWorkflowState: (id) => loadWorkflowState(getInternals(this), id),
@@ -496,6 +550,9 @@ export class Engine extends EventTarget {
   async getStreamChunks(workflowId, key, options) {
     return getStreamChunksFromInternals(getInternals(this), workflowId, key, options);
   }
+  async getOffload(workflowId, key) {
+    return getOffloadFromInternals(getInternals(this), workflowId, key);
+  }
   async fork(sourceWorkflowId, options) {
     return forkFromLifecycle(getInternals(this), sourceWorkflowId, options, this.#createLifecycleCallbacks());
   }
@@ -515,6 +572,9 @@ export class Engine extends EventTarget {
   async cancel(workflowId) {
     await cancelWorkflowFromTermination(getInternals(this), workflowId, this.#createTerminationCallbacks());
   }
+  async suspend(workflowId) {
+    await suspendWorkflowFromTermination(getInternals(this), workflowId, this.#createTerminationCallbacks());
+  }
   async timeout(workflowId) {
     await timeoutWorkflowFromTermination(getInternals(this), workflowId, this.#createTerminationCallbacks());
   }
@@ -524,6 +584,15 @@ export class Engine extends EventTarget {
       return { ...state, status: "pending" };
     return state;
   }
+  async getCurrentCheckpointStep(workflowId) {
+    const inMemory = getInternals(this).checkpoints.get(workflowId);
+    if (inMemory !== void 0)
+      return inMemory.step;
+    const bytes = await getInternals(this).storage.get(KEYS.checkpoint(workflowId));
+    if (bytes === null)
+      return null;
+    return deserializeCheckpoint(bytes).step;
+  }
   async getAttributes(workflowId) {
     return getWorkflowAttributes(getInternals(this), workflowId);
   }
@@ -581,6 +650,14 @@ export class Engine extends EventTarget {
     disposeEngine(getInternals(this));
   }
   async[Symbol.asyncDispose]() {
+    if (!getInternals(this).disposed) {
+      try {
+        await drainQueuedInlineWorkflowStartsForEngine(this);
+      } finally {
+        this[Symbol.dispose]();
+      }
+      return;
+    }
     this[Symbol.dispose]();
   }
   get storage() {