@lostgradient/weft 0.20.0 → 0.22.0

package/dist/core/engine/lease-deposition.d.ts

@@ -64,3 +64,135 @@ export declare const ENGINE_LEASE_LOST_WARNING_NAME = "WeftEngineLeaseLostWarnin
  * not advance in-memory state past a durable write that did not land.
  */
 export declare function handleDeposition(internals: EngineInternals): void;
+/**
+ * `name` of the operator warning emitted when `ownership: 'workflow-lease'`
+ * loses one workflow's claim — a renewal CAS failure (a successor stole the
+ * claim) or a fenced write rejected because a newer epoch now holds it. Unlike
+ * {@link ENGINE_LEASE_LOST_WARNING_NAME}, this is per-workflow, not per-engine:
+ * the rest of this engine's claimed workflows are unaffected and keep running.
+ *
+ * @example
+ * ```ts
+ * import { WORKFLOW_CLAIM_LOST_WARNING_NAME } from '@lostgradient/weft';
+ *
+ * process.on('warning', (warning) => {
+ *   if (warning.name === WORKFLOW_CLAIM_LOST_WARNING_NAME) {
+ *     console.error('lost a workflow claim', warning.message);
+ *   }
+ * });
+ * ```
+ */
+export declare const WORKFLOW_CLAIM_LOST_WARNING_NAME = "WeftWorkflowClaimLostWarning";
+/**
+ * Operator diagnostic for a lost per-workflow ownership claim under
+ * `ownership: 'workflow-lease'` (see
+ * [ADR 0002](../../../documentation/contributing/architecture-decisions/0002-multiengine-per-workflow-ownership.md)).
+ * Carries the affected `workflowId` as a real field — `process.emitWarning(message,
+ * name)` only accepts strings, so this is emitted as the warning object itself
+ * (`process.emitWarning(warning)`) rather than passed as a message, which lets
+ * consumers read `warning.workflowId` directly instead of parsing it back out
+ * of the message text.
+ *
+ * @example
+ * ```ts
+ * import { WeftWorkflowClaimLostWarning } from '@lostgradient/weft';
+ *
+ * process.on('warning', (warning) => {
+ *   if (warning instanceof WeftWorkflowClaimLostWarning) {
+ *     console.error('deposed workflow:', warning.workflowId);
+ *   }
+ * });
+ * ```
+ */
+export declare class WeftWorkflowClaimLostWarning extends Error {
+    readonly workflowId: string;
+    constructor(workflowId: string);
+}
+/**
+ * The wake path a stale in-memory resolver was discarded from, for
+ * {@link WeftWorkflowWakeDiscardedWarning}. Mirrors the `wakeOwnershipCheck`
+ * call sites named in ADR 0002: a durable timer firing, a re-evaluated
+ * `ctx.waitUntil()` condition, a delivered signal, an async-activity
+ * completion/failure, a child workflow's termination, or a deferred inline
+ * macrotask drive.
+ *
+ * @example
+ * ```ts
+ * import type { WorkflowWakeKind } from '@lostgradient/weft';
+ *
+ * const kind: WorkflowWakeKind = 'signal';
+ * void kind;
+ * ```
+ */
+export type WorkflowWakeKind = 'sleep' | 'wait-condition' | 'signal' | 'async-activity' | 'child-completion' | 'update' | 'inline-macrotask-drive';
+/**
+ * `name` of the operator warning emitted when `wakeOwnershipCheck` discards a
+ * stale in-memory wake resolver — it re-read the durable holder record and
+ * found this engine no longer holds the generation (engine id AND epoch) it
+ * parked the workflow under, so the resolver is dropped without driving the
+ * generator.
+ *
+ * @example
+ * ```ts
+ * import { WORKFLOW_WAKE_DISCARDED_WARNING_NAME } from '@lostgradient/weft';
+ *
+ * process.on('warning', (warning) => {
+ *   if (warning.name === WORKFLOW_WAKE_DISCARDED_WARNING_NAME) {
+ *     console.error('discarded a stale wake', warning.message);
+ *   }
+ * });
+ * ```
+ */
+export declare const WORKFLOW_WAKE_DISCARDED_WARNING_NAME = "WeftWorkflowWakeDiscardedWarning";
+/**
+ * Operator diagnostic emitted whenever `wakeOwnershipCheck` discards a stale
+ * in-memory wake resolver under `ownership: 'workflow-lease'` (see
+ * [ADR 0002](../../../documentation/contributing/architecture-decisions/0002-multiengine-per-workflow-ownership.md)).
+ * Carries the affected `workflowId` and the `wakeKind` that was discarded as
+ * real fields, for the same reason {@link WeftWorkflowClaimLostWarning} does —
+ * `process.emitWarning(message, name)` cannot carry structured data, so this is
+ * emitted as the warning object itself.
+ *
+ * @example
+ * ```ts
+ * import { WeftWorkflowWakeDiscardedWarning } from '@lostgradient/weft';
+ *
+ * process.on('warning', (warning) => {
+ *   if (warning instanceof WeftWorkflowWakeDiscardedWarning) {
+ *     console.error('discarded wake', warning.workflowId, warning.wakeKind);
+ *   }
+ * });
+ * ```
+ */
+export declare class WeftWorkflowWakeDiscardedWarning extends Error {
+    readonly workflowId: string;
+    readonly wakeKind: WorkflowWakeKind;
+    constructor(workflowId: string, wakeKind: WorkflowWakeKind);
+}
+/**
+ * Emit one of the two per-workflow warnings above. Injected as a seam
+ * (defaulting to `process.emitWarning(warning)`) so later stages — the claim
+ * renewal loop and `wakeOwnershipCheck` — get deterministic test coverage of
+ * their emission sites, mirroring the `warn` option
+ * {@link createSecondInstanceDetector} already takes. Unlike that seam, which
+ * is message-only because its warning name is a single fixed constant, this
+ * one takes the warning *instance* — `WeftWorkflowClaimLostWarning` and
+ * `WeftWorkflowWakeDiscardedWarning` carry different fields, so a caller
+ * filtering or asserting on a specific warning needs the real object, not a
+ * pre-flattened string.
+ */
+export type EmitWorkflowLeaseWarning = (warning: WeftWorkflowClaimLostWarning | WeftWorkflowWakeDiscardedWarning) => void;
+/**
+ * Emit {@link WeftWorkflowClaimLostWarning} for `workflowId`. `emit` defaults
+ * to `process.emitWarning(warning)`; pass a test double to assert on the
+ * emitted instance deterministically instead of scraping `process`'s global
+ * `warning` event.
+ */
+export declare function emitWorkflowClaimLostWarning(workflowId: string, emit?: EmitWorkflowLeaseWarning): void;
+/**
+ * Emit {@link WeftWorkflowWakeDiscardedWarning} for `workflowId`/`wakeKind`.
+ * `emit` defaults to `process.emitWarning(warning)`; pass a test double to
+ * assert on the emitted instance deterministically instead of scraping
+ * `process`'s global `warning` event.
+ */
+export declare function emitWorkflowWakeDiscardedWarning(workflowId: string, wakeKind: WorkflowWakeKind, emit?: EmitWorkflowLeaseWarning): void;

