@lostgradient/weft 0.20.0 → 0.21.0

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)

package/dist/core/engine/storage-io.d.ts

@@ -1,6 +1,7 @@
 import { type BatchOperation } from '../../storage/interface.ts';
 import type { ScheduleState, WorkflowState } from '../types.ts';
 import type { EngineInternals } from './internals.ts';
+import { type WorkflowClaimTransitionFragment } from './workflow-claim-transitions.ts';
 /** Run a workflow-state write after any earlier write for that workflow has settled. */
 export declare function runSerializedWorkflowStateWrite<TResult>(internals: EngineInternals, workflowId: string, writeOperation: () => Promise<TResult>): Promise<TResult>;
 /**
@@ -15,23 +16,70 @@ export declare function runSerializedWorkflowStateWrite<TResult>(internals: Engi
 export declare function runSerializedScheduleStateOperation<TResult>(internals: EngineInternals, scheduleId: string, operation: () => Promise<TResult>): Promise<TResult>;
 /** Load and decode persisted workflow state by workflow ID. */
 export declare function loadWorkflowState(internals: EngineInternals, workflowId: string): Promise<WorkflowState | null>;
+/**
+ * Derive a terminal result (or throw the persisted terminal error) from an
+ * ALREADY-LOADED `WorkflowState` — pure, no storage read. Callers that hold a
+ * state snapshot they have already validated as terminal (e.g.
+ * `bootstrapWorkflowResultResolver`) must use this instead of
+ * {@link loadWorkflowResult}: a second independent `loadWorkflowState` read
+ * can observe a DIFFERENT run than the one the caller validated, if
+ * `onTerminalConflict: 'start-new'` replaces the workflow between the two
+ * reads — attributing a replacement run's result (or a spurious "still
+ * running") to a waiter that was made terminal by the original run.
+ */
+export declare function deriveWorkflowResultFromState(state: WorkflowState): unknown;
 /** Load a terminal workflow result or throw the persisted terminal error. */
 export declare function loadWorkflowResult(internals: EngineInternals, workflowId: string): Promise<unknown>;
 type WorkflowStateCommitOptions = {
     includePendingAtomicSideEffects?: boolean;
 };
 /**
- * Commit an engine-generator-owned workflow-state advance, FENCED on the lease
- * epoch under `ownership: 'lease'` (issue #470 Step 2). A deposed engine's write
- * loses its CAS instead of corrupting the successor's state; the deposition is
- * detected and the engine halts (see {@link commitFencedEngineWrite}). Under
- * `ownership: 'none'` it is byte-for-byte the pre-Step-2 commit shape — the epoch
- * condition is only appended when a lease is held. Use this for suspend,
- * completion, and other state advances driven by the workflow lifecycle. Operator/
- * external mutations (search-attribute and tag edits) do NOT use this helper; they
- * batch directly and are intentionally never fenced.
+ * Build the `wf-owner-epoch:<id>` / `wf-owner-holder:<id>` ROTATION fragment
+ * for an EXTERNAL terminal transition — cancel, timeout, suspend, purge (ADR
+ * 0002 § "External terminal transitions must rotate the epoch"). Any engine
+ * may commit these against a workflow it does not own; deleting the holder
+ * alone is not sufficient to make that safe, so the epoch is rotated in the
+ * SAME atomic batch that writes the terminal/suspended state, deposing a
+ * still-running owner — its next write carries the now-stale epoch and loses
+ * its CAS. Meant to be folded (via `[...fragment.operations]` /
+ * `[...fragment.conditions]`) into the caller's own operations/conditions,
+ * never committed standalone.
+ *
+ * Under `ownership: 'none'` or `'lease'` this returns an EMPTY fragment with
+ * NO storage read: the `wf-owner-*` keyspace is not in play under those
+ * modes, and this function must not touch it — that is what keeps external
+ * terminal commits byte-for-byte unchanged there.
+ */
+export declare function buildExternalTerminalRotationFragment(internals: EngineInternals, workflowId: string): Promise<WorkflowClaimTransitionFragment>;
+/**
+ * Commit a SELF-transition workflow-state advance (complete, fail): this
+ * engine is finishing its OWN workflow, so the write is workflow-scoped and
+ * fenced on THIS engine's claim epoch under `ownership: 'workflow-lease'`
+ * (via {@link commitFencedEngineWrite}'s `workflowId` parameter), or the
+ * global lease epoch under `ownership: 'lease'`. A deposed engine's write
+ * loses its CAS instead of corrupting the successor's state; the deposition
+ * is detected and the engine (or, under `workflow-lease`, just this one
+ * workflow) halts. Under `ownership: 'none'` this is byte-for-byte the
+ * pre-ADR commit shape. Never rotates `wf-owner-epoch:<id>` — that is the
+ * external-transition shape below. Operator/external mutations
+ * (search-attribute and tag edits) do NOT use this helper; they batch
+ * directly and are intentionally never fenced.
+ */
+export declare function commitSelfWorkflowStateOperations(internals: EngineInternals, state: WorkflowState, operations: BatchOperation[], options?: WorkflowStateCommitOptions): Promise<void>;
+/**
+ * Commit an EXTERNAL terminal workflow-state transition — cancel, timeout, or
+ * suspend (ADR 0002 § "External terminal transitions must rotate the
+ * epoch"). ANY engine may commit these against a workflow it does not own, so
+ * — unlike {@link commitSelfWorkflowStateOperations} — this is never fenced
+ * on this engine's own workflow claim (`workflowId: null` is passed to
+ * {@link commitFencedEngineWrite}). Instead {@link
+ * buildExternalTerminalRotationFragment} folds a claim ROTATION into the same
+ * atomic batch under `ownership: 'workflow-lease'`, deposing a still-running
+ * owner. Under `ownership: 'lease'` the write still carries the global lease
+ * epoch condition (via `commitFencedEngineWrite`'s `workflowId: null` path);
+ * under `'none'` it is byte-for-byte unchanged.
  */
