@lostgradient/weft 0.8.0 → 0.10.0

package/dist/core/engine/async-activity-records.d.ts

@@ -0,0 +1,106 @@
+/**
+ * Durable record layer for out-of-band ("async") activity completion.
+ *
+ * Two record shapes share the `async-act:v1:` keyspace, discriminated by their
+ * decode guards (never by key shape):
+ *
+ * - **Pending token records** ({@link KEYS.asyncActivity}): an activity that
+ *   deferred via `ctx.completeAsync()` and is awaiting an external completion.
+ * - **Resolution records** ({@link KEYS.asyncActivityResolution}): an
+ *   acknowledged completion or failure whose resumed-workflow checkpoint has
+ *   not committed yet. Written atomically with the token-record delete so the
+ *   acknowledgement is durable before the caller learns it succeeded.
+ *
+ * The completion orchestration (park, consume, deliver, resume) lives in
+ * `async-activity-completion.ts`; this module owns the persisted shapes, the
+ * key derivations, and the in-memory resolution queue that recovery drains.
+ */
+import { type BatchOperation } from '../../storage/interface.ts';
+import type { OperationOutcome } from '../types.ts';
+import type { EngineInternals } from './internals.ts';
+/**
+ * Storage-key prefix for durable async-activity records. Matches the base of
+ * {@link KEYS.asyncActivity}; the full key appends `<workflowId>:<token>` (and
+ * `:resolution` for resolution records). The trailing colon (absent from the
+ * token prefix) scopes the global recovery scan to record keys only.
+ */
+export declare const ASYNC_ACTIVITY_KEY_PREFIX = "async-act:v1:";
+/**
+ * Per-workflow prefix for all async-activity storage keys — pending token
+ * records AND resolution records. Used by cleanup and purge paths that need to
+ * sweep every async-activity record for a workflow without enumerating
+ * individual tokens.
+ */
+export declare function asyncActivityWorkflowPrefix(workflowId: string): string;
+/**
+ * In-memory record of an activity that deferred to out-of-band completion and
+ * is awaiting `completeAsyncActivity` / `failAsyncActivity`.
+ */
+export type PendingAsyncActivity = {
+    readonly token: string;
+    readonly workflowId: string;
+    readonly activityName: string;
+    readonly operationId: string;
+    readonly step: number;
+    readonly attempt: number;
+    readonly createdAt: number;
+};
+/**
+ * In-memory form of an acknowledged outcome awaiting delivery into the workflow
+ * generator. `originalReason` (the raw thrown value on the failure path) exists
+ * only within the acknowledging process — it is not persisted, so a resolution
+ * reloaded by recovery reconstructs the error from the recorded outcome.
+ */
+export type PendingAsyncActivityResolution = {
+    readonly token: string;
+    readonly outcome: OperationOutcome;
+    readonly originalReason?: {
+        value: unknown;
+    };
+    readonly timelineStatus: 'completed' | 'failed';
+    readonly timelineOutput: unknown;
+};
+/**
+ * Derive the durable, deterministic task token for an async activity.
+ *
+ * The token is anchored to the workflow id, the activity state key, and the
+ * dispatch attempt — all of which are stable across replay — so a workflow that
+ * crashes while parked on an async activity mints the identical token after
+ * recovery. Plain `ctx.run()` uses the workflow step as the state key.
+ * `operationId` is deliberately excluded because it is regenerated on every
+ * yield and would change on replay.
+ */
+export declare function deriveAsyncActivityToken(workflowId: string, step: number | string, attempt: number): string;
+/**
+ * Build the acknowledgement batch for a consumed token: delete the pending
+ * token record and persist the resolution record carrying `outcome`, in one
+ * batch, so the acknowledgement is durable before the caller learns it
+ * succeeded.
+ */
+export declare function buildAsyncActivityAcknowledgementOperations(pending: PendingAsyncActivity, outcome: OperationOutcome): BatchOperation[];
+/**
+ * Register a deferred activity: record it in memory and durably, then announce
+ * the token via {@link ActivityAsyncPendingEvent}. Idempotent on `token`: if the
+ * token is already registered (e.g. because `recoverPendingAsyncActivities` loaded
+ * it before the workflow replayed and re-deferred), the durable record is
+ * refreshed but the event is NOT re-emitted, preventing duplicate side-effects
+ * (e.g. re-sending a webhook notification) on replay.
+ */
+export declare function registerPendingAsyncActivity(internals: EngineInternals, pending: PendingAsyncActivity): Promise<void>;
+/**
+ * Reload async-activity records from storage into memory. Called by
+ * `recoverAll()` so a token minted before a crash is resolvable again — even
+ * before the recovered workflow has replayed far enough to re-register it —
+ * and so an acknowledged-but-not-yet-checkpointed resolution is redelivered
+ * when replay re-parks on the same deterministic token.
+ */
+export declare function recoverPendingAsyncActivities(internals: EngineInternals): Promise<void>;
+/**
+ * True when a resolution cannot be delivered yet because inline replay has not
+ * adopted the workflow generator (the post-recovery window).
+ */
+export declare function shouldBufferPendingAsyncActivityResolution(internals: EngineInternals, workflowId: string): boolean;
+/** Queue a resolution for delivery when replay reaches its token again. */
+export declare function queuePendingAsyncActivityResolution(internals: EngineInternals, workflowId: string, resolution: PendingAsyncActivityResolution): void;
+/** Take the queued resolution for `token`, if one is waiting. */
+export declare function takePendingAsyncActivityResolution(internals: EngineInternals, workflowId: string, token: string): PendingAsyncActivityResolution | undefined;

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/bulk-operations.js

