@lostgradient/weft 0.2.1 → 0.4.0

package/dist/core/engine/fenced-write.js

@@ -0,0 +1,71 @@
+import { KEYS, storageConditionalBatch } from "../../storage/interface.js";
+import { decodeEpoch } from "./lease-codec.js";
+import { handleDeposition } from "./lease-deposition.js";
+import { EngineDeposedError, EngineLeaseNotHeldError } from "./lease-errors.js";
+export function assertLeaseHeldForEngineWork(internals) {
+  if (internals.options.ownershipMode !== "lease")
+    return;
+  if (!(!internals.deposed && internals.leaseManager !== null && internals.leaseManager.currentEpochBytes() !== null))
+    throw new EngineLeaseNotHeldError;
+}
+async function fencedCommit(internals, operations, baseConditions) {
+  const epochBytes = resolveFenceEpochOrHalt(internals);
+  if (epochBytes === null) {
+    if (baseConditions.length === 0) {
+      await internals.storage.batch(operations);
+      return "committed";
+    }
+    return await storageConditionalBatch(internals.storage, baseConditions, operations) ? "committed" : "lost-race";
+  }
+  const conditions = [
+    ...baseConditions,
+    { key: KEYS.leaseEpoch(), expectedValue: epochBytes }
+  ];
+  if (await storageConditionalBatch(internals.storage, conditions, operations))
+    return "committed";
+  if (await isDeposed(internals, epochBytes)) {
+    handleDeposition(internals);
+    throw new EngineDeposedError;
+  }
+  return "lost-race";
+}
+function resolveFenceEpochOrHalt(internals) {
+  if (internals.deposed)
+    throw new EngineDeposedError;
+  if (internals.options.ownershipMode !== "lease")
+    return null;
+  const epochBytes = internals.leaseManager?.currentEpochBytes() ?? null;
+  if (epochBytes === null) {
+    handleDeposition(internals);
+    throw new EngineDeposedError;
+  }
+  return epochBytes;
+}
+export async function commitFencedEngineWrite(internals, operations, baseConditions, onLostRace) {
+  if (await fencedCommit(internals, operations, baseConditions) === "lost-race")
+    throw onLostRace();
+}
+export async function commitFencedEngineWriteAllowingPreconditionFailure(internals, operations, baseConditions) {
+  return await fencedCommit(internals, operations, baseConditions) === "committed";
+}
+function epochBytesEqual(a, b) {
+  if (b === null || a.byteLength !== b.byteLength)
+    return !1;
+  for (let index = 0;index < a.byteLength; index += 1)
+    if (a[index] !== b[index])
+      return !1;
+  return !0;
+}
+async function isDeposed(internals, heldEpochBytes) {
+  let currentEpochRaw;
+  try {
+    currentEpochRaw = await internals.storage.get(KEYS.leaseEpoch());
+  } catch {
+    return !0;
+  }
+  if (currentEpochRaw === null)
+    return !0;
+  if (decodeEpoch(currentEpochRaw) === null)
+    return !0;
+  return !epochBytesEqual(heldEpochBytes, currentEpochRaw);
+}

package/dist/core/engine/finalizer-state.d.ts

@@ -0,0 +1,28 @@
+import type { EngineInternals } from './internals.ts';
+/**
+ * Engine-side handler for `ctx.setFinalizerState(value)` (issue #446). Durably
+ * records the payload associated with the workflow's definition-level
+ * `finalizer` activity.
+ *
+ * This handler only records the value; the engine passes the decoded payload as
+ * the finalizer's input when it drives cancel/timeout teardown (#446 Phase 2).
+ *
+ * The value is staged as a pending atomic side-effect — a `put` of
+ * {@link KEYS.finalizerState} — that commits with whichever durable write lands
+ * first: the next checkpoint/suspend commit, or, if no checkpoint runs before the
+ * workflow terminates, the terminal `updateWorkflowState` batch
+ * (`includePendingAtomicSideEffects` is set for terminal transitions). Either way
+ * the resource id is durable before teardown is driven: a cancel arriving before
+ * the next checkpoint still flushes the staged op in the terminal batch, so the
+ * finalizer always sees the resource id. The staged op inherits the lease-epoch
+ * fence (#470) for free, since checkpoint and terminal commits route through
+ * `commitFencedWorkflowStateOperations`.
+ *
+ * Oversized payloads are rejected before staging (the same hostile-input guard
+ * activity results use). A call made once the workflow is already terminalizing
+ * — e.g. from an `onCancel` handler, which runs after the terminal batch has
+ * already taken the pending side-effects — is a no-op: the staged op has no
+ * future commit to ride and is cleared on terminal cleanup. A development
+ * warning is emitted so the footgun is visible, but no error is thrown.
+ */
+export declare function recordFinalizerState(internals: EngineInternals, workflowId: string, value: unknown): void;

package/dist/core/engine/finalizer-state.js

