@nodii/retry 0.0.0 → 0.1.0

package/README.md

@@ -1 +1,214 @@
-Placeholder claim for @nodii/retry. Real releases come from cognion-nucleus/nodii-libs via npm trusted publishing.
+# @nodii/retry
+
+The retry / exponential-backoff / jitter policy for the Nodii stack, as a real package.
+
+Retry+backoff+jitter was hand-rolled **14 times inside `ts/*` itself** — not in the services, in
+the shared libraries. Every service inherited whichever variant its lib happened to implement, so
+two consumers of the same fleet behaved differently under the same failure.
+
+Zero runtime dependencies. Injectable clock and RNG throughout — a suite exercising a 30s cap
+finishes in microseconds.
+
+---
+
+## The survey
+
+Every row is a real implementation on `origin/main` @ `8af8e137`. `FLEET_POLICIES` in
+`src/fleet-policies.ts` encodes each one, and `tests/fleet-parity.test.ts` asserts this package
+reproduces it.
+
+| # | Site | Base | Mult | Cap | Jitter | Max attempts | Retryable |
+|---|------|------|------|-----|--------|--------------|-----------|
+| 1 | `approval/consumer.ts:161` (BullMQ `backoffStrategy`) | 250ms | ×2 | 60s | none | 5 (`consumerMaxRetries`) | any handler throw |
+| 2 | `approval/streams-reader.ts:389` | 200ms | — | — | none | ∞ | any loop throw |
+| 3 | `onboarding/submit/client.ts:37` | 1000ms | ×2 (literal `[1000,2000]`) | — | none | 3 | network/timeout + 5xx |
+| 4 | `onboarding/submit/signup-client.ts:44` | 1000ms | ×2 (literal `[1000,2000]`) | — | none | 3 | network/timeout + 5xx |
+| 5 | `outbox-dispatcher/sql-builders.ts:39` (SQL cooldown) | 60s | **linear** ×n | — | none | 8 (`publishMaxAttempts`) | every publish failure |
+| 6 | `outbox-dispatcher/drainer.ts:421` | 200ms | — | — | none | ∞ | any drain throw |
+| 7 | `replica-consumer/start.ts:242` (cold start) | 1000ms | ×2 | 30s | **±20%** | **0 = indefinite** | every bootstrap failure |
+| 8 | `replica-consumer/define-replica.ts:294` + `init.ts:17` | 100ms | ×2 | 30s | `jitterPct: 25` | 5 | **n/a — DEAD CONFIG** |
+| 9 | `replica-consumer/worker/streams-worker.ts:1120` | — (PEL redelivery) | — | — | none | 5 | all apply errors → DLQ |
+| 10 | `role-catalog/publish.ts:203` | 100ms | ×2 | 30s | **±12.5%** | 30 | gRPC `UNAVAILABLE` only |
+| 11 | `saga/participant-worker.ts:351` | 250ms | — | — | none | ∞ | any loop throw |
+| 12 | `telemetry/worker/streams-worker.ts:776` | — (PEL redelivery) | — | — | none | 3 | poison-tagged only |
+| 13 | `telemetry/worker/outbox-dispatcher.ts:262` | 200ms | — | — | none | ∞ | any drain throw |
+| 14 | `telemetry/worker/single-active-lease.ts:714` | `max(1s, ttl/2)` | — | — | none | ∞ | lease not held / Redis down |
+
+## The divergences
+
+### Accidental
+
+1. **`jitterPct` carries two different UNITS inside one package.** `replica-consumer/start.ts`
+   writes `0.2` (a fraction); `define-replica.ts` and `init.ts` write `25` (a percent) for a field
+   of the same name in the same library. Read as a fraction, `25` is ±2500% jitter. This package
+   rejects `pct > 1` outright so the ambiguity cannot survive migration.
+2. **`retryBackoff` is DEAD CONFIG.** `git grep retryBackoff -- ts/` returns three hits: two
+   constructors and one type. Nothing reads it. `replica-consumer` declares an exponential
+   100ms→30s ±25% apply backoff that has never executed — the real spacing is Redis PEL redelivery
+   plus the XCLAIM reaper. Do not "migrate" it; migrating would ACTIVATE a delay that has never run
+   in production.
+3. **Three structurally identical loop-error sleeps, two constants.** `approval/streams-reader`,
+   `outbox-dispatcher/drainer` and `telemetry/worker/outbox-dispatcher` all sleep 200ms; `saga/
+   participant-worker` sleeps 250ms. Same failure mode (Redis blip in a stream-read loop), same
+   remedy, arbitrary difference. None has jitter or growth, so a sustained Redis outage means every
+   pod issues 4–5 commands/second forever.
+4. **Both jitter sites can exceed their own declared cap.** Both apply jitter AFTER the cap and
+   never re-clamp: `role-catalog` sleeps up to 33 750ms against a declared 30 000ms cap;
+   `replica-consumer` cold start up to 36 000ms against the same declared cap. A cap the code may
+   exceed is not a cap.
+5. **`approval`'s declared 250ms base is never slept.** `2 ** attemptsMade * 250` against
+   BullMQ's post-incremented counter means the first retry waits 500ms. Off by one doubling.
+6. **Three jitter magnitudes (12.5% / 20% / 25%) for one concept**, none of them derived from
+   anything.
+7. **`single-active-lease` self-heals on a fixed `ttl/2` tick with zero jitter.** This is the one
+   genuine thundering-herd shape in the survey: after a Redis blip every replica of a service
+   retries the acquire path in lockstep.
+
+### Deliberate (leave alone)
+
+1. **`replica-consumer` cold start retries indefinitely (`maxAttempts: 0`).** Giving up means
+   silently dropping a backfill. Correct.
+2. **`outbox-dispatcher`'s cooldown is LINEAR, not exponential** — and `publishMaxAttempts` caps
+   RE-CLAIM, never deletes the row (D401). A row is source of truth; the 24h sweep raises the M17
+   page. Correct, and the reason `growth: "linear"` exists in this package.
+3. **`onboarding` does not auto-retry 429.** Honouring a `Retry-After` is the caller's decision.
+   Correct.
+4. **`role-catalog` retries `UNAVAILABLE` only, fail-fast on `FAILED_PRECONDITION`.** A version
+   mismatch will never heal by waiting. Correct.
+5. **`telemetry`'s retry ledger is bumped only for poison-tagged errors**; infra errors (fence
+   lost, store down) leave the entry in the PEL without spending budget. Correct — otherwise five
+   Redis blips silently dead-letter a good event.
+6. **`replica-consumer` treats `UnknownAggregateKind` as process-fatal, not retryable.** A silent
+   drop there is data loss. Correct.
+
+---
+
+## Why equal jitter is the default
+
+`"equal"` — `d/2 + U(0, d/2)`.
+
+- **Full jitter** (`U(0, d)`) minimizes contention but has no floor: any attempt can return ≈0. In
+  this fleet almost every retry waits on a *single dependency that is booting* (role-catalog
+  publishing at boot against a cold tenant-service; replica cold-start backfill against the
+  snapshot producer), not on a contended shared resource. Full jitter's benefit is *herd
+  dispersal*; its cost — losing the monotonically growing floor — is what actually bites, because
+  a near-zero delay both burns an attempt from a finite budget and adds load to something already
+  struggling.
+- **Equal jitter** keeps an exponentially growing floor (`d/2`) while still dispersing enough to
+  break lockstep between the N pods of a service that boot together — which is exactly the herd
+  case here (an ECS rolling deploy). AWS's own analysis finds full and equal near-identical on
+  total work and completion time; equal keeps the floor.
+- **Decorrelated jitter** (`min(cap, U(base, 3·prev))`) is the strongest for pure contention, but
+  it is *stateful* and also non-monotone, and nothing in the fleet does it today — defaulting to it
+  would silently change all 14 sites. Offered, never defaulted. (`bullmqBackoffStrategy` rejects it
+  outright: BullMQ's `backoffStrategy` is stateless and has no previous delay to thread.)
+- **`{ kind: "proportional", pct }`** exists because it is what the two live jitter sites actually
+  do. `role-catalog`'s `randomFn()*0.25 + 0.875` is *exactly* `1 + 0.125·(2r−1)`, so their
+  migration is byte-preserving for the same RNG draw.
+- **`"none"`** exists because 11 sites have no jitter and their migration must be
+  behaviour-preserving.
+
+Order of operations — the part the fleet gets wrong:
+
+```
+grow → cap → jitter → clamp (unless allowJitterAboveCap) → floor at 0 → round to integer ms
+```
+
+`allowJitterAboveCap: true` reproduces the live overshoot exactly, for a byte-preserving migration.
+Default `false`, i.e. the declared cap holds.
+
+---
+
+## The BullMQ off-by-one
+
+BullMQ increments `job.attemptsMade` **before** the backoff is computed and before `failed` fires.
+So after the k-th attempt fails, `attemptsMade === k`, and "was that the last one?" is:
+
+```ts
+isFinalAttemptFromAttemptsMade(attemptsMade, maxAttempts); // attemptsMade + 1 >= maxAttempts
+```
+
+The naive `attemptsMade >= maxAttempts` disagrees at exactly one point (`attemptsMade === max - 1`)
+and runs one attempt too many. The 1-based in-process ledger convention (`retries.inc(id)`) is a
+**different** function:
+
+```ts
+isFinalAttempt(attempt, maxAttempts); // attempt >= maxAttempts
+```
+
+Two named functions, deliberately — there is no single `isLastAttempt(n, max)` for a call site to
+guess at. `maxAttempts === 0` means unbounded; nothing is ever final.
+
+---
+
+## The boundary with `@nodii/idempotency`
+
+They answer different questions and must not be merged:
+
+| | `@nodii/idempotency` (D242) | `@nodii/retry` |
+|---|---|---|
+| Question | should the KEY be cached or released? | should the CALLER re-invoke? |
+| Kind | storage / replay | control flow |
+| Side | server | client |
+| Keyed by | the completed OUTCOME | the thrown ERROR |
+
+`transport` is a **superset** of "retryable": `RESOURCE_EXHAUSTED` is transport, yet a caller
+honouring a `Retry-After` may decline to retry (`@nodii/onboarding` does exactly this for 429). And
+`CANCELLED` / `UNKNOWN` / `UNIMPLEMENTED` / `DATA_LOSS` are deliberately unmapped by D242 and fall
+back to `defaultClass` — a default that exists to answer the *storage* question and must not
+silently become a retry verdict.
+
+So this package ships **no gRPC-status table, no HTTP-status table, and no dependency on
+`@nodii/idempotency`** — a change to D242's map cannot silently change anyone's retry behaviour.
+Coupling is explicit and **one-way**:
+
+```ts
+shouldRetry: shouldRetryFromOutcomeClassifier(myD242Classifier); // transport ⇒ may retry
+```
+
+The reverse direction is forbidden and not offered: declining to retry does not make an outcome
+deterministic, and caching a key on that basis would replay a transport failure as a business
+result. The bridge fails **closed** on any unrecognised class.
+
+---
+
+## Usage
+
+```ts
+import { retry, NonRetryableError, bullmqBackoffStrategy } from "@nodii/retry";
+
+const res = await retry(
+  async (ctx) => {
+    const r = await fetch(url);
+    if (r.status === 403) throw new NonRetryableError("bot challenge failed");
+    if (r.status >= 500) throw new Error(`server ${r.status}`);
+    return r.json();
+  },
+  {
+    policy: { maxAttempts: 3, baseDelayMs: 1000, multiplier: 2, jitter: "equal" },
+    shouldRetry: (err) => !(err instanceof TypeError),
+    onRetry: ({ attempt, delayMs, error }) =>
+      logger.warn("retrying", { attempt, delay_ms: delayMs, error: String(error) }),
+  },
+);
+```
+
+```ts
+// BullMQ — the post-increment handled in one place
+new Worker(queue, handler, {
+  settings: {
+    backoffStrategy: bullmqBackoffStrategy({
+      baseDelayMs: 500, multiplier: 2, maxDelayMs: 60_000, jitter: "equal",
+    }),
+  },
+});
+```
+
+Everything is injectable: `sleep`, `random`, `signal`. `backoffSequence(policy, n)` gives the
+deterministic schedule for tests and for operators reasoning about "how long until we give up".
+
+## Migration
+
+Call sites are **not** migrated in this release. `FLEET_POLICIES[<id>].migration` states, per site,
+whether the migration is behaviour-preserving or a deliberate change, and `tests/fleet-parity.
+test.ts` proves the preserving ones really are.

package/dist/adapters/bullmq.d.ts

@@ -0,0 +1,38 @@
+import { type RandomFn } from "../jitter.js";
+import { type RetryPolicy } from "../policy.js";
+export interface BullmqBackoffOptions {
+    random?: RandomFn;
+    /**
+     * Added to BullMQ's `attemptsMade` before it is used as the 1-based retry
+     * index.
+     *
+     * `0` (default, CORRECT): `attemptsMade === 1` → retry index 1 → `baseDelayMs`.
+     *
+     * `1`: reproduces `ts/approval/src/consumer.ts` byte-for-byte — retry index
+     * `attemptsMade + 1`, so the first retry waits `base · multiplier`. Set this
+     * ONLY to make an approval migration behaviour-preserving, and say so in the
+     * migration note. The honest alternative is `attemptOffset: 0` with
+     * `baseDelayMs: 500`, which produces the same sequence from a truthful base.
+     */
+    attemptOffset?: 0 | 1;
+}
+/**
+ * Build a BullMQ `settings.backoffStrategy` from a policy.
+ *
+ * ```ts
+ * new Worker(queue, handler, {
+ *   settings: {
+ *     backoffStrategy: bullmqBackoffStrategy({
+ *       baseDelayMs: 500, multiplier: 2, maxDelayMs: 60_000, jitter: "equal",
+ *     }),
+ *   },
+ * });
+ * ```
+ *
+ * The returned function accepts BullMQ's full `(attemptsMade, type, err, job)`
+ * signature but only consults the first argument, so it is assignable wherever
+ * BullMQ expects a `BackoffStrategy` without importing bullmq's types (this
+ * package has zero dependencies).
+ */
+export declare function bullmqBackoffStrategy(policy?: Partial<RetryPolicy>, opts?: BullmqBackoffOptions): (attemptsMade: number) => number;
+//# sourceMappingURL=bullmq.d.ts.map

package/dist/adapters/bullmq.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bullmq.d.ts","sourceRoot":"","sources":["../../src/adapters/bullmq.ts"],"names":[],"mappings":"AAcA,OAAO,EAAE,KAAK,QAAQ,EAA2B,MAAM,cAAc,CAAC;AACtE,OAAO,EAAE,KAAK,WAAW,EAAiB,MAAM,cAAc,CAAC;AAE/D,MAAM,WAAW,oBAAoB;IACnC,MAAM,CAAC,EAAE,QAAQ,CAAC;IAClB;;;;;;;;;;;OAWG;IACH,aAAa,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC;CACvB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,EAC7B,IAAI,GAAE,oBAAyB,GAC9B,CAAC,YAAY,EAAE,MAAM,KAAK,MAAM,CAmBlC"}

package/dist/adapters/bullmq.js

@@ -0,0 +1,52 @@
+// BullMQ adapter — the post-increment off-by-one, contained in one place.
+//
+// BullMQ v5 increments `job.attemptsMade` BEFORE it computes the backoff and
+// BEFORE the `failed` handler runs. So a `backoffStrategy` receiving
+// `attemptsMade === 1` is being asked for the delay before the SECOND attempt,
+// i.e. the FIRST retry.
+//
+// `ts/approval/src/consumer.ts:161` computes `Math.min(60_000, 2 ** attempts *
+// 250)` from that argument, which is `250 · 2^attemptsMade` — one doubling
+// AHEAD of the canonical `base · multiplier^(retryIndex - 1)`. Its declared
+// 250ms base is therefore never actually slept: approval's first retry waits
+// 500ms. That is an off-by-one in approval, and this adapter does NOT
+// reproduce it silently — see `attemptOffset`.
+import { jitteredDelayForAttempt } from "../jitter.js";
+import { resolvePolicy } from "../policy.js";
+/**
+ * Build a BullMQ `settings.backoffStrategy` from a policy.
+ *
+ * ```ts
+ * new Worker(queue, handler, {
+ *   settings: {
+ *     backoffStrategy: bullmqBackoffStrategy({
+ *       baseDelayMs: 500, multiplier: 2, maxDelayMs: 60_000, jitter: "equal",
+ *     }),
+ *   },
+ * });
+ * ```
+ *
+ * The returned function accepts BullMQ's full `(attemptsMade, type, err, job)`
+ * signature but only consults the first argument, so it is assignable wherever
+ * BullMQ expects a `BackoffStrategy` without importing bullmq's types (this
+ * package has zero dependencies).
+ */
+export function bullmqBackoffStrategy(policy, opts = {}) {
+    const resolved = resolvePolicy(policy);
+    const random = opts.random ?? Math.random;
+    const offset = opts.attemptOffset ?? 0;
+    // `"decorrelated"` is a recurrence over the PREVIOUS delay, and BullMQ hands
+    // us only an index — there is no previous delay to thread. Refuse rather
+    // than silently emitting the seeded first delay on every attempt.
+    if (resolved.jitter === "decorrelated") {
+        throw new Error('bullmqBackoffStrategy: jitter "decorrelated" is stateful (min(cap, U(base, 3·previous))) and BullMQ\'s backoffStrategy is stateless — use "equal", "full", "none", or proportional jitter');
+    }
+    return (attemptsMade) => {
+        // Guard: BullMQ has been observed to pass 0 on some paths. A retry index
+        // must be >= 1 or `baseDelayForAttempt` throws inside a worker's failure
+        // path, which would mask the real error.
+        const retryIndex = Math.max(1, Math.floor(attemptsMade) + offset);
+        return jitteredDelayForAttempt(resolved, retryIndex, { random });
+    };
+}
+//# sourceMappingURL=bullmq.js.map

package/dist/adapters/bullmq.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bullmq.js","sourceRoot":"","sources":["../../src/adapters/bullmq.ts"],"names":[],"mappings":"AAAA,0EAA0E;AAC1E,EAAE;AACF,6EAA6E;AAC7E,qEAAqE;AACrE,+EAA+E;AAC/E,wBAAwB;AACxB,EAAE;AACF,+EAA+E;AAC/E,2EAA2E;AAC3E,4EAA4E;AAC5E,6EAA6E;AAC7E,sEAAsE;AACtE,+CAA+C;AAE/C,OAAO,EAAiB,uBAAuB,EAAE,MAAM,cAAc,CAAC;AACtE,OAAO,EAAoB,aAAa,EAAE,MAAM,cAAc,CAAC;AAmB/D;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,qBAAqB,CACnC,MAA6B,EAC7B,OAA6B,EAAE;IAE/B,MAAM,QAAQ,GAAG,aAAa,CAAC,MAAM,CAAC,CAAC;IACvC,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,IAAI,IAAI,CAAC,MAAM,CAAC;IAC1C,MAAM,MAAM,GAAG,IAAI,CAAC,aAAa,IAAI,CAAC,CAAC;IACvC,6EAA6E;IAC7E,yEAAyE;IACzE,kEAAkE;IAClE,IAAI,QAAQ,CAAC,MAAM,KAAK,cAAc,EAAE,CAAC;QACvC,MAAM,IAAI,KAAK,CACb,2LAA2L,CAC5L,CAAC;IACJ,CAAC;IACD,OAAO,CAAC,YAAoB,EAAU,EAAE;QACtC,yEAAyE;QACzE,yEAAyE;QACzE,yCAAyC;QACzC,MAAM,UAAU,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,GAAG,MAAM,CAAC,CAAC;QAClE,OAAO,uBAAuB,CAAC,QAAQ,EAAE,UAAU,EAAE,EAAE,MAAM,EAAE,CAAC,CAAC;IACnE,CAAC,CAAC;AACJ,CAAC"}

package/dist/attempts.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Convention (b): `attempt` is 1-based and IS the attempt being judged.
+ *
+ * `isFinalAttempt(1, 1)` → `true` (a budget of 1 means no retries at all).
+ */
+export declare function isFinalAttempt(attempt: number, maxAttempts: number): boolean;
+/**
+ * Convention (a): BullMQ's POST-INCREMENTED `job.attemptsMade`.
+ *
+ * After the first attempt fails, `attemptsMade === 1`. With
+ * `maxAttempts === 3`, attempts 1 and 2 must retry and attempt 3 is terminal:
+ *
+ * | attemptsMade | attemptsMade + 1 | >= 3 ? | verdict  |
+ * |--------------|------------------|--------|----------|
+ * | 1            | 2                | no     | retry    |
+ * | 2            | 3                | YES    | TERMINAL |
+ *
+ * `attemptsMade === 2` is the boundary. Using `attemptsMade >= maxAttempts`
+ * here burns a 4th attempt against a budget of 3.
+ */
+export declare function isFinalAttemptFromAttemptsMade(attemptsMade: number, maxAttempts: number): boolean;
+/**
+ * Retries still available after the 1-based `attempt` (convention (b)).
+ * `Number.POSITIVE_INFINITY` when unbounded.
+ */
+export declare function remainingAttempts(attempt: number, maxAttempts: number): number;
+//# sourceMappingURL=attempts.d.ts.map

package/dist/attempts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"attempts.d.ts","sourceRoot":"","sources":["../src/attempts.ts"],"names":[],"mappings":"AAgCA;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAG5E;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,8BAA8B,CAC5C,YAAY,EAAE,MAAM,EACpB,WAAW,EAAE,MAAM,GAClB,OAAO,CAGT;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,MAAM,EACf,WAAW,EAAE,MAAM,GAClB,MAAM,CAGR"}

