@lostgradient/weft 0.9.0 → 0.10.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/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-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';
@@ -239,6 +239,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,7 +70,9 @@ import {
   createQueuedInlineWorkflowStartHandler,
   createSecondInstanceDetectorResolver,
   drainQueuedInlineWorkflowStartsForEngine,
-  isActivityDefinition
+  isActivityDefinition,
+  shouldStartEngineScheduler,
+  validateEngineCreateBackgroundTaskOptions
 } from "./engine-runtime-helpers.js";
 import { EngineCreateNameMismatchError, EngineDisposedError } from "./errors.js";
 import { assertLeaseHeldForEngineWork, commitFencedEngineWrite } from "./fenced-write.js";
@@ -222,6 +224,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 +241,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]();
@@ -341,7 +344,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 +367,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();
   }
@@ -586,6 +589,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/internals.d.ts

@@ -186,13 +186,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>;

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

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

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

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

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

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

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

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