@lostgradient/weft 0.20.0 → 0.21.0

package/dist/core/engine/updates.js

@@ -1,9 +1,11 @@
 import { UpdateCompletedEvent, UpdateReceivedEvent } from "../events.js";
-import { isGeneratorResult } from "../step-context.js";
-import { UpdateValidationError } from "../updates.js";
 import { notifyConditionWaiters } from "./condition-waiters.js";
+import { invokeUpdateHandler } from "./invoke-update-handler.js";
+import { isLiveContextStale, isWorkflowClaimedByAnotherEngine } from "./queries.js";
 import { trackWaiterKey, untrackWaiterKey } from "./signals.js";
+import { runUpdateValidator } from "./update-validation.js";
 import { waitForUpdateResponse } from "./waiting-update-response.js";
+import { confirmWakeOwnership } from "./wake-ownership-guard.js";
 export async function update(internals, workflowId, name, payload, options, callbacks) {
   const timeout = options?.timeout ?? 30000;
   await runUpdateValidator(internals, workflowId, name, payload);
@@ -11,19 +13,32 @@ export async function update(internals, workflowId, name, payload, options, call
   const inlineResult = await tryInlineUpdateHandler(internals, workflowId, name, payload, callbacks);
   if (inlineResult.handled)
     return inlineResult.value;
+  if (inlineResult.reason === "not-owned-locally")
+    return await runCoordinatedUpdate(internals, workflowId, name, payload, timeout, callbacks);
   const waitingResult = await tryWaitingUpdateHandler(internals, workflowId, name, payload, timeout, callbacks);
   if (waitingResult.handled)
     return waitingResult.value;
   return await runCoordinatedUpdate(internals, workflowId, name, payload, timeout, callbacks);
 }
-async function tryInlineUpdateHandler(internals, workflowId, name, payload, callbacks) {
+function refreshUpdateHandlerAfterAwait(internals, workflowId, name, capturedHandler, stale) {
+  if (stale === !1)
+    return capturedHandler;
+  return internals.inlineStrategy?.getContext(workflowId)?.updateHandlers.get(name);
+}
+export async function tryInlineUpdateHandler(internals, workflowId, name, payload, callbacks) {
   const handler = internals.inlineStrategy?.getContext(workflowId)?.updateHandlers.get(name);
   if (!handler)
-    return { handled: !1 };
+    return { handled: !1, reason: await isWorkflowClaimedByAnotherEngine(internals, workflowId) ? "not-owned-locally" : "no-handler" };
+  const stale = isLiveContextStale(internals, workflowId);
+  if (stale !== !1 && await stale)
+    return { handled: !1, reason: "not-owned-locally" };
+  const liveHandler = refreshUpdateHandlerAfterAwait(internals, workflowId, name, handler, stale);
+  if (!liveHandler)
+    return { handled: !1, reason: "no-handler" };
   const updateId = crypto.randomUUID();
   callbacks.dispatchEvent(new UpdateReceivedEvent(updateId, workflowId, name, payload));
   try {
-    const result = await invokeUpdateHandler(internals, name, handler, payload);
+    const result = await invokeUpdateHandler(internals, name, liveHandler, payload);
     callbacks.dispatchEvent(new UpdateCompletedEvent(updateId, workflowId, name, result));
     callbacks.broadcast({ type: "update:completed", workflowId, updateId });
     notifyConditionWaiters(internals, workflowId);
@@ -43,6 +58,8 @@ async function tryWaitingUpdateHandler(internals, workflowId, name, payload, tim
   const existingPendingUpdate = await callbacks.findPendingUpdateByName(workflowId, name);
   if (internals.updateWaiters.get(waiterKey) !== updateWaiter || existingPendingUpdate)
     return { handled: !1 };
+  if (await confirmWakeOwnership(internals, workflowId, "update") === "discard")
+    return { handled: !1 };
   internals.updateWaiters.delete(waiterKey);
   untrackWaiterKey(internals.updateWaitersByWorkflow, workflowId, waiterKey);
   const updateId = crypto.randomUUID();
@@ -152,6 +169,8 @@ export async function deliverCoordinatedUpdateToWaiterIfAvailable(internals, wor
   const oldestPendingUpdate = await callbacks.findPendingUpdateByName(workflowId, updateRequest.name);
   if (!oldestPendingUpdate || oldestPendingUpdate.updateId !== updateRequest.updateId)
     return !1;
+  if (await confirmWakeOwnership(internals, workflowId, "update") === "discard")
+    return !1;
   await internals.updateCoordinator.deleteRequest(workflowId, updateRequest.updateId);
   internals.updateWaiters.delete(waiterKey);
   untrackWaiterKey(internals.updateWaitersByWorkflow, workflowId, waiterKey);
@@ -166,45 +185,3 @@ export async function deliverCoordinatedUpdateToWaiterIfAvailable(internals, wor
 export async function findPendingUpdateByName(internals, workflowId, name) {
   return (await internals.updateCoordinator.getPendingUpdates(workflowId)).find((updateRequest) => updateRequest.name === name);
 }
-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;
-}
-async function runUpdateValidator(internals, workflowId, name, payload) {
-  const validator = internals.inlineStrategy?.getContext(workflowId)?.updateValidators.get(name);
-  if (validator === void 0)
-    return;
-  let result;
-  try {
-    result = await validator(payload);
-  } catch (error) {
-    const message = error instanceof Error ? error.message : String(error);
-    throw new UpdateValidationError(name, [{ message }]);
-  }
-  const issues = extractStandardSchemaIssues(result);
-  if (issues !== null && issues.length > 0)
-    throw new UpdateValidationError(name, issues);
-}
-export function extractStandardSchemaIssues(result) {
-  if (result === null || typeof result !== "object" || !("issues" in result))
-    return null;
-  const { issues } = result;
-  if (!Array.isArray(issues))
-    return null;
-  return issues.flatMap((issue) => {
-    if (issue === null || typeof issue !== "object")
-      return [];
-    const obj = issue;
-    if (typeof obj.message !== "string")
-      return [];
-    const entry = { message: obj.message };
-    if (Array.isArray(obj.path) && obj.path.length > 0)
-      entry.path = obj.path.reduce((p, seg) => {
-        const k = seg !== null && typeof seg === "object" && "key" in seg ? String(seg.key) : String(seg);
-        return p + "/" + k.replace(/~/g, "~0").replace(/\//g, "~1");
-      }, "");
-    return [entry];
-  });
-}

package/dist/core/engine/wake-ownership-check.d.ts

@@ -0,0 +1,86 @@
+/**
+ * `wakeOwnershipCheck` — the read-only re-read of `wf-owner-holder:<id>`
+ * specified in
+ * [ADR 0002 § Ownership transitions](../../../documentation/contributing/architecture-decisions/0002-multiengine-per-workflow-ownership.md#ownership-transitions)
+ * (the paragraph immediately after the transitions table).
+ *
+ * **Why this exists.** Under `ownership: 'workflow-lease'`, every code path
+ * that is about to resolve an in-memory waiter or drive a generator for a
+ * parked workflow — a fired sleep timer, 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 — must
+ * first confirm THIS engine still holds the claim generation it parked the
+ * workflow under. Skipping that check would let a stale in-memory resolver
+ * from a prior generation drive a workflow this engine no longer owns.
+ *
+ * **Why the FULL generation, not just the engine id.** When an engine
+ * releases a workflow and later reacquires the same id, its `engineId` is
+ * unchanged while `epoch` names a new generation. An engine-id-only check
+ * would let a delayed wake or a stale in-memory resolver from the PRIOR
+ * generation drive the NEW one — the exact ABA hazard the epoch exists to
+ * close. This check therefore compares `engineId` AND `epoch` together,
+ * never `engineId` alone.
+ *
+ * **What a match does and does not prove.** A match is a cheap pre-check,
+ * not the safety mechanism itself — the durable write that follows still
+ * carries the epoch as a `conditionalBatch` precondition, and that CAS is
+ * the actual backstop. A mismatch means this engine no longer holds the
+ * generation it parked under: the caller must discard its in-memory
+ * resolver without driving the generator. This module emits
+ * `WeftWorkflowWakeDiscardedWarning` on every mismatch; it does not decide
+ * what the caller does next (that decision, and the actual discard, belong
+ * to the wake call sites this check is wired into — a later stage).
+ *
+ * **Scope.** This module is the check alone: read the holder record, decide
+ * match or discard, warn on discard. It is NOT wired into any of the wake
+ * call sites named above — that wiring is a later stage's responsibility.
+ *
+ * @module core/engine/wake-ownership-check
+ */
+import { type Storage } from '../../storage/interface.ts';
+import { type EmitWorkflowLeaseWarning, type WorkflowWakeKind } from './lease-deposition.ts';
+/** Parameters for {@link wakeOwnershipCheck}. */
+export type WakeOwnershipCheckParams = {
+    /** Durable storage to re-read `wf-owner-holder:<workflowId>` from. */
+    storage: Storage;
+    /** The workflow whose parked wake is about to be resolved or driven. */
+    workflowId: string;
+    /** Which wake path is asking — folded into the discard warning for operator diagnosis. */
+    wakeKind: WorkflowWakeKind;
+    /** The `engineId` this engine parked the workflow under. */
+    expectedEngineId: string;
+    /** The `epoch` this engine parked the workflow under. */
+    expectedEpoch: number;
+    /** Operator-warning seam; defaults to `process.emitWarning` via `lease-deposition.ts`. */
+    warn?: EmitWorkflowLeaseWarning;
+};
+/** Why a re-read holder record failed to match the expected generation. */
+export type WakeOwnershipDiscardReason = 'holder-absent' | 'holder-undecodable' | 'generation-mismatch';
+/** Result of {@link wakeOwnershipCheck}. */
+export type WakeOwnershipCheckResult = {
+    status: 'match';
+} | {
+    status: 'discarded';
+    reason: WakeOwnershipDiscardReason;
+    /** The `engineId` actually found on re-read, or `null` when the holder was absent/undecodable. */
+    observedEngineId: string | null;
+    /** The `epoch` actually found on re-read, or `null` when the holder was absent/undecodable. */
+    observedEpoch: number | null;
+};
+/**
+ * Re-read `wf-owner-holder:<workflowId>` and compare it against the full
+ * generation (`engineId` + `epoch`) this engine parked the workflow under.
+ *
+ * Returns `{ status: 'match' }` when both fields agree — the caller may
+ * proceed to resolve its in-memory waiter or drive the generator (the
+ * following durable write still carries the epoch as the real backstop).
+ * Returns `{ status: 'discarded', reason }` and emits
+ * `WeftWorkflowWakeDiscardedWarning` in every other case: the holder key is
+ * absent (`'holder-absent'`), the stored bytes do not decode to a valid
+ * holder record (`'holder-undecodable'`), or a holder record was found but
+ * its `engineId`/`epoch` do not both match what was expected
+ * (`'generation-mismatch'`) — including the stale-generation case where
+ * `engineId` matches but `epoch` does not, the exact hazard this check
+ * exists to close.
+ */
+export declare function wakeOwnershipCheck(params: WakeOwnershipCheckParams): Promise<WakeOwnershipCheckResult>;

package/dist/core/engine/wake-ownership-check.js

@@ -0,0 +1,19 @@
+import { KEYS } from "../../storage/interface.js";
+import {
+  emitWorkflowWakeDiscardedWarning
+} from "./lease-deposition.js";
+import { decodeWorkflowClaimHolder } from "./workflow-claim-codec.js";
+export async function wakeOwnershipCheck(params) {
+  const { storage, workflowId, wakeKind, expectedEngineId, expectedEpoch, warn } = params, discard = (reason, observedEngineId, observedEpoch) => {
+    emitWorkflowWakeDiscardedWarning(workflowId, wakeKind, warn);
+    return { status: "discarded", reason, observedEngineId, observedEpoch };
+  }, raw = await storage.get(KEYS.workflowOwnerHolder(workflowId));
+  if (raw === null)
+    return discard("holder-absent", null, null);
+  const holder = decodeWorkflowClaimHolder(raw);
+  if (holder === null)
+    return discard("holder-undecodable", null, null);
+  if (holder.engineId !== expectedEngineId || holder.epoch !== expectedEpoch)
+    return discard("generation-mismatch", holder.engineId, holder.epoch);
+  return { status: "match" };
+}

package/dist/core/engine/wake-ownership-guard.d.ts

@@ -0,0 +1,46 @@
+/**
+ * `confirmWakeOwnership` — the single call-site helper every claim-requiring
+ * wake path (sleep, wait-condition, async-activity, inline-macrotask-drive)
+ * uses to run `wakeOwnershipCheck` before resolving an in-memory waiter or
+ * driving a generator for a parked workflow, per
+ * [ADR 0002 § Ownership transitions](../../../documentation/contributing/architecture-decisions/0002-multiengine-per-workflow-ownership.md#ownership-transitions).
+ *
+ * **Why a wrapper instead of calling `wakeOwnershipCheck` directly at each
+ * site.** `wakeOwnershipCheck` requires a non-null `expectedEngineId` /
+ * `expectedEpoch` pair — it has no opinion on how a caller obtains those. Every
+ * wake site needs the exact same three-way decision tree first:
+ *
+ * - `internals.workflowClaimRegistry` is `null` (ownership is `'none'` or
+ *   `'lease'`): this check is a no-op. Proceed — byte-identical to every
+ *   pre-ADR-0002 deployment. This is the property every wake site must
+ *   preserve above all else.
+ * - The registry is present but tracks no epoch for this workflow id
+ *   (`currentEpoch(workflowId)` is `null` — e.g. a `renew()` loss already
+ *   dropped this engine's local claim entry): there is nothing to compare
+ *   against, so this is itself a discard. `wakeOwnershipCheck` cannot be
+ *   called with a null epoch, so this module emits
+ *   `WeftWorkflowWakeDiscardedWarning` itself rather than skipping the
+ *   operator diagnostic.
+ * - The registry tracks an epoch: re-read the durable holder record and
+ *   compare the full generation via `wakeOwnershipCheck`.
+ *
+ * **A thrown storage read is `'proceed'`, not `'discard'`.** This helper is a
+ * cheap pre-check; the epoch-conditioned durable write that follows every
+ * proceed path is the real backstop (`EngineDeposedError` if it has actually
+ * lost the claim). A storage blip during the pre-check must not permanently
+ * strand a wake — a fired sleep timer or a signalled `waitUntil` deadline is
+ * not retried — so a thrown read is treated the same as a match and the
+ * caller proceeds to its normal (already-fenced) write path.
+ *
+ * @module core/engine/wake-ownership-guard
+ */
+import type { EngineInternals } from './internals.ts';
+import { type WorkflowWakeKind } from './lease-deposition.ts';
+/** Outcome of {@link confirmWakeOwnership}: whether the caller may proceed with this wake. */
+export type WakeOwnershipDecision = 'proceed' | 'discard';
+/**
+ * Decide whether a claim-requiring wake path may resolve its in-memory
+ * waiter / drive its generator for `workflowId`. See the module doc for the
+ * three-way decision tree and the thrown-read policy.
+ */
+export declare function confirmWakeOwnership(internals: EngineInternals, workflowId: string, wakeKind: WorkflowWakeKind): Promise<WakeOwnershipDecision>;

package/dist/core/engine/wake-ownership-guard.js

@@ -0,0 +1,23 @@
+import { emitWorkflowWakeDiscardedWarning } from "./lease-deposition.js";
+import { wakeOwnershipCheck } from "./wake-ownership-check.js";
+export async function confirmWakeOwnership(internals, workflowId, wakeKind) {
+  const registry = internals.workflowClaimRegistry;
+  if (registry === null)
+    return "proceed";
+  const expectedEpoch = registry.currentEpoch(workflowId);
+  if (expectedEpoch === null) {
+    emitWorkflowWakeDiscardedWarning(workflowId, wakeKind);
+    return "discard";
+  }
+  try {
+    return (await wakeOwnershipCheck({
+      storage: internals.storage,
+      workflowId,
+      wakeKind,
+      expectedEngineId: registry.engineId,
+      expectedEpoch
+    })).status === "match" ? "proceed" : "discard";
+  } catch {
+    return "proceed";
+  }
+}

package/dist/core/engine/workflow-claim-codec.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Pure codecs for the per-workflow ownership claim keys (`wf-owner-epoch:<id>`
+ * and `wf-owner-holder:<id>`) and for the store-wide `ownership-mode-marker`.
+ *
+ * These back the `ownership: 'workflow-lease'` mode described in
+ * [ADR 0002](../../../documentation/contributing/architecture-decisions/0002-multiengine-per-workflow-ownership.md).
+ * The epoch codec itself is shared with the global lease — `encodeEpoch` and
+ * `decodeEpoch` are imported from `lease-codec.ts` rather than reimplemented, so
+ * both fencing tokens stay byte-identical in representation.
+ *
+ * Only the holder record differs: the global lease holds three fields for one
+ * store-wide lease, while a per-workflow claim holds four, adding `claimedAt`
+ * for operator visibility and carrying `engineId` rather than `holderId`.
+ *
+ * Every decoder is fail-closed: any structurally invalid, foreign, or corrupt
+ * value decodes to `null` rather than throwing, matching `lease-codec.ts`.
+ *
+ * @module core/engine/workflow-claim-codec
+ */
+import { decodeEpoch, encodeEpoch } from './lease-codec.ts';
+export { decodeEpoch, encodeEpoch };
+/** The ownership modes that fence engine work and therefore stamp the store-wide marker. */
+export type FencingOwnershipMode = 'lease' | 'workflow-lease';
+/** The decoded `wf-owner-holder:<workflowId>` record. */
+export type WorkflowClaimHolderRecord = {
+    /** Identity of the owning engine process, minted once per engine. */
+    engineId: string;
+    /** The claim generation this holder owns. Mirrors `wf-owner-epoch:<workflowId>`. */
+    epoch: number;
+    /** Engine-clock ms after which the claim becomes eligible for takeover. */
+    expiresAt: number;
+    /** Engine-clock ms when this epoch was first claimed. Unchanged across renewals. */
+    claimedAt: number;
+};
+/** The decoded store-wide `ownership-mode-marker` record. */
+export type OwnershipModeMarkerRecord = {
+    /** The fencing mode the first fencing-mode engine stamped on this store. */
+    mode: FencingOwnershipMode;
+    /** Engine-clock ms when the marker was established. Diagnostics only. */
+    establishedAt: number;
+};
+/** Encode a per-workflow claim holder record to its stored JSON bytes. */
+export declare function encodeWorkflowClaimHolder(record: WorkflowClaimHolderRecord): Uint8Array;
+/**
+ * Decode a stored per-workflow claim holder record, tolerating any
+ * malformed or foreign value as `null`.
+ *
+ * An empty `engineId` is rejected: it can never match a real engine's identity,
+ * so admitting it would produce a holder that no engine can renew or release.
+ */
+export declare function decodeWorkflowClaimHolder(raw: Uint8Array): WorkflowClaimHolderRecord | null;
+/** Encode the store-wide ownership-mode marker to its stored JSON bytes. */
+export declare function encodeOwnershipModeMarker(record: OwnershipModeMarkerRecord): Uint8Array;
+/**
+ * Decode the store-wide ownership-mode marker, tolerating any malformed or
+ * foreign value as `null`.
+ *
+ * An unrecognized `mode` decodes to `null` rather than being preserved. The
+ * marker exists to make a mode mismatch detectable, and a mode this build does
+ * not understand cannot be compared meaningfully; treating it as absent lets the
+ * reader fail closed on its own terms instead of comparing against a string it
+ * cannot interpret.
+ */
+export declare function decodeOwnershipModeMarker(raw: Uint8Array): OwnershipModeMarkerRecord | null;

package/dist/core/engine/workflow-claim-codec.js

@@ -0,0 +1,44 @@
+import { decodeEpoch, encodeEpoch } from "./lease-codec.js";
+
+export { decodeEpoch, encodeEpoch };
+const textEncoder = new TextEncoder, textDecoder = new TextDecoder;
+function isRecord(value) {
+  return typeof value === "object" && value !== null;
+}
+function isUsableTimestamp(value) {
+  return typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+}
+function isUsableEpoch(value) {
+  return typeof value === "number" && Number.isSafeInteger(value) && value >= 1 && value < Number.MAX_SAFE_INTEGER;
+}
+function parseJsonBytes(raw) {
+  try {
+    return JSON.parse(textDecoder.decode(raw));
+  } catch {
+    return null;
+  }
+}
+export function encodeWorkflowClaimHolder(record) {
+  return textEncoder.encode(JSON.stringify(record));
+}
+export function decodeWorkflowClaimHolder(raw) {
+  const parsed = parseJsonBytes(raw);
+  if (!isRecord(parsed))
+    return null;
+  const { engineId, epoch, expiresAt, claimedAt } = parsed;
+  if (typeof engineId !== "string" || engineId.length === 0 || !isUsableEpoch(epoch) || !isUsableTimestamp(expiresAt) || !isUsableTimestamp(claimedAt))
+    return null;
+  return { engineId, epoch, expiresAt, claimedAt };
+}
+export function encodeOwnershipModeMarker(record) {
+  return textEncoder.encode(JSON.stringify(record));
+}
+export function decodeOwnershipModeMarker(raw) {
+  const parsed = parseJsonBytes(raw);
+  if (!isRecord(parsed))
+    return null;
+  const { mode, establishedAt } = parsed;
+  if (mode !== "lease" && mode !== "workflow-lease" || !isUsableTimestamp(establishedAt))
+    return null;
+  return { mode, establishedAt };
+}

package/dist/core/engine/workflow-claim-cooldown.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Per-workflow-id anti-thrash takeover cooldown, specified in
+ * [ADR 0002 § Ownership transitions](../../../documentation/contributing/architecture-decisions/0002-multiengine-per-workflow-ownership.md#ownership-transitions)
+ * (the `takeover` row's "A per-workflow-id anti-thrash cooldown" sentence).
+ *
+ * **The problem this dampens.** Without it, a reclaim scan and the engine
+ * that just lost a claim can thrash: this engine loses `workflowId` via a
+ * failed `renew`, its own recurring reclaim scan later judges the same
+ * holder stale (a genuine race — the deposing engine can itself stall or
+ * crash right after depositing this one), and this engine immediately steals
+ * it back, only to lose it again the same way. The cooldown makes that loop
+ * back off instead of spinning.
+ *
+ * **Shape.** In-memory, per-engine-process, keyed by workflow id — not
+ * durable and not shared across engines; a restart forgets every cooldown,
+ * which is safe, since a fresh process has not just been deposed from
+ * anything yet. `WorkflowClaimRegistry` owns one instance and drives it from
+ * exactly three points: a failed `renew` calls {@link recordDeposition}, a
+ * successful `acquire`/`takeover`/folded-acquire calls {@link clear}, and
+ * `takeover` consults {@link isActive} before attempting its CAS.
+ *
+ * **Curve.** A fixed window of `workflowClaimRenewInterval`, not exponential.
+ * Through `WorkflowClaimRegistry`'s real call graph, a second
+ * `recordDeposition` for the same id is only reachable after an intervening
+ * successful (re)acquire has already {@link clear}ed the tracked entry — this
+ * class never observes consecutive depositions for the same id without a
+ * clear between them, so a growing window would never actually grow. An
+ * exponential curve was tried here and found unreachable in review; keep this
+ * simple until a call-graph change (preserving loss history across successful
+ * reacquisition) makes a growing window meaningful.
+ *
+ * @module core/engine/workflow-claim-cooldown
+ */
+/** Options for {@link WorkflowClaimTakeoverCooldown}. Mirrors `WorkflowClaimRegistryOptions`'s same-named field, so the caller need not compute the window itself. */
+export type WorkflowClaimTakeoverCooldownOptions = {
+    /** Cooldown window (ms) — `workflowClaimRenewInterval`. */
+    claimRenewIntervalMs: number;
+};
+/**
+ * Tracks one engine's per-workflow-id takeover cooldown. See the module doc
+ * for the mechanism and curve.
+ */
+export declare class WorkflowClaimTakeoverCooldown {
+    #private;
+    constructor(options: WorkflowClaimTakeoverCooldownOptions);
+    /**
+     * Whether `workflowId` is currently within its cooldown window at `now`.
+     * The boundary itself (`now === untilMs`) is NOT active — matches
+     * `isWorkflowClaimExpired`'s "strictly earlier" convention for the sibling
+     * expiry judgment.
+     */
+    isActive(workflowId: string, now: number): boolean;
+    /**
+     * Record that this engine just lost ownership of `workflowId` via a failed
+     * `renew`. Starts (or restarts) a fixed-length cooldown window.
+     */
+    recordDeposition(workflowId: string, now: number): void;
+    /** Clear any tracked cooldown for `workflowId` — call on a successful (re)acquire or takeover. */
+    clear(workflowId: string): void;
+}

package/dist/core/engine/workflow-claim-cooldown.js

@@ -0,0 +1,17 @@
+export class WorkflowClaimTakeoverCooldown {
+  #windowMs;
+  #untilMsByWorkflowId = new Map;
+  constructor(options) {
+    this.#windowMs = options.claimRenewIntervalMs;
+  }
+  isActive(workflowId, now) {
+    const untilMs = this.#untilMsByWorkflowId.get(workflowId);
+    return untilMs !== void 0 && now < untilMs;
+  }
+  recordDeposition(workflowId, now) {
+    this.#untilMsByWorkflowId.set(workflowId, now + this.#windowMs);
+  }
+  clear(workflowId) {
+    this.#untilMsByWorkflowId.delete(workflowId);
+  }
+}

package/dist/core/engine/workflow-claim-fold.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Shared "fold `acquire` into an enabling write" helper for ADR 0002's
+ * CLAIM-ACQUIRING entry points this stage owns: workflow start
+ * (`lifecycle/start-commit.ts` — the create batch), delayed-start timer fire
+ * (`operations-time.ts`), and bulk retry reactivation (`bulk-operations.ts`).
+ * Scheduled runs and child-workflow launches funnel through `startWorkflow`
+ * (`lifecycle/start.ts`) and inherit the fold from there — see
+ * [ADR 0002 § Entry point classification](../../../documentation/contributing/architecture-decisions/0002-multiengine-per-workflow-ownership.md#entry-point-classification),
+ * the `startWorkflow`/`buildAndCommitStartBatch` row, which explicitly groups
+ * `ctx.startChild` and `startScheduledRun` with it.
+ *
+ * A claim-acquiring write establishes a claim THIS commit has never held
+ * before, so it can never be fenced through `commitFencedEngineWrite` (which
+ * requires an ALREADY-tracked epoch in `EngineInternals.workflowClaimRegistry`
+ * — see `fenced-write.ts`'s `fencedCommitForWorkflow`). Instead, the claim's
+ * OWN `acquire` conditions (holder absent, epoch matches what was just read)
+ * ARE the fence for this first write: {@link prepareWorkflowClaimFold} reads
+ * fresh `wf-owner-epoch:<id>` bytes and builds the pure acquire fragment via
+ * `WorkflowClaimRegistry.prepareAcquireFragment`, the caller merges the
+ * fragment's conditions/operations into its own enabling write, and
+ * {@link commitWithWorkflowClaimFold} commits ONE atomic
+ * `storageConditionalBatch`. Only after that commit succeeds does it call
+ * `WorkflowClaimRegistry.recordFoldedAcquire`, installing the tracking entry
+ * every later `commitFencedEngineWrite` for this workflow needs.
+ *
+ * Under `ownership: 'none'`/`'lease'`, or `'workflow-lease'` with no registry
+ * constructed yet (Gate 1/Gate 2 wiring is a parallel/later stage) —
+ * {@link prepareWorkflowClaimFold} returns `undefined` and every caller's
+ * pre-existing code path runs byte-for-byte unchanged. It also returns
+ * `undefined` when this engine already tracks a claim for `workflowId`: bulk
+ * retry folds `acquire` into its own reactivation write, then calls
+ * `engine.resume()`, which must not attempt a second acquire for the same
+ * workflow (see `lifecycle/resume.ts`).
+ *
+ * @module core/engine/workflow-claim-fold
+ */
+import { type BatchOperation, type ConditionalBatchCondition } from '../../storage/interface.ts';
+import type { EngineInternals } from './internals.ts';
+import type { WorkflowClaimAcquirePreparation, WorkflowClaimRegistry } from './workflow-claim-registry.ts';
+/** A prepared, not-yet-committed claim-acquire fold for one workflow id. */
+export type WorkflowClaimFold = {
+    registry: WorkflowClaimRegistry;
+    workflowId: string;
+    preparation: WorkflowClaimAcquirePreparation;
+    conditions: ConditionalBatchCondition[];
+    operations: BatchOperation[];
+};
+/**
+ * Prepare a claim-acquire fold for `workflowId`, or `undefined` when folding
+ * does not apply — see the module doc for the three cases that return
+ * `undefined`. Call again on every retry attempt of the caller's own
+ * enabling-write loop; never reuse a preparation across attempts, since a
+ * stale epoch read dooms the retry's CAS.
+ */
+export declare function prepareWorkflowClaimFold(internals: EngineInternals, workflowId: string): Promise<WorkflowClaimFold | undefined>;
+/** Outcome of {@link commitWithWorkflowClaimFold}. */
+export type WorkflowClaimFoldCommitResult = {
+    status: 'committed';
+} | {
+    status: 'lost-race';
+    /** Whether the fold's OWN conditions (not the caller's) were the ones that lost the CAS. */
+    claimConflict: boolean;
+};
+/**
+ * Commit `operations`/`conditions` merged with `fold`'s own acquire
+ * fragment, as ONE atomic `storageConditionalBatch`. On success, installs
+ * the fold's tracking entry via `WorkflowClaimRegistry.recordFoldedAcquire`.
+ * On a lost CAS, re-reads the fold's own conditions to report whether THEY
+ * were the ones that failed — distinct from the caller's own conditions
+ * (idempotency mapping, workflow-concurrency admission) — so the caller can
+ * raise `WorkflowClaimUnavailableError` instead of misreporting a claim loss
+ * as an unrelated precondition conflict, or vice versa.
+ */
+export declare function commitWithWorkflowClaimFold(internals: EngineInternals, fold: WorkflowClaimFold, operations: BatchOperation[], conditions: ConditionalBatchCondition[], featureName: string): Promise<WorkflowClaimFoldCommitResult>;
+/**
+ * Raise `WorkflowClaimUnavailableError` for `workflowId`, re-reading its
+ * current holder for the `heldBy` field — the shared shape every explicit,
+ * single-workflow claim-acquiring call site (start, bulk retry reactivation)
+ * uses on a confirmed claim conflict, instead of each repeating the
+ * re-read-then-throw.
+ */
+export declare function throwWorkflowClaimUnavailable(internals: EngineInternals, workflowId: string): Promise<never>;

package/dist/core/engine/workflow-claim-fold.js

@@ -0,0 +1,53 @@
+import {
+  KEYS,
+  requireStorageCapability,
+  storageConditionalBatch,
+  storageValuesEqual
+} from "../../storage/interface.js";
+import { WorkflowClaimUnavailableError } from "./lease-errors.js";
+import { decodeWorkflowClaimHolder } from "./workflow-claim-codec.js";
+export async function prepareWorkflowClaimFold(internals, workflowId) {
+  if (internals.options.ownershipMode !== "workflow-lease")
+    return;
+  const registry = internals.workflowClaimRegistry;
+  if (registry === null)
+    return;
+  if (registry.currentEpoch(workflowId) !== null)
+    return;
+  const preparation = await registry.prepareAcquireFragment(workflowId);
+  return {
+    registry,
+    workflowId,
+    preparation,
+    conditions: preparation.fragment.conditions,
+    operations: preparation.fragment.operations
+  };
+}
+export async function commitWithWorkflowClaimFold(internals, fold, operations, conditions, featureName) {
+  requireStorageCapability(internals.storage, "conditionalBatch", featureName);
+  if (await storageConditionalBatch(internals.storage, [...conditions, ...fold.conditions], [...operations, ...fold.operations])) {
+    fold.registry.recordFoldedAcquire(fold.workflowId, fold.preparation);
+    return { status: "committed" };
+  }
+  return {
+    status: "lost-race",
+    claimConflict: await hasWorkflowClaimFoldConflict(internals, fold)
+  };
+}
+async function hasWorkflowClaimFoldConflict(internals, fold) {
+  for (const condition of fold.conditions) {
+    const currentValue = await internals.storage.get(condition.key);
+    if (!storageValuesEqual(currentValue, condition.expectedValue))
+      return !0;
+  }
+  return !1;
+}
+async function resolveWorkflowClaimHolder(internals, workflowId) {
+  const raw = await internals.storage.get(KEYS.workflowOwnerHolder(workflowId));
+  if (raw === null)
+    return null;
+  return decodeWorkflowClaimHolder(raw)?.engineId ?? null;
+}
+export async function throwWorkflowClaimUnavailable(internals, workflowId) {
+  throw new WorkflowClaimUnavailableError(workflowId, await resolveWorkflowClaimHolder(internals, workflowId));
+}