@lostgradient/weft 0.19.0 → 0.21.0

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

package/dist/core/engine/sleep-timer-acknowledgements.d.ts

@@ -5,7 +5,75 @@ export type SleepTimerAcknowledgement = {
     cancel: () => void;
     promise: Promise<void>;
 };
+/**
+ * Durable sleep timers fire globally — under `ownership: 'workflow-lease'`
+ * every engine sharing the store observes the same expired timer, not only
+ * the workflow's owner (see ADR 0002's entry-point classification: the
+ * scheduler dispatch shell is claim-acquiring only for claim-ACQUIRING
+ * branches; this one is claim-REQUIRING and checks for itself). Running
+ * `confirmWakeOwnership` FIRST — before `shouldIgnoreUnclaimedSleepTimer`
+ * even loads workflow state — matters: on a non-owning engine that state
+ * legitimately reads `'running'` (the true owner is actively driving it),
+ * which would otherwise hit `shouldIgnoreUnclaimedSleepTimer`'s "fired
+ * before ready" throw meant for a same-engine registration race, not a
+ * cross-engine ownership miss.
+ *
+ * A discard is NOT a silent no-op: `handleTimerFired`'s caller — the
+ * `Scheduler` — treats a callback that returns without throwing as
+ * "processed" and durably deletes the fired timer key
+ * (`commitTimerCleanup`, engine-scoped and unfenced on any single workflow's
+ * claim, since one tick's cleanup batch can span fired timers from many
+ * workflows — see `src/core/engine/index.ts`'s `Scheduler` wiring). If a
+ * discarding non-owner let that deletion proceed, it would delete the true
+ * owner's only durable record of this fire before the owner ever observes
+ * it — see `retainDiscardedDurableTimer` below.
+ */
 export declare function handleSleepTimerWithAcknowledgement(internals: EngineInternals, entry: TimerEntry, loadWorkflowState: (workflowId: string) => Promise<WorkflowState | null>): Promise<void>;
+/** What to do with a durable timer key once a claim-requiring wake has discarded it. */
+export type DiscardedTimerDisposition = 'retain' | 'collect';
+/**
+ * Decide what a discarded claim-requiring timer fire (ADR 0002's `sleep` and
+ * `wait-condition` wake kinds — see `operations-time.ts`'s
+ * `resolveConditionTimer` for the second caller) should do with its durable
+ * timer key. Shared by both wake kinds because they share the exact same
+ * hazard: `commitTimerCleanup` batches deletes across many workflows in one
+ * engine-scoped, unfenced write, so a non-owner that discards must not let
+ * the Scheduler treat the fire as "processed" while some other engine still
+ * needs the same durable record to perform the real wake.
+ *
+ * "Not locally owned" is not by itself proof the timer is stale, though —
+ * `resolveSleepTimer`'s own comment documents that a durable sleep timer
+ * OUTLIVES terminal cleanup (cleanup only drops the in-memory resolver, not
+ * the durable key). Blindly retaining on every discard would turn an
+ * orphaned post-terminal timer into an immortal one: every engine sharing
+ * the store would rediscover it, discard it, and retain it again on every
+ * Scheduler tick forever. So this reads the workflow's CURRENT persisted
+ * status to disambiguate:
+ * - `null`, or a terminal status ({@link isTerminalWorkflowStatus}):
+ *   `'collect'` — no engine holds or will ever again acquire a claim for
+ *   this workflow, so nothing will ever consume this fire; let the
+ *   Scheduler's normal cleanup remove the orphaned key, matching
+ *   pre-ADR-0002 behavior for an unclaimed timer.
+ * - `'suspended'`: `'collect'` — `engine.suspend()`'s durable re-arm
+ *   establishes its own fresh timer on resume; the pre-suspend fire being
+ *   discarded here is not the one that wakes the resumed run.
+ * - any other status (`'running'`, `'pending'`): `'retain'` — some engine
+ *   still holds, or will still acquire, a live claim for this workflow;
+ *   leave the durable key so that engine's own copy of this same fire
+ *   performs the real wake and deletes it for real, bounded by that
+ *   engine's own next Scheduler poll.
+ */
+export declare function resolveDiscardedTimerDisposition(workflowId: string, loadWorkflowState: (workflowId: string) => Promise<WorkflowState | null>): Promise<DiscardedTimerDisposition>;
+/**
+ * Apply {@link resolveDiscardedTimerDisposition} to a discarded claim-requiring
+ * timer fire: throws when the durable key must be retained, so the
+ * `Scheduler`'s `#processSelectedTimer` catch block treats this fire as
+ * `'retry'` — leaving the timer key in storage instead of collecting it —
+ * and resolves normally when the workflow is gone, terminal, or suspended,
+ * so a genuinely orphaned timer is still collected exactly as it was before
+ * this ownership check existed.
+ */
+export declare function retainDiscardedDurableTimer(timerId: string, workflowId: string, loadWorkflowState: (workflowId: string) => Promise<WorkflowState | null>): Promise<void>;
 export declare function createSleepTimerAcknowledgement(internals: EngineInternals, workflowId: string, operationId: string, fireAt: number): SleepTimerAcknowledgement;
 export declare function recordDurableInlineOperation(internals: EngineInternals, workflowId: string, operation: ContextOperationRequest): void;
 export declare function settleSleepTimerAcknowledgements(internals: EngineInternals, workflowId: string, disposition: 'suspended' | 'terminal'): void;

package/dist/core/engine/sleep-timer-acknowledgements.js

@@ -1,4 +1,10 @@
+import { isTerminalWorkflowStatus } from "./validation.js";
+import { confirmWakeOwnership } from "./wake-ownership-guard.js";
 export async function handleSleepTimerWithAcknowledgement(internals, entry, loadWorkflowState) {
+  if (await confirmWakeOwnership(internals, entry.workflowId, "sleep") === "discard") {
+    await retainDiscardedDurableTimer(entry.id, entry.workflowId, loadWorkflowState);
+    return;
+  }
   const operationId = entry.id.replace("sleep:", "");
   if (await shouldIgnoreUnclaimedSleepTimer(internals, entry, operationId, loadWorkflowState))
     return;
@@ -9,6 +15,19 @@ export async function handleSleepTimerWithAcknowledgement(internals, entry, load
   }
   await acknowledgement?.promise;
 }
+export async function resolveDiscardedTimerDisposition(workflowId, loadWorkflowState) {
+  const state = await loadWorkflowState(workflowId);
+  if (state === null)
+    return "collect";
+  if (state.status === "suspended" || isTerminalWorkflowStatus(state.status))
+    return "collect";
+  return "retain";
+}
+export async function retainDiscardedDurableTimer(timerId, workflowId, loadWorkflowState) {
+  if (await resolveDiscardedTimerDisposition(workflowId, loadWorkflowState) !== "retain")
+    return;
+  throw Error(`Durable timer "${timerId}" for workflow "${workflowId}" was discarded by a non-owning engine under ownership: 'workflow-lease'; retaining it in storage for the true owner instead of letting the scheduler delete it.`);
+}
 async function shouldIgnoreUnclaimedSleepTimer(internals, entry, operationId, loadWorkflowState) {
   const resolverKey = `${entry.workflowId}:${operationId}`;
   if (internals.sleepResolvers.has(resolverKey) || internals.inlineStrategy === null)