@lostgradient/weft 0.2.1 → 0.4.0

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

@@ -28,13 +28,19 @@ import type { InlineExecutionStrategy } from '../inline-execution-strategy.ts';
 import type { ComposedActivityInterceptor, ComposedWorkflowInterceptor, Interceptor } from '../interceptor.ts';
 import type { HumanReviewResult, ReviewCoordinator } from '../review/index.ts';
 import type { Scheduler } from '../scheduler.ts';
-import type { Checkpoint } from '../types.ts';
+import type { Checkpoint, StartWorkflowOptions } from '../types.ts';
 import type { UpdateCoordinator } from '../updates.ts';
 import type { WorkflowVersionTuple } from '../workflow-version-tuple.ts';
 import type { PendingTimelineEntry, QueuedInlineWorkflowExecutionStart, RegistrationEntry, ResolvedOptions, TrackedWaiterKeys, WorkflowResultWaiter } from './engine-internal-types.ts';
-import type { ScheduleHandleEngine, WorkflowHandle, WorkflowHandleEngine } from './handles.ts';
+import type { EngineCleanupIntervalDisposalTracker } from './engine-leak-warnings.ts';
+import type { WorkflowHandle, WorkflowHandleEngine } from './handles.ts';
 import type { WorkflowFeedListener } from './index.ts';