@@ -62,20 +62,13 @@ async function runBulkCancellation(internals, filter, options = {}) {
   const workflowIdsToCancel = preparation.workflowIds, bulkConcurrency = resolveBulkOperationConcurrency(options);
   let cancelled = 0;
   const errors = [], cancellationResults = await runBulkWorkflowPool(workflowIdsToCancel, bulkConcurrency, async (workflowId) => {
-    try {
-      await internals.engine.cancel(workflowId);
-      if ((await loadWorkflowState(internals, workflowId))?.status === "cancelled")
-        return { status: "cancelled" };
-      return {
-        status: "failed",
-        error: { id: workflowId, error: "Workflow no longer cancellable" }
-      };
-    } catch (error) {
-      return {
-        status: "failed",
-        error: toBulkOperationError(internals, workflowId, error)
-      };
-    }
+    await internals.engine.cancel(workflowId);
+    if ((await loadWorkflowState(internals, workflowId))?.status === "cancelled")
+      return { status: "cancelled" };
+    return {
+      status: "failed",
+      error: { id: workflowId, error: "Workflow no longer cancellable" }
+    };
   });
   for (const cancellationResult of cancellationResults) {
     if (cancellationResult.status === "rejected") {
@@ -107,27 +100,15 @@ async function runBulkFailedWorkflowRetry(internals, filter, options = {}) {
   const bulkConcurrency = resolveBulkOperationConcurrency(options);
   let retried = 0;
   const errors = [], retryResults = await runBulkWorkflowPool(preparation.workflowIds, bulkConcurrency, async (workflowId) => {
-    try {
-      await retryFailedWorkflow(internals, workflowId);
-      return { status: "retried" };
-    } catch (error) {
-      return {
-        status: "failed",
-        error: toBulkOperationError(internals, workflowId, error)
-      };
-    }
+    await retryFailedWorkflow(internals, workflowId);
+    return { status: "retried" };
   });
   for (const retryResult of retryResults) {
     if (retryResult.status === "rejected") {
       errors.push(toBulkOperationError(internals, retryResult.item, retryResult.reason));
       continue;
     }
-    const { value } = retryResult;
-    if (value.status === "retried") {
-      retried += 1;
-      continue;
-    }
-    errors.push(value.error);
+    retried += 1;
   }
   const result = { retried, failed: errors.length, errors };
   if (!shouldPersistBulkAudit(options))

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

@@ -122,7 +122,7 @@ export function createTimeOperationCallbacks(engine) {
     loadWorkflowState: (workflowId) => loadWorkflowState(getInternals(engine), workflowId),
     failWorkflow: (workflowId, error) => failWorkflow(getInternals(engine), workflowId, error, createTerminationCallbacks(engine)),
     runSerializedWorkflowStateWrite: (workflowId, writeOperation) => runSerializedWorkflowStateWrite(getInternals(engine), workflowId, writeOperation),
-    beginWorkflowExecution: (workflowId, workflowType, input, checkpoint, executionDeadline, executionStateOwnerId, registration) => beginWorkflowExecution(getInternals(engine), workflowId, workflowType, input, checkpoint, executionDeadline, executionStateOwnerId, registration, createLifecycleCallbacks(engine)),
+    beginWorkflowExecution: (workflowId, workflowExecutionToken, workflowType, input, checkpoint, executionDeadline, executionStateOwnerId, registration) => beginWorkflowExecution(getInternals(engine), workflowId, workflowExecutionToken, workflowType, input, checkpoint, executionDeadline, executionStateOwnerId, registration, createLifecycleCallbacks(engine)),
     workflowVersionTupleFromState: (state) => workflowVersionTupleFromState(getInternals(engine), state, createLifecycleCallbacks(engine)),
     setWorkflowStartHeaders: (workflowId, headers) => setWorkflowStartHeaders(getInternals(engine), workflowId, headers, createLifecycleCallbacks(engine)),
     loadWorkflowStartHeaders: (workflowId) => loadWorkflowStartHeaders(getInternals(engine), workflowId, createLifecycleCallbacks(engine)),

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

@@ -46,6 +46,7 @@ export function disposeEngine(internals) {
   internals.pendingWebhooks.clear();
   internals.sleepResolvers.clear();
   internals.sleepResolversByWorkflow.clear();
+  internals.sleepTimersFiredWithoutResolver.clear();
   internals.checkpoints.clear();
   internals.pendingExecutionStateOwnerId = void 0;
   internals.workflowNestingDepths.clear();

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;
@@ -84,6 +85,7 @@ export type PendingTimelineEntry = {
 };
 export type QueuedInlineWorkflowExecutionStart = {
     workflowId: string;
+    workflowExecutionToken?: string;
     workflowType: string;
     input: unknown;
     checkpoint: Checkpoint;

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>;