@lostgradient/weft 0.24.0 → 0.24.2

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/recovery-revision-groups.d.ts

@@ -0,0 +1,75 @@
+/**
+ * `recoverAll()`'s per-`(type, revision)` preload barrier (WFT-17/WFT-18),
+ * replacing the per-`type`-only barrier `recovery-dynamic-sources.ts` used
+ * to own. Split out of `transition.ts`, which has no headroom under the
+ * repository's 500-line implementation-file ceiling for this logic inline
+ * — the same reason `recovery-dynamic-sources.ts` was split out for
+ * WFT-15/16.
+ *
+ * Recovery scans non-terminal workflow states, groups them by their exact
+ * `(type, revision)` pin (a legacy record with no persisted `revision`
+ * groups under `undefined` for its type), and preloads/classifies every
+ * group BEFORE any group's runs advance — ready, or unavailable with the
+ * error every run in that group fails with. Grouping and classification use
+ * nested `Map<type, Map<revision, …>>` structures rather than a
+ * delimiter-joined composite key, so an arbitrary workflow `type` or
+ * `revision` string can never collide with a delimiter.
+ *
+ * @module core/engine/lifecycle/recovery-revision-groups
+ */
+import { DynamicWorkflowSourceUnavailableError } from '../dynamic-source-errors.ts';
+import type { EngineInternals } from '../internals.ts';
+import { WorkflowRevisionUnavailableError } from '../revision-errors.ts';
+import type { LifecycleCallbacks } from './shared.ts';
+/** One preflight-recoverable entry's identity, as `transition.ts`'s preflight scan produces it. */
+export type RecoverableRevisionEntry = {
+    readonly workflowId: string;
+    readonly type: string;
+    readonly revision: string | undefined;
+};
+/** One `(type, revision)` group: every non-terminal run pinned to that exact revision. */
+export type RecoveryRevisionGroup = {
+    readonly type: string;
+    readonly revision: string | undefined;
+    readonly workflowIds: readonly string[];
+};
+/** `type -> revision -> group`. A legacy entry (no persisted `revision`) groups under the `undefined` key. */
+export type RecoveryRevisionGroups = ReadonlyMap<string, ReadonlyMap<string | undefined, RecoveryRevisionGroup>>;
+/**
+ * Group preflight-recoverable entries by their exact `(type, revision)` pin.
+ * Every non-terminal run pinned to the same revision of the same type lands
+ * in one group, regardless of scan order.
+ */
+export declare function buildRecoveryRevisionGroups(entries: readonly RecoverableRevisionEntry[]): RecoveryRevisionGroups;
+/** Outcome of classifying one `(type, revision)` group. */
+export type RevisionGroupClassification = {
+    readonly status: 'ready';
+} | {
+    readonly status: 'unavailable';
+    readonly error: WorkflowRevisionUnavailableError | DynamicWorkflowSourceUnavailableError;
+};
+/** `type -> revision -> classification`, mirroring {@link RecoveryRevisionGroups}'s shape. */
+export type RevisionGroupClassifications = ReadonlyMap<string, ReadonlyMap<string | undefined, RevisionGroupClassification>>;
+/**
+ * Resolve every `(type, revision)` group to `'ready'` or `'unavailable'`,
+ * concurrently, one `resolveExecutableRegistrationForRevision()` call per
+ * group — even when many non-terminal runs share the same pin. An eager
+ * type's groups are omitted from the result entirely (eager is always
+ * ready and needs no preload call); only dynamic-source groups are
+ * classified. A disposal mid-preload aborts the whole barrier by
+ * rethrowing, matching `recoverEntryOrIsolateFailure`'s own un-isolated
+ * treatment of {@link EngineDisposedError}.
+ */
+export declare function classifyRevisionGroups(internals: EngineInternals, callbacks: LifecycleCallbacks, groups: RecoveryRevisionGroups): Promise<RevisionGroupClassifications>;
+/**
+ * Wrap `callbacks` so `recoverAll()`'s own per-entry `resume()` calls below
+ * see a batch's cached `classifyRevisionGroups()` failure for the entry's
+ * `(type, revision)` group, WITHOUT touching any state shared with other
+ * callers. `classifications` is a plain, closure-local `Map` structure —
+ * nothing outside `recoverAll()` ever sees it, so a concurrent, unrelated
+ * `engine.start()`, `engine.resume()`, or a second concurrent `recoverAll()`
+ * batch for the SAME `(type, revision)` keeps using the real, un-wrapped
+ * `callbacks.resolveExecutableRegistrationForRevision` and can never observe
+ * (or race the reset of) this batch's classification.
+ */
+export declare function createRecoveryScopedRevisionCallbacks(callbacks: LifecycleCallbacks, classifications: RevisionGroupClassifications): LifecycleCallbacks;

package/dist/core/engine/lifecycle/recovery-revision-groups.js

