@lostgradient/weft 0.19.0 → 0.21.0

package/dist/core/engine/owner-side-update-poll.d.ts

@@ -0,0 +1,116 @@
+/**
+ * Owner-side coordinated-update polling (WFT-79), mirroring
+ * `owner-side-signal-poll.ts`'s mechanism and rationale.
+ *
+ * **The problem.** `updates.ts`'s `deliverCoordinatedUpdateToWaiterIfAvailable`
+ * discards a delivery attempt when this engine no longer holds the claim
+ * generation it parked the waiter under (`confirmWakeOwnership`), leaving the
+ * durable coordinated-update request in place for the true owner to deliver.
+ * But nothing DRIVES the true owner to look: `schedulePendingInlineUpdateDrain`
+ * only fires a `setTimeout(0)` drain on the engine that RECEIVED the
+ * `engine.update()`/`submitCoordinatedUpdate()` call, and the owning engine's
+ * maintenance task polls the durable signal buffer and child-result state,
+ * never pending coordinated updates. If the true owner is parked on
+ * `ctx.waitForUpdate()`, or simply has no reason to re-check because nothing
+ * else is advancing it, the caller's request sits durable and undelivered
+ * until something unrelated happens to drive that workflow.
+ *
+ * **The fix.** The owning engine re-checks its own held workflows' pending
+ * coordinated-update queues on the same cadence it renews their claims, and
+ * drains any workflow with at least one buffered request — by any engine.
+ * This bounds cross-engine update delivery latency at one renewal interval,
+ * the same bound ADR 0002 already gives cross-engine signal delivery.
+ *
+ * **Scope and independence.** This module is the poll pass alone: given this
+ * engine's held workflow ids, probe each for pending coordinated updates, and
+ * drain the ones that have any. It does not read `pending-updates.ts` or
+ * `updates.ts` directly — the dependencies below are small structural types
+ * this module owns, so it stays independent of those modules' concrete
+ * shapes. Draining is expected to be satisfied by composing
+ * `processPendingUpdatesForHandlers` (drains inline `ctx.onUpdate()`
+ * handlers) and `deliverCoordinatedUpdateToWaiterIfAvailable`-per-pending-
+ * update (drains `ctx.waitForUpdate()` waiters) — both already idempotent and
+ * fenced on this engine's own claim generation, so a poll racing a
+ * concurrent delivery (the normal `setTimeout(0)` drain, or another poll
+ * tick) is always safe to re-run. This module is also NOT a recurring task
+ * by itself (compare `workflow-claim-renewal-task.ts`) — it is production-
+ * wired by `ownership-bootstrap.ts`, which composes `EngineInternals` into a
+ * real {@link OwnerSideUpdatePollTarget}, and by
+ * `workflow-claim-renewal-task.ts`, which calls {@link runOwnerSideUpdatePoll}
+ * against that target from the same lifecycle cadence that drives claim
+ * renewal and signal polling.
+ *
+ * @module core/engine/owner-side-update-poll
+ */
+/**
+ * The minimal structural shape this poll needs. Satisfied in production by
+ * `ownership-bootstrap.ts`'s adapter, composed from `EngineInternals` —
+ * without this module importing it.
+ */
+export type OwnerSideUpdatePollTarget = {
+    /**
+     * Every workflow id this engine currently holds a live claim for, active or
+     * parked. Read fresh at the start of every pass — implementations may
+     * return a live or a defensive-copy array; this poll never mutates it and
+     * takes its own snapshot before iterating.
+     *
+     * Expected to be satisfied by `WorkflowClaimRegistry.listHeldWorkflowIds`,
+     * the same source `workflow-claim-renewal-task.ts`'s own renewal sub-pass
+     * uses.
+     */
+    listHeldWorkflowIds(): readonly string[];
+    /**
+     * Whether `workflowId` currently has at least one durably-buffered
+     * coordinated-update request, without consuming any of them.
+     *
+     * Expected to be satisfied by
+     * `internals.updateCoordinator.getPendingUpdates(workflowId).length > 0`.
+     */
+    hasPendingUpdates(workflowId: string): Promise<boolean>;
+    /**
+     * Drain every pending coordinated update currently buffered for
+     * `workflowId`: deliver to a registered `ctx.onUpdate()` handler, or to a
+     * parked `ctx.waitForUpdate()` waiter, whichever applies. Idempotent and
+     * self-fenced on this engine's own current claim generation — safe to call
+     * even when a concurrent drain (the normal post-request `setTimeout(0)`
+     * trigger, or another poll tick) is racing it.
+     */
+    drainPendingUpdates(workflowId: string): Promise<void>;
+};
+/** One held workflow's outcome within a single update-poll pass. */
+export type OwnerSideUpdatePollOutcome = {
+    workflowId: string;
+    status: 'drained';
+} | {
+    workflowId: string;
+    status: 'no-pending-updates';
+} | {
+    workflowId: string;
+    status: 'drain-failed';
+    error: unknown;
+};
+/** The result of one full owner-side update poll pass ({@link runOwnerSideUpdatePoll}). */
+export type OwnerSideUpdatePollResult = {
+    /** `getNow()` read at the start of the pass, before any probe. */
+    startedAt: number;
+    /** `getNow()` read after every probe/drain has settled. */
+    finishedAt: number;
+    /** One entry per held workflow id the pass attempted, in iteration order. */
+    outcomes: OwnerSideUpdatePollOutcome[];
+    /** `outcomes.filter(o => o.status === 'drained').length`, precomputed for observability consumers. */
+    drainedCount: number;
+};
+/** Options for {@link runOwnerSideUpdatePoll}. */
+export type OwnerSideUpdatePollOptions = {
+    target: OwnerSideUpdatePollTarget;
+    /** Wall-clock source (ms), injected so tests never depend on real time. */
+    getNow: () => number;
+};
+/**
+ * Run exactly one owner-side update poll pass: snapshot this engine's
+ * currently-held workflow ids, probe each for pending coordinated updates,
+ * and drain the ones that have any. A drain failure for one workflow is
+ * captured as a `'drain-failed'` outcome and never stops the remaining held
+ * workflows in the same pass from being probed and, where pending, drained.
+ */
+export declare function runOwnerSideUpdatePoll(options: OwnerSideUpdatePollOptions): Promise<OwnerSideUpdatePollResult>;