@@ -0,0 +1,16 @@
+import { KEYS } from "../../storage/interface.js";
+import { encode } from "../codec.js";
+import { assertPayloadWithinLimit } from "../payload-size.js";
+import { stageAtomicWorkflowCommitSideEffects } from "./checkpoint-side-effects.js";
+export function recordFinalizerState(internals, workflowId, value) {
+  if (internals.terminalizingWorkflows.has(workflowId)) {
+    if (internals.options.development)
+      console.warn(`[weft] ctx.setFinalizerState() called for workflow "${workflowId}" after it began terminalizing; the value is ignored. Record finalizer state while the workflow is still running.`);
+    return;
+  }
+  assertPayloadWithinLimit(value, internals.options.payloadSizePolicy.maxBytes, "finalizer state");
+  stageAtomicWorkflowCommitSideEffects(internals, workflowId, {
+    conditions: [],
+    operations: [{ type: "put", key: KEYS.finalizerState(workflowId), value: encode(value) }]
+  });
+}

package/dist/core/engine/handle-result.js

@@ -35,7 +35,7 @@ export async function bootstrapWorkflowResultResolver(internals, workflowId, wai
       waiter.reject(Error(`Workflow "${workflowId}" not found in storage`));
       return;
     }
-    if (state.status === "running" || state.status === "pending")
+    if (state.status === "running" || state.status === "pending" || state.status === "suspended")
       return;
     try {
       const result = await loadWorkflowResult(internals, workflowId);

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

@@ -1,9 +1,20 @@
-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';
+/**
+ * Which atomic path a `startOrSignal` call took, returned alongside the
+ * {@link WorkflowHandle} in `StartOrSignalResult` (not a field on the handle —
+ * converged concurrent callers share one cached engine handle, so the outcome
+ * rides the per-call result instead). `'started'` when the call created the
+ * run, `'signalled'` when it delivered a signal to a run that already existed.
+ */
+export type StartOrSignalOutcome = 'started' | 'signalled';
 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 +25,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 +83,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 +192,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

@@ -1,28 +1,33 @@
 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 { TypedEventTarget, WeftEventMap } from '../events.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 BulkRetryFailedResult, 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 StartWorkflowOptions, type SubmitReviewOptions, type TypedListFilter, type UpdateDefinition, type WorkflowEvent, type WorkflowInput, type WorkflowOutput, type WorkflowReplay, type WorkflowServices, type WorkflowServicesUnion, 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 ActivityDefinitionName, type EngineCreateOptions, type EngineCreateWorkflowRegistry, 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 { HANDLE_RESULT_PROMISE, WorkflowHandle } from './handles.ts';
+import { ENGINE_LEASE_LOST_WARNING_NAME } from './lease-deposition.ts';
+import { type RecoverAllOptions, type StartOrSignalResult } 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, WorkflowConcurrencyLimitExceededError, WorkflowNotFoundError, WorkflowNotRegisteredError, WorkflowSuspendNotSupportedError, WorkflowTeardownPendingError, WorkflowTypeNotRegisteredForRecoveryError, } from './errors.ts';
+export { HANDLE_RESULT_PROMISE, WorkflowHandle } from './handles.ts';
+export { EngineLeaseAcquisitionTimeoutError, EngineLeaseCorruptedError, EngineLeaseNotHeldError, } from './lease-errors.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 +35,8 @@ 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;
+export { ENGINE_LEASE_LOST_WARNING_NAME };
 /**
  * Durable execution engine.
  *
@@ -72,7 +79,7 @@ export declare const ENGINE_SIGNAL_WAITER_COUNT_FOR_TESTING: unique symbol;
  * void engine;
  * ```
  */
