@lostgradient/weft 0.20.0 → 0.22.0

package/dist/core/engine/ownership-mode-marker.d.ts

@@ -0,0 +1,82 @@
+/**
+ * The two construction-time capability gates described in
+ * [ADR 0002 § Construction-time capability gates](../../../documentation/contributing/architecture-decisions/0002-multiengine-per-workflow-ownership.md#construction-time-capability-gates):
+ *
+ * - **Gate 1 — storage capability.** Fails fast when the configured storage
+ *   backend does not support `conditionalBatch`, naming the *configured*
+ *   fencing mode in the diagnostic rather than a hardcoded one, so an operator
+ *   troubleshooting the shipped `ownership: 'lease'` is not sent chasing
+ *   `workflow-lease`, which is unimplemented until a later stage.
+ * - **Gate 2 — ownership-mode marker.** Stamps or verifies the store-wide
+ *   `ownership-mode-marker` singleton so `ownership: 'lease'` and
+ *   `ownership: 'workflow-lease'` remain mutually exclusive across engine
+ *   *processes*, not merely within one process.
+ *
+ * Both gates fire only for the two fencing modes (`'lease'` and
+ * `'workflow-lease'`); `ownership: 'none'` never touches the marker or checks
+ * the capability. {@link bootstrapOwnershipGates} runs them in the ADR's
+ * required order (Gate 1 then Gate 2) and is the unit later wired in front of
+ * claim acquisition, recovery scanning, scheduler polling, and task polling —
+ * that wiring is a later stage and is deliberately not done here.
+ *
+ * @module core/engine/ownership-mode-marker
+ */
+import { type Storage } from '../../storage/interface.ts';
+import { type FencingOwnershipMode } from './workflow-claim-codec.ts';
+/**
+ * Mirrors the full `ownership` discriminant (`EngineConstructorOptions.ownership`
+ * / `ResolvedOptions.ownershipMode`). Duplicated here as a literal union rather
+ * than imported, because neither call site exports a standalone name for it —
+ * importing `ResolvedOptions` would pull in the whole engine-internal-types
+ * surface for one field's type.
+ */
+export type EngineOwnershipMode = 'none' | 'lease' | 'workflow-lease';
+/**
+ * Gate 1 — storage capability. Fires for `ownership: 'lease'` or
+ * `ownership: 'workflow-lease'`; reuses the existing, untyped `Error` that
+ * {@link requireStorageCapability} already throws. The diagnostic names the
+ * mode that is actually configured — hardcoding `'workflow-lease'` into the
+ * message would misdirect an operator troubleshooting the shipped global
+ * lease toward an unimplemented feature.
+ */
+export declare function assertOwnershipStorageCapability(storage: Storage, configuredMode: FencingOwnershipMode): void;
+/** Input to {@link assertOwnershipModeMarker}. */
+export type AssertOwnershipModeMarkerInput = {
+    storage: Storage;
+    /** This engine's configured fencing mode. */
+    configuredMode: FencingOwnershipMode;
+    /** Engine-clock source (ms), injected so tests can control `establishedAt` deterministically. */
+    getNow: () => number;
+};
+/**
+ * Gate 2 — ownership-mode marker. Fires immediately after Gate 1 passes, for
+ * the same trigger (`ownership: 'lease'` or `ownership: 'workflow-lease'`;
+ * `ownership: 'none'` never calls this).
+ *
+ * Reads `KEYS.ownershipModeMarker()`. If absent, `conditionalBatch`-puts
+ * `{ mode: configuredMode, establishedAt: now() }` with an expected value of
+ * `null` — the first fencing-mode engine against a fresh store establishes
+ * the mode every later one must agree with. On a CAS loss (another engine won
+ * the race to stamp it), re-reads and compares against that engine's mode
+ * instead, since it is now authoritative. If the stored mode — from either
+ * the initial read or the post-CAS-loss re-read — differs from this engine's
+ * configured mode, throws {@link OwnershipModeMismatchError} before any
+ * further construction proceeds.
+ */
+export declare function assertOwnershipModeMarker(input: AssertOwnershipModeMarkerInput): Promise<void>;
+/** Input to {@link bootstrapOwnershipGates}. */
+export type BootstrapOwnershipGatesInput = {
+    storage: Storage;
+    ownershipMode: EngineOwnershipMode;
+    /** Engine-clock source (ms), injected so tests can control `establishedAt` deterministically. */
+    getNow: () => number;
+};
+/**
+ * Run Gate 1 then Gate 2, in that order, as ADR 0002 requires. No-op for
+ * `ownership: 'none'`, which never touches storage-capability enforcement or
+ * the mode marker. Both gates must complete successfully before any claim
+ * acquisition, recovery scan, scheduler poll, or task poll proceeds — but
+ * wiring this into `Engine` construction or any of those call sites is a
+ * later stage; this function is the standalone, testable unit only.
+ */
+export declare function bootstrapOwnershipGates(input: BootstrapOwnershipGatesInput): Promise<void>;

