@nodii/retry 0.0.0 → 0.1.0

package/dist/fleet-policies.d.ts

@@ -0,0 +1,220 @@
+import type { RetryPolicy } from "./policy.js";
+export interface FleetSite {
+    /** Where the hand-rolled implementation lives on origin/main. */
+    readonly source: string;
+    /** The policy that reproduces it (or, where noted, corrects it). */
+    readonly policy: RetryPolicy;
+    /** What the site treats as retryable. */
+    readonly retryable: string;
+    /** Behaviour-preserving, or a deliberate change? */
+    readonly migration: string;
+}
+export declare const FLEET_POLICIES: {
+    readonly "approval.consumer": {
+        readonly source: "ts/approval/src/consumer.ts:161 (BullMQ settings.backoffStrategy)";
+        readonly policy: {
+            readonly maxAttempts: 5;
+            readonly baseDelayMs: 250;
+            readonly multiplier: 2;
+            readonly maxDelayMs: 60000;
+            readonly growth: "exponential";
+            readonly jitter: "none";
+            readonly allowJitterAboveCap: false;
+        };
+        readonly retryable: "anything the handler throws; terminal at attemptsMade+1 >= consumerMaxRetries (consumer.ts:621 — the post-increment test, correct)";
+        readonly migration: "bullmqBackoffStrategy(FLEET_POLICIES['approval.consumer'].policy, { attemptOffset: 1 }) is byte-preserving. attemptOffset 0 (the correct index) makes the first retry 250ms instead of 500ms — a deliberate change, and the one worth taking, since 250ms is what the code claims its base is.";
+    };
+    readonly "approval.streamsReader": {
+        readonly source: "ts/approval/src/streams-reader.ts:389 (loop-error backoff)";
+        readonly policy: {
+            readonly maxAttempts: 0;
+            readonly baseDelayMs: 200;
+            readonly multiplier: 1;
+            readonly maxDelayMs: 200;
+            readonly growth: "exponential";
+            readonly jitter: "none";
+            readonly allowJitterAboveCap: false;
+        };
+        readonly retryable: "any XREADGROUP / handler throw; the loop never gives up";
+        readonly migration: "Behaviour-preserving as written. DELIBERATE CHANGE worth making: multiplier 2 + cap 30s + equal jitter, so a long Redis outage stops issuing 5 commands/second per pod.";
+    };
+    readonly "onboarding.submitLead": {
+        readonly source: "ts/onboarding/src/submit/client.ts:37 (MAX_ATTEMPTS/RETRY_DELAYS_MS)";
+        readonly policy: {
+            readonly maxAttempts: 3;
+            readonly baseDelayMs: 1000;
+            readonly multiplier: 2;
+            readonly maxDelayMs: number;
+            readonly growth: "exponential";
+            readonly jitter: "none";
+            readonly allowJitterAboveCap: false;
+        };
+        readonly retryable: "network error + request timeout + HTTP 5xx. NOT: 403, 409, 422, 429 (429 is caller-decides, deliberately not auto-retried)";
+        readonly migration: "Behaviour-preserving: the [1000, 2000] literal table IS base 1000 × 2^(n-1) for n = 1,2. Retryability moves into a shouldRetry predicate; the 403/409/422 paths become NonRetryableError throws.";
+    };
+    readonly "onboarding.submitSignup": {
+        readonly source: "ts/onboarding/src/submit/signup-client.ts:44 (verbatim copy of the above)";
+        readonly policy: {
+            readonly maxAttempts: 3;
+            readonly baseDelayMs: 1000;
+            readonly multiplier: 2;
+            readonly maxDelayMs: number;
+            readonly growth: "exponential";
+            readonly jitter: "none";
+            readonly allowJitterAboveCap: false;
+        };
+        readonly retryable: "identical to onboarding.submitLead";
+        readonly migration: "Behaviour-preserving. This site and submitLead are a literal duplicate — one shared policy constant removes the copy.";
+    };
+    readonly "outboxDispatcher.claimCooldown": {
+        readonly source: "ts/outbox-dispatcher/src/sql-builders.ts:39 (`last_attempt_at < now() - interval '1 minute' * publish_attempts`) + define-dispatcher.ts:18 (DEFAULT_PUBLISH_MAX_ATTEMPTS)";
+        readonly policy: {
+            readonly maxAttempts: 8;
+            readonly baseDelayMs: 60000;
+            readonly multiplier: 1;
+            readonly maxDelayMs: number;
+            readonly growth: "linear";
+            readonly jitter: "none";
+            readonly allowJitterAboveCap: false;
+        };
+        readonly retryable: "every publish failure. D401: the row is NEVER deleted and never DLQ'd; maxAttempts caps RE-CLAIM only, and the 24h sweep raises the M17 page.";
+        readonly migration: "NOT a drop-in: the delay is enforced by a SQL predicate, not a sleep. The package's role here is to GENERATE the interval expression / validate the constants, so the TS, Python and Go ports of the dispatcher cannot drift apart. Behaviour-preserving if the SQL keeps `interval '1 minute' * publish_attempts`.";
+    };
+    readonly "outboxDispatcher.drainLoop": {
+        readonly source: "ts/outbox-dispatcher/src/drainer.ts:421 (`sleep(Math.min(pollMs, 200))` on error)";
+        readonly policy: {
+            readonly maxAttempts: 0;
+            readonly baseDelayMs: 200;
+            readonly multiplier: 1;
+            readonly maxDelayMs: 200;
+            readonly growth: "exponential";
+            readonly jitter: "none";
+            readonly allowJitterAboveCap: false;
+        };
+        readonly retryable: "any drain-iteration throw; the loop never gives up";
+        readonly migration: "Behaviour-preserving. Same accidental-divergence class as approval.streamsReader and telemetry.outboxDispatcherLoop — three fixed error sleeps, three different rationales, no jitter anywhere.";
+    };
+    readonly "replicaConsumer.coldStart": {
+        readonly source: "ts/replica-consumer/src/start.ts:242 (coldStartBackoffMs) + DEFAULT_COLD_START_RETRY";
+        readonly policy: {
+            readonly maxAttempts: 0;
+            readonly baseDelayMs: 1000;
+            readonly multiplier: 2;
+            readonly maxDelayMs: 30000;
+            readonly growth: "exponential";
+            readonly jitter: {
+                readonly kind: "proportional";
+                readonly pct: 0.2;
+            };
+            readonly allowJitterAboveCap: true;
+        };
+        readonly retryable: "every bootstrap failure (fail-soft: the process stays alive)";
+        readonly migration: "Byte-preserving with allowJitterAboveCap: true — the jitter formula `capped·(1 + 0.2·(2r−1))` is identical to this package's proportional strategy for the same RNG draw. Flipping it to false is a DELIBERATE change that makes the declared 30s cap actually hold (max delay 36s → 30s).";
+    };
+    readonly "replicaConsumer.declaredApplyBackoff": {
+        readonly source: "ts/replica-consumer/src/define-replica.ts:294 + init.ts:17 + types.ts:334 (RetryBackoff) — DEAD CONFIG, never read";
+        readonly policy: {
+            readonly maxAttempts: 5;
+            readonly baseDelayMs: 100;
+            readonly multiplier: 2;
+            readonly maxDelayMs: 30000;
+            readonly growth: "exponential";
+            readonly jitter: {
+                readonly kind: "proportional";
+                readonly pct: 0.25;
+            };
+            readonly allowJitterAboveCap: false;
+        };
+        readonly retryable: "n/a — nothing reads this object";
+        readonly migration: "DELETE, do not migrate. `retryBackoff` is constructed in two places and read in ZERO (`git grep retryBackoff -- ts/` → 3 hits, all declarations). Migrating it would ACTIVATE a delay that has never run in production. Either wire it deliberately as a separate change, or drop the field.";
+    };
+    readonly "replicaConsumer.applyRetry": {
+        readonly source: "ts/replica-consumer/src/worker/streams-worker.ts:1120 (attempt >= replica.retryMaxAttempts)";
+        readonly policy: {
+            readonly maxAttempts: 5;
+            readonly baseDelayMs: 0;
+            readonly multiplier: 1;
+            readonly maxDelayMs: 0;
+            readonly growth: "exponential";
+            readonly jitter: "none";
+            readonly allowJitterAboveCap: false;
+        };
+        readonly retryable: "all apply errors incl. NoBaseRowForPartial; DLQ at the budget. Excluded: UnknownAggregateKind (process-fatal) and trimmed phantom entries (tombstoned).";
+        readonly migration: "Counting only. The DELAY between attempts is Redis PEL redelivery + the XCLAIM reaper, not a sleep — baseDelayMs 0 records that honestly. Migrate `isFinalAttempt(attempt, maxAttempts)` for the boundary test and leave the redelivery timing alone.";
+    };
+    readonly "roleCatalog.publishAtBoot": {
+        readonly source: "ts/role-catalog/src/publish.ts:203 (computeBackoff)";
+        readonly policy: {
+            readonly maxAttempts: 30;
+            readonly baseDelayMs: 100;
+            readonly multiplier: 2;
+            readonly maxDelayMs: 30000;
+            readonly growth: "exponential";
+            readonly jitter: {
+                readonly kind: "proportional";
+                readonly pct: 0.125;
+            };
+            readonly allowJitterAboveCap: true;
+        };
+        readonly retryable: "gRPC UNAVAILABLE only. FAILED_PRECONDITION → fail-fast; every other error → rethrow immediately.";
+        readonly migration: "Byte-preserving up to integer rounding: `randomFn()*0.25 + 0.875` is exactly `1 + 0.125·(2r−1)`, so the same RNG draw yields the same multiplier. This package rounds to whole ms (setTimeout truncates anyway). This is the ONLY surveyed site that already injects `sleepFn` + `randomFn`, i.e. the only one that was deterministically testable before this package existed.";
+    };
+    readonly "saga.participantWorkerLoop": {
+        readonly source: "ts/saga/src/participant-worker.ts:351 (sleep(250) on loop error)";
+        readonly policy: {
+            readonly maxAttempts: 0;
+            readonly baseDelayMs: 250;
+            readonly multiplier: 1;
+            readonly maxDelayMs: 250;
+            readonly growth: "exponential";
+            readonly jitter: "none";
+            readonly allowJitterAboveCap: false;
+        };
+        readonly retryable: "any XREADGROUP / handleMessage throw; the loop never gives up";
+        readonly migration: "Behaviour-preserving. 250ms here vs 200ms in the two sibling loops is the clearest ACCIDENTAL divergence in the survey — three loops, same failure mode, three different constants.";
+    };
+    readonly "telemetry.streamsWorkerRetry": {
+        readonly source: "ts/telemetry/src/worker/streams-worker.ts:776 (attempt < retryMaxAttempts) + DEFAULT_RETRY_MAX";
+        readonly policy: {
+            readonly maxAttempts: 3;
+            readonly baseDelayMs: 0;
+            readonly multiplier: 1;
+            readonly maxDelayMs: 0;
+            readonly growth: "exponential";
+            readonly jitter: "none";
+            readonly allowJitterAboveCap: false;
+        };
+        readonly retryable: "poison-tagged apply errors only; infra errors (fence lost, store down) leave the entry in the PEL WITHOUT bumping the ledger";
+        readonly migration: "Counting only, like replicaConsumer.applyRetry. `attempt < max` (here) and `attempt >= max` (replica) are complementary forms of the SAME 1-based convention — both dead-letter on attempt N. Migrating both to isFinalAttempt() removes the need to prove that each time.";
+    };
+    readonly "telemetry.outboxDispatcherLoop": {
+        readonly source: "ts/telemetry/src/worker/outbox-dispatcher.ts:262 (setTimeout(min(pollMs, 200)))";
+        readonly policy: {
+            readonly maxAttempts: 0;
+            readonly baseDelayMs: 200;
+            readonly multiplier: 1;
+            readonly maxDelayMs: 200;
+            readonly growth: "exponential";
+            readonly jitter: "none";
+            readonly allowJitterAboveCap: false;
+        };
+        readonly retryable: "any drain-iteration throw";
+        readonly migration: "Behaviour-preserving. Duplicate of outboxDispatcher.drainLoop.";
+    };
+    readonly "telemetry.singleActiveLeaseSelfHeal": {
+        readonly source: "ts/telemetry/src/worker/single-active-lease.ts:714 (retryMs = max(1000, ttlMs/2))";
+        readonly policy: {
+            readonly maxAttempts: 0;
+            readonly baseDelayMs: 15000;
+            readonly multiplier: 1;
+            readonly maxDelayMs: 15000;
+            readonly growth: "exponential";
+            readonly jitter: "none";
+            readonly allowJitterAboveCap: false;
+        };
+        readonly retryable: "lease not held / Redis down — retries on a fixed tick forever";
+        readonly migration: "DELIBERATE CHANGE recommended: add equal jitter. This is the one surveyed site with a genuine thundering-herd shape — every replica of a service self-heals on the SAME ttl/2 tick with zero jitter, so after a Redis blip they all hammer the acquire path in lockstep. Preserve the ttl/2 base; jitter the tick.";
+    };
+};
+export type FleetSiteId = keyof typeof FLEET_POLICIES;
+//# sourceMappingURL=fleet-policies.d.ts.map

