@lostgradient/weft 0.24.1 → 0.24.2

package/README.md

@@ -1,6 +1,6 @@
 # Weft
 
-A Bun-native durable execution engine. Current release: `0.24.1`.
+A Bun-native durable execution engine. Current release: `0.24.2`.
 
 Install the library from npm as `@lostgradient/weft`:
 

package/dist/core/engine/bulk-operations-purge.d.ts

@@ -21,7 +21,7 @@ export declare function purgeWorkflow(internals: EngineInternals, state: Workflo
  * `onTerminalConflict: 'start-new'` restart path prepends them to the create batch
  * so purge-and-recreate land as one atomic unit (no window where the prior run is
  * gone but the new one has not committed). Keep this the single source of truth
- * for "what a purge deletes" — do not fork the delete-set.
+ * for "what a purge deletes" — do not fork the delete-set. (`wf-gen:<id>` is deliberately excluded; WFT-153, see {@link buildBaseWorkflowDeleteKeys}.)
  */
 export declare function collectWorkflowPurgeDeleteOperations(internals: EngineInternals, state: WorkflowState): Promise<BatchOperation[]>;
 /**

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

@@ -20,6 +20,7 @@ import { decodeScheduleRunMetadata } from "./schedule-run-metadata.js";
 import { createTerminalCleanupTimerId } from "./state-utilities.js";
 import { buildExternalTerminalRotationFragment } from "./storage-io.js";
 import { decodeWorkflowState, isTerminalWorkflowStatus } from "./validation.js";
+import { foldWorkflowGenerationBumpForPurge } from "./workflow-generation-fence.js";
 import { buildWorkflowVisibilityIndexTransition } from "./workflow-indexes.js";
 import { getWorkflowRetentionDeadline } from "./workflow-retention-deadline.js";
 export const TERMINAL_CLEANUP_DELAY_MS = 60000;
@@ -127,8 +128,8 @@ async function shouldPurgeWorkflowState(internals, state, expiredOnly, now) {
   return deadline !== null && deadline <= now;
 }
 export async function purgeWorkflow(internals, state, cleanupWaiters) {
-  const deleteOperations = await collectWorkflowPurgeDeleteOperations(internals, state), rotation = await buildExternalTerminalRotationFragment(internals, state.id), operations = [...deleteOperations, ...rotation.operations];
-  await commitFencedEngineWrite(internals, null, operations, rotation.conditions, () => {
+  const deleteOperations = await collectWorkflowPurgeDeleteOperations(internals, state), rotation = await buildExternalTerminalRotationFragment(internals, state.id), fenced = await foldWorkflowGenerationBumpForPurge(internals, state.id, rotation), operations = [...deleteOperations, ...fenced.operations];
+  await commitFencedEngineWrite(internals, null, operations, fenced.conditions, () => {
     return Error(`Purge commit for workflow "${state.id}" lost its precondition.`);
   });
   clearPurgedWorkflowInMemoryState(internals, state.id, cleanupWaiters);

package/dist/core/engine/bulk-operations-retry.d.ts

@@ -1,9 +1,24 @@
 import type { BulkOperationDryRunResult, BulkOperationOptions, BulkRetryFailedResult, ListFilter } from '../types.ts';
 import type { EngineInternals } from './internals.ts';
+import { type LifecycleCallbacks } from './lifecycle.ts';
 /**
  * `bulkOperations.ts`'s `retryFailedAll()` implementation, split into its
  * own module (with the rest of the retry-failed cluster below) to keep
  * `bulk-operations.ts` under the 800-line implementation-file ceiling —
  * the same reason `bulk-operations-purge.ts` was split out earlier.
  */
-export declare function runBulkFailedWorkflowRetry(internals: EngineInternals, filter: ListFilter, options?: BulkOperationOptions): Promise<BulkRetryFailedResult | BulkOperationDryRunResult>;
+export declare function runBulkFailedWorkflowRetry(internals: EngineInternals, filter: ListFilter, options?: BulkOperationOptions, 
+/**
+ * Threaded down from `Engine#retryFailedAll()`'s own `#createLifecycleCallbacks()`
+ * (WFT-95 issue 2 follow-up). Needed only by `retryFailedWorkflow()`'s
+ * checkpoint-absent fallback, which must call the internal `startWorkflow()`
+ * directly (see its doc comment) rather than the public `engine.start()`.
+ * Sourced this way — as a parameter, rather than this module importing
+ * `createLifecycleCallbacks` from `callback-creators-core.ts` itself — to avoid
+ * introducing a `bulk-operations-retry.ts` -> `callback-creators-core.ts` ->
+ * `termination.ts` -> `termination/complete.ts` -> `bulk-operations.ts` ->
+ * `bulk-operations-retry.ts` import cycle. Optional so direct-internals test
+ * harnesses that never reach the checkpoint-absent fallback (e.g.
+ * `bulk-operations-retry-direct.test.ts`) do not need to construct one.
+ */
+callbacks?: LifecycleCallbacks): Promise<BulkRetryFailedResult | BulkOperationDryRunResult>;

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

@@ -19,8 +19,13 @@ import {
   validateBulkConfirmation,
   withBulkAuditEvent
 } from "./bulk-operations-shared.js";
+import { ensureWorkflowCatalogReady, isWorkflowCatalogReady } from "./catalog-readiness.js";
 import { resolveExecutableRegistrationForRetry } from "./dynamic-source-execution.js";
-import { commitFencedEngineWriteAllowingPreconditionFailure } from "./fenced-write.js";
+import {
+  assertLeaseHeldForEngineWork,
+  commitFencedEngineWriteAllowingPreconditionFailure
+} from "./fenced-write.js";
+import { startWorkflow } from "./lifecycle.js";
 import { buildCatalogEntryRevisionCondition } from "./lifecycle/start-commit.js";
 import { createTerminalCleanupTimerId } from "./state-utilities.js";
 import { loadWorkflowState, runSerializedWorkflowStateWrite } from "./storage-io.js";
@@ -33,7 +38,7 @@ import {
 import { buildWorkflowConcurrencyStartOperations } from "./workflow-concurrency.js";
 import { buildWorkflowVisibilityIndexTransition } from "./workflow-indexes.js";
 const FAILED_WORKFLOW_STATUSES = ["failed"], CHECKPOINT_RETRY_CONCURRENCY_ADMISSION_MAX_ATTEMPTS = 5;
-export async function runBulkFailedWorkflowRetry(internals, filter, options = {}) {
+export async function runBulkFailedWorkflowRetry(internals, filter, options = {}, callbacks) {
   options = normalizeBulkOperationOptions(options);
   assertScopedBulkWorkflowFilter(filter);
   const actionableFilter = buildActionableBulkWorkflowFilter(internals, filter, FAILED_WORKFLOW_STATUSES), preparation = await prepareBulkOperation(internals, "retry-failed", actionableFilter, filter, {}, options);
@@ -43,7 +48,7 @@ export async function runBulkFailedWorkflowRetry(internals, filter, options = {}
   const bulkConcurrency = resolveBulkOperationConcurrency(options);
   let retried = 0;
   const errors = [], retryResults = await runBulkWorkflowPool(preparation.workflowIds, bulkConcurrency, async (workflowId) => {
-    await retryFailedWorkflow(internals, workflowId);
+    await retryFailedWorkflow(internals, workflowId, callbacks);
     return { status: "retried" };
   });
   for (const retryResult of retryResults) {
@@ -58,7 +63,7 @@ export async function runBulkFailedWorkflowRetry(internals, filter, options = {}
     return result;
   return withBulkAuditEvent(internals, preparation, options, result, retried);
 }
-async function retryFailedWorkflow(internals, workflowId) {
+async function retryFailedWorkflow(internals, workflowId, callbacks) {
   const state = await loadWorkflowState(internals, workflowId);
   if (state === null)
     throw Error("Workflow no longer exists");
@@ -69,11 +74,19 @@ async function retryFailedWorkflow(internals, workflowId) {
     await internals.engine.resume(workflowId);
     return;
   }
-  await internals.engine.start(state.type, state.input, {
+  const restartOptions = {
     id: workflowId,
     onTerminalConflict: "start-new",
     ...state.tags !== void 0 ? { tags: state.tags } : {}
-  });
+  };
+  if (callbacks === void 0) {
+    await internals.engine.start(state.type, state.input, restartOptions);
+    return;
+  }
+  assertLeaseHeldForEngineWork(internals);
+  if (!isWorkflowCatalogReady(internals.engine))
+    await ensureWorkflowCatalogReady(internals.engine);
+  await startWorkflow(internals, state.type, state.input, restartOptions, void 0, callbacks, void 0, void 0, "bulk-retry-only");
 }
 async function reactivateFailedWorkflowFromCheckpoint(internals, state) {
   const reactivated = await runSerializedWorkflowStateWrite(internals, state.id, async () => reactivateFailedWorkflowFromCheckpointSerialized(internals, state.id));

package/dist/core/engine/bulk-operations.d.ts

@@ -1,14 +1,15 @@
 import type { BulkCancelResult, BulkDeleteResult, BulkOperationCommitOptions, BulkOperationDryRunOptions, BulkOperationDryRunResult, BulkOperationOptions, BulkRetryFailedResult, BulkSignalAllCommitOptions, BulkSignalAllDryRunOptions, BulkSignalResult, BulkTagResult, ListFilter, PurgeResult } from '../types.ts';
 import { type CleanupWaiters } from './bulk-operations-purge.ts';
 import type { EngineInternals } from './internals.ts';
+import type { LifecycleCallbacks } from './lifecycle.ts';
 export { purgeInternal, TERMINAL_CLEANUP_DELAY_MS } from './bulk-operations-purge.ts';
 export declare function purge(internals: EngineInternals, filter: ListFilter | undefined, cleanupWaiters: CleanupWaiters): Promise<PurgeResult>;
 export declare function cancelAll(internals: EngineInternals, filter: ListFilter, options: BulkOperationDryRunOptions): Promise<BulkOperationDryRunResult>;
 export declare function cancelAll(internals: EngineInternals, filter: ListFilter, options?: BulkOperationCommitOptions): Promise<BulkCancelResult>;
 export declare function cancelAll(internals: EngineInternals, filter: ListFilter, options?: BulkOperationDryRunOptions | BulkOperationCommitOptions): Promise<BulkCancelResult | BulkOperationDryRunResult>;
 export declare function retryFailedAll(internals: EngineInternals, filter: ListFilter, options: BulkOperationDryRunOptions): Promise<BulkOperationDryRunResult>;
-export declare function retryFailedAll(internals: EngineInternals, filter: ListFilter, options?: BulkOperationCommitOptions): Promise<BulkRetryFailedResult>;
-export declare function retryFailedAll(internals: EngineInternals, filter: ListFilter, options?: BulkOperationDryRunOptions | BulkOperationCommitOptions): Promise<BulkRetryFailedResult | BulkOperationDryRunResult>;
+export declare function retryFailedAll(internals: EngineInternals, filter: ListFilter, options?: BulkOperationCommitOptions, callbacks?: LifecycleCallbacks): Promise<BulkRetryFailedResult>;
+export declare function retryFailedAll(internals: EngineInternals, filter: ListFilter, options?: BulkOperationDryRunOptions | BulkOperationCommitOptions, callbacks?: LifecycleCallbacks): Promise<BulkRetryFailedResult | BulkOperationDryRunResult>;
 export declare function signalAll(internals: EngineInternals, filter: ListFilter, name: string, payload: unknown, options: BulkSignalAllDryRunOptions): Promise<BulkOperationDryRunResult>;
 export declare function signalAll(internals: EngineInternals, filter: ListFilter, name: string, payload: unknown, options: BulkSignalAllCommitOptions): Promise<BulkSignalResult>;
 export declare function signalAll(internals: EngineInternals, filter: ListFilter, name: string, payload?: unknown, options?: BulkOperationCommitOptions): Promise<BulkSignalResult>;

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

@@ -64,9 +64,9 @@ async function runBulkCancellation(internals, filter, options = {}) {
 export async function cancelAll(internals, filter, options = {}) {
   return runBulkCancellation(internals, filter, options);
 }
-export async function retryFailedAll(internals, filter, options = {}) {
+export async function retryFailedAll(internals, filter, options = {}, callbacks) {
   assertLeaseHeldForEngineWork(internals);
-  return runBulkFailedWorkflowRetry(internals, filter, options);
+  return runBulkFailedWorkflowRetry(internals, filter, options, callbacks);
 }
 export async function signalAll(internals, filter, name, payload, maybeOptions) {
   const options = normalizeBulkOperationOptions(maybeOptions ?? {});

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

@@ -58,7 +58,7 @@ import {
 export function createChildWorkflowOperationCallbacks(engine) {
   return {
     runOperationWithResult: (workflowId, operation, execute) => runOperationWithResultForEngine(engine, workflowId, operation, execute),
-    start: (type, input, options) => startWorkflow(getInternals(engine), type, input, options, void 0, createLifecycleCallbacks(engine)),
+    start: (type, input, options, skipAdmissionIdCheck) => startWorkflow(getInternals(engine), type, input, options, void 0, createLifecycleCallbacks(engine), void 0, void 0, skipAdmissionIdCheck),
     loadWorkflowState: (workflowId) => loadWorkflowState(getInternals(engine), workflowId),
     getHandle: (workflowId) => engine.getHandle(workflowId),
     getComposedWorkflowInterceptor: () => getComposedWorkflowInterceptor(getInternals(engine))

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

@@ -20,8 +20,8 @@ import { feedOperationResult } from "./strategy-helpers.js";
 import { ensureTerminalCleanupTracked, failWorkflow, handleCleanupError } from "./termination.js";
 export function createScheduleCallbacks(engine) {
   return {
-    startWorkflow: async (type, input, options, additionalStartOperations, revisionOverride) => {
-      await startWorkflow(getInternals(engine), type, input, options, additionalStartOperations, createLifecycleCallbacks(engine), void 0, revisionOverride);
+    startWorkflow: async (type, input, options, additionalStartOperations, revisionOverride, skipAdmissionIdCheck) => {
+      await startWorkflow(getInternals(engine), type, input, options, additionalStartOperations, createLifecycleCallbacks(engine), void 0, revisionOverride, skipAdmissionIdCheck);
     },
     loadWorkflowState: (workflowId) => loadWorkflowState(getInternals(engine), workflowId),
     cancelWorkflow: (workflowId) => engine.cancel(workflowId),

package/dist/core/engine/child-workflow.d.ts

@@ -8,7 +8,19 @@ type ChildWorkflowOperation = Extract<ContextOperationRequest, {
 }>;
 export type ChildWorkflowOperationCallbacks = {
     runOperationWithResult: (workflowId: string, operation: ChildWorkflowOperation, execute: () => Promise<unknown>) => Promise<void>;
-    start: (type: string, input: unknown, options?: StartOptions) => Promise<WorkflowHandle>;
+    /**
+     * `skipAdmissionIdCheck` (WFT-95, internal only) is threaded straight through
+     * to `startWorkflow`'s parameter of the same name — see its doc comment. It
+     * is NEVER part of the public `StartOptions` a caller passes; only
+     * `dispatchChildWorkflowStart`'s crash-reattach retry sets it, and only
+     * after confirming a matching persisted child record already exists for
+     * `childWorkflowId`. This retry always passes the literal `'reattach-only'`,
+     * not `true`: the confirming read here is separate from
+     * `startWorkflow`'s own atomic re-check, so `'reattach-only'` fences the
+     * bypass to that re-check actually finding a match to reattach to (see
+     * `startWorkflow`'s doc comment for the full TOCTOU race this closes).
+     */
+    start: (type: string, input: unknown, options?: StartOptions, skipAdmissionIdCheck?: boolean | 'reattach-only') => Promise<WorkflowHandle>;
     loadWorkflowState: (workflowId: string) => Promise<WorkflowState | null>;
     getHandle: (workflowId: string) => WorkflowHandle;
     getComposedWorkflowInterceptor: () => ComposedWorkflowInterceptor | null;

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

@@ -1,4 +1,8 @@
-import { assertOnTerminalConflictUnsupported } from "../start-workflow-validation.js";
+import {
+  assertOnTerminalConflictUnsupported,
+  StartWorkflowValidationError
+} from "../start-workflow-validation.js";
+import { isReservedWorkflowIdLiteral } from "../workflow-identifiers.js";
 import { stageAtomicWorkflowCommitSideEffects } from "./checkpoint-side-effects.js";
 import {
   buildChildCancellationOperations,
@@ -50,6 +54,18 @@ async function resolveCollisionChildHandle(childWorkflowId, operation, execution
     throw Error(`Child workflow id collision for "${childWorkflowId}" does not match the requested child workflow`, { cause: collisionError });
   return callbacks.getHandle(childWorkflowId);
 }
+async function reattachLegacyReservedChildOrRethrow(childWorkflowId, operation, context, callbacks, originalError) {
+  const existingState = await callbacks.loadWorkflowState(childWorkflowId);
+  if (!existingState || !existingChildMatchesRequest(existingState, operation, context.pendingExecutionStateOwnerId ?? void 0, context.pendingParentWorkflowId, context.pendingParentWorkflowExecutionToken))
+    throw originalError;
+  try {
+    return await callbacks.start(operation.workflowType, operation.input, { id: childWorkflowId }, "reattach-only");
+  } catch (retryError) {
+    if (!(retryError instanceof WorkflowAlreadyExistsError))
+      throw retryError;
+    return resolveCollisionChildHandle(childWorkflowId, operation, context.pendingExecutionStateOwnerId ?? void 0, context.pendingParentWorkflowId, context.pendingParentWorkflowExecutionToken, retryError, callbacks);
+  }
+}
 async function dispatchChildWorkflowStart(internals, childWorkflowId, operation, context, callbacks) {
   assertOnTerminalConflictUnsupported(operation.options, "ctx.startChild");
   applyPendingChildExecutionContext(internals, context);
@@ -58,9 +74,11 @@ async function dispatchChildWorkflowStart(internals, childWorkflowId, operation,
       id: childWorkflowId
     });
   } catch (error) {
-    if (!(error instanceof WorkflowAlreadyExistsError))
-      throw error;
-    return resolveCollisionChildHandle(childWorkflowId, operation, context.pendingExecutionStateOwnerId ?? void 0, context.pendingParentWorkflowId, context.pendingParentWorkflowExecutionToken, error, callbacks);
+    if (error instanceof WorkflowAlreadyExistsError)
+      return resolveCollisionChildHandle(childWorkflowId, operation, context.pendingExecutionStateOwnerId ?? void 0, context.pendingParentWorkflowId, context.pendingParentWorkflowExecutionToken, error, callbacks);
+    if (error instanceof StartWorkflowValidationError && isReservedWorkflowIdLiteral(childWorkflowId))
+      return reattachLegacyReservedChildOrRethrow(childWorkflowId, operation, context, callbacks, error);
+    throw error;
   } finally {
     clearPendingChildExecutionContext(internals, context);
   }

package/dist/core/engine/generation-codec.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Pure codec for the durable per-workflow-id generation counter
+ * (`wf-gen:<id>`, WFT-153).
+ *
+ * Reuses `lease-codec.ts`'s `encodeEpoch`/`decodeEpoch` under
+ * generation-specific names rather than reimplementing them: both are
+ * permanently-retained monotonic uint64 counters minted the same way
+ * (`(observed ?? 0) + 1`, never a literal), so sharing one encoder/decoder
+ * keeps their on-disk representation byte-identical and their validity range
+ * ([1, MAX_SAFE_INTEGER)) — fail-closed on corruption — in lockstep by
+ * construction rather than by convention.
+ *
+ * @module core/engine/generation-codec
+ */
+import { decodeEpoch, encodeEpoch } from './lease-codec.ts';
+/** Encode an 8-byte big-endian uint64 generation. See `lease-codec.ts#encodeEpoch`. */
+export declare const encodeGeneration: typeof encodeEpoch;
+/**
+ * Decode an 8-byte big-endian uint64 generation, or `null` when the stored
+ * value is not a usable generation. See `lease-codec.ts#decodeEpoch`.
+ */
+export declare const decodeGeneration: typeof decodeEpoch;

package/dist/core/engine/generation-codec.js

@@ -0,0 +1,2 @@
+import { decodeEpoch, encodeEpoch } from "./lease-codec.js";
+export const encodeGeneration = encodeEpoch, decodeGeneration = decodeEpoch;

package/dist/core/engine/index.js

@@ -847,7 +847,7 @@ export class Engine extends EventTarget {
     return cancelAllWorkflows(getInternals(this), filter, options);
   }
   async retryFailedAll(filter, options) {
-    return retryFailedAllWorkflows(getInternals(this), filter, options);
+    return retryFailedAllWorkflows(getInternals(this), filter, options, this.#createLifecycleCallbacks());
   }
   async signalAll(filter, name, payloadOrOptions, options) {
     if (options === void 0)

package/dist/core/engine/lifecycle/recovery-isolation.d.ts

@@ -0,0 +1,20 @@
+/**
+ * `recoverAll()`'s per-entry error isolation — split out of `transition.ts`,
+ * which has no headroom under this repository's 500-line implementation-file
+ * ceiling for the WFT-134 claim-release wrapping `recoverEntryOrIsolateFailure`
+ * needed (mirrors `resume-body.ts`'s same split). This file's own job is just
+ * the branch-matching: given the error `resume()` rejected with, either
+ * isolate it to just this workflow (returning `null`) or rethrow it.
+ *
+ * @module core/engine/lifecycle/recovery-isolation
+ */
+import type { WorkflowHandle } from '../handles.ts';
+import type { LifecycleCallbacks, RecoverAllOptions } from './shared.ts';
+/**
+ * Isolate one `recoverAll()` entry's failure to just this workflow when it
+ * matches a known-recoverable error, committing the matching `failWorkflowForXxx`
+ * fenced write; rethrows anything else, including an opted-in
+ * `VersionMismatchError` throw. See `transition.ts`'s `recoverEntryOrIsolateFailure`
+ * for the caller-side claim-release wrapping around this.
+ */
+export declare function isolateRecoveryFailure(workflowId: string, callbacks: LifecycleCallbacks, options: RecoverAllOptions | undefined, error: unknown): Promise<WorkflowHandle | null>;

package/dist/core/engine/lifecycle/recovery-isolation.js

@@ -0,0 +1,26 @@
+import { RegExpExtensionDecodeError } from "../../codec/extension-codec.js";
+import { VersionMismatchError } from "../../versioning.js";
+import { DynamicWorkflowSourceUnavailableError } from "../dynamic-source-errors.js";
+import { WorkflowClaimUnavailableError } from "../lease-errors.js";
+import { WorkflowRevisionUnavailableError } from "../revision-errors.js";
+export async function isolateRecoveryFailure(workflowId, callbacks, options, error) {
+  if (error instanceof RegExpExtensionDecodeError) {
+    await callbacks.failWorkflowForCheckpointDecodeError(workflowId, error);
+    return null;
+  }
+  if (error instanceof VersionMismatchError && options?.versionMismatchPolicy !== "throw") {
+    await callbacks.failWorkflowForVersionMismatch(workflowId, error);
+    return null;
+  }
+  if (error instanceof WorkflowClaimUnavailableError)
+    return null;
+  if (error instanceof WorkflowRevisionUnavailableError) {
+    await callbacks.failWorkflowForRevisionUnavailable(workflowId, error);
+    return null;
+  }
+  if (error instanceof DynamicWorkflowSourceUnavailableError) {
+    await callbacks.failWorkflowForUnavailableDynamicSource(workflowId, error);
+    return null;
+  }
+  throw error;
+}

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

@@ -0,0 +1,44 @@
+/**
+ * `resumeWorkflowFromStorage()`'s guts — split out of `resume.ts`, which has
+ * no headroom under the repository's 500-line implementation-file ceiling
+ * for the WFT-134 claim-release wrapping added around this logic (mirrors
+ * `resume-generation-guard.ts`'s same split). `resume.ts` itself is now just
+ * the public entry point: load/validate state, acquire a claim if needed,
+ * and call {@link performResumeAfterClaimAcquired} below inside the
+ * claim-release `try`/`catch`.
+ *
+ * @module core/engine/lifecycle/resume-body
+ */
+import { type EventHeadRecord } from '../../event-log.ts';
+import type { Checkpoint, WorkflowState } from '../../types.ts';
+import { type WorkflowVersionTuple } from '../../workflow-version-tuple.ts';
+import { type WorkflowHandle } from '../handles.ts';
+import type { EngineInternals } from '../internals.ts';
+import { deriveResumeGeneration } from './resume-generation-guard.ts';
+import { type LifecycleCallbacks, type RecoverAllOptions, type RegistrationEntry } from './shared.ts';
+export type SerializedResumeArgs = {
+    workflowId: string;
+    resumeCheckpoint: Checkpoint;
+    serializedCheckpoint: Uint8Array;
+    registeredVersionTuple: WorkflowVersionTuple;
+    restoredHead: EventHeadRecord;
+    workflowStartHeaders: Map<string, string> | undefined;
+    registration: RegistrationEntry;
+    /**
+     * The EXACT revision `registration` resolved against, NOT `state.revision`
+     * re-read independently (WFT-19 round 5): a legacy record with one registered
+     * candidate has `state.revision === undefined` even though the resolver
+     * resolved it — caching `state.revision` here would disable exact-revision lookup.
+     */
+    resolvedRevision: string | undefined;
+    expectedGeneration: ReturnType<typeof deriveResumeGeneration>;
+    callbacks: LifecycleCallbacks;
+};
+/**
+ * Everything `resumeWorkflowFromStorage` does once a claim (if any) is
+ * acquired: load tracking/checkpoint/registration state, prepare the resume,
+ * and either relaunch inline or in a worker. `resumeWorkflowFromStorage`
+ * itself just wraps a call to this in the WFT-134 claim-release
+ * `try`/`catch`.
+ */
+export declare function performResumeAfterClaimAcquired(internals: EngineInternals, workflowId: string, state: WorkflowState, dispatchResumedEvent: boolean, callbacks: LifecycleCallbacks, onRecoveredWorkflow?: RecoverAllOptions['onRecoveredWorkflow']): Promise<WorkflowHandle>;

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

@@ -0,0 +1,211 @@
+import { KEYS } from "../../../storage/interface.js";
+import { deserializeCheckpoint, serializeCheckpoint } from "../../checkpoint.js";
+import { encode } from "../../codec.js";
+import { Context, setContextWorkflowInterceptor } from "../../context.js";
+import { EventLog } from "../../event-log.js";
+import { WorkflowResumedEvent } from "../../events.js";
+import { buildTimerBatchOperations } from "../../scheduler.js";
+import { createCancelHandlerRegistration, resetCancelHandlers } from "../cancel-handlers.js";
+import { rememberCommittedCheckpointBytes } from "../checkpoint-commit-snapshots.js";
+import { rehydrateChildCancellationHandlers } from "../child-workflow-cancellation.js";
+import { resolveExecutableRegistrationOrRenamedNotFound } from "../dynamic-source-execution.js";
+import { commitFencedEngineWrite } from "../fenced-write.js";
+import { getWorkflowExecutionStartedAt } from "../handles.js";
+import { loadWorkflowState } from "../storage-io.js";
+import { getComposedWorkflowInterceptor } from "../strategy-helpers.js";
+import { buildWorkflowVisibilityIndexTransition } from "../workflow-indexes.js";
+import { prepareResumeState } from "./persist.js";
+import {
+  reprovideRecoveredServices,
+  workflowServicesResolverInfoFromState
+} from "./recovered-services.js";
+import { assertSameGeneration, deriveResumeGeneration } from "./resume-generation-guard.js";
+import {
+  enforceHistoryPolicyBeforeReplay,
+  loadTerminalCleanupTrackedState,
+  loadWorkflowStartHeaders,
+  setWorkflowStartHeaders
+} from "./shared.js";
+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))
+    throw Error(`Cannot resume workflow "${workflowId}": termination is in progress`);
+}
+function commitSerializedResumeState(internals, args) {
+  const {
+    workflowId,
+    resumeCheckpoint,
+    serializedCheckpoint,
+    registeredVersionTuple,
+    restoredHead,
+    callbacks
+  } = args;
+  internals.checkpoints.set(workflowId, resumeCheckpoint);
+  rememberCommittedCheckpointBytes(internals, workflowId, serializedCheckpoint);
+  internals.workflowVersionTuples.set(workflowId, registeredVersionTuple);
+  internals.eventLogHeads.set(workflowId, restoredHead);
+  setWorkflowStartHeaders(internals, workflowId, args.workflowStartHeaders, callbacks);
+  internals.parkedInlineWorkflows.delete(workflowId);
+}
+async function relaunchInlineWorkflowAfterResume(internals, latestState, args) {
+  const { workflowId, resumeCheckpoint, registration, resolvedRevision, callbacks } = args, accumulatedResults = new Map(resumeCheckpoint.accumulatedResults), workflowAbort = new AbortController;
+  internals.workflowTypeByWorkflowId.set(workflowId, {
+    type: latestState.type,
+    revision: resolvedRevision
+  });
+  resetCancelHandlers(internals, workflowId);
+  await rehydrateChildCancellationHandlers(internals, workflowId, callbacks);
+  const context = new Context({
+    workflowId,
+    ...latestState.workflowExecutionToken !== void 0 && {
+      workflowExecutionToken: latestState.workflowExecutionToken
+    },
+    workflowType: latestState.type,
+    startedAt: getWorkflowExecutionStartedAt(latestState),
+    abortController: workflowAbort,
+    getNow: internals.options.getNow,
+    resolveWorkflowType: callbacks.resolveWorkflowTypeTarget,
+    executionStateOwnerId: latestState.executionStateOwnerId ?? workflowId,
+    accumulatedResults,
+    locals: resumeCheckpoint.locals,
+    searchAttributes: resumeCheckpoint.searchAttributes,
+    registerCancelHandler: createCancelHandlerRegistration(internals, workflowId),
+    ...registration.searchAttributes && {
+      searchAttributeSchema: registration.searchAttributes
+    },
+    sleepReferenceTime: resumeCheckpoint.createdAt,
+    ...latestState.executionDeadline !== void 0 && {
+      deadline: latestState.executionDeadline
+    },
+    services: internals.workflowServices.get(workflowId),
+    ...internals.options.onLog != null && { logSink: internals.options.onLog }
+  });
+  setContextWorkflowInterceptor(context, getComposedWorkflowInterceptor(internals));
+  if (internals.options.development)
+    context.explain(!0);
+  const generator = registration.handler(context, latestState.input), inlineStrategy = internals.inlineStrategy;
+  inlineStrategy.adoptWorkflow(workflowId, generator, context, workflowAbort);
+  inlineStrategy.continueWorkflow(workflowId, void 0);
+}
+async function relaunchWorkerWorkflowAfterResume(internals, latestState, args) {
+  const { workflowId, resumeCheckpoint, workflowStartHeaders, resolvedRevision, callbacks } = args;
+  internals.workflowTypeByWorkflowId.set(workflowId, {
+    type: latestState.type,
+    revision: resolvedRevision
+  });
+  resetCancelHandlers(internals, workflowId);
+  await rehydrateChildCancellationHandlers(internals, workflowId, callbacks);
+  const serialized = serializeCheckpoint(resumeCheckpoint);
+  internals.strategy.startWorkflow({
+    workflowId,
+    ...latestState.workflowExecutionToken !== void 0 && {
+      workflowExecutionToken: latestState.workflowExecutionToken
+    },
+    workflowType: latestState.type,
+    input: latestState.input,
+    checkpoint: serialized,
+    nestingDepth: internals.workflowNestingDepths.get(workflowId) ?? 0,
+    executionStateOwnerId: latestState.executionStateOwnerId ?? workflowId,
+    ...latestState.executionDeadline !== void 0 && {
+      deadline: latestState.executionDeadline
+    },
+    ...workflowStartHeaders !== void 0 && workflowStartHeaders.size > 0 && {
+      headers: [...workflowStartHeaders]
+    }
+  });
+}
+async function reactivateSuspendedWorkflowState(internals, state) {
+  if (state.status !== "suspended")
+    return;
+  const previousState = { ...state };
+  state.status = "running";
+  state.updatedAt = internals.options.getNow();
+  await commitFencedEngineWrite(internals, state.id, [
+    { type: "put", key: KEYS.workflow(state.id), value: encode(state) },
+    ...buildWorkflowVisibilityIndexTransition(state.id, previousState, state).batchOps,
+    ...state.executionDeadline !== void 0 ? buildTimerBatchOperations({
+      id: `deadline:${state.id}`,
+      workflowId: state.id,
+      fireAt: state.executionDeadline,
+      kind: "execution-deadline"
+    }) : []
+  ], [], () => Error(`Resume of workflow "${state.id}" lost its CAS race.`));
+}
+async function performSerializedResume(internals, args) {
+  const { workflowId } = args;
+  assertResumeNotTerminating(internals, workflowId);
+  const latestState = await loadWorkflowState(internals, workflowId);
+  assertResumeNotTerminating(internals, workflowId);
+  if (!latestState)
+    throw Error(`Workflow "${workflowId}" not found in storage`);
+  if (latestState.status !== "running" && latestState.status !== "suspended")
+    throw Error(`Cannot resume workflow "${workflowId}": status is "${latestState.status}", expected "running" or "suspended"`);
+  assertSameGeneration(workflowId, latestState, args.expectedGeneration);
+  await reactivateSuspendedWorkflowState(internals, latestState);
+  commitSerializedResumeState(internals, args);
+  if (internals.inlineStrategy) {
+    await relaunchInlineWorkflowAfterResume(internals, latestState, args);
+    return;
+  }
+  await relaunchWorkerWorkflowAfterResume(internals, latestState, args);
+}
+export async function performResumeAfterClaimAcquired(internals, workflowId, state, dispatchResumedEvent, callbacks, onRecoveredWorkflow) {
+  await loadTerminalCleanupTrackedState(internals, workflowId, callbacks);
+  const checkpointBytes = await internals.storage.get(KEYS.checkpoint(workflowId));
+  if (!checkpointBytes)
+    throw Error(`Checkpoint not found for workflow "${workflowId}"`);
+  const checkpoint = deserializeCheckpoint(checkpointBytes), { entry: registration, revision: resolvedRevision } = await resolveExecutableRegistrationOrRenamedNotFound((type) => callbacks.resolveExecutableRegistrationForRevision(type, state.revision), state.type, () => Error(`No workflow registered with name "${state.type}" (needed to resume "${workflowId}")`)), preparedResumeState = await prepareResumeState(internals, workflowId, state, checkpoint, checkpointBytes, registration, callbacks), resumeCheckpoint = preparedResumeState.checkpoint, registeredVersionTuple = preparedResumeState.versionTuple, restoredHead = await new EventLog(internals.storage, workflowId).loadHead();
+  if (await enforceHistoryPolicyBeforeReplay(internals, workflowId, restoredHead, callbacks))
+    return callbacks.getHandle(workflowId);
+  const workflowStartHeaders = await loadWorkflowStartHeaders(internals, workflowId, callbacks), { handle, shouldStop } = await prepareRecoveredWorkflowOrFail(internals, state, callbacks, onRecoveredWorkflow);
+  if (shouldStop)
+    return handle;
+  await callbacks.runSerializedWorkflowStateWrite(workflowId, () => performSerializedResume(internals, {
+    workflowId,
+    resumeCheckpoint,
+    serializedCheckpoint: preparedResumeState.serializedCheckpoint,
+    registeredVersionTuple,
+    restoredHead,
+    workflowStartHeaders,
+    registration,
+    resolvedRevision,
+    expectedGeneration: deriveResumeGeneration(state),
+    callbacks
+  }));
+  if (dispatchResumedEvent)
+    callbacks.dispatchEvent(new WorkflowResumedEvent(workflowId, resumeCheckpoint.step));
+  if (internals.inlineStrategy)
+    callbacks.swallowPromiseRejection(callbacks.processPendingUpdatesAfterInlineAdvance(workflowId));
+  return handle;
+}