-type EngineRuntime = WorkflowHandleEngine & ScheduleHandleEngine;
+import type { LeaseManager } from './lease-manager.ts';
+import type { ScheduleHandleEngine } from './schedule-handle.ts';
+import type { SecondInstanceDetector } from './second-instance-detector.ts';
+type EngineRuntime = WorkflowHandleEngine & ScheduleHandleEngine & {
+    start(type: string, input: unknown, options?: StartWorkflowOptions): Promise<WorkflowHandle>;
+};
 export interface EngineInternals {
     engine: EngineRuntime;
     storage: WeftStorage;
@@ -64,6 +70,23 @@ export interface EngineInternals {
     resultResolvers: Map<string, WorkflowResultWaiter>;
     signalWaiters: Map<string, () => void>;
     signalWaitersByWorkflow: Map<string, TrackedWaiterKeys>;
+    /**
+     * In-process resolvers for inline `ctx.waitUntil` waits, keyed by `workflowId`
+     * ALONE — a workflow has at most one active wait-condition because its inline
+     * generator is suspended at exactly one yield, and the top-level-only guard in
+     * `executeSubOperation` rejects `waitUntil` as a `race`/`all`/`speculate`
+     * branch. So unlike `signalWaiters` (which need a per-workflow string-or-Set
+     * index because they CAN be concurrent sub-operations), this is a flat map with
+     * no secondary index. Calling the resolver wakes `processWaitConditionOperation`
+     * to re-evaluate its predicate. Never checkpointed — engine-memory state cleared
+     * on terminal cleanup.
+     *
+     * Note: the deadline TIMER is still keyed `cond:${workflowId}:${step}` (step is
+     * stable across replay, so recovery does not double-arm). Only this waiter map
+     * keys by `workflowId`. If `waitUntil`-in-`race`/`all`/`speculate` is ever
+     * supported, this keying must revert to `${workflowId}:${step}` + a Set index.
+     */
+    conditionWaiters: Map<string, () => void>;
     updateWaiters: Map<string, (payload: unknown) => void>;
     updateWaitersByWorkflow: Map<string, TrackedWaiterKeys>;
     sleepResolvers: Map<string, () => void>;
@@ -75,11 +98,15 @@ export interface EngineInternals {
     activityRegistry: ActivityRegistry;
     /**
      * Per-workflow activity registries built from
-     * `workflow({ name }).activities({ ... }).execute(...)`. Indexed by workflow
-     * type. Phase 3 wires lookups via `activityRegistriesByWorkflow.get(type)`
-     * first, falling back to {@link EngineInternals.activityRegistry} so the
-     * legacy global path keeps working until Phase 6 removes it. Each registry
-     * is constructed from a defensive deep clone+freeze of the workflow's
+     * `workflow({ name }).activities({ ... }).execute(...)`, indexed by workflow
+     * type. Activity lookup is per-activity: it consults the workflow's
+     * `activityRegistriesByWorkflow.get(type)` registry first and, for any activity
+     * that registry does not contain, falls back to the engine-wide
+     * {@link EngineInternals.activityRegistry}. Both sources are first-class — a
+     * workflow can resolve some activities from its own `activities(...)` map and
+     * others (shared/globally-registered) from the global registry, and a workflow
+     * with no per-workflow map resolves entirely from the global one. Each
+     * per-workflow registry is a defensive deep clone+freeze of the workflow's
      * `activities` map so post-registration mutation cannot reach the engine.
      */
     activityRegistriesByWorkflow: Map<string, ActivityRegistry>;
@@ -103,11 +130,25 @@ export interface EngineInternals {
     broadcastChannel: BroadcastChannel | null;
     pendingNestingDepth: number | undefined;
     pendingParentHeaders: Map<string, string> | undefined;
-    pendingExecutionStateOwnerId: string | undefined;
+    pendingExecutionStateOwnerId: string | null | undefined;
     workflowNestingDepths: Map<string, number>;
     workflowHeaders: Map<string, Map<string, string>>;
     workflowStateWriteChains: Map<string, Promise<void>>;
     heartbeatDetails: Map<string, unknown>;
+    /**
+     * Last heartbeat payload PER ACTIVITY STEP, so a retry of a step can read the
+     * heartbeat its previous attempt recorded (the resumable-batch pattern). Keyed
+     * `workflowId -> step -> details`. This is separate from {@link heartbeatDetails}
+     * (which is keyed by `workflowId` alone and powers the `activityProgress` query):
+     * concurrent activities inside one `ctx.all` would clobber a workflow-keyed map,
+     * so a retry could read a sibling's heartbeat. The step is stable across attempts
+     * (assigned once at `stepIndex++`), so a retry reads its OWN prior heartbeat.
+     * Never checkpointed — held only in engine memory and cleared (by workflowId, the
+     * outer key) on terminal cleanup and purge, the same lifecycle as
+     * {@link heartbeatDetails}. Inline-execution only; worker-executed activities run
+     * their function out of process and never observe this.
+     */
+    lastHeartbeatDetailsByStep: Map<string, Map<number, unknown>>;
     /**
      * Per-run, non-serialized `services` value exposed to the workflow body as
      * `ctx.services`. Set at `engine.start({ services })` and re-provided on
@@ -123,17 +164,63 @@ export interface EngineInternals {
      * reloaded by `recoverAll()`. See `async-activity-completion.ts`.
      */
     pendingAsyncActivities: Map<string, import('./async-activity-completion.ts').PendingAsyncActivity>;
+    /**
+     * Completed or failed async-activity tokens that were consumed before inline
+     * recovery adopted the workflow generator. Replay drains these by workflow id
+     * when it reaches the same deterministic async-activity token again.
+     */
+    pendingAsyncActivityResolutions: Map<string, import('./async-activity-completion.ts').PendingAsyncActivityResolution[]>;
     pendingStarts: Set<string>;
     pendingScheduleCreations: Set<string>;
     workflowsNeedingTerminalCleanup: Set<string>;
     cleanupInterval: ReturnType<typeof setInterval> | null;
-    cleanupIntervalDisposalTracker: {
-        disposed: boolean;
-        cleanupInterval: ReturnType<typeof setInterval> | null;
-    } | null;
+    cleanupIntervalDisposalTracker: EngineCleanupIntervalDisposalTracker | null;
     retentionSweepInterval: ReturnType<typeof setInterval> | null;
     retentionSweepInFlight: Promise<void> | null;
     nextRetentionSweepAt: number | null;
+    /** Interval driving the best-effort second-instance detector; `null` when off. */
+    secondInstanceDetectionInterval: ReturnType<typeof setInterval> | null;
+    /** The active second-instance detector; `null` when detection is disabled. */
+    secondInstanceDetector: SecondInstanceDetector | null;
+    /**
+     * The active lease manager for `ownership: 'lease'`; `null` when ownership is
+     * `'none'`. Acquired before recovery, renewed on a heartbeat, released on
+     * dispose. Unlike the second-instance detector its acquire/renew errors are real
+     * (a failed acquire blocks recovery). Renewal loss is surfaced as a warning in
+     * Step 1; epoch fencing of durable writes (Step 2) is what makes it enforceable.
+     */
+    leaseManager: LeaseManager | null;
+    /**
+     * The in-flight lease acquisition, or `null` when none is running. Set while
+     * `#acquireLeaseIfConfigured` awaits `acquire()` (which can park for the whole
+     * `leaseWaitTimeout` waiting for a handoff) and cleared when it settles. Disposal
+     * awaits this so a dispose that races a parked acquire is a clean handoff — the
+     * holder this engine may take is released before `asyncDispose` resolves, rather
+     * than leaking until TTL on an already-disposed engine.
+     */
+    inFlightLeaseAcquire: 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
+     * newer epoch ({@link commitFencedEngineWrite}) or the lease manager reported
+     * `onLeaseLost('deposed')`. It is the synchronous half of the deposition halt:
+     * {@link commitFencedEngineWrite} short-circuits at its top on this flag, so a
+     * write that *starts* after detection is rejected before reaching storage,
+     * while writes already in flight are caught by the epoch CAS itself. Set once
+     * by {@link handleDeposition}, which also warns the operator and schedules a
+     * deferred engine teardown. Always `false` under `ownership: 'none'`.
+     */
+    deposed: boolean;
+    /**
+     * Teardown callback invoked (deferred to a later tick) when this engine is
+     * deposed. Set once during engine construction to the engine's own
+     * `disposeAfterDeposition` method. It exists as an injected field rather than a
+     * direct import so {@link handleDeposition} (reached from the durable-write
+     * helper) does not statically import `disposal.ts`, which would close an import
+     * cycle (`storage-io → fenced-write → lease-deposition → disposal → … →
+     * storage-io`). `null` until the constructor wires it.
+     */
+    tearDownAfterDeposition: (() => void) | null;
     reviewCoordinator: ReviewCoordinator;
     reviewWaiters: Map<string, (decision: HumanReviewResult) => void>;
     reviewWaitersByWorkflow: Map<string, TrackedWaiterKeys>;
@@ -144,6 +231,22 @@ export interface EngineInternals {
     workflowReviewIds: Map<string, Set<string>>;
     parkedInlineWorkflows: Set<string>;
     terminalizingWorkflows: Set<string>;
+    /**
+     * Coordinated update IDs already claimed for delivery by a pending-update
+     * drain, keyed by workflow. Several drain triggers (each `update()` schedules a
+     * `setTimeout(0)` drain; the post-advance path drains too) can fire
+     * near-simultaneously, and the durable consume-delete (`buildResponseOperations`
+     * deletes the pending key via async `storage.batch`) lags the in-memory
+     * `getPendingUpdates` scan — so overlapping drains would re-read and re-deliver
+     * the same buffered update. Each drain claims an update's id SYNCHRONOUSLY (no
+     * `await` between the membership check and the add) before delivering it, so a
+     * racing drain that scans the same id skips it. The claim persists across
+     * drains (unlike a per-drain guard), which is what makes delivery idempotent
+     * against the cross-drain race. Cleared per workflow on terminal cleanup; empty
+     * after a crash, which matches durable state (recovery re-delivers exactly the
+     * updates whose delete never committed).
+     */
+    deliveredPendingUpdateIds: Map<string, Set<string>>;
     cancelHandlersByWorkflow: Map<string, Array<() => Promise<void> | void>>;
     reviewTimerIds: Map<string, string[]>;
     pendingWebhooks: Set<AbortController>;
@@ -151,7 +254,16 @@ export interface EngineInternals {
     eventLogHeads: Map<string, Readonly<EventHeadRecord>>;
     workflowFeedListeners: Map<string, Set<WorkflowFeedListener>>;
     workflowVersionTuples: Map<string, WorkflowVersionTuple>;
+    /**
+     * Cached visibility-index watermark for query planning. `undefined` means the
+     * watermark has not been read yet or an in-process caller invalidated it.
+     * `workflowVisibilityWatermarkExpiresAt` bounds how long external maintenance
+     * commands can leave this process planning against a stale watermark.
+     */
+    workflowVisibilityWatermark: 'current' | 'stale' | undefined;
+    workflowVisibilityWatermarkExpiresAt: number | undefined;
     pendingTimelineEntries: Map<string, PendingTimelineEntry>;
+    pendingAtomicWorkflowCommitSideEffects: Map<string, import('./checkpoint-side-effects.ts').AtomicWorkflowCommitSideEffects>;
 }
 /**
  * Set up an empty `EngineInternals` skeleton in the WeakMap. The Engine

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

@@ -0,0 +1,35 @@
+/**
+ * Pure codecs for the two lease ownership keys (`lease:epoch` and `lease:holder`).
+ * Extracted from `lease-manager.ts` to keep that file under the `max-lines` ceiling;
+ * these functions have no engine state, so they live and test cleanly on their own.
+ *
+ * @module core/engine/lease-codec
+ */
+/** The decoded `lease:holder` record. */
+export type LeaseHolderRecord = {
+    holderId: string;
+    /** Wall-clock ms (from the engine's `getNow`) after which the lease may be stolen. */
+    expiresAt: number;
+    /** The ownership epoch this holder acquired. Mirrors `lease:epoch`. */
+    epoch: number;
+};
+/**
+ * Encode an 8-byte big-endian uint64 epoch. `DataView.setBigUint64` is the
+ * standard, overflow-safe encoder — preferred over a hand-rolled byte loop.
+ */
+export declare function encodeEpoch(epoch: number): Uint8Array;
+/**
+ * Decode an 8-byte big-endian uint64 epoch, or `null` when the stored value is
+ * not a usable epoch — not exactly 8 bytes, or outside `[1, MAX_SAFE_INTEGER)`.
+ * The epoch is the monotonic fencing high-water mark, so it must stay exactly
+ * comparable AND have room to increment: acquisition always mints `epoch + 1`, so
+ * `Number.MAX_SAFE_INTEGER` itself is rejected too — minting `2^53` would fail
+ * `Number.isSafeInteger` on the next boot and brick the lease. A value at or above
+ * the safe-integer ceiling (or below `1`) routes to the corruption path
+ * (fail-closed at boot) rather than silently re-minting an imprecise generation.
+ */
+export declare function decodeEpoch(raw: Uint8Array): number | null;
+/** Encode a holder record to its stored JSON bytes. */
+export declare function encodeHolder(record: LeaseHolderRecord): Uint8Array;
+/** Decode a stored holder record, tolerating any malformed/foreign value as `null`. */
+export declare function decodeHolder(raw: Uint8Array): LeaseHolderRecord | null;

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

@@ -0,0 +1,32 @@
+const textEncoder = new TextEncoder, textDecoder = new TextDecoder;
+export function encodeEpoch(epoch) {
+  const bytes = new Uint8Array(8);
+  new DataView(bytes.buffer).setBigUint64(0, BigInt(epoch), !1);
+  return bytes;
+}
+export function decodeEpoch(raw) {
+  if (raw.byteLength !== 8)
+    return null;
+  const value = new DataView(raw.buffer, raw.byteOffset, raw.byteLength).getBigUint64(0, !1), numberValue = Number(value);
+  return Number.isSafeInteger(numberValue) && numberValue >= 1 && numberValue < Number.MAX_SAFE_INTEGER ? numberValue : null;
+}
+export function encodeHolder(record) {
+  return textEncoder.encode(JSON.stringify(record));
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null;
+}
+export function decodeHolder(raw) {
+  let parsed;
+  try {
+    parsed = JSON.parse(textDecoder.decode(raw));
+  } catch {
+    return null;
+  }
+  if (!isRecord(parsed))
+    return null;
+  const { holderId, expiresAt, epoch } = parsed;
+  if (typeof holderId !== "string" || typeof expiresAt !== "number" || !Number.isSafeInteger(expiresAt) || expiresAt < 0 || typeof epoch !== "number" || !Number.isSafeInteger(epoch) || epoch < 1)
+    return null;
+  return { holderId, expiresAt, epoch };
+}

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

@@ -0,0 +1,66 @@
+/**
+ * Deposition handling for `ownership: 'lease'` Step-2 fencing (issue #470).
+ *
+ * "Deposed" means another instance now holds the ownership lease at a strictly
+ * newer epoch, so this instance has lost the store. Deposition is detected at two
+ * sites and both funnel here:
+ *
+ * - A fenced durable write's CAS fails against a newer epoch
+ *   ({@link commitFencedEngineWrite} re-reads `lease:epoch` to disambiguate).
+ * - The lease manager's renewal reports `onLeaseLost('deposed')` (a successor
+ *   stole the holder out from under an otherwise-idle engine).
+ *
+ * The renewal-loss reason `'renewal-unconfirmable'` is deliberately NOT routed
+ * here: it is a transient storage blip (the holder could not prove it still
+ * holds), and halting a healthy holder on a momentary storage hiccup would be a
+ * self-inflicted outage. Only a confirmed `'deposed'` triggers the halt.
+ *
+ * {@link handleDeposition} is idempotent (guarded on {@link EngineInternals.deposed})
+ * and does the minimum synchronously — set the flag, warn the operator — then
+ * schedules engine teardown on a later tick. Teardown is never run inline:
+ * detection happens mid-commit while a workflow generator is advancing, and
+ * synchronous {@link disposeEngine} clears maps that the unwinding commit and
+ * other in-flight workflows still touch. The flag (plus the
+ * {@link commitFencedEngineWrite} top short-circuit) carries the halt guarantee;
+ * deferring the actual dispose by a tick is safe because every write in that
+ * window is still fenced on the now-stale epoch and loses its CAS.
+ *
+ * This module is allow-listed for import only from `src/core/engine/**`.
+ */
+import type { EngineInternals } from './internals.ts';
+/**
+ * The `name` of the `process` warning emitted when an engine configured with
+ * `ownership: 'lease'` can no longer be sure it owns the store. The same name
+ * covers all three signals, so a single `process.on('warning')` handler catches
+ * every "this engine may no longer own the store" event:
+ *
+ * - **deposed (confirmed)** — a renewal's CAS failed (a successor stole the lease),
+ *   or a fenced durable write was rejected because a newer epoch holds the store
+ *   (Step 2). The engine halts.
+ * - **renewal-unconfirmable (transient)** — a storage error left the holder unable
+ *   to prove it still holds within the lease window. This is NOT a confirmed
+ *   deposition; the engine keeps running, and a later renewal or fenced write
+ *   resolves the truth. The warning is informational so operators can investigate.
+ *
+ * Filter on this name to react to ownership-loss signals (alert, drain, restart).
+ *
+ * @example
+ * ```ts
+ * import { ENGINE_LEASE_LOST_WARNING_NAME } from '@lostgradient/weft';
+ *
+ * process.on('warning', (warning) => {
+ *   if (warning.name === ENGINE_LEASE_LOST_WARNING_NAME) {
+ *     // This engine may no longer own the store — investigate / drain / restart.
+ *   }
+ * });
+ * ```
+ */
+export declare const ENGINE_LEASE_LOST_WARNING_NAME = "WeftEngineLeaseLostWarning";
+/**
+ * React to a confirmed deposition. Idempotent: the first call sets the deposed
+ * flag, emits the operator warning, and schedules a deferred engine teardown;
+ * subsequent calls are no-ops. Returns immediately — the caller is expected to
+ * then throw {@link EngineDeposedError} to unwind the current commit so it does
+ * not advance in-memory state past a durable write that did not land.
+ */
+export declare function handleDeposition(internals: EngineInternals): void;

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

@@ -0,0 +1,10 @@
+export const ENGINE_LEASE_LOST_WARNING_NAME = "WeftEngineLeaseLostWarning";
+export function handleDeposition(internals) {
+  if (internals.deposed)
+    return;
+  internals.deposed = !0;
+  process.emitWarning("engine deposed: a durable write was fenced out because another instance now holds this store's ownership lease at a newer epoch. This engine is halting to avoid split-brain writes. Weft supports one engine process per store; ensure your deploy hands off cleanly (graceful shutdown releases the lease) and keep infrastructure-level single-instance enforcement in place.", ENGINE_LEASE_LOST_WARNING_NAME);
+  const tearDown = internals.tearDownAfterDeposition;
+  if (tearDown !== null)
+    Promise.resolve().then(tearDown).catch(() => {});
+}

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

@@ -0,0 +1,99 @@
+import { WeftError } from '../weft-error.ts';
+/**
+ * Thrown when `ownership: 'lease'` is configured and the engine cannot acquire the
+ * storage lease within the configured wait window — another live instance still
+ * holds it. Raised from the lease-acquire step, which runs both inside
+ * {@link Engine.create} and at the top of {@link Engine.recoverAll} (so a
+ * `new Engine({ ownership: 'lease' })` + `recoverAll()` boot must handle it too).
+ * In a rolling deploy this means the
+ * outgoing instance has not released the lease (or its lease has not yet expired)
+ * within `leaseWaitTimeout`; size that window above the outgoing instance's drain
+ * time and above the lease TTL so a crash (no clean release) still resolves once
+ * the held lease expires. Inspect `waitedMs` for how long this instance waited
+ * and `heldBy` for the holder id observed when it gave up (`null` if unknown).
+ *
+ * @example
+ * ```ts
+ * import { EngineLeaseAcquisitionTimeoutError } from '@lostgradient/weft';
+ *
+ * function isLeaseHandoffStuck(error: unknown): boolean {
+ *   return error instanceof EngineLeaseAcquisitionTimeoutError;
+ * }
+ * ```
+ */
+export declare class EngineLeaseAcquisitionTimeoutError extends WeftError<'EngineLeaseAcquisitionTimeoutError'> {
+    readonly waitedMs: number;
+    readonly heldBy: string | null;
+    constructor(waitedMs: number, heldBy: string | null);
+}
+/**
+ * Thrown when `ownership: 'lease'` is configured but the lease keys in storage are
+ * corrupt. Raised from the lease-acquire step, which runs both inside
+ * {@link Engine.create} and at the top of {@link Engine.recoverAll} (so a
+ * `new Engine({ ownership: 'lease' })` + `recoverAll()` boot must handle it too) —
+ * the `lease:epoch` high-water mark is present
+ * but does not decode to a valid epoch, or a holder record exists with no epoch
+ * key (which the lease protocol never produces, since `release()` deletes only the
+ * holder and never the epoch). The lease epoch is the sole source of truth for the
+ * monotonic fencing generation, so a booting instance fails closed rather than
+ * re-minting a generation at or below the true high-water mark and risking a
+ * split-brain. Resolve by operator repair: delete both `lease:` keys only if you
+ * are certain no other instance is running, or reset `lease:epoch` above its last
+ * known value.
+ *
+ * @example
+ * ```ts
+ * import { EngineLeaseCorruptedError } from '@lostgradient/weft';
+ *
+ * function isLeaseCorrupted(error: unknown): boolean {
+ *   return error instanceof EngineLeaseCorruptedError;
+ * }
+ * ```
+ */
+export declare class EngineLeaseCorruptedError extends WeftError<'EngineLeaseCorruptedError'> {
+    constructor(detail: string);
+}
+/**
+ * Thrown by {@link Engine.start} and {@link Engine.startOrSignal} when
+ * `ownership: 'lease'` is configured but the engine does not yet hold the lease —
+ * it was constructed with `new Engine({ ownership: 'lease' })` and used to start
+ * work before `recoverAll()` ran, or created with `recover: false`. In lease mode
+ * an engine must hold the single-writer lease (and have recovered existing runs)
+ * before it durably writes new workflow state, or a fresh start could race an
+ * instance that legitimately owns the store. {@link Engine.create} acquires the
+ * lease and recovers for you; a direct constructor must `await engine.recoverAll()`
+ * first.
+ *
+ * @example
+ * ```ts
+ * import { Engine, EngineLeaseNotHeldError } from '@lostgradient/weft';
+ *
+ * const engine = new Engine({ ownership: 'lease' });
+ * try {
+ *   await engine.start('ping', null);
+ * } catch (error) {
+ *   if (error instanceof EngineLeaseNotHeldError) {
+ *     await engine.recoverAll(); // acquires the lease, then retry the start
+ *   }
+ * }
+ * ```
+ */
+export declare class EngineLeaseNotHeldError extends WeftError<'EngineLeaseNotHeldError'> {
+    constructor();
+}
+/**
+ * Thrown internally on the durable-write path when `ownership: 'lease'` is
+ * configured and a fenced write's CAS fails because the held lease epoch is
+ * stale — a successor instance has taken the lease and bumped the epoch, so this
+ * instance has been deposed. It is the local unwind that stops the commit from
+ * advancing in-memory state past a durable write that did not land; the actual
+ * "this engine is deposed" reaction (set the `deposed` flag, warn the operator,
+ * tear the engine down) is driven by {@link handleDeposition} at the detection
+ * site, not by this error propagating — the inline strategy swallows turn
+ * rejections, so the throw never reaches a handler. Internal-only: it is never
+ * surfaced to user code (deposition reaches operators through the
+ * `WeftEngineLeaseLostWarning` process warning).
+ */
+export declare class EngineDeposedError extends WeftError<'EngineDeposedError'> {
+    constructor();
+}

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

@@ -0,0 +1,30 @@
+import { WeftError } from "../weft-error.js";
+
+export class EngineLeaseAcquisitionTimeoutError extends WeftError {
+  waitedMs;
+  heldBy;
+  constructor(waitedMs, heldBy) {
+    const heldClause = heldBy === null ? "" : ` (currently held by "${heldBy}")`;
+    super("EngineLeaseAcquisitionTimeoutError", `Could not acquire the storage ownership lease within ${waitedMs}ms${heldClause}. Another engine instance still holds it. Increase leaseWaitTimeout above the outgoing instance's drain time and the lease TTL, or ensure the previous instance releases the lease on shutdown.`);
+    this.waitedMs = waitedMs;
+    this.heldBy = heldBy;
+  }
+}
+
+export class EngineLeaseCorruptedError extends WeftError {
+  constructor(detail) {
+    super("EngineLeaseCorruptedError", `The ownership lease state in storage is corrupt and cannot be used safely: ${detail}. Resolve by operator repair (delete both "lease:" keys only if no other instance is running, or reset "lease:epoch" above its last known value).`);
+  }
+}
+
+export class EngineLeaseNotHeldError extends WeftError {
+  constructor() {
+    super("EngineLeaseNotHeldError", "ownership: 'lease' requires the engine to hold the lease before starting work. Use `Engine.create({ ownership: \"lease\" })` (which acquires the lease and recovers), or call `await engine.recoverAll()` on a directly-constructed engine before `start()`.");
+  }
+}
+
+export class EngineDeposedError extends WeftError {
+  constructor() {
+    super("EngineDeposedError", "Engine was deposed: a fenced durable write lost its CAS race because another instance now holds the ownership lease at a newer epoch. This engine is halting.");
+  }
+}

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

@@ -0,0 +1,114 @@
+/**
+ * Lease-fenced single-writer ownership over a shared durable store. This is the
+ * opt-in `Engine.create({ ownership: 'lease' })` mechanism — a CORRECTNESS-PATH
+ * coordinator, NOT a best-effort smoke alarm like the second-instance detector.
+ * Lease outcomes are acted on, never silently dropped, but the channel differs by
+ * phase: a failed acquire THROWS and blocks recovery (corruption fails closed, a
+ * timed-out handoff raises a typed error); a renewal reports loss through
+ * `onLeaseLost` rather than throwing — a CAS-failed renewal means a successor took
+ * the lease ('deposed'), and a transient renewal storage error is tolerated until
+ * the lease is too close to lapsing to prove ownership ('renewal-unconfirmable').
+ * In Step 1 that loss is observability only (the engine warns); Step 2 will make it
+ * enforceable by fencing every durable write on the lease epoch.
+ *
+ * **Why a lease.** Weft's supported model is one engine process per durable
+ * store. Without a lease, a rolling deploy briefly runs two engines (old draining
+ * + new booting), both recovering and both issuing at-least-once activities. The
+ * lease turns that into a clean handoff: the booting instance ACQUIRES the lease
+ * before recovering, the draining instance RELEASES it on dispose, and the new
+ * instance only recovers once it owns the lease.
+ *
+ * **Two-key schema (this is load-bearing, not an optimization).** Ownership is
+ * tracked by two keys, never one:
+ *
+ * - `lease:epoch` — an 8-byte big-endian uint64 fencing token. It changes ONLY on
+ *   ownership transfer (cold acquire, or a steal/re-acquire after the prior
+ *   holder's lease lapsed), NEVER on a renewal. It is a monotonic high-water mark
+ *   that SURVIVES release.
+ * - `lease:holder` — a JSON `{ holderId, expiresAt, epoch }` record renewed on
+ *   every heartbeat (its `expiresAt` advances), so its bytes churn constantly.
+ *
+ * They are split because `conditionalBatch` compares the WHOLE stored value as
+ * bytes. If the epoch lived inside the churning holder record, the fencing token
+ * (Step 2) would change on every renewal, spuriously failing the fence and
+ * self-terminating healthy holders. Keeping the epoch in its own stable key lets
+ * a holder cache its epoch once ({@link LeaseManager.currentEpochBytes}) and use
+ * it unchanged as a fencing condition across many renewals.
+ *
+ * **Epoch monotonicity is the anti-split-brain invariant.** Every transfer
+ * conditions on BOTH the holder AND the current epoch and bumps the epoch by one;
+ * `release()` deletes ONLY the holder and never the epoch. This guarantees a
+ * deposed zombie from generation N can never see its epoch re-minted under it —
+ * so once Step 2 fences durable writes on the epoch, the zombie always loses.
+ *
+ * @module core/engine/lease-manager
+ */
+import { type Storage } from '../../storage/interface.ts';
+/** Why a holder lost its lease — surfaced to {@link LeaseManagerOptions.onLeaseLost}. */
+export type LeaseLostReason = 'deposed' | 'renewal-unconfirmable';
+/** Options for {@link createLeaseManager}. */
+export type LeaseManagerOptions = {
+    storage: Storage;
+    /** This engine's unique instance id (the lease holder id). */
+    holderId: string;
+    /** Wall-clock source (ms), injected so tests can advance time deterministically. */
+    getNow: () => number;
+    /** Lease time-to-live (ms). A stolen lease becomes available `ttlMs` after its last renewal. */
+    ttlMs: number;
+    /** Renewal interval (ms). The holder re-asserts the lease this often; must be `< ttlMs`. */
+    renewIntervalMs: number;
+    /** Boot-time wait window (ms) before {@link LeaseManager.acquire} throws. */
+    waitTimeoutMs: number;
+    /** Poll interval (ms) for the acquire wait loop. */
+    acquirePollIntervalMs?: number;
+    /**
+     * Delay primitive for the acquire poll loop. Defaults to a real `setTimeout`.
+     * Injected so tests drive the loop deterministically: a test `delay` advances
+     * the same injected clock by the poll interval and resolves immediately, so the
+     * wait deadline (read from `getNow`) trips without real waiting. Mirrors the
+     * `getNow` injection — not test-only scaffolding.
+     */
+    delay?: (ms: number) => Promise<void>;
+    /**
+     * Called once when this holder loses the lease while running — either CAS-false
+     * on renewal (`'deposed'`: a successor stole it) or storage failures that make
+     * the holder unable to prove it still holds before the lease lapses
+     * (`'renewal-unconfirmable'`). In Step 1 the engine reacts by warning; Step 2
+     * uses this to halt fenced writes. The lease manager never throws into the
+     * renewal timer — it reports through this seam instead.
+     */
+    onLeaseLost?: (reason: LeaseLostReason) => void;
+};
+/**
+ * A running lease manager.
+ *
+ * - `acquire()` blocks until this instance owns the lease, then resolves; throws
+ *   {@link EngineLeaseAcquisitionTimeoutError} on timeout. Call before recovery.
+ *   One exception to "resolved ⇒ owned": if the manager was `stop()`ped (disposal)
+ *   while acquire was waiting, it resolves WITHOUT owning — the engine gates
+ *   recovery on `disposed` so a stopped-then-resolved acquire never proceeds.
+ * - `startRenewal()` begins the heartbeat that keeps the lease held (drives
+ *   {@link LeaseManager.renewOnce} on an interval).
+ * - `renewOnce()` runs a single renewal round; exposed for tests so renewal can be
+ *   driven deterministically with an injected clock, mirroring the detector's
+ *   `tick()`.
+ * - `currentEpochBytes()` returns the held epoch as bytes for Step-2 fencing
+ *   conditions; `null` before a successful acquire. Synchronous and stable across
+ *   renewals.
+ * - `release()` best-effort relinquishes the lease (holder key only) on dispose.
+ */
+export type LeaseManager = {
+    acquire(): Promise<void>;
+    startRenewal(): void;
+    renewOnce(): Promise<void>;
+    currentEpochBytes(): Uint8Array | null;
+    release(): Promise<void>;
+    stop(): void;
+};
+/**
+ * Create a lease manager. Does not start any timer or acquire anything itself —
+ * the engine drives `acquire()` at the boot gate (before recovery) and
+ * `startRenewal()` afterward, and clears the renewal timer through its own
+ * disposal path (mirroring how it owns the second-instance detector's interval).
+ */
+export declare function createLeaseManager(options: LeaseManagerOptions): LeaseManager;