@lostgradient/weft 0.20.0 → 0.21.0

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

@@ -128,7 +128,7 @@ export async function executeActivityOperationResult(internals, workflowId, oper
     if (executionOptions.reconciliationCompletion === "immediate-fenced") {
       const finishImmediateReconciliationCommit = executionOptions.beforeImmediateReconciliationCommit?.();
       try {
-        await commitActivityReconciliationTransitionWithFencedWrite(internals, reference, started, completedRecord);
+        await commitActivityReconciliationTransitionWithFencedWrite(internals, workflowId, reference, started, completedRecord);
       } finally {
         finishImmediateReconciliationCommit?.();
       }

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

@@ -2,13 +2,16 @@ import { KEYS, storageHas } from "../../storage/interface.js";
 import { deserializeCheckpoint } from "../checkpoint.js";
 import { encode } from "../codec.js";
 import { buildTimerBatchOperations, normalizeStorageTimestamp } from "../scheduler.js";
+import { notifyConditionWaiters, notifyConditionWaitersForTimerFire } from "./condition-waiters.js";
 import { commitFencedEngineWrite } from "./fenced-write.js";
 import { reprovideRecoveredServices } from "./lifecycle/recovered-services.js";
 import {
   acknowledgeSupersededSleepTimers,
   handleSleepTimerWithAcknowledgement,
-  resolveSleepTimer
+  resolveSleepTimer,
+  retainDiscardedDurableTimer
 } from "./sleep-timer-acknowledgements.js";
+import { commitWithWorkflowClaimFold, prepareWorkflowClaimFold } from "./workflow-claim-fold.js";
 import { buildWorkflowVisibilityIndexTransition } from "./workflow-indexes.js";
 export function createDelayedStartTimerEntry(_internals, workflowId, scheduledStartAt, options, callbacks) {
   return {
@@ -118,7 +121,10 @@ export async function startDelayedWorkflow(internals, entry, callbacks) {
         fireAt: executionDeadline,
         kind: "execution-deadline"
       }));
-    await commitFencedEngineWrite(internals, operations, [], () => Error(`Delayed-start transition for workflow "${entry.workflowId}" lost its CAS race.`));
+    const claimFold = await prepareWorkflowClaimFold(internals, entry.workflowId);
+    if (claimFold)
+      return (await commitWithWorkflowClaimFold(internals, claimFold, operations, [], "delayed-start workflow claim acquisition")).status === "committed" ? nextRunningState : null;
+    await commitFencedEngineWrite(internals, entry.workflowId, operations, [], () => Error(`Delayed-start transition for workflow "${entry.workflowId}" lost its CAS race.`));
     return nextRunningState;
   });
   if (!runningState)
