@lostgradient/weft 0.9.0 → 0.11.0

package/dist/core/engine/async-activity-records.js

@@ -0,0 +1,124 @@
+import { KEYS, encodeStorageKeyComponent } from "../../storage/interface.js";
+import { decode, encode } from "../codec.js";
+import { ActivityAsyncPendingEvent } from "../events.js";
+import { commitFencedEngineWrite } from "./fenced-write.js";
+const ASYNC_ACTIVITY_TOKEN_PREFIX = "async-act:v1";
+export const ASYNC_ACTIVITY_KEY_PREFIX = "async-act:v1:";
+export function asyncActivityWorkflowPrefix(workflowId) {
+  return `${ASYNC_ACTIVITY_KEY_PREFIX}${encodeStorageKeyComponent(workflowId)}:`;
+}
+function isPersistedAsyncActivity(value) {
+  if (typeof value !== "object" || value === null)
+    return !1;
+  const record = value;
+  return record.version === 1 && typeof record.token === "string" && typeof record.workflowId === "string" && typeof record.activityName === "string" && typeof record.operationId === "string" && typeof record.step === "number" && typeof record.attempt === "number" && typeof record.createdAt === "number";
+}
+function isPersistedOperationOutcome(value) {
+  if (typeof value !== "object" || value === null)
+    return !1;
+  const record = value;
+  if (record.status === "completed")
+    return "value" in record;
+  if (record.status === "failed")
+    return typeof record.error === "string";
+  return !1;
+}
+function isPersistedAsyncActivityResolution(value) {
+  if (typeof value !== "object" || value === null)
+    return !1;
+  const record = value;
+  return record.version === 1 && record.kind === "resolution" && typeof record.token === "string" && typeof record.workflowId === "string" && isPersistedOperationOutcome(record.outcome);
+}
+export function deriveAsyncActivityToken(workflowId, step, attempt) {
+  return `${ASYNC_ACTIVITY_TOKEN_PREFIX}:${workflowId}:${step}:${attempt}`;
+}
+function buildPersistPendingAsyncActivityOperation(pending) {
+  const record = {
+    version: 1,
+    token: pending.token,
+    workflowId: pending.workflowId,
+    activityName: pending.activityName,
+    operationId: pending.operationId,
+    step: pending.step,
+    attempt: pending.attempt,
+    createdAt: pending.createdAt
+  };
+  return {
+    type: "put",
+    key: KEYS.asyncActivity(pending.workflowId, pending.token),
+    value: encode(record)
+  };
+}
+export function buildAsyncActivityAcknowledgementOperations(pending, outcome) {
+  const record = {
+    version: 1,
+    kind: "resolution",
+    token: pending.token,
+    workflowId: pending.workflowId,
+    outcome
+  };
+  return [
+    { type: "delete", key: KEYS.asyncActivity(pending.workflowId, pending.token) },
+    {
+      type: "put",
+      key: KEYS.asyncActivityResolution(pending.workflowId, pending.token),
+      value: encode(record)
+    }
+  ];
+}
+export async function registerPendingAsyncActivity(internals, pending) {
+  const alreadyRegistered = internals.pendingAsyncActivities.has(pending.token);
+  internals.pendingAsyncActivities.set(pending.token, pending);
+  await commitFencedEngineWrite(internals, [buildPersistPendingAsyncActivityOperation(pending)], [], () => Error(`Async activity registration for token "${pending.token}" lost its precondition.`));
+  if (!alreadyRegistered)
+    internals.engine.dispatchEvent(new ActivityAsyncPendingEvent(pending.token, pending.operationId, pending.workflowId, pending.activityName, pending.attempt));
+}
+export async function recoverPendingAsyncActivities(internals) {
+  for await (const [, bytes] of internals.storage.scan(ASYNC_ACTIVITY_KEY_PREFIX)) {
+    const decoded = decode(bytes);
+    if (isPersistedAsyncActivity(decoded)) {
+      internals.pendingAsyncActivities.set(decoded.token, {
+        token: decoded.token,
+        workflowId: decoded.workflowId,
+        activityName: decoded.activityName,
+        operationId: decoded.operationId,
+        step: decoded.step,
+        attempt: decoded.attempt,
+        createdAt: decoded.createdAt
+      });
+      continue;
+    }
+    if (isPersistedAsyncActivityResolution(decoded))
+      queuePendingAsyncActivityResolution(internals, decoded.workflowId, {
+        token: decoded.token,
+        outcome: decoded.outcome,
+        timelineStatus: decoded.outcome.status,
+        timelineOutput: decoded.outcome.status === "completed" ? decoded.outcome.value : decoded.outcome.error
+      });
+  }
+}
+export function shouldBufferPendingAsyncActivityResolution(internals, workflowId) {
+  return internals.inlineStrategy !== null && !internals.inlineStrategy.hasGenerator(workflowId);
+}
+export function queuePendingAsyncActivityResolution(internals, workflowId, resolution) {
+  internals.pendingAsyncActivityResolutions ??= new Map;
+  const queued = internals.pendingAsyncActivityResolutions.get(workflowId) ?? [];
+  queued.push(resolution);
+  internals.pendingAsyncActivityResolutions.set(workflowId, queued);
+}
+export function takePendingAsyncActivityResolution(internals, workflowId, token) {
+  internals.pendingAsyncActivityResolutions ??= new Map;
+  const queued = internals.pendingAsyncActivityResolutions.get(workflowId);
+  if (queued === void 0)
+    return;
+  const index = queued.findIndex((resolution) => resolution.token === token);
+  if (index === -1)
+    return;
+  const resolution = queued[index];
+  if (resolution === void 0)
+    return;
+  queued.splice(index, 1);
+  if (queued.length === 0)
+    internals.pendingAsyncActivityResolutions.delete(workflowId);
+  return resolution;
+}

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

