fix: heartbeat v2.3 — immediate first beat + lead-clamp regime

Spec review round 4 (two confirmed findings, both fixed):

1. Any bounded first-beat delay can outlive a small tenant-capped lease
   (a 30 s cap is still 28 s too late for a 2 s grant). The first extend
   now fires IMMEDIATELY: it costs one extension but provably beats an
   arbitrarily small lease, and its response primes the grant ledger
   with a real grant sample. All Date-derived effective-TTL/hint
   scheduling is removed from the heartbeat path (start_heartbeat drops
   the hint parameter; reserve() no longer threads date_ms).
   ApiResponse::date_ms + httpdate parsing remain as general response
   utilities with unit and e2e tests.

2. Under a server-side maximum-LEAD clamp (extend re-stamps
   expires_at ~ now + L), successive expires_at_ms differences measure
   elapsed time, not lease — grant-derived cadence is self-referential
   and collapses to the 500 ms floor, burning max_extensions in
   seconds. Each success is now classified (is_lead_clamp_grant): a
   grant that is non-positive, or < 0.9*requested while within
   [0.75, 1.25]x elapsed-since-last-success (a clock reading, not a
   lease), holds the cadence at min(requested/2, 30 s), never
   tightened, with a tracing::warn once per heartbeat. The lower band
   arm lets a real-but-small per-extend grant re-tighten after a skip
   doubles the gap. The same held cadence paces retries before any
   grant sample exists, so a failed immediate first beat can never
   hot-loop at zero delay.

Everything else unchanged: skip rule (lead_min >= 1.5*last_grant),
requested-amount wire extends, same-key transient retry, permanent stop
set, 2xx-as-applied, intended-instant scheduling, cancellation.

Also folds in the uncommitted v2.2 grant-ledger baseline this refines
(rounds 2-3: Date rejected as a correctness input, grant ledger with
same-frame arithmetic, per-beat delays, TENANT_CLOSED/NOT_FOUND stops).

Tests: wiremock suite reworked — immediate-first-beat cadence
(extend@0/1000/2000, skip@3000, extend@4000), capped-grant discovery via
the immediate beat, 503-on-first-beat single held-cadence retry with
same idempotency key, lead-clamp echo responder holding cadence (no
floor collapse), zero-grant immediate prime holding cadence, per-extend
grant clamp (+ttl/4) still tightening to 500 ms, small-ttl liveness,
permanent stops, unknown-status 2xx as applied. Pure cadence/regime
functions unit-tested (held-cadence pins incl. 30 s cap, lead-clamp
band boundaries, skip threshold, trace). Obsolete effective-TTL/date-
hint tests removed; Date parsing tests kept; date_ms asserted e2e in
response_test.

