docs(sdk): §16 preamble errata — five SDKs diverged (1.8.2)

[ilpanich]

Second correction to the same paragraph. The count has been wrong twice, and both times the fault was the survey method rather than the writing — so this records the method as well as the answer.

Revision	Claimed	Missing
1.8	two (Java, Rust)	TypeScript, Go, C#
1.8.1	three (+ TypeScript)	Go, C#
1.8.2	five (+ Go, C#)	— verified exhaustively

Why it was wrong twice

1.8's survey grepped only parts of each repo. 1.8.1's follow-up grepped $repo/src uniformly — which silently skipped Go entirely, because its sources live at the repo root, not under src/. Neither pass looked at C# at all. A grep that finds nothing looks exactly like a repo with nothing to find, which is what made the same mistake survive a correction.

The command behind this table makes no path assumption and enumerates per-language extensions:

grep -rlniE "backoff|jitter" $repo --include="*.go" --include="*.cs" --include="*.kt" ...

I also confirmed the six negatives rather than inferring them, and checked one false positive by hand: PHP's for ($attempt = 0; $attempt < 3; $attempt++) in OidcClient.php is §9 single-flight coordination, not a §16 transport retry.

The verified table

SDK	Attempts	Base	Cap	Jitter	Retry-After	Wired in?
Java	3	200 ms	5 s	full	floor	yes
C#	3	200 ms	5 s	yes	—	yes
Rust	3	library default	—	none	ignored	yes
Go	3	100 ms	none	none	ignored	yes
TypeScript	3	1000 ms	8 s	partial	replaced the backoff	no

Six had none at all: Python, Kotlin, PHP, Swift, C, C++.

Three cells are called out in the text, because each is a distinct way the clause gets got wrong:

• TypeScript, Retry-After — retryAfterMs ?? backoffDelayMs(attempt) lets a Retry-After: 0 retry immediately, defeating the backoff. §16.1's "floor, never a ceiling" was written on principle and turned out to describe shipped code.
• TypeScript, "wired in" — the helper was exported and unit-tested but called by nothing. Already carried into 1.8.1 as the requirement to assert §16 through the public check_access surface.
• Go — backoff *= 2 with no cap and no jitter is the shape this section most wants to eliminate. Uncapped, the third wait is bounded by nothing but the attempt count; unjittered, every client retries in lockstep.

A non-conformance the contract can't fix

C# exposes MaxRetryAttempts, RetryBaseDelay and RetryMaxDelay as public settable options. Its defaults match the table exactly — it is the closest of the five — but §16.1 permits only lowering the cap or disabling retry outright. A caller who can raise them turns one client into the herd the policy exists to prevent.

That is a code fix, tracked to the C# SDK's own D5 PR. Noted here so the table isn't read as "C# conforms".

Verification

scripts/check-doc-links.sh — 129 relative links resolved across 21 files. Version footer 1.8.1 → 1.8.2.

Notes

• Docs only: one paragraph in sdks/CONTRACT.md plus the footer. No code, no OpenAPI, no proto.
• Branch restarted from main after docs(sdk): §16 preamble errata — three SDKs diverged, not two (1.8.1) #284 merged, per the merged-PR rule.
• No open issues in this repository to reference.

---

Generated by Claude Code