package/dist/attempts.js

@@ -0,0 +1,69 @@
+// Attempt-counting semantics — the off-by-one this fleet has already been
+// burned by.
+//
+// There are TWO counter conventions live in ts/* right now and they are NOT
+// interchangeable:
+//
+//  (a) POST-INCREMENTED (BullMQ `job.attemptsMade`): after the k-th attempt
+//      fails, `attemptsMade === k`. The library sees it AFTER the increment,
+//      so "was that the last one?" is `attemptsMade + 1 >= maxAttempts`.
+//      -> ts/approval/src/consumer.ts:621 gets this right.
+//
+//  (b) PRE-INCREMENTED / 1-BASED (an in-process ledger the worker bumps
+//      itself, e.g. `retries.inc(id)`): the value IS the index of the attempt
+//      currently being judged, so the test is `attempt >= maxAttempts`.
+//      -> ts/replica-consumer/src/worker/streams-worker.ts:1121 (`>=`) and
+//         ts/telemetry/src/worker/streams-worker.ts:776 (`<`, complementary)
+//         both use this convention.
+//
+// Getting (a) wrong by using (b)'s test means a permanent failure retries
+// forever (off by one too many) or a transient one is dropped on its first
+// blip (off by one too few). Both have shipped in this fleet before. These are
+// two NAMED functions precisely so a call site cannot silently pick the wrong
+// convention — there is no single `isLastAttempt(n, max)` to guess at.
+/**
+ * `maxAttempts === 0` means UNBOUNDED (`@nodii/replica-consumer` cold-start
+ * default). Nothing is ever the final attempt.
+ */
+function unbounded(maxAttempts) {
+    return maxAttempts === 0;
+}
+/**
+ * Convention (b): `attempt` is 1-based and IS the attempt being judged.
+ *
+ * `isFinalAttempt(1, 1)` → `true` (a budget of 1 means no retries at all).
+ */
+export function isFinalAttempt(attempt, maxAttempts) {
+    if (unbounded(maxAttempts))
+        return false;
+    return attempt >= maxAttempts;
+}
+/**
+ * Convention (a): BullMQ's POST-INCREMENTED `job.attemptsMade`.
+ *
+ * After the first attempt fails, `attemptsMade === 1`. With
+ * `maxAttempts === 3`, attempts 1 and 2 must retry and attempt 3 is terminal:
+ *
+ * | attemptsMade | attemptsMade + 1 | >= 3 ? | verdict  |
+ * |--------------|------------------|--------|----------|
+ * | 1            | 2                | no     | retry    |
+ * | 2            | 3                | YES    | TERMINAL |
+ *
+ * `attemptsMade === 2` is the boundary. Using `attemptsMade >= maxAttempts`
+ * here burns a 4th attempt against a budget of 3.
+ */
+export function isFinalAttemptFromAttemptsMade(attemptsMade, maxAttempts) {
+    if (unbounded(maxAttempts))
+        return false;
+    return attemptsMade + 1 >= maxAttempts;
+}
+/**
+ * Retries still available after the 1-based `attempt` (convention (b)).
+ * `Number.POSITIVE_INFINITY` when unbounded.
+ */
+export function remainingAttempts(attempt, maxAttempts) {
+    if (unbounded(maxAttempts))
+        return Number.POSITIVE_INFINITY;
+    return Math.max(0, maxAttempts - attempt);
+}
+//# sourceMappingURL=attempts.js.map