package/dist/core/engine/ownership-mode-marker.js

@@ -0,0 +1,52 @@
+import {
+  KEYS,
+  requireStorageCapability,
+  storageConditionalBatch
+} from "../../storage/interface.js";
+import { OwnershipModeMismatchError } from "./lease-errors.js";
+import {
+  decodeOwnershipModeMarker,
+  encodeOwnershipModeMarker
+} from "./workflow-claim-codec.js";
+export function assertOwnershipStorageCapability(storage, configuredMode) {
+  requireStorageCapability(storage, "conditionalBatch", `ownership: '${configuredMode}'`);
+}
+async function readOwnershipModeMarkerOrThrowIfCorrupt(storage, markerKey) {
+  const bytes = await storage.get(markerKey);
+  if (bytes === null)
+    return null;
+  const decoded = decodeOwnershipModeMarker(bytes);
+  if (decoded === null)
+    throw Error(`The store's ownership-mode-marker ("${markerKey}") exists but does not decode as a valid { mode, establishedAt } record. Treating an undecodable marker as absent would let this engine silently overwrite whatever mode the store's real prior engines agreed on, defeating the marker's purpose of making a mixed fencing-mode deployment detectable. Resolve by operator repair: inspect the stored bytes and, only if certain no other engine relies on them, delete the key so a fresh marker can be established.`);
+  return decoded;
+}
+function assertOwnershipModeMatches(configuredMode, storedRecord) {
+  if (storedRecord.mode !== configuredMode)
+    throw new OwnershipModeMismatchError(configuredMode, storedRecord.mode, storedRecord.establishedAt);
+}
+export async function assertOwnershipModeMarker(input) {
+  const { storage, configuredMode, getNow } = input, markerKey = KEYS.ownershipModeMarker(), initial = await readOwnershipModeMarkerOrThrowIfCorrupt(storage, markerKey);
+  if (initial !== null) {
+    assertOwnershipModeMatches(configuredMode, initial);
+    return;
+  }
+  if (await storageConditionalBatch(storage, [{ key: markerKey, expectedValue: null }], [
+    {
+      type: "put",
+      key: markerKey,
+      value: encodeOwnershipModeMarker({ mode: configuredMode, establishedAt: getNow() })
+    }
+  ]))
+    return;
+  const reread = await readOwnershipModeMarkerOrThrowIfCorrupt(storage, markerKey);
+  if (reread === null)
+    throw Error(`Lost the compare-and-swap while establishing the store's ownership-mode-marker ("${markerKey}"), and a re-read then found it absent again. This indicates the marker was deleted concurrently during construction rather than raced by another engine's write (which would have left it present). Retry construction once the concurrent deletion has settled.`);
+  assertOwnershipModeMatches(configuredMode, reread);
+}
+export async function bootstrapOwnershipGates(input) {
+  const { storage, ownershipMode, getNow } = input;
+  if (ownershipMode === "none")
+    return;
+  assertOwnershipStorageCapability(storage, ownershipMode);
+  await assertOwnershipModeMarker({ storage, configuredMode: ownershipMode, getNow });
+}

package/dist/core/engine/ownership-options.d.ts

@@ -4,21 +4,37 @@
  * file under the `max-lines` ceiling; mirrors the second-instance resolver's
  * "only validate when the feature is enabled" discipline.
  *
+ * `ownership` is a three-member discriminated union — `'none'`, `'lease'`
+ * (a single store-wide lease), and `'workflow-lease'` (per-workflow fencing,
+ * ADR 0002 at
+ * `documentation/contributing/architecture-decisions/0002-multiengine-per-workflow-ownership.md`).
+ * This module resolves and validates the option surface only: it resolves the
+ * `workflowClaimTtl`/`workflowClaimRenewInterval` tuning fields and rejects
+ * incoherent configuration. The fencing behavior itself lives in the claim
+ * registry, the ownership bootstrap, and the fenced-write path.
+ *
  * @module core/engine/ownership-options
  */
 import type { EngineConstructorOptions, ResolvedOptions } from './engine-internal-types.ts';
+import { WORKFLOW_CLAIM_TTL_SAFETY_MULTIPLIER } from './workflow-claim-transitions.ts';
 /** Default lease time-to-live for `ownership: 'lease'`. */
 export declare const DEFAULT_LEASE_TTL_MS = 30000;
 /** Default lease renewal interval for `ownership: 'lease'`. */
 export declare const DEFAULT_LEASE_RENEW_INTERVAL_MS = 5000;
 /** Default boot-time lease acquisition wait window for `ownership: 'lease'`. */
 export declare const DEFAULT_LEASE_WAIT_TIMEOUT_MS = 60000;