-export declare class Engine<TWorkflows extends object = DefaultWorkflowRegistry, TActivities extends object = DefaultActivityTypes> extends EventTarget implements Disposable, AsyncDisposable {
+export declare class Engine<TWorkflows extends object = DefaultWorkflowRegistry, TActivities extends object = DefaultActivityTypes> extends EventTarget implements Disposable, AsyncDisposable, TypedEventTarget<WeftEventMap> {
     #private;
     /**
      * Construct and register an engine in one step. Activities are registered
@@ -102,7 +109,7 @@ export declare class Engine<TWorkflows extends object = DefaultWorkflowRegistry,
     static create<TWorkflowDefinitions extends Record<string, AnyWorkflowDefinition>>(options: EngineCreateOptions<TWorkflowDefinitions, EmptyActivityDefinitions> & {
         activities?: undefined;
         workflows: TWorkflowDefinitions;
-    }): Promise<Engine<InferWorkflowEntries<TWorkflowDefinitions>>>;
+    }): Promise<Engine<EngineCreateWorkflowRegistry<TWorkflowDefinitions>>>;
     static create<TActivityDefinitions extends Record<string, AnyActivityDefinition>>(options: EngineCreateOptions<EmptyWorkflowDefinitions, TActivityDefinitions> & {
         activities: TActivityDefinitions;
         workflows?: undefined;
@@ -110,8 +117,12 @@ export declare class Engine<TWorkflows extends object = DefaultWorkflowRegistry,
     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);
+    }): Promise<Engine<EngineCreateWorkflowRegistry<TWorkflowDefinitions>, InferActivityEntries<TActivityDefinitions>>>;
+    constructor(options?: EngineConstructorOptions<WorkflowServicesUnion<TWorkflows>>);
+    addEventListener<K extends Extract<keyof WeftEventMap, string>>(type: K, listener: (event: WeftEventMap[K]) => void, options?: boolean | AddEventListenerOptions): void;
+    addEventListener(type: string, listener: EventListenerOrEventListenerObject | null, options?: boolean | AddEventListenerOptions): void;
+    removeEventListener<K extends Extract<keyof WeftEventMap, string>>(type: K, listener: (event: WeftEventMap[K]) => void, options?: boolean | EventListenerOptions): void;
+    removeEventListener(type: string, listener: EventListenerOrEventListenerObject | null, options?: boolean | EventListenerOptions): void;
     get state(): EngineStateNamespace;
     /**
      * Register a workflow by name or definition, or register an activity
@@ -183,8 +194,27 @@ export declare class Engine<TWorkflows extends object = DefaultWorkflowRegistry,
     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>;
+    start<TName extends KnownWorkflowNames<TWorkflows>>(type: TName, input: WorkflowInput<TWorkflows, TName>, options?: StartWorkflowOptions<WorkflowServices<TWorkflows, TName>>): Promise<WorkflowHandle<WorkflowOutput<TWorkflows, TName>>>;
+    start<TName extends string>(type: UnknownWorkflowNameWhenDefaultRegistryIsEmpty<TWorkflows, TName>, input: unknown, options?: StartWorkflowOptions): 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<WorkflowServices<TWorkflows, TName>>): Promise<StartOrSignalResult<WorkflowOutput<TWorkflows, TName>>>;
+    startOrSignal<TName extends string>(type: UnknownWorkflowNameWhenDefaultRegistryIsEmpty<TWorkflows, TName>, input: unknown, signal: StartOrSignalSignal, options?: StartOptions): Promise<StartOrSignalResult>;
     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>;
@@ -192,6 +222,8 @@ export declare class Engine<TWorkflows extends object = DefaultWorkflowRegistry,
     purge(filter?: ListFilter): Promise<PurgeResult>;
     cancelAll(filter: ListFilter, options: BulkOperationDryRunOptions): Promise<BulkOperationDryRunResult>;
     cancelAll(filter: ListFilter, options?: BulkOperationCommitOptions): Promise<BulkCancelResult>;
+    retryFailedAll(filter: ListFilter, options: BulkOperationDryRunOptions): Promise<BulkOperationDryRunResult>;
+    retryFailedAll(filter: ListFilter, options?: BulkOperationCommitOptions): Promise<BulkRetryFailedResult>;
     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>;
@@ -201,6 +233,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`, `backfill`, and `jitter`.
+     * - 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 +275,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>;
@@ -257,6 +321,13 @@ export declare class Engine<TWorkflows extends object = DefaultWorkflowRegistry,
      */
     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
@@ -264,7 +335,7 @@ export declare class Engine<TWorkflows extends object = DefaultWorkflowRegistry,
      * registered workflow type on this engine.
      *
      * `acknowledgeUnknownWorkflowTypes` is a dangerous escape hatch for rolling
-     * deploys or explicit storage migrations.
+     * deploys or explicit operator storage repair.
      * When set, unknown workflow types are skipped and reported through
      * {@link WorkflowRecoverySkippedEvent}.
      */
@@ -274,7 +345,11 @@ export declare class Engine<TWorkflows extends object = DefaultWorkflowRegistry,
      * 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.
+     * though the activity had returned `result` inline. During recovery, a
+     * completion that arrives after token recovery but before replay adopts the
+     * workflow generator is buffered and delivered when replay reaches the same
+     * async-activity token. Await `recoverAll()` before accepting callback traffic
+     * when your application needs startup ordering to be fully deterministic.
      *
      * @throws {AsyncActivityTokenNotFoundError} when no pending activity matches
      * the token (unknown, or already completed/failed — tokens are single-use).
@@ -284,15 +359,34 @@ export declare class Engine<TWorkflows extends object = DefaultWorkflowRegistry,
      * 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.
+     * policy apply unchanged. During recovery, a failure that arrives after token
+     * recovery but before replay adopts the workflow generator is buffered and
+     * delivered when replay reaches the same async-activity token. Await
+     * `recoverAll()` before accepting callback traffic when your application needs
+     * startup ordering to be fully deterministic.
      *
      * @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>;
+    /**
+     * 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>;
@@ -313,7 +407,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;