@@ -0,0 +1,64 @@
+import { DynamicWorkflowSourceUnavailableError } from "../dynamic-source-errors.js";
+import { EngineDisposedError } from "../errors.js";
+import { WorkflowRevisionUnavailableError } from "../revision-errors.js";
+export function buildRecoveryRevisionGroups(entries) {
+  const groups = new Map;
+  for (const entry of entries) {
+    let byRevision = groups.get(entry.type);
+    if (byRevision === void 0) {
+      byRevision = new Map;
+      groups.set(entry.type, byRevision);
+    }
+    const existing = byRevision.get(entry.revision);
+    if (existing === void 0)
+      byRevision.set(entry.revision, {
+        type: entry.type,
+        revision: entry.revision,
+        workflowIds: [entry.workflowId]
+      });
+    else
+      existing.workflowIds.push(entry.workflowId);
+  }
+  return groups;
+}
+export async function classifyRevisionGroups(internals, callbacks, groups) {
+  const dynamicGroups = [];
+  for (const [type, byRevision] of groups) {
+    if (internals.registrations.has(type))
+      continue;
+    dynamicGroups.push(...byRevision.values());
+  }
+  const results = new Map;
+  if (dynamicGroups.length === 0)
+    return results;
+  const settled = await Promise.allSettled(dynamicGroups.map((group) => callbacks.resolveExecutableRegistrationForRevision(group.type, group.revision)));
+  for (const [index, outcome] of settled.entries()) {
+    const group = dynamicGroups[index];
+    let byRevision = results.get(group.type);
+    if (byRevision === void 0) {
+      byRevision = new Map;
+      results.set(group.type, byRevision);
+    }
+    if (outcome.status === "fulfilled") {
+      byRevision.set(group.revision, { status: "ready" });
+      continue;
+    }
+    const reason = outcome.reason;
+    if (reason instanceof EngineDisposedError)
+      throw reason;
+    const error = reason instanceof WorkflowRevisionUnavailableError || reason instanceof DynamicWorkflowSourceUnavailableError ? reason : new DynamicWorkflowSourceUnavailableError(group.type, group.revision, "load-failed", reason);
+    byRevision.set(group.revision, { status: "unavailable", error });
+  }
+  return results;
+}
+export function createRecoveryScopedRevisionCallbacks(callbacks, classifications) {
+  return {
+    ...callbacks,
+    resolveExecutableRegistrationForRevision: (type, revision) => {
+      const classification = classifications.get(type)?.get(revision);
+      if (classification?.status === "unavailable")
+        return Promise.reject(classification.error);
+      return callbacks.resolveExecutableRegistrationForRevision(type, revision);
+    }
+  };
+}

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

package/dist/core/engine/lifecycle/resume-generation-guard.d.ts

@@ -0,0 +1,58 @@
+/**
+ * `resumeWorkflowFromStorage()`'s generation-identity re-check (WFT-19
+ * review round 7, chatgpt-codex-connector + stevekinney) — split out of
+ * `resume.ts`, which has no headroom under the repository's 500-line
+ * implementation-file ceiling for this doc-heavy addition.
+ *
+ * @module core/engine/lifecycle/resume-generation-guard
+ */
+import type { WorkflowState } from '../../types.ts';
+/**
+ * The generation a resume's `registration`/`resumeCheckpoint`/`resolvedRevision`
+ * were all resolved against — captured from the SAME `WorkflowState` decoded
+ * at the very top of `resumeWorkflowFromStorage()`, before
+ * `acquireStandaloneClaimBeforeResume`, the checkpoint load, and registration
+ * resolution all ran.
+ *
+ * `performSerializedResume()` re-reads workflow state fresh inside its
+ * serialized section but (before this guard existed) only re-checked
+ * `status` — never identity. An `onTerminalConflict: 'start-new'`
+ * replacement landing on this SAME `workflowId` between the top-of-function
+ * read and the serialized section's fresh read (e.g. a concurrent
+ * cancel/timeout terminalizes this run, then a fresh `start()` call replaces
+ * it) purges the old record and writes a brand-new one — new
+ * `type`/`revision` possibly, and ALWAYS a fresh `workflowExecutionToken`
+ * (`crypto.randomUUID()`, minted by every `start()` — see
+ * `start-state.ts`'s `buildInitialIdentitySlice`). Without
+ * {@link assertSameGeneration}, the stale `registration`/
+ * `resumeCheckpoint` a resume closure already built would replay against the
+ * replacement's fresh state: `commitSerializedResumeState` populates
+ * `internals.checkpoints` from the OLD checkpoint, and
+ * `relaunchInlineWorkflowAfterResume` drives the OLD handler — silently
+ * corrupting the replacement's run.
+ *
+ * A DIFFERENT engine's replacement is additionally caught earlier, by
+ * `acquireStandaloneClaimBeforeResume`'s durable `wakeOwnershipCheck`
+ * (workflow-lease mode only) — but that check compares only holder
+ * identity/epoch, never workflow identity, so a SAME-engine replacement
+ * (whose fold-acquire updates this engine's own already-held claim in
+ * place, leaving the epoch check trivially satisfied) is not caught there.
+ * This guard closes that gap for every ownership mode, not just
+ * workflow-lease.
+ */
+export type ResumeGeneration = {
+    type: string;
+    revision: string | undefined;
+    workflowExecutionToken: string | undefined;
+};
+/** Captures {@link ResumeGeneration} off the `WorkflowState` a resume decoded at its top, before any `await`. */
+export declare function deriveResumeGeneration(state: WorkflowState): ResumeGeneration;
+/**
+ * Throws when `latestState` — freshly re-read inside `performSerializedResume()`'s
+ * serialized section — no longer belongs to the same generation `expected`
+ * names. See {@link ResumeGeneration}'s doc for the exact race this
+ * closes. All three fields are compared — `workflowExecutionToken` alone
+ * would miss a legacy record that carries `undefined` on both sides of the
+ * race.
+ */
+export declare function assertSameGeneration(workflowId: string, latestState: WorkflowState, expected: ResumeGeneration): void;

