@lostgradient/weft 0.2.1 → 0.3.0

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>;
@@ -257,6 +311,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
@@ -291,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>;
@@ -313,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 {
@@ -114,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,
@@ -123,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 {
@@ -134,6 +144,7 @@ import {
   cancelWorkflow as cancelWorkflowFromTermination,
   cleanupWaiters as cleanupWaitersFromTermination,
   finalizePendingTimelineEntry,
+  suspendWorkflow as suspendWorkflowFromTermination,
   timeoutWorkflow as timeoutWorkflowFromTermination
 } from "./termination.js";
 import {
@@ -159,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,
@@ -175,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);
@@ -283,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;
@@ -292,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;
@@ -299,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));
@@ -400,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) {
@@ -481,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),
@@ -521,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());
   }
@@ -530,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);
   }
@@ -587,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() {

package/dist/core/engine/inline-launch-queue.d.ts

@@ -9,6 +9,20 @@ export declare function queueInlineWorkflowExecutionStart(internals: EngineInter
 export declare function flushQueuedInlineWorkflowStarts(internals: EngineInternals, callbacks: InlineLaunchQueueCallbacks): Promise<void>;
 /** Used by scheduler-driven direct backfill flushes. Clears the scheduled flag first. */
 export declare function flushQueuedInlineWorkflowStartsDirectly(internals: EngineInternals, callbacks: InlineLaunchQueueCallbacks): Promise<void>;
+/**
+ * Drain every pending inline launch before engine teardown. Called from
+ * `[Symbol.asyncDispose]` *before* `disposeEngine` aborts the signal, so the
+ * flush actually executes the queued starts (the abort check in
+ * {@link flushQueuedInlineWorkflowStarts} would otherwise discard them). This
+ * turns a deferred-launch macrotask into work that completes before
+ * `asyncDispose` returns, so a disposed engine leaves no dangling pending
+ * launch — the fix for the test-runner macrotask-starvation footgun.
+ *
+ * A queued start that was already aborted (signal set before this is reached)
+ * is left for the synchronous `disposeQueuedInlineWorkflowStarts` path, which
+ * discards it and settles its `defer: false` awaiter.
+ */
+export declare function drainQueuedInlineWorkflowStarts(internals: EngineInternals, callbacks: InlineLaunchQueueCallbacks): Promise<void>;
 export declare function dropQueuedInlineWorkflowStart(internals: EngineInternals, workflowId: string): boolean;
 export declare function disposeQueuedInlineWorkflowStarts(internals: EngineInternals): void;
 export declare function hasQueuedInlineWorkflowStart(internals: EngineInternals, workflowId: string): boolean;

package/dist/core/engine/inline-launch-queue.js

@@ -17,9 +17,18 @@ export function queueInlineWorkflowExecutionStart(internals, start, callbacks) {
     callbacks.swallowPromiseRejection(flushQueuedInlineWorkflowStarts(internals, callbacks));
   }, 0);
 }
+function settleDiscardedInlineStarts(internals, discarded) {
+  for (const start of discarded) {
+    internals.queuedInlineWorkflowStartIds.delete(start.workflowId);
+    internals.queuedOrLaunchingInlineWorkflowStartIds.delete(start.workflowId);
+    start.onStarted?.();
+  }
+}
 export async function flushQueuedInlineWorkflowStarts(internals, callbacks) {
   if (internals.abortController.signal.aborted) {
+    const discarded = internals.queuedInlineWorkflowStarts;
     internals.queuedInlineWorkflowStarts = [];
+    settleDiscardedInlineStarts(internals, discarded);
     return;
   }
   if (internals.queuedInlineWorkflowStarts.length === 0)
@@ -27,12 +36,21 @@ export async function flushQueuedInlineWorkflowStarts(internals, callbacks) {
   const pendingStarts = internals.queuedInlineWorkflowStarts;
   internals.queuedInlineWorkflowStarts = [];
   for (const start of pendingStarts)
-    await startQueuedInlineWorkflowExecution(internals, start, callbacks);
+    await callbacks.swallowPromiseRejection(startQueuedInlineWorkflowExecution(internals, start, callbacks));
 }
 export async function flushQueuedInlineWorkflowStartsDirectly(internals, callbacks) {
   internals.queuedInlineWorkflowStartFlushScheduled = !1;
   await flushQueuedInlineWorkflowStarts(internals, callbacks);
 }
+export async function drainQueuedInlineWorkflowStarts(internals, callbacks) {
+  internals.queuedInlineWorkflowStartFlushScheduled = !1;
+  let passes = 0;
+  const maxPasses = 1000;
+  while (internals.queuedInlineWorkflowStarts.length > 0 && !internals.abortController.signal.aborted && passes < maxPasses) {
+    passes += 1;
+    await callbacks.swallowPromiseRejection(flushQueuedInlineWorkflowStarts(internals, callbacks));
+  }
+}
 async function startQueuedInlineWorkflowExecution(internals, start, callbacks) {
   try {
     const state = await loadWorkflowState(internals, start.workflowId);
@@ -45,22 +63,29 @@ async function startQueuedInlineWorkflowExecution(internals, start, callbacks) {
   } finally {
     internals.queuedInlineWorkflowStartIds.delete(start.workflowId);
     internals.queuedOrLaunchingInlineWorkflowStartIds.delete(start.workflowId);
+    start.onStarted?.();
   }
 }
 export function dropQueuedInlineWorkflowStart(internals, workflowId) {
   if (internals.queuedInlineWorkflowStarts.length === 0)
     return !1;
-  const initialLength = internals.queuedInlineWorkflowStarts.length;
-  internals.queuedInlineWorkflowStarts = internals.queuedInlineWorkflowStarts.filter((start) => start.workflowId !== workflowId);
-  if (internals.queuedInlineWorkflowStarts.length !== initialLength) {
-    internals.queuedInlineWorkflowStartIds.delete(workflowId);
-    internals.queuedOrLaunchingInlineWorkflowStartIds.delete(workflowId);
-  }
+  const initialLength = internals.queuedInlineWorkflowStarts.length, dropped = [];
+  internals.queuedInlineWorkflowStarts = internals.queuedInlineWorkflowStarts.filter((start) => {
+    if (start.workflowId === workflowId) {
+      dropped.push(start);
+      return !1;
+    }
+    return !0;
+  });
+  if (internals.queuedInlineWorkflowStarts.length !== initialLength)
+    settleDiscardedInlineStarts(internals, dropped);
   return internals.queuedInlineWorkflowStarts.length !== initialLength;
 }
 export function disposeQueuedInlineWorkflowStarts(internals) {
   internals.queuedInlineWorkflowStartFlushScheduled = !1;
+  const discarded = internals.queuedInlineWorkflowStarts;
   internals.queuedInlineWorkflowStarts = [];
+  settleDiscardedInlineStarts(internals, discarded);
   internals.queuedInlineWorkflowStartIds.clear();
   internals.queuedOrLaunchingInlineWorkflowStartIds.clear();
   const channel = internals.queuedInlineWorkflowStartChannel;

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

@@ -32,8 +32,11 @@ import type { Checkpoint } from '../types.ts';
 import type { UpdateCoordinator } from '../updates.ts';
 import type { WorkflowVersionTuple } from '../workflow-version-tuple.ts';
 import type { PendingTimelineEntry, QueuedInlineWorkflowExecutionStart, RegistrationEntry, ResolvedOptions, TrackedWaiterKeys, WorkflowResultWaiter } from './engine-internal-types.ts';
-import type { ScheduleHandleEngine, WorkflowHandle, WorkflowHandleEngine } from './handles.ts';
+import type { EngineCleanupIntervalDisposalTracker } from './engine-leak-warnings.ts';
+import type { WorkflowHandle, WorkflowHandleEngine } from './handles.ts';
 import type { WorkflowFeedListener } from './index.ts';
+import type { ScheduleHandleEngine } from './schedule-handle.ts';
+import type { SecondInstanceDetector } from './second-instance-detector.ts';
 type EngineRuntime = WorkflowHandleEngine & ScheduleHandleEngine;
 export interface EngineInternals {
     engine: EngineRuntime;
@@ -75,11 +78,15 @@ export interface EngineInternals {
     activityRegistry: ActivityRegistry;
     /**
      * Per-workflow activity registries built from
-     * `workflow({ name }).activities({ ... }).execute(...)`. Indexed by workflow
-     * type. Phase 3 wires lookups via `activityRegistriesByWorkflow.get(type)`
-     * first, falling back to {@link EngineInternals.activityRegistry} so the
-     * legacy global path keeps working until Phase 6 removes it. Each registry
-     * is constructed from a defensive deep clone+freeze of the workflow's
+     * `workflow({ name }).activities({ ... }).execute(...)`, indexed by workflow
+     * type. Activity lookup is per-activity: it consults the workflow's
+     * `activityRegistriesByWorkflow.get(type)` registry first and, for any activity
+     * that registry does not contain, falls back to the engine-wide
+     * {@link EngineInternals.activityRegistry}. Both sources are first-class — a
+     * workflow can resolve some activities from its own `activities(...)` map and
+     * others (shared/globally-registered) from the global registry, and a workflow
+     * with no per-workflow map resolves entirely from the global one. Each
+     * per-workflow registry is a defensive deep clone+freeze of the workflow's
      * `activities` map so post-registration mutation cannot reach the engine.
      */
     activityRegistriesByWorkflow: Map<string, ActivityRegistry>;
@@ -127,13 +134,14 @@ export interface EngineInternals {
     pendingScheduleCreations: Set<string>;
     workflowsNeedingTerminalCleanup: Set<string>;
     cleanupInterval: ReturnType<typeof setInterval> | null;
-    cleanupIntervalDisposalTracker: {
-        disposed: boolean;
-        cleanupInterval: ReturnType<typeof setInterval> | null;
-    } | null;
+    cleanupIntervalDisposalTracker: EngineCleanupIntervalDisposalTracker | null;
     retentionSweepInterval: ReturnType<typeof setInterval> | null;
     retentionSweepInFlight: Promise<void> | null;
     nextRetentionSweepAt: number | null;
+    /** Interval driving the best-effort second-instance detector; `null` when off. */
+    secondInstanceDetectionInterval: ReturnType<typeof setInterval> | null;
+    /** The active second-instance detector; `null` when detection is disabled. */
+    secondInstanceDetector: SecondInstanceDetector | null;
     reviewCoordinator: ReviewCoordinator;
     reviewWaiters: Map<string, (decision: HumanReviewResult) => void>;
     reviewWaitersByWorkflow: Map<string, TrackedWaiterKeys>;

package/dist/core/engine/lifecycle/fork-helpers.js

@@ -22,17 +22,11 @@ export function createForkedWorkflowState(_internals, workflowId, sourceState, v
     type: sourceState.type,
     status: "running",
     input: sourceState.input,
-    version: versionTuple.workflowVersion,
+    versionTuple,
     executionStateOwnerId: workflowId,
     createdAt: forkedAt,
     startedAt: forkedAt,
     updatedAt: forkedAt,
-    ...versionTuple.agentVersion !== void 0 && {
-      agentVersion: versionTuple.agentVersion
-    },
-    ...versionTuple.toolVersions !== void 0 && {
-      toolVersions: versionTuple.toolVersions
-    },
     forkedFrom: lineage
   };
 }

package/dist/core/engine/lifecycle/persist.js

@@ -16,28 +16,13 @@ export function createWorkflowVersionTuple(_internals, registration, _callbacks)
   };
 }
 export function workflowVersionTupleFromState(_internals, state, _callbacks) {
-  return {
-    workflowVersion: state.version,
-    ...state.agentVersion !== void 0 && { agentVersion: state.agentVersion },
-    ...state.toolVersions !== void 0 && { toolVersions: state.toolVersions }
-  };
+  return state.versionTuple;
 }
 export function workflowStateWithVersionTuple(internals, state, versionTuple, _callbacks) {
-  const {
-    agentVersion: _existingAgentVersion,
-    toolVersions: _existingToolVersions,
-    ...rest
-  } = state;
   return {
-    ...rest,
-    version: versionTuple.workflowVersion,
-    updatedAt: internals.options.getNow(),
-    ...versionTuple.agentVersion !== void 0 && {
-      agentVersion: versionTuple.agentVersion
-    },
-    ...versionTuple.toolVersions !== void 0 && {
-      toolVersions: versionTuple.toolVersions
-    }
+    ...state,
+    versionTuple,
+    updatedAt: internals.options.getNow()
   };
 }
 export function derivePreparedExecutionState(internals, workflowId, state, checkpoint, registration, callbacks) {
@@ -76,5 +61,5 @@ export async function prepareResumeState(internals, workflowId, state, checkpoin
   };
 }
 export function throwVersionMismatch(_internals, workflowId, state, registration, versionDiff, _callbacks) {
-  throw new VersionMismatchError(workflowId, state.type, state.version, registration.version, void 0, versionDiff);
+  throw new VersionMismatchError(workflowId, state.type, state.versionTuple.workflowVersion, registration.version, void 0, versionDiff);
 }