@lostgradient/weft 0.20.0 → 0.21.0

package/README.md

@@ -1,6 +1,6 @@
 # Weft
 
-A Bun-native durable execution engine. Current release: `0.19.0`.
+A Bun-native durable execution engine. Current release: `0.21.0`.
 
 Install the library from npm as `@lostgradient/weft`:
 
@@ -96,7 +96,7 @@ const result = await handle.result();
 
 That's the core loop: `workflow({ name })` is a **chained builder** that co-locates the workflow's side-effecting steps inside `.activities({...})`, and `.execute(fn)` seals it all together and returns a `WorkflowDefinition`. Inside the generator, `ctx.run('formatGreeting', input)` autocompletes from the workflow's own activity table, typechecks the input, and infers the output. Every `yield*` is a checkpoint boundary; `handle.result()` waits for the output. Checkpoints are written to `./weft.db`, so running workflows survive process crashes.
 
-`Engine.create()` does the registration dance for you: it constructs the engine and registers each workflow in the `workflows` map, pulling in all the activities each workflow declares. It then **recovers by default** — `engine.recoverAll()` runs after registration, so any workflows still running from a previous process pick up where they left off. That's the point of durable storage, so you don't have to ask for it. Pass `recover: false` to opt out (handy for tests, for `ScopedStorage`-isolated engines, or when you want to inspect a store before migrating it). Durability is separate: each step is persisted before it commits no matter what `recover` is set to — `recover` only decides whether _this_ engine resumes that persisted work on boot. If a host owns recovery but still needs durable timers, use `startScheduler: true`; otherwise `recover: false` also leaves the real-time scheduler stopped. Run a single engine per durable store; pointing two at the same store is not yet coordinated and can double-resume a workflow.
+`Engine.create()` does the registration dance for you: it constructs the engine and registers each workflow in the `workflows` map, pulling in all the activities each workflow declares. It then **recovers by default** — `engine.recoverAll()` runs after registration, so any workflows still running from a previous process pick up where they left off. That's the point of durable storage, so you don't have to ask for it. Pass `recover: false` to opt out (handy for tests, for `ScopedStorage`-isolated engines, or when you want to inspect a store before migrating it). Durability is separate: each step is persisted before it commits no matter what `recover` is set to — `recover` only decides whether _this_ engine resumes that persisted work on boot. If a host owns recovery but still needs durable timers, use `startScheduler: true`; otherwise `recover: false` also leaves the real-time scheduler stopped. By default (`ownership: 'none'`) run a single engine per durable store: pointing two at the same store is uncoordinated and can double-resume a workflow. To share one store across engines, select `ownership: 'workflow-lease'`, which claims each workflow for exactly one engine before its generator runs.
 
 Passing an explicitly empty workflow map is the same default-registry boot shape as omitting `workflows`: `Engine.create({ workflows: {} })` recovers after registration and returns an engine whose TypeScript type is compatible with default-registry consumers such as `serve({ engine })`. Use a non-empty `workflows` map when you want TypeScript to narrow `engine.start(...)` to the registered names.
 

package/dist/core/engine/activity-reconciliation.d.ts