package/dist/core/engine/lifecycle/resume-generation-guard.js

@@ -0,0 +1,11 @@
+export function deriveResumeGeneration(state) {
+  return {
+    type: state.type,
+    revision: state.revision,
+    workflowExecutionToken: state.workflowExecutionToken
+  };
+}
+export function assertSameGeneration(workflowId, latestState, expected) {
+  if (latestState.workflowExecutionToken !== expected.workflowExecutionToken || latestState.type !== expected.type || latestState.revision !== expected.revision)
+    throw Error(`Cannot resume workflow "${workflowId}": its persisted state changed generation (a replacement run landed at this same id) between resume's registration lookup ` + "and its serialized commit \u2014 retry against the new generation instead of replaying " + "stale state.");
+}

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

@@ -1,4 +1,47 @@
-import { type WorkflowHandle } from '../handles.ts';
+/**
+ * `engine.resume(id)` / `recoverAll()`'s standalone-replay-from-storage entry
+ * point. The actual work — load tracking/checkpoint/registration state,
+ * prepare the resume, and relaunch inline or in a worker — lives in
+ * `resume-body.ts`'s `performResumeAfterClaimAcquired` (split out to stay
+ * under this repository's 500-line implementation-file ceiling once the
+ * WFT-134 claim-release wrapping below was added). This file's own job is
+ * just: load and validate state, acquire a claim if this run doesn't already
+ * hold one, and release a claim it freshly acquired if the resume turns out
+ * not to succeed after all — UNLESS `options.deferClaimReleaseOnRejection`
+ * asks this call to leave that claim installed for its caller instead (see
+ * {@link ResumeFromStorageOptions}).
+ *
+ * @module core/engine/lifecycle/resume
+ */
+import type { WorkflowHandle } from '../handles.ts';
 import type { EngineInternals } from '../internals.ts';
-import { type LifecycleCallbacks, type RecoverAllOptions } from './shared.ts';
-export declare function resumeWorkflowFromStorage(internals: EngineInternals, workflowId: string, dispatchResumedEvent: boolean, callbacks: LifecycleCallbacks, onRecoveredWorkflow?: RecoverAllOptions['onRecoveredWorkflow']): Promise<WorkflowHandle>;
+import type { LifecycleCallbacks, RecoverAllOptions } from './shared.ts';
+/**
+ * An out-parameter this call populates with the epoch of a claim it freshly
+ * acquired, so a caller using `deferClaimReleaseOnRejection` can release that
+ * EXACT generation itself once it is done using it (WFT-134 review round 2,
+ * issue D). Left at `{ epoch: null }` when no fresh acquisition happened —
+ * folding disabled, no registry, the cached claim matched, or acquisition
+ * itself threw `WorkflowClaimUnavailableError` before returning.
+ */
+export type FreshResumeClaimTracker = {
+    epoch: number | null;
+};
+/** Options for {@link resumeWorkflowFromStorage}. */
+export type ResumeFromStorageOptions = {
+    /**
+     * `true` for `recoverAll()`'s per-entry recovery loop (WFT-134 issue D):
+     * its own `recoverEntryOrIsolateFailure` isolates several errors into a
+     * fenced `failWorkflowForXxx()` commit that needs a freshly-acquired claim
+     * to still be installed, so this call must NOT release on rejection —
+     * instead it records the acquired epoch in `freshClaimTracker` and lets the
+     * caller release once its own isolated-failure handling is done. Default
+     * (`false`/omitted) is correct for an explicit `engine.resume()` caller,
+     * which has nothing further to do with the claim and must release
+     * immediately on any rejection.
+     */
+    deferClaimReleaseOnRejection?: boolean;
+    /** Populated with the freshly-acquired epoch, if any — see {@link FreshResumeClaimTracker}. */
+    freshClaimTracker?: FreshResumeClaimTracker;
+};
+export declare function resumeWorkflowFromStorage(internals: EngineInternals, workflowId: string, dispatchResumedEvent: boolean, callbacks: LifecycleCallbacks, onRecoveredWorkflow?: RecoverAllOptions['onRecoveredWorkflow'], options?: ResumeFromStorageOptions): Promise<WorkflowHandle>;