package/dist/core/engine/lease-deposition.js

@@ -8,3 +8,34 @@ export function handleDeposition(internals) {
   if (tearDown !== null)
     Promise.resolve().then(tearDown).catch(() => {});
 }
+export const WORKFLOW_CLAIM_LOST_WARNING_NAME = "WeftWorkflowClaimLostWarning";
+
+export class WeftWorkflowClaimLostWarning extends Error {
+  workflowId;
+  constructor(workflowId) {
+    super(`workflow "${workflowId}" lost its ownership claim: another engine now holds it at a newer epoch. This engine stops driving that workflow; the rest of its claimed workflows are unaffected.`);
+    this.name = WORKFLOW_CLAIM_LOST_WARNING_NAME;
+    this.workflowId = workflowId;
+  }
+}
+export const WORKFLOW_WAKE_DISCARDED_WARNING_NAME = "WeftWorkflowWakeDiscardedWarning";
+
+export class WeftWorkflowWakeDiscardedWarning extends Error {
+  workflowId;
+  wakeKind;
+  constructor(workflowId, wakeKind) {
+    super(`discarded a stale "${wakeKind}" wake for workflow "${workflowId}": this engine no longer holds the ownership-claim generation it parked under. The in-memory resolver is dropped without driving the generator.`);
+    this.name = WORKFLOW_WAKE_DISCARDED_WARNING_NAME;
+    this.workflowId = workflowId;
+    this.wakeKind = wakeKind;
+  }
+}
+const defaultEmitWorkflowLeaseWarning = (warning) => {
+  process.emitWarning(warning);
+};
+export function emitWorkflowClaimLostWarning(workflowId, emit = defaultEmitWorkflowLeaseWarning) {
+  emit(new WeftWorkflowClaimLostWarning(workflowId));
+}
+export function emitWorkflowWakeDiscardedWarning(workflowId, wakeKind, emit = defaultEmitWorkflowLeaseWarning) {
+  emit(new WeftWorkflowWakeDiscardedWarning(workflowId, wakeKind));
+}