@@ -8,7 +8,7 @@ import {
 import { decode } from "../codec.js";
 import { buildIndexOperations } from "../search-attributes.js";
 import { buildWorkflowTagIndexOperations, normalizeWorkflowTags } from "../workflow-tags.js";
-import { asyncActivityWorkflowPrefix } from "./async-activity-completion.js";
+import { asyncActivityWorkflowPrefix } from "./async-activity-records.js";
 import { forgetCommittedCheckpointBytes } from "./checkpoint-commit-snapshots.js";
 import { commitFencedEngineWrite } from "./fenced-write.js";
 import { streamWorkflowStates } from "./listing.js";
@@ -192,6 +192,7 @@ function buildBaseWorkflowDeleteKeys(state) {
     KEYS.workflowHeaders(state.id),
     KEYS.terminalCleanupNeeded(state.id),
     KEYS.workflowConcurrencyHolder(state.id),
+    KEYS.scheduleRun(state.id),
     KEYS.workflowHasServices(state.id),
     KEYS.finalizerState(state.id),
     KEYS.teardownOwed(state.id),

package/dist/core/engine/callback-creators-core.js

@@ -76,6 +76,7 @@ export function createLifecycleCallbacks(engine) {
     swallowPromiseRejection: (promise) => swallowPromiseRejection(promise),
     enforceHistoryCircuitBreaker: (workflowId) => terminateWorkflow(getInternals(engine), workflowId, "timed-out", createTerminationCallbacks(engine), HISTORY_CIRCUIT_BREAKER_REASON),
     failWorkflowForUnavailableServices: (workflowId, error) => failWorkflow(getInternals(engine), workflowId, error, createTerminationCallbacks(engine), "system"),
+    failWorkflowForRecoveryHook: (workflowId, error) => failWorkflow(getInternals(engine), workflowId, error, createTerminationCallbacks(engine), "system"),
     failWorkflowForCheckpointDecodeError: (workflowId, error) => failWorkflow(getInternals(engine), workflowId, error, createTerminationCallbacks(engine), "system")
   };
 }

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

@@ -1,8 +1,7 @@
-import { AlertManager } from '../../alerting/alert-manager.ts';
 import type { Storage as WeftStorage } from '../../storage/interface.ts';
 import { ActivityWorkerDispatcher } from '../../workers/activity-worker-dispatcher.ts';
 import type { ComposedWorkflowInterceptor, Interceptor } from '../interceptor.ts';
-import { type AnyActivityDefinition, type AnyWorkflowDefinition, type EngineOptions, type RegisteredWorkflowDefinition } from '../types.ts';
+import { type AnyActivityDefinition, type AnyWorkflowDefinition, type RegisteredWorkflowDefinition } from '../types.ts';
 import type { WorkflowLogRecord } from '../types/workflow-log.ts';
 import type { EngineConstructorOptions, ExecutionStrategyBundle, RegistrationEntry, ResolvedOptions } from './engine-internal-types.ts';
 export type KnownWorkflowNames<TWorkflows extends object> = Extract<keyof TWorkflows, string>;
@@ -60,5 +59,4 @@ export declare function createExecutionStrategyBundle(parameters: {
     getLogSink?: () => ((record: WorkflowLogRecord) => void) | undefined;
 }): ExecutionStrategyBundle;
 export declare function createActivityWorkerDispatcher(activityExecution: EngineConstructorOptions['activityExecution']): ActivityWorkerDispatcher | null;
-export declare function createAlertManagerForEngine(engine: EventTarget, alerts: EngineOptions['alerts'] | undefined, getNow: () => number): AlertManager | null;
 export {};

package/dist/core/engine/construction.js

@@ -1,4 +1,3 @@
-import { AlertManager } from "../../alerting/alert-manager.js";
 import { CompressedStorage } from "../../storage/compressed-storage.js";
 import { MemoryStorage } from "../../storage/memory.js";
 import { ActivityWorkerDispatcher } from "../../workers/activity-worker-dispatcher.js";
@@ -16,7 +15,7 @@ import {
   DEFAULT_WORKER_TURN_TIMEOUT_MS,
   MIN_WORKER_PROTOCOL_MESSAGE_BYTES
 } from "../worker-protocol.js";
-import { resolveOwnershipFields } from "./ownership-options.js";
+import { resolveBackgroundTaskMode, resolveOwnershipFields } from "./ownership-options.js";
 import {
   normalizeHistoryPolicy,
   normalizePayloadSizePolicy,
@@ -122,6 +121,7 @@ export function resolveEngineOptions(storage, options, getNow) {
     getNow,
     resolveWorkflowServices: options?.resolveWorkflowServices ?? null,
     onLog: options?.onLog ?? null,
+    backgroundTaskMode: resolveBackgroundTaskMode(options),
     ...resolveBooleanDefaults(options),
     ...resolveNumericDefaults(options),
     ...resolveRetentionFields(options),
@@ -235,6 +235,3 @@ export function createActivityWorkerDispatcher(activityExecution) {
     smol: activityExecution.smol ?? !1
   }));
 }