@@ -158,7 +164,7 @@ async function failInvalidDelayedExecutionTimeout(entry, callbacks) {
   await callbacks.failWorkflow(entry.workflowId, Error(`Invalid delayed execution timeout for workflow "${entry.workflowId}"`));
 }
 export async function handleTimerFired(internals, entry, callbacks) {
-  if (entry.id.startsWith("review-escalation:") || entry.id.startsWith("review-timeout:")) {
+  if (isReviewTimerEntry(entry)) {
     await handleReviewTimer(internals, entry, callbacks);
     return;
   }
@@ -181,14 +187,22 @@ export async function handleTimerFired(internals, entry, callbacks) {
   if (entry.kind === "sleep")
     await handleSleepTimerWithAcknowledgement(internals, entry, callbacks.loadWorkflowState);
   else if (entry.kind === "wait-condition")
-    resolveConditionTimer(internals, entry);
+    if (internals.workflowClaimRegistry === null)
+      resolveConditionTimer(internals, entry);
+    else
+      await resolveConditionTimerConfirmingOwnership(internals, entry, callbacks.loadWorkflowState);
   else if (entry.kind === "execution-deadline")
     await callbacks.timeout(entry.workflowId);
 }
+function isReviewTimerEntry(entry) {
+  return entry.id.startsWith("review-escalation:") || entry.id.startsWith("review-timeout:");
+}
 function resolveConditionTimer(internals, entry) {
-  const resolver = internals.conditionWaiters.get(entry.workflowId);
-  if (resolver)
-    resolver();
+  notifyConditionWaiters(internals, entry.workflowId);
+}
+async function resolveConditionTimerConfirmingOwnership(internals, entry, loadWorkflowState) {
+  if (await notifyConditionWaitersForTimerFire(internals, entry.workflowId) === "discard")
+    await retainDiscardedDurableTimer(entry.id, entry.workflowId, loadWorkflowState);
 }
 async function handleReviewTimer(internals, entry, callbacks) {
   const reviewId = entry.id.split(":")[1];

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

@@ -0,0 +1,132 @@
+/**
+ * Owner-side signal polling, specified in
+ * [ADR 0002 § Entry point classification](../../../documentation/contributing/architecture-decisions/0002-multiengine-per-workflow-ownership.md)
+ * (the paragraph beginning "Signal delivery needs more than a
+ * classification").
+ *
+ * **The problem.** Weft has no cross-engine RPC. A signal sent to any engine
+ * is durably buffered — but under `ownership: 'workflow-lease'`, only the
+ * engine that owns a workflow inspects its in-memory waiters when a signal
+ * arrives. If the signal lands on a NON-owning engine, the durable buffer is
+ * written and nobody wakes the owner: a workflow parked on
+ * `waitForSignal()` (including a `waitForSignal` branch inside `ctx.race()`)
+ * hangs until something unrelated happens to drive it.
+ *
+ * **The fix.** The owning engine re-checks the durable signal buffer for its
+ * OWN parked workflows on the same cadence it renews their claims, and wakes
+ * any whose awaited signal has since been buffered — by any engine. This
+ * bounds cross-engine signal delivery latency at one renewal interval rather
+ * than leaving it unbounded. Owner-side polling is the accepted mechanism;
+ * real cross-engine notification would be a later latency optimization, not
+ * a correctness fix.
+ *
+ * **Scope and independence.** This module is the poll pass alone: given a
+ * list of this engine's parked signal waits, probe the durable buffer for
+ * each, and wake the ones that are ready. It does not read
+ * `src/core/engine/signals.ts` or `src/core/engine/inline-parking.ts`
+ * directly — the dependencies below are small structural types this module
+ * owns, so it stays independent of those modules' concrete shapes. Each
+ * type's doc comment names the existing function it satisfies. This module
+ * is also NOT a recurring task by itself (compare
+ * `workflow-claim-renewal-task.ts`) — it is production-wired by
+ * `ownership-bootstrap.ts`'s {@link buildOwnerSideSignalPollTarget}, which
+ * composes {@link OwnerSideSignalPollSources} (from `EngineInternals` and
+ * `inline-parking.ts`) into a real {@link OwnerSideSignalPollTarget}, and by
+ * `workflow-claim-renewal-task.ts`, which calls {@link runOwnerSideSignalPoll}
+ * against that target from the same lifecycle cadence that drives claim
+ * renewal.
+ *
+ * @module core/engine/owner-side-signal-poll
+ */
+/** One workflow parked on `waitForSignal(signalName)` (or a `ctx.race()` branch awaiting it), that this engine owns. */
+export type ParkedSignalWait = {
+    workflowId: string;
+    signalName: string;
+};
+/**
+ * The minimal structural shape this poll needs. Satisfied in production by
+ * `ownership-bootstrap.ts`'s `buildOwnerSideSignalPollTarget`, composed from
+ * `EngineInternals` and `signals.ts` / `inline-parking.ts` — without this
+ * module importing either.
+ */
+export type OwnerSideSignalPollTarget = {
+    /**
+     * Every signal wait this engine's currently-parked workflows are awaiting.
+     * 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 deriving from `EngineInternals.signalWaiters`
+     * (a `Map<string, () => void>` keyed by `` `${workflowId}:${signalName}` ``,
+     * the same format `src/core/engine/signals.ts`'s `deliverBufferedSignals`
+     * reads), splitting each key back into its `workflowId`/`signalName` pair.
+     */
+    listParkedSignalWaits(): readonly ParkedSignalWait[];
+    /**
+     * Probe whether `signalName` has already been durably buffered for
+     * `workflowId`, without consuming it — this poll only decides WHETHER to
+     * wake, never consumes the signal itself, so a losing `ctx.race()` branch
+     * is never silently dropped.
+     *
+     * Expected to be satisfied by `hasBufferedSignal` from
+     * `src/core/engine/signals.ts`.
+     */
+    hasBufferedSignal(workflowId: string, signalName: string): Promise<boolean>;
+    /**
+     * Wake `workflowId` so it re-evaluates its parked state and, ultimately,
+     * consumes the buffered signal and resumes its generator. Resolves once
+     * the wake attempt has been dispatched; rejects on failure, which this
+     * poll catches and records without stopping the remaining wakes in the
+     * pass.
+     *
+     * Expected to be satisfied by `resumeParkedInlineWorkflow` from
+     * `src/core/engine/inline-parking.ts` (already surfaced to callers today
+     * through `SignalCallbacks.resumeParkedInlineWorkflow` in `signals.ts`).
+     * The real implementation is expected to perform its own
+     * `wakeOwnershipCheck` immediately before driving the generator, per the
+     * ADR — that check is this poll's sibling module, not this poll's
+     * responsibility.
+     */
+    wakeWorkflow(workflowId: string): Promise<void>;
+};
+/** One parked signal wait's outcome within a single poll pass. */
+export type OwnerSideSignalPollOutcome = {
+    workflowId: string;
+    signalName: string;
+    status: 'woken';
+} | {
+    workflowId: string;
+    signalName: string;
+    status: 'not-buffered';
+} | {
+    workflowId: string;
+    signalName: string;
+    status: 'wake-failed';
+    error: unknown;
+};
+/** The result of one full owner-side signal poll pass ({@link runOwnerSideSignalPoll}). */
+export type OwnerSideSignalPollResult = {
+    /** `getNow()` read at the start of the pass, before any probe. */
+    startedAt: number;
+    /** `getNow()` read after every probe/wake has settled. */
+    finishedAt: number;
+    /** One entry per parked signal wait the pass attempted, in iteration order. */
+    outcomes: OwnerSideSignalPollOutcome[];
+    /** `outcomes.filter(o => o.status === 'woken').length`, precomputed for observability consumers. */
+    wokenCount: number;
+};
+/** Options for {@link runOwnerSideSignalPoll}. */
+export type OwnerSideSignalPollOptions = {
+    target: OwnerSideSignalPollTarget;
+    /** Wall-clock source (ms), injected so tests never depend on real time. */
+    getNow: () => number;
+};
+/**
+ * Run exactly one owner-side signal poll pass: snapshot this engine's
+ * currently-parked signal waits, probe the durable buffer for each, and wake
+ * the ones that are ready. A wake failure for one parked workflow is
+ * captured as a `'wake-failed'` outcome and never stops the remaining
+ * parked workflows in the same pass from being probed and, where ready,
+ * woken.
+ */
+export declare function runOwnerSideSignalPoll(options: OwnerSideSignalPollOptions): Promise<OwnerSideSignalPollResult>;

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

@@ -0,0 +1,22 @@
+export async function runOwnerSideSignalPoll(options) {
+  const { target, getNow } = options, startedAt = getNow(), parkedWaits = target.listParkedSignalWaits(), outcomes = [];
+  for (const { workflowId, signalName } of parkedWaits) {
+    if (!await target.hasBufferedSignal(workflowId, signalName)) {
+      outcomes.push({ workflowId, signalName, status: "not-buffered" });
+      continue;
+    }
+    try {
+      await target.wakeWorkflow(workflowId);
+      outcomes.push({ workflowId, signalName, status: "woken" });
+    } catch (error) {
+      outcomes.push({ workflowId, signalName, status: "wake-failed", error });
+    }
+  }
+  const finishedAt = getNow();
+  return {
+    startedAt,
+    finishedAt,
+    outcomes,
+    wokenCount: outcomes.filter((outcome) => outcome.status === "woken").length
+  };
+}

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>;