package/dist/attempts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"attempts.js","sourceRoot":"","sources":["../src/attempts.ts"],"names":[],"mappings":"AAAA,0EAA0E;AAC1E,aAAa;AACb,EAAE;AACF,4EAA4E;AAC5E,mBAAmB;AACnB,EAAE;AACF,4EAA4E;AAC5E,6EAA6E;AAC7E,yEAAyE;AACzE,2DAA2D;AAC3D,EAAE;AACF,wEAAwE;AACxE,8EAA8E;AAC9E,wEAAwE;AACxE,2EAA2E;AAC3E,6EAA6E;AAC7E,oCAAoC;AACpC,EAAE;AACF,0EAA0E;AAC1E,2EAA2E;AAC3E,+EAA+E;AAC/E,8EAA8E;AAC9E,uEAAuE;AAEvE;;;GAGG;AACH,SAAS,SAAS,CAAC,WAAmB;IACpC,OAAO,WAAW,KAAK,CAAC,CAAC;AAC3B,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAAC,OAAe,EAAE,WAAmB;IACjE,IAAI,SAAS,CAAC,WAAW,CAAC;QAAE,OAAO,KAAK,CAAC;IACzC,OAAO,OAAO,IAAI,WAAW,CAAC;AAChC,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,8BAA8B,CAC5C,YAAoB,EACpB,WAAmB;IAEnB,IAAI,SAAS,CAAC,WAAW,CAAC;QAAE,OAAO,KAAK,CAAC;IACzC,OAAO,YAAY,GAAG,CAAC,IAAI,WAAW,CAAC;AACzC,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAC/B,OAAe,EACf,WAAmB;IAEnB,IAAI,SAAS,CAAC,WAAW,CAAC;QAAE,OAAO,MAAM,CAAC,iBAAiB,CAAC;IAC5D,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,CAAC;AAC5C,CAAC"}