+/** Default per-workflow claim time-to-live for `ownership: 'workflow-lease'`. */
+export declare const DEFAULT_WORKFLOW_CLAIM_TTL_MS = 30000;
+/** Default per-workflow claim renewal interval for `ownership: 'workflow-lease'`. */
+export declare const DEFAULT_WORKFLOW_CLAIM_RENEW_INTERVAL_MS = 5000;
+export { WORKFLOW_CLAIM_TTL_SAFETY_MULTIPLIER };
 export declare function resolveBackgroundTaskMode(options: EngineConstructorOptions | undefined): ResolvedOptions['backgroundTaskMode'];
 /**
- * Resolve the ownership posture and lease tuning into their `ResolvedOptions`
- * fields. Defaults to `'none'`. The lease durations are documented as "ignored
- * when ownership is not 'lease'", so they are only normalized (and thus only
- * able to throw on an invalid value) when lease ownership is actually enabled —
- * an invalid duration must not make an off-by-default config fatal at boot.
+ * Resolve the ownership posture and its per-mode tuning into their
+ * `ResolvedOptions` fields. Defaults to `'none'`. The lease and workflow-claim
+ * durations are documented as "ignored" outside their own mode, so they are
+ * only normalized (and thus only able to throw on an invalid value) when that
+ * mode is actually selected — an invalid duration must not make an off-by-
+ * default config fatal at boot.
  */
-export declare function resolveOwnershipFields(options: EngineConstructorOptions | undefined): Pick<ResolvedOptions, 'ownershipMode' | 'leaseTtlMs' | 'leaseRenewIntervalMs' | 'leaseWaitTimeoutMs'>;
+export declare function resolveOwnershipFields(options: EngineConstructorOptions | undefined): Pick<ResolvedOptions, 'ownershipMode' | 'leaseTtlMs' | 'leaseRenewIntervalMs' | 'leaseWaitTimeoutMs' | 'workflowClaimTtlMs' | 'workflowClaimRenewIntervalMs'>;

package/dist/core/engine/ownership-options.js

@@ -1,5 +1,8 @@
 import { normalizeRetentionDuration } from "./validation.js";
