pool: frozen pages, a token-keyed prefix tree, a host tier; ablated to what kern-serve uses and gated by one GPU e2e

[xiaguan]

Why

A review found a P1 in the host tier: a checkpoint taken inside a page shared that page with the lease that kept writing it, and Host::park, deduplicating parked pages by device node id, reused the stale copy. It was a missing invariant, not a typo: nothing in the types said a chain's page is frozen. This PR puts the invariant into the types, rebuilds the index and the host tier on top of it, then cuts the crate back to what kern-serve uses and closes the gate with one GPU e2e over every target. Design record: docs/pool.md (validated against Dynamo KVBM / kv_router and SGLang's radix caches).

Pool

• Frozen pages. A Node's page is never written after the node exists. Whole pages are shared through the chain, the page a checkpoint ends inside is copied for it, and the only writer of any page is a live lease into its own pages. restore and fork already did this; checkpoint was the exception.
• One set of types over both tiers. Storage (sealed; Pool and Host), Store<T> = a prefix's bytes in one tier, Checkpoint = Store<Pool>, Parked = Store<Host>. Value semantics: a clone is another holder, the last drop returns what nobody else holds. No ids cross a module boundary.
• Twin link. A device node holds a Weak to its host copy: parking a session again copies only the new pages, and a woken checkpoint is born twinned and parks again for free (the lessons.md gap).
• Wake is one allocation. Host::restore(&Parked, &Pool, len, tokens) has the shape of Pool::restore: the pages the request needs taken once, the parked prefix copied into them (whole pages sealed and twinned, so the next park is free), and the scheduler admits the landed row at once. The parked entry stays in the index; the request's finish indexes the longer context.
• Token-keyed radix prefix index. Entries own their stores, so the tree branches at any token while no page is ever split; a Hit holds a clone and survives make_room. Longest usable entry wins, resident first at equal length.
• Ablated to what kern-serve uses. Prefix makes room itself (evict(park) → Evicted::Parked / Dropped); coldest / park / remove are no longer public, Store exposes tokens / has_slot only, Host is built from bytes, Waking::tokens and Tray::fork are gone. No mod tests: the accounting is tested through what it hands out (tests/pool.rs reference Mapping model landing Remap plans, tests/prefix.rs brute-force model learning tiers from Evicted, tests/host.rs).
• Host-tier visibility. kern-serve's stats line and the AgentX replay report hits by tier: resident_hits / resident_hit_tokens / host_hits / host_hit_tokens.

One GPU e2e over the four spec families

tools/e2e/e2e.py drives every target of a kern.toml through kern-serve the way a client does (README in the dir): kern test, conc1 vs kern run, repeat / turn2 hits, warm vs kern run and vs a cold server, twelve at once, a client hanging up mid-stream, a small pool with a host tier filled until the server parks, slot growth from two slots, --rows 1. Byte identity gates; a divergence on a single-rank target is excused only by the logits of that step (kern run --prompt-ids <shared context> --rows 1 --probe-dir, both tokens within 4 ULPs of the top); tray targets report cross-path identity instead of gating it.

Writing the scenarios found three interface problems, fixed here:

• kern run --prompt-ids: an answer's text need not tokenize back to its ids, so turn2 is sent as ids and the oracle replays them.
• kern-serve: a speculative round accepting past max_tokens or the stop left a request-end snapshot keyed by tokens no next turn sends (DSv4.1 2/4, dflash2 1/4 turn2 misses, a slot held until evicted). Not kept any more (not kept debug line); a state ending exactly at the stop token is.
• kern-serve: a scheduler panic left the port open with every request hanging; the process exits 101.

A toy gate over the same path, exact, in three minutes

tools/toy: manifests that are not models. Each token slot holds 64 marks of its token and position; the next token is the sum over every word of every slot the sequence holds (plus a line's ordered fold for a per-sequence state); a speculative round chains its own rows and takes 1 + S % rows. tools/toy/model.py is the same arithmetic, so e2e.py --reference tools/toy/model.py gates every scenario token-exactly, including warm vs cold and woken vs cold that a real model can only report. Six manifests (paged, stateful, spec, stateful spec, a 64 KiB/token 281 GiB one, and a 128-thread build as kern test's A): all pass on one GB300 in 2 min 54 s with 256 tokens per request. On its first day it caught a regression: master's 64 MiB chunk cap (bb50189) turned --capacity <tokens> into whole chunks (2832 tokens → 1023 pages, the small-pool scenario parked nothing), invisible on real models whose pages exceed a chunk; Pool::new now takes the tokens asked for and caps the pages. (The kern run / kern-serve disagreement on a weights file's checkpoint directory it also hit was fixed on master the same day.)

The review, fixed test-first

An Opus design review of this PR read ten confirmed defects. Each got a test that failed on the code as it was, then the fix (commit per finding):