package/dist/classify.d.ts

@@ -0,0 +1,41 @@
+/** Context handed to a {@link ShouldRetry} predicate. */
+export interface ShouldRetryContext {
+    /** 1-based index of the attempt that just FAILED. */
+    attempt: number;
+    /** The resolved attempt budget (`0` = unbounded). */
+    maxAttempts: number;
+}
+/**
+ * The seam. Return `false` to make the error terminal — `retry()` stops
+ * immediately and rethrows without sleeping.
+ */
+export type ShouldRetry = (error: unknown, ctx: ShouldRetryContext) => boolean;
+/**
+ * DEFAULT predicate: retry everything.
+ *
+ * Chosen because it is what 11 of the 14 surveyed sites do — every worker-loop
+ * and consumer site retries any thrown error and relies on the attempt budget
+ * (plus a DLQ) for termination. The two selective sites (role-catalog:
+ * UNAVAILABLE only; onboarding: network + 5xx only) pass their own predicate,
+ * which is precisely why this is a seam.
+ */
+export declare const retryAll: ShouldRetry;
+/** Never retry — a one-shot with a policy attached. */
+export declare const retryNone: ShouldRetry;
+/** All predicates must agree before an error is retried. */
+export declare function allOf(...predicates: ShouldRetry[]): ShouldRetry;
+/** Any predicate agreeing is enough to retry. */
+export declare function anyOf(...predicates: ShouldRetry[]): ShouldRetry;
+/**
+ * The ONE-WAY bridge to an `@nodii/idempotency` `OutcomeClassifier`.
+ *
+ * `classify` is structurally typed (`(response, error) => string`) so this
+ * package takes no dependency on @nodii/idempotency; pass that lib's
+ * classifier directly.
+ *
+ * `transport` → may retry. Anything else (`application`, or any future class)
+ * → terminal. Fail-CLOSED on an unrecognised class: an unknown outcome class
+ * must not license an unbounded retry loop against a money path.
+ */
+export declare function shouldRetryFromOutcomeClassifier(classify: (response: unknown, error: unknown) => string): ShouldRetry;
+//# sourceMappingURL=classify.d.ts.map

