@lostgradient/weft 0.20.0 → 0.22.0

package/dist/core/engine/workflow-claim-registry.d.ts

@@ -0,0 +1,227 @@
+/**
+ * The stateful per-workflow claim registry — the object that actually
+ * performs durable IO for the `wf-owner-epoch:<id>` / `wf-owner-holder:<id>`
+ * claim transitions specified in
+ * [ADR 0002 § Ownership transitions](../../../documentation/contributing/architecture-decisions/0002-multiengine-per-workflow-ownership.md#ownership-transitions).
+ *
+ * `workflow-claim-transitions.ts` supplies pure `{ conditions, operations }`
+ * fragments; this module is the thin, stateful layer around them that reads
+ * storage, executes `storageConditionalBatch`, and tracks — for every claim
+ * THIS engine currently holds — the exact epoch and holder bytes it last
+ * wrote. Renewal and release condition on those exact bytes, extracted from
+ * the fragment they were just written by rather than re-encoded from the
+ * fields the registry happens to know, mirroring `lease-manager.ts`'s
+ * "never round-trip encode(decode(raw))" discipline.
+ *
+ * **Scope.** The unit itself: acquire, renew, release, takeover, and
+ * release-all — plus, additively, {@link WorkflowClaimRegistry.prepareAcquireFragment}
+ * and {@link WorkflowClaimRegistry.recordFoldedAcquire}, the two-step seam a
+ * caller uses to fold `acquire` into ITS OWN atomic enabling write (a create
+ * batch, a delayed-start pending→running transition, a failed-workflow
+ * reactivation) instead of committing the fragment through this registry's
+ * own `acquire()`. Driving `renew` and the reclaim scan from a lifecycle
+ * task, and turning a lost `acquire`/`takeover` into
+ * `WorkflowClaimUnavailableError` for explicit single-workflow callers, are
+ * still each call site's own responsibility — this registry never throws
+ * that error itself. Per the ADR, background scanning never throws it either
+ * — it skips the workflow and continues — so every method here returns a
+ * discriminated result instead of throwing on a lost CAS, leaving that
+ * decision to the caller — `takeover` also gates on a per-workflow-id
+ * anti-thrash cooldown ({@link WorkflowClaimTakeoverCooldown}). Still out of
+ * scope: `weft_workflow_claim_*` metrics, `wakeOwnershipCheck`, and external
+ * terminal-transition rotation (any engine may commit those unconditioned).
+ *
+ * **Renewal-vs-release serialization.** A per-workflow in-flight-renewal
+ * promise (mirroring `lease-manager.ts`'s single `inFlightRenewal`) lets
+ * `release()` await a renewal already in progress before reading the cached
+ * bytes it conditions on; otherwise both race the same holder bytes and
+ * whichever commits second loses its CAS. A `releasing` set stops a NEW
+ * renewal from starting once release has begun, so a `renew()` arriving
+ * mid-release fails fast as `'not-held'`. A renewal that THROWS (a transient
+ * storage error, not a CAS-false result) is not a lost claim: it propagates
+ * to its caller leaving cached bytes untouched, and `release()`'s wait
+ * swallows it — a storage hiccup must not fail a terminal or shutdown release.
+ *
+ * @module core/engine/workflow-claim-registry
+ */
+import { type Storage } from '../../storage/interface.ts';
+import { type EmitWorkflowLeaseWarning } from './lease-deposition.ts';
+import { type WorkflowClaimTransitionFragment } from './workflow-claim-transitions.ts';
+/** Options for {@link WorkflowClaimRegistry}. */
+export type WorkflowClaimRegistryOptions = {
+    storage: Storage;
+    /** This engine's identity, minted once per process — the holder record's `engineId`. */
+    engineId: string;
+    /** Wall-clock source (ms), injected so tests can drive time deterministically. */
+    getNow: () => number;
+    /** `workflowClaimTtl` (ms), resolved by `ownership-options.ts`. */
+    claimTtlMs: number;
+    /**
+     * `workflowClaimRenewInterval` (ms), resolved by `ownership-options.ts` —
+     * feeds `isWorkflowClaimExpired`'s grace term.
+     */
+    claimRenewIntervalMs: number;
+    /** Operator-warning seam; defaults to `process.emitWarning` via {@link emitWorkflowClaimLostWarning}. */
+    warn?: EmitWorkflowLeaseWarning;
+};
+/** Result of {@link WorkflowClaimRegistry.acquire}. */
+export type WorkflowClaimAcquireResult = {
+    status: 'acquired';
+    workflowId: string;
+    epoch: number;
+} | {
+    status: 'lost-race';
+    workflowId: string;
+    heldBy: string | null;
+};
+/** Result of {@link WorkflowClaimRegistry.renew}. */
+export type WorkflowClaimRenewResult = {
+    status: 'renewed';
+    workflowId: string;
+} | {
+    status: 'lost';
+    workflowId: string;
+} | {
+    status: 'not-held';
+    workflowId: string;
+};
+/** Result of {@link WorkflowClaimRegistry.release}. */
+export type WorkflowClaimReleaseResult = {
+    status: 'released';
+    workflowId: string;
+} | {
+    status: 'lost-race';
+    workflowId: string;
+} | {
+    status: 'not-held';
+    workflowId: string;
+};
+/**
+ * A prepared, not-yet-committed `acquire` — the output of
+ * {@link WorkflowClaimRegistry.prepareAcquireFragment}, meant to be merged
+ * into a caller's own atomic enabling write and then handed back to
+ * {@link WorkflowClaimRegistry.recordFoldedAcquire} once that write commits.
+ */
+export type WorkflowClaimAcquirePreparation = {
+    fragment: WorkflowClaimTransitionFragment;
+    epoch: number;
+    claimedAt: number;
+};
+/** Result of {@link WorkflowClaimRegistry.takeover}. */
+export type WorkflowClaimTakeoverResult = {
+    status: 'acquired';
+    workflowId: string;
+    epoch: number;
+} | {
+    status: 'lost-race';
+    workflowId: string;
+    heldBy: string | null;
+} | {
+    status: 'not-expired';
+    workflowId: string;
+    heldBy: string | null;
+    expiresAt: number;
+} | {
+    status: 'no-claim';
+    workflowId: string;
+} | {
+    status: 'backoff-skipped';
+    workflowId: string;
+};
+/**
+ * Owns this engine's per-workflow ownership claims: reads storage, executes
+ * the pure transition fragments, and tracks the exact bytes it last wrote for
+ * every claim it currently holds. See the module doc for scope.
+ */
+export declare class WorkflowClaimRegistry {
+    #private;
+    constructor(options: WorkflowClaimRegistryOptions);
+    /** The epoch this engine currently believes it holds for `workflowId`, or `null` if untracked. */
+    currentEpoch(workflowId: string): number | null;
+    /** This engine's identity; with {@link currentEpoch} it forms the generation a wake check compares. */
+    get engineId(): string;
+    /**
+     * Every workflow id this engine currently tracks a live claim for — active
+     * or parked. A defensive-copy snapshot, mirroring `releaseAll`'s own
+     * `[...this.#claims.keys()]` read: callers (the claim-renewal task, an
+     * active-claims metrics gauge) must not observe mutations to this registry's
+     * internal map while iterating a snapshot they already took.
+     */
+    listHeldWorkflowIds(): readonly string[];
+    /**
+     * Defensive copy of the epoch bytes this engine last wrote for
+     * `workflowId`, for fencing durable writes — `null` if untracked. A copy so
+     * a caller mutating the returned buffer cannot corrupt this registry's
+     * cached fencing token.
+     */
+    currentEpochBytes(workflowId: string): Uint8Array | null;
+    /**
+     * `acquire`: always reads both keys fresh — never assumes absence — then
+     * builds and attempts the fragment from what it read. On a lost CAS,
+     * resolves `heldBy` from the holder bytes already read when they were
+     * non-null; otherwise (a competitor raced in between the read and the
+     * write) re-reads to report the true current holder.
+     */
+    acquire(workflowId: string): Promise<WorkflowClaimAcquireResult>;
+    /**
+     * Read fresh `wf-owner-epoch:<workflowId>` bytes and build the pure
+     * `acquire` fragment WITHOUT committing it or updating this registry's
+     * tracking — for a caller that folds the fragment into ITS OWN atomic
+     * enabling write instead of letting {@link acquire} commit it alone. The
+     * caller merges `fragment.conditions`/`fragment.operations` into its own
+     * operation list, commits ONE atomic `storageConditionalBatch`, and —
+     * ONLY on success — calls {@link recordFoldedAcquire} with this SAME
+     * preparation. Safe to call again on every retry attempt: this always
+     * re-reads fresh bytes, so a stale epoch from an earlier attempt never
+     * dooms a later one.
+     */
+    prepareAcquireFragment(workflowId: string): Promise<WorkflowClaimAcquirePreparation>;
+    /**
+     * Install the tracking entry for a claim acquired via a FOLDED enabling
+     * write (see {@link prepareAcquireFragment}) — call ONLY after the
+     * caller's own atomic commit that included `preparation.fragment`'s
+     * conditions and operations has actually succeeded. Extracts the exact
+     * bytes the fragment wrote using the same "never round-trip
+     * encode(decode(raw))" discipline every other grant path in this class
+     * uses.
+     */
+    recordFoldedAcquire(workflowId: string, preparation: WorkflowClaimAcquirePreparation): void;
+    /**
+     * `renew`: conditions on the exact holder bytes this engine last wrote.
+     * Concurrent calls for the same id share the one in-flight promise. A
+     * CAS-false result marks the claim lost locally and emits
+     * `WeftWorkflowClaimLostWarning` — losing one workflow's claim never
+     * touches any other tracked claim.
+     */
+    renew(workflowId: string): Promise<WorkflowClaimRenewResult>;
+    /**
+     * `release`: stops new renewals for `workflowId` and awaits any renewal
+     * already in flight (swallowing a thrown rejection — best-effort, never
+     * reject on a renewal's storage error) before building the expected bytes,
+     * so the two can never race the same holder bytes. Deletes only the holder
+     * key — the epoch key is never touched, so a successor's next `acquire`
+     * reads the true prior epoch. A lost CAS means this engine was already
+     * fenced out; the local entry is dropped either way, since there is
+     * nothing left to protect.
+     */
+    release(workflowId: string): Promise<WorkflowClaimReleaseResult>;
+    /**
+     * `takeover`: reads the holder and epoch keys fresh, and only attempts the
+     * CAS once the holder is not live — either its grace-adjusted `expiresAt`
+     * has passed ({@link isWorkflowClaimExpired}), or the holder bytes are
+     * foreign/undecodable garbage no valid engine could have written (mirrors
+     * `lease-manager.ts`'s "garbage is not a live owner" treatment: not live,
+     * so it can be stolen via CAS on its exact observed bytes). A holder
+     * present with no epoch key violates the write invariant — the two are
+     * always written together, and the epoch key is never deleted — so it is
+     * treated defensively as nothing safe to fence a takeover against.
+     */
+    takeover(workflowId: string): Promise<WorkflowClaimTakeoverResult>;
+    /**
+     * Best-effort release of every claim this engine currently tracks, for
+     * graceful shutdown. A failed release (thrown or lost-race) is swallowed
+     * per workflow so shutdown proceeds — the reclaim scan (a later stage)
+     * collects any stranded claim once its grace-adjusted expiry passes.
+     */
+    releaseAll(): Promise<void>;
+}

package/dist/core/engine/workflow-claim-registry.js

@@ -0,0 +1,198 @@
+import { KEYS, storageConditionalBatch } from "../../storage/interface.js";
+import { emitWorkflowClaimLostWarning } from "./lease-deposition.js";
+import { decodeEpoch, decodeWorkflowClaimHolder } from "./workflow-claim-codec.js";
+import { WorkflowClaimTakeoverCooldown } from "./workflow-claim-cooldown.js";
+import {
+  buildWorkflowClaimAcquireTransition,
+  buildWorkflowClaimReleaseTransition,
+  buildWorkflowClaimRenewTransition,
+  buildWorkflowClaimTakeoverTransition,
+  extractPutOperationValue,
+  isWorkflowClaimExpired
+} from "./workflow-claim-transitions.js";
+function mintNextEpoch(observedEpochBytes) {
+  return ((observedEpochBytes === null ? null : decodeEpoch(observedEpochBytes)) ?? 0) + 1;
+}
+
+export class WorkflowClaimRegistry {
+  #claimStorage;
+  #engineId;
+  #getNow;
+  #claimTtlMs;
+  #claimRenewIntervalMs;
+  #warn;
+  #claims = new Map;
+  #inFlightRenewals = new Map;
+  #releasing = new Set;
+  #takeoverCooldown;
+  constructor(options) {
+    this.#claimStorage = options.storage;
+    this.#engineId = options.engineId;
+    this.#getNow = options.getNow;
+    this.#claimTtlMs = options.claimTtlMs;
+    this.#claimRenewIntervalMs = options.claimRenewIntervalMs;
+    this.#warn = options.warn;
+    this.#takeoverCooldown = new WorkflowClaimTakeoverCooldown(options);
+  }
+  currentEpoch(workflowId) {
+    return this.#claims.get(workflowId)?.epoch ?? null;
+  }
+  get engineId() {
+    return this.#engineId;
+  }
+  listHeldWorkflowIds() {
+    return [...this.#claims.keys()];
+  }
+  currentEpochBytes(workflowId) {
+    const entry = this.#claims.get(workflowId);
+    return entry === void 0 ? null : entry.epochBytes.slice();
+  }
+  async#resolveHeldBy(workflowId) {
+    const raw = await this.#claimStorage.get(KEYS.workflowOwnerHolder(workflowId));
+    if (raw === null)
+      return null;
+    return decodeWorkflowClaimHolder(raw)?.engineId ?? null;
+  }
+  async acquire(workflowId) {
+    const observedHolderBytes = await this.#claimStorage.get(KEYS.workflowOwnerHolder(workflowId)), observedEpochBytes = await this.#claimStorage.get(KEYS.workflowOwnerEpoch(workflowId)), now = this.#getNow(), fragment = buildWorkflowClaimAcquireTransition({
+      workflowId,
+      engineId: this.#engineId,
+      now,
+      claimTtlMs: this.#claimTtlMs,
+      observedEpochBytes
+    });
+    if (!await storageConditionalBatch(this.#claimStorage, fragment.conditions, fragment.operations)) {
+      const heldBy = observedHolderBytes !== null ? decodeWorkflowClaimHolder(observedHolderBytes)?.engineId ?? null : await this.#resolveHeldBy(workflowId);
+      return { status: "lost-race", workflowId, heldBy };
+    }
+    const epoch = mintNextEpoch(observedEpochBytes), epochBytes = extractPutOperationValue(fragment.operations, KEYS.workflowOwnerEpoch(workflowId)), holderBytes = extractPutOperationValue(fragment.operations, KEYS.workflowOwnerHolder(workflowId));
+    this.#claims.set(workflowId, { epoch, claimedAt: now, epochBytes, holderBytes });
+    this.#takeoverCooldown.clear(workflowId);
+    return { status: "acquired", workflowId, epoch };
+  }
+  async prepareAcquireFragment(workflowId) {
+    const observedEpochBytes = await this.#claimStorage.get(KEYS.workflowOwnerEpoch(workflowId)), now = this.#getNow();
+    return { fragment: buildWorkflowClaimAcquireTransition({
+      workflowId,
+      engineId: this.#engineId,
+      now,
+      claimTtlMs: this.#claimTtlMs,
+      observedEpochBytes
+    }), epoch: mintNextEpoch(observedEpochBytes), claimedAt: now };
+  }
+  recordFoldedAcquire(workflowId, preparation) {
+    const epochBytes = extractPutOperationValue(preparation.fragment.operations, KEYS.workflowOwnerEpoch(workflowId)), holderBytes = extractPutOperationValue(preparation.fragment.operations, KEYS.workflowOwnerHolder(workflowId));
+    this.#claims.set(workflowId, {
+      epoch: preparation.epoch,
+      claimedAt: preparation.claimedAt,
+      epochBytes,
+      holderBytes
+    });
+    this.#takeoverCooldown.clear(workflowId);
+  }
+  async renew(workflowId) {
+    const existing = this.#inFlightRenewals.get(workflowId);
+    if (existing !== void 0)
+      return existing;
+    const promise = this.#performRenew(workflowId).finally(() => {
+      this.#inFlightRenewals.delete(workflowId);
+    });
+    this.#inFlightRenewals.set(workflowId, promise);
+    return promise;
+  }
+  async#performRenew(workflowId) {
+    if (this.#releasing.has(workflowId))
+      return { status: "not-held", workflowId };
+    const entry = this.#claims.get(workflowId);
+    if (entry === void 0)
+      return { status: "not-held", workflowId };
+    const fragment = buildWorkflowClaimRenewTransition({
+      workflowId,
+      now: this.#getNow(),
+      claimTtlMs: this.#claimTtlMs,
+      currentHolderBytes: entry.holderBytes
+    });
+    if (!await storageConditionalBatch(this.#claimStorage, fragment.conditions, fragment.operations)) {
+      if (this.#claims.get(workflowId) === entry) {
+        this.#claims.delete(workflowId);
+        this.#takeoverCooldown.recordDeposition(workflowId, this.#getNow());
+      }
+      emitWorkflowClaimLostWarning(workflowId, this.#warn);
+      return { status: "lost", workflowId };
+    }
+    const holderBytes = extractPutOperationValue(fragment.operations, KEYS.workflowOwnerHolder(workflowId));
+    if (this.#claims.get(workflowId) === entry)
+      this.#claims.set(workflowId, { ...entry, holderBytes });
+    return { status: "renewed", workflowId };
+  }
+  async release(workflowId) {
+    this.#releasing.add(workflowId);
+    try {
+      const inFlight = this.#inFlightRenewals.get(workflowId);
+      if (inFlight !== void 0)
+        await inFlight.catch(() => {
+          return;
+        });
+      const entry = this.#claims.get(workflowId);
+      if (entry === void 0)
+        return { status: "not-held", workflowId };
+      const fragment = buildWorkflowClaimReleaseTransition({
+        workflowId,
+        currentEpochBytes: entry.epochBytes,
+        currentHolderBytes: entry.holderBytes
+      }), committed = await storageConditionalBatch(this.#claimStorage, fragment.conditions, fragment.operations);
+      if (this.#claims.get(workflowId) === entry)
+        this.#claims.delete(workflowId);
+      return { status: committed ? "released" : "lost-race", workflowId };
+    } finally {
+      this.#releasing.delete(workflowId);
+    }
+  }
+  async takeover(workflowId) {
+    const now = this.#getNow();
+    if (this.#takeoverCooldown.isActive(workflowId, now))
+      return { status: "backoff-skipped", workflowId };
+    const observedHolderBytes = await this.#claimStorage.get(KEYS.workflowOwnerHolder(workflowId));
+    if (observedHolderBytes === null)
+      return { status: "no-claim", workflowId };
+    const observedEpochBytes = await this.#claimStorage.get(KEYS.workflowOwnerEpoch(workflowId));
+    if (observedEpochBytes === null)
+      return { status: "no-claim", workflowId };
+    const holder = decodeWorkflowClaimHolder(observedHolderBytes);
+    if (holder !== null && !isWorkflowClaimExpired({
+      expiresAt: holder.expiresAt,
+      now,
+      renewIntervalMs: this.#claimRenewIntervalMs
+    }))
+      return {
+        status: "not-expired",
+        workflowId,
+        heldBy: holder.engineId,
+        expiresAt: holder.expiresAt
+      };
+    const fragment = buildWorkflowClaimTakeoverTransition({
+      workflowId,
+      engineId: this.#engineId,
+      now,
+      claimTtlMs: this.#claimTtlMs,
+      observedHolderBytes,
+      observedEpochBytes
+    });
+    if (!await storageConditionalBatch(this.#claimStorage, fragment.conditions, fragment.operations)) {
+      const heldBy = await this.#resolveHeldBy(workflowId);
+      return { status: "lost-race", workflowId, heldBy };
+    }
+    const epoch = mintNextEpoch(observedEpochBytes), epochBytes = extractPutOperationValue(fragment.operations, KEYS.workflowOwnerEpoch(workflowId)), holderBytes = extractPutOperationValue(fragment.operations, KEYS.workflowOwnerHolder(workflowId));
+    this.#claims.set(workflowId, { epoch, claimedAt: now, epochBytes, holderBytes });
+    this.#takeoverCooldown.clear(workflowId);
+    return { status: "acquired", workflowId, epoch };
+  }
+  async releaseAll() {
+    const workflowIds = [...this.#claims.keys()];
+    await Promise.all(workflowIds.map(async (workflowId) => {
+      try {
+        await this.release(workflowId);
+      } catch {}
+    }));
+  }
+}

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

@@ -0,0 +1,50 @@
+/**
+ * Interval-mode driving for `workflow-claim-renewal-task.ts`'s claim-renewal
+ * task. Split out purely to keep that module under the repository's
+ * implementation-file-size ceiling as the number of independent interval-mode
+ * sub-passes has grown (renewal, reclaim, signal poll, update poll) — see
+ * that module's own doc for the "each sub-pass gets its own single-flight
+ * slot" design this file implements. `workflow-claim-renewal-task.ts` is the
+ * only expected caller; `runOnce()`/the manual combined pass stays there,
+ * since it shares none of this file's interval-scheduling state.
+ *
+ * @module core/engine/workflow-claim-renewal-interval
+ */
+import type { OwnerSideSignalPollTarget } from './owner-side-signal-poll.ts';
+import type { OwnerSideUpdatePollTarget } from './owner-side-update-poll.ts';
+import { type WorkflowClaimReclaimTarget, type WorkflowClaimRenewalTarget } from './workflow-claim-renewal-subpasses.ts';
+import type { WorkflowClaimRenewalIntervalScheduler, WorkflowClaimRenewalPassResult } from './workflow-claim-renewal-task.ts';
+/** Options for {@link createWorkflowClaimRenewalIntervalDriver}. Mirrors the relevant subset of `WorkflowClaimRenewalTaskOptions`. */
+export type WorkflowClaimRenewalIntervalDriverOptions = {
+    target: WorkflowClaimRenewalTarget;
+    getNow: () => number;
+    intervalMs: number;
+    scheduler: WorkflowClaimRenewalIntervalScheduler;
+    reclaimTarget?: WorkflowClaimReclaimTarget;
+    signalPollTarget?: OwnerSideSignalPollTarget;
+    updatePollTarget?: OwnerSideUpdatePollTarget;
+    onPassComplete?: (result: WorkflowClaimRenewalPassResult) => void;
+};
+/** A running interval-mode driver. */
+export type WorkflowClaimRenewalIntervalDriver = {
+    /** Start interval-driven passes. Idempotent — a second call while already started does not create a second interval. */
+    start(): void;
+    /** Stop interval-driven passes. Idempotent. Only clears the interval; passes already in flight still run to completion. */
+    stop(): void;
+};
+/**
+ * Real-timer scheduler used when no `scheduler` is injected. Keeps each real
+ * `Timer` in a private map, keyed by an opaque token, so the public
+ * {@link WorkflowClaimRenewalIntervalScheduler} interface never needs to name
+ * the concrete timer type — `clearInterval` looks the real timer back up by
+ * token rather than requiring a narrowed `unknown` parameter.
+ */
+export declare function defaultWorkflowClaimRenewalScheduler(): WorkflowClaimRenewalIntervalScheduler;
+/**
+ * Create the interval-mode driver: four independent single-flight sub-passes
+ * (renewal, reclaim, signal poll, update poll), each on its OWN cadence slot
+ * so a slow or hung sub-pass never delays a different one — see
+ * `workflow-claim-renewal-task.ts`'s module doc for the full rationale
+ * (WFT-79 Finding 2 and its extensions).
+ */
+export declare function createWorkflowClaimRenewalIntervalDriver(options: WorkflowClaimRenewalIntervalDriverOptions): WorkflowClaimRenewalIntervalDriver;

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

@@ -0,0 +1,132 @@
+import {
+  runReclaimPass,
+  runRenewalSubPass,
+  runSignalPollSubPass,
+  runUpdatePollSubPass
+} from "./workflow-claim-renewal-subpasses.js";
+export function defaultWorkflowClaimRenewalScheduler() {
+  const timers = new Map;
+  let nextToken = 1;
+  return {
+    setInterval(callback, intervalMs) {
+      const token = nextToken;
+      nextToken += 1;
+      const handle = setInterval(callback, intervalMs);
+      handle.unref?.();
+      timers.set(token, handle);
+      return token;
+    },
+    clearInterval(handle) {
+      if (typeof handle !== "number")
+        return;
+      const timer = timers.get(handle);
+      if (timer === void 0)
+        return;
+      clearInterval(timer);
+      timers.delete(handle);
+    }
+  };
+}
+export function createWorkflowClaimRenewalIntervalDriver(options) {
+  const {
+    target,
+    getNow,
+    intervalMs,
+    scheduler,
+    reclaimTarget,
+    signalPollTarget,
+    updatePollTarget,
+    onPassComplete
+  } = options;
+  let intervalHandle = null, inFlightRenewal = null, inFlightReclaim = null, inFlightSignalPoll = null, inFlightUpdatePoll = null;
+  function emitPassComplete(result) {
+    try {
+      onPassComplete?.(result);
+    } catch (error) {
+      console.error("weft: workflow claim renewal onPassComplete sink threw", error);
+    }
+  }
+  async function runRenewalTickPass() {
+    const startedAt = getNow(), workflowIds = [...target.listHeldWorkflowIds()], renewal = await runRenewalSubPass(target, workflowIds), finishedAt = getNow(), result = { startedAt, finishedAt, ...renewal };
+    emitPassComplete(result);
+    return result;
+  }
+  async function runReclaimTickPass() {
+    const startedAt = getNow(), reclaim = await runReclaimPass(reclaimTarget), finishedAt = getNow(), result = {
+      startedAt,
+      finishedAt,
+      outcomes: [],
+      renewedCount: 0,
+      failedCount: 0,
+      reclaim
+    };
+    emitPassComplete(result);
+    return result;
+  }
+  async function runSignalPollTickPass() {
+    const startedAt = getNow(), signalPoll = await runSignalPollSubPass(signalPollTarget, getNow), finishedAt = getNow(), result = {
+      startedAt,
+      finishedAt,
+      outcomes: [],
+      renewedCount: 0,
+      failedCount: 0,
+      signalPoll
+    };
+    emitPassComplete(result);
+    return result;
+  }
+  async function runUpdatePollTickPass() {
+    const startedAt = getNow(), updatePoll = await runUpdatePollSubPass(updatePollTarget, getNow), finishedAt = getNow(), result = {
+      startedAt,
+      finishedAt,
+      outcomes: [],
+      renewedCount: 0,
+      failedCount: 0,
+      updatePoll
+    };
+    emitPassComplete(result);
+    return result;
+  }
+  function tick() {
+    if (inFlightRenewal === null) {
+      const pass = runRenewalTickPass();
+      inFlightRenewal = pass;
+      pass.catch(() => {}).finally(() => {
+        inFlightRenewal = null;
+      });
+    }
+    if (inFlightReclaim === null && reclaimTarget !== void 0) {
+      const pass = runReclaimTickPass();
+      inFlightReclaim = pass;
+      pass.catch(() => {}).finally(() => {
+        inFlightReclaim = null;
+      });
+    }
+    if (inFlightSignalPoll === null && signalPollTarget !== void 0) {
+      const pass = runSignalPollTickPass();
+      inFlightSignalPoll = pass;
+      pass.catch(() => {}).finally(() => {
+        inFlightSignalPoll = null;
+      });
+    }
+    if (inFlightUpdatePoll === null && updatePollTarget !== void 0) {
+      const pass = runUpdatePollTickPass();
+      inFlightUpdatePoll = pass;
+      pass.catch(() => {}).finally(() => {
+        inFlightUpdatePoll = null;
+      });
+    }
+  }
+  function start() {
+    if (intervalHandle !== null)
+      return;
+    intervalHandle = scheduler.setInterval(tick, intervalMs);
+  }
+  function stop() {
+    if (intervalHandle === null)
+      return;
+    scheduler.clearInterval(intervalHandle);
+    intervalHandle = null;
+  }
+  return { start, stop };
+}