-export const DEFAULT_LEASE_TTL_MS = 30000, DEFAULT_LEASE_RENEW_INTERVAL_MS = 5000, DEFAULT_LEASE_WAIT_TIMEOUT_MS = 60000;
+import { WORKFLOW_CLAIM_TTL_SAFETY_MULTIPLIER } from "./workflow-claim-transitions.js";
+export const DEFAULT_LEASE_TTL_MS = 30000, DEFAULT_LEASE_RENEW_INTERVAL_MS = 5000, DEFAULT_LEASE_WAIT_TIMEOUT_MS = 60000, DEFAULT_WORKFLOW_CLAIM_TTL_MS = 30000, DEFAULT_WORKFLOW_CLAIM_RENEW_INTERVAL_MS = 5000;
+
+export { WORKFLOW_CLAIM_TTL_SAFETY_MULTIPLIER };
 export function resolveBackgroundTaskMode(options) {
   const mode = options?.backgroundTasks ?? "automatic";
   if (mode !== "automatic" && mode !== "manual")
@@ -15,26 +18,53 @@ function assertManualBackgroundTaskCompatibility(options) {
     throw Error('ownership cannot be "lease" when backgroundTasks is "manual"');
 }
 export function resolveOwnershipFields(options) {
-  const ownershipMode = assertKnownOwnershipMode(options?.ownership ?? "none");
-  if (ownershipMode !== "lease")
-    return {
-      ownershipMode,
-      leaseTtlMs: DEFAULT_LEASE_TTL_MS,
-      leaseRenewIntervalMs: DEFAULT_LEASE_RENEW_INTERVAL_MS,
-      leaseWaitTimeoutMs: DEFAULT_LEASE_WAIT_TIMEOUT_MS
-    };
+  const ownershipMode = assertKnownOwnershipMode(options?.ownership ?? "none"), leaseDefaults = {
+    leaseTtlMs: DEFAULT_LEASE_TTL_MS,
+    leaseRenewIntervalMs: DEFAULT_LEASE_RENEW_INTERVAL_MS,
+    leaseWaitTimeoutMs: DEFAULT_LEASE_WAIT_TIMEOUT_MS
+  }, workflowClaimDefaults = {
+    workflowClaimTtlMs: DEFAULT_WORKFLOW_CLAIM_TTL_MS,
+    workflowClaimRenewIntervalMs: DEFAULT_WORKFLOW_CLAIM_RENEW_INTERVAL_MS
+  };
+  if (ownershipMode === "lease")
+    return { ownershipMode, ...resolveLeaseTiming(options), ...workflowClaimDefaults };
+  if (ownershipMode === "workflow-lease") {
+    assertWorkflowLeaseCompatibleWithSecondInstanceDetection(options);
+    return { ownershipMode, ...leaseDefaults, ...resolveWorkflowClaimTiming(options) };
+  }
+  return { ownershipMode, ...leaseDefaults, ...workflowClaimDefaults };
+}
+function resolveLeaseTiming(options) {
   const leaseTtlMs = normalizeRetentionDuration(options?.leaseTtl, "options.leaseTtl") ?? DEFAULT_LEASE_TTL_MS, leaseRenewIntervalMs = normalizeRetentionDuration(options?.leaseRenewInterval, "options.leaseRenewInterval") ?? DEFAULT_LEASE_RENEW_INTERVAL_MS, leaseWaitTimeoutMs = normalizeRetentionDuration(options?.leaseWaitTimeout, "options.leaseWaitTimeout") ?? DEFAULT_LEASE_WAIT_TIMEOUT_MS;
   assertLeaseTimingCoherent(leaseTtlMs, leaseRenewIntervalMs, leaseWaitTimeoutMs);
-  return { ownershipMode, leaseTtlMs, leaseRenewIntervalMs, leaseWaitTimeoutMs };
+  return { leaseTtlMs, leaseRenewIntervalMs, leaseWaitTimeoutMs };
+}
+function resolveWorkflowClaimTiming(options) {
+  const workflowClaimTtlMs = normalizeRetentionDuration(options?.workflowClaimTtl, "options.workflowClaimTtl") ?? DEFAULT_WORKFLOW_CLAIM_TTL_MS, workflowClaimRenewIntervalMs = normalizeRetentionDuration(options?.workflowClaimRenewInterval, "options.workflowClaimRenewInterval") ?? DEFAULT_WORKFLOW_CLAIM_RENEW_INTERVAL_MS;
+  assertWorkflowClaimTimingCoherent(workflowClaimTtlMs, workflowClaimRenewIntervalMs);
+  return { workflowClaimTtlMs, workflowClaimRenewIntervalMs };
 }
 function assertKnownOwnershipMode(mode) {
-  if (mode !== "none" && mode !== "lease")
-    throw Error(`Unknown ownership posture "${String(mode)}". Expected 'none' or 'lease'.`);
+  if (mode !== "none" && mode !== "lease" && mode !== "workflow-lease")
+    throw Error(`Unknown ownership posture "${mode}". Expected 'none', 'lease', or 'workflow-lease'.`);
   return mode;
 }
+function assertWorkflowLeaseCompatibleWithSecondInstanceDetection(options) {
+  if (options?.detectSecondInstance === !0)
+    throw Error("ownership: 'workflow-lease' cannot be combined with detectSecondInstance: true " + "\u2014 second-instance detection assumes a single global owner.");
+}
 function assertLeaseTimingCoherent(leaseTtlMs, leaseRenewIntervalMs, leaseWaitTimeoutMs) {
   if (leaseTtlMs <= 0 || leaseRenewIntervalMs <= 0 || leaseWaitTimeoutMs <= 0)
     throw Error(`ownership: 'lease' requires positive leaseTtl, leaseRenewInterval, and leaseWaitTimeout (got leaseTtl=${leaseTtlMs}ms, leaseRenewInterval=${leaseRenewIntervalMs}ms, leaseWaitTimeout=${leaseWaitTimeoutMs}ms).`);
   if (leaseRenewIntervalMs >= leaseTtlMs)
     throw Error(`ownership: 'lease' requires leaseRenewInterval (${leaseRenewIntervalMs}ms) to be strictly less than leaseTtl (${leaseTtlMs}ms), so a renewal fires before the lease can lapse.`);
 }
+function assertWorkflowClaimTimingCoherent(workflowClaimTtlMs, workflowClaimRenewIntervalMs) {
+  if (workflowClaimTtlMs <= 0 || workflowClaimRenewIntervalMs <= 0)
+    throw Error(`ownership: 'workflow-lease' requires positive workflowClaimTtl and workflowClaimRenewInterval (got workflowClaimTtl=${workflowClaimTtlMs}ms, workflowClaimRenewInterval=${workflowClaimRenewIntervalMs}ms).`);
+  if (workflowClaimRenewIntervalMs >= workflowClaimTtlMs)
+    throw Error(`ownership: 'workflow-lease' requires workflowClaimRenewInterval (${workflowClaimRenewIntervalMs}ms) to be strictly less than workflowClaimTtl (${workflowClaimTtlMs}ms), so a renewal fires before the claim can lapse.`);
+  const requiredTtlMs = WORKFLOW_CLAIM_TTL_SAFETY_MULTIPLIER * workflowClaimRenewIntervalMs;
+  if (workflowClaimTtlMs < requiredTtlMs)
+    throw Error(`ownership: 'workflow-lease' requires workflowClaimTtl (${workflowClaimTtlMs}ms) to be at least WORKFLOW_CLAIM_TTL_SAFETY_MULTIPLIER (${WORKFLOW_CLAIM_TTL_SAFETY_MULTIPLIER}) times workflowClaimRenewInterval (${workflowClaimRenewIntervalMs}ms), i.e. at least ${requiredTtlMs}ms, so a stalled renewal has margin before the claim can be taken over.`);
+}

package/dist/core/engine/pending-updates.js

@@ -2,10 +2,9 @@ import { UpdateCompletedEvent, UpdateReceivedEvent } from "../events.js";
 import { UpdateValidationError } from "../updates.js";
 import { notifyConditionWaiters } from "./condition-waiters.js";
 import { commitFencedEngineWrite } from "./fenced-write.js";
-import {
-  extractStandardSchemaIssues,
-  invokeUpdateHandler as invokeUpdateHandlerFromInternals
-} from "./updates.js";
+import { invokeUpdateHandler as invokeUpdateHandlerFromInternals } from "./invoke-update-handler.js";
+import { isLiveContextStale } from "./queries.js";
+import { extractStandardSchemaIssues } from "./update-validation.js";
 async function waitForNextMacrotask() {
   await new Promise((resolve) => {
     setTimeout(resolve, 0);
@@ -63,32 +62,44 @@ async function runPendingUpdateValidator(validator, updateName, payload) {
     return new UpdateValidationError(updateName, issues).message;
   return null;
 }
+async function resolveLiveHandlerContext(internals, workflowId) {
+  const stale = isLiveContextStale(internals, workflowId);
+  if (stale !== !1 && await stale)
+    return;
+  return internals.inlineStrategy?.getContext(workflowId);
+}
+async function processOnePendingUpdate(internals, workflowId, update, handlers, context, callbacks) {
+  const handler = handlers.get(update.name);
+  if (!handler)
+    return !1;
+  if (!claimPendingUpdateForDelivery(internals, workflowId, update.updateId))
+    return !1;
+  const validatorRejectionError = await runValidatorIfPresent(context, update);
+  if (validatorRejectionError !== null) {
+    await rejectPendingUpdate(internals, workflowId, update, validatorRejectionError, callbacks);
+    return !1;
+  }
+  await deliverPendingUpdate(internals, workflowId, update, handler, callbacks);
+  return !0;
+}
 export async function processPendingUpdatesForHandlers(internals, workflowId, callbacks) {
-  const context = internals.inlineStrategy?.getContext(workflowId);
+  const initialContext = internals.inlineStrategy?.getContext(workflowId);
+  if (!initialContext || initialContext.updateHandlers.size === 0)
+    return;
+  const pendingUpdates = await internals.updateCoordinator.getPendingUpdates(workflowId);
+  if (pendingUpdates.length === 0)
+    return;
+  const context = await resolveLiveHandlerContext(internals, workflowId);
   if (!context)
     return;
   const handlers = context.updateHandlers;
   if (handlers.size === 0)
     return;
-  const pendingUpdates = await internals.updateCoordinator.getPendingUpdates(workflowId);
-  if (pendingUpdates.length === 0)
-    return;
   let handlerRan = !1;
   try {
-    for (const update of pendingUpdates) {
-      const handler = handlers.get(update.name);
-      if (!handler)
-        continue;
-      if (!claimPendingUpdateForDelivery(internals, workflowId, update.updateId))
-        continue;
-      const validatorRejectionError = await runValidatorIfPresent(context, update);
-      if (validatorRejectionError !== null) {
-        await rejectPendingUpdate(internals, workflowId, update, validatorRejectionError, callbacks);
-        continue;
-      }
-      handlerRan = !0;
-      await deliverPendingUpdate(internals, workflowId, update, handler, callbacks);
-    }
+    for (const update of pendingUpdates)
+      if (await processOnePendingUpdate(internals, workflowId, update, handlers, context, callbacks))
+        handlerRan = !0;
   } finally {
     if (handlerRan)
       notifyConditionWaiters(internals, workflowId);
@@ -113,7 +124,7 @@ async function runValidatorIfPresent(context, update) {
 }
 async function rejectPendingUpdate(internals, workflowId, update, errorMessage, callbacks) {
   const responseOperations = internals.updateCoordinator.buildResponseOperations(update.updateId, workflowId, void 0, errorMessage, update.idempotencyKey);
-  await commitFencedEngineWrite(internals, responseOperations, [], () => Error(`Update rejection for workflow "${workflowId}" lost its CAS race.`));
+  await commitFencedEngineWrite(internals, workflowId, responseOperations, [], () => Error(`Update rejection for workflow "${workflowId}" lost its CAS race.`));
   callbacks.broadcast({ type: "update:completed", workflowId, updateId: update.updateId });
 }
 async function deliverPendingUpdate(internals, workflowId, update, handler, callbacks) {
@@ -125,7 +136,7 @@ async function deliverPendingUpdate(internals, workflowId, update, handler, call
     error = handlerError instanceof Error ? handlerError.message : String(handlerError);
   }
   const responseOperations = internals.updateCoordinator.buildResponseOperations(update.updateId, workflowId, result, error, update.idempotencyKey);
-  await commitFencedEngineWrite(internals, responseOperations, [], () => Error(`Update response for workflow "${workflowId}" lost its CAS race.`));
+  await commitFencedEngineWrite(internals, workflowId, responseOperations, [], () => Error(`Update response for workflow "${workflowId}" lost its CAS race.`));
   callbacks.dispatchEvent(new UpdateCompletedEvent(update.updateId, workflowId, update.name, result, error));
   callbacks.broadcast({ type: "update:completed", workflowId, updateId: update.updateId });
 }

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

@@ -1,3 +1,73 @@
 import type { EngineInternals } from './internals.ts';
+/**
+ * Thrown by `query()` when this engine has no live local execution context for
+ * `workflowId` AND a durable `ownership: 'workflow-lease'` claim shows another
+ * engine currently holds it — distinguishing "not owned here, retry against
+ * the owner" from a query handler that legitimately resolved to `undefined`.
+ * A workflow that is simply terminal, purged, or never existed still resolves
+ * to plain `undefined`, unchanged — this error fires only when a live holder
+ * record names a DIFFERENT engine.
+ *
+ * Not a public `WeftError`: ADR 0002 § Open questions leaves the cross-engine
+ * query/update ROUTING mechanism open (forward to the true owner vs. surface
+ * a retry-elsewhere error to the caller); this is the smaller, non-speculative
+ * fix for the silent-`undefined` bug alone, reusing the same "untyped `Error`"
+ * shape Gate 1 (`requireStorageCapability`) already ships for a similarly
+ * not-yet-typed diagnostic rather than adding a new public error code and its
+ * full registration surface for a routing question ADR 0002 has not settled.
+ * `query()` has no durable fallback path the way `update()`'s coordinated
+ * path does (see `updates.ts`), so surfacing an error here — rather than a
+ * value indistinguishable from a real `undefined` result — is the only
+ * correct option.
+ */
+export declare class WorkflowNotLocallyOwnedError extends Error {
+    readonly workflowId: string;
+    constructor(workflowId: string);
+}
+/**
+ * Cheap, read-only check for whether `workflowId` is durably claimed by a
+ * DIFFERENT engine under `ownership: 'workflow-lease'` — a
+ * `wakeOwnershipCheck`-style storage read (one `storage.get`, no
+ * `conditionalBatch`), not the actual safety mechanism. Always `false`
+ * (inert) under `ownership: 'none'`/`'lease'`, where no claim registry is
+ * installed.
+ *
+ * Always re-reads the durable holder rather than trusting this engine's own
+ * cached `registry.currentEpoch(workflowId)`: after a takeover elsewhere,
+ * this engine's local claim entry stays populated (and its cached epoch
+ * stale) until its next renewal CAS independently detects the loss — a
+ * `registry.currentEpoch(workflowId) !== null` shortcut would let a stale
+ * engine keep answering `false` (and so keep serving queries/updates from a
+ * deposed context) for up to a full renewal interval. Deciding by the
+ * durable holder's `engineId` alone — not epoch — is sufficient here: this
+ * engine reacquiring the same workflow at a new epoch after a release still
+ * means the holder names THIS engine, correctly answering `false`.
+ */
+export declare function isWorkflowClaimedByAnotherEngine(internals: EngineInternals, workflowId: string): Promise<boolean>;
+/**
+ * `true` when `workflowId`'s persisted `WorkflowState` is missing (never
+ * existed, or already purged) or terminal. Used to ignore a durably stale
+ * `wf-owner-holder:<id>` record: a normal owner-side complete/fail commit is
+ * fenced but does not delete the holder record (only an explicit `release`
+ * — graceful shutdown or the reclaim scan's redrive-detects-terminal path —
+ * or a `takeover`/rotation does), so a contextless query for an already-
+ * terminal workflow can otherwise see a holder record naming a DIFFERENT
+ * engine and incorrectly throw `WorkflowNotLocallyOwnedError` for a workflow
+ * every engine agrees has already finished. Documented behavior is that
+ * terminal, purged, or unknown workflows keep resolving to plain
+ * `undefined` — this check restores that for the `workflow-lease` claim
+ * path specifically.
+ */
+export declare function isWorkflowLocallyTerminalOrMissing(internals: EngineInternals, workflowId: string): Promise<boolean>;
+/**
+ * `internals.workflowClaimRegistry !== null && (await isWorkflowClaimedByAnotherEngine(...))`,
+ * factored out so every "revalidate before serving a possibly-stale live
+ * Context" call site — `query()` below and `tryInlineUpdateHandler` in
+ * `updates.ts` — shares the exact same registry-gated short-circuit. The
+ * registry-null check is a plain property read, not an unconditional await,
+ * so `ownership: 'none'`/`'lease'` stay exactly as synchronous as they are
+ * today; only `'workflow-lease'` pays for the cheap durable read.
+ */
+export declare function isLiveContextStale(internals: EngineInternals, workflowId: string): boolean | Promise<boolean>;
 /** Resolve a workflow query from built-in progress state or exposed inline accessors. */
 export declare function query(internals: EngineInternals, workflowId: string, name: string, input?: unknown): Promise<unknown>;

package/dist/core/engine/queries.js

@@ -1,16 +1,70 @@
+import { KEYS } from "../../storage/interface.js";
+import { decodeWorkflowState, isTerminalWorkflowStatus } from "./validation.js";
+import { decodeWorkflowClaimHolder } from "./workflow-claim-codec.js";
+
+export class WorkflowNotLocallyOwnedError extends Error {
+  workflowId;
+  constructor(workflowId) {
+    super(`Workflow "${workflowId}" has no live query context on this engine, and a durable workflow-lease claim shows another engine currently owns it. Retry the query against the engine that currently holds the claim.`);
+    this.name = "WorkflowNotLocallyOwnedError";
+    this.workflowId = workflowId;
+  }
+}
+export async function isWorkflowClaimedByAnotherEngine(internals, workflowId) {
+  const registry = internals.workflowClaimRegistry;
+  if (registry === null)
+    return !1;
+  const raw = await internals.storage.get(KEYS.workflowOwnerHolder(workflowId));
+  if (raw === null)
+    return !1;
+  const holder = decodeWorkflowClaimHolder(raw);
+  if (holder === null)
+    return !1;
+  return holder.engineId !== registry.engineId;
+}
+export async function isWorkflowLocallyTerminalOrMissing(internals, workflowId) {
+  const stateBytes = await internals.storage.get(KEYS.workflow(workflowId));
+  if (stateBytes === null)
+    return !0;
+  const state = decodeWorkflowState(stateBytes);
+  return isTerminalWorkflowStatus(state.status);
+}
+export function isLiveContextStale(internals, workflowId) {
+  if (internals.workflowClaimRegistry === null)
+    return !1;
+  return isWorkflowClaimedByAnotherEngine(internals, workflowId);
+}
+function resolveDispatchContext(inlineStrategy, workflowId) {
+  return inlineStrategy.getContext(workflowId) ?? inlineStrategy.getParkedContext(workflowId);
+}
+async function resolveContextlessQueryResult(internals, workflowId) {
+  if (await isWorkflowClaimedByAnotherEngine(internals, workflowId) && !await isWorkflowLocallyTerminalOrMissing(internals, workflowId))
+    throw new WorkflowNotLocallyOwnedError(workflowId);
+  return;
+}
 export async function query(internals, workflowId, name, input) {
   if (name === "activityProgress")
     return internals.heartbeatDetails.get(workflowId);
   const inlineStrategy = internals.inlineStrategy;
   if (!inlineStrategy)
     throw Error("Workflow queries are not supported when using the worker execution strategy.");
-  const context = inlineStrategy.getContext(workflowId) ?? inlineStrategy.getParkedContext(workflowId);
+  const context = resolveDispatchContext(inlineStrategy, workflowId);
   if (!context)
-    return;
-  const queryHandler = context.queryHandlers.get(name);
+    return resolveContextlessQueryResult(internals, workflowId);
+  const staleCheck = isLiveContextStale(internals, workflowId);
+  let liveContext = context;
+  if (staleCheck !== !1) {
+    if (await staleCheck)
+      throw new WorkflowNotLocallyOwnedError(workflowId);
+    const refreshedContext = resolveDispatchContext(inlineStrategy, workflowId);
+    if (!refreshedContext)
+      return;
+    liveContext = refreshedContext;
+  }
+  const queryHandler = liveContext.queryHandlers.get(name);
   if (queryHandler)
     return queryHandler(input);
-  const accessor = context.exposedAccessors.get(name);
+  const accessor = liveContext.exposedAccessors.get(name);
   if (!accessor)
     return;
   return accessor();

package/dist/core/engine/schedules.js

@@ -238,5 +238,5 @@ export async function handleScheduledWorkflowTerminal(internals, workflowId, cal
   });
 }
 async function deleteTransientScheduleRunMetadata(internals, workflowId) {
-  await commitFencedEngineWrite(internals, [{ type: "delete", key: KEYS.scheduleRun(workflowId) }], [], () => Error(`Schedule-run cleanup for workflow "${workflowId}" lost its precondition.`));
+  await commitFencedEngineWrite(internals, workflowId, [{ type: "delete", key: KEYS.scheduleRun(workflowId) }], [], () => Error(`Schedule-run cleanup for workflow "${workflowId}" lost its precondition.`));
 }

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

@@ -30,7 +30,17 @@ export type ConsumedSignalResult = {
     payload: unknown;
 };
 export declare function signal(internals: EngineInternals, workflowId: string, name: string, payload: unknown, callbacks: SignalCallbacks, options?: SignalDeliveryOptions): Promise<void>;
-export declare function releaseSignalWaiter(internals: EngineInternals, workflowId: string, waiterKey: string, expectedResolve?: () => void): void;
+/**
+ * Remove the signal waiter registered under `waiterKey`, optionally only when
+ * it is still `expectedResolve`.
+ *
+ * Returns whether THIS call removed that exact waiter. Callers that go on to
+ * invoke the resolver must gate on the return value: a waiter captured before
+ * an await can be replaced by replay or a fresh park while that await is in
+ * flight, and invoking the captured resolver anyway advances a superseded
+ * generator even though the replacement was correctly left in place.
+ */
+export declare function releaseSignalWaiter(internals: EngineInternals, workflowId: string, waiterKey: string, expectedResolve?: () => void): boolean;
 export declare function bufferSignalPayloads(internals: EngineInternals, workflowId: string, deliveries: BufferedSignalDelivery[], callbacks: SignalCallbacks, defaultOptions?: SignalDeliveryOptions): Promise<void>;
 /**
  * Build the durable operations for a single keyed signal so it can be folded

package/dist/core/engine/signals.js

@@ -11,6 +11,7 @@ import { validateSignalId } from "../signal-id.js";
 import { commitAnonymousSignalOperations } from "./anonymous-signal-sequence.js";
 import { stageAtomicWorkflowCommitSideEffects } from "./checkpoint-side-effects.js";
 import { isTerminalWorkflowStatus } from "./validation.js";
+import { confirmWakeOwnership } from "./wake-ownership-guard.js";
 const EMPTY_STORAGE_VALUE = new Uint8Array(0), SIGNAL_ACCEPTED_RESPONSE = { ok: !0 }, SIGNAL_KEY_COMPONENT_COUNT = 5;
 export async function signal(internals, workflowId, name, payload, callbacks, options = {}) {
   const deliverSignal = async (targetWorkflowId, signalName, signalPayload) => {
@@ -44,11 +45,12 @@ export async function signal(internals, workflowId, name, payload, callbacks, op
 export function releaseSignalWaiter(internals, workflowId, waiterKey, expectedResolve) {
   const currentWaiter = internals.signalWaiters.get(waiterKey);
   if (!currentWaiter)
-    return;
+    return !1;
   if (expectedResolve && currentWaiter !== expectedResolve)
-    return;
+    return !1;
   internals.signalWaiters.delete(waiterKey);
   untrackWaiterKey(internals.signalWaitersByWorkflow, workflowId, waiterKey);
+  return !0;
 }
 export async function bufferSignalPayloads(internals, workflowId, deliveries, callbacks, defaultOptions = {}) {
   if (deliveries.length === 0)
@@ -69,11 +71,11 @@ export async function bufferSignalPayloads(internals, workflowId, deliveries, ca
     if (!await storageConditionalBatch(internals.storage, [{ key: acceptedResponseKey, expectedValue: null }], [...operations, { type: "put", key: acceptedResponseKey, value: acceptedResponse }]))
       return;
     markTerminalCleanupTracked(internals, workflowId);
-    deliverBufferedSignals(internals, workflowId, deliveries, callbacks);
+    await deliverBufferedSignals(internals, workflowId, deliveries, callbacks);
     return;
   }
   await commitAnonymousSignalOperations(internals, workflowId, deliveries, (operations) => appendTerminalCleanupOperation(internals, workflowId, operations), () => markTerminalCleanupTracked(internals, workflowId));
-  deliverBufferedSignals(internals, workflowId, deliveries, callbacks);
+  await deliverBufferedSignals(internals, workflowId, deliveries, callbacks);
 }
 function createExplicitSignalOperations(internals, workflowId, deliveries, signalId) {
   return deliveries.map(({ signalName, payload }) => ({
@@ -109,7 +111,7 @@ function appendTerminalCleanupOperation(internals, workflowId, operations) {
 function markTerminalCleanupTracked(internals, workflowId) {
   internals.workflowsNeedingTerminalCleanup.add(workflowId);
 }
-function deliverBufferedSignals(internals, workflowId, deliveries, callbacks) {
+async function deliverBufferedSignals(internals, workflowId, deliveries, callbacks) {
   let shouldResumeParkedWorkflow = !1;
   for (const { signalName, payload, options } of deliveries) {
     if (options?.emitPublicEvent !== !1) {
@@ -118,8 +120,10 @@ function deliverBufferedSignals(internals, workflowId, deliveries, callbacks) {
     }
     const waiterKey = `${workflowId}:${signalName}`, waiter = internals.signalWaiters.get(waiterKey);
     if (waiter) {
-      releaseSignalWaiter(internals, workflowId, waiterKey, waiter);
-      waiter();
+      if (internals.workflowClaimRegistry !== null && await confirmWakeOwnership(internals, workflowId, "signal") === "discard")
+        continue;
+      if (releaseSignalWaiter(internals, workflowId, waiterKey, waiter))
+        waiter();
       continue;
     }
     if (internals.parkedInlineWorkflows.has(workflowId))