@lostgradient/weft 0.11.0 → 0.13.0

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

@@ -2,8 +2,8 @@ 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:";
+const ASYNC_ACTIVITY_TOKEN_PREFIX = "async-act:v1", PENDING_ASYNC_ACTIVITY_CURSOR_PREFIX = "pending-async:v1:";
+export const DEFAULT_PENDING_ASYNC_ACTIVITY_LIMIT = 50, MAX_PENDING_ASYNC_ACTIVITY_LIMIT = 200, MAX_PENDING_ASYNC_ACTIVITY_CURSOR_LENGTH = 8192, ASYNC_ACTIVITY_KEY_PREFIX = "async-act:v1:";
 export function asyncActivityWorkflowPrefix(workflowId) {
   return `${ASYNC_ACTIVITY_KEY_PREFIX}${encodeStorageKeyComponent(workflowId)}:`;
 }
@@ -13,6 +13,85 @@ function isPersistedAsyncActivity(value) {
   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 decodePendingAsyncActivityCursor(cursor) {
+  if (cursor.length > MAX_PENDING_ASYNC_ACTIVITY_CURSOR_LENGTH || !cursor.startsWith(PENDING_ASYNC_ACTIVITY_CURSOR_PREFIX))
+    return null;
+  try {
+    const suffix = decodeURIComponent(cursor.slice(PENDING_ASYNC_ACTIVITY_CURSOR_PREFIX.length));
+    return suffix.length > 0 ? suffix : null;
+  } catch {
+    return null;
+  }
+}
+export function isPendingAsyncActivityCursor(cursor) {
+  return decodePendingAsyncActivityCursor(cursor) !== null;
+}
+export function isPendingAsyncActivityCursorForWorkflow(cursor, workflowId) {
+  const key = decodePendingAsyncActivityCursor(cursor), prefix = asyncActivityWorkflowPrefix(workflowId);
+  return key !== null && key.startsWith(prefix) && key.length > prefix.length;
+}
+function encodePendingAsyncActivityCursor(key) {
+  return `${PENDING_ASYNC_ACTIVITY_CURSOR_PREFIX}${encodeURIComponent(key)}`;
+}
+function resolvePendingAsyncActivityLimit(limit) {
+  const resolved = limit ?? DEFAULT_PENDING_ASYNC_ACTIVITY_LIMIT;
+  if (!Number.isSafeInteger(resolved) || resolved < 1 || resolved > MAX_PENDING_ASYNC_ACTIVITY_LIMIT)
+    throw RangeError(`Pending async activity limit must be an integer between 1 and ${MAX_PENDING_ASYNC_ACTIVITY_LIMIT}.`);
+  return resolved;
+}
+function toPendingAsyncActivityInfo(value, key, workflowId) {
+  if (!isPersistedAsyncActivity(value))
+    return null;
+  if (value.workflowId !== workflowId || key !== KEYS.asyncActivity(workflowId, value.token))
+    return null;
+  if (!Number.isSafeInteger(value.step) || value.step < 0 || !Number.isSafeInteger(value.attempt) || value.attempt < 1 || !Number.isFinite(value.createdAt))
+    return null;
+  return {
+    token: value.token,
+    operationId: value.operationId,
+    activityName: value.activityName,
+    step: value.step,
+    attempt: value.attempt,
+    createdAt: value.createdAt
+  };
+}
+function resolvePendingAsyncActivityAfterKey(cursor, workflowId) {
+  if (cursor === void 0)
+    return;
+  const key = decodePendingAsyncActivityCursor(cursor);
+  if (key === null || !isPendingAsyncActivityCursorForWorkflow(cursor, workflowId))
+    throw TypeError("Invalid pending async activity cursor.");
+  return key;
+}
+function decodePendingAsyncActivityInfo(bytes, key, workflowId) {
+  try {
+    return toPendingAsyncActivityInfo(decode(bytes), key, workflowId);
+  } catch {
+    return null;
+  }
+}
+function pendingAsyncActivityPage(scanned, limit, workflowId) {
+  const pageEntries = scanned.slice(0, limit), items = pageEntries.flatMap(([key, bytes]) => {
+    const item = decodePendingAsyncActivityInfo(bytes, key, workflowId);
+    return item === null ? [] : [item];
+  }), cursorKey = pageEntries.at(-1)?.[0];
+  return {
+    items,
+    ...scanned.length > limit && cursorKey !== void 0 ? { nextCursor: encodePendingAsyncActivityCursor(cursorKey) } : {}
+  };
+}
+export async function listPendingAsyncActivities(internals, workflowId, options = {}) {
+  const limit = resolvePendingAsyncActivityLimit(options.limit), prefix = asyncActivityWorkflowPrefix(workflowId), afterKey = resolvePendingAsyncActivityAfterKey(options.cursor, workflowId), scanned = [];
+  for await (const entry of internals.storage.scan(prefix, {
+    limit: limit + 1,
+    ...afterKey === void 0 ? {} : { gt: afterKey }
+  })) {
+    scanned.push(entry);
+    if (scanned.length >= limit + 1)
+      break;
+  }
+  return pendingAsyncActivityPage(scanned, limit, workflowId);
+}
 function isPersistedOperationOutcome(value) {
   if (typeof value !== "object" || value === null)
     return !1;

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

@@ -12,6 +12,7 @@ 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";
+import { decodeScheduleRunMetadata } from "./schedule-run-metadata.js";
 import { createTerminalCleanupTimerId } from "./state-utilities.js";
 import {
   decodeWorkflowState,
@@ -181,12 +182,22 @@ async function collectWorkflowPurgeDeleteKeys(internals, state) {
   const workflowId = state.id, deleteKeys = buildBaseWorkflowDeleteKeys(state);
   addExecutionDeadlineDeleteKeys(deleteKeys, state);
   addTerminalCleanupDeleteKey(deleteKeys, state);
+  await addScheduleRunHistoryDeleteKeys(internals.storage, deleteKeys, workflowId);
   await addUpdateRequestDeleteKeys(internals.storage, deleteKeys, workflowId);
   await addWorkflowPrefixDeleteKeys(internals.storage, deleteKeys, workflowId);
   return deleteKeys;
 }
+async function addScheduleRunHistoryDeleteKeys(storage, deleteKeys, workflowId) {
+  const linkKey = KEYS.scheduleRunLink(workflowId), linkBytes = await storage.get(linkKey);
+  deleteKeys.add(linkKey);
+  if (linkBytes === null)
+    return;
+  const metadata = decodeScheduleRunMetadata(linkBytes);
+  if (metadata !== null)
+    deleteKeys.add(KEYS.scheduleRunBySchedule(metadata.id, workflowId));
+}
 function buildBaseWorkflowDeleteKeys(state) {
-  return new Set([
+  const keys = new Set([
     KEYS.workflow(state.id),
     KEYS.checkpoint(state.id),
     KEYS.workflowHeaders(state.id),
@@ -196,9 +207,13 @@ function buildBaseWorkflowDeleteKeys(state) {
     KEYS.workflowHasServices(state.id),
     KEYS.finalizerState(state.id),
     KEYS.teardownOwed(state.id),
+    KEYS.teardownSucceeded(state.id),
     KEYS.attribute(state.id),
     KEYS.terminalWorkflow(state.updatedAt, state.id)
   ]);
+  if (state.parentWorkflowId !== void 0)
+    keys.add(KEYS.childWorkflowByParent(state.parentWorkflowId, state.parentWorkflowExecutionToken, state.id));
+  return keys;
 }
 function addExecutionDeadlineDeleteKeys(deleteKeys, state) {
   if (state.executionDeadline === void 0)

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

@@ -63,6 +63,8 @@ function summarizeBulkFilter(filter) {
     summary.status = Array.isArray(filter.status) ? uniqueSorted(filter.status) : filter.status;
   if (filter.type !== void 0)
     summary.type = filter.type;
+  if (filter.scheduleId !== void 0)
+    summary.scheduleId = filter.scheduleId;
   const normalizedTags = normalizeWorkflowTags(filter.tags);
   if (normalizedTags !== void 0)
     summary.tags = normalizedTags;

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

@@ -77,7 +77,8 @@ export function createLifecycleCallbacks(engine) {
     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")
+    failWorkflowForCheckpointDecodeError: (workflowId, error) => failWorkflow(getInternals(engine), workflowId, error, createTerminationCallbacks(engine), "system"),
+    failWorkflowForVersionMismatch: (workflowId, error) => failWorkflow(getInternals(engine), workflowId, error, createTerminationCallbacks(engine), "system")
   };
 }
 export function createTerminationCallbacksWith(engine, handleScheduledWorkflowTerminal) {

package/dist/core/engine/callback-creators-schedule.d.ts

@@ -1,12 +1,13 @@
 import type { ScheduleState, TimerEntry } from '../types.ts';
 import type { Engine } from './index.ts';
 import type { ReviewOperationCallbacks, SubmitReviewCallbacks } from './reviews.ts';
+import type { ScheduledRunStartOptions } from './schedule-run.ts';
 import { type RefreshedScheduleState, type ScheduleCallbacks } from './schedules.ts';
 export declare function createScheduleCallbacks<TWorkflows extends object, TActivities extends object>(engine: Engine<TWorkflows, TActivities>): ScheduleCallbacks;
 export declare function createReviewOperationCallbacks<TWorkflows extends object, TActivities extends object>(engine: Engine<TWorkflows, TActivities>): ReviewOperationCallbacks;
 export declare function createSubmitReviewCallbacks<TWorkflows extends object, TActivities extends object>(engine: Engine<TWorkflows, TActivities>): SubmitReviewCallbacks;
 export declare function refreshScheduledWorkflowStateForEngine<TWorkflows extends object, TActivities extends object>(engine: Engine<TWorkflows, TActivities>, state: ScheduleState): Promise<RefreshedScheduleState>;
-export declare function startScheduledRunForEngine<TWorkflows extends object, TActivities extends object>(engine: Engine<TWorkflows, TActivities>, state: ScheduleState, occurrence?: number): Promise<string>;
+export declare function startScheduledRunForEngine<TWorkflows extends object, TActivities extends object>(engine: Engine<TWorkflows, TActivities>, state: ScheduleState, options?: ScheduledRunStartOptions): Promise<string>;
 export declare function applyScheduleOccurrenceForEngine<TWorkflows extends object, TActivities extends object>(engine: Engine<TWorkflows, TActivities>, state: ScheduleState, occurrence?: number): Promise<ScheduleState>;
 export declare function settleBackfillScheduleStateForEngine<TWorkflows extends object, TActivities extends object>(engine: Engine<TWorkflows, TActivities>, state: ScheduleState): Promise<ScheduleState>;
 export declare function handleScheduleTimerForEngine<TWorkflows extends object, TActivities extends object>(engine: Engine<TWorkflows, TActivities>, entry: TimerEntry): Promise<void>;

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

@@ -27,7 +27,7 @@ export function createScheduleCallbacks(engine) {
     cancelWorkflow: (workflowId) => engine.cancel(workflowId),
     getWorkflowResult: (workflowId) => engine.getHandle(workflowId).result(),
     refreshScheduledWorkflowState: (state) => refreshScheduledWorkflowStateForEngine(engine, state),
-    startScheduledRun: (state, occurrence) => startScheduledRunForEngine(engine, state, occurrence),
+    startScheduledRun: (state, options) => startScheduledRunForEngine(engine, state, options),
     applyScheduleOccurrence: (state, occurrence) => applyScheduleOccurrenceForEngine(engine, state, occurrence),
     settleBackfillScheduleState: (state) => settleBackfillScheduleStateForEngine(engine, state),
     flushQueuedInlineWorkflowStartsDirectly: () => flushQueuedInlineWorkflowStartsDirectly(getInternals(engine), createInlineLaunchQueueCallbacks(engine)),
@@ -51,8 +51,8 @@ export function createSubmitReviewCallbacks(engine) {
 export async function refreshScheduledWorkflowStateForEngine(engine, state) {
   return refreshScheduledWorkflowState(getInternals(engine), state, createScheduleCallbacks(engine));
 }
-export async function startScheduledRunForEngine(engine, state, occurrence) {
-  return startScheduledRun(getInternals(engine), state, createScheduleCallbacks(engine), occurrence);
+export async function startScheduledRunForEngine(engine, state, options) {
+  return startScheduledRun(getInternals(engine), state, createScheduleCallbacks(engine), options);
 }
 export async function applyScheduleOccurrenceForEngine(engine, state, occurrence) {
   return applyScheduleOccurrence(getInternals(engine), state, createScheduleCallbacks(engine), occurrence);

package/dist/core/engine/checkpoint-reads.js

@@ -66,12 +66,22 @@ export async function getTimeline(internals, workflowId) {
         inputSummary: sanitizeTimelineSummary(decoded.inputSummary) ?? decoded.inputSummary,
         ...decoded.outputSummary !== void 0 ? {
           outputSummary: sanitizeTimelineSummary(decoded.outputSummary) ?? decoded.outputSummary
-        } : {}
+        } : {},
+        ...decoded.branches === void 0 ? {} : { branches: decoded.branches.map(sanitizeTimelineOperationDetail) },
+        ...decoded.children === void 0 ? {} : { children: decoded.children.map(sanitizeTimelineOperationDetail) }
       });
   }
   timeline.sort((left, right) => left.step - right.step);
   return timeline;
 }
+function sanitizeTimelineOperationDetail(detail) {
+  if (detail.errorSummary === void 0)
+    return detail;
+  return {
+    ...detail,
+    errorSummary: sanitizeTimelineSummary(detail.errorSummary) ?? detail.errorSummary
+  };
+}
 export async function replayTo(internals, workflowId, step) {
   const bytes = await internals.storage.get(KEYS.checkpointHistory(workflowId, step));
   if (!bytes)

package/dist/core/engine/child-workflow.js

@@ -22,6 +22,8 @@ function applyPendingChildExecutionContext(internals, context) {
   internals.pendingNestingDepth = context.pendingNestingDepth;
   internals.pendingParentHeaders = context.pendingParentHeaders;
   internals.pendingExecutionStateOwnerId = context.pendingExecutionStateOwnerId;
+  internals.pendingParentWorkflowId = context.pendingParentWorkflowId;
+  internals.pendingParentWorkflowExecutionToken = context.pendingParentWorkflowExecutionToken;
 }
 function clearPendingChildExecutionContext(internals, context) {
   if (internals.pendingNestingDepth === context.pendingNestingDepth)
@@ -30,15 +32,20 @@ function clearPendingChildExecutionContext(internals, context) {
     internals.pendingParentHeaders = void 0;
   if (internals.pendingExecutionStateOwnerId === context.pendingExecutionStateOwnerId)
     internals.pendingExecutionStateOwnerId = void 0;
+  if (internals.pendingParentWorkflowId === context.pendingParentWorkflowId)
+    internals.pendingParentWorkflowId = void 0;
+  if (internals.pendingParentWorkflowExecutionToken === context.pendingParentWorkflowExecutionToken)
+    internals.pendingParentWorkflowExecutionToken = void 0;
 }
-function existingChildMatchesRequest(existingState, operation, executionStateOwnerId) {
-  return existingState.type === operation.workflowType && encodedValuesEqual(existingState.input, operation.input) && existingState.executionStateOwnerId === executionStateOwnerId;
+function existingChildMatchesRequest(existingState, operation, executionStateOwnerId, parentWorkflowId, parentWorkflowExecutionToken) {
+  const lineageMatches = existingState.parentWorkflowId === void 0 && existingState.parentWorkflowExecutionToken === void 0 || existingState.parentWorkflowId === parentWorkflowId && existingState.parentWorkflowExecutionToken === parentWorkflowExecutionToken;
+  return existingState.type === operation.workflowType && encodedValuesEqual(existingState.input, operation.input) && existingState.executionStateOwnerId === executionStateOwnerId && lineageMatches;
 }
-async function resolveCollisionChildHandle(childWorkflowId, operation, executionStateOwnerId, collisionError, callbacks) {
+async function resolveCollisionChildHandle(childWorkflowId, operation, executionStateOwnerId, parentWorkflowId, parentWorkflowExecutionToken, collisionError, callbacks) {
   const existingState = await callbacks.loadWorkflowState(childWorkflowId);
   if (!existingState)
     throw collisionError;
-  if (!existingChildMatchesRequest(existingState, operation, executionStateOwnerId))
+  if (!existingChildMatchesRequest(existingState, operation, executionStateOwnerId, parentWorkflowId, parentWorkflowExecutionToken))
     throw Error(`Child workflow id collision for "${childWorkflowId}" does not match the requested child workflow`, { cause: collisionError });
   return callbacks.getHandle(childWorkflowId);
 }
@@ -52,7 +59,7 @@ async function dispatchChildWorkflowStart(internals, childWorkflowId, operation,
   } catch (error) {
     if (!(error instanceof WorkflowAlreadyExistsError))
       throw error;
-    return resolveCollisionChildHandle(childWorkflowId, operation, context.pendingExecutionStateOwnerId ?? void 0, error, callbacks);
+    return resolveCollisionChildHandle(childWorkflowId, operation, context.pendingExecutionStateOwnerId ?? void 0, context.pendingParentWorkflowId, context.pendingParentWorkflowExecutionToken, error, callbacks);
   } finally {
     clearPendingChildExecutionContext(internals, context);
   }
@@ -62,7 +69,9 @@ export async function executeChildWorkflow(internals, workflowId, operation, cur
     const context = {
       pendingNestingDepth: currentDepth + 1,
       pendingParentHeaders: internals.workflowHeaders.get(workflowId),
-      pendingExecutionStateOwnerId: executionStateOwnerId
+      pendingExecutionStateOwnerId: executionStateOwnerId,
+      pendingParentWorkflowId: workflowId,
+      pendingParentWorkflowExecutionToken: parentState?.workflowExecutionToken
     }, childHandle = await dispatchChildWorkflowStart(internals, childWorkflowId, operation, context, callbacks);
     if (parentClosePolicy === "abandon")
       return createChildWorkflowHandleReference(childHandle.id);

package/dist/core/engine/construction.js

@@ -72,6 +72,9 @@ export function copyWorkflowDefinition(type, registration) {
     ...registration.description === void 0 ? {} : { description: registration.description },
     ...registration.inputSchema === void 0 ? {} : { inputSchema: registration.inputSchema },
     ...registration.outputSchema === void 0 ? {} : { outputSchema: registration.outputSchema },
+    ...registration.signals === void 0 ? {} : { signals: { ...registration.signals } },
+    ...registration.updates === void 0 ? {} : { updates: { ...registration.updates } },
+    ...registration.queries === void 0 ? {} : { queries: { ...registration.queries } },
     ...registration.searchAttributes === void 0 ? {} : { searchAttributes: registration.searchAttributes },
     ...registration.concurrency === void 0 ? {} : { concurrency: registration.concurrency }
   };

package/dist/core/engine/disposal.js

@@ -53,6 +53,8 @@ export function disposeEngine(internals) {
   internals.sleepTimersFiredWithoutResolver.clear();
   internals.checkpoints.clear();
   internals.pendingExecutionStateOwnerId = void 0;
+  internals.pendingParentWorkflowId = void 0;
+  internals.pendingParentWorkflowExecutionToken = void 0;
   internals.workflowNestingDepths.clear();
   internals.workflowServices.clear();
   internals.workflowHeaders.clear();

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

@@ -2,7 +2,7 @@ import type { Storage as WeftStorage } from '../../storage/interface.ts';
 import type { ConstraintDefinition } from '../constraint.ts';
 import type { ExecutionStrategy } from '../execution-strategy.ts';
 import type { InlineExecutionStrategy } from '../inline-execution-strategy.ts';
-import type { AnyActivityDefinition, ArchiveAdapter, Checkpoint, DefinitionSchema, EngineOptions, NormalizedHistoryPolicy, NormalizedPayloadSizePolicy, NormalizedRetentionPolicy, SearchAttributeSchema, WorkflowConcurrencyOptions, WorkflowFunction, WorkflowTimelineEntry } from '../types.ts';
+import type { AnyActivityDefinition, ArchiveAdapter, Checkpoint, DefinitionSchema, EngineOptions, NormalizedHistoryPolicy, NormalizedPayloadSizePolicy, NormalizedRetentionPolicy, QueryDefinition, SearchAttributeSchema, SignalDefinition, UpdateDefinition, WorkflowConcurrencyOptions, WorkflowFunction, WorkflowTimelineEntry } from '../types.ts';
 export interface RegistrationEntry {
     handler: WorkflowFunction;
     version: string;
@@ -10,6 +10,9 @@ export interface RegistrationEntry {
     tags?: ReadonlyArray<string>;
     inputSchema?: DefinitionSchema;
     outputSchema?: DefinitionSchema;
+    signals?: Readonly<Record<string, Readonly<SignalDefinition<unknown>>>>;
+    updates?: Readonly<Record<string, Readonly<UpdateDefinition<unknown>>>>;
+    queries?: Readonly<Record<string, Readonly<QueryDefinition<unknown>>>>;
     searchAttributes?: SearchAttributeSchema;
     retention?: NormalizedRetentionPolicy;
     concurrency?: WorkflowConcurrencyOptions;

package/dist/core/engine/fenced-write.d.ts

@@ -27,9 +27,11 @@ import type { EngineInternals } from './internals.ts';
  * work before `recoverAll()` would otherwise durably write workflow state without
  * single-writer ownership and without having recovered existing runs. Placed at
  * each public awaited entry so the caller gets a clean {@link EngineLeaseNotHeldError}
- * — without this, fork/resume would reach `resolveFenceEpochOrHalt` with no held
- * epoch and be misreported as a deposition (warn + teardown) rather than the true
- * "lease not held yet" condition. A no-op under `ownership: 'none'`.
+ * — without this, fork, resume, and the schedule mutators (`schedule`,
+ * `pauseSchedule`, `resumeSchedule`, `cancelSchedule`, and `updateSchedule`) would
+ * reach `resolveFenceEpochOrHalt` with no held epoch and be misreported as a
+ * deposition (warn + teardown) rather than the true "lease not held yet"
+ * condition. A no-op under `ownership: 'none'`.
  */
 export declare function assertLeaseHeldForEngineWork(internals: EngineInternals): void;
 /**

package/dist/core/engine/finalizer-status.d.ts

@@ -0,0 +1,10 @@
+import { type BatchOperation } from '../../storage/interface.ts';
+import type { WorkflowFinalizerStatus, WorkflowState } from '../types.ts';
+import type { EngineInternals } from './internals.ts';
+export interface TeardownSucceededRecord {
+    attempts: number;
+    completedAt: number;
+    workflowExecutionToken?: string;
+}
+export declare function buildTeardownSuccessOperations(workflowId: string, attempts: number, completedAt: number, workflowExecutionToken: string | undefined): BatchOperation[];
+export declare function getFinalizerStatus(internals: EngineInternals, workflowId: string, state: WorkflowState | null): Promise<WorkflowFinalizerStatus | null>;

package/dist/core/engine/finalizer-status.js

@@ -0,0 +1,82 @@
+import { KEYS } from "../../storage/interface.js";
+import { decode, encode } from "../codec.js";
+import { isRecord } from "../debug-output.js";
+import { isTeardownClaim } from "./state-utilities.js";
+export function buildTeardownSuccessOperations(workflowId, attempts, completedAt, workflowExecutionToken) {
+  const outcome = {
+    attempts,
+    completedAt,
+    ...workflowExecutionToken === void 0 ? {} : { workflowExecutionToken }
+  };
+  return [
+    { type: "delete", key: KEYS.teardownOwed(workflowId) },
+    { type: "delete", key: KEYS.finalizerState(workflowId) },
+    { type: "put", key: KEYS.teardownSucceeded(workflowId), value: encode(outcome) }
+  ];
+}
+function decodeUnknown(bytes) {
+  try {
+    return decode(bytes);
+  } catch {
+    return null;
+  }
+}
+function isNonNegativeSafeInteger(value) {
+  return typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+}
+function isNonNegativeFiniteNumber(value) {
+  return typeof value === "number" && Number.isFinite(value) && value >= 0;
+}
+function recordBelongsToRun(record, state) {
+  const recordToken = record.workflowExecutionToken;
+  if (recordToken !== void 0 && typeof recordToken !== "string")
+    return !1;
+  if (state === null)
+    return !0;
+  return recordToken === state.workflowExecutionToken;
+}
+export async function getFinalizerStatus(internals, workflowId, state) {
+  const claimBytes = await internals.storage.get(KEYS.teardownOwed(workflowId)), claimStatus = decodeClaimStatus(claimBytes);
+  if (claimStatus !== null)
+    return claimStatus;
+  const deadLetterBytes = await internals.storage.get(KEYS.teardownDeadLetter(workflowId)), failedStatus = decodeFailedStatus(deadLetterBytes, state);
+  if (failedStatus !== null)
+    return failedStatus;
+  const succeededBytes = await internals.storage.get(KEYS.teardownSucceeded(workflowId));
+  return decodeSucceededStatus(succeededBytes, state);
+}
+function decodeClaimStatus(bytes) {
+  if (bytes === null)
+    return null;
+  const claim = decodeUnknown(bytes);
+  if (!isTeardownClaim(claim))
+    return null;
+  if (claim.status === "running" && claim.claimedAt !== void 0)
+    return { status: "running", attempts: claim.attempts + 1, startedAt: claim.claimedAt };
+  return { status: "pending", attempts: claim.attempts };
+}
+function decodeFailedStatus(bytes, state) {
+  if (bytes === null)
+    return null;
+  const record = decodeUnknown(bytes);
+  if (!isRecord(record) || !recordBelongsToRun(record, state) || typeof record.lastError !== "string" || !isNonNegativeSafeInteger(record.attempts) || !isNonNegativeFiniteNumber(record.deadLetteredAt))
+    return null;
+  return {
+    status: "failed",
+    attempts: record.attempts,
+    failedAt: record.deadLetteredAt,
+    error: record.lastError
+  };
+}
+function decodeSucceededStatus(bytes, state) {
+  if (bytes === null)
+    return null;
+  const record = decodeUnknown(bytes);
+  if (!isRecord(record) || !recordBelongsToRun(record, state) || !isNonNegativeSafeInteger(record.attempts) || !isNonNegativeFiniteNumber(record.completedAt))
+    return null;
+  return {
+    status: "succeeded",
+    attempts: record.attempts,
+    completedAt: record.completedAt
+  };
+}

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

@@ -5,7 +5,7 @@ import type { TypedEventTarget, WeftEventMap } from '../events.ts';
 import type { Interceptor } from '../interceptor.ts';
 import { type ReviewRequest } from '../review/index.ts';
 import { Scheduler } from '../scheduler.ts';
-import { type AnyActivityDefinition, type AnyWorkflowDefinition, type AttributeFilterKey, type BulkCancelResult, type BulkDeleteResult, type BulkOperationCommitOptions, type BulkOperationDryRunOptions, type BulkOperationDryRunResult, type BulkRetryFailedResult, type BulkSignalAllCommitOptions, type BulkSignalAllDryRunOptions, type BulkSignalResult, type BulkTagResult, type CheckpointState, type CheckpointSummary, type CoordinatedUpdateResult, type DefaultActivityTypes, type DefaultWorkflowRegistry, type ForkOptions, type InferActivityEntries, type InferActivityEntry, type InferWorkflowEntries, type InferWorkflowEntry, type ListFilter, type ListOptions, type PaginatedResult, type PurgeResult, type QueryDefinition, type RegisteredWorkflowDefinition, type RetentionOverview, type ReviewListEntry, type ReviewListFilter, type ScheduleDefinition, type ScheduleFilter, type ScheduleOptions, type ScheduleSpec, type ScheduleSummary, type SearchAttributeValue, type SignalDefinition, type SignalDeliveryOptions, type StartOrSignalOptions, type StartOrSignalSignal, type StartWorkflowOptions, type SubmitReviewOptions, type TypedListFilter, type UpdateDefinition, type WorkflowEvent, type WorkflowInput, type WorkflowOutput, type WorkflowReplay, type WorkflowServices, type WorkflowServicesUnion, type WorkflowState, type WorkflowSummary, type WorkflowTimelineEntry } from '../types.ts';
+import { type AnyActivityDefinition, type AnyWorkflowDefinition, type AttributeFilterKey, type BulkCancelResult, type BulkDeleteResult, type BulkOperationCommitOptions, type BulkOperationDryRunOptions, type BulkOperationDryRunResult, type BulkRetryFailedResult, type BulkSignalAllCommitOptions, type BulkSignalAllDryRunOptions, type BulkSignalResult, type BulkTagResult, type CheckpointState, type CheckpointSummary, type CoordinatedUpdateResult, type DefaultActivityTypes, type DefaultWorkflowRegistry, type ForkOptions, type InferActivityEntries, type InferActivityEntry, type InferWorkflowEntries, type InferWorkflowEntry, type ListFilter, type ListOptions, type PaginatedResult, type PendingAsyncActivityListOptions, type PendingAsyncActivityPage, type PurgeResult, type QueryDefinition, type RegisteredWorkflowDefinition, type RetentionOverview, type ReviewListEntry, type ReviewListFilter, type ScheduleDefinition, type ScheduleFilter, type ScheduleOptions, type ScheduleSpec, type ScheduleSummary, type ScheduleUpdateOptions, type SearchAttributeValue, type SignalDefinition, type SignalDeliveryOptions, type StartOrSignalOptions, type StartOrSignalSignal, type StartWorkflowOptions, type SubmitReviewOptions, type TypedListFilter, type UpdateDefinition, type WorkflowEvent, type WorkflowFinalizerStatus, type WorkflowInput, type WorkflowOutput, type WorkflowReplay, type WorkflowScheduleProvenance, type WorkflowServices, type WorkflowServicesUnion, type WorkflowState, type WorkflowSummary, type WorkflowTimelineEntry } from '../types.ts';
 import type { TimerEntry } from '../types/checkpoint.ts';
 import type { WorkflowAlreadyRegistered } from '../types/workflow-builder.ts';
 import { type AggregateOptions, type AggregateResult } from './aggregate.ts';
@@ -15,6 +15,7 @@ import type { EngineConstructorOptions } from './engine-internal-types.ts';
 import type { EngineStateNamespace } from './engine-state-namespace.ts';
 import { HANDLE_RESULT_PROMISE, WorkflowHandle } from './handles.ts';
 import { ENGINE_LEASE_LOST_WARNING_NAME } from './lease-deposition.ts';
+import type { EngineLeaseHealth } from './lease-health.ts';
 import { type RecoverAllOptions, type StartOrSignalResult } from './lifecycle.ts';
 import { assertCompatiblePersistedDataVersion } from './persisted-data-version.ts';
 import { ScheduleHandle } from './schedule-handle.ts';
@@ -26,6 +27,7 @@ export type { PendingTimelineEntry, RegistrationEntry, ResolvedOptions, TrackedW
 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 { EngineLeaseHealth, LeaseLostReason } from './lease-health.ts';
 export type { RecoverAllOptions, RecoveredWorkflowInfo } from './lifecycle.ts';
 export { ScheduleHandle } from './schedule-handle.ts';
 export type { WorkflowFeedListener, WorkflowFeedRecord, WorkflowFeedSelector, } from './workflow-feed.ts';
@@ -304,7 +306,7 @@ export declare class Engine<TWorkflows extends object = DefaultWorkflowRegistry,
     pauseSchedule(scheduleId: string): Promise<void>;
     resumeSchedule(scheduleId: string): Promise<void>;
     cancelSchedule(scheduleId: string): Promise<void>;
-    updateSchedule(scheduleId: string, newSpec: string | ScheduleSpec): Promise<void>;
+    updateSchedule(scheduleId: string, newSpec: string | ScheduleSpec, options?: ScheduleUpdateOptions): Promise<void>;
     [HANDLE_RESULT_PROMISE](workflowId: string): Promise<unknown>;
     [ENGINE_PARKED_WORKFLOW_COUNT_FOR_TESTING](): number;
     [ENGINE_SIGNAL_WAITER_COUNT_FOR_TESTING](): number;
@@ -371,6 +373,12 @@ export declare class Engine<TWorkflows extends object = DefaultWorkflowRegistry,
      * deploys or explicit operator storage repair.
      * When set, unknown workflow types are skipped and reported through
      * {@link WorkflowRecoverySkippedEvent}.
+     *
+     * A recovered workflow whose persisted version metadata no longer matches
+     * its registered `WorkflowDefinition.version` is isolated per
+     * {@link RecoverAllOptions.versionMismatchPolicy} (default `'fail-run'`):
+     * only that workflow fails, and `recoverAll()` continues recovering its
+     * siblings in the same call.
      */
     recoverAll(options?: RecoverAllOptions): Promise<WorkflowHandle[]>;
     /**
@@ -388,6 +396,13 @@ export declare class Engine<TWorkflows extends object = DefaultWorkflowRegistry,
      * the token (unknown, or already completed/failed — tokens are single-use).
      */
     completeAsyncActivity(token: string, result: unknown): Promise<void>;
+    /**
+     * List a bounded page of durable async activities awaiting out-of-band
+     * completion for one workflow. This reads storage directly, so callers can
+     * recover tokens after a process restart before `recoverAll()` repopulates
+     * the in-memory completion map.
+     */
+    listPendingAsyncActivities(workflowId: string, options?: PendingAsyncActivityListOptions): Promise<PendingAsyncActivityPage>;
     /**
      * Fail a deferred activity out-of-band with `error`. The error is thrown into
      * the workflow generator at the parked step — identical to an inline activity
@@ -419,6 +434,21 @@ export declare class Engine<TWorkflows extends object = DefaultWorkflowRegistry,
     suspend(workflowId: string): Promise<void>;
     timeout(workflowId: string): Promise<void>;
     get(workflowId: string): Promise<WorkflowState | null>;
+    /** Return the schedule occurrence that launched a workflow, when applicable. */
+    getScheduleProvenance(workflowId: string): Promise<WorkflowScheduleProvenance | null>;
+    /** Return durable post-terminal finalizer progress or outcome, when applicable. */
+    getFinalizerStatus(workflowId: string): Promise<WorkflowFinalizerStatus | null>;
+    /**
+     * Return this process's last-known ownership-lease health.
+     *
+     * This is a synchronous diagnostic snapshot: it never performs a storage read
+     * and therefore remains available to operator transports after a confirmed
+     * deposition has detached the lease manager. Holder identifiers and timestamps
+     * are present only while the manager still has its own last-written holder
+     * record; a detached deposed engine reports the confirmed loss without
+     * inventing successor details.
+     */
+    getLeaseHealth(): EngineLeaseHealth;
     getCurrentCheckpointStep(workflowId: string): Promise<number | null>;
     getAttributes(workflowId: string): Promise<Record<string, SearchAttributeValue> | null>;
     setAttributes(workflowId: string, attributes: Record<string, SearchAttributeValue>): Promise<void>;
@@ -490,3 +520,40 @@ export declare class Engine<TWorkflows extends object = DefaultWorkflowRegistry,
      */
     fireTimer(entry: TimerEntry): Promise<void>;
 }
+/**
+ * `Engine` with its two chained-builder registration methods removed —
+ * `register` and `registerWorkflows`, whose return type is itself
+ * `Engine<NarrowedRegistry>` (see `register()`'s JSDoc: registering returns
+ * "this same engine with the definition added to its phantom type
+ * registry"). That self-reference is what makes `Engine` invariant in its
+ * registry generics: a concretely narrowed `Engine<Concrete>` (e.g. from
+ * `Engine.create({ workflows })`) is not structurally assignable to the
+ * plain default `Engine<DefaultWorkflowRegistry>`, even though every other
+ * member — including `start` and `startOrSignal`, whose *parameter* types
+ * (not return types) reference `TWorkflows` but never produce another
+ * `Engine<T>` — is not part of that recursive comparison.
+ *
+ * `start` and `startOrSignal` are deliberately KEPT (not omitted): hosted
+ * transports genuinely call them at runtime (REST/JSON-RPC workflow starts,
+ * MCP tool invocations) via `runtimeWorkflowEngine()`'s registry-erased
+ * dynamic-name overload, so a value satisfying this type must still provide
+ * them — a duck-typed engine substitute lacking `start` correctly fails to
+ * satisfy `RegistryAgnosticEngine` (see this type's `.test-d.ts` coverage).
+ *
+ * Host-facing options that accept an already-constructed `Engine` without
+ * needing the two chained-builder registration methods — `serve({ engine })`,
+ * the Service Worker helpers, the MCP session/HTTP/stdio surfaces — use this
+ * type instead of the bare default `Engine`, so both `new Engine({ storage })`
+ * and `Engine.create({ workflows })` are accepted without a call-site cast.
+ * See #708.
+ *
+ * (`Engine<object, object>` looks like the obvious fix — the widest legal
+ * instantiation of the registry generics — but TypeScript's structural check
+ * on `register()`'s self-referential return type does not reliably resolve
+ * that relationship: it can pass or fail for the identical `Engine<A>` /
+ * `Engine<B>` pair depending on unrelated compilation context, such as other
+ * files in the same program. Removing the registry-typed members entirely,
+ * rather than widening their generic arguments, avoids the recursive
+ * comparison altogether.)
+ */
+export type RegistryAgnosticEngine = Omit<Engine, 'register' | 'registerWorkflows'>;