package/dist/core/engine/lease-errors.d.ts

@@ -1,4 +1,5 @@
 import { WeftError } from '../weft-error.ts';
+import type { FencingOwnershipMode } from './workflow-claim-codec.ts';
 /**
  * Thrown when `ownership: 'lease'` is configured and the engine cannot acquire the
  * storage lease within the configured wait window — another live instance still
@@ -82,18 +83,88 @@ export declare class EngineLeaseNotHeldError extends WeftError<'EngineLeaseNotHe
     constructor();
 }
 /**
- * Thrown internally on the durable-write path when `ownership: 'lease'` is
- * configured and a fenced write's CAS fails because the held lease epoch is
- * stale — a successor instance has taken the lease and bumped the epoch, so this
- * instance has been deposed. It is the local unwind that stops the commit from
- * advancing in-memory state past a durable write that did not land; the actual
- * "this engine is deposed" reaction (set the `deposed` flag, warn the operator,
- * tear the engine down) is driven by {@link handleDeposition} at the detection
+ * Thrown internally on the durable-write path when either fencing `ownership`
+ * mode is configured and a fenced write's CAS fails because the held epoch is
+ * stale — a successor instance has taken over, so this instance has been
+ * deposed. It is the local unwind that stops the commit from advancing
+ * in-memory state past a durable write that did not land; the actual "this
+ * engine is deposed" reaction (set the `deposed` flag, warn the operator, tear
+ * the engine down) is driven by {@link handleDeposition} at the detection
  * site, not by this error propagating — the inline strategy swallows turn
  * rejections, so the throw never reaches a handler. Internal-only: it is never
  * surfaced to user code (deposition reaches operators through the
- * `WeftEngineLeaseLostWarning` process warning).
+ * `WeftEngineLeaseLostWarning` process warning, or, under `workflow-lease`,
+ * through `WeftWorkflowClaimLostWarning`).
+ *
+ * `workflowId` is additive: under the global `ownership: 'lease'` mode
+ * deposition is store-wide and no single workflow is implicated, so existing
+ * call sites that construct `new EngineDeposedError()` with no argument keep
+ * working unchanged. Under `ownership: 'workflow-lease'`, deposition is scoped
+ * to one workflow's fenced epoch, so callers on that path supply the id and it
+ * folds into the message.
  */
 export declare class EngineDeposedError extends WeftError<'EngineDeposedError'> {
-    constructor();
+    readonly workflowId: string | undefined;
+    constructor(workflowId?: string);
+}
+/**
+ * Thrown when an explicit, single-workflow public API — {@link Engine.resume},
+ * or a per-workflow step inside a bulk operation — loses the `acquire`,
+ * `takeover`, or standalone-resume CAS for a workflow's ownership claim under
+ * `ownership: 'workflow-lease'`, because another engine still holds a live,
+ * unexpired claim on it. Never thrown from background scanning: `recoverAll`
+ * and the scheduler tick isolate the loss to that one workflow and continue
+ * with the rest of the sweep, exactly as a background scan skips a workflow it
+ * cannot acquire rather than failing the whole pass.
+ *
+ * Like the other lease errors in this module, this does not carry a stable
+ * {@link WeftErrorCode} — match by `instanceof` rather than `.code`.
+ *
+ * @example
+ * ```ts
+ * import { WorkflowClaimUnavailableError } from '@lostgradient/weft';
+ *
+ * function isClaimContested(error: unknown): boolean {
+ *   return error instanceof WorkflowClaimUnavailableError;
+ * }
+ * ```
+ */
+export declare class WorkflowClaimUnavailableError extends WeftError<'WorkflowClaimUnavailableError'> {
+    readonly workflowId: string;
+    readonly heldBy: string | null;
+    constructor(workflowId: string, heldBy: string | null);
+}
+/**
+ * Thrown at engine construction when Gate 2 (the store-wide
+ * `ownership-mode-marker` check) finds the store already stamped with a
+ * different fencing mode than this engine is configured with. Fired
+ * immediately after Gate 1 (storage `conditionalBatch` capability) passes, for
+ * `ownership: 'lease'` or `ownership: 'workflow-lease'` — `ownership: 'none'`
+ * engines never touch the marker. Raised before `recoverAll()` or any storage
+ * write beyond the marker read/CAS attempt, so construction fails closed
+ * rather than letting two incompatible fencing modes coexist against one
+ * store.
+ *
+ * Unlike the other lease errors in this module, this one DOES carry a stable
+ * {@link WeftErrorCode} — it is a configuration-time boot blocker an operator
+ * needs to route and alert on, not an internal fencing unwind.
+ *
+ * @example
+ * ```ts
+ * import { OwnershipModeMismatchError } from '@lostgradient/weft';
+ *
+ * function describeMismatch(error: OwnershipModeMismatchError): string {
+ *   return `configured "${error.configuredMode}" but store is "${error.storedMode}" ` +
+ *     `(established ${new Date(error.establishedAt).toISOString()})`;
+ * }
+ * ```
+ */
+export declare class OwnershipModeMismatchError extends WeftError<'OwnershipModeMismatchError'> {
+    /** This engine's configured `ownership` option. */
+    readonly configuredMode: FencingOwnershipMode;
+    /** The fencing mode read from the store's `ownership-mode-marker`. */
+    readonly storedMode: FencingOwnershipMode;
+    /** The marker's `establishedAt` timestamp, for diagnosing when the mismatch was introduced. */
+    readonly establishedAt: number;
+    constructor(configuredMode: FencingOwnershipMode, storedMode: FencingOwnershipMode, establishedAt: number);
 }

