@lostgradient/weft 0.20.0 → 0.21.0

package/dist/core/engine/workflow-claim-renewal-subpasses.d.ts

@@ -0,0 +1,265 @@
+/**
+ * The three individual sub-pass implementations `workflow-claim-renewal-task.ts`
+ * composes into its combined `runOnce()` pass and, in interval mode, its two
+ * independently single-flight-guarded tick passes (see that module's
+ * "Renewal cadence is independent of the reclaim scan and signal poll in
+ * interval mode" doc section, WFT-79 Finding 2). Split into its own module so
+ * `workflow-claim-renewal-task.ts` stays under the repository's
+ * implementation-file-size ceiling; these are pure, target-driven functions
+ * with no dependency on the renewal task's own scheduling/single-flight
+ * state.
+ *
+ * Also home to every structural target/result type these sub-passes and
+ * `workflow-claim-renewal-task.ts` share, for the same reason —
+ * `ownership-bootstrap.ts` imports several of these types directly from
+ * `workflow-claim-renewal-task.ts` (not from here), so that module re-exports
+ * them; this module is the one place they are actually defined.
+ *
+ * @module core/engine/workflow-claim-renewal-subpasses
+ */
+import { type OwnerSideSignalPollResult, type OwnerSideSignalPollTarget } from './owner-side-signal-poll.ts';
+import { type OwnerSideUpdatePollResult, type OwnerSideUpdatePollTarget } from './owner-side-update-poll.ts';
+/**
+ * The minimal structural shape the renewal sub-pass needs from a per-workflow
+ * claim holder. A `WorkflowClaimRegistry` (built separately) is expected to
+ * satisfy this interface; it is defined locally, rather than imported, so
+ * this module has no dependency on that registry's concrete shape or module
+ * path.
+ */
+export type WorkflowClaimRenewalTarget = {
+    /**
+     * 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; the caller never mutates it and
+     * takes its own snapshot before iterating.
+     */
+    listHeldWorkflowIds(): readonly string[];
+    /**
+     * Renew this engine's claim for one workflow. Resolves when the renewal
+     * committed; rejects (with any error shape) when it did not — a lost-race
+     * CAS failure, a storage error, or anything else. The implementation is
+     * responsible for its own per-workflow in-flight-renewal guard against a
+     * concurrent `release`, and for reacting to a lost claim (aborting
+     * in-flight work, emitting `WeftWorkflowClaimLostWarning`). The caller only
+     * calls it, catches whatever it throws, and continues to the next
+     * workflow.
+     */
+    renewWorkflowClaim(workflowId: string): Promise<void>;
+};
+/** One workflow's outcome within a single renewal pass. */
+export type WorkflowClaimRenewalOutcome = {
+    workflowId: string;
+    status: 'renewed';
+} | {
+    workflowId: string;
+    status: 'failed';
+    error: unknown;
+};
+/**
+ * The minimal structural shape the reclaim-scan sub-pass needs. Defined
+ * locally for the same decoupling reason as {@link WorkflowClaimRenewalTarget}
+ * — expected to be satisfied by an adapter over
+ * `listWorkflowClaimReclaimCandidates` (`workflow-claim-reclaim-scan.ts`) and
+ * `WorkflowClaimRegistry.takeover`, built by `ownership-bootstrap.ts`.
+ */
+export type WorkflowClaimReclaimTarget = {
+    /**
+     * Every workflow id with a currently-persisted holder record this engine
+     * does not itself already hold. Read fresh at the start of every pass.
+     */
+    listReclaimCandidateWorkflowIds(): Promise<readonly string[]>;
+    /**
+     * Attempt to reclaim one candidate. Retrying a lost-race CAS (bounded, per
+     * the ADR, at 5 attempts within this call) and gating on the per-workflow-id
+     * anti-thrash cooldown are the implementation's responsibility — the caller
+     * calls it exactly once per candidate, catches whatever it throws, and
+     * continues to the next one.
+     */
+    attemptWorkflowClaimTakeover(workflowId: string): Promise<WorkflowClaimReclaimAttemptResult>;
+};
+/** One candidate's non-throwing outcome from {@link WorkflowClaimReclaimTarget.attemptWorkflowClaimTakeover}. */
+export type WorkflowClaimReclaimAttemptResult = {
+    status: 'reclaimed';
+} | {
+    status: 'not-eligible';
+} | {
+    status: 'backoff-skipped';
+} | {
+    status: 'lost-race';
+};
+/** One workflow's outcome within a single reclaim-scan pass. */
+export type WorkflowClaimReclaimOutcome = ({
+    workflowId: string;
+} & WorkflowClaimReclaimAttemptResult) | {
+    workflowId: string;
+    status: 'error';
+    error: unknown;
+};
+/**
+ * The reclaim-scan sub-pass's result. `'discovery-failed'` covers
+ * `listReclaimCandidateWorkflowIds()` itself throwing — without a candidate
+ * list there is no per-workflow loop to run, but that must not fail the rest
+ * of an enclosing combined pass (renewals already committed by then, and a
+ * `backgroundTasks: 'manual'` host awaiting `runMaintenance()` must not see a
+ * rejected promise for a problem isolated to this one sub-step).
+ */
+export type WorkflowClaimReclaimPassResult = {
+    status: 'completed';
+    outcomes: WorkflowClaimReclaimOutcome[];
+    reclaimedCount: number;
+} | {
+    status: 'discovery-failed';
+    error: unknown;
+};
+/**
+ * The owner-side signal-poll sub-pass's result. `'failed'` covers
+ * {@link runOwnerSideSignalPoll} itself rejecting (e.g. its target's
+ * `hasBufferedSignal` throwing) — same non-fatal-to-the-enclosing-pass
+ * treatment as {@link WorkflowClaimReclaimPassResult}'s `'discovery-failed'`.
+ */
+export type WorkflowClaimSignalPollOutcome = {
+    status: 'completed';
+    result: OwnerSideSignalPollResult;
+} | {
+    status: 'failed';
+    error: unknown;
+};
+/**
+ * The owner-side update-poll sub-pass's result (WFT-79). `'failed'` covers
+ * {@link runOwnerSideUpdatePoll} itself rejecting (e.g. its target's
+ * `hasPendingUpdates` throwing) — same non-fatal-to-the-enclosing-pass
+ * treatment as {@link WorkflowClaimSignalPollOutcome}'s `'failed'`.
+ */
+export type WorkflowClaimUpdatePollOutcome = {
+    status: 'completed';
+    result: OwnerSideUpdatePollResult;
+} | {
+    status: 'failed';
+    error: unknown;
+};
+/**
+ * The result of one full claim-renewal pass
+ * (`workflow-claim-renewal-task.ts`'s `WorkflowClaimRenewalTask.runOnce`, or
+ * one of `workflow-claim-renewal-interval.ts`'s interval-mode sub-passes).
+ * `reclaim`/`signalPoll`/`updatePoll` are `undefined` exactly when the
+ * matching target option was omitted — that omission is how a caller (or a
+ * test exercising renewal alone) opts out of running that sub-step at all.
+ * Defined here (rather than in `workflow-claim-renewal-task.ts`) so both that
+ * module and `workflow-claim-renewal-interval.ts` can depend on it without a
+ * cycle between them; `workflow-claim-renewal-task.ts` re-exports it for
+ * backward-compatible import paths.
+ */
+export type WorkflowClaimRenewalPassResult = {
+    /** `getNow()` read at the start of the pass, before any renewal call. */
+    startedAt: number;
+    /** `getNow()` read after renewal, reclaim, and signal-poll have all settled. */
+    finishedAt: number;
+    /** One entry per workflow id the pass attempted, in iteration order. */
+    outcomes: WorkflowClaimRenewalOutcome[];
+    /** `outcomes.filter(o => o.status === 'renewed').length`, precomputed for observability consumers. */
+    renewedCount: number;
+    /** `outcomes.filter(o => o.status === 'failed').length`, precomputed for observability consumers. */
+    failedCount: number;
+    /** Present only when this task was constructed with a `reclaimTarget`. */
+    reclaim?: WorkflowClaimReclaimPassResult;
+    /** Present only when this task was constructed with a `signalPollTarget`. */
+    signalPoll?: WorkflowClaimSignalPollOutcome;
+    /** Present only when this task was constructed with an `updatePollTarget`. */
+    updatePoll?: WorkflowClaimUpdatePollOutcome;
+};
+/**
+ * The interval-scheduling seam `workflow-claim-renewal-interval.ts` drives
+ * its interval-mode cadence through. The handle type is deliberately
+ * `unknown` on this public interface — nothing inspects a handle, only
+ * round-trips whatever `setInterval` returned back into `clearInterval` — so
+ * a test double can use a plain number, object, or anything else as its
+ * handle without either side needing to know the real timer type. Defined
+ * here for the same cross-module-without-a-cycle reason as
+ * {@link WorkflowClaimRenewalPassResult}; `workflow-claim-renewal-task.ts`
+ * re-exports it.
+ */
+export type WorkflowClaimRenewalIntervalScheduler = {
+    setInterval(callback: () => void, intervalMs: number): unknown;
+    clearInterval(handle: unknown): void;
+};
+/**
+ * How many reclaim attempts may be in flight at once within a single pass.
+ *
+ * A serial loop lets one stuck candidate block every later one indefinitely —
+ * `attemptWorkflowClaimTakeover` can await an `onReclaimed` drive that never
+ * settles (e.g. a stalled storage read during replay), and a serial `for`
+ * loop never reaches the next candidate until that await resolves. Each
+ * candidate's takeover/acquire CAS and drive are independent per-workflow
+ * operations, so running them through the same bounded pool
+ * `runRenewalSubPass` uses for renewals is safe here too — see that
+ * function's doc for why a fixed-width pool is the right middle ground
+ * between full serialization and an unbounded stampede.
+ */
+export declare const WORKFLOW_CLAIM_RECLAIM_CONCURRENCY = 16;
+/**
+ * Run one reclaim-scan sub-pass: list candidates, attempt each through a
+ * bounded pool (see {@link WORKFLOW_CLAIM_RECLAIM_CONCURRENCY}), and catch
+ * both a per-candidate throw and the listing call itself throwing. See
+ * {@link WorkflowClaimReclaimPassResult}'s doc for why discovery failure is a
+ * result, not a rejection. `outcomes` stays in `candidates` order regardless
+ * of the order attempts actually settle, matching `runRenewalSubPass`'s own
+ * positional-result discipline.
+ */
+export declare function runReclaimPass(target: WorkflowClaimReclaimTarget): Promise<WorkflowClaimReclaimPassResult>;
+/**
+ * How many claim renewals may be in flight at once within a single pass.
+ *
+ * A serial loop costs one storage round trip per held claim before returning to
+ * the first one, so with many claims on a high-latency shared store the pass
+ * itself can outlast `workflowClaimTtl`: later claims expire before their first
+ * renewal, and earlier ones expire before the next pass. Separating the reclaim
+ * scan out of the renewal single-flight does not help — this loop is unbounded
+ * in the number of claims, independently of what else shares the tick.
+ *
+ * The opposite extreme is just as wrong: renewing every claim at once turns
+ * starvation into a storage stampede that the store may then rate-limit or
+ * queue, reproducing the latency it was meant to avoid. So renewals run through
+ * a fixed-width pool.
+ *
+ * Sixteen is chosen to be wide enough that per-request latency dominates rather
+ * than accumulates — it cuts a 1000-claim pass from 1000 sequential round trips
+ * to 63 — while staying within the connection budget a modest remote store
+ * offers. It is deliberately a constant rather than an option: it trades two
+ * failure modes against each other and neither is something a caller is well
+ * placed to tune. Revisit it with measurements, not intuition.
+ */
+export declare const WORKFLOW_CLAIM_RENEWAL_CONCURRENCY = 16;
+/**
+ * Renew every id in `workflowIds`, continuing past a per-workflow failure.
+ *
+ * Renewals run through a bounded pool (see
+ * {@link WORKFLOW_CLAIM_RENEWAL_CONCURRENCY}) rather than one at a time, so a
+ * large claim set cannot push the pass past the claim validity window. Losing
+ * one claim still stops only that workflow: each renewal keeps its own
+ * `try`/`catch`, and `outcomes` stays in `workflowIds` order regardless of the
+ * order results actually arrive, so callers and tests see a stable, positional
+ * result.
+ *
+ * Pure — no clock reads, no `onPassComplete` — so it is shared verbatim by
+ * `workflow-claim-renewal-task.ts`'s combined `runOnce()` pass and interval
+ * mode's standalone renewal sub-pass.
+ */
+export declare function runRenewalSubPass(target: WorkflowClaimRenewalTarget, workflowIds: readonly string[]): Promise<{
+    outcomes: WorkflowClaimRenewalOutcome[];
+    renewedCount: number;
+    failedCount: number;
+}>;
+/**
+ * Run the owner-side signal-poll sub-step, translating a throw into the
+ * `'failed'` result shape rather than letting it reject. Shared by
+ * `workflow-claim-renewal-task.ts`'s combined `runOnce()` pass and interval
+ * mode's standalone reclaim-plus-poll sub-pass.
+ */
+export declare function runSignalPollSubPass(signalPollTarget: OwnerSideSignalPollTarget, getNow: () => number): Promise<WorkflowClaimSignalPollOutcome>;
+/**
+ * Run the owner-side update-poll sub-step (WFT-79), translating a throw into
+ * the `'failed'` result shape rather than letting it reject. Shared by
+ * `workflow-claim-renewal-task.ts`'s combined `runOnce()` pass and interval
+ * mode's standalone update-poll sub-pass.
+ */
+export declare function runUpdatePollSubPass(updatePollTarget: OwnerSideUpdatePollTarget, getNow: () => number): Promise<WorkflowClaimUpdatePollOutcome>;

