@lostgradient/weft 0.20.0 → 0.22.0

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

@@ -0,0 +1,131 @@
+/**
+ * Bounded-cardinality observability recorder for the `ownership: 'workflow-lease'`
+ * per-workflow claim protocol described in
+ * [ADR 0002 § Observability](../../../documentation/contributing/architecture-decisions/0002-multiengine-per-workflow-ownership.md#observability).
+ *
+ * This module is a standalone recorder, not wired into
+ * `src/observability/metrics.ts`/`metrics-catalog.ts` — those files already
+ * document a "keeping this as an interface" plug-point idiom for exactly this
+ * situation (see `PrometheusExporter` there), and the existing `METRICS`
+ * catalogue and `MetricsCollector` have no concept of a labelled series at
+ * all: every entry is a flat, unlabelled name. Folding `outcome` into that
+ * shape would require editing `metrics-catalog.ts` and `metrics.ts`, which is
+ * out of scope for this stage (see the module-level follow-up note below).
+ * Instead this module defines the same three signals as a small, injectable,
+ * structurally-typed recorder that a later stage can either back the existing
+ * exporter with directly, or bridge into `MetricsCollector` by fanning
+ * `snapshot().attempts` out into five unlabelled counter names.
+ *
+ * The ADR states twice that workflow ids are never Prometheus metric labels.
+ * That is enforced here at the type level, not by convention: the only value
+ * {@link WorkflowClaimMetricsRecorder.recordClaimAttempt} accepts is
+ * {@link WorkflowClaimAttemptOutcome}, a closed union of exactly five string
+ * literals. A workflow id — an arbitrary `string` — is not a member of that
+ * union, so passing one is a compile error, not a runtime cardinality bug
+ * waiting to happen. See `workflow-claim-metrics.test-d.ts` for the pinned
+ * proof.
+ *
+ * **Follow-up (not built here):** wiring this recorder's snapshot into the
+ * server's `/v1/metrics` `PrometheusExporter` (`src/observability/metrics.ts`)
+ * requires editing that file, which is owned by a different in-flight patch
+ * for this stage. {@link WorkflowClaimMetricsRecorder} is deliberately
+ * structural so that wiring can happen later without reshaping this module.
+ *
+ * @module core/engine/workflow-claim-metrics
+ */
+/**
+ * The exact, closed set of outcomes {@link WorkflowClaimMetricsRecorder.recordClaimAttempt}
+ * accepts. Matches `weft_workflow_claim_attempts_total`'s `outcome` label
+ * value set in ADR 0002 § Observability — five fixed values, nothing else.
+ */
+export type WorkflowClaimAttemptOutcome = 'acquired' | 'takeover' | 'lost_race' | 'deposed' | 'backoff_skipped';
+/**
+ * Every {@link WorkflowClaimAttemptOutcome} value, in declaration order. The
+ * single source of truth for the label's cardinality bound — both the
+ * recorder's internal counter map and the Prometheus serializer iterate this
+ * tuple rather than re-listing the five values.
+ */
+export declare const WORKFLOW_CLAIM_ATTEMPT_OUTCOMES: readonly ["acquired", "takeover", "lost_race", "deposed", "backoff_skipped"];
+/** One count per {@link WorkflowClaimAttemptOutcome}, always present (zero-filled when never recorded). */
+export type WorkflowClaimAttemptCounts = Readonly<Record<WorkflowClaimAttemptOutcome, number>>;
+/** A point-in-time read of everything this module tracks. */
+export type WorkflowClaimMetricsSnapshot = {
+    /** Per-outcome attempt counts. Mirrors `weft_workflow_claim_attempts_total{outcome="..."}`. */
+    attempts: WorkflowClaimAttemptCounts;
+    /** Mirrors `weft_workflow_claims_active` — workflows this engine currently holds a claim for. */
+    activeClaims: number;
+    /** Mirrors `weft_workflow_claim_renewal_failures_total`. */
+    renewalFailures: number;
+};
+/**
+ * Structural recorder interface for the three ADR 0002 observability signals.
+ * Defined as an interface — not just the concrete {@link WorkflowClaimMetricsCollector}
+ * class — so a caller can satisfy it with any implementation (a bridge into
+ * `MetricsCollector`, an OpenTelemetry adapter, a test double) without
+ * depending on this module's storage choices.
+ *
+ * `recordClaimAttempt`'s parameter type is the whole point of this interface:
+ * it is impossible to express "pass a workflow id here" without a type error,
+ * because the parameter is {@link WorkflowClaimAttemptOutcome}, not `string`.
+ */
+export interface WorkflowClaimMetricsRecorder {
+    /** Record one claim-attempt outcome. Increments only that outcome's series. */
+    recordClaimAttempt(outcome: WorkflowClaimAttemptOutcome): void;
+    /**
+     * Set the absolute count of workflows this engine currently holds a claim
+     * for. An absolute set (not a delta), matching the existing
+     * `MetricsCollector.gauge()` idiom in `src/observability/metrics.ts`. Must
+     * be a safe, non-negative integer.
+     */
+    setActiveClaims(count: number): void;
+    /** Record one renewal-failure occurrence. */
+    recordClaimRenewalFailure(): void;
+}
+/**
+ * In-memory implementation of {@link WorkflowClaimMetricsRecorder}, one per
+ * engine process — matching the ADR's "single counter/gauge per engine
+ * process" cardinality note for these three signals.
+ *
+ * @example
+ * ```ts
+ * import { WorkflowClaimMetricsCollector } from './workflow-claim-metrics.ts';
+ *
+ * const collector = new WorkflowClaimMetricsCollector();
+ * collector.recordClaimAttempt('acquired');
+ * collector.setActiveClaims(1);
+ * console.log(collector.snapshot().attempts.acquired); // 1
+ * ```
+ */
+export declare class WorkflowClaimMetricsCollector implements WorkflowClaimMetricsRecorder {
+    #private;
+    constructor();
+    recordClaimAttempt(outcome: WorkflowClaimAttemptOutcome): void;
+    setActiveClaims(count: number): void;
+    recordClaimRenewalFailure(): void;
+    /** Return a point-in-time snapshot of all three signals. */
+    snapshot(): WorkflowClaimMetricsSnapshot;
+    /** Clear all collected values back to zero. */
+    reset(): void;
+}
+/**
+ * Serialize a {@link WorkflowClaimMetricsSnapshot} as Prometheus text format,
+ * using the exact metric names ADR 0002 § Observability specifies. Every
+ * outcome always emits a line — including zero-valued ones — so a scraper
+ * sees a stable schema regardless of which outcomes have occurred yet,
+ * matching the stable-schema behavior of
+ * `serializeMetricsSnapshotForPrometheus` in `src/observability/metrics.ts`.
+ *
+ * @example
+ * ```ts
+ * import {
+ *   WorkflowClaimMetricsCollector,
+ *   serializeWorkflowClaimMetricsForPrometheus,
+ * } from './workflow-claim-metrics.ts';
+ *
+ * const collector = new WorkflowClaimMetricsCollector();
+ * collector.recordClaimAttempt('acquired');
+ * const body = serializeWorkflowClaimMetricsForPrometheus(collector.snapshot());
+ * console.log(body.includes('weft_workflow_claim_attempts_total{outcome="acquired"} 1'));
+ * ```
+ */
+export declare function serializeWorkflowClaimMetricsForPrometheus(snapshot: WorkflowClaimMetricsSnapshot): string;

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

@@ -0,0 +1,62 @@
+export const WORKFLOW_CLAIM_ATTEMPT_OUTCOMES = [
+  "acquired",
+  "takeover",
+  "lost_race",
+  "deposed",
+  "backoff_skipped"
+];
+function assertSafeNonNegativeInteger(value, label) {
+  if (!Number.isInteger(value) || !Number.isSafeInteger(value) || value < 0)
+    throw RangeError(`${label} must be a safe, non-negative integer; received ${String(value)}`);
+}
+function zeroFilledAttemptCounts() {
+  const counts = {};
+  for (const outcome of WORKFLOW_CLAIM_ATTEMPT_OUTCOMES)
+    counts[outcome] = 0;
+  return counts;
+}
+
+export class WorkflowClaimMetricsCollector {
+  #attempts;
+  #activeClaims;
+  #renewalFailures;
+  constructor() {
+    this.#attempts = zeroFilledAttemptCounts();
+    this.#activeClaims = 0;
+    this.#renewalFailures = 0;
+  }
+  recordClaimAttempt(outcome) {
+    this.#attempts[outcome] += 1;
+  }
+  setActiveClaims(count) {
+    assertSafeNonNegativeInteger(count, "activeClaims");
+    this.#activeClaims = count;
+  }
+  recordClaimRenewalFailure() {
+    this.#renewalFailures += 1;
+  }
+  snapshot() {
+    return {
+      attempts: { ...this.#attempts },
+      activeClaims: this.#activeClaims,
+      renewalFailures: this.#renewalFailures
+    };
+  }
+  reset() {
+    this.#attempts = zeroFilledAttemptCounts();
+    this.#activeClaims = 0;
+    this.#renewalFailures = 0;
+  }
+}
+export function serializeWorkflowClaimMetricsForPrometheus(snapshot) {
+  const lines = [
+    "# HELP weft_workflow_claim_attempts_total Total per-workflow ownership claim attempts, by outcome",
+    "# TYPE weft_workflow_claim_attempts_total counter"
+  ];
+  for (const outcome of WORKFLOW_CLAIM_ATTEMPT_OUTCOMES)
+    lines.push(`weft_workflow_claim_attempts_total{outcome="${outcome}"} ${snapshot.attempts[outcome]}`);
+  lines.push("# HELP weft_workflow_claims_active Workflows this engine currently holds a claim for", "# TYPE weft_workflow_claims_active gauge", `weft_workflow_claims_active ${snapshot.activeClaims}`, "# HELP weft_workflow_claim_renewal_failures_total Total per-workflow claim renewal failures", "# TYPE weft_workflow_claim_renewal_failures_total counter", `weft_workflow_claim_renewal_failures_total ${snapshot.renewalFailures}`);
+  return lines.join(`
+`) + `
+`;
+}

package/dist/core/engine/workflow-claim-reclaim-scan.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Storage-scan candidate discovery for the recurring reclaim pass described
+ * in [ADR 0002 § Reclaiming stranded claims](../../../documentation/contributing/architecture-decisions/0002-multiengine-per-workflow-ownership.md#reclaiming-stranded-claims).
+ *
+ * A single boot-time `recoverAll()` sweep only catches a stranded claim that
+ * happens to already be past its grace-adjusted expiry at boot. An engine
+ * that crashes (or whose graceful-shutdown release fails) later leaves its
+ * `wf-owner-holder:<id>` record behind for every OTHER engine to discover;
+ * nothing rescans for that unless something recurring does. This module is
+ * the discovery half of that recurring scan: enumerate every workflow id
+ * with a currently-persisted holder record, store-wide, so a caller can
+ * attempt `WorkflowClaimRegistry.takeover` against each one.
+ *
+ * **Deliberately not a liveness filter.** This module does not decode holder
+ * bytes or judge staleness — `WorkflowClaimRegistry.takeover` already does
+ * that with a fresh read at the moment of the attempt (see its own
+ * grace-adjusted `isWorkflowClaimExpired` check), and re-deciding it here
+ * from a possibly-stale scan read would be redundant at best and a source of
+ * a second, drifting judgment at worst. This is discovery only.
+ *
+ * **Ownerless-but-running workflows.** The holder-keyed scan above misses a
+ * real rolling-deploy shape: an incoming engine boots and runs its
+ * `recoverAll()` sweep WHILE an outgoing engine is still the live holder of
+ * some workflow — recovery correctly skips it, since the holder is not yet
+ * expired. If the outgoing engine then disposes gracefully, its
+ * `releaseAll()` DELETES that workflow's `wf-owner-holder:<id>` record
+ * (per the ADR's `release` row — the epoch is retained, only the holder
+ * goes). The workflow is now `running` in `WorkflowState` with no holder at
+ * all, and the holder-keyed scan above will never find it again — there is
+ * no `wf-owner-holder:<id>` key left to enumerate. The already-running
+ * incoming engine has nothing further to trigger a re-scan, so the workflow
+ * is stranded until an operator explicitly calls `recoverAll()`/`resume()`.
+ * This module closes that gap with a second scan over the `running`-status
+ * workflow-visibility index (`wf-idx-status:running:`), checking each
+ * candidate's holder key fresh and including only the genuinely holderless
+ * ones — bounded to the same cost class as the holder-keyed scan (one extra
+ * index prefix scan per pass, plus one point read per running-and-holderless
+ * candidate).
+ *
+ * **Workflows with no visibility-index entry at all (WFT-79 Finding 2).**
+ * The index-based scan above is itself incomplete on a Bun SQLite deployment
+ * that predates the workflow visibility indexes and has not yet run the
+ * one-time backfill (see
+ * [Workflow Visibility Backfill](../../../documentation/guides/workflow-visibility-backfill.md)):
+ * such a workflow has no `wf-idx-status:running:<id>` row to enumerate. If
+ * that workflow is the outgoing engine's live holder at the moment an
+ * incoming engine's `recoverAll()` sweep runs, recovery correctly skips it
+ * (the holder is not yet expired); if the outgoing engine then disposes
+ * gracefully, `releaseAll()` deletes the holder record and the workflow is
+ * left `running` with no holder AND no visibility-index entry — invisible to
+ * both scans above. Left there, it is stranded indefinitely: nothing else
+ * re-scans for it.
+ *
+ * This module closes that second gap with a bounded, cursor-rotated fallback
+ * scan directly over the authoritative `wf:<id>` workflow records (the same
+ * source `recoverAll()`'s own preflight already scans at boot — see
+ * `lifecycle/transition.ts`'s `preflightRecoverAll`), decoding each record
+ * and including only genuinely holderless `running` ones not already found
+ * by either scan above. This IS a store-wide operation and therefore more
+ * expensive than the index-based scans, so it is bounded per pass to
+ * {@link WORKFLOW_CLAIM_RECLAIM_AUTHORITATIVE_SCAN_LIMIT} records rather than
+ * scanning the entire keyspace on every call. A per-storage cursor (advanced
+ * past the last key read, and wrapped back to the start once a pass reaches
+ * the end of the keyspace) rotates the scanned window across passes, so a
+ * store with more un-backfilled workflows than the per-pass limit still gets
+ * full coverage over several reclaim-scan passes rather than only ever
+ * re-scanning the same lexicographically-first window. This fallback is
+ * expected to do genuine work only on deployments that have not yet run the
+ * visibility backfill; run that backfill to eliminate this scan's ongoing
+ * cost entirely.
+ *
+ * @module core/engine/workflow-claim-reclaim-scan
+ */
+import { type Storage } from '../../storage/interface.ts';
+/**
+ * Per-pass bound on the authoritative-record fallback scan
+ * ({@link listOwnerlessRunningCandidatesFromAuthoritativeRecords}). This
+ * fallback is a store-wide scan, unlike the two index-based scans above, so
+ * it is capped rather than run to exhaustion on every pass — see the module
+ * doc's "Workflows with no visibility-index entry at all" section for why
+ * the cap is safe (a per-storage cursor rotates the scanned window across
+ * passes, so a store with more un-backfilled workflows than this limit still
+ * gets full coverage over several passes).
+ */
+export declare const WORKFLOW_CLAIM_RECLAIM_AUTHORITATIVE_SCAN_LIMIT = 500;
+/**
+ * Full candidate discovery for one reclaim-scan pass: every workflow id with
+ * a currently-persisted holder record, every `running`-status workflow id
+ * with NO holder record at all found via the visibility index (see the
+ * module doc's "Ownerless-but-running workflows" section), and every
+ * `running`-status, holderless workflow id found by the bounded
+ * authoritative-record fallback for workflows with no visibility-index entry
+ * at all (see the module doc's "Workflows with no visibility-index entry at
+ * all" section) — excluding `excludeWorkflowIds` from all three.
+ */
+export declare function listWorkflowClaimReclaimCandidates(storage: Storage, excludeWorkflowIds: ReadonlySet<string>): Promise<string[]>;

package/dist/core/engine/workflow-claim-reclaim-scan.js

@@ -0,0 +1,66 @@
+import { KEYS, tryDecodeStorageKeyComponent } from "../../storage/interface.js";
+import { decodeWorkflowState } from "./validation.js";
+const RUNNING_STATUS = "running";
+export const WORKFLOW_CLAIM_RECLAIM_AUTHORITATIVE_SCAN_LIMIT = 500;
+const authoritativeScanCursors = new WeakMap;
+async function listHolderScanCandidates(storage, excludeWorkflowIds) {
+  const prefix = KEYS.workflowOwnerHolder(""), candidates = [];
+  for await (const [key] of storage.scan(prefix)) {
+    const workflowId = tryDecodeStorageKeyComponent(key.slice(prefix.length));
+    if (workflowId === null || excludeWorkflowIds.has(workflowId))
+      continue;
+    candidates.push(workflowId);
+  }
+  return candidates;
+}
+async function listOwnerlessRunningCandidates(storage, excludeWorkflowIds, seen) {
+  const prefix = KEYS.workflowVisibilityStatus(RUNNING_STATUS, ""), candidates = [];
+  for await (const [key] of storage.scan(prefix)) {
+    const workflowId = tryDecodeStorageKeyComponent(key.slice(prefix.length));
+    if (workflowId === null || excludeWorkflowIds.has(workflowId) || seen.has(workflowId) || candidates.includes(workflowId))
+      continue;
+    if (await storage.get(KEYS.workflowOwnerHolder(workflowId)) !== null)
+      continue;
+    candidates.push(workflowId);
+  }
+  return candidates;
+}
+async function classifyAuthoritativeScanEntry(storage, prefix, key, value, excludeWorkflowIds, seen, alreadyCollected) {
+  const workflowId = tryDecodeStorageKeyComponent(key.slice(prefix.length));
+  if (workflowId === null)
+    return null;
+  if (KEYS.workflow(workflowId) !== key)
+    return null;
+  if (excludeWorkflowIds.has(workflowId) || seen.has(workflowId) || alreadyCollected.has(workflowId))
+    return null;
+  let status;
+  try {
+    status = decodeWorkflowState(value).status;
+  } catch {
+    return null;
+  }
+  if (status !== RUNNING_STATUS)
+    return null;
+  if (await storage.get(KEYS.workflowOwnerHolder(workflowId)) !== null)
+    return null;
+  return workflowId;
+}
+async function listOwnerlessRunningCandidatesFromAuthoritativeRecords(storage, excludeWorkflowIds, seen) {
+  const prefix = KEYS.workflow(""), cursor = authoritativeScanCursors.get(storage), scanOptions = cursor === void 0 ? { limit: WORKFLOW_CLAIM_RECLAIM_AUTHORITATIVE_SCAN_LIMIT } : { limit: WORKFLOW_CLAIM_RECLAIM_AUTHORITATIVE_SCAN_LIMIT, gt: cursor }, candidates = [], collected = new Set;
+  let scannedCount = 0, lastKey;
+  for await (const [key, value] of storage.scan(prefix, scanOptions)) {
+    scannedCount += 1;
+    lastKey = key;
+    const workflowId = await classifyAuthoritativeScanEntry(storage, prefix, key, value, excludeWorkflowIds, seen, collected);
+    if (workflowId === null)
+      continue;
+    collected.add(workflowId);
+    candidates.push(workflowId);
+  }
+  authoritativeScanCursors.set(storage, scannedCount < WORKFLOW_CLAIM_RECLAIM_AUTHORITATIVE_SCAN_LIMIT ? void 0 : lastKey);
+  return candidates;
+}
+export async function listWorkflowClaimReclaimCandidates(storage, excludeWorkflowIds) {
+  const holderCandidates = await listHolderScanCandidates(storage, excludeWorkflowIds), ownerlessCandidates = await listOwnerlessRunningCandidates(storage, excludeWorkflowIds, new Set(holderCandidates)), authoritativeFallbackCandidates = await listOwnerlessRunningCandidatesFromAuthoritativeRecords(storage, excludeWorkflowIds, new Set([...holderCandidates, ...ownerlessCandidates]));
+  return [...holderCandidates, ...ownerlessCandidates, ...authoritativeFallbackCandidates];
+}

package/dist/core/engine/workflow-claim-reclaim-target.d.ts

@@ -0,0 +1,107 @@
+/**
+ * The reclaim-scan candidate-discovery and takeover-attempt machinery for
+ * `ownership: 'workflow-lease'` ([ADR 0002](../../../documentation/contributing/architecture-decisions/0002-multiengine-per-workflow-ownership.md)).
+ * Extracted from `ownership-bootstrap.ts` — which still composes this module's
+ * {@link createWorkflowClaimReclaimTarget} into the renewal task's
+ * `reclaimTarget` option — so that file stays under the repository's
+ * implementation-file-size ceiling as this seam grows disposal-quiescence and
+ * epoch-fenced-release handling on top of the original takeover-retry loop.
+ * This is a real responsibility boundary, not an arbitrary split: everything
+ * here is "how one engine discovers and attempts to reclaim a stranded
+ * workflow's claim," while `ownership-bootstrap.ts` keeps gate execution,
+ * registry/renewal-task construction, and the owner-side signal-poll seam.
+ *
+ * @module core/engine/workflow-claim-reclaim-target
+ */
+import type { Storage } from '../../storage/interface.ts';
+import type { WorkflowClaimMetricsCollector } from './workflow-claim-metrics.ts';
+import type { WorkflowClaimRegistry } from './workflow-claim-registry.ts';
+import type { WorkflowClaimReclaimTarget } from './workflow-claim-renewal-subpasses.ts';
+/** Bound on retrying a lost-race `takeover` CAS for one reclaim candidate within one pass — ADR 0002's `takeover` row. */
+export declare const WORKFLOW_CLAIM_TAKEOVER_MAX_ATTEMPTS = 5;
+/**
+ * A {@link WorkflowClaimReclaimTarget} with one additional, non-interface
+ * method: {@link markDisposing}. Structurally still a valid
+ * `WorkflowClaimReclaimTarget` (every caller that only knows that narrower
+ * type — e.g. `createWorkflowClaimRenewalTask`'s `reclaimTarget` option —
+ * keeps working unchanged), so existing tests that only exercise
+ * `listReclaimCandidateWorkflowIds`/`attemptWorkflowClaimTakeover` are
+ * unaffected by this addition.
+ */
+export type WorkflowClaimReclaimTargetHandle = WorkflowClaimReclaimTarget & {
+    /**
+     * Synchronously flip this target into "disposing" mode: every future
+     * `attemptWorkflowClaimTakeover` call becomes an immediate `'not-eligible'`
+     * no-op (no CAS attempted, no `onReclaimed` drive invoked), and
+     * `listReclaimCandidateWorkflowIds` returns `[]`. A reclaim attempt already
+     * past this checkpoint when disposal begins keeps running to its next
+     * checkpoint — every checkpoint after an `await` re-checks the flag — and,
+     * if it lands a takeover/acquire CAS after disposal was signaled, releases
+     * that claim immediately instead of driving it or leaving it held. See this
+     * module's doc and `ownership-bootstrap.ts`'s `bootstrapWorkflowLeaseOwnership`
+     * for how this is wired to `WorkflowClaimRenewalTask.stop()`.
+     *
+     * Idempotent. Calling this before any pass has started simply prevents one
+     * from ever discovering or attempting a candidate.
+     */
+    markDisposing(): void;
+};
+/**
+ * Adapt a {@link WorkflowClaimRegistry} plus `storage` to the renewal task's
+ * {@link WorkflowClaimReclaimTarget} contract. Candidate discovery excludes
+ * this engine's own currently-held ids (`registry.listHeldWorkflowIds()`) —
+ * see `workflow-claim-reclaim-scan.ts`'s doc for why — then adds back any
+ * workflow this engine holds but whose `onReclaimed` drive previously
+ * failed (see `driveReclaimedWorkflow` below). `attemptWorkflowClaimTakeover`
+ * retries a `'lost-race'` CAS, bounded at {@link WORKFLOW_CLAIM_TAKEOVER_MAX_ATTEMPTS}
+ * per the ADR, and records `weft_workflow_claim_attempts_total{outcome="backoff_skipped"}`
+ * the moment the registry's own anti-thrash cooldown suppresses an attempt —
+ * the one `WorkflowClaimAttemptOutcome` this stage wires; the other four
+ * remain unrecorded by design (see the ADR's Observability section for the
+ * full set — that wiring is a later stage's work).
+ *
+ * **A failed `onReclaimed` drive is retried in place, never released.**
+ * Releasing on failure was considered and rejected: `onReclaimed` (bound to
+ * `resumeWorkflowFromStorage` in production) can throw AFTER
+ * `relaunchInlineWorkflowAfterResume` has already adopted the generator —
+ * `InlineExecutionStrategy#continueWorkflow` fires the drive and returns
+ * without awaiting it, so a caught error here does not prove no local user
+ * code started. Releasing the claim in that state would let another engine
+ * `acquire` it while this engine may still be mid-turn — the exact
+ * duplicate-execution hazard ADR 0002 exists to close, just re-opened via
+ * the failure path instead of the happy path. Retrying in place keeps the
+ * claim (and its write fence) intact and simply asks `onReclaimed` again on
+ * a later pass, via `pendingRedriveWorkflowIds` below.
+ *
+ * **Discovered and pending-redrive candidates are merged through a `Set`
+ * (WFT-79 Finding 4).** After a failed redrive loses this engine's local
+ * claim (a renewal loss between the failed drive and the next pass), the
+ * same workflow id can surface BOTH through `listWorkflowClaimReclaimCandidates`
+ * (as a foreign holder, since `registry.listHeldWorkflowIds()` no longer
+ * excludes it) AND through `pendingRedriveWorkflowIds`. Without deduping,
+ * one renewal pass would call `attemptWorkflowClaimTakeover` for that id
+ * twice, and each call independently retries up to
+ * {@link WORKFLOW_CLAIM_TAKEOVER_MAX_ATTEMPTS} — doubling the advertised
+ * per-pass bound to 10 attempts for that workflow, exactly when contention is
+ * already highest (deposition churn).
+ *
+ * **Disposal quiescence (WFT-79 Finding 2).** {@link WorkflowClaimReclaimTargetHandle.markDisposing}
+ * closes two related hazards when disposal overlaps an in-flight
+ * interval-driven pass: a late-landing takeover/acquire CAS stranding a claim
+ * this engine will never renew again, and a late `onReclaimed` drive running
+ * against a torn-down host. Every checkpoint that follows an `await` inside
+ * this target re-checks the flag; a CAS that lands after disposal was
+ * signaled is released immediately rather than driven, so the claim never
+ * outlives this engine's own best-effort `WorkflowClaimRegistry.releaseAll()`
+ * call regardless of the ordering race between them.
+ */
+export declare function createWorkflowClaimReclaimTarget(registry: WorkflowClaimRegistry, storage: Storage, metrics: WorkflowClaimMetricsCollector, onReclaimed?: (workflowId: string) => Promise<void>, 
+/**
+ * Optional workflow-type eligibility check, consulted before this engine
+ * ever attempts a fresh takeover/acquire CAS for a candidate (never for a
+ * `redriveAlreadyHeldClaim` retry, since that claim already passed this
+ * check when it was first taken). Omitted (the default) skips the check —
+ * every existing caller/test that does not care about mixed workflow-type
+ * fleets keeps working unchanged.
+ */
+isTypeRegistered?: (workflowType: string) => boolean): WorkflowClaimReclaimTargetHandle;

package/dist/core/engine/workflow-claim-reclaim-target.js

@@ -0,0 +1,155 @@
+import { KEYS } from "../../storage/interface.js";
+import { decodeWorkflowState } from "./validation.js";
+import { listWorkflowClaimReclaimCandidates } from "./workflow-claim-reclaim-scan.js";
+export const WORKFLOW_CLAIM_TAKEOVER_MAX_ATTEMPTS = 5;
+async function isWorkflowStillRunning(storage, workflowId) {
+  const bytes = await storage.get(KEYS.workflow(workflowId));
+  if (bytes === null)
+    return !1;
+  try {
+    return decodeWorkflowState(bytes).status === "running";
+  } catch {
+    return !1;
+  }
+}
+async function isWorkflowTypeRegistered(storage, workflowId, isTypeRegistered) {
+  const bytes = await storage.get(KEYS.workflow(workflowId));
+  if (bytes === null)
+    return !1;
+  try {
+    return isTypeRegistered(decodeWorkflowState(bytes).type);
+  } catch {
+    return !1;
+  }
+}
+export function createWorkflowClaimReclaimTarget(registry, storage, metrics, onReclaimed, isTypeRegistered) {
+  const pendingRedriveWorkflowIds = new Map;
+  let disposing = !1;
+  async function driveReclaimedWorkflow(workflowId, epoch) {
+    if (onReclaimed === void 0) {
+      pendingRedriveWorkflowIds.delete(workflowId);
+      return { status: "reclaimed" };
+    }
+    try {
+      await onReclaimed(workflowId);
+      pendingRedriveWorkflowIds.delete(workflowId);
+      return { status: "reclaimed" };
+    } catch (error) {
+      pendingRedriveWorkflowIds.set(workflowId, epoch);
+      throw error;
+    }
+  }
+  async function releaseClaimAcquiredWhileDisposing(workflowId) {
+    await registry.release(workflowId);
+  }
+  async function confirmStillRunningOrReleaseFreshClaim(workflowId, acquiredEpoch) {
+    if (await isWorkflowStillRunning(storage, workflowId))
+      return !0;
+    if (registry.currentEpoch(workflowId) === acquiredEpoch)
+      await registry.release(workflowId);
+    return !1;
+  }
+  async function redriveAlreadyHeldClaim(workflowId, expectedEpoch) {
+    if (disposing)
+      return { status: "not-eligible" };
+    if (!await isWorkflowStillRunning(storage, workflowId)) {
+      pendingRedriveWorkflowIds.delete(workflowId);
+      if (registry.currentEpoch(workflowId) === expectedEpoch)
+        await registry.release(workflowId);
+      return { status: "not-eligible" };
+    }
+    if (disposing)
+      return { status: "not-eligible" };
+    return await driveReclaimedWorkflow(workflowId, expectedEpoch);
+  }
+  async function acquireOwnerlessRunningClaim(workflowId) {
+    if (disposing)
+      return { status: "not-eligible" };
+    if (!await isWorkflowStillRunning(storage, workflowId))
+      return { status: "not-eligible" };
+    if (disposing)
+      return { status: "not-eligible" };
+    const acquireResult = await registry.acquire(workflowId);
+    if (acquireResult.status === "lost-race") {
+      metrics.recordClaimAttempt("lost_race");
+      return "retry";
+    }
+    metrics.recordClaimAttempt("acquired");
+    if (disposing) {
+      await releaseClaimAcquiredWhileDisposing(workflowId);
+      return { status: "not-eligible" };
+    }
+    if (!await confirmStillRunningOrReleaseFreshClaim(workflowId, acquireResult.epoch))
+      return { status: "not-eligible" };
+    return await driveReclaimedWorkflow(workflowId, acquireResult.epoch);
+  }
+  async function handleTakeoverAcquired(workflowId, acquiredEpoch) {
+    metrics.recordClaimAttempt("takeover");
+    if (disposing) {
+      await releaseClaimAcquiredWhileDisposing(workflowId);
+      return { status: "not-eligible" };
+    }
+    if (!await confirmStillRunningOrReleaseFreshClaim(workflowId, acquiredEpoch))
+      return { status: "not-eligible" };
+    return await driveReclaimedWorkflow(workflowId, acquiredEpoch);
+  }
+  async function isEligibleForFreshTakeover(workflowId) {
+    if (isTypeRegistered === void 0)
+      return !0;
+    return await isWorkflowTypeRegistered(storage, workflowId, isTypeRegistered);
+  }
+  async function takeoverWithRetries(workflowId) {
+    if (!await isEligibleForFreshTakeover(workflowId))
+      return { status: "not-eligible" };
+    for (let attempt = 0;attempt < WORKFLOW_CLAIM_TAKEOVER_MAX_ATTEMPTS; attempt += 1) {
+      if (disposing)
+        return { status: "not-eligible" };
+      const result = await registry.takeover(workflowId);
+      switch (result.status) {
+        case "acquired":
+          return await handleTakeoverAcquired(workflowId, result.epoch);
+        case "backoff-skipped":
+          metrics.recordClaimAttempt("backoff_skipped");
+          return { status: "backoff-skipped" };
+        case "not-expired":
+          return { status: "not-eligible" };
+        case "no-claim": {
+          const outcome = await acquireOwnerlessRunningClaim(workflowId);
+          if (outcome === "retry")
+            continue;
+          return outcome;
+        }
+        case "lost-race":
+          metrics.recordClaimAttempt("lost_race");
+          continue;
+      }
+    }
+    return { status: "lost-race" };
+  }
+  return {
+    async listReclaimCandidateWorkflowIds() {
+      if (disposing)
+        return [];
+      const discovered = await listWorkflowClaimReclaimCandidates(storage, new Set(registry.listHeldWorkflowIds()));
+      return [...new Set([...discovered, ...pendingRedriveWorkflowIds.keys()])];
+    },
+    async attemptWorkflowClaimTakeover(workflowId) {
+      if (disposing)
+        return { status: "not-eligible" };
+      const currentEpoch = registry.currentEpoch(workflowId);
+      if (currentEpoch !== null) {
+        const pendingRedriveEpoch = pendingRedriveWorkflowIds.get(workflowId);
+        if (pendingRedriveEpoch !== void 0 && pendingRedriveEpoch !== currentEpoch) {
+          pendingRedriveWorkflowIds.delete(workflowId);
+          return await takeoverWithRetries(workflowId);
+        }
+        return await redriveAlreadyHeldClaim(workflowId, currentEpoch);
+      }
+      pendingRedriveWorkflowIds.delete(workflowId);
+      return await takeoverWithRetries(workflowId);
+    },
+    markDisposing() {
+      disposing = !0;
+    }
+  };
+}