-export function createAlertManagerForEngine(engine, alerts, getNow) {
-  return alerts ? new AlertManager(engine, alerts, getNow) : null;
-}

package/dist/core/engine/deferred-consume-envelope.d.ts

@@ -25,6 +25,7 @@
  * nested coordinator surfaces up to its parent.
  */
 declare const DEFERRED_CONSUME_BRAND: unique symbol;
+declare const KEYED_RACE_RESULT_BRAND: unique symbol;
 /**
  * A branch result whose real value is produced by a single deferred consume that
  * only the winning coordinator performs.
@@ -34,6 +35,12 @@ export type DeferredConsumeEnvelope = {
     /** Perform the single destructive consume and return the consumed payload. */
     readonly finalize: () => Promise<unknown>;
 };
+type KeyedRaceResultEnvelope = {
+    readonly [KEYED_RACE_RESULT_BRAND]: true;
+    readonly key: string;
+    readonly value: unknown;
+};
+export declare function createKeyedRaceResultEnvelope(key: string, value: unknown): KeyedRaceResultEnvelope;
 /** Wrap a deferred consume into a branded envelope. */
 export declare function createDeferredConsumeEnvelope(finalize: () => Promise<unknown>): DeferredConsumeEnvelope;
 /** Detect an envelope by its brand symbol only (never structurally). */
@@ -43,7 +50,9 @@ export declare function isDeferredConsumeEnvelope(value: unknown): value is Defe
  * cache. A winning `wait-signal` branch surfaces a {@link DeferredConsumeEnvelope}
  * whose `finalize()` performs the single consume; a nested `ctx.all` branch
  * surfaces an ARRAY that may hold envelopes at arbitrary positions, so arrays are
- * walked and each element finalized. Any other value passes through untouched.
+ * walked and each element finalized. A nested `ctx.raceKeyed()` winner is walked
+ * through its value while retaining its key. Any other value passes through
+ * untouched.
  *
  * This runs only on the WINNING path (race winner, or every branch of a settled
  * `ctx.all`), so finalizing here is exactly the linearization point of "this

package/dist/core/engine/deferred-consume-envelope.js

@@ -1,4 +1,10 @@
-const DEFERRED_CONSUME_BRAND = Symbol("weft.deferredConsume");
+const DEFERRED_CONSUME_BRAND = Symbol("weft.deferredConsume"), KEYED_RACE_RESULT_BRAND = Symbol("weft.keyedRaceResult");
+export function createKeyedRaceResultEnvelope(key, value) {
+  return { [KEYED_RACE_RESULT_BRAND]: !0, key, value };
+}
+function isKeyedRaceResultEnvelope(value) {
+  return typeof value === "object" && value !== null && value[KEYED_RACE_RESULT_BRAND] === !0;
+}
 export function createDeferredConsumeEnvelope(finalize) {
   return { [DEFERRED_CONSUME_BRAND]: !0, finalize };
 }
@@ -10,5 +16,7 @@ export async function finalizeAndUnwrap(value) {
     return value.finalize();
   if (Array.isArray(value))
     return Promise.all(value.map((element) => finalizeAndUnwrap(element)));
+  if (isKeyedRaceResultEnvelope(value))
+    return { key: value.key, value: await finalizeAndUnwrap(value.value) };
   return value;
 }

package/dist/core/engine/disposal.js

@@ -1,6 +1,7 @@
 import { disposeEngineCleanupInterval } from "./engine-runtime-helpers.js";
 import { EngineDisposedError } from "./errors.js";
 import { disposeQueuedInlineWorkflowStarts } from "./inline-launch-queue.js";
