@lostgradient/weft 0.20.0 → 0.21.0

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

@@ -32,6 +32,7 @@ import type { Scheduler } from '../scheduler.ts';
 import type { Checkpoint, StartWorkflowOptions } from '../types.ts';
 import type { UpdateCoordinator } from '../updates.ts';
 import type { WorkflowVersionTuple } from '../workflow-version-tuple.ts';
+import type { RecoveredWorkflowInfo } from './lifecycle/shared.ts';
 import type { ActivityHeartbeatKey } from './activity-heartbeat-tracking.ts';
 import type { PendingTimelineEntry, QueuedInlineWorkflowExecutionStart, RegistrationEntry, ResolvedOptions, TrackedWaiterKeys, WorkflowResultWaiter } from './engine-internal-types.ts';
 import type { EngineCleanupIntervalDisposalTracker } from './engine-leak-warnings.ts';
@@ -40,6 +41,9 @@ import type { WorkflowFeedListener } from './index.ts';
 import type { LeaseManager } from './lease-manager.ts';
 import type { ScheduleHandleEngine } from './schedule-handle.ts';
 import type { SecondInstanceDetector } from './second-instance-detector.ts';
+import type { WorkflowClaimMetricsRecorder } from './workflow-claim-metrics.ts';
+import type { WorkflowClaimRegistry } from './workflow-claim-registry.ts';
+import type { WorkflowClaimRenewalTask } from './workflow-claim-renewal-task.ts';
 export type SleepTimerAcknowledgementWaiter = {
     fireAt: number;
     operationId: string;
@@ -239,6 +243,43 @@ export interface EngineInternals {
      * Step 1; epoch fencing of durable writes (Step 2) is what makes it enforceable.
      */
     leaseManager: LeaseManager | null;
+    /**
+     * The active per-workflow claim registry for `ownership: 'workflow-lease'`;
+     * `null` under `'none'`/`'lease'` and, for now, ALSO under `'workflow-lease'`
+     * itself — wiring construction (Gate 1/Gate 2, actually instantiating the
+     * registry, and folding `acquire()` into start/resume/delayed-start-fire) is a
+     * later stage. Its presence here lets {@link commitFencedEngineWrite} read
+     * {@link WorkflowClaimRegistry.currentEpochBytes} for a workflow-scoped write
+     * without that later stage having to touch the fencing path again. Until it is
+     * populated, every workflow-scoped write under `'workflow-lease'` fails closed
+     * with {@link EngineDeposedError} — correct, not a bug: this engine holds no
+     * claim for any workflow yet.
+     */
+    workflowClaimRegistry: WorkflowClaimRegistry | null;
+    /**
+     * The active per-workflow claim-renewal task for `ownership: 'workflow-lease'`;
+     * `null` under `'none'`/`'lease'` and until `#bootstrapOwnershipIfConfigured`
+     * completes. Renews every claim this engine holds (active or parked) on its
+     * own cadence — independent of the durable-timer scheduler, so `startScheduler:
+     * false` still renews claims — or via `runMaintenance()` under
+     * `backgroundTasks: 'manual'`, which never starts its interval. Stopped
+     * (interval cleared, never awaited — stopping is synchronous) and detached at
+     * every `disposeEngine` call site; releasing the claims it was renewing is the
+     * separate, best-effort `workflowClaimRegistry.releaseAll()` step each
+     * disposal path drives on its own schedule.
+     */
+    workflowClaimRenewalTask: WorkflowClaimRenewalTask | null;
+    /**
+     * Bounded-cardinality observability recorder for the `ownership:
+     * 'workflow-lease'` claim protocol (ADR 0002 § Observability); `null` under
+     * `'none'`/`'lease'` and until `#bootstrapOwnershipIfConfigured` completes.
+     * One instance per engine process, shared by this engine's claim-renewal task
+     * (which feeds it renewal-failure counts and the active-claim gauge after
+     * every pass) and, in a later stage, its claim-acquiring entry points (start,
+     * resume, delayed-start fire), which would record `acquired`/`takeover`/
+     * `lost_race`/`deposed`/`backoff_skipped` attempts into the same instance.
+     */
+    workflowClaimMetrics: WorkflowClaimMetricsRecorder | null;
     /**
      * The in-flight lease acquisition, or `null` when none is running. Set while
      * `#acquireLeaseIfConfigured` awaits `acquire()` (which can park for the whole
@@ -248,6 +289,15 @@ export interface EngineInternals {
      * than leaking until TTL on an already-disposed engine.
      */
     inFlightLeaseAcquire: Promise<void> | null;
+    /**
+     * The in-flight `ownership: 'workflow-lease'` bootstrap (Gate 1, Gate 2, and
+     * claim-registry/renewal-task construction), or `null` when none is running.
+     * Mirrors {@link inFlightLeaseAcquire}'s idempotency shape: concurrent
+     * `Engine.create` + `recoverAll` (and repeated `recoverAll`/`runMaintenance`)
+     * callers await this same promise rather than racing the gates twice. Always
+     * `null` under `ownership: 'none'`/`'lease'`, which never run this bootstrap.
+     */
+    inFlightOwnershipBootstrap: Promise<void> | null;
     /**
      * Set to `true` the instant this engine is detected as deposed under
      * `ownership: 'lease'` — either a fenced durable write's CAS failed against a
@@ -296,9 +346,32 @@ export interface EngineInternals {
      * updates whose delete never committed).
      */
     deliveredPendingUpdateIds: Map<string, Set<string>>;
+    /**
+     * The most recent `recoverAll({ onRecoveredWorkflow })` hook installed by
+     * this host, retained so a LATER same-engine reclaim (ADR 0002's recurring
+     * scan, after `recover: false` skipped this workflow entirely at startup
+     * because another engine held it then) still runs it before resuming.
+     * Without this, `index.ts`'s `onWorkflowClaimReclaimed` callback would pass
+     * `undefined` for every reclaim-driven resume, silently skipping whatever
+     * host initialization/validation the hook contract guarantees runs before
+     * recovered execution. `undefined` until `recoverAll()` is ever called with
+     * this option.
+     */
+    onRecoveredWorkflowHook: ((info: RecoveredWorkflowInfo) => void | Promise<void>) | undefined;
     cancelHandlersByWorkflow: Map<string, Array<() => Promise<void> | void>>;
     reviewTimerIds: Map<string, string[]>;
     pendingWebhooks: Set<AbortController>;
+    /**
+     * Every `setTimeout` handle `scheduleCrossEngineResultPollIfPending`
+     * (`handle-result.ts`) currently has pending, so disposal can cancel them.
+     * Without this, disposing an automatic-mode engine while a cross-engine
+     * result waiter is parked rejects and clears the waiter but leaves this
+     * untracked timer alive — the timer queue retains the waiter, engine
+     * internals, and storage reference until `workflowClaimRenewIntervalMs`
+     * elapses, and its callback then calls `bootstrapWorkflowResultResolver`
+     * against already-disposed storage.
+     */
+    pendingResultPollTimers: Set<ReturnType<typeof setTimeout>>;
     alertManager: AlertManager | null;
     eventLogHeads: Map<string, Readonly<EventHeadRecord>>;
     workflowFeedListeners: Map<string, Set<WorkflowFeedListener>>;

package/dist/core/engine/invoke-update-handler.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Invoking an `ctx.onUpdate()` handler, and the type of the handler itself.
+ *
+ * Separate from `updates.ts` because both the inline dispatch path and
+ * `pending-updates.ts`'s replay path call it, and because it is pure handler
+ * invocation with no coupling to the in-memory waiter maps or the durable
+ * coordinated-update protocol that make up the rest of update delivery.
+ *
+ * @module core/engine/invoke-update-handler
+ */
+import type { EngineInternals } from './internals.ts';
+/** An `ctx.onUpdate()` handler as stored on a live workflow context. */
+export type InlineUpdateHandler = (payload: unknown) => unknown;
+/**
+ * Invoke an update handler, checking that it does not return a generator.
+ * Centralises the runtime generator guard for both the inline-handler path
+ * in `update()` and the pending-drain path on resume.
+ */
+export declare function invokeUpdateHandler(_internals: EngineInternals, name: string, handler: (payload: unknown) => unknown, payload: unknown): Promise<unknown>;

package/dist/core/engine/invoke-update-handler.js

@@ -0,0 +1,7 @@
+import { isGeneratorResult } from "../step-context.js";
+export async function invokeUpdateHandler(_internals, name, handler, payload) {
+  const result = handler(payload);
+  if (isGeneratorResult(result))
+    throw TypeError(`Update handler "${name}" returned a generator. Update handlers must return a plain value or a Promise, not a generator.`);
+  return await result;
+}

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