package/dist/core/engine/workflow-claim-renewal-subpasses.js

@@ -0,0 +1,104 @@
+import {
+  runOwnerSideSignalPoll
+} from "./owner-side-signal-poll.js";
+import {
+  runOwnerSideUpdatePoll
+} from "./owner-side-update-poll.js";
+export const WORKFLOW_CLAIM_RECLAIM_CONCURRENCY = 16;
+export async function runReclaimPass(target) {
+  let candidates;
+  try {
+    candidates = await target.listReclaimCandidateWorkflowIds();
+  } catch (error) {
+    return { status: "discovery-failed", error };
+  }
+  const outcomes = Array.from({ length: candidates.length });
+  async function attemptOne(index) {
+    const workflowId = candidates[index];
+    try {
+      const attempt = await target.attemptWorkflowClaimTakeover(workflowId);
+      outcomes[index] = { workflowId, ...attempt };
+    } catch (error) {
+      outcomes[index] = { workflowId, status: "error", error };
+    }
+  }
+  if (candidates.length <= 1)
+    for (const [index] of candidates.entries())
+      await attemptOne(index);
+  else {
+    let nextIndex = 0;
+    async function attemptFromQueue() {
+      for (;; ) {
+        const index = nextIndex;
+        nextIndex += 1;
+        if (index >= candidates.length)
+          return;
+        await attemptOne(index);
+      }
+    }
+    const workerCount = Math.min(WORKFLOW_CLAIM_RECLAIM_CONCURRENCY, candidates.length);
+    await Promise.all(Array.from({ length: workerCount }, attemptFromQueue));
+  }
+  return {
+    status: "completed",
+    outcomes,
+    reclaimedCount: outcomes.filter((outcome) => outcome.status === "reclaimed").length
+  };
+}
+export const WORKFLOW_CLAIM_RENEWAL_CONCURRENCY = 16;
+export async function runRenewalSubPass(target, workflowIds) {
+  const outcomes = Array.from({ length: workflowIds.length });
+  let nextIndex = 0;
+  async function renewFromQueue() {
+    for (;; ) {
+      const index = nextIndex;
+      nextIndex += 1;
+      if (index >= workflowIds.length)
+        return;
+      const workflowId = workflowIds[index];
+      try {
+        await target.renewWorkflowClaim(workflowId);
+        outcomes[index] = { workflowId, status: "renewed" };
+      } catch (error) {
+        outcomes[index] = { workflowId, status: "failed", error };
+      }
+    }
+  }
+  if (workflowIds.length <= 1)
+    for (const [index, workflowId] of workflowIds.entries())
+      try {
+        await target.renewWorkflowClaim(workflowId);
+        outcomes[index] = { workflowId, status: "renewed" };
+      } catch (error) {
+        outcomes[index] = { workflowId, status: "failed", error };
+      }
+  else {
+    const workerCount = Math.min(WORKFLOW_CLAIM_RENEWAL_CONCURRENCY, workflowIds.length);
+    await Promise.all(Array.from({ length: workerCount }, renewFromQueue));
+  }
+  return {
+    outcomes,
+    renewedCount: outcomes.filter((outcome) => outcome.status === "renewed").length,
+    failedCount: outcomes.filter((outcome) => outcome.status === "failed").length
+  };
+}
+export async function runSignalPollSubPass(signalPollTarget, getNow) {
+  try {
+    return {
+      status: "completed",
+      result: await runOwnerSideSignalPoll({ target: signalPollTarget, getNow })
+    };
+  } catch (error) {
+    return { status: "failed", error };
+  }
+}
+export async function runUpdatePollSubPass(updatePollTarget, getNow) {
+  try {
+    return {
+      status: "completed",
+      result: await runOwnerSideUpdatePoll({ target: updatePollTarget, getNow })
+    };
+  } catch (error) {
+    return { status: "failed", error };
+  }
+}

