perf(envelope): jittered backoff between OCC retries; bounded Retry-After (#72)

[JumpTechCode]

Closes #72.

Problem

execute() retried OccConflict up to MAX_OCC_RETRIES (5) with zero delay between attempts, and the RetryExhausted 503 advertised Retry-After: 0. Server-broken deadlocks (40P01) from the pick/cancel-vs-reaper ABBA lock ordering (ADR-0019) are translated to OccConflict (ADR-0020) and absorbed by this same loop. With no spacing, a loser re-ran instantly against the same hot rows — re-forming the deadlock or re-losing the same CAS — and could burn all five attempts in microseconds, returning 503 where a few ms of spacing would have let it commit. Retry-After: 0 compounded it by inviting the herd to rejoin on the same beat.

Correctness was never at risk (CAS/guards arbitrate), but the load harness — built to exercise exactly this contention — would read an inflated 503 rate.

Fix

• Full-jitter exponential backoff between OCC retries: rand() * min(cap, base · 2^attempt) with base 10ms, cap 200ms. Injected via sleep/rand seams so the unit suite stays deterministic. No pause after the final attempt; the idempotency-claim (EXISTS) replay branch stays backoff-free.
• Bounded, non-zero Retry-After (1–3s, jittered) on the RetryExhausted 503 instead of 0.

The 503 status itself (ADR-0020) is unchanged; only the spacing and the header value changed. execute gains keyword-only sleep/rand seams (defaulted), so the 13 call sites are untouched.

Scope / deliberate non-goal

The ABBA lock-order inversion (ADR-0019) is left in place: backoff mitigates the deadlock-driven 503s rather than resolving them at source. Aligning the reaper and pick/cancel lock orders is a larger, separately-reasoned change. Recorded as the accepted V1 posture in ADR-0028.

Tests

• test_envelope.py: pure _occ_backoff_delay (full-jitter exponential, capped, scales with jitter); execute backs off between each attempt pair with the right schedule and not after the last; the replay branch never backs off; existing retry tests inject a no-op sleep to stay instant.
• test_api_errors.py: RetryExhausted 503 advertises a bounded non-zero Retry-After.
• test_api_allocate.py: updated the exhaustion test from == "0" to 1 ≤ Retry-After ≤ 3.

make verify green locally: 511 passed, 99.15% coverage.

🤖 Generated with Claude Code