@lostgradient/weft 0.8.0 → 0.10.0

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 () => {
@@ -40,7 +40,7 @@ export function buildActivityCompensation(internals, workflowId, operation, resu
     await activity.compensate?.(operation.input, result);
   };
 }
-export async function invokeWorkerActivity(internals, operationId, activityName, input, attempt) {
+export async function invokeWorkerActivity(internals, operationId, activityName, input, attempt, workflowExecutionToken, activityAttemptToken) {
   const dispatcher = internals.activityWorkerDispatcher;
   if (!dispatcher)
     throw Error(`No activity worker dispatcher available for "${activityName}"`);
@@ -48,7 +48,9 @@ export async function invokeWorkerActivity(internals, operationId, activityName,
     operationId,
     activityName,
     input,
-    attempt
+    attempt,
+    ...workflowExecutionToken !== void 0 && { workflowExecutionToken },
+    ...activityAttemptToken !== void 0 && { activityAttemptToken }
   });
   if (result.status === "failed") {
     const error = Error(result.error);
@@ -74,11 +76,11 @@ function getActivityStateKey(operation) {
   return operation.activityStateKey ?? operation.step ?? 0;
 }
 export async function executeActivity(internals, workflowId, operation, callbacks, attempt = getActivityAttempt(operation), coordinatorSignal) {
-  const activityInput = operation.input, activityStateKey = getActivityStateKey(operation);
+  const activityInput = operation.input, activityStateKey = getActivityStateKey(operation), workflowExecutionToken = operation.workflowExecutionToken;
   warnIfRetryMissingHeartbeat(internals, workflowId, activityStateKey, attempt);
-  const asyncToken = deriveAsyncActivityToken(workflowId, activityStateKey, attempt), { perAttemptTimeoutMs, attemptAbortController, activitySignal } = resolvePerAttemptTimeout(internals, workflowId, operation, coordinatorSignal), activityContext = buildActivityContext(internals, workflowId, activityStateKey, activitySignal, () => {
+  const asyncToken = deriveAsyncActivityToken(workflowId, activityStateKey, attempt), { perAttemptTimeoutMs, attemptAbortController, activitySignal } = resolvePerAttemptTimeout(internals, workflowId, operation, coordinatorSignal), activityContext = buildActivityContext(internals, workflowId, workflowExecutionToken, activityStateKey, attempt, activitySignal, () => {
     throw new AsyncActivityDeferral(asyncToken);
-  }), invokeActivity = internals.activityWorkerDispatcher ? (activityName, input) => invokeWorkerActivity(internals, operation.operationId, activityName, input, attempt) : (activityName, input) => withPerAttemptTimeout(invokeInlineActivity(internals, workflowId, operation, activityContext, activityName, input), perAttemptTimeoutMs, activityName, attempt, attemptAbortController), composedActivity = callbacks.getComposedActivityInterceptor(), executeWithActivityInterceptors = async (activityName, input, headers) => {
+  }), activityAttemptToken = activityContext.activityAttemptToken, invokeActivity = internals.activityWorkerDispatcher ? (activityName, input) => invokeWorkerActivity(internals, operation.operationId, activityName, input, attempt, workflowExecutionToken, activityAttemptToken) : (activityName, input) => withPerAttemptTimeout(invokeInlineActivity(internals, workflowId, operation, activityContext, activityName, input), perAttemptTimeoutMs, activityName, attempt, attemptAbortController), composedActivity = callbacks.getComposedActivityInterceptor(), executeWithActivityInterceptors = async (activityName, input, headers) => {
     if (!composedActivity)
       return invokeActivity(activityName, input);
     const activityInterception = {

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.d.ts

@@ -12,7 +12,7 @@ export type TimeOperationCallbacks = {
     loadWorkflowState: (workflowId: string) => Promise<WorkflowState | null>;
     failWorkflow: (workflowId: string, error: Error) => Promise<void>;
     runSerializedWorkflowStateWrite: <Result>(workflowId: string, writeOperation: () => Promise<Result>) => Promise<Result>;
-    beginWorkflowExecution: (workflowId: string, workflowType: string, input: unknown, checkpoint: Checkpoint, executionDeadline: number | undefined, executionStateOwnerId: string, registration: RegistrationEntry) => void;
+    beginWorkflowExecution: (workflowId: string, workflowExecutionToken: string | undefined, workflowType: string, input: unknown, checkpoint: Checkpoint, executionDeadline: number | undefined, executionStateOwnerId: string, registration: RegistrationEntry) => void;
     workflowVersionTupleFromState: (state: WorkflowState) => WorkflowVersionTuple;
     setWorkflowStartHeaders: (workflowId: string, headers: Map<string, string> | undefined) => void;
     loadWorkflowStartHeaders: (workflowId: string) => Promise<Map<string, string> | undefined>;
@@ -25,7 +25,7 @@ export type TimeOperationCallbacks = {
 };
 export declare function createDelayedStartTimerEntry(_internals: EngineInternals, workflowId: string, scheduledStartAt: number, options: StartOptions | undefined, callbacks: Pick<TimeOperationCallbacks, 'parseStartOptionDuration'>): TimerEntry;
 export declare function processSleepOperation(internals: EngineInternals, workflowId: string, operation: SleepOperation, callbacks: Pick<TimeOperationCallbacks, 'completeOperation' | 'loadWorkflowState'>): Promise<void>;
-export declare function registerSleepResolver(internals: EngineInternals, workflowId: string, operationId: string, resolve: () => void): void;
+export declare function registerSleepResolver(internals: EngineInternals, workflowId: string, operationId: string, resolve: () => void, scheduledFireAt: number): void;
 export declare function startDelayedWorkflow(internals: EngineInternals, entry: TimerEntry, callbacks: Pick<TimeOperationCallbacks, 'beginWorkflowExecution' | 'dispatchEvent' | 'failWorkflow' | 'handleCleanupError' | 'loadWorkflowStartHeaders' | 'loadWorkflowState' | 'runSerializedWorkflowStateWrite' | 'setWorkflowStartHeaders' | 'workflowVersionTupleFromState'>): Promise<void>;
 export declare function handleTimerFired(internals: EngineInternals, entry: TimerEntry, callbacks: Pick<TimeOperationCallbacks, 'failWorkflow' | 'handleCleanupError' | 'loadWorkflowStartHeaders' | 'loadWorkflowState' | 'runDeferredTerminalCleanup' | 'runWorkflowFinalizer' | 'runSerializedWorkflowStateWrite' | 'handleScheduleTimer' | 'setWorkflowStartHeaders' | 'timeout' | 'beginWorkflowExecution' | 'dispatchEvent' | 'workflowVersionTupleFromState'>): Promise<void>;
 export {};

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

@@ -16,6 +16,18 @@ export function createDelayedStartTimerEntry(_internals, workflowId, scheduledSt
     }
   };
 }
+function sleepTimerFiredEarly(internals, workflowId, operation) {
+  const workflowMarkers = internals.sleepTimersFiredWithoutResolver.get(workflowId);
+  if (!workflowMarkers)
+    return !1;
+  const markedFireAt = workflowMarkers.get(operation.operationId);
+  if (markedFireAt === void 0)
+    return !1;
+  workflowMarkers.delete(operation.operationId);
+  if (workflowMarkers.size === 0)
+    internals.sleepTimersFiredWithoutResolver.delete(workflowId);
+  return markedFireAt >= operation.scheduledFireAt;
+}
 export async function processSleepOperation(internals, workflowId, operation, callbacks) {
   if (operation.scheduledFireAt <= internals.options.getNow()) {
     callbacks.completeOperation(workflowId, void 0);
@@ -28,13 +40,24 @@ export async function processSleepOperation(internals, workflowId, operation, ca
     fireAt: operation.scheduledFireAt,
     kind: "sleep"
   });
-  registerSleepResolver(internals, workflowId, operation.operationId, resolve);
+  registerSleepResolver(internals, workflowId, operation.operationId, resolve, operation.scheduledFireAt);
+  const resolverKey = `${workflowId}:${operation.operationId}`;
+  if (sleepTimerFiredEarly(internals, workflowId, operation) && internals.sleepResolvers.has(resolverKey))
+    resolveSleepTimer(internals, {
+      id: `sleep:${operation.operationId}`,
+      workflowId,
+      fireAt: operation.scheduledFireAt,
+      kind: "sleep"
+    });
   await promise;
   if ((await callbacks.loadWorkflowState(workflowId))?.status === "running")
     callbacks.completeOperation(workflowId, void 0);
 }
-export function registerSleepResolver(internals, workflowId, operationId, resolve) {
-  internals.sleepResolvers.set(`${workflowId}:${operationId}`, resolve);
+export function registerSleepResolver(internals, workflowId, operationId, resolve, scheduledFireAt) {
+  internals.sleepResolvers.set(`${workflowId}:${operationId}`, {
+    resolve,
+    fireAt: scheduledFireAt
+  });
   let workflowOperations = internals.sleepResolversByWorkflow.get(workflowId);
   if (!workflowOperations) {
     workflowOperations = new Set;
@@ -94,7 +117,7 @@ export async function startDelayedWorkflow(internals, entry, callbacks) {
   internals.checkpoints.set(entry.workflowId, checkpoint);
   internals.workflowVersionTuples.set(entry.workflowId, callbacks.workflowVersionTupleFromState(runningState));
   callbacks.setWorkflowStartHeaders(entry.workflowId, await callbacks.loadWorkflowStartHeaders(entry.workflowId));
-  callbacks.beginWorkflowExecution(entry.workflowId, runningState.type, runningState.input, checkpoint, executionDeadline, runningState.executionStateOwnerId ?? entry.workflowId, registration);
+  callbacks.beginWorkflowExecution(entry.workflowId, runningState.workflowExecutionToken, runningState.type, runningState.input, checkpoint, executionDeadline, runningState.executionStateOwnerId ?? entry.workflowId, registration);
 }
 async function loadDelayedWorkflowCheckpoint(internals, entry, callbacks) {
   const checkpointBytes = await internals.storage.get(KEYS.checkpoint(entry.workflowId));
@@ -168,11 +191,22 @@ async function handleReviewTimer(internals, entry, callbacks) {
 }
 function resolveSleepTimer(internals, entry) {
   const operationId = entry.id.replace("sleep:", ""), resolverKey = `${entry.workflowId}:${operationId}`, resolver = internals.sleepResolvers.get(resolverKey);
-  if (!resolver)
+  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();
+  resolver.resolve();
 }
 function untrackSleepResolver(internals, workflowId, operationId) {
   const workflowOperations = internals.sleepResolversByWorkflow.get(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,
@@ -35,6 +36,9 @@ export async function schedule(internals, type, input, spec, options) {
       id: scheduleId,
       workflowType: type,
       input,
+      ...normalizedOptions.description !== void 0 && {
+        description: normalizedOptions.description
+      },
       ...cadenceFields,
       status: "active",
       overlap: normalizedOptions.overlap,
@@ -205,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";
@@ -43,23 +43,25 @@ function cleanupTrackedWaiter(internals, workflowId, kind) {
 }
 function cleanupSleepResolvers(internals, workflowId) {
   const sleepOps = internals.sleepResolversByWorkflow.get(workflowId);
-  if (!sleepOps)
-    return;
-  for (const operationId of sleepOps) {
-    const key = `${workflowId}:${operationId}`, resolver = internals.sleepResolvers.get(key);
-    if (resolver)
-      resolver();
-    internals.sleepResolvers.delete(key);
+  if (sleepOps) {
+    for (const operationId of sleepOps) {
+      const key = `${workflowId}:${operationId}`, resolver = internals.sleepResolvers.get(key);
+      if (resolver)
+        resolver.resolve();
+      internals.sleepResolvers.delete(key);
+    }
+    internals.sleepResolversByWorkflow.delete(workflowId);
   }
-  internals.sleepResolversByWorkflow.delete(workflowId);
+  internals.sleepTimersFiredWithoutResolver.delete(workflowId);
 }
 function evictSleepResolversWithoutResolving(internals, workflowId) {
   const sleepOps = internals.sleepResolversByWorkflow.get(workflowId);
-  if (!sleepOps)
-    return;
-  for (const operationId of sleepOps)
-    internals.sleepResolvers.delete(`${workflowId}:${operationId}`);
-  internals.sleepResolversByWorkflow.delete(workflowId);
+  if (sleepOps) {
+    for (const operationId of sleepOps)
+      internals.sleepResolvers.delete(`${workflowId}:${operationId}`);
+    internals.sleepResolversByWorkflow.delete(workflowId);
+  }
+  internals.sleepTimersFiredWithoutResolver.delete(workflowId);
 }
 function cleanupConditionWaiters(internals, workflowId) {
   const resolver = internals.conditionWaiters.get(workflowId);
@@ -192,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/engine/termination/finalizer-activity.d.ts

@@ -50,4 +50,4 @@ export type FinalizerAttemptResult = {
  * @param attempt - 1-based attempt number, for the per-attempt timeout error message
  * @param shutdownSignal - the engine's dispose/shutdown abort signal; aborting it stops a cooperating finalizer
  */
-export declare function runFinalizerActivity(finalizer: RunnableFinalizer, input: unknown, attempt: number, shutdownSignal: AbortSignal): Promise<FinalizerAttemptResult>;
+export declare function runFinalizerActivity(finalizer: RunnableFinalizer, input: unknown, attempt: number, shutdownSignal: AbortSignal, workflowExecutionToken?: string): Promise<FinalizerAttemptResult>;

package/dist/core/engine/termination/finalizer-activity.js

@@ -1,6 +1,6 @@
 import { parseDuration } from "../../scheduler.js";
 import { withPerAttemptTimeout } from "../activity-per-attempt-timeout.js";
-export async function runFinalizerActivity(finalizer, input, attempt, shutdownSignal) {
+export async function runFinalizerActivity(finalizer, input, attempt, shutdownSignal, workflowExecutionToken) {
   const perAttemptTimeoutMs = finalizer.timeout === void 0 ? void 0 : parseDuration(finalizer.timeout), attemptController = new AbortController, relayShutdownAbort = () => attemptController.abort(shutdownSignal.reason);
   if (shutdownSignal.aborted)
     attemptController.abort(shutdownSignal.reason);
@@ -8,6 +8,10 @@ export async function runFinalizerActivity(finalizer, input, attempt, shutdownSi
     shutdownSignal.addEventListener("abort", relayShutdownAbort, { once: !0 });
   const activityContext = {
     signal: attemptController.signal,
+    ...workflowExecutionToken !== void 0 && {
+      workflowExecutionToken,
+      activityAttemptToken: `${workflowExecutionToken}:finalizer:${String(attempt)}`
+    },
     heartbeat: () => {},
     completeAsync: () => {
       throw Error(`Finalizer "${finalizer.name}" called ctx.completeAsync(), which is not supported in a workflow finalizer: the finalizer runs after the workflow is already terminal, so there is no durable step to complete out of band. Run the teardown synchronously instead.`);

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

@@ -103,7 +103,7 @@ async function driveResolvedTeardown(internals, workflowId, token, drive, callba
     await rearmTeardownTimer(internals, workflowId, token, TEARDOWN_SELF_HEAL_DELAY_MS);
     return;
   }
-  const result = await runFinalizerActivity(finalizer, finalizerInput, attempt, internals.abortController.signal);
+  const result = await runFinalizerActivity(finalizer, finalizerInput, attempt, internals.abortController.signal, state.workflowExecutionToken);
   if (result.ok) {
     await settleTeardownSuccess(internals, workflowId, state.type, token, attempt, runningBytes, callbacks);
     return;

package/dist/core/engine/validation/schedule-options.d.ts

@@ -0,0 +1,9 @@
+import type { ScheduleOptions, ScheduleOverlapPolicy } from '../../types.ts';
+export declare const SCHEDULE_OVERLAP_POLICIES: Set<ScheduleOverlapPolicy>;
+type NormalizedScheduleOptions = Required<Pick<ScheduleOptions, 'overlap' | 'backfill'>> & {
+    id?: string;
+    description?: string;
+    jitterMs?: number;
+};
+export declare function normalizeScheduleOptions(options: ScheduleOptions | undefined): NormalizedScheduleOptions;
+export {};

package/dist/core/engine/validation/schedule-options.js

@@ -0,0 +1,59 @@
+import { parseDuration } from "../../scheduler.js";
+import { coerceStartWorkflowId } from "../../start-workflow-validation.js";
+export const SCHEDULE_OVERLAP_POLICIES = new Set([
+  "skip",
+  "queue",
+  "cancel-running",
+  "allow"
+]);
+export function normalizeScheduleOptions(options) {
+  if (options === void 0)
+    return { overlap: "skip", backfill: !1 };
+  if (typeof options !== "object" || options === null)
+    throw Error("options must be an object when provided");
+  return {
+    overlap: normalizeScheduleOverlap(options.overlap),
+    backfill: normalizeScheduleBackfill(options.backfill),
+    ...options.id !== void 0 && { id: coerceStartWorkflowId(options.id, "options.id") },
+    ...options.description !== void 0 && {
+      description: normalizeScheduleDescription(options.description)
+    },
+    ...options.jitter !== void 0 && {
+      jitterMs: normalizeScheduleJitter(options.jitter, "options.jitter")
+    }
+  };
+}
+function normalizeScheduleDescription(description) {
+  if (typeof description !== "string")
+    throw Error("options.description must be a string when provided");
+  return description;
+}
+function normalizeScheduleOverlap(overlap) {
+  if (overlap === void 0)
+    return "skip";
+  if (!SCHEDULE_OVERLAP_POLICIES.has(overlap))
+    throw Error(`options.overlap must be one of ${[...SCHEDULE_OVERLAP_POLICIES].join(", ")}`);
+  return overlap;
+}
+function normalizeScheduleBackfill(backfill) {
+  if (backfill === void 0)
+    return !1;
+  if (typeof backfill !== "boolean")
+    throw Error("options.backfill must be a boolean when provided");
+  return backfill;
+}
+function normalizeScheduleJitter(value, fieldName) {
+  if (typeof value !== "string" && typeof value !== "number")
+    throw Error(`${fieldName} must be a duration string or a number of milliseconds`);
+  let milliseconds;
+  try {
+    milliseconds = parseDuration(value);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw Error(`Invalid ${fieldName}: ${message}`, { cause: error });
+  }
+  const jitterMs = Math.ceil(milliseconds);
+  if (!Number.isSafeInteger(jitterMs) || jitterMs <= 0)
+    throw Error(`${fieldName} must resolve to a positive number of milliseconds`);
+  return jitterMs;
+}

package/dist/core/engine/validation/schedule.d.ts

@@ -1,15 +1,11 @@
-import type { ScheduleFilter, ScheduleOptions, ScheduleOverlapPolicy, ScheduleSpec, ScheduleState, ScheduleStatus } from '../../types.ts';
+import type { ScheduleFilter, ScheduleOverlapPolicy, ScheduleSpec, ScheduleState, ScheduleStatus } from '../../types.ts';
+export { normalizeScheduleOptions, SCHEDULE_OVERLAP_POLICIES } from './schedule-options.ts';
 export declare const SCHEDULE_STATUSES: Set<ScheduleStatus>;
-export declare const SCHEDULE_OVERLAP_POLICIES: Set<ScheduleOverlapPolicy>;
 export declare function isValidScheduleTimestamp(value: unknown): value is number;
 export declare function isValidScheduleStatus(value: unknown): value is ScheduleStatus;
 export declare function isValidScheduleOverlapPolicy(value: unknown): value is ScheduleOverlapPolicy;
 export declare function isValidScheduleIdentifier(value: unknown): value is string;
 export declare function coerceScheduleId(scheduleId: string, fieldName: string): string;
-export declare function normalizeScheduleOptions(options: ScheduleOptions | undefined): Required<Pick<ScheduleOptions, 'overlap' | 'backfill'>> & {
-    id?: string;
-    jitterMs?: number;
-};
 /**
  * A recurrence specification normalized into the discriminated cadence the
  * engine persists. Interval periods are resolved to whole milliseconds.
@@ -33,7 +29,6 @@ export declare function decodeScheduleIdentityFields(decoded: Record<string, unk
     cronExpression?: string;
     intervalMs?: number;
 }) | null;
-type ScheduleRuntimeFields = Pick<ScheduleState, 'backfill' | 'jitterMs' | 'createdAt' | 'updatedAt' | 'lastFireAt' | 'lastMissedFireAt' | 'nextFireAt' | 'currentWorkflowId' | 'missedFireCount' | 'queuedRuns'>;
+type ScheduleRuntimeFields = Pick<ScheduleState, 'description' | 'backfill' | 'jitterMs' | 'createdAt' | 'updatedAt' | 'lastFireAt' | 'lastMissedFireAt' | 'nextFireAt' | 'currentWorkflowId' | 'missedFireCount' | 'queuedRuns'>;
 export declare function decodeScheduleRuntimeFields(decoded: Record<string, unknown>, scheduleId: string): ScheduleRuntimeFields | null;
 export declare function decodeScheduleState(bytes: Uint8Array): ScheduleState | null;
-export {};