@lostgradient/weft 0.2.1 → 0.3.0

package/dist/core/context/run-operation.js

@@ -1,8 +1,15 @@
 import { calculateBackoff } from "../scheduler.js";
-import { DEFAULT_RETRY_POLICY } from "../types.js";
-import { getInternals } from "./internals.js";
+import {
+  DEFAULT_RETRY_POLICY
+} from "../types.js";
+import { getInternals, hasContextInternals } from "./internals.js";
 import { isActivityCallOptions } from "./session-state.js";
 import { captureCallerStack } from "./validation.js";
+export function asConcreteContext(context) {
+  if (!hasContextInternals(context))
+    throw Error("Step-based workflows (compileStepWorkflow / ctx.step) require workflowExecutionMode: 'inline'. The worker execution strategy runs workflows with a different context that has no durable step machinery. Use the generator workflow API for worker execution mode.");
+  return context;
+}
 const ACTIVITY_RETRY_STATE_LOCAL_KEY = "__weftActivityRetryState", ACTIVITY_RETRY_STATE_VERSION = 1, MAX_CHECKPOINTED_RETRY_ATTEMPT = 1e4;
 function acceptsNoActivityInput(fn) {
   if (typeof fn !== "function")
@@ -104,7 +111,9 @@ function completeActivityRetryAttempt(internals, step, completedRetrySleepCount)
     }
   };
 }