package/dist/core/engine/lease-errors.js

@@ -24,7 +24,33 @@ export class EngineLeaseNotHeldError extends WeftError {
 }
 
 export class EngineDeposedError extends WeftError {
-  constructor() {
-    super("EngineDeposedError", "Engine was deposed: a fenced durable write lost its CAS race because another instance now holds the ownership lease at a newer epoch. This engine is halting.");
+  workflowId;
+  constructor(workflowId) {
+    const scopeClause = workflowId === void 0 ? "another instance now holds the ownership lease at a newer epoch" : `another engine now holds workflow "${workflowId}"'s ownership claim at a newer epoch`;
+    super("EngineDeposedError", `Engine was deposed: a fenced durable write lost its CAS race because ${scopeClause}. This engine is halting.`);
+    this.workflowId = workflowId;
+  }
+}
+
+export class WorkflowClaimUnavailableError extends WeftError {
+  workflowId;
+  heldBy;
+  constructor(workflowId, heldBy) {
+    const heldClause = heldBy === null ? "" : ` (currently held by "${heldBy}")`;
+    super("WorkflowClaimUnavailableError", `Could not acquire the ownership claim for workflow "${workflowId}"${heldClause}. Another engine still holds a live, unexpired claim for it. Retry later, or investigate whether the holding engine has crashed without releasing (it will become eligible for takeover once its claim expires).`);
+    this.workflowId = workflowId;
+    this.heldBy = heldBy;
+  }
+}
+
+export class OwnershipModeMismatchError extends WeftError {
+  configuredMode;
+  storedMode;
+  establishedAt;
+  constructor(configuredMode, storedMode, establishedAt) {
+    super("OwnershipModeMismatchError", `This engine is configured with ownership: '${configuredMode}', but the store's ownership-mode-marker records '${storedMode}' (established at ${new Date(establishedAt).toISOString()}). Every engine sharing a store under a fencing mode must agree on that mode. Stop every engine pointed at this store, pick one mode, ` + "and restart them all \u2014 mixing modes against one store is unsafe.");
+    this.configuredMode = configuredMode;
+    this.storedMode = storedMode;
+    this.establishedAt = establishedAt;
   }
 }

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

@@ -25,6 +25,7 @@ import {
   loadWorkflowStartHeaders,
   setWorkflowStartHeaders
 } from "./shared.js";
+import { acquireStandaloneClaimBeforeResume } from "./standalone-claim-acquire.js";
 async function prepareRecoveredServicesOrFail(internals, state, callbacks, resolverInfo) {
   return reprovideRecoveredServices(internals, state, callbacks.failWorkflowForUnavailableServices, callbacks.handleCleanupError, callbacks.dispatchEvent, resolverInfo);
 }
@@ -159,7 +160,7 @@ async function reactivateSuspendedWorkflowState(internals, state) {
   const previousState = { ...state };
   state.status = "running";
   state.updatedAt = internals.options.getNow();
-  await commitFencedEngineWrite(internals, [
+  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({
@@ -177,6 +178,7 @@ export async function resumeWorkflowFromStorage(internals, workflowId, dispatchR
   const state = decodeWorkflowState(stateBytes);
   if (state.status !== "running" && state.status !== "suspended")
     throw Error(`Cannot resume workflow "${workflowId}": status is "${state.status}", expected "running" or "suspended"`);
+  await acquireStandaloneClaimBeforeResume(internals, workflowId);
   const checkpointBytes = await internals.storage.get(KEYS.checkpoint(workflowId));
   if (!checkpointBytes)
     throw Error(`Checkpoint not found for workflow "${workflowId}"`);

package/dist/core/engine/lifecycle/standalone-claim-acquire.d.ts

@@ -0,0 +1,33 @@
+/**
+ * ADR 0002 § "Two additional transitions": `acquire (standalone resume)`. A
+ * workflow found `running` OR `suspended` at recovery has no other enabling
+ * write here to fold a claim into, so this commits the acquire fragment
+ * ALONE — the one named exception to "never a standalone commit". Attempted
+ * BEFORE `prepareResumeState`, `onRecoveredWorkflow`, and generator relaunch,
+ * so no user code — and no earlier fenced write this function makes, such as
+ * the history-policy circuit breaker or a services-unavailable failure —
+ * can run without a held claim.
+ *
+ * Deliberately covers `running` and `suspended` the same way. The ADR
+ * describes `suspended` as folding `acquire` into the status flip itself
+ * (`reactivateSuspendedWorkflowState`'s commit in `resume.ts`), but the
+ * EARLIER fenced writes above need a held claim regardless of final status,
+ * so one early standalone acquire is the pragmatic shape for both — a
+ * documented deviation from that row, not an oversight.
+ *
+ * A no-op when folding does not apply (`ownership !== 'workflow-lease'`, no
+ * registry constructed yet) or when this engine already tracks a claim for
+ * `workflowId` — a parked signal-driven wake (`inline-parking.ts`) or a bulk
+ * retry that folded `acquire` into its own reactivation write before calling
+ * `resume` (`bulk-operations.ts`) — PROVIDED `wakeOwnershipCheck` confirms
+ * the durable holder still matches the cached generation. A stalled, expired
+ * engine keeps `currentEpoch(workflowId) !== null` until its next renewal
+ * CAS detects the loss; trusting the cache alone would replay the parked
+ * generator against a successor. `acquire()` itself is unsafe as the
+ * re-check (it can win the CAS against a still-valid claim), so only the
+ * durable holder is re-read (no write) and compared.
+ *
+ * @module core/engine/lifecycle/standalone-claim-acquire
+ */
+import type { EngineInternals } from '../internals.ts';
+export declare function acquireStandaloneClaimBeforeResume(internals: EngineInternals, workflowId: string): Promise<void>;

package/dist/core/engine/lifecycle/standalone-claim-acquire.js

@@ -0,0 +1,25 @@
+import { WorkflowClaimUnavailableError } from "../lease-errors.js";
+import { wakeOwnershipCheck } from "../wake-ownership-check.js";
+export async function acquireStandaloneClaimBeforeResume(internals, workflowId) {
+  if (internals.options.ownershipMode !== "workflow-lease")
+    return;
+  const registry = internals.workflowClaimRegistry;
+  if (registry === null)
+    return;
+  const cachedEpoch = registry.currentEpoch(workflowId);
+  if (cachedEpoch !== null) {
+    const check = await wakeOwnershipCheck({
+      storage: internals.storage,
+      workflowId,
+      wakeKind: "signal",
+      expectedEngineId: registry.engineId,
+      expectedEpoch: cachedEpoch
+    });
+    if (check.status === "discarded")
+      throw new WorkflowClaimUnavailableError(workflowId, check.observedEngineId);
+    return;
+  }
+  const result = await registry.acquire(workflowId);
+  if (result.status === "lost-race")
+    throw new WorkflowClaimUnavailableError(workflowId, result.heldBy);
+}

package/dist/core/engine/lifecycle/start-commit.js

@@ -4,6 +4,11 @@ import {
   commitFencedEngineWrite,
   commitFencedEngineWriteAllowingPreconditionFailure
 } from "../fenced-write.js";
+import {
+  commitWithWorkflowClaimFold,
+  prepareWorkflowClaimFold,
+  throwWorkflowClaimUnavailable
+} from "../workflow-claim-fold.js";
 import { buildStartBatchOperations } from "./start-batch.js";
 
 export class StartIdempotencyRaceLostError extends Error {
@@ -13,13 +18,20 @@ export class StartIdempotencyRaceLostError extends Error {
   }
 }
 const WORKFLOW_CONCURRENCY_ADMISSION_MAX_ATTEMPTS = 5;
-async function persistStartBatch(internals, startOperations, conditions) {
+async function persistStartBatch(internals, workflowId, startOperations, conditions, claimFold, isDelayedStart) {
+  if (claimFold) {
+    const result = await commitWithWorkflowClaimFold(internals, claimFold, startOperations, conditions.map((entry) => entry.condition), "workflow claim acquisition");
+    if (result.status === "committed")
+      return "committed";
+    return result.claimConflict ? "claim-lost" : "precondition-lost";
+  }
+  const fenceWorkflowId = isDelayedStart ? null : workflowId;
   if (conditions.length === 0) {
-    await commitFencedEngineWrite(internals, startOperations, [], () => Error("Workflow start lost its CAS race."));
-    return !0;
+    await commitFencedEngineWrite(internals, fenceWorkflowId, startOperations, [], () => Error("Workflow start lost its CAS race."));
+    return "committed";
   }
   requireStorageCapability(internals.storage, "conditionalBatch", "start preconditions");
-  return commitFencedEngineWriteAllowingPreconditionFailure(internals, startOperations, conditions.map((entry) => entry.condition));
+  return await commitFencedEngineWriteAllowingPreconditionFailure(internals, fenceWorkflowId, startOperations, conditions.map((entry) => entry.condition)) ? "committed" : "precondition-lost";
 }
 async function hasStartPreconditionConflict(internals, conditions) {
   for (const entry of conditions) {
@@ -57,11 +69,13 @@ export async function buildAndCommitStartBatch(context, buildIdempotentStartOper
     const startOperations = buildStartBatchOperations(internals, workflowId, state, checkpoint, registration, options, state.executionDeadline, context.delayedStartTimer, context.persistedWorkflowStartHeaders, mergeAdditionalStartOperations(context.additionalStartOperations, mergeAdditionalStartOperations(idempotent?.operations, workflowConcurrency?.operations)), context.callbacks, context.purgeDeleteOperations), conditions = [
       ...tagStartPreconditions(idempotent?.conditions),
       ...tagWorkflowConcurrencyConditions(workflowConcurrency?.conditions ?? [])
-    ];
-    if (await persistStartBatch(internals, startOperations, conditions))
+    ], isDelayedStart = context.delayedStartTimer !== void 0, claimFold = isDelayedStart ? void 0 : await prepareWorkflowClaimFold(internals, workflowId), outcome = await persistStartBatch(internals, workflowId, startOperations, conditions, claimFold, isDelayedStart);
+    if (outcome === "committed")
       return;
     if (await hasStartPreconditionConflict(internals, conditions))
       throw new StartIdempotencyRaceLostError;
+    if (outcome === "claim-lost")
+      return throwWorkflowClaimUnavailable(internals, workflowId);
     if (workflowConcurrency === void 0)
       throw new StartIdempotencyRaceLostError;
   }

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

@@ -3,6 +3,20 @@ import { type WorkflowHandle } from '../handles.ts';
 import type { EngineInternals } from '../internals.ts';
 import { type LifecycleCallbacks, type RecoverAllOptions, type RegistrationEntry } from './shared.ts';
 export declare function recoverAll(internals: EngineInternals, callbacks: LifecycleCallbacks, options?: RecoverAllOptions): Promise<WorkflowHandle[]>;
-export declare function resume(internals: EngineInternals, workflowId: string, callbacks: LifecycleCallbacks, onRecoveredWorkflow?: RecoverAllOptions['onRecoveredWorkflow']): Promise<WorkflowHandle>;
+/** Options for {@link resume}. */
+export type ResumeOptions = {
+    /**
+     * Skip the local-ownership fast path and always replay from durable storage.
+     *
+     * Required by ADR 0002 reclaim-driven resume: deposition drops only the
+     * registry's claim entry, so local checkpoints, parked markers, contexts and
+     * generators survive. Without this, a reclaim by the same engine returns the
+     * pre-deposition handle without reaching `resumeWorkflowFromStorage()` and
+     * renews a run that never restarted from durable state. Ordinary
+     * `engine.resume()` leaves it `false` — nothing was deposed there.
+     */
+    readonly forceReplayFromStorage?: boolean;
+};
+export declare function resume(internals: EngineInternals, workflowId: string, callbacks: LifecycleCallbacks, onRecoveredWorkflow?: RecoverAllOptions['onRecoveredWorkflow'], options?: ResumeOptions): Promise<WorkflowHandle>;
 export declare function fork(internals: EngineInternals, sourceWorkflowId: string, options: ForkOptions | undefined, callbacks: LifecycleCallbacks): Promise<WorkflowHandle>;
 export declare function launchWorkflowFromCheckpoint(internals: EngineInternals, workflowId: string, state: WorkflowState, checkpoint: Checkpoint, registration: RegistrationEntry, callbacks: LifecycleCallbacks): WorkflowHandle;

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

@@ -11,6 +11,7 @@ import { hydrateCheckpointReplayState } from "../checkpoint-replay.js";
 import { WorkflowTypeNotRegisteredForRecoveryError } from "../errors.js";
 import { commitFencedEngineWrite } from "../fenced-write.js";
 import { getWorkflowExecutionStartedAt } from "../handles.js";
+import { WorkflowClaimUnavailableError } from "../lease-errors.js";
 import { normalizeForkStep, selectPersistedWorkflowStartHeaders } from "../state-utilities.js";
 import { loadWorkflowState } from "../storage-io.js";
 import { getComposedWorkflowInterceptor } from "../strategy-helpers.js";
@@ -73,6 +74,8 @@ async function recoverEntryOrIsolateFailure(internals, workflowId, callbacks, op
       await callbacks.failWorkflowForVersionMismatch(workflowId, error);
       return null;
     }
+    if (error instanceof WorkflowClaimUnavailableError)
+      return null;
     throw error;
   }
 }
@@ -98,9 +101,9 @@ export async function recoverAll(internals, callbacks, options) {
   }
   return handles;
 }
-export async function resume(internals, workflowId, callbacks, onRecoveredWorkflow) {
+export async function resume(internals, workflowId, callbacks, onRecoveredWorkflow, options) {
   const workflowState = await loadWorkflowState(internals, workflowId);
-  if (workflowState !== null) {
+  if (workflowState !== null && options?.forceReplayFromStorage !== !0) {
     if (callbacks.isInlineWorkflowLocallyOwned(workflowId, workflowState.status) || callbacks.hasLocalCheckpointOwnership(workflowId, workflowState.status)) {
       await enforceHistoryPolicyBeforeReplayById(internals, workflowId, callbacks);
       return callbacks.getHandle(workflowId);
@@ -130,7 +133,7 @@ export async function fork(internals, sourceWorkflowId, options, callbacks) {
   let forkStarted = !1;
   try {
     const forkCheckpointBytes = serializeCheckpoint(forkCheckpoint);
-    await commitFencedEngineWrite(internals, buildForkBatchOperations(internals, workflowId, forkState, forkCheckpoint, forkCheckpointBytes, persistedWorkflowStartHeaders, callbacks), [], () => Error(`Fork of workflow "${workflowId}" lost its CAS race.`));
+    await commitFencedEngineWrite(internals, workflowId, buildForkBatchOperations(internals, workflowId, forkState, forkCheckpoint, forkCheckpointBytes, persistedWorkflowStartHeaders, callbacks), [], () => Error(`Fork of workflow "${workflowId}" lost its CAS race.`));
     internals.eventLogHeads.set(workflowId, EMPTY_EVENT_HEAD);
     setWorkflowStartHeaders(internals, workflowId, persistedWorkflowStartHeaders, callbacks);
     const handle = launchWorkflowFromCheckpoint(internals, workflowId, forkState, forkCheckpoint, registration, callbacks);

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

@@ -128,7 +128,7 @@ export async function executeActivityOperationResult(internals, workflowId, oper
     if (executionOptions.reconciliationCompletion === "immediate-fenced") {
       const finishImmediateReconciliationCommit = executionOptions.beforeImmediateReconciliationCommit?.();
       try {
-        await commitActivityReconciliationTransitionWithFencedWrite(internals, reference, started, completedRecord);
+        await commitActivityReconciliationTransitionWithFencedWrite(internals, workflowId, reference, started, completedRecord);
       } finally {
         finishImmediateReconciliationCommit?.();
       }

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

@@ -2,13 +2,16 @@ import { KEYS, storageHas } from "../../storage/interface.js";
 import { deserializeCheckpoint } from "../checkpoint.js";
 import { encode } from "../codec.js";
 import { buildTimerBatchOperations, normalizeStorageTimestamp } from "../scheduler.js";
+import { notifyConditionWaiters, notifyConditionWaitersForTimerFire } from "./condition-waiters.js";
 import { commitFencedEngineWrite } from "./fenced-write.js";
 import { reprovideRecoveredServices } from "./lifecycle/recovered-services.js";
 import {
   acknowledgeSupersededSleepTimers,
   handleSleepTimerWithAcknowledgement,
-  resolveSleepTimer
+  resolveSleepTimer,
+  retainDiscardedDurableTimer
 } from "./sleep-timer-acknowledgements.js";
+import { commitWithWorkflowClaimFold, prepareWorkflowClaimFold } from "./workflow-claim-fold.js";
 import { buildWorkflowVisibilityIndexTransition } from "./workflow-indexes.js";
 export function createDelayedStartTimerEntry(_internals, workflowId, scheduledStartAt, options, callbacks) {
   return {
@@ -118,7 +121,10 @@ export async function startDelayedWorkflow(internals, entry, callbacks) {
         fireAt: executionDeadline,
         kind: "execution-deadline"
       }));
-    await commitFencedEngineWrite(internals, operations, [], () => Error(`Delayed-start transition for workflow "${entry.workflowId}" lost its CAS race.`));
+    const claimFold = await prepareWorkflowClaimFold(internals, entry.workflowId);
+    if (claimFold)
+      return (await commitWithWorkflowClaimFold(internals, claimFold, operations, [], "delayed-start workflow claim acquisition")).status === "committed" ? nextRunningState : null;
+    await commitFencedEngineWrite(internals, entry.workflowId, operations, [], () => Error(`Delayed-start transition for workflow "${entry.workflowId}" lost its CAS race.`));
     return nextRunningState;
   });
   if (!runningState)
@@ -158,7 +164,7 @@ async function failInvalidDelayedExecutionTimeout(entry, callbacks) {
   await callbacks.failWorkflow(entry.workflowId, Error(`Invalid delayed execution timeout for workflow "${entry.workflowId}"`));
 }
 export async function handleTimerFired(internals, entry, callbacks) {
-  if (entry.id.startsWith("review-escalation:") || entry.id.startsWith("review-timeout:")) {
+  if (isReviewTimerEntry(entry)) {
     await handleReviewTimer(internals, entry, callbacks);
     return;
   }
@@ -181,14 +187,22 @@ export async function handleTimerFired(internals, entry, callbacks) {
   if (entry.kind === "sleep")
     await handleSleepTimerWithAcknowledgement(internals, entry, callbacks.loadWorkflowState);
   else if (entry.kind === "wait-condition")
-    resolveConditionTimer(internals, entry);
+    if (internals.workflowClaimRegistry === null)
+      resolveConditionTimer(internals, entry);
+    else
+      await resolveConditionTimerConfirmingOwnership(internals, entry, callbacks.loadWorkflowState);
   else if (entry.kind === "execution-deadline")
     await callbacks.timeout(entry.workflowId);
 }
+function isReviewTimerEntry(entry) {
+  return entry.id.startsWith("review-escalation:") || entry.id.startsWith("review-timeout:");
+}
 function resolveConditionTimer(internals, entry) {
-  const resolver = internals.conditionWaiters.get(entry.workflowId);
-  if (resolver)
-    resolver();
+  notifyConditionWaiters(internals, entry.workflowId);
+}
+async function resolveConditionTimerConfirmingOwnership(internals, entry, loadWorkflowState) {
+  if (await notifyConditionWaitersForTimerFire(internals, entry.workflowId) === "discard")
+    await retainDiscardedDurableTimer(entry.id, entry.workflowId, loadWorkflowState);
 }
 async function handleReviewTimer(internals, entry, callbacks) {
   const reviewId = entry.id.split(":")[1];