@lostgradient/weft 0.19.0 → 0.21.0

package/dist/core/engine/index.js

@@ -37,6 +37,7 @@ import {
   untagAll as untagAllWorkflows
 } from "./bulk-operations.js";
 import { createTimeOperationCallbacks as createTimeOperationCallbacksForEngine } from "./callback-creators-bundles.js";
+import { createPendingUpdateCallbacks as createPendingUpdateCallbacksForEngine } from "./callback-creators-core.js";
 import {
   createBroadcastCallbacks as createBroadcastCallbacksForEngine,
   createInlineParkingCallbacks as createInlineParkingCallbacksForEngine,
@@ -88,7 +89,8 @@ import { recordFinalizerState } from "./finalizer-state.js";
 import { getFinalizerStatus as getFinalizerStatusFromInternals } from "./finalizer-status.js";
 import {
   createWorkflowHandleWithResultPromise as createWorkflowHandleWithResultPromiseFromInternals,
-  getWorkflowResultPromise as getWorkflowResultPromiseFromInternals
+  getWorkflowResultPromise as getWorkflowResultPromiseFromInternals,
+  pollPendingCrossEngineResultWaiters
 } from "./handle-result.js";
 import { HANDLE_RESULT_PROMISE, WorkflowHandle } from "./handles.js";
 import { hasQueuedInlineWorkflowStart } from "./inline-launch-queue.js";
@@ -119,6 +121,12 @@ import { getStreamChunksFromInternals } from "./operations-stream.js";
 import {
   handleTimerFired as handleTimerFiredFromInternals
 } from "./operations-time.js";
+import {
+  bootstrapWorkflowLeaseOwnership,
+  buildOwnerSideSignalPollTarget
+} from "./ownership-bootstrap.js";
+import { bootstrapOwnershipGates } from "./ownership-mode-marker.js";
+import { processPendingUpdatesForHandlers as processPendingUpdatesForHandlersFromInternals } from "./pending-updates.js";
 import { assertCompatiblePersistedDataVersion } from "./persisted-data-version.js";
 import { query as queryWorkflow } from "./queries.js";
 import {
@@ -154,7 +162,11 @@ import {
   createSecondInstanceDetectionTick,
   createSecondInstanceDetector
 } from "./second-instance-detector.js";
-import { signal as signalWorkflow } from "./signals.js";
+import {
+  hasBufferedSignal as hasBufferedSignalFromInternals,
+  releaseSignalWaiter,
+  signal as signalWorkflow
+} from "./signals.js";
 import {
   loadScheduleState,
   loadWorkflowState,
@@ -173,12 +185,14 @@ import {
   timeoutWorkflow as timeoutWorkflowFromTermination
 } from "./termination.js";
 import {
+  deliverCoordinatedUpdateToWaiterIfAvailable as deliverCoordinatedUpdateToWaiterIfAvailableFromInternals,
   getUpdateResult as getUpdateResultFromInternals,
   submitCoordinatedUpdate as submitCoordinatedUpdateFromInternals,
   update as updateFromInternals
 } from "./updates.js";
 import { isTerminalWorkflowStatus } from "./validation.js";
 import { coerceScheduleId } from "./validation/schedule.js";
+import { confirmWakeOwnership } from "./wake-ownership-guard.js";
 import {
   replayWorkflowFeed,
   snapshotWorkflowFeedTail,
@@ -209,10 +223,18 @@ export {
   WorkflowTypeNotRegisteredForRecoveryError
 } from "./errors.js";
 export { HANDLE_RESULT_PROMISE, WorkflowHandle } from "./handles.js";
+export {
+  WeftWorkflowClaimLostWarning,
+  WeftWorkflowWakeDiscardedWarning,
+  WORKFLOW_CLAIM_LOST_WARNING_NAME,
+  WORKFLOW_WAKE_DISCARDED_WARNING_NAME
+} from "./lease-deposition.js";
 export {
   EngineLeaseAcquisitionTimeoutError,
   EngineLeaseCorruptedError,
-  EngineLeaseNotHeldError
+  EngineLeaseNotHeldError,
+  OwnershipModeMismatchError,
+  WorkflowClaimUnavailableError
 } from "./lease-errors.js";
 export { ScheduleHandle } from "./schedule-handle.js";
 export {
@@ -257,6 +279,7 @@ export class Engine extends EventTarget {
           throw new EngineCreateNameMismatchError("workflow", name, definition.name);
         engine.register(definition);
       }
+      await engine.#bootstrapOwnershipIfConfigured();
       await engine.#acquireLeaseIfConfigured();
       if (options.recover !== !1)
         await engine.recoverAll(options.acknowledgeUnknownWorkflowTypes !== void 0 ? { acknowledgeUnknownWorkflowTypes: options.acknowledgeUnknownWorkflowTypes } : {});
@@ -331,7 +354,7 @@ export class Engine extends EventTarget {
       onTimerFired: (entry) => handleTimerFiredFromInternals(getInternals(this), entry, this.#createTimeOperationCallbacks()),
       pollIntervalMs: resolvedOptions.schedulerPollIntervalMs,
       getNow,
-      commitTimerCleanup: (operations) => commitFencedEngineWrite(getInternals(this), operations, [], () => Error("Timer cleanup lost its fenced CAS race"))
+      commitTimerCleanup: (operations) => commitFencedEngineWrite(getInternals(this), null, operations, [], () => Error("Timer cleanup lost its fenced CAS race"))
     });
     getInternals(this).strategy = strategyBundle.strategy;
     getInternals(this).inlineStrategy = strategyBundle.inlineStrategy;
@@ -359,9 +382,11 @@ export class Engine extends EventTarget {
     getInternals(this).parkedInlineWorkflows = new Set;
     getInternals(this).terminalizingWorkflows = new Set;
     getInternals(this).deliveredPendingUpdateIds = new Map;
+    getInternals(this).onRecoveredWorkflowHook = void 0;
     getInternals(this).cancelHandlersByWorkflow = new Map;
     getInternals(this).reviewTimerIds = new Map;
     getInternals(this).pendingWebhooks = new Set;
+    getInternals(this).pendingResultPollTimers = new Set;
     getInternals(this).pendingTimelineEntries = new Map;
     getInternals(this).pendingAtomicWorkflowCommitSideEffects = new Map;
     getInternals(this).cleanupIntervalDisposalTracker = null;
@@ -381,7 +406,11 @@ export class Engine extends EventTarget {
     getInternals(this).secondInstanceDetectionInterval = null;
     getInternals(this).secondInstanceDetector = null;
     getInternals(this).leaseManager = null;
+    getInternals(this).workflowClaimRegistry = null;
+    getInternals(this).workflowClaimRenewalTask = null;
+    getInternals(this).workflowClaimMetrics = null;
     getInternals(this).inFlightLeaseAcquire = null;
+    getInternals(this).inFlightOwnershipBootstrap = null;
     getInternals(this).deposed = !1;
     getInternals(this).tearDownAfterDeposition = () => {
       this.#disposeAfterDeposition();
@@ -458,15 +487,81 @@ export class Engine extends EventTarget {
         internals.inFlightLeaseAcquire = null;
     }
   }
+  async#bootstrapOwnershipIfConfigured() {
+    const internals = getInternals(this), ownershipMode = internals.options.ownershipMode;
+    if (ownershipMode === "none")
+      return;
+    if (internals.disposed)
+      throw new EngineDisposedError;
+    if (ownershipMode === "lease") {
+      await bootstrapOwnershipGates({
+        storage: internals.storage,
+        ownershipMode,
+        getNow: internals.options.getNow
+      });
+      return;
+    }
+    if (internals.inFlightOwnershipBootstrap !== null) {
+      await internals.inFlightOwnershipBootstrap;
+      return;
+    }
+    if (internals.workflowClaimRegistry !== null)
+      return;
+    const bootstrap = (async () => {
+      const result = await bootstrapWorkflowLeaseOwnership({
+        storage: internals.storage,
+        getNow: internals.options.getNow,
+        claimTtlMs: internals.options.workflowClaimTtlMs,
+        claimRenewIntervalMs: internals.options.workflowClaimRenewIntervalMs,
+        isWorkflowTypeRegistered: (workflowType) => internals.workflowDefinitionsByName.has(workflowType),
+        onWorkflowClaimReclaimed: async (workflowId) => {
+          internals.inlineStrategy?.evictContextForReclaim(workflowId);
+          internals.deliveredPendingUpdateIds.delete(workflowId);
+          await recoverPendingAsyncActivities(internals, workflowId);
+          if (internals.disposed)
+            return;
+          await resumeFromLifecycle(internals, workflowId, this.#createLifecycleCallbacks(), internals.onRecoveredWorkflowHook, { forceReplayFromStorage: !0 });
+        },
+        signalPollTarget: this.#buildOwnerSideSignalPollTarget(),
+        updatePollTarget: this.#buildOwnerSideUpdatePollTarget()
+      });
+      if (internals.disposed)
+        throw new EngineDisposedError;
+      internals.workflowClaimRegistry = result.registry;
+      internals.workflowClaimRenewalTask = result.renewalTask;
+      internals.workflowClaimMetrics = result.metrics;
+      if (internals.options.backgroundTaskMode === "automatic")
+        result.renewalTask.start();
+    })();
+    internals.inFlightOwnershipBootstrap = bootstrap;
+    try {
+      await bootstrap;
+    } finally {
+      if (internals.inFlightOwnershipBootstrap === bootstrap)
+        internals.inFlightOwnershipBootstrap = null;
+    }
+  }
+  #detachWorkflowClaimOwnership() {
+    const internals = getInternals(this), registry = internals.workflowClaimRegistry;
+    internals.workflowClaimRenewalTask?.stop();
+    internals.workflowClaimRenewalTask = null;
+    internals.workflowClaimRegistry = null;
+    internals.workflowClaimMetrics = null;
+    return { registry };
+  }
+  async#releaseWorkflowClaimsBestEffort(registry) {
+    await registry?.releaseAll().catch(() => {});
+  }
   #disposeAfterDeposition() {
     const internals = getInternals(this);
     if (internals.disposed)
       return;
-    const leaseManager = internals.leaseManager;
+    const leaseManager = internals.leaseManager, { registry: workflowClaimRegistry } = this.#detachWorkflowClaimOwnership();
     disposeEngine(internals);
     if (this.#synchronousDisposeResult === null)
       this.#synchronousDisposeResult = (leaseManager?.release() ?? Promise.resolve(!0)).catch(() => !1);
     this.#synchronousDisposeResult;
+    this.#releaseWorkflowClaimsBestEffort(workflowClaimRegistry);
   }
   #startSecondInstanceDetection() {
     const internals = getInternals(this);
@@ -517,9 +612,55 @@ export class Engine extends EventTarget {
   #createInlineParkingCallbacks() {
     return createInlineParkingCallbacksForEngine(this);
   }
+  #buildOwnerSideSignalPollTarget() {
+    const internals = getInternals(this);
+    return buildOwnerSideSignalPollTarget({
+      listParkedInlineWorkflowIds: () => internals.parkedInlineWorkflows,
+      isParkedInlineWorkflow: (workflowId) => internals.parkedInlineWorkflows.has(workflowId),
+      parkedSignalName: (workflowId) => {
+        const pending = internals.pendingTimelineEntries.get(workflowId);
+        return pending?.entry.operationType === "wait-signal" ? pending.entry.operationLabel : void 0;
+      },
+      listSignalWaiterEntries: function* signalWaiterEntries() {
+        for (const [workflowId, waiterKeys] of internals.signalWaitersByWorkflow) {
+          if (typeof waiterKeys === "string") {
+            yield [workflowId, waiterKeys];
+            continue;
+          }
+          for (const waiterKey of waiterKeys)
+            yield [workflowId, waiterKey];
+        }
+      },
+      hasBufferedSignal: (workflowId, signalName) => hasBufferedSignalFromInternals(internals, workflowId, signalName),
+      resumeParkedInlineWorkflow: (workflowId) => resumeParkedInlineWorkflowFromInternals(internals, workflowId, this.#createInlineParkingCallbacks()),
+      confirmSignalWakeOwnership: (workflowId) => confirmWakeOwnership(internals, workflowId, "signal"),
+      wakeSignalWaiter: (workflowId, waiterKey) => {
+        const waiter = internals.signalWaiters.get(waiterKey);
+        if (waiter === void 0)
+          return;
+        if (releaseSignalWaiter(internals, workflowId, waiterKey, waiter))
+          waiter();
+      }
+    });
+  }
   #createUpdateCallbacks() {
     return createUpdateCallbacksForEngine(this);
   }
+  #buildOwnerSideUpdatePollTarget() {
+    const internals = getInternals(this);
+    return {
+      listHeldWorkflowIds: () => internals.workflowClaimRegistry?.listHeldWorkflowIds() ?? [],
+      hasPendingUpdates: async (workflowId) => {
+        return (await internals.updateCoordinator.getPendingUpdates(workflowId)).length > 0;
+      },
+      drainPendingUpdates: async (workflowId) => {
+        await processPendingUpdatesForHandlersFromInternals(internals, workflowId, createPendingUpdateCallbacksForEngine(this));
+        const stillPending = await internals.updateCoordinator.getPendingUpdates(workflowId), updateCallbacks = this.#createUpdateCallbacks();
+        for (const updateRequest of stillPending)
+          await deliverCoordinatedUpdateToWaiterIfAvailableFromInternals(internals, workflowId, updateRequest, !1, updateCallbacks);
+      }
+    };
+  }
   #createTimeOperationCallbacks() {
     return createTimeOperationCallbacksForEngine(this);
   }
@@ -629,6 +770,9 @@ export class Engine extends EventTarget {
   }
   async runMaintenance(now = getInternals(this).options.getNow()) {
     const internals = getInternals(this);
+    await this.#bootstrapOwnershipIfConfigured();
+    await internals.workflowClaimRenewalTask?.runOnce();
+    await pollPendingCrossEngineResultWaiters(internals);
     await internals.scheduler.tick(now);
     try {
       await internals.updateCoordinator.cleanupExpiredResponses();
@@ -768,11 +912,13 @@ export class Engine extends EventTarget {
     return resumeFromLifecycle(getInternals(this), workflowId, this.#createLifecycleCallbacks());
   }
   async recoverAll(options) {
+    await this.#bootstrapOwnershipIfConfigured();
     await this.#acquireLeaseIfConfigured();
     if (getInternals(this).disposed)
       throw new EngineDisposedError;
     await recoverPendingAsyncActivities(getInternals(this));
     await recoverOrphanedScheduleTimers(getInternals(this));
+    getInternals(this).onRecoveredWorkflowHook = options?.onRecoveredWorkflow;
     return recoverAllFromLifecycle(getInternals(this), this.#createLifecycleCallbacks(), options);
   }
   async completeAsyncActivity(token, result) {
@@ -934,10 +1080,12 @@ export class Engine extends EventTarget {
     const leaseManager = getInternals(this).leaseManager;
     if (leaseManager !== null && leaseManager.currentEpochBytes() !== null)
       process.emitWarning("engine ownership lease disposed synchronously; lease release is fire-and-forget, so exiting before the release completes can make the next instance wait for leaseTtl. Use await engine.shutdown(), await using, or await engine[Symbol.asyncDispose]() for prompt rolling-deploy handoff.", ENGINE_LEASE_SYNCHRONOUS_DISPOSE_WARNING_NAME);
+    const { registry: workflowClaimRegistry } = this.#detachWorkflowClaimOwnership();
     disposeEngine(getInternals(this));
     if (this.#synchronousDisposeResult === null)
       this.#synchronousDisposeResult = leaseManager?.release() ?? Promise.resolve(!0);
     this.#synchronousDisposeResult;
+    this.#releaseWorkflowClaimsBestEffort(workflowClaimRegistry);
   }
   async#disposeAsyncWithLeaseResult() {
     if (!getInternals(this).disposed) {
@@ -950,9 +1098,11 @@ export class Engine extends EventTarget {
       } catch (error) {
         drainFailure = { error };
       } finally {
+        const { registry: workflowClaimRegistry } = this.#detachWorkflowClaimOwnership();
         disposeEngine(getInternals(this));
         await getInternals(this).inFlightLeaseAcquire?.catch(() => {});
         leaseReleased = await (this.#synchronousDisposeResult ?? leaseManager?.release() ?? Promise.resolve(!0));
+        await this.#releaseWorkflowClaimsBestEffort(workflowClaimRegistry);
       }
       if (drainFailure !== null)
         throw new EngineDisposalError(drainFailure.error, leaseReleased);

package/dist/core/engine/inline-launch-queue.js

@@ -1,6 +1,7 @@
 import { WorkflowStartedEvent } from "../events.js";
 import { startWorkflowExecution } from "./lifecycle.js";
 import { loadWorkflowState } from "./storage-io.js";
+import { confirmWakeOwnership } from "./wake-ownership-guard.js";
 async function yieldQueuedShutdownAdvanceOpportunity() {
   await new Promise((resolve) => {
     setTimeout(resolve, 0);
@@ -83,11 +84,19 @@ export async function drainQueuedInlineWorkflowStarts(internals, callbacks, opti
     }
   }
 }
+async function isQueuedStartStillTheLiveRun(internals, start) {
+  const currentState = await loadWorkflowState(internals, start.workflowId);
+  return currentState !== null && currentState.status === "running" && (start.workflowExecutionToken === void 0 || currentState.workflowExecutionToken === start.workflowExecutionToken);
+}
 async function startQueuedInlineWorkflowExecution(internals, start, callbacks, options) {
   try {
     const state = await loadWorkflowState(internals, start.workflowId);
     if (!state || state.status !== "running")
       return;
+    if (await confirmWakeOwnership(internals, start.workflowId, "inline-macrotask-drive") === "discard")
+      return;
+    if (!await isQueuedStartStillTheLiveRun(internals, start))
+      return;
     internals.queuedInlineWorkflowStartIds.delete(start.workflowId);
     internals.engine.dispatchEvent(new WorkflowStartedEvent(start.workflowId, start.workflowType, start.input));
     startWorkflowExecution(internals, start.workflowId, state.workflowExecutionToken, start.workflowType, start.input, start.checkpoint, start.nestingDepth, start.executionDeadline, start.executionStateOwnerId);

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

@@ -32,6 +32,7 @@ import type { Scheduler } from '../scheduler.ts';
 import type { Checkpoint, StartWorkflowOptions } from '../types.ts';
 import type { UpdateCoordinator } from '../updates.ts';
 import type { WorkflowVersionTuple } from '../workflow-version-tuple.ts';
+import type { RecoveredWorkflowInfo } from './lifecycle/shared.ts';
 import type { ActivityHeartbeatKey } from './activity-heartbeat-tracking.ts';
 import type { PendingTimelineEntry, QueuedInlineWorkflowExecutionStart, RegistrationEntry, ResolvedOptions, TrackedWaiterKeys, WorkflowResultWaiter } from './engine-internal-types.ts';
 import type { EngineCleanupIntervalDisposalTracker } from './engine-leak-warnings.ts';
@@ -40,6 +41,9 @@ import type { WorkflowFeedListener } from './index.ts';
 import type { LeaseManager } from './lease-manager.ts';
 import type { ScheduleHandleEngine } from './schedule-handle.ts';
 import type { SecondInstanceDetector } from './second-instance-detector.ts';
+import type { WorkflowClaimMetricsRecorder } from './workflow-claim-metrics.ts';
+import type { WorkflowClaimRegistry } from './workflow-claim-registry.ts';
+import type { WorkflowClaimRenewalTask } from './workflow-claim-renewal-task.ts';
 export type SleepTimerAcknowledgementWaiter = {
     fireAt: number;
     operationId: string;
@@ -239,6 +243,43 @@ export interface EngineInternals {
      * Step 1; epoch fencing of durable writes (Step 2) is what makes it enforceable.
      */
     leaseManager: LeaseManager | null;
+    /**
+     * The active per-workflow claim registry for `ownership: 'workflow-lease'`;
+     * `null` under `'none'`/`'lease'` and, for now, ALSO under `'workflow-lease'`
+     * itself — wiring construction (Gate 1/Gate 2, actually instantiating the
+     * registry, and folding `acquire()` into start/resume/delayed-start-fire) is a
+     * later stage. Its presence here lets {@link commitFencedEngineWrite} read
+     * {@link WorkflowClaimRegistry.currentEpochBytes} for a workflow-scoped write
+     * without that later stage having to touch the fencing path again. Until it is
+     * populated, every workflow-scoped write under `'workflow-lease'` fails closed
+     * with {@link EngineDeposedError} — correct, not a bug: this engine holds no
+     * claim for any workflow yet.
+     */
+    workflowClaimRegistry: WorkflowClaimRegistry | null;
+    /**
+     * The active per-workflow claim-renewal task for `ownership: 'workflow-lease'`;
+     * `null` under `'none'`/`'lease'` and until `#bootstrapOwnershipIfConfigured`
+     * completes. Renews every claim this engine holds (active or parked) on its
+     * own cadence — independent of the durable-timer scheduler, so `startScheduler:
+     * false` still renews claims — or via `runMaintenance()` under
+     * `backgroundTasks: 'manual'`, which never starts its interval. Stopped
+     * (interval cleared, never awaited — stopping is synchronous) and detached at
+     * every `disposeEngine` call site; releasing the claims it was renewing is the
+     * separate, best-effort `workflowClaimRegistry.releaseAll()` step each
+     * disposal path drives on its own schedule.
+     */
+    workflowClaimRenewalTask: WorkflowClaimRenewalTask | null;
+    /**
+     * Bounded-cardinality observability recorder for the `ownership:
+     * 'workflow-lease'` claim protocol (ADR 0002 § Observability); `null` under
+     * `'none'`/`'lease'` and until `#bootstrapOwnershipIfConfigured` completes.
+     * One instance per engine process, shared by this engine's claim-renewal task
+     * (which feeds it renewal-failure counts and the active-claim gauge after
+     * every pass) and, in a later stage, its claim-acquiring entry points (start,
+     * resume, delayed-start fire), which would record `acquired`/`takeover`/
+     * `lost_race`/`deposed`/`backoff_skipped` attempts into the same instance.
+     */
+    workflowClaimMetrics: WorkflowClaimMetricsRecorder | null;
     /**
      * The in-flight lease acquisition, or `null` when none is running. Set while
      * `#acquireLeaseIfConfigured` awaits `acquire()` (which can park for the whole
@@ -248,6 +289,15 @@ export interface EngineInternals {
      * than leaking until TTL on an already-disposed engine.
      */
     inFlightLeaseAcquire: Promise<void> | null;
+    /**
+     * The in-flight `ownership: 'workflow-lease'` bootstrap (Gate 1, Gate 2, and
+     * claim-registry/renewal-task construction), or `null` when none is running.
+     * Mirrors {@link inFlightLeaseAcquire}'s idempotency shape: concurrent
+     * `Engine.create` + `recoverAll` (and repeated `recoverAll`/`runMaintenance`)
+     * callers await this same promise rather than racing the gates twice. Always
+     * `null` under `ownership: 'none'`/`'lease'`, which never run this bootstrap.
+     */
+    inFlightOwnershipBootstrap: Promise<void> | null;
     /**
      * Set to `true` the instant this engine is detected as deposed under
      * `ownership: 'lease'` — either a fenced durable write's CAS failed against a
@@ -296,9 +346,32 @@ export interface EngineInternals {
      * updates whose delete never committed).
      */
     deliveredPendingUpdateIds: Map<string, Set<string>>;
+    /**
+     * The most recent `recoverAll({ onRecoveredWorkflow })` hook installed by
+     * this host, retained so a LATER same-engine reclaim (ADR 0002's recurring
+     * scan, after `recover: false` skipped this workflow entirely at startup
+     * because another engine held it then) still runs it before resuming.
+     * Without this, `index.ts`'s `onWorkflowClaimReclaimed` callback would pass
+     * `undefined` for every reclaim-driven resume, silently skipping whatever
+     * host initialization/validation the hook contract guarantees runs before
+     * recovered execution. `undefined` until `recoverAll()` is ever called with
+     * this option.
+     */
+    onRecoveredWorkflowHook: ((info: RecoveredWorkflowInfo) => void | Promise<void>) | undefined;
     cancelHandlersByWorkflow: Map<string, Array<() => Promise<void> | void>>;
     reviewTimerIds: Map<string, string[]>;
     pendingWebhooks: Set<AbortController>;
+    /**
+     * Every `setTimeout` handle `scheduleCrossEngineResultPollIfPending`
+     * (`handle-result.ts`) currently has pending, so disposal can cancel them.
+     * Without this, disposing an automatic-mode engine while a cross-engine
+     * result waiter is parked rejects and clears the waiter but leaves this
+     * untracked timer alive — the timer queue retains the waiter, engine
+     * internals, and storage reference until `workflowClaimRenewIntervalMs`
+     * elapses, and its callback then calls `bootstrapWorkflowResultResolver`
+     * against already-disposed storage.
+     */
+    pendingResultPollTimers: Set<ReturnType<typeof setTimeout>>;
     alertManager: AlertManager | null;
     eventLogHeads: Map<string, Readonly<EventHeadRecord>>;
     workflowFeedListeners: Map<string, Set<WorkflowFeedListener>>;

package/dist/core/engine/invoke-update-handler.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Invoking an `ctx.onUpdate()` handler, and the type of the handler itself.
+ *
+ * Separate from `updates.ts` because both the inline dispatch path and
+ * `pending-updates.ts`'s replay path call it, and because it is pure handler
+ * invocation 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/invoke-update-handler
+ */
+import type { EngineInternals } from './internals.ts';
+/** An `ctx.onUpdate()` handler as stored on a live workflow context. */
+export type InlineUpdateHandler = (payload: unknown) => unknown;
+/**
+ * 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>;

package/dist/core/engine/invoke-update-handler.js

@@ -0,0 +1,7 @@
+import { isGeneratorResult } from "../step-context.js";
+export async function invokeUpdateHandler(_internals, name, handler, payload) {
+  const result = handler(payload);
+  if (isGeneratorResult(result))
+    throw TypeError(`Update handler "${name}" returned a generator. Update handlers must return a plain value or a Promise, not a generator.`);
+  return await result;
+}

package/dist/core/engine/lease-deposition.d.ts

@@ -64,3 +64,135 @@ export declare const ENGINE_LEASE_LOST_WARNING_NAME = "WeftEngineLeaseLostWarnin
  * not advance in-memory state past a durable write that did not land.
  */
 export declare function handleDeposition(internals: EngineInternals): void;
+/**
+ * `name` of the operator warning emitted when `ownership: 'workflow-lease'`
+ * loses one workflow's claim — a renewal CAS failure (a successor stole the
+ * claim) or a fenced write rejected because a newer epoch now holds it. Unlike
+ * {@link ENGINE_LEASE_LOST_WARNING_NAME}, this is per-workflow, not per-engine:
+ * the rest of this engine's claimed workflows are unaffected and keep running.
+ *
+ * @example
+ * ```ts
+ * import { WORKFLOW_CLAIM_LOST_WARNING_NAME } from '@lostgradient/weft';
+ *
+ * process.on('warning', (warning) => {
+ *   if (warning.name === WORKFLOW_CLAIM_LOST_WARNING_NAME) {
+ *     console.error('lost a workflow claim', warning.message);
+ *   }
+ * });
+ * ```
+ */
+export declare const WORKFLOW_CLAIM_LOST_WARNING_NAME = "WeftWorkflowClaimLostWarning";
+/**
+ * Operator diagnostic for a lost per-workflow ownership claim under
+ * `ownership: 'workflow-lease'` (see
+ * [ADR 0002](../../../documentation/contributing/architecture-decisions/0002-multiengine-per-workflow-ownership.md)).
+ * Carries the affected `workflowId` as a real field — `process.emitWarning(message,
+ * name)` only accepts strings, so this is emitted as the warning object itself
+ * (`process.emitWarning(warning)`) rather than passed as a message, which lets
+ * consumers read `warning.workflowId` directly instead of parsing it back out
+ * of the message text.
+ *
+ * @example
+ * ```ts
+ * import { WeftWorkflowClaimLostWarning } from '@lostgradient/weft';
+ *
+ * process.on('warning', (warning) => {
+ *   if (warning instanceof WeftWorkflowClaimLostWarning) {
+ *     console.error('deposed workflow:', warning.workflowId);
+ *   }
+ * });
+ * ```
+ */
+export declare class WeftWorkflowClaimLostWarning extends Error {
+    readonly workflowId: string;
+    constructor(workflowId: string);
+}
+/**
+ * The wake path a stale in-memory resolver was discarded from, for
+ * {@link WeftWorkflowWakeDiscardedWarning}. Mirrors the `wakeOwnershipCheck`
+ * call sites named in ADR 0002: a durable timer firing, a re-evaluated
+ * `ctx.waitUntil()` condition, a delivered signal, an async-activity
+ * completion/failure, a child workflow's termination, or a deferred inline
+ * macrotask drive.
+ *
+ * @example
+ * ```ts
+ * import type { WorkflowWakeKind } from '@lostgradient/weft';
+ *
+ * const kind: WorkflowWakeKind = 'signal';
+ * void kind;
+ * ```
+ */
+export type WorkflowWakeKind = 'sleep' | 'wait-condition' | 'signal' | 'async-activity' | 'child-completion' | 'update' | 'inline-macrotask-drive';
+/**
+ * `name` of the operator warning emitted when `wakeOwnershipCheck` discards a
+ * stale in-memory wake resolver — it re-read the durable holder record and
+ * found this engine no longer holds the generation (engine id AND epoch) it
+ * parked the workflow under, so the resolver is dropped without driving the
+ * generator.
+ *
+ * @example
+ * ```ts
+ * import { WORKFLOW_WAKE_DISCARDED_WARNING_NAME } from '@lostgradient/weft';
+ *
+ * process.on('warning', (warning) => {
+ *   if (warning.name === WORKFLOW_WAKE_DISCARDED_WARNING_NAME) {
+ *     console.error('discarded a stale wake', warning.message);
+ *   }
+ * });
+ * ```
+ */
+export declare const WORKFLOW_WAKE_DISCARDED_WARNING_NAME = "WeftWorkflowWakeDiscardedWarning";
+/**
+ * Operator diagnostic emitted whenever `wakeOwnershipCheck` discards a stale
+ * in-memory wake resolver under `ownership: 'workflow-lease'` (see
+ * [ADR 0002](../../../documentation/contributing/architecture-decisions/0002-multiengine-per-workflow-ownership.md)).
+ * Carries the affected `workflowId` and the `wakeKind` that was discarded as
+ * real fields, for the same reason {@link WeftWorkflowClaimLostWarning} does —
+ * `process.emitWarning(message, name)` cannot carry structured data, so this is
+ * emitted as the warning object itself.
+ *
+ * @example
+ * ```ts
+ * import { WeftWorkflowWakeDiscardedWarning } from '@lostgradient/weft';
+ *
+ * process.on('warning', (warning) => {
+ *   if (warning instanceof WeftWorkflowWakeDiscardedWarning) {
+ *     console.error('discarded wake', warning.workflowId, warning.wakeKind);
+ *   }
+ * });
+ * ```
+ */
+export declare class WeftWorkflowWakeDiscardedWarning extends Error {
+    readonly workflowId: string;
+    readonly wakeKind: WorkflowWakeKind;
+    constructor(workflowId: string, wakeKind: WorkflowWakeKind);
+}
+/**
+ * Emit one of the two per-workflow warnings above. Injected as a seam
+ * (defaulting to `process.emitWarning(warning)`) so later stages — the claim
+ * renewal loop and `wakeOwnershipCheck` — get deterministic test coverage of
+ * their emission sites, mirroring the `warn` option
+ * {@link createSecondInstanceDetector} already takes. Unlike that seam, which
+ * is message-only because its warning name is a single fixed constant, this
+ * one takes the warning *instance* — `WeftWorkflowClaimLostWarning` and
+ * `WeftWorkflowWakeDiscardedWarning` carry different fields, so a caller
+ * filtering or asserting on a specific warning needs the real object, not a
+ * pre-flattened string.
+ */
+export type EmitWorkflowLeaseWarning = (warning: WeftWorkflowClaimLostWarning | WeftWorkflowWakeDiscardedWarning) => void;
+/**
+ * Emit {@link WeftWorkflowClaimLostWarning} for `workflowId`. `emit` defaults
+ * to `process.emitWarning(warning)`; pass a test double to assert on the
+ * emitted instance deterministically instead of scraping `process`'s global
+ * `warning` event.
+ */
+export declare function emitWorkflowClaimLostWarning(workflowId: string, emit?: EmitWorkflowLeaseWarning): void;
+/**
+ * Emit {@link WeftWorkflowWakeDiscardedWarning} for `workflowId`/`wakeKind`.
+ * `emit` defaults to `process.emitWarning(warning)`; pass a test double to
+ * assert on the emitted instance deterministically instead of scraping
+ * `process`'s global `warning` event.
+ */
+export declare function emitWorkflowWakeDiscardedWarning(workflowId: string, wakeKind: WorkflowWakeKind, emit?: EmitWorkflowLeaseWarning): void;

package/dist/core/engine/lease-deposition.js

@@ -8,3 +8,34 @@ export function handleDeposition(internals) {
   if (tearDown !== null)
     Promise.resolve().then(tearDown).catch(() => {});
 }
+export const WORKFLOW_CLAIM_LOST_WARNING_NAME = "WeftWorkflowClaimLostWarning";
+
+export class WeftWorkflowClaimLostWarning extends Error {
+  workflowId;
+  constructor(workflowId) {
+    super(`workflow "${workflowId}" lost its ownership claim: another engine now holds it at a newer epoch. This engine stops driving that workflow; the rest of its claimed workflows are unaffected.`);
+    this.name = WORKFLOW_CLAIM_LOST_WARNING_NAME;
+    this.workflowId = workflowId;
+  }
+}
+export const WORKFLOW_WAKE_DISCARDED_WARNING_NAME = "WeftWorkflowWakeDiscardedWarning";
+
+export class WeftWorkflowWakeDiscardedWarning extends Error {
+  workflowId;
+  wakeKind;
+  constructor(workflowId, wakeKind) {
+    super(`discarded a stale "${wakeKind}" wake for workflow "${workflowId}": this engine no longer holds the ownership-claim generation it parked under. The in-memory resolver is dropped without driving the generator.`);
+    this.name = WORKFLOW_WAKE_DISCARDED_WARNING_NAME;
+    this.workflowId = workflowId;
+    this.wakeKind = wakeKind;
+  }
+}
+const defaultEmitWorkflowLeaseWarning = (warning) => {
+  process.emitWarning(warning);
+};
+export function emitWorkflowClaimLostWarning(workflowId, emit = defaultEmitWorkflowLeaseWarning) {
+  emit(new WeftWorkflowClaimLostWarning(workflowId));
+}
+export function emitWorkflowWakeDiscardedWarning(workflowId, wakeKind, emit = defaultEmitWorkflowLeaseWarning) {
+  emit(new WeftWorkflowWakeDiscardedWarning(workflowId, wakeKind));
+}