feat: §17 memo, §18 close(), §19 telemetry, §16.6 switch (D5)

[ilpanich]

Re-vendors CONTRACT.md at 1.8.2. §16's arithmetic is unchanged here — this SDK is the exception among the five that had invented a policy.

Fifth of eleven, after rust#45, typescript#47, python#34 and go#31.

§16 was already right

internal/Retry does 3 attempts, 200 ms base, 5 s cap, full jitter over [0, backoff], and honors Retry-After via Math.max. It is the implementation whose parameters contract 1.8 adopted — and of the five SDKs that had each invented one, the only one that got both full jitter and Retry-After-as-a-floor right.

I checked the TypeScript failure mode first. Before touching anything I verified that checkAccess actually routes through withRetry — that is where an exported, unit-tested, green helper turned out to be called by nothing. Here all three authz paths were genuinely wired, so the new §16 conformance tests are a regression lock, not a fix.

Two things were missing rather than wrong:

• Builder.retryDisabled() (§16.6). No builder method for the attempt cap, base or delay cap: §16.1 permits lowering the cap or disabling retry, never raising either.
• The §16.5 retry event. withRetry gains an attempt-aware overload that passes the 1-based attempt into the operation and emits Retry before each wait.

§17 — generic, so internal stays internal

DecisionMemo<T> is generic in the decision type rather than importing AxiamClient.AccessResult. DiscoveryCache<T> already establishes that convention in this package, and an internal helper reaching back into the public client class would invert the dependency.

Off by default, clamped to MAX_TTL (5 s), synchronized — a Java client is routinely shared across a request-handling thread pool.

Reads-your-own-writes is not guaranteed.

§18 — idempotent via compareAndSet

Not merely "calling it twice doesn't throw": compareAndSet means a concurrent double-close does the work once rather than two threads racing the executor shutdown and connection-pool eviction.

close() does not log out and never reaches the network — asserted against the wire, because a logout wired into close succeeds silently.

§19 — sealed, which is the Java-specific version of the guarantee

TelemetryEvent is a sealed hierarchy of records. No code outside this library can add a variant, so "no event payload can carry a secret" is enforced by the compiler rather than by review — the strongest form of that guarantee across the SDKs so far.

One RequestStart/RequestEnd pair per attempt.

A test that needed rethinking

logout() rejects with AuthError when there is no session, so the memo-clear test could not simply call it on a fresh client.

The clear runs before that check, deliberately: the trigger is the caller's intent to change credentials, not the server's answer. A logout that failed still means this caller is done with the principal whose decisions are cached, and entries are keyed by subject rather than session — so keeping them would let a re-authentication as a different principal inherit them. The test now asserts exactly that, which is sharper than what I first wrote.

Verification

Gate	Result
mvn test	471 passed (20 new), 0 failures
JaCoCo check	line-coverage gate (0.93) satisfied
scripts/tls-bypass-gate.sh	clean across src/ and examples/
mvn compile	clean

The pre-existing RetryTest passes unchanged — the arithmetic it covers was not touched.

Notes

• New example: examples/telemetry-hook/TelemetryHookExample.java, with the Micrometer mapping written out. It pulls no metrics dependency, which is the point of §19.
• No open issues in this repository to reference.

---

Generated by Claude Code