docs(sdk): contract 1.8 — retry policy, decision memo, close(), telemetry (D5)

[ilpanich]

Adds the four SDK quality-of-life sections D5 calls for — and fixes a dangling normative reference found while writing the first of them.

Docs only: one file, sdks/CONTRACT.md, +344/−7. No code, no OpenAPI, no proto. This is the contract half of D5; the eleven-repo implementation fan-out follows under D6's recurring gate.

The defect this uncovered

§11.2 rule 5 and §14.2 rule 6 have both been instructing SDKs to retry "under the SDK's existing bounded read-only retry policy" — and no such policy was ever defined in this contract.

I surveyed all eleven repos before writing a line of it:

SDK	Read-only retry policy today
Java	3 attempts, 200 ms base, 5 s cap, full jitter, honors Retry-After
Rust	3 attempts via backon defaults, NetworkError only, no jitter, no Retry-After
The other nine	None. Only §9's refresh-then-retry-once, which is a different mechanism

So two normative clauses were deferring to eleven separate guesses, and the two SDKs that did implement something disagreed with each other. Same defect class as the §14.3 device_login errata in 1.7, but this one was live in two sections at once.

§16 is that missing policy as one binding table. The values follow Java's, which was closest to what the phrase implied.

What the four sections settle

§16 Retry Policy — MUST

• Eligibility is "changes no server state", explicitly not "is an HTTP GET." AXIAM's authorization check is a POST with a request body and is the single most important operation in the section. An SDK that gates retry on the HTTP verb retries nothing that matters. Called out in bold because it is the mistake this section exists to prevent.
• Full jitter, specified as a range and tested as one. Not "backoff ± 10%". Partial jitter keeps every client's retries clustered around the same instant, which causes the failure mode retries are meant to fix. The required test pins the PRNG to 0 and to 1 to prove the range really is [0, backoff].
• Retry-After is a floor, never a ceiling — so a Retry-After: 0 cannot defeat the backoff.
• The ineligible list is justified twice over: these operations change state (a transient failure after the server committed is indistinguishable at the client from one before it committed), and their credentials are single-use (an authorization code, a device code at redemption, a rotating refresh token) so a retry replays a spent credential and turns a recoverable blip into a hard invalid_grant.
• It does not amend §9. The two compose in one direction only: an operation inside a §9 refresh-retry may itself be §16-retried, but a §9 refresh may not be, and a mid-operation refresh does not reset the §16 budget.
• Revocation gets its own note: §12.1's RFC 7009 idempotency remark is about server behaviour and is not licence for a client to retry a mutation.

§17 Client-Side Decision Memo — MAY, off by default

§11.2 rule 6's ban on decision caching stands as the default; §17 is the single opt-in exception, and the rule is amended to say exactly that rather than being quietly contradicted.

• Mirrors the server's own DECISION_CACHE_TTL_SECS / SESSION_VALIDATION_CACHE_TTL_SECS bound rather than inventing a second staleness story.
• TTL clamped to 5 s. The server's equivalent setting is an unclamped u64 that lets an operator configure a multi-hour staleness window — a known residual. The client has no reason to repeat it, and the contract says so.
• Allows and denies cache identically. Asymmetric caching changes the timing of the two outcomes and so leaks which one occurred to anyone who can observe latency.
• Read-your-own-writes is not guaranteed, in those words. The admin UI that grants a role and immediately re-checks is the case that breaks, and it breaks silently.
• Rule 10: the memo must never serve §11.2 rule 5's fail-closed path. Serving a stale allow during an outage inverts fail-closed into fail-open at exactly the moment it matters.
• Never negative-caches a failure — caching a transport error as a deny would turn a blip into a TTL-long outage.

§18 Deterministic Shutdown — MUST

Each language's existing idiom, not a new invented spelling. Idempotent; releases everything; use-after-close raises rather than being undefined behaviour in the manual-memory languages.

Close must not reach the network. An SDK that logged out on close would silently end sessions on every deploy. The required test asserts against the transport rather than the return value, because that is what catches a logout accidentally wired in.

§19 Telemetry Hooks — SHOULD

Optional callbacks so callers can wire OpenTelemetry or Prometheus without this SDK depending on either; the OTel adapter ships as an examples/ entry per SDK.

• A hook that throws is caught and swallowed. Telemetry is not permitted to fail an authorization check.
• Payloads never carry tokens, bodies, or Sensitive<T> contents — this surface exists to be shipped to a metrics backend, which is the last place a bearer token should land. The required test scans the serialized payload for the fixture token, the same discipline §12/§14/§15 use on error paths.
• Path templates, not substituted URLs, so a metric label cannot become a cardinality bomb.
• One request_start/request_end pair per attempt, not per logical call, so a caller can count real wire calls. §16.5 requires the retry event for the same reason: a retried-then-succeeded operation is otherwise invisible, and that silence is the standing objection to automatic retry.

Conformance — stated plainly, not papered over

§16 and §18 are MUST-level and land unimplemented everywhere. §18 exists today only in the TypeScript and Python gRPC clients and C's axiam_client_free; §16 exists in two disagreeing forms.

The Closing Notes say so directly: each SDK is non-conformant on those two sections until the D6 fan-out lands them, and its README must not imply otherwise. They are not named in the conformance statement, because a MUST is not something an SDK opts into. §17 and §19 are optional and are named when shipped, like §14/§15.

Verification

Gate	Result
scripts/check-doc-links.sh	129 relative links resolved across 21 files
scripts/check-remediation-evidence.py	37 verified, 0 failed, 0 skipped, 0 unparseable
scripts/check-frontend-coverage.py	30 handler modules, all recorded
docs/api/openapi.json parses	ok

New internal anchors follow the file's existing convention and resolve under the link-checker.

Notes

• Contract 1.6 → 1.7 was the device_login errata (docs(sdk): contract 1.7 — device_login credential-adoption errata (D6) #282). This is 1.7 → 1.8.
• No open issues in this repository to reference.

---

Generated by Claude Code