package/dist/classify.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"classify.d.ts","sourceRoot":"","sources":["../src/classify.ts"],"names":[],"mappings":"AAyCA,yDAAyD;AACzD,MAAM,WAAW,kBAAkB;IACjC,qDAAqD;IACrD,OAAO,EAAE,MAAM,CAAC;IAChB,qDAAqD;IACrD,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;;GAGG;AACH,MAAM,MAAM,WAAW,GAAG,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,kBAAkB,KAAK,OAAO,CAAC;AAE/E;;;;;;;;GAQG;AACH,eAAO,MAAM,QAAQ,EAAE,WAAwB,CAAC;AAEhD,uDAAuD;AACvD,eAAO,MAAM,SAAS,EAAE,WAAyB,CAAC;AAElD,4DAA4D;AAC5D,wBAAgB,KAAK,CAAC,GAAG,UAAU,EAAE,WAAW,EAAE,GAAG,WAAW,CAE/D;AAED,iDAAiD;AACjD,wBAAgB,KAAK,CAAC,GAAG,UAAU,EAAE,WAAW,EAAE,GAAG,WAAW,CAE/D;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,gCAAgC,CAC9C,QAAQ,EAAE,CAAC,QAAQ,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,KAAK,MAAM,GACtD,WAAW,CAEb"}