• concurrent was not a gate, and under the exact oracle toy-stateful's twelve concurrent answers were all wrong: gen.py bound the decode fold's rows to the batch's tokens, so every group folded the others' rows into its line. Gated → FAIL: concurrent 0/12 → decode folds a literal 1.
• A near-tie excused the whole answer. Same now excuses that token alone, takes the oracle's continuation from the server's token and compares on (≤ 3 per answer); qwen3-4b's repeat answer has an exact tie at token 46 (two logits at 21.5), excused, the remaining 18 match. The bf16 ulp is frexp's exponent, not int(x).bit_length().
• turn2_hit paired misses with a count of not kept lines; a miss now pairs with its own first turns' request ids. spec_acceptance was a fixed 20%; it is half of the serial rate, inside the bounds an exact oracle states (toy: 40–60). A single-rank target with no oracle fails instead of reporting; all-skipped exits nonzero; with --reference, kern run on the spare GPU is itself held to the reference. The verdicts are pure functions, tools/e2e/test_e2e.py, run by CI.
• kern-pool: Prefix::evict's successful park lost the count of parked entries dropped for the room (host_evictions undercounted); lookup restamped an off-path candidate sharing no whole page, so a query that found nothing made the coldest entry warm. Both reproduced in tests/prefix.rs first.
• Toy coverage: slots and lines are written and checked whole (tails are functions of the head / carry, a mismatch poisons the sum), head words rotate by position so page order is in the answer, every shape has a -ref for kern test. That found kern test's prefill sweep going to tokens.max (8192) past the 4096-token lease, and the k3 golden harness reading slots a lease had sealed.
• Driver races, from running the gate repeatedly: the small-pool fill stopped at "four parked lines" and a log-read race decided whether turn2 woke anything; serving is logged before pegainfer binds the port. The fill runs until the checkpoints turn2 hits have parked; ready is when the port answers.

Toy gate 2026-09-15 tray06 (two GPUs): five of five in 3 min 09 s. qwen3-4b same day: nine of nine. Docs: docs/serve.md "toy 门禁", docs/pool.md (sealed rule, Pool::new(.., tokens)).

The pre-merge DSv4.1 run found a livelock, fixed the same way

DSv4.1 EP4 on tray06 (--chunk 128 --max-seqs 16) hung in the host session's second turn: 2.36M parked tokens=86 lines. The wake path decided room twice — wake the checkpoint (one allocation), index it, lease from it (another) — and when the woken pages plus the half page's copy plus the continuation were one page more than the pool, the only resident make_room could park was the one just woken. A new e2e scenario, wake_room (a pool sized for exactly one worst-case second turn), reproduces it on toy-stateful in 30 s (6.08M lines), then:

• pool / runtime / kern-serve: wake into the lease (above); Host::wake and the scheduler's woken list are gone.
• kern-serve: the same scenario then exposed that max_request_tokens counted the pad's page — a request filling the pool exactly was neither rejected nor ever seated. Tray::max_seq_tokens leaves the pad its page and an over-cap request is a ContextLength reject before any lease.

Rerun: toy five of five (stateful targets park once and wake into the row), qwen3-4b / -dspark all pass, DSv4.1 EP4 8 gated all pass (wake_room parks=1, woken into a 2-page lease). docs/lessons.md: "一个请求的房间只问一次".

Gate

• cargo test -p kern-pool: property tests against reference models, green; workspace tests, clippy, fmt, hawk green on the host; kern-serve builds, tests and clippy clean in the kernel-lab container.
• e2e 2026-09-14 (tray06 / tray07 / tray09, 4×GB300 each): qwen3-4b, qwen3-4b-dspark, qwen3.8-27b, qwen3.8-27b-dflash2, DeepSeek-V4.1-Flash EP4, Kimi-K3 4-layer EP4 — all pass. Table in docs/serve.md "e2e 门禁". Toy gate 2026-09-15 (tray06, two GPUs, after the review round): five targets, all pass; qwen3-4b under the same rules, all pass.
• AgentX replay, qwen3.8-27b shape (page 784, 64 KiB/token, 147 MiB slot, 250 GiB, concurrency 32):

host tier	hit	resident hits	host hits (woken)	extend p50 / p90 / p99
none	93.1% (unchanged)	85 217 req	0	1202 / 12 956 / 430 464
512 GiB	96.4% (was 95.6%)	85 972 req, 94.4%	1 276 req, 443.6M tokens (2.1%)	1174 / 10 128 / 129 728 (was 208k)

Open, noted in serve.md: K3 4-layer at the default budget is 131k chunks of 2 MiB (chunk = half the smallest object), 40–60 s of mapping per rank and one cuMemSetAccess OOM — the chunk should scale with the budget. The review's P2 (rebalance over-counting shared chunks) is orthogonal and still open.

🤖 Generated with Claude Code

https://claude.ai/code/session_01G6hPjvcgRZcdFcymLwFchB

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-09-14T10:19:33.483547Z	ece29fd	PR opened

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[chatgpt-codex-connector]

💡 Codex Review

kern/crates/kern-serve/src/scheduler.rs

Line 563 in ece29fd

Err(Error::Denied(Denied::Busy)) if self.make_room()? => {}

Reserve capacity before repeatedly waking a parked prefix

When a parked prefix fits in the currently free pages but the request's full worst allocation does not because active rows hold the remainder, the wake succeeds, then lease_from returns Busy here. make_room can park the newly woken snapshot—the only resident checkpoint—so the next retries wake and park the same multi-GiB prefix repeatedly instead of waiting for an active row to finish, consuming transfer bandwidth and delaying admission. Preserve the woken resident snapshot on this Busy path or reserve the full request capacity before starting the wake.

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Publish host twins only after their copy is committed

When callers use the documented two-phase API to reserve several checkpoints from the same runtime, two checkpoints may share a device node: room(cp1) publishes this weak twin before any transfer is queued, so room(cp2) reuses it and omits that page from its copy plan. If the first room is then dropped or refused while the second is parked, the second room keeps the host node alive but no operation ever initializes its bytes, and a later wake silently restores stale memory. The twin must not become reusable until the room that owns its copy is committed, or dependent rooms must retain that copy obligation.

Useful? React with 👍 / 👎.