package/dist/core/engine/owner-side-update-poll.js

@@ -0,0 +1,22 @@
+export async function runOwnerSideUpdatePoll(options) {
+  const { target, getNow } = options, startedAt = getNow(), heldWorkflowIds = target.listHeldWorkflowIds(), outcomes = [];
+  for (const workflowId of heldWorkflowIds) {
+    if (!await target.hasPendingUpdates(workflowId)) {
+      outcomes.push({ workflowId, status: "no-pending-updates" });
+      continue;
+    }
+    try {
+      await target.drainPendingUpdates(workflowId);
+      outcomes.push({ workflowId, status: "drained" });
+    } catch (error) {
+      outcomes.push({ workflowId, status: "drain-failed", error });
+    }
+  }
+  const finishedAt = getNow();
+  return {
+    startedAt,
+    finishedAt,
+    outcomes,
+    drainedCount: outcomes.filter((outcome) => outcome.status === "drained").length
+  };
+}

package/dist/core/engine/ownership-bootstrap.d.ts

@@ -0,0 +1,280 @@
+/**
+ * Engine-level bootstrap for `ownership: 'workflow-lease'`
+ * ([ADR 0002](../../../documentation/contributing/architecture-decisions/0002-multiengine-per-workflow-ownership.md)):
+ * runs the two construction-time capability gates ({@link bootstrapOwnershipGates})
+ * and, once they pass, constructs this engine's {@link WorkflowClaimRegistry}
+ * and its claim-renewal task. Standalone from `Engine`/`EngineInternals` so the
+ * idempotency, disposal-race, and background-task-mode wiring in
+ * `src/core/engine/index.ts` stay thin call sites over one tested unit.
+ *
+ * **Both fencing modes run the gates.** This module builds the
+ * `workflow-lease` machinery, but `Engine`'s ownership bootstrap also runs
+ * Gate 1 and Gate 2 for `ownership: 'lease'` before it acquires the global
+ * lease, so the store-wide mode marker rejects a mismatched pairing in either
+ * direction. `'lease'` acquisition, fencing, health, and disposal are
+ * otherwise unchanged.
+ *
+ * **The renewal task's reclaim scan is fully wired here**, via
+ * {@link createWorkflowClaimReclaimTarget}: candidate discovery
+ * (`workflow-claim-reclaim-scan.ts`, including its ownerless-but-running
+ * scan — ADR 0002 § "Reclaiming stranded claims") plus a bounded-retry
+ * `registry.takeover`/`registry.acquire` loop, per the ADR's "bounded at 5
+ * attempts" row. A reclaimed or freshly-acquired claim's `onReclaimed` drive
+ * is retried on every later pass if it throws — see
+ * {@link createWorkflowClaimReclaimTarget}'s doc for why release-on-failure
+ * is unsafe here.
+ *
+ * **Owner-side signal polling is composed here from small structural
+ * sources** ({@link buildOwnerSideSignalPollTarget}) rather than built
+ * against `EngineInternals` directly — this module stays independent of
+ * that module's concrete shape, matching `owner-side-signal-poll.ts`'s own
+ * decoupling discipline. `src/core/engine/index.ts` is the only expected
+ * caller: it already has `EngineInternals` in scope and supplies
+ * {@link OwnerSideSignalPollSources} as one-line closures over
+ * `getInternals(this)`, then passes the composed target through
+ * {@link WorkflowLeaseOwnershipBootstrapOptions.signalPollTarget}.
+ *
+ * @module core/engine/ownership-bootstrap
+ */
+import type { Storage } from '../../storage/interface.ts';
+import type { OwnerSideSignalPollTarget } from './owner-side-signal-poll.ts';
+import type { OwnerSideUpdatePollTarget } from './owner-side-update-poll.ts';
+import { WorkflowClaimMetricsCollector } from './workflow-claim-metrics.ts';
+import { WorkflowClaimRegistry } from './workflow-claim-registry.ts';
+import type { WorkflowClaimRenewalTarget } from './workflow-claim-renewal-subpasses.ts';
+import { type WorkflowClaimRenewalTask } from './workflow-claim-renewal-task.ts';
+export { createWorkflowClaimReclaimTarget, WORKFLOW_CLAIM_TAKEOVER_MAX_ATTEMPTS, type WorkflowClaimReclaimTargetHandle, } from './workflow-claim-reclaim-target.ts';
+/** Input to {@link bootstrapWorkflowLeaseOwnership}. */
+export type WorkflowLeaseOwnershipBootstrapOptions = {
+    storage: Storage;
+    /** Engine-clock source (ms), injected so tests can drive it deterministically. */
+    getNow: () => number;
+    /** Resolved `workflowClaimTtl` (ms). */
+    claimTtlMs: number;
+    /** Resolved `workflowClaimRenewInterval` (ms). */
+    claimRenewIntervalMs: number;
+    /**
+     * Optional owner-side signal-poll target, built by a caller with access to
+     * `EngineInternals`/`inline-parking.ts` — typically
+     * {@link buildOwnerSideSignalPollTarget} composed from
+     * {@link OwnerSideSignalPollSources}. See the module doc's signal-poll
+     * paragraph. Omitted leaves `result.signalPoll` `undefined` on every pass.
+     */
+    signalPollTarget?: OwnerSideSignalPollTarget;
+    /**
+     * Optional owner-side update-poll target (WFT-79), built by a caller with
+     * access to `EngineInternals` — typically `index.ts`'s
+     * `#buildOwnerSideUpdatePollTarget`. Omitted leaves `result.updatePoll`
+     * `undefined` on every pass. See `owner-side-update-poll.ts`'s module doc
+     * for why the owning engine must re-check its own held workflows' pending
+     * coordinated-update queues rather than relying solely on the
+     * `setTimeout(0)` drain the receiving engine fires.
+     */
+    updatePollTarget?: OwnerSideUpdatePollTarget;
+    /**
+     * Invoked after this engine reclaims a stranded claim, to actually drive the
+     * workflow. Taking the claim only moves durable ownership keys; without this
+     * the reclaimed workflow makes no progress while this engine's renewal keeps
+     * its claim alive, shielding it from any engine that would have resumed it.
+     */
+    onWorkflowClaimReclaimed?: (workflowId: string) => Promise<void>;
+    /**
+     * Optional workflow-type eligibility check, forwarded to
+     * {@link createWorkflowClaimReclaimTarget}'s `isTypeRegistered` parameter.
+     * Omitted skips the check, matching that function's own default. See its
+     * doc for why an engine that cannot execute a candidate's registered type
+     * must never win its claim in the first place.
+     */
+    isWorkflowTypeRegistered?: (workflowType: string) => boolean;
+};
+/**
+ * Everything `Engine` needs to hold on `EngineInternals` once bootstrap
+ * succeeds. `metrics` is the concrete {@link WorkflowClaimMetricsCollector} —
+ * not just the structural `WorkflowClaimMetricsRecorder` interface it also
+ * satisfies — so a caller (tests, a later Prometheus-exporter bridge) can read
+ * `snapshot()` directly instead of needing a second recorder reference.
+ */
+export type WorkflowLeaseOwnershipBootstrapResult = {
+    registry: WorkflowClaimRegistry;
+    renewalTask: WorkflowClaimRenewalTask;
+    metrics: WorkflowClaimMetricsCollector;
+};
+/**
+ * Structural sources {@link buildOwnerSideSignalPollTarget} composes into a
+ * real {@link OwnerSideSignalPollTarget} (ADR 0002 § "Signal delivery needs
+ * more than a classification"). Defined as small closures rather than
+ * accepting `EngineInternals` directly — see this module's doc comment.
+ * `src/core/engine/index.ts` is the only expected caller.
+ *
+ * A parked `waitForSignal()` lands in one of two disjoint in-memory
+ * populations, and both need owner-side polling to survive a signal
+ * delivered on a non-owning engine:
+ *
+ * - **Checkpoint-parked** (`listParkedInlineWorkflowIds`/`parkedSignalName`):
+ *   a top-level `waitForSignal()` with no live `ctx.onQuery`/update handler
+ *   is evicted from memory (`inline-parking.ts`'s `parkInlineWorkflowAfterCheckpoint`)
+ *   and tracked only as `EngineInternals.parkedInlineWorkflows` plus the
+ *   checkpointed operation itself — recovered here via
+ *   `EngineInternals.pendingTimelineEntries`, which every checkpoint commit
+ *   sets to the just-persisted operation's timeline summary
+ *   (`checkpoint-io.ts`) and only clears once that operation is finalized.
+ *   For a still-parked `wait-signal` entry, `operationLabel` IS the awaited
+ *   signal name (`state-utilities.ts`'s `getTimelineOperationLabel`).
+ * - **Live in-memory waiters** (`listSignalWaiterEntries`): a `ctx.race`/
+ *   `ctx.all` wait-signal branch, or a top-level `waitForSignal()` on a
+ *   workflow WITH live query/update handlers, registers into
+ *   `EngineInternals.signalWaiters`/`signalWaitersByWorkflow` instead
+ *   (`operations-coordination.ts`, `coordination-branch-executors.ts`) — the
+ *   generator's turn stays alive, blocked on an unresolved in-process
+ *   promise, rather than being evicted.
+ */
+export type OwnerSideSignalPollSources = {
+    /** `EngineInternals.parkedInlineWorkflows` — this engine's checkpoint-parked (memory-evicted) workflow ids. */
+    listParkedInlineWorkflowIds(): Iterable<string>;
+    /** Whether `workflowId` is currently checkpoint-parked. */
+    isParkedInlineWorkflow(workflowId: string): boolean;
+    /**
+     * The signal name a checkpoint-parked workflow is currently awaiting —
+     * `undefined` when `workflowId` is not parked on a `wait-signal`
+     * operation. See this type's doc comment for the `pendingTimelineEntries`
+     * source.
+     */
+    parkedSignalName(workflowId: string): string | undefined;
+    /**
+     * Every `[workflowId, waiterKey]` pair from
+     * `EngineInternals.signalWaitersByWorkflow`. `waiterKey` is always
+     * `` `${workflowId}:${signalName}` ``.
+     */
+    listSignalWaiterEntries(): Iterable<readonly [workflowId: string, waiterKey: string]>;
+    /** `signals.ts`'s `hasBufferedSignal`. */
+    hasBufferedSignal(workflowId: string, signalName: string): Promise<boolean>;
+    /** `inline-parking.ts`'s `resumeParkedInlineWorkflow`, bound to this engine. */
+    resumeParkedInlineWorkflow(workflowId: string): Promise<void>;
+    /**
+     * Wake exactly the in-memory signal waiter registered under `waiterKey` —
+     * mirrors `signals.ts`'s (unexported) `deliverBufferedSignals` waiter
+     * branch: release the waiter via the exported `releaseSignalWaiter`, then
+     * invoke it. A no-op when no waiter is currently registered under that
+     * exact key (already consumed by something else since discovery).
+     */
+    wakeSignalWaiter(workflowId: string, waiterKey: string): void;
+    /**
+     * Optional pre-wake ownership confirmation for the LIVE in-memory waiter
+     * branch only (WFT-79 Finding 1). Mirrors `wake-ownership-guard.ts`'s
+     * `confirmWakeOwnership` three-way decision tree: `'discard'` means this
+     * engine no longer holds the claim generation it registered the waiter
+     * under, so `wakeSignalWaiter` must NOT be called — doing so would let a
+     * signal buffered for a `ctx.race()`/`ctx.all()` branch wake a generator
+     * this engine has since been deposed from, driving it concurrently with
+     * whichever engine now legitimately owns the workflow (the exact
+     * duplicate-execution hazard ADR 0002 exists to close). `'proceed'` (or
+     * this source being omitted entirely) preserves the pre-guard behavior:
+     * every confirmed-buffered live waiter is woken unconditionally.
+     *
+     * **Not called for the checkpoint-parked branch above.** A checkpoint-parked
+     * resume goes through `resumeParkedInlineWorkflow` →
+     * `resumeWorkflowFromStorage`'s `acquireStandaloneClaimBeforeResume`, which
+     * re-confirms this engine's cached claim generation against the durable
+     * holder (via `wakeOwnershipCheck`) before resuming, and throws
+     * `WorkflowClaimUnavailableError` rather than replaying against a stale
+     * generation when that check fails — guarding it here too would be
+     * redundant, not unsafe, but the finding is scoped to the live-waiter
+     * release this module makes directly.
+     *
+     * **Required, deliberately.** This module cannot call `confirmWakeOwnership`
+     * directly: that helper takes `EngineInternals`, and this module stays
+     * independent of that concrete shape (see this module's doc comment) so it
+     * never couples to `src/core/engine/index.ts`'s internals layout. The caller
+     * therefore supplies it — `src/core/engine/index.ts` passes
+     * `(workflowId) => confirmWakeOwnership(internals, workflowId, 'signal')`.
+     *
+     * It is NOT optional, because an optional fence is one that silently does
+     * nothing when a call site forgets it — which is exactly how the owner-side
+     * signal poll shipped unwired in the first place. Making it required turns a
+     * missing fence into a compile error rather than a duplicate-execution bug
+     * that only a reviewer can catch. A caller that genuinely needs no fence
+     * (`ownership: 'none'`/`'lease'`) still passes one; `confirmWakeOwnership`
+     * returns `'proceed'` when no claim registry is installed.
+     */
+    confirmSignalWakeOwnership(workflowId: string): Promise<'proceed' | 'discard'>;
+};
+/**
+ * Compose {@link OwnerSideSignalPollSources} into a real
+ * {@link OwnerSideSignalPollTarget}.
+ *
+ * `wakeWorkflow` re-confirms `hasBufferedSignal` for each live waiter key it
+ * owns before firing it, rather than trusting the outer poll's per-entry
+ * probe: `runOwnerSideSignalPoll` calls `wakeWorkflow(workflowId)` with no
+ * `signalName` (`owner-side-signal-poll.ts`'s fixed contract), and one
+ * workflow can have multiple live waiter keys at once (distinct `ctx.race`
+ * branches waiting on different signals). Firing all of them because ONE was
+ * confirmed buffered would spuriously "win" a branch whose signal never
+ * arrived — `coordination-branch-executors.ts`'s race branch resolves
+ * unconditionally once its waiter fires, with no re-check.
+ */
+export declare function buildOwnerSideSignalPollTarget(sources: OwnerSideSignalPollSources): OwnerSideSignalPollTarget;
+/**
+ * Adapt a {@link WorkflowClaimRegistry} to the renewal task's
+ * {@link WorkflowClaimRenewalTarget} contract. `registry.renew()`'s
+ * discriminated result never throws on a lost CAS — background scanning must
+ * isolate a per-workflow failure and continue, so every `WorkflowClaimRegistry`
+ * method returns a result instead of throwing. This adapter is where that gets
+ * converted to the renewal task's reject-on-failure contract, without adding a
+ * throwing method to the registry itself, so the registry's "none throw"
+ * contract stays intact for every other caller.
+ *
+ * `'renewed'` resolves. `'not-held'` also resolves rather than rejects: it is
+ * the benign race against this engine's own `release()` (the registry stops
+ * new renewals for a workflow before it reads the bytes `release()` conditions
+ * on — see `workflow-claim-registry.ts`'s module doc), not a lost claim, and
+ * counting it as a renewal failure would inflate
+ * `weft_workflow_claim_renewal_failures_total` on ordinary terminal shutdown.
+ * Only `'lost'` rejects. The registry's own `renew()` already emits
+ * `WeftWorkflowClaimLostWarning` on a `'lost'` result, so this adapter does not
+ * double-emit.
+ *
+ * Exported (only) so its three-branch mapping can be pinned directly against a
+ * canned `WorkflowClaimRenewResult`, without needing a storage-timing race to
+ * reach `'not-held'` through a real registry.
+ */
+export declare function createWorkflowClaimRenewalTarget(registry: WorkflowClaimRegistry, metrics?: WorkflowClaimMetricsCollector): WorkflowClaimRenewalTarget;
+/**
+ * Run Gate 1 + Gate 2 for `ownership: 'workflow-lease'`, then construct this
+ * engine's {@link WorkflowClaimRegistry} and claim-renewal task. Does not
+ * start the renewal task's interval — the caller decides interval-mode vs.
+ * `runMaintenance()`-driven mode, since only it knows `backgroundTaskMode`.
+ * Throws whatever {@link bootstrapOwnershipGates} throws (a bare `Error` for
+ * Gate 1, `OwnershipModeMismatchError` for Gate 2) before constructing
+ * anything durable-adjacent — a failed gate leaves no registry, no renewal
+ * task, and no metrics recorder behind.
+ *
+ * The renewal task's `onPassComplete` seam bridges every pass into the
+ * returned {@link WorkflowClaimMetricsRecorder}: each `'failed'` renewal
+ * outcome records one `weft_workflow_claim_renewal_failures_total`, and the
+ * registry's own currently-held-id count (read fresh after the pass, since a
+ * failed renewal can drop a claim mid-pass) sets `weft_workflow_claims_active`.
+ *
+ * **`renewalTask.stop()` also quiesces the reclaim target (WFT-79 Finding 2).**
+ * `createWorkflowClaimRenewalTask`'s own `stop()` only clears the interval —
+ * a reclaim pass already in flight (started by the last tick before `stop()`)
+ * still runs to completion, per that module's own doc. Left alone, a
+ * disposal that races an in-flight interval-driven pass could let the
+ * {@link createWorkflowClaimReclaimTarget reclaim target} land a fresh
+ * takeover/acquire CAS, or drive a freshly reclaimed workflow's `onReclaimed`
+ * against a host that is mid-teardown, AFTER `Engine`'s disposal path has
+ * already snapshotted the registry for `WorkflowClaimRegistry.releaseAll()`.
+ * The `renewalTask` this function returns wraps the raw task's `stop` so it
+ * synchronously calls {@link WorkflowClaimReclaimTargetHandle.markDisposing}
+ * first: since JS has no preemption, that flag flip happens strictly before
+ * any other code runs, so every reclaim-target checkpoint after an `await`
+ * (including one a suspended continuation resumes into after `stop()` was
+ * called) observes it. A checkpoint that finds itself disposing self-releases
+ * any claim it just landed rather than driving it — see that module's doc —
+ * so the hazard closes without `Engine`'s disposal path (`index.ts`, out of
+ * this module's scope) needing to await anything new. This wrapping makes
+ * `stop()` permanent: a later `start()` on the returned task still clears
+ * `disposing` for renewal-interval purposes, but the reclaim target itself
+ * never un-disposes. That is intentional — `index.ts` never restarts a
+ * renewal task after detaching it — and is pinned by a test.
+ */
+export declare function bootstrapWorkflowLeaseOwnership(options: WorkflowLeaseOwnershipBootstrapOptions): Promise<WorkflowLeaseOwnershipBootstrapResult>;