package/dist/classify.js

@@ -0,0 +1,75 @@
+// The terminal-vs-transient SEAM.
+//
+// ── Boundary with @nodii/idempotency (D242) ─────────────────────────────────
+//
+// @nodii/idempotency has an `OutcomeClassifier` that answers a DIFFERENT
+// question, and the two must not be merged:
+//
+//   idempotency  — "given a COMPLETED attempt's outcome, should the
+//                   idempotency KEY be cached (application) or released
+//                   (transport)?"   Storage decision. Server side. Keyed by
+//                   OUTCOME class. Governs replay.
+//
+//   retry        — "given a THROWN error, should the CALLER re-invoke?"
+//                   Control-flow decision. Client side. Keyed by the ERROR.
+//                   Governs whether a next attempt happens at all.
+//
+// They are duals, not synonyms, and `transport` is a SUPERSET of "retryable":
+//
+//   - RESOURCE_EXHAUSTED(8) is TRANSPORT (key released, a retry may
+//     re-execute) but a caller under a tight budget, or one honouring a
+//     Retry-After, may legitimately decline to retry. @nodii/onboarding does
+//     exactly this: 429 is not auto-retried.
+//   - ALREADY_EXISTS(6) is APPLICATION and also non-retryable — agreement here
+//     is a coincidence of that particular code, not a general rule.
+//   - CANCELLED(1) / UNKNOWN(2) / UNIMPLEMENTED(12) / DATA_LOSS(15) are
+//     deliberately UNMAPPED by D242 and fall back to idempotency's
+//     `defaultClass`. That default exists to answer the STORAGE question; it
+//     must not silently become a retry verdict.
+//
+// So: this package ships NO gRPC-status table, NO HTTP-status table, and has
+// NO dependency (compile-time or otherwise) on @nodii/idempotency. A change to
+// D242's map therefore cannot silently change anyone's retry behaviour. A
+// service that wants the two coupled writes the coupling EXPLICITLY, one
+// direction only, via `shouldRetryFromOutcomeClassifier` below.
+//
+// The permitted direction is one-way: an idempotency classification may inform
+// a retry decision. The reverse (deriving an outcome class from a retry
+// verdict) is forbidden and not offered — declining to retry does not make an
+// outcome deterministic, and caching a key on that basis would replay a
+// transport failure as if it were a business result.
+/**
+ * DEFAULT predicate: retry everything.
+ *
+ * Chosen because it is what 11 of the 14 surveyed sites do — every worker-loop
+ * and consumer site retries any thrown error and relies on the attempt budget
+ * (plus a DLQ) for termination. The two selective sites (role-catalog:
+ * UNAVAILABLE only; onboarding: network + 5xx only) pass their own predicate,
+ * which is precisely why this is a seam.
+ */
+export const retryAll = () => true;
+/** Never retry — a one-shot with a policy attached. */
+export const retryNone = () => false;
+/** All predicates must agree before an error is retried. */
+export function allOf(...predicates) {
+    return (error, ctx) => predicates.every((p) => p(error, ctx));
+}
+/** Any predicate agreeing is enough to retry. */
+export function anyOf(...predicates) {
+    return (error, ctx) => predicates.some((p) => p(error, ctx));
+}
+/**
+ * The ONE-WAY bridge to an `@nodii/idempotency` `OutcomeClassifier`.
+ *
+ * `classify` is structurally typed (`(response, error) => string`) so this
+ * package takes no dependency on @nodii/idempotency; pass that lib's
+ * classifier directly.
+ *
+ * `transport` → may retry. Anything else (`application`, or any future class)
+ * → terminal. Fail-CLOSED on an unrecognised class: an unknown outcome class
+ * must not license an unbounded retry loop against a money path.
+ */
+export function shouldRetryFromOutcomeClassifier(classify) {
+    return (error) => classify(undefined, error) === "transport";
+}
+//# sourceMappingURL=classify.js.map