@@ -95,14 +95,14 @@ export declare function buildActivityReconciliationReference(workflowId: string,
 export declare function resolveActivityIdempotencyKey(activity: ActivityReconciliationMetadata | undefined, operation: ActivityOperation): string | undefined;
 export declare function readActivityReconciliationRecord(storage: Storage, key: string): Promise<ActivityReconciliationRecord | null>;
 export declare function validateActivityResultForReconciliation(result: unknown, maxPayloadBytes: number | null): Uint8Array;
-export declare function claimActivityReconciliationStart(storage: Storage, reference: ActivityReconciliationReference, record: ActivityReconciliationRecord): Promise<boolean>;
+export declare function claimActivityReconciliationStart(internals: EngineInternals, workflowId: string, reference: ActivityReconciliationReference, record: ActivityReconciliationRecord): Promise<boolean>;
 export declare function createCompletedActivityReconciliationRecord(startedRecord: ActivityReconciliationRecord, result: unknown, now: number): ActivityReconciliationRecord;
 export declare function resolveStartedActivityReconciliationRecord(internals: EngineInternals, workflowId: string, operation: ActivityOperation, reference: ActivityReconciliationReference, activity: ActivityReconciliationMetadata | undefined, idempotencyKey: string, attempt: number): Promise<ActivityReconciliationRecord | {
     completedResult: unknown;
 }>;
 export declare function writeActivityReconciliationTransition(storage: Storage, reference: ActivityReconciliationReference, expectedRecord: ActivityReconciliationRecord, nextRecord: ActivityReconciliationRecord): Promise<void>;
 export declare function stageActivityReconciliationTransitionWithAtomicWorkflowCommit(internals: EngineInternals, workflowId: string, reference: ActivityReconciliationReference, expectedRecord: ActivityReconciliationRecord, nextRecord: ActivityReconciliationRecord): void;
-export declare function commitActivityReconciliationTransitionWithFencedWrite(internals: EngineInternals, reference: ActivityReconciliationReference, expectedRecord: ActivityReconciliationRecord, nextRecord: ActivityReconciliationRecord): Promise<void>;
+export declare function commitActivityReconciliationTransitionWithFencedWrite(internals: EngineInternals, workflowId: string, reference: ActivityReconciliationReference, expectedRecord: ActivityReconciliationRecord, nextRecord: ActivityReconciliationRecord): Promise<void>;
 export declare function normalizePreDispatchVerificationResult(result: ActivityVerificationResult): 'not-completed' | 'completed-result-unavailable' | 'indeterminate' | {
     result: unknown;
 };

package/dist/core/engine/activity-reconciliation.js

@@ -7,7 +7,10 @@ import { decode, encode } from "../codec.js";
 import { assertPayloadWithinLimit } from "../payload-size.js";
 import { WeftError } from "../weft-error.js";
 import { stageAtomicWorkflowCommitSideEffects } from "./checkpoint-side-effects.js";
-import { commitFencedEngineWrite } from "./fenced-write.js";
+import {
+  commitFencedEngineWrite,
+  commitFencedEngineWriteAllowingPreconditionFailure
+} from "./fenced-write.js";
 
 export class ActivityReconciliationCapabilityError extends WeftError {
   constructor() {
@@ -50,11 +53,12 @@ export function validateActivityResultForReconciliation(result, maxPayloadBytes)
   assertPayloadWithinLimit(result, maxPayloadBytes, "activity result");
   return encode(result);
 }
-export async function claimActivityReconciliationStart(storage, reference, record) {
+export async function claimActivityReconciliationStart(internals, workflowId, reference, record) {
+  const storage = internals.storage;
   if (!storage.capabilities().conditionalBatch)
     throw new ActivityReconciliationCapabilityError;
   requireStorageCapability(storage, "conditionalBatch", "activity result reconciliation");
-  return storageConditionalBatch(storage, [{ key: reference.key, expectedValue: null }], [{ type: "put", key: reference.key, value: encode(record) }]);
+  return commitFencedEngineWriteAllowingPreconditionFailure(internals, workflowId, [{ type: "put", key: reference.key, value: encode(record) }], [{ key: reference.key, expectedValue: null }]);
 }
 export function createCompletedActivityReconciliationRecord(startedRecord, result, now) {
   return {
@@ -84,7 +88,7 @@ export async function resolveStartedActivityReconciliationRecord(internals, work
       ownerId: crypto.randomUUID(),
       updatedAt: internals.options.getNow()
     };
-    await commitActivityReconciliationTransitionWithFencedWrite(internals, reference, record, nextRecord);
+    await commitActivityReconciliationTransitionWithFencedWrite(internals, workflowId, reference, record, nextRecord);
     return nextRecord;
   }
   if (normalized === "completed-result-unavailable")
@@ -93,7 +97,7 @@ export async function resolveStartedActivityReconciliationRecord(internals, work
     throw new ActivityReconciliationIndeterminateError(`Activity "${operation.activityName}" reconciliation is indeterminate.`);
   validateActivityResultForReconciliation(normalized.result, internals.options.payloadSizePolicy.maxBytes);
   const completedRecord = createCompletedActivityReconciliationRecord(record, normalized.result, internals.options.getNow());
-  await commitActivityReconciliationTransitionWithFencedWrite(internals, reference, record, completedRecord);
+  await commitActivityReconciliationTransitionWithFencedWrite(internals, workflowId, reference, record, completedRecord);
   return { completedResult: normalized.result };
 }
 export async function writeActivityReconciliationTransition(storage, reference, expectedRecord, nextRecord) {
@@ -104,9 +108,9 @@ export async function writeActivityReconciliationTransition(storage, reference,
 export function stageActivityReconciliationTransitionWithAtomicWorkflowCommit(internals, workflowId, reference, expectedRecord, nextRecord) {
   stageAtomicWorkflowCommitSideEffects(internals, workflowId, buildActivityReconciliationTransitionSideEffects(reference, expectedRecord, nextRecord));
 }
-export async function commitActivityReconciliationTransitionWithFencedWrite(internals, reference, expectedRecord, nextRecord) {
+export async function commitActivityReconciliationTransitionWithFencedWrite(internals, workflowId, reference, expectedRecord, nextRecord) {
   const sideEffects = buildActivityReconciliationTransitionSideEffects(reference, expectedRecord, nextRecord);
-  await commitFencedEngineWrite(internals, sideEffects.operations, sideEffects.conditions, () => new ActivityReconciliationConflictError("Activity reconciliation completion lost compare-and-set ownership."));
+  await commitFencedEngineWrite(internals, workflowId, sideEffects.operations, sideEffects.conditions, () => new ActivityReconciliationConflictError("Activity reconciliation completion lost compare-and-set ownership."));
 }
 function buildActivityReconciliationTransitionSideEffects(reference, expectedRecord, nextRecord) {
   return {
@@ -171,7 +175,7 @@ function createStartedRecord(workflowId, operation, reference, attempt, now) {
 }
 async function claimStartedRecord(internals, workflowId, operation, reference, attempt) {
   const startedRecord = createStartedRecord(workflowId, operation, reference, attempt, internals.options.getNow());
-  if (await claimActivityReconciliationStart(internals.storage, reference, startedRecord))
+  if (await claimActivityReconciliationStart(internals, workflowId, reference, startedRecord))
     return { didClaim: !0, record: startedRecord };
   const record = await readActivityReconciliationRecord(internals.storage, reference.key);
   if (record === null)

package/dist/core/engine/async-activity-completion.js

@@ -10,6 +10,7 @@ import {
 } from "./async-activity-records.js";
 import { stageAtomicWorkflowCommitSideEffects } from "./checkpoint-side-effects.js";
 import { commitFencedEngineWrite } from "./fenced-write.js";
+import { confirmWakeOwnership } from "./wake-ownership-guard.js";
 
 export class AsyncActivityDeferral extends Error {
   token;
@@ -30,7 +31,7 @@ export class AsyncActivityTokenNotFoundError extends WeftError {
 export async function parkDeferredAsyncActivity(internals, deferral, details, callbacks) {
   const queuedResolution = takePendingAsyncActivityResolution(internals, details.workflowId, deferral.token);
   if (queuedResolution !== void 0) {
-    deliverPendingAsyncActivityResolution(internals, details.workflowId, queuedResolution, callbacks);
+    await deliverPendingAsyncActivityResolution(internals, details.workflowId, queuedResolution, callbacks);
     return new Promise(() => {});
   }
   await registerPendingAsyncActivity(internals, {
@@ -44,16 +45,23 @@ async function consumePendingAsyncActivity(internals, token, outcome) {
   const pending = internals.pendingAsyncActivities.get(token);
   if (!pending)
     throw new AsyncActivityTokenNotFoundError(token);
+  const registry = internals.workflowClaimRegistry;
+  if (registry !== null && registry.currentEpoch(pending.workflowId) === null)
+    throw new AsyncActivityTokenNotFoundError(token);
   internals.pendingAsyncActivities.delete(token);
   try {
-    await commitFencedEngineWrite(internals, buildAsyncActivityAcknowledgementOperations(pending, outcome), [], () => Error(`Async activity acknowledgement for token "${token}" lost its precondition.`));
+    await commitFencedEngineWrite(internals, pending.workflowId, buildAsyncActivityAcknowledgementOperations(pending, outcome), [], () => Error(`Async activity acknowledgement for token "${token}" lost its precondition.`));
   } catch (error) {
     internals.pendingAsyncActivities.set(token, pending);
     throw error;
   }
   return pending;
 }
-function deliverPendingAsyncActivityResolution(internals, workflowId, resolution, callbacks) {
+async function deliverPendingAsyncActivityResolution(internals, workflowId, resolution, callbacks) {
+  if (internals.workflowClaimRegistry !== null) {
+    if (await confirmWakeOwnership(internals, workflowId, "async-activity") === "discard")
+      return;
+  }
   stageAtomicWorkflowCommitSideEffects(internals, workflowId, {
     conditions: [],
     operations: [
@@ -75,7 +83,7 @@ async function resolvePendingAsyncActivity(internals, token, outcome, callbacks,
     queuePendingAsyncActivityResolution(internals, pending.workflowId, resolution);
     return;
   }
-  deliverPendingAsyncActivityResolution(internals, pending.workflowId, resolution, callbacks);
+  await deliverPendingAsyncActivityResolution(internals, pending.workflowId, resolution, callbacks);
 }
 export async function completeAsyncActivity(internals, token, result, callbacks) {
   assertPayloadWithinLimit(result, internals.options.payloadSizePolicy.maxBytes, "activity result");

package/dist/core/engine/async-activity-records.d.ts

@@ -104,8 +104,18 @@ export declare function registerPendingAsyncActivity(internals: EngineInternals,
  * before the recovered workflow has replayed far enough to re-register it —
  * and so an acknowledged-but-not-yet-checkpointed resolution is redelivered
  * when replay re-parks on the same deterministic token.
+ *
+ * Pass `workflowId` to reload just one workflow's records. ADR 0002's
+ * reclaim-driven resume needs this: a resolution acknowledged by an expired
+ * owner is discarded by that engine's `confirmWakeOwnership` check, leaving
+ * only the durable record. The engine that takes the workflow over finished
+ * its startup scan long ago, so without a per-workflow reload it never
+ * discovers a resolution written after that scan — the workflow re-parks and
+ * waits forever even though the completion caller was told it succeeded. The
+ * scan is bounded to {@link asyncActivityWorkflowPrefix}, so a takeover pays
+ * for one workflow rather than a store-wide sweep.
  */
-export declare function recoverPendingAsyncActivities(internals: EngineInternals): Promise<void>;
+export declare function recoverPendingAsyncActivities(internals: EngineInternals, workflowId?: string): Promise<void>;
 /**
  * True when a resolution cannot be delivered yet because inline replay has not
  * adopted the workflow generator (the post-recovery window).

package/dist/core/engine/async-activity-records.js

@@ -148,12 +148,13 @@ export function buildAsyncActivityAcknowledgementOperations(pending, outcome) {
 export async function registerPendingAsyncActivity(internals, pending) {
   const alreadyRegistered = internals.pendingAsyncActivities.has(pending.token);
   internals.pendingAsyncActivities.set(pending.token, pending);
-  await commitFencedEngineWrite(internals, [buildPersistPendingAsyncActivityOperation(pending)], [], () => Error(`Async activity registration for token "${pending.token}" lost its precondition.`));
+  await commitFencedEngineWrite(internals, pending.workflowId, [buildPersistPendingAsyncActivityOperation(pending)], [], () => Error(`Async activity registration for token "${pending.token}" lost its precondition.`));
   if (!alreadyRegistered)
     internals.engine.dispatchEvent(new ActivityAsyncPendingEvent(pending.token, pending.operationId, pending.workflowId, pending.activityName, pending.attempt));
 }
-export async function recoverPendingAsyncActivities(internals) {
-  for await (const [, bytes] of internals.storage.scan(ASYNC_ACTIVITY_KEY_PREFIX)) {
+export async function recoverPendingAsyncActivities(internals, workflowId) {
+  const scanPrefix = workflowId === void 0 ? ASYNC_ACTIVITY_KEY_PREFIX : asyncActivityWorkflowPrefix(workflowId);
+  for await (const [, bytes] of internals.storage.scan(scanPrefix)) {
     const decoded = decode(bytes);
     if (isPersistedAsyncActivity(decoded)) {
       internals.pendingAsyncActivities.set(decoded.token, {

package/dist/core/engine/attributes-tags.d.ts

@@ -1,6 +1,16 @@
 import type { BatchOperation } from '../../storage/interface.ts';
 import type { BulkTagResult, ListFilter, SearchAttributeValue, WorkflowState, WorkflowStatus } from '../types.ts';
 import type { EngineInternals } from './internals.ts';
+/**
+ * `updateWorkflowState`'s two callers commit very different transitions per
+ * ADR 0002: `failWorkflow` is a SELF-transition (this engine finishing its
+ * own workflow) while `terminateWorkflow` (cancel/timeout) is an EXTERNAL
+ * terminal transition (any engine may commit it, and it rotates the claim
+ * epoch under `ownership: 'workflow-lease'`). `category` is a REQUIRED
+ * positional parameter rather than an optional options field so a caller
+ * cannot silently default into the wrong fencing shape.
+ */
+export type WorkflowStateTransitionCategory = 'self' | 'external-terminal';
 type WorkflowStateUpdateOptions = {
     allowedStatuses?: readonly WorkflowStatus[];
     buildAdditionalOperations?: (previousState: WorkflowState, updatedAt: number) => BatchOperation[];
@@ -21,7 +31,7 @@ export declare function writeRetainedTerminalSearchAttributes(internals: EngineI
 /** Build secondary-index updates for terminal workflow state transitions. */
 export declare function buildTerminalWorkflowIndexOperations(previousState: WorkflowState, nextState: WorkflowState): BatchOperation[];
 /** Apply a serialized workflow-state update and return the previous state metadata. */
-export declare function updateWorkflowState(internals: EngineInternals, workflowId: string, updates: Partial<WorkflowState>, options?: WorkflowStateUpdateOptions): Promise<WorkflowStateUpdateResult | null>;
+export declare function updateWorkflowState(internals: EngineInternals, workflowId: string, updates: Partial<WorkflowState>, category: WorkflowStateTransitionCategory, options?: WorkflowStateUpdateOptions): Promise<WorkflowStateUpdateResult | null>;
 /** Add or remove tags for a single workflow under the serialized state-write lock. */
 export declare function mutateWorkflowTags(internals: EngineInternals, workflowId: string, tags: string[], mode: 'add' | 'remove'): Promise<boolean>;
 /** Add or remove tags for every workflow selected by a scoped bulk filter. */

package/dist/core/engine/attributes-tags.js

@@ -10,7 +10,8 @@ import { assertWorkflowTagCount, coerceStartWorkflowTags } from "../start-workfl
 import { buildWorkflowTagIndexOperations, normalizeWorkflowTags } from "../workflow-tags.js";
 import { WorkflowNotFoundError } from "./errors.js";
 import {
-  commitFencedWorkflowStateOperations,
+  commitExternalTerminalWorkflowStateOperations,
+  commitSelfWorkflowStateOperations,
   runSerializedWorkflowStateWrite
 } from "./storage-io.js";
 import {
@@ -63,7 +64,7 @@ export function buildTerminalWorkflowIndexOperations(previousState, nextState) {
     });
   return operations;
 }
-export async function updateWorkflowState(internals, workflowId, updates, options = {}) {
+export async function updateWorkflowState(internals, workflowId, updates, category, options = {}) {
   return await runSerializedWorkflowStateWrite(internals, workflowId, async () => {
     const bytes = await internals.storage.get(KEYS.workflow(workflowId));
     if (!bytes)
@@ -76,7 +77,7 @@ export async function updateWorkflowState(internals, workflowId, updates, option
       ...updates,
       updatedAt
     }, additionalOperations = options.buildAdditionalOperations?.(state, updatedAt) ?? [];
-    await commitFencedWorkflowStateOperations(internals, state, [
+    await (category === "self" ? commitSelfWorkflowStateOperations : commitExternalTerminalWorkflowStateOperations)(internals, state, [
       ...buildTerminalWorkflowIndexOperations(state, updated),
       { type: "put", key: KEYS.workflow(workflowId), value: encode(updated) },
       ...buildWorkflowVisibilityIndexTransition(workflowId, state, updated).batchOps,

package/dist/core/engine/bulk-operations-purge.js

@@ -14,6 +14,7 @@ import { commitFencedEngineWrite } from "./fenced-write.js";
 import { streamWorkflowStates } from "./listing.js";
 import { decodeScheduleRunMetadata } from "./schedule-run-metadata.js";
 import { createTerminalCleanupTimerId } from "./state-utilities.js";
+import { buildExternalTerminalRotationFragment } from "./storage-io.js";
 import {
   decodeWorkflowState,
   isTerminalWorkflowStatus,
@@ -132,8 +133,10 @@ function getWorkflowRetentionDeadline(internals, state) {
   return state.updatedAt + retentionMs;
 }
 export async function purgeWorkflow(internals, state, cleanupWaiters) {
-  const deleteOperations = await collectWorkflowPurgeDeleteOperations(internals, state);
-  await commitFencedEngineWrite(internals, deleteOperations, [], () => Error(`Purge commit for workflow "${state.id}" lost its precondition.`));
+  const deleteOperations = await collectWorkflowPurgeDeleteOperations(internals, state), rotation = await buildExternalTerminalRotationFragment(internals, state.id), operations = [...deleteOperations, ...rotation.operations];
+  await commitFencedEngineWrite(internals, null, operations, rotation.conditions, () => {
+    return Error(`Purge commit for workflow "${state.id}" lost its precondition.`);
+  });
   clearPurgedWorkflowInMemoryState(internals, state.id, cleanupWaiters);
 }
 export async function collectWorkflowPurgeDeleteOperations(internals, state) {

package/dist/core/engine/bulk-operations.js

@@ -31,6 +31,11 @@ import { BULK_OPERATION_BATCH_SIZE } from "./listing.js";
 import { createTerminalCleanupTimerId } from "./state-utilities.js";
 import { loadWorkflowState, runSerializedWorkflowStateWrite } from "./storage-io.js";
 import { decodeWorkflowState, isTerminalWorkflowStatus } from "./validation.js";
+import {
+  commitWithWorkflowClaimFold,
+  prepareWorkflowClaimFold,
+  throwWorkflowClaimUnavailable
+} from "./workflow-claim-fold.js";
 import { buildWorkflowConcurrencyStartOperations } from "./workflow-concurrency.js";
 import { buildWorkflowVisibilityIndexTransition } from "./workflow-indexes.js";
 export { purgeInternal, TERMINAL_CLEANUP_DELAY_MS } from "./bulk-operations-purge.js";
@@ -171,17 +176,24 @@ async function reactivateFailedWorkflowFromCheckpointSerialized(internals, workf
       }),
       ...concurrencyStartOperations?.operations ?? []
     ], conditions = concurrencyStartOperations?.conditions ?? [];
-    if (await commitFailedWorkflowReactivation(internals, operations, conditions))
+    if (await commitFailedWorkflowReactivation(internals, workflowId, operations, conditions))
       return {
         terminalCleanupTimerId: currentState.terminalCleanupToken === void 0 ? void 0 : createTerminalCleanupTimerId(!1, currentState.terminalCleanupToken)
       };
   }
   throw Error(`Workflow concurrency admission for "${lastConcurrencyStateKey ?? workflowId}" changed too many times while retrying failed workflow "${workflowId}"`);
 }
-async function commitFailedWorkflowReactivation(internals, operations, conditions) {
-  if (conditions.length > 0)
-    requireStorageCapability(internals.storage, "conditionalBatch", "retry failed workflow");
-  return commitFencedEngineWriteAllowingPreconditionFailure(internals, operations, conditions);
+async function commitFailedWorkflowReactivation(internals, workflowId, operations, conditions) {
+  const claimFold = await prepareWorkflowClaimFold(internals, workflowId);
+  if (claimFold === void 0) {
+    if (conditions.length > 0)
+      requireStorageCapability(internals.storage, "conditionalBatch", "retry failed workflow");
+    return commitFencedEngineWriteAllowingPreconditionFailure(internals, workflowId, operations, conditions);
+  }
+  const result = await commitWithWorkflowClaimFold(internals, claimFold, operations, conditions, "retry failed workflow claim acquisition");
+  if (result.status === "committed")
+    return !0;
+  return result.claimConflict ? throwWorkflowClaimUnavailable(internals, workflowId) : !1;
 }
 function buildReactivatedWorkflowState(internals, state) {
   const reactivatedState = {

package/dist/core/engine/callback-creators-bundles.js

@@ -154,7 +154,7 @@ export function createUpdateCallbacks(engine) {
 async function persistCoordinatedUpdateResponse(engine, workflowId, updateName, updateId, idempotencyKey, value) {
   const internals = getInternals(engine), responseOperations = internals.updateCoordinator.buildResponseOperations(updateId, workflowId, value, void 0, idempotencyKey);
   try {
-    await commitFencedEngineWrite(internals, responseOperations, [], () => Error(`Coordinated update response for workflow "${workflowId}" lost its CAS race.`));
+    await commitFencedEngineWrite(internals, workflowId, responseOperations, [], () => Error(`Coordinated update response for workflow "${workflowId}" lost its CAS race.`));
     engine.dispatchEvent(new UpdateCompletedEvent(updateId, workflowId, updateName, value));
     broadcastFromInternals(internals, { type: "update:completed", workflowId, updateId }, createBroadcastCallbacks(engine));
   } catch (error) {

package/dist/core/engine/callback-creators-core.js

@@ -18,7 +18,8 @@ import {
 import { resolveWorkflowTypeTarget } from "./registration.js";
 import { cleanupReviews } from "./reviews.js";
 import {
-  commitFencedWorkflowStateOperations,
+  commitExternalTerminalWorkflowStateOperations,
+  commitSelfWorkflowStateOperations,
   loadWorkflowState,
   runSerializedWorkflowStateWrite
 } from "./storage-io.js";
@@ -94,7 +95,8 @@ export function createTerminationCallbacksWith(engine, handleScheduledWorkflowTe
     handleScheduledWorkflowTerminal,
     loadWorkflowState: (workflowId) => loadWorkflowState(getInternals(engine), workflowId),
     runSerializedWorkflowStateWrite: (workflowId, writeOperation) => runSerializedWorkflowStateWrite(getInternals(engine), workflowId, writeOperation),
-    commitWorkflowStateOperations: (state, operations, options) => commitFencedWorkflowStateOperations(getInternals(engine), state, operations, options),
+    commitSelfWorkflowStateOperations: (state, operations, options) => commitSelfWorkflowStateOperations(getInternals(engine), state, operations, options),
+    commitExternalTerminalWorkflowStateOperations: (state, operations, options) => commitExternalTerminalWorkflowStateOperations(getInternals(engine), state, operations, options),
     cleanupReviews: (workflowId) => cleanupReviews(getInternals(engine), workflowId)
   };
 }

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

@@ -122,7 +122,7 @@ async function commitCheckpoint(internals, workflowId, operation, commit, callba
   if (pendingSideEffects !== void 0)
     commit.operations.push(...pendingSideEffects.operations);
   const storageSupportsConditionalBatch = internals.storage.capabilities().conditionalBatch, sideEffectConditions = checkpointSideEffectConditions(pendingSideEffects, storageSupportsConditionalBatch), conditions = buildCheckpointCommitConditions(workflowId, commit, storageSupportsConditionalBatch, sideEffectConditions);
-  await commitFencedEngineWrite(internals, commit.operations, conditions, () => {
+  await commitFencedEngineWrite(internals, workflowId, commit.operations, conditions, () => {
     return Error(`Checkpoint commit for workflow "${workflowId}" lost its CAS race against a newer checkpoint.`);
   });
   if (pendingSideEffects !== void 0)

package/dist/core/engine/child-workflow.js

@@ -5,6 +5,7 @@ import {
   registerChildCancellationHandler
 } from "./child-workflow-cancellation.js";
 import { WorkflowAlreadyExistsError } from "./errors.js";
+import { getGeneratorOwnedWorkflowResultPromise } from "./handle-result.js";
 import { encodedValuesEqual } from "./state-utilities.js";
 export async function processChildWorkflowOperation(internals, workflowId, operation, callbacks) {
   return callbacks.runOperationWithResult(workflowId, operation, () => executeChildWorkflow(internals, workflowId, operation, assertChildWorkflowNestingDepth(internals, workflowId), callbacks));
@@ -83,7 +84,7 @@ export async function executeChildWorkflow(internals, workflowId, operation, cur
       registerChildCancellationHandler(internals, workflowId, childHandle.id, callbacks);
       return createChildWorkflowHandleReference(childHandle.id);
     }
-    return childHandle.result();
+    return getGeneratorOwnedWorkflowResultPromise(internals, childHandle.id, workflowId);
   }, composedInterceptor = callbacks.getComposedWorkflowInterceptor();
   if (!composedInterceptor)
     return executeChild();

package/dist/core/engine/completed-review-storage.js

@@ -35,7 +35,7 @@ export async function listCompletedReviewsFromStorage(storage, filter) {
 }
 export async function persistCompletedReviewRecord(internals, reviewKey, reviewData, decisionResult) {
   const completedReview = toCompletedReviewEntry(reviewData, decisionResult);
-  await commitFencedEngineWrite(internals, [
+  await commitFencedEngineWrite(internals, reviewData.workflowId, [
     {
       type: "put",
       key: completedReviewStorageKey(reviewData.workflowId, reviewData.reviewId),

package/dist/core/engine/condition-waiters.d.ts

@@ -1,14 +1,56 @@
 import type { EngineInternals } from './internals.ts';
+import { type WakeOwnershipDecision } from './wake-ownership-guard.ts';
 /**
  * Re-drive every in-process `ctx.waitUntil` waiter registered for a workflow.
- * Called after an inline `onUpdate` handler runs (`tryInlineUpdateHandler`),
- * since the handler may have mutated the workflow-local state a predicate reads.
- * Each call wakes the parked `processWaitConditionOperation`, which re-evaluates
+ * Called after an inline `onUpdate` handler runs (`tryInlineUpdateHandler`) —
+ * since the handler may have mutated the workflow-local state a predicate
+ * reads. Wakes the parked `processWaitConditionOperation`, which re-evaluates
  * its predicate against the (possibly mutated) state.
  *
  * Weft signals are pull-only (`ctx.waitForSignal`) and run no state-mutating
  * handler, so signal delivery is intentionally NOT a re-drive trigger — `onUpdate`
  * is the push path. Lives in its own module so `updates.ts` can call it without
  * an import cycle through `operations-coordination.ts`.
+ *
+ * **`wakeOwnershipCheck` under `ownership: 'workflow-lease'`.** This is a
+ * claim-requiring wake site (ADR 0002's `wait-condition` kind): resolving
+ * `conditionWaiters` drives a parked generator turn. This function's only
+ * remaining callers — `updates.ts` and `pending-updates.ts` — invoke it from
+ * an `onUpdate` handler with no associated durable timer to protect, so they
+ * call it synchronously with no `await` and must stay that way: this
+ * function's signature stays `void`, never `Promise<void>`, so neither
+ * becomes a floating-promise lint violation. Under `'none'`/`'lease'`
+ * (`workflowClaimRegistry === null`) the resolver is looked up and called
+ * synchronously — byte-identical to before this check existed. Under
+ * `'workflow-lease'` the ownership re-read runs as a fire-and-forget async
+ * check, and the resolver is looked up fresh (never captured before the
+ * await) once that check settles, so a newer waiter registered in the
+ * meantime is never resolved by a stale reference.
+ *
+ * The durable-timer-driven wake (a `wait-condition` deadline timer firing)
+ * does NOT use this function — see {@link notifyConditionWaitersForTimerFire}
+ * below. That caller feeds directly into the `Scheduler`'s "was this fire
+ * processed" decision, so it cannot be fire-and-forget the way an
+ * `onUpdate`-driven poke safely can.
  */
 export declare function notifyConditionWaiters(internals: EngineInternals, workflowId: string): void;
+/**
+ * Timer-driven counterpart to {@link notifyConditionWaiters}, used only by
+ * `operations-time.ts`'s `resolveConditionTimer` when a durable
+ * `ctx.waitUntil()` deadline timer fires under `ownership: 'workflow-lease'`.
+ *
+ * Unlike the `onUpdate`-driven path above, this caller feeds directly into
+ * the `Scheduler`'s `#processSelectedTimer`: once the returned promise
+ * settles, the caller decides whether the Scheduler may treat this fire as
+ * "processed" and durably delete the timer key. A fire-and-forget check here
+ * (mirroring `notifyConditionWaiters`'s `'workflow-lease'` branch) would let
+ * the Scheduler delete the timer before the ownership decision — and, on a
+ * `'proceed'`, the wake dispatch itself — has actually happened, stranding a
+ * parked workflow with no deterministic timeout record if the process exits
+ * or disposes in that window. So this returns the raw {@link
+ * WakeOwnershipDecision} instead of swallowing it: the caller uses a
+ * `'discard'` to decide retain-vs-collect via
+ * `sleep-timer-acknowledgements.ts`'s `resolveDiscardedTimerDisposition`,
+ * the same disposal policy the `sleep` wake kind shares this hazard with.
+ */
+export declare function notifyConditionWaitersForTimerFire(internals: EngineInternals, workflowId: string): Promise<WakeOwnershipDecision>;

package/dist/core/engine/condition-waiters.js

@@ -1,5 +1,14 @@
+import { confirmWakeOwnership } from "./wake-ownership-guard.js";
 export function notifyConditionWaiters(internals, workflowId) {
-  const resolve = internals.conditionWaiters.get(workflowId);
-  if (resolve)
-    resolve();
+  if (internals.workflowClaimRegistry === null) {
+    internals.conditionWaiters.get(workflowId)?.();
+    return;
+  }
+  confirmWakeOwnership(internals, workflowId, "wait-condition").then((decision) => decision === "proceed" ? internals.conditionWaiters.get(workflowId)?.() : void 0);
+}
+export async function notifyConditionWaitersForTimerFire(internals, workflowId) {
+  const decision = await confirmWakeOwnership(internals, workflowId, "wait-condition");
+  if (decision === "proceed")
+    internals.conditionWaiters.get(workflowId)?.();
+  return decision;
 }

package/dist/core/engine/disposal.js

@@ -8,6 +8,11 @@ function settleSleepResolverReadyWaitersForTesting(internals) {
       notifyReady();
   internals.sleepResolverReadyWaitersForTesting?.clear();
 }
+function clearPendingResultPollTimers(internals) {
+  for (const timer of internals.pendingResultPollTimers)
+    clearTimeout(timer);
+  internals.pendingResultPollTimers.clear();
+}
 export function disposeEngine(internals) {
   internals.disposed = !0;
   internals.alertManager?.[Symbol.dispose]();
@@ -52,6 +57,7 @@ export function disposeEngine(internals) {
   for (const controller of internals.pendingWebhooks)
     controller.abort();
   internals.pendingWebhooks.clear();
+  clearPendingResultPollTimers(internals);
   internals.sleepResolvers.clear();
   internals.sleepResolversByWorkflow.clear();
   settleSleepResolverReadyWaitersForTesting(internals);

package/dist/core/engine/engine-internal-types.d.ts

@@ -46,17 +46,25 @@ export interface ResolvedOptions {
     /** Heartbeat interval (ms) for the second-instance detector when enabled. */
     secondInstanceHeartbeatIntervalMs: number;
     /**
-     * Single-writer ownership posture. `'none'` recovers immediately (infra owns
-     * mutual exclusion); `'lease'` acquires a storage lease before recovery. The
-     * lease tuning fields below are only meaningful when this is `'lease'`.
+     * Ownership posture. `'none'` recovers immediately (infra owns mutual
+     * exclusion); `'lease'` acquires a single store-wide storage lease before
+     * recovery; `'workflow-lease'` fences execution per workflow instead
+     * (ADR 0002), letting multiple engines share one durable store. The lease
+     * tuning fields below are only meaningful when this is `'lease'`; the
+     * workflow-claim tuning fields are only meaningful when this is
+     * `'workflow-lease'`.
      */
-    ownershipMode: 'none' | 'lease';
+    ownershipMode: 'none' | 'lease' | 'workflow-lease';
     /** Lease time-to-live (ms) when `ownershipMode` is `'lease'`. */
     leaseTtlMs: number;
     /** Lease renewal interval (ms) when `ownershipMode` is `'lease'`. */
     leaseRenewIntervalMs: number;
     /** Boot-time lease acquisition wait window (ms) when `ownershipMode` is `'lease'`. */
     leaseWaitTimeoutMs: number;
+    /** Per-workflow claim time-to-live (ms) when `ownershipMode` is `'workflow-lease'`. */
+    workflowClaimTtlMs: number;
+    /** Per-workflow claim renewal interval (ms) when `ownershipMode` is `'workflow-lease'`. */
+    workflowClaimRenewIntervalMs: number;
     getNow: () => number;
     /**
      * Re-provides the non-serialized per-run `services` value on recovery; `null`

package/dist/core/engine/fenced-write.d.ts

@@ -1,5 +1,6 @@
 /**
- * Step-2 epoch fencing for `ownership: 'lease'` (issue #470).
+ * Step-2 epoch fencing for `ownership: 'lease'` (issue #470), extended by ADR
+ * 0002 to per-workflow fencing under `ownership: 'workflow-lease'`.
  *
  * Step 1 made a rolling deploy a clean lease handoff but added no correctness
  * backstop: a deposed zombie instance (GC pause, partition) that emerged after
@@ -15,6 +16,20 @@
  * from silently spinning on swallowed write losses, surface the deposition to the
  * operator, and release resources. They are not what makes the system safe.
  *
+ * ADR 0002 adds a SECOND, independent fencing token: `wf-owner-epoch:<workflowId>`.
+ * Every caller of {@link commitFencedEngineWrite} / {@link
+ * commitFencedEngineWriteAllowingPreconditionFailure} now states, via the
+ * required `workflowId` parameter, whether the write is scoped to one
+ * workflow's execution (pass its id) or is engine-scoped/cross-workflow (pass
+ * `null`) — an optional parameter would let a call site silently forget the
+ * fence, which is exactly the correctness hole this mechanism exists to close.
+ * Under `ownership: 'workflow-lease'` with a non-null `workflowId`, the write
+ * is fenced on THAT workflow's claim epoch instead of the global lease epoch;
+ * losing that fence deposes only that one workflow (warn + throw), never the
+ * whole engine. Under `'lease'` and `'none'`, and under `'workflow-lease'`
+ * with `workflowId: null`, behavior is byte-for-byte unchanged from Step 2 —
+ * `workflowId` is only consulted in the one new branch.
+ *
  * This module is allow-listed for import only from `src/core/engine/**`.
  */
 import type { BatchOperation, ConditionalBatchCondition } from '../../storage/interface.ts';
@@ -31,37 +46,53 @@ import type { EngineInternals } from './internals.ts';
  * `pauseSchedule`, `resumeSchedule`, `cancelSchedule`, and `updateSchedule`) would
  * reach `resolveFenceEpochOrHalt` with no held epoch and be misreported as a
  * deposition (warn + teardown) rather than the true "lease not held yet"
- * condition. A no-op under `ownership: 'none'`.
+ * condition. A no-op under `ownership: 'none'` and under `ownership:
+ * 'workflow-lease'` — the analogous "claim not held yet" guard for a
+ * workflow-scoped write is a later stage's concern (folding `acquire()` into
+ * the enabling write), not this global-lease-only assertion.
  */
 export declare function assertLeaseHeldForEngineWork(internals: EngineInternals): void;
 /**
- * Commit an engine-generator-owned durable write, fenced on the held lease epoch
- * under `ownership: 'lease'` (a byte-for-byte no-op under `ownership: 'none'`). A
- * lost CAS race throws the caller-supplied `onLostRace` error so existing retry
- * semantics apply; a deposition halts the engine and throws
- * {@link EngineDeposedError}. The helper owns the batch-vs-conditionalBatch
- * decision — pass plain operations plus whatever base conditions you already need.
+ * Commit an engine-generator-owned durable write, fenced on the applicable
+ * epoch: the global lease epoch under `ownership: 'lease'`, this workflow's
+ * claim epoch under `ownership: 'workflow-lease'` when `workflowId` is
+ * non-null, or — under `'none'` and every other `workflowId`/mode
+ * combination — byte-for-byte unfenced. A lost CAS race throws the
+ * caller-supplied `onLostRace` error so existing retry semantics apply; a
+ * deposition halts (the engine under global `'lease'`, or just this one
+ * workflow under `'workflow-lease'`) and throws {@link EngineDeposedError}.
+ * The helper owns the batch-vs-conditionalBatch decision — pass plain
+ * operations plus whatever base conditions you already need.
  *
- * @param internals - the engine internals (ownership mode, lease manager, deposed flag)
+ * @param internals - the engine internals (ownership mode, lease manager,
+ *   workflow claim registry, deposed flag)
+ * @param workflowId - the workflow this write is scoped to, fenced on that
+ *   workflow's claim epoch under `ownership: 'workflow-lease'`; or `null` for
+ *   an engine-scoped/cross-workflow write, which is never fenced on a
+ *   per-workflow claim regardless of ownership mode. Required — there is no
+ *   default — so every call site states its scope explicitly.
  * @param operations - the durable operations to commit atomically
  * @param baseConditions - CAS conditions the caller already requires (may be empty)
  * @param onLostRace - builds the error thrown on a same-epoch lost CAS race
  */
-export declare function commitFencedEngineWrite(internals: EngineInternals, operations: BatchOperation[], baseConditions: ConditionalBatchCondition[], onLostRace: () => Error): Promise<void>;
+export declare function commitFencedEngineWrite(internals: EngineInternals, workflowId: string | null, operations: BatchOperation[], baseConditions: ConditionalBatchCondition[], onLostRace: () => Error): Promise<void>;
 /**
  * Like {@link commitFencedEngineWrite}, but the caller treats a base-precondition
  * failure as a legitimate outcome rather than an error — used by the idempotent
  * start path, where a `false` means a concurrent same-key caller already wrote the
  * record (resolve to the existing run) rather than "retry". Returns `true` when the
  * batch committed and `false` when a base condition failed. Deposition is still a
- * hard halt: if the epoch condition is the one that failed, this drives
- * {@link handleDeposition} and throws {@link EngineDeposedError} — a deposed engine
- * must never report a precondition-failure the caller would read as "already exists"
- * and silently move on.
+ * hard halt: if the epoch condition is the one that failed, this drives the
+ * applicable deposition path and throws {@link EngineDeposedError} — a deposed
+ * engine (or a deposed single workflow, under `workflow-lease`) must never report a
+ * precondition-failure the caller would read as "already exists" and silently
+ * move on.
  *
  * @param internals - the engine internals
+ * @param workflowId - see {@link commitFencedEngineWrite} — the workflow this
+ *   write is scoped to, or `null` for an engine-scoped write
  * @param operations - the durable operations to commit atomically
  * @param baseConditions - the caller's required CAS conditions (non-empty in
  *   practice — this path is for conditional starts, which always carry one)
  */
-export declare function commitFencedEngineWriteAllowingPreconditionFailure(internals: EngineInternals, operations: BatchOperation[], baseConditions: ConditionalBatchCondition[]): Promise<boolean>;
+export declare function commitFencedEngineWriteAllowingPreconditionFailure(internals: EngineInternals, workflowId: string | null, operations: BatchOperation[], baseConditions: ConditionalBatchCondition[]): Promise<boolean>;