-export declare function commitFencedWorkflowStateOperations(internals: EngineInternals, state: WorkflowState, operations: BatchOperation[], options?: WorkflowStateCommitOptions): Promise<void>;
+export declare function commitExternalTerminalWorkflowStateOperations(internals: EngineInternals, state: WorkflowState, operations: BatchOperation[], options?: WorkflowStateCommitOptions): Promise<void>;
 /** Load and decode persisted schedule state by schedule ID. */
 export declare function loadScheduleState(internals: EngineInternals, scheduleId: string): Promise<ScheduleState | null>;
 /** Load a schedule state. */

package/dist/core/engine/storage-io.js

@@ -14,6 +14,9 @@ import { resolveEffectiveScheduleFireAt } from "./schedule-jitter.js";
 import { createScheduleTimerId, decodeWorkflowStartHeaders } from "./state-utilities.js";
 import { decodeWorkflowState } from "./validation.js";
 import { decodeScheduleState } from "./validation/schedule.js";
+import {
+  buildWorkflowClaimExternalTerminalRotationTransition
+} from "./workflow-claim-transitions.js";
 export async function runSerializedWorkflowStateWrite(internals, workflowId, writeOperation) {
   const execution = (internals.workflowStateWriteChains.get(workflowId) ?? Promise.resolve()).catch(() => {
     return;
@@ -51,10 +54,7 @@ export async function loadWorkflowState(internals, workflowId) {
     return null;
   return decodeWorkflowState(bytes);
 }
-export async function loadWorkflowResult(internals, workflowId) {
-  const state = await loadWorkflowState(internals, workflowId);
-  if (!state)
-    throw Error(`Workflow "${workflowId}" not found`);
+export function deriveWorkflowResultFromState(state) {
   if (state.status === "completed")
     return state.result;
   if (state.status === "failed") {
@@ -67,9 +67,15 @@ export async function loadWorkflowResult(internals, workflowId) {
     throw Error("Workflow cancelled");
   if (state.status === "timed-out") {
     const elapsed = state.executionDeadline ? state.executionDeadline - getWorkflowExecutionStartedAt(state) : 0;
-    throw new WorkflowTimeoutError(workflowId, "execution", elapsed, state.terminationReason);
+    throw new WorkflowTimeoutError(state.id, "execution", elapsed, state.terminationReason);
   }
-  throw Error(`Workflow "${workflowId}" is still ${state.status}`);
+  throw Error(`Workflow "${state.id}" is still ${state.status}`);
+}
+export async function loadWorkflowResult(internals, workflowId) {
+  const state = await loadWorkflowState(internals, workflowId);
+  if (!state)
+    throw Error(`Workflow "${workflowId}" not found`);
+  return deriveWorkflowResultFromState(state);
 }
 function buildWorkflowStateCommit(internals, workflowId, operations, options) {
   const pendingSideEffects = options.includePendingAtomicSideEffects ? takePendingAtomicWorkflowCommitSideEffects(internals, workflowId) : void 0, operationsWithSideEffects = pendingSideEffects === void 0 ? operations : [...operations, ...pendingSideEffects.operations], conditions = internals.storage.capabilities().conditionalBatch ? pendingSideEffects?.conditions ?? [] : [];
@@ -79,9 +85,21 @@ function buildWorkflowStateCommit(internals, workflowId, operations, options) {
     hasPendingSideEffects: pendingSideEffects !== void 0
   };
 }
-export async function commitFencedWorkflowStateOperations(internals, state, operations, options = {}) {
+export async function buildExternalTerminalRotationFragment(internals, workflowId) {
+  if (internals.options.ownershipMode !== "workflow-lease")
+    return { conditions: [], operations: [] };
+  const observedEpochBytes = await internals.storage.get(KEYS.workflowOwnerEpoch(workflowId));
+  return buildWorkflowClaimExternalTerminalRotationTransition({ workflowId, observedEpochBytes });
+}
+export async function commitSelfWorkflowStateOperations(internals, state, operations, options = {}) {
   const commit = buildWorkflowStateCommit(internals, state.id, operations, options);
-  await commitFencedEngineWrite(internals, commit.operations, commit.conditions, () => Error(`Workflow state commit for workflow "${state.id}" lost its atomic side-effect precondition.`));
+  await commitFencedEngineWrite(internals, state.id, commit.operations, commit.conditions, () => Error(`Workflow state commit for workflow "${state.id}" lost its atomic side-effect precondition.`));
+  if (commit.hasPendingSideEffects)
+    clearPendingAtomicWorkflowCommitSideEffects(internals, state.id);
+}
+export async function commitExternalTerminalWorkflowStateOperations(internals, state, operations, options = {}) {
+  const commit = buildWorkflowStateCommit(internals, state.id, operations, options), rotation = await buildExternalTerminalRotationFragment(internals, state.id);
+  await commitFencedEngineWrite(internals, null, [...commit.operations, ...rotation.operations], [...commit.conditions, ...rotation.conditions], () => Error(`External terminal commit for workflow "${state.id}" lost a commit precondition (staged side effects, or the ownership epoch rotation under \`workflow-lease\`).`));
   if (commit.hasPendingSideEffects)
     clearPendingAtomicWorkflowCommitSideEffects(internals, state.id);
 }
@@ -132,7 +150,7 @@ export async function writeScheduleState(internals, state, options) {
   ], includeTimer = options?.includeTimer ?? state.status === "active";
   operations.push(...buildScheduleTimerReplacementOperations(state, includeTimer, options?.replaceTimerFrom));
   operations.push(...options?.additionalOperations ?? []);
-  await commitFencedEngineWrite(internals, operations, [], () => Error(`Schedule state commit for schedule "${state.id}" lost its precondition.`));
+  await commitFencedEngineWrite(internals, null, operations, [], () => Error(`Schedule state commit for schedule "${state.id}" lost its precondition.`));
 }
 export async function loadWorkflowStartHeaders(internals, workflowId) {
   const bytes = await internals.storage.get(KEYS.workflowHeaders(workflowId));

package/dist/core/engine/termination/cleanup.d.ts

@@ -1,6 +1,6 @@
-import type { BatchOperation } from '../../../storage/interface.ts';
 import type { WorkflowState, WorkflowStatus } from '../../types.ts';
 import type { EngineInternals } from '../internals.ts';
+import type { WorkflowStateCommitCallback } from './state-commit-callbacks.ts';
 export type TerminationCallbacks = {
     dispatchEvent: (event: Event) => void;
     forwardEventToHandle: (workflowId: string, event: Event) => void;
@@ -13,9 +13,10 @@ export type TerminationCallbacks = {
     handleScheduledWorkflowTerminal: (workflowId: string) => Promise<void>;
     loadWorkflowState: (workflowId: string) => Promise<WorkflowState | null>;
     runSerializedWorkflowStateWrite: <Result>(workflowId: string, writeOperation: () => Promise<Result>) => Promise<Result>;
-    commitWorkflowStateOperations: (state: WorkflowState, operations: BatchOperation[], options?: {
-        includePendingAtomicSideEffects?: boolean;
-    }) => Promise<void>;
+    /** SELF-transition (complete): fences on this engine's own claim. See ADR 0002. */
+    commitSelfWorkflowStateOperations: WorkflowStateCommitCallback;
+    /** EXTERNAL terminal transition (suspend): rotates the claim epoch. See ADR 0002. */
+    commitExternalTerminalWorkflowStateOperations: WorkflowStateCommitCallback;
     cleanupReviews: (workflowId: string) => Promise<void>;
 };
 export declare const TERMINAL_WORKFLOW_STATUSES: ReadonlySet<WorkflowStatus>;

package/dist/core/engine/termination/complete.js

@@ -64,7 +64,7 @@ export async function terminateWorkflow(internals, workflowId, status, callbacks
       status,
       ...reason !== void 0 ? { terminationReason: reason } : {},
       ...terminalCleanupToken !== void 0 ? { terminalCleanupToken } : {}
-    }, {
+    }, "external-terminal", {
       allowedStatuses: FORCIBLY_TERMINABLE_STATUSES,
       buildAdditionalOperations: (_previousState, updatedAt) => {
         finalizePendingTimelineEntry(internals, workflowId, status, terminationMessage, updatedAt);
@@ -78,6 +78,7 @@ export async function terminateWorkflow(internals, workflowId, status, callbacks
     });
     if (!terminationResult)
       return;
+    const claimEpoch = captureCurrentClaimEpoch(internals, workflowId);
     await runCancellationHandlersForStatus(internals, workflowId, status, callbacks);
     await releaseWorkflowConcurrencySlot(internals, workflowId);
     const { previousState, updatedAt } = terminationResult, elapsed = updatedAt - getWorkflowExecutionStartedAt(previousState);
@@ -87,6 +88,7 @@ export async function terminateWorkflow(internals, workflowId, status, callbacks
     if (previousState.status === "pending")
       callbacks.swallowPromiseRejection(internals.scheduler.cancel(`delayed-start:${workflowId}`, workflowId));
     const resolver = internals.resultResolvers.get(workflowId), terminalError = buildTerminalError(workflowId, status, elapsed, reason);
+    await releaseWorkflowClaimAfterTerminalSettlement(internals, workflowId, claimEpoch);
     try {
       await cleanupTerminalWorkflowSynchronously(internals, workflowId, !0, callbacks);
       const event = buildTerminalEvent(workflowId, status, elapsed, reason);
@@ -165,6 +167,19 @@ function notifyCompletionWaiters(internals, workflowId, result, duration, callba
     internals.resultResolvers.delete(workflowId);
   }
 }
+function captureCurrentClaimEpoch(internals, workflowId) {
+  return internals.workflowClaimRegistry?.currentEpoch(workflowId) ?? null;
+}
+async function releaseWorkflowClaimAfterTerminalSettlement(internals, workflowId, capturedEpoch) {
+  const registry = internals.workflowClaimRegistry;
+  if (registry === null || capturedEpoch === null)
+    return;
+  if (registry.currentEpoch(workflowId) !== capturedEpoch)
+    return;
+  try {
+    await registry.release(workflowId);
+  } catch {}
+}
 export async function completeWorkflow(internals, workflowId, result, callbacks) {
   const completionMetadata = await callbacks.runSerializedWorkflowStateWrite(workflowId, async () => {
     const state = await callbacks.loadWorkflowState(workflowId);
@@ -180,14 +195,16 @@ export async function completeWorkflow(internals, workflowId, result, callbacks)
     appendSearchAttributeOperations(completionOperations, workflowId, currentAttributes);
     if (terminalCleanupToken !== void 0)
       completionOperations.push(...buildTerminalCleanupTimerOperations(internals, workflowId, !1, now, terminalCleanupToken));
-    await callbacks.commitWorkflowStateOperations(state, completionOperations, {
+    await callbacks.commitSelfWorkflowStateOperations(state, completionOperations, {
       includePendingAtomicSideEffects: !0
     });
-    return { duration };
+    const claimEpoch = captureCurrentClaimEpoch(internals, workflowId);
+    return { duration, claimEpoch };
   });
   if (!completionMetadata)
     return;
   await releaseWorkflowConcurrencySlot(internals, workflowId);
+  await releaseWorkflowClaimAfterTerminalSettlement(internals, workflowId, completionMetadata.claimEpoch);
   notifyCompletionWaiters(internals, workflowId, result, completionMetadata.duration, callbacks);
 }
 export async function failWorkflow(internals, workflowId, error, callbacks, failureCategory = "system") {
@@ -202,7 +219,7 @@ export async function failWorkflow(internals, workflowId, error, callbacks, fail
     stateUpdate.errorStack = error.stack;
   if (terminalCleanupToken !== void 0)
     stateUpdate.terminalCleanupToken = terminalCleanupToken;
-  if (!await updateWorkflowState(internals, workflowId, stateUpdate, {
+  if (!await updateWorkflowState(internals, workflowId, stateUpdate, "self", {
     allowedStatuses: FORCIBLY_TERMINABLE_STATUSES,
     buildAdditionalOperations: (_previousState, updatedAt) => {
       finalizePendingTimelineEntry(internals, workflowId, "failed", error.message, updatedAt);
@@ -214,11 +231,13 @@ export async function failWorkflow(internals, workflowId, error, callbacks, fail
     }
   }))
     return;
+  const claimEpoch = captureCurrentClaimEpoch(internals, workflowId);
   await releaseWorkflowConcurrencySlot(internals, workflowId);
   await cleanupAttributeIndex(internals, workflowId, attributes);
   callbacks.swallowPromiseRejection(internals.scheduler.cancel(`deadline:${workflowId}`, workflowId));
   await writeRetainedTerminalSearchAttributes(internals, workflowId, retainedAttributes);
   const resolver = internals.resultResolvers.get(workflowId);
+  await releaseWorkflowClaimAfterTerminalSettlement(internals, workflowId, claimEpoch);
   try {
     await cleanupTerminalWorkflowSynchronously(internals, workflowId, !1, callbacks);
     const event = new WorkflowFailedEvent(workflowId, error);

package/dist/core/engine/termination/finalizer-claim.js

@@ -45,22 +45,22 @@ export function encodeRunningClaim(attempts, token, claimedAt) {
 export async function rearmTeardownTimer(internals, workflowId, token, delayMs) {
   const fireAt = internals.options.getNow() + delayMs;
   try {
-    await commitFencedEngineWrite(internals, teardownTimerOperations(token, workflowId, fireAt), [], () => Error("teardown self-heal re-arm lost the lease fence"));
+    await commitFencedEngineWrite(internals, workflowId, teardownTimerOperations(token, workflowId, fireAt), [], () => Error("teardown self-heal re-arm lost the lease fence"));
   } catch {}
 }
 export async function clearTeardownMarker(internals, workflowId, expectedBytes) {
   try {
-    return await commitFencedEngineWriteAllowingPreconditionFailure(internals, [{ type: "delete", key: KEYS.teardownOwed(workflowId) }], [{ key: KEYS.teardownOwed(workflowId), expectedValue: expectedBytes }]);
+    return await commitFencedEngineWriteAllowingPreconditionFailure(internals, workflowId, [{ type: "delete", key: KEYS.teardownOwed(workflowId) }], [{ key: KEYS.teardownOwed(workflowId), expectedValue: expectedBytes }]);
   } catch {
     return !1;
   }
 }
 export async function claimTeardownMarker(internals, workflowId, expectedBytes, attempts, token) {
   const runningBytes = encodeRunningClaim(attempts, token, internals.options.getNow());
-  return await commitFencedEngineWriteAllowingPreconditionFailure(internals, [{ type: "put", key: KEYS.teardownOwed(workflowId), value: runningBytes }], [{ key: KEYS.teardownOwed(workflowId), expectedValue: expectedBytes }]) ? runningBytes : null;
+  return await commitFencedEngineWriteAllowingPreconditionFailure(internals, workflowId, [{ type: "put", key: KEYS.teardownOwed(workflowId), value: runningBytes }], [{ key: KEYS.teardownOwed(workflowId), expectedValue: expectedBytes }]) ? runningBytes : null;
 }
 export async function settleOnRunningClaim(internals, workflowId, runningBytes, operations) {
-  return commitFencedEngineWriteAllowingPreconditionFailure(internals, operations, [
+  return commitFencedEngineWriteAllowingPreconditionFailure(internals, workflowId, operations, [
     { key: KEYS.teardownOwed(workflowId), expectedValue: runningBytes }
   ]);
 }

package/dist/core/engine/termination/state-commit-callbacks.d.ts

@@ -0,0 +1,15 @@
+import type { BatchOperation } from '../../../storage/interface.ts';
+import type { WorkflowState } from '../../types.ts';
+/**
+ * Shared function shape for the two workflow-state commit callbacks
+ * {@link TerminationCallbacks} exposes, split by ADR 0002's self/
+ * external-terminal transition classification (see
+ * `documentation/contributing/architecture-decisions/0002-multiengine-per-workflow-ownership.md`).
+ * A self-transition (complete, fail) fences on this engine's own claim; an
+ * external terminal transition (cancel, timeout, suspend) rotates the claim
+ * epoch instead, so any engine may commit it. Kept as one shared type so the
+ * two `TerminationCallbacks` fields cannot drift in shape.
+ */
+export type WorkflowStateCommitCallback = (state: WorkflowState, operations: BatchOperation[], options?: {
+    includePendingAtomicSideEffects?: boolean;
+}) => Promise<void>;

package/dist/core/engine/termination/suspend.js

@@ -18,7 +18,7 @@ export async function suspendWorkflow(internals, workflowId, callbacks) {
     internals.parkedInlineWorkflows.delete(workflowId);
     evictSuspendedWorkflowWaiters(internals, workflowId, callbacks);
     const updatedAt = internals.options.getNow(), updatedState = { ...state, status: "suspended", updatedAt };
-    await callbacks.commitWorkflowStateOperations(state, [
+    await callbacks.commitExternalTerminalWorkflowStateOperations(state, [
       { type: "put", key: KEYS.workflow(workflowId), value: encode(updatedState) },
       ...buildWorkflowVisibilityIndexTransition(workflowId, state, updatedState).batchOps,
       ...buildDeadlineTimerDeleteOperations(workflowId, state.executionDeadline)

package/dist/core/engine/update-validation.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Pre-acceptance validation for workflow updates: running a registered
+ * `updateValidators` entry and normalizing a Standard Schema v1 failure result
+ * into the issue list `UpdateValidationError` carries.
+ *
+ * Lives apart from `updates.ts` because it is shared — `pending-updates.ts`
+ * normalizes validator results through the same helper — and because it is
+ * pure payload validation with no coupling to the in-memory waiter maps or the
+ * durable coordinated-update protocol that make up the rest of update delivery.
+ *
+ * @module core/engine/update-validation
+ */
+import type { EngineInternals } from './internals.ts';
+/**
+ * Run the pre-acceptance validator for an update, if one is registered.
+ * Throws `UpdateValidationError` if the validator rejects (by throwing or by
+ * returning a Standard Schema `{ issues: [...] }` failure result).
+ */
+export declare function runUpdateValidator(internals: EngineInternals, workflowId: string, name: string, payload: unknown): Promise<void>;
+/**
+ * Extract issues from a Standard Schema v1 failure result, or null if absent.
+ * No string-`message` entries yields `[]`; callers reject only on a non-empty
+ * array, so `null` and `[]` both mean acceptance. Preserves `path` (RFC 6901).
+ */
+export declare function extractStandardSchemaIssues(result: unknown): Array<{
+    message: string;
+    path?: string;
+}> | null;

package/dist/core/engine/update-validation.js

@@ -0,0 +1,37 @@
+import { UpdateValidationError } from "../updates.js";
+export 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/updates.d.ts

@@ -1,6 +1,6 @@
 import type { ContextOperationRequest } from '../context.ts';
 import type { CoordinatedUpdateResult } from '../types.ts';
-import { type UpdateRequest, type UpdateResponse } from '../updates.ts';
+import type { UpdateRequest, UpdateResponse } from '../updates.ts';
 import type { EngineInternals } from './internals.ts';
 export type UpdateCallbacks = {
     dispatchEvent: (event: Event) => boolean;
@@ -22,6 +22,22 @@ export type UpdateCallbacks = {
 export declare function update(internals: EngineInternals, workflowId: string, name: string, payload: unknown, options: {
     timeout?: number;
 } | undefined, callbacks: UpdateCallbacks): Promise<unknown>;
+/**
+ * `handled: false` used to conflate two reasons: no live local context at all
+ * (`'not-owned-locally'`, possible under `ownership: 'workflow-lease'` when
+ * another engine holds the claim) versus a live context with no handler
+ * registered for `name` (`'no-handler'`). See the `update()` call site for
+ * why neither is routed differently — the reason is exposed so a caller that
+ * DOES care (tests, future routing) can tell them apart.
+ */
+export type InlineUpdateAttemptResult = {
+    handled: true;
+    value: unknown;
+} | {
+    handled: false;
+    reason: 'not-owned-locally' | 'no-handler';
+};
+export declare function tryInlineUpdateHandler(internals: EngineInternals, workflowId: string, name: string, payload: unknown, callbacks: UpdateCallbacks): Promise<InlineUpdateAttemptResult>;
 /** Retrieve the result of a coordinated update by its ID. */
 export declare function getUpdateResult(internals: EngineInternals, updateId: string): Promise<UpdateResponse | null>;
 /**
@@ -39,18 +55,3 @@ export declare function dispatchPendingUpdateReceived(_internals: EngineInternal
 export declare function createCoordinatedUpdateResponder(_internals: EngineInternals, workflowId: string, updateName: string, updateRequest: UpdateRequest, callbacks: Pick<UpdateCallbacks, 'persistCoordinatedUpdateResponse'>): (value: unknown) => void;
 export declare function deliverCoordinatedUpdateToWaiterIfAvailable(internals: EngineInternals, workflowId: string, updateRequest: UpdateRequest, dispatchReceivedEvent: boolean | undefined, callbacks: UpdateCallbacks): Promise<boolean>;
 export declare function findPendingUpdateByName(internals: EngineInternals, workflowId: string, name: string): Promise<UpdateRequest | undefined>;
-/**
- * Invoke an update handler, checking that it does not return a generator.
- * Centralises the runtime generator guard for both the inline-handler path
- * in `update()` and the pending-drain path on resume.
- */
-export declare function invokeUpdateHandler(_internals: EngineInternals, name: string, handler: (payload: unknown) => unknown, payload: unknown): Promise<unknown>;
-/**
- * Extract issues from a Standard Schema v1 failure result, or null if absent.
- * No string-`message` entries yields `[]`; callers reject only on a non-empty
- * array, so `null` and `[]` both mean acceptance. Preserves `path` (RFC 6901).
- */
-export declare function extractStandardSchemaIssues(result: unknown): Array<{
-    message: string;
-    path?: string;
-}> | null;