CHANGELOG and AUDIT amended in place (same 0.3.1 release, PR #75).

Author: amavashev

AUDIT.md

@@ -8,7 +8,7 @@
 
 ---
 
-## 2026-07-27 — heartbeat extend-drift fix, grant-ledger v2.2 (v0.3.1)
+## 2026-07-27 — heartbeat extend-drift fix, grant-ledger v2.3 (v0.3.1)
 
 P1 liveness, fleet-wide (same bug in all four SDKs). The spec's `extend_by_ms`
 is relative to the reservation's *current* `expires_at_ms`, not request time,
@@ -29,32 +29,47 @@ correctness input — RFC 9110 `Date` is a whole-second best-effort
 *origination* timestamp replaceable by intermediaries, and in cycles-server
 `expires_at_ms` comes from Redis `TIME` while `Date` comes from the HTTP
 layer (not the same clock), so the difference is no lease measurement and the
-1000 ms upward clamp fabricated lease. Final **grant-ledger (v2.2)** design:
-correctness rests on `lead_min = grants_sum − elapsed` (signed, starts 0), a
-rigorous lower bound built only from same-frame arithmetic — each grant is
-the difference of successive server-frame `expires_at_ms` values (reserve's
-threaded from the guard, then each extend response's), elapsed is
-client-monotonic to the beat's intended instant. Skip iff a grant sample
-exists and `lead_min ≥ 1.5·last_grant`; else extend by the **requested**
-`ttl_ms`. Per-beat delays replace the fixed interval: first beat
-`min(requested/2, 30 s, date_hint/2)` (the `Date`-derived estimate survives
-only as this raw, unclamped cadence hint — `ApiResponse::date_ms`, `httpdate`
-direct dep), then `clamp(last_grant/2, 500 ms, requested/2)`, so the cadence
-tracks observed grants (clamped grants speed it up); transient failures retry
-at the current cadence with the same idempotency key (replay dedupe); beats
-schedule from intended instants and realign to now after stalls
-(`MissedTickBehavior::Skip` equivalent, hand-rolled for variable delays). Any
-2xx counts as applied (`expires_at_ms` authoritative, warn on odd status);
-permanent codes (`RESERVATION_EXPIRED`/`RESERVATION_FINALIZED`/
-`MAX_EXTENSIONS_EXCEEDED`/`TENANT_CLOSED`/`NOT_FOUND` or HTTP 410/404) stop
-the heartbeat. Cancellation unchanged. Ten wiremock tests with dynamic expiry
-responders (cadence extend@1..4/skip@5/extend@6; capped grant keeping
-`extend_by_ms` at the request while beating at hint/2 then grant/2; garbage
-`Date` → requested/2; key reuse; permanent stops; small-ttl liveness; clamped
-grants never skipping; unknown-status 200 as applied) + extracted pure
-delay/lead functions unit-tested (incl. the 30 s first-beat cap and raw
-unclamped hint) in `src/heartbeat.rs`; `Date`-parsing unit tests in
-`src/response.rs`. Coverage 95.73%; tests, clippy `-D warnings`, fmt green.
+1000 ms upward clamp fabricated lease. Spec review round 4 then removed
+lease estimation from scheduling entirely: any *bounded* first-beat delay
+can outlive a small capped lease, so the **first extend fires immediately**
+(costs one extension, provably beats an arbitrarily small grant, and primes
+the ledger with a real sample; `ApiResponse::date_ms`/`httpdate` stay as
+general response utilities the heartbeat no longer consumes). Round 4 also
+found that under a server-side **maximum-LEAD clamp** (extend re-stamps
+`expires_at ≈ now + L`) successive `expires_at_ms` differences measure
+*elapsed time, not lease* — grant-derived cadence is self-referential there
+and collapses to the 500 ms floor, burning `max_extensions` in seconds.
+Final **grant-ledger (v2.3)** design: correctness rests on
+`lead_min = grants_sum − elapsed` (signed, starts 0), a rigorous lower bound
+built only from same-frame arithmetic — each grant is the difference of
+successive server-frame `expires_at_ms` values (reserve's threaded from the
+guard, then each extend response's), elapsed is client-monotonic to the
+beat's intended instant. Skip iff a grant sample exists and
+`lead_min ≥ 1.5·last_grant`; else extend by the **requested** `ttl_ms`.
+Per-beat delays replace the fixed interval: first beat immediate, then
+`clamp(grant/2, 500 ms, requested/2)` (clamped grants speed it up) — unless
+`is_lead_clamp_grant` classifies the grant as a clock reading (non-positive,
+or `< 0.9·requested` while within `[0.75, 1.25]×` elapsed-since-last-
+success), which holds the cadence at `min(requested/2, 30 s)` and warns once
+per heartbeat; the same held cadence paces retries before any grant sample,
+so a failed immediate beat cannot hot-loop. Transient failures retry with
+the same idempotency key (replay dedupe); beats schedule from intended
+instants and realign to now after stalls (`MissedTickBehavior::Skip`
+equivalent, hand-rolled for variable delays). Any 2xx counts as applied
+(`expires_at_ms` authoritative, warn on odd status); permanent codes
+(`RESERVATION_EXPIRED`/`RESERVATION_FINALIZED`/`MAX_EXTENSIONS_EXCEEDED`/
+`TENANT_CLOSED`/`NOT_FOUND` or HTTP 410/404) stop the heartbeat.
+Cancellation unchanged. Eleven wiremock tests with dynamic expiry responders
+(immediate first beat + extend@0/1000/2000, skip@3000, extend@4000; capped
+grant keeping `extend_by_ms` at the request while the immediate beat
+discovers the cap; 503 on the immediate beat → single held-cadence retry
+with the same key; permanent stops; small-ttl liveness; per-extend grant
+clamp still tightening to grant/2; lead-clamp echo responder holding
+cadence instead of collapsing; zero-grant immediate prime holding cadence;
+unknown-status 200 as applied) + extracted pure cadence/regime functions
+unit-tested (incl. the 30 s held-cadence cap and the lead-clamp band
+boundaries) in `src/heartbeat.rs`; `Date`-parsing unit tests in
+`src/response.rs`. Coverage 95.12%; tests, clippy `-D warnings`, fmt green.
 
 ## 2026-07-27 — v0.3.0 self-review hardening
 

CHANGELOG.md

@@ -169,16 +169,7 @@ impl CyclesClient {
         validation::validate_grace_period_ms(req.grace_period_ms)?;
         validation::validate_non_negative(req.estimate.amount, "estimate.amount")?;
 
-        // The metadata variant surfaces the HTTP `Date` header: paired with
-        // the body's expires_at_ms it yields a rough TTL estimate used as
-        // the heartbeat's *first-beat cadence hint* when a tenant policy
-        // (max_reservation_ttl_ms) silently capped the grant. Hint only —
-        // Date is not the same clock as expires_at_ms (RFC 9110 whole-second
-        // best-effort origination timestamp vs. Redis TIME), so correctness
-        // never depends on it; see src/heartbeat.rs module docs.
-        let resp = self.create_reservation_with_metadata(&req).await?;
-        let date_ms = resp.date_ms;
-        let resp = resp.into_inner();
+        let resp = self.create_reservation(&req).await?;
 
         if resp.decision.is_denied() {
             return Err(Error::BudgetExceeded {
@@ -238,7 +229,6 @@ impl CyclesClient {
             resp.expires_at_ms,
             resp.affected_scopes.clone(),
             req.ttl_ms,
-            crate::heartbeat::date_ttl_hint_ms(resp.expires_at_ms, date_ms),
             req.subject.clone(),
             req.action.clone(),
         ))

src/client.rs

@@ -83,21 +83,20 @@ impl ReservationGuard {
         expires_at_ms: Option<u64>,
         affected_scopes: Vec<String>,
         requested_ttl_ms: u64,
-        date_ttl_hint_ms: Option<u64>,
         subject: Subject,
         action: Action,
     ) -> Self {
         let cancel = CancellationToken::new();
         // The reserve response's expires_at_ms (server frame) is the base of
-        // the heartbeat's grant ledger; the Date-derived TTL estimate is a
-        // first-beat cadence hint only (the Date header is not the same
-        // clock as expires_at_ms); see src/heartbeat.rs module docs.
+        // the heartbeat's grant ledger. The first extend fires immediately —
+        // a tenant policy may have silently capped the lease far below the
+        // requested TTL, and no bounded delay provably beats an arbitrarily
+        // small grant; see src/heartbeat.rs module docs.
         let heartbeat = start_heartbeat(
             client.clone(),
             id.clone(),
             requested_ttl_ms,
             expires_at_ms,
-            date_ttl_hint_ms,
             cancel.clone(),
         );