package/dist/classify.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"classify.js","sourceRoot":"","sources":["../src/classify.ts"],"names":[],"mappings":"AAAA,kCAAkC;AAClC,EAAE;AACF,+EAA+E;AAC/E,EAAE;AACF,yEAAyE;AACzE,4CAA4C;AAC5C,EAAE;AACF,oEAAoE;AACpE,wEAAwE;AACxE,4EAA4E;AAC5E,mDAAmD;AACnD,EAAE;AACF,wEAAwE;AACxE,4EAA4E;AAC5E,mEAAmE;AACnE,EAAE;AACF,8EAA8E;AAC9E,EAAE;AACF,oEAAoE;AACpE,wEAAwE;AACxE,6EAA6E;AAC7E,6CAA6C;AAC7C,+EAA+E;AAC/E,oEAAoE;AACpE,wEAAwE;AACxE,mEAAmE;AACnE,6EAA6E;AAC7E,gDAAgD;AAChD,EAAE;AACF,6EAA6E;AAC7E,+EAA+E;AAC/E,0EAA0E;AAC1E,yEAAyE;AACzE,gEAAgE;AAChE,EAAE;AACF,+EAA+E;AAC/E,wEAAwE;AACxE,8EAA8E;AAC9E,wEAAwE;AACxE,qDAAqD;AAgBrD;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAgB,GAAG,EAAE,CAAC,IAAI,CAAC;AAEhD,uDAAuD;AACvD,MAAM,CAAC,MAAM,SAAS,GAAgB,GAAG,EAAE,CAAC,KAAK,CAAC;AAElD,4DAA4D;AAC5D,MAAM,UAAU,KAAK,CAAC,GAAG,UAAyB;IAChD,OAAO,CAAC,KAAK,EAAE,GAAG,EAAE,EAAE,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC,CAAC;AAChE,CAAC;AAED,iDAAiD;AACjD,MAAM,UAAU,KAAK,CAAC,GAAG,UAAyB;IAChD,OAAO,CAAC,KAAK,EAAE,GAAG,EAAE,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC,CAAC;AAC/D,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,gCAAgC,CAC9C,QAAuD;IAEvD,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,QAAQ,CAAC,SAAS,EAAE,KAAK,CAAC,KAAK,WAAW,CAAC;AAC/D,CAAC"}

