ilpanich / axiam-typescript-sdk / 31327955085

94%

Build Type

push

github

Committed by web-flow

Commit Message

feat: §16 retry, §17 memo, §18 close(), §19 telemetry (D5) (#47)

Implements the four contract-1.8 quality-of-life sections, and fixes two
defects found while doing it. Re-vendors CONTRACT.md at 1.8.1.

THE BUG THAT MATTERED: withRetry was never called.

`src/rest/retry.ts` was exported, unit-tested and green — and no production
path invoked it. `checkAccess` went straight to axios. So this SDK performed
NO read-only retries at all, while `test/rest/retry.test.ts` passed and the
exported symbol made it look wired. §11.2 rule 5 has required retries here
since it was written, and the requirement was silently unmet.

A tested helper nobody calls is worse than an absent one: the passing tests are
exactly what stop anyone from looking. That is why the new conformance tests
assert through the public `checkAccess` surface — counting requests on the wire
— rather than against the helper in isolation, and why contract 1.8.1 now
requires that of every SDK claiming §16.

The second defect, in the same file: `retryAfterMs ?? backoffDelayMs(attempt)`
made the server's hint REPLACE the computed backoff, so a `Retry-After: 0`
retried immediately and defeated the policy entirely. That is precisely what
§16.1's "floor, never a ceiling" forbids. I wrote that clause on principle for
contract 1.8; it turned out to describe a defect we already shipped.

§16. The policy now matches the normative table: 3 attempts, 200 ms base, 5 s
cap, full jitter over [0, backoff], Retry-After as a floor. The old parameters
(1000 ms / 8 s / partial jitter) were a third divergent invention — Java, Rust
and this SDK each had different ones, which is what contract 1.8 exists to end.
Full jitter is the substantive change: partial jitter keeps every client's
retries clustered around the same instant, causing the thundering herd retries
are meant to prevent. `maxAttempts` is gone from RetryOptions — §16.1 fixes the
cap and forbids raising it.

§17. Opt-in decision memo, off by default (`decisio... (continued)

Coverage Stats

857 of 935 branches covered (91.66%)

Branch coverage included in aggregate %.

90 of 95 new or added lines in 7 files covered. (94.74%)

16 existing lines in 2 files now uncovered.

1409 of 1457 relevant lines covered (96.71%)

40.01 hits per line