Kata: retry with exponential backoff and jitter

On the dive boat	In the code
the card allows the first dive and three repeats	fn runs at most 1 + retries times (step 2)
after a failed dive she rests on deck, each rest twice the last but never past the card's limit	min(maxMs, baseMs × factor^i) (step 6)
after the last failed dive she heads for harbour at once	no wait after the last failure (step 4)
"anchor wedged under rock" ends the job at the first look	shouldRetry false: rethrow at once (step 4)
the job sheet records what the last dive found, in her words	rethrow the last error unchanged (step 5)
each job starts its own count on its own sheet	state per call (step 8)
the instructor checks a new diver's card with a stopwatch she can skip forward and a die she sets	injected sleep and random (step 9)

In real terms: a correct retry makes at most 1 + retries calls, sleeps only between them, stops at once on a permanent error, and rejects with the error that stopped it.

Breaks down when: a diver can see the anchor's state before she dives; code learns only by trying. And the club's doubling rule is the analogy's own, not dive-table practice.

Contrasting case: a diver who dives once and goes home. That is a plain await fn(): no waits, and the first failure reaches the caller.

4.1 ExamHall EXH-2800: autosave gives up on the first 503 (MR !3100)

At 09:00 a burst of 503s from the answers API made ExamHall's autosave show "Not saved" while the API recovered within a second. MR !3100 sends each save through the reference retry, with shouldRetry true only for 503. Every autosave carries a sequence number and an Idempotency-Key, which is what makes repeating it safe (api-idempotency-keys).

export async function retry(fn, {
  retries = 3, baseMs = 100, factor = 2, maxMs = 10_000, jitter = 'full',
  shouldRetry = () => true, sleep, random = Math.random,
} = {}) {
  for (let attempt = 0; ; attempt += 1) {
    try {
      return await fn(attempt);
    } catch (error) {
      if (attempt >= retries || !shouldRetry(error)) throw error;
      const capped = Math.min(maxMs, baseMs * factor ** attempt);
      await sleep(jitter === 'full' ? capped * random() : capped);
    }
  }
}

The same outage replayed on a virtual clock, with random stubbed:

4.1 MR !3100 retry(putAnswer, { retries: 5, baseMs: 250, factor: 2, maxMs: 4000, jitter: 'full', shouldRetry: 503 only }) · random() stub 0.8, 0.4, 0.6
4.1 call 1 at 0 ms: 503 · wait 200 (0.8 × 250)
4.1 call 2 at 200 ms: 503 · wait 200 (0.4 × 500)
4.1 call 3 at 400 ms: 503 · wait 600 (0.6 × 1000)
4.1 call 4 at 1000 ms: 200 saved · no more waits
4.1 resolved saved after 4 calls · waits written down 200 + 200 + 600 = 1000 ms

The waits sit between calls only, each the capped backoff times that wait's own draw (steps 4, 6, 7). After the success nothing waits.

4.2 Proof domain, ticketing: the test list as a mutation check

A box office's seat-hold client uses the same retry. Its test list (step 10, lib/cases.mjs) is run against the reference and against four one-line mutants of it:

4.2 the test list T1, T2, T3, T4, T5, T6, T7 on the reference: passes 7 of 7
4.2 mutant await removed        (return await fn(attempt); -> return fn(attempt);): killed by T2, T3, T5, T6, T7
4.2 mutant shouldRetry dropped  (|| !shouldRetry(error) -> nothing): killed by T4
4.2 mutant cap dropped          (Math.min(maxMs, baseMs * factor ** attempt) -> baseMs * factor ** attempt): killed by T5, T6
4.2 mutant exponent dropped     (baseMs * factor ** attempt -> baseMs): killed by T2, T3, T5, T6, T7

Each mutant is killed by at least one test: removing await lets rejections escape the catch (step 3), dropping shouldRetry retries a seat already taken (step 4), and dropping the cap or the exponent changes the waits (step 6). A test list earns its place by killing mutants like these.