package/dist/errors.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Marker for "do not retry this, whatever the policy says".
+ *
+ * Thrown from INSIDE the operation when the operation itself knows the failure
+ * is terminal (`@nodii/onboarding`'s 403 bot-challenge, `@nodii/role-catalog`'s
+ * FAILED_PRECONDITION). `retry()` rethrows it as-is without consulting
+ * `shouldRetry` — the operation's own verdict wins over the caller's predicate.
+ *
+ * The original error is on `.cause`; the marker is rethrown rather than
+ * unwrapped so `instanceof NonRetryableError` stays a usable signal at the
+ * boundary. Callers that want the underlying error read `.cause`.
+ */
+export declare class NonRetryableError extends Error {
+    readonly cause: unknown;
+    constructor(message: string, cause?: unknown);
+}
+export declare function isNonRetryableError(err: unknown): err is NonRetryableError;
+/**
+ * Optional wrapper for "the attempt budget is spent".
+ *
+ * OFF by default: `retry()` rethrows the LAST error so a caller's existing
+ * `instanceof OnboardingServerError` checks keep working (which is what
+ * `@nodii/onboarding` does today). Opt in with `wrapExhausted: true` when you
+ * want the `@nodii/role-catalog` shape instead — a distinct typed error that
+ * carries the attempt count.
+ */
+export declare class RetryExhaustedError extends Error {
+    readonly cause: unknown;
+    readonly attempts: number;
+    constructor(attempts: number, cause: unknown);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,qBAAa,iBAAkB,SAAQ,KAAK;IAC1C,SAAkB,KAAK,EAAE,OAAO,CAAC;gBACrB,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO;CAK7C;AAED,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,OAAO,GAAG,GAAG,IAAI,iBAAiB,CAE1E;AAED;;;;;;;;GAQG;AACH,qBAAa,mBAAoB,SAAQ,KAAK;IAC5C,SAAkB,KAAK,EAAE,OAAO,CAAC;IACjC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;gBACd,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO;CAQ7C"}

package/dist/errors.js

@@ -0,0 +1,44 @@
+/**
+ * Marker for "do not retry this, whatever the policy says".
+ *
+ * Thrown from INSIDE the operation when the operation itself knows the failure
+ * is terminal (`@nodii/onboarding`'s 403 bot-challenge, `@nodii/role-catalog`'s
+ * FAILED_PRECONDITION). `retry()` rethrows it as-is without consulting
+ * `shouldRetry` — the operation's own verdict wins over the caller's predicate.
+ *
+ * The original error is on `.cause`; the marker is rethrown rather than
+ * unwrapped so `instanceof NonRetryableError` stays a usable signal at the
+ * boundary. Callers that want the underlying error read `.cause`.
+ */
+export class NonRetryableError extends Error {
+    cause;
+    constructor(message, cause) {
+        super(message);
+        this.name = "NonRetryableError";
+        this.cause = cause;
+    }
+}
+export function isNonRetryableError(err) {
+    return err instanceof NonRetryableError;
+}
+/**
+ * Optional wrapper for "the attempt budget is spent".
+ *
+ * OFF by default: `retry()` rethrows the LAST error so a caller's existing
+ * `instanceof OnboardingServerError` checks keep working (which is what
+ * `@nodii/onboarding` does today). Opt in with `wrapExhausted: true` when you
+ * want the `@nodii/role-catalog` shape instead — a distinct typed error that
+ * carries the attempt count.
+ */
+export class RetryExhaustedError extends Error {
+    cause;
+    attempts;
+    constructor(attempts, cause) {
+        const detail = cause instanceof Error ? cause.message : String(cause ?? "unknown error");
+        super(`retry exhausted after ${attempts} attempt(s): ${detail}`);
+        this.name = "RetryExhaustedError";
+        this.attempts = attempts;
+        this.cause = cause;
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,MAAM,OAAO,iBAAkB,SAAQ,KAAK;IACxB,KAAK,CAAU;IACjC,YAAY,OAAe,EAAE,KAAe;QAC1C,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,mBAAmB,CAAC;QAChC,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;IACrB,CAAC;CACF;AAED,MAAM,UAAU,mBAAmB,CAAC,GAAY;IAC9C,OAAO,GAAG,YAAY,iBAAiB,CAAC;AAC1C,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,OAAO,mBAAoB,SAAQ,KAAK;IAC1B,KAAK,CAAU;IACxB,QAAQ,CAAS;IAC1B,YAAY,QAAgB,EAAE,KAAc;QAC1C,MAAM,MAAM,GACV,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,IAAI,eAAe,CAAC,CAAC;QAC5E,KAAK,CAAC,yBAAyB,QAAQ,gBAAgB,MAAM,EAAE,CAAC,CAAC;QACjE,IAAI,CAAC,IAAI,GAAG,qBAAqB,CAAC;QAClC,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;QACzB,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;IACrB,CAAC;CACF"}