package/dist/core/engine/workflow-claim-renewal-task.d.ts

@@ -0,0 +1,159 @@
+/**
+ * Recurring driver for the per-workflow claim-renewal lifecycle task described
+ * in [ADR 0002 § Reclaiming stranded claims](../../../documentation/contributing/architecture-decisions/0002-multiengine-per-workflow-ownership.md#reclaiming-stranded-claims)
+ * and its `renew` transition row.
+ *
+ * **Why this must be its own driver, independent of the durable-timer
+ * scheduler.** Renewal keeps a *parked* workflow's claim alive — sleep,
+ * wait-signal, wait-update, wait-condition, wait-async-activity, and
+ * await-child-completion all keep the claim held rather than releasing it (see
+ * the ADR's `wf-owner-holder` row). A parked workflow has no pending durable
+ * timer of its own to piggyback on, and `startScheduler: false` is an
+ * explicitly supported, orthogonal configuration — tying renewal to
+ * `Scheduler#tick` would silently expire every parked claim the moment the
+ * scheduler is disabled, even though the owning engine is perfectly healthy.
+ * This task runs on its own cadence, or on an explicitly awaited host tick
+ * under `backgroundTasks: 'manual'` (see `Engine#runMaintenance()`), and never
+ * depends on the scheduler being started.
+ *
+ * **What this module owns.** `runOnce()` — the manual/`backgroundTasks:
+ * 'manual'` combined pass — plus the public options/result/task types. The
+ * actual claim storage transitions (`buildWorkflowClaimRenewTransition`), the
+ * in-flight-renewal guard *per workflow* that serializes a renewal against a
+ * concurrent `release` (ADR `renew` row), and the deposition side effects of
+ * a failed renewal — aborting the workflow's in-flight work and emitting
+ * {@link WeftWorkflowClaimLostWarning} — all belong to the claim holder this
+ * task is handed ({@link WorkflowClaimRenewalTarget}), typically a
+ * `WorkflowClaimRegistry`. This module never imports that registry directly
+ * and never imports `lease-deposition.ts`: coupling to the registry's exact
+ * shape here would tie two patches built in parallel together, and duplicating
+ * its warning-emission would double-emit once the two are wired together.
+ * Interval-mode driving (four independent single-flight sub-pass slots) lives
+ * in `workflow-claim-renewal-interval.ts`, split out to keep this file under
+ * the repository's implementation-file-size ceiling — see that module's doc
+ * for the full "each sub-pass gets its own slot" rationale (WFT-79 Finding 2
+ * and its extensions).
+ *
+ * **`runOnce()` still runs every configured sub-step sequentially in one
+ * awaited call**, exactly as ADR 0002 describes — a host calling
+ * `runMaintenance()` gets one coherent pass (serialized against any other
+ * concurrent `runOnce()` call — see `inFlightManualPass`). Interval mode's
+ * `start()`/`stop()` (delegated to `workflow-claim-renewal-interval.ts`)
+ * gives renewal, reclaim, signal poll, and update poll each their own
+ * cadence instead.
+ *
+ * **Three more ADR 0002 responsibilities besides renewal itself**, each
+ * OPTIONAL: a reclaim scan that attempts `takeover` for workflows whose
+ * holders have passed the grace-adjusted `expire` judgment (ADR § Reclaiming
+ * stranded claims), driven through the {@link WorkflowClaimReclaimTarget}
+ * structural seam — expected to be satisfied by
+ * `listWorkflowClaimReclaimCandidates` (`workflow-claim-reclaim-scan.ts`)
+ * plus `WorkflowClaimRegistry.takeover`, adapted by `ownership-bootstrap.ts`
+ * — owner-side polling of the durable signal buffer for parked
+ * `waitForSignal` workflows (ADR § signal delivery, "owner-side polling"),
+ * and owner-side polling of pending coordinated updates (WFT-79). All three
+ * are `undefined` in {@link WorkflowClaimRenewalPassResult} when their target
+ * option is omitted, which is how a caller with only the renewal target (or
+ * a test) opts out of running them at all.
+ *
+ * @module core/engine/workflow-claim-renewal-task
+ */
+import type { OwnerSideSignalPollTarget } from './owner-side-signal-poll.ts';
+import type { OwnerSideUpdatePollTarget } from './owner-side-update-poll.ts';
+import { type WorkflowClaimReclaimTarget, type WorkflowClaimRenewalIntervalScheduler, type WorkflowClaimRenewalPassResult, type WorkflowClaimRenewalTarget } from './workflow-claim-renewal-subpasses.ts';
+export type { WorkflowClaimRenewalIntervalScheduler, WorkflowClaimRenewalPassResult, } from './workflow-claim-renewal-subpasses.ts';
+/** Options for {@link createWorkflowClaimRenewalTask}. */
+export type WorkflowClaimRenewalTaskOptions = {
+    /** The claim holder this task renews on behalf of. */
+    target: WorkflowClaimRenewalTarget;
+    /**
+     * Wall-clock source (ms), injected so tests never depend on real time. There
+     * is no default — every call site (the engine) already threads an injected
+     * clock through the rest of the ownership machinery (see `lease-manager.ts`),
+     * and an implicit `Date.now()` default would be a code path tests could
+     * never exercise deterministically.
+     */
+    getNow: () => number;
+    /** Interval-mode cadence (ms). Should be the configured `workflowClaimRenewInterval`. */
+    intervalMs: number;
+    /**
+     * Interval-scheduling seam. Defaults to the real `setInterval`/`clearInterval`,
+     * with the created interval `unref()`'d (when supported) so it never keeps an
+     * otherwise-idle process alive — mirroring `lease-manager.ts`'s `startRenewal`.
+     */
+    scheduler?: WorkflowClaimRenewalIntervalScheduler;
+    /**
+     * Optional reclaim-scan target. Omitted (the default) runs renewal alone —
+     * `result.reclaim` stays `undefined`. See {@link WorkflowClaimReclaimTarget}.
+     */
+    reclaimTarget?: WorkflowClaimReclaimTarget;
+    /**
+     * Optional owner-side signal-poll target. Omitted (the default) leaves
+     * `result.signalPoll` `undefined`. See `owner-side-signal-poll.ts`'s
+     * `OwnerSideSignalPollTarget`.
+     */
+    signalPollTarget?: OwnerSideSignalPollTarget;
+    /**
+     * Optional owner-side update-poll target (WFT-79). Omitted (the default)
+     * leaves `result.updatePoll` `undefined`. See `owner-side-update-poll.ts`'s
+     * `OwnerSideUpdatePollTarget`.
+     */
+    updatePollTarget?: OwnerSideUpdatePollTarget;
+    /**
+     * Called after every completed pass, interval-driven or explicit. This is
+     * the reporting seam a later observability stage hangs a metrics counter
+     * off of (e.g. `weft_workflow_claim_renewal_failures_total`); this task does
+     * not touch any metrics registry itself.
+     */
+    onPassComplete?: (result: WorkflowClaimRenewalPassResult) => void;
+};
+/** A running claim-renewal task. */
+export type WorkflowClaimRenewalTask = {
+    /**
+     * Run exactly one pass: snapshot the currently-held workflow ids, renew each
+     * in turn, and continue past a failure on any one of them so a single lost
+     * claim never stops the rest from renewing. A per-workflow renewal failure is
+     * captured as a `'failed'` outcome rather than a rejection; the pass itself
+     * rejects only if `listHeldWorkflowIds()` throws, since without a snapshot
+     * there is no pass to run. A throwing `onPassComplete` sink never fails the
+     * pass — the renewal work already committed by then.
+     * This is the entry point `backgroundTasks: 'manual'` hosts drive from an
+     * awaited host tick (`Engine#runMaintenance()`), and the one tests use to
+     * step the task deterministically. Bypasses the interval-mode single-flight
+     * slots by design — same as `renewOnce()` does relative to
+     * `startRenewal()`'s timer in `lease-manager.ts` — so an explicit caller
+     * is never silently skipped because an interval-driven pass happens to be
+     * in flight. It IS, however, deduped against another concurrent `runOnce()`
+     * call: `Engine.create()` documents concurrent `runMaintenance()` calls as
+     * safe, and two independent combined passes sharing this task's targets
+     * could otherwise both act on the same stale reclaim candidate. An
+     * overlapping caller receives the already-running pass's result rather
+     * than starting a second one.
+     */
+    runOnce(): Promise<WorkflowClaimRenewalPassResult>;
+    /**
+     * Start interval-driven passes. Idempotent — a second call while already
+     * started does not create a second interval. Each interval tick is guarded
+     * by a single-flight lock: if the previous interval-driven pass is still
+     * running when the next tick fires, that tick is skipped rather than
+     * starting an overlapping pass.
+     */
+    start(): void;
+    /**
+     * Stop interval-driven passes. Idempotent — a second call, or a call before
+     * `start()`, does not throw. Only clears the interval; a pass already in
+     * flight (started by the last tick before `stop()`) still runs to
+     * completion, but no further tick fires afterward.
+     */
+    stop(): void;
+};
+/**
+ * Create a claim-renewal task. Does not start any timer and does not run any
+ * pass itself — the caller drives it, either via `start()` for interval mode
+ * (delegated to `workflow-claim-renewal-interval.ts`) or by awaiting
+ * `runOnce()` directly under `backgroundTasks: 'manual'`. The sub-pass
+ * implementations both this module and the interval driver compose
+ * (`runReclaimPass`, `runRenewalSubPass`, `runSignalPollSubPass`,
+ * `runUpdatePollSubPass`) live in `workflow-claim-renewal-subpasses.ts`.
+ */
+export declare function createWorkflowClaimRenewalTask(options: WorkflowClaimRenewalTaskOptions): WorkflowClaimRenewalTask;

