@lostgradient/weft 0.9.0 → 0.10.0

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/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/sub-operation.js

@@ -16,7 +16,10 @@ import {
   executeActivityOperationResult
 } from "./operations-activity.js";
 import {
-  executeRunAllOperationResult
+  assertValidRaceBranchNames,
+  executeRaceSubOperations,
+  executeRunAllOperationResult,
+  wrapRaceWinner
 } from "./operations-coordination.js";
 import { callMemoFunction } from "./state-utilities.js";
 export async function processWaitReviewOperation(_internals, workflowId, operation, callbacks) {
@@ -82,16 +85,6 @@ async function executeParallelSubOperation(internals, workflowId, operation, cal
 }
 async function executeRaceSubOperation(internals, workflowId, operation, callbacks, signal, speculativeState) {
   signal?.throwIfAborted();
-  const controller = new AbortController, abortNestedRace = () => {
-    controller.abort(signal?.reason);
-  };
-  signal?.addEventListener("abort", abortNestedRace, { once: !0 });
-  const subOperations = operation.operations.map((subOperation) => executeSubOperation(internals, workflowId, subOperation, callbacks, controller.signal, speculativeState));
-  Promise.allSettled(subOperations);
-  try {
-    return await Promise.race(subOperations);
-  } finally {
-    signal?.removeEventListener("abort", abortNestedRace);
-    controller.abort();
-  }
+  assertValidRaceBranchNames(operation);
+  return executeRaceSubOperations(internals, workflowId, operation.operations, (subOperation, branchSignal) => executeSubOperation(internals, workflowId, subOperation, callbacks, branchSignal, speculativeState), signal, (winnerIndex, value) => wrapRaceWinner(operation, winnerIndex, value));
 }

package/dist/core/engine/termination/cleanup.js

@@ -1,6 +1,6 @@
 import { KEYS, encodeStorageKeyComponent, storageHas } from "../../../storage/interface.js";
 import { CleanupWarningEvent } from "../../events.js";
-import { asyncActivityWorkflowPrefix } from "../async-activity-completion.js";
+import { asyncActivityWorkflowPrefix } from "../async-activity-records.js";
 import { forgetCommittedCheckpointBytes } from "../checkpoint-commit-snapshots.js";
 import { parseTerminalCleanupTimerId, workflowFeedListenerKey } from "../state-utilities.js";
 import { releaseWorkflowConcurrencySlot } from "../workflow-concurrency.js";
@@ -194,7 +194,9 @@ export async function runDeferredTerminalCleanup(internals, workflowId, timerId,
   if (state.terminalCleanupToken !== parsedTimer.terminalCleanupToken)
     return;
   try {
+    await finalizeScheduledWorkflowTerminal(internals, workflowId, callbacks);
     await cleanupTerminalWorkflowDurableState(internals, workflowId, parsedTimer.includeOutputArtifacts, callbacks);
+    await internals.storage.delete(KEYS.scheduleRun(workflowId));
   } catch (error) {
     callbacks.handleCleanupError("cleanupTerminalWorkflowDurableState", error, workflowId);
     throw error;

package/dist/core/types/options.d.ts

@@ -218,6 +218,18 @@ export interface ForkOptions {
 export interface EngineOptions<TServices = unknown> {
     storage?: WeftStorage;
     development?: boolean;
+    /**
+     * Select how engine-owned periodic work is driven. The default `'automatic'`
+     * profile starts in-process intervals for update-response cleanup, configured
+     * retention sweeps, alert re-evaluation, and the durable-timer scheduler used
+     * by {@link Engine.create}. Use `'manual'` in runtimes such as Cloudflare
+     * Durable Objects where the host must wake the engine through alarms or Cron
+     * triggers, then call {@link Engine.runMaintenance} from each wake-up.
+     *
+     * Manual mode rejects interval-dependent ownership and second-instance
+     * detection options instead of silently starting background work.
+     */
+    backgroundTasks?: 'automatic' | 'manual';
     serializer?: Serializer;
     retention?: RetentionPolicy;
     retentionSweepInterval?: Duration;

package/dist/core/types/services-resolution.d.ts

@@ -50,7 +50,11 @@ export interface WorkflowServicesResolverLaunchOptions {
 }
 /**
  * Schedule context passed to {@link EngineOptions.resolveWorkflowServices} for
- * scheduled occurrences.
+ * scheduled occurrences. New scheduled runs persist this context with the
+ * workflow record, so a fresh-process recovery receives the same schedule id and
+ * known occurrence timestamp as the live launch path. Runs from older stores
+ * that predate the metadata may omit it, and queue-drained runs may omit
+ * `occurrence` because their original grid timestamp was not retained.
  *
  * @example
  * ```ts
@@ -72,8 +76,9 @@ export interface WorkflowServicesResolverScheduleInfo {
  * recovered workflow or scheduled occurrence. `input` is the original durable
  * launch input, available at resume time — typically enough to rebuild the run's
  * dependencies (tenant, model, tool registry) without a side table. When tags or
- * schedule identity are part of the durable launch context, they are exposed so
- * resolvers do not need parallel side channels for the same classification.
+ * schedule identity are part of the durable launch context, they are exposed on
+ * both live scheduled launches and recovery so resolvers do not need parallel
+ * side channels for the same classification.
  *
  * @example
  * ```ts

package/dist/core/types/workflow-builder.d.ts

@@ -50,8 +50,8 @@ export type WorkflowGenerator<TInput, TOutput, TActivities extends ActivityMap,
  * Bare-`WorkflowContext` callers (no declared activity/signal/etc. maps)
  * typecheck because the interface's generics all default to permissive shapes:
  * the typed overloads de-prioritise to `never` and the dynamic string-name /
- * callable overloads match instead. This permissive path is current API — it is
- * how untyped, ad-hoc-name authoring is supported, not a compatibility shim.
+ * callable overloads match instead. This permissive path is the current API for
+ * untyped, ad-hoc-name authoring.
  */
 export type WorkflowContextOf<TActivities extends ActivityMap = ActivityMap, TSignals extends SignalMap = SignalMap, TUpdates extends UpdateMap = UpdateMap, TQueries extends QueryMap = QueryMap, TSearchAttributes extends SearchAttributeSchema = SearchAttributeSchema, TServices = unknown> = WorkflowContext<TActivities, TSignals, TUpdates, TQueries, TSearchAttributes, TServices>;
 /**

package/dist/core/types/workflow-context.d.ts

@@ -15,6 +15,32 @@ export type WorkflowOperationResult<TOperation> = TOperation extends Generator<u
 export type WorkflowOperationTupleResult<TOperations extends readonly WorkflowOperation<unknown>[]> = {
     -readonly [TIndex in keyof TOperations]: WorkflowOperationResult<TOperations[TIndex]>;
 };
+/**
+ * Discriminated winner returned by {@link WorkflowContext.raceKeyed}. Checking
+ * `key` narrows `value` to the result type of that named workflow operation.
+ * Numeric object keys are returned as strings, matching JavaScript object
+ * enumeration; symbol keys are rejected at runtime.
+ *
+ * @example
+ * ```ts
+ * import type { WorkflowKeyedRaceResult, WorkflowOperation } from '@lostgradient/weft';
+ *
+ * type Winner = WorkflowKeyedRaceResult<{
+ *   event: WorkflowOperation<string>;
+ *   idle: WorkflowOperation<void>;
+ * }>;
+ *
+ * function handleWinner(winner: Winner): string {
+ *   return winner.key === 'event' ? winner.value : 'timed out';
+ * }
+ * ```
+ */
+export type WorkflowKeyedRaceResult<TOperations extends Readonly<Record<string, WorkflowOperation<unknown>>>> = {
+    [TKey in keyof TOperations]: {
+        key: TKey extends string | number ? `${TKey}` : never;
+        value: WorkflowOperationResult<TOperations[TKey]>;
+    };
+}[keyof TOperations];
 type RunAllBranchResult<TBranch> = TBranch extends readonly [
     execute: infer TExecute,
     ...rest: unknown[]
@@ -180,6 +206,7 @@ export interface WorkflowContext<TActivities extends ActivityMap = {}, TSignals
     review(options: HumanReviewOptions): WorkflowOperation<HumanReviewResult>;
     all<const TOperations extends readonly WorkflowOperation<unknown>[]>(operations: TOperations): WorkflowOperation<WorkflowOperationTupleResult<TOperations>>;
     race<const TOperations extends readonly WorkflowOperation<unknown>[]>(operations: TOperations): WorkflowOperation<WorkflowOperationTupleResult<TOperations>[number]>;
+    raceKeyed<const TOperations extends Readonly<Record<string, WorkflowOperation<unknown>>>>(operations: TOperations): WorkflowOperation<WorkflowKeyedRaceResult<TOperations>>;
     memo<T>(key: string, fn: () => T | Promise<T>): WorkflowOperation<T>;
     offload<T>(key: string, fn: () => Promise<T>): WorkflowOperation<OffloadReference>;
     stream(key: string, fn: (sink: StreamSink) => AsyncGenerator<unknown, void, unknown>): WorkflowOperation<StreamReference>;

package/dist/index.d.ts

@@ -22,9 +22,9 @@ export { FAULT_CODE_TO_FAILURE_CATEGORY, failureCategoryForFaultCode, isFaultCod
 export type { FaultCode } from './core/fault-code.ts';
 export { DurableActivityScopeError, DurableActivityUnsupportedError, durableActivity, } from './core/context/durable-activity.ts';
 export { ActivityReconciliationCapabilityError, ActivityReconciliationConflictError, ActivityReconciliationIndeterminateError, ActivityResolutionError, AsyncActivityTokenNotFoundError, BulkDeleteRequiresTerminalWorkflowsError, BulkOperationConfirmationError, ENGINE_LEASE_LOST_WARNING_NAME, ENGINE_LEASE_SYNCHRONOUS_DISPOSE_WARNING_NAME, Engine, EngineCreateNameMismatchError, EngineDisposedError, EngineLeaseAcquisitionTimeoutError, EngineLeaseCorruptedError, EngineLeaseNotHeldError, IdempotencyKeyPurgedError, PersistedDataIncompatibleError, ScheduleHandle, StartOrSignalConflictError, WorkflowAlreadyExistsError, WorkflowConcurrencyLimitExceededError, WorkflowHandle, WorkflowNotFoundError, WorkflowNotRegisteredError, WorkflowSuspendNotSupportedError, WorkflowTeardownPendingError, WorkflowTypeNotRegisteredForRecoveryError, } from './core/engine';
-export type { EngineCreateOptions, EngineStateNamespace, RecoverAllOptions } from './core/engine';
+export type { EngineCreateOptions, EngineStateNamespace, RecoverAllOptions, RecoveredWorkflowInfo, } from './core/engine';
 export { DEFAULT_CHECKPOINT_SIZE_WARNING_THRESHOLD, DEFAULT_MAX_NESTING_DEPTH, DEFAULT_POLL_INTERVAL_MS, DEFAULT_RETRY_POLICY, DEFAULT_VISIBILITY_TIMEOUT_MS, HISTORY_CIRCUIT_BREAKER_REASON, WorkflowBuilderError, query, schedule, signal, update, workflow, } from './core/types';
-export type { ActivityArgsFor, ActivityCallOptions, ActivityCallable, ActivityContext, ActivityDefinition, ActivityEntryInput, ActivityFunction, ActivityMap, ActivityMapInput, ActivityObjectInput, ActivityResultFor, ActivityVerificationContext, ActivityVerificationPhase, ActivityVerificationResult, AnyActivityDefinition, AnyWorkflowDefinition, ArchiveAdapter, BuilderState, BuiltWorkflowDefinition, BulkCancelResult, BulkDeleteResult, BulkOperationAction, BulkOperationAuditEvent, BulkOperationCommitOptions, BulkOperationDryRunOptions, BulkOperationDryRunResult, BulkOperationError, BulkOperationFilterSummary, BulkOperationOptions, BulkOperationPrincipal, BulkOperationScopeSummary, BulkRetryFailedResult, BulkSignalAllCommitOptions, BulkSignalAllDryRunOptions, BulkSignalAllOptions, BulkSignalResult, BulkTagResult, Checkpoint, CheckpointState, CheckpointSummary, CompletedReviewEntry, CoordinatedUpdateResult, DefinitionSchema, Duration, EngineOptions, FailureCategory, ForkLineage, ForkOptions, HistoryPolicy, InferActivityEntries, InferActivityEntry, InferWorkflowEntries, InferWorkflowEntry, InitialBuilderState, LaunchMetadata, ListFilter, ListOptions, MarkBuilderState, NormalizeActivities, NormalizedActivityEntry, NormalizedRetentionPolicy, PaginatedResult, PayloadSizePolicy, PendingReviewEntry, PurgeResult, QueryDefinition, QueryMap, QueryShape, RegisteredWorkflowDefinition, RetentionOverview, RetentionPolicy, RetryPolicy, ReviewListEntry, ReviewListFilter, ReviewStatus, ScheduleDefinition, ScheduleFilter, ScheduleOptions, ScheduleOverlapPolicy, ScheduleSpec, ScheduleState, ScheduleStatus, ScheduleSummary, SearchAttributeDefinition, SearchAttributeHandle, SearchAttributeSchema, SearchAttributeValue, Serializer, SignalDefinition, SignalDeliveryOptions, SignalMap, SignalPayload, StartOptions, StartOrSignalOptions, StartOrSignalSignal, SubmitReviewOptions, TerminationReason, UpdateDefinition, UpdateMap, UpdatePayload, WorkerReplayOperationFailure, WorkerReplayOperationSignature, WorkflowAlreadyRegistered, WorkflowAtomicState, WorkflowAtomicStateOptions, WorkflowBuilder, WorkflowBuilderOptions, WorkflowConcurrencyOptions, WorkflowContext, WorkflowDefinition, WorkflowEvent, WorkflowFunction, WorkflowGenerator, WorkflowId, WorkflowLogLevel, WorkflowLogRecord, WorkflowLogger, WorkflowRegistry, WorkflowReplay, WorkflowServicesResolution, WorkflowServicesResolverInfo, WorkflowServicesResolverLaunchOptions, WorkflowServicesResolverScheduleInfo, WorkflowSessionState, WorkflowSnapshot, WorkflowState, WorkflowStateNamespace, WorkflowStatus, WorkflowSummary, WorkflowTimelineEntry, WorkflowTimelineStatus, WorkflowTypeRetentionPolicy, } from './core/types';
+export type { ActivityArgsFor, ActivityCallOptions, ActivityCallable, ActivityContext, ActivityDefinition, ActivityEntryInput, ActivityFunction, ActivityMap, ActivityMapInput, ActivityObjectInput, ActivityResultFor, ActivityVerificationContext, ActivityVerificationPhase, ActivityVerificationResult, AnyActivityDefinition, AnyWorkflowDefinition, ArchiveAdapter, BuilderState, BuiltWorkflowDefinition, BulkCancelResult, BulkDeleteResult, BulkOperationAction, BulkOperationAuditEvent, BulkOperationCommitOptions, BulkOperationDryRunOptions, BulkOperationDryRunResult, BulkOperationError, BulkOperationFilterSummary, BulkOperationOptions, BulkOperationPrincipal, BulkOperationScopeSummary, BulkRetryFailedResult, BulkSignalAllCommitOptions, BulkSignalAllDryRunOptions, BulkSignalAllOptions, BulkSignalResult, BulkTagResult, Checkpoint, CheckpointState, CheckpointSummary, CompletedReviewEntry, CoordinatedUpdateResult, DefinitionSchema, Duration, EngineOptions, FailureCategory, ForkLineage, ForkOptions, HistoryPolicy, InferActivityEntries, InferActivityEntry, InferWorkflowEntries, InferWorkflowEntry, InitialBuilderState, LaunchMetadata, ListFilter, ListOptions, MarkBuilderState, NormalizeActivities, NormalizedActivityEntry, NormalizedRetentionPolicy, PaginatedResult, PayloadSizePolicy, PendingReviewEntry, PurgeResult, QueryDefinition, QueryMap, QueryShape, RegisteredWorkflowDefinition, RetentionOverview, RetentionPolicy, RetryPolicy, ReviewListEntry, ReviewListFilter, ReviewStatus, ScheduleDefinition, ScheduleFilter, ScheduleOptions, ScheduleOverlapPolicy, ScheduleSpec, ScheduleState, ScheduleStatus, ScheduleSummary, SearchAttributeDefinition, SearchAttributeHandle, SearchAttributeSchema, SearchAttributeValue, Serializer, SignalDefinition, SignalDeliveryOptions, SignalMap, SignalPayload, StartOptions, StartOrSignalOptions, StartOrSignalSignal, SubmitReviewOptions, TerminationReason, UpdateDefinition, UpdateMap, UpdatePayload, WorkerReplayOperationFailure, WorkerReplayOperationSignature, WorkflowAlreadyRegistered, WorkflowAtomicState, WorkflowAtomicStateOptions, WorkflowBuilder, WorkflowBuilderOptions, WorkflowConcurrencyOptions, WorkflowContext, WorkflowDefinition, WorkflowEvent, WorkflowFunction, WorkflowGenerator, WorkflowId, WorkflowKeyedRaceResult, WorkflowLogLevel, WorkflowLogRecord, WorkflowLogger, WorkflowRegistry, WorkflowReplay, WorkflowServicesResolution, WorkflowServicesResolverInfo, WorkflowServicesResolverLaunchOptions, WorkflowServicesResolverScheduleInfo, WorkflowSessionState, WorkflowSnapshot, WorkflowState, WorkflowStateNamespace, WorkflowStatus, WorkflowSummary, WorkflowTimelineEntry, WorkflowTimelineStatus, WorkflowTypeRetentionPolicy, } from './core/types';
 export { AlertManager } from './alerting/index';
 export type { AlertAction, AlertMetric, AlertRule, AlertState, AlertStatus, AlertingOptions, WebhookTarget, } from './alerting/types';
 export { ActivityAsyncPendingEvent, ActivityCompletedEvent, ActivityFailedEvent, ActivityStartedEvent, AlertFiredEvent, AlertResolvedEvent, AttributesChangedEvent, CheckpointSizeWarningEvent, ConstraintViolatedEvent, DevelopmentWarningEvent, ScheduleFiredEvent, ScheduleMissedFireEvent, SignalDeliveredEvent, SignalReceivedEvent, StorageSizeReportedEvent, TaskResultDeadLetteredEvent, UpdateCompletedEvent, UpdateReceivedEvent, WorkflowCancelledEvent, WorkflowCompletedEvent, WorkflowDefinitionRegisteredEvent, WorkflowFailedEvent, WorkflowRecoverySkippedEvent, WorkflowResumedEvent, WorkflowStartedEvent, WorkflowSuspendedEvent, WorkflowTeardownEvent, WorkflowTimedOutEvent, } from './core/events';