@lostgradient/weft 0.9.0 → 0.11.0

package/dist/core/engine/lifecycle/recovered-services.d.ts

@@ -1,4 +1,4 @@
-import type { WorkflowState } from '../../types.ts';
+import type { WorkflowServicesResolverInfo, WorkflowState } from '../../types.ts';
 import type { EngineInternals } from '../internals.ts';
 /**
  * Re-provide a recovered inline workflow's non-serialized `services` before its
@@ -36,7 +36,9 @@ import type { EngineInternals } from '../internals.ts';
  * @param onCommitError - Records a fail-warn when `failRun` itself throws, so the
  *   swallowed terminal-commit fault is still observable.
  */
-export declare function reprovideRecoveredServices(internals: EngineInternals, state: WorkflowState, failRun: (workflowId: string, error: Error) => Promise<void>, onCommitError: (source: string, error: unknown, workflowId: string) => void, dispatchDiagnostic?: (event: Event) => void): Promise<boolean>;
+export declare function reprovideRecoveredServices(internals: EngineInternals, state: WorkflowState, failRun: (workflowId: string, error: Error) => Promise<void>, onCommitError: (source: string, error: unknown, workflowId: string) => void, dispatchDiagnostic?: (event: Event) => void, resolverInfo?: WorkflowServicesResolverInfo): Promise<boolean>;
+/** Build the durable recovery context shared by the services resolver and recovery hook. */
+export declare function workflowServicesResolverInfoFromState(internals: EngineInternals, state: WorkflowState): Promise<WorkflowServicesResolverInfo>;
 /**
  * The canonical terminal error for any run whose services could not be provided —
  * both recovery re-provision paths and a scheduled-occurrence launch. Shared so

package/dist/core/engine/lifecycle/recovered-services.js

@@ -1,7 +1,9 @@
 import { KEYS } from "../../../storage/interface.js";
 import { DevelopmentWarningEvent } from "../../events.js";
+import { decodeScheduleRunMetadata } from "../schedule-run-metadata.js";
+import { loadScheduleState } from "../storage-io.js";
 const RESOLVE_WORKFLOW_SERVICES_OPTION_PATH = "EngineOptions.resolveWorkflowServices";
-export async function reprovideRecoveredServices(internals, state, failRun, onCommitError, dispatchDiagnostic = () => {}) {
+export async function reprovideRecoveredServices(internals, state, failRun, onCommitError, dispatchDiagnostic = () => {}, resolverInfo) {
   const resolver = internals.options.resolveWorkflowServices;
   if (internals.inlineStrategy === null)
     return !1;
@@ -20,13 +22,9 @@ export async function reprovideRecoveredServices(internals, state, failRun, onCo
     return !0;
   }
   let reason;
+  const info = resolverInfo ?? await workflowServicesResolverInfoFromState(internals, state);
   try {
-    const resolution = await resolver({
-      workflowId: state.id,
-      workflowType: state.type,
-      input: state.input,
-      launchOptions: launchOptionsFromWorkflowState(state)
-    });
+    const resolution = await resolver(info);
     if (resolution.status === "available") {
       internals.workflowServices.set(state.id, resolution.services);
       return !1;
@@ -42,6 +40,16 @@ export async function reprovideRecoveredServices(internals, state, failRun, onCo
   }
   return !0;
 }
+export async function workflowServicesResolverInfoFromState(internals, state) {
+  const schedule = await scheduleFromWorkflowState(internals, state);
+  return {
+    workflowId: state.id,
+    workflowType: state.type,
+    input: state.input,
+    launchOptions: launchOptionsFromWorkflowState(state),
+    ...schedule !== null ? { schedule } : {}
+  };
+}
 export function unavailableServicesError(workflowId, reason) {
   return Error(`Workflow "${workflowId}" services unavailable: ${reason}`);
 }
@@ -54,3 +62,25 @@ function launchOptionsFromWorkflowState(state) {
     ...state.tags !== void 0 && state.tags.length > 0 ? { tags: [...state.tags] } : {}
   };
 }
+async function scheduleFromWorkflowState(internals, state) {
+  const bytes = await internals.storage.get(KEYS.scheduleRun(state.id));
+  if (bytes === null)
+    return null;
+  const metadata = decodeScheduleRunMetadata(bytes);
+  if (metadata === null)
+    return null;
+  const scheduleState = await loadScheduleState(internals, metadata.id);
+  if (scheduleState === null)
+    return null;
+  if (scheduleState.workflowType !== state.type)
+    return null;
+  if (scheduleState.overlap === "allow")
+    return metadata.occurrence !== void 0 ? metadata : null;
+  if (scheduleState.currentWorkflowId === state.id)
+    return metadata;
+  if (metadata.occurrence !== void 0 && scheduleState.nextFireAt === metadata.occurrence)
+    return metadata;
+  if (metadata.occurrence === void 0 && scheduleState.overlap === "queue" && scheduleState.queuedRuns > 0)
+    return metadata;
+  return null;
+}

package/dist/core/engine/lifecycle/resume.d.ts

@@ -1,4 +1,4 @@
 import { type WorkflowHandle } from '../handles.ts';
 import type { EngineInternals } from '../internals.ts';
-import { type LifecycleCallbacks } from './shared.ts';
-export declare function resumeWorkflowFromStorage(internals: EngineInternals, workflowId: string, dispatchResumedEvent: boolean, callbacks: LifecycleCallbacks): Promise<WorkflowHandle>;
+import { type LifecycleCallbacks, type RecoverAllOptions } from './shared.ts';
+export declare function resumeWorkflowFromStorage(internals: EngineInternals, workflowId: string, dispatchResumedEvent: boolean, callbacks: LifecycleCallbacks, onRecoveredWorkflow?: RecoverAllOptions['onRecoveredWorkflow']): Promise<WorkflowHandle>;

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

@@ -15,15 +15,47 @@ import { getComposedWorkflowInterceptor } from "../strategy-helpers.js";
 import { decodeWorkflowState } from "../validation.js";
 import { buildWorkflowVisibilityIndexTransition } from "../workflow-indexes.js";
 import { prepareResumeState } from "./persist.js";
-import { reprovideRecoveredServices } from "./recovered-services.js";
+import {
+  reprovideRecoveredServices,
+  workflowServicesResolverInfoFromState
+} from "./recovered-services.js";
 import {
   enforceHistoryPolicyBeforeReplay,
   loadTerminalCleanupTrackedState,
   loadWorkflowStartHeaders,
   setWorkflowStartHeaders
 } from "./shared.js";
-async function prepareRecoveredServicesOrFail(internals, state, callbacks) {
-  return reprovideRecoveredServices(internals, state, callbacks.failWorkflowForUnavailableServices, callbacks.handleCleanupError, callbacks.dispatchEvent);
+async function prepareRecoveredServicesOrFail(internals, state, callbacks, resolverInfo) {
+  return reprovideRecoveredServices(internals, state, callbacks.failWorkflowForUnavailableServices, callbacks.handleCleanupError, callbacks.dispatchEvent, resolverInfo);
+}
+async function runRecoveredWorkflowHookOrFail(internals, state, handle, resolverInfo, onRecoveredWorkflow, callbacks) {
+  const info = {
+    ...resolverInfo,
+    handle,
+    launchOptions: resolverInfo.launchOptions ?? { id: state.id },
+    services: internals.workflowServices.get(state.id)
+  };
+  try {
+    await onRecoveredWorkflow(info);
+    return !1;
+  } catch (error) {
+    const reason = error instanceof Error ? error.message : String(error), hookError = Error(`Recovery hook failed for workflow "${state.id}": ${reason}`);
+    try {
+      await callbacks.failWorkflowForRecoveryHook(state.id, hookError);
+    } catch (commitError) {
+      callbacks.handleCleanupError("onRecoveredWorkflow", commitError, state.id);
+    }
+    return !0;
+  }
+}
+async function prepareRecoveredWorkflowOrFail(internals, state, callbacks, onRecoveredWorkflow) {
+  const resolverInfo = onRecoveredWorkflow === void 0 ? void 0 : await workflowServicesResolverInfoFromState(internals, state), handle = callbacks.getHandle(state.id);
+  if (await prepareRecoveredServicesOrFail(internals, state, callbacks, resolverInfo))
+    return { handle, shouldStop: !0 };
+  if (onRecoveredWorkflow === void 0 || resolverInfo === void 0)
+    return { handle, shouldStop: !1 };
+  const shouldStop = await runRecoveredWorkflowHookOrFail(internals, state, handle, resolverInfo, onRecoveredWorkflow, callbacks);
+  return { handle, shouldStop };
 }
 function assertResumeNotTerminating(internals, workflowId) {
   if (internals.terminalizingWorkflows.has(workflowId))
@@ -138,7 +170,7 @@ async function reactivateSuspendedWorkflowState(internals, state) {
     }) : []
   ], [], () => Error(`Resume of workflow "${state.id}" lost its CAS race.`));
 }
-export async function resumeWorkflowFromStorage(internals, workflowId, dispatchResumedEvent, callbacks) {
+export async function resumeWorkflowFromStorage(internals, workflowId, dispatchResumedEvent, callbacks, onRecoveredWorkflow) {
   const stateBytes = await internals.storage.get(KEYS.workflow(workflowId));
   if (!stateBytes)
     throw Error(`Workflow "${workflowId}" not found in storage`);
@@ -156,9 +188,9 @@ export async function resumeWorkflowFromStorage(internals, workflowId, dispatchR
     return callbacks.getHandle(workflowId);
   const workflowStartHeaders = await loadWorkflowStartHeaders(internals, workflowId, callbacks);
   await loadTerminalCleanupTrackedState(internals, workflowId, callbacks);
-  if (await prepareRecoveredServicesOrFail(internals, state, callbacks))
-    return callbacks.getHandle(workflowId);
-  const handle = callbacks.getHandle(workflowId);
+  const { handle, shouldStop } = await prepareRecoveredWorkflowOrFail(internals, state, callbacks, onRecoveredWorkflow);
+  if (shouldStop)
+    return handle;
   await callbacks.runSerializedWorkflowStateWrite(workflowId, () => performSerializedResume(internals, {
     workflowId,
     resumeCheckpoint,

package/dist/core/engine/lifecycle/shared.d.ts

@@ -1,10 +1,35 @@
 import type { ComposedWorkflowInterceptor } from '../../interceptor.ts';
+import type { WorkflowServicesResolverLaunchOptions, WorkflowServicesResolverScheduleInfo } from '../../types.ts';
 import type { QueuedInlineWorkflowExecutionStart } from '../engine-internal-types.ts';
 import { type WorkflowHandle } from '../handles.ts';
 import type { EngineInternals } from '../internals.ts';
 export type RegistrationEntry = EngineInternals['registrations'] extends Map<string, infer Entry> ? Entry : never;
 export declare const FORK_LINEAGE_ATTRIBUTE = "weft:forkedFrom";
 export declare const EMPTY_STORAGE_VALUE: Uint8Array<ArrayBuffer>;
+/**
+ * Durable run context passed to {@link RecoverAllOptions.onRecoveredWorkflow}
+ * before recovered user code advances.
+ *
+ * @example
+ * ```ts
+ * import type { RecoveredWorkflowInfo } from '@lostgradient/weft';
+ *
+ * function registerSurface(info: RecoveredWorkflowInfo): void {
+ *   console.log(`Recovered ${info.workflowType}/${info.workflowId}`);
+ * }
+ * ```
+ */
+export interface RecoveredWorkflowInfo {
+    /** Handle for the recovered run. */
+    handle: WorkflowHandle;
+    workflowId: string;
+    workflowType: string;
+    input: unknown;
+    launchOptions: WorkflowServicesResolverLaunchOptions;
+    schedule?: WorkflowServicesResolverScheduleInfo;
+    /** Re-provided host services, or `undefined` when the run did not use services. */
+    services: unknown;
+}
 /**
  * Options for {@link Engine.recoverAll}. The acknowledgement flag is an
  * explicit escape hatch for deployments that intentionally skip stored
@@ -25,6 +50,13 @@ export type RecoverAllOptions = {
      * rolling deploys or explicit operator storage repair.
      */
     acknowledgeUnknownWorkflowTypes?: boolean;