package/dist/core/engine/workflow-claim-renewal-task.js

@@ -0,0 +1,65 @@
+import {
+  createWorkflowClaimRenewalIntervalDriver,
+  defaultWorkflowClaimRenewalScheduler
+} from "./workflow-claim-renewal-interval.js";
+import {
+  runReclaimPass,
+  runRenewalSubPass,
+  runSignalPollSubPass,
+  runUpdatePollSubPass
+} from "./workflow-claim-renewal-subpasses.js";
+export function createWorkflowClaimRenewalTask(options) {
+  const {
+    target,
+    getNow,
+    intervalMs,
+    reclaimTarget,
+    signalPollTarget,
+    updatePollTarget,
+    onPassComplete
+  } = options, scheduler = options.scheduler ?? defaultWorkflowClaimRenewalScheduler();
+  let inFlightManualPass = null;
+  function emitPassComplete(result) {
+    try {
+      onPassComplete?.(result);
+    } catch (error) {
+      console.error("weft: workflow claim renewal onPassComplete sink threw", error);
+    }
+  }
+  async function runCombinedPass() {
+    const startedAt = getNow(), workflowIds = [...target.listHeldWorkflowIds()], renewal = await runRenewalSubPass(target, workflowIds), reclaim = reclaimTarget === void 0 ? void 0 : await runReclaimPass(reclaimTarget), signalPoll = signalPollTarget === void 0 ? void 0 : await runSignalPollSubPass(signalPollTarget, getNow), updatePoll = updatePollTarget === void 0 ? void 0 : await runUpdatePollSubPass(updatePollTarget, getNow), finishedAt = getNow(), result = {
+      startedAt,
+      finishedAt,
+      ...renewal,
+      ...reclaim === void 0 ? {} : { reclaim },
+      ...signalPoll === void 0 ? {} : { signalPoll },
+      ...updatePoll === void 0 ? {} : { updatePoll }
+    };
+    emitPassComplete(result);
+    return result;
+  }
+  async function runOnce() {
+    if (inFlightManualPass !== null)
+      return inFlightManualPass;
+    const pass = runCombinedPass().finally(() => {
+      inFlightManualPass = null;
+    });
+    inFlightManualPass = pass;
+    return pass;
+  }
+  const intervalDriver = createWorkflowClaimRenewalIntervalDriver({
+    target,
+    getNow,
+    intervalMs,
+    scheduler,
+    ...reclaimTarget === void 0 ? {} : { reclaimTarget },
+    ...signalPollTarget === void 0 ? {} : { signalPollTarget },
+    ...updatePollTarget === void 0 ? {} : { updatePollTarget },
+    ...onPassComplete === void 0 ? {} : { onPassComplete }
+  });
+  return {
+    runOnce,
+    start: () => intervalDriver.start(),
+    stop: () => intervalDriver.stop()
+  };
+}