CP HiCache L3 3.4: cold-start (restart durability) — load|clear via SGLANG_CP_L3_COLD_START

On restart the LMDB index + disk-slab blobs persist, but CpL3Store.from_config built the slot
pools all-free and the GC LRU empty -> the next spill re-hands-out a slot the durable index still
references (clobbers a live blob) and GC never reclaims the carried-over entries. Neither a clean
start nor a durable reload was actually realized.

connect() now applies a cold-start policy BEFORE the bg threads start (the write thread is the sole
pool/GC owner, so the single-threaded reconcile must precede it):
  - clear (default): wipe the persisted index + reset the pools/GC -> genuinely empty start (disk
    blobs are inert, overwritten lazily on slot reuse).
  - load: rebuild this rank's slot free-list + GC LRU from the durable disk blobs. Drive the scan
    from the rank's OWN slab file (header-only reads) so it never inspects another rank's slots even
    when ranks share a disk; a slot is LIVE iff its blob header parses AND the shared index still maps
    that content hash back to this exact slot -> occupy + seed the GC LRU with the durable last_access;
    orphan/unwritten slots stay free. Header-only (no payload CRC); reload-time verify-on-read still
    fail-softs a torn payload. The L3 durable floor now survives a process restart.

Primitives: CpL3SlotPool.rebuild_from_allocated (O(num_slots) bulk-occupy) + CpL3DiskSlab.read_header
(one aligned block, not the multi-MB slot). Env SGLANG_CP_L3_COLD_START (default "clear"), read in
_maybe_init_cp_l3 and passed to connect(). Tests: 4 cold-start e2e (load rebuilds the floor + no slot
collision after a fresh spill; GC LRU rebuilt; clear starts empty; unknown mode fails loud) + 2 unit
(rebuild_from_allocated, read_header). 23 L3 store/disk/posix tests green.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
2026-06-23 18:09:37 +00:00
co-authored by Claude Opus 4.8
parent d6aabace90
commit ea4ce31f95
8 changed files with 296 additions and 5 deletions
@@ -110,6 +110,19 @@ class TestDiskSlab(unittest.TestCase):
self.slab.write_slot(0, _h(0), 1, b"\x33" * PAGE)
self.slab.fdatasync() # must not raise
def test_read_header_for_cold_rebuild(self):
# header-only read (cold-rebuild scan): a written slot returns its parsed header; an unwritten slot
# returns None (fresh fallocate = zeros = bad magic). Cheap: reads one aligned block, not the slot.
payload = bytes((i * 5) & 0xFF for i in range(PAGE))
self.slab.write_slot(2, _h(13), 78, payload)
hdr = self.slab.read_header(2)
self.assertIsNotNone(hdr)
self.assertEqual(hdr.payload_kind, "target_kv")
self.assertEqual(hdr.content_hash, _h(13)) # _h returns 32 raw bytes here
self.assertEqual(hdr.n_layers, 78)
self.assertEqual(hdr.page_bytes, PAGE)
self.assertIsNone(self.slab.read_header(5)) # unwritten -> None
if __name__ == "__main__":
unittest.main()