package/dist/fleet-policies.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fleet-policies.d.ts","sourceRoot":"","sources":["../src/fleet-policies.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE/C,MAAM,WAAW,SAAS;IACxB,iEAAiE;IACjE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,oEAAoE;IACpE,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAC7B,yCAAyC;IACzC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,oDAAoD;IACpD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAID,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAsPmB,CAAC;AAE/C,MAAM,MAAM,WAAW,GAAG,MAAM,OAAO,cAAc,CAAC"}

package/dist/fleet-policies.js

@@ -0,0 +1,232 @@
+// The survey, as executable constants.
+//
+// Every entry below is the REAL parameter set of a hand-rolled backoff found
+// in ts/* on origin/main at 8af8e137 — not a suggestion. `tests/fleet-parity.
+// test.ts` asserts this package reproduces each site's observed delay sequence,
+// which is what makes "the union of what they actually do is the requirements
+// document" a check rather than a claim.
+//
+// These are also the drop-in targets for the sequenced migration PR: a call
+// site migrates by passing `FLEET_POLICIES["<id>"]` and deleting its local
+// math. Each entry's `migration` note says whether that is behaviour-preserving
+// or a deliberate change.
+const UNCAPPED = Number.POSITIVE_INFINITY;
+export const FLEET_POLICIES = {
+    // ── 1 ──────────────────────────────────────────────────────────────────
+    "approval.consumer": {
+        source: "ts/approval/src/consumer.ts:161 (BullMQ settings.backoffStrategy)",
+        policy: {
+            maxAttempts: 5, // DEFAULT_CONSUMER_MAX_RETRIES (ts/approval/src/types.ts:628)
+            baseDelayMs: 250,
+            multiplier: 2,
+            maxDelayMs: 60_000,
+            growth: "exponential",
+            jitter: "none",
+            allowJitterAboveCap: false,
+        },
+        retryable: "anything the handler throws; terminal at attemptsMade+1 >= consumerMaxRetries (consumer.ts:621 — the post-increment test, correct)",
+        migration: "bullmqBackoffStrategy(FLEET_POLICIES['approval.consumer'].policy, { attemptOffset: 1 }) is byte-preserving. attemptOffset 0 (the correct index) makes the first retry 250ms instead of 500ms — a deliberate change, and the one worth taking, since 250ms is what the code claims its base is.",
+    },
+    // ── 2 ──────────────────────────────────────────────────────────────────
+    "approval.streamsReader": {
+        source: "ts/approval/src/streams-reader.ts:389 (loop-error backoff)",
+        policy: {
+            maxAttempts: 0, // loop retries forever
+            baseDelayMs: 200,
+            multiplier: 1, // constant
+            maxDelayMs: 200,
+            growth: "exponential",
+            jitter: "none",
+            allowJitterAboveCap: false,
+        },
+        retryable: "any XREADGROUP / handler throw; the loop never gives up",
+        migration: "Behaviour-preserving as written. DELIBERATE CHANGE worth making: multiplier 2 + cap 30s + equal jitter, so a long Redis outage stops issuing 5 commands/second per pod.",
+    },
+    // ── 3 + 4 ──────────────────────────────────────────────────────────────
+    "onboarding.submitLead": {
+        source: "ts/onboarding/src/submit/client.ts:37 (MAX_ATTEMPTS/RETRY_DELAYS_MS)",
+        policy: {
+            maxAttempts: 3,
+            baseDelayMs: 1000,
+            multiplier: 2,
+            maxDelayMs: UNCAPPED, // the 2-entry table never reaches a cap
+            growth: "exponential",
+            jitter: "none",
+            allowJitterAboveCap: false,
+        },
+        retryable: "network error + request timeout + HTTP 5xx. NOT: 403, 409, 422, 429 (429 is caller-decides, deliberately not auto-retried)",
+        migration: "Behaviour-preserving: the [1000, 2000] literal table IS base 1000 × 2^(n-1) for n = 1,2. Retryability moves into a shouldRetry predicate; the 403/409/422 paths become NonRetryableError throws.",
+    },
+    "onboarding.submitSignup": {
+        source: "ts/onboarding/src/submit/signup-client.ts:44 (verbatim copy of the above)",
+        policy: {
+            maxAttempts: 3,
+            baseDelayMs: 1000,
+            multiplier: 2,
+            maxDelayMs: UNCAPPED,
+            growth: "exponential",
+            jitter: "none",
+            allowJitterAboveCap: false,
+        },
+        retryable: "identical to onboarding.submitLead",
+        migration: "Behaviour-preserving. This site and submitLead are a literal duplicate — one shared policy constant removes the copy.",
+    },
+    // ── 5 ──────────────────────────────────────────────────────────────────
+    "outboxDispatcher.claimCooldown": {
+        source: "ts/outbox-dispatcher/src/sql-builders.ts:39 (`last_attempt_at < now() - interval '1 minute' * publish_attempts`) + define-dispatcher.ts:18 (DEFAULT_PUBLISH_MAX_ATTEMPTS)",
+        policy: {
+            maxAttempts: 8,
+            baseDelayMs: 60_000,
+            multiplier: 1, // unused by linear growth
+            maxDelayMs: UNCAPPED, // 8 attempts → 8 min max cooldown; no explicit cap
+            growth: "linear", // 1, 2, 3, … minutes — the reason `growth` exists
+            jitter: "none",
+            allowJitterAboveCap: false,
+        },
+        retryable: "every publish failure. D401: the row is NEVER deleted and never DLQ'd; maxAttempts caps RE-CLAIM only, and the 24h sweep raises the M17 page.",
+        migration: "NOT a drop-in: the delay is enforced by a SQL predicate, not a sleep. The package's role here is to GENERATE the interval expression / validate the constants, so the TS, Python and Go ports of the dispatcher cannot drift apart. Behaviour-preserving if the SQL keeps `interval '1 minute' * publish_attempts`.",
+    },
+    // ── 6 ──────────────────────────────────────────────────────────────────
+    "outboxDispatcher.drainLoop": {
+        source: "ts/outbox-dispatcher/src/drainer.ts:421 (`sleep(Math.min(pollMs, 200))` on error)",
+        policy: {
+            maxAttempts: 0,
+            baseDelayMs: 200,
+            multiplier: 1,
+            maxDelayMs: 200,
+            growth: "exponential",
+            jitter: "none",
+            allowJitterAboveCap: false,
+        },
+        retryable: "any drain-iteration throw; the loop never gives up",
+        migration: "Behaviour-preserving. Same accidental-divergence class as approval.streamsReader and telemetry.outboxDispatcherLoop — three fixed error sleeps, three different rationales, no jitter anywhere.",
+    },
+    // ── 7 ──────────────────────────────────────────────────────────────────
+    "replicaConsumer.coldStart": {
+        source: "ts/replica-consumer/src/start.ts:242 (coldStartBackoffMs) + DEFAULT_COLD_START_RETRY",
+        policy: {
+            maxAttempts: 0, // indefinite — dropping a backfill silently is worse
+            baseDelayMs: 1000,
+            multiplier: 2,
+            maxDelayMs: 30_000,
+            growth: "exponential",
+            jitter: { kind: "proportional", pct: 0.2 },
+            // The live code jitters AFTER the cap and never re-clamps, so it can
+            // sleep 36s against a declared 30s cap. `true` preserves that.
+            allowJitterAboveCap: true,
+        },
+        retryable: "every bootstrap failure (fail-soft: the process stays alive)",
+        migration: "Byte-preserving with allowJitterAboveCap: true — the jitter formula `capped·(1 + 0.2·(2r−1))` is identical to this package's proportional strategy for the same RNG draw. Flipping it to false is a DELIBERATE change that makes the declared 30s cap actually hold (max delay 36s → 30s).",
+    },
+    // ── 8 ──────────────────────────────────────────────────────────────────
+    "replicaConsumer.declaredApplyBackoff": {
+        source: "ts/replica-consumer/src/define-replica.ts:294 + init.ts:17 + types.ts:334 (RetryBackoff) — DEAD CONFIG, never read",
+        policy: {
+            maxAttempts: 5,
+            baseDelayMs: 100,
+            multiplier: 2,
+            maxDelayMs: 30_000,
+            growth: "exponential",
+            // `jitterPct: 25` in the source. Read as a FRACTION (the unit its
+            // sibling start.ts uses) that is 2500%; read as a percent it is 0.25.
+            // Encoded as 0.25 here because that is the only reading that is not
+            // absurd — but the field is ambiguous BY CONSTRUCTION and this package
+            // rejects a pct > 1 outright so the ambiguity cannot survive migration.
+            jitter: { kind: "proportional", pct: 0.25 },
+            allowJitterAboveCap: false,
+        },
+        retryable: "n/a — nothing reads this object",
+        migration: "DELETE, do not migrate. `retryBackoff` is constructed in two places and read in ZERO (`git grep retryBackoff -- ts/` → 3 hits, all declarations). Migrating it would ACTIVATE a delay that has never run in production. Either wire it deliberately as a separate change, or drop the field.",
+    },
+    // ── 9 ──────────────────────────────────────────────────────────────────
+    "replicaConsumer.applyRetry": {
+        source: "ts/replica-consumer/src/worker/streams-worker.ts:1120 (attempt >= replica.retryMaxAttempts)",
+        policy: {
+            maxAttempts: 5,
+            baseDelayMs: 0, // no library-controlled delay — see below
+            multiplier: 1,
+            maxDelayMs: 0,
+            growth: "exponential",
+            jitter: "none",
+            allowJitterAboveCap: false,
+        },
+        retryable: "all apply errors incl. NoBaseRowForPartial; DLQ at the budget. Excluded: UnknownAggregateKind (process-fatal) and trimmed phantom entries (tombstoned).",
+        migration: "Counting only. The DELAY between attempts is Redis PEL redelivery + the XCLAIM reaper, not a sleep — baseDelayMs 0 records that honestly. Migrate `isFinalAttempt(attempt, maxAttempts)` for the boundary test and leave the redelivery timing alone.",
+    },
+    // ── 10 ─────────────────────────────────────────────────────────────────
+    "roleCatalog.publishAtBoot": {
+        source: "ts/role-catalog/src/publish.ts:203 (computeBackoff)",
+        policy: {
+            maxAttempts: 30, // ~5 min worst case
+            baseDelayMs: 100,
+            multiplier: 2,
+            maxDelayMs: 30_000,
+            growth: "exponential",
+            jitter: { kind: "proportional", pct: 0.125 }, // randomFn()*0.25 + 0.875
+            allowJitterAboveCap: true, // jitter applied after the cap, never re-clamped
+        },
+        retryable: "gRPC UNAVAILABLE only. FAILED_PRECONDITION → fail-fast; every other error → rethrow immediately.",
+        migration: "Byte-preserving up to integer rounding: `randomFn()*0.25 + 0.875` is exactly `1 + 0.125·(2r−1)`, so the same RNG draw yields the same multiplier. This package rounds to whole ms (setTimeout truncates anyway). This is the ONLY surveyed site that already injects `sleepFn` + `randomFn`, i.e. the only one that was deterministically testable before this package existed.",
+    },
+    // ── 11 ─────────────────────────────────────────────────────────────────
+    "saga.participantWorkerLoop": {
+        source: "ts/saga/src/participant-worker.ts:351 (sleep(250) on loop error)",
+        policy: {
+            maxAttempts: 0,
+            baseDelayMs: 250,
+            multiplier: 1,
+            maxDelayMs: 250,
+            growth: "exponential",
+            jitter: "none",
+            allowJitterAboveCap: false,
+        },
+        retryable: "any XREADGROUP / handleMessage throw; the loop never gives up",
+        migration: "Behaviour-preserving. 250ms here vs 200ms in the two sibling loops is the clearest ACCIDENTAL divergence in the survey — three loops, same failure mode, three different constants.",
+    },
+    // ── 12 ─────────────────────────────────────────────────────────────────
+    "telemetry.streamsWorkerRetry": {
+        source: "ts/telemetry/src/worker/streams-worker.ts:776 (attempt < retryMaxAttempts) + DEFAULT_RETRY_MAX",
+        policy: {
+            maxAttempts: 3,
+            baseDelayMs: 0, // PEL redelivery, not a sleep
+            multiplier: 1,
+            maxDelayMs: 0,
+            growth: "exponential",
+            jitter: "none",
+            allowJitterAboveCap: false,
+        },
+        retryable: "poison-tagged apply errors only; infra errors (fence lost, store down) leave the entry in the PEL WITHOUT bumping the ledger",
+        migration: "Counting only, like replicaConsumer.applyRetry. `attempt < max` (here) and `attempt >= max` (replica) are complementary forms of the SAME 1-based convention — both dead-letter on attempt N. Migrating both to isFinalAttempt() removes the need to prove that each time.",
+    },
+    // ── 13 ─────────────────────────────────────────────────────────────────
+    "telemetry.outboxDispatcherLoop": {
+        source: "ts/telemetry/src/worker/outbox-dispatcher.ts:262 (setTimeout(min(pollMs, 200)))",
+        policy: {
+            maxAttempts: 0,
+            baseDelayMs: 200,
+            multiplier: 1,
+            maxDelayMs: 200,
+            growth: "exponential",
+            jitter: "none",
+            allowJitterAboveCap: false,
+        },
+        retryable: "any drain-iteration throw",
+        migration: "Behaviour-preserving. Duplicate of outboxDispatcher.drainLoop.",
+    },
+    // ── 14 ─────────────────────────────────────────────────────────────────
+    "telemetry.singleActiveLeaseSelfHeal": {
+        source: "ts/telemetry/src/worker/single-active-lease.ts:714 (retryMs = max(1000, ttlMs/2))",
+        policy: {
+            maxAttempts: 0,
+            baseDelayMs: 15_000, // max(1000, 30_000/2) for the default 30s TTL
+            multiplier: 1,
+            maxDelayMs: 15_000,
+            growth: "exponential",
+            jitter: "none",
+            allowJitterAboveCap: false,
+        },
+        retryable: "lease not held / Redis down — retries on a fixed tick forever",
+        migration: "DELIBERATE CHANGE recommended: add equal jitter. This is the one surveyed site with a genuine thundering-herd shape — every replica of a service self-heals on the SAME ttl/2 tick with zero jitter, so after a Redis blip they all hammer the acquire path in lockstep. Preserve the ttl/2 base; jitter the tick.",
+    },
+};
+//# sourceMappingURL=fleet-policies.js.map