package/dist/core/engine/ownership-bootstrap.js

@@ -0,0 +1,89 @@
+import { bootstrapOwnershipGates } from "./ownership-mode-marker.js";
+import { WorkflowClaimMetricsCollector } from "./workflow-claim-metrics.js";
+import { createWorkflowClaimReclaimTarget } from "./workflow-claim-reclaim-target.js";
+import { WorkflowClaimRegistry } from "./workflow-claim-registry.js";
+import {
+  createWorkflowClaimRenewalTask
+} from "./workflow-claim-renewal-task.js";
+export {
+  createWorkflowClaimReclaimTarget,
+  WORKFLOW_CLAIM_TAKEOVER_MAX_ATTEMPTS
+} from "./workflow-claim-reclaim-target.js";
+export function buildOwnerSideSignalPollTarget(sources) {
+  return {
+    listParkedSignalWaits() {
+      const waits = [];
+      for (const workflowId of sources.listParkedInlineWorkflowIds()) {
+        const signalName = sources.parkedSignalName(workflowId);
+        if (signalName !== void 0)
+          waits.push({ workflowId, signalName });
+      }
+      for (const [workflowId, waiterKey] of sources.listSignalWaiterEntries())
+        waits.push({ workflowId, signalName: waiterKey.slice(workflowId.length + 1) });
+      return waits;
+    },
+    hasBufferedSignal: (workflowId, signalName) => sources.hasBufferedSignal(workflowId, signalName),
+    async wakeWorkflow(workflowId) {
+      if (sources.isParkedInlineWorkflow(workflowId)) {
+        await sources.resumeParkedInlineWorkflow(workflowId);
+        return;
+      }
+      for (const [waiterWorkflowId, waiterKey] of sources.listSignalWaiterEntries()) {
+        if (waiterWorkflowId !== workflowId)
+          continue;
+        const signalName = waiterKey.slice(workflowId.length + 1);
+        if (await sources.hasBufferedSignal(workflowId, signalName)) {
+          if (await sources.confirmSignalWakeOwnership(workflowId) === "discard")
+            continue;
+          sources.wakeSignalWaiter(workflowId, waiterKey);
+        }
+      }
+    }
+  };
+}
+export function createWorkflowClaimRenewalTarget(registry, metrics) {
+  return {
+    listHeldWorkflowIds: () => registry.listHeldWorkflowIds(),
+    async renewWorkflowClaim(workflowId) {
+      if ((await registry.renew(workflowId)).status === "lost") {
+        metrics?.recordClaimAttempt("deposed");
+        throw Error(`workflow "${workflowId}" lost its ownership claim during renewal`);
+      }
+    }
+  };
+}
+export async function bootstrapWorkflowLeaseOwnership(options) {
+  await bootstrapOwnershipGates({
+    storage: options.storage,
+    ownershipMode: "workflow-lease",
+    getNow: options.getNow
+  });
+  const registry = new WorkflowClaimRegistry({
+    storage: options.storage,
+    engineId: crypto.randomUUID(),
+    getNow: options.getNow,
+    claimTtlMs: options.claimTtlMs,
+    claimRenewIntervalMs: options.claimRenewIntervalMs
+  }), metrics = new WorkflowClaimMetricsCollector, reclaimTarget = createWorkflowClaimReclaimTarget(registry, options.storage, metrics, options.onWorkflowClaimReclaimed, options.isWorkflowTypeRegistered), rawRenewalTask = createWorkflowClaimRenewalTask({
+    target: createWorkflowClaimRenewalTarget(registry, metrics),
+    reclaimTarget,
+    ...options.signalPollTarget === void 0 ? {} : { signalPollTarget: options.signalPollTarget },
+    ...options.updatePollTarget === void 0 ? {} : { updatePollTarget: options.updatePollTarget },
+    getNow: options.getNow,
+    intervalMs: options.claimRenewIntervalMs,
+    onPassComplete: (result) => {
+      for (const outcome of result.outcomes)
+        if (outcome.status === "failed")
+          metrics.recordClaimRenewalFailure();
+      metrics.setActiveClaims(registry.listHeldWorkflowIds().length);
+    }
+  });
+  return { registry, renewalTask: {
+    runOnce: () => rawRenewalTask.runOnce(),
+    start: () => rawRenewalTask.start(),
+    stop: () => {
+      reclaimTarget.markDisposing();
+      rawRenewalTask.stop();
+    }
+  }, metrics };
+}