-function getActivityName(activity) {
+function getActivityName(activity, explicitName) {
+  if (explicitName !== void 0)
+    return explicitName;
   return typeof activity === "string" ? activity : activity.name || "anonymous";
 }
 function getActivityFunction(activity) {
@@ -190,8 +199,8 @@ function prepareActivityRetryRequest(request, attempt) {
     attempt
   };
 }
-export function createRunActivityRequest(context, activity, rest) {
-  const { input, options } = parseRunArguments(activity, rest), activityName = getActivityName(activity), activityFunction = getActivityFunction(activity), internals = getInternals(context), step = internals.stepIndex++, cachedRequest = getCachedRunActivityRequest(internals, step, activityName, input);
+export function createRunActivityRequest(context, activity, rest, explicitName) {
+  const { input, options } = parseRunArguments(activity, rest), activityName = getActivityName(activity, explicitName), activityFunction = getActivityFunction(activity), internals = getInternals(context), step = internals.stepIndex++, cachedRequest = getCachedRunActivityRequest(internals, step, activityName, input);
   if (cachedRequest.hasCachedResult)
     return cachedRequest;
   const retryPolicy = resolveActivityRetryPolicy(activity, options);
@@ -203,8 +212,8 @@ export function createRunActivityRequest(context, activity, rest) {
     ...retryPolicy === void 0 ? {} : { retryPolicy }
   };
 }
-export function* runActivityWithRetry(context, activity, rest) {
-  const { request, step, hasCachedResult, cachedResult, retryAttempt, retryPolicy } = createRunActivityRequest(context, activity, rest);
+export function* runActivityWithRetry(context, activity, rest, explicitName) {
+  const { request, step, hasCachedResult, cachedResult, retryAttempt, retryPolicy } = createRunActivityRequest(context, activity, rest, explicitName);
   if (hasCachedResult)
     return cachedResult;
   const internals = getInternals(context);

package/dist/core/engine/bulk-operations.js

@@ -17,7 +17,7 @@ import { BULK_OPERATION_BATCH_SIZE } from "./listing.js";
 import { loadWorkflowState } from "./storage-io.js";
 import { isTerminalWorkflowStatus } from "./validation.js";
 export { purgeInternal, TERMINAL_CLEANUP_DELAY_MS } from "./bulk-operations-purge.js";
-const ACTIVE_WORKFLOW_STATUSES = ["pending", "running"];
+const ACTIVE_WORKFLOW_STATUSES = ["pending", "running", "suspended"];
 export async function purge(internals, filter, cleanupWaiters) {
   return purgeInternal(internals, filter, { expiredOnly: !1, now: internals.options.getNow() }, cleanupWaiters);
 }

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

@@ -18,7 +18,6 @@ export type EngineCreateRuntimeOptions = EngineConstructorOptions & {
     workflows?: Record<string, AnyWorkflowDefinition> | undefined;
     recover?: boolean | undefined;
     acknowledgeUnknownWorkflowTypes?: boolean | undefined;
-    allowLegacyData?: boolean | undefined;
 };
 export type NormalizedWorkerExecutionConfiguration = {
     mode: 'inline';

package/dist/core/engine/construction.js

@@ -103,6 +103,14 @@ function resolveHistoryFields(options) {
     payloadSizePolicy: normalizePayloadSizePolicy(options?.payloadSize, "options.payloadSize")
   };
 }
+const DEFAULT_SECOND_INSTANCE_HEARTBEAT_INTERVAL_MS = 15000;
+function resolveSecondInstanceFields(options) {
+  const enabled = defaultTo(options?.detectSecondInstance, !1), intervalMs = enabled ? normalizeRetentionDuration(options?.secondInstanceHeartbeatInterval, "options.secondInstanceHeartbeatInterval") ?? DEFAULT_SECOND_INSTANCE_HEARTBEAT_INTERVAL_MS : DEFAULT_SECOND_INSTANCE_HEARTBEAT_INTERVAL_MS;
+  return {
+    secondInstanceDetectionEnabled: enabled,
+    secondInstanceHeartbeatIntervalMs: intervalMs
+  };
+}
 export function resolveEngineOptions(storage, options, getNow) {
   return {
     storage,
@@ -111,7 +119,8 @@ export function resolveEngineOptions(storage, options, getNow) {
     ...resolveBooleanDefaults(options),
     ...resolveNumericDefaults(options),
     ...resolveRetentionFields(options),
-    ...resolveHistoryFields(options)
+    ...resolveHistoryFields(options),
+    ...resolveSecondInstanceFields(options)
   };
 }
 export function normalizeWorkerExecutionConfiguration(options) {

package/dist/core/engine/disposal.js

@@ -22,6 +22,7 @@ export function disposeEngine(internals) {
     internals.retentionSweepInterval = null;
   }
   internals.nextRetentionSweepAt = null;
+  disposeSecondInstanceDetection(internals);
   internals.handleCache.clear();
   for (const waiter of internals.resultResolvers.values())
     waiter.reject(new EngineDisposedError);
@@ -43,6 +44,7 @@ export function disposeEngine(internals) {
   internals.checkpoints.clear();
   internals.pendingExecutionStateOwnerId = void 0;
   internals.workflowNestingDepths.clear();
+  internals.workflowServices.clear();
   internals.workflowHeaders.clear();
   internals.pendingStarts.clear();
   internals.pendingScheduleCreations.clear();
@@ -56,3 +58,13 @@ export function disposeEngine(internals) {
   internals.broadcastChannel?.close();
   internals.broadcastChannel = null;
 }
+function disposeSecondInstanceDetection(internals) {
+  if (internals.secondInstanceDetectionInterval !== null) {
+    clearInterval(internals.secondInstanceDetectionInterval ?? void 0);
+    internals.secondInstanceDetectionInterval = null;
+  }
+  if (internals.secondInstanceDetector !== null) {
+    internals.secondInstanceDetector.stop();
+    internals.secondInstanceDetector = null;
+  }
+}

package/dist/core/engine/engine-create-types.d.ts

@@ -29,20 +29,6 @@ export type EngineCreateOptions<TWorkflowDefinitions extends Record<string, AnyW
     workflows?: TWorkflowDefinitions;
     /** Activity definitions to register before workflows. */
     activities?: TActivityDefinitions;
-    /**
-     * Opt out of the persisted-data schema-version gate when opening a storage
-     * that contains workflow data written by `new Engine({ storage })` before
-     * the schema-version sentinel existed.
-     *
-     * The gate normally rejects any storage that already holds workflow records
-     * but lacks the sentinel — a safety check against silently classifying
-     * pre-sentinel data as schema-current. Set `allowLegacyData: true` only when
-     * you knowingly opened the same storage with the legacy constructor path and
-     * are intentionally recovering it via `Engine.create`. On success, the
-     * current schema-version sentinel is written. Remove the opt-in once the
-     * data has been migrated.
-     */
-    allowLegacyData?: boolean;
 } & ({
     /**
      * Recover stored running workflows after registration. Defaults to

package/dist/core/engine/engine-internal-types.d.ts

@@ -29,6 +29,10 @@ export interface ResolvedOptions {
     /** Operator-supplied sink for compacted event-log ranges; `null` when none. */
     archiveAdapter: ArchiveAdapter | null;
     payloadSizePolicy: NormalizedPayloadSizePolicy;
+    /** Whether the best-effort second-instance liveness detector is enabled. */
+    secondInstanceDetectionEnabled: boolean;
+    /** Heartbeat interval (ms) for the second-instance detector when enabled. */
+    secondInstanceHeartbeatIntervalMs: number;
     getNow: () => number;
     /**
      * Re-provides the non-serialized per-run `services` value on recovery; `null`
@@ -61,4 +65,12 @@ export type QueuedInlineWorkflowExecutionStart = {
     nestingDepth: number;
     executionDeadline: number | undefined;
     executionStateOwnerId: string;
+    /**
+     * Liveness callback invoked once this queued start has actually begun
+     * executing (its generator has been driven). Set only for `defer: false`
+     * launches, which await it before `engine.start()` resolves. Fired exactly
+     * once; a discarded start (engine disposed without draining) settles it via
+     * the dispose path so the `defer: false` awaiter never hangs.
+     */
+    onStarted?: () => void;
 };

package/dist/core/engine/engine-leak-warnings.d.ts

@@ -6,6 +6,12 @@
 export type EngineCleanupIntervalDisposalTracker = {
     disposed: boolean;
     cleanupInterval: ReturnType<typeof setInterval> | null;
+    /**
+     * The optional second-instance detector interval, tracked alongside the
+     * cleanup interval so the same finalizer clears it when an engine is
+     * garbage-collected without `[Symbol.dispose]()`. Null when detection is off.
+     */
+    secondInstanceDetectionInterval: ReturnType<typeof setInterval> | null;
     testToken: symbol | undefined;
 };
 export declare const engineCleanupIntervalFinalizer: FinalizationRegistry<EngineCleanupIntervalDisposalTracker>;

package/dist/core/engine/engine-leak-warnings.js

@@ -6,6 +6,10 @@ export const engineCleanupIntervalFinalizer = new FinalizationRegistry((tracker)
     clearInterval(tracker.cleanupInterval);
     tracker.cleanupInterval = null;
   }
+  if (tracker.secondInstanceDetectionInterval !== null) {
+    clearInterval(tracker.secondInstanceDetectionInterval);
+    tracker.secondInstanceDetectionInterval = null;
+  }
   if (!tracker.disposed && shouldEmitEngineLeakWarning()) {
     if (tracker.testToken !== void 0)
       engineLeakWarningTokensForTesting.add(tracker.testToken);

package/dist/core/engine/engine-runtime-helpers.d.ts

@@ -2,7 +2,24 @@ import type { AnyActivityDefinition } from '../types.ts';
 import { type EngineCleanupIntervalDisposalTracker } from './engine-leak-warnings.ts';
 import type { Engine } from './index.ts';
 import { type EngineInternals } from './internals.ts';
+import type { SecondInstanceDetector } from './second-instance-detector.ts';
 export declare function isActivityDefinition(value: unknown): value is AnyActivityDefinition;
 export declare function createQueuedInlineWorkflowStartHandler<TWorkflows extends object, TActivities extends object>(weakEngine: WeakRef<Engine<TWorkflows, TActivities>>, channel: MessageChannel): () => void;
+/**
+ * Drain pending inline launches for `engine` before teardown. Built with the
+ * same inline-launch-queue callbacks as the scheduled flush handler so a drained
+ * start advances identically to a normally-flushed one. Called from
+ * `[Symbol.asyncDispose]` ahead of synchronous disposal (which aborts the signal
+ * and would otherwise discard the queue).
+ */
+export declare function drainQueuedInlineWorkflowStartsForEngine<TWorkflows extends object, TActivities extends object>(engine: Engine<TWorkflows, TActivities>): Promise<void>;
 export declare function createCleanupIntervalTick<TWorkflows extends object, TActivities extends object>(weakEngine: WeakRef<Engine<TWorkflows, TActivities>>, tracker: EngineCleanupIntervalDisposalTracker): () => void;
+/**
+ * Build the resolver the second-instance detection interval uses to find its live
+ * detector. Returns `null` when the engine has been garbage-collected or disposed
+ * (so the tick is skipped), otherwise the engine's current detector. Extracted
+ * here — like {@link createCleanupIntervalTick} — so the deref/disposed guard is
+ * directly testable without driving a real interval.
+ */
+export declare function createSecondInstanceDetectorResolver<TWorkflows extends object, TActivities extends object>(weakEngine: WeakRef<Engine<TWorkflows, TActivities>>): () => SecondInstanceDetector | null;
 export declare function disposeEngineCleanupInterval(internals: EngineInternals): void;

package/dist/core/engine/engine-runtime-helpers.js

@@ -3,12 +3,22 @@ import { createLifecycleCallbacks, createTerminationCallbacks } from "./callback
 import {
   engineCleanupIntervalFinalizer
 } from "./engine-leak-warnings.js";
-import { flushQueuedInlineWorkflowStarts } from "./inline-launch-queue.js";
+import {
+  drainQueuedInlineWorkflowStarts,
+  flushQueuedInlineWorkflowStarts
+} from "./inline-launch-queue.js";
 import { getInternals } from "./internals.js";
 import { swallowPromiseRejection } from "./strategy-helpers.js";
 export function isActivityDefinition(value) {
   return typeof value === "function" && typeof value.name === "string" && "execute" in value && typeof value.execute === "function";
 }
+function inlineLaunchQueueCallbacksForEngine(engine) {
+  const lifecycleCallbacks = createLifecycleCallbacks(engine);
+  return {
+    processPendingUpdatesAfterInlineAdvance: (workflowId) => lifecycleCallbacks.processPendingUpdatesAfterInlineAdvance(workflowId),
+    swallowPromiseRejection: (promise) => swallowPromiseRejection(promise)
+  };
+}
 export function createQueuedInlineWorkflowStartHandler(weakEngine, channel) {
   return function handleQueuedInlineWorkflowStart() {
     const engine = weakEngine.deref();
@@ -18,12 +28,12 @@ export function createQueuedInlineWorkflowStartHandler(weakEngine, channel) {
       return;
     }
     getInternals(engine).queuedInlineWorkflowStartFlushScheduled = !1;
-    swallowPromiseRejection(flushQueuedInlineWorkflowStarts(getInternals(engine), {
-      processPendingUpdatesAfterInlineAdvance: (workflowId) => createLifecycleCallbacks(engine).processPendingUpdatesAfterInlineAdvance(workflowId),
-      swallowPromiseRejection: (promise) => swallowPromiseRejection(promise)
-    }));
+    swallowPromiseRejection(flushQueuedInlineWorkflowStarts(getInternals(engine), inlineLaunchQueueCallbacksForEngine(engine)));
   };
 }
+export async function drainQueuedInlineWorkflowStartsForEngine(engine) {
+  await drainQueuedInlineWorkflowStarts(getInternals(engine), inlineLaunchQueueCallbacksForEngine(engine));
+}
 export function createCleanupIntervalTick(weakEngine, tracker) {
   return function cleanupExpiredResponsesForLiveEngine() {
     const engine = weakEngine.deref();
@@ -38,6 +48,17 @@ export function createCleanupIntervalTick(weakEngine, tracker) {
     createExpiredResponseCleanupTick(internals.updateCoordinator, (source, error) => createTerminationCallbacks(engine).handleCleanupError(source, error))();
   };
 }
+export function createSecondInstanceDetectorResolver(weakEngine) {
+  return function resolveLiveSecondInstanceDetector() {
+    const engine = weakEngine.deref();
+    if (engine === void 0)
+      return null;
+    const internals = getInternals(engine);
+    if (internals.disposed)
+      return null;
+    return internals.secondInstanceDetector;
+  };
+}
 export function disposeEngineCleanupInterval(internals) {
   if (internals.cleanupInterval !== null) {
     clearInterval(internals.cleanupInterval ?? void 0);

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

@@ -1,3 +1,4 @@
+import type { WorkflowStatus } from '../types/identity.ts';
 import { WeftError } from '../weft-error.ts';
 /**
  * Thrown by {@link Engine.start} when a workflow with the requested ID already
@@ -186,6 +187,32 @@ export declare class WorkflowNotRegisteredError extends WeftError<'WorkflowNotRe
     readonly workflowType: string;
     constructor(workflowType: string);
 }
+/**
+ * Thrown by {@link Engine.suspend} when invoked on an engine running in worker
+ * execution mode. Suspension parks the live run without aborting it, which the
+ * inline strategy supports directly; a worker run cannot be paused without
+ * sending it a cancellation, so the engine refuses rather than silently
+ * aborting. Suspend/resume in worker mode is a scoped follow-up.
+ *
+ * @example
+ * ```ts
+ * import { Engine, WorkflowSuspendNotSupportedError } from '@lostgradient/weft';
+ *
+ * async function trySuspend(engine: Engine, id: string) {
+ *   try {
+ *     await engine.suspend(id);
+ *   } catch (err) {
+ *     if (err instanceof WorkflowSuspendNotSupportedError) {
+ *       // worker-mode engine: cancel instead, or run inline
+ *     }
+ *   }
+ * }
+ * void trySuspend;
+ * ```
+ */
+export declare class WorkflowSuspendNotSupportedError extends WeftError<'WorkflowSuspendNotSupportedError'> {
+    constructor(message: string);
+}
 /**
  * Thrown when the engine cannot resolve an activity name to a registered
  * function during dispatch. The per-workflow {@link ActivityRegistry} (built
@@ -212,4 +239,51 @@ export declare class ActivityResolutionError extends WeftError<'ActivityResoluti
     readonly activityName: string;
     constructor(workflowType: string, activityName: string);
 }
+/**
+ * Thrown by {@link Engine.startOrSignal} when the target workflow already exists
+ * and is in a terminal state (completed, failed, cancelled, or timed out). A
+ * terminal run cannot accept a signal and must not be silently replaced, so
+ * `startOrSignal` surfaces this conflict instead of starting a fresh run under
+ * the same id or dropping the signal.
+ *
+ * Inspect `workflowId` to identify the conflicting run and `status` to see why
+ * it was rejected. To deliberately start a new run, choose a different id (or
+ * idempotency key); to deliver to a fresh run, terminal-state reuse is not a
+ * supported policy.
+ *
+ * @example
+ * ```ts
+ * import { StartOrSignalConflictError } from '@lostgradient/weft';
+ *
+ * function isTerminalStartOrSignalConflict(error: unknown): boolean {
+ *   return error instanceof StartOrSignalConflictError;
+ * }
+ * ```
+ */
+export declare class StartOrSignalConflictError extends WeftError<'StartOrSignalConflictError'> {
+    readonly workflowId: string;
+    readonly status: WorkflowStatus;
+    constructor(workflowId: string, status: WorkflowStatus);
+}
+/**
+ * Thrown by {@link Engine.start} / {@link Engine.startOrSignal} when an
+ * `idempotencyKey` resolves to a workflow that no longer exists — its run was
+ * purged or bulk-deleted while the durable `start-idem:` mapping (intentionally
+ * not swept on cleanup) lived on. The key is "spent": it can neither return the
+ * gone run nor safely start a fresh one under the same key (a concurrent caller
+ * may still hold the mapping). Use a different idempotency key to start anew.
+ *
+ * @example
+ * ```ts
+ * import { IdempotencyKeyPurgedError } from '@lostgradient/weft';
+ *
+ * function isPurgedIdempotencyKey(error: unknown): boolean {
+ *   return error instanceof IdempotencyKeyPurgedError;
+ * }
+ * ```
+ */
+export declare class IdempotencyKeyPurgedError extends WeftError<'IdempotencyKeyPurgedError'> {
+    readonly workflowId: string;
+    constructor(workflowId: string);
+}
 export { PersistedDataIncompatibleError } from '../persisted-data-incompatible-error.ts';

package/dist/core/engine/errors.js

@@ -78,13 +78,37 @@ export class WorkflowNotRegisteredError extends WeftError {
   }
 }
 
+export class WorkflowSuspendNotSupportedError extends WeftError {
+  constructor(message) {
+    super("WorkflowSuspendNotSupportedError", message);
+  }
+}
+
 export class ActivityResolutionError extends WeftError {
   workflowType;
   activityName;
   constructor(workflowType, activityName) {
-    super("ActivityResolutionError", `No activity registered with name "${activityName}" for workflow type "${workflowType}". Register the activity via \`workflow({ name }).activities({ ... })\` on the workflow that runs it, or via \`engine.register(activityDefinition)\` for the legacy global registry.`);
+    super("ActivityResolutionError", `No activity registered with name "${activityName}" for workflow type "${workflowType}". Register the activity via \`workflow({ name }).activities({ ... })\` on the workflow that runs it, or via \`engine.register(activityDefinition)\` to make it available to every workflow on that engine instance.`);
     this.workflowType = workflowType;
     this.activityName = activityName;
   }
 }
+
+export class StartOrSignalConflictError extends WeftError {
+  workflowId;
+  status;
+  constructor(workflowId, status) {
+    super("StartOrSignalConflictError", `Workflow "${workflowId}" is already in terminal state "${status}" and cannot accept a startOrSignal: a terminal run cannot be signalled and is not replaced. Use a different id or idempotency key to start a new run.`);
+    this.workflowId = workflowId;
+    this.status = status;
+  }
+}
+
+export class IdempotencyKeyPurgedError extends WeftError {
+  workflowId;
+  constructor(workflowId) {
+    super("IdempotencyKeyPurgedError", `The idempotency key maps to workflow "${workflowId}", which no longer exists (it was purged or deleted). Use a different idempotency key to start a new run.`);
+    this.workflowId = workflowId;
+  }
+}
 export { PersistedDataIncompatibleError } from "../persisted-data-incompatible-error.js";

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,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;
-  }
-}