package/dist/fleet-policies.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fleet-policies.js","sourceRoot":"","sources":["../src/fleet-policies.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+export { type GrowthKind, type JitterStrategy, type RetryPolicy, DEFAULT_POLICY, InvalidRetryPolicyError, resolvePolicy, baseDelayForAttempt, } from "./policy.js";
+export { type RandomFn, applyJitter, jitteredDelayForAttempt, backoffSequence, } from "./jitter.js";
+export { isFinalAttempt, isFinalAttemptFromAttemptsMade, remainingAttempts, } from "./attempts.js";
+export { type ShouldRetry, type ShouldRetryContext, retryAll, retryNone, allOf, anyOf, shouldRetryFromOutcomeClassifier, } from "./classify.js";
+export { NonRetryableError, RetryExhaustedError, isNonRetryableError, } from "./errors.js";
+export { type AttemptContext, type ExhaustedEvent, type RetryEvent, type RetryOptions, type SleepFn, defaultSleep, retry, } from "./run.js";
+export { type BullmqBackoffOptions, bullmqBackoffStrategy, } from "./adapters/bullmq.js";
+export { FLEET_POLICIES, type FleetSiteId } from "./fleet-policies.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAOA,OAAO,EACL,KAAK,UAAU,EACf,KAAK,cAAc,EACnB,KAAK,WAAW,EAChB,cAAc,EACd,uBAAuB,EACvB,aAAa,EACb,mBAAmB,GACpB,MAAM,aAAa,CAAC;AAErB,OAAO,EACL,KAAK,QAAQ,EACb,WAAW,EACX,uBAAuB,EACvB,eAAe,GAChB,MAAM,aAAa,CAAC;AAErB,OAAO,EACL,cAAc,EACd,8BAA8B,EAC9B,iBAAiB,GAClB,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,KAAK,WAAW,EAChB,KAAK,kBAAkB,EACvB,QAAQ,EACR,SAAS,EACT,KAAK,EACL,KAAK,EACL,gCAAgC,GACjC,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,iBAAiB,EACjB,mBAAmB,EACnB,mBAAmB,GACpB,MAAM,aAAa,CAAC;AAErB,OAAO,EACL,KAAK,cAAc,EACnB,KAAK,cAAc,EACnB,KAAK,UAAU,EACf,KAAK,YAAY,EACjB,KAAK,OAAO,EACZ,YAAY,EACZ,KAAK,GACN,MAAM,UAAU,CAAC;AAElB,OAAO,EACL,KAAK,oBAAoB,EACzB,qBAAqB,GACtB,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EAAE,cAAc,EAAE,KAAK,WAAW,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/index.js