package/dist/core/engine/ownership-mode-marker.d.ts

@@ -0,0 +1,82 @@
+/**
+ * The two construction-time capability gates described in
+ * [ADR 0002 § Construction-time capability gates](../../../documentation/contributing/architecture-decisions/0002-multiengine-per-workflow-ownership.md#construction-time-capability-gates):
+ *
+ * - **Gate 1 — storage capability.** Fails fast when the configured storage
+ *   backend does not support `conditionalBatch`, naming the *configured*
+ *   fencing mode in the diagnostic rather than a hardcoded one, so an operator
+ *   troubleshooting the shipped `ownership: 'lease'` is not sent chasing
+ *   `workflow-lease`, which is unimplemented until a later stage.
+ * - **Gate 2 — ownership-mode marker.** Stamps or verifies the store-wide
+ *   `ownership-mode-marker` singleton so `ownership: 'lease'` and
+ *   `ownership: 'workflow-lease'` remain mutually exclusive across engine
+ *   *processes*, not merely within one process.
+ *
+ * Both gates fire only for the two fencing modes (`'lease'` and
+ * `'workflow-lease'`); `ownership: 'none'` never touches the marker or checks
+ * the capability. {@link bootstrapOwnershipGates} runs them in the ADR's
+ * required order (Gate 1 then Gate 2) and is the unit later wired in front of
+ * claim acquisition, recovery scanning, scheduler polling, and task polling —
+ * that wiring is a later stage and is deliberately not done here.
+ *
+ * @module core/engine/ownership-mode-marker
+ */
+import { type Storage } from '../../storage/interface.ts';
+import { type FencingOwnershipMode } from './workflow-claim-codec.ts';
+/**
+ * Mirrors the full `ownership` discriminant (`EngineConstructorOptions.ownership`
+ * / `ResolvedOptions.ownershipMode`). Duplicated here as a literal union rather
+ * than imported, because neither call site exports a standalone name for it —
+ * importing `ResolvedOptions` would pull in the whole engine-internal-types
+ * surface for one field's type.
+ */
+export type EngineOwnershipMode = 'none' | 'lease' | 'workflow-lease';
+/**
+ * Gate 1 — storage capability. Fires for `ownership: 'lease'` or
+ * `ownership: 'workflow-lease'`; reuses the existing, untyped `Error` that
+ * {@link requireStorageCapability} already throws. The diagnostic names the
+ * mode that is actually configured — hardcoding `'workflow-lease'` into the
+ * message would misdirect an operator troubleshooting the shipped global
+ * lease toward an unimplemented feature.
+ */
+export declare function assertOwnershipStorageCapability(storage: Storage, configuredMode: FencingOwnershipMode): void;
+/** Input to {@link assertOwnershipModeMarker}. */
+export type AssertOwnershipModeMarkerInput = {
+    storage: Storage;
+    /** This engine's configured fencing mode. */
+    configuredMode: FencingOwnershipMode;
+    /** Engine-clock source (ms), injected so tests can control `establishedAt` deterministically. */
+    getNow: () => number;
+};
+/**
+ * Gate 2 — ownership-mode marker. Fires immediately after Gate 1 passes, for
+ * the same trigger (`ownership: 'lease'` or `ownership: 'workflow-lease'`;
+ * `ownership: 'none'` never calls this).
+ *
+ * Reads `KEYS.ownershipModeMarker()`. If absent, `conditionalBatch`-puts
+ * `{ mode: configuredMode, establishedAt: now() }` with an expected value of
+ * `null` — the first fencing-mode engine against a fresh store establishes
+ * the mode every later one must agree with. On a CAS loss (another engine won
+ * the race to stamp it), re-reads and compares against that engine's mode
+ * instead, since it is now authoritative. If the stored mode — from either
+ * the initial read or the post-CAS-loss re-read — differs from this engine's
+ * configured mode, throws {@link OwnershipModeMismatchError} before any
+ * further construction proceeds.
+ */
+export declare function assertOwnershipModeMarker(input: AssertOwnershipModeMarkerInput): Promise<void>;
+/** Input to {@link bootstrapOwnershipGates}. */
+export type BootstrapOwnershipGatesInput = {
+    storage: Storage;
+    ownershipMode: EngineOwnershipMode;
+    /** Engine-clock source (ms), injected so tests can control `establishedAt` deterministically. */
+    getNow: () => number;
+};
+/**
+ * Run Gate 1 then Gate 2, in that order, as ADR 0002 requires. No-op for
+ * `ownership: 'none'`, which never touches storage-capability enforcement or
+ * the mode marker. Both gates must complete successfully before any claim
+ * acquisition, recovery scan, scheduler poll, or task poll proceeds — but
+ * wiring this into `Engine` construction or any of those call sites is a
+ * later stage; this function is the standalone, testable unit only.
+ */
+export declare function bootstrapOwnershipGates(input: BootstrapOwnershipGatesInput): Promise<void>;