+import { rejectAllSleepTimerAcknowledgements } from "./sleep-timer-acknowledgements.js";
 export function disposeEngine(internals) {
   internals.disposed = !0;
   internals.alertManager?.[Symbol.dispose]();
@@ -30,6 +31,7 @@ export function disposeEngine(internals) {
   internals.handleCache.clear();
   for (const waiter of internals.resultResolvers.values())
     waiter.reject(new EngineDisposedError);
+  rejectAllSleepTimerAcknowledgements(internals, new EngineDisposedError);
   internals.resultResolvers.clear();
   internals.updateWaiters.clear();
   internals.updateWaitersByWorkflow.clear();
@@ -46,6 +48,8 @@ export function disposeEngine(internals) {
   internals.pendingWebhooks.clear();
   internals.sleepResolvers.clear();
   internals.sleepResolversByWorkflow.clear();
+  internals.sleepTimerAcknowledgementWaiters.clear();
+  internals.durableInlineOperations.clear();
   internals.sleepTimersFiredWithoutResolver.clear();
   internals.checkpoints.clear();
   internals.pendingExecutionStateOwnerId = void 0;

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

@@ -24,6 +24,7 @@ export interface RegistrationEntry {
 export interface ResolvedOptions {
     storage: WeftStorage;
     development: boolean;
+    backgroundTaskMode: 'automatic' | 'manual';
     checkpointHistory: number;
     checkpointSizeWarningThreshold: number;
     maxNestingDepth: number;

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

@@ -15,6 +15,8 @@ export type EngineCleanupIntervalDisposalTracker = {
     testToken: symbol | undefined;
 };
 export declare const engineCleanupIntervalFinalizer: FinalizationRegistry<EngineCleanupIntervalDisposalTracker>;
+/** Test-only hook for the finalizer callback's synchronous warning gate. */
+export declare function finalizeEngineCleanupIntervalTrackerForTesting(tracker: EngineCleanupIntervalDisposalTracker): void;
 export declare function shouldEmitEngineLeakWarning(): boolean;
 /** Test-only override for the engine leak-warning environment gate. */
 export declare function setEngineLeakWarningOverrideForTesting(value: boolean | undefined): void;

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

@@ -1,6 +1,6 @@
 let engineLeakWarningOverrideForTesting, engineLeakCollectionCountForTesting = 0, nextEngineLeakWarningTokenForTesting;
 const engineLeakWarningTokensForTesting = new Set;
-export const engineCleanupIntervalFinalizer = new FinalizationRegistry((tracker) => {
+function finalizeEngineCleanupIntervalTracker(tracker) {
   engineLeakCollectionCountForTesting++;
   if (tracker.cleanupInterval !== null) {
     clearInterval(tracker.cleanupInterval);
@@ -15,7 +15,13 @@ export const engineCleanupIntervalFinalizer = new FinalizationRegistry((tracker)
       engineLeakWarningTokensForTesting.add(tracker.testToken);
     process.emitWarning("WeftEngineLeakWarning: A Weft Engine was garbage-collected without calling [Symbol.dispose](). Use `using`, `await using`, or call engine[Symbol.dispose]() to clear background timers and release runtime resources.");
   }
+}
+export const engineCleanupIntervalFinalizer = new FinalizationRegistry((tracker) => {
+  finalizeEngineCleanupIntervalTracker(tracker);
 });
+export function finalizeEngineCleanupIntervalTrackerForTesting(tracker) {
+  finalizeEngineCleanupIntervalTracker(tracker);
+}
 export function shouldEmitEngineLeakWarning() {
   if (engineLeakWarningOverrideForTesting !== void 0)
     return engineLeakWarningOverrideForTesting;

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

@@ -4,6 +4,13 @@ import type { Engine } from './index.ts';
 import { type EngineInternals } from './internals.ts';
 import type { SecondInstanceDetector } from './second-instance-detector.ts';
 export declare function isActivityDefinition(value: unknown): value is AnyActivityDefinition;
+type EngineCreateBackgroundTaskOptions = {
+    backgroundTasks?: 'automatic' | 'manual' | undefined;
+    recover?: boolean | undefined;
+    startScheduler?: boolean | undefined;
+};
+export declare function validateEngineCreateBackgroundTaskOptions(options: EngineCreateBackgroundTaskOptions): void;
+export declare function shouldStartEngineScheduler(options: EngineCreateBackgroundTaskOptions, backgroundTaskMode: 'automatic' | 'manual'): boolean;
 export declare function createQueuedInlineWorkflowStartHandler<TWorkflows extends object, TActivities extends object>(weakEngine: WeakRef<Engine<TWorkflows, TActivities>>, channel: MessageChannel): () => void;
 /**
  * Drain pending inline launches for `engine` before teardown. Built with the
@@ -23,3 +30,4 @@ export declare function createCleanupIntervalTick<TWorkflows extends object, TAc
  */
 export declare function createSecondInstanceDetectorResolver<TWorkflows extends object, TActivities extends object>(weakEngine: WeakRef<Engine<TWorkflows, TActivities>>): () => SecondInstanceDetector | null;
 export declare function disposeEngineCleanupInterval(internals: EngineInternals): void;
+export {};

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

@@ -12,6 +12,15 @@ import { swallowPromiseRejection } from "./strategy-helpers.js";
 export function isActivityDefinition(value) {
   return typeof value === "function" && typeof value.name === "string" && "execute" in value && typeof value.execute === "function";
 }
+export function validateEngineCreateBackgroundTaskOptions(options) {
+  if (options.backgroundTasks === "manual" && options.startScheduler === !0)
+    throw Error('startScheduler cannot be true when backgroundTasks is "manual"');
+}
+export function shouldStartEngineScheduler(options, backgroundTaskMode) {
+  if (backgroundTaskMode === "manual")
+    return !1;
+  return options.startScheduler ?? options.recover !== !1;
+}
 function inlineLaunchQueueCallbacksForEngine(engine) {
   const lifecycleCallbacks = createLifecycleCallbacks(engine);
   return {

package/dist/core/engine/errors.js

@@ -43,7 +43,7 @@ export class WorkflowTypeNotRegisteredForRecoveryError extends WeftError {
     const missingWorkflowCount = parameters.missingWorkflows.length, missingTypes = [
       ...new Set(parameters.missingWorkflows.map((workflow) => workflow.type))
     ].toSorted(), registeredTypes = [...parameters.registeredTypes].toSorted(), summarizedTypes = summarizeMissingWorkflowTypes(missingTypes);
-    super("WorkflowTypeNotRegisteredForRecoveryError", `Cannot recover ${missingWorkflowCount} running workflow(s): workflow type(s) not registered: ${summarizedTypes}. Register the missing workflow types before calling \`recoverAll()\`, or pass ` + "`{ acknowledgeUnknownWorkflowTypes: true }` (dangerous \u2014 see migration docs).");
+    super("WorkflowTypeNotRegisteredForRecoveryError", `Cannot recover ${missingWorkflowCount} running workflow(s): workflow type(s) not registered: ${summarizedTypes}. Register the missing workflow types before calling \`recoverAll()\`, or pass ` + "`{ acknowledgeUnknownWorkflowTypes: true }` (dangerous \u2014 see " + "https://github.com/stevekinney/weft/blob/main/documentation/guides/recovery-and-deploys.md#acknowledging-drift-acknowledgeunknownworkflowtypes).");
     this.registeredTypes = registeredTypes;
     this.missingTypes = missingTypes;
     this.missingWorkflowSamples = parameters.missingWorkflows.slice(0, MISSING_WORKFLOW_SAMPLE_LIMIT).map((workflow) => ({ ...workflow }));

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

@@ -21,12 +21,12 @@ import { ScheduleHandle } from './schedule-handle.ts';
 import { type WorkflowFeedListener, type WorkflowFeedRecord, type WorkflowFeedSelector } from './workflow-feed.ts';
 export { ActivityReconciliationCapabilityError, ActivityReconciliationConflictError, ActivityReconciliationIndeterminateError, } from './activity-reconciliation.ts';
 export { AsyncActivityTokenNotFoundError } from './async-activity-completion.ts';
-export type { PendingAsyncActivity } from './async-activity-completion.ts';
+export type { PendingAsyncActivity } from './async-activity-records.ts';
 export type { PendingTimelineEntry, RegistrationEntry, ResolvedOptions, TrackedWaiterKeys, WorkflowResultWaiter, } from './engine-internal-types.ts';
 export { ActivityResolutionError, BulkDeleteRequiresTerminalWorkflowsError, BulkOperationConfirmationError, EngineCreateNameMismatchError, EngineDisposedError, IdempotencyKeyPurgedError, PersistedDataIncompatibleError, StartOrSignalConflictError, WorkflowAlreadyExistsError, WorkflowConcurrencyLimitExceededError, WorkflowNotFoundError, WorkflowNotRegisteredError, WorkflowSuspendNotSupportedError, WorkflowTeardownPendingError, WorkflowTypeNotRegisteredForRecoveryError, } from './errors.ts';
 export { HANDLE_RESULT_PROMISE, WorkflowHandle } from './handles.ts';
 export { EngineLeaseAcquisitionTimeoutError, EngineLeaseCorruptedError, EngineLeaseNotHeldError, } from './lease-errors.ts';
-export type { RecoverAllOptions } from './lifecycle.ts';
+export type { RecoverAllOptions, RecoveredWorkflowInfo } from './lifecycle.ts';
 export { ScheduleHandle } from './schedule-handle.ts';
 export type { WorkflowFeedListener, WorkflowFeedRecord, WorkflowFeedSelector, } from './workflow-feed.ts';
 export type { EngineCreateOptions } from './engine-create-types.ts';
@@ -220,9 +220,12 @@ export declare class Engine<TWorkflows extends object = DefaultWorkflowRegistry,
      * (signal-with-start). With an absent target, the workflow record and the
      * first signal commit in one batch and the freshly-launched run consumes the
      * signal on its first drive. A non-terminal target (running, pending, or
-     * suspended) is signalled through the normal signal path; a terminal target
-     * throws {@link StartOrSignalConflictError} unless
-     * `options.onTerminalConflict: 'start-new'` is supplied with an explicit
+     * suspended) is signalled through a workflow-serialized signal path. If
+     * terminal completion wins that handoff, the target is treated as terminal:
+     * the default path throws {@link StartOrSignalConflictError}, while
+     * `options.onTerminalConflict: 'start-new'` transfers the signal to the
+     * replacement run. A terminal target throws {@link StartOrSignalConflictError}
+     * unless `options.onTerminalConflict: 'start-new'` is supplied with an explicit
      * workflow id and deterministic `signal.signalId`.
      *
      * Concurrent callers converge on one workflow and one delivered signal. Pass
@@ -239,6 +242,16 @@ export declare class Engine<TWorkflows extends object = DefaultWorkflowRegistry,
     list<const TAttributeKeys extends readonly AttributeFilterKey[] = readonly AttributeFilterKey[]>(filter?: TypedListFilter<TAttributeKeys>, options?: ListOptions): Promise<PaginatedResult<WorkflowSummary>>;
     aggregate(filter: ListFilter | undefined, options: AggregateOptions): Promise<AggregateResult>;
     getRetentionOverview(): RetentionOverview;
+    /**
+     * Run one host-driven maintenance cycle. This fires due durable timers,
+     * deletes expired update responses, applies configured retention, and
+     * re-evaluates alert rules without relying on process-local intervals.
+     *
+     * Use with `backgroundTasks: 'manual'` from a serverless alarm, Cron trigger,
+     * or another externally scheduled wake-up. Concurrent calls are safe, but a
+     * host should await each cycle before scheduling another.
+     */
+    runMaintenance(now?: number): Promise<void>;
     purge(filter?: ListFilter): Promise<PurgeResult>;
     cancelAll(filter: ListFilter, options: BulkOperationDryRunOptions): Promise<BulkOperationDryRunResult>;
     cancelAll(filter: ListFilter, options?: BulkOperationCommitOptions): Promise<BulkCancelResult>;

package/dist/core/engine/index.js

@@ -1,3 +1,4 @@
+import { AlertManager } from "../../alerting/alert-manager.js";
 import {
   KEYS,
   requireStorageCapability
@@ -19,9 +20,9 @@ import {
 } from "./aggregate.js";
 import {
   completeAsyncActivity as completeAsyncActivityFromInternals,
-  failAsyncActivity as failAsyncActivityFromInternals,
-  recoverPendingAsyncActivities
+  failAsyncActivity as failAsyncActivityFromInternals
 } from "./async-activity-completion.js";
+import { recoverPendingAsyncActivities } from "./async-activity-records.js";
 import { broadcast as broadcastFromInternals } from "./broadcast.js";
 import {
   cancelAll as cancelAllWorkflows,
@@ -52,7 +53,6 @@ import {
 import {
   copyWorkflowDefinition,
   createActivityWorkerDispatcher,
-  createAlertManagerForEngine,
   createExecutionStrategyBundle,
   definitionEntries,
   resolveEngineInterceptors,
@@ -70,9 +70,15 @@ import {
   createQueuedInlineWorkflowStartHandler,
   createSecondInstanceDetectorResolver,
   drainQueuedInlineWorkflowStartsForEngine,
-  isActivityDefinition
+  isActivityDefinition,
+  shouldStartEngineScheduler,
+  validateEngineCreateBackgroundTaskOptions
 } from "./engine-runtime-helpers.js";
-import { EngineCreateNameMismatchError, EngineDisposedError } from "./errors.js";
+import {
+  EngineCreateNameMismatchError,
+  EngineDisposedError,
+  StartOrSignalConflictError
+} from "./errors.js";
 import { assertLeaseHeldForEngineWork, commitFencedEngineWrite } from "./fenced-write.js";
 import { recordFinalizerState } from "./finalizer-state.js";
 import {
@@ -143,7 +149,11 @@ import {
   createSecondInstanceDetector
 } from "./second-instance-detector.js";
 import { signal as signalWorkflow } from "./signals.js";
-import { loadScheduleState, loadWorkflowState } from "./storage-io.js";
+import {
+  loadScheduleState,
+  loadWorkflowState,
+  runSerializedWorkflowStateWrite
+} from "./storage-io.js";
 import {
   feedOperationResult,
   getComposedWorkflowInterceptor,
@@ -161,6 +171,7 @@ import {
   submitCoordinatedUpdate as submitCoordinatedUpdateFromInternals,
   update as updateFromInternals
 } from "./updates.js";
+import { isTerminalWorkflowStatus } from "./validation.js";
 import { coerceScheduleId } from "./validation/schedule.js";
 import {
   replayWorkflowFeed,
@@ -222,6 +233,7 @@ function scheduleDefinitionFromInternals(internals, definition) {
 
 export class Engine extends EventTarget {
   static async create(options) {
+    validateEngineCreateBackgroundTaskOptions(options);
     const engine = new Engine(options);
     try {
       await assertCompatiblePersistedDataVersion(getInternals(engine).storage);
@@ -238,7 +250,7 @@ export class Engine extends EventTarget {
       await engine.#acquireLeaseIfConfigured();
       if (options.recover !== !1)
         await engine.recoverAll(options.acknowledgeUnknownWorkflowTypes !== void 0 ? { acknowledgeUnknownWorkflowTypes: options.acknowledgeUnknownWorkflowTypes } : {});
-      if (options.startScheduler ?? options.recover !== !1)
+      if (shouldStartEngineScheduler(options, getInternals(engine).options.backgroundTaskMode))
         getInternals(engine).scheduler.start();
     } catch (error) {
       await engine[Symbol.asyncDispose]();
@@ -277,6 +289,8 @@ export class Engine extends EventTarget {
     getInternals(this).updateWaitersByWorkflow = new Map;
     getInternals(this).sleepResolvers = new Map;
     getInternals(this).sleepResolversByWorkflow = new Map;
+    getInternals(this).sleepTimerAcknowledgementWaiters = new Map;
+    getInternals(this).durableInlineOperations = new Map;
     getInternals(this).sleepTimersFiredWithoutResolver = new Map;
     getInternals(this).interceptors = resolveEngineInterceptors(options);
     getInternals(this).composedWorkflowInterceptor = void 0;
@@ -341,7 +355,7 @@ export class Engine extends EventTarget {
       cleanupInterval: null,
       secondInstanceDetectionInterval: null,
       testToken: consumeNextEngineLeakWarningTokenForTesting()
-    }, cleanupInterval = setInterval(createCleanupIntervalTick(weakEngine, cleanupIntervalDisposalTracker), 60000);
+    }, cleanupInterval = resolvedOptions.backgroundTaskMode === "automatic" ? setInterval(createCleanupIntervalTick(weakEngine, cleanupIntervalDisposalTracker), 60000) : null;
     cleanupIntervalDisposalTracker.cleanupInterval = cleanupInterval;
     getInternals(this).cleanupInterval = cleanupInterval;
     getInternals(this).cleanupIntervalDisposalTracker = cleanupIntervalDisposalTracker;
@@ -364,7 +378,7 @@ export class Engine extends EventTarget {
     getInternals(this).workflowVisibilityWatermarkExpiresAt = void 0;
     getInternals(this).activityWorkerDispatcher = createActivityWorkerDispatcher(options?.activityExecution);
     getInternals(this).strategy.onMessage(this.#handleStrategyMessage.bind(this));
-    getInternals(this).alertManager = createAlertManagerForEngine(this, options?.alerts, getNow);
+    getInternals(this).alertManager = options?.alerts ? new AlertManager(this, options.alerts, getNow, resolvedOptions.backgroundTaskMode === "automatic") : null;
     this.#ensureRetentionSweepInterval();
     this.#startSecondInstanceDetection();
   }
@@ -565,7 +579,12 @@ export class Engine extends EventTarget {
   #createStartOrSignalCallbacks() {
     return {
       ...this.#createLifecycleCallbacks(),
-      signalExistingWorkflow: (workflowId, signalName, payload, signalId) => this.signal(workflowId, signalName, payload, { signalId })
+      signalExistingWorkflow: (workflowId, signalName, payload, signalId) => runSerializedWorkflowStateWrite(getInternals(this), workflowId, async () => {
+        const state = await loadWorkflowState(getInternals(this), workflowId);
+        if (state && isTerminalWorkflowStatus(state.status))
+          throw new StartOrSignalConflictError(workflowId, state.status);
+        await this.signal(workflowId, signalName, payload, { signalId });
+      })
     };
   }
   getHandle(workflowId) {
@@ -586,6 +605,18 @@ export class Engine extends EventTarget {
   getRetentionOverview() {
     return getRetentionOverviewSnapshot(getInternals(this), (type) => resolveWorkflowTypeRetention(getInternals(this), type));
   }
+  async runMaintenance(now = getInternals(this).options.getNow()) {
+    const internals = getInternals(this);
+    await internals.scheduler.tick(now);
+    try {
+      await internals.updateCoordinator.cleanupExpiredResponses();
+    } catch (error) {
+      this.#createTerminationCallbacks().handleCleanupError("cleanupExpiredResponses", error);
+    }
+    if (this.#hasConfiguredRetention())
+      await this.#runRetentionSweep();
+    internals.alertManager?.tick();
+  }
   async purge(filter) {
     return purgeWorkflows(getInternals(this), filter, (workflowId) => cleanupWaitersFromTermination(getInternals(this), workflowId, this.#createTerminationCallbacks()));
   }

package/dist/core/engine/inline-parking.js

@@ -2,6 +2,10 @@ import { hasExposedAccessors, hasUpdateHandlers } from "../context/context-prese
 import {
   resumeWorkflowFromStorage as resumeWorkflowFromStorageFromLifecycle
 } from "./lifecycle.js";
+import {
+  recordDurableInlineOperation,
+  rejectSleepTimerAcknowledgements
+} from "./sleep-timer-acknowledgements.js";
 import {
   completeWorkflow as completeWorkflowFromTermination,
   failWorkflow as failWorkflowFromTermination
@@ -53,7 +57,7 @@ export async function getParkedWorkflowResumeDisposition(internals, workflowId,
     return "corrupt";
   return "resumable";
 }
-export async function handleStrategyMessage(internals, message, callbacks) {
+async function dispatchStrategyMessage(internals, message, callbacks) {
   switch (message.type) {
     case "completed":
       await completeWorkflowFromTermination(internals, message.workflowId, message.result, callbacks.createTerminationCallbacks());
@@ -68,6 +72,7 @@ export async function handleStrategyMessage(internals, message, callbacks) {
     case "checkpoint": {
       const operation = callbacks.translateOperationRequest(message.operationRequest);
       await callbacks.persistCheckpoint(message.workflowId, operation, message.checkpoint);
+      recordDurableInlineOperation(internals, message.workflowId, operation);
       callbacks.validateDevelopmentCheckpoint(message.workflowId);
       if (await callbacks.evaluateConstraints(message.workflowId))
         break;
@@ -85,3 +90,11 @@ export async function handleStrategyMessage(internals, message, callbacks) {
     }
   }
 }
+export async function handleStrategyMessage(internals, message, callbacks) {
+  try {
+    await dispatchStrategyMessage(internals, message, callbacks);
+  } catch (error) {
+    rejectSleepTimerAcknowledgements(internals, message.workflowId, error);
+    throw error;
+  }
+}

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

@@ -22,6 +22,7 @@ import type { AlertManager } from '../../alerting/alert-manager.ts';
 import type { Storage as WeftStorage } from '../../storage/interface.ts';
 import type { ActivityWorkerDispatcher } from '../../workers/activity-worker-dispatcher.ts';
 import type { ActivityRegistry } from '../activity-registry.ts';
+import type { ContextOperationRequest } from '../context.ts';
 import type { EventHeadRecord } from '../event-log.ts';
 import type { ExecutionStrategy } from '../execution-strategy.ts';
 import type { InlineExecutionStrategy } from '../inline-execution-strategy.ts';
@@ -39,6 +40,17 @@ import type { WorkflowFeedListener } from './index.ts';
 import type { LeaseManager } from './lease-manager.ts';
 import type { ScheduleHandleEngine } from './schedule-handle.ts';
 import type { SecondInstanceDetector } from './second-instance-detector.ts';
+export type SleepTimerAcknowledgementWaiter = {
+    fireAt: number;
+    operationId: string;
+    reject: (error: Error) => void;
+    resolve: () => void;
+};
+export type DurableInlineOperation = {
+    operationId: string;
+    scheduledFireAt?: number;
+    type: ContextOperationRequest['type'];
+};
 type EngineRuntime = WorkflowHandleEngine & ScheduleHandleEngine & {
     start(type: string, input: unknown, options?: StartWorkflowOptions): Promise<WorkflowHandle>;
 };
@@ -102,6 +114,15 @@ export interface EngineInternals {
         fireAt: number;
     }>;
     sleepResolversByWorkflow: Map<string, Set<string>>;
+    /**
+     * Fired sleep timers awaiting proof that the awakened inline workflow reached
+     * its next durable checkpoint or terminal state. External schedulers must not
+     * delete a timer before these waiters settle, or a Service Worker eviction can
+     * lose the only durable wake-up between resolver settlement and checkpointing.
+     */
+    sleepTimerAcknowledgementWaiters: Map<string, Set<SleepTimerAcknowledgementWaiter>>;
+    /** Most recently persisted inline operation, used to reject stale sleep-timer callbacks. */
+    durableInlineOperations: Map<string, DurableInlineOperation>;
     /**
      * Per-workflow maps of `operationId` → fired timer `fireAt` for sleep timers
      * the scheduler tick fired before the resolver was registered. Keyed by
@@ -186,13 +207,13 @@ export interface EngineInternals {
      * by their durable task token. Mirrored to storage (`KEYS.asyncActivity`) and
      * reloaded by `recoverAll()`. See `async-activity-completion.ts`.
      */
-    pendingAsyncActivities: Map<string, import('./async-activity-completion.ts').PendingAsyncActivity>;
+    pendingAsyncActivities: Map<string, import('./async-activity-records.ts').PendingAsyncActivity>;
     /**
      * Completed or failed async-activity tokens that were consumed before inline
      * recovery adopted the workflow generator. Replay drains these by workflow id
      * when it reaches the same deterministic async-activity token again.
      */
-    pendingAsyncActivityResolutions: Map<string, import('./async-activity-completion.ts').PendingAsyncActivityResolution[]>;
+    pendingAsyncActivityResolutions: Map<string, import('./async-activity-records.ts').PendingAsyncActivityResolution[]>;
     pendingStarts: Set<string>;
     pendingScheduleCreations: Set<string>;
     workflowsNeedingTerminalCleanup: Set<string>;