feat: contract 1.8 — §16 retry, §17 memo, §18 close(), §19 telemetry (D5)

[ilpanich]

Implements all four SDK quality-of-life sections that contract 1.8 added (ilpanich/axiam#283), and re-vendors CONTRACT.md at 1.8. openapi.json is unchanged — 1.8 is docs-only.

This is the first of eleven SDKs. Four decisions below get copied into the other ten, so they are worth disagreeing with now rather than after the fan-out.

Section	Level	What landed
§16 retry policy	MUST	src/retry.rs, wired into every authz read, replacing backon
§18 deterministic shutdown	MUST	close() + ensure_open() on every entry point
§19 telemetry hooks	SHOULD	src/telemetry.rs + examples/telemetry_hook.rs
§17 decision memo	MAY	src/memo.rs, opt-in, off by default

§16 — the policy that was being required but never defined

§11.2 rule 5 and §14.2 rule 6 had both been telling SDKs to retry "under the SDK's existing bounded read-only retry policy" while no such policy existed in the contract. This crate's improvisation was backon's defaults with with_max_times(2) — no jitter, no Retry-After. Contract 1.8 wrote the table down; this implements it.

Hand-rolled rather than reconfigured, for two things backon cannot express:

• Full jitter. §16.1 requires the wait uniform over [0, backoff]. backon's with_jitter() adds a value in [0, min_delay) — a much narrower distribution. That difference is the entire clause: partial jitter keeps every client's retries clustered at the same instant, which causes the thundering herd retries are meant to prevent.
• Retry-After. No seam for a server-supplied floor on the wait.

Both non-deterministic inputs are injected behind traits, as §16.7 demands — "a test that really waits 200 ms is a test nobody runs." The tests pin the jitter fraction to 0.0 and 1.0 to prove the range really is [0, backoff] and not backoff ± something, and record delays instead of taking them. The whole file runs in 0.12 s.

Nothing that changes server state is retried. The ineligible list is disqualified twice over: a transient failure after the server committed is indistinguishable at the client from one before it, 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 into a hard invalid_grant. The retry-eligible set is unchanged from before this PR: authz reads only.

§17 — opt-in, and the warning is the feature

Off by default, because §11.2 rule 6's ban on caching authorization decisions is still the default behaviour.

• TTL clamped to 5 s. The server's equivalent (AXIAM__AUTHZ__DECISION_CACHE_TTL_SECS) is an unclamped u64, so an operator can configure a multi-hour staleness window — a known residual. The client has no reason to repeat it.
• Allows and denies memoized identically. Caching only one makes the two outcomes take measurably different times, leaking which occurred to anyone who can observe latency.
• Failures never memoized, enforced structurally: put_at is only reachable on the Ok path, so the rule can't be forgotten rather than merely being checked. Caching a transport error as a deny would turn a blip into a TTL-long outage.
• Cleared on any credential change. Entries are keyed by subject, not session, so re-authenticating as a different principal would otherwise inherit the previous one's decisions.

The README states reads-your-own-writes is not guaranteed in those words, in a blockquote. The admin UI that grants a role and immediately re-checks is the case that breaks, and it breaks silently.

§18 — close() does not log out

Idempotent; use-after-close raises an error naming the cause rather than silently reconnecting.

It never reaches the network. The server-side session deliberately outlives the client object — that is what lets a process restart and resume — so a close() that logged out would silently end every user's session on each deploy. tests/close_lifecycle_test.rs asserts this against the wire, not the return value, because that is the only way to catch it: a logout wired into close() succeeds silently.

reqwest exposes no eager pool-shutdown hook, so the guarantee close() actually makes is "no further requests", enforced by ensure_open() rather than merely documented.

§19 — and why the example matters

A panicking hook cannot fail the operation that fired it (catch_unwind), and TelemetryEvent has a closed field set with no escape hatch, so there is no way to leak a token into a payload bound for a metrics backend. Path templates, never substituted URLs.

One RequestStart/RequestEnd pair per attempt, not per logical call, so callers can count real wire calls. Running examples/telemetry_hook.rs against an unreachable host prints:

check_access  failure  count=3  mean=354ms
retries: check_access 2

That is §16's attempt cap made observable, and the one-line argument for §16.5: without the hook those three wire calls are a single slow failure, and a server degrading under retries looks healthy right up until the retries stop being enough.

The example pulls no metrics crate — §19 exists so callers can wire OTel or Prometheus without this crate depending on either, and shipping an opentelemetry dev-dependency to demonstrate that would have undercut the point. The exact OTel mapping is written out alongside it.

Two things I got wrong, caught locally

• I clamped Retry-After to the 5 s delay cap. My own test caught the contradiction: that cap governs the computed backoff, while §16.1 makes the hint a floor with no ceiling. Clamping means retrying sooner than the server said it would be ready — the one thing the clause forbids. Exposure stays bounded by the attempt cap anyway, and a server that wants to stall a caller can simply not answer.
• A public doc linked to a private item. decision_memo_ttl linked crate::memo::MAX_TTL; memo is private. CI runs cargo doc with RUSTDOCFLAGS: -D warnings, so this would have been a red docs job — found by running that gate with the same flag rather than waiting for CI.

Decisions worth a second opinion before the fan-out

1. Retry-After rides an internal Attempt type, not AxiamError. §16 requires the policy to honor the hint, not callers to read it, and putting it on the public non_exhaustive Network variant would have churned 45 construction sites for something no caller asked for. The public error type is unchanged. If you'd rather callers could read it, that is cheap now and expensive after ten more SDKs.
2. Hand-rolling the backoff instead of configuring each language's retry library — justified above, but it is 11 hand-rolled implementations.
3. close() not logging out, and being async because TokenManager::clear() is.
4. The memo's 5 s clamp being silent rather than a construction error.

Verification

Full sweep from a clean target/:

Gate	Result
cargo test --all-features	every binary green, 0 failures
cargo clippy --all-targets --all-features -- -D warnings	clean
cargo fmt --all --check	clean
cargo doc --all-features --no-deps with RUSTDOCFLAGS=-D warnings	clean
cargo build --examples --all-features	clean
Leak gate (no eyJ-prefixed strings in target/debug/)	clean
TLS-bypass lint (§6)	clean

New tests: 13 retry unit, 9 memo unit, 4 §18 integration, 7 §17 integration. The 5 pre-existing authz retry integration tests pass unchanged against the new policy.

Notes

• Removed the direct backon dependency — nothing referenced it once §16 landed. It stays in Cargo.lock as a transitive dep of lapin under the amqp feature.
• Conformance line now names §17 and §19. §16 and §18 are MUST-level and deliberately not named: a MUST is not something an SDK opts into.
• No open issues in this repository to reference.

---

Generated by Claude Code