package/dist/core/engine/ownership-mode-marker.js

@@ -0,0 +1,52 @@
+import {
+  KEYS,
+  requireStorageCapability,
+  storageConditionalBatch
+} from "../../storage/interface.js";
+import { OwnershipModeMismatchError } from "./lease-errors.js";
+import {
+  decodeOwnershipModeMarker,
+  encodeOwnershipModeMarker
+} from "./workflow-claim-codec.js";
+export function assertOwnershipStorageCapability(storage, configuredMode) {
+  requireStorageCapability(storage, "conditionalBatch", `ownership: '${configuredMode}'`);
+}
+async function readOwnershipModeMarkerOrThrowIfCorrupt(storage, markerKey) {
+  const bytes = await storage.get(markerKey);
+  if (bytes === null)
+    return null;
+  const decoded = decodeOwnershipModeMarker(bytes);
+  if (decoded === null)
+    throw Error(`The store's ownership-mode-marker ("${markerKey}") exists but does not decode as a valid { mode, establishedAt } record. Treating an undecodable marker as absent would let this engine silently overwrite whatever mode the store's real prior engines agreed on, defeating the marker's purpose of making a mixed fencing-mode deployment detectable. Resolve by operator repair: inspect the stored bytes and, only if certain no other engine relies on them, delete the key so a fresh marker can be established.`);
+  return decoded;
+}
+function assertOwnershipModeMatches(configuredMode, storedRecord) {
+  if (storedRecord.mode !== configuredMode)
+    throw new OwnershipModeMismatchError(configuredMode, storedRecord.mode, storedRecord.establishedAt);
+}
+export async function assertOwnershipModeMarker(input) {
+  const { storage, configuredMode, getNow } = input, markerKey = KEYS.ownershipModeMarker(), initial = await readOwnershipModeMarkerOrThrowIfCorrupt(storage, markerKey);
+  if (initial !== null) {
+    assertOwnershipModeMatches(configuredMode, initial);
+    return;
+  }
+  if (await storageConditionalBatch(storage, [{ key: markerKey, expectedValue: null }], [
+    {
+      type: "put",
+      key: markerKey,
+      value: encodeOwnershipModeMarker({ mode: configuredMode, establishedAt: getNow() })
+    }
+  ]))
+    return;
+  const reread = await readOwnershipModeMarkerOrThrowIfCorrupt(storage, markerKey);
+  if (reread === null)
+    throw Error(`Lost the compare-and-swap while establishing the store's ownership-mode-marker ("${markerKey}"), and a re-read then found it absent again. This indicates the marker was deleted concurrently during construction rather than raced by another engine's write (which would have left it present). Retry construction once the concurrent deletion has settled.`);
+  assertOwnershipModeMatches(configuredMode, reread);
+}
+export async function bootstrapOwnershipGates(input) {
+  const { storage, ownershipMode, getNow } = input;
+  if (ownershipMode === "none")
+    return;
+  assertOwnershipStorageCapability(storage, ownershipMode);
+  await assertOwnershipModeMarker({ storage, configuredMode: ownershipMode, getNow });
+}