+    /**
+     * Register consumer-owned live state for each recovered run after services
+     * are re-provided but before the workflow generator advances. The callback is
+     * awaited. If it throws, only that run fails with a `system` failure and
+     * recovery continues with its siblings.
+     */
+    onRecoveredWorkflow?: (info: RecoveredWorkflowInfo) => void | Promise<void>;
 };
 export type LifecycleCallbacks = {
     dispatchEvent: (event: Event) => void;
@@ -56,6 +88,8 @@ export type LifecycleCallbacks = {
      * `error` is the canonical {@link unavailableServicesError}.
      */
     failWorkflowForUnavailableServices: (workflowId: string, error: Error) => Promise<void>;
+    /** Fail one recovered workflow whose pre-resume consumer hook threw. */
+    failWorkflowForRecoveryHook: (workflowId: string, error: Error) => Promise<void>;
     /**
      * Force a recovered workflow to a terminal `failed` state because its
      * persisted checkpoint cannot be decoded on this runtime. The failure is

package/dist/core/engine/lifecycle/transition.d.ts

@@ -3,6 +3,6 @@ import { type WorkflowHandle } from '../handles.ts';
 import type { EngineInternals } from '../internals.ts';
 import { type LifecycleCallbacks, type RecoverAllOptions, type RegistrationEntry } from './shared.ts';
 export declare function recoverAll(internals: EngineInternals, callbacks: LifecycleCallbacks, options?: RecoverAllOptions): Promise<WorkflowHandle[]>;
-export declare function resume(internals: EngineInternals, workflowId: string, callbacks: LifecycleCallbacks): Promise<WorkflowHandle>;
+export declare function resume(internals: EngineInternals, workflowId: string, callbacks: LifecycleCallbacks, onRecoveredWorkflow?: RecoverAllOptions['onRecoveredWorkflow']): Promise<WorkflowHandle>;
 export declare function fork(internals: EngineInternals, sourceWorkflowId: string, options: ForkOptions | undefined, callbacks: LifecycleCallbacks): Promise<WorkflowHandle>;
 export declare function launchWorkflowFromCheckpoint(internals: EngineInternals, workflowId: string, state: WorkflowState, checkpoint: Checkpoint, registration: RegistrationEntry, callbacks: LifecycleCallbacks): WorkflowHandle;

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

@@ -77,7 +77,7 @@ export async function recoverAll(internals, callbacks, options) {
       continue;
     }
     try {
-      handles.push(await resume(internals, entry.workflowId, callbacks));
+      handles.push(await resume(internals, entry.workflowId, callbacks, options?.onRecoveredWorkflow));
     } catch (error) {
       if (error instanceof RegExpExtensionDecodeError) {
         await callbacks.failWorkflowForCheckpointDecodeError(entry.workflowId, error);
@@ -88,7 +88,7 @@ export async function recoverAll(internals, callbacks, options) {
   }
   return handles;
 }
-export async function resume(internals, workflowId, callbacks) {
+export async function resume(internals, workflowId, callbacks, onRecoveredWorkflow) {
   const workflowState = await loadWorkflowState(internals, workflowId);
   if (workflowState !== null) {
     if (callbacks.isInlineWorkflowLocallyOwned(workflowId, workflowState.status) || callbacks.hasLocalCheckpointOwnership(workflowId, workflowState.status)) {
@@ -96,7 +96,7 @@ export async function resume(internals, workflowId, callbacks) {
       return callbacks.getHandle(workflowId);
     }
   }
-  return resumeWorkflowFromStorage(internals, workflowId, !0, callbacks);
+  return resumeWorkflowFromStorage(internals, workflowId, !0, callbacks, onRecoveredWorkflow);
 }
 export async function fork(internals, sourceWorkflowId, options, callbacks) {
   const sourceState = await loadWorkflowState(internals, sourceWorkflowId);

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

@@ -1,4 +1,4 @@
-export { EMPTY_STORAGE_VALUE, createWorkflowHandle, loadTerminalCleanupTrackedState, loadWorkflowStartHeaders, normalizeStartWorkflowTags, processPendingUpdatesAfterReplay, setWorkflowStartHeaders, type LifecycleCallbacks, type RecoverAllOptions, } from './lifecycle/shared.ts';
+export { EMPTY_STORAGE_VALUE, createWorkflowHandle, loadTerminalCleanupTrackedState, loadWorkflowStartHeaders, normalizeStartWorkflowTags, processPendingUpdatesAfterReplay, setWorkflowStartHeaders, type LifecycleCallbacks, type RecoverAllOptions, type RecoveredWorkflowInfo, } from './lifecycle/shared.ts';
 export { createWorkflowVersionTuple, derivePreparedExecutionState, prepareResumeState, throwVersionMismatch, workflowStateWithVersionTuple, workflowVersionTupleFromState, } from './lifecycle/persist.ts';
 export { createInitialCheckpoint, createInitialWorkflowState, parseStartOptionDuration, resolveScheduledStartAt, start, startWorkflow, } from './lifecycle/start.ts';
 export { startOrSignal, startWithIdempotency, type StartOrSignalCallbacks, type StartOrSignalResult, } from './lifecycle/start-or-signal.ts';

package/dist/core/engine/memo-durable-activity.js

@@ -198,15 +198,13 @@ class MemoDurableActivityScope {
         onAbort();
         return;
       }
-      operation.then((value) => {
-        settle(() => {
-          if (this.#closed || signal.aborted) {
-            reject(this.#abortError());
-            return;
-          }
-          resolve(value);
-        });
-      }).catch((error) => {
+      operation.then((value) => settle(() => {
+        if (this.#closed || signal.aborted) {
+          reject(this.#abortError());
+          return;
+        }
+        resolve(value);
+      })).catch((error) => {
         settle(() => reject(error));
       });
     });

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

@@ -18,10 +18,10 @@ import {
 import { getActivityFunctionWithMetadata, resolveActivityFunction } from "./activity-resolution.js";
 import {
   AsyncActivityDeferral,
-  deriveAsyncActivityToken,
   driveWorkflowInterceptorGenerator,
   parkDeferredAsyncActivity
 } from "./async-activity-completion.js";
+import { deriveAsyncActivityToken } from "./async-activity-records.js";
 import { callActivityFunction } from "./state-utilities.js";
 export function buildActivityVerification(_internals, activityName, verify, context, result) {
   return (async () => {

package/dist/core/engine/operations-coordination.d.ts

@@ -33,7 +33,21 @@ export type CoordinationOperationCallbacks = {
 };
 export declare function processWaitSignalOperation(internals: EngineInternals, workflowId: string, operation: WaitSignalOperation, callbacks: Pick<CoordinationOperationCallbacks, 'completeOperation'>): Promise<void>;
 export declare function processParallelOperation(internals: EngineInternals, workflowId: string, operation: ParallelOperation, callbacks: Pick<CoordinationOperationCallbacks, 'executeSubOperation' | 'runOperationWithResult'>): Promise<void>;
-export declare function processRaceOperation(_internals: EngineInternals, workflowId: string, operation: RaceOperation, callbacks: Pick<CoordinationOperationCallbacks, 'executeSubOperation' | 'runOperationWithResult'>): Promise<void>;
+export declare function processRaceOperation(internals: EngineInternals, workflowId: string, operation: RaceOperation, callbacks: Pick<CoordinationOperationCallbacks, 'executeSubOperation' | 'runOperationWithResult'>): Promise<void>;
+export declare function assertValidRaceBranchNames(operation: RaceOperation): void;
+export declare function wrapRaceWinner(operation: RaceOperation, winnerIndex: number, value: unknown): unknown;
+/**
+ * Execute race branches while giving an already-buffered signal priority over a
+ * literal zero-duration sleep. The preflight is non-destructive: the selected
+ * wait-signal branch still returns its deferred-consume envelope, so the owning
+ * coordinator remains the only place that consumes the durable record.
+ *
+ * Positive-duration sleeps deliberately bypass this preflight, including when
+ * their deadline becomes past-due before dispatch. That keeps ordinary timeout
+ * races on the existing Promise.race path and limits the stronger ordering
+ * guarantee to the explicit non-blocking-drain idiom.
+ */
+export declare function executeRaceSubOperations(internals: EngineInternals, workflowId: string, operations: readonly ContextOperationRequest[], execute: (operation: ContextOperationRequest, signal: AbortSignal) => Promise<unknown>, parentSignal?: AbortSignal, wrapWinner?: (winnerIndex: number, value: unknown) => unknown): Promise<unknown>;
 export declare function processRunAllOperation(internals: EngineInternals, workflowId: string, operation: RunAllOperation, callbacks: Pick<CoordinationOperationCallbacks, 'runOperationWithResult'>): Promise<void>;
 export declare function isConfiguredInlineActivity(fn: Function): fn is RunAllOperation['branches'][string][0] & ActivityFunctionWithMetadata;
 /**

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

@@ -5,7 +5,7 @@ import {
   executeRunAllBranches,
   executeRunAllBranchesSettled
 } from "../engine-helpers.js";
-import { finalizeAndUnwrap } from "./deferred-consume-envelope.js";
+import { createKeyedRaceResultEnvelope, finalizeAndUnwrap } from "./deferred-consume-envelope.js";
 import {
   executeActivityOperationResult as executeActivityOperationResultFromInternals
 } from "./operations-activity.js";
@@ -16,6 +16,7 @@ import {
 } from "./parallel-dispatch.js";
 import {
   consumeSignalWithAtomicWorkflowCommit,
+  peekSignal,
   trackWaiterKey,
   untrackWaiterKey
 } from "./signals.js";
@@ -106,20 +107,52 @@ function assertPartialFailurePersistenceSupported(partialEntryWritten, slots, op
     return;
   throw Error(`${operationName} partial-failure preservation is not supported in ${executionMode}: the engine cannot persist fulfilled branch slots after a sibling branch fails. Run the workflow inline or make branch side effects idempotent.`);
 }
-export async function processRaceOperation(_internals, workflowId, operation, callbacks) {
+export async function processRaceOperation(internals, workflowId, operation, callbacks) {
   return callbacks.runOperationWithResult(workflowId, operation, async () => {
     assertSupportedSignalBranches(operation.operations);
-    const controller = new AbortController, subOperations = operation.operations.map((subOperation) => callbacks.executeSubOperation(workflowId, subOperation, controller.signal));
-    Promise.allSettled(subOperations);
-    let winner;
-    try {
-      winner = await Promise.race(subOperations);
-    } finally {
-      controller.abort();
-    }
+    assertValidRaceBranchNames(operation);
+    const winner = await executeRaceSubOperations(internals, workflowId, operation.operations, (subOperation, signal) => callbacks.executeSubOperation(workflowId, subOperation, signal), void 0, (winnerIndex, value) => wrapRaceWinner(operation, winnerIndex, value));
     return finalizeAndUnwrap(winner);
   });
 }
+export function assertValidRaceBranchNames(operation) {
+  if (operation.branchNames !== void 0 && operation.branchNames.length !== operation.operations.length)
+    throw Error("ctx.raceKeyed branch names must match its operation count");
+}
+export function wrapRaceWinner(operation, winnerIndex, value) {
+  const key = operation.branchNames?.[winnerIndex];
+  return key === void 0 ? value : createKeyedRaceResultEnvelope(key, value);
+}
+export async function executeRaceSubOperations(internals, workflowId, operations, execute, parentSignal, wrapWinner) {
+  parentSignal?.throwIfAborted();
+  const controller = new AbortController, abortFromParent = () => controller.abort(parentSignal?.reason);
+  parentSignal?.addEventListener("abort", abortFromParent, { once: !0 });
+  try {
+    const bufferedSignal = await findBufferedSignalDrainBranch(internals, workflowId, operations);
+    parentSignal?.throwIfAborted();
+    if (bufferedSignal !== void 0) {
+      const value = await execute(bufferedSignal.operation, controller.signal);
+      return wrapWinner === void 0 ? value : wrapWinner(bufferedSignal.index, value);
+    }
+    const subOperations = operations.map((operation, index) => execute(operation, controller.signal).then((value) => ({ index, value })));
+    Promise.allSettled(subOperations);
+    const winner = await Promise.race(subOperations);
+    return wrapWinner === void 0 ? winner.value : wrapWinner(winner.index, winner.value);
+  } finally {
+    parentSignal?.removeEventListener("abort", abortFromParent);
+    controller.abort();
+  }
+}
+async function findBufferedSignalDrainBranch(internals, workflowId, operations) {
+  if (operations.length !== 2)
+    return;
+  const waitSignalOperation = operations.find((operation) => operation.type === "wait-signal"), zeroDurationSleep = operations.find((operation) => operation.type === "sleep" && operation.duration === 0);
+  if (waitSignalOperation === void 0 || zeroDurationSleep === void 0)
+    return;
+  if (!(await peekSignal(internals, workflowId, waitSignalOperation.signalName)).found)
+    return;
+  return { index: operations.indexOf(waitSignalOperation), operation: waitSignalOperation };
+}
 export async function processRunAllOperation(internals, workflowId, operation, callbacks) {
   return callbacks.runOperationWithResult(workflowId, operation, async () => {
     const branchNames = Object.keys(operation.branches), operationIds = branchNames.map((name) => `run-all:${operation.step}:${name}`), resumedSlots = extractResumedSlots(operation.resumedCacheEntry), resumedSlotsByName = mapResumedSlotsByName(resumedSlots, branchNames), branchesToRun = filterBranchesToRun(operation.branches, branchNames, resumedSlotsByName), { outcomes, hasFirstError, firstError } = await executeRunAllBranchesSettled(branchesToRun, (fn, input) => callActivityFunction(fn, input)), slots = mergeRunAllSlots(branchNames, operationIds, resumedSlotsByName, outcomes), entry = buildEntryFromSlots("run-all", slots, branchNames), partialEntryWritten = writePartialEntry(internals, workflowId, operation.step, entry);

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

@@ -4,6 +4,11 @@ import { encode } from "../codec.js";
 import { buildTimerBatchOperations, normalizeStorageTimestamp } from "../scheduler.js";
 import { commitFencedEngineWrite } from "./fenced-write.js";
 import { reprovideRecoveredServices } from "./lifecycle/recovered-services.js";
+import {
+  acknowledgeSupersededSleepTimers,
+  handleSleepTimerWithAcknowledgement,
+  resolveSleepTimer
+} from "./sleep-timer-acknowledgements.js";
 import { buildWorkflowVisibilityIndexTransition } from "./workflow-indexes.js";
 export function createDelayedStartTimerEntry(_internals, workflowId, scheduledStartAt, options, callbacks) {
   return {
@@ -26,6 +31,8 @@ function sleepTimerFiredEarly(internals, workflowId, operation) {
   workflowMarkers.delete(operation.operationId);
   if (workflowMarkers.size === 0)
     internals.sleepTimersFiredWithoutResolver.delete(workflowId);
+  if (markedFireAt < operation.scheduledFireAt)
+    acknowledgeSupersededSleepTimers(internals, workflowId, operation.scheduledFireAt);
   return markedFireAt >= operation.scheduledFireAt;
 }
 export async function processSleepOperation(internals, workflowId, operation, callbacks) {
@@ -166,7 +173,7 @@ export async function handleTimerFired(internals, entry, callbacks) {
     return;
   }
   if (entry.kind === "sleep")
-    resolveSleepTimer(internals, entry);
+    await handleSleepTimerWithAcknowledgement(internals, entry, callbacks.loadWorkflowState);
   else if (entry.kind === "wait-condition")
     resolveConditionTimer(internals, entry);
   else if (entry.kind === "execution-deadline")
@@ -189,30 +196,3 @@ async function handleReviewTimer(internals, entry, callbacks) {
     return;
   await handler(entry);
 }
-function resolveSleepTimer(internals, entry) {
-  const operationId = entry.id.replace("sleep:", ""), resolverKey = `${entry.workflowId}:${operationId}`, resolver = internals.sleepResolvers.get(resolverKey);
-  if (!resolver) {
-    let workflowMarkers = internals.sleepTimersFiredWithoutResolver.get(entry.workflowId);
-    if (!workflowMarkers) {
-      workflowMarkers = new Map;
-      internals.sleepTimersFiredWithoutResolver.set(entry.workflowId, workflowMarkers);
-    }
-    const existing = workflowMarkers.get(operationId);
-    if (existing === void 0 || entry.fireAt > existing)
-      workflowMarkers.set(operationId, entry.fireAt);
-    return;
-  }
-  if (entry.fireAt < resolver.fireAt)
-    return;
-  internals.sleepResolvers.delete(resolverKey);
-  untrackSleepResolver(internals, entry.workflowId, operationId);
-  resolver.resolve();
-}
-function untrackSleepResolver(internals, workflowId, operationId) {
-  const workflowOperations = internals.sleepResolversByWorkflow.get(workflowId);
-  if (!workflowOperations)
-    return;
-  workflowOperations.delete(operationId);
-  if (workflowOperations.size === 0)
-    internals.sleepResolversByWorkflow.delete(workflowId);
-}

package/dist/core/engine/ownership-options.d.ts

@@ -13,6 +13,7 @@ export declare const DEFAULT_LEASE_TTL_MS = 30000;
 export declare const DEFAULT_LEASE_RENEW_INTERVAL_MS = 5000;
 /** Default boot-time lease acquisition wait window for `ownership: 'lease'`. */
 export declare const DEFAULT_LEASE_WAIT_TIMEOUT_MS = 60000;
+export declare function resolveBackgroundTaskMode(options: EngineConstructorOptions | undefined): ResolvedOptions['backgroundTaskMode'];
 /**
  * Resolve the ownership posture and lease tuning into their `ResolvedOptions`
  * fields. Defaults to `'none'`. The lease durations are documented as "ignored

package/dist/core/engine/ownership-options.js

@@ -1,5 +1,19 @@
 import { normalizeRetentionDuration } from "./validation.js";
 export const DEFAULT_LEASE_TTL_MS = 30000, DEFAULT_LEASE_RENEW_INTERVAL_MS = 5000, DEFAULT_LEASE_WAIT_TIMEOUT_MS = 60000;
+export function resolveBackgroundTaskMode(options) {
+  const mode = options?.backgroundTasks ?? "automatic";
+  if (mode !== "automatic" && mode !== "manual")
+    throw Error('options.backgroundTasks must be "automatic" or "manual" when provided');
+  if (mode === "manual")
+    assertManualBackgroundTaskCompatibility(options);
+  return mode;
+}
+function assertManualBackgroundTaskCompatibility(options) {
+  if (options?.detectSecondInstance === !0)
+    throw Error('detectSecondInstance cannot be enabled when backgroundTasks is "manual"');
+  if (options?.ownership === "lease")
+    throw Error('ownership cannot be "lease" when backgroundTasks is "manual"');
+}
 export function resolveOwnershipFields(options) {
   const ownershipMode = assertKnownOwnershipMode(options?.ownership ?? "none");
   if (ownershipMode !== "lease")

package/dist/core/engine/retention.js

@@ -11,6 +11,10 @@ export function setNextRetentionSweepAt(internals) {
   internals.nextRetentionSweepAt = internals.options.getNow() + internals.options.retentionSweepIntervalMs;
 }
 export function ensureRetentionSweepInterval(internals, callbacks) {
+  if (internals.options.backgroundTaskMode === "manual") {
+    internals.nextRetentionSweepAt = null;
+    return;
+  }
   if (!callbacks.hasConfiguredRetention()) {
     if (internals.retentionSweepInterval !== null) {
       clearInterval(internals.retentionSweepInterval ?? void 0);

package/dist/core/engine/schedule-run-metadata.d.ts

@@ -0,0 +1,3 @@
+import type { WorkflowServicesResolverScheduleInfo } from '../types.ts';
+export declare function encodeScheduleRunMetadata(scheduleId: string, occurrence: number | undefined): Uint8Array;
+export declare function decodeScheduleRunMetadata(bytes: Uint8Array): WorkflowServicesResolverScheduleInfo | null;

package/dist/core/engine/schedule-run-metadata.js

@@ -0,0 +1,29 @@
+import { decode, encode } from "../codec.js";
+import { isRecord } from "../debug-output.js";
+import { isValidScheduleIdentifier } from "./validation/schedule.js";
+export function encodeScheduleRunMetadata(scheduleId, occurrence) {
+  return encode({
+    id: scheduleId,
+    ...occurrence !== void 0 ? { occurrence } : {}
+  });
+}
+export function decodeScheduleRunMetadata(bytes) {
+  let decoded;
+  try {
+    decoded = decode(bytes);
+  } catch {
+    return null;
+  }
+  if (typeof decoded === "string")
+    return isValidScheduleIdentifier(decoded) ? { id: decoded } : null;
+  if (!isRecord(decoded))
+    return null;
+  const { id, occurrence } = decoded;
+  if (!isValidScheduleIdentifier(id))
+    return null;
+  if (occurrence === void 0)
+    return { id };
+  if (typeof occurrence !== "number" || !Number.isSafeInteger(occurrence))
+    return null;
+  return { id, occurrence };
+}

package/dist/core/engine/schedule-run.js

@@ -1,16 +1,31 @@
 import { KEYS } from "../../storage/interface.js";
-import { encode } from "../codec.js";
 import { ScheduleFiredEvent } from "../events.js";
 import { unavailableServicesError } from "./lifecycle/recovered-services.js";
 import { EMPTY_STORAGE_VALUE } from "./lifecycle/shared.js";
+import { encodeScheduleRunMetadata } from "./schedule-run-metadata.js";
 export async function startScheduledRun(internals, state, callbacks, occurrence) {
-  const workflowId = crypto.randomUUID(), scheduleRunOperations = state.overlap === "allow" ? [] : [{ type: "put", key: KEYS.scheduleRun(workflowId), value: encode(state.id) }], resolution = await resolveScheduledRunServices(internals, workflowId, state, occurrence);
+  const workflowId = crypto.randomUUID(), scheduleRunOperations = [
+    {
+      type: "put",
+      key: KEYS.scheduleRun(workflowId),
+      value: encodeScheduleRunMetadata(state.id, occurrence)
+    },
+    {
+      type: "put",
+      key: KEYS.terminalCleanupNeeded(workflowId),
+      value: EMPTY_STORAGE_VALUE
+    }
+  ], resolution = await resolveScheduledRunServices(internals, workflowId, state, occurrence);
   if (resolution !== null) {
-    scheduleRunOperations.push({ type: "put", key: KEYS.workflowHasServices(workflowId), value: EMPTY_STORAGE_VALUE }, { type: "put", key: KEYS.terminalCleanupNeeded(workflowId), value: EMPTY_STORAGE_VALUE });
-    internals.workflowsNeedingTerminalCleanup.add(workflowId);
+    scheduleRunOperations.push({
+      type: "put",
+      key: KEYS.workflowHasServices(workflowId),
+      value: EMPTY_STORAGE_VALUE
+    });
     if (resolution.status === "available")
       internals.workflowServices.set(workflowId, resolution.services);
   }
+  internals.workflowsNeedingTerminalCleanup.add(workflowId);
   await callbacks.startWorkflow(state.workflowType, state.input, { id: workflowId }, scheduleRunOperations);
   internals.engine.dispatchEvent(new ScheduleFiredEvent(state.id, workflowId, internals.options.getNow(), occurrence));
   if (resolution !== null && resolution.status === "unavailable") {

package/dist/core/engine/schedules.js

@@ -4,6 +4,7 @@ import { WorkflowNotRegisteredError } from "./errors.js";
 import { ScheduleHandle } from "./schedule-handle.js";
 import { resolveEffectiveScheduleFireAt } from "./schedule-jitter.js";
 import { getNextScheduleOccurrence } from "./schedule-occurrence.js";
+import { decodeScheduleRunMetadata } from "./schedule-run-metadata.js";
 import {
   clearScheduleCurrentWorkflow,
   createScheduleTimerId,
@@ -208,10 +209,10 @@ export async function handleScheduledWorkflowTerminal(internals, workflowId, cal
   if (!scheduleRunBytes)
     return;
   await internals.storage.delete(KEYS.scheduleRun(workflowId));
-  const decodedScheduleId = decode(scheduleRunBytes);
-  if (!isValidScheduleIdentifier(decodedScheduleId))
+  const metadata = decodeScheduleRunMetadata(scheduleRunBytes);
+  if (metadata === null || !isValidScheduleIdentifier(metadata.id))
     return;
-  const state = await loadScheduleState(internals, decodedScheduleId);
+  const scheduleId = metadata.id, state = await loadScheduleState(internals, scheduleId);
   if (!state || state.currentWorkflowId !== workflowId)
     return;
   const now = internals.options.getNow(), clearedState = {

package/dist/core/engine/sleep-timer-acknowledgements.d.ts

@@ -0,0 +1,15 @@
+import type { ContextOperationRequest } from '../context.ts';
+import type { TimerEntry, WorkflowState } from '../types.ts';
+import type { EngineInternals } from './internals.ts';
+export type SleepTimerAcknowledgement = {
+    cancel: () => void;
+    promise: Promise<void>;
+};
+export declare function handleSleepTimerWithAcknowledgement(internals: EngineInternals, entry: TimerEntry, loadWorkflowState: (workflowId: string) => Promise<WorkflowState | null>): Promise<void>;
+export declare function createSleepTimerAcknowledgement(internals: EngineInternals, workflowId: string, operationId: string, fireAt: number): SleepTimerAcknowledgement;
+export declare function recordDurableInlineOperation(internals: EngineInternals, workflowId: string, operation: ContextOperationRequest): void;
+export declare function settleSleepTimerAcknowledgements(internals: EngineInternals, workflowId: string, disposition: 'suspended' | 'terminal'): void;
+export declare function acknowledgeSupersededSleepTimers(internals: EngineInternals, workflowId: string, currentDeadline: number): void;
+export declare function rejectSleepTimerAcknowledgements(internals: EngineInternals, workflowId: string, error: unknown): void;
+export declare function rejectAllSleepTimerAcknowledgements(internals: EngineInternals, error: Error): void;
+export declare function resolveSleepTimer(internals: EngineInternals, entry: TimerEntry): boolean;