L3 3.2: async disk->L2 reload + request hold (Model B), zero new collectives, EAGLE-correct

On a radix miss, reload the evicted-but-L3-durable suffix from disk into L2 + insert a fresh
radix node, holding the triggering request until then (mirrors the storage-prefetch hold, which
is disabled under CP). The reloaded prefix re-enters the radix as a normal L2 node, so the
existing load_back serves L2->L1 -- no new device path.

Design (docs_internal/cp_hicache_l3_phase3_impl_design.md §9, refined for minimal sync):
- ENTRY (scheduler _prefetch_kvcache, enable_cp_l3 branch): mark a miss-with-suffix as a reload
  candidate (rank-uniform: requests are broadcast). cp_l3_reload_lookup computes the suffix's
  full-page content hashes -- the SAME SHA chain spill wrote (compute_node_hash_values).
- RESERVE + ADMIT fold into the existing per-tick _drain_l3_control_queues MINs -- ZERO new
  collectives: the candidates' per-rank exists_prefix counts ride the qsize MIN vector -> a
  rank-uniform agreed count C (this reconciles the async-LMDB read-skew); reload-ack oks ride the
  durable ok-AND. Reserve is then collective-free (deterministic evict-to-fit mirroring
  _reserve_write_cp_shared_l2_evict_to_fit); the request waits non-blocking in waiting_queue
  (check_cp_l3_reload_progress skip) and is admitted + re-matched the SAME tick the reload lands
  (check_hicache_events runs before batch formation). CP-aware insert only on a still-clean attach
  (else abort+recompute). Capped (cp_l3_reload_max_inflight) + content-key deduped (piggyback).

EAGLE/bigram (opus-studied, PROVABLY correct -- not deferred): the radix key is bigram-converted
over the whole request, and convert_to_bigram_key(fill_ids[M:]) == bigrams(fill_ids)[M:] exactly
(the boundary bigram belongs to the matched prefix), so the bigram-converted suffix hashes
reproduce node.hash_value. Verified vs source + a new slice-identity regression test.

Opus review (FIX-THEN-SHIP, no CRITICAL; the 4 crash surfaces -- MIN-vector shape, read-skew,
attach-anchor, placement-digest -- traced clean) + independently re-verified; fixes folded:
- M1: cp_l3_release_request clears reload state on request abort/timeout/preempt (no leak).
- H1: rank-uniform per-op TTL bound releases a held request if its reload op never acks (the
  default SGLANG_REQ_WAITING_TIMEOUT is off); the reservation frees safely at the (late) ack.
- L1: fail-soft anchor guard at insert (re-derive the first suffix hash from lhn's live hash).
- empty-waiters reload aborts (frees L2) instead of inserting an unrequested node.

Imports hoisted to top-level (get_hash_str -- hicache_storage is a leaf module, no cycle;
convert_to_bigram_key already top-level), no inline imports. py_compile clean; 54 L3 unit tests
green. Reload triggering (submit_reload/exists_prefix/free_object) now wired (was write-only).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
2026-06-23 00:09:38 +00:00
co-authored by Claude Opus 4.8
parent 815da6c4e5
commit 864b1c808e
3 changed files with 384 additions and 26 deletions
@@ -82,6 +82,17 @@ class TestConvertToBigramKey(unittest.TestCase):
self.assertEqual(got, [(7, 7), (7, 7)])
self.assertIsNot(got[0], got[1])
def test_suffix_slice_identity_for_l3_reload(self):
# The CP L3 reload (cp_l3_reload_lookup) computes a radix-miss suffix's content hashes by slicing the
# RAW fill_ids at the bigram-unit matched_len, then re-converting. For the hashes to match the spilled
# node.hash_value (computed over the full-sequence bigram key), this MUST hold:
# convert_to_bigram_key(fill_ids[M:]) == convert_to_bigram_key(fill_ids)[M:]
# i.e. the boundary bigram (f[M-1], f[M]) belongs to the matched prefix (index M-1), not the suffix.
fill_ids = list(range(100))
full = convert_to_bigram_key(fill_ids)
for m in (0, 1, 7, 50, 98): # M <= len-1
self.assertEqual(convert_to_bigram_key(fill_ids[m:]), full[m:])
if __name__ == "__main__":
unittest.main()