@@ -0,0 +1,15 @@
+// @nodii/retry — the one retry / backoff / jitter policy for the Nodii stack.
+//
+// Built because the audit found retry+backoff+jitter hand-rolled in 14 places
+// INSIDE the shared libraries, so every service inherited whichever variant
+// its lib happened to implement. See README § "The survey" for the table and
+// § "Divergences" for which of those disagreements look deliberate.
+export { DEFAULT_POLICY, InvalidRetryPolicyError, resolvePolicy, baseDelayForAttempt, } from "./policy.js";
+export { applyJitter, jitteredDelayForAttempt, backoffSequence, } from "./jitter.js";
+export { isFinalAttempt, isFinalAttemptFromAttemptsMade, remainingAttempts, } from "./attempts.js";
+export { retryAll, retryNone, allOf, anyOf, shouldRetryFromOutcomeClassifier, } from "./classify.js";
+export { NonRetryableError, RetryExhaustedError, isNonRetryableError, } from "./errors.js";
+export { defaultSleep, retry, } from "./run.js";
+export { bullmqBackoffStrategy, } from "./adapters/bullmq.js";
+export { FLEET_POLICIES } from "./fleet-policies.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,EAAE;AACF,8EAA8E;AAC9E,4EAA4E;AAC5E,6EAA6E;AAC7E,oEAAoE;AAEpE,OAAO,EAIL,cAAc,EACd,uBAAuB,EACvB,aAAa,EACb,mBAAmB,GACpB,MAAM,aAAa,CAAC;AAErB,OAAO,EAEL,WAAW,EACX,uBAAuB,EACvB,eAAe,GAChB,MAAM,aAAa,CAAC;AAErB,OAAO,EACL,cAAc,EACd,8BAA8B,EAC9B,iBAAiB,GAClB,MAAM,eAAe,CAAC;AAEvB,OAAO,EAGL,QAAQ,EACR,SAAS,EACT,KAAK,EACL,KAAK,EACL,gCAAgC,GACjC,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,iBAAiB,EACjB,mBAAmB,EACnB,mBAAmB,GACpB,MAAM,aAAa,CAAC;AAErB,OAAO,EAML,YAAY,EACZ,KAAK,GACN,MAAM,UAAU,CAAC;AAElB,OAAO,EAEL,qBAAqB,GACtB,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EAAE,cAAc,EAAoB,MAAM,qBAAqB,CAAC"}

package/dist/jitter.d.ts

@@ -0,0 +1,47 @@
+import { type JitterStrategy, type RetryPolicy } from "./policy.js";
+/** Injectable RNG. Tests pass a deterministic sequence; production omits it. */
+export type RandomFn = () => number;
+/**
+ * Apply `strategy` to an already-capped delay `d`.
+ *
+ * `previousDelayMs` is only consulted by `"decorrelated"` (which is a
+ * recurrence, not a function of the attempt index). Callers that do not track
+ * it get the seeded form (`previous = base`).
+ *
+ * The result is NOT clamped here — {@link jitteredDelayForAttempt} owns the
+ * final clamp so `allowJitterAboveCap` has exactly one implementation.
+ */
+export declare function applyJitter(d: number, strategy: JitterStrategy, random: RandomFn, ctx: {
+    baseDelayMs: number;
+    maxDelayMs: number;
+    previousDelayMs: number;
+}): number;
+/**
+ * The FINAL delay (ms, integer) for a 1-based `attempt`.
+ *
+ * Order of operations — this is the part the fleet gets wrong:
+ *
+ *   1. grow      →  base · mult^(n-1)   (or base · n for linear)
+ *   2. cap       →  min(·, maxDelayMs)
+ *   3. jitter    →  strategy(·)
+ *   4. clamp     →  min(·, maxDelayMs) unless `allowJitterAboveCap`
+ *   5. floor at 0 + round to integer ms
+ *
+ * Step 4 is the fix. `@nodii/role-catalog` and `@nodii/replica-consumer` both
+ * stop after step 3, so their declared 30s cap is really a 33.75s / 36s cap.
+ */
+export declare function jitteredDelayForAttempt(policy: RetryPolicy, attempt: number, opts: {
+    random: RandomFn;
+    previousDelayMs?: number;
+}): number;
+/**
+ * The first `count` delays under `policy` — the deterministic preview used by
+ * tests and by operators reasoning about "how long until we give up".
+ *
+ * Threads `previousDelayMs` so `"decorrelated"` produces its true recurrence
+ * rather than a seeded-every-time sequence.
+ */
+export declare function backoffSequence(policy: RetryPolicy, count: number, opts?: {
+    random?: RandomFn;
+}): number[];
+//# sourceMappingURL=jitter.d.ts.map

package/dist/jitter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"jitter.d.ts","sourceRoot":"","sources":["../src/jitter.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,cAAc,EACnB,KAAK,WAAW,EAEjB,MAAM,aAAa,CAAC;AAErB,gFAAgF;AAChF,MAAM,MAAM,QAAQ,GAAG,MAAM,MAAM,CAAC;AAEpC;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CACzB,CAAC,EAAE,MAAM,EACT,QAAQ,EAAE,cAAc,EACxB,MAAM,EAAE,QAAQ,EAChB,GAAG,EAAE;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,eAAe,EAAE,MAAM,CAAA;CAAE,GACxE,MAAM,CAwBR;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,WAAW,EACnB,OAAO,EAAE,MAAM,EACf,IAAI,EAAE;IAAE,MAAM,EAAE,QAAQ,CAAC;IAAC,eAAe,CAAC,EAAE,MAAM,CAAA;CAAE,GACnD,MAAM,CAWR;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAC7B,MAAM,EAAE,WAAW,EACnB,KAAK,EAAE,MAAM,EACb,IAAI,CAAC,EAAE;IAAE,MAAM,CAAC,EAAE,QAAQ,CAAA;CAAE,GAC3B,MAAM,EAAE,CAaV"}

package/dist/jitter.js

@@ -0,0 +1,84 @@
+import { baseDelayForAttempt, } from "./policy.js";
+/**
+ * Apply `strategy` to an already-capped delay `d`.
+ *
+ * `previousDelayMs` is only consulted by `"decorrelated"` (which is a
+ * recurrence, not a function of the attempt index). Callers that do not track
+ * it get the seeded form (`previous = base`).
+ *
+ * The result is NOT clamped here — {@link jitteredDelayForAttempt} owns the
+ * final clamp so `allowJitterAboveCap` has exactly one implementation.
+ */
+export function applyJitter(d, strategy, random, ctx) {
+    if (typeof strategy === "object") {
+        // proportional: d · (1 + pct·U(-1,1))
+        return d * (1 + strategy.pct * (random() * 2 - 1));
+    }
+    switch (strategy) {
+        case "none":
+            return d;
+        case "full":
+            // U(0, d)
+            return random() * d;
+        case "equal":
+            // d/2 + U(0, d/2) — a FLOOR of d/2 that still grows, plus dispersal.
+            return d / 2 + random() * (d / 2);
+        case "decorrelated": {
+            // AWS decorrelated: sleep = min(cap, U(base, 3·previous)).
+            // Seeded at `base`, so the first delay is U(base, 3·base).
+            const lo = ctx.baseDelayMs;
+            const hi = ctx.previousDelayMs * 3;
+            const span = hi - lo;
+            const v = span > 0 ? lo + random() * span : lo;
+            return Math.min(ctx.maxDelayMs, v);
+        }
+    }
+}
+/**
+ * The FINAL delay (ms, integer) for a 1-based `attempt`.
+ *
+ * Order of operations — this is the part the fleet gets wrong:
+ *
+ *   1. grow      →  base · mult^(n-1)   (or base · n for linear)
+ *   2. cap       →  min(·, maxDelayMs)
+ *   3. jitter    →  strategy(·)
+ *   4. clamp     →  min(·, maxDelayMs) unless `allowJitterAboveCap`
+ *   5. floor at 0 + round to integer ms
+ *
+ * Step 4 is the fix. `@nodii/role-catalog` and `@nodii/replica-consumer` both
+ * stop after step 3, so their declared 30s cap is really a 33.75s / 36s cap.
+ */
+export function jitteredDelayForAttempt(policy, attempt, opts) {
+    const capped = baseDelayForAttempt(policy, attempt);
+    const jittered = applyJitter(capped, policy.jitter, opts.random, {
+        baseDelayMs: policy.baseDelayMs,
+        maxDelayMs: policy.maxDelayMs,
+        previousDelayMs: opts.previousDelayMs ?? policy.baseDelayMs,
+    });
+    const clamped = policy.allowJitterAboveCap
+        ? jittered
+        : Math.min(jittered, policy.maxDelayMs);
+    return Math.max(0, Math.round(clamped));
+}
+/**
+ * The first `count` delays under `policy` — the deterministic preview used by
+ * tests and by operators reasoning about "how long until we give up".
+ *
+ * Threads `previousDelayMs` so `"decorrelated"` produces its true recurrence
+ * rather than a seeded-every-time sequence.
+ */
+export function backoffSequence(policy, count, opts) {
+    const random = opts?.random ?? Math.random;
+    const out = [];
+    let previous = policy.baseDelayMs;
+    for (let attempt = 1; attempt <= count; attempt++) {
+        const d = jitteredDelayForAttempt(policy, attempt, {
+            random,
+            previousDelayMs: previous,
+        });
+        out.push(d);
+        previous = d;
+    }
+    return out;
+}
+//# sourceMappingURL=jitter.js.map