diff --git a/.gitignore b/.gitignore
index c3b7432..baad4ad 100644
--- a/.gitignore
+++ b/.gitignore
@@ -13,6 +13,9 @@ dist/
 # Trained adapter artifacts (never committed; see README)
 artifacts/
 
+# Downloaded checkpoints (README quick start puts them here)
+models/
+
 # macOS
 .DS_Store
 
diff --git a/README.md b/README.md
index 8d174e0..994bbad 100644
--- a/README.md
+++ b/README.md
@@ -216,7 +216,7 @@ edge0-35b, 2.8 for edge0-8b** (MMLU-Pro is even above the base). Max 100:
 
 ## Benchmark
 
-Measured with `examples/bench.py` (3.3k-token prompt prefill → 10 sampled
+Measured with `examples/bench.py` (3.3k-token prompt prefill → 10 greedy
 warmup steps → 200 timed sampled decode tokens, 2 runs per tier):
 
 | Tier | Decode speed | Prefill throughput (cold / warm)* | Peak active memory** | Test machine |
diff --git a/README_zh.md b/README_zh.md
index 89aef98..f05f5ec 100644
--- a/README_zh.md
+++ b/README_zh.md
@@ -198,7 +198,7 @@ engine.close()   # 释放 mmap / 专家缓存
 
 ## 性能实测
 
-`examples/bench.py` 实测（3.3k token prompt prefill → 10 步采样 warmup →
+`examples/bench.py` 实测（3.3k token prompt prefill → 10 步贪心 warmup →
 200 token 计时段，每档 2 轮）：
 
 | 档位 | 解码速度 | Prefill 吞吐（冷/热）* | 峰值 active 内存** | 测试机器 |
diff --git a/docs/nvidia.md b/docs/nvidia.md
index b86994e..a5d6fcf 100644
--- a/docs/nvidia.md
+++ b/docs/nvidia.md
@@ -1,5 +1,492 @@
 # NVIDIA / CUDA support — status
 
+## Jetson Orin Nano bring-up
+
+**Status (16 September 2026): edge0-8b runs on a physical Orin Nano 8 GB,
+and the bring-up plan is complete through its final validation.**
+Decode **0.77–0.82 tok/s**, prefill 42 tok/s at a 3.3k-token prompt,
+inside a byte budget that rejects what will not fit before the model
+loads, with token choices matching the reference implementation on this
+device.  The claim covers exactly the board, build, checkpoint, profile
+and workloads in the [tested operating
+envelope](#tested-operating-envelope-task-7-final-validation): single
+request, greedy sampling, ≤ 4096 declared context, ≤ 256 validated
+generation, 25W mode.  The route there is the
+[Task 3 baseline](#task-3-orin-baseline-summary) (0.553 tok/s
+unoptimized), the [byte budget](#memory-budgeted-profile-task-4), the
+[transfer knobs](#bounded-expert-reuse-and-predicted-prefetch-task-5-opt-in)
+and the [quantized paths](#task-6-orin-acceptance) — **+42% end to end**
+over the baseline.
+
+Before attempting inference on an Orin Nano, capture a machine-readable
+capability report with the read-only probe:
+
+```bash
+EDGE0_BACKEND=cuda python scripts/jetson_probe.py \
+  --model-dir "$EDGE0_8B_MODEL" \
+  --output artifacts/orin-probe.json
+```
+
+The command exits non-zero and lists actionable blockers when it cannot confirm
+a Jetson Orin, CUDA-enabled PyTorch, and NVMe-backed model storage. It reports
+facts only; passing the probe does not imply that inference fits in 8 GB.
+
+The staged implementation and measurement gates are documented in
+[`docs/plans/jetson-orin-nano.md`](plans/jetson-orin-nano.md) (change
+justifications in [`jetson-orin-nano-review.md`](plans/jetson-orin-nano-review.md)).
+Start with the 8B tier and retain the existing correctness path while
+optimizing memory and I/O. The benchmark's machine-readable report, which the
+Orin baseline uses, is described in [Benchmark reporting](#benchmark-reporting)
+below.
+
+### Task 3 Orin baseline summary
+
+Target: Jetson Orin Nano Developer Kit (Super), 8 GB (7.85 GB observed),
+NVMe/ext4, L4T R39.2 (kernel 6.8.12-tegra), 25W power mode (observed, not
+changed), Python 3.12.3.  Torch: the official **2.14.0+cu130 aarch64
+wheel** — the same build the GB10 work used.  It warns that its SASS list
+excludes `sm_87`; empirically the `sm_80` binaries run on this Orin
+(CC 8.x binary compatibility), and the smoke suite below is the evidence
+gate that decides this, not the warning or the docs.  Environment:
+edge0 installed `pip install -e . --no-deps` plus
+numpy/safetensors/tokenizers/psutil/transformers (5.17.0) — no MLX
+package on the device; the 8B torch import path needs none.
+
+Evidence chain (raw reports in the untracked evidence set, sanitized
+summary here):
+
+* **Probe** (`scripts/jetson_probe.py --model-dir …`): `ready: true`,
+  no blockers; checkpoint manifest sha256 `a83dee78…` (48 files,
+  4.60 GB).
+* **CUDA acceptance** — `pytest tests/test_torch_cuda_smoke.py
+  --require-cuda -q`: 6/6 pass on the device (matmul vs float64
+  reference, packed-uint32 int4 `gather_qmm` vs a hand-computed
+  dequantization, RMSNorm, unsigned-word view semantics, core ops).
+  The suite FAILS rather than skips when CUDA is missing (verified
+  with `CUDA_VISIBLE_DEVICES=""`).
+* **32-token greedy correctness** (`scripts/orin_reference_check.py`,
+  CUDA generation vs torch-CPU teacher-forced logits; torch-CPU is the
+  path checked against MLX layer-by-layer on the GB10): **32/32 token
+  choices identical, zero near-ties consumed** (smallest top-1→top-2
+  margin 0.067, median 4.6).  The pre-registered vocab-wide logit
+  bound (max |Δ| ≤ 1.0) was **exceeded: max |Δ| = 2.06** — reported as
+  the FAIL it is, not re-run with a looser bound.  Post-hoc analysis
+  (recorded in the evidence set): median |Δ| 0.087, p99 0.52; every
+  excursion above 1.0 sits on deep-tail tokens (worst: reference rank
+  429); at the reference's top-8 tokens of every step the difference
+  is ≤ 0.22.  This is accumulated bfloat16 reduction-order noise, not
+  a kernel defect; a top-k-scoped logit criterion should be registered
+  in review before the next comparison run, and MLX-generated fixtures
+  remain the intended reference once available.
+* **Short baseline** (`BENCH_TEMP=0 BENCH_SEED=0 examples/bench.py
+  edge0-8b --ntok 32 --warmup 0`, probe linked, tegrastats at 1 s
+  alongside, three independent process launches, two internal runs
+  each, `EDGE0_TORCH_WEIGHT_CACHE=0 EDGE0_PREWARM=0`):
+
+  | Launch | Prefill (37 tok) | Decode (32 tok) | CUDA alloc peak | Peak RSS |
+  |---|---|---|---|---|
+  | 1 | 15.9 / 11.7 s | 0.53 / 0.55 tok/s | 0.92 / 1.00 GiB | 5.31 GiB |
+  | 2 | 13.4 / 11.4 s | 0.55 / 0.55 tok/s | 0.92 / 1.00 GiB | 5.69 GiB |
+  | 3 | 14.9 / 13.2 s | 0.56 / 0.58 tok/s | 0.92 / 1.00 GiB | 5.76 GiB |
+
+  Six runs, descriptive statistics: decode mean **0.55 tok/s** (min
+  0.53, max 0.58); engine build ~11.4 s.  GPU utilization pegged at
+  99% during decode (tegrastats); no OOM, no swap activity; RSS and
+  CUDA peaks are separate views (unified memory — RSS includes
+  touched mmapped expert pages) and are not added.  A desktop session
+  (~3.5 GB) was resident throughout — headroom, not a guarantee.
+
+This is the **unoptimized reference implementation**: `gather_qmm`
+dequantizes every gathered expert on every call, exactly the cost
+Tasks 4–6 of the plan exist to remove (the GB10 measured 2.5× from the
+dequantized-weight cache alone; it is off here pending Task 4's byte
+budget).  Do not read 0.55 tok/s as the platform's capability.
+
+### Memory-budgeted profile (Task 4)
+
+`EDGE0_MEMORY_BUDGET=auto` (or an explicit byte count) makes the 8B
+engine resolve an explicit byte budget immediately before it builds the
+streaming caches: observed available RAM (tightened by any address-space
+rlimit), minus an OS-growth reserve, an allocator allowance, KV at the
+DECLARED context (`EDGE0_BUDGET_CONTEXT`, default 1024 tokens), the
+whole-layer prefill transient and in-flight expert builds — every
+payload priced from the checkpoint's safetensors header, not from slot
+counts.  What remains bounds the shared LRU and the prefetch buffer in
+bytes; the budget only ever LOWERS the tested profile, and it enforces
+two bounds the unbudgeted path leaves open (`PrefetchBuffer.max_cap`
+against `prefetch_all()`'s growth, `LayerOptions.max_inflight` against
+the speculative build queue).
+
+Impossible profiles fail BEFORE inference with the itemized arithmetic:
+a context whose KV cannot fit, a cache allowance below the working set
+(a calculated zero is rejected — `SharedExpertCache(0)` /
+`PrefetchBuffer(0)` mean *unbounded*, never "off"), or
+`EDGE0_TORCH_WEIGHT_CACHE=1` whose measured ~4.1 GB does not fit the
+post-cache headroom.  The resolved policy (or the rejection) lands in
+the bench report's `caches.memory_budget` group.  On the Orin Nano
+8 GB baseline workload, `auto` resolves ≈ 4.2 GB usable, keeps the
+tested 64-slot / 48-cap profile with ≈ 1.9 GB headroom, and measures
+identically to the unbudgeted baseline; a declared 4096-token context
+is rejected (KV alone ≈ 4.5 GB), as is the weight cache.  Unset, the
+engine behaves exactly as before Task 4.
+
+### Bounded expert reuse and predicted prefetch (Task 5, opt-in)
+
+The measured Orin profile found the tested 64-slot LRU never hits on
+this tier (working set 184 bundles/step) — and also that decode is
+compute-bound, so transfers barely show end-to-end until the Task 6
+kernel work lands.  Two opt-in knobs, both scheduling-only (token
+output is bit-identical; wrong or late predictions fall back to demand
+loads, never a staged zero row):
+
+* `EDGE0_CACHE_SLOTS=512` — request a working-set-sized shared LRU
+  (the budget may lower it).  85% hit rate on the baseline workload.
+* `EDGE0_PREDICT_PREFETCH=1` — the prerouter's per-step predictions
+  are prefetched for non-staged layers while the current forward runs
+  (98.8% of predicted builds consumed, zero waited on, zero wasted).
+
+Together on the baseline workload: decode 0.568–0.623 tok/s (mean
+0.594) vs 0.53–0.58 (mean 0.552) — **+7.7%**, for ~0.6 GiB more
+resident, inside the resolved budget.  Off by default until the
+post-Task-6 re-measurement; the pinned-buffer CUDA-stream pipeline is
+deferred on the same evidence (see the plan's Task 5 status).
+
+### Quantized paths (Task 6, developed on a workstation GPU)
+
+The Orin profile (plan Task 6 scoping) put 37% of a decode step in
+`quant.gather_qmm` and 26% in the dense `QuantizedLinear.forward`, both
+dequantize-then-matmul.  Three paths were developed and parity-tested
+on an RTX PRO 6000 (torch 2.14.0+cu130, the Orin's torch version) per
+[`plans/rtx6000-task6-handoff.md`](plans/rtx6000-task6-handoff.md).  All are
+guarded (every unsupported case falls through to the reference
+implementation unchanged), priced for the Task 4 budget and
+recorded in the bench report's `caches.quant_paths` group.  Which one the
+Orin adopts, and any tok/s, is decided on the Orin — see
+[the acceptance](#task-6-orin-acceptance) below, which made
+`EDGE0_QMM_BATCHED` the **default** on this backend and left the two
+dense knobs opt-in.
+
+| Knob | What it does | Exact? | Extra memory |
+|---|---|---|---|
+| `EDGE0_QMM_BATCHED=1` | `gather_qmm` dequantizes the distinct experts of a call ONCE and runs ONE batched matmul over a padded per-expert slab instead of a Python loop of dequantize+matmul pairs (decode: 8 pairs -> 1 + 1). Affine 4-bit only; 2/8-bit and any call whose priced transient exceeds `EDGE0_QMM_BATCHED_MAX_BYTES` (default 256 MiB) take the reference loop. | yes: same float32 arithmetic, parity 1e-4 to a float64 hand reference and 1e-5 to the loop | per-call transient only, priced by `quant.batched_transient_bytes`; the cap is deducted once by the budget |
+| `EDGE0_TORCH_WEIGHT_CACHE_BYTES=<n>` | keeps the dequantized bf16 weight of the dense `QuantizedLinear` modules that fit `n` bytes, admitted first-fit in checkpoint order with each module's own build transient counted (`nn.WeightCachePolicy`); the engine shrinks `n` to the budget's post-cache headroom; the admitted module list is in the report | the dequantized weight is bit-identical to the on-the-fly path (same per-chunk expression, asserted on CUDA); the cached forward then issues one GEMM where the reference issues one per 4096-row chunk, so for the two modules wider than a chunk (lm_head, layer-0 dense gate/up) cuBLAS may split differently — identical on this GPU and on the CPU, and the reference check decides on the device | the admitted bytes plus one build transient at a time: the fill is chunked, so it costs `nn.fill_transient_bytes` (edge0-8b's widest module, lm_head 157184 x 1536: 460.5 MiB resident, 556.9 MiB measured peak) rather than the 3702 MiB a whole-weight dequantization peaks at. edge0-8b's cacheable dense linears total 1.40 GB in bf16: lm_head 0.46 GiB, attention and shared experts the rest. Routers are not quantized in this checkpoint and `word_embeddings` is a `QuantizedEmbedding` that dequantizes only the rows it looks up, so neither is a candidate |
+| `EDGE0_INT4PACK=1` | dense `QuantizedLinear` through torch's built-in `_weight_int4pack_mm` after a one-time repack of the MLX layout (uint32 LSB-first codes -> uint8 high-nibble-first pairs, `zero = bias + 8 * scale`), lazily on the first eligible call; CUDA + bf16 activations + 4-bit + group 32/64/128/256 + `in_features % 128 == 0` + `out_features % 8 == 0` only, and `int4pack.probe` must execute the kernel once on the device first (the Orin's wheel warns `sm_87` is outside its SASS list, so execution evidence gates, not the warning); a runtime failure disables the path for that module permanently | **no**: `zero` is rounded to bf16 and the kernel dequantizes in bf16; measured (identity-vector probe, n=512, k=1536): per-weight error median 3.7e-4, p99 3.7e-3, max 1.1e-2; 68% of weights equal the reference's bf16-rounded weights, the rest within ~1-2 bf16 ulps; outputs within 3.5e-3 of the output scale. Pre-registered test bounds: 1e-2 of output scale, 2^-6 (max|w| + max|zero|) per weight | duplicates the int4 payload it covers (`int4pack_extra_bytes`) next to the original buffers; for all of edge0-8b's dense linears that is 0.35 GB |
+
+Precedence inside `QuantizedLinear.forward`: full cache, then the capped
+cache, then the int4 kernel, then the chunked on-the-fly dequantization —
+exact paths first.
+
+**Both dense knobs need bfloat16 activations, and most calls are not.**
+Traced on the real edge0-8b model over one prefill plus one decode step,
+400 of 470 dense `QuantizedLinear` calls arrive as float32 and only 70 as
+bfloat16. The cache therefore fills 35 of the 235 modules it admits
+(0.174 GB of the 1.402 GB reserved) and the int4 kernel repacks exactly
+those same 35. The reservation stays conservative on purpose — it never
+under-reserves — and the report states `filled_bytes` next to
+`admitted_bytes` so residency is never overstated. The routed path
+(`EDGE0_QMM_BATCHED`) has no such gate and engages on every call.  The batched gather touches only the routed-expert
+path; the dense knobs touch only the dense path; nothing changes token
+choice by construction except the int4 kernel, whose acceptability the
+32-token reference check decides (`scripts/orin_reference_check.py` now
+takes `--test-env KEY=VALUE` / `--reference-env` so the reference path and an
+opt-in path can be compared on the SAME device, isolating the path from
+device noise).
+
+Tests (no MLX, hand-computed references, tolerances written before any Orin
+run): `tests/test_quant_paths.py` (every broadcast shape of
+`tests/test_cuda_backend.py`, 2/8-bit fall-through, index boundaries,
+negative scales, code extremes, bf16 dtypes, transient cap fall-back, the
+allocator-measured transient against the price, kernel-launch counts),
+`tests/test_weight_cache_policy.py` (admission, caps, re-finalize, bit
+identity, loader registration), `tests/test_int4pack.py` (exact repack round
+trip, the zero mapping, every guard, the registered kernel bounds, the LoRA
+wrapper, exact-cache precedence), `tests/test_task6_budget.py` (pricing).
+The CUDA cases skip without a device and FAIL under `--require-cuda`.
+
+Custom fused kernel (design C): not written. Toolchain recorded for the next
+session: WSL Ubuntu nvcc 13.0.88 + g++ 13.3 compile
+`-gencode arch=compute_87,code=sm_87 -gencode arch=compute_120,code=sm_120`
+fat binaries that run on this GPU; Windows has VS 2022 BuildTools + CUDA
+12.8 as an alternative.
+
+### Task 6 Orin acceptance
+
+Run on the target (Orin Nano 8 GB, L4T R39.2, CUDA 13.2, torch
+2.14.0+cu130, 25W, budget active) on 16 September 2026.  Same workload
+and instrumentation as the Task 3 baseline: 37-token prompt, 32 greedy
+tokens, `BENCH_TEMP=0 BENCH_SEED=0`, three independent launches x two
+internal runs, tegrastats alongside.
+
+**Environment and correctness.** Full suite 341 passed on-device; the
+CUDA suites pass under `--require-cuda` (96 tests).  `int4pack.probe`
+**executes on sm_87** — the kernel the wheel's SASS list does not
+advertise runs here, answered by execution as the design intended.
+
+Same-device 32-token reference checks (`--test-env`, so the only
+variable is the knob; the registered bound is Task 3's max |Δlogit| ≤ 1.0):
+
+| Path | Token choices | max abs logit diff | Verdict |
+|---|---|---|---|
+| `EDGE0_QMM_BATCHED=1` | 32/32 identical | **0.777** | **PASS** |
+| `EDGE0_TORCH_WEIGHT_CACHE_BYTES=1.5e9` | 32/32 identical | 1.58 | FAIL of that bound, recorded |
+| `EDGE0_INT4PACK=1` | 32/32 identical | 2.17 | FAIL of that bound, recorded |
+
+**Decode (6 runs each, mean ± sd):**
+
+| Configuration | decode tok/s | mean | vs baseline | CUDA peak / RSS |
+|---|---|---|---|---|
+| baseline (Task 3) | 0.530–0.580 | 0.553 | — | 1.00 / 5.3–5.8 GiB |
+| batched gather | 0.623–0.699 | **0.668** | **+20.7%** | 1.00 / 5.6–5.7 GiB |
+| batched + Task 5 knobs | 0.743–0.815 | **0.785** | **+41.8%** | 1.58 / 5.8–5.9 GiB |
+| capped weight cache (screen) | 0.517 | 0.517 | +0.8% | 1.16 GiB |
+| int4 kernel (screen) | 0.524–0.540 | 0.532 | +3.7% | 1.07 GiB |
+
+**Decision.** `EDGE0_QMM_BATCHED` is now **on by default** on this
+backend (`EDGE0_QMM_BATCHED=0` selects the reference loop): it is the
+only path that both passed the registered correctness bound on the
+target and delivered a measured benefit there, it engages on every
+gather call, its transient is bounded and the budget deducts the cap.
+The two dense knobs stay **opt-in**: they move decode by ~1–4% because
+of the dtype gate below, and both exceed the registered bound.
+
+**The Task 5 re-measurement Gate D asked for.** With compute reduced,
+transfers matter more, exactly as predicted: the Task 5 knobs were worth
++7.7% before Task 6 and are worth **+17.5% on top of the batched gather**
+now (0.668 → 0.785), with expert load wall falling 72.5 s → 17.0 s over
+the same six runs and 30,159 cache hits against 5,169 loads.  They remain
+opt-in because they are board-specific tuning that needs the budget
+active (`EDGE0_MEMORY_BUDGET=auto EDGE0_CACHE_SLOTS=512
+EDGE0_PREDICT_PREFETCH=1` is the recommended Orin profile, and is what
+the 0.785 figure uses).
+
+**Two corrections to the workstation's report, found only by running here:**
+
+1. *The capped weight cache is not bit-identical on this GPU.*  The
+   workstation measured max |Δlogit| exactly 0; the Orin measures 1.58.
+   Isolated: the cached dequantized weight IS bit-identical to the
+   chunked path's (verified directly), but feeding those same weights
+   through one GEMM versus the reference's per-4096-row GEMMs differs by
+   0.03125 on a 30.6 output scale — one bf16 ulp of accumulation-order
+   difference in cuBLAS's kernel choice for the two shapes.  The
+   exactness claim is a property of the workstation's cuBLAS heuristics,
+   not of the code; on sm_87 the path is exact in the weights and
+   near-exact in the outputs.
+2. *The float32 activation gate is an MLA/RoPE promotion, not an
+   accident.*  Confirmed here (35 bf16 vs 200 float32 dense calls per
+   decode step) and traced to its origin: layer 3 is the first
+   `BailingMLA`, whose RoPE path computes in float32 and concatenates
+   `q_nope.to(q_pe.dtype)` with the float32 `q_pe` — deliberate MLX
+   promotion parity, commented as such in the vendored model.  From that
+   layer on, the residual stream stays float32, so only layers 0–2 (KDA)
+   present bf16 activations to their dense linears.  That is the 35
+   modules, and it is a numerics-parity decision, not a kernel
+   limitation: reaching the rest of the dense 26% means deciding to
+   diverge from MLX's promotion in the MLA path, which belongs in review
+   with its own reference check, not in a kernel increment.
+
+### Tested operating envelope (Task 7 final validation)
+
+Everything below was measured on the target on 16 September 2026.  It
+describes **this** board, build, checkpoint and profile on the workloads
+listed; it is descriptive evidence from small samples, not a performance
+guarantee, and nothing here is claimed for other Orin models, power
+modes or context lengths.
+
+**Configuration under test.** Jetson Orin Nano Developer Kit (Super),
+8 GB (7.85 GB observed), NVMe/ext4, L4T R39.2 (kernel 6.8.12-tegra),
+CUDA 13.2 driver, 25W power mode (observed, unchanged), Python 3.12.3,
+torch 2.14.0+cu130, no MLX installed.  Checkpoint
+`Edge0/Edge0-8B-A1B-preview`, manifest sha256 `a83dee78…`, with its
+bundled LoRA and prerouter adapters.  Profile: the shipped default
+(batched expert gather on) plus `EDGE0_MEMORY_BUDGET=auto
+EDGE0_CACHE_SLOTS=512 EDGE0_PREDICT_PREFETCH=1`.  A desktop session
+(~3.5 GB) was resident throughout — this is the realistic condition on
+this board, not a cleared one.
+
+| Dimension | Tested envelope |
+|---|---|
+| Decode, short prompt | 0.744–0.786 tok/s, mean **0.772**, sd 0.016 (n=6: three launches x two runs) |
+| Decode, sustained | mean **0.817** tok/s, sd 0.028, min 0.745, max 0.853 (30 requests / 960 tokens / 25 min, one process) |
+| Prefill | 13.6–15.6 s at 37 tokens; **42.4–42.8 tok/s** at 3292 tokens |
+| Generation length | validated to **256 tokens** in one request (0.807 / 0.820 tok/s over two runs — no decay with generation length) |
+| Prompt / context | validated at **3292 prompt tokens**; the budget admits up to a **4096-token declared context** on this board, and rejects beyond that before loading |
+| Memory | CUDA allocator peak 1.58 GiB short-prompt, 3.14 GiB at 3292 tokens; process RSS 5.45–5.82 GiB |
+| Thermal | junction 54.5–61.8 °C over 25 minutes, **no throttling**; GPU busy in 749 of 774 samples |
+| Correctness | 32/32 token choices identical to the reference loop, max abs logit diff **0.777** against the registered bound of 1.0 (PASS); all 30 sustained requests produced byte-identical tokens |
+
+**KV growth was measured, not inherited.**  `kv_bytes_per_token` for
+this tier was 1,100,000 — the README's Apple/MLX figure.  Measured here
+across 128…2048-token prefills, the marginal cost is **561,320 B/token
+(548 KiB)**, roughly half of that; growth is sublinear below the top of
+the range because most layers of this hybrid are KDA, whose state is
+fixed-size, so only the MLA layers' KV grows with context.  The constant
+is now 600,000 (≈7% margin over the measurement).  The practical effect
+is a larger honest envelope: the declared context the budget admits on
+this board goes from ~2560 to 4096 tokens.  Over-reserving was safe but
+was rejecting contexts that fit.
+
+**Repeated requests are stable, and the RSS movement is not a leak.**
+Across 30 sequential requests RSS moved between 5.45 and 5.70 GiB,
+rising *and falling* (5.45 → 5.65 → 5.53 → 5.70 → 5.69): mmapped expert
+pages being reclaimed and re-faulted under memory pressure, which is
+what RSS counting mmapped files looks like, not monotonic growth.  CUDA
+allocator peaks were flat at 1.57 GiB and every request produced
+identical tokens.
+
+**Swap, stated explicitly.**  The sustained run *did* swap: +1,165 MB in
+the first fifth of the run, then flat (+24, 0, +18, −2 MB across the
+remaining four fifths), with no throughput degradation — in fact the
+later quartiles were slightly faster (0.791 / 0.834 / 0.816 / 0.824).
+That profile is a one-time eviction of the resident desktop's idle pages
+to make room, not the model's working set thrashing.  Per the plan's
+rule a swapping run cannot establish a resident-memory target, so the
+memory figures above are stated as observed peaks under these
+conditions, and a swap-free claim is **not** made for a board with a
+desktop session resident.
+
+**Known limitations of this envelope.**  Single concurrent request only
+(no batching, no concurrent sessions tested).  Greedy sampling at
+temperature 0 for every measurement.  Contexts beyond 4096 declared
+tokens are rejected by the budget, not degraded gracefully.  Prefill at
+short prompts is dominated by fixed overhead (2–3 tok/s at 37 tokens vs
+42 tok/s at 3292) and was not optimized.  edge0-35b remains out of scope
+on this board.
+
+## Benchmark reporting
+
+`examples/bench.py` keeps its two-run protocol and its human-readable output
+and can additionally write a machine-readable report:
+
+```bash
+EDGE0_BACKEND=cuda EDGE0_TORCH_DEVICE=cuda \
+  python examples/bench.py edge0-8b --ntok 32 --warmup 0 \
+  --probe-json "$EDGE0_RUN_DIR/orin-probe.json" \
+  --json-output "$EDGE0_RUN_DIR/orin-short-baseline.json"
+```
+
+The pure builder (`examples/benchmark_report.py`, standard library only,
+imports neither torch nor MLX) turns measured numbers into the schema; the
+benchmark-owned collectors (`examples/benchmark_measure.py`) talk to the
+backend, the process and the machine behind lazy, injectable imports.
+
+### What is measured
+
+* **Protocol** `fixed-length-sample-and-step`, version 1. Per run:
+  `engine.reset()`, a timed chat-templated prefill, `--warmup` **greedy**
+  (argmax) steps that are not timed, then `--ntok` timed iterations of "sample
+  one token from the current logits, run one engine step". The final step's
+  logits are computed but never sampled and the loop does not stop at EOS.
+  None of the numbers is a time-to-first-token or an EOS-aware completion
+  latency; the report's `protocol` block says so.
+* **Counts** per run: `prompt_tokens` (after chat templating),
+  `warmup_tokens`, `timed_decode_tokens`,
+  `total_generated_tokens = warmup + timed`,
+  `decode_start_context_tokens = prompt + warmup`; the requested counts are
+  kept separately (`requested_*`). `decode_tokens_per_second` divides the
+  timed tokens only. A zero measured duration gives `null` plus a reason,
+  never a zero rate; `--ntok 0` is refused.
+* **Wall time** is `time.perf_counter()` and includes storage, transfer and
+  CPU sampling costs by design. On an actual CUDA device (`EDGE0_BACKEND=cuda`
+  *and* a resolved `cuda` device; `EDGE0_TORCH_DEVICE=cpu`/`mps` is not one)
+  the benchmark calls `torch.cuda.synchronize(device)` after the engine reset,
+  at the end of prefill, at the end of warmup and after the final timed step:
+  phase boundaries only, no per-token synchronization. On MLX nothing changes,
+  the engine's `core.eval(logits)` already materializes every step. Torch on
+  `mps` is not synchronized by the benchmark (the plan mandates CUDA only), so
+  its wall times may exclude the final step's in-flight device work; the
+  report says so in `runtime.measurement.synchronization`.
+* **Memory** is integer bytes everywhere, each value with its `method` and
+  `scope`. Per run (`runs[i].memory`): `cuda_peak_allocated` from the torch
+  caching allocator, reset immediately before prefill and read after the
+  synchronized decode. It covers prefill + warmup + decode, includes whatever
+  was resident at the reset (recorded as `allocated_at_reset`), does not
+  recover an earlier load transient and does not see the CUDA context,
+  driver or non-torch memory. `cuda_peak_reserved` is recorded next to it
+  with its own scope: `reset_peak_memory_stats` does not drop the reserved
+  peak below the segments the allocator already holds, so its floor is every
+  segment cached at the reset (`reserved_at_reset`) and run 0 and run 1 are
+  expected to be close. The headline value (the human `peak_active` line and
+  the legacy `peak_gib`) is `cuda_peak_allocated`, the analogue of MLX's peak
+  active memory; `runtime.measurement.headline_peak` names it. On MLX the
+  same reset point feeds `mlx_peak_active` (`mlx.core.get_peak_memory`); for
+  torch on any non-CUDA device (cpu, mps) the per-run `backend_peak` is
+  `null` with the reason. Process-wide (`memory`): `process_peak_rss`, a
+  lifetime high-water mark (`ru_maxrss`; `peak_wset` on Windows) that
+  includes model load and every run, and the sampled peaks from a sampler
+  thread started before the model loads (`--rss-sample-interval`, default
+  0.25 s, `0` disables; spikes shorter than the interval are missed):
+  `process_sampled_peak_rss`, plus on Linux (`/proc/self/status`)
+  `process_sampled_peak_rss_anon`, `process_sampled_peak_rss_file` and
+  `process_sampled_peak_swap`. Resident set size counts the resident
+  file-backed pages of the mmap'd checkpoint (whole-layer prefill touches
+  every expert of `model.safetensors`, reclaimable page cache) together with
+  anonymous memory, so it is not the process's anonymous footprint and not
+  comparable to the "peak anonymous memory" figure further down this page;
+  the `*_rss_anon` peak is. A non-zero swap peak marks a swapping run, which
+  cannot establish a resident-memory target. RSS and allocator peaks are
+  separate views of the same shared DRAM on Jetson; never add them.
+* **Unavailable values** are `null` with a reason: every data group
+  (`identity`, `model`, `runtime`, `workload`, `caches`, `memory`, `probe`,
+  each entry of `runs[]`, each statistic block of `summary` and every nested
+  object that can hold a null) carries an `unavailable_reasons` map
+  (`{field: reason}`), and memory metric objects carry `unavailable_reason`;
+  `protocol` and the `summary` container hold no nullable fields. An invalid *required* measurement (negative or
+  non-finite timing, count or byte value) aborts the run instead of being
+  written. Serialization is strict JSON (`allow_nan=False`).
+
+### Report layout (`schema_version` 1, independent of the probe's schema)
+
+| Group | Contents |
+|---|---|
+| `protocol` | name, version and the labels above |
+| `identity` | start/finish timestamps, git commit and tracked-file dirty flag of this checkout (untracked files do not count), `run_count`, `command.argv`, the requested `BENCH_*` / `EDGE0_*` / `MLX_CACHE_LIMIT_MB` / `LING_HIDDEN_CLIP` / `LING_PREWARM` / `PREROUTER_*` knobs as raw strings, snapshotted before the engine is built (the 8B engine sets a default `LING_HIDDEN_CLIP` the user did not request), the requested arguments |
+| `model` | resolved local checkpoint path, tier, `model_type` / `architectures`, `config.json` SHA-256, the checkpoint manifest (`files`: every regular file's relative path and size, `algorithm`, and the `sha256` over that list, so the digest is reproducible from the retained list; weights are never content-hashed), SHA-256 of every non-weight file up to 32 MiB (config, chat template, `tokenizer.json`, vocab, merges), safetensors header metadata, tensor counts and header hashes, `tokenizer_files` (name, size, SHA-256), and the LoRA / prerouter adapters as the engine resolved them (`engine.cfg`, which may point at the repo's `artifacts/` fallback rather than the checkpoint directory: path, whether it is inside the checkpoint directory, size, SHA-256 up to 256 MiB, header metadata, r/alpha and prerouter settings) |
+| `runtime` | backend and version, resolved device, the measurement adapter's description (synchronization policy, peak source, `headline_peak`), execution evidence (class and device of the logits the engine produced), Python / torch / CUDA or MLX versions, platform, Jetson power mode (`nvpmodel -q`, else the nvpmodel status file, else a reason) |
+| `workload` | prompt source, SHA-256 of the prompt text, SHA-256 of the prompt token ids after chat templating (`prompt_token_ids_sha256`: two launches are the same workload only if prompt digest, token count and token-id digest all match), length, text and token count; requested counts; resolved seed, temperature, top-k, top-p, repetition penalty, prefill chunk and think flag; `model_env`, the model-read knobs resolved after the build exactly as the bailing_hybrid code parses them (`ling_hidden_clip`, `prerouter_feature_topk`, `prerouter_intra`), which change numerics and per-token work and must be equal on both sides of a comparison |
+| `caches` | resolved `LayerOptions`, the actual shared-LRU and prefetch capacities read from the installed streaming layers, `weight_cache` (the torch backend's resolved `EDGE0_TORCH_WEIGHT_CACHE`), `prewarm` (the requested `EDGE0_PREWARM` / `LING_PREWARM` flag; only the 8B engine honors it), thread settings, the MLX cache limit, streaming statistics after the runs |
+| `runs[]` | per-run counts, `prefill_seconds` / `prefill_tokens_per_second`, `decode_seconds` / `decode_tokens_per_second`, per-run memory metrics, execution evidence |
+| `summary` | per metric: `n`, `n_valid`, the per-run `values` (nulls kept in run order), mean, min, max and sample standard deviation over the runs that have a value (null with a reason when none has one; the standard deviation needs two); descriptive only, two sequential runs in one process are not independent launches |
+| `memory` | the process-lifetime RSS peak and the sampled RSS / anonymous / file-backed / swap peaks, with notes |
+| `probe` | with `--probe-json`: the probe's own `schema_version`, the SHA-256 of the file as read, its `ready` flag, its timestamp and local path |
+
+### Safety rails
+
+* `--json-output` must be a new path. An existing destination, an invalid
+  `--probe-json` (missing, not JSON, no integer `schema_version`),
+  `--ntok <= 0` (also via `BENCH_NTOK`), `--warmup < 0`, a non-integer
+  `BENCH_SEED` or a non-numeric `BENCH_TEMP` are rejected **before** the model
+  loads, and none of that needs a backend: `bench.py` imports the framework
+  lazily, so `--help` and the argument checks work on a host without torch
+  or MLX. `BENCH_SEED=0` is a seed (both runs re-seed with it right after
+  prefill); at `BENCH_TEMP=0` the sampler is greedy, so the output does not
+  depend on the seed even though it is recorded. A tier name resolves to
+  `EDGE0_<TIER>_MODEL` by the same rule as the CLI.
+* The report is written atomically (temporary file in the destination
+  directory, fsync, then linked or renamed into place without ever
+  overwriting an existing file). A failed engine build, benchmark, report
+  assembly or write exits non-zero, prints `[bench] FAILED during <stage>` and
+  leaves no report at the destination; the engine and the sampler are closed
+  in `finally` either way.
+* The human output is unchanged, except that `peak_active` prints `n/a` when
+  the backend peak is unavailable and measured CUDA numbers now include the
+  synchronized device work.
+* Keep the JSON outside tracked source: it records local paths and the prompt
+  text. Share sanitized summaries and evidence digests.
+
+### What this does and does not show
+
+`tests/test_benchmark_report.py`, `tests/test_benchmark_measure.py` and
+`tests/test_bench_cli.py` validate the instrumentation with a fake engine, a
+fake array namespace and fake device APIs: dispatch, synchronization order,
+count arithmetic, units, pre-load validation, failure paths and cleanup. They
+run on a host with neither torch nor MLX. `tests/test_bench_backend.py`
+repeats the core cases through the real `core` ops and sampler of whichever
+backend is importable (on a host without MLX it selects the torch backend on
+the CPU unless the environment already chose otherwise) and is skipped when
+there is none. None of this is CUDA or Orin evidence. The Orin baseline
+(Task 3 of the plan) needs the physical device, a validated environment and
+the probe.
+
 `edge0` does **not** run on NVIDIA through MLX, at any version tested:
 the first forward pass fails, differently at each version (the table
 below). It does run on NVIDIA through the torch backend in
diff --git a/docs/plans/jetson-orin-nano-review.md b/docs/plans/jetson-orin-nano-review.md
new file mode 100644
index 0000000..8aa4140
--- /dev/null
+++ b/docs/plans/jetson-orin-nano-review.md
@@ -0,0 +1,145 @@
+# Edge0 Orin plan review and change justifications
+
+Reviewed 14 September 2026.
+
+**Assessment:** retain the staged Torch/CUDA approach, but correct the execution gates and benchmark prerequisites before implementing Task 2. The reviewed benchmark cannot currently run through its first memory reset on the CUDA backend. The baseline smoke command tests MLX, and the proposed memory/prefetch policies omit behaviors that could defeat their correctness or bounds.
+
+The attached file was treated as a document to review, not authorization to execute its embedded Claude prompt. Its referenced full plan, relevant implementation and tests were inspected through a separate public-repository checkout. No Edge0 implementation was changed, no commit/push was made, and no Jetson inference was run.
+
+## Deliverables
+
+- Revised Claude handoff: delivered outside the repository (it names a local checkout path and a private evidence directory).
+- [Revised full engineering plan](jetson-orin-nano.md): now the repository plan.
+- This review: justification and evidence for every substantive change, identified as C01–C16 in the revised documents.
+
+## Source and verification scope
+
+The original `edge0-orin-claude.md` remains unchanged. SHA-256:
+
+```text
+7E2EC53ED180A5BCF91800A61E435B2C18AD57A434AF90C05F59A3F00D8FA455
+```
+
+The public [draft PR #1](https://github.com/KarlTaylorKnight/Edge0/pull/1) was inspected on the review date. The code and full plan were read at commit `dc1d9b3b78f51eb1a5f3705d63ed16c5b2cc9dfe`; links below pin that snapshot. The Mac checkout path, its working-tree state and historical test outputs in the attachment were not independently inspected. Upstream PR discussion is useful provenance, not physical Orin evidence.
+
+## Changes and reasons
+
+### C01 — Pin the reviewed source and qualify inherited claims
+
+**Change:** add the reviewed commit, distinguish the supplied Mac path from the inspected public checkout, and label prior Mac checks as historical reports. Retain the PR #19 base and separate it from issue #20's MLX experiment.
+
+**Why:** mutable branches and upstream discussions can change. Without a source revision, a later implementer cannot tell whether a finding still applies. The attachment's test claims and another GPU's performance are not fresh Orin results. The [PR](https://github.com/KarlTaylorKnight/Edge0/pull/1) establishes the public branch context; the [reviewed NVIDIA notes](https://github.com/KarlTaylorKnight/Edge0/blob/dc1d9b3b78f51eb1a5f3705d63ed16c5b2cc9dfe/docs/nvidia.md) describe the different experiments.
+
+### C02 — Make Task 2's stopping point consistent
+
+**Change:** finish portable reporting in Task 2; put physical benchmark execution in Task 3. Replace “baseline captured and committed” with retained evidence and a reviewed summary. Permit a documented failed baseline attempt to lead to memory-policy correction, while requiring a successful reference run before performance optimization.
+
+**Why:** the handoff says to stop after Task 2, but the [full plan](https://github.com/KarlTaylorKnight/Edge0/blob/dc1d9b3b78f51eb1a5f3705d63ed16c5b2cc9dfe/docs/plans/jetson-orin-nano.md) requires an Orin run inside Task 2 and again in Task 3. It also alternates between committing results and forbidding generated artifacts. These contradictions can block useful host work or encourage premature hardware claims. An OOM baseline needs a recovery path rather than a circular prerequisite.
+
+### C03 — Repair the benchmark's missing CUDA measurement interface
+
+**Change:** add a benchmark-owned backend-aware measurement adapter and fake-engine integration tests before serializing results. Keep optional runtime imports out of the pure builder.
+
+**Why:** the [benchmark, lines 95 and 120](https://github.com/KarlTaylorKnight/Edge0/blob/dc1d9b3b78f51eb1a5f3705d63ed16c5b2cc9dfe/examples/bench.py#L95) calls peak-memory methods absent from the [CUDA core](https://github.com/KarlTaylorKnight/Edge0/blob/dc1d9b3b78f51eb1a5f3705d63ed16c5b2cc9dfe/src/edge0/backends/cuda/core.py). JSON-builder tests would miss the immediate runtime failure. A small benchmark adapter fixes the consumer without expanding the task into a backend rewrite.
+
+### C04 — Define synchronized wall-clock timing
+
+**Change:** synchronize the actual CUDA device at prefill/decode boundaries, including the end of warmup and the final timed step. Keep storage, transfer waits and sampling inside the relevant wall-time interval.
+
+**Why:** CUDA work is asynchronous and [CUDA `core.eval()`](https://github.com/KarlTaylorKnight/Edge0/blob/dc1d9b3b78f51eb1a5f3705d63ed16c5b2cc9dfe/src/edge0/backends/cuda/core.py#L292) does not synchronize. Existing incidental synchronizations do not define a reliable measurement contract. Kernel event time alone also omits the host/I/O costs central to this application. [PyTorch documents synchronization requirements for accurate CUDA timing](https://docs.pytorch.org/docs/main/notes/cuda.html#asynchronous-execution).
+
+### C05 — Specify what the report actually measures
+
+**Change:** version the benchmark schema; record requested and resolved configuration, backend and actual device, per-run results, sampling settings, input/model identity and an actual probe digest/reference. Distinguish prompt, warmup, timed and total generated tokens. Preserve and label the existing fixed-length sample-and-step protocol.
+
+**Why:** the [current loop](https://github.com/KarlTaylorKnight/Edge0/blob/dc1d9b3b78f51eb1a5f3705d63ed16c5b2cc9dfe/examples/bench.py#L93) uses greedy warmup despite its comment, executes an additional forward for every emitted timed token, and ignores EOS. Reporting these numbers as user-visible completion latency would be misleading. Also, the [Torch backend can select CPU](https://github.com/KarlTaylorKnight/Edge0/blob/dc1d9b3b78f51eb1a5f3705d63ed16c5b2cc9dfe/src/edge0/backends/cuda/core.py#L38); a backend label is not device evidence. A probe version alone cannot identify which machine-state report accompanied a run.
+
+### C06 — Give memory metrics correct units, scope and limitations
+
+**Change:** use integer bytes and measurement methods; separate process-lifetime RSS peaks, sampled peaks, CUDA allocated/reserved peaks and system telemetry. State precisely when CUDA peak statistics reset and exclude earlier loading transients from that per-run claim. Use null/reasons when metrics are unavailable.
+
+**Why:** an endpoint sample is not a peak, and a process high-water mark cannot be reset by subtracting earlier values. PyTorch allocation statistics cover its allocator, not every device allocation. On Tegra, CPU and GPU allocations share physical DRAM; RSS plus CUDA peaks is not a valid total-footprint formula. The combination of scoped metrics and system observations supports an honest fit assessment. [PyTorch allocator documentation](https://docs.pytorch.org/docs/main/notes/cuda.html#memory-management), [NVIDIA Tegra memory architecture](https://docs.nvidia.com/cuda/archive/13.0.2/cuda-for-tegra-appnote/index.html#memory-management).
+
+### C07 — Test collection, CLI failure and cleanup as well as fields
+
+**Change:** extend TDD to dispatch, synchronization order, count arithmetic, unavailable/invalid metrics, strict JSON, atomic writing and engine cleanup. Require a new output path so stale success artifacts cannot be mistaken for a failed run's result. Keep mocked and device evidence separate.
+
+**Why:** a schema test cannot detect an incorrect timer, CPU fallback, partial file or leaked engine. The [current CLI](https://github.com/KarlTaylorKnight/Edge0/blob/dc1d9b3b78f51eb1a5f3705d63ed16c5b2cc9dfe/examples/bench.py#L134) closes its engine only after successful benchmarking. Python's JSON encoder permits NaN/infinity by default, so a nominal JSON result can fail strict downstream consumers unless validated. [Python JSON documentation](https://docs.python.org/3.10/library/json.html). These are focused behavioral tests for the new reporting feature, not an unrelated testing expansion.
+
+### C08 — Add a reproducible Jetson installation prerequisite
+
+**Change:** resolve the actual board/L4T/JetPack/Python/Torch/CUDA combination, required features and tokenizer imports before inference. Audit backend dependency separation and preserve Apple defaults.
+
+**Why:** “Python 3.10+, PyTorch for Jetson” does not define an installable stack. The reviewed [package metadata](https://github.com/KarlTaylorKnight/Edge0/blob/dc1d9b3b78f51eb1a5f3705d63ed16c5b2cc9dfe/pyproject.toml) mandates MLX while [CUDA tokenizer loading](https://github.com/KarlTaylorKnight/Edge0/blob/dc1d9b3b78f51eb1a5f3705d63ed16c5b2cc9dfe/src/edge0/backends/cuda/io.py#L141) imports Transformers, and CUDA modules require specific Torch APIs. NVIDIA ties its builds and prerequisites to particular JetPack versions. The plan therefore requires a tested combination rather than inventing a wheel/version from an unknown device. [Installation requirements](https://docs.nvidia.com/deeplearning/frameworks/install-pytorch-jetson-platform/index.html), [compatibility matrix](https://docs.nvidia.com/deeplearning/frameworks/install-pytorch-jetson-platform-release-notes/pytorch-jetson-rel.html).
+
+### C09 — Limit what a successful probe certifies
+
+**Change:** retain the completed probe but explicitly check Nano 8 GB identity, missing memory evidence, environment compatibility and checkpoint completeness separately. Describe Linux-specific test prerequisites.
+
+**Why:** [the probe](https://github.com/KarlTaylorKnight/Edge0/blob/dc1d9b3b78f51eb1a5f3705d63ed16c5b2cc9dfe/scripts/jetson_probe.py#L244) matches generic Jetson/Orin model strings, queries CUDA properties and checks storage. Its blockers do not validate the 8 GB Nano variant, model contents, enough RAM or successful kernel execution. This is a limitation of its current contract, not grounds to discard the probe. A passing probe must not silently advance the entire acceptance gate.
+
+### C10 — Replace the incorrect hardware acceptance test
+
+**Change:** add a Torch-only test that requires and exercises CUDA, plus identified reference fixtures for on-device correctness. Retain existing MLX comparisons on supported hosts and define numerical tolerances before the run.
+
+**Why:** [the nominated NVIDIA smoke test](https://github.com/KarlTaylorKnight/Edge0/blob/dc1d9b3b78f51eb1a5f3705d63ed16c5b2cc9dfe/tests/test_nvidia_backend_smoke.py#L1) imports MLX directly. Setting `EDGE0_BACKEND=cuda` does not turn it into a Torch test. Nor is [test_cuda_backend.py](https://github.com/KarlTaylorKnight/Edge0/blob/dc1d9b3b78f51eb1a5f3705d63ed16c5b2cc9dfe/tests/test_cuda_backend.py#L14) a substitute: it requires MLX and its helper creates CPU tensors. The original “tokens or logits” criterion also allows the metric to be chosen after a mismatch; separate predefined comparisons avoid that ambiguity.
+
+### C11 — Replace the guessed footprint threshold with enforceable budgets
+
+**Change:** derive an explicit byte budget from observed conditions and the declared workload, accounting for load/prefill/KV/transient, staging and inflight allocations. Reject calculated zero capacities unless an explicit disabled-cache mode is implemented. Inspect configuration and cache construction, not only CUDA namespace files.
+
+**Why:** a universal 6.5 GB RSS ceiling does not establish system headroom. More concretely, [SharedExpertCache and PrefetchBuffer](https://github.com/KarlTaylorKnight/Edge0/blob/dc1d9b3b78f51eb1a5f3705d63ed16c5b2cc9dfe/src/edge0/streaming/cache.py#L19) evict only for positive capacities: zero is unbounded. The [prefetch implementation](https://github.com/KarlTaylorKnight/Edge0/blob/dc1d9b3b78f51eb1a5f3705d63ed16c5b2cc9dfe/src/edge0/streaming/layer.py#L456) also has inflight work and a path that grows capacity. Ignoring those behaviors defeats a nominally bounded LRU policy.
+
+### C12 — Preserve the actual 8B routing profile
+
+**Change:** connect future prefetch/cache work to the existing exact path; retain required expert contributions on misses. Do not enable staged decoding merely to activate prefetch.
+
+**Why:** [the 8B configuration](https://github.com/KarlTaylorKnight/Edge0/blob/dc1d9b3b78f51eb1a5f3705d63ed16c5b2cc9dfe/src/edge0/models/edge0_8b/__init__.py#L48) selects `prod_k8`, whose [definition deliberately disables staging](https://github.com/KarlTaylorKnight/Edge0/blob/dc1d9b3b78f51eb1a5f3705d63ed16c5b2cc9dfe/src/edge0/streaming/options.py#L112). The [engine](https://github.com/KarlTaylorKnight/Edge0/blob/dc1d9b3b78f51eb1a5f3705d63ed16c5b2cc9dfe/src/edge0/engine/ling.py#L70) passes only staged layers to the slot stager, while existing staged misses can use a zero row. A scheduling optimization must not silently become a routing/quality change.
+
+### C13 — Complete the asynchronous ownership contract
+
+**Change:** require both copy-completion and consumer-completion ordering, slot generations, pinned-buffer lifetime, bounded queues, failure/reset/close handling and stress tests. Treat pinned staging as a measured candidate on shared DRAM.
+
+**Why:** a readiness event prevents reading an incomplete copy but does not prevent overwriting a slot still used by a previous kernel. Reusing a pinned source too early can also corrupt a copy. Persistent asynchronous resources need stronger lifecycle handling than the current [reset/close logic](https://github.com/KarlTaylorKnight/Edge0/blob/dc1d9b3b78f51eb1a5f3705d63ed16c5b2cc9dfe/src/edge0/streaming/layer.py#L1378). [PyTorch stream semantics](https://docs.pytorch.org/docs/main/notes/cuda.html#cuda-streams) support these ordering requirements; [NVIDIA's Tegra guide](https://docs.nvidia.com/cuda/archive/13.0.2/cuda-for-tegra-appnote/index.html#memory-management) explains why duplicated host/device buffers share the same physical capacity.
+
+### C14 — Make kernel work conditional and align Gate D with its scope
+
+**Change:** select kernels from the measured profile, add guarded dispatch/fallback and target toolchain validation, and distinguish expert gather from dense quantized-linear optimization. Limit the allocation-free promise to expert-transfer payload reuse.
+
+**Why:** an INT4-only implementation cannot replace all the [existing quantization cases](https://github.com/KarlTaylorKnight/Edge0/blob/dc1d9b3b78f51eb1a5f3705d63ed16c5b2cc9dfe/src/edge0/backends/cuda/quant.py), and tensor outputs/intermediates still allocate. A fused expert gather also leaves [dense QuantizedLinear dequantization](https://github.com/KarlTaylorKnight/Edge0/blob/dc1d9b3b78f51eb1a5f3705d63ed16c5b2cc9dfe/src/edge0/backends/cuda/nn.py#L93) untouched. The revised gate avoids promising a larger kernel/allocator rewrite than the staged plan supplies, while retaining the opportunity to address dense work when measured evidence supports it.
+
+### C15 — Make before/after measurements comparable
+
+**Change:** freeze the workload, collect at least three independent launches on both baseline and optimized versions, retain each internal run, distinguish warm/cold assumptions, and record sustained thermal behavior and failed attempts. A reduced context is a separate experiment.
+
+**Why:** the [benchmark has two internal runs](https://github.com/KarlTaylorKnight/Edge0/blob/dc1d9b3b78f51eb1a5f3705d63ed16c5b2cc9dfe/examples/bench.py#L93), and engine reset does not guarantee cold storage or all caches. Comparing a single cold baseline with a warm optimized mean can attribute caching or thermal differences to the code. Power/thermal/system telemetry supplies the context needed to interpret the result. [NVIDIA tegrastats documentation](https://docs.nvidia.com/jetson/archives/r36.5/DeveloperGuide/AT/JetsonLinuxDevelopmentTools/TegrastatsUtility.html).
+
+### C16 — Separate reproducible local evidence from shared artifacts
+
+**Change:** store exact local paths and raw reports in an untracked evidence set; put sanitized summaries and content references in documentation. Hash/reference the specific probe and checkpoint manifest outside timed regions. Permit small reviewed deterministic test fixtures as test assets. Keep the supplied source unchanged and deliver revised copies.
+
+**Why:** exact paths and command strings can reveal usernames/machine details, conflicting with the original no-identifiers/no-generated-artifacts rules when copied into Git. A digest provides identity but must reference retained inputs to support reproduction. Keeping both source and revised copies makes the review auditable. This clarifies the existing artifact restriction rather than introducing a publication requirement.
+
+## Validation performed
+
+The review checked the pinned source, test imports, benchmark calls, cache capacity semantics, profile selection and supporting NVIDIA/PyTorch documentation. The source checkout was kept free of implementation changes. The original attachment's SHA-256 was recorded for preservation verification.
+
+On Windows/Python 3.14, this command ran:
+
+```text
+uv run --no-project --with pytest python -m pytest tests/test_jetson_probe.py -q
+14 failed, 10 passed in 0.79s
+```
+
+Failures include POSIX sysfs fixture names such as `259:1`, Linux mount-path assumptions and unavailable `os.major` on Windows. They are actual failures on that host, not evidence of an Orin regression and not a reproduction of the historical Mac test result.
+
+The same unchanged tests then ran under Ubuntu/WSL with Python 3.12 and pytest 9.1.1, using isolated test packages in the review workspace:
+
+```text
+PYTHONPATH=<review-workspace>/work/pytest-linux-packages python3 -m pytest tests/test_jetson_probe.py -q
+24 passed in 0.36s
+```
+
+The initial WSL interpreter had neither pytest nor working venv bootstrapping. Test packages were installed into a task-local target directory; no system Python packages or operating-system packages were changed. This is a Linux fixture test result, not an on-device readiness result.
+
+No full backend/parity suite or physical CUDA/Orin benchmark was run during the review. The current benchmark failure is established by its calls and the missing functions in the selected backend; a model was not downloaded to reproduce it.
diff --git a/docs/plans/jetson-orin-nano.md b/docs/plans/jetson-orin-nano.md
new file mode 100644
index 0000000..afefb23
--- /dev/null
+++ b/docs/plans/jetson-orin-nano.md
@@ -0,0 +1,427 @@
+# Jetson Orin Nano CUDA implementation plan — revised
+
+Review date: 14 September 2026. Source snapshot: `KarlTaylorKnight/Edge0` commit `dc1d9b3b78f51eb1a5f3705d63ed16c5b2cc9dfe`. Change IDs link this plan to the accompanying [justifications](jetson-orin-nano-review.md).
+
+## Goal and scope [C01, C02]
+
+Establish reproducible Edge0-8B inference on a physical **8 GB Jetson Orin Nano with NVMe**, then improve the measured bottleneck while retaining the current Torch reference implementation and MLX behavior. Keep the branch stacked on `cuda-backend-base`, derived from upstream PR #19. Do not substitute the different MLX CUDA experiment in issue #20.
+
+Task 1 is present in the reviewed branch. Task 2 is the next implementation increment and its stopping point. Tasks 3–7 remain later increments. No reviewed evidence establishes Orin inference support or an Orin performance number.
+
+Preserve the existing model engines and facade. Add narrow measurement/configuration/streaming hooks as required, with regression tests. Edge0-35B, a TensorRT rewrite and new model families remain outside the initial target. Do not project GB10 results onto Orin.
+
+Use RED → GREEN → REFACTOR for meaningful behaviors. Document changes and evidence after each increment. Retain raw measurements outside Git; a documented baseline means a reviewed summary plus retrievable evidence references, not committed raw artifacts.
+
+## Acceptance gates
+
+### Gate A — target and installation evidence [C08, C09]
+
+Record board/module identity, nominal memory variant, observed RAM, architecture, L4T/JetPack, Python ABI, installed Torch build, CUDA runtime, GPU properties, storage backing and checkpoint identity. Verify the target is the intended Nano 8 GB model; a generic Orin match also accepts other Orin models.
+
+The existing probe provides preliminary evidence. Its `ready` field does not certify the 8 GB SKU, enough free memory, a valid/complete checkpoint, package compatibility or a successful CUDA kernel. Missing required observations remain blockers. Resolve L4T to JetPack only from a supported mapping or package evidence; otherwise report it as unknown.
+
+Before inference, establish a reproducible environment compatible with the detected board/software stack. Record exact package versions and wheel URLs/digests or container digest. Verify actual imports and required APIs, including `torch.nn.RMSNorm`, the unsigned dtypes used by the backend, tokenizer dependencies and CUDA execution. Use NVIDIA's [installation requirements](https://docs.nvidia.com/deeplearning/frameworks/install-pytorch-jetson-platform/index.html) and [compatibility matrix](https://docs.nvidia.com/deeplearning/frameworks/install-pytorch-jetson-platform-release-notes/pytorch-jetson-rel.html); select a combination supported for this Orin, rather than the newest table entry automatically.
+
+The reviewed packaging unconditionally depends on MLX/MLX-LM and omits explicit Torch/Transformers dependencies. Audit the actual 8B import path and provide an isolated, tested Torch installation recipe. If dependency metadata must be separated, make that a small prerequisite change and preserve the default Apple installation path. Do not use the unrelated Mac wheel blocker as a diagnosis of Jetson compatibility.
+
+### Gate B — actual CUDA and model correctness [C10, C12]
+
+Require a Torch-only smoke test that executes representative backend operations on CUDA and synchronizes. The acceptance invocation must fail if CUDA is required but absent, rather than quietly skipping or falling back to CPU. Assert tensor/output device identity, finite output and comparison against a deterministic reference.
+
+Then run Edge0-8B with a pinned checkpoint, tokenizer/chat template, LoRA/prerouter identity, prompt IDs, routing profile and numerical settings. Capture at least 32 greedy tokens and compare teacher-forced logits and token choices with identified reference data. Define tolerances before examining the Orin result. Any allowed near-tie token divergence must be explained by the logit comparison; do not retroactively loosen tolerances to pass.
+
+Run live MLX/Torch comparison suites where MLX is supported. Provide small, reviewed deterministic fixtures with generating commit, input/model hashes, dtype and tolerance for use on Jetson. An optimized CUDA path must also agree with the current Torch correctness path on the same Orin and workload. Keep free-running output checks separate from teacher-forced numerical comparisons.
+
+### Gate C — bounded shared memory [C06, C11]
+
+Require no OOM across initialization, prefill, decode and repeated requests for the declared workload. Replace the unsupported universal “RSS below 6.5 GB” acceptance threshold with an explicit byte budget and observed system headroom. Record the selected reserve and why it is adequate for this device's services and workload; it is a tested policy, not a hardware guarantee.
+
+Start from observed available RAM and any tighter process/container limit. Deduct allocations still to be made, OS/application growth reserve, KV/context growth, prefill and dequantization transients, pinned staging, in-flight work, retained caches and allocator/driver allowance. Account for each allocation once at the chosen observation point. Compute tensor payload sizes from checkpoint metadata; slot counts alone are insufficient.
+
+Validate minimum available RAM, RAM/swap trends, process RSS and Torch allocator peaks during the run. RSS and CUDA peaks are separate views and must not be added as a total. Mark swap activity explicitly; a swapping run cannot establish a resident-memory target. Reject impossible profiles before inference when the calculation can identify them, and preserve evidence for unexpected OOMs.
+
+### Gate D — measured optimization [C13, C14]
+
+For expert transfers, reuse a bounded payload pool after initialization; do not require every model operation to become allocation-free. Preserve exact fallback for required experts that are late, absent or predicted incorrectly. Demonstrate correct asynchronous ownership and a measured benefit before enabling a new path by default.
+
+Treat elimination of dense-layer dequantization as a separate, conditional objective. An expert gather kernel does not meet it. Any dense-weight cache must fit the byte budget; whole-model expansion is not a default Orin setting.
+
+## Task 1 — retain the probe; record its limits [C09]
+
+Keep `scripts/jetson_probe.py`, its stable schema and focused tests. Do not redo the completed increment. Add narrowly scoped corrections only if required evidence is missing or defective, with schema changes documented rather than silently redefining `ready`.
+
+Treat its Linux storage/sysfs behavior as platform-specific. Use Linux for those tests, and distinguish fixtures exercised on a supported host from behavior on the actual Jetson. The report builder introduced next must remain independently testable without this platform dependency.
+
+## Task 2 — functioning, machine-readable benchmark reporting [C03–C07]
+
+**Scope:** reporting, backend-aware measurement, focused tests and documentation. No cache/kernel optimization and no mandatory physical-device run in this increment.
+
+**Files:** modify `examples/bench.py`; add a pure helper such as `examples/benchmark_report.py`; add `tests/test_benchmark_report.py` and focused integration tests as appropriate; update `docs/nvidia.md` and this plan. Keep optional imports and metric collection outside the pure builder.
+
+### Measurement behavior [C03, C04, C05]
+
+The current benchmark calls peak-memory methods absent from the CUDA core. Add a benchmark-owned adapter: retain MLX metric behavior where available, use Torch CUDA metrics for an actual CUDA device, and use explicit unavailable values elsewhere. `EDGE0_BACKEND=cuda` alone does not prove the selected device is CUDA.
+
+Measure wall time with a monotonic clock. On CUDA, synchronize the resolved device before each timed phase and before its endpoint. Finish prefill before recording its time; complete untimed warmup before starting decode; finish the final timed step before recording decode. Use phase boundaries, not new per-token synchronizations. Include storage, transfer and CPU sampling costs in wall time; kernel-only event timings are a separate diagnostic. [PyTorch timing and stream semantics](https://docs.pytorch.org/docs/main/notes/cuda.html#asynchronous-execution).
+
+Keep the current two-run protocol, defaults, sampling behavior and human-output format. The existing warmup is greedy; timed iterations perform sampling followed by an engine step, including a final forward whose logits are not sampled. The loop is fixed-length and does not stop at EOS. Label this protocol explicitly; do not call it TTFT or EOS-aware completion latency. Correct the warmup comment without changing it to sampled warmup.
+
+For each run, record prompt tokens after chat templating; actual warmup tokens; timed decode tokens; total generated tokens; and context length at timed decode start. For the current loop, `total_generated = warmup + timed_decode` and `decode_start_context = prompt + warmup`. Timed throughput uses only timed decode tokens. Keep requested counts separately. Reject invalid negative counts and require a positive timed-token count; do not silently produce a successful empty benchmark.
+
+### Report contract [C05, C06, C16]
+
+Use a benchmark schema version independent of the probe schema. Include:
+
+| Group | Required information |
+|---|---|
+| Run identity | Timestamp, benchmark protocol version, Git commit, dirty status, run count/index and command/configuration needed to reproduce |
+| Model | Local resolved checkpoint path, model/revision identity, manifest digest where available, tokenizer/template and adapter/prerouter identity |
+| Runtime | Backend name, resolved device, observed execution evidence, Python/Torch/CUDA versions, platform; observed power mode or an explicit unavailable reason |
+| Workload | Prompt identity/digest and token count; counts defined above; resolved seed, temperature, top-k, top-p, repetition penalty, context/prefill settings |
+| Caches | Resolved LRU/prefetch/staging settings, weight-cache and prewarm flags, and relevant thread settings; do not record only requested environment variables |
+| Timings | Per-run prefill/decode seconds and their separate token/s values; all runs retained; summary calculation and variability defined |
+| Memory | Integer byte values, method and scope for every metric, with explicit unavailable reasons |
+| Probe link | Optional supplied probe file's schema version, content SHA-256 and local reference; linkage to that actual report, not only a schema number |
+
+Record process-lifetime peak RSS with a platform-specific method and unit normalization. If only periodic samples are available, call it a sampled peak and record the interval. A single endpoint RSS value is not a peak. Do not subtract lifetime high-water marks to invent a per-run peak.
+
+For CUDA, synchronize after engine reset, reset allocator peak statistics immediately before prefill, and read allocated/reserved peaks after synchronized decode. State that this covers prefill, warmup and decode, and includes allocations already resident at reset; it does not recover an earlier initialization transient. Start process/system observation before model load in physical baseline runs. Allocator peaks do not measure all driver or non-Torch memory. [Torch allocator scope](https://docs.pytorch.org/docs/main/notes/cuda.html#memory-management).
+
+Keep hashing, power queries, collector setup and report construction outside timed intervals. Preconfigured lightweight memory/system samplers may run throughout the benchmark; record their interval and use identical instrumentation for comparisons. The pure builder performs no collection. Prepare a checkpoint manifest outside measurement; do not hash large weights before each alleged cold-cache trial. A digest identifies an input but does not reproduce it: retain the referenced manifest/prompt in the private evidence set.
+
+Represent unavailable metrics as `null` with a reason. Distinguish unavailable metadata from a failed required measurement. Reject negative/nonfinite timings and memory; zero measured duration gives unavailable throughput, not a fabricated zero-rate success. Use strict JSON serialization (`allow_nan=False`). [Python JSON behavior](https://docs.python.org/3.10/library/json.html).
+
+### CLI and acceptance tests [C07]
+
+Add `--json-output PATH` and optional `--probe-json PATH`. Validate an explicitly requested probe before inference. Keep probe collection separate so generic benchmarks do not acquire Jetson prerequisites. Preserve human-output format, except measured numeric values may correctly change after synchronization.
+
+Require a new output path and reject an existing destination before inference. Write complete JSON atomically through a temporary file in the destination directory; report output errors with a nonzero exit status. Close the engine and collectors in `finally`, including generation and write failures. Failed inference must not leave a success report at the requested path; identify failures separately.
+
+Use TDD for schema/units, count arithmetic, requested versus resolved configuration, CPU/MLX/CUDA dispatch, phase synchronization order, missing metrics, malformed probes, nonfinite inputs, output failure and cleanup. Exercise the CLI and fake engine without weights. Test output-format compatibility without pinning real measured numbers. Host tests validate instrumentation; CUDA tests validate device behavior; neither substitutes for the Orin baseline.
+
+**Done:** applicable checks pass, exact results and host limitations are reported, documentation describes the protocol, and Task 3's next command is supplied. Stop here in the current handoff.
+
+**Status (14 September 2026):** implemented on this branch. `examples/benchmark_report.py` (pure builder, schema version 1), `examples/benchmark_measure.py` (backend-aware measurement adapter, process-memory sampler, git/power/checkpoint/adapter identity), `examples/bench.py` (`--json-output`, `--probe-json`, `--rss-sample-interval`, phase-boundary synchronization, pre-load validation, `finally` cleanup, lazy backend import), tests `tests/test_benchmark_report.py`, `tests/test_benchmark_measure.py`, `tests/test_bench_cli.py` (fakes only) and `tests/test_bench_backend.py` (real backend namespace, no weights), and the protocol/schema section in `docs/nvidia.md`. `pyproject.toml` gained `pythonpath = ["."]` so the plain `pytest` invocation collects the repo-root `scripts`/`examples` imports. Host checks only: no CUDA execution and no Orin run were performed; Task 3 starts with the commands below.
+
+## Task 3 — establish the unoptimized Orin baseline [C08–C10, C15]
+
+First complete Gate A's installation and model checks. Add a small Torch-only acceptance module, proposed as `tests/test_torch_cuda_smoke.py`, with a documented `--require-cuda` option or equivalent hard-fail contract. Add an on-device reference checker using the pinned fixtures described in Gate B. These are future deliverables, not commands that exist in the reviewed branch.
+
+The reviewed plan's `tests/test_nvidia_backend_smoke.py` is an MLX smoke test. The existing `test_cuda_backend.py` also imports MLX and uses CPU tensors in its comparison helper. Keep those suites, but do not use their skip/pass result as CUDA execution evidence.
+
+On the actual Orin, use an isolated validated environment and an untracked `$EDGE0_RUN_DIR`:
+
+```bash
+export EDGE0_BACKEND=cuda
+export EDGE0_TORCH_DEVICE=cuda
+export EDGE0_TORCH_WEIGHT_CACHE=0
+export EDGE0_PREWARM=0
+python scripts/jetson_probe.py --model-dir "$EDGE0_8B_MODEL" \
+  --output "$EDGE0_RUN_DIR/orin-probe.json"
+```
+
+After implementing the dedicated acceptance test, its intended invocation is:
+
+```bash
+python -m pytest tests/test_torch_cuda_smoke.py --require-cuda -q
+```
+
+Run the separate 32-token greedy correctness check and retain its comparison evidence. After that passes and Task 2 reporting exists, a short benchmark is:
+
+```bash
+BENCH_TEMP=0 BENCH_SEED=0 python examples/bench.py edge0-8b \
+  --ntok 32 --warmup 0 \
+  --probe-json "$EDGE0_RUN_DIR/orin-probe.json" \
+  --json-output "$EDGE0_RUN_DIR/orin-short-baseline.json"
+```
+
+For performance comparisons, freeze a workload manifest and use at least three independent process launches before and after optimization. Keep both internal runs from each launch and distinguish their order/cache state. Use the same prompt, counts, seed, checkpoint, numerical/routing settings and power profile on both sides. A benchmark reset is not an OS or expert-cache flush.
+
+Capture `tegrastats` beside the run, from before loading until cleanup, with interval and timestamps. Record power mode, clock policy, cooling, storage/filesystem and thermal/throttling evidence. Observe existing settings before proposing changes. Do not assume a fresh process makes storage cold or drop system caches automatically. [NVIDIA tegrastats](https://docs.nvidia.com/jetson/archives/r36.5/DeveloperGuide/AT/JetsonLinuxDevelopmentTools/TegrastatsUtility.html).
+
+If inference fails, preserve its stage, configuration, available diagnostic evidence and exit status. OOM diagnostics may not reveal an exact failing allocation, especially for an OS kill; state unknown when necessary. Reducing context or generation produces a new workload, so retain both results. If default inference cannot fit, a documented failed attempt permits a bounded-memory correction in Task 4; establish a successful reference baseline before asynchronous or kernel optimization.
+
+**Status (14 September 2026, on the physical device):** executed on an
+Orin Nano Developer Kit (Super) 8 GB, L4T R39.2, CUDA 13.2 driver,
+25W mode, NVMe.  Gate A: validated venv (Python 3.12.3, official torch
+2.14.0+cu130 aarch64 wheel — the GB10 combination; edge0 installed
+`--no-deps`, no MLX on device; `torch.nn.RMSNorm`, `torch.uint32`,
+tokenizer imports and CUDA kernel execution verified).  The wheel warns
+`sm_87` is outside its SASS list; execution evidence, not the warning,
+was used as the gate.  Probe: `ready: true`, no blockers.
+`tests/test_torch_cuda_smoke.py` + `tests/conftest.py` (`--require-cuda`)
+added: 6/6 pass on device; hard-fail contract verified with
+`CUDA_VISIBLE_DEVICES=""`.  `scripts/orin_reference_check.py` added
+(CUDA greedy vs torch-CPU teacher-forced logits, tolerances registered
+in the script before the run): 32/32 token choices identical, no
+near-ties consumed; the pre-registered vocab-wide logit bound (1.0)
+was exceeded (max |Δ| 2.06, tail-token bfloat16 noise — ≤ 0.22 at every
+step's top-8 tokens; analysis retained in the evidence set).  Recorded
+as a FAIL of that bound, not loosened retroactively; a top-k-scoped
+criterion is proposed for review before the next comparison run, and
+MLX fixtures remain the intended reference.  Short baseline: three
+independent launches × two runs (`--ntok 32 --warmup 0`, temp 0, seed 0,
+weight cache and prewarm off, tegrastats alongside): decode 0.53–0.58
+tok/s (mean 0.55), prefill 11.3–15.9 s at 37 prompt tokens, CUDA
+allocator peak ≤ 1.00 GiB, process peak RSS 5.3–5.8 GiB, GPU 99%
+utilized, no OOM/swap.  Raw JSON reports, npz logit captures and
+tegrastats logs live in the untracked `$EDGE0_RUN_DIR` evidence set;
+sanitized summary in `docs/nvidia.md`.  Task 4's profiling starts from
+this baseline; the dominant cost is per-call expert dequantization in
+`gather_qmm` (GB10 already measured 2.5× from the weight cache that
+Task 4's byte budget must first make safe to enable here).
+
+## Task 4 — memory-budgeted profile [C11]
+
+Implement the pure budget calculation first, then integrate at existing configuration/cache-construction points. Inspect `models/base.py`, the 8B configuration, `streaming/install.py`, `streaming/cache.py` and `streaming/layer.py`; the CUDA backend namespace alone cannot enforce the profile.
+
+Resolve byte limits for completed caches and in-flight builds, prefetch buffers, pinned memory, staged/assembled copies, full-layer prefill, transient dequantization and KV growth. Bound the producer queues as well as their completed outputs. Audit `prefetch_all()`, which can raise buffer capacity beyond its configured starting value.
+
+**Existing zero semantics:** `SharedExpertCache(0)` and `PrefetchBuffer(0)` disable eviction. Never pass a calculated zero allowance to them as if it disabled caching. Initially reject such impossible settings; if cache-off operation is needed, implement an explicit bounded/disabled state with regression tests rather than silently changing shared MLX semantics.
+
+Record resolved policy and rejected overrides. Keep full dequantized weight caching off unless the measured budget permits it. Test exhausted/tiny budgets, missing observations, overflow, invalid overrides, varying tensor sizes, inflight backpressure and repeated-request memory stability.
+
+**Status (15 September 2026, implemented and validated on the device):**
+`edge0/streaming/budget.py` (pure: `Observation` / `ExpertFootprint` /
+`WorkloadDecl` / `Reserves` → `resolve_budget()` → `ResolvedBudget` with
+itemized deductions; `bundle_bytes_from_entries()` prices the per-expert
+payload from the safetensors header, not slot counts).  Enforcement:
+`PrefetchBuffer` gained `max_cap` (a ceiling `set_cap` cannot exceed —
+bounds `prefetch_all()`'s silent growth to `num_experts + 32`);
+`LayerOptions.max_inflight` bounds QUEUED speculative prefetch builds
+(demand loads are never dropped); both default to the historical
+unbounded semantics when no budget is active.  Integration:
+`EDGE0_MEMORY_BUDGET=auto|<bytes>` resolved in the 8B engine's
+`load_installed` immediately before cache construction
+(`EDGE0_BUDGET_CONTEXT` declares the context, default 1024 tokens;
+`ModelConfig.kv_bytes_per_token` prices it — measured, 1.1 MB/token for
+this tier).  The resolved policy raises `BudgetError` pre-inference for
+impossible profiles — a calculated starved cache is rejected, never
+constructed as `SharedExpertCache(0)`/`PrefetchBuffer(0)` — and is
+recorded in the engine (`engine.memory_budget`) and the bench report's
+caches group.  `EDGE0_TORCH_WEIGHT_CACHE=1` under a budget is vetoed
+unless its measured 4.1 GB fits the post-cache headroom.  25 unit tests
+in `tests/test_memory_budget.py`; the streaming package init became
+lazy for backend-bound names so the pure modules test everywhere.
+On-device validation (Orin Nano 8 GB): `auto` resolved usable ≈ 4.2 GB,
+kept the tested 64/48 profile (real bundle ≈ 1.30 MiB/expert, full-layer
+transient 162 MiB), benchmark equivalent to the unoptimized baseline
+(0.52 tok/s, same peaks, RSS 5.55 GiB in the baseline range); a
+4096-token declaration was rejected with itemized arithmetic (KV
+4.5 GB > usable), and the weight cache was vetoed (4.1 GB > 2.2 GB
+headroom).  Not yet done: staged/assembled-copy pricing (the 8B
+`prod_k8` profile has staging off — budgeting a staged profile is
+future work with Task 5), and a long repeated-request soak (two
+same-process runs were stable; a sustained test belongs to Task 7).
+
+## Task 5 — bounded asynchronous expert transfers [C12, C13]
+
+The 8B `prod_k8` profile deliberately disables staged decode. Do not enable `staged_k8` or replace routing to activate prefetch. Integrate the new transfer cache with the existing exact expert-consumption path. Predictions may change scheduling, not required expert identity or contribution. Missing required data must wait/load through the reference path rather than use the existing staged zero-row behavior.
+
+Start with bounded reusable pinned buffers and CUDA slots as a candidate design. Both consume the same physical DRAM pool on Jetson; measure their duplication and benefit. Keep alternative memory paths and GPUDirect Storage deferred until support and benefit are established. [NVIDIA Tegra memory architecture](https://docs.nvidia.com/cuda/archive/13.0.2/cuda-for-tegra-appnote/index.html#memory-management).
+
+Define slot ownership from free → filling → ready → in-use → reusable, with generation IDs. Publish readiness only after copy completion. Reuse a slot only after all GPU consumers finish; retain pinned source contents until its copy finishes. Bound queued work; handle stale completion events, failed reads, cancellation, reset, close and partial initialization. Use explicit stream dependencies and allocator lifetime handling as required. [PyTorch stream ownership](https://docs.pytorch.org/docs/main/notes/cuda.html#cuda-streams).
+
+Test state transitions with fake events, then real CUDA stress/parity cases: wrong/late predictions, eviction during consumption, repeated requests and shutdown. Define counters and scopes for cache/prediction hits, bytes requested/read/copied, I/O wait and consumer stalls. Distinguish logical file reads from physical NVMe traffic. Demonstrate overlap and end-to-end improvement on the baseline workload before making the path default.
+
+**Status (15 September 2026, measured on the device):** the measured
+profile reshaped this task.  First finding: the tested 64-slot shared
+LRU is smaller than this tier's per-step working set (23 MoE layers x
+K=8 = 184 bundles), so on the baseline it NEVER hits (`hits: 0`,
+~184 rebuilds per token).  Second finding: fixing that (512 slots, 65%
+hit rate, loads 11,776 → 4,075 over the workload) moved end-to-end
+decode by roughly nothing (0.49–0.57 vs 0.50–0.52 tok/s) — the
+unoptimized decode is COMPUTE-bound (GPU pegged at 99%; per-call
+dequantization).  Per this task's own gate, the pinned-buffer /
+CUDA-stream slot pipeline (free→filling→ready→in-use→reusable,
+generation IDs) is therefore **deferred** — it would optimize a cost
+that is currently invisible end-to-end — and is to be revisited after
+Task 6 shrinks compute, when transfers become a meaningful fraction.
+
+What WAS implemented (opt-in, exact path untouched):
+`EDGE0_CACHE_SLOTS=<int>` overrides the REQUESTED LRU size (the budget
+may still lower it; zero/negative rejected), and
+`LayerOptions.predict_prefetch` / `EDGE0_PREDICT_PREFETCH=1` routes
+each step's prerouter predictions into the existing bounded
+`prefetch()` for non-staged layers (`prod_k8` keeps staged decode OFF;
+`stage_experts` is untouched; wrong/late predictions fall back to
+demand loads through `_get_bundles` — never a staged zero row).  The
+prefetch buffer is raised to one full predicted step (owners x K = 128)
+and the per-layer in-flight bound defaults to K, both priced by the
+Task 4 budget (in-flight transient = per-layer bound x producing
+layers).  Reuse-safety of consumed bundles rests on Python/torch
+reference counting (consumers hold the tensors they use); the manual
+slot-generation lifecycle belongs to the deferred pinned design.
+
+Measured (3 independent launches x 2 runs, identical workload and
+instrumentation as the Task 3 baseline, budget active): decode
+**0.568–0.623 tok/s, mean 0.594** vs baseline 0.53–0.58 mean 0.552
+(**+7.7%**); hit rate 85% (10,059 hits / 1,717 loads); 2,038 of 2,063
+predicted prefetches consumed (98.8%), 0 wasted, prefetch_wait 0.0 s —
+the builds genuinely overlap the forward; load wall 26.5 s → ~6 s;
+CUDA peak 1.45/1.58 GiB and RSS 5.48–5.82 GiB, both inside the
+resolved budget (headroom ≈ 1.27 GB) with no OOM.  Token choices are
+bit-identical to the Task 3 reference sequence with both knobs on.
+Kept **off by default** per Gate D: the gain is real but small while
+compute dominates; defaulting is a profile change to make together
+with the Task 6 re-measurement.  Remaining for a later increment:
+logical-vs-physical NVMe read accounting, CUDA stress cases for
+eviction-during-consumption, and the deferred pinned-slot pipeline.
+
+## Task 6 — conditional quantized-kernel work [C14]
+
+**Scoping (15 September 2026, measured on the device):** per-op decode
+shares — `gather_qmm` 37% (69 calls/step), dense `QuantizedLinear` 26%
+(235 calls/step), everything else 37%. Both dequantization paths
+qualify. Development is handed to a workstation GPU per
+[`rtx6000-task6-handoff.md`](rtx6000-task6-handoff.md); decisions and
+acceptance stay on the Orin.
+
+**Workstation increment (15 September 2026, RTX PRO 6000, torch
+2.14.0+cu130 — parity and pricing only, no Orin decision):** three
+opt-in, guarded paths, documented in `docs/nvidia.md` ("Opt-in quantized
+paths"): `EDGE0_QMM_BATCHED=1` (exact batched expert gather, transient
+priced at 140 MB for the decode shape and deducted by the budget),
+`EDGE0_TORCH_WEIGHT_CACHE_BYTES=<n>` (exact capped dequantized-weight
+cache, first-fit, shrunk to the budget headroom; the full cache is now
+priced at the measured bf16 total, 1.40 GB for this tier, not 4.1 GB),
+and `EDGE0_INT4PACK=1` (torch's built-in int4 kernel: approximate at
+bf16 rounding, bounds registered in `tests/test_int4pack.py` before any
+Orin run). Design C (custom fused kernel) was scoped to a cross-compile
+toolchain record only. Orin acceptance for each knob: the Task 3
+reference check with `--test-env <knob>` against the reference path on
+the same device, then the three-launch benchmark protocol.
+
+**Finding that reshapes this task's dense half:** traced on the real
+model, 400 of 470 dense `QuantizedLinear` calls per step arrive with
+float32 activations and only 70 with bfloat16. Both dense knobs require
+bf16, so the weight cache fills 35 of the 235 modules it admits
+(0.174 GB of 1.402 GB reserved) and the int4 kernel repacks exactly
+those same 35. Neither moves decode measurably as a result. The dense
+26% is therefore gated by activation dtype, not by the kernel; whether
+those call sites can run bf16, and what that costs numerically, is the
+question to settle on the device before more kernel effort. The batched
+expert gather is unaffected: it covers the routed 37% and engages on
+every call.
+
+Use the measured profile to choose expert gather, dense quantized linear work, or no kernel change. For an INT4 prototype, verify the actual checkpoint layout: packed words, group size, signed/negative scale behavior, bias handling, accumulation and output dtype. Pin the CUDA extension/CUTLASS/compiler combination supported by the detected Orin stack and verify runtime loading.
+
+Dispatch only supported dtype/shape/stride/transpose/group-size/device combinations to the new kernel. Keep the current implementation for unsupported cases, including 2/8-bit layouts. Test all existing broadcast and gather shapes, valid index boundaries, quantization extremes and checkpoint dtypes. Compare numerical results against both deterministic MLX fixtures and the current Torch path on Orin. Define tolerances in advance and measure scratch-memory peaks as well as speed.
+
+A fused expert gather does not remove dense `QuantizedLinear` dequantization. If dense work remains dominant, handle it as its own bounded, parity-tested change or document the residual cost. Gate D does not require eliminating all model allocations.
+
+**Status — ACCEPTED ON THE DEVICE (16 September 2026).** Orin Nano 8 GB,
+same workload and instrumentation as the Task 3 baseline, budget active,
+three launches x two runs per configuration; sanitized tables in
+`docs/nvidia.md` (Task 6 Orin acceptance), raw reports in the evidence
+set.  Suite 341 passed on-device, 96 under `--require-cuda`.
+
+*Adopted:* the batched expert gather is now the **default** on the CUDA
+backend (`EDGE0_QMM_BATCHED=0` selects the reference loop).  It is the
+only candidate that both PASSED the registered 32-token reference bound
+on the target (32/32 token choices, max |Δlogit| 0.777 vs the bound of
+1.0) and delivered a measured benefit there: decode 0.623–0.699,
+mean **0.668 tok/s, +20.7%** over the 0.553 baseline, at unchanged CUDA
+peak (1.00 GiB) and RSS.  Its transient is bounded and the budget
+deducts the cap (verified in the report: `kernel_transient` 268,435,456
+with no env var set).  `int4pack.probe` executes on sm_87 — the kernel
+runs on hardware the wheel's SASS list does not advertise, decided by
+execution as designed.
+
+*Not adopted (kept opt-in):* the capped weight cache (+0.8%) and the
+int4 kernel (+3.7%), both because the activation-dtype gate limits them
+to 35 of 235 modules, and both exceed the registered bound (1.58 and
+2.17) — recorded as that bound's failures, not loosened.
+
+*Gate D's Task 5 re-measurement:* with compute reduced the transfer
+knobs are worth much more than before — +7.7% pre-Task-6, **+17.5% on
+top of the batched gather** now (0.668 → 0.785 tok/s, expert load wall
+72.5 s → 17.0 s over the same six runs).  `EDGE0_MEMORY_BUDGET=auto
+EDGE0_CACHE_SLOTS=512 EDGE0_PREDICT_PREFETCH=1` is the recommended Orin
+profile and stays opt-in as board-specific tuning that requires the
+budget.  End to end the tier now runs at **0.785 tok/s, +42% over the
+Task 3 baseline**, inside the resolved budget with no OOM.
+
+*Two workstation claims corrected here, both only visible on the target:*
+the capped weight cache is NOT bit-identical on sm_87 — the cached
+weights are, but one GEMM versus the reference's per-chunk GEMMs differs
+by one bf16 ulp of accumulation order (isolated directly: same weights,
+0.03125 on a 30.6 scale), so that exactness was a property of the
+workstation's cuBLAS heuristics; and the float32 activation gate is
+deliberate MLX promotion parity in the MLA/RoPE path (layer 3 is the
+first `BailingMLA`; the residual stream is float32 from there on), so
+reaching the remaining dense 26% is a numerics-parity decision for
+review, not a kernel increment.
+
+*Open for a later increment:* design C (custom fused kernel) remains
+unwritten with its toolchain recorded; the MLA float32 promotion
+question; and the deferred pinned-slot transfer pipeline from Task 5,
+which is now more attractive than it was at the compute-bound baseline.
+
+## Task 7 — final validation and evidence [C15, C16]
+
+Repeat the identical workload manifest using at least three independent launches. Retain individual prefill/decode results, explain first-versus-repeated-run state, and report sample count, mean, standard deviation and min/max separately. Treat the small sample as descriptive evidence rather than a broad performance guarantee.
+
+Repeat correctness, maximum declared context/generation, memory pressure and repeated-request checks, plus a declared sustained-run test long enough to expose thermal behavior. Capture failures and throttling. State the tested operating envelope: exact board/software/checkpoint/profile, context limits, memory reserve and remaining limitations.
+
+Only claim physical Orin inference once Gate B passes, and qualify the claim to its tested workload. Claim the bounded profile or optimization only after its own gates pass. Commit reviewed code/tests/docs and sanitized result summaries; keep raw benchmarks, telemetry, private paths, identifiers and checkpoints in the separate evidence set. Small reviewed deterministic test fixtures are test assets, not raw benchmark dumps.
+
+**Status — COMPLETE (16 September 2026).**  The tested operating
+envelope is stated in `docs/nvidia.md`; raw reports, telemetry logs and
+the npz logit captures stay in the untracked evidence set.
+
+*Repeat measurement.*  Final adopted profile, three independent launches
+x two runs: decode 0.744–0.786 tok/s, **mean 0.772, sd 0.016** (n=6),
+prefill 13.6–15.6 s, CUDA peak 1.58 GiB, RSS 5.57–5.69 GiB.  Reported as
+descriptive statistics of a small sample, not a guarantee.
+
+*Correctness repeat.*  Same-device 32-token reference check of the final
+profile against the reference loop: **PASS**, 32/32 token choices
+identical, max |Δlogit| 0.777 against the registered bound of 1.0.  All
+30 requests of the sustained run produced byte-identical tokens.
+
+*Maximum declared context and generation.*  KV growth was MEASURED here
+rather than inherited: the marginal cost is 561,320 B/token (548 KiB),
+about half the 1,100,000 taken from the README's Apple/MLX figure, so
+`kv_bytes_per_token` for this tier is corrected to 600,000 (≈7% margin).
+Growth is sublinear below the top of the range because most layers of
+this hybrid are KDA with fixed-size state; only the MLA layers' KV grows
+with context, which is why the top-of-range marginal slope is the right
+constant to extrapolate from.  With it the budget admits a **4096-token
+declared context** on this board (it admitted ~2560 before), validated
+by a real 3292-token prompt run: prefill 42.4–42.8 tok/s, decode
+0.72–0.81 tok/s, CUDA peak 3.14 GiB, RSS 5.8 GiB, no OOM, 39 MB of
+resolved headroom at a 3584-token declaration.  Generation validated to
+**256 tokens** in one request (0.807 / 0.820 tok/s — no decay with
+length).
+
+*Memory pressure, repeated requests, sustained run.*  30 sequential
+requests in one process over 25 minutes (960 tokens): decode mean
+**0.817 tok/s**, sd 0.028, quartile means 0.791 / 0.834 / 0.816 / 0.824
+— no degradation over time.  Junction temperature 54.5–61.8 °C with
+**no throttling** (GPU busy in 749 of 774 samples).  RSS moved between
+5.45 and 5.70 GiB, rising and falling rather than growing monotonically:
+mmapped expert pages reclaimed and re-faulted, not a leak; CUDA
+allocator peaks flat at 1.57 GiB.
+
+*Swap, marked explicitly.*  The sustained run DID swap: +1,165 MB during
+the first fifth, then flat (+24, 0, +18, −2 MB), with no throughput
+loss.  That is a one-time eviction of the resident desktop session's
+idle pages, not the model's working set thrashing — but per Gate C a
+swapping run cannot establish a resident-memory target, so no swap-free
+claim is made for this board with a desktop resident.
+
+*The claim, qualified.*  edge0-8b runs on a physical Jetson Orin Nano
+8 GB at **0.77–0.82 tok/s decode**, 42 tok/s prefill at 3.3k tokens,
+within a byte budget that rejects what does not fit before loading, with
+token choices matching the reference implementation on this device.  The
+claim covers exactly the board, build, checkpoint, profile and workloads
+above: single request, greedy sampling, ≤ 4096 declared context, ≤ 256
+validated generation, 25W mode, desktop resident.
+
+*Remaining, none of it blocking:* design C (custom fused kernel,
+toolchain recorded); the MLA float32 promotion question that gates the
+dense 26%; the deferred pinned-slot transfer pipeline; concurrent /
+batched requests, which were never in scope here; and short-prompt
+prefill overhead (2–3 tok/s at 37 tokens against 42 tok/s at 3292),
+which no increment targeted.
diff --git a/docs/plans/rtx6000-task6-handoff.md b/docs/plans/rtx6000-task6-handoff.md
new file mode 100644
index 0000000..0366f35
--- /dev/null
+++ b/docs/plans/rtx6000-task6-handoff.md
@@ -0,0 +1,241 @@
+# Task 6 handoff: quantized-kernel development on a workstation GPU
+
+Written 15 September 2026 on the target Orin, for kernel development on
+a separate CUDA workstation (RTX 6000-class). Read
+[`jetson-orin-nano.md`](jetson-orin-nano.md) Task 6 and Gate D first —
+this document adds the measured profile that picks the work and the
+division of labor between the two machines. Branch:
+`feat/jetson-orin-nano-foundation` (Tasks 1–5 complete; Task 3–5
+statuses in the plan carry the Orin evidence).
+
+## Why this split
+
+Kernel iteration (nvcc/CUTLASS builds, parity sweeps) is slow and
+memory-cramped on the 8 GB Orin. Correctness of an int4 kernel is
+arch-portable and can be developed anywhere torch + CUDA runs; sm_87
+SASS cross-compiles from any x86 CUDA 12/13 toolchain
+(`-gencode arch=compute_87,code=sm_87` — no Jetson needed to build).
+What does NOT transfer is performance: an RTX 6000 (discrete GDDR,
+different SM generation) has a different bottleneck shape than the
+unified-LPDDR5 sm_87 board, exactly the way the plan forbids projecting
+GB10 numbers. So: **develop and parity-test there, decide and accept
+here.**
+
+## The measured Orin profile (what to optimize)
+
+Decode is compute-bound (GPU 99%; transfers measured near-irrelevant —
+plan Task 5 status). Per-op shares of one decode step, synchronized
+timers, unoptimized profile (`EDGE0_TORCH_WEIGHT_CACHE=0`; shares are
+the signal, absolute times are sync-inflated):
+
+| Op | Share | Calls per step | What it is |
+|---|---:|---:|---|
+| `backends/cuda/quant.py::gather_qmm` | **37%** | 69 (23 layers × 3 projections) | routed experts: python loop over ≤8 experts, each dequantized in full to float32, then matmul |
+| `backends/cuda/nn.py::QuantizedLinear.forward` | **26%** | 235 | dense attention / shared expert / router / lm_head: dequantize per call, then linear |
+| everything else | 37% | — | attention, routing, sampling, expert loads, sync overhead |
+
+Both consumers read the same storage format: MLX affine int4,
+group_size 64, codes packed 8-per-uint32 little-end-first along the
+input axis, `w = code * scale + bias`, scales/biases bf16, **scales can
+be negative and there is no zero-point symmetry** — see the layout
+notes at the top of `backends/cuda/quant.py`, verified against real
+`mx.quantize` output in `tests/test_cuda_backend.py`.
+
+## Candidate designs (in rising effort order)
+
+A. **Repack to torch's built-in int4 kernel.** `torch.ops.aten.
+   _weight_int4pack_mm` (the gpt-fast / torchao path) runs group-wise
+   int4×bf16 on CUDA. One-time repack at load (MLX layout → tensor-core
+   tiled layout; MLX's `scale/bias` maps to the kernel's
+   `scales_and_zeros`) would accelerate `QuantizedLinear` with no
+   custom extension. Check sm_87 support in the pinned torch build
+   FIRST (the Orin runs the official `2.14.0+cu130` aarch64 wheel);
+   verify the affine (bias, not zero-point) mapping is exact, not
+   approximate.
+B. **Batch the expert loop.** `gather_qmm` currently dequantizes and
+   matmuls one distinct expert at a time in python. A batched variant
+   (dequantize the ≤8 gathered experts into one `[E, out, in]`
+   transient, one `bmm`) cuts launch count ~8× at the cost of a
+   bounded, budget-priceable transient. Pure torch, no extension —
+   cheap to try before any custom kernel.
+C. **Custom fused kernel** (CUDA C++/CUTLASS extension): int4 dequant
+   in registers fused into the matmul, covering both the gathered
+   (`rhs_indices`) and dense cases. Highest ceiling, highest cost; pin
+   the extension/compiler combination and prove runtime loading on the
+   Orin stack per the plan.
+
+Recommendation: try A and B first — they are hours, not days, and their
+Orin acceptance can run immediately.
+
+## Workstation setup
+
+```bash
+git clone <repo> && cd Edge0
+git checkout feat/jetson-orin-nano-foundation
+python3.12 -m venv .venv
+.venv/bin/pip install "numpy>=1.24" "safetensors>=0.4" "tokenizers>=0.15" \
+    "psutil>=5.9" "pytest>=8.0" transformers
+.venv/bin/pip install torch --index-url https://download.pytorch.org/whl/cu130
+.venv/bin/pip install -e . --no-deps        # keep MLX out
+.venv/bin/python -m pytest -q               # expect: all pass, MLX suites skip
+.venv/bin/python -m pytest tests/test_torch_cuda_smoke.py --require-cuda -q
+```
+
+Real weights are optional for kernel work (the parity tests build
+synthetic quantized tensors); for end-to-end runs fetch
+`Edge0/Edge0-8B-A1B-preview` (~4.2 GB) per the README and export
+`EDGE0_BACKEND=cuda EDGE0_8B_MODEL=...`.
+
+## Deliverables (what to bring back)
+
+1. The kernel/path behind a **guarded dispatch**: only supported
+   dtype/shape/stride/transpose/group-size/device combinations take the
+   new path; everything else — including 2-bit and 8-bit layouts —
+   falls through to the current reference implementation unchanged.
+   Off by default (env-gated), like every Task 5 knob.
+2. **Parity tests in the smoke-suite style** (hand-computed references,
+   no MLX): every broadcast/gather shape already covered in
+   `tests/test_cuda_backend.py`, index boundaries, negative scales,
+   quantization extremes, all checkpoint dtypes. Tolerances DEFINED IN
+   THE TEST before any Orin run (the Task 3 reference check shows the
+   format for pre-registering them).
+3. Build pinned and cross-arch: compile for the workstation's arch AND
+   `compute_87`; record the exact toolchain versions. For design A,
+   record the repack transform and its inverse test.
+4. Scratch/transient memory of the new path measured and stated in
+   bytes, so the Task 4 budget can price it (`streaming/budget.py`
+   takes it as a deduction or per-call transient).
+
+## What stays on the Orin (do not claim from the workstation)
+
+* Which design wins, and any tok/s number: re-run the profile above and
+  the 3-launch benchmark protocol (`docs/nvidia.md`, Task 3 status) on
+  the Orin only.
+* Runtime loading of any compiled extension on the L4T R39 / CUDA 13.2
+  / torch 2.14.0+cu130 stack.
+* The 32-token reference check (`scripts/orin_reference_check.py`)
+  with the new path enabled — token choices must stay explainable
+  under the pre-registered comparison, same as Task 3.
+* The Task 5 re-measurement: once compute shrinks, transfers matter
+  more — `EDGE0_CACHE_SLOTS` / `EDGE0_PREDICT_PREFETCH` (+7.7%
+  measured pre-Task-6) and the deferred pinned-slot pipeline get
+  re-evaluated then.
+
+## Workstation results (15 September 2026)
+
+Workstation: RTX PRO 6000 Blackwell (sm_120, 96 GB), Windows 11; venv
+Python 3.12 + **torch 2.14.0+cu130** (the Orin's torch version, x86
+build) for every GPU measurement; a torch-CPU venv (Python 3.11) and a
+Python 3.9 venv for portability; WSL Ubuntu 24.04 for the Linux checks.
+Nothing below is an Orin number.
+
+### Delivered (all opt-in, off by default, guarded, priced)
+
+| Design | Knob | Files | Status |
+|---|---|---|---|
+| B batched expert gather | `EDGE0_QMM_BATCHED=1`, `EDGE0_QMM_BATCHED_MAX_BYTES` | `backends/cuda/quant.py` | exact (float32, parity 1e-4 to a float64 hand reference, 1e-5 to the loop); 4-bit affine only, 2/8-bit and over-cap calls fall through; transient priced by `batched_transient_bytes` and asserted against allocator peaks in `tests/test_quant_paths.py`; kernel launches per call (reference loop vs batched) counted with `torch.profiler`, >= 3x fewer asserted |
+| A' capped exact weight cache | `EDGE0_TORCH_WEIGHT_CACHE_BYTES=<n>` | `backends/cuda/nn.py` (`WeightCachePolicy`), `backends/cuda/io.py`, `engine/ling.py` | first-fit in checkpoint order, each module admitted only if its resident bytes AND its own build transient fit; engine shrinks the cap to the budget headroom. The dequantized weight is bit-identical to the on-the-fly path (same per-chunk expression, asserted on CUDA); the cached forward issues one GEMM instead of one per 4096-row chunk, which only the two modules wider than a chunk (lm_head, layer-0 dense gate/up) can notice. **The fill is chunked**: whole-weight dequantization of lm_head (157184 x 1536) peaks at 3702 MiB for a 460.5 MiB result and would OOM the Orin's stated headroom; chunked it measures 556.9 MiB, and `fill_transient_bytes` prices that. The full cache shares the branch and inherits the fix; it is priced from the loader's measured total (235 cacheable linears, 1.402 GB bf16 — routers are not quantized here and `word_embeddings` is a lookup-only `QuantizedEmbedding`) plus one fill transient |
+| A torch int4 kernel | `EDGE0_INT4PACK=1` | `backends/cuda/int4pack.py`, `backends/cuda/nn.py` | runs on torch 2.14.0+cu130; **approximate**: per-weight error median 3.7e-4 / p99 3.7e-3 / max 1.1e-2 (n=512, k=1536, MLX-like statistics), 68% of weights identical to the reference's bf16 weights, outputs within 3.5e-3 of the output scale; bounds registered in `tests/test_int4pack.py` (1e-2 of output scale; 2^-6 (max\|w\| + max\|zero\|) per weight). Constraints verified on this build: bf16 activations only, `in_features % 128 == 0` (every edge0-8b dense k qualifies: 256, 512, 1536, 2048, 4608), `out_features % 8 == 0` up to the 157184-row lm_head; the dequantization is exactly `(q - 8) * scale + zero` on an identity probe. **sm_87 is not answered from a table**: `int4pack.probe` executes the kernel once per module on the target device before committing, and any runtime failure disables the path for that module — so a wheel without an image for the Orin's arch falls through instead of raising. Extra resident bytes: the repacked payload, 0.351 GB for all dense linears; originals stay for the fall-through paths |
+| C custom fused kernel | — | — | not written; toolchain proven: WSL `nvcc` 13.0.88 + g++ 13.3.0 compile `-gencode arch=compute_87,code=sm_87 -gencode arch=compute_120,code=sm_120` and the binary runs on this GPU; Windows alternative: VS 2022 BuildTools + CUDA 12.8 |
+
+Budget: `streaming/budget.py` gained `Reserves.kernel_transient_bytes`
+(the batched gather's cap, deducted once when the path is on) and
+`dense_cache_request`, which prices the dense cache as resident bytes
+plus one build transient (`full` keeps its veto, `capped` shrinks to the
+headroom, `off` prices nothing); `engine/ling.py` calls it and
+re-finalizes the policy after the budget resolves.
+Report: `examples/bench.py` records `caches.quant_paths` (batched gate
+and cap, the policy's admitted/skipped modules with their bytes and fill
+transients, int4pack repacked modules and extra bytes) and echoes the
+four knobs.
+Reference check: `scripts/orin_reference_check.py --test-env KEY=VALUE`
+/ `--reference-env` run the two phases with different knobs on the same
+device. The report now carries **host identity** (GPU name, compute
+capability, torch build, `/proc/device-tree/model`, machine, hashed
+hostname) and each phase's **resolved** knobs, not just the CLI
+overrides — a workstation report can no longer be mistaken for an Orin
+one, and a same-device run whose two phases resolve identical knobs
+warns that it is comparing a configuration with itself. The schema is
+`edge0-reference-check/2`.
+
+### Same-device reference checks on the workstation (real weights)
+
+`scripts/orin_reference_check.py models/edge0-8b --test-device cuda
+--reference-device cuda --test-env <KNOB>` — the reference path
+teacher-forces the tokens the knob's path generated, on the same GPU, so
+the only variable is the knob. 32 greedy tokens, edge0-8b, RTX PRO 6000:
+
+| Knob | Token choices | Divergences | max abs logit diff | Verdict against the registered bound (1.0) |
+|---|---|---|---|---|
+| `EDGE0_TORCH_WEIGHT_CACHE_BYTES=2000000000` | 32/32 identical | 0 | **0 exactly** | PASS — bit-identical through the whole model, the strongest form of the exactness claim |
+| `EDGE0_QMM_BATCHED=1` | 32/32 identical | 0 | 1.01 | FAIL of that bound, reported as such |
+| `EDGE0_INT4PACK=1` | 32/32 identical | 0 | 2.06 | FAIL of that bound, reported as such |
+
+All three keep every token choice with zero near-ties consumed. The two
+that exceed the bound are **not** loosened: as in Task 3, the bound's
+failure is recorded. For the batched gather the mechanism is identified —
+at the real decode shapes it lands within one bfloat16 ulp of the
+reference loop (`tests/test_quant_paths.py` asserts exactly that), and 24
+layers of one-ulp differences accumulate; note the Task 3 CUDA-vs-CPU
+baseline measured 2.06 by the same mechanism, so 1.01 sits below the
+noise the tier already exhibits. For the int4 kernel the difference is
+expected by construction (bf16 zero-point and bf16 dequantization). The
+Orin's own reference check decides acceptability; a top-k-scoped
+criterion is the change to propose in review first, per the Task 3 status.
+
+**A caution about this machine's shape.** Decode here runs at roughly
+1 tok/s against the Orin's 0.55 — under 2x, on a GPU with vastly more
+compute. That is the handoff's point restated as data: the bottleneck is
+launch and host overhead, not arithmetic, so a workstation speedup would
+not transfer. No tok/s comparison between configurations is reported
+here for that reason; only launch counts, bytes and parity.
+
+### The finding that reshapes the dense half of Task 6
+
+**Most dense `QuantizedLinear` calls run with float32 activations, so
+both dense paths engage on a small minority of them.** Traced on the real
+model, one prefill plus one decode step: **400 of 470 calls arrive as
+float32, only 70 as bfloat16.** Both dense knobs require bf16 — the cache
+because it is priced at the checkpoint's scales itemsize, the int4 kernel
+because `_weight_int4pack_mm` accepts nothing else. So:
+
+* the weight cache admits 235 modules / 1.402 GB but **actually fills 35
+  modules / 0.174 GB**; the reservation is conservative and never
+  under-reserves, and the bench report now states `filled_bytes` beside
+  `admitted_bytes` so the two are never confused;
+* the int4 kernel repacks **exactly those same 35 modules** — that is
+  where its `repacked_modules: 35` comes from, not from a shape guard;
+* neither knob moves decode measurably on this GPU (0.95 and 0.96 against
+  a 0.92 baseline), which is what covering 70 of 470 calls predicts.
+
+This is the thing to settle before spending more effort on design A or C:
+the dense half of the 26% is currently gated by **activation dtype, not by
+the kernel**. Whether those float32 call sites can run bf16 (and what that
+costs numerically) is a model-path question for the Orin session, and it
+governs how much of that 26% any kernel can reach. The batched expert
+gather is unaffected — it covers the routed 37% and engages on every call.
+
+### What the benchmarks showed (workstation only, 3 launches x 2 runs each)
+
+| Configuration | decode tok/s (6 runs) | CUDA alloc peak | Engaged |
+|---|---|---|---|
+| baseline | 0.90-0.95 (mean 0.92) | 1.02 GiB | — |
+| `EDGE0_QMM_BATCHED=1` | 1.41-1.52 (mean 1.46) | 1.02 GiB | every gather call |
+| `EDGE0_TORCH_WEIGHT_CACHE_BYTES=1.5e9` | 0.94-0.96 (mean 0.95) | 1.18 GiB | 35/235 modules filled |
+| `EDGE0_INT4PACK=1` | 0.95-0.96 (mean 0.96) | 1.07 GiB | 35 modules repacked |
+| batched + weight cache | 1.46-1.47 (mean 1.46) | 1.18 GiB | both |
+
+Every configuration ran to completion with the budget active, no OOM.
+**Do not project the batched gather's 1.59x onto the Orin.** The
+mechanism (fewer kernel launches) is the same one that dominates the
+Orin's decode, but this is a different SM generation with different
+launch costs, and the plan forbids projecting between machines — the
+whole reason this workstation decodes at only ~1 tok/s against the
+Orin's 0.55 despite far more compute. The number is here as evidence the
+path works end to end, not as a prediction.
+
+### How the Orin accepts a knob
+
+1. `EDGE0_BACKEND=cuda EDGE0_TORCH_DEVICE=cuda python -m pytest tests/test_quant_paths.py tests/test_weight_cache_policy.py tests/test_int4pack.py tests/test_task6_budget.py --require-cuda -q` on the board (the CUDA cases run for real there).
+2. `scripts/orin_reference_check.py edge0-8b --test-device cuda --reference-device cuda --test-env <KNOB>=<value> --output "$EDGE0_RUN_DIR/ref-<knob>.json"` — the reference path vs the knob on the same device; the exact knobs must match 32/32 tokens with logits at float32-noise level, the int4 kernel is judged by the pre-registered bounds and the near-tie rule.
+3. The three-launch benchmark protocol (Task 3 status) with `EDGE0_MEMORY_BUDGET=auto` so the transient / cache bytes are priced, comparing against the Task 5 baseline; then the Task 5 re-measurement.
diff --git a/examples/bench.py b/examples/bench.py
index 971c459..12faba3 100644
--- a/examples/bench.py
+++ b/examples/bench.py
@@ -2,17 +2,40 @@
 """edge0 speed + memory benchmark (any tier).
 
 Runs the same measurement shape as the deployment's bench: prefill ->
-sampled warmup steps -> timed sampled decode -> report tok/s and MLX
-peak active memory.  Works for both tiers; the tier is auto-detected
-from the checkpoint (or forced via the model name).
+greedy warmup steps (untimed) -> timed sampled decode -> report tok/s and
+the backend's peak memory (MLX peak active memory; the torch CUDA
+allocator's peak allocated bytes on a CUDA device; n/a for torch on
+cpu/mps).  Works for both tiers; the tier is auto-detected from the
+checkpoint (or forced via the model name).
+
+What the numbers are (and are not).  Two runs per process; each run
+resets the engine, times the chat-templated prefill, runs ``--warmup``
+greedy steps untimed, then times ``--ntok`` iterations of "sample one
+token, run one engine step".  The loop is fixed-length and does not stop
+at EOS; the final step's logits are computed but never sampled.  This is
+NOT time-to-first-token and NOT an EOS-aware completion latency.  On a
+CUDA device the resolved device is synchronized at those phase
+boundaries only (after reset, end of prefill, end of warmup, after the
+final timed step) so every wall time includes the device work it
+launched; storage, transfer and CPU sampling costs are inside the wall
+time by design.  Sampling at temperature 0 is greedy (see
+``edge0.sampling``), so ``BENCH_TEMP=0`` output does not depend on the
+seed; the seed is still recorded.
 
 Usage:
     python examples/bench.py /path/to/model [--ntok 200] [--warmup 10]
     python examples/bench.py edge0-35b        # via $EDGE0_35B_MODEL
     BENCH_LONG=1 python examples/bench.py edge0-35b   # ~3k-token prefill
+    python examples/bench.py edge0-8b --json-output "$RUN/bench.json" \\
+        --probe-json "$RUN/orin-probe.json"   # machine-readable report
+
+``--json-output`` must name a NEW file (an existing one is refused before
+the model loads); the report schema is described in docs/nvidia.md.
+Keep the JSON outside tracked source: it records local paths and the
+prompt text.
 
 Env (sampling knobs, defaults follow the tier's GenerationConfig):
-    BENCH_TEMP / BENCH_PROMPT / BENCH_SEED
+    BENCH_TEMP / BENCH_PROMPT / BENCH_SEED / BENCH_NTOK
     BENCH_LONG=1  use a ~3k-token synthetic prompt so the prefill timing
                   is meaningful (short prompts only measure fixed
                   overhead; set BENCH_PROMPT for your own long text)
@@ -21,13 +44,26 @@
 from __future__ import annotations
 
 import argparse
+import dataclasses
+import enum
+import hashlib
+import math
 import os
 import sys
 import time
+import traceback
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+try:  # imported as ``examples.bench`` (tests)
+    from examples import benchmark_measure as measure
+    from examples import benchmark_report as report
+except ImportError:  # run as a script: helpers sit next to this file
+    import benchmark_measure as measure  # type: ignore[no-redef]
+    import benchmark_report as report  # type: ignore[no-redef]
 
-from edge0 import AutoEngine
-from edge0.backends import core
-from edge0.sampling import sample
+REPO_ROOT = Path(__file__).resolve().parents[1]
 
 PROMPTS = {
     "edge0-35b": "什么是混合专家模型（MoE）？它和普通 Transformer 有什么区别？",
@@ -55,12 +91,49 @@
     "hidden state, SSD read latency hides behind compute entirely, which "
     "matters for large-model deployment on edge hardware.")
 
+#: Environment knobs echoed into the report as REQUESTED (raw strings,
+#: snapshotted before the engine is built: ``engine/ling.py`` sets a
+#: default ``LING_HIDDEN_CLIP`` the user did not ask for).
+ENV_KNOBS = ("BENCH_TEMP", "BENCH_PROMPT", "BENCH_SEED", "BENCH_NTOK",
+             "BENCH_LONG", "EDGE0_BACKEND", "EDGE0_TORCH_DEVICE",
+             "EDGE0_MEMORY_BUDGET", "EDGE0_BUDGET_CONTEXT",
+             "EDGE0_CACHE_SLOTS", "EDGE0_PREDICT_PREFETCH",
+             "EDGE0_QMM_BATCHED", "EDGE0_QMM_BATCHED_MAX_BYTES",
+             "EDGE0_TORCH_WEIGHT_CACHE_BYTES", "EDGE0_INT4PACK",
+             "EDGE0_TORCH_WEIGHT_CACHE", "EDGE0_PREWARM", "LING_PREWARM",
+             "MLX_CACHE_LIMIT_MB", "LING_HIDDEN_CLIP",
+             "PREROUTER_FEATURE_TOPK", "PREROUTER_INTRA")
+
+_TOKENIZER_FILE_PREFIXES = ("tokenizer", "chat_template", "special_tokens",
+                            "vocab", "merges", "added_tokens")
+
+
+def _framework():
+    """The active backend, its array namespace and the sampler.
+
+    Imported lazily: ``edge0.backends`` binds to ``EDGE0_BACKEND`` at
+    import time, and nothing in argument validation, ``--help`` or the
+    pre-load output/probe checks needs a backend.  Tests replace this
+    with fakes.
+    """
+    from edge0.backends import backend, core
+    from edge0.sampling import sample
+    return backend, core, sample
+
 
 def _long_prompt() -> str:
     paras = [_PARA_ZH if i % 2 == 0 else _PARA_EN for i in range(40)]
     return "请仔细阅读以下材料并用一句话总结其核心思想：" + " ".join(paras)
 
 
+def _prompt_source() -> str:
+    if os.environ.get("BENCH_PROMPT"):
+        return "BENCH_PROMPT"
+    if os.environ.get("BENCH_LONG") == "1":
+        return "BENCH_LONG"
+    return "tier default"
+
+
 def _prompt_for(engine) -> str:
     if os.environ.get("BENCH_PROMPT"):
         return os.environ["BENCH_PROMPT"]
@@ -69,46 +142,115 @@ def _prompt_for(engine) -> str:
     return PROMPTS.get(engine.name, DEFAULT_PROMPT)
 
 
-def run_bench(engine, ntok: int, warmup: int) -> dict:
+def _encode_prompt(engine, prompt: str) -> list[int]:
     tok = engine._tok
-    prompt = _prompt_for(engine)
     if hasattr(engine, "encode_chat"):
-        ids = engine.encode_chat(
-            [{"role": "user", "content": prompt}], think=False)
-    else:
-        ids = list(tok(tok.apply_chat_template(
-            [{"role": "user", "content": prompt}],
-            tokenize=False, add_generation_prompt=True,
-            enable_thinking=False))["input_ids"])
+        return [int(t) for t in engine.encode_chat(
+            [{"role": "user", "content": prompt}], think=False)]
+    return [int(t) for t in tok(tok.apply_chat_template(
+        [{"role": "user", "content": prompt}],
+        tokenize=False, add_generation_prompt=True,
+        enable_thinking=False))["input_ids"]]
 
+
+def _sampling_knobs(engine) -> dict:
+    """Resolved sampling settings: the tier's GenerationConfig, overridden
+    by BENCH_TEMP / BENCH_SEED (parsed once; ``BENCH_SEED=0`` is a seed)."""
     gen = getattr(engine.cfg, "gen", None)
-    temperature = float(os.environ.get(
-        "BENCH_TEMP", getattr(gen, "temperature", 0.7)))
-    top_k = getattr(gen, "top_k", 64)
-    top_p = getattr(gen, "top_p", 0.95)
-    rp = getattr(gen, "repetition_penalty", 1.0)
-    seed = os.environ.get("BENCH_SEED")
+    seed_env = os.environ.get("BENCH_SEED")
+    return {
+        "temperature": float(os.environ.get(
+            "BENCH_TEMP", getattr(gen, "temperature", 0.7))),
+        "top_k": getattr(gen, "top_k", 64),
+        "top_p": getattr(gen, "top_p", 0.95),
+        "repetition_penalty": getattr(gen, "repetition_penalty", 1.0),
+        "seed": int(seed_env) if seed_env is not None else None,
+    }
+
+
+def _headline_bytes(peaks: dict, measurement):
+    """The one per-run peak the human output and the legacy ``peak_gib``
+    show (allocated on CUDA, peak active on MLX); ``None`` when that
+    metric is unavailable."""
+    name = getattr(measurement, "headline", None)
+    metric = peaks.get(name) if name else None
+    if metric is None:
+        for candidate in peaks.values():
+            if candidate.get("bytes") is not None:
+                return candidate["bytes"]
+        return None
+    return metric.get("bytes")
+
+
+def _fmt_gib(value) -> str:
+    return "n/a" if value is None else f"{value:.2f} GiB"
+
+
+def run_bench(engine, ntok: int, warmup: int, *, measurement=None,
+              runs: int = 2) -> dict:
+    """Run the fixed-length sample-and-step benchmark.
+
+    Returns the legacy dict (``runs`` with prefill_s/decode_s/ntok/
+    peak_gib/tok_s, ``mean_tok_s``, ``peak_gib``) plus ``report_runs``
+    (validated ``benchmark_report.run_result`` entries), ``workload``,
+    ``measurement`` and ``execution_evidence`` for the JSON report.
+    ``measurement`` defaults to the adapter for the active backend and
+    its resolved device (``benchmark_measure.make_measurement``).
+    """
+    if not isinstance(ntok, int) or isinstance(ntok, bool) or ntok <= 0:
+        raise ValueError(
+            "ntok must be a positive integer: an empty timed window is not "
+            "a benchmark")
+    if not isinstance(warmup, int) or isinstance(warmup, bool) or warmup < 0:
+        raise ValueError("warmup must be an integer >= 0")
+    backend, core, sample = _framework()
+    if measurement is None:
+        measurement = measure.make_measurement(backend.name, core)
+
+    prompt = _prompt_for(engine)
+    ids = _encode_prompt(engine, prompt)
+    knobs = _sampling_knobs(engine)
+    temperature = knobs["temperature"]
+    top_k, top_p, rp, seed = (knobs["top_k"], knobs["top_p"],
+                              knobs["repetition_penalty"], knobs["seed"])
 
     results = []
-    for run in range(2):
+    report_runs = []
+    evidence = None
+    for run in range(runs):
         engine.reset()
-        core.reset_peak_memory()
+        # Finish any device work the reset queued, then reset the peak
+        # statistics right before prefill: the per-run peak covers
+        # prefill + warmup + decode (plus whatever is resident now).
+        measurement.synchronize()
+        measurement.reset_peak()
         t0 = time.perf_counter()
         engine.prefill(ids)
+        # Prefill's final device work belongs to prefill wall time.
+        measurement.synchronize()
         t_prefill = time.perf_counter() - t0
         logits = engine.next_logits()
+        if evidence is None:
+            evidence = measure.execution_evidence(logits)
         if seed is not None:
             core.random.seed(int(seed))
 
         history = list(ids)
-        # warmup: sampled, untimed (first tokens are dominated by expert
-        # cold-starts; the timed window is the steady state)
+        # warmup: GREEDY (argmax), untimed -- the first tokens are
+        # dominated by expert cold-starts; the timed window below is the
+        # steady state.  Only the timed loop samples.
+        warmup_done = 0
         for _ in range(warmup):
             tid = int(core.argmax(logits, axis=-1).item())
             history.append(tid)
             logits = engine.step(tid)
+            warmup_done += 1
+        # Warmup must be complete before the decode clock starts.
+        measurement.synchronize()
         out: list[int] = []
         t0 = time.perf_counter()
+        # timed: sample from the current logits, then one forward.  The
+        # last forward's logits are never sampled; no EOS stop.
         for _ in range(ntok):
             tid = sample(logits, temperature=temperature, top_k=top_k,
                          top_p=top_p, repetition_penalty=rp,
@@ -116,48 +258,542 @@ def run_bench(engine, ntok: int, warmup: int) -> dict:
             history.append(tid)
             out.append(tid)
             logits = engine.step(tid)
+        # The final timed step's device work is inside decode wall time.
+        measurement.synchronize()
         t_decode = time.perf_counter() - t0
-        peak_gib = core.get_peak_memory() / (1024 ** 3)
-        results.append(dict(prefill_s=t_prefill, decode_s=t_decode,
-                            ntok=len(out), peak_gib=peak_gib,
-                            tok_s=len(out) / t_decode if t_decode else 0.0))
+        peaks = measurement.peak_metrics()  # after the synchronized decode
+        report_runs.append(report.run_result(
+            index=run, prompt_tokens=len(ids),
+            requested_warmup_tokens=warmup, warmup_tokens=warmup_done,
+            requested_timed_tokens=ntok, timed_decode_tokens=len(out),
+            prefill_seconds=t_prefill, decode_seconds=t_decode,
+            memory=peaks, execution_evidence=evidence))
+        peak_bytes = _headline_bytes(peaks, measurement)
+        peak_gib = (peak_bytes / (1024 ** 3)) if peak_bytes is not None else None
+        results.append({"prefill_s": t_prefill, "decode_s": t_decode,
+                        "ntok": len(out), "peak_gib": peak_gib,
+                        "tok_s": len(out) / t_decode if t_decode else 0.0})
         pf_tps = (len(ids) / t_prefill) if t_prefill else 0.0
         print(f"prompt={len(ids)} tok  prefill={t_prefill:.2f}s "
               f"({pf_tps:.0f} tok/s)  "
               f"decode={len(out)}/{t_decode:.2f}s  "
               f"tok/s={results[-1]['tok_s']:.1f}  "
-              f"peak_active={peak_gib:.2f} GiB", flush=True)
+              f"peak_active={_fmt_gib(peak_gib)}", flush=True)
     mean_ts = sum(r["tok_s"] for r in results) / len(results)
-    max_peak = max(r["peak_gib"] for r in results)
-    print(f"[bench] mean tok/s={mean_ts:.1f}  peak_active<={max_peak:.2f} GiB",
-          flush=True)
-    return {"runs": results, "mean_tok_s": mean_ts, "peak_gib": max_peak}
+    max_peak = max((r["peak_gib"] for r in results
+                    if r["peak_gib"] is not None), default=None)
+    print(f"[bench] mean tok/s={mean_ts:.1f}  "
+          f"peak_active<={_fmt_gib(max_peak)}", flush=True)
+    workload = {
+        "prompt_source": _prompt_source(),
+        "prompt_sha256": hashlib.sha256(prompt.encode("utf-8")).hexdigest(),
+        "prompt_token_ids_sha256": hashlib.sha256(
+            ",".join(str(t) for t in ids).encode()).hexdigest(),
+        "prompt_chars": len(prompt),
+        "prompt_text": prompt,
+        "prompt_tokens": len(ids),
+        "requested_warmup_tokens": warmup,
+        "requested_timed_tokens": ntok,
+        **knobs,
+    }
+    return {"runs": results, "mean_tok_s": mean_ts, "peak_gib": max_peak,
+            "report_runs": report_runs, "workload": workload,
+            "measurement": measurement.describe(),
+            "execution_evidence": evidence}
 
 
-def main() -> int:
-    ap = argparse.ArgumentParser(description=__doc__)
-    ap.add_argument("model", help="checkpoint dir or tier name")
-    ap.add_argument("--ntok", type=int,
-                    default=int(os.environ.get("BENCH_NTOK", "200")))
-    ap.add_argument("--warmup", type=int, default=10)
-    args = ap.parse_args()
-    # tier name -> checkpoint dir via $EDGE0_<TIER>_MODEL (cli parity)
-    model = args.model
-    name = None
+# ---- report assembly (outside every timed interval) ---------------------------
+
+
+def _jsonable(value) -> Any:
+    """Config objects -> JSON: enums by name, paths as strings, tuples as
+    lists, dataclasses as dicts, anything else by repr."""
+    if isinstance(value, bool) or value is None or isinstance(
+            value, (str, int, float)):
+        return value
+    if isinstance(value, enum.Enum):
+        return value.name
+    if isinstance(value, dict):
+        return {str(k): _jsonable(v) for k, v in value.items()}
+    if isinstance(value, (list, tuple, set, frozenset)):
+        return [_jsonable(v) for v in value]
+    if isinstance(value, os.PathLike):
+        return os.fspath(value)
+    if dataclasses.is_dataclass(value) and not isinstance(value, type):
+        return _jsonable(dataclasses.asdict(value))
+    return repr(value)
+
+
+def _with_reasons(obj: dict, reason: str) -> dict:
+    """Give a plain mapping the schema's null convention: every ``None``
+    value gets ``reason`` in ``unavailable_reasons``."""
+    out = dict(obj)
+    reasons = dict(out.get("unavailable_reasons") or {})
+    for key, value in out.items():
+        if key != "unavailable_reasons" and value is None:
+            reasons.setdefault(key, reason)
+    out["unavailable_reasons"] = reasons
+    return out
+
+
+def _env_snapshot() -> dict:
+    """The requested environment knobs, taken BEFORE the engine is built."""
+    return {k: os.environ[k] for k in ENV_KNOBS if k in os.environ}
+
+
+def _model_env() -> dict:
+    """Model-read knobs as the bailing_hybrid code parses them, resolved
+    AFTER the engine is built (``engine/ling.py`` fills in a default
+    ``LING_HIDDEN_CLIP``).  They change numerics and per-token work, so
+    before/after comparisons must hold them equal."""
+    out: dict[str, Any] = {
+        "ling_hidden_clip": None,
+        "prerouter_feature_topk": os.environ.get("PREROUTER_FEATURE_TOPK",
+                                                 "teacher"),
+        "prerouter_intra": os.environ.get("PREROUTER_INTRA", "0") == "1",
+        "note": ("parsed exactly as the bailing_hybrid model code does; "
+                 "ling_hidden_clip 0.0 means the hidden-state clip is off"),
+        "unavailable_reasons": {},
+    }
+    raw = os.environ.get("LING_HIDDEN_CLIP", "0")
+    try:
+        out["ling_hidden_clip"] = float(raw)
+    except ValueError:
+        out["unavailable_reasons"]["ling_hidden_clip"] = (
+            f"LING_HIDDEN_CLIP={raw!r} is not a number")
+    return out
+
+
+def _model_group(engine, model_dir: str) -> dict:
+    root = Path(model_dir)
+    manifest = measure.checkpoint_manifest(root)
+    config = manifest["config"]
+    cfg = engine.cfg
+    prerouter = getattr(cfg, "prerouter", None)
+    adapters = {
+        "lora": measure.adapter_identity(getattr(cfg, "lora", None), root),
+        "prerouter": measure.adapter_identity(
+            getattr(prerouter, "weights_file", None), root),
+        "lora_settings": _with_reasons(_jsonable({
+            "r": getattr(cfg, "lora_r", None),
+            "alpha": getattr(cfg, "lora_alpha", None)}),
+            "tier config has no LoRA settings"),
+        "prerouter_settings": _with_reasons(_jsonable({
+            "start_layer": getattr(prerouter, "start_layer", None),
+            "hidden": getattr(prerouter, "hidden", None),
+            "dtype": getattr(prerouter, "dtype", None),
+            "feature_topk": getattr(prerouter, "feature_topk", None),
+            "owners": getattr(prerouter, "owners", None),
+            "top_k": getattr(cfg, "prerouter_top_k", None)}),
+            "tier config has no prerouter"),
+    }
+    small = manifest["small_file_sha256"]
+    tokenizer_files = []
+    for entry in manifest["manifest"].get("files") or []:
+        name = entry["path"]
+        if not name.startswith(_TOKENIZER_FILE_PREFIXES):
+            continue
+        item = {"name": name, "size_bytes": entry["size_bytes"],
+                "sha256": small.get(name), "unavailable_reasons": {}}
+        if item["sha256"] is None:
+            item["unavailable_reasons"]["sha256"] = (
+                "not hashed: larger than the small-file cap or unreadable")
+        tokenizer_files.append(item)
+    group = {
+        "checkpoint_path": str(root.resolve()),
+        "tier": engine.name,
+        "model_type": config.get("model_type") or None,
+        "architectures": _jsonable(config.get("architectures") or []),
+        "config_sha256": manifest["config_sha256"],
+        "manifest": manifest["manifest"],
+        "small_file_sha256": small,
+        "safetensors_headers": manifest["safetensors_headers"],
+        "adapters": adapters,
+        "tokenizer_files": tokenizer_files,
+        "unavailable_reasons": {},
+    }
+    if group["model_type"] is None:
+        group["unavailable_reasons"]["model_type"] = (
+            "config.json missing or has no model_type")
+    if group["config_sha256"] is None:
+        group["unavailable_reasons"]["config_sha256"] = (
+            "config.json not found in the checkpoint directory")
+    return group
+
+
+def _runtime_group(bench: dict, backend) -> dict:
+    info = measure.runtime_info(backend.name)
+    try:
+        version = str(backend.version)
+    except Exception as exc:  # noqa: BLE001 - never fail the report here
+        version = None
+        info["unavailable_reasons"]["backend_version"] = (
+            f"backend.version failed: {type(exc).__name__}: {exc}")
+    return {
+        "backend": backend.name,
+        "backend_version": version,
+        "resolved_device": bench["measurement"]["resolved_device"],
+        "measurement": bench["measurement"],
+        "execution_evidence": bench["execution_evidence"],
+        "power_mode": measure.power_mode(),
+        **info,
+    }
+
+
+def _quant_paths_group(engine) -> dict:
+    """Resolved state of the torch backend's opt-in quantized paths
+    (Task 6): the batched expert gather, the capped exact weight cache
+    and the int4 kernel, with the bytes each one added."""
+    from edge0.backends.cuda import int4pack as i4
+    from edge0.backends.cuda import nn as cuda_nn
+    from edge0.backends.cuda import quant as cq
+    repacked = 0
+    extra = 0
+    filled = 0
+    filled_bytes = 0
+    reasons: dict[str, str] = {}
+    model = getattr(engine, "model", None)
+    if model is None or not hasattr(model, "modules"):
+        reasons["repacked_modules"] = "engine exposes no torch model"
+        reasons["extra_bytes"] = "engine exposes no torch model"
+        repacked = extra = None
+        filled = filled_bytes = None
+    else:
+        for module in model.modules():
+            n = getattr(module, "int4pack_bytes", None)
+            if callable(n):
+                b = n()
+                if b:
+                    repacked += 1
+                    extra += b
+            if getattr(module, "_dequantized", None) is not None:
+                filled += 1
+                filled_bytes += cuda_nn.dequantized_bytes(module)
+    policy = dict(cuda_nn.WEIGHT_CACHE.summary())
+    # Admission is deliberately conservative: a module is admitted on the
+    # assumption it will be used at the priced dtype, but the cache only
+    # fills when the activation itemsize matches.  Report what is actually
+    # resident next to what was reserved, so the two are never confused.
+    policy["filled_modules"] = filled
+    policy["filled_bytes"] = filled_bytes
+    policy = _with_reasons(policy, "weight cache policy off or not finalized")
+    return {
+        "batched_gather": {"enabled": bool(cq.BATCHED),
+                           "max_transient_bytes": int(cq.BATCHED_MAX_BYTES)},
+        "weight_cache_policy": policy,
+        "int4pack": {"enabled": bool(i4.INT4PACK),
+                     "repacked_modules": repacked,
+                     "extra_bytes": extra,
+                     "unavailable_reasons": reasons},
+    }
+
+
+def _caches_group(engine, backend) -> dict:
+    opts = getattr(engine.cfg, "options", None)
+    reasons: dict[str, str] = {}
+    if dataclasses.is_dataclass(opts) and not isinstance(opts, type):
+        layer_options = _with_reasons(
+            _jsonable(dataclasses.asdict(opts)),
+            "option unset (None): the model config value applies")
+    else:
+        layer_options = {"unavailable_reasons": {}}
+        reasons["layer_options"] = "engine config has no LayerOptions"
+    layers = getattr(engine, "_all_stream_layers", {}) or {}
+    first = next(iter(layers.values()), None)
+    shared_slots = prefetch_cap = None
+    if first is None:
+        reasons["shared_cache_slots_resolved"] = (
+            "engine has no streaming layers")
+        reasons["prefetch_cap_resolved"] = "engine has no streaming layers"
+    else:
+        shared_slots = getattr(getattr(first, "shared_cache", None),
+                               "slots", None)
+        prefetch_cap = getattr(getattr(first, "_prefetch_buf", None),
+                               "cap", None)
+        if shared_slots is None:
+            reasons["shared_cache_slots_resolved"] = (
+                "streaming layer exposes no shared_cache.slots")
+        if prefetch_cap is None:
+            reasons["prefetch_cap_resolved"] = (
+                "streaming layer exposes no _prefetch_buf.cap")
+    threads: dict[str, Any] = {
+        "load_threads": getattr(opts, "load_threads", None),
+        "prefetch_threads": getattr(opts, "prefetch_threads", None),
+        "torch_num_threads": None}
+    thread_reasons = {}
+    weight_cache = None
+    mlx_cache_limit = None
+    quant_paths = None
+    if backend.name == "cuda":
+        from edge0.backends.cuda import nn as cuda_nn
+        weight_cache = bool(getattr(cuda_nn, "CACHE_DEQUANTIZED", False))
+        quant_paths = _quant_paths_group(engine)
+        try:
+            import torch
+            threads["torch_num_threads"] = int(torch.get_num_threads())
+        except Exception as exc:  # noqa: BLE001 - reported, not raised
+            thread_reasons["torch_num_threads"] = f"{type(exc).__name__}: {exc}"
+        reasons["mlx_cache_limit_bytes"] = "backend is cuda"
+    else:
+        reasons["weight_cache"] = (
+            "EDGE0_TORCH_WEIGHT_CACHE applies to the torch backend only")
+        reasons["quant_paths"] = (
+            "the opt-in quantized paths exist in the torch backend only")
+        thread_reasons["torch_num_threads"] = "backend is not torch"
+        try:
+            mlx_cache_limit = int(
+                os.environ.get("MLX_CACHE_LIMIT_MB", "256")) * 1024 * 1024
+        except ValueError:
+            reasons["mlx_cache_limit_bytes"] = "MLX_CACHE_LIMIT_MB not an int"
+    for key in ("load_threads", "prefetch_threads"):
+        if threads[key] is None:
+            thread_reasons[key] = "engine config has no LayerOptions"
+    threads["unavailable_reasons"] = thread_reasons
+    prewarm = os.environ.get(
+        "EDGE0_PREWARM", os.environ.get("LING_PREWARM", "0")) == "1"
+    try:
+        stats = _jsonable(engine.stats())
+    except Exception as exc:  # noqa: BLE001 - diagnostics only
+        stats = {"stats": None, "unavailable_reasons": {
+            "stats": f"{type(exc).__name__}: {exc}"}}
+    resolved_budget = getattr(engine, "memory_budget", None)
+    if resolved_budget is None:
+        reasons["memory_budget"] = (
+            "no memory budget resolved (EDGE0_MEMORY_BUDGET off or "
+            "engine predates Task 4)")
+    return {
+        "layer_options": layer_options,
+        "shared_cache_slots_resolved": shared_slots,
+        "prefetch_cap_resolved": prefetch_cap,
+        "memory_budget": (resolved_budget.as_dict()
+                          if resolved_budget is not None else None),
+        "weight_cache": weight_cache,
+        "quant_paths": quant_paths,
+        "prewarm": prewarm,
+        "threads": threads,
+        "mlx_cache_limit_bytes": mlx_cache_limit,
+        "streaming_stats_after_runs": stats,
+        "unavailable_reasons": reasons,
+    }
+
+
+def _build_report(engine, bench: dict, args, argv: list[str],
+                  started_utc: str, model_dir: str, probe, sampler,
+                  env_knobs: dict, model_env: dict, backend) -> dict:
+    """Assemble the JSON report.  Called after the timed runs (and after
+    the sampler stopped): hashing, git and power queries happen here."""
+    requested = {
+        "model": args.model,
+        "ntok": args.ntok,
+        "warmup": args.warmup,
+        "rss_sample_interval_seconds": args.rss_sample_interval,
+        "json_output": args.json_output,
+        "probe_json": args.probe_json,
+    }
+    identity = {
+        "timestamp_utc": started_utc,
+        "finished_utc": datetime.now(timezone.utc).isoformat(),
+        "git": measure.git_identity(REPO_ROOT),
+        "run_count": len(bench["report_runs"]),
+        "command": {"argv": list(argv), "env_knobs": dict(env_knobs)},
+        "requested": _with_reasons(requested, "not requested"),
+        "unavailable_reasons": {},
+    }
+    workload = dict(bench["workload"])
+    workload["prefill_chunk"] = getattr(engine, "prefill_chunk", None)
+    workload["think"] = getattr(engine, "think", None)
+    workload["model_env"] = model_env
+    workload = _with_reasons(workload, "not set")
+    if workload["seed"] is None:
+        workload["unavailable_reasons"]["seed"] = (
+            "BENCH_SEED not set: sampling is unseeded")
+    memory = {
+        "process_peak_rss": measure.process_peak_rss(),
+        **sampler.metrics(),
+        "notes": [
+            ("process RSS and device allocator peaks are separate views of "
+             "the same shared DRAM on Jetson; never add them"),
+            ("RSS includes resident file-backed pages of the mmap'd "
+             "checkpoint; the sampled *_rss_anon peak is the anonymous "
+             "footprint (Linux only)"),
+            ("allocator peaks cover the framework allocator only, not the "
+             "CUDA context, driver or non-torch memory"),
+            ("cuda_peak_reserved's floor is every segment cached at the "
+             "reset, so run 0 and run 1 are expected to be close; use "
+             "cuda_peak_allocated for per-run activity"),
+            ("process_peak_rss is a lifetime high-water mark (model load "
+             "included); per-run peaks are the backend metrics in runs[]"),
+        ],
+        "unavailable_reasons": {},
+    }
+    return report.build_report(
+        identity=identity,
+        model=_model_group(engine, model_dir),
+        runtime=_runtime_group(bench, backend),
+        workload=workload,
+        caches=_caches_group(engine, backend),
+        runs=bench["report_runs"],
+        memory=memory,
+        probe=probe,
+    )
+
+
+# ---- CLI ---------------------------------------------------------------------
+
+
+def _build_engine(model_dir: str, name):
+    from edge0 import AutoEngine
+    return AutoEngine.from_pretrained(model_dir, name=name)
+
+
+#: Copy of ``edge0.cli.TIER_ENV`` so tier resolution needs no backend
+#: import (``edge0.cli`` loads the model registry, which loads the
+#: backend).  ``tests/test_bench_backend.py::test_tier_env_matches_the_cli``
+#: keeps the two in sync.
+_TIER_ENV = {
+    "edge0-35b": "EDGE0_35B_MODEL",
+    "edge0-8b": "EDGE0_8B_MODEL",
+}
+
+
+def _resolve_model(model: str) -> tuple[str, str | None]:
+    """tier name -> checkpoint dir via $EDGE0_<TIER>_MODEL (cli parity)."""
     if model.startswith("edge0-"):
-        from edge0.cli import TIER_ENV
-        env = os.environ.get(TIER_ENV.get(model, ""))
+        env_name = _TIER_ENV.get(model)
+        if env_name is None:
+            raise SystemExit(
+                f"unknown tier {model!r}; known tiers: "
+                f"{', '.join(sorted(_TIER_ENV))} (or pass the checkpoint "
+                f"directory itself)")
+        env = os.environ.get(env_name)
         if not env:
             raise SystemExit(
-                f"set {TIER_ENV.get(model, 'EDGE0_<TIER>_MODEL')} to the "
-                f"checkpoint directory for {model}, or pass the dir itself")
-        model = env
-    engine = AutoEngine.from_pretrained(model, name=name)
-    print(f"[bench] tier={engine.name} ntok={args.ntok} warmup={args.warmup}",
-          flush=True)
-    run_bench(engine, args.ntok, args.warmup)
-    engine.close()
-    return 0
+                f"set {env_name} to the checkpoint directory for {model}, "
+                f"or pass the dir itself")
+        return env, None
+    return model, None
+
+
+def _prepare_output(path: str) -> str:
+    """Refuse an existing destination and make its directory exist, both
+    before the model loads."""
+    dest = Path(path).expanduser()
+    if dest.exists() or dest.is_symlink():
+        raise FileExistsError(
+            f"--json-output {dest} already exists; choose a new path so a "
+            f"stale report is never mistaken for this run")
+    dest.parent.mkdir(parents=True, exist_ok=True)
+    return str(dest.resolve())
+
+
+def _load_probe(path: str) -> dict:
+    """Read and validate an explicitly requested probe before inference."""
+    return report.probe_link(path=path, text=Path(path).read_bytes())
+
+
+def _parse_args(ap: argparse.ArgumentParser, argv: list[str]):
+    args = ap.parse_args(argv)
+    if args.ntok is None:
+        raw = os.environ.get("BENCH_NTOK", "200")
+        try:
+            args.ntok = int(raw)
+        except ValueError:
+            ap.error(f"BENCH_NTOK must be an integer, got {raw!r}")
+    if args.ntok <= 0:
+        ap.error("--ntok (or BENCH_NTOK) must be > 0: an empty timed window "
+                 "is not a benchmark")
+    if args.warmup < 0:
+        ap.error("--warmup must be >= 0")
+    if not (0 <= args.rss_sample_interval < math.inf):
+        ap.error("--rss-sample-interval must be a finite number >= 0")
+    if args.json_output is not None and not args.json_output.strip():
+        ap.error("--json-output needs a path")
+    if args.probe_json is not None and not args.probe_json.strip():
+        ap.error("--probe-json needs a path")
+    seed = os.environ.get("BENCH_SEED")
+    if seed is not None:
+        try:
+            int(seed)
+        except ValueError:
+            ap.error(f"BENCH_SEED must be an integer, got {seed!r}")
+    temp = os.environ.get("BENCH_TEMP")
+    if temp is not None:
+        try:
+            value = float(temp)
+        except ValueError:
+            ap.error(f"BENCH_TEMP must be a number, got {temp!r}")
+        else:
+            if not math.isfinite(value):
+                ap.error(f"BENCH_TEMP must be finite, got {temp!r}")
+    return args
+
+
+def main(argv: list[str] | None = None) -> int:
+    ap = argparse.ArgumentParser(
+        description=__doc__,
+        formatter_class=argparse.RawDescriptionHelpFormatter)
+    ap.add_argument("model", help="checkpoint dir or tier name")
+    ap.add_argument("--ntok", type=int, default=None,
+                    help="timed decode tokens per run (> 0; default "
+                         "$BENCH_NTOK or 200)")
+    ap.add_argument("--warmup", type=int, default=10,
+                    help="untimed greedy warmup steps per run (>= 0)")
+    ap.add_argument("--json-output", metavar="PATH",
+                    help="write the machine-readable report to this NEW file")
+    ap.add_argument("--probe-json", metavar="PATH",
+                    help="link an existing scripts/jetson_probe.py report")
+    ap.add_argument("--rss-sample-interval", type=float, default=0.25,
+                    metavar="SECONDS",
+                    help="process memory sampling interval (0 disables)")
+    argv = list(sys.argv[1:] if argv is None else argv)
+    args = _parse_args(ap, argv)
+
+    started_utc = datetime.now(timezone.utc).isoformat()
+    model_dir, name = _resolve_model(args.model)
+    # Everything that can be rejected is rejected before the model loads.
+    try:
+        json_output = (_prepare_output(args.json_output)
+                       if args.json_output is not None else None)
+        probe = (_load_probe(args.probe_json)
+                 if args.probe_json is not None else None)
+    except (OSError, ValueError) as exc:
+        ap.exit(2, f"[bench] error: {exc}\n")
+    env_knobs = _env_snapshot()  # before the engine can touch the environment
+
+    sampler = measure.RssSampler(args.rss_sample_interval)
+    engine = None
+    stage = "engine build"
+    try:
+        sampler.start()  # before the model loads: load transients are sampled
+        engine = _build_engine(model_dir, name)
+        model_env = _model_env()  # resolved after the build, before the runs
+        print(f"[bench] tier={engine.name} ntok={args.ntok} "
+              f"warmup={args.warmup}", flush=True)
+        stage = "benchmark"
+        bench = run_bench(engine, args.ntok, args.warmup)
+        if json_output is not None:
+            stage = "report"
+            sampler.stop()
+            backend = _framework()[0]
+            doc = _build_report(engine, bench, args, argv, started_utc,
+                                model_dir, probe, sampler, env_knobs,
+                                model_env, backend)
+            stage = "write"
+            report.write_report(doc, json_output)
+            stage = "output after a successful write"
+            print(f"[bench] wrote {json_output}", flush=True)
+        return 0
+    except Exception as exc:  # noqa: BLE001 - reported with its stage
+        traceback.print_exc()
+        print(f"[bench] FAILED during {stage}: {type(exc).__name__}: {exc}",
+              file=sys.stderr, flush=True)
+        return 1
+    finally:
+        try:
+            sampler.stop()
+        finally:
+            if engine is not None:
+                engine.close()
 
 
 if __name__ == "__main__":
diff --git a/examples/benchmark_measure.py b/examples/benchmark_measure.py
new file mode 100644
index 0000000..463cb64
--- /dev/null
+++ b/examples/benchmark_measure.py
@@ -0,0 +1,842 @@
+"""Benchmark-owned measurement: backend peaks, process memory, run identity.
+
+``examples/bench.py`` is the only consumer.  Everything that touches a
+backend (``torch.cuda``, ``mlx.core``), the process (``psutil``,
+``resource``, ``/proc``) or the machine (``git``, ``nvpmodel``) lives
+here, behind lazy imports and injectable hooks so the dispatch logic is
+unit-tested on a host with neither CUDA nor MLX.  Nothing here runs
+inside a timed interval except the explicit ``synchronize`` /
+``reset_peak`` / ``peak_metrics`` calls the benchmark makes at phase
+boundaries.
+
+The pure report builder (``benchmark_report``) only sees the dicts these
+functions return.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import importlib
+import json
+import os
+import platform
+import re
+import struct
+import subprocess
+import threading
+from pathlib import Path
+from typing import Any
+
+try:  # imported as ``examples.benchmark_measure`` (tests)
+    from examples import benchmark_report as _report
+except ImportError:  # run next to bench.py as a script
+    import benchmark_report as _report  # type: ignore[no-redef]
+
+memory_metric = _report.memory_metric
+
+_AUTO = object()
+
+#: What a per-run backend peak covers.  The reset happens immediately
+#: before prefill, the read after the synchronized final decode step.
+RUN_PEAK_SCOPE = (
+    "one benchmark run: statistics reset immediately before prefill and "
+    "read after the synchronized final decode step; covers prefill, "
+    "warmup and decode and includes allocations already resident at the "
+    "reset; an earlier initialization transient is not recovered")
+
+_CUDA_ALLOCATED_SCOPE = (
+    RUN_PEAK_SCOPE + "; torch caching allocator only, not driver, context "
+    "or non-torch memory")
+
+#: ``max_memory_reserved`` is not reset to zero by
+#: ``reset_peak_memory_stats``: its floor is every segment the allocator
+#: already holds, so it is close to a lifetime figure.
+CUDA_RESERVED_SCOPE = (
+    "one benchmark run: statistics reset immediately before prefill and "
+    "read after the synchronized final decode step; peak of the segments "
+    "held by the torch caching allocator, whose floor is every segment "
+    "already cached at the reset (model load, earlier runs, any earlier "
+    "initialization transient) because the allocator does not release "
+    "segments between runs; not driver, context or non-torch memory")
+
+
+def _bytes(value):
+    """Integer bytes from a backend counter; floats that are whole numbers
+    are accepted, anything else is left for ``memory_metric`` to reject."""
+    if isinstance(value, float) and value.is_integer():
+        return int(value)
+    return value
+
+
+# ---- backend measurement adapters --------------------------------------------
+
+
+class NullMeasurement:
+    """No backend peak available (torch on cpu/mps, unknown backend)."""
+
+    kind = "null"
+    headline = "backend_peak"
+
+    def __init__(self, backend: str, device: str, reason: str):
+        self.backend = backend
+        self.device = device
+        self.reason = reason
+
+    def synchronize(self) -> None:
+        return None
+
+    def reset_peak(self) -> None:
+        return None
+
+    def peak_metrics(self) -> dict:
+        return {self.headline: memory_metric(
+            None, method="none", scope=RUN_PEAK_SCOPE,
+            unavailable_reason=self.reason)}
+
+    def describe(self) -> dict:
+        sync = "none: the benchmark synchronizes only an actual CUDA device"
+        if str(self.device).startswith("mps"):
+            sync += ("; mps execution is asynchronous, so prefill/decode wall "
+                     "times may exclude the final step's in-flight device work")
+        return {"kind": self.kind, "backend": self.backend,
+                "resolved_device": self.device,
+                "synchronization": sync,
+                "peak_source": f"none: {self.reason}",
+                "headline_peak": self.headline}
+
+
+class MlxMeasurement:
+    """The pre-existing MLX behavior: ``reset_peak_memory`` before
+    prefill, ``get_peak_memory`` after decode, no added synchronization
+    (the engine's ``core.eval(logits)`` already materializes every step,
+    so the wall time is unchanged from the original benchmark)."""
+
+    kind = "mlx"
+    headline = "mlx_peak_active"
+
+    def __init__(self, core):
+        self._core = core
+
+    def synchronize(self) -> None:
+        return None
+
+    def reset_peak(self) -> None:
+        self._core.reset_peak_memory()
+
+    def peak_metrics(self) -> dict:
+        return {self.headline: memory_metric(
+            _bytes(self._core.get_peak_memory()),
+            method="mlx.core.get_peak_memory", scope=RUN_PEAK_SCOPE)}
+
+    def describe(self) -> dict:
+        default = getattr(self._core, "default_device", None)
+        try:
+            device = str(default()) if callable(default) else "mlx default"
+        except Exception as exc:  # noqa: BLE001 - never fail a report here
+            device = f"mlx default (query failed: {type(exc).__name__})"
+        return {"kind": self.kind, "backend": "mlx",
+                "resolved_device": device,
+                "synchronization": (
+                    "none added: MLX evaluation is forced by the engine "
+                    "(core.eval) at every step; timing behavior unchanged"),
+                "peak_source": "mlx.core.get_peak_memory (reset before prefill)",
+                "headline_peak": self.headline}
+
+
+class CudaMeasurement:
+    """Torch on an actual CUDA device: synchronize the resolved device at
+    phase boundaries and read the caching-allocator peaks.  The headline
+    (human output, legacy ``peak_gib``) is ``max_memory_allocated``, the
+    analogue of MLX's peak active memory; ``max_memory_reserved`` is
+    JSON-only."""
+
+    kind = "cuda"
+    headline = "cuda_peak_allocated"
+
+    def __init__(self, device, cuda_api):
+        self.device = device
+        self._cuda = cuda_api
+        self._at_reset: dict[str, Any] = {}
+
+    def synchronize(self) -> None:
+        self._cuda.synchronize(self.device)
+
+    def reset_peak(self) -> None:
+        self._cuda.reset_peak_memory_stats(self.device)
+        # What is resident right now is the floor of both peaks; record it
+        # (attribute reads, before the prefill clock starts).
+        self._at_reset = {}
+        for key, name in (("allocated_at_reset", "memory_allocated"),
+                          ("reserved_at_reset", "memory_reserved")):
+            reader = getattr(self._cuda, name, None)
+            if callable(reader):
+                self._at_reset[key] = _bytes(reader(self.device))
+
+    def peak_metrics(self) -> dict:
+        allocated = _bytes(self._cuda.max_memory_allocated(self.device))
+        reserved = _bytes(self._cuda.max_memory_reserved(self.device))
+        alloc_details = {k: v for k, v in self._at_reset.items()
+                         if k == "allocated_at_reset"}
+        res_details = {k: v for k, v in self._at_reset.items()
+                       if k == "reserved_at_reset"}
+        return {
+            "cuda_peak_allocated": memory_metric(
+                allocated, method="torch.cuda.max_memory_allocated",
+                scope=_CUDA_ALLOCATED_SCOPE, **alloc_details),
+            "cuda_peak_reserved": memory_metric(
+                reserved, method="torch.cuda.max_memory_reserved",
+                scope=CUDA_RESERVED_SCOPE, **res_details),
+        }
+
+    def describe(self) -> dict:
+        return {"kind": self.kind, "backend": "cuda",
+                "resolved_device": str(self.device),
+                "synchronization": (
+                    "torch.cuda.synchronize(device) after engine reset, "
+                    "at the end of prefill, at the end of warmup and after "
+                    "the final timed decode step; no per-token syncs"),
+                "peak_source": (
+                    "torch.cuda caching allocator statistics, "
+                    "reset_peak_memory_stats before prefill"),
+                "headline_peak": self.headline}
+
+
+def _torch_cuda():
+    import torch
+    return torch.cuda
+
+
+def make_measurement(backend_name: str, core_module, *, cuda_api=None):
+    """Pick the adapter for the ACTIVE backend and its RESOLVED device.
+
+    ``EDGE0_BACKEND=cuda`` alone does not prove the device is CUDA: the
+    torch backend runs on cpu/mps when ``EDGE0_TORCH_DEVICE`` says so or
+    when no CUDA device exists, and then allocator peaks are simply
+    unavailable.  ``resolved_device`` and the unavailable reason are both
+    derived from the same ``core_module.DEVICE`` object.
+    """
+    if backend_name == "mlx":
+        if (callable(getattr(core_module, "reset_peak_memory", None))
+                and callable(getattr(core_module, "get_peak_memory", None))):
+            return MlxMeasurement(core_module)
+        return NullMeasurement(
+            "mlx", "mlx default",
+            "mlx core namespace has no reset_peak_memory/get_peak_memory; "
+            "peak memory unavailable")
+    if backend_name == "cuda":
+        device = getattr(core_module, "DEVICE", None)
+        if device is None:
+            return NullMeasurement(
+                "cuda", "unknown",
+                "torch core namespace has no DEVICE; resolved device unknown")
+        dev_type = getattr(device, "type", str(device))
+        if dev_type == "cuda":
+            return CudaMeasurement(device, cuda_api or _torch_cuda())
+        return NullMeasurement(
+            "cuda", str(device),
+            f"torch device is {dev_type}, not cuda: torch allocator peaks "
+            f"are unavailable")
+    return NullMeasurement(
+        backend_name, "unknown",
+        f"backend {backend_name!r} exposes no peak-memory interface")
+
+
+def execution_evidence(logits) -> dict:
+    """What the engine actually produced: the array class and, when the
+    class carries one, its device (an attribute read, no sync)."""
+    cls = type(logits)
+    array_type = f"{cls.__module__}.{cls.__name__}"
+    evidence: dict[str, Any] = {"array_type": array_type, "device": None,
+                                "unavailable_reasons": {}}
+    device = getattr(logits, "device", None)
+    if device is None:
+        evidence["unavailable_reasons"]["device"] = (
+            f"{array_type} carries no device attribute (MLX arrays are "
+            f"device-agnostic); see runtime.measurement.resolved_device")
+    else:
+        evidence["device"] = str(device)
+    return evidence
+
+
+# ---- process memory --------------------------------------------------------------
+
+
+_RSS_COMPOSITION = (
+    "resident set size = anonymous memory plus resident file-backed pages "
+    "(the mmap'd checkpoint: prod_k8 whole-layer prefill touches every "
+    "expert of model.safetensors each run, and those pages are reclaimable "
+    "page cache), so it is not the process's anonymous footprint and not "
+    "comparable to the 'peak anonymous memory' figure in docs/nvidia.md; "
+    "must not be added to device allocator peaks")
+
+_RSS_LIFETIME_SCOPE = (
+    "process lifetime high-water mark of " + _RSS_COMPOSITION
+    + "; includes model load and every run; cannot be reset per run")
+
+
+def _rusage_self():
+    try:
+        import resource
+        return getattr(resource, "RUSAGE_SELF", 0)
+    except ImportError:
+        return 0
+
+
+def process_peak_rss(*, system=None, getrusage: Any = _AUTO,
+                     psutil_module: Any = _AUTO) -> dict:
+    """Process-lifetime peak RSS with a platform-specific method and unit
+    normalization to bytes."""
+    system = system or platform.system()
+    if getrusage is _AUTO:
+        try:
+            import resource
+            getrusage = getattr(resource, "getrusage", None)
+        except ImportError:
+            getrusage = None
+    if psutil_module is _AUTO:
+        try:
+            import psutil as psutil_module
+        except ImportError:
+            psutil_module = None
+
+    if system == "Linux":
+        if getrusage is None:
+            return memory_metric(None, method="none",
+                                 scope=_RSS_LIFETIME_SCOPE,
+                                 unavailable_reason="resource module unavailable")
+        return memory_metric(
+            int(getrusage(_rusage_self()).ru_maxrss) * 1024,
+            method="resource.getrusage(RUSAGE_SELF).ru_maxrss (KiB x 1024)",
+            scope=_RSS_LIFETIME_SCOPE)
+    if system == "Darwin":
+        if getrusage is None:
+            return memory_metric(None, method="none",
+                                 scope=_RSS_LIFETIME_SCOPE,
+                                 unavailable_reason="resource module unavailable")
+        return memory_metric(
+            int(getrusage(_rusage_self()).ru_maxrss),
+            method="resource.getrusage(RUSAGE_SELF).ru_maxrss (bytes)",
+            scope=_RSS_LIFETIME_SCOPE)
+    if system == "Windows":
+        if psutil_module is None:
+            return memory_metric(None, method="none",
+                                 scope=_RSS_LIFETIME_SCOPE,
+                                 unavailable_reason="psutil unavailable")
+        return memory_metric(
+            int(psutil_module.Process().memory_info().peak_wset),
+            method="psutil.Process().memory_info().peak_wset",
+            scope=_RSS_LIFETIME_SCOPE)
+    return memory_metric(
+        None, method="none", scope=_RSS_LIFETIME_SCOPE,
+        unavailable_reason=f"no process peak RSS method for platform {system!r}")
+
+
+_PROC_STATUS_FIELDS = (("VmRSS", "rss"), ("RssAnon", "rss_anon"),
+                       ("RssFile", "rss_file"), ("VmSwap", "swap"))
+
+
+def parse_proc_status(text: str) -> dict:
+    """``/proc/self/status`` -> bytes for rss / rss_anon / rss_file / swap
+    (``None`` where the kernel does not report a field)."""
+    values: dict[str, int | None] = {key: None for _, key in _PROC_STATUS_FIELDS}
+    wanted = dict(_PROC_STATUS_FIELDS)
+    for line in text.splitlines():
+        name, sep, rest = line.partition(":")
+        if not sep or name not in wanted:
+            continue
+        parts = rest.split()
+        if not parts:
+            continue
+        try:
+            number = int(parts[0])
+        except ValueError:
+            continue
+        unit = parts[1].lower() if len(parts) > 1 else "bytes"
+        values[wanted[name]] = number * (1024 if unit == "kb" else 1)
+    return values
+
+
+def read_process_memory() -> dict | None:
+    """Current process memory composition: ``/proc/self/status`` on Linux
+    (rss, anonymous, file-backed, swap), else psutil rss only, else
+    ``None``.  The ``method`` key names the source used."""
+    try:
+        with open("/proc/self/status", encoding="utf-8") as fh:
+            parsed = parse_proc_status(fh.read())
+        if parsed["rss"] is not None:
+            parsed["method"] = "/proc/self/status (VmRSS, RssAnon, RssFile, VmSwap)"
+            return parsed
+    except OSError:
+        pass
+    try:
+        import psutil
+        rss = int(psutil.Process().memory_info().rss)
+    except Exception:  # noqa: BLE001 - optional dependency
+        return None
+    return {"rss": rss, "rss_anon": None, "rss_file": None, "swap": None,
+            "method": "psutil.Process().memory_info().rss"}
+
+
+_SAMPLED_METRICS = (
+    ("rss", "process_sampled_peak_rss",
+     "sampled peak of process " + _RSS_COMPOSITION),
+    ("rss_anon", "process_sampled_peak_rss_anon",
+     ("sampled peak of the process's anonymous (non-file-backed) resident "
+      "pages; the closest match to the 'peak anonymous memory' figure in "
+      "docs/nvidia.md")),
+    ("rss_file", "process_sampled_peak_rss_file",
+     ("sampled peak of the process's resident file-backed pages (mmap'd "
+      "checkpoint page cache, reclaimable)")),
+    ("swap", "process_sampled_peak_swap",
+     ("sampled peak of swapped-out process memory; a non-zero value marks "
+      "a swapping run, which cannot establish a resident-memory target")),
+)
+
+
+class RssSampler:
+    """Lightweight periodic process-memory sampler (one daemon thread).
+
+    Start it BEFORE the model is built so load transients are covered.
+    The result is a *sampled* peak: spikes shorter than the interval are
+    missed, and the report says so.  On Linux the anonymous, file-backed
+    and swap components are tracked too.
+    """
+
+    def __init__(self, interval_seconds: float, *, read_rss=None,
+                 read_memory=None, join_timeout: float | None = None):
+        self.interval_seconds = float(interval_seconds)
+        self.join_timeout = (float(join_timeout) if join_timeout is not None
+                             else max(5.0, 4 * self.interval_seconds))
+        if read_rss is not None:
+            self._read = lambda: {"rss": int(read_rss())}
+            self._method = "injected read_rss"
+        elif read_memory is not None:
+            self._read = read_memory
+            self._method = "injected read_memory"
+        else:
+            self._read = None
+            self._method = "none"
+        self._peaks: dict[str, int | None] = {
+            key: None for key, _, _ in _SAMPLED_METRICS}
+        self._count = 0
+        self._error: str | None = None
+        self._stop = threading.Event()
+        self._thread: threading.Thread | None = None
+        self._started = False
+
+    @property
+    def is_running(self) -> bool:
+        return self._thread is not None and self._thread.is_alive()
+
+    @property
+    def peak(self) -> int | None:
+        return self._peaks["rss"]
+
+    @property
+    def sample_count(self) -> int:
+        return self._count
+
+    def _sample(self) -> None:
+        read = self._read
+        if read is None:
+            return
+        try:
+            mem = read()
+        except Exception as exc:  # noqa: BLE001 - sampling must never raise
+            self._error = f"{type(exc).__name__}: {exc}"
+            return
+        if not mem:
+            self._error = "memory reader returned nothing"
+            return
+        method = mem.get("method")
+        if method:
+            self._method = str(method)
+        self._count += 1
+        for key in self._peaks:
+            value = mem.get(key)
+            if value is None:
+                continue
+            value = int(value)
+            current = self._peaks[key]
+            self._peaks[key] = value if current is None else max(current, value)
+
+    def _loop(self) -> None:
+        while not self._stop.wait(self.interval_seconds):
+            self._sample()
+
+    def start(self) -> None:
+        if self.interval_seconds <= 0 or self._started:
+            return
+        if self._read is None:
+            probe = read_process_memory()
+            if probe is None:
+                self._error = "no process memory reader (no /proc, no psutil)"
+                return
+            self._read = read_process_memory
+        self._started = True
+        self._sample()
+        self._thread = threading.Thread(
+            target=self._loop, name="bench-rss-sampler", daemon=True)
+        self._thread.start()
+
+    def stop(self) -> None:
+        """Stop sampling (idempotent).  The thread reference is only
+        dropped once the thread has actually exited, so ``is_running``
+        stays true (and the metric carries a reason) if a reader hangs
+        past ``join_timeout``."""
+        self._stop.set()
+        thread = self._thread
+        if thread is None:
+            return
+        thread.join(timeout=self.join_timeout)
+        if thread.is_alive():
+            self._error = (f"sampler thread did not stop within "
+                           f"{self.join_timeout:g}s (reader blocked?)")
+            return
+        self._thread = None
+        self._sample()
+
+    def metrics(self) -> dict:
+        """All sampled peaks as memory metric objects (rss always; the
+        composition only where the reader supplied it)."""
+        out = {}
+        for key, name, scope in _SAMPLED_METRICS:
+            details = {"interval_seconds": self.interval_seconds,
+                       "sample_count": self._count}
+            if self.interval_seconds <= 0:
+                out[name] = memory_metric(
+                    None, method="none", scope=scope,
+                    unavailable_reason="sampler disabled (interval 0)",
+                    interval_seconds=self.interval_seconds)
+                continue
+            value = self._peaks[key]
+            if value is not None:
+                if self._error and self.is_running:
+                    details["warning"] = self._error
+                out[name] = memory_metric(value, method=self._method,
+                                          scope=scope, **details)
+            elif key == "rss":
+                out[name] = memory_metric(
+                    None, method=self._method, scope=scope,
+                    unavailable_reason=self._error or "sampler never ran",
+                    **details)
+            else:
+                out[name] = memory_metric(
+                    None, method=self._method, scope=scope,
+                    unavailable_reason=(
+                        f"{key} needs /proc/self/status (Linux); the "
+                        f"memory reader did not supply it"),
+                    **details)
+        return out
+
+    def metric(self) -> dict:
+        return self.metrics()["process_sampled_peak_rss"]
+
+
+# ---- run identity ------------------------------------------------------------------
+
+
+def git_identity(repo_dir, *, run=subprocess.run) -> dict:
+    """HEAD commit and tracked-file dirty state of ``repo_dir``."""
+    out: dict[str, Any] = {"commit": None, "dirty": None,
+                           "unavailable_reasons": {}}
+
+    def _git(*args):
+        return run(["git", "-C", str(repo_dir), *args], capture_output=True,
+                   text=True, timeout=15)
+
+    try:
+        head = _git("rev-parse", "HEAD")
+    except (OSError, subprocess.SubprocessError) as exc:
+        reason = f"git unavailable: {type(exc).__name__}: {exc}"
+        out["unavailable_reasons"] = {"commit": reason, "dirty": reason}
+        return out
+    if head.returncode != 0 or not head.stdout.strip():
+        reason = (f"git rev-parse failed (exit {head.returncode}): "
+                  f"{(head.stderr or '').strip() or 'no output'}")
+        out["unavailable_reasons"] = {"commit": reason, "dirty": reason}
+        return out
+    out["commit"] = head.stdout.strip()
+    try:
+        status = _git("status", "--porcelain", "--untracked-files=no")
+    except (OSError, subprocess.SubprocessError) as exc:
+        out["unavailable_reasons"]["dirty"] = (
+            f"git status failed: {type(exc).__name__}: {exc}")
+        return out
+    if status.returncode != 0:
+        out["unavailable_reasons"]["dirty"] = (
+            f"git status failed (exit {status.returncode})")
+        return out
+    out["dirty"] = bool(status.stdout.strip())
+    return out
+
+
+_NVPMODEL_STATUS = Path("/var/lib/nvpmodel/status")
+
+
+def power_mode(*, run=subprocess.run, status_path=_NVPMODEL_STATUS) -> dict:
+    """Jetson power mode via ``nvpmodel -q``, else the nvpmodel status
+    file, else an explicit unavailable reason."""
+    out: dict[str, Any] = {"value": None, "mode_id": None, "method": None,
+                           "unavailable_reasons": {}}
+    reasons = []
+    try:
+        proc = run(["nvpmodel", "-q"], capture_output=True, text=True,
+                   timeout=10)
+        if proc.returncode == 0:
+            name = None
+            mode_id = None
+            for line in (proc.stdout or "").splitlines():
+                text = line.strip()
+                if text.lower().startswith("nv power mode:"):
+                    name = text.split(":", 1)[1].strip()
+                elif name is not None and mode_id is None and text.isdigit():
+                    mode_id = int(text)
+            if name:
+                out.update(value=name, mode_id=mode_id, method="nvpmodel -q")
+                if mode_id is None:
+                    out["unavailable_reasons"]["mode_id"] = (
+                        "nvpmodel -q printed no numeric mode id")
+                return out
+            reasons.append("nvpmodel -q printed no 'NV Power Mode' line")
+        else:
+            reasons.append(
+                f"nvpmodel -q exited {proc.returncode}: "
+                f"{(proc.stderr or '').strip() or 'no output'}")
+    except (OSError, subprocess.SubprocessError) as exc:
+        reasons.append(f"nvpmodel not runnable: {type(exc).__name__}: {exc}")
+    try:
+        text = Path(status_path).read_text(errors="replace")
+        match = re.search(r"pmode:(\d+)", text)
+        if match:
+            mode_id = int(match.group(1))
+            out.update(value=f"pmode {mode_id}", mode_id=mode_id,
+                       method=f"{status_path} pmode field")
+            return out
+        reasons.append(f"{status_path} has no pmode field")
+    except OSError as exc:
+        reasons.append(f"{status_path}: {type(exc).__name__}")
+    reason = ("; ".join(reasons)
+              + " (not a Jetson, or nvpmodel is not on PATH)")
+    out["unavailable_reasons"] = {"value": reason, "mode_id": reason,
+                                  "method": reason}
+    return out
+
+
+# ---- checkpoint identity -----------------------------------------------------------
+
+
+def _sha256_file(path: Path) -> str:
+    digest = hashlib.sha256()
+    with open(path, "rb") as fh:
+        for chunk in iter(lambda: fh.read(1 << 20), b""):
+            digest.update(chunk)
+    return digest.hexdigest()
+
+
+def safetensors_header(path) -> dict:
+    """``__metadata__``, tensor count and a hash of the JSON header of a
+    safetensors file: an 8-byte length prefix plus the header, no weight
+    bytes touched."""
+    out: dict[str, Any] = {"metadata": {}, "tensor_count": None,
+                           "header_sha256": None, "unavailable_reasons": {}}
+    try:
+        with open(path, "rb") as fh:
+            (length,) = struct.unpack("<Q", fh.read(8))
+            if length > (256 << 20):
+                raise ValueError(f"header length {length} is implausible")
+            raw = fh.read(length)
+        header = json.loads(raw.decode("utf-8"))
+        if not isinstance(header, dict):
+            raise ValueError("header is not a JSON object")
+        metadata = header.get("__metadata__")
+        out["metadata"] = dict(metadata) if isinstance(metadata, dict) else {}
+        out["tensor_count"] = len([k for k in header if k != "__metadata__"])
+        out["header_sha256"] = hashlib.sha256(raw).hexdigest()
+    except (OSError, ValueError, struct.error) as exc:
+        reason = f"safetensors header unreadable: {type(exc).__name__}: {exc}"
+        out["unavailable_reasons"] = {"tensor_count": reason,
+                                      "header_sha256": reason}
+    return out
+
+
+MANIFEST_ALGORITHM = ("sha256 over 'path\\tsize\\n' lines, one per regular "
+                      "file, sorted by relative POSIX path")
+
+
+def checkpoint_manifest(model_dir, *, hash_limit_bytes: int = 32 << 20) -> dict:
+    """Identify a checkpoint directory without hashing weights.
+
+    Every regular file contributes ``(relative path, size)`` to the
+    manifest digest and the retained ``files`` list.  Files up to
+    ``hash_limit_bytes`` that are not safetensors are content-hashed
+    (config, chat template, tokenizer); safetensors files contribute
+    their header metadata, tensor count and header hash.
+    """
+    out: dict[str, Any] = {
+        "manifest": {"algorithm": MANIFEST_ALGORITHM, "file_count": None,
+                     "total_bytes": None, "sha256": None, "files": [],
+                     "unavailable_reasons": {}},
+        "small_file_sha256": {},
+        "safetensors_headers": {},
+        "config": {},
+        "config_sha256": None,
+    }
+    root = Path(model_dir)
+    if not root.is_dir():
+        reason = f"checkpoint directory {str(root)!r} does not exist"
+        out["manifest"]["unavailable_reasons"] = {
+            "file_count": reason, "total_bytes": reason, "sha256": reason}
+        return out
+    entries = []
+    total = 0
+    for path in sorted(p for p in root.rglob("*") if p.is_file()):
+        rel = path.relative_to(root).as_posix()
+        size = path.stat().st_size
+        entries.append((rel, size))
+        total += size
+        if path.suffix == ".safetensors":
+            out["safetensors_headers"][rel] = safetensors_header(path)
+        elif size <= hash_limit_bytes:
+            try:
+                out["small_file_sha256"][rel] = _sha256_file(path)
+            except OSError:
+                pass
+    entries.sort()
+    digest = hashlib.sha256()
+    for rel, size in entries:
+        digest.update(f"{rel}\t{size}\n".encode())
+    out["manifest"].update(
+        file_count=len(entries), total_bytes=total,
+        sha256=digest.hexdigest(),
+        files=[{"path": rel, "size_bytes": size} for rel, size in entries])
+    config_path = root / "config.json"
+    if config_path.is_file():
+        try:
+            with open(config_path, encoding="utf-8") as fh:
+                config = json.load(fh)
+            if isinstance(config, dict):
+                out["config"] = config
+        except (OSError, ValueError):
+            pass
+        out["config_sha256"] = out["small_file_sha256"].get("config.json")
+    return out
+
+
+def adapter_identity(path, checkpoint_dir, *,
+                     sha256_max_bytes: int = 256 << 20) -> dict:
+    """Identity of the adapter file the engine actually applied
+    (``engine.cfg.lora`` / ``engine.cfg.prerouter.weights_file``), which
+    may live outside the checkpoint directory (``artifacts/`` fallback).
+    Adapter files are small enough to hash; the cap keeps a misconfigured
+    path from hashing a weight shard."""
+    out: dict[str, Any] = {"file": None, "path": None,
+                           "inside_checkpoint_dir": None, "size_bytes": None,
+                           "sha256": None, "safetensors_header": None,
+                           "unavailable_reasons": {}}
+    reasons = out["unavailable_reasons"]
+    if not path:
+        reason = "disabled: no adapter file configured for this tier"
+        for key in ("file", "path", "inside_checkpoint_dir", "size_bytes",
+                    "sha256", "safetensors_header"):
+            reasons[key] = reason
+        return out
+    p = Path(os.fspath(path))
+    resolved = p.resolve()
+    out["path"] = str(resolved)
+    root = Path(checkpoint_dir).resolve()
+    try:
+        rel = resolved.relative_to(root).as_posix()
+        inside = True
+    except ValueError:
+        rel = None
+        inside = False
+    out["inside_checkpoint_dir"] = inside
+    out["file"] = rel if inside else str(resolved)
+    if not p.is_file():
+        reason = f"adapter file not found: {resolved}"
+        for key in ("size_bytes", "sha256", "safetensors_header"):
+            reasons[key] = reason
+        return out
+    size = p.stat().st_size
+    out["size_bytes"] = size
+    if size <= sha256_max_bytes:
+        out["sha256"] = _sha256_file(p)
+    else:
+        reasons["sha256"] = (f"not hashed: {size} bytes is larger than the "
+                             f"{sha256_max_bytes}-byte cap")
+    if p.suffix == ".safetensors":
+        out["safetensors_header"] = safetensors_header(p)
+    else:
+        reasons["safetensors_header"] = "not a safetensors file"
+    return out
+
+
+# ---- runtime -----------------------------------------------------------------------
+
+
+def runtime_info(backend_name: str, *, importer=importlib.import_module) -> dict:
+    """Interpreter, platform and framework versions for the ACTIVE backend
+    only (the other framework is not imported)."""
+    info: dict[str, Any] = {
+        "python_version": platform.python_version(),
+        "platform": {"system": platform.system(),
+                     "release": platform.release(),
+                     "machine": platform.machine()},
+        "torch_version": None,
+        "torch_cuda_version": None,
+        "mlx_version": None,
+        "unavailable_reasons": {},
+    }
+    reasons = info["unavailable_reasons"]
+    if backend_name == "cuda":
+        reasons["mlx_version"] = "backend is cuda; mlx not imported"
+        try:
+            torch = importer("torch")
+        except Exception as exc:  # noqa: BLE001 - reported, not raised
+            reason = f"torch import failed: {exc}"
+            reasons["torch_version"] = reason
+            reasons["torch_cuda_version"] = reason
+            return info
+        info["torch_version"] = str(getattr(torch, "__version__", "unknown"))
+        cuda = getattr(getattr(torch, "version", None), "cuda", None)
+        if cuda:
+            info["torch_cuda_version"] = str(cuda)
+        else:
+            reasons["torch_cuda_version"] = (
+                "torch build has no CUDA runtime (CPU-only build)")
+    elif backend_name == "mlx":
+        reasons["torch_version"] = "backend is mlx; torch not imported"
+        reasons["torch_cuda_version"] = "backend is mlx; torch not imported"
+        try:
+            mlx = importer("mlx")
+            info["mlx_version"] = str(getattr(mlx, "__version__", "unknown"))
+        except Exception as exc:  # noqa: BLE001 - reported, not raised
+            reasons["mlx_version"] = f"mlx import failed: {exc}"
+    else:
+        reason = f"backend {backend_name!r} has no known runtime"
+        for key in ("torch_version", "torch_cuda_version", "mlx_version"):
+            reasons[key] = reason
+    return info
+
+
+__all__ = [
+    "CUDA_RESERVED_SCOPE",
+    "MANIFEST_ALGORITHM",
+    "RUN_PEAK_SCOPE",
+    "CudaMeasurement",
+    "MlxMeasurement",
+    "NullMeasurement",
+    "RssSampler",
+    "adapter_identity",
+    "checkpoint_manifest",
+    "execution_evidence",
+    "git_identity",
+    "make_measurement",
+    "parse_proc_status",
+    "power_mode",
+    "process_peak_rss",
+    "read_process_memory",
+    "runtime_info",
+    "safetensors_header",
+]
diff --git a/examples/benchmark_report.py b/examples/benchmark_report.py
new file mode 100644
index 0000000..1bf58bd
--- /dev/null
+++ b/examples/benchmark_report.py
@@ -0,0 +1,546 @@
+"""Pure benchmark report builder: measured numbers -> JSON contract.
+
+This module is deliberately standard-library only.  It never imports
+``edge0``, ``torch`` or ``mlx`` and performs no measurement of its own:
+``examples/bench.py`` measures, ``examples/benchmark_measure.py`` collects
+backend/process metrics, and the functions here validate and assemble the
+result into the versioned schema documented in ``docs/nvidia.md``.
+
+Conventions of the schema:
+
+* ``schema_version`` is the benchmark schema, independent of the probe
+  schema in ``scripts/jetson_probe.py``.
+* A required measurement (a token count, a wall-clock duration, a byte
+  count) that is invalid -- negative, non-finite, wrong type -- raises
+  ``ValueError``; it is never written as a plausible-looking number.
+* Unavailable *metadata* is ``null`` plus a reason: every group object
+  carries an ``unavailable_reasons`` map (``{field: reason}``) and every
+  ``null`` field in the group has an entry there (and vice versa).
+  Single-valued memory metric objects carry their own
+  ``unavailable_reason`` instead.
+* Serialization is strict JSON (``allow_nan=False``).
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import math
+import os
+import statistics
+import tempfile
+from typing import Any
+
+#: Benchmark report schema.  Independent of ``scripts/jetson_probe.py``'s
+#: ``schema_version``; bump when a field's meaning or presence changes.
+SCHEMA_VERSION = 1
+
+#: What ``examples/bench.py`` measures.  Stated in the report so a number
+#: is never mistaken for time-to-first-token or an EOS-aware completion.
+PROTOCOL = {
+    "name": "fixed-length-sample-and-step",
+    "version": 1,
+    "description": (
+        "Two sequential runs in one process.  Each run: engine reset, "
+        "timed chat-templated prefill, untimed warmup steps, then a "
+        "timed fixed-length decode window.  Wall time is host monotonic "
+        "time and includes storage, transfer and CPU sampling costs; on "
+        "CUDA the device is synchronized at phase boundaries only."),
+    "warmup": (
+        "greedy argmax steps, untimed; excluded from every throughput "
+        "figure (expert cold-start and first-step overhead land here)"),
+    "timed_phase": (
+        "each timed iteration samples one token from the current logits "
+        "and runs one engine step (a forward pass); the final step's "
+        "logits are computed but never sampled; the loop is fixed-length "
+        "and does not stop at EOS"),
+    "not_measured": ["TTFT", "EOS-aware completion latency"],
+}
+
+#: Required direct fields per group (``unavailable_reasons`` is added or
+#: checked separately).
+REQUIRED_FIELDS = {
+    "identity": ("timestamp_utc", "git", "run_count", "command",
+                 "requested"),
+    "model": ("checkpoint_path", "tier", "model_type", "architectures",
+              "config_sha256", "manifest", "small_file_sha256", "adapters",
+              "tokenizer_files"),
+    "runtime": ("backend", "backend_version", "resolved_device",
+                "measurement", "execution_evidence", "python_version",
+                "torch_version", "torch_cuda_version", "mlx_version",
+                "platform", "power_mode"),
+    "workload": ("prompt_source", "prompt_sha256", "prompt_token_ids_sha256",
+                 "prompt_chars", "prompt_tokens", "requested_warmup_tokens",
+                 "requested_timed_tokens", "seed", "temperature", "top_k",
+                 "top_p", "repetition_penalty", "prefill_chunk", "think"),
+    "caches": ("layer_options", "shared_cache_slots_resolved",
+               "prefetch_cap_resolved", "weight_cache", "prewarm",
+               "threads", "mlx_cache_limit_bytes"),
+    "memory": ("process_peak_rss", "process_sampled_peak_rss", "notes"),
+}
+
+_RUN_FIELDS = ("index", "prompt_tokens", "requested_warmup_tokens",
+               "warmup_tokens", "requested_timed_tokens",
+               "timed_decode_tokens", "total_generated_tokens",
+               "decode_start_context_tokens", "prefill_seconds",
+               "prefill_tokens_per_second", "decode_seconds",
+               "decode_tokens_per_second", "memory", "execution_evidence",
+               "unavailable_reasons")
+
+_SUMMARY_METRICS = ("decode_tokens_per_second", "prefill_tokens_per_second",
+                    "prefill_seconds", "decode_seconds")
+
+
+def _is_int(value) -> bool:
+    return isinstance(value, int) and not isinstance(value, bool)
+
+
+def _require_count(name: str, value) -> int:
+    if not _is_int(value):
+        raise ValueError(f"{name} must be an int, got {value!r}")
+    if value < 0:
+        raise ValueError(f"{name} must be >= 0, got {value}")
+    return value
+
+
+def _require_seconds(name: str, value) -> float:
+    if isinstance(value, bool) or not isinstance(value, (int, float)):
+        raise ValueError(f"{name} must be a number, got {value!r}")
+    value = float(value)
+    if not math.isfinite(value):
+        raise ValueError(f"{name} must be finite, got {value!r}")
+    if value < 0:
+        raise ValueError(f"{name} must be >= 0, got {value!r}")
+    return value
+
+
+def memory_metric(bytes_value, *, method: str, scope: str,
+                  unavailable_reason: str | None = None, **details) -> dict:
+    """One memory measurement: integer bytes, how it was measured, and
+    what interval/process it covers.
+
+    ``bytes_value`` is ``None`` only together with ``unavailable_reason``
+    (and a measured value never carries a reason).  Extra keyword details
+    (``interval_seconds``, ``sample_count``, ...) are kept verbatim.
+    """
+    if not method:
+        raise ValueError("memory metric needs a non-empty method")
+    if not scope:
+        raise ValueError("memory metric needs a non-empty scope")
+    if bytes_value is None:
+        if not unavailable_reason:
+            raise ValueError(
+                "memory metric without bytes needs an unavailable_reason")
+    else:
+        if unavailable_reason:
+            raise ValueError(
+                "memory metric with bytes must not carry an unavailable "
+                "reason")
+        if not _is_int(bytes_value):
+            raise ValueError(
+                f"memory metric bytes must be an int, got {bytes_value!r}")
+        if bytes_value < 0:
+            raise ValueError(
+                f"memory metric bytes must be >= 0, got {bytes_value}")
+    metric = {
+        "bytes": bytes_value,
+        "unit": "bytes",
+        "method": method,
+        "scope": scope,
+        "unavailable_reason": unavailable_reason or None,
+    }
+    metric.update(details)
+    return metric
+
+
+def _rate(tokens: int, seconds: float):
+    """tokens/seconds, or ``None`` when the measured duration is zero (an
+    unavailable rate, never a fabricated zero)."""
+    if seconds == 0.0:
+        return None
+    return tokens / seconds
+
+
+def run_result(*, index: int, prompt_tokens: int,
+               requested_warmup_tokens: int, warmup_tokens: int,
+               requested_timed_tokens: int, timed_decode_tokens: int,
+               prefill_seconds: float, decode_seconds: float,
+               memory: dict, execution_evidence: dict | None = None) -> dict:
+    """Validate one benchmark run and derive its counts and rates.
+
+    For the fixed-length sample-and-step loop in ``examples/bench.py``:
+    ``total_generated_tokens = warmup + timed_decode`` and
+    ``decode_start_context_tokens = prompt + warmup``.  Throughput uses
+    only the timed decode tokens.  Requested counts are kept separately
+    from the counts actually executed.
+    """
+    index = _require_count("index", index)
+    prompt_tokens = _require_count("prompt_tokens", prompt_tokens)
+    requested_warmup_tokens = _require_count(
+        "requested_warmup_tokens", requested_warmup_tokens)
+    warmup_tokens = _require_count("warmup_tokens", warmup_tokens)
+    requested_timed_tokens = _require_count(
+        "requested_timed_tokens", requested_timed_tokens)
+    timed_decode_tokens = _require_count(
+        "timed_decode_tokens", timed_decode_tokens)
+    if timed_decode_tokens <= 0:
+        raise ValueError(
+            "timed_decode_tokens must be > 0: an empty timed window is "
+            "not a successful benchmark")
+    prefill_seconds = _require_seconds("prefill_seconds", prefill_seconds)
+    decode_seconds = _require_seconds("decode_seconds", decode_seconds)
+
+    unavailable: dict[str, str] = {}
+    prefill_tps = _rate(prompt_tokens, prefill_seconds)
+    if prefill_tps is None:
+        unavailable["prefill_tokens_per_second"] = (
+            "measured prefill duration is zero")
+    decode_tps = _rate(timed_decode_tokens, decode_seconds)
+    if decode_tps is None:
+        unavailable["decode_tokens_per_second"] = (
+            "measured decode duration is zero")
+
+    return {
+        "index": index,
+        "prompt_tokens": prompt_tokens,
+        "requested_warmup_tokens": requested_warmup_tokens,
+        "warmup_tokens": warmup_tokens,
+        "requested_timed_tokens": requested_timed_tokens,
+        "timed_decode_tokens": timed_decode_tokens,
+        "total_generated_tokens": warmup_tokens + timed_decode_tokens,
+        "decode_start_context_tokens": prompt_tokens + warmup_tokens,
+        "prefill_seconds": prefill_seconds,
+        "prefill_tokens_per_second": prefill_tps,
+        "decode_seconds": decode_seconds,
+        "decode_tokens_per_second": decode_tps,
+        "memory": dict(memory),
+        "execution_evidence": dict(execution_evidence or {}),
+        "unavailable_reasons": unavailable,
+    }
+
+
+# ---- validation --------------------------------------------------------------
+
+
+def _walk(value, path: str, errors: list[str]) -> None:
+    """Strict-JSON and null-with-reason walk over a report fragment."""
+    if isinstance(value, dict):
+        for key in value:
+            if not isinstance(key, str):
+                errors.append(f"{path}: non-string key {key!r}")
+        reasons = value.get("unavailable_reasons")
+        if "unavailable_reasons" in value:
+            if not isinstance(reasons, dict):
+                errors.append(f"{path}.unavailable_reasons must be a map")
+                reasons = {}
+            for key, reason in reasons.items():
+                if key not in value:
+                    errors.append(
+                        f"{path}.unavailable_reasons names unknown field "
+                        f"{key!r}")
+                elif value[key] is not None:
+                    errors.append(
+                        f"{path}.{key} has an unavailable reason but also a "
+                        f"value {value[key]!r}")
+                if not isinstance(reason, str) or not reason:
+                    errors.append(
+                        f"{path}.unavailable_reasons[{key!r}] must be a "
+                        f"non-empty string")
+        elif "bytes" in value and "unavailable_reason" in value:
+            # memory metric object: single value, single reason
+            if value["bytes"] is None and not value["unavailable_reason"]:
+                errors.append(f"{path}.bytes is null without a reason")
+            if value["bytes"] is not None and value["unavailable_reason"]:
+                errors.append(
+                    f"{path}.bytes has a value and an unavailable reason")
+        for key, child in value.items():
+            if key == "unavailable_reasons":
+                continue
+            child_path = f"{path}.{key}"
+            if child is None:
+                is_metric_null = key == "unavailable_reason" or (
+                    key == "bytes" and "unavailable_reason" in value)
+                if "unavailable_reasons" in value:
+                    if key not in (reasons or {}):
+                        errors.append(
+                            f"{child_path} is null without an unavailable "
+                            f"reason")
+                elif not is_metric_null:
+                    errors.append(
+                        f"{child_path} is null in an object without an "
+                        f"unavailable_reasons map")
+                continue
+            _walk(child, child_path, errors)
+    elif isinstance(value, list):
+        for i, child in enumerate(value):
+            if child is None:
+                # list entries mirror per-run fields; the reason lives on
+                # the run object (see summarize_runs)
+                continue
+            _walk(child, f"{path}[{i}]", errors)
+    elif value is None or isinstance(value, (bool, str, int)):
+        return
+    elif isinstance(value, float):
+        if not math.isfinite(value):
+            errors.append(f"{path}: non-finite number {value!r}")
+    else:
+        errors.append(
+            f"{path}: unsupported type {type(value).__name__} "
+            f"(not JSON-serializable)")
+
+
+def validate_report(report: dict) -> None:
+    """Raise ``ValueError`` listing every contract violation."""
+    errors: list[str] = []
+    if not isinstance(report, dict):
+        raise ValueError("report must be a dict")
+    for key in ("schema_version", "protocol", "identity", "model",
+                "runtime", "workload", "caches", "runs", "summary",
+                "memory", "probe"):
+        if key not in report:
+            errors.append(f"missing top-level field {key!r}")
+    if errors:
+        raise ValueError("invalid benchmark report:\n  " + "\n  ".join(errors))
+    if report["schema_version"] != SCHEMA_VERSION:
+        errors.append(
+            f"schema_version {report['schema_version']!r} != "
+            f"{SCHEMA_VERSION}")
+    for group, fields in REQUIRED_FIELDS.items():
+        obj = report[group]
+        if not isinstance(obj, dict):
+            errors.append(f"{group} must be an object")
+            continue
+        for field in fields:
+            if field not in obj:
+                errors.append(f"{group}.{field} is required")
+        if "unavailable_reasons" not in obj:
+            errors.append(f"{group}.unavailable_reasons is required")
+    runs = report["runs"]
+    if not isinstance(runs, list) or not runs:
+        errors.append("runs must be a non-empty list")
+    else:
+        for i, run in enumerate(runs):
+            if not isinstance(run, dict):
+                errors.append(f"runs[{i}] must be an object")
+                continue
+            for field in _RUN_FIELDS:
+                if field not in run:
+                    errors.append(f"runs[{i}].{field} is required")
+            if run.get("index") != i:
+                errors.append(
+                    f"runs[{i}].index is {run.get('index')!r}, expected {i}")
+        run_count = report["identity"].get("run_count") \
+            if isinstance(report["identity"], dict) else None
+        if run_count != len(runs):
+            errors.append(
+                f"identity.run_count {run_count!r} != len(runs) "
+                f"{len(runs)}")
+    _walk(report, "report", errors)
+    if errors:
+        raise ValueError("invalid benchmark report:\n  " + "\n  ".join(errors))
+
+
+# ---- summary -----------------------------------------------------------------
+
+
+def _stat_block(values: list) -> dict:
+    """Descriptive statistics over per-run values (``None`` allowed)."""
+    values = list(values)
+    present = [v for v in values if v is not None]
+    block: dict[str, Any] = {
+        "n": len(values), "n_valid": len(present), "values": values,
+        "mean": None, "min": None, "max": None, "sample_stdev": None,
+        "unavailable_reasons": {}}
+    if not present:
+        reason = "no run has a value for this metric (n_valid = 0)"
+        for key in ("mean", "min", "max", "sample_stdev"):
+            block["unavailable_reasons"][key] = reason
+        return block
+    block["mean"] = statistics.fmean(present)
+    block["min"] = min(present)
+    block["max"] = max(present)
+    if len(present) >= 2:
+        block["sample_stdev"] = statistics.stdev(present)
+    else:
+        block["unavailable_reasons"]["sample_stdev"] = (
+            f"sample standard deviation needs at least 2 runs with a value "
+            f"(n_valid = {len(present)})")
+    return block
+
+
+def summarize_runs(runs: list[dict]) -> dict:
+    """Summary over every retained run.  Runs are sequential within one
+    process, so this is descriptive, not an estimate from independent
+    launches (those are Task 3/7's job)."""
+    summary: dict[str, Any] = {"run_count": len(runs)}
+    for metric in _SUMMARY_METRICS:
+        summary[metric] = _stat_block([run.get(metric) for run in runs])
+    summary["method"] = (
+        "arithmetic mean, min, max and sample standard deviation (n-1) "
+        "over every retained run with a value (n_valid; values keeps the "
+        "per-run entries, null included); runs are sequential in one "
+        "process (run 0 is the first request after model load) and are "
+        "not independent launches")
+    return summary
+
+
+# ---- probe link --------------------------------------------------------------
+
+
+_PROBE_FIELDS = ("path", "schema_version", "sha256", "ready",
+                 "collected_at_utc")
+
+
+def probe_link(*, path, text) -> dict:
+    """Link the report to an actual probe file: its schema version, the
+    SHA-256 of the file content as read, and the local reference.
+
+    ``text`` is the raw file content (``bytes`` are hashed as-is; ``str``
+    is hashed as UTF-8).  ``None`` means no probe was supplied.
+    """
+    link: dict[str, Any]
+    if text is None:
+        reason = "no probe file supplied (--probe-json not given)"
+        link = {"supplied": False}
+        link.update({field: None for field in _PROBE_FIELDS})
+        link["unavailable_reasons"] = {f: reason for f in _PROBE_FIELDS}
+        return link
+    raw = text if isinstance(text, bytes) else text.encode("utf-8")
+    digest = hashlib.sha256(raw).hexdigest()
+    try:
+        data = json.loads(raw.decode("utf-8"))
+    except (UnicodeDecodeError, ValueError) as exc:
+        raise ValueError(f"probe file {path!r} is not valid JSON: {exc}")
+    if not isinstance(data, dict):
+        raise ValueError(f"probe file {path!r} is not a JSON object")
+    schema = data.get("schema_version")
+    if not _is_int(schema):
+        raise ValueError(
+            f"probe file {path!r} has no integer schema_version")
+    link = {"supplied": True, "path": os.fspath(path),
+            "schema_version": schema, "sha256": digest,
+            "ready": None, "collected_at_utc": None,
+            "unavailable_reasons": {}}
+    ready = data.get("ready")
+    if isinstance(ready, bool):
+        link["ready"] = ready
+    else:
+        link["unavailable_reasons"]["ready"] = (
+            "probe has no boolean 'ready' field")
+    collected = data.get("collected_at_utc")
+    if isinstance(collected, str) and collected:
+        link["collected_at_utc"] = collected
+    else:
+        link["unavailable_reasons"]["collected_at_utc"] = (
+            "probe has no 'collected_at_utc' field")
+    return link
+
+
+# ---- assembly and serialization ------------------------------------------------
+
+
+def build_report(*, identity: dict, model: dict, runtime: dict,
+                 workload: dict, caches: dict, runs: list[dict],
+                 memory: dict, probe: dict | None = None) -> dict:
+    """Assemble and validate the full report.  ``runs`` are
+    ``run_result`` dicts; ``probe`` is a ``probe_link`` dict (``None`` =
+    not supplied)."""
+    def _group(obj, name):
+        if not isinstance(obj, dict):
+            raise ValueError(f"{name} must be an object")
+        out = dict(obj)
+        out.setdefault("unavailable_reasons", {})
+        return out
+
+    report = {
+        "schema_version": SCHEMA_VERSION,
+        "protocol": dict(PROTOCOL),
+        "identity": _group(identity, "identity"),
+        "model": _group(model, "model"),
+        "runtime": _group(runtime, "runtime"),
+        "workload": _group(workload, "workload"),
+        "caches": _group(caches, "caches"),
+        "runs": [dict(run) for run in runs],
+        "summary": summarize_runs(runs) if runs else {},
+        "memory": _group(memory, "memory"),
+        "probe": (probe if probe is not None
+                  else probe_link(path=None, text=None)),
+    }
+    validate_report(report)
+    return report
+
+
+def dumps_report(report: dict) -> str:
+    """Strict JSON text (``allow_nan=False``, sorted keys, trailing
+    newline).  Validates first so a NaN never reaches the encoder."""
+    validate_report(report)
+    return json.dumps(report, indent=2, sort_keys=True, allow_nan=False) + "\n"
+
+
+def _place_new_file(tmp: str, dest: str) -> None:
+    """Move ``tmp`` to ``dest`` without ever overwriting ``dest``.
+
+    A hard link is atomic and fails with EEXIST when the destination
+    appeared meanwhile; the temporary name is then unlinked.  Filesystems
+    without hard links fall back to a rename (``os.rename`` refuses an
+    existing destination on Windows; POSIX ``os.replace`` is the last
+    resort after a fresh existence check).
+    """
+    try:
+        os.link(tmp, dest)
+    except FileExistsError:
+        raise FileExistsError(
+            f"benchmark output {dest!r} appeared while the report was being "
+            f"written; refusing to overwrite it")
+    except (OSError, AttributeError):
+        if os.path.lexists(dest):
+            raise FileExistsError(
+                f"benchmark output {dest!r} appeared while the report was "
+                f"being written; refusing to overwrite it")
+        if os.name == "nt":
+            os.rename(tmp, dest)
+        else:
+            os.replace(tmp, dest)
+        return
+    os.unlink(tmp)
+
+
+def write_report(report: dict, path) -> str:
+    """Validate, then write the report atomically to a NEW file.
+
+    The destination must not exist (a stale success report can otherwise
+    be mistaken for this run's result).  The text is written to a
+    temporary file in the destination directory, fsynced, and linked or
+    renamed into place without overwriting; on any failure the temporary
+    file is removed and the destination is left as it was.
+    """
+    text = dumps_report(report)
+    path = os.fspath(path)
+    if os.path.lexists(path):
+        raise FileExistsError(
+            f"benchmark output {path!r} already exists; refusing to "
+            f"overwrite (choose a new path)")
+    dest_dir = os.path.dirname(os.path.abspath(path)) or os.curdir
+    if not os.path.isdir(dest_dir):
+        raise FileNotFoundError(
+            f"benchmark output directory {dest_dir!r} does not exist")
+    fd, tmp = tempfile.mkstemp(prefix=".bench-", suffix=".json.tmp",
+                               dir=dest_dir)
+    try:
+        if os.name != "nt":
+            # mkstemp creates 0600; give the report the usual umask mode
+            mask = os.umask(0)
+            os.umask(mask)
+            os.chmod(tmp, 0o666 & ~mask)
+        with os.fdopen(fd, "w", encoding="utf-8", newline="\n") as fh:
+            fh.write(text)
+            fh.flush()
+            os.fsync(fh.fileno())
+        _place_new_file(tmp, path)
+    except BaseException:
+        try:
+            os.unlink(tmp)
+        except OSError:
+            pass
+        raise
+    return text
diff --git a/pyproject.toml b/pyproject.toml
index 5186b0b..98ce6a1 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -50,6 +50,10 @@ where = ["src"]
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]
+# tests import repo-root packages (``from scripts import jetson_probe``,
+# ``from examples import bench``); put the root on sys.path for the plain
+# ``pytest`` invocation too, not only for ``python -m pytest``.
+pythonpath = ["."]
 markers = [
     "slow: real-weight e2e tests (skip with -m 'not slow')",
 ]
diff --git a/scripts/jetson_probe.py b/scripts/jetson_probe.py
new file mode 100755
index 0000000..1e01f10
--- /dev/null
+++ b/scripts/jetson_probe.py
@@ -0,0 +1,332 @@
+#!/usr/bin/env python3
+"""Collect reproducible Jetson/CUDA facts before running Edge0 benchmarks.
+
+The probe is read-only and uses the Python standard library unless PyTorch is
+installed. It prints JSON so benchmark reports can retain the exact platform
+and storage context that produced them.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import platform
+import shutil
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+_AUTO_TORCH = object()
+
+
+def _read_text(path: Path) -> str | None:
+    try:
+        return path.read_text(errors="replace").rstrip("\x00\n")
+    except (OSError, UnicodeError):
+        return None
+
+
+def parse_meminfo(text: str) -> dict[str, int | None]:
+    """Return total and available memory in bytes from Linux meminfo text."""
+    values: dict[str, int] = {}
+    for line in text.splitlines():
+        if ":" not in line:
+            continue
+        name, raw = line.split(":", 1)
+        fields = raw.split()
+        if not fields:
+            continue
+        try:
+            value = int(fields[0])
+        except ValueError:
+            continue
+        unit = fields[1].lower() if len(fields) > 1 else "bytes"
+        multiplier = 1024 if unit == "kb" else 1
+        values[name] = value * multiplier
+    return {
+        "total_bytes": values.get("MemTotal"),
+        "available_bytes": values.get("MemAvailable"),
+    }
+
+
+def _unescape_mount_field(value: str) -> str:
+    for escaped, plain in (
+        ("\\040", " "),
+        ("\\011", "\t"),
+        ("\\012", "\n"),
+        ("\\134", "\\"),
+    ):
+        value = value.replace(escaped, plain)
+    return value
+
+
+def _mounts(mountinfo_text: str) -> list[dict[str, str]]:
+    mounts = []
+    for line in mountinfo_text.splitlines():
+        fields = line.split()
+        try:
+            separator = fields.index("-")
+            mounts.append(
+                {
+                    "device_id": fields[2],
+                    "mount_point": _unescape_mount_field(fields[4]),
+                    "filesystem": fields[separator + 1],
+                    "device": _unescape_mount_field(fields[separator + 2]),
+                }
+            )
+        except (ValueError, IndexError):
+            continue
+    return mounts
+
+
+def _sysfs_tree_is_nvme(path: Path, seen: set[Path] | None = None) -> bool:
+    try:
+        resolved = path.resolve(strict=True)
+    except OSError:
+        return False
+    seen = seen or set()
+    if resolved in seen:
+        return False
+    seen.add(resolved)
+    try:
+        slaves = list((resolved / "slaves").iterdir())
+    except OSError:
+        slaves = []
+    if slaves:
+        return all(_sysfs_tree_is_nvme(slave, seen) for slave in slaves)
+    return any(part.startswith("nvme") for part in resolved.parts)
+
+
+def _device_is_nvme(
+    device: str,
+    device_id: str | None,
+    sys_dev_block: Path,
+) -> bool | None:
+    if device_id:
+        sysfs_device = sys_dev_block / device_id
+        if sysfs_device.exists():
+            return _sysfs_tree_is_nvme(sysfs_device)
+    if device.startswith(("/dev/mmc", "/dev/sd", "/dev/vd")):
+        return False
+    return None
+
+
+def storage_device_for_path(
+    path: Path,
+    mountinfo_text: str,
+    *,
+    sys_dev_block: Path = Path("/sys/dev/block"),
+    disk_usage_fn: Any = shutil.disk_usage,
+    path_device_id: str | None = None,
+) -> dict[str, Any]:
+    """Describe the longest-prefix Linux mount containing *path*."""
+    target = path.resolve()
+    if path_device_id is None:
+        try:
+            stat = target.stat()
+            path_device_id = f"{os.major(stat.st_dev)}:{os.minor(stat.st_dev)}"
+        except OSError:
+            path_device_id = None
+    candidates = []
+    for position, mount in enumerate(_mounts(mountinfo_text)):
+        mount_path = Path(mount["mount_point"])
+        try:
+            target.relative_to(mount_path)
+        except ValueError:
+            continue
+        if path_device_id is not None and mount["device_id"] != path_device_id:
+            continue
+        candidates.append((len(mount_path.parts), position, mount))
+
+    selected = (
+        max(candidates, key=lambda item: (item[0], item[1]))[2]
+        if candidates
+        else {
+            "device_id": None,
+            "mount_point": None,
+            "filesystem": None,
+            "device": None,
+        }
+    )
+    device = selected.get("device") or ""
+    is_nvme = _device_is_nvme(
+        device,
+        selected.get("device_id"),
+        sys_dev_block,
+    )
+
+    try:
+        usage = disk_usage_fn(target)
+        total_bytes, free_bytes = usage.total, usage.free
+        disk_usage_available = True
+    except OSError:
+        total_bytes = free_bytes = None
+        disk_usage_available = False
+
+    return {
+        **selected,
+        "is_nvme": is_nvme,
+        "path": str(target),
+        "path_exists": target.exists(),
+        "path_is_dir": target.is_dir(),
+        "disk_usage_available": disk_usage_available,
+        "total_bytes": total_bytes,
+        "free_bytes": free_bytes,
+    }
+
+
+def collect_torch_info(torch_module: Any = _AUTO_TORCH) -> dict[str, Any]:
+    """Collect CUDA facts without making torch a probe dependency."""
+    info: dict[str, Any] = {
+        "installed": False,
+        "version": None,
+        "cuda_available": False,
+        "cuda_version": None,
+        "device_name": None,
+        "compute_capability": None,
+        "device_memory_bytes": None,
+        "errors": [],
+    }
+    if torch_module is _AUTO_TORCH:
+        try:
+            import torch as torch_module  # type: ignore[no-redef]
+        except Exception as exc:  # noqa: BLE001 - vendor imports can fail broadly
+            info["errors"].append(f"PyTorch import failed: {type(exc).__name__}: {exc}")
+            return info
+    if torch_module is None:
+        info["errors"].append("PyTorch import was skipped or unavailable")
+        return info
+
+    info["installed"] = True
+    info["version"] = str(getattr(torch_module, "__version__", "unknown"))
+    cuda = getattr(torch_module, "cuda", None)
+    info["cuda_version"] = getattr(getattr(torch_module, "version", None), "cuda", None)
+    try:
+        cuda_available = bool(cuda is not None and cuda.is_available())
+    except Exception as exc:  # noqa: BLE001 - CUDA driver failures vary
+        info["errors"].append(
+            f"CUDA availability check failed: {type(exc).__name__}: {exc}"
+        )
+        return info
+    info["cuda_available"] = cuda_available
+    if cuda_available:
+        assert cuda is not None
+        try:
+            props = cuda.get_device_properties(0)
+            info.update(
+                {
+                    "device_name": props.name,
+                    "compute_capability": [props.major, props.minor],
+                    "device_memory_bytes": props.total_memory,
+                }
+            )
+        except Exception as exc:  # noqa: BLE001 - CUDA driver failures vary
+            info["errors"].append(
+                f"CUDA device query failed: {type(exc).__name__}: {exc}"
+            )
+    return info
+
+
+def collect_probe(
+    model_dir: Path,
+    *,
+    fs_root: Path = Path("/"),
+    mountinfo_text: str | None = None,
+    torch_module: Any = _AUTO_TORCH,
+    disk_usage_fn: Any = shutil.disk_usage,
+    path_device_id: str | None = None,
+) -> dict[str, Any]:
+    """Collect a JSON-serializable Edge0/Jetson readiness report."""
+    model = _read_text(fs_root / "proc/device-tree/model")
+    l4t_release = _read_text(fs_root / "etc/nv_tegra_release")
+    is_jetson_orin = bool(
+        model and "jetson" in model.lower() and "orin" in model.lower()
+    )
+
+    meminfo_text = _read_text(fs_root / "proc/meminfo") or ""
+    memory = parse_meminfo(meminfo_text)
+    if mountinfo_text is None:
+        mountinfo_text = _read_text(fs_root / "proc/self/mountinfo") or ""
+    storage = storage_device_for_path(
+        model_dir,
+        mountinfo_text,
+        sys_dev_block=fs_root / "sys/dev/block",
+        disk_usage_fn=disk_usage_fn,
+        path_device_id=path_device_id,
+    )
+    torch_info = collect_torch_info(torch_module)
+
+    blockers = []
+    if not storage["path_exists"]:
+        blockers.append("model path does not exist")
+    elif not storage["path_is_dir"]:
+        blockers.append("model path is not a directory")
+    if not storage["disk_usage_available"]:
+        blockers.append("model path disk usage could not be determined")
+    if not is_jetson_orin:
+        blockers.append("hardware is not a Jetson Orin")
+    if not torch_info["installed"]:
+        blockers.append("PyTorch is not installed")
+    if not torch_info["cuda_available"]:
+        blockers.append("CUDA is not available through PyTorch")
+    blockers.extend(
+        f"PyTorch/CUDA probe error: {error}" for error in torch_info["errors"]
+    )
+    if storage["is_nvme"] is None:
+        blockers.append("model path NVMe backing could not be confirmed")
+    elif not storage["is_nvme"]:
+        blockers.append("model path is not on NVMe storage")
+
+    return {
+        "schema_version": 1,
+        "collected_at_utc": datetime.now(timezone.utc).isoformat(),
+        "platform": {
+            "system": platform.system(),
+            "release": platform.release(),
+            "machine": platform.machine(),
+            "python": platform.python_version(),
+        },
+        "jetson": {
+            "is_jetson_orin": is_jetson_orin,
+            "model": model,
+            "l4t_release": l4t_release,
+        },
+        "memory": memory,
+        "storage": storage,
+        "torch": torch_info,
+        "edge0_backend": os.environ.get("EDGE0_BACKEND", "mlx"),
+        "ready": not blockers,
+        "blockers": blockers,
+    }
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument(
+        "--model-dir",
+        type=Path,
+        default=Path.cwd(),
+        help="checkpoint directory whose backing storage should be inspected",
+    )
+    parser.add_argument("--output", type=Path, help="also write JSON to this path")
+    parser.add_argument(
+        "--skip-torch",
+        action="store_true",
+        help="do not import PyTorch (reported as an explicit blocker)",
+    )
+    args = parser.parse_args(argv)
+
+    torch_module = None if args.skip_torch else _AUTO_TORCH
+    report = collect_probe(args.model_dir, torch_module=torch_module)
+    rendered = json.dumps(report, indent=2, sort_keys=True) + "\n"
+    sys.stdout.write(rendered)
+    if args.output:
+        args.output.parent.mkdir(parents=True, exist_ok=True)
+        args.output.write_text(rendered)
+    return 0 if report["ready"] else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
diff --git a/scripts/orin_reference_check.py b/scripts/orin_reference_check.py
new file mode 100644
index 0000000..59465fb
--- /dev/null
+++ b/scripts/orin_reference_check.py
@@ -0,0 +1,426 @@
+#!/usr/bin/env python3
+"""On-device Edge0-8B correctness check (Task 3, Gate B).
+
+Generates >= 32 greedy tokens with the torch backend on the TEST device
+(default ``cuda``), then teacher-forces the SAME token sequence through
+the torch backend on the REFERENCE device (default ``cpu``) and compares
+the full per-step logits and token choices.
+
+Why torch-CPU is the reference here: the plan's Gate B fixtures were to
+be generated against MLX, which does not exist on a Jetson.  The torch
+implementation itself was checked against real MLX layer by layer on a
+GB10 (edge0-8b backbone: 5.3e-7 max per layer, 4.3e-7 on the logits,
+same argmax — docs/nvidia.md), so torch-on-CPU is the closest identified
+reference data available on this device, and the comparison isolates
+exactly the variable Task 3 introduces: the CUDA device.  When MLX
+fixtures land, point ``--reference-npz`` at them instead.
+
+Tolerances (DEFINED IN ADVANCE, before any Orin result was examined —
+do not loosen them to make a run pass):
+
+* ``--logit-tol`` (default 1.0): max absolute per-step logit difference.
+  The dense model math runs in bfloat16 (~8 mantissa bits); reduction
+  order differs across devices, so logits at a scale of tens can move
+  by a few tenths through 24 layers.  1.0 is the a-priori bf16 bound,
+  NOT an observed number.
+* ``--near-tie-margin`` (default 1.0): a token divergence at step i is
+  acceptable only if the reference's own logit gap between its top
+  token and the test's chosen token is within this margin (a genuine
+  near-tie), AND the logit tolerance holds at that step.  Any other
+  divergence fails.
+
+Each phase runs in its own subprocess because the torch backend binds
+``EDGE0_TORCH_DEVICE`` at import time.  Exit status: 0 PASS, 1 FAIL,
+2 usage/environment error.  The JSON report records checkpoint /
+adapter / git identity, prompt digest, per-step statistics and the
+verdict; keep it in the untracked evidence set ($EDGE0_RUN_DIR).
+"""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import os
+import subprocess
+import sys
+import time
+from datetime import datetime, timezone
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(REPO_ROOT))
+
+DEFAULT_PROMPT = "9.11 和 9.8 哪个大？请仔细比较。"  # examples/bench.py edge0-8b
+
+#: Knobs recorded per phase as RESOLVED (inherited from the shell or set
+#: by --test-env/--reference-env): the comparison is only meaningful when
+#: the two phases differ in exactly what the caller intended.
+RECORDED_ENV = (
+    "EDGE0_BACKEND", "EDGE0_TORCH_DEVICE", "EDGE0_QMM_BATCHED",
+    "EDGE0_QMM_BATCHED_MAX_BYTES", "EDGE0_INT4PACK",
+    "EDGE0_TORCH_WEIGHT_CACHE", "EDGE0_TORCH_WEIGHT_CACHE_BYTES",
+    "EDGE0_MEMORY_BUDGET", "EDGE0_BUDGET_CONTEXT", "EDGE0_CACHE_SLOTS",
+    "EDGE0_PREDICT_PREFETCH", "EDGE0_PREWARM", "LING_PREWARM",
+    "LING_HIDDEN_CLIP", "PREROUTER_FEATURE_TOPK", "PREROUTER_INTRA",
+)
+
+
+def host_identity() -> dict:
+    """Which machine produced this phase.  A report without it reads the
+    same whether it came from the Orin or a workstation GPU, and this
+    script's results gate an Orin claim."""
+    import platform
+    out = {
+        "hostname_hash": hashlib.sha256(
+            platform.node().encode("utf-8")).hexdigest()[:16],
+        "machine": platform.machine(),
+        "system": platform.system(),
+        "python": platform.python_version(),
+        "gpu_name": None,
+        "compute_capability": None,
+        "torch_version": None,
+        "torch_cuda_version": None,
+        "jetson_model": None,
+        "unavailable_reasons": {},
+    }
+    try:
+        import torch
+        out["torch_version"] = str(torch.__version__)
+        out["torch_cuda_version"] = getattr(torch.version, "cuda", None)
+        if torch.cuda.is_available():
+            props = torch.cuda.get_device_properties(0)
+            out["gpu_name"] = props.name
+            out["compute_capability"] = f"{props.major}.{props.minor}"
+        else:
+            out["unavailable_reasons"]["gpu_name"] = "no CUDA device"
+            out["unavailable_reasons"]["compute_capability"] = "no CUDA device"
+    except Exception as exc:  # noqa: BLE001 - identity is best-effort
+        reason = f"{type(exc).__name__}: {exc}"
+        for key in ("torch_version", "torch_cuda_version", "gpu_name",
+                    "compute_capability"):
+            out["unavailable_reasons"].setdefault(key, reason)
+    try:
+        out["jetson_model"] = Path(
+            "/proc/device-tree/model").read_text(errors="replace").rstrip("\x00\n")
+    except OSError:
+        out["unavailable_reasons"]["jetson_model"] = (
+            "/proc/device-tree/model unreadable: not a Jetson")
+    if out["torch_cuda_version"] is None:
+        out["unavailable_reasons"].setdefault(
+            "torch_cuda_version", "torch build has no CUDA runtime")
+    return out
+
+
+# --------------------------------------------------------------- phases
+
+def _encode_prompt(engine, prompt: str) -> list[int]:
+    # Same chat templating as examples/bench.py (think=False).
+    tok = engine._tok
+    if hasattr(engine, "encode_chat"):
+        return [int(t) for t in engine.encode_chat(
+            [{"role": "user", "content": prompt}], think=False)]
+    return [int(t) for t in tok(tok.apply_chat_template(
+        [{"role": "user", "content": prompt}],
+        tokenize=False, add_generation_prompt=True,
+        enable_thinking=False))["input_ids"]]
+
+
+def _logits_to_numpy(logits):
+    import numpy as np
+    import torch
+    if isinstance(logits, torch.Tensor):
+        return logits.detach().reshape(-1).to("cpu", torch.float32).numpy()
+    return np.asarray(logits, dtype="float32").reshape(-1)
+
+
+def run_phase(model_dir: str, prompt: str, ntok: int, out_npz: str,
+              forced: list[int] | None) -> None:
+    """One engine pass on the device the environment selected.
+
+    ``forced is None``: greedy generation, logits captured at every step.
+    ``forced``: teacher-forcing — capture logits, then feed forced[i]
+    regardless of what this device would have chosen.
+    """
+    import numpy as np
+
+    from edge0 import AutoEngine
+
+    t0 = time.perf_counter()
+    engine = AutoEngine.from_pretrained(model_dir)
+    try:
+        ids = _encode_prompt(engine, prompt)
+        engine.reset()
+        engine.prefill(ids)
+        logits = engine.next_logits()
+        first = _logits_to_numpy(logits)
+        steps = [first]
+        tokens: list[int] = []
+        for i in range(ntok):
+            if forced is None:
+                tid = int(steps[-1].argmax())
+            else:
+                tid = int(forced[i])
+            tokens.append(tid)
+            if i < ntok - 1:
+                logits = engine.step(tid)
+                steps.append(_logits_to_numpy(logits))
+        evidence = {
+            "logits_class": type(logits).__name__,
+            "device": str(getattr(logits, "device", "unknown")),
+            "elapsed_s": time.perf_counter() - t0,
+            **host_identity(),
+            # every knob as this phase RESOLVED it, not just the CLI
+            # overrides: a value inherited from the shell would otherwise
+            # turn a same-device comparison into a self-comparison
+            "resolved_env": {k: os.environ[k] for k in RECORDED_ENV
+                             if k in os.environ},
+        }
+        np.savez_compressed(
+            out_npz, logits=np.stack(steps), tokens=np.asarray(tokens),
+            prompt_ids=np.asarray(ids))
+        Path(out_npz + ".meta.json").write_text(json.dumps(evidence))
+    finally:
+        engine.close()
+
+
+# --------------------------------------------------------------- compare
+
+def compare(test_npz: str, ref_npz: str, logit_tol: float,
+            near_tie_margin: float) -> dict:
+    import numpy as np
+
+    test = np.load(test_npz)
+    ref = np.load(ref_npz)
+    if not np.array_equal(test["prompt_ids"], ref["prompt_ids"]):
+        return {"pass": False, "error": "prompt ids differ between phases"}
+    if not np.array_equal(test["tokens"], ref["tokens"]):
+        return {"pass": False,
+                "error": "teacher phase did not replay the test tokens"}
+    a, b = test["logits"], ref["logits"]
+    if a.shape != b.shape:
+        return {"pass": False,
+                "error": f"logit shapes differ: {a.shape} vs {b.shape}"}
+    if not (np.isfinite(a).all() and np.isfinite(b).all()):
+        return {"pass": False, "error": "non-finite logits"}
+
+    steps = []
+    divergences = []
+    ok = True
+    for i in range(a.shape[0]):
+        diff = float(np.abs(a[i] - b[i]).max())
+        t_test = int(test["tokens"][i])          # what the test device chose
+        r_top = int(b[i].argmax())               # reference greedy choice
+        entry = {"step": i, "max_abs_logit_diff": diff,
+                 "test_token": t_test, "reference_token": r_top}
+        if diff > logit_tol:
+            entry["fail"] = f"logit diff {diff:.4g} > tol {logit_tol}"
+            ok = False
+        if t_test != r_top:
+            gap = float(b[i][r_top] - b[i][t_test])
+            entry["reference_gap"] = gap
+            near_tie = 0.0 <= gap <= near_tie_margin and diff <= logit_tol
+            entry["explained_near_tie"] = near_tie
+            divergences.append(entry)
+            if not near_tie:
+                entry.setdefault(
+                    "fail", f"token divergence with reference gap "
+                            f"{gap:.4g} > margin {near_tie_margin}")
+                ok = False
+        steps.append(entry)
+    diffs = [s["max_abs_logit_diff"] for s in steps]
+    return {
+        "pass": ok,
+        "steps_compared": len(steps),
+        "tokens_matched": len(steps) - len(divergences),
+        "divergences": divergences,
+        "max_abs_logit_diff": max(diffs),
+        "mean_abs_logit_diff_of_max": sum(diffs) / len(diffs),
+        "per_step": steps,
+    }
+
+
+# ----------------------------------------------------------- orchestrate
+
+def parse_env_overrides(items: list[str] | None) -> dict[str, str]:
+    """``KEY=VALUE`` pairs for one phase's environment (Task 6: run the
+    reference path and an opt-in path on the SAME device, e.g.
+    ``--test-env EDGE0_QMM_BATCHED=1``).  An empty value unsets the key."""
+    out: dict[str, str] = {}
+    for item in items or ():
+        key, sep, value = item.partition("=")
+        if not sep or not key.strip():
+            raise ValueError(f"expected KEY=VALUE, got {item!r}")
+        out[key.strip()] = value
+    return out
+
+
+def _spawn(device: str, argv: list[str],
+           overrides: dict[str, str] | None = None) -> None:
+    env = dict(os.environ)
+    env["EDGE0_BACKEND"] = "cuda"
+    env["EDGE0_TORCH_DEVICE"] = device
+    for key, value in (overrides or {}).items():
+        if value == "":
+            env.pop(key, None)
+        else:
+            env[key] = value
+    proc = subprocess.run([sys.executable, os.fspath(Path(__file__).resolve()),
+                           "--phase-internal", *argv], env=env)
+    if proc.returncode != 0:
+        raise RuntimeError(f"phase on device {device!r} failed "
+                           f"(exit {proc.returncode})")
+
+
+def main(argv: list[str] | None = None) -> int:
+    ap = argparse.ArgumentParser(description=__doc__.split("\n", 1)[0])
+    ap.add_argument("model", help="model directory or tier name")
+    ap.add_argument("--tokens", type=int, default=32)
+    ap.add_argument("--prompt", default=DEFAULT_PROMPT)
+    ap.add_argument("--test-device", default="cuda")
+    ap.add_argument("--reference-device", default="cpu")
+    ap.add_argument("--reference-npz", default=None,
+                    help="use pre-generated reference logits instead of "
+                         "running the reference device phase")
+    ap.add_argument("--logit-tol", type=float, default=1.0)
+    ap.add_argument("--near-tie-margin", type=float, default=1.0)
+    ap.add_argument("--test-env", action="append", metavar="KEY=VALUE",
+                    help="environment override for the TEST phase only "
+                         "(repeatable; empty value unsets), e.g. "
+                         "EDGE0_QMM_BATCHED=1 to check an opt-in path "
+                         "against the reference path on the same device")
+    ap.add_argument("--reference-env", action="append", metavar="KEY=VALUE",
+                    help="environment override for the REFERENCE phase only")
+    ap.add_argument("--output", required=True,
+                    help="JSON report path (must not exist)")
+    ap.add_argument("--phase-internal", action="store_true",
+                    help=argparse.SUPPRESS)
+    ap.add_argument("--phase-out", help=argparse.SUPPRESS)
+    ap.add_argument("--phase-forced", help=argparse.SUPPRESS)
+    args = ap.parse_args(argv)
+
+    if args.phase_internal:
+        forced = (json.loads(Path(args.phase_forced).read_text())
+                  if args.phase_forced else None)
+        run_phase(args.model, args.prompt, args.tokens, args.phase_out, forced)
+        return 0
+
+    if args.tokens < 32:
+        print("[reference-check] Gate B requires at least 32 tokens",
+              file=sys.stderr)
+        return 2
+    try:
+        test_env = parse_env_overrides(args.test_env)
+        reference_env = parse_env_overrides(args.reference_env)
+    except ValueError as exc:
+        print(f"[reference-check] {exc}", file=sys.stderr)
+        return 2
+    out = Path(args.output)
+    if out.exists():
+        print(f"[reference-check] refusing to overwrite {out}",
+              file=sys.stderr)
+        return 2
+    out.parent.mkdir(parents=True, exist_ok=True)
+
+    from examples import benchmark_measure as measure
+
+    model_dir = args.model
+    if not Path(model_dir).exists():
+        env_name = f"EDGE0_{args.model.split('-')[-1].upper()}_MODEL"
+        model_dir = os.environ.get(env_name, model_dir)
+    if not Path(model_dir).exists():
+        print(f"[reference-check] model not found: {args.model}",
+              file=sys.stderr)
+        return 2
+
+    work = out.parent / (out.stem + ".phases")
+    work.mkdir(exist_ok=True)
+    test_npz = str(work / f"test-{args.test_device}.npz")
+    ref_npz = args.reference_npz or str(
+        work / f"reference-{args.reference_device}.npz")
+
+    common = [model_dir, "--prompt", args.prompt,
+              "--tokens", str(args.tokens), "--output", "unused"]
+    print(f"[reference-check] phase 1/2: greedy {args.tokens} tokens on "
+          f"{args.test_device}"
+          + (f" with {test_env}" if test_env else ""))
+    _spawn(args.test_device, common + ["--phase-out", test_npz], test_env)
+
+    if not args.reference_npz:
+        import numpy as np
+        tokens = [int(t) for t in np.load(test_npz)["tokens"]]
+        forced_file = work / "forced-tokens.json"
+        forced_file.write_text(json.dumps(tokens))
+        print(f"[reference-check] phase 2/2: teacher-forcing on "
+              f"{args.reference_device}"
+              + (f" with {reference_env}" if reference_env else ""))
+        _spawn(args.reference_device,
+               common + ["--phase-out", ref_npz,
+                         "--phase-forced", str(forced_file)],
+               reference_env)
+
+    result = compare(test_npz, ref_npz, args.logit_tol, args.near_tie_margin)
+
+    same_device = (not args.reference_npz
+                   and args.test_device == args.reference_device)
+    phase_env = {
+        name: json.loads(Path(p + ".meta.json").read_text()).get(
+            "resolved_env", {})
+        for name, p in (("test", test_npz), ("reference", ref_npz))
+        if Path(p + ".meta.json").exists()}
+    env_differences = sorted(
+        set(phase_env.get("test", {}).items())
+        ^ set(phase_env.get("reference", {}).items()))
+    if same_device and not env_differences:
+        print("[reference-check] WARNING: same device and identical "
+              "resolved knobs in both phases: this compares a "
+              "configuration with itself and proves nothing",
+              file=sys.stderr)
+
+    report = {
+        "schema": "edge0-reference-check/2",
+        "timestamp_utc": datetime.now(timezone.utc).isoformat(),
+        "host": host_identity(),
+        "same_device_comparison": same_device,
+        "resolved_env_differences": [list(kv) for kv in env_differences],
+        "git": measure.git_identity(REPO_ROOT),
+        "model_dir": os.path.abspath(model_dir),
+        "checkpoint": measure.checkpoint_manifest(model_dir),
+        "prompt_sha256": hashlib.sha256(
+            args.prompt.encode("utf-8")).hexdigest(),
+        "prompt_text": args.prompt,
+        "tokens_requested": args.tokens,
+        "test_device": args.test_device,
+        "test_env": test_env,
+        "reference_device": (args.reference_device if not args.reference_npz
+                             else f"npz:{args.reference_npz}"),
+        "reference_env": reference_env,
+        "tolerances": {"logit_tol": args.logit_tol,
+                       "near_tie_margin": args.near_tie_margin},
+        "phase_evidence": {
+            name: json.loads(Path(p + ".meta.json").read_text())
+            for name, p in (("test", test_npz), ("reference", ref_npz))
+            if Path(p + ".meta.json").exists()},
+        "result": {k: v for k, v in result.items() if k != "per_step"},
+        "per_step": result.get("per_step"),
+    }
+    tmp = out.with_suffix(out.suffix + ".tmp")
+    tmp.write_text(json.dumps(report, indent=1, allow_nan=False))
+    tmp.rename(out)
+
+    verdict = "PASS" if result.get("pass") else "FAIL"
+    # ASCII only: this line is printed on whatever console the target has,
+    # and a Windows cp1252 stdout raises UnicodeEncodeError on "Δ" AFTER
+    # the report is already written -- turning a PASS into a crash.
+    print(f"[reference-check] {verdict}: "
+          f"{result.get('tokens_matched')}/{result.get('steps_compared')} "
+          f"tokens matched, max abs logit diff = "
+          f"{result.get('max_abs_logit_diff', float('nan')):.4g} "
+          f"(tol {args.logit_tol}); report: {out}")
+    if result.get("error"):
+        print(f"[reference-check] error: {result['error']}", file=sys.stderr)
+    return 0 if result.get("pass") else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())
diff --git a/src/edge0/backends/cuda/int4pack.py b/src/edge0/backends/cuda/int4pack.py
new file mode 100644
index 0000000..4713b15
--- /dev/null
+++ b/src/edge0/backends/cuda/int4pack.py
@@ -0,0 +1,185 @@
+"""torch's built-in int4 kernel for the dense quantized linears (Task 6,
+design A, opt-in ``EDGE0_INT4PACK=1``).
+
+``torch.ops.aten._weight_int4pack_mm`` (the gpt-fast / torchao path)
+runs a group-wise int4 x bfloat16 matmul on CUDA.  It wants the weight
+in its own tiled layout (``_convert_weight_to_int4pack`` of a
+``[n, k/2]`` uint8 tensor, high nibble first) and computes
+``w = (q - 8) * scale + zero`` from a ``[k/group, n, 2]`` bfloat16
+``scales_and_zeros`` tensor.  The MLX affine layout this repo stores
+(8 codes per uint32, least significant bits first, ``w = code * scale
++ bias``) maps onto it with ``zero = bias + 8 * scale``.
+
+That mapping is NOT exact: ``zero`` is rounded to bfloat16 and the
+kernel dequantizes in bfloat16, so its weights differ from the
+reference's own bfloat16-rounded weights by about one bfloat16 ulp for
+roughly a third of the entries (measured on torch 2.14.0+cu130, see
+``tests/test_int4pack.py`` for the pre-registered bounds).  The exact
+paths (the on-the-fly dequantization and both dequantized-weight
+caches) therefore take precedence in ``nn.QuantizedLinear``; this path
+is used only when the gate is on, nothing exact is cached for the
+module, and every guard in ``is_supported`` holds.  Whether the
+approximation is acceptable is decided by the 32-token reference check
+on the target device, not here.
+
+Costs: the repacked payload duplicates the int4 words it covers
+(``int4pack_extra_bytes``) -- the original buffers stay for the
+fall-through paths -- and the kernel accepts only 2-D bfloat16
+activations, so inputs are reshaped around the call.
+"""
+
+from __future__ import annotations
+
+import os
+
+import torch
+
+INT4PACK_ENV = "EDGE0_INT4PACK"
+#: ``_convert_weight_to_int4pack`` tiling; the kernel then needs
+#: ``in_features % (INNER_K_TILES * 16) == 0``.
+INNER_K_TILES = 8
+SUPPORTED_GROUP_SIZES = (32, 64, 128, 256)
+
+
+def _read_int4pack_gate() -> bool:
+    return os.environ.get(INT4PACK_ENV, "") == "1"
+
+
+#: Read once at import, like ``quant.BATCHED``; tests patch the attribute.
+INT4PACK = _read_int4pack_gate()
+
+
+# ---- pure repack (CPU or CUDA, exact) -------------------------------------------
+
+
+def codes_to_uint8(weight_u32: torch.Tensor) -> torch.Tensor:
+    """MLX-packed ``[..., k/8]`` uint32 (8 codes per word, least
+    significant bits first) -> ``[..., k/2]`` uint8 with the EVEN column's
+    code in the high nibble and the ODD column's in the low nibble (the
+    order ``_convert_weight_to_int4pack`` expects)."""
+    words = weight_u32.view(torch.int32)
+    shifts = torch.arange(8, device=words.device, dtype=torch.int32) * 4
+    codes = ((words.unsqueeze(-1) >> shifts) & 0xF)
+    codes = codes.reshape(*words.shape[:-1], words.shape[-1] * 8)
+    return ((codes[..., 0::2] << 4) | codes[..., 1::2]).to(torch.uint8)
+
+
+def uint8_to_codes(packed_u8: torch.Tensor) -> torch.Tensor:
+    """Inverse of ``codes_to_uint8``: ``[..., k/2]`` uint8 -> ``[..., k]``
+    int64 codes in [0, 15]."""
+    words = packed_u8.to(torch.int64)
+    hi = (words >> 4) & 0xF
+    lo = words & 0xF
+    return torch.stack([hi, lo], dim=-1).reshape(*words.shape[:-1],
+                                                 words.shape[-1] * 2)
+
+
+def codes_to_uint32(codes: torch.Tensor) -> torch.Tensor:
+    """``[..., k]`` codes -> the MLX packing (8 per uint32, LSB first)."""
+    grouped = codes.reshape(*codes.shape[:-1], -1, 8).to(torch.int64)
+    shifts = torch.arange(8, device=codes.device, dtype=torch.int64) * 4
+    words = (grouped << shifts).sum(-1)
+    return words.to(torch.int32).view(torch.uint32)
+
+
+def scales_and_zeros(scales: torch.Tensor, biases: torch.Tensor) -> torch.Tensor:
+    """``[n, k/group]`` scales/biases -> ``[k/group, n, 2]`` bfloat16
+    ``(scale, zero)`` with ``zero = bias + 8 * scale`` so that the kernel's
+    ``(q - 8) * scale + zero`` is the affine ``q * scale + bias``."""
+    s = scales.to(torch.float32)
+    z = biases.to(torch.float32) + 8.0 * s
+    return torch.stack([s.t(), z.t()], dim=-1).to(torch.bfloat16).contiguous()
+
+
+def zero_rounding_error(scales: torch.Tensor, biases: torch.Tensor) -> float:
+    """Largest |bf16(zero) - zero| the mapping introduces (reported, never
+    hidden: it is one of the two reasons the path is approximate)."""
+    z = biases.double() + 8.0 * scales.double()
+    return float((z.to(torch.bfloat16).double() - z).abs().max().item())
+
+
+def is_supported(*, in_features: int, out_features: int, group_size: int,
+                 bits: int, device_type: str, x_dtype) -> tuple[bool, str]:
+    """Guarded dispatch: every combination the kernel does not handle
+    falls through to the reference implementation."""
+    if bits != 4:
+        return False, f"{bits}-bit layout (kernel is int4 only)"
+    if group_size not in SUPPORTED_GROUP_SIZES:
+        return False, f"group_size {group_size} not in {SUPPORTED_GROUP_SIZES}"
+    if in_features % (INNER_K_TILES * 16) != 0:
+        return False, (f"in_features {in_features} is not a multiple of "
+                       f"{INNER_K_TILES * 16}")
+    if out_features % 8 != 0:
+        return False, f"out_features {out_features} is not a multiple of 8"
+    if device_type != "cuda":
+        return False, f"device {device_type!r} (CUDA kernel only)"
+    if x_dtype is not torch.bfloat16:
+        return False, f"activation dtype {x_dtype} (kernel takes bfloat16)"
+    return True, ""
+
+
+def int4pack_extra_bytes(out_features: int, in_features: int,
+                         group_size: int) -> int:
+    """Bytes the repacked payload adds next to the original buffers."""
+    return (out_features * in_features // 2
+            + (in_features // group_size) * out_features * 2 * 2)
+
+
+# ---- kernel (CUDA) --------------------------------------------------------------------
+
+
+class KernelUnavailable(RuntimeError):
+    """The device has no usable image for the kernel (e.g. a wheel whose
+    SASS list excludes this architecture).  Every guard passed, so the
+    caller falls through to the reference path and stops retrying."""
+
+
+def repack(weight_u32: torch.Tensor, scales: torch.Tensor,
+           biases: torch.Tensor, group_size: int):
+    """Build the kernel's operands from the MLX layout."""
+    packed_u8 = codes_to_uint8(weight_u32)
+    tiled = torch.ops.aten._convert_weight_to_int4pack(packed_u8, INNER_K_TILES)
+    return tiled, scales_and_zeros(scales, biases)
+
+
+def probe(device=None) -> tuple[bool, str]:
+    """Run the kernel once on a tiny tensor to prove the device actually
+    has an image for it.
+
+    ``is_supported`` checks shapes and dtypes; only execution proves the
+    build covers this architecture.  The Orin's torch wheel warns that
+    ``sm_87`` is outside its SASS list (CC 8.x binary compatibility is
+    expected to carry it, but the plan's rule is that execution evidence
+    gates, not the warning), so the dispatch probes before it commits.
+    """
+    try:
+        codes = torch.randint(0, 16, (8, 256), device=device)
+        packed = codes_to_uint32(codes)
+        scales = torch.ones(8, 4, dtype=torch.bfloat16, device=device)
+        biases = torch.zeros(8, 4, dtype=torch.bfloat16, device=device)
+        tiled, saz = repack(packed, scales, biases, 64)
+        x = torch.ones(1, 256, dtype=torch.bfloat16, device=device)
+        out = _int4pack_mm(x, tiled, 64, saz)
+        if device is not None and getattr(device, "type", device) == "cuda":
+            torch.cuda.synchronize()
+        if not torch.isfinite(out).all():
+            return False, "kernel probe produced non-finite output"
+    except Exception as exc:  # noqa: BLE001 - any failure disables the path
+        return False, f"kernel probe failed: {type(exc).__name__}: {exc}"
+    return True, ""
+
+
+def _int4pack_mm(x2d: torch.Tensor, tiled: torch.Tensor, group_size: int,
+                 saz: torch.Tensor) -> torch.Tensor:
+    return torch.ops.aten._weight_int4pack_mm(x2d, tiled, group_size, saz)
+
+
+def int4pack_linear(x: torch.Tensor, tiled: torch.Tensor, group_size: int,
+                    saz: torch.Tensor, bias: torch.Tensor | None = None):
+    """``F.linear`` on the repacked weight: reshape to the 2-D bfloat16
+    input the kernel takes and back."""
+    x2d = x.reshape(-1, x.shape[-1]).contiguous()
+    y = _int4pack_mm(x2d, tiled, group_size, saz)
+    if bias is not None:
+        y = y + bias.to(y.dtype)
+    return y.reshape(*x.shape[:-1], y.shape[-1])
diff --git a/src/edge0/backends/cuda/io.py b/src/edge0/backends/cuda/io.py
index e5dd816..f1332e6 100644
--- a/src/edge0/backends/cuda/io.py
+++ b/src/edge0/backends/cuda/io.py
@@ -19,7 +19,7 @@
 import torch
 
 from edge0.backends.base import TensorStore
-from edge0.backends.cuda.core import DEVICE, _as_tensor
+from edge0.backends.cuda.core import DEVICE
 
 _DTYPES = {
     "F64": torch.float64, "F32": torch.float32, "F16": torch.float16,
@@ -338,6 +338,7 @@ def _install_quantized(model, state: dict, dtype) -> set:
         if isinstance(mod, torch.nn.Linear):
             bias = state.pop(f"{path}.bias", None)
             new = cnn.QuantizedLinear(w, s, b, mod.in_features, bias=bias)
+            cnn.WEIGHT_CACHE.register(path, new)   # capped exact cache candidate
         elif isinstance(mod, torch.nn.Embedding):
             new = cnn.QuantizedEmbedding(w, s, b, mod.embedding_dim,
                                          dtype=dtype)
@@ -379,8 +380,6 @@ def load_model(model_path, lazy=True, strict=False, model_config=None,
     import json
     import os
 
-    import torch
-
     with open(os.path.join(os.fspath(model_path), "config.json")) as f:
         raw_config = json.load(f)
 
@@ -417,7 +416,12 @@ def load_model(model_path, lazy=True, strict=False, model_config=None,
         _undo_mlx_qwen35_sanitize(state)
     if engine_path and hasattr(model, "sanitize"):
         state = model.sanitize(state)
+    from edge0.backends.cuda import nn as _cnn
+    _cnn.WEIGHT_CACHE.begin()                 # one model per process
     quantized = _install_quantized(model, state, dtype)
+    # Admit against the requested cap now; the 8B engine re-finalizes
+    # against the memory budget's headroom once that is resolved.
+    _cnn.WEIGHT_CACHE.finalize()
     for k, t in state.items():
         if dtype is not None and t.is_floating_point():
             state[k] = t.to(dtype)
diff --git a/src/edge0/backends/cuda/nn.py b/src/edge0/backends/cuda/nn.py
index 1134ee9..424150b 100644
--- a/src/edge0/backends/cuda/nn.py
+++ b/src/edge0/backends/cuda/nn.py
@@ -7,16 +7,33 @@
 here under the contract's names rather than assuming call sites import
 ``torch.nn`` directly (see ``backends/__init__.py``'s enforcement that
 framework code only ever imports ``edge0.backends.{core,nn,io,quant}``).
+
+The quantized modules keep the 4-bit payload resident and dequantize on
+the fly.  Three opt-in alternatives exist for the dense linears, tried
+in this order in ``QuantizedLinear.forward`` (exact ones first):
+
+* ``EDGE0_TORCH_WEIGHT_CACHE=1`` -- keep EVERY weight dequantized
+  (bit-identical to on-the-fly; ~1.9 GB in bf16 for edge0-8b's dense
+  modules, 4.1 GB in float32 as measured on the GB10);
+* ``EDGE0_TORCH_WEIGHT_CACHE_BYTES=<n>`` -- keep only the modules that
+  fit a byte cap (``WeightCachePolicy``: first-fit in registration
+  order, re-finalized by the engine against the Task 4 budget's
+  headroom, recorded in the bench report);
+* ``EDGE0_INT4PACK=1`` -- torch's built-in int4 kernel (see
+  ``int4pack.py``; approximate at bfloat16 rounding, guarded).
 """
 
 from __future__ import annotations
 
 import os
+from typing import Any
 
 import torch
 import torch.nn as _tnn
 import torch.nn.functional as F
 
+from edge0.backends.cuda import int4pack as _i4
+
 Module = _tnn.Module
 
 
@@ -66,14 +83,183 @@ def _quant_params(weight, scales, in_features):
 #: Off by default: the whole point of the quantized layers is that the
 #: 4-bit payload is what stays resident. Worth turning on where memory is
 #: plentiful: on a GB10 it takes the edge0-8b decode step from 206 ms to
-#: 124 ms a token, for 4.1 GB more resident (EDGE0_TORCH_WEIGHT_CACHE=1).
+#: 124 ms a token, for a measured 4.1 GB more resident
+#: (EDGE0_TORCH_WEIGHT_CACHE=1). For this tier the dequantized weights
+#: themselves are 1.40 GB in bf16 (``WeightCachePolicy`` prices them from
+#: the loaded modules); the difference is allocator segments the fill
+#: leaves behind, which is why the fill is chunked.
 CACHE_DEQUANTIZED = os.environ.get("EDGE0_TORCH_WEIGHT_CACHE", "") == "1"
 
+WEIGHT_CACHE_BYTES_ENV = "EDGE0_TORCH_WEIGHT_CACHE_BYTES"
+
+
+def _read_weight_cache_cap() -> int | None:
+    """``None`` when unset (policy off); ``0`` also means off."""
+    raw = os.environ.get(WEIGHT_CACHE_BYTES_ENV, "").strip()
+    if not raw:
+        return None
+    try:
+        value = int(raw)
+    except ValueError:
+        raise ValueError(
+            f"{WEIGHT_CACHE_BYTES_ENV} must be an integer byte count, got "
+            f"{raw!r}") from None
+    if value < 0:
+        raise ValueError(f"{WEIGHT_CACHE_BYTES_ENV} must be >= 0, got {value}")
+    return value
+
+
+def dequantized_bytes(module, itemsize: int | None = None) -> int:
+    """Bytes a module's dequantized weight occupies once cached (activation
+    itemsize defaults to the checkpoint's scales dtype, bf16 for the
+    shipped tiers)."""
+    if itemsize is None:
+        itemsize = module.scales.element_size()
+    return module.out_features * module.in_features * itemsize
+
+
+def fill_transient_bytes(module) -> int:
+    """Peak EXTRA bytes of building one cached weight, on top of the
+    resident result.
+
+    The fill runs ``ROWS_PER_CHUNK`` rows at a time, so the transient is
+    bounded by the chunk, not by the module: ``_dequantize`` keeps four
+    float32-sized tensors of one chunk live at its peak, plus the
+    float32 casts of that chunk's scales and biases, plus the chunk's
+    converted result before it is written into the buffer.  Measured at
+    edge0-8b's widest module (lm_head, 157184 x 1536) on torch
+    2.14.0+cu130: 556.9 MiB of total peak against a 460.5 MiB resident
+    result.  Whole-weight dequantization instead peaks at 3702 MiB for
+    the same module, which is why the fill is chunked.
+    """
+    rows = min(QuantizedLinear.ROWS_PER_CHUNK, module.out_features)
+    in_features = module.in_features
+    itemsize = module.scales.element_size()
+    groups = -(-in_features // module.group_size)
+    chain = 4 * rows * in_features * 4
+    scale_terms = 2 * rows * groups * (itemsize + 4)
+    chunk_result = rows * in_features * itemsize
+    return chain + scale_terms + chunk_result
+
+
+_UNSET: Any = object()
+
+
+class WeightCachePolicy:
+    """Capped, exact dequantized-weight cache: which ``QuantizedLinear``
+    modules keep their dequantized weight.
+
+    Candidates are registered by the loader in model order; ``finalize``
+    admits them first-fit until ``cap_bytes`` is used, sets
+    ``module.cache_weight`` and records the decision.  Re-finalizing with a
+    smaller cap (the engine does this once the Task 4 budget resolves)
+    releases weights the new selection no longer covers, so nothing stale
+    survives.  ``None`` / ``0`` means off: no module is admitted.
+    """
+
+    def __init__(self, cap_bytes: int | None = None):
+        self.cap_bytes = cap_bytes
+        self._candidates: list[tuple[str, Any, int]] = []
+        self._summary: dict | None = None
+
+    @classmethod
+    def from_env(cls) -> "WeightCachePolicy":
+        return cls(_read_weight_cache_cap())
+
+    @property
+    def enabled(self) -> bool:
+        return bool(self.cap_bytes)
+
+    def begin(self) -> None:
+        """A new model load starts: forget the previous model's modules."""
+        self._candidates = []
+        self._summary = None
+
+    def register(self, path: str, module) -> None:
+        self._candidates.append((path, module, dequantized_bytes(module)))
+
+    def candidate_bytes_total(self) -> int:
+        return sum(nbytes for _, _, nbytes in self._candidates)
+
+    def max_fill_transient_bytes(self, admitted_only: bool = True) -> int:
+        """Largest build transient among the modules that will be filled
+        (zero when none is admitted).  The fills happen lazily at the first
+        forward, AFTER the budget's observation point, so this is what the
+        budget must still have room for."""
+        chosen = [m for _, m, _ in self._candidates
+                  if not admitted_only or getattr(m, "cache_weight", False)]
+        return max((fill_transient_bytes(m) for m in chosen), default=0)
+
+    def finalize(self, cap_bytes=_UNSET) -> dict:
+        cap = self.cap_bytes if cap_bytes is _UNSET else cap_bytes
+        enabled = bool(cap)
+        admitted, skipped, used = [], [], 0
+        for path, module, nbytes in self._candidates:
+            # Each module must fit with its OWN build transient: the fills
+            # are sequential, so only one is ever live, but a module whose
+            # fill does not fit would OOM at the first forward even though
+            # its resident bytes fit the cap.
+            fill = fill_transient_bytes(module)
+            if enabled and used + nbytes + fill <= cap:
+                module.cache_weight = True
+                used += nbytes
+                admitted.append({"path": path, "bytes": nbytes,
+                                 "fill_transient_bytes": fill})
+                continue
+            if getattr(module, "cache_weight", False):
+                module._dequantized = None      # dropped: release, not stale
+            module.cache_weight = False
+            skipped.append({
+                "path": path, "bytes": nbytes,
+                "reason": ("policy off" if not enabled else
+                           f"does not fit: {used + nbytes + fill:,} "
+                           f"(incl. {fill:,} build transient) > cap {cap:,}"),
+            })
+        self._summary = {
+            "enabled": enabled,
+            "requested_cap_bytes": (self.cap_bytes if self.cap_bytes is not None
+                                    else cap),
+            "effective_cap_bytes": cap,
+            "admitted_bytes": used,
+            "max_fill_transient_bytes": self.max_fill_transient_bytes(),
+            "admitted": admitted,
+            "skipped": skipped,
+            "candidate_bytes_total": self.candidate_bytes_total(),
+            "candidate_count": len(self._candidates),
+            "finalized": True,
+        }
+        return self._summary
+
+    def summary(self) -> dict:
+        if self._summary is not None:
+            return self._summary
+        return {
+            "enabled": self.enabled,
+            "requested_cap_bytes": self.cap_bytes,
+            "effective_cap_bytes": None,
+            "admitted_bytes": 0,
+            "max_fill_transient_bytes": 0,
+            "admitted": [],
+            "skipped": [],
+            "candidate_bytes_total": self.candidate_bytes_total(),
+            "candidate_count": len(self._candidates),
+            "finalized": False,
+        }
+
+
+#: Process-wide policy, filled by ``io.load_model`` (one model per process).
+WEIGHT_CACHE = WeightCachePolicy.from_env()
+
 
 class QuantizedLinear(_tnn.Module):
     """``mlx.nn.QuantizedLinear`` layout (``weight`` packed uint32,
     ``scales``, ``biases``) dequantized on the fly -- the 4-bit payload
-    stays resident, not a bf16 copy (unless ``CACHE_DEQUANTIZED``)."""
+    stays resident, not a bf16 copy (unless ``CACHE_DEQUANTIZED`` or the
+    ``WeightCachePolicy`` admitted this module)."""
+
+    weight: torch.Tensor      # buffers (declared for type checkers)
+    scales: torch.Tensor
+    biases: torch.Tensor
 
     def __init__(self, weight, scales, biases, in_features, bias=None):
         super().__init__()
@@ -85,24 +271,83 @@ def __init__(self, weight, scales, biases, in_features, bias=None):
         self.register_buffer("biases", biases)
         self.bias = None if bias is None else _tnn.Parameter(bias, False)
         self._dequantized = None          # (dtype, weight), see forward
+        #: set by WeightCachePolicy.finalize; priced at the scales' itemsize
+        self.cache_weight = False
+        self._priced_itemsize = scales.element_size()
+        self._int4pack = None             # (tiled weight, scales_and_zeros)
+        #: falsy while usable; the reason string once the kernel proved
+        #: unusable on this device (never retried afterwards)
+        self._int4pack_disabled = ""
 
     ROWS_PER_CHUNK = 4096
 
+    def int4pack_bytes(self) -> int:
+        """Extra resident bytes of the repacked int4 payload (0 until the
+        kernel path has been used)."""
+        if self._int4pack is None:
+            return 0
+        return _i4.int4pack_extra_bytes(self.out_features, self.in_features,
+                                        self.group_size)
+
+    def _int4pack_eligible(self, x) -> bool:
+        if self._int4pack_disabled or x.dtype is not torch.bfloat16 \
+                or x.device.type != "cuda":
+            return False
+        if self._int4pack is not None:
+            return True
+        if self.weight.device.type != "cuda" or x.shape[-1] != self.in_features:
+            return False
+        ok, _reason = _i4.is_supported(
+            in_features=self.in_features, out_features=self.out_features,
+            group_size=self.group_size, bits=self.bits,
+            device_type=x.device.type, x_dtype=x.dtype)
+        if not ok:
+            return False
+        # Shapes and dtypes are not enough: prove the device has an image
+        # for the kernel before committing to it (once per module).
+        usable, reason = _i4.probe(x.device)
+        if not usable:
+            self._int4pack_disabled = reason
+            return False
+        return True
+
     def forward(self, x):
         """Dequantize ``ROWS_PER_CHUNK`` output rows at a time: the full
         float weight of a large projection is never materialized (edge0-8b's
         lm_head alone would be ~1 GB per call). Same arithmetic per
         element as dequantizing everything first."""
         from edge0.backends.cuda.quant import _dequantize
-        if CACHE_DEQUANTIZED:
-            # Same weight every call: dequantize once. The chunking below
-            # exists to bound the transient, which a kept weight makes moot.
+        if CACHE_DEQUANTIZED or (self.cache_weight
+                                 and x.element_size() == self._priced_itemsize):
+            # Same weight every call: dequantize once.  Fill it CHUNKED
+            # into a preallocated buffer -- element for element the same
+            # arithmetic as the on-the-fly path below, but bounding the
+            # build transient to one chunk: whole-weight dequantization of
+            # edge0-8b's lm_head peaks at 3.7 GB for a 0.46 GB result,
+            # which does not fit an 8 GB Orin's headroom
+            # (``fill_transient_bytes`` prices what this costs instead).
             if self._dequantized is None or self._dequantized[0] != x.dtype:
-                w = _dequantize(self.weight, self.scales, self.biases,
-                                self.group_size, self.bits).to(x.dtype)
+                w = torch.empty(self.out_features, self.in_features,
+                                dtype=x.dtype, device=self.weight.device)
+                for r in range(0, self.out_features, self.ROWS_PER_CHUNK):
+                    sl = slice(r, r + self.ROWS_PER_CHUNK)
+                    w[sl] = _dequantize(self.weight[sl], self.scales[sl],
+                                        self.biases[sl], self.group_size,
+                                        self.bits).to(x.dtype)
                 self._dequantized = (x.dtype, w)
             b = None if self.bias is None else self.bias.to(x.dtype)
             return F.linear(x, self._dequantized[1], b)
+        if _i4.INT4PACK and self._int4pack_eligible(x):
+            try:
+                if self._int4pack is None:
+                    self._int4pack = _i4.repack(self.weight, self.scales,
+                                                self.biases, self.group_size)
+                tiled, saz = self._int4pack
+                return _i4.int4pack_linear(x, tiled, self.group_size, saz,
+                                           bias=self.bias)
+            except RuntimeError as exc:   # no image, or a shape the kernel
+                self._int4pack = None     # rejects at runtime: fall through
+                self._int4pack_disabled = f"{type(exc).__name__}: {exc}"
         outs = []
         for r in range(0, self.out_features, self.ROWS_PER_CHUNK):
             sl = slice(r, r + self.ROWS_PER_CHUNK)
@@ -118,6 +363,10 @@ class QuantizedEmbedding(_tnn.Module):
     dequantized. Output dtype: ``dtype``, else the scales' (the
     checkpoint's)."""
 
+    weight: torch.Tensor      # buffers (declared for type checkers)
+    scales: torch.Tensor
+    biases: torch.Tensor
+
     def __init__(self, weight, scales, biases, embedding_dim, dtype=None):
         super().__init__()
         self.num_embeddings = weight.shape[0]
diff --git a/src/edge0/backends/cuda/quant.py b/src/edge0/backends/cuda/quant.py
index 3201c4e..5f65bf9 100644
--- a/src/edge0/backends/cuda/quant.py
+++ b/src/edge0/backends/cuda/quant.py
@@ -16,14 +16,70 @@
 * ``sorted_indices`` is a kernel hint in MLX; it never changes the values.
   Ignored here.
 
-Not fast: every call dequantizes the gathered experts in full. The point
-is a correct, testable reference for the streaming path.
+Two implementations share those semantics:
+
+* the reference loop: one distinct expert at a time, each dequantized in
+  full to float32 and multiplied -- correct, testable, and the one every
+  other path is compared against.  ``EDGE0_QMM_BATCHED=0`` selects it;
+* the batched path (Task 6, **default on this backend**): the same
+  float32 arithmetic with ONE dequantization over the distinct experts
+  and ONE batched matmul over a padded per-expert slab, instead of a
+  python loop of ``len(unique)`` dequantize+matmul pairs.  Only affine
+  4-bit takes it; 2/8-bit layouts and any call whose priced transient
+  exceeds ``EDGE0_QMM_BATCHED_MAX_BYTES`` (default 256 MiB) fall through
+  to the reference loop.  The transient is bounded and priced
+  (``batched_transient_bytes``) so the Task 4 budget deducts it.
+
+The default was flipped on the Orin's Task 6 acceptance evidence, which
+is what Gate D asks for before a path becomes default: measured benefit
+on the target (decode +21%, three independent launches) plus the
+pre-registered 32-token reference check PASSING there (32/32 token
+choices identical, max |delta logit| 0.777 against the registered bound
+of 1.0) -- and a second GPU generation agreeing in direction (+59% on an
+RTX PRO 6000).  The arithmetic is the same expression per element; it
+lands within one bfloat16 ulp of the reference loop at the real decode
+shapes, which is why the check passes rather than merely not crashing.
 """
 
 from __future__ import annotations
 
+import os
+
 import torch
 
+BATCHED_ENV = "EDGE0_QMM_BATCHED"
+BATCHED_MAX_BYTES_ENV = "EDGE0_QMM_BATCHED_MAX_BYTES"
+DEFAULT_BATCHED_MAX_BYTES = 256 << 20
+
+
+def _read_batched_gate() -> bool:
+    """On by default (see the module docstring for the evidence that
+    flipped it); ``EDGE0_QMM_BATCHED=0`` selects the reference loop.
+    Any other value is treated as unset, so a typo cannot silently
+    change the path."""
+    return os.environ.get(BATCHED_ENV, "").strip() != "0"
+
+
+def _read_batched_max_bytes() -> int:
+    raw = os.environ.get(BATCHED_MAX_BYTES_ENV, "").strip()
+    if not raw:
+        return DEFAULT_BATCHED_MAX_BYTES
+    try:
+        value = int(raw)
+    except ValueError:
+        raise ValueError(
+            f"{BATCHED_MAX_BYTES_ENV} must be an integer byte count, got "
+            f"{raw!r}") from None
+    if value < 0:
+        raise ValueError(f"{BATCHED_MAX_BYTES_ENV} must be >= 0, got {value}")
+    return value
+
+
+#: Read once at import, like ``nn.CACHE_DEQUANTIZED``; tests patch the
+#: module attributes.  A malformed cap fails the import visibly.
+BATCHED = _read_batched_gate()
+BATCHED_MAX_BYTES = _read_batched_max_bytes()
+
 
 def _dequantize(w: torch.Tensor, scales: torch.Tensor, biases: torch.Tensor,
                 group_size: int, bits: int) -> torch.Tensor:
@@ -42,14 +98,38 @@ def _dequantize(w: torch.Tensor, scales: torch.Tensor, biases: torch.Tensor,
     return deq.reshape(codes.shape)
 
 
-def gather_qmm(x, w, scales, biases, rhs_indices, transpose=True,
-               group_size=64, bits=4, mode="affine",
-               sorted_indices=False):
-    """Quantized matmul over a gathered subset of experts (``mx.gather_qmm``)."""
-    if mode != "affine" or bits not in (2, 4, 8):
-        raise NotImplementedError(
-            f"reference gather_qmm covers affine 2/4/8-bit only "
-            f"(got mode={mode!r}, bits={bits!r})")
+def batched_transient_bytes(n_unique: int, rows_max: int, m: int, d_in: int,
+                            n_out: int, bits: int = 4, group_size: int = 64,
+                            scale_itemsize: int = 2) -> int:
+    """Upper bound on the extra bytes ``_gather_qmm_batched`` allocates for
+    one call (freed on return): the gathered packed words, the int32 code
+    tensors and float32 dequantized copies the ``_dequantize`` chain keeps
+    live (four float32-sized tensors of ``n_unique * n_out * d_in``), the
+    gathered scales/biases and their float32 casts, and the padded
+    input/output slabs.  Pure arithmetic, checked against allocator peaks
+    in ``tests/test_quant_paths.py``."""
+    for name, value in (("n_unique", n_unique), ("rows_max", rows_max),
+                        ("m", m), ("d_in", d_in), ("n_out", n_out),
+                        ("group_size", group_size),
+                        ("scale_itemsize", scale_itemsize)):
+        if isinstance(value, bool) or not isinstance(value, int) or value <= 0:
+            raise ValueError(f"{name} must be a positive int, got {value!r}")
+    per_expert = n_out * d_in
+    packed = n_unique * per_expert * bits // 8
+    chain = 4 * n_unique * per_expert * 4
+    groups = -(-d_in // group_size)
+    scale_terms = 2 * n_unique * n_out * groups * (scale_itemsize + 4)
+    slabs = 2 * n_unique * rows_max * m * (d_in + n_out) * 4
+    return packed + chain + scale_terms + slabs
+
+
+def _gather_qmm_reference(x, w, scales, biases, rhs_indices, transpose,
+                          group_size, bits):
+    """One distinct expert at a time (the reference every other path is
+    compared against).  Dequantizing a copy per (token, expert) pair
+    peaked at several GB per MoE layer during prefill, hence per expert.
+    An index past the last expert raises here; in MLX it silently reads
+    out of bounds."""
     idx = rhs_indices.to(torch.long)
     bshape = torch.broadcast_shapes(x.shape[:-2], idx.shape)
     M = x.shape[-2]
@@ -57,9 +137,6 @@ def gather_qmm(x, w, scales, biases, rhs_indices, transpose=True,
     flat = idx.expand(bshape).reshape(-1)
     n_out = w.shape[-2] if transpose else w.shape[-1] * (32 // bits)
     out = torch.empty(flat.numel(), M, n_out, dtype=torch.float32, device=x.device)
-    # One distinct expert at a time: dequantizing a copy per (token, expert)
-    # pair peaked at several GB per MoE layer during prefill. An index past
-    # the last expert raises here; in MLX it silently reads out of bounds.
     for e in torch.unique(flat).tolist():
         rows = (flat == e).nonzero().squeeze(-1)
         deq = _dequantize(w[e], scales[e], biases[e], group_size, bits)
@@ -67,6 +144,77 @@ def gather_qmm(x, w, scales, biases, rhs_indices, transpose=True,
     return out.reshape(*bshape, M, n_out).to(x.dtype)
 
 
+def _gather_qmm_batched(x, w, scales, biases, rhs_indices, transpose,
+                        group_size, bits):
+    """Same result as the reference loop with one dequantization and one
+    batched matmul; ``None`` when the priced transient exceeds the cap
+    (the caller then runs the reference loop)."""
+    idx = rhs_indices.to(torch.long)
+    bshape = torch.broadcast_shapes(x.shape[:-2], idx.shape)
+    M = x.shape[-2]
+    D = x.shape[-1]
+    n_out = w.shape[-2] if transpose else w.shape[-1] * (32 // bits)
+    flat = idx.expand(bshape).reshape(-1)
+    R = flat.numel()
+    if R == 0:
+        return torch.empty(*bshape, M, n_out, dtype=x.dtype, device=x.device)
+    uniq, inverse = torch.unique(flat, return_inverse=True)
+    n_experts = w.shape[0]
+    if int(uniq.max()) >= n_experts:
+        raise IndexError(
+            f"expert index {int(uniq.max())} out of range for {n_experts} "
+            f"experts")
+    U = uniq.numel()
+    counts = torch.bincount(inverse, minlength=U)
+    rows_max = int(counts.max())
+    priced = batched_transient_bytes(U, rows_max, M, D, n_out, bits,
+                                     group_size, scales.element_size())
+    if priced > BATCHED_MAX_BYTES:
+        return None
+
+    xf = x.to(torch.float32).expand(*bshape, M, D).reshape(-1, M, D)
+    # One dequantization over the distinct experts.  Index the int32 view:
+    # CUDA has no index kernel for uint32 (see nn.QuantizedEmbedding), and
+    # _dequantize reads the words as int32 anyway.
+    deq = _dequantize(w.view(torch.int32)[uniq], scales[uniq], biases[uniq],
+                      group_size, bits)                        # [U, out, in]
+    wmat = deq.transpose(1, 2) if transpose else deq          # [U, in, out]
+    order = torch.argsort(inverse, stable=True)               # rows by expert
+    grouped = inverse[order]
+    if rows_max == 1:
+        # decode: every distinct expert has exactly one row, no padding
+        y = torch.matmul(xf[order], wmat)                     # [U, M, out]
+        out = torch.empty(R, M, n_out, dtype=torch.float32, device=x.device)
+        out[order] = y
+        return out.reshape(*bshape, M, n_out).to(x.dtype)
+    starts = torch.cumsum(counts, 0) - counts                 # [U]
+    slot = torch.arange(R, device=flat.device) - starts[grouped]
+    slab = xf.new_zeros(U, rows_max, M, D)
+    slab[grouped, slot] = xf[order]
+    y = torch.matmul(slab.reshape(U, rows_max * M, D), wmat)
+    y = y.reshape(U, rows_max, M, n_out)[grouped, slot]        # [R, M, out]
+    out = torch.empty(R, M, n_out, dtype=torch.float32, device=x.device)
+    out[order] = y
+    return out.reshape(*bshape, M, n_out).to(x.dtype)
+
+
+def gather_qmm(x, w, scales, biases, rhs_indices, transpose=True,
+               group_size=64, bits=4, mode="affine",
+               sorted_indices=False):
+    """Quantized matmul over a gathered subset of experts (``mx.gather_qmm``)."""
+    if mode != "affine" or bits not in (2, 4, 8):
+        raise NotImplementedError(
+            f"reference gather_qmm covers affine 2/4/8-bit only "
+            f"(got mode={mode!r}, bits={bits!r})")
+    if BATCHED and bits == 4:
+        out = _gather_qmm_batched(x, w, scales, biases, rhs_indices,
+                                  transpose, group_size, bits)
+        if out is not None:
+            return out
+    return _gather_qmm_reference(x, w, scales, biases, rhs_indices,
+                                 transpose, group_size, bits)
+
+
 def gather_sort(x, indices):
     """Sort token rows by expert id for ``gather_qmm(sorted_indices=True)``:
     returns ``(x_sorted, indices_sorted, inv_order)``, as mlx-lm's
diff --git a/src/edge0/engine/ling.py b/src/edge0/engine/ling.py
index fb24049..5a65cde 100644
--- a/src/edge0/engine/ling.py
+++ b/src/edge0/engine/ling.py
@@ -29,10 +29,179 @@
 )
 from edge0.prerouter.install import install_prerouter
 from edge0.prerouter.stager import LingPrerouterStager
+from edge0.streaming import budget as _budget
+from edge0.streaming.cache import PrefetchBuffer, SharedExpertCache
 from edge0.streaming.install import install_streaming_experts
 from edge0.streaming.mmap import SafetensorsMmap
 
 
+def _apply_env_profile(cfg, opts, spec):
+    """Task 5 opt-in profile knobs, applied to the REQUESTED options
+    before the budget prices them (the budget may still lower them).
+
+    ``EDGE0_CACHE_SLOTS=<int>``: request a different shared-LRU size.
+    The tested default (64) is smaller than the per-step working set on
+    this tier (23 MoE layers x K=8 = 184 bundles), so it never hits;
+    512 measured a 65% hit rate on the Orin baseline (evidence in the
+    plan's Task 5 status).
+
+    ``EDGE0_PREDICT_PREFETCH=1``: enable
+    ``LayerOptions.predict_prefetch``; the prefetch buffer is raised to
+    hold one full predicted step (owners x K) and the per-layer
+    in-flight bound defaults to K, both priced by the budget.
+    """
+    from dataclasses import replace as _dc_replace
+    env_slots = os.environ.get("EDGE0_CACHE_SLOTS", "").strip()
+    if env_slots:
+        try:
+            slots = int(env_slots)
+        except ValueError:
+            raise ValueError(
+                f"EDGE0_CACHE_SLOTS must be an integer, got "
+                f"{env_slots!r}") from None
+        if slots <= 0:
+            raise ValueError(
+                f"EDGE0_CACHE_SLOTS must be positive, got {slots} "
+                "(0 would disable eviction, not caching)")
+        opts = _dc_replace(opts, cache_slots=slots)
+    if os.environ.get("EDGE0_PREDICT_PREFETCH", "") == "1":
+        opts = _dc_replace(opts, predict_prefetch=True)
+    if opts.predict_prefetch:
+        owners_n = len(getattr(cfg.prerouter, "owners", ()) or ())
+        per_layer = opts.top_k or spec.top_k
+        opts = _dc_replace(
+            opts,
+            prefetch_cap=max(opts.prefetch_cap, owners_n * per_layer),
+            max_inflight=opts.max_inflight or per_layer)
+    return opts
+
+
+def _torch_quant_modules():
+    """``(nn, quant)`` of the torch backend, ``(None, None)`` on MLX."""
+    from edge0.backends import backend
+    if backend.name != "cuda":
+        return None, None
+    from edge0.backends.cuda import nn as cnn
+    from edge0.backends.cuda import quant as cq
+    return cnn, cq
+
+
+def _resolve_memory_budget(cfg, opts, shards):
+    """Resolve the Task 4 memory budget when ``EDGE0_MEMORY_BUDGET`` asks
+    for one; return ``None`` when it is off (the default — behavior is
+    then exactly the pre-budget code path).
+
+    ``EDGE0_MEMORY_BUDGET`` accepts ``auto`` (observe MemAvailable and
+    any tighter address-space rlimit at this point, right before cache
+    construction) or an explicit byte count.  The declared context comes
+    from ``EDGE0_BUDGET_CONTEXT`` (tokens, default 1024): contexts
+    beyond the declaration are a different workload and must be
+    re-declared, not discovered as an OOM.
+    """
+    req = os.environ.get("EDGE0_MEMORY_BUDGET", "").strip()
+    if not req:
+        return None
+    if req == "auto":
+        import psutil
+        available = int(psutil.virtual_memory().available)
+        limit = None
+        try:
+            import resource
+            soft, _hard = resource.getrlimit(resource.RLIMIT_AS)
+            if soft not in (-1, resource.RLIM_INFINITY):
+                limit = int(soft)
+        except (ImportError, OSError, ValueError):
+            limit = None
+        obs = _budget.Observation(available_bytes=available,
+                                  process_limit_bytes=limit)
+    else:
+        try:
+            obs = _budget.Observation(available_bytes=int(req))
+        except ValueError:
+            raise _budget.BudgetError(
+                f"EDGE0_MEMORY_BUDGET must be 'auto' or a byte count, "
+                f"got {req!r}") from None
+    spec = cfg.moe_spec
+    # Layer 0 is dense on this tier; layer 1 carries the expert tensors.
+    entries = {}
+    for shard in shards:
+        entries.update(shard.entries)
+    bundle = _budget.bundle_bytes_from_entries(
+        entries, spec.key_template.format(layer=1), spec.num_experts)
+    if not cfg.kv_bytes_per_token:
+        raise _budget.BudgetError(
+            f"{cfg.name}: kv_bytes_per_token is not measured for this "
+            "tier; a memory budget cannot price the declared context")
+    context = int(os.environ.get("EDGE0_BUDGET_CONTEXT", "1024"))
+    top_k = opts.top_k or spec.top_k
+    # In-flight transient: per-layer bound x layers that can be
+    # producing at once.  With predict_prefetch every owner layer may
+    # hold a step's predictions in flight; otherwise only the thread
+    # pool's builds are outstanding.
+    per_layer_inflight = opts.max_inflight or max(1, opts.prefetch_threads)
+    if opts.predict_prefetch:
+        producing_layers = len(getattr(cfg.prerouter, "owners", ()) or ())
+        inflight_total = max(1, per_layer_inflight * producing_layers)
+    else:
+        inflight_total = per_layer_inflight
+    # The dense dequantized-weight cache: the full cache (measured 4.1 GB
+    # in float32 on the GB10; the loader now prices the actual bf16 total
+    # of this tier's QuantizedLinear modules) is only ever vetoed by the
+    # budget, never enabled; the capped cache (Task 6) is shrunk to the
+    # headroom.  The batched expert gather's per-call transient cap is
+    # deducted once when that path is on.
+    weight_cache_requested = (
+        os.environ.get("EDGE0_TORCH_WEIGHT_CACHE", "") == "1")
+    cnn, cq = _torch_quant_modules()
+    candidate_total = cnn.WEIGHT_CACHE.candidate_bytes_total() if cnn else 0
+    request = _budget.dense_cache_request(
+        full_requested=weight_cache_requested,
+        cap_bytes=cnn.WEIGHT_CACHE.cap_bytes if cnn else None,
+        candidate_total=candidate_total,
+        max_fill_transient_bytes=(
+            cnn.WEIGHT_CACHE.max_fill_transient_bytes(admitted_only=False)
+            if cnn else 0))
+    kernel_transient = int(cq.BATCHED_MAX_BYTES) if (cq and cq.BATCHED) else 0
+    resolved = _budget.resolve_budget(
+        obs,
+        _budget.ExpertFootprint(
+            bundle_bytes=bundle, num_experts=spec.num_experts,
+            num_moe_layers=23),
+        _budget.WorkloadDecl(max_context_tokens=context,
+                             kv_bytes_per_token=cfg.kv_bytes_per_token),
+        requested_cache_slots=opts.cache_slots,
+        requested_prefetch_cap=opts.prefetch_cap,
+        full_layer_prefill=opts.full_layer_prefill,
+        inflight_builds=inflight_total,
+        min_cache_slots=2 * top_k,
+        weight_cache_bytes=(request["priced_bytes"]
+                            if request["mode"] != "off" else None),
+        reserves=_budget.Reserves(kernel_transient_bytes=kernel_transient),
+        )
+    if request["mode"] == "full" and not resolved.weight_cache_permitted:
+        raise _budget.BudgetError(
+            "EDGE0_TORCH_WEIGHT_CACHE=1 rejected: the dequantized dense "
+            f"weights ({request['resident_bytes']:,} bytes resident plus a "
+            f"{request['fill_transient_bytes']:,} byte build transient) do "
+            f"not fit the resolved headroom of {resolved.headroom_bytes:,} "
+            f"bytes "
+            f"(budget: {resolved.as_dict()})")
+    if request["mode"] == "capped" and cnn is not None:
+        from dataclasses import replace as _dc_replace
+        # The policy admits each module with its own build transient, so
+        # the effective cap is the headroom itself.
+        effective = _budget.effective_capped_bytes(
+            cap_bytes=request["cap_bytes"],
+            headroom_bytes=resolved.headroom_bytes)
+        summary = cnn.WEIGHT_CACHE.finalize(effective)
+        resolved = _dc_replace(resolved, notes=resolved.notes + (
+            f"capped weight cache: requested {request['cap_bytes']:,} B, "
+            f"effective {effective:,} B, admitted "
+            f"{summary['admitted_bytes']:,} B in "
+            f"{len(summary['admitted'])} modules",))
+    return resolved
+
+
 def _get_model_classes(config):
     """load_model class hook: serve the active backend's port of the bailing
     backbone (imported here so the module itself imports without MLX)."""
@@ -65,8 +234,33 @@ def load_installed(model_dir: str, cfg):
     spec = cfg.moe_spec
     opts = cfg.options
     n_layers = model_config["num_hidden_layers"]
+    opts = _apply_env_profile(cfg, opts, spec)
+    resolved_budget = _resolve_memory_budget(cfg, opts, shards)
+    shared_cache = prefetch_buffer = None
+    if resolved_budget is not None:
+        from dataclasses import replace as _dc_replace
+        # cache/prefetch capacities come from the budget; the in-flight
+        # bound stays PER-LAYER (the budget priced the total across
+        # producing layers, see _resolve_memory_budget).
+        opts = _dc_replace(
+            opts, cache_slots=resolved_budget.cache_slots,
+            prefetch_cap=resolved_budget.prefetch_cap,
+            max_inflight=(opts.max_inflight
+                          or max(1, opts.prefetch_threads)))
+        shared_cache = SharedExpertCache(resolved_budget.cache_slots)
+        prefetch_buffer = PrefetchBuffer(
+            resolved_budget.prefetch_cap,
+            max_cap=resolved_budget.max_prefetch_cap)
+        print(f"[edge0-8b] memory budget: usable="
+              f"{resolved_budget.usable_bytes:,}B cache_slots="
+              f"{resolved_budget.cache_slots} prefetch_cap="
+              f"{resolved_budget.prefetch_cap} headroom="
+              f"{resolved_budget.headroom_bytes:,}B"
+              + (f" notes={list(resolved_budget.notes)}"
+                 if resolved_budget.notes else ""), flush=True)
     installed = install_streaming_experts(
-        model, shards, spec, options=opts, num_layers=n_layers)
+        model, shards, spec, options=opts, num_layers=n_layers,
+        shared_cache=shared_cache, prefetch_buffer=prefetch_buffer)
     all_stream = {li: t for li, t in enumerate(installed) if t is not None}
     stream_layers = {li: t for li, t in all_stream.items() if t._staged_mode}
 
@@ -78,16 +272,22 @@ def load_installed(model_dir: str, cfg):
     if cfg.prerouter and cfg.prerouter.weights_file:
         pg_state, heads = install_prerouter(
             model=model, spec=spec, pspec=cfg.prerouter, n_layers=n_layers)
+        prefetch_layers = None
+        if opts.predict_prefetch:
+            prefetch_layers = {li: t for li, t in all_stream.items()
+                               if not t._staged_mode}
         pg_stager = LingPrerouterStager(
             model=model, spec=spec, pspec=cfg.prerouter,
             state=pg_state, stream_layers=stream_layers,
-            top_k=cfg.prerouter_top_k)
+            top_k=cfg.prerouter_top_k,
+            prefetch_layers=prefetch_layers)
         print(f"[edge0-8b] prerouter installed: {len(heads)} heads, "
               f"start={cfg.prerouter.start_layer}, "
               f"K={cfg.prerouter_top_k}", flush=True)
     installs = dict(all_stream_layers=all_stream,
                     stream_layers=stream_layers,
-                    pg_state=pg_state, pg_stager=pg_stager)
+                    pg_state=pg_state, pg_stager=pg_stager,
+                    memory_budget=resolved_budget)
     return model, model_config, shards, installs
 
 
@@ -118,6 +318,9 @@ def _build(self):
         self._stream_layers = inst["stream_layers"]
         self._pg_state = inst["pg_state"]
         self._pg_stager = inst["pg_stager"]
+        #: Resolved Task 4 memory budget (None when EDGE0_MEMORY_BUDGET
+        #: is off); the bench report's caches group records it.
+        self.memory_budget = inst["memory_budget"]
         opts = cfg.options
         if self._tok is None:
             try:
diff --git a/src/edge0/models/base.py b/src/edge0/models/base.py
index 09a14b9..f0c4fb7 100644
--- a/src/edge0/models/base.py
+++ b/src/edge0/models/base.py
@@ -62,6 +62,11 @@ class ModelConfig:
     # acceptance profile (measured on the production Mac)
     target_tok_s: float = 0.0
     peak_active_mem_mb: float = 0.0
+    #: Measured KV-cache growth per context token (bytes), used by the
+    #: memory-budgeted profile (EDGE0_MEMORY_BUDGET) to price the
+    #: declared context.  0 = not measured for this tier; a requested
+    #: budget then fails loudly instead of guessing.
+    kv_bytes_per_token: int = 0
 
     @classmethod
     def from_pretrained(cls, model_dir: str | None = None, **overrides):
diff --git a/src/edge0/models/edge0_8b/__init__.py b/src/edge0/models/edge0_8b/__init__.py
index 7c8f4db..fdd3b4b 100644
--- a/src/edge0/models/edge0_8b/__init__.py
+++ b/src/edge0/models/edge0_8b/__init__.py
@@ -69,6 +69,19 @@ def _defaults(cls, model_dir: str) -> "Ling8BConfig":
             port=8083,
             target_tok_s=33.0,
             peak_active_mem_mb=1400.0,
+            # MEASURED on the torch backend (Orin, Task 7): the marginal
+            # cost between 1536 and 2048 tokens is 561,320 B/token
+            # (548 KiB), recorded in the evidence set; 600,000 keeps ~7%
+            # margin.  Growth is sublinear below that — most layers of
+            # this hybrid are KDA, whose state is fixed-size, so only the
+            # MLA layers' KV grows with context — which is why the
+            # marginal slope at the top of the range is the right
+            # constant to extrapolate a declared context from.
+            # The previous 1,100,000 came from the README's Apple/MLX
+            # figure and over-reserved by ~2x, rejecting contexts that
+            # fit.  Over-reserving is safe but shrinks the envelope, so
+            # it is corrected from the measurement, not from the doc.
+            kv_bytes_per_token=600_000,
         )
 
 
diff --git a/src/edge0/prerouter/stager.py b/src/edge0/prerouter/stager.py
index e47b65f..56d3955 100644
--- a/src/edge0/prerouter/stager.py
+++ b/src/edge0/prerouter/stager.py
@@ -65,12 +65,17 @@ def __init__(
         state: PrerouterState,
         stream_layers: dict[int, StreamingSwitchGLU],
         top_k: int,
+        prefetch_layers: dict[int, StreamingSwitchGLU] | None = None,
     ):
         self.model = model
         self.spec = spec
         self.pspec = pspec
         self.state = state
         self.stream_layers = stream_layers
+        #: Non-staged layers whose predicted expert sets are routed to
+        #: ``prefetch()`` (LayerOptions.predict_prefetch).  Scheduling
+        #: only: the exact consumption path is untouched.
+        self.prefetch_layers = prefetch_layers or {}
         self.top_k = top_k
         self.num_experts = spec.num_experts
         self.records: list | None = None
@@ -190,10 +195,12 @@ class LingPrerouterStager(PrerouterStager):
 
     def __init__(self, *, model, spec: MoESpec, pspec: PrerouterSpec,
                  state: PrerouterState,
-                 stream_layers: dict[int, StreamingSwitchGLU], top_k: int):
+                 stream_layers: dict[int, StreamingSwitchGLU], top_k: int,
+                 prefetch_layers: dict[int, StreamingSwitchGLU]
+                 | None = None):
         super().__init__(model=model, spec=spec, pspec=pspec,
                          state=state, stream_layers=stream_layers,
-                         top_k=top_k)
+                         top_k=top_k, prefetch_layers=prefetch_layers)
         self.pg_cache: dict[int, core.array] = {}
 
     def _head_of(self, owner: int):
@@ -232,6 +239,15 @@ def _store(self, consumer: int, logits_i, inds_i, scores_i,
         exp = self.stream_layers.get(consumer)
         if exp is not None:
             exp.stage_experts(experts)
+            return
+        # Non-staged consumer (prod profiles): overlap the predicted
+        # next-step builds with the current forward.  prefetch() is
+        # bounded (max_inflight / prefetch buffer caps) and consumption
+        # stays on the exact _get_bundles path — a wrong or late
+        # prediction is just a demand load, never a zero row.
+        pre = self.prefetch_layers.get(consumer)
+        if pre is not None:
+            pre.prefetch(experts)
 
     def _note(self, owner: int, cur_oh) -> None:
         block = self.spec.block_of(self.model, owner)
diff --git a/src/edge0/streaming/__init__.py b/src/edge0/streaming/__init__.py
index 8e412b0..5ea6592 100644
--- a/src/edge0/streaming/__init__.py
+++ b/src/edge0/streaming/__init__.py
@@ -1,9 +1,14 @@
 """Streaming expert offload: mmap stores, shared LRU caches, staged
-decode slots, whole-layer prefill and hot-expert pins."""
+decode slots, whole-layer prefill and hot-expert pins.
+
+``StreamingSwitchGLU`` and ``install_streaming_experts`` bind to the
+active backend at import; they are exposed lazily (PEP 562) so the
+backend-free modules (``cache``, ``options``, ``budget``, ``mmap``)
+stay importable on hosts with no backend installed — the Task 4 budget
+tests run everywhere.
+"""
 
 from edge0.streaming.cache import PrefetchBuffer, SharedExpertCache
-from edge0.streaming.install import install_streaming_experts
-from edge0.streaming.layer import StreamingSwitchGLU
 from edge0.streaming.mmap import SafetensorsMmap
 from edge0.streaming.options import LayerOptions
 
@@ -15,3 +20,19 @@
     "LayerOptions",
     "install_streaming_experts",
 ]
+
+_LAZY = {
+    "StreamingSwitchGLU": ("edge0.streaming.layer", "StreamingSwitchGLU"),
+    "install_streaming_experts": ("edge0.streaming.install",
+                                  "install_streaming_experts"),
+}
+
+
+def __getattr__(name):
+    try:
+        module_name, attr = _LAZY[name]
+    except KeyError:
+        raise AttributeError(
+            f"module {__name__!r} has no attribute {name!r}") from None
+    import importlib
+    return getattr(importlib.import_module(module_name), attr)
diff --git a/src/edge0/streaming/budget.py b/src/edge0/streaming/budget.py
new file mode 100644
index 0000000..61f3737
--- /dev/null
+++ b/src/edge0/streaming/budget.py
@@ -0,0 +1,339 @@
+"""Memory-budgeted streaming profile (pure calculation).
+
+Task 4 of ``docs/plans/jetson-orin-nano.md``: turn an OBSERVED amount of
+memory into explicit byte allowances for everything the streaming stack
+retains or transiently allocates, and refuse impossible profiles before
+inference instead of OOMing during it.
+
+Everything here is pure: the caller supplies observations (available
+RAM, process limits), checkpoint-derived payload sizes and the declared
+workload; this module only does arithmetic and policy.  No psutil, no
+torch, no engine imports — see ``engine/ling.py`` for the integration
+that gathers the inputs.
+
+Accounting rules (Gate C):
+
+* Start from observed available RAM, tightened by any process limit.
+* Deduct, each exactly once: an OS/application growth reserve; KV cache
+  at the DECLARED maximum context; the prefill transient (whole-layer
+  load-drop materializes every expert of one layer at once when
+  ``full_layer_prefill`` is on); in-flight expert builds (bounded by
+  the resolved ``max_inflight``, not the thread count alone); pinned
+  staging (Task 5 — zero today); the batched expert gather's per-call
+  transient cap (Task 6 — zero unless ``EDGE0_QMM_BATCHED=1``); and an
+  allocator/driver allowance (fraction of the observed total, applied
+  once).
+* What remains is the retained-cache allowance, split between the
+  shared LRU and the prefetch buffer in payload bytes computed from
+  checkpoint metadata — slot counts alone are meaningless.
+* ``SharedExpertCache(0)`` and ``PrefetchBuffer(0)`` DISABLE eviction
+  (unbounded).  A calculated zero is therefore never passed through:
+  any allowance that cannot fit the minimum working set raises
+  ``BudgetError`` with the itemized deductions.
+* The budget only ever LOWERS the profile's requested capacities.  A
+  budget roomier than the tested profile keeps the tested values.
+* Full dequantized-weight caching (``EDGE0_TORCH_WEIGHT_CACHE``) is
+  reported as permitted only when its measured payload fits in the
+  allowance that remains AFTER the caches — it is never turned on by
+  this module, only vetoed.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+class BudgetError(ValueError):
+    """The declared workload cannot fit the observed memory."""
+
+
+def _positive_int(name: str, value) -> int:
+    if isinstance(value, bool) or not isinstance(value, int):
+        raise BudgetError(f"{name} must be an int, got {value!r}")
+    if value <= 0:
+        raise BudgetError(f"{name} must be positive, got {value}")
+    return value
+
+
+def _non_negative_int(name: str, value) -> int:
+    if isinstance(value, bool) or not isinstance(value, int):
+        raise BudgetError(f"{name} must be an int, got {value!r}")
+    if value < 0:
+        raise BudgetError(f"{name} must be >= 0, got {value}")
+    return value
+
+
+@dataclass(frozen=True)
+class Observation:
+    """What was actually observed on the target, at the observation
+    point (immediately before engine construction — allocations already
+    resident at that point are outside ``available_bytes`` by
+    definition and must not be deducted again)."""
+
+    available_bytes: int
+    #: A tighter limit than system RAM when one exists (cgroup,
+    #: rlimit); None means no separate limit was observed.
+    process_limit_bytes: int | None = None
+
+    def usable(self) -> int:
+        avail = _positive_int("available_bytes", self.available_bytes)
+        if self.process_limit_bytes is None:
+            return avail
+        return min(avail,
+                   _positive_int("process_limit_bytes",
+                                 self.process_limit_bytes))
+
+
+@dataclass(frozen=True)
+class ExpertFootprint:
+    """Per-expert payload from checkpoint metadata (see
+    ``bundle_bytes_from_entries``)."""
+
+    bundle_bytes: int
+    num_experts: int
+    num_moe_layers: int
+
+
+@dataclass(frozen=True)
+class WorkloadDecl:
+    """The declared operating envelope.  KV for ``max_context_tokens``
+    is deducted up front: a context the budget did not declare is a
+    different workload and must be re-resolved, not discovered OOM."""
+
+    max_context_tokens: int
+    kv_bytes_per_token: int
+
+
+@dataclass(frozen=True)
+class Reserves:
+    os_growth_bytes: int = 512 * 1024 * 1024
+    #: Allocator + driver allowance as a fraction of the usable
+    #: observation, deducted once.
+    allocator_fraction: float = 0.10
+    #: Task 5's pinned staging pool; zero until it exists.
+    pinned_staging_bytes: int = 0
+    #: Task 6's batched expert gather: the per-call transient cap
+    #: (``EDGE0_QMM_BATCHED_MAX_BYTES``) when that path is on, else zero.
+    kernel_transient_bytes: int = 0
+
+
+@dataclass(frozen=True)
+class ResolvedBudget:
+    """The resolved policy, with its arithmetic shown."""
+
+    usable_bytes: int
+    deductions: tuple  # ((name, bytes), ...) in application order
+    cache_allowance_bytes: int
+    cache_slots: int
+    cache_bytes: int
+    prefetch_cap: int
+    prefetch_bytes: int
+    #: Hard ceiling for ``PrefetchBuffer.set_cap`` growth
+    #: (``prefetch_all`` raises the cap to num_experts + 32 otherwise).
+    max_prefetch_cap: int
+    max_inflight: int
+    weight_cache_permitted: bool
+    weight_cache_bytes: int | None
+    headroom_bytes: int
+    notes: tuple = ()
+
+    def as_dict(self) -> dict:
+        reasons = {}
+        if self.weight_cache_bytes is None:
+            reasons["weight_cache_bytes"] = (
+                "no dequantized-weight cache was requested "
+                "(EDGE0_TORCH_WEIGHT_CACHE unset)")
+        return {
+            "unavailable_reasons": reasons,
+            "usable_bytes": self.usable_bytes,
+            "deductions": [list(d) for d in self.deductions],
+            "cache_allowance_bytes": self.cache_allowance_bytes,
+            "cache_slots": self.cache_slots,
+            "cache_bytes": self.cache_bytes,
+            "prefetch_cap": self.prefetch_cap,
+            "prefetch_bytes": self.prefetch_bytes,
+            "max_prefetch_cap": self.max_prefetch_cap,
+            "max_inflight": self.max_inflight,
+            "weight_cache_permitted": self.weight_cache_permitted,
+            "weight_cache_bytes": self.weight_cache_bytes,
+            "headroom_bytes": self.headroom_bytes,
+            "notes": list(self.notes),
+        }
+
+
+def dense_cache_request(*, full_requested: bool, cap_bytes,
+                        candidate_total: int,
+                        max_fill_transient_bytes: int = 0) -> dict:
+    """What the budget prices for the dense dequantized-weight cache
+    (Task 6).
+
+    The price is the RESIDENT bytes the cache keeps plus the largest
+    single build transient: the weights are filled lazily at the first
+    forward, one chunked module at a time, so exactly one transient is
+    live but it must still fit alongside everything resident.
+
+    ``full`` (``EDGE0_TORCH_WEIGHT_CACHE=1``) prices the loader's measured
+    total of every ``QuantizedLinear`` (the GB10's 4.1 GB figure only when
+    no model is loaded yet) and keeps its veto; ``capped``
+    (``EDGE0_TORCH_WEIGHT_CACHE_BYTES``) prices ``min(cap, total)`` and is
+    later shrunk to the headroom instead of vetoed; ``off`` prices nothing.
+    """
+    fill = _non_negative_int("max_fill_transient_bytes",
+                             max_fill_transient_bytes)
+    if full_requested:
+        resident = candidate_total or 4_100_000_000
+        return {"mode": "full", "priced_bytes": resident + fill,
+                "resident_bytes": resident, "fill_transient_bytes": fill,
+                "cap_bytes": None}
+    if cap_bytes:
+        resident = min(int(cap_bytes), candidate_total)
+        return {"mode": "capped", "priced_bytes": resident + fill,
+                "resident_bytes": resident, "fill_transient_bytes": fill,
+                "cap_bytes": int(cap_bytes)}
+    return {"mode": "off", "priced_bytes": 0, "resident_bytes": 0,
+            "fill_transient_bytes": 0, "cap_bytes": None}
+
+
+def effective_capped_bytes(*, cap_bytes: int, headroom_bytes: int) -> int:
+    """The capped cache never exceeds the budget's post-cache headroom."""
+    return max(0, min(int(cap_bytes), int(headroom_bytes)))
+
+
+def bundle_bytes_from_entries(entries: dict, key_prefix: str,
+                              num_experts: int,
+                              projections=("gate_proj", "up_proj",
+                                           "down_proj"),
+                              parts=("weight", "scales", "biases")) -> int:
+    """Per-expert payload bytes for one layer, from a safetensors header.
+
+    ``entries`` maps tensor name to ``{"size": bytes, ...}`` (the
+    ``SafetensorsMmap.entries`` shape) or directly to an int size.
+    Expert tensors are stacked ``[num_experts, ...]``; the per-expert
+    payload is the summed tensor size divided by the expert count.
+    """
+    _positive_int("num_experts", num_experts)
+    total = 0
+    for proj in projections:
+        for part in parts:
+            name = f"{key_prefix}.{proj}.{part}"
+            if name not in entries:
+                raise BudgetError(
+                    f"checkpoint metadata is missing {name!r}; cannot "
+                    "compute the expert payload from slot counts alone")
+            meta = entries[name]
+            size = meta["size"] if isinstance(meta, dict) else meta
+            total += _positive_int(f"size of {name}", size)
+    if total % num_experts:
+        # Not fatal — round up so the budget never undercounts.
+        return total // num_experts + 1
+    return total // num_experts
+
+
+def resolve_budget(
+    observation: Observation,
+    experts: ExpertFootprint,
+    workload: WorkloadDecl,
+    *,
+    requested_cache_slots: int,
+    requested_prefetch_cap: int,
+    full_layer_prefill: bool,
+    inflight_builds: int,
+    min_cache_slots: int | None = None,
+    weight_cache_bytes: int | None = None,
+    reserves: Reserves = Reserves(),
+) -> ResolvedBudget:
+    """Resolve the streaming memory policy for one engine build.
+
+    Raises ``BudgetError`` when the declared workload cannot fit — with
+    the itemized deductions, so the failure is a review artifact rather
+    than a mystery OOM.  ``min_cache_slots`` defaults to the larger of
+    2 and the per-step working set the caller declares; the shared LRU
+    is never resolved below it and never to zero.
+    """
+    bundle = _positive_int("bundle_bytes", experts.bundle_bytes)
+    n_experts = _positive_int("num_experts", experts.num_experts)
+    _positive_int("num_moe_layers", experts.num_moe_layers)
+    slots_req = _positive_int("requested_cache_slots", requested_cache_slots)
+    cap_req = _positive_int("requested_prefetch_cap", requested_prefetch_cap)
+    inflight = _positive_int("inflight_builds", inflight_builds)
+    min_slots = (2 if min_cache_slots is None
+                 else _positive_int("min_cache_slots", min_cache_slots))
+    if weight_cache_bytes is not None:
+        _non_negative_int("weight_cache_bytes", weight_cache_bytes)
+    if not 0.0 <= reserves.allocator_fraction < 1.0:
+        raise BudgetError(
+            f"allocator_fraction must be in [0, 1), got "
+            f"{reserves.allocator_fraction!r}")
+
+    usable = observation.usable()
+    kv_bytes = (_non_negative_int("max_context_tokens",
+                                  workload.max_context_tokens)
+                * _positive_int("kv_bytes_per_token",
+                                workload.kv_bytes_per_token))
+    prefill_transient = bundle * n_experts if full_layer_prefill else 0
+    inflight_bytes = bundle * inflight
+    deductions = (
+        ("os_growth_reserve", _non_negative_int(
+            "os_growth_bytes", reserves.os_growth_bytes)),
+        ("allocator_allowance", int(usable * reserves.allocator_fraction)),
+        ("kv_cache_at_declared_context", kv_bytes),
+        ("full_layer_prefill_transient", prefill_transient),
+        ("inflight_expert_builds", inflight_bytes),
+        ("pinned_staging", _non_negative_int(
+            "pinned_staging_bytes", reserves.pinned_staging_bytes)),
+        ("kernel_transient", _non_negative_int(
+            "kernel_transient_bytes", reserves.kernel_transient_bytes)),
+    )
+    allowance = usable - sum(d[1] for d in deductions)
+    if allowance <= 0:
+        detail = ", ".join(f"{n}={b:,}" for n, b in deductions)
+        raise BudgetError(
+            f"declared workload does not fit: usable={usable:,} bytes, "
+            f"deductions leave {allowance:,} ({detail})")
+
+    # Shared LRU first (correctness path), prefetch from the remainder.
+    cache_slots = min(slots_req, allowance // bundle)
+    if cache_slots < min_slots:
+        raise BudgetError(
+            f"cache allowance {allowance:,} bytes fits only "
+            f"{cache_slots} expert bundles of {bundle:,} bytes — below "
+            f"the minimum working set of {min_slots}; a zero/starved "
+            f"cache is rejected, not constructed (SharedExpertCache(0) "
+            f"would disable eviction entirely)")
+    cache_bytes = cache_slots * bundle
+    prefetch_cap = min(cap_req, (allowance - cache_bytes) // bundle)
+    notes = []
+    if prefetch_cap < 1:
+        # An explicit bounded floor, never PrefetchBuffer(0): one slot
+        # keeps the buffer's eviction semantics intact and costs one
+        # bundle, which min_cache_slots' margin covers.
+        prefetch_cap = 1
+        notes.append("prefetch_cap floored to 1 (0 disables eviction)")
+    prefetch_bytes = prefetch_cap * bundle
+    if cache_slots < slots_req:
+        notes.append(
+            f"cache_slots lowered {slots_req} -> {cache_slots} by budget")
+    if prefetch_cap < cap_req:
+        notes.append(
+            f"prefetch_cap lowered {cap_req} -> {prefetch_cap} by budget")
+
+    headroom = allowance - cache_bytes - prefetch_bytes
+    permitted = (weight_cache_bytes is not None
+                 and weight_cache_bytes <= headroom)
+    return ResolvedBudget(
+        usable_bytes=usable,
+        deductions=deductions,
+        cache_allowance_bytes=allowance,
+        cache_slots=cache_slots,
+        cache_bytes=cache_bytes,
+        prefetch_cap=prefetch_cap,
+        prefetch_bytes=prefetch_bytes,
+        # prefetch_all may not grow the buffer past what the budget
+        # priced in; without a budget it grows to num_experts + 32.
+        max_prefetch_cap=prefetch_cap,
+        max_inflight=inflight,
+        weight_cache_permitted=permitted,
+        weight_cache_bytes=weight_cache_bytes,
+        headroom_bytes=headroom,
+        notes=tuple(notes),
+    )
diff --git a/src/edge0/streaming/cache.py b/src/edge0/streaming/cache.py
index d426768..b3eb518 100644
--- a/src/edge0/streaming/cache.py
+++ b/src/edge0/streaming/cache.py
@@ -56,11 +56,22 @@ class PrefetchBuffer:
     it (it is then promoted into the shared LRU by the caller).
     """
 
-    def __init__(self, cap: int = 48):
-        self.cap = max(0, cap)
+    def __init__(self, cap: int = 48, max_cap: int | None = None):
+        # ``max_cap`` is a hard ceiling for later ``set_cap`` growth
+        # (``prefetch_all`` raises the cap to num_experts + 32 on its
+        # own); a memory budget passes the ceiling it priced in.  None
+        # keeps the historical unbounded-growth semantics.
+        self.max_cap = max_cap
+        self.cap = self._clamp(cap)
         self._buf = OrderedDict()
         self._lock = threading.Lock()
 
+    def _clamp(self, cap: int) -> int:
+        cap = max(0, cap)
+        if self.max_cap is not None:
+            cap = min(cap, self.max_cap)
+        return cap
+
     def put(self, key, bundle):
         with self._lock:
             self._buf[key] = bundle
@@ -78,4 +89,4 @@ def contains(self, key) -> bool:
             return key in self._buf
 
     def set_cap(self, cap: int):
-        self.cap = max(0, cap)
+        self.cap = self._clamp(cap)
diff --git a/src/edge0/streaming/layer.py b/src/edge0/streaming/layer.py
index 78a330f..2c0767a 100644
--- a/src/edge0/streaming/layer.py
+++ b/src/edge0/streaming/layer.py
@@ -94,6 +94,7 @@ def __init__(
         self.hot_decay = o.hot_decay
         self._pin_bonus = o.pin_bonus
         self._use_compile = o.use_compile
+        self._max_inflight = o.max_inflight
 
         self._pool = ThreadPoolExecutor(max_workers=o.load_threads)
         self._prefetch_pool = ThreadPoolExecutor(
@@ -469,6 +470,13 @@ def prefetch(self, experts):
                 ):
                     continue
                 missing.append(e)
+            limit = self._max_inflight
+            if limit is not None:
+                # Speculative builds only: the queue may not outrun the
+                # budget's priced-in transient.  Demand loads
+                # (_get_bundles) are never dropped by this bound.
+                room = max(0, limit - len(self._inflight))
+                missing = missing[:room]
             for e in missing:
                 fut = self._prefetch_pool.submit(self._build, e)
                 self._inflight[e] = fut
diff --git a/src/edge0/streaming/options.py b/src/edge0/streaming/options.py
index 34a27a3..397727c 100644
--- a/src/edge0/streaming/options.py
+++ b/src/edge0/streaming/options.py
@@ -42,6 +42,20 @@ class LayerOptions:
             selecting hot pins.
         cache_slots: shared LRU capacity across all layers.
         prefetch_cap: prefetch buffer capacity.
+        max_inflight: per-layer bound on QUEUED speculative prefetch
+            builds (None = unbounded, the historical behavior).  Demand
+            loads are never dropped; a memory budget sets this so the
+            producer queue cannot outrun the priced-in transient.
+        predict_prefetch: route each step's prerouter predictions into
+            ``prefetch()`` for NON-staged layers (the prod profiles),
+            overlapping next-step expert builds with the current
+            forward.  Scheduling only: consumption stays on the exact
+            ``_get_bundles`` path (late/wrong predictions fall back to
+            demand loads; no staged zero rows).  Default off — on the
+            Orin the unoptimized decode is compute-bound and the
+            measured end-to-end benefit was below noise (see
+            docs/plans/jetson-orin-nano.md Task 5); revisit once the
+            Task 6 kernel work shrinks compute.
         load_threads: threads for on-demand expert builds.
         prefetch_threads: threads for eager prefetch builds.
         use_compile: wrap the MoE math in ``mx.compile``.
@@ -69,6 +83,8 @@ class LayerOptions:
     pin_bonus: float = 2.0
     cache_slots: int = 64
     prefetch_cap: int = 48
+    max_inflight: int | None = None
+    predict_prefetch: bool = False
     load_threads: int = 8
     prefetch_threads: int = 4
     use_compile: bool = True
diff --git a/tests/conftest.py b/tests/conftest.py
new file mode 100644
index 0000000..9a398b8
--- /dev/null
+++ b/tests/conftest.py
@@ -0,0 +1,18 @@
+"""Repo-wide pytest options.
+
+``--require-cuda`` turns the CUDA smoke suite's environment skips into
+hard failures (Task 3, Gate B: the acceptance invocation must fail if
+CUDA is required but absent, rather than quietly skipping).  Without the
+flag every suite keeps its current skip behavior, so plain ``pytest``
+on a host without torch or a GPU is unchanged.
+"""
+
+from __future__ import annotations
+
+
+def pytest_addoption(parser):
+    parser.addoption(
+        "--require-cuda", action="store_true", default=False,
+        help="fail (instead of skip) tests that need a working torch CUDA "
+             "device; the Orin acceptance contract from "
+             "docs/plans/jetson-orin-nano.md Task 3")
diff --git a/tests/test_bench_backend.py b/tests/test_bench_backend.py
new file mode 100644
index 0000000..ea4fb70
--- /dev/null
+++ b/tests/test_bench_backend.py
@@ -0,0 +1,187 @@
+"""``examples/bench.py`` on a real backend namespace (still no weights).
+
+``tests/test_bench_cli.py`` covers the benchmark with fakes only; this
+module repeats the core cases through the actual ``core`` ops and the
+actual sampler of whichever backend is importable, so a real-array
+regression (dtype, device, argmax semantics) is caught.  On a host
+without MLX and with torch installed the torch backend is selected on the
+CPU unless the environment already chose otherwise; with neither, the
+module is skipped.  A CPU/MPS result here is an instrumentation check,
+not CUDA or Orin evidence.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from types import SimpleNamespace
+
+import pytest
+
+if "EDGE0_BACKEND" not in os.environ:
+    try:
+        import mlx.core  # type: ignore[import-not-found]  # noqa: F401
+    except ImportError:
+        os.environ["EDGE0_BACKEND"] = "cuda"
+        os.environ.setdefault("EDGE0_TORCH_DEVICE", "cpu")
+
+pytest.importorskip(
+    "edge0.backends",
+    reason="needs an importable edge0 backend: MLX, or torch (EDGE0_BACKEND=cuda)")
+
+from edge0.backends import backend, core  # noqa: E402
+from edge0.config import GenerationConfig  # noqa: E402
+from edge0.streaming.options import LayerOptions  # noqa: E402
+from examples import bench  # noqa: E402
+from examples import benchmark_report as br  # noqa: E402
+from tests.test_bench_cli import (  # noqa: E402
+    HUMAN_LINE,
+    FakeTok,
+    RecordingMeasurement,
+    _kinds,
+    _match,
+)
+
+VOCAB = 8
+
+
+class ArrayFakeEngine:
+    """Fake engine whose logits are real backend arrays."""
+
+    name = "fake-tier"
+
+    def __init__(self, prompt_ids=(1, 2, 3)):
+        self._tok = FakeTok(prompt_ids)
+        self.cfg = SimpleNamespace(
+            gen=GenerationConfig(temperature=0.7, top_p=0.95, top_k=4,
+                                 repetition_penalty=1.0),
+            options=LayerOptions.prod_k8(), model_dir="fake-dir",
+            lora="", lora_r=16, lora_alpha=32.0, prerouter=None,
+            prerouter_top_k=8)
+        self.dir = "fake-dir"
+        self.prefill_chunk = 2048
+        self.think = False
+        self.events: list = []
+        self.closed = 0
+        self.pos = 0
+        self._logits = None
+        self._all_stream_layers = {}
+
+    def _make_logits(self):
+        row = [0.0] * VOCAB
+        row[self.pos % VOCAB] = 10.0
+        return core.array(row, dtype=core.float32)
+
+    def reset(self):
+        self.events.append("reset")
+        self.pos = 0
+
+    def prefill(self, ids):
+        self.events.append(("prefill", len(ids)))
+        self.pos += len(ids)
+        self._logits = self._make_logits()
+
+    def next_logits(self):
+        return self._logits
+
+    def step(self, tid):
+        self.events.append(("step", int(tid)))
+        self.pos += 1
+        return self._make_logits()
+
+    def stats(self):
+        return {}
+
+    def close(self):
+        self.closed += 1
+
+
+def test_tier_env_matches_the_cli():
+    from edge0.cli import TIER_ENV
+    assert bench._TIER_ENV == TIER_ENV
+
+
+def test_real_core_warmup_is_greedy_and_timed_steps_sample(monkeypatch):
+    # At T=0 the real sampler is greedy too, so the token sequence alone
+    # cannot tell a sampled warmup from a greedy one: count the calls to
+    # the REAL ops (still executed) through the framework seam.
+    from edge0.sampling import sample as real_sample
+    monkeypatch.setenv("BENCH_TEMP", "0")
+    monkeypatch.delenv("BENCH_SEED", raising=False)
+    calls = {"argmax": 0, "sample": 0}
+    real_argmax = core.argmax
+
+    def counting_argmax(*args, **kwargs):
+        calls["argmax"] += 1
+        return real_argmax(*args, **kwargs)
+
+    def counting_sample(*args, **kwargs):
+        calls["sample"] += 1
+        return real_sample(*args, **kwargs)
+    monkeypatch.setattr(core, "argmax", counting_argmax)
+    monkeypatch.setattr(bench, "_framework",
+                        lambda: (backend, core, counting_sample))
+    eng = ArrayFakeEngine(prompt_ids=(1, 2, 3))
+    out = bench.run_bench(eng, ntok=5, warmup=2,
+                          measurement=RecordingMeasurement(eng))
+    steps = [e[1] for e in eng.events if isinstance(e, tuple) and e[0] == "step"]
+    assert steps[:7] == [3, 4, 5, 6, 7, 0, 1]
+    assert calls == {"argmax": 2 * 2, "sample": 5 * 2}   # per run: warmup, ntok
+    kinds = _kinds(eng.events)
+    assert kinds.count("sync") == 8 and kinds.count("reset_peak") == 2
+    run = out["report_runs"][0]
+    assert run["total_generated_tokens"] == 7
+    assert run["execution_evidence"]["array_type"]
+
+
+def test_seed_is_applied_through_the_real_core(monkeypatch):
+    seen: list = []
+    monkeypatch.setattr(core.random, "seed", seen.append)
+    monkeypatch.setenv("BENCH_SEED", "0")
+    monkeypatch.setenv("BENCH_TEMP", "0")
+    eng = ArrayFakeEngine()
+    bench.run_bench(eng, ntok=1, warmup=0,
+                    measurement=RecordingMeasurement(eng))
+    assert seen == [0, 0]
+
+
+def test_default_measurement_dispatches_on_the_active_backend():
+    eng = ArrayFakeEngine()
+    out = bench.run_bench(eng, ntok=1, warmup=0)
+    desc = out["measurement"]
+    assert desc["backend"] == backend.name
+    if backend.name == "cuda":
+        expected = "cuda" if core.DEVICE.type == "cuda" else "null"
+        assert desc["kind"] == expected
+        assert desc["resolved_device"] == str(core.DEVICE)
+    else:
+        assert desc["kind"] == "mlx"
+
+
+def test_cli_report_states_the_actually_resolved_device(tmp_path, monkeypatch,
+                                                        capsys):
+    eng = ArrayFakeEngine()
+    monkeypatch.setattr(bench, "_build_engine", lambda model, name=None: eng)
+    monkeypatch.setenv("BENCH_TEMP", "0")
+    model_dir = tmp_path / "ckpt"
+    model_dir.mkdir()
+    out = tmp_path / "bench.json"
+    assert bench.main([str(model_dir), "--ntok", "2", "--warmup", "1",
+                       "--rss-sample-interval", "0",
+                       "--json-output", str(out)]) == 0
+    assert eng.closed == 1
+    doc = json.loads(out.read_text(encoding="utf-8"))
+    br.validate_report(doc)
+    rt = doc["runtime"]
+    assert rt["backend"] == backend.name
+    if backend.name == "cuda":
+        assert rt["resolved_device"] == str(core.DEVICE)
+        assert rt["measurement"]["kind"] == (
+            "cuda" if core.DEVICE.type == "cuda" else "null")
+        assert rt["torch_version"]
+    else:
+        assert rt["measurement"]["kind"] == "mlx"
+        assert rt["mlx_version"]
+    assert doc["caches"]["layer_options"]["cache_slots"] == 64
+    lines = capsys.readouterr().out.splitlines()
+    assert _match(HUMAN_LINE, lines[1])
diff --git a/tests/test_bench_cli.py b/tests/test_bench_cli.py
new file mode 100644
index 0000000..fd6c0f6
--- /dev/null
+++ b/tests/test_bench_cli.py
@@ -0,0 +1,794 @@
+"""``examples/bench.py`` end to end with fakes only: no backend, no weights.
+
+``bench.py`` imports the framework lazily (``bench._framework``), so this
+module runs on a host with neither torch nor MLX: the engine, the array
+namespace, the sampler and the measurement adapter are all fakes that
+record the order of every call.  That is what lets the phase
+synchronization order, the count arithmetic, the memory units, the
+pre-load validation, the failure paths and the cleanup be asserted
+anywhere.  ``tests/test_bench_backend.py`` repeats the core cases on a
+real backend when one is importable.  Host results are instrumentation
+checks, not Orin evidence.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import re
+import struct
+import subprocess
+import sys
+import time
+from dataclasses import dataclass
+from pathlib import Path
+from types import SimpleNamespace
+from typing import Any
+
+import pytest
+
+from examples import bench
+from examples import benchmark_measure as bm
+from examples import benchmark_report as br
+
+ROOT = Path(__file__).resolve().parents[1]
+VOCAB = 8
+GIB = 1024 ** 3
+
+HUMAN_LINE = re.compile(
+    r"^prompt=(\d+) tok  prefill=([\d.]+)s \((\d+) tok/s\)  "
+    r"decode=(\d+)/([\d.]+)s  tok/s=([\d.]+)  "
+    r"peak_active=((?:[\d.]+ GiB)|n/a)$")
+SUMMARY_LINE = re.compile(
+    r"^\[bench\] mean tok/s=([\d.]+)  peak_active<=((?:[\d.]+ GiB)|n/a)$")
+
+
+# ---- import boundary --------------------------------------------------------------
+
+
+def test_bench_module_imports_without_torch_mlx_or_edge0():
+    code = (
+        f"import sys; sys.path.insert(0, {str(ROOT)!r}); "
+        "from examples import bench; "
+        "bad = sorted(m for m in sys.modules "
+        "if m.split('.')[0] in ('torch', 'mlx', 'mlx_lm', 'edge0')); "
+        "print(bad)"
+    )
+    proc = subprocess.run([sys.executable, "-c", code],
+                          capture_output=True, text=True, check=True)
+    assert proc.stdout.strip() == "[]", proc.stdout
+
+
+def test_help_and_argument_errors_need_no_backend():
+    env = dict(os.environ, EDGE0_BACKEND="no-such-backend")
+    proc = subprocess.run(
+        [sys.executable, str(ROOT / "examples" / "bench.py"), "--help"],
+        capture_output=True, text=True, env=env, check=False)
+    assert proc.returncode == 0, proc.stderr
+    assert "--json-output" in proc.stdout
+    proc = subprocess.run(
+        [sys.executable, str(ROOT / "examples" / "bench.py"), "x", "--ntok", "0"],
+        capture_output=True, text=True, env=env, check=False)
+    assert proc.returncode == 2
+    assert "--ntok" in proc.stderr
+
+
+# ---- fakes ------------------------------------------------------------------------------
+
+
+def _argmax(logits):
+    return max(range(len(logits)), key=logits.__getitem__)
+
+
+class FakeCore:
+    """The two ``core`` calls the benchmark loop makes."""
+
+    def __init__(self):
+        self.seeds: list[int] = []
+        self.random = SimpleNamespace(seed=self.seeds.append)
+
+    @staticmethod
+    def argmax(logits, axis=-1):
+        return SimpleNamespace(item=lambda: _argmax(logits))
+
+
+def fake_sample(logits, temperature=0.7, top_k=None, top_p=None,
+                repetition_penalty=1.0, history=(), seed=None):
+    """Deliberately NOT the argmax, so a warmup step that sampled (or a
+    timed step that took the argmax) is visible in the recorded tokens."""
+    return (_argmax(logits) + 1) % VOCAB
+
+
+class FakeTok:
+    def __init__(self, ids):
+        self.ids = list(ids)
+
+    def apply_chat_template(self, messages, tokenize=False,
+                            add_generation_prompt=True,
+                            enable_thinking=False):
+        return "templated:" + messages[-1]["content"]
+
+    def __call__(self, text):
+        return {"input_ids": list(self.ids)}
+
+
+@dataclass
+class FakeOptions:
+    cache_slots: int = 64
+    prefetch_cap: int = 48
+    load_threads: int = 8
+    prefetch_threads: int = 4
+    top_k: int | None = None
+
+
+def _safetensors(path: Path, metadata: dict, n_tensors: int = 1):
+    header: dict = {"__metadata__": metadata}
+    for i in range(n_tensors):
+        header[f"t{i}"] = {"dtype": "F16", "shape": [1],
+                           "data_offsets": [2 * i, 2 * i + 2]}
+    blob = json.dumps(header).encode()
+    path.write_bytes(struct.pack("<Q", len(blob)) + blob + b"\0" * (2 * n_tensors))
+
+
+class FakeEngine:
+    """Duck-typed Edge0Engine: logits are lists whose argmax is
+    ``pos % VOCAB``; every call is recorded in ``events``."""
+
+    name = "fake-tier"
+
+    def __init__(self, prompt_ids=(1, 2, 3), fail_at_step=None,
+                 on_step=None, model_dir="fake-dir", lora="",
+                 prerouter_file=""):
+        self._tok = FakeTok(prompt_ids)
+        self.cfg = SimpleNamespace(
+            gen=SimpleNamespace(temperature=0.7, top_p=0.95, top_k=4,
+                                repetition_penalty=1.0),
+            options=FakeOptions(), model_dir=model_dir,
+            lora=lora, lora_r=16, lora_alpha=32.0,
+            prerouter=SimpleNamespace(
+                weights_file=prerouter_file, start_layer=7, hidden=512,
+                dtype="fp16", feature_topk="executed", owners=(7, 8)),
+            prerouter_top_k=8)
+        self.dir = model_dir
+        self.prefill_chunk = 2048
+        self.think = False
+        self.events: list = []
+        self.closed = 0
+        self.pos = 0
+        self.steps = 0
+        self._fail_at_step = fail_at_step
+        self._on_step = on_step
+        self._logits = None
+        self._all_stream_layers = {
+            1: SimpleNamespace(shared_cache=SimpleNamespace(slots=64),
+                               _prefetch_buf=SimpleNamespace(cap=48))}
+
+    def _make_logits(self):
+        row = [0.0] * VOCAB
+        row[self.pos % VOCAB] = 10.0
+        return row
+
+    def reset(self):
+        self.events.append("reset")
+        self.pos = 0
+
+    def prefill(self, ids):
+        self.events.append(("prefill", len(ids)))
+        self.pos += len(ids)
+        self._logits = self._make_logits()
+
+    def next_logits(self):
+        return self._logits
+
+    def step(self, tid):
+        self.steps += 1
+        self.events.append(("step", int(tid)))
+        if self._on_step is not None:
+            self._on_step(self.steps)
+        if self._fail_at_step is not None and self.steps == self._fail_at_step:
+            raise RuntimeError("synthetic decode failure")
+        self.pos += 1
+        return self._make_logits()
+
+    def stats(self):
+        return {1: {"loads": 3, "hits": 5}}
+
+    def close(self):
+        self.closed += 1
+        self.events.append("close")
+
+
+class RecordingMeasurement:
+    kind = "fake"
+    headline = "fake_peak"
+
+    def __init__(self, engine, peak: Any = 3 * GIB, sync_sleep=0.0):
+        self.engine = engine
+        self.peak = peak
+        self.sync_sleep = sync_sleep
+
+    def synchronize(self):
+        self.engine.events.append("sync")
+        if self.sync_sleep:
+            time.sleep(self.sync_sleep)
+
+    def reset_peak(self):
+        self.engine.events.append("reset_peak")
+
+    def peak_metrics(self):
+        self.engine.events.append("peaks")
+        return {"fake_peak": br.memory_metric(self.peak, method="fake",
+                                              scope="fake scope")}
+
+    def describe(self):
+        return {"kind": "fake", "backend": "fake", "resolved_device": "fake",
+                "synchronization": "recorded", "peak_source": "fake",
+                "headline_peak": self.headline}
+
+
+class FakeCudaApi:
+    def __init__(self, allocated, reserved):
+        self.calls: list = []
+        self._a, self._r = allocated, reserved
+
+    def synchronize(self, device=None):
+        self.calls.append("synchronize")
+
+    def reset_peak_memory_stats(self, device=None):
+        self.calls.append("reset_peak_memory_stats")
+
+    def max_memory_allocated(self, device=None):
+        return self._a
+
+    def max_memory_reserved(self, device=None):
+        return self._r
+
+
+def _kinds(events):
+    return [e[0] if isinstance(e, tuple) else e for e in events]
+
+
+def _match(pattern: re.Pattern, line: str) -> re.Match:
+    m = pattern.match(line)
+    assert m is not None, f"{line!r} does not match {pattern.pattern}"
+    return m
+
+
+def _expected_run(warmup, ntok):
+    return (["reset", "sync", "reset_peak", "prefill", "sync"]
+            + ["step"] * warmup + ["sync"] + ["step"] * ntok
+            + ["sync", "peaks"])
+
+
+@pytest.fixture
+def fake_framework(monkeypatch):
+    core = FakeCore()
+    backend = SimpleNamespace(name="fake", version="0.0")
+    monkeypatch.setattr(bench, "_framework",
+                        lambda: (backend, core, fake_sample))
+    monkeypatch.delenv("BENCH_PROMPT", raising=False)
+    monkeypatch.delenv("BENCH_SEED", raising=False)
+    monkeypatch.delenv("BENCH_TEMP", raising=False)
+    monkeypatch.delenv("BENCH_LONG", raising=False)
+    return core
+
+
+# ---- run_bench: order, counts, units --------------------------------------------------
+
+
+def test_run_bench_synchronizes_at_phase_boundaries_only(fake_framework):
+    eng = FakeEngine(prompt_ids=(1, 2, 3))
+    out = bench.run_bench(eng, ntok=4, warmup=2,
+                          measurement=RecordingMeasurement(eng))
+    assert _kinds(eng.events) == _expected_run(2, 4) * 2
+    assert eng.closed == 0  # run_bench never closes: the CLI's finally does
+    assert len(out["report_runs"]) == 2
+
+
+def test_run_bench_warmup_is_greedy_and_counts_are_separate(fake_framework):
+    eng = FakeEngine(prompt_ids=(1, 2, 3))
+    out = bench.run_bench(eng, ntok=5, warmup=2,
+                          measurement=RecordingMeasurement(eng))
+    steps = [e[1] for e in eng.events if isinstance(e, tuple) and e[0] == "step"]
+    # after a 3-token prefill the argmax is pos % VOCAB.  Warmup steps take
+    # the argmax (3, 4); timed steps go through the sampler, whose fake
+    # returns argmax + 1 (5->6, 6->7, 7->0, 0->1, 1->2).
+    assert steps[:7] == [3, 4, 6, 7, 0, 1, 2]
+    run = out["report_runs"][0]
+    assert run["prompt_tokens"] == 3
+    assert run["warmup_tokens"] == 2
+    assert run["timed_decode_tokens"] == 5
+    assert run["total_generated_tokens"] == 7
+    assert run["decode_start_context_tokens"] == 5
+    assert run["requested_timed_tokens"] == 5
+    assert run["requested_warmup_tokens"] == 2
+    assert run["decode_tokens_per_second"] == pytest.approx(
+        5 / run["decode_seconds"])
+
+
+def test_run_bench_synchronization_lands_inside_the_timed_phases(fake_framework):
+    eng = FakeEngine()
+    out = bench.run_bench(eng, ntok=2, warmup=1, runs=1,
+                          measurement=RecordingMeasurement(eng, sync_sleep=0.1))
+    run = out["report_runs"][0]
+    # exactly one boundary sync inside each timed phase; the post-warmup
+    # sync is outside both
+    assert 0.1 <= run["prefill_seconds"] < 0.2
+    assert 0.1 <= run["decode_seconds"] < 0.2
+
+
+def test_run_bench_seeds_every_run_with_the_resolved_seed(fake_framework,
+                                                          monkeypatch):
+    core = fake_framework
+    monkeypatch.setenv("BENCH_SEED", "0")
+    eng = FakeEngine()
+    out = bench.run_bench(eng, ntok=1, warmup=0,
+                          measurement=RecordingMeasurement(eng))
+    assert core.seeds == [0, 0]            # BENCH_SEED=0 seeds both runs
+    assert out["workload"]["seed"] == 0
+    core.seeds.clear()
+    monkeypatch.delenv("BENCH_SEED")
+    out = bench.run_bench(eng, ntok=1, warmup=0,
+                          measurement=RecordingMeasurement(eng))
+    assert core.seeds == []
+    assert out["workload"]["seed"] is None
+
+
+def test_run_bench_memory_units_are_bytes_in_json_and_gib_in_text(
+        fake_framework, capsys):
+    eng = FakeEngine()
+    out = bench.run_bench(eng, ntok=2, warmup=0,
+                          measurement=RecordingMeasurement(eng, peak=3 * GIB))
+    assert out["report_runs"][0]["memory"]["fake_peak"]["bytes"] == 3 * GIB
+    assert out["peak_gib"] == pytest.approx(3.0)
+    lines = capsys.readouterr().out.splitlines()
+    human = [m for m in (HUMAN_LINE.match(line) for line in lines) if m]
+    assert len(human) == 2
+    assert all(m.group(7) == "3.00 GiB" for m in human)
+    assert _match(SUMMARY_LINE, lines[-1]).group(2) == "3.00 GiB"
+
+
+def test_run_bench_human_peak_uses_the_allocated_headline_not_reserved(
+        fake_framework, capsys):
+    eng = FakeEngine()
+    dev = SimpleNamespace(type="cuda", index=0, __str__=lambda s: "cuda:0")
+    api = FakeCudaApi(allocated=1 * GIB, reserved=2 * GIB)
+    out = bench.run_bench(eng, ntok=1, warmup=0, runs=1,
+                          measurement=bm.CudaMeasurement(dev, api))
+    assert out["peak_gib"] == pytest.approx(1.0)
+    run = out["report_runs"][0]
+    assert run["memory"]["cuda_peak_allocated"]["bytes"] == GIB
+    assert run["memory"]["cuda_peak_reserved"]["bytes"] == 2 * GIB
+    lines = capsys.readouterr().out.splitlines()
+    assert _match(HUMAN_LINE, lines[0]).group(7) == "1.00 GiB"
+    assert api.calls.count("synchronize") == 4
+    assert api.calls.count("reset_peak_memory_stats") == 1
+
+
+def test_run_bench_prints_n_a_when_the_backend_peak_is_unavailable(
+        fake_framework, capsys):
+    eng = FakeEngine()
+    null = bm.NullMeasurement("cuda", "cpu", "torch device is cpu, not cuda")
+    out = bench.run_bench(eng, ntok=2, warmup=1, measurement=null)
+    assert out["peak_gib"] is None
+    assert all(r["peak_gib"] is None for r in out["runs"])
+    assert out["report_runs"][0]["memory"]["backend_peak"]["bytes"] is None
+    text = capsys.readouterr().out
+    lines = text.splitlines()
+    assert _match(HUMAN_LINE, lines[0]).group(7) == "n/a"
+    assert _match(SUMMARY_LINE, lines[-1]).group(2) == "n/a"
+    assert "0.00 GiB" not in text
+
+
+def test_run_bench_rejects_empty_or_negative_windows(fake_framework):
+    eng = FakeEngine()
+    with pytest.raises(ValueError, match="ntok"):
+        bench.run_bench(eng, ntok=0, warmup=0,
+                        measurement=RecordingMeasurement(eng))
+    with pytest.raises(ValueError, match="warmup"):
+        bench.run_bench(eng, ntok=1, warmup=-1,
+                        measurement=RecordingMeasurement(eng))
+    assert eng.events == []
+
+
+def test_run_bench_nonfinite_peak_fails_visibly(fake_framework):
+    eng = FakeEngine()
+    with pytest.raises(ValueError, match="bytes"):
+        bench.run_bench(eng, ntok=1, warmup=0,
+                        measurement=RecordingMeasurement(eng, peak=float("nan")))
+
+
+def test_run_bench_records_the_workload_identity(fake_framework, monkeypatch):
+    monkeypatch.setenv("BENCH_PROMPT", "hello there")
+    monkeypatch.setenv("BENCH_SEED", "7")
+    monkeypatch.setenv("BENCH_TEMP", "0.3")
+    eng = FakeEngine(prompt_ids=(4, 5))
+    out = bench.run_bench(eng, ntok=1, warmup=0,
+                          measurement=RecordingMeasurement(eng))
+    w = out["workload"]
+    assert w["prompt_source"] == "BENCH_PROMPT"
+    assert w["prompt_sha256"] == hashlib.sha256(b"hello there").hexdigest()
+    assert w["prompt_token_ids_sha256"] == hashlib.sha256(b"4,5").hexdigest()
+    assert w["prompt_chars"] == 11
+    assert w["prompt_text"] == "hello there"
+    assert w["prompt_tokens"] == 2
+    assert w["seed"] == 7
+    assert w["temperature"] == pytest.approx(0.3)
+    assert w["top_k"] == 4 and w["top_p"] == 0.95
+    assert w["repetition_penalty"] == 1.0
+
+
+# ---- CLI --------------------------------------------------------------------------------
+
+
+@pytest.fixture
+def cli(monkeypatch, tmp_path, fake_framework):
+    """Patch engine construction and the RSS sampler; return a helper."""
+    built: list = []
+    samplers: list = []
+    model_dir = tmp_path / "ckpt"
+    model_dir.mkdir()
+    (model_dir / "config.json").write_text(
+        '{"model_type": "bailing_hybrid", "architectures": ["X"]}')
+    (model_dir / "tokenizer.json").write_text('{"version": "1.0"}')
+    (model_dir / "chat_template.jinja").write_text("{{ messages }}")
+    _safetensors(model_dir / "model.safetensors", {"format": "mlx"}, 2)
+    # a non-canonical adapter name: only engine.cfg.lora can find it
+    _safetensors(model_dir / "my-lora.safetensors", {"edge0_adapter": "lora"})
+    _safetensors(model_dir / "lora_edge0_8b.safetensors", {"decoy": "1"})
+    artifacts = tmp_path / "artifacts"
+    artifacts.mkdir()
+    _safetensors(artifacts / "prerouter_edge0_8b.safetensors", {"heads": "16"})
+    running_at_build: list = []
+
+    class Sampler(bm.RssSampler):
+        def __init__(self, interval):
+            super().__init__(interval, read_memory=lambda: {"rss": 4096})
+            self.stop_calls = 0
+            samplers.append(self)
+
+        def stop(self):
+            self.stop_calls += 1
+            super().stop()
+
+    monkeypatch.setattr(bm, "RssSampler", Sampler)
+    monkeypatch.delenv("LING_HIDDEN_CLIP", raising=False)
+
+    def use(engine):
+        def build(model, name=None):
+            built.append((model, name))
+            running_at_build.append(samplers[-1].is_running if samplers
+                                    else None)
+            # mirror engine/ling.py: the engine sets a default the user
+            # did not request
+            if "LING_HIDDEN_CLIP" not in os.environ:
+                monkeypatch.setenv("LING_HIDDEN_CLIP", "1000")
+            return engine
+        monkeypatch.setattr(bench, "_build_engine", build)
+        return engine
+
+    def engine(**kw):
+        kw.setdefault("model_dir", str(model_dir))
+        kw.setdefault("lora", str(model_dir / "my-lora.safetensors"))
+        kw.setdefault("prerouter_file",
+                      str(artifacts / "prerouter_edge0_8b.safetensors"))
+        return FakeEngine(**kw)
+
+    return SimpleNamespace(model_dir=model_dir, artifacts=artifacts,
+                           built=built, samplers=samplers, use=use,
+                           engine=engine, tmp=tmp_path,
+                           running_at_build=running_at_build)
+
+
+def _tmp_entries(tmp):
+    return sorted(p.name for p in tmp.iterdir())
+
+
+def test_cli_writes_a_complete_report(cli, capsys):
+    eng = cli.use(cli.engine())
+    out = cli.tmp / "run" / "bench.json"
+    rc = bench.main([str(cli.model_dir), "--ntok", "3", "--warmup", "1",
+                     "--json-output", str(out)])
+    assert rc == 0
+    assert cli.built == [(str(cli.model_dir), None)]
+    assert eng.closed == 1
+    assert cli.running_at_build == [True]          # sampling covers the load
+    assert cli.samplers[0].stop_calls >= 1 and not cli.samplers[0].is_running
+    doc = json.loads(out.read_text(encoding="utf-8"))
+    br.validate_report(doc)
+    assert doc["schema_version"] == br.SCHEMA_VERSION
+    assert doc["protocol"]["name"] == "fixed-length-sample-and-step"
+    assert len(doc["runs"]) == 2
+    ident = doc["identity"]
+    assert ident["run_count"] == 2
+    assert ident["requested"]["ntok"] == 3
+    assert ident["requested"]["warmup"] == 1
+    assert ident["command"]["argv"][0] == str(cli.model_dir)
+    assert ident["git"]["commit"] is None or len(ident["git"]["commit"]) == 40
+    model = doc["model"]
+    assert model["checkpoint_path"] == str(cli.model_dir.resolve())
+    assert model["tier"] == "fake-tier"
+    assert model["model_type"] == "bailing_hybrid"
+    assert model["config_sha256"] == hashlib.sha256(
+        (cli.model_dir / "config.json").read_bytes()).hexdigest()
+    assert [f["path"] for f in model["manifest"]["files"]] == [
+        "chat_template.jinja", "config.json", "lora_edge0_8b.safetensors",
+        "model.safetensors", "my-lora.safetensors", "tokenizer.json"]
+    tok = {f["name"]: f for f in model["tokenizer_files"]}
+    assert set(tok) == {"tokenizer.json", "chat_template.jinja"}
+    assert tok["tokenizer.json"]["sha256"] == hashlib.sha256(
+        (cli.model_dir / "tokenizer.json").read_bytes()).hexdigest()
+    lora = model["adapters"]["lora"]
+    assert lora["file"] == "my-lora.safetensors"      # from engine.cfg.lora
+    assert lora["inside_checkpoint_dir"] is True
+    assert lora["sha256"] == hashlib.sha256(
+        (cli.model_dir / "my-lora.safetensors").read_bytes()).hexdigest()
+    assert lora["safetensors_header"]["metadata"] == {"edge0_adapter": "lora"}
+    prerouter = model["adapters"]["prerouter"]
+    assert prerouter["inside_checkpoint_dir"] is False
+    assert prerouter["safetensors_header"]["metadata"] == {"heads": "16"}
+    assert model["adapters"]["prerouter_settings"]["start_layer"] == 7
+    assert model["adapters"]["lora_settings"] == {
+        "r": 16, "alpha": 32.0, "unavailable_reasons": {}}
+    rt = doc["runtime"]
+    assert rt["backend"] == "fake"
+    assert rt["measurement"]["kind"] == "null"
+    assert rt["execution_evidence"]["array_type"] == "builtins.list"
+    w = doc["workload"]
+    assert w["prompt_tokens"] == 3
+    assert w["requested_timed_tokens"] == 3
+    assert w["model_env"]["ling_hidden_clip"] == 1000.0
+    assert w["model_env"]["prerouter_feature_topk"] == "teacher"
+    assert w["model_env"]["prerouter_intra"] is False
+    caches = doc["caches"]
+    assert caches["layer_options"]["cache_slots"] == 64
+    assert caches["shared_cache_slots_resolved"] == 64
+    assert caches["prefetch_cap_resolved"] == 48
+    assert caches["prewarm"] is False
+    assert caches["streaming_stats_after_runs"] == {"1": {"loads": 3, "hits": 5}}
+    mem = doc["memory"]
+    assert mem["process_sampled_peak_rss"]["bytes"] == 4096
+    assert mem["process_sampled_peak_rss"]["interval_seconds"] == 0.25
+    assert mem["process_sampled_peak_rss_anon"]["bytes"] is None
+    assert doc["probe"]["supplied"] is False
+    text = capsys.readouterr().out
+    assert sum(1 for line in text.splitlines() if HUMAN_LINE.match(line)) == 2
+    assert "[bench] tier=fake-tier ntok=3 warmup=1" in text
+
+
+def test_cli_env_knobs_are_snapshotted_before_the_engine_runs(cli, monkeypatch):
+    # LING_HIDDEN_CLIP is unset by the user; the (fake) engine sets 1000 at
+    # build time.  The requested snapshot must not show the engine's value,
+    # the resolved model_env must.
+    cli.use(cli.engine())
+    out = cli.tmp / "a.json"
+    assert bench.main([str(cli.model_dir), "--ntok", "1", "--warmup", "0",
+                       "--json-output", str(out)]) == 0
+    doc = json.loads(out.read_text(encoding="utf-8"))
+    assert "LING_HIDDEN_CLIP" not in doc["identity"]["command"]["env_knobs"]
+    assert doc["workload"]["model_env"]["ling_hidden_clip"] == 1000.0
+    monkeypatch.setenv("LING_HIDDEN_CLIP", "0")
+    monkeypatch.setenv("PREROUTER_FEATURE_TOPK", "executed")
+    monkeypatch.setenv("BENCH_SEED", "3")
+    out = cli.tmp / "b.json"
+    assert bench.main([str(cli.model_dir), "--ntok", "1", "--warmup", "0",
+                       "--json-output", str(out)]) == 0
+    doc = json.loads(out.read_text(encoding="utf-8"))
+    knobs = doc["identity"]["command"]["env_knobs"]
+    assert knobs["LING_HIDDEN_CLIP"] == "0"
+    assert knobs["BENCH_SEED"] == "3"
+    assert doc["workload"]["model_env"]["ling_hidden_clip"] == 0.0
+    assert doc["workload"]["model_env"]["prerouter_feature_topk"] == "executed"
+    assert doc["workload"]["seed"] == 3
+
+
+def test_cli_collects_identity_outside_the_timed_runs(cli, monkeypatch):
+    eng = cli.use(cli.engine())
+    for name in ("checkpoint_manifest", "adapter_identity", "git_identity",
+                 "power_mode", "process_peak_rss", "runtime_info"):
+        real = getattr(bm, name)
+
+        def spy(*args, _real=real, _name=name, **kwargs):
+            eng.events.append(("collect", _name))
+            return _real(*args, **kwargs)
+        monkeypatch.setattr(bm, name, spy)
+    out = cli.tmp / "bench.json"
+    assert bench.main([str(cli.model_dir), "--ntok", "1", "--warmup", "0",
+                       "--json-output", str(out)]) == 0
+    kinds = [e[0] if isinstance(e, tuple) else e for e in eng.events]
+    # every collector runs after the engine's final timed step of the last
+    # run (and before close): never inside a run
+    last_step = max(i for i, k in enumerate(kinds) if k == "step")
+    close = kinds.index("close")
+    collects = [i for i, k in enumerate(kinds) if k == "collect"]
+    assert collects and last_step < min(collects) and max(collects) < close
+    assert {e[1] for e in eng.events if isinstance(e, tuple)
+            and e[0] == "collect"} >= {"checkpoint_manifest", "git_identity",
+                                       "power_mode", "process_peak_rss"}
+
+
+def test_cli_without_json_output_keeps_the_old_behavior(cli, capsys):
+    eng = cli.use(cli.engine())
+    assert bench.main([str(cli.model_dir), "--ntok", "2", "--warmup", "0"]) == 0
+    assert eng.closed == 1
+    assert _tmp_entries(cli.tmp) == ["artifacts", "ckpt"]
+    lines = capsys.readouterr().out.splitlines()
+    assert lines[0] == "[bench] tier=fake-tier ntok=2 warmup=0"
+    assert HUMAN_LINE.match(lines[1]) and HUMAN_LINE.match(lines[2])
+    assert SUMMARY_LINE.match(lines[3])
+
+
+def test_cli_resolves_tier_names_through_the_environment(cli, monkeypatch):
+    cli.use(cli.engine())
+    monkeypatch.setenv("EDGE0_8B_MODEL", str(cli.model_dir))
+    assert bench.main(["edge0-8b", "--ntok", "1", "--warmup", "0"]) == 0
+    assert cli.built == [(str(cli.model_dir), None)]
+    monkeypatch.delenv("EDGE0_8B_MODEL")
+    with pytest.raises(SystemExit):
+        bench.main(["edge0-8b", "--ntok", "1"])
+    monkeypatch.setenv("EDGE0_FOO_MODEL", str(cli.model_dir))
+    with pytest.raises(SystemExit):           # unknown tier, like the CLI
+        bench.main(["edge0-foo", "--ntok", "1"])
+    assert len(cli.built) == 1
+
+
+@pytest.mark.parametrize("argv,env", [
+    (["--ntok", "0"], {}), (["--ntok", "-3"], {}), (["--warmup", "-1"], {}),
+    (["--rss-sample-interval", "-1"], {}),
+    (["--rss-sample-interval", "inf"], {}),
+    (["--rss-sample-interval", "nan"], {}),
+    (["--json-output", ""], {}), (["--probe-json", " "], {}),
+    ([], {"BENCH_SEED": "abc"}), ([], {"BENCH_TEMP": "hot"}),
+    ([], {"BENCH_TEMP": "nan"}), ([], {"BENCH_TEMP": "inf"}),
+    ([], {"BENCH_NTOK": "0"}), ([], {"BENCH_NTOK": "many"}),
+])
+def test_cli_rejects_invalid_requests_before_loading(cli, monkeypatch, argv,
+                                                     env, capsys):
+    cli.use(cli.engine())
+    for key, value in env.items():
+        monkeypatch.setenv(key, value)
+    with pytest.raises(SystemExit) as exc:
+        bench.main([str(cli.model_dir), *argv])
+    assert exc.value.code == 2
+    assert cli.built == []
+    err = capsys.readouterr().err
+    assert (argv[0] if argv else next(iter(env))) in err
+
+
+def test_cli_rejects_an_existing_output_before_loading(cli, capsys):
+    cli.use(cli.engine())
+    out = cli.tmp / "bench.json"
+    out.write_text("stale")
+    with pytest.raises(SystemExit) as exc:
+        bench.main([str(cli.model_dir), "--ntok", "1", "--json-output",
+                    str(out)])
+    assert exc.value.code == 2
+    assert cli.built == []
+    assert out.read_text() == "stale"
+    assert "already exists" in capsys.readouterr().err
+
+
+def test_cli_rejects_an_unwritable_output_location_before_loading(cli):
+    cli.use(cli.engine())
+    blocker = cli.tmp / "file"
+    blocker.write_text("x")
+    with pytest.raises(SystemExit) as exc:
+        bench.main([str(cli.model_dir), "--ntok", "1", "--json-output",
+                    str(blocker / "bench.json")])
+    assert exc.value.code == 2
+    assert cli.built == []
+
+
+def test_cli_links_the_supplied_probe_by_content_hash(cli):
+    cli.use(cli.engine())
+    probe = cli.tmp / "probe.json"
+    # non-canonical bytes (key order, spacing, trailing newline): the hash
+    # must be over the file as read, not over re-serialized JSON
+    probe.write_bytes(b'{\n "ready": false ,\n "collected_at_utc":'
+                      b' "2026-09-14T09:00:00+00:00",\n'
+                      b' "schema_version" : 1\n}\n')
+    assert json.dumps(json.loads(probe.read_bytes())).encode() != probe.read_bytes()
+    out = cli.tmp / "bench.json"
+    assert bench.main([str(cli.model_dir), "--ntok", "1", "--warmup", "0",
+                       "--probe-json", str(probe),
+                       "--json-output", str(out)]) == 0
+    doc = json.loads(out.read_text(encoding="utf-8"))
+    assert doc["probe"]["supplied"] is True
+    assert doc["probe"]["schema_version"] == 1
+    assert doc["probe"]["ready"] is False
+    assert doc["probe"]["sha256"] == hashlib.sha256(
+        probe.read_bytes()).hexdigest()
+    assert doc["probe"]["path"] == str(probe)
+
+
+@pytest.mark.parametrize("content", [b"{oops", b"[]", b'{"ready": true}'])
+def test_cli_rejects_a_malformed_probe_before_loading(cli, content, capsys):
+    cli.use(cli.engine())
+    probe = cli.tmp / "probe.json"
+    probe.write_bytes(content)
+    with pytest.raises(SystemExit) as exc:
+        bench.main([str(cli.model_dir), "--ntok", "1",
+                    "--probe-json", str(probe)])
+    assert exc.value.code == 2
+    assert cli.built == []
+    assert "probe" in capsys.readouterr().err
+
+
+def test_cli_rejects_a_missing_probe_before_loading(cli):
+    cli.use(cli.engine())
+    with pytest.raises(SystemExit) as exc:
+        bench.main([str(cli.model_dir), "--ntok", "1",
+                    "--probe-json", str(cli.tmp / "absent.json")])
+    assert exc.value.code == 2
+    assert cli.built == []
+
+
+def test_cli_generation_failure_leaves_no_report_and_cleans_up(cli, capsys):
+    eng = cli.use(cli.engine(fail_at_step=2))
+    out = cli.tmp / "bench.json"
+    rc = bench.main([str(cli.model_dir), "--ntok", "3", "--warmup", "0",
+                     "--json-output", str(out)])
+    assert rc == 1
+    assert not out.exists()
+    assert _tmp_entries(cli.tmp) == ["artifacts", "ckpt"]   # no temp files
+    assert eng.closed == 1
+    assert cli.samplers[0].stop_calls >= 1 and not cli.samplers[0].is_running
+    err = capsys.readouterr().err
+    assert "FAILED" in err and "benchmark" in err
+    assert "synthetic decode failure" in err
+
+
+def test_cli_write_failure_is_nonzero_and_still_closes_the_engine(cli, capsys):
+    out = cli.tmp / "bench.json"
+
+    def steal_path(step):
+        if step == 1:
+            out.write_text("someone else")
+    eng = cli.use(cli.engine(on_step=steal_path))
+    rc = bench.main([str(cli.model_dir), "--ntok", "2", "--warmup", "0",
+                     "--json-output", str(out)])
+    assert rc == 1
+    assert out.read_text() == "someone else"          # never overwritten
+    assert eng.closed == 1
+    assert _tmp_entries(cli.tmp) == ["artifacts", "bench.json", "ckpt"]
+    err = capsys.readouterr().err
+    assert "FAILED" in err and "write" in err
+
+
+def test_cli_engine_build_failure_is_nonzero_and_stops_the_sampler(
+        cli, capsys, monkeypatch):
+    def build(model, name=None):
+        raise RuntimeError("no weights here")
+    monkeypatch.setattr(bench, "_build_engine", build)
+    out = cli.tmp / "bench.json"
+    rc = bench.main([str(cli.model_dir), "--ntok", "1", "--json-output",
+                     str(out)])
+    assert rc == 1
+    assert not out.exists()
+    assert cli.samplers[0].stop_calls >= 1 and not cli.samplers[0].is_running
+    assert "engine build" in capsys.readouterr().err
+
+
+def test_cli_sampler_stop_failure_still_closes_the_engine(cli, monkeypatch):
+    eng = cli.use(cli.engine())
+
+    def broken_stop(self):
+        raise RuntimeError("sampler exploded")
+    monkeypatch.setattr(bm.RssSampler, "stop", broken_stop)
+    with pytest.raises(RuntimeError, match="sampler exploded"):
+        bench.main([str(cli.model_dir), "--ntok", "1", "--warmup", "0"])
+    assert eng.closed == 1
+
+
+def test_cli_can_disable_the_rss_sampler(cli):
+    cli.use(cli.engine())
+    out = cli.tmp / "bench.json"
+    assert bench.main([str(cli.model_dir), "--ntok", "1", "--warmup", "0",
+                       "--rss-sample-interval", "0",
+                       "--json-output", str(out)]) == 0
+    doc = json.loads(out.read_text(encoding="utf-8"))
+    m = doc["memory"]["process_sampled_peak_rss"]
+    assert m["bytes"] is None
+    assert "disabled" in m["unavailable_reason"]
+    assert cli.running_at_build == [False]
diff --git a/tests/test_benchmark_measure.py b/tests/test_benchmark_measure.py
new file mode 100644
index 0000000..55b6cda
--- /dev/null
+++ b/tests/test_benchmark_measure.py
@@ -0,0 +1,686 @@
+"""Benchmark-owned measurement adapter (``examples/benchmark_measure.py``).
+
+Everything here runs with fakes: no CUDA, no MLX, no checkpoint.  The
+CUDA dispatch path is exercised through an injected ``cuda_api`` object,
+the MLX path through a fake ``core`` namespace, RSS/git/power collectors
+through injected readers.  Real-device behavior is Task 3's job.
+"""
+
+from __future__ import annotations
+
+import json
+import struct
+import subprocess
+import sys
+from pathlib import Path
+from types import SimpleNamespace
+from typing import Any
+
+import pytest
+
+from examples import benchmark_measure as bm
+
+ROOT = Path(__file__).resolve().parents[1]
+
+
+# ---- import boundary -----------------------------------------------------------
+
+
+def test_measure_module_imports_without_torch_or_mlx():
+    code = (
+        f"import sys; sys.path.insert(0, {str(ROOT)!r}); "
+        "from examples import benchmark_measure; "
+        "bad = sorted(m for m in sys.modules "
+        "if m.split('.')[0] in ('torch', 'mlx', 'mlx_lm', 'edge0')); "
+        "print(bad)"
+    )
+    proc = subprocess.run([sys.executable, "-c", code],
+                          capture_output=True, text=True, check=True)
+    assert proc.stdout.strip() == "[]", proc.stdout
+
+
+# ---- fakes -----------------------------------------------------------------------
+
+
+class FakeCudaApi:
+    """Records every call in order, like a torch.cuda namespace would see."""
+
+    def __init__(self, allocated: Any = 3 * 1024 ** 3,
+                 reserved: Any = 4 * 1024 ** 3):
+        self.calls: list[tuple] = []
+        self._allocated = allocated
+        self._reserved = reserved
+
+    def synchronize(self, device=None):
+        self.calls.append(("synchronize", device))
+
+    def reset_peak_memory_stats(self, device=None):
+        self.calls.append(("reset_peak_memory_stats", device))
+
+    def max_memory_allocated(self, device=None):
+        self.calls.append(("max_memory_allocated", device))
+        return self._allocated
+
+    def max_memory_reserved(self, device=None):
+        self.calls.append(("max_memory_reserved", device))
+        return self._reserved
+
+
+class FakeDevice:
+    def __init__(self, type_, index=0):
+        self.type = type_
+        self.index = index
+
+    def __str__(self):
+        return f"{self.type}:{self.index}"
+
+
+class FakeMlxCore:
+    def __init__(self, peak=1500):
+        self.calls = []
+        self._peak = peak
+
+    def reset_peak_memory(self):
+        self.calls.append("reset_peak_memory")
+
+    def get_peak_memory(self):
+        self.calls.append("get_peak_memory")
+        return self._peak
+
+    def default_device(self):
+        return "Device(gpu, 0)"
+
+
+# ---- dispatch -------------------------------------------------------------------
+
+
+def test_cuda_backend_on_a_cuda_device_uses_torch_cuda_metrics():
+    api = FakeCudaApi()
+    core = SimpleNamespace(DEVICE=FakeDevice("cuda", 0))
+    m = bm.make_measurement("cuda", core, cuda_api=api)
+    assert isinstance(m, bm.CudaMeasurement)
+    d = m.describe()
+    assert d["kind"] == "cuda"
+    assert d["backend"] == "cuda"
+    assert d["resolved_device"] == "cuda:0"
+    assert "synchronize" in d["synchronization"]
+
+
+def test_cuda_backend_on_a_cpu_device_reports_unavailable_peaks():
+    core = SimpleNamespace(DEVICE=FakeDevice("cpu"))
+    m = bm.make_measurement("cuda", core, cuda_api=FakeCudaApi())
+    assert isinstance(m, bm.NullMeasurement)
+    m.synchronize()
+    m.reset_peak()
+    peaks = m.peak_metrics()
+    assert list(peaks) == ["backend_peak"]
+    assert peaks["backend_peak"]["bytes"] is None
+    assert "cpu" in peaks["backend_peak"]["unavailable_reason"]
+    assert "cuda" in peaks["backend_peak"]["unavailable_reason"]
+    desc = m.describe()
+    assert desc["resolved_device"] == "cpu:0"
+    assert desc["synchronization"].startswith("none")
+    assert "no device" not in desc["synchronization"]
+    assert "mps" not in desc["synchronization"]
+
+
+def test_cuda_backend_on_mps_reports_unavailable_peaks():
+    core = SimpleNamespace(DEVICE=FakeDevice("mps"))
+    m = bm.make_measurement("cuda", core, cuda_api=FakeCudaApi())
+    assert isinstance(m, bm.NullMeasurement)
+    assert "mps" in m.peak_metrics()["backend_peak"]["unavailable_reason"]
+    sync = m.describe()["synchronization"]
+    assert sync.startswith("none")
+    assert "no device" not in sync
+    assert "mps" in sync and "asynchronous" in sync
+
+
+def test_mlx_backend_keeps_the_mlx_peak_memory_behavior():
+    core = FakeMlxCore(peak=1500)
+    m = bm.make_measurement("mlx", core)
+    assert isinstance(m, bm.MlxMeasurement)
+    m.synchronize()          # no-op: MLX timing behavior is unchanged
+    m.reset_peak()
+    peaks = m.peak_metrics()
+    assert core.calls == ["reset_peak_memory", "get_peak_memory"]
+    assert peaks["mlx_peak_active"]["bytes"] == 1500
+    assert peaks["mlx_peak_active"]["method"] == "mlx.core.get_peak_memory"
+    assert "reset" in peaks["mlx_peak_active"]["scope"]
+    assert m.describe()["kind"] == "mlx"
+
+
+def test_mlx_core_without_peak_api_is_null_with_a_reason():
+    m = bm.make_measurement("mlx", SimpleNamespace())
+    assert isinstance(m, bm.NullMeasurement)
+    assert "peak" in m.peak_metrics()["backend_peak"]["unavailable_reason"]
+
+
+def test_unknown_backend_is_null_with_a_reason():
+    m = bm.make_measurement("other", SimpleNamespace())
+    assert isinstance(m, bm.NullMeasurement)
+    assert "other" in m.peak_metrics()["backend_peak"]["unavailable_reason"]
+
+
+# ---- CUDA call semantics ----------------------------------------------------------
+
+
+def test_cuda_measurement_calls_are_bound_to_the_resolved_device():
+    api = FakeCudaApi(allocated=123, reserved=456)
+    dev = FakeDevice("cuda", 1)
+    m = bm.CudaMeasurement(dev, api)
+    m.synchronize()
+    m.reset_peak()
+    m.synchronize()
+    peaks = m.peak_metrics()
+    assert api.calls == [
+        ("synchronize", dev),
+        ("reset_peak_memory_stats", dev),
+        ("synchronize", dev),
+        ("max_memory_allocated", dev),
+        ("max_memory_reserved", dev),
+    ]
+    assert peaks["cuda_peak_allocated"]["bytes"] == 123
+    assert peaks["cuda_peak_reserved"]["bytes"] == 456
+    assert peaks["cuda_peak_allocated"]["method"] == (
+        "torch.cuda.max_memory_allocated")
+    assert peaks["cuda_peak_reserved"]["method"] == (
+        "torch.cuda.max_memory_reserved")
+    for metric in peaks.values():
+        assert "allocator" in metric["scope"]
+        assert "reset" in metric["scope"]
+
+
+def test_cuda_measurement_rejects_nonfinite_or_negative_peaks():
+    m = bm.CudaMeasurement(FakeDevice("cuda"), FakeCudaApi(allocated=-1))
+    with pytest.raises(ValueError, match="bytes"):
+        m.peak_metrics()
+    m = bm.CudaMeasurement(FakeDevice("cuda"),
+                           FakeCudaApi(allocated=float("nan")))
+    with pytest.raises(ValueError, match="bytes"):
+        m.peak_metrics()
+
+
+# ---- execution evidence ------------------------------------------------------------
+
+
+def test_execution_evidence_records_array_type_and_device():
+    class Tensor:
+        device = FakeDevice("cuda", 0)
+    Tensor.__module__ = "torch"
+    ev = bm.execution_evidence(Tensor())
+    assert ev["array_type"] == "torch.Tensor"
+    assert ev["device"] == "cuda:0"
+    assert ev["unavailable_reasons"] == {}
+
+
+def test_execution_evidence_without_a_device_attribute():
+    class array:  # mimics mlx.core.array (lowercase on purpose)
+        pass
+    array.__module__ = "mlx.core"
+    ev = bm.execution_evidence(array())
+    assert ev["array_type"] == "mlx.core.array"
+    assert ev["device"] is None
+    assert "mlx.core.array" in ev["unavailable_reasons"]["device"]
+    assert "device attribute" in ev["unavailable_reasons"]["device"]
+
+
+# ---- process RSS ----------------------------------------------------------------------
+
+
+def test_process_peak_rss_linux_converts_kib_to_bytes():
+    ru = SimpleNamespace(ru_maxrss=2048)
+    m = bm.process_peak_rss(system="Linux", getrusage=lambda who: ru)
+    assert m["bytes"] == 2048 * 1024
+    assert "ru_maxrss" in m["method"]
+    assert "lifetime" in m["scope"]
+
+
+def test_process_peak_rss_macos_is_already_bytes():
+    ru = SimpleNamespace(ru_maxrss=2048)
+    m = bm.process_peak_rss(system="Darwin", getrusage=lambda who: ru)
+    assert m["bytes"] == 2048
+
+
+def test_process_peak_rss_windows_uses_peak_working_set():
+    fake_psutil = SimpleNamespace(Process=lambda: SimpleNamespace(
+        memory_info=lambda: SimpleNamespace(peak_wset=777, rss=700)))
+    m = bm.process_peak_rss(system="Windows", psutil_module=fake_psutil)
+    assert m["bytes"] == 777
+    assert "peak_wset" in m["method"]
+
+
+def test_process_peak_rss_unavailable_has_a_reason():
+    m = bm.process_peak_rss(system="Plan9", getrusage=None,
+                            psutil_module=None)
+    assert m["bytes"] is None
+    assert "Plan9" in m["unavailable_reason"]
+
+
+def test_process_peak_rss_on_this_host_is_a_positive_integer():
+    m = bm.process_peak_rss()
+    if m["bytes"] is None:
+        pytest.skip(m["unavailable_reason"])
+    assert isinstance(m["bytes"], int) and m["bytes"] > 0
+
+
+# ---- RSS sampler ------------------------------------------------------------------------
+
+
+def test_rss_sampler_reports_a_sampled_peak_with_its_interval():
+    values = iter([100, 300, 200, 250])
+    sampler = bm.RssSampler(0.01, read_rss=lambda: next(values, 250))
+    sampler.start()
+    import time
+    time.sleep(0.08)
+    sampler.stop()
+    m = sampler.metric()
+    assert m["bytes"] == 300
+    assert m["interval_seconds"] == 0.01
+    assert m["sample_count"] >= 2
+    assert "sampled" in m["scope"]
+    assert "psutil" in m["method"] or "read_rss" in m["method"]
+
+
+def test_rss_sampler_disabled_is_unavailable():
+    sampler = bm.RssSampler(0)
+    sampler.start()
+    sampler.stop()
+    m = sampler.metric()
+    assert m["bytes"] is None
+    assert "disabled" in m["unavailable_reason"]
+
+
+def test_rss_sampler_stop_is_idempotent_and_thread_exits():
+    sampler = bm.RssSampler(0.01, read_rss=lambda: 5)
+    sampler.start()
+    assert sampler.is_running
+    sampler.stop()
+    sampler.stop()
+    assert not sampler.is_running
+    assert sampler.metric()["bytes"] == 5
+
+
+def test_rss_sampler_reports_a_reader_that_will_not_stop():
+    import threading
+    import time
+    release = threading.Event()
+    started = threading.Event()
+
+    def blocked():
+        if started.is_set():
+            release.wait(5)      # the second sample hangs
+        started.set()
+        return 7
+
+    sampler = bm.RssSampler(0.01, read_rss=blocked, join_timeout=0.05)
+    sampler.start()
+    time.sleep(0.05)
+    sampler.stop()
+    try:
+        assert sampler.is_running          # not hidden: the thread is stuck
+        m = sampler.metric()
+        assert m["bytes"] == 7
+        assert "did not stop" in m["warning"]
+    finally:
+        release.set()
+        sampler.stop()
+    assert not sampler.is_running
+
+
+# ---- git identity --------------------------------------------------------------------------
+
+
+def _fake_run(responses):
+    def run(cmd, **kw):
+        key = tuple(cmd[cmd.index("git") + 1:]) if "git" in cmd else tuple(cmd)
+        rc, out = responses[key[-1] if key[-1] in responses else key]
+        return SimpleNamespace(returncode=rc, stdout=out, stderr="")
+    return run
+
+
+def test_git_identity_reports_commit_and_dirty_state():
+    run = _fake_run({"HEAD": (0, "abc123\n"), "--untracked-files=no": (0, " M x.py\n")})
+    g = bm.git_identity("/repo", run=run)
+    assert g == {"commit": "abc123", "dirty": True, "unavailable_reasons": {}}
+
+
+def test_git_identity_clean_tree():
+    run = _fake_run({"HEAD": (0, "abc123\n"), "--untracked-files=no": (0, "")})
+    assert bm.git_identity("/repo", run=run)["dirty"] is False
+
+
+def test_git_identity_unavailable_when_git_fails():
+    def run(cmd, **kw):
+        raise FileNotFoundError("git")
+    g = bm.git_identity("/repo", run=run)
+    assert g["commit"] is None and g["dirty"] is None
+    assert "git" in g["unavailable_reasons"]["commit"]
+
+
+def test_git_identity_on_this_checkout():
+    g = bm.git_identity(str(ROOT))
+    if g["commit"] is None:
+        pytest.skip(g["unavailable_reasons"]["commit"])
+    assert len(g["commit"]) == 40
+
+
+# ---- power mode -------------------------------------------------------------------------------
+
+
+def test_power_mode_parses_nvpmodel_output():
+    def run(cmd, **kw):
+        assert cmd[0] == "nvpmodel"
+        return SimpleNamespace(returncode=0, stdout="NV Power Mode: 15W\n1\n",
+                               stderr="")
+    p = bm.power_mode(run=run)
+    assert p["value"] == "15W"
+    assert p["mode_id"] == 1
+    assert p["method"] == "nvpmodel -q"
+    assert p["unavailable_reasons"] == {}
+
+
+def test_power_mode_falls_back_to_the_status_file(tmp_path):
+    status = tmp_path / "status"
+    status.write_text("pmode:0002 fmode:quiet\n")
+
+    def run(cmd, **kw):
+        raise FileNotFoundError("nvpmodel")
+    p = bm.power_mode(run=run, status_path=status)
+    assert p["mode_id"] == 2
+    assert p["value"] == "pmode 2"
+    assert "status" in p["method"]
+
+
+def test_power_mode_unavailable_with_reason(tmp_path):
+    def run(cmd, **kw):
+        raise FileNotFoundError("nvpmodel")
+    p = bm.power_mode(run=run, status_path=tmp_path / "absent")
+    assert p["value"] is None and p["method"] is None and p["mode_id"] is None
+    assert "nvpmodel" in p["unavailable_reasons"]["value"]
+
+
+# ---- checkpoint manifest -------------------------------------------------------------------
+
+
+def _safetensors(path: Path, metadata: dict, n_tensors: int = 2):
+    header = {"__metadata__": metadata}
+    for i in range(n_tensors):
+        header[f"t{i}"] = {"dtype": "F16", "shape": [1],
+                           "data_offsets": [2 * i, 2 * i + 2]}
+    blob = json.dumps(header).encode()
+    path.write_bytes(struct.pack("<Q", len(blob)) + blob + b"\0" * (2 * n_tensors))
+
+
+def test_checkpoint_manifest_identifies_files_without_hashing_weights(tmp_path):
+    (tmp_path / "config.json").write_text('{"model_type": "bailing_hybrid"}')
+    (tmp_path / "chat_template.jinja").write_text("{{ messages }}")
+    _safetensors(tmp_path / "model.safetensors", {"format": "mlx"})
+    _safetensors(tmp_path / "lora_edge0_8b.safetensors",
+                 {"edge0_adapter": "lora", "commit": "deadbeef"}, 1)
+    big = tmp_path / "big.bin"
+    big.write_bytes(b"x" * 100)
+
+    man = bm.checkpoint_manifest(tmp_path, hash_limit_bytes=50)
+    assert man["manifest"]["file_count"] == 5
+    assert man["manifest"]["total_bytes"] == sum(
+        p.stat().st_size for p in tmp_path.iterdir())
+    assert len(man["manifest"]["sha256"]) == 64
+    # small non-weight files are hashed, the "big" file and weights are not
+    assert set(man["small_file_sha256"]) == {"chat_template.jinja",
+                                             "config.json"}
+    header = man["safetensors_headers"]["model.safetensors"]
+    assert header["metadata"] == {"format": "mlx"}
+    assert header["tensor_count"] == 2
+    assert header["unavailable_reasons"] == {}
+    assert man["safetensors_headers"]["lora_edge0_8b.safetensors"][
+        "metadata"]["commit"] == "deadbeef"
+    assert man["config"]["model_type"] == "bailing_hybrid"
+
+
+def test_checkpoint_manifest_digest_tracks_names_and_sizes(tmp_path):
+    (tmp_path / "a").write_bytes(b"12")
+    d1 = bm.checkpoint_manifest(tmp_path)["manifest"]["sha256"]
+    (tmp_path / "a").write_bytes(b"123")
+    d2 = bm.checkpoint_manifest(tmp_path)["manifest"]["sha256"]
+    assert d1 != d2
+
+
+def test_checkpoint_manifest_of_a_missing_directory_is_unavailable(tmp_path):
+    man = bm.checkpoint_manifest(tmp_path / "nope")
+    assert man["manifest"]["sha256"] is None
+    assert "sha256" in man["manifest"]["unavailable_reasons"]
+    assert man["config"] == {}
+
+
+# ---- runtime info --------------------------------------------------------------------------
+
+
+def test_runtime_info_cuda_backend_reports_torch_versions():
+    fake_torch = SimpleNamespace(__version__="2.14.0+cpu",
+                                 version=SimpleNamespace(cuda=None))
+
+    def importer(name):
+        assert name == "torch"
+        return fake_torch
+    info = bm.runtime_info("cuda", importer=importer)
+    assert info["torch_version"] == "2.14.0+cpu"
+    assert info["torch_cuda_version"] is None
+    assert "torch_cuda_version" in info["unavailable_reasons"]
+    assert info["mlx_version"] is None
+    assert "mlx_version" in info["unavailable_reasons"]
+    assert info["python_version"] == sys.version.split()[0]
+    assert set(info["platform"]) == {"system", "release", "machine"}
+
+
+def test_runtime_info_mlx_backend_reports_mlx_version():
+    def importer(name):
+        assert name == "mlx"
+        return SimpleNamespace(__version__="0.30.4")
+    info = bm.runtime_info("mlx", importer=importer)
+    assert info["mlx_version"] == "0.30.4"
+    assert info["torch_version"] is None
+    assert "torch_version" in info["unavailable_reasons"]
+
+
+def test_runtime_info_import_failure_is_a_reason_not_a_crash():
+    def importer(name):
+        raise ImportError("no module")
+    info = bm.runtime_info("cuda", importer=importer)
+    assert info["torch_version"] is None
+    assert "no module" in info["unavailable_reasons"]["torch_version"]
+
+
+# ---- review follow-ups: headline peaks, reserved scope, at-reset details ------------
+
+
+class FakeCudaApiWithCurrent(FakeCudaApi):
+    def __init__(self, allocated=1 * 1024 ** 3, reserved=2 * 1024 ** 3,
+                 current_allocated=100, current_reserved=200):
+        super().__init__(allocated, reserved)
+        self._cur_alloc = current_allocated
+        self._cur_res = current_reserved
+
+    def memory_allocated(self, device=None):
+        self.calls.append(("memory_allocated", device))
+        return self._cur_alloc
+
+    def memory_reserved(self, device=None):
+        self.calls.append(("memory_reserved", device))
+        return self._cur_res
+
+
+def test_cuda_headline_is_allocated_and_reserved_has_its_own_scope():
+    api = FakeCudaApiWithCurrent()
+    m = bm.CudaMeasurement(FakeDevice("cuda"), api)
+    assert m.headline == "cuda_peak_allocated"
+    m.reset_peak()
+    peaks = m.peak_metrics()
+    allocated = peaks["cuda_peak_allocated"]
+    reserved = peaks["cuda_peak_reserved"]
+    assert allocated["scope"] != reserved["scope"]
+    assert "transient" in allocated["scope"]
+    assert "cached" in reserved["scope"] or "segments" in reserved["scope"]
+    assert "allocator" in reserved["scope"]
+    # the values current at the reset are recorded next to each peak
+    assert allocated["allocated_at_reset"] == 100
+    assert reserved["reserved_at_reset"] == 200
+    assert m.describe()["headline_peak"] == "cuda_peak_allocated"
+
+
+def test_cuda_measurement_without_current_readers_still_reports_peaks():
+    m = bm.CudaMeasurement(FakeDevice("cuda"), FakeCudaApi(allocated=5,
+                                                         reserved=6))
+    m.reset_peak()
+    peaks = m.peak_metrics()
+    assert peaks["cuda_peak_allocated"]["bytes"] == 5
+    assert "allocated_at_reset" not in peaks["cuda_peak_allocated"]
+
+
+def test_headline_names_for_mlx_and_null():
+    assert bm.MlxMeasurement(FakeMlxCore()).headline == "mlx_peak_active"
+    assert bm.NullMeasurement("cuda", "cpu", "r").headline == "backend_peak"
+    assert bm.NullMeasurement("cuda", "cpu", "r").describe()[
+        "headline_peak"] == "backend_peak"
+
+
+def test_mps_null_measurement_reports_the_resolved_device():
+    core = SimpleNamespace(DEVICE=FakeDevice("mps"))
+    m = bm.make_measurement("cuda", core, cuda_api=FakeCudaApi())
+    assert m.describe()["resolved_device"] == "mps:0"
+    assert "cuda" in m.peak_metrics()["backend_peak"]["unavailable_reason"]
+
+
+# ---- process memory composition ----------------------------------------------------
+
+
+def test_process_peak_rss_scope_names_file_backed_pages():
+    m = bm.process_peak_rss(system="Linux",
+                            getrusage=lambda who: SimpleNamespace(ru_maxrss=1))
+    assert "file-backed" in m["scope"]
+    assert "anonymous" in m["scope"]
+
+
+def test_parse_proc_status_extracts_rss_composition():
+    text = ("Name:\tpython3\nVmRSS:\t   2048 kB\nRssAnon:\t 1024 kB\n"
+            "RssFile:\t 1000 kB\nRssShmem:\t 24 kB\nVmSwap:\t 16 kB\n")
+    parsed = bm.parse_proc_status(text)
+    assert parsed == {"rss": 2048 * 1024, "rss_anon": 1024 * 1024,
+                      "rss_file": 1000 * 1024, "swap": 16 * 1024}
+
+
+def test_parse_proc_status_missing_fields_are_none():
+    parsed = bm.parse_proc_status("VmRSS:\t 10 kB\n")
+    assert parsed["rss"] == 10 * 1024
+    assert parsed["rss_anon"] is None and parsed["swap"] is None
+
+
+def test_rss_sampler_tracks_anon_file_and_swap_peaks():
+    samples = iter([
+        {"rss": 100, "rss_anon": 60, "rss_file": 40, "swap": 0},
+        {"rss": 300, "rss_anon": 70, "rss_file": 230, "swap": 5},
+        {"rss": 200, "rss_anon": 90, "rss_file": 110, "swap": 2},
+    ])
+    last = {"rss": 200, "rss_anon": 90, "rss_file": 110, "swap": 2}
+    sampler = bm.RssSampler(0.01, read_memory=lambda: next(samples, last))
+    sampler.start()
+    import time
+    time.sleep(0.08)
+    sampler.stop()
+    metrics = sampler.metrics()
+    assert metrics["process_sampled_peak_rss"]["bytes"] == 300
+    assert metrics["process_sampled_peak_rss_anon"]["bytes"] == 90
+    assert metrics["process_sampled_peak_rss_file"]["bytes"] == 230
+    assert metrics["process_sampled_peak_swap"]["bytes"] == 5
+    assert sampler.metric() == metrics["process_sampled_peak_rss"]
+    for m in metrics.values():
+        assert m["interval_seconds"] == 0.01
+        assert "sampled" in m["scope"]
+
+
+def test_rss_sampler_reports_unavailable_composition_with_reasons():
+    sampler = bm.RssSampler(0.01, read_memory=lambda: {"rss": 7})
+    sampler.start()
+    sampler.stop()
+    metrics = sampler.metrics()
+    assert metrics["process_sampled_peak_rss"]["bytes"] == 7
+    anon = metrics["process_sampled_peak_rss_anon"]
+    assert anon["bytes"] is None
+    assert "proc" in anon["unavailable_reason"].lower()
+
+
+def test_read_process_memory_on_this_host_returns_rss():
+    mem = bm.read_process_memory()
+    if mem is None:
+        pytest.skip("no process memory reader on this host")
+    assert isinstance(mem["rss"], int) and mem["rss"] > 0
+
+
+# ---- checkpoint identity follow-ups ----------------------------------------------------
+
+
+def test_checkpoint_manifest_retains_the_file_list_that_reproduces_the_digest(tmp_path):
+    import hashlib
+    (tmp_path / "b").write_bytes(b"12")
+    (tmp_path / "a").write_bytes(b"123")
+    (tmp_path / "sub").mkdir()
+    (tmp_path / "sub" / "c").write_bytes(b"1")
+    man = bm.checkpoint_manifest(tmp_path)["manifest"]
+    files = man["files"]
+    assert [f["path"] for f in files] == ["a", "b", "sub/c"]
+    assert len(files) == man["file_count"]
+    assert sum(f["size_bytes"] for f in files) == man["total_bytes"]
+    digest = hashlib.sha256("".join(
+        f"{f['path']}\t{f['size_bytes']}\n" for f in files).encode()).hexdigest()
+    assert digest == man["sha256"]
+    assert "sha256" in man["algorithm"] and "size" in man["algorithm"]
+
+
+def test_safetensors_header_records_a_header_hash(tmp_path):
+    import hashlib
+    path = tmp_path / "w.safetensors"
+    _safetensors(path, {"k": "v"}, 3)
+    header = bm.safetensors_header(path)
+    raw = path.read_bytes()
+    n = struct.unpack("<Q", raw[:8])[0]
+    assert header["header_sha256"] == hashlib.sha256(raw[8:8 + n]).hexdigest()
+    assert header["tensor_count"] == 3
+
+
+def test_adapter_identity_hashes_the_actual_adapter_file(tmp_path):
+    import hashlib
+    ckpt = tmp_path / "ckpt"
+    ckpt.mkdir()
+    inside = ckpt / "lora.safetensors"
+    _safetensors(inside, {"edge0_adapter": "lora"}, 1)
+    outside = tmp_path / "artifacts" / "prerouter.safetensors"
+    outside.parent.mkdir()
+    _safetensors(outside, {}, 2)
+
+    a = bm.adapter_identity(str(inside), ckpt)
+    assert a["file"] == "lora.safetensors"
+    assert a["path"] == str(inside.resolve())
+    assert a["inside_checkpoint_dir"] is True
+    assert a["size_bytes"] == inside.stat().st_size
+    assert a["sha256"] == hashlib.sha256(inside.read_bytes()).hexdigest()
+    assert a["safetensors_header"]["metadata"] == {"edge0_adapter": "lora"}
+    assert a["unavailable_reasons"] == {}
+
+    b = bm.adapter_identity(str(outside), ckpt)
+    assert b["inside_checkpoint_dir"] is False
+    assert b["file"] == str(outside.resolve())
+
+    c = bm.adapter_identity(str(outside), ckpt, sha256_max_bytes=10)
+    assert c["sha256"] is None
+    assert "sha256" in c["unavailable_reasons"]
+    assert "larger" in c["unavailable_reasons"]["sha256"]
+
+
+def test_adapter_identity_disabled_and_missing(tmp_path):
+    d = bm.adapter_identity("", tmp_path)
+    assert d["file"] is None and d["sha256"] is None
+    assert "disabled" in d["unavailable_reasons"]["file"]
+    m = bm.adapter_identity(str(tmp_path / "absent.safetensors"), tmp_path)
+    assert m["path"].endswith("absent.safetensors")
+    assert m["size_bytes"] is None
+    assert "not found" in m["unavailable_reasons"]["size_bytes"]
+    assert m["inside_checkpoint_dir"] is True
diff --git a/tests/test_benchmark_report.py b/tests/test_benchmark_report.py
new file mode 100644
index 0000000..2acc141
--- /dev/null
+++ b/tests/test_benchmark_report.py
@@ -0,0 +1,527 @@
+"""Pure benchmark report builder (``examples/benchmark_report.py``).
+
+These tests never need MLX, torch or a checkpoint: the builder is a
+stdlib-only module that turns already-measured numbers into the JSON
+report contract described in ``docs/plans/jetson-orin-nano.md`` (Task 2).
+Collection (timers, allocator peaks, RSS) lives in
+``examples/benchmark_measure.py`` and is tested separately.
+"""
+
+from __future__ import annotations
+
+import subprocess
+import sys
+from pathlib import Path
+from typing import Any
+
+import pytest
+
+from examples import benchmark_report as br
+
+ROOT = Path(__file__).resolve().parents[1]
+
+
+# ---- import boundary --------------------------------------------------------
+
+
+def test_builder_imports_without_torch_mlx_or_edge0():
+    code = (
+        f"import sys; sys.path.insert(0, {str(ROOT)!r}); "
+        "from examples import benchmark_report; "
+        "bad = sorted(m for m in sys.modules "
+        "if m.split('.')[0] in ('torch', 'mlx', 'mlx_lm', 'edge0')); "
+        "print(bad)"
+    )
+    proc = subprocess.run([sys.executable, "-c", code],
+                          capture_output=True, text=True, check=True)
+    assert proc.stdout.strip() == "[]", proc.stdout
+
+
+# ---- per-run counts and timings ----------------------------------------------
+
+
+def _run(**overrides):
+    kw = {"index": 0, "prompt_tokens": 12, "requested_warmup_tokens": 3,
+          "warmup_tokens": 3, "requested_timed_tokens": 5,
+          "timed_decode_tokens": 5, "prefill_seconds": 0.5,
+          "decode_seconds": 2.0, "memory": {}}
+    kw.update(overrides)
+    return br.run_result(**kw)
+
+
+def test_run_result_count_arithmetic_and_throughput():
+    run = _run()
+    assert run["index"] == 0
+    assert run["prompt_tokens"] == 12
+    assert run["warmup_tokens"] == 3
+    assert run["timed_decode_tokens"] == 5
+    # total_generated = warmup + timed_decode; decode starts after prompt+warmup
+    assert run["total_generated_tokens"] == 8
+    assert run["decode_start_context_tokens"] == 15
+    # throughput uses ONLY the timed decode tokens
+    assert run["decode_tokens_per_second"] == pytest.approx(2.5)
+    assert run["prefill_tokens_per_second"] == pytest.approx(24.0)
+    assert run["requested_warmup_tokens"] == 3
+    assert run["requested_timed_tokens"] == 5
+    assert run["unavailable_reasons"] == {}
+
+
+def test_run_result_keeps_requested_and_actual_counts_separate():
+    run = _run(requested_timed_tokens=200, timed_decode_tokens=5)
+    assert run["requested_timed_tokens"] == 200
+    assert run["timed_decode_tokens"] == 5
+
+
+@pytest.mark.parametrize("field", [
+    "prompt_tokens", "requested_warmup_tokens", "warmup_tokens",
+    "requested_timed_tokens", "timed_decode_tokens", "index",
+])
+def test_run_result_rejects_negative_counts(field):
+    with pytest.raises(ValueError, match=field):
+        _run(**{field: -1})
+
+
+@pytest.mark.parametrize("value", [1.0, True, "5", None])
+def test_run_result_rejects_non_integer_counts(value):
+    with pytest.raises(ValueError, match="prompt_tokens"):
+        _run(prompt_tokens=value)
+
+
+def test_run_result_requires_a_positive_timed_token_count():
+    with pytest.raises(ValueError, match="timed_decode_tokens"):
+        _run(timed_decode_tokens=0)
+
+
+@pytest.mark.parametrize("value", [float("nan"), float("inf"),
+                                   float("-inf"), -0.001, "1.0", None])
+def test_run_result_rejects_invalid_timings(value):
+    with pytest.raises(ValueError, match="decode_seconds"):
+        _run(decode_seconds=value)
+    with pytest.raises(ValueError, match="prefill_seconds"):
+        _run(prefill_seconds=value)
+
+
+def test_zero_measured_duration_gives_unavailable_rate_not_zero():
+    run = _run(decode_seconds=0.0, prefill_seconds=0)
+    assert run["decode_tokens_per_second"] is None
+    assert run["prefill_tokens_per_second"] is None
+    assert "zero" in run["unavailable_reasons"]["decode_tokens_per_second"]
+    assert "zero" in run["unavailable_reasons"]["prefill_tokens_per_second"]
+
+
+# ---- memory metric objects ----------------------------------------------------
+
+
+def test_memory_metric_is_integer_bytes_with_method_and_scope():
+    m = br.memory_metric(3 * 1024 ** 3, method="torch.cuda.max_memory_allocated",
+                         scope="per run after reset")
+    assert m == {
+        "bytes": 3 * 1024 ** 3,
+        "unit": "bytes",
+        "method": "torch.cuda.max_memory_allocated",
+        "scope": "per run after reset",
+        "unavailable_reason": None,
+    }
+
+
+def test_memory_metric_keeps_extra_details():
+    m = br.memory_metric(10, method="psutil rss sampler",
+                         scope="sampled peak", interval_seconds=0.25,
+                         sample_count=40)
+    assert m["interval_seconds"] == 0.25
+    assert m["sample_count"] == 40
+
+
+def test_memory_metric_unavailable_requires_a_reason():
+    m = br.memory_metric(None, method="none", scope="n/a",
+                         unavailable_reason="torch device is cpu, not cuda")
+    assert m["bytes"] is None
+    assert m["unavailable_reason"] == "torch device is cpu, not cuda"
+    with pytest.raises(ValueError, match="reason"):
+        br.memory_metric(None, method="none", scope="n/a")
+    with pytest.raises(ValueError, match="reason"):
+        br.memory_metric(5, method="m", scope="s", unavailable_reason="x")
+
+
+@pytest.mark.parametrize("value", [-1, 1.5, True, "12", float("nan")])
+def test_memory_metric_rejects_non_integer_or_negative_bytes(value):
+    with pytest.raises(ValueError, match="bytes"):
+        br.memory_metric(value, method="m", scope="s")
+
+
+def test_memory_metric_requires_method_and_scope():
+    with pytest.raises(ValueError, match="method"):
+        br.memory_metric(1, method="", scope="s")
+    with pytest.raises(ValueError, match="scope"):
+        br.memory_metric(1, method="m", scope="")
+
+
+# ---- report assembly ----------------------------------------------------------
+
+
+def _metric(n: Any = 1024, **kw):
+    kw.setdefault("method", "fake")
+    kw.setdefault("scope", "fake scope")
+    return br.memory_metric(n, **kw)
+
+
+def _groups(**overrides):
+    g = {
+        "identity": {
+            "timestamp_utc": "2026-09-14T10:00:00+00:00",
+            "git": {"commit": "abc", "dirty": False, "unavailable_reasons": {}},
+            "run_count": 2,
+            "command": {"argv": ["bench.py", "x"], "env_knobs": {}},
+            "requested": {"ntok": 5, "warmup": 3},
+        },
+        "model": {
+            "checkpoint_path": "/tmp/ckpt", "tier": "edge0-8b",
+            "model_type": "bailing_hybrid", "architectures": ["X"],
+            "config_sha256": "00", "manifest": {"file_count": 1,
+                                                "total_bytes": 1,
+                                                "sha256": "11"},
+            "small_file_sha256": {}, "adapters": {}, "tokenizer_files": [],
+        },
+        "runtime": {
+            "backend": "cuda", "backend_version": "2.14.0",
+            "resolved_device": "cpu",
+            "measurement": {"kind": "null"},
+            "execution_evidence": {"array_type": "torch.Tensor",
+                                   "device": "cpu"},
+            "python_version": "3.11.9", "torch_version": "2.14.0",
+            "torch_cuda_version": None, "mlx_version": None,
+            "platform": {"system": "Linux", "release": "x", "machine": "y"},
+            "power_mode": {"value": None, "method": None,
+                           "unavailable_reasons": {
+                               "value": "nvpmodel not found",
+                               "method": "nvpmodel not found"}},
+            "unavailable_reasons": {"torch_cuda_version": "CPU-only torch",
+                                    "mlx_version": "backend is cuda"},
+        },
+        "workload": {
+            "prompt_source": "tier default", "prompt_sha256": "22",
+            "prompt_token_ids_sha256": "33",
+            "prompt_chars": 10, "prompt_tokens": 12,
+            "requested_warmup_tokens": 3, "requested_timed_tokens": 5,
+            "seed": None, "temperature": 0.7, "top_k": 64, "top_p": 0.95,
+            "repetition_penalty": 1.1, "prefill_chunk": 2048,
+            "think": False,
+            "unavailable_reasons": {"seed": "BENCH_SEED not set"},
+        },
+        "caches": {
+            "layer_options": {"cache_slots": 64},
+            "shared_cache_slots_resolved": 64, "prefetch_cap_resolved": 48,
+            "weight_cache": False, "prewarm": False,
+            "threads": {"load_threads": 8},
+            "mlx_cache_limit_bytes": None,
+            "unavailable_reasons": {"mlx_cache_limit_bytes": "backend is cuda"},
+        },
+        "runs": [_run(index=0, memory={"backend_peak": _metric()}),
+                 _run(index=1, decode_seconds=1.0,
+                      memory={"backend_peak": _metric(2048)})],
+        "memory": {
+            "process_peak_rss": _metric(5000),
+            "process_sampled_peak_rss": _metric(
+                None, unavailable_reason="sampler disabled"),
+            "notes": ["RSS and allocator peaks are separate views"],
+        },
+        "probe": None,
+    }
+    g.update(overrides)
+    return g
+
+
+def test_schema_version_is_independent_of_the_probe_schema():
+    assert isinstance(br.SCHEMA_VERSION, int)
+    report = br.build_report(**_groups())
+    assert report["schema_version"] == br.SCHEMA_VERSION
+    # the probe's own schema number lives only inside the probe link
+    assert report["probe"]["supplied"] is False
+    assert report["probe"]["schema_version"] is None
+    assert "schema_version" in report["probe"]["unavailable_reasons"]
+
+
+def test_protocol_block_labels_the_workload_honestly():
+    report = br.build_report(**_groups())
+    proto = report["protocol"]
+    assert proto["name"] == "fixed-length-sample-and-step"
+    assert isinstance(proto["version"], int)
+    assert "greedy" in proto["warmup"].lower()
+    assert "eos" in proto["timed_phase"].lower()
+    assert "TTFT" in proto["not_measured"]
+
+
+def test_build_report_contains_every_group_and_summary():
+    report = br.build_report(**_groups())
+    for key in ("identity", "model", "runtime", "workload", "caches",
+                "runs", "summary", "memory", "probe"):
+        assert key in report, key
+    for group in ("identity", "model", "runtime", "workload", "caches",
+                  "memory", "probe"):
+        assert "unavailable_reasons" in report[group], group
+    assert report["identity"]["run_count"] == 2
+    assert len(report["runs"]) == 2
+
+
+@pytest.mark.parametrize("group,field", [
+    ("identity", "timestamp_utc"), ("model", "checkpoint_path"),
+    ("runtime", "resolved_device"), ("workload", "prompt_tokens"),
+    ("caches", "layer_options"), ("memory", "process_peak_rss"),
+])
+def test_build_report_rejects_missing_required_fields(group, field):
+    groups = _groups()
+    del groups[group][field]
+    with pytest.raises(ValueError, match=field):
+        br.build_report(**groups)
+
+
+def test_build_report_rejects_null_without_reason_and_reason_without_null():
+    groups = _groups()
+    groups["workload"]["top_k"] = None
+    with pytest.raises(ValueError, match="top_k"):
+        br.build_report(**groups)
+    groups = _groups()
+    groups["workload"]["unavailable_reasons"]["top_k"] = "bogus"
+    with pytest.raises(ValueError, match="top_k"):
+        br.build_report(**groups)
+
+
+def test_build_report_checks_nested_reason_maps():
+    groups = _groups()
+    groups["identity"]["git"]["commit"] = None  # nested null, no reason
+    with pytest.raises(ValueError, match="commit"):
+        br.build_report(**groups)
+
+
+def test_build_report_requires_runs_and_consistent_run_count():
+    groups = _groups(runs=[])
+    with pytest.raises(ValueError, match="runs"):
+        br.build_report(**groups)
+    groups = _groups()
+    groups["identity"]["run_count"] = 3
+    with pytest.raises(ValueError, match="run_count"):
+        br.build_report(**groups)
+
+
+def test_build_report_rejects_nonfinite_anywhere():
+    groups = _groups()
+    groups["caches"]["layer_options"]["hot_decay"] = float("nan")
+    with pytest.raises(ValueError, match="hot_decay"):
+        br.build_report(**groups)
+
+
+def test_build_report_rejects_non_json_types():
+    groups = _groups()
+    groups["model"]["checkpoint_path"] = Path("/tmp/x")
+    with pytest.raises(ValueError, match="checkpoint_path"):
+        br.build_report(**groups)
+
+
+# ---- summary -------------------------------------------------------------------
+
+
+def test_summary_keeps_every_run_and_defines_the_statistics():
+    report = br.build_report(**_groups())
+    s = report["summary"]
+    assert s["run_count"] == 2
+    d = s["decode_tokens_per_second"]
+    assert d["values"] == pytest.approx([2.5, 5.0])
+    assert d["mean"] == pytest.approx(3.75)
+    assert d["min"] == pytest.approx(2.5)
+    assert d["max"] == pytest.approx(5.0)
+    assert d["sample_stdev"] == pytest.approx(1.7677669529663687)
+    assert "independent" in s["method"]
+    assert set(s) >= {"decode_tokens_per_second", "prefill_tokens_per_second",
+                      "prefill_seconds", "decode_seconds"}
+
+
+def test_summary_single_run_has_no_stdev():
+    groups = _groups(runs=[_run(index=0, memory={})])
+    groups["identity"]["run_count"] = 1
+    s = br.build_report(**groups)["summary"]
+    assert s["decode_tokens_per_second"]["sample_stdev"] is None
+    assert "sample_stdev" in s["decode_tokens_per_second"]["unavailable_reasons"]
+
+
+def test_summary_statistics_use_the_runs_that_have_a_value():
+    groups = _groups(runs=[_run(index=0, memory={}),
+                           _run(index=1, decode_seconds=0.0, memory={})])
+    s = br.build_report(**groups)["summary"]
+    d = s["decode_tokens_per_second"]
+    assert d["values"] == [2.5, None]          # run order, null kept
+    assert d["n"] == 2 and d["n_valid"] == 1
+    assert d["mean"] == pytest.approx(2.5)
+    assert d["min"] == pytest.approx(2.5) and d["max"] == pytest.approx(2.5)
+    assert d["sample_stdev"] is None
+    assert "n_valid" in d["unavailable_reasons"]["sample_stdev"]
+    assert "mean" not in d["unavailable_reasons"]
+
+
+def test_summary_with_no_valid_value_is_null_with_a_reason():
+    groups = _groups(runs=[_run(index=0, decode_seconds=0.0, memory={}),
+                           _run(index=1, decode_seconds=0.0, memory={})])
+    d = br.build_report(**groups)["summary"]["decode_tokens_per_second"]
+    assert d["n_valid"] == 0
+    assert d["mean"] is None and d["min"] is None and d["max"] is None
+    assert "n_valid = 0" in d["unavailable_reasons"]["mean"]
+
+
+# ---- probe link ------------------------------------------------------------------
+
+
+def test_probe_link_hashes_the_actual_file_content():
+    import hashlib
+    import json
+    # deliberately NOT canonical json.dumps output: key order, spacing and
+    # a trailing newline differ, so re-serializing would change the hash
+    text = ('{\n  "ready": true ,\n  "collected_at_utc":'
+            ' "2026-09-14T09:00:00+00:00",\n  "schema_version" : 1\n}\n')
+    assert json.dumps(json.loads(text)) != text
+    link = br.probe_link(path="/run/orin-probe.json", text=text)
+    assert link["supplied"] is True
+    assert link["schema_version"] == 1
+    assert link["sha256"] == hashlib.sha256(text.encode("utf-8")).hexdigest()
+    raw = text.encode("utf-8")
+    assert br.probe_link(path="p", text=raw)["sha256"] == hashlib.sha256(
+        raw).hexdigest()
+    assert link["ready"] is True
+    assert link["collected_at_utc"] == "2026-09-14T09:00:00+00:00"
+    assert link["path"] == "/run/orin-probe.json"
+    assert link["unavailable_reasons"] == {}
+
+
+def test_probe_link_without_a_probe():
+    link = br.probe_link(path=None, text=None)
+    assert link["supplied"] is False
+    assert link["sha256"] is None
+    assert set(link["unavailable_reasons"]) >= {"path", "schema_version",
+                                                "sha256"}
+
+
+@pytest.mark.parametrize("text", ["{not json", "[]", '{"ready": true}',
+                                  '{"schema_version": "1"}'])
+def test_probe_link_rejects_malformed_probes(text):
+    with pytest.raises(ValueError, match="probe"):
+        br.probe_link(path="p.json", text=text)
+
+
+# ---- strict JSON and atomic writing ---------------------------------------------
+
+
+def test_dumps_report_is_strict_sorted_json():
+    import json
+    report = br.build_report(**_groups())
+    text = br.dumps_report(report)
+    assert text.endswith("\n")
+    assert json.loads(text) == report
+    report["runs"][0]["decode_seconds"] = float("nan")
+    with pytest.raises(ValueError):
+        br.dumps_report(report)
+
+
+def test_write_report_refuses_an_existing_destination(tmp_path):
+    dest = tmp_path / "out.json"
+    dest.write_text("old")
+    with pytest.raises(FileExistsError):
+        br.write_report(br.build_report(**_groups()), dest)
+    assert dest.read_text() == "old"
+
+
+def test_write_report_is_atomic_and_leaves_no_temp_files(tmp_path):
+    import json
+    dest = tmp_path / "out.json"
+    br.write_report(br.build_report(**_groups()), dest)
+    assert json.loads(dest.read_text(encoding="utf-8"))["schema_version"] == 1
+    assert sorted(p.name for p in tmp_path.iterdir()) == ["out.json"]
+
+
+def test_write_report_fails_visibly_when_the_directory_is_missing(tmp_path):
+    dest = tmp_path / "missing" / "out.json"
+    with pytest.raises(OSError):
+        br.write_report(br.build_report(**_groups()), dest)
+    assert not dest.exists()
+
+
+def test_write_report_writes_nothing_for_an_invalid_report(tmp_path):
+    dest = tmp_path / "out.json"
+    report = br.build_report(**_groups())
+    report["runs"][0]["decode_seconds"] = float("inf")
+    with pytest.raises(ValueError):
+        br.write_report(report, dest)
+    assert list(tmp_path.iterdir()) == []
+
+
+# ---- review follow-ups --------------------------------------------------------------
+
+
+def test_write_report_removes_the_temp_when_placing_the_file_fails(
+        tmp_path, monkeypatch):
+    dest = tmp_path / "out.json"
+
+    def boom(src, dst):
+        raise OSError("disk full")
+    monkeypatch.setattr(br, "_place_new_file", boom)
+    with pytest.raises(OSError, match="disk full"):
+        br.write_report(br.build_report(**_groups()), dest)
+    assert not dest.exists()
+    assert list(tmp_path.iterdir()) == []
+
+
+def test_write_report_uses_a_temp_file_in_the_destination_directory(
+        tmp_path, monkeypatch):
+    dest_dir = tmp_path / "run"
+    dest_dir.mkdir()
+    seen = []
+    real = br.tempfile.mkstemp
+
+    def spy(*args, **kwargs):
+        seen.append(kwargs.get("dir"))
+        return real(*args, **kwargs)
+    monkeypatch.setattr(br.tempfile, "mkstemp", spy)
+    br.write_report(br.build_report(**_groups()), dest_dir / "out.json")
+    assert [Path(d).resolve() for d in seen] == [dest_dir.resolve()]
+
+
+def test_write_report_never_overwrites_a_file_that_appears_meanwhile(
+        tmp_path, monkeypatch):
+    dest = tmp_path / "out.json"
+    real_fsync = br.os.fsync
+
+    def racer(fd):
+        dest.write_text("someone else")   # appears after the pre-check
+        real_fsync(fd)
+    monkeypatch.setattr(br.os, "fsync", racer)
+    with pytest.raises(FileExistsError):
+        br.write_report(br.build_report(**_groups()), dest)
+    assert dest.read_text() == "someone else"
+    assert sorted(p.name for p in tmp_path.iterdir()) == ["out.json"]
+
+
+@pytest.mark.skipif(sys.platform == "win32", reason="POSIX file modes")
+def test_write_report_honors_the_umask(tmp_path):
+    import os
+    dest = tmp_path / "out.json"
+    mask = os.umask(0o027)
+    try:
+        br.write_report(br.build_report(**_groups()), dest)
+    finally:
+        os.umask(mask)
+    assert dest.stat().st_mode & 0o777 == 0o640
+
+
+def test_summary_reports_n_and_n_valid():
+    groups = _groups(runs=[_run(index=0, memory={}),
+                           _run(index=1, decode_seconds=0.0, memory={})])
+    s = br.build_report(**groups)["summary"]
+    d = s["decode_tokens_per_second"]
+    assert d["n"] == 2 and d["n_valid"] == 1
+    p = s["prefill_seconds"]
+    assert p["n"] == 2 and p["n_valid"] == 2
+    assert "n_valid" in s["method"]
+
+
+def test_workload_requires_the_prompt_token_id_digest():
+    groups = _groups()
+    del groups["workload"]["prompt_token_ids_sha256"]
+    with pytest.raises(ValueError, match="prompt_token_ids_sha256"):
+        br.build_report(**groups)
diff --git a/tests/test_int4pack.py b/tests/test_int4pack.py
new file mode 100644
index 0000000..433ffd0
--- /dev/null
+++ b/tests/test_int4pack.py
@@ -0,0 +1,239 @@
+"""torch's built-in int4 kernel for the dense quantized linears (Task 6,
+design A, opt-in ``EDGE0_INT4PACK=1``).
+
+The MLX affine int4 layout (8 codes per uint32, least significant bits
+first, ``w = code * scale + bias``) is repacked into the layout of
+``torch.ops.aten._weight_int4pack_mm`` (uint8 pairs, high nibble first,
+tiled by ``_convert_weight_to_int4pack``) with ``zero = bias + 8 * scale``
+so that the kernel's ``(q - 8) * scale + zero`` equals the affine form.
+The mapping is NOT exact: ``zero`` is rounded to bfloat16 and the kernel
+dequantizes in bfloat16, so weights differ from the reference's own
+bfloat16-rounded weights by about one bfloat16 ulp for a third of the
+entries (measured on torch 2.14.0+cu130).  Tolerances below were
+registered from that workstation measurement BEFORE any Orin run; the
+Orin's 32-token reference check decides whether the path is acceptable.
+
+The pure repack step is tested for an exact round trip on the CPU; the
+kernel cases need a CUDA device (skip without one, FAIL with
+``--require-cuda``).  No MLX anywhere.
+"""
+
+from __future__ import annotations
+
+import os
+
+import pytest
+
+os.environ.setdefault("EDGE0_BACKEND", "cuda")
+torch = pytest.importorskip("torch")
+
+from edge0.backends.cuda import int4pack as i4  # noqa: E402
+from edge0.backends.cuda import nn as cnn  # noqa: E402
+from tests.test_quant_paths import _dequant64, _pack  # noqa: E402
+
+#: Pre-registered tolerances (see the module docstring).
+OUTPUT_RTOL = 1e-2           # max |y - y_exact| <= OUTPUT_RTOL * max |y_exact|
+WEIGHT_ABS_FRACTION = 2 ** -6  # max |w_kernel - w_exact| <= 2^-6 * (max|w| + max|zero|)
+
+
+def _within(got, ref, rtol=OUTPUT_RTOL) -> bool:
+    """The registered output criterion: max |got - ref| relative to the
+    output scale (bf16 outputs make an elementwise floor meaningless)."""
+    diff = (got.double() - ref.double()).abs().max().item()
+    return diff <= rtol * ref.double().abs().max().item()
+
+
+# ---- pure repack --------------------------------------------------------------------
+
+
+def test_gate_and_constants(monkeypatch):
+    monkeypatch.delenv("EDGE0_INT4PACK", raising=False)
+    assert i4._read_int4pack_gate() is False
+    monkeypatch.setenv("EDGE0_INT4PACK", "1")
+    assert i4._read_int4pack_gate() is True
+    assert i4.INNER_K_TILES == 8
+    assert i4.SUPPORTED_GROUP_SIZES == (32, 64, 128, 256)
+
+
+@pytest.mark.parametrize("seed", [0, 1])
+def test_uint32_to_uint8_repack_round_trips_exactly(seed):
+    gen = torch.Generator().manual_seed(seed)
+    codes = torch.randint(0, 16, (24, 256), generator=gen)
+    codes[0, :8] = 0
+    codes[1, :8] = 15
+    codes[2, :8] = torch.tensor([0, 15, 1, 14, 2, 13, 3, 12])
+    packed_u32 = _pack(codes, 4)
+    u8 = i4.codes_to_uint8(packed_u32)
+    assert u8.dtype == torch.uint8 and tuple(u8.shape) == (24, 128)
+    # high nibble = even column, low nibble = odd column
+    assert int(u8[2, 0]) == (0 << 4) | 15
+    assert int(u8[2, 1]) == (1 << 4) | 14
+    assert torch.equal(i4.uint8_to_codes(u8), codes)
+    assert torch.equal(i4.codes_to_uint32(i4.uint8_to_codes(u8)), packed_u32)
+
+
+def test_scales_and_zeros_mapping():
+    scales = torch.tensor([[0.5, -0.25], [1.0, 2.0]], dtype=torch.bfloat16)   # [n=2, k/g=2]
+    biases = torch.tensor([[1.0, 3.0], [-4.0, 0.5]], dtype=torch.bfloat16)
+    saz = i4.scales_and_zeros(scales, biases)
+    assert saz.dtype == torch.bfloat16 and tuple(saz.shape) == (2, 2, 2)  # [k/g, n, 2]
+    assert saz[0, 0, 0].item() == 0.5 and saz[0, 0, 1].item() == 1.0 + 8 * 0.5
+    assert saz[1, 0, 0].item() == -0.25 and saz[1, 0, 1].item() == 3.0 + 8 * -0.25
+    assert saz[0, 1, 1].item() == -4.0 + 8 * 1.0
+    # the rounding the kernel will see is reported, never hidden
+    err = i4.zero_rounding_error(scales, biases)
+    assert err >= 0.0
+
+
+@pytest.mark.parametrize("in_f,out_f,group,bits,device,dtype,ok", [
+    (1536, 512, 64, 4, "cuda", torch.bfloat16, True),
+    (2048, 1536, 64, 4, "cuda", torch.bfloat16, True),
+    (1536, 512, 128, 4, "cuda", torch.bfloat16, True),
+    (1600, 512, 64, 4, "cuda", torch.bfloat16, False),    # k % 128 != 0
+    (1536, 12, 64, 4, "cuda", torch.bfloat16, False),     # n % 8 != 0
+    (1536, 512, 48, 4, "cuda", torch.bfloat16, False),    # unsupported group
+    (1536, 512, 64, 8, "cuda", torch.bfloat16, False),    # 8-bit layout
+    (1536, 512, 64, 2, "cuda", torch.bfloat16, False),    # 2-bit layout
+    (1536, 512, 64, 4, "cpu", torch.bfloat16, False),     # no CUDA kernel
+    (1536, 512, 64, 4, "cuda", torch.float16, False),     # kernel wants bf16
+    (1536, 512, 64, 4, "cuda", torch.float32, False),
+])
+def test_is_supported_guards(in_f, out_f, group, bits, device, dtype, ok):
+    supported, reason = i4.is_supported(in_features=in_f, out_features=out_f,
+                                        group_size=group, bits=bits,
+                                        device_type=device, x_dtype=dtype)
+    assert supported is ok, reason
+    if not ok:
+        assert reason
+
+
+def test_extra_bytes_prices_the_duplicate_payload():
+    # the repacked payload duplicates the int4 words plus scales_and_zeros
+    assert i4.int4pack_extra_bytes(out_features=512, in_features=1536,
+                                   group_size=64) == 512 * 1536 // 2 + (1536 // 64) * 512 * 2 * 2
+
+
+# ---- CUDA --------------------------------------------------------------------------------
+
+
+@pytest.fixture(scope="module")
+def torch_cuda(request):
+    from tests.test_torch_cuda_smoke import _torch_with_cuda
+    return _torch_with_cuda(request)
+
+
+def _dense(seed, out_f, in_f, group=64):
+    gen = torch.Generator().manual_seed(seed)
+    codes = torch.randint(0, 16, (out_f, in_f), generator=gen)
+    scales = (torch.randn(out_f, in_f // group, generator=gen) * 0.05).to(torch.bfloat16)
+    biases = (torch.randn(out_f, in_f // group, generator=gen) * 0.05).to(torch.bfloat16)
+    return codes, _pack(codes, 4), scales, biases
+
+
+@pytest.mark.parametrize("out_f,in_f,m", [(512, 1536, 1), (1536, 2048, 4),
+                                          (4608, 1536, 37), (2048, 512, 1)])
+def test_int4pack_linear_matches_exact_reference_within_registered_tolerance(
+        torch_cuda, out_f, in_f, m):
+    codes, packed, scales, biases = _dense(30 + m, out_f, in_f)
+    tiled, saz = i4.repack(packed.cuda(), scales.cuda(), biases.cuda(), 64)
+    gen = torch.Generator().manual_seed(40 + m)
+    x = (torch.randn(2, m, in_f, generator=gen) * 0.5).to(torch.bfloat16).cuda()
+    y = i4.int4pack_linear(x, tiled, 64, saz)
+    torch.cuda.synchronize()
+    assert y.device.type == "cuda" and y.dtype == torch.bfloat16
+    assert tuple(y.shape) == (2, m, out_f)
+    y_exact = x.cpu().double() @ _dequant64(codes, scales, biases, 64).T
+    err = (y.cpu().double() - y_exact).abs().max().item()
+    assert err <= OUTPUT_RTOL * y_exact.abs().max().item(), err
+
+
+def test_int4pack_per_weight_error_is_within_the_registered_bound(torch_cuda):
+    out_f, in_f = 512, 1536
+    codes, packed, scales, biases = _dense(50, out_f, in_f)
+    tiled, saz = i4.repack(packed.cuda(), scales.cuda(), biases.cuda(), 64)
+    eye = torch.eye(in_f, dtype=torch.bfloat16, device="cuda")   # exact in bf16
+    w_kernel = i4.int4pack_linear(eye, tiled, 64, saz).t().cpu().double()
+    torch.cuda.synchronize()
+    w_exact = _dequant64(codes, scales, biases, 64)
+    zero = biases.double() + 8 * scales.double()
+    bound = WEIGHT_ABS_FRACTION * (w_exact.abs().max().item() + zero.abs().max().item())
+    assert (w_kernel - w_exact).abs().max().item() <= bound
+    # and it is genuinely approximate: report, don't hide
+    assert (w_kernel != w_exact.to(torch.bfloat16).double()).any()
+
+
+def test_quantized_linear_uses_the_kernel_only_when_eligible(torch_cuda,
+                                                           monkeypatch):
+    monkeypatch.setattr(cnn, "CACHE_DEQUANTIZED", False)
+    monkeypatch.setattr(cnn, "WEIGHT_CACHE", cnn.WeightCachePolicy(None))
+    monkeypatch.setattr(i4, "INT4PACK", True)
+    calls = []
+    real = i4.int4pack_linear
+
+    def spy(*args, **kwargs):
+        calls.append(1)
+        return real(*args, **kwargs)
+    monkeypatch.setattr(i4, "int4pack_linear", spy)
+    codes, packed, scales, biases = _dense(60, 512, 1536)
+    mod = cnn.QuantizedLinear(packed, scales, biases, 1536).cuda()
+    x = (torch.randn(3, 1536) * 0.5).to(torch.bfloat16).cuda()
+    monkeypatch.setattr(i4, "INT4PACK", False)
+    with torch.no_grad():
+        ref = mod(x)                       # gate off: the reference path
+    assert calls == [] and mod._int4pack is None and mod.int4pack_bytes() == 0
+    monkeypatch.setattr(i4, "INT4PACK", True)
+    with torch.no_grad():
+        y = mod(x)                         # repacked lazily on the first eligible call
+        y2 = mod(x)
+    assert mod._int4pack is not None
+    assert calls == [1, 1]
+    assert torch.equal(y, y2)
+    # registered criterion: max |y - ref| relative to the output scale
+    # (both outputs are bfloat16, so an elementwise floor makes no sense)
+    assert _within(y, ref)
+    assert (y != ref).any()                # approximate, and honest about it
+    with torch.no_grad():
+        f32 = mod(x.float())               # float32 activations: reference path
+    assert calls == [1, 1]
+    assert f32.dtype == torch.float32
+    assert i4.int4pack_extra_bytes(512, 1536, 64) == mod.int4pack_bytes()
+
+
+def test_exact_caches_take_precedence_over_the_kernel(torch_cuda, monkeypatch):
+    monkeypatch.setattr(cnn, "CACHE_DEQUANTIZED", False)
+    policy = cnn.WeightCachePolicy(None)
+    monkeypatch.setattr(cnn, "WEIGHT_CACHE", policy)
+    monkeypatch.setattr(i4, "INT4PACK", True)
+    calls = []
+    monkeypatch.setattr(i4, "int4pack_linear",
+                        lambda *a, **k: calls.append(1) or i4._int4pack_mm(*a, **k))
+    codes, packed, scales, biases = _dense(61, 512, 1536)
+    mod = cnn.QuantizedLinear(packed, scales, biases, 1536).cuda()
+    policy.register("m", mod)
+    policy.finalize(cap_bytes=1 << 30)
+    x = (torch.randn(3, 1536) * 0.5).to(torch.bfloat16).cuda()
+    with torch.no_grad():
+        mod(x)
+    assert calls == [] and mod._dequantized is not None
+
+
+def test_int4pack_under_a_lora_wrapper(torch_cuda, monkeypatch):
+    monkeypatch.setattr(cnn, "CACHE_DEQUANTIZED", False)
+    monkeypatch.setattr(cnn, "WEIGHT_CACHE", cnn.WeightCachePolicy(None))
+    monkeypatch.setattr(i4, "INT4PACK", True)
+    from edge0.adapters.lora import LoraLinear
+    codes, packed, scales, biases = _dense(62, 512, 1536)
+    mod = cnn.QuantizedLinear(packed, scales, biases, 1536).cuda()
+    gen = torch.Generator().manual_seed(63)
+    a = (torch.randn(16, 1536, generator=gen) * 0.02).to(torch.float16).cuda()
+    b = (torch.randn(512, 16, generator=gen) * 0.02).to(torch.float16).cuda()
+    wrapped = LoraLinear(mod, a, b, 2.0)
+    x = (torch.randn(3, 1536) * 0.5).to(torch.bfloat16).cuda()
+    with torch.no_grad():
+        y = wrapped(x)
+    assert y.dtype == torch.bfloat16 and y.device.type == "cuda"
+    monkeypatch.setattr(i4, "INT4PACK", False)
+    mod._int4pack = None
+    with torch.no_grad():
+        ref = wrapped(x)
+    assert _within(y, ref)
diff --git a/tests/test_jetson_probe.py b/tests/test_jetson_probe.py
new file mode 100644
index 0000000..fd7d199
--- /dev/null
+++ b/tests/test_jetson_probe.py
@@ -0,0 +1,494 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from scripts import jetson_probe
+from scripts.jetson_probe import (
+    collect_probe,
+    collect_torch_info,
+    parse_meminfo,
+    storage_device_for_path,
+)
+
+
+def _make_nvme_sysfs(root: Path, device_id: str = "259:1") -> Path:
+    sys_dev_block = root / "sys/dev/block"
+    backing = root / "sys/devices/platform/nvme/nvme0/nvme0n1"
+    backing.mkdir(parents=True, exist_ok=True)
+    sys_dev_block.mkdir(parents=True, exist_ok=True)
+    (sys_dev_block / device_id).symlink_to(backing)
+    return sys_dev_block
+
+
+def test_parse_meminfo_converts_kib_to_bytes():
+    parsed = parse_meminfo("MemTotal: 8192000 kB\nMemAvailable: 4096000 kB\n")
+
+    assert parsed == {
+        "total_bytes": 8_388_608_000,
+        "available_bytes": 4_194_304_000,
+    }
+
+
+def test_parse_meminfo_allows_missing_available_memory():
+    parsed = parse_meminfo("MemTotal: 1024 kB\n")
+
+    assert parsed == {"total_bytes": 1_048_576, "available_bytes": None}
+
+
+def test_storage_device_uses_longest_mount_prefix(tmp_path: Path):
+    model_dir = tmp_path / "models" / "edge0-8b"
+    model_dir.mkdir(parents=True)
+    mountinfo = "\n".join(
+        [
+            "30 20 8:1 / / rw,relatime - ext4 /dev/mmcblk0p1 rw",
+            f"31 30 259:1 / {tmp_path / 'models'} rw,relatime - ext4 /dev/nvme0n1p1 rw",
+        ]
+    )
+
+    storage = storage_device_for_path(
+        model_dir,
+        mountinfo,
+        path_device_id="259:1",
+        sys_dev_block=_make_nvme_sysfs(tmp_path),
+    )
+
+    assert storage["device"] == "/dev/nvme0n1p1"
+    assert storage["mount_point"] == str(tmp_path / "models")
+    assert storage["filesystem"] == "ext4"
+    assert storage["is_nvme"] is True
+
+
+def test_storage_device_marks_non_nvme_media(tmp_path: Path):
+    mountinfo = "30 20 179:1 / / rw,relatime - ext4 /dev/mmcblk0p1 rw"
+
+    storage = storage_device_for_path(
+        tmp_path,
+        mountinfo,
+        path_device_id="179:1",
+    )
+
+    assert storage["is_nvme"] is False
+
+
+def test_storage_device_resolves_device_mapper_backing_nvme(tmp_path: Path):
+    sys_dev_block = tmp_path / "sys/dev/block"
+    mapped = tmp_path / "sys/devices/virtual/block/dm-0"
+    physical = tmp_path / "sys/devices/platform/nvme/nvme0/nvme0n1"
+    (mapped / "slaves").mkdir(parents=True)
+    physical.mkdir(parents=True)
+    sys_dev_block.mkdir(parents=True)
+    (sys_dev_block / "253:0").symlink_to(mapped)
+    (mapped / "slaves/nvme0n1").symlink_to(physical)
+    mountinfo = "30 20 253:0 / / rw,relatime - ext4 /dev/mapper/cryptroot rw"
+
+    storage = storage_device_for_path(
+        tmp_path,
+        mountinfo,
+        path_device_id="253:0",
+        sys_dev_block=sys_dev_block,
+    )
+
+    assert storage["device_id"] == "253:0"
+    assert storage["is_nvme"] is True
+
+
+def test_storage_device_rejects_mixed_device_mapper_backing(tmp_path: Path):
+    sys_dev_block = tmp_path / "sys/dev/block"
+    mapped = tmp_path / "sys/devices/virtual/block/dm-0"
+    nvme = tmp_path / "sys/devices/platform/nvme/nvme0/nvme0n1"
+    mmc = tmp_path / "sys/devices/platform/mmc/mmcblk0"
+    (mapped / "slaves").mkdir(parents=True)
+    nvme.mkdir(parents=True)
+    mmc.mkdir(parents=True)
+    sys_dev_block.mkdir(parents=True)
+    (sys_dev_block / "253:0").symlink_to(mapped)
+    (mapped / "slaves/nvme0n1").symlink_to(nvme)
+    (mapped / "slaves/mmcblk0").symlink_to(mmc)
+
+    storage = storage_device_for_path(
+        tmp_path,
+        "30 20 253:0 / / rw - ext4 /dev/mapper/mixed rw",
+        path_device_id="253:0",
+        sys_dev_block=sys_dev_block,
+    )
+
+    assert storage["is_nvme"] is False
+
+
+def test_storage_device_handles_escaped_mounts_and_malformed_rows(tmp_path: Path):
+    model_dir = tmp_path / "model files"
+    model_dir.mkdir()
+    escaped = str(model_dir).replace(" ", "\\040")
+    mountinfo = "\n".join(
+        [
+            "malformed",
+            f"31 30 259:1 / {escaped} rw - ext4 /dev/nvme0n1p1 rw",
+        ]
+    )
+
+    storage = storage_device_for_path(
+        model_dir,
+        mountinfo,
+        path_device_id="259:1",
+        sys_dev_block=_make_nvme_sysfs(tmp_path),
+    )
+
+    assert storage["mount_point"] == str(model_dir)
+    assert storage["is_nvme"] is True
+
+
+def test_storage_device_preserves_unknown_nvme_state(tmp_path: Path):
+    mountinfo = "30 20 0:42 / / rw - overlay overlay rw"
+
+    storage = storage_device_for_path(
+        tmp_path,
+        mountinfo,
+        path_device_id="0:42",
+        sys_dev_block=tmp_path / "missing-sysfs",
+    )
+
+    assert storage["is_nvme"] is None
+
+
+def test_storage_device_does_not_trust_network_or_pseudo_source_names(tmp_path: Path):
+    for mountinfo, device_id in (
+        ("30 20 0:42 / / rw - nfs server:/nvme0n1 rw", "0:42"),
+        ("31 20 0:43 / / rw - tmpfs /dev/nvme0n1 rw", "0:43"),
+    ):
+        storage = storage_device_for_path(
+            tmp_path,
+            mountinfo,
+            path_device_id=device_id,
+            sys_dev_block=tmp_path / "missing-sysfs",
+        )
+
+        assert storage["is_nvme"] is not True
+
+
+def test_storage_device_matches_active_device_id_for_stacked_mounts(tmp_path: Path):
+    mountinfo = (
+        "30 20 259:1 / / rw - ext4 /dev/nvme0n1p1 rw\n"
+        "31 20 179:1 / / rw - ext4 /dev/mmcblk0p1 rw"
+    )
+
+    storage = storage_device_for_path(
+        tmp_path,
+        mountinfo,
+        path_device_id="179:1",
+    )
+
+    assert storage["device_id"] == "179:1"
+    assert storage["is_nvme"] is False
+
+
+def test_storage_device_reports_disk_usage_failure(tmp_path: Path):
+    def fail_disk_usage(_path):
+        raise OSError("unavailable")
+
+    storage = storage_device_for_path(
+        tmp_path,
+        "30 20 259:1 / / rw - ext4 /dev/nvme0n1p1 rw",
+        disk_usage_fn=fail_disk_usage,
+    )
+
+    assert storage["disk_usage_available"] is False
+    assert storage["total_bytes"] is None
+    assert storage["free_bytes"] is None
+
+
+class _FakeProps:
+    name = "Orin"
+    total_memory = 8_000_000_000
+    major = 8
+    minor = 7
+
+
+class _FakeCuda:
+    @staticmethod
+    def is_available():
+        return True
+
+    @staticmethod
+    def get_device_properties(_index):
+        return _FakeProps()
+
+
+class _FakeVersion:
+    cuda = "12.6"
+
+
+class _FakeTorch:
+    __version__ = "2.8.0"
+    cuda = _FakeCuda()
+    version = _FakeVersion()
+
+
+def test_collect_torch_info_reports_cuda_device():
+    info = collect_torch_info(_FakeTorch())
+
+    assert info == {
+        "installed": True,
+        "version": "2.8.0",
+        "cuda_available": True,
+        "cuda_version": "12.6",
+        "device_name": "Orin",
+        "compute_capability": [8, 7],
+        "device_memory_bytes": 8_000_000_000,
+        "errors": [],
+    }
+
+
+def test_collect_torch_info_reports_missing_torch():
+    info = collect_torch_info(None)
+
+    assert info == {
+        "installed": False,
+        "version": None,
+        "cuda_available": False,
+        "cuda_version": None,
+        "device_name": None,
+        "compute_capability": None,
+        "device_memory_bytes": None,
+        "errors": ["PyTorch import was skipped or unavailable"],
+    }
+
+
+class _BrokenCuda:
+    @staticmethod
+    def is_available():
+        raise RuntimeError("CUDA driver initialization failed")
+
+
+class _BrokenTorch:
+    __version__ = "2.8.0"
+    cuda = _BrokenCuda()
+    version = _FakeVersion()
+
+
+def test_collect_torch_info_turns_cuda_driver_failure_into_probe_data():
+    info = collect_torch_info(_BrokenTorch())
+
+    assert info["installed"] is True
+    assert info["cuda_available"] is False
+    assert info["errors"] == [
+        (
+            "CUDA availability check failed: "
+            "RuntimeError: CUDA driver initialization failed"
+        )
+    ]
+
+
+class _BrokenPropertiesCuda(_FakeCuda):
+    @staticmethod
+    def get_device_properties(_index):
+        raise RuntimeError("device query failed")
+
+
+class _BrokenPropertiesTorch:
+    __version__ = "2.8.0"
+    cuda = _BrokenPropertiesCuda()
+    version = _FakeVersion()
+
+
+def test_collect_torch_info_turns_device_query_failure_into_probe_data():
+    info = collect_torch_info(_BrokenPropertiesTorch())
+
+    assert info["cuda_available"] is True
+    assert info["errors"] == [
+        "CUDA device query failed: RuntimeError: device query failed"
+    ]
+
+
+def test_collect_probe_reports_actionable_blockers(tmp_path: Path):
+    root = tmp_path / "root"
+    (root / "proc/device-tree").mkdir(parents=True)
+    (root / "etc").mkdir()
+    (root / "proc/device-tree/model").write_bytes(
+        b"NVIDIA Jetson Orin Nano Developer Kit\x00"
+    )
+    (root / "etc/nv_tegra_release").write_text("# R36 (release), REVISION: 4.3\n")
+    (root / "proc/meminfo").write_text(
+        "MemTotal: 8192000 kB\nMemAvailable: 4096000 kB\n"
+    )
+    model_dir = tmp_path / "models"
+    model_dir.mkdir()
+    mountinfo = "30 20 179:1 / / rw,relatime - ext4 /dev/mmcblk0p1 rw"
+
+    report = collect_probe(
+        model_dir=model_dir,
+        fs_root=root,
+        mountinfo_text=mountinfo,
+        torch_module=None,
+        path_device_id="179:1",
+    )
+
+    assert report["schema_version"] == 1
+    assert report["jetson"]["is_jetson_orin"] is True
+    assert report["jetson"]["l4t_release"].startswith("# R36")
+    assert report["storage"]["is_nvme"] is False
+    assert report["ready"] is False
+    assert "PyTorch is not installed" in report["blockers"]
+    assert "CUDA is not available through PyTorch" in report["blockers"]
+    assert "model path is not on NVMe storage" in report["blockers"]
+
+
+def test_collect_probe_rejects_a_missing_model_path(tmp_path: Path):
+    root = tmp_path / "root"
+    (root / "proc/device-tree").mkdir(parents=True)
+    (root / "etc").mkdir()
+    (root / "proc/device-tree/model").write_text("NVIDIA Jetson Orin Nano")
+    (root / "etc/nv_tegra_release").write_text("# R36")
+    (root / "proc/meminfo").write_text("MemTotal: 8192000 kB\n")
+    _make_nvme_sysfs(root)
+
+    report = collect_probe(
+        model_dir=tmp_path / "missing-model",
+        fs_root=root,
+        mountinfo_text="30 20 259:1 / / rw - ext4 /dev/nvme0n1p1 rw",
+        torch_module=_FakeTorch(),
+        path_device_id="259:1",
+    )
+
+    assert report["storage"]["is_nvme"] is True
+    assert report["ready"] is False
+    assert "model path does not exist" in report["blockers"]
+
+
+def test_collect_probe_rejects_a_model_path_that_is_not_a_directory(tmp_path: Path):
+    model_file = tmp_path / "model.safetensors"
+    model_file.write_bytes(b"")
+    root = tmp_path / "root"
+    (root / "proc/device-tree").mkdir(parents=True)
+    (root / "etc").mkdir()
+    (root / "proc/device-tree/model").write_text("NVIDIA Jetson Orin Nano")
+    (root / "proc/meminfo").write_text("MemTotal: 8192000 kB\n")
+    _make_nvme_sysfs(root)
+
+    report = collect_probe(
+        model_dir=model_file,
+        fs_root=root,
+        mountinfo_text="30 20 259:1 / / rw - ext4 /dev/nvme0n1p1 rw",
+        torch_module=_FakeTorch(),
+        path_device_id="259:1",
+    )
+
+    assert report["ready"] is False
+    assert "model path is not a directory" in report["blockers"]
+
+
+def test_collect_probe_blocks_incomplete_cuda_device_evidence(tmp_path: Path):
+    root = tmp_path / "root"
+    (root / "proc/device-tree").mkdir(parents=True)
+    (root / "etc").mkdir()
+    (root / "proc/device-tree/model").write_text("NVIDIA Jetson Orin Nano")
+    (root / "proc/meminfo").write_text("MemTotal: 8192000 kB\n")
+    _make_nvme_sysfs(root)
+
+    report = collect_probe(
+        model_dir=tmp_path,
+        fs_root=root,
+        mountinfo_text="30 20 259:1 / / rw - ext4 /dev/nvme0n1p1 rw",
+        torch_module=_BrokenPropertiesTorch(),
+        path_device_id="259:1",
+    )
+
+    assert report["ready"] is False
+    assert any("CUDA device query failed" in item for item in report["blockers"])
+
+
+def test_collect_probe_can_report_fully_ready(tmp_path: Path):
+    root = tmp_path / "root"
+    (root / "proc/device-tree").mkdir(parents=True)
+    (root / "etc").mkdir()
+    (root / "proc/device-tree/model").write_text("NVIDIA Jetson Orin Nano")
+    (root / "etc/nv_tegra_release").write_text("# R36")
+    (root / "proc/meminfo").write_text("MemTotal: 8192000 kB\n")
+    _make_nvme_sysfs(root)
+
+    report = collect_probe(
+        model_dir=tmp_path,
+        fs_root=root,
+        mountinfo_text="30 20 259:1 / / rw - ext4 /dev/nvme0n1p1 rw",
+        torch_module=_FakeTorch(),
+        path_device_id="259:1",
+    )
+
+    assert report["ready"] is True
+    assert report["blockers"] == []
+
+
+def test_collect_probe_blocks_when_disk_usage_is_unavailable(tmp_path: Path):
+    root = tmp_path / "root"
+    (root / "proc/device-tree").mkdir(parents=True)
+    (root / "etc").mkdir()
+    (root / "proc/device-tree/model").write_text("NVIDIA Jetson Orin Nano")
+    (root / "proc/meminfo").write_text("MemTotal: 8192000 kB\n")
+    _make_nvme_sysfs(root)
+
+    def fail_disk_usage(_path):
+        raise OSError("unavailable")
+
+    report = collect_probe(
+        model_dir=tmp_path,
+        fs_root=root,
+        mountinfo_text="30 20 259:1 / / rw - ext4 /dev/nvme0n1p1 rw",
+        torch_module=_FakeTorch(),
+        disk_usage_fn=fail_disk_usage,
+        path_device_id="259:1",
+    )
+
+    assert report["ready"] is False
+    assert "model path disk usage could not be determined" in report["blockers"]
+
+
+def test_probe_report_is_json_serializable(tmp_path: Path):
+    root = tmp_path / "root"
+    (root / "proc/device-tree").mkdir(parents=True)
+    (root / "etc").mkdir()
+    (root / "proc/device-tree/model").write_text("generic arm board")
+    (root / "proc/meminfo").write_text("MemTotal: 1024 kB\n")
+
+    report = collect_probe(
+        model_dir=tmp_path,
+        fs_root=root,
+        mountinfo_text="30 20 8:1 / / rw - ext4 /dev/sda1 rw",
+        torch_module=None,
+    )
+
+    json.dumps(report)
+    assert "hardware is not a Jetson Orin" in report["blockers"]
+
+
+def test_cli_writes_json_and_returns_nonzero_for_blockers(
+    tmp_path: Path,
+    monkeypatch,
+    capsys,
+):
+    expected = {"schema_version": 1, "ready": False, "blockers": ["test"]}
+    monkeypatch.setattr(jetson_probe, "collect_probe", lambda *_args, **_kw: expected)
+    output = tmp_path / "probe.json"
+
+    result = jetson_probe.main(
+        [
+            "--model-dir",
+            str(tmp_path),
+            "--output",
+            str(output),
+            "--skip-torch",
+        ]
+    )
+
+    assert result == 1
+    assert json.loads(output.read_text()) == expected
+    assert json.loads(capsys.readouterr().out) == expected
+
+
+def test_cli_returns_zero_for_a_ready_report(tmp_path: Path, monkeypatch, capsys):
+    expected = {"schema_version": 1, "ready": True, "blockers": []}
+    monkeypatch.setattr(jetson_probe, "collect_probe", lambda *_args, **_kw: expected)
+
+    result = jetson_probe.main(["--model-dir", str(tmp_path)])
+
+    assert result == 0
+    assert json.loads(capsys.readouterr().out) == expected
diff --git a/tests/test_memory_budget.py b/tests/test_memory_budget.py
new file mode 100644
index 0000000..a46cc78
--- /dev/null
+++ b/tests/test_memory_budget.py
@@ -0,0 +1,229 @@
+"""Task 4: memory-budgeted streaming profile (pure calculation + the
+cache-side enforcement hooks).  No backend, no weights, no psutil."""
+
+from __future__ import annotations
+
+import pytest
+
+from edge0.streaming import budget as B
+from edge0.streaming.cache import PrefetchBuffer
+
+MB = 1024 * 1024
+GB = 1024 * MB
+
+#: A comfortable Orin-like scenario: ~3.5 GB observed, 2 MB bundles.
+OBS = B.Observation(available_bytes=3500 * MB)
+EXPERTS = B.ExpertFootprint(bundle_bytes=2 * MB, num_experts=128,
+                            num_moe_layers=23)
+WORKLOAD = B.WorkloadDecl(max_context_tokens=1024,
+                          kv_bytes_per_token=1_100_000)
+
+
+def resolve(obs=OBS, experts=EXPERTS, workload=WORKLOAD, **kw):
+    kw.setdefault("requested_cache_slots", 64)
+    kw.setdefault("requested_prefetch_cap", 48)
+    kw.setdefault("full_layer_prefill", True)
+    kw.setdefault("inflight_builds", 4)
+    kw.setdefault("min_cache_slots", 16)
+    return B.resolve_budget(obs, experts, workload, **kw)
+
+
+# ---------------------------------------------------------------- happy path
+
+def test_roomy_budget_keeps_requested_profile():
+    r = resolve()
+    assert r.cache_slots == 64
+    assert r.prefetch_cap == 48
+    assert r.max_prefetch_cap == 48       # prefetch_all may not grow past it
+    assert r.max_inflight == 4
+    assert r.notes == ()
+    # every deduction appears exactly once and the arithmetic closes
+    assert r.cache_allowance_bytes == r.usable_bytes - sum(
+        b for _, b in r.deductions)
+    assert r.headroom_bytes == (r.cache_allowance_bytes
+                                - r.cache_bytes - r.prefetch_bytes)
+    names = [n for n, _ in r.deductions]
+    assert names == ["os_growth_reserve", "allocator_allowance",
+                     "kv_cache_at_declared_context",
+                     "full_layer_prefill_transient",
+                     "inflight_expert_builds", "pinned_staging",
+                     "kernel_transient"]
+
+
+def test_deductions_use_declared_values():
+    r = resolve()
+    d = dict(r.deductions)
+    assert d["kv_cache_at_declared_context"] == 1024 * 1_100_000
+    assert d["full_layer_prefill_transient"] == 128 * 2 * MB
+    assert d["inflight_expert_builds"] == 4 * 2 * MB
+    r2 = resolve(full_layer_prefill=False)
+    assert dict(r2.deductions)["full_layer_prefill_transient"] == 0
+
+
+def test_overflow_scale_budget_never_raises_requested():
+    r = resolve(obs=B.Observation(available_bytes=10**18))
+    assert r.cache_slots == 64            # requested is the ceiling
+    assert r.prefetch_cap == 48
+
+
+def test_process_limit_tightens_observation():
+    obs = B.Observation(available_bytes=3500 * MB,
+                        process_limit_bytes=2500 * MB)
+    assert obs.usable() == 2500 * MB
+    assert resolve(obs=obs).usable_bytes == 2500 * MB
+
+
+# ------------------------------------------------------------ tight budgets
+
+def test_tight_budget_lowers_and_records():
+    r = resolve(obs=B.Observation(available_bytes=2150 * MB))
+    assert 16 <= r.cache_slots < 64
+    assert any("cache_slots lowered" in n for n in r.notes)
+    assert r.cache_bytes == r.cache_slots * EXPERTS.bundle_bytes
+
+
+def test_prefetch_floor_is_one_never_zero():
+    # Just enough for the LRU minimum, nothing left for prefetch:
+    # PrefetchBuffer(0) disables eviction, so the floor is 1, recorded.
+    r = resolve(obs=B.Observation(available_bytes=2100 * MB),
+                min_cache_slots=16)
+    assert r.prefetch_cap >= 1
+    if r.prefetch_cap == 1:
+        assert any("floored" in n for n in r.notes)
+
+
+def test_exhausted_budget_rejected_with_itemization():
+    with pytest.raises(B.BudgetError) as exc:
+        resolve(obs=B.Observation(available_bytes=600 * MB))
+    msg = str(exc.value)
+    assert "does not fit" in msg and "kv_cache_at_declared_context" in msg
+
+
+def test_starved_cache_rejected_not_constructed_as_zero():
+    # Allowance fits a few bundles but fewer than the working set.
+    with pytest.raises(B.BudgetError) as exc:
+        resolve(obs=B.Observation(available_bytes=2080 * MB),
+                min_cache_slots=32)
+    assert "SharedExpertCache(0)" in str(exc.value)
+
+
+def test_declared_context_is_priced_not_ignored():
+    ok = resolve()
+    with pytest.raises(B.BudgetError):
+        resolve(workload=B.WorkloadDecl(max_context_tokens=4096,
+                                        kv_bytes_per_token=1_100_000))
+    assert ok.cache_slots == 64
+
+
+# ------------------------------------------------------- invalid inputs
+
+@pytest.mark.parametrize("field,value", [
+    ("requested_cache_slots", 0), ("requested_cache_slots", -1),
+    ("requested_prefetch_cap", 0), ("inflight_builds", 0),
+    ("min_cache_slots", 0),
+])
+def test_invalid_requests_rejected(field, value):
+    with pytest.raises(B.BudgetError):
+        resolve(**{field: value})
+
+
+def test_invalid_observation_rejected():
+    with pytest.raises(B.BudgetError):
+        resolve(obs=B.Observation(available_bytes=0))
+    with pytest.raises(B.BudgetError):
+        resolve(obs=B.Observation(available_bytes=None))  # missing
+    with pytest.raises(B.BudgetError):
+        resolve(obs=B.Observation(available_bytes=True))  # bool is not int
+
+
+def test_invalid_reserves_rejected():
+    with pytest.raises(B.BudgetError):
+        resolve(reserves=B.Reserves(allocator_fraction=1.0))
+    with pytest.raises(B.BudgetError):
+        resolve(reserves=B.Reserves(os_growth_bytes=-1))
+
+
+def test_invalid_workload_rejected():
+    with pytest.raises(B.BudgetError):
+        resolve(workload=B.WorkloadDecl(max_context_tokens=-1,
+                                        kv_bytes_per_token=1_100_000))
+    with pytest.raises(B.BudgetError):
+        resolve(workload=B.WorkloadDecl(max_context_tokens=1024,
+                                        kv_bytes_per_token=0))
+
+
+# ------------------------------------------------- payload from metadata
+
+def _entries(per_tensor: int):
+    names = [f"model.layers.1.mlp.experts.{p}.{part}"
+             for p in ("gate_proj", "up_proj", "down_proj")
+             for part in ("weight", "scales", "biases")]
+    return {n: {"size": per_tensor} for n in names}
+
+
+def test_bundle_bytes_from_entries():
+    got = B.bundle_bytes_from_entries(
+        _entries(128 * 1000), "model.layers.1.mlp.experts", 128)
+    assert got == 9 * 1000
+
+
+def test_bundle_bytes_rounds_up_on_remainder():
+    got = B.bundle_bytes_from_entries(
+        _entries(1001), "model.layers.1.mlp.experts", 128)
+    assert got == (9 * 1001) // 128 + 1
+
+
+def test_bundle_bytes_missing_tensor_rejected():
+    entries = _entries(1000)
+    entries.pop("model.layers.1.mlp.experts.down_proj.biases")
+    with pytest.raises(B.BudgetError) as exc:
+        B.bundle_bytes_from_entries(
+            entries, "model.layers.1.mlp.experts", 128)
+    assert "down_proj.biases" in str(exc.value)
+
+
+def test_bundle_bytes_varying_sizes_change_slots():
+    small = resolve(experts=B.ExpertFootprint(
+        bundle_bytes=1 * MB, num_experts=128, num_moe_layers=23))
+    big = resolve(experts=B.ExpertFootprint(
+        bundle_bytes=16 * MB, num_experts=128, num_moe_layers=23),
+        obs=B.Observation(available_bytes=4500 * MB))
+    assert small.cache_slots == 64
+    assert big.cache_slots < 64
+
+
+# ------------------------------------------------------- weight cache veto
+
+def test_weight_cache_permitted_only_within_headroom():
+    denied = resolve(weight_cache_bytes=4_100_000_000)
+    assert not denied.weight_cache_permitted
+    granted = resolve(obs=B.Observation(available_bytes=10 * GB),
+                      weight_cache_bytes=4_100_000_000)
+    assert granted.weight_cache_permitted
+    assert resolve().weight_cache_bytes is None
+
+
+# ----------------------------------------------- PrefetchBuffer max_cap
+
+def test_prefetch_buffer_max_cap_clamps_growth():
+    buf = PrefetchBuffer(4, max_cap=6)
+    assert buf.cap == 4
+    buf.set_cap(160)                      # prefetch_all's n + 32 growth
+    assert buf.cap == 6
+    for i in range(10):
+        buf.put(i, object())
+    assert len(buf._buf) == 6
+
+
+def test_prefetch_buffer_default_semantics_unchanged():
+    buf = PrefetchBuffer(4)
+    buf.set_cap(160)
+    assert buf.cap == 160                 # historical unbounded growth
+    zero = PrefetchBuffer(0)
+    for i in range(100):
+        zero.put(i, object())
+    assert len(zero._buf) == 100          # 0 still means no eviction
+
+
+def test_prefetch_buffer_constructor_clamped_by_max_cap():
+    assert PrefetchBuffer(48, max_cap=6).cap == 6
diff --git a/tests/test_predict_prefetch.py b/tests/test_predict_prefetch.py
new file mode 100644
index 0000000..90a186c
--- /dev/null
+++ b/tests/test_predict_prefetch.py
@@ -0,0 +1,124 @@
+"""Task 5: prediction-driven prefetch plumbing (opt-in, exact path).
+
+Backend-dependent modules are involved (stager, engine), so the suite
+skips when no backend is importable; the routing logic itself is tested
+with fakes, no weights."""
+
+from __future__ import annotations
+
+import os
+
+import pytest
+
+os.environ.setdefault("EDGE0_BACKEND",
+                      "cuda" if os.environ.get("EDGE0_BACKEND", "") == ""
+                      else os.environ["EDGE0_BACKEND"])
+pytest.importorskip("edge0.backends",
+                    reason="no backend importable on this host")
+
+from edge0.prerouter.stager import LingPrerouterStager  # noqa: E402
+from edge0.streaming.options import LayerOptions  # noqa: E402
+
+
+class _FakeLayer:
+    def __init__(self):
+        self.staged = []
+        self.prefetched = []
+
+    def stage_experts(self, experts):
+        self.staged.append(list(experts))
+
+    def prefetch(self, experts):
+        self.prefetched.append(list(experts))
+
+
+def _stager(stream_layers, prefetch_layers):
+    # __init__ only stores these; the fakes never touch the model/spec.
+    s = LingPrerouterStager.__new__(LingPrerouterStager)
+    from edge0.prerouter.stager import PrerouterStager
+    PrerouterStager.__init__(
+        s, model=None, spec=_FakeSpec(), pspec=None,
+        state=_FakeState(), stream_layers=stream_layers, top_k=8,
+        prefetch_layers=prefetch_layers)
+    s.pg_cache = {}
+    return s
+
+
+class _FakeSpec:
+    num_experts = 128
+
+
+class _FakeState:
+    owners = ()
+
+
+def test_staged_consumer_stages_and_does_not_prefetch():
+    staged, plain = _FakeLayer(), _FakeLayer()
+    s = _stager({3: staged}, {3: plain, 5: plain})
+    s._store(3, "logits", None, None, [1, 2, 3])
+    assert staged.staged == [[1, 2, 3]]
+    assert plain.prefetched == []
+    assert s.pg_cache[3] == "logits"
+
+
+def test_non_staged_consumer_prefetches():
+    plain = _FakeLayer()
+    s = _stager({}, {5: plain})
+    s._store(5, "logits", None, None, [7, 8])
+    assert plain.prefetched == [[7, 8]]
+    assert plain.staged == []
+
+
+def test_consumer_without_layers_only_caches_logits():
+    s = _stager({}, {})
+    s._store(9, "logits", None, None, [1])
+    assert s.pg_cache[9] == "logits"
+
+
+def test_prefetch_layers_default_is_empty():
+    s = _stager({}, None)
+    s._store(9, "logits", None, None, [1])  # must not raise
+
+
+# ---------------------------------------------------------- env profile
+
+def test_apply_env_profile_cache_slots(monkeypatch):
+    from edge0.engine.ling import _apply_env_profile
+    cfg = _cfg()
+    monkeypatch.setenv("EDGE0_CACHE_SLOTS", "512")
+    out = _apply_env_profile(cfg, LayerOptions.prod_k8(), cfg.moe_spec)
+    assert out.cache_slots == 512
+
+
+@pytest.mark.parametrize("bad", ["0", "-3", "many"])
+def test_apply_env_profile_rejects_bad_slots(monkeypatch, bad):
+    from edge0.engine.ling import _apply_env_profile
+    cfg = _cfg()
+    monkeypatch.setenv("EDGE0_CACHE_SLOTS", bad)
+    with pytest.raises(ValueError):
+        _apply_env_profile(cfg, LayerOptions.prod_k8(), cfg.moe_spec)
+
+
+def test_apply_env_profile_predict_prefetch_sizes_buffer(monkeypatch):
+    from edge0.engine.ling import _apply_env_profile
+    cfg = _cfg()
+    monkeypatch.setenv("EDGE0_PREDICT_PREFETCH", "1")
+    out = _apply_env_profile(cfg, LayerOptions.prod_k8(), cfg.moe_spec)
+    assert out.predict_prefetch
+    assert out.max_inflight == 8                # per-layer = K
+    assert out.prefetch_cap == 16 * 8           # one full predicted step
+
+
+def test_apply_env_profile_defaults_unchanged():
+    from edge0.engine.ling import _apply_env_profile
+    for var in ("EDGE0_CACHE_SLOTS", "EDGE0_PREDICT_PREFETCH"):
+        assert os.environ.get(var, "") in ("", "0"), (
+            f"{var} leaked into the test environment")
+    cfg = _cfg()
+    base = LayerOptions.prod_k8()
+    assert _apply_env_profile(cfg, base, cfg.moe_spec) == base
+
+
+def _cfg():
+    from edge0.models.edge0_8b import Ling8BConfig
+    return Ling8BConfig._defaults("/nonexistent")
diff --git a/tests/test_quant_paths.py b/tests/test_quant_paths.py
new file mode 100644
index 0000000..67c653d
--- /dev/null
+++ b/tests/test_quant_paths.py
@@ -0,0 +1,427 @@
+"""Opt-in quantized paths for the torch backend (Task 6, workstation side).
+
+Every test here computes its reference independently of the code under
+test: int4 codes are packed by hand (8 per uint32 word, least
+significant bits first, the layout ``backends/cuda/quant.py`` documents
+and ``tests/test_cuda_backend.py`` verified against ``mx.quantize``),
+dequantized by the documented formula ``code * scale + bias`` in
+float64, and multiplied in float64.  No MLX anywhere: the suite runs on
+a Jetson.  Tolerances are written down here, before any Orin run.
+
+CPU cases run everywhere; the CUDA cases reuse the acceptance fixture
+of ``tests/test_torch_cuda_smoke.py`` (skip without a device, FAIL with
+``--require-cuda``).  Nothing here is a performance statement.
+"""
+
+from __future__ import annotations
+
+import os
+
+import pytest
+
+os.environ.setdefault("EDGE0_BACKEND", "cuda")
+torch = pytest.importorskip("torch")
+
+from edge0.backends.cuda import quant as cq  # noqa: E402
+
+E, OUT, D, GS = 8, 16, 128, 64
+
+
+# ---- hand-computed helpers ------------------------------------------------------
+
+
+def _pack(codes, bits):
+    """Pack integer codes along the last axis, ``32 // bits`` per uint32,
+    least significant bits first (independent of ``quant._dequantize``)."""
+    per_word = 32 // bits
+    assert codes.shape[-1] % per_word == 0
+    grouped = codes.reshape(*codes.shape[:-1], -1, per_word).to(torch.int64)
+    shifts = torch.arange(per_word, dtype=torch.int64) * bits
+    words = (grouped << shifts).sum(-1)
+    return words.to(torch.int32).view(torch.uint32)
+
+
+def _dequant64(codes, scales, biases, group):
+    shp = codes.shape
+    return (codes.reshape(*shp[:-1], -1, group).double()
+            * scales.double().unsqueeze(-1)
+            + biases.double().unsqueeze(-1)).reshape(shp)
+
+
+def _gather_ref64(x, w64, idx, transpose):
+    """``out[b] = x[b] @ W[idx[b]].T`` over the broadcast batch, float64."""
+    bshape = torch.broadcast_shapes(x.shape[:-2], idx.shape)
+    M = x.shape[-2]
+    xb = x.double().expand(*bshape, M, x.shape[-1]).reshape(-1, M, x.shape[-1])
+    ib = idx.expand(bshape).reshape(-1)
+    outs = []
+    for row, e in zip(xb, ib.tolist()):
+        wm = w64[e]
+        outs.append(row @ (wm.T if transpose else wm))
+    return torch.stack(outs).reshape(*bshape, M, -1)
+
+
+def _quantized(seed, bits=4, shape=(E, OUT, D), group=GS, dtype=torch.float32):
+    gen = torch.Generator().manual_seed(seed)
+    codes = torch.randint(0, 1 << bits, shape, generator=gen)
+    scales = (torch.randn(*shape[:-1], shape[-1] // group, generator=gen)
+              * 0.1).to(dtype)
+    biases = (torch.randn(*shape[:-1], shape[-1] // group, generator=gen)
+              * 0.05).to(dtype)
+    return codes, _pack(codes, bits), scales, biases
+
+
+SHAPES = [
+    ((3, D), (3,)),            # default convention: broadcasts to (3, 3, OUT)
+    ((5, 1, 1, D), (5, 3)),    # streaming/layer.py unsorted path
+    ((15, 1, D), (15,)),       # streaming/layer.py sorted path
+    ((2, 1, 4, D), (2, 3)),
+    ((1, 2, D), (4, 1)),
+]
+
+
+@pytest.fixture
+def batched(monkeypatch):
+    """Turn the batched gather on for one test."""
+    monkeypatch.setattr(cq, "BATCHED", True)
+    monkeypatch.setattr(cq, "BATCHED_MAX_BYTES", cq.DEFAULT_BATCHED_MAX_BYTES)
+    return cq
+
+
+@pytest.fixture
+def reference_spy(monkeypatch):
+    calls = []
+    real = cq._gather_qmm_reference
+
+    def spy(*args, **kwargs):
+        calls.append(1)
+        return real(*args, **kwargs)
+    monkeypatch.setattr(cq, "_gather_qmm_reference", spy)
+    return calls
+
+
+# ---- gate ------------------------------------------------------------------------
+
+
+def test_batched_gate_is_on_unless_disabled(monkeypatch):
+    """Default flipped on the Orin's Task 6 acceptance (decode +21% on the
+    target, reference check PASSING the registered bound); ``0`` selects
+    the reference loop and any other value is treated as unset, so a typo
+    cannot silently pick a path."""
+    monkeypatch.delenv("EDGE0_QMM_BATCHED", raising=False)
+    assert cq._read_batched_gate() is True
+    monkeypatch.setenv("EDGE0_QMM_BATCHED", "0")
+    assert cq._read_batched_gate() is False
+    monkeypatch.setenv("EDGE0_QMM_BATCHED", "1")
+    assert cq._read_batched_gate() is True
+    monkeypatch.setenv("EDGE0_QMM_BATCHED", "no")
+    assert cq._read_batched_gate() is True
+    assert cq.DEFAULT_BATCHED_MAX_BYTES == 256 << 20
+    monkeypatch.setenv("EDGE0_QMM_BATCHED_MAX_BYTES", "1024")
+    assert cq._read_batched_max_bytes() == 1024
+    monkeypatch.setenv("EDGE0_QMM_BATCHED_MAX_BYTES", "lots")
+    with pytest.raises(ValueError, match="EDGE0_QMM_BATCHED_MAX_BYTES"):
+        cq._read_batched_max_bytes()
+
+
+def test_reference_path_is_selectable_and_2bit_still_falls_through(
+        reference_spy, monkeypatch):
+    """``EDGE0_QMM_BATCHED=0`` reaches the reference loop, and a layout the
+    batched path does not cover falls through to it even when the (now
+    default-on) gate is set."""
+    codes, packed, s, b = _quantized(0)
+    x = torch.randn(3, D)
+    monkeypatch.setattr(cq, "BATCHED", False)
+    cq.gather_qmm(x, packed, s, b, torch.tensor([1, 2, 3]), transpose=True,
+                  group_size=GS, bits=4)
+    assert reference_spy == [1]
+    monkeypatch.setattr(cq, "BATCHED", True)
+    codes2, packed2, s2, b2 = _quantized(0, bits=2)
+    cq.gather_qmm(x, packed2, s2, b2, torch.tensor([1, 2, 3]), transpose=True,
+                  group_size=GS, bits=2)
+    assert reference_spy == [1, 1]
+
+
+# ---- batched gather: parity ------------------------------------------------------
+
+
+@pytest.mark.parametrize("x_shape,idx_shape", SHAPES)
+def test_batched_matches_hand_reference_and_reference_loop(batched,
+                                                          reference_spy,
+                                                          x_shape, idx_shape):
+    codes, packed, s, b = _quantized(1)
+    gen = torch.Generator().manual_seed(11)
+    x = torch.randn(x_shape, generator=gen)
+    idx = torch.randint(0, E, idx_shape, generator=gen)
+    got = cq.gather_qmm(x, packed, s, b, idx, transpose=True, group_size=GS,
+                        bits=4)
+    assert reference_spy == []                     # the batched path ran
+    ref = _gather_ref64(x, _dequant64(codes, s, b, GS), idx, True)
+    assert got.shape == ref.shape and got.dtype == x.dtype
+    assert torch.allclose(got.double(), ref, rtol=1e-4, atol=1e-4)
+    loop = cq._gather_qmm_reference(x, packed, s, b, idx, True, GS, 4)
+    assert torch.allclose(got, loop, rtol=1e-5, atol=1e-5)
+
+
+def test_batched_no_transpose(batched, reference_spy):
+    codes, packed, s, b = _quantized(2, shape=(E, D, OUT * 4))
+    gen = torch.Generator().manual_seed(12)
+    x = torch.randn(3, 1, 1, D, generator=gen)
+    idx = torch.randint(0, E, (3, 2), generator=gen)
+    got = cq.gather_qmm(x, packed, s, b, idx, transpose=False, group_size=GS,
+                        bits=4)
+    assert reference_spy == []
+    ref = _gather_ref64(x, _dequant64(codes, s, b, GS), idx, False)
+    assert torch.allclose(got.double(), ref, rtol=1e-4, atol=1e-4)
+
+
+def test_batched_sorted_hint_and_repeated_experts_with_padding(batched):
+    """The sorted call pattern with uneven group sizes (Rmax > 1, M > 1):
+    padding rows must never leak into real rows."""
+    codes, packed, s, b = _quantized(3)
+    gen = torch.Generator().manual_seed(13)
+    x = torch.randn(9, 2, D, generator=gen)
+    idx = torch.tensor([0, 0, 0, 0, 3, 3, 5, 7, 7])
+    got = cq.gather_qmm(x, packed, s, b, idx, transpose=True, group_size=GS,
+                        bits=4, sorted_indices=True)
+    ref = _gather_ref64(x, _dequant64(codes, s, b, GS), idx, True)
+    assert torch.allclose(got.double(), ref, rtol=1e-4, atol=1e-4)
+    # unsorted order of the same rows gives the same per-row answers
+    perm = torch.tensor([8, 2, 6, 0, 4, 1, 7, 3, 5])
+    got_p = cq.gather_qmm(x[perm], packed, s, b, idx[perm], transpose=True,
+                          group_size=GS, bits=4)
+    assert torch.allclose(got_p, got[perm], rtol=1e-6, atol=1e-6)
+
+
+def test_batched_negative_scales_and_code_extremes(batched):
+    gen = torch.Generator().manual_seed(4)
+    codes = torch.randint(0, 16, (E, OUT, D), generator=gen)
+    codes[0] = 0                                   # all-zero codes
+    codes[1] = 15                                  # all-max codes
+    codes[2, :, :GS] = 15
+    codes[2, :, GS:] = 0
+    packed = _pack(codes, 4)
+    scales = torch.randn(E, OUT, D // GS, generator=gen) * 4.0   # +/- and large
+    scales[3] = -3.0
+    biases = torch.randn(E, OUT, D // GS, generator=gen) * 20.0
+    x = torch.randn(4, 1, 1, D, generator=gen)
+    idx = torch.tensor([[0, 1], [2, 3], [3, 0], [1, 2]])
+    got = cq.gather_qmm(x, packed, scales, biases, idx, transpose=True,
+                        group_size=GS, bits=4)
+    ref = _gather_ref64(x, _dequant64(codes, scales, biases, GS), idx, True)
+    assert torch.allclose(got.double(), ref, rtol=1e-4, atol=1e-3)
+
+
+def test_batched_index_boundaries(batched):
+    codes, packed, s, b = _quantized(5)
+    x = torch.randn(2, 1, 1, D)
+    last = torch.tensor([[E - 1, 0], [E - 1, E - 1]])
+    got = cq.gather_qmm(x, packed, s, b, last, transpose=True, group_size=GS,
+                        bits=4)
+    ref = _gather_ref64(x, _dequant64(codes, s, b, GS), last, True)
+    assert torch.allclose(got.double(), ref, rtol=1e-4, atol=1e-4)
+    with pytest.raises(IndexError):
+        cq.gather_qmm(x, packed, s, b, torch.tensor([[E, 0], [1, 2]]),
+                      transpose=True, group_size=GS, bits=4)
+    with pytest.raises(IndexError):
+        cq._gather_qmm_reference(x, packed, s, b, torch.tensor([[E, 0], [1, 2]]),
+                                 True, GS, 4)
+
+
+def test_batched_bf16_checkpoint_dtypes(batched):
+    codes, packed, s, b = _quantized(6, dtype=torch.bfloat16)
+    gen = torch.Generator().manual_seed(16)
+    x = torch.randn(4, 1, 1, D, generator=gen).to(torch.bfloat16)
+    idx = torch.randint(0, E, (4, 2), generator=gen)
+    got = cq.gather_qmm(x, packed, s, b, idx, transpose=True, group_size=GS,
+                        bits=4)
+    assert got.dtype == torch.bfloat16
+    ref = _gather_ref64(x, _dequant64(codes, s, b, GS), idx, True)
+    assert torch.allclose(got.double(), ref, rtol=2e-2, atol=1e-1)
+    loop = cq._gather_qmm_reference(x, packed, s, b, idx, True, GS, 4)
+    assert torch.allclose(got.float(), loop.float(), rtol=1e-2, atol=1e-2)
+
+
+# ---- batched gather: guards and fall-through ------------------------------------------
+
+
+@pytest.mark.parametrize("bits", [2, 8])
+def test_batched_falls_through_for_2_and_8_bit(batched, reference_spy, bits):
+    codes, packed, s, b = _quantized(7, bits=bits)
+    x = torch.randn(4, 1, 1, D)
+    idx = torch.randint(0, E, (4, 2))
+    got = cq.gather_qmm(x, packed, s, b, idx, transpose=True, group_size=GS,
+                        bits=bits)
+    assert reference_spy == [1]
+    ref = _gather_ref64(x, _dequant64(codes, s, b, GS), idx, True)
+    assert torch.allclose(got.double(), ref, rtol=1e-4, atol=1e-4)
+
+
+def test_batched_falls_through_when_the_transient_exceeds_the_cap(
+        batched, reference_spy, monkeypatch):
+    codes, packed, s, b = _quantized(8)
+    x = torch.randn(4, 1, 1, D)
+    idx = torch.randint(0, E, (4, 2))
+    monkeypatch.setattr(cq, "BATCHED_MAX_BYTES", 1)
+    got = cq.gather_qmm(x, packed, s, b, idx, transpose=True, group_size=GS,
+                        bits=4)
+    assert reference_spy == [1]
+    ref = _gather_ref64(x, _dequant64(codes, s, b, GS), idx, True)
+    assert torch.allclose(got.double(), ref, rtol=1e-4, atol=1e-4)
+
+
+def test_batched_rejects_non_affine(batched):
+    codes, packed, s, b = _quantized(9)
+    with pytest.raises(NotImplementedError):
+        cq.gather_qmm(torch.randn(2, D), packed, s, b, torch.tensor([0, 1]),
+                      transpose=True, group_size=GS, bits=4, mode="mxfp4")
+
+
+def test_batched_transient_bytes_formula():
+    # decode shape of edge0-8b: 8 distinct experts, one row each, M=1,
+    # in=2048 (up/gate) or 512 (down), out=512 / 2048
+    n = cq.batched_transient_bytes(n_unique=8, rows_max=1, m=1, d_in=2048,
+                                   n_out=512, bits=4)
+    per_expert_elems = 512 * 2048
+    assert n >= 8 * per_expert_elems * 4 * 3      # >= three float32-sized copies
+    assert n <= 8 * per_expert_elems * 4 * 6      # not absurdly loose
+    assert cq.batched_transient_bytes(1, 1, 1, 64, 8) > 0
+    with pytest.raises(ValueError):
+        cq.batched_transient_bytes(0, 1, 1, 64, 8)
+
+
+# ---- batched gather on an actual CUDA device ------------------------------------------
+# Skips without a device; FAILS with --require-cuda (the acceptance contract
+# of tests/test_torch_cuda_smoke.py).  Numbers measured here are workstation
+# evidence for the instrumentation, never Orin evidence.
+
+
+@pytest.fixture(scope="module")
+def torch_cuda(request):
+    from tests.test_torch_cuda_smoke import _torch_with_cuda
+    return _torch_with_cuda(request)
+
+
+@pytest.mark.parametrize("x_shape,idx_shape", SHAPES)
+def test_batched_on_cuda_matches_hand_reference(torch_cuda, batched,
+                                                x_shape, idx_shape):
+    codes, packed, s, b = _quantized(21)
+    gen = torch.Generator().manual_seed(31)
+    x = torch.randn(x_shape, generator=gen)
+    idx = torch.randint(0, E, idx_shape, generator=gen)
+    got = cq.gather_qmm(x.cuda(), packed.cuda(), s.cuda(), b.cuda(),
+                        idx.cuda(), transpose=True, group_size=GS, bits=4)
+    torch.cuda.synchronize()
+    assert got.device.type == "cuda"
+    assert torch.isfinite(got).all()
+    ref = _gather_ref64(x, _dequant64(codes, s, b, GS), idx, True)
+    assert torch.allclose(got.cpu().double(), ref, rtol=1e-4, atol=1e-4)
+
+
+def test_batched_on_cuda_padding_and_bf16(torch_cuda, batched):
+    codes, packed, s, b = _quantized(22, dtype=torch.bfloat16)
+    gen = torch.Generator().manual_seed(32)
+    x = torch.randn(9, 2, D, generator=gen).to(torch.bfloat16)
+    idx = torch.tensor([4, 4, 4, 1, 1, 7, 0, 0, 0])
+    got = cq.gather_qmm(x.cuda(), packed.cuda(), s.cuda(), b.cuda(),
+                        idx.cuda(), transpose=True, group_size=GS, bits=4,
+                        sorted_indices=True)
+    torch.cuda.synchronize()
+    assert got.dtype == torch.bfloat16
+    ref = _gather_ref64(x, _dequant64(codes, s, b, GS), idx, True)
+    assert torch.allclose(got.cpu().double(), ref, rtol=2e-2, atol=1e-1)
+
+
+def _decode_shape_inputs(seed):
+    """The edge0-8b decode shape of one up/gate projection: 8 distinct
+    experts for one token, out 512, in 2048."""
+    n_experts, out_f, in_f = 128, 512, 2048
+    gen = torch.Generator().manual_seed(seed)
+    codes = torch.randint(0, 16, (n_experts, out_f, in_f), generator=gen)
+    packed = _pack(codes, 4)
+    scales = (torch.randn(n_experts, out_f, in_f // GS, generator=gen) * 0.1
+              ).to(torch.bfloat16)
+    biases = (torch.randn(n_experts, out_f, in_f // GS, generator=gen) * 0.05
+              ).to(torch.bfloat16)
+    x = torch.randn(1, 1, 1, in_f, generator=gen).to(torch.bfloat16)
+    idx = torch.tensor([[3, 17, 42, 64, 65, 99, 100, 127]])
+    return packed, scales, biases, x, idx
+
+
+def test_batched_transient_on_cuda_is_within_the_priced_bound(torch_cuda,
+                                                              batched):
+    packed, scales, biases, x, idx = (t.cuda() for t in _decode_shape_inputs(41))
+    priced = cq.batched_transient_bytes(n_unique=8, rows_max=1, m=1,
+                                        d_in=2048, n_out=512, bits=4,
+                                        group_size=GS, scale_itemsize=2)
+    torch.cuda.synchronize()
+    torch.cuda.reset_peak_memory_stats()
+    base = torch.cuda.memory_allocated()
+    out = cq.gather_qmm(x, packed, scales, biases, idx, transpose=True,
+                        group_size=GS, bits=4)
+    torch.cuda.synchronize()
+    peak = torch.cuda.max_memory_allocated() - base
+    del out
+    assert peak <= priced, f"measured transient {peak} > priced {priced}"
+    assert peak >= priced // 4, f"pricing is > 4x loose: {peak} vs {priced}"
+
+
+def _count_cuda_kernels(fn):
+    from torch.profiler import ProfilerActivity, profile
+    fn()                                   # warm up (allocator, cuBLAS)
+    torch.cuda.synchronize()
+    with profile(activities=[ProfilerActivity.CUDA]) as prof:
+        fn()
+        torch.cuda.synchronize()
+    return sum(1 for ev in (prof.events() or [])
+               if ev.device_type == torch.autograd.DeviceType.CUDA)
+
+
+def test_batched_launches_fewer_kernels_than_the_loop(torch_cuda, monkeypatch):
+    """Launch count is the architecture-independent part of the win: the
+    reference loop launches ~8x (dequant chain + matmul) per distinct
+    expert, the batched path launches one chain + one bmm."""
+    packed, scales, biases, x, idx = (t.cuda() for t in _decode_shape_inputs(42))
+    monkeypatch.setattr(cq, "BATCHED_MAX_BYTES", cq.DEFAULT_BATCHED_MAX_BYTES)
+    monkeypatch.setattr(cq, "BATCHED", False)
+    loop = _count_cuda_kernels(lambda: cq.gather_qmm(
+        x, packed, scales, biases, idx, transpose=True, group_size=GS, bits=4))
+    monkeypatch.setattr(cq, "BATCHED", True)
+    batched_n = _count_cuda_kernels(lambda: cq.gather_qmm(
+        x, packed, scales, biases, idx, transpose=True, group_size=GS, bits=4))
+    assert batched_n * 3 <= loop, (loop, batched_n)
+
+
+def test_batched_is_within_one_bfloat16_ulp_at_the_real_decode_shapes(
+        torch_cuda, batched):
+    """Parity at the shapes the 8B tier actually decodes with, in the
+    checkpoint's dtypes.  The two paths dequantize identically and differ
+    only in how cuBLAS reduces the matmul, so the bf16 result must land on
+    the same value or its neighbour -- one ulp, not a tolerance chosen
+    after the fact.  End to end through 24 layers this accumulates: the
+    workstation reference check measured max |dlogit| 1.01 with all 32
+    token choices identical."""
+    for n_experts, out_f, in_f, name in ((128, 512, 1536, "up/gate"),
+                                         (128, 1536, 512, "down")):
+        gen = torch.Generator().manual_seed(80 + out_f)
+        codes = torch.randint(0, 16, (n_experts, out_f, in_f), generator=gen)
+        packed = _pack(codes, 4).cuda()
+        scales = (torch.randn(n_experts, out_f, in_f // GS, generator=gen)
+                  * 0.05).to(torch.bfloat16).cuda()
+        biases = (torch.randn(n_experts, out_f, in_f // GS, generator=gen)
+                  * 0.05).to(torch.bfloat16).cuda()
+        x = torch.randn(1, 1, 1, in_f, generator=gen).to(torch.bfloat16).cuda()
+        idx = torch.tensor([[3, 17, 42, 64, 65, 99, 100, 127]]).cuda()
+        got = cq.gather_qmm(x, packed, scales, biases, idx, transpose=True,
+                            group_size=GS, bits=4)
+        loop = cq._gather_qmm_reference(x, packed, scales, biases, idx,
+                                        True, GS, 4)
+        torch.cuda.synchronize()
+        assert got.dtype == torch.bfloat16
+        diff = (got.float() - loop.float()).abs()
+        # one bfloat16 ulp of each element (8 mantissa bits)
+        ulp = torch.ldexp(torch.ones_like(diff),
+                          torch.floor(torch.log2(
+                              loop.float().abs().clamp_min(1e-30))) - 7)
+        assert (diff <= ulp).all(), (
+            name, diff.max().item(), (diff / ulp).max().item())
diff --git a/tests/test_sampling.py b/tests/test_sampling.py
index 965c01c..6583f77 100644
--- a/tests/test_sampling.py
+++ b/tests/test_sampling.py
@@ -2,10 +2,11 @@
 
 from __future__ import annotations
 
-import mlx.core as mx
 import pytest
 
-from edge0.sampling import _mask_logits, sample
+mx = pytest.importorskip("mlx.core")
+
+from edge0.sampling import _mask_logits, sample  # noqa: E402
 
 
 def test_mask_identity_for_sane_kwargs():
diff --git a/tests/test_streaming_math.py b/tests/test_streaming_math.py
index e77154e..96d3ba8 100644
--- a/tests/test_streaming_math.py
+++ b/tests/test_streaming_math.py
@@ -11,13 +11,15 @@
 
 import numpy as np
 import pytest
-import mlx.core as mx
-import mlx.nn as nn
-from safetensors.numpy import save_file
 
-from edge0.moe.spec import MoESpec, QuantSpec, WeightLayout
-from edge0.streaming.cache import SharedExpertCache
-from edge0.streaming.layer import StreamingSwitchGLU
+mx = pytest.importorskip("mlx.core")
+nn = pytest.importorskip("mlx.nn")
+
+from safetensors.numpy import save_file  # noqa: E402
+
+from edge0.moe.spec import MoESpec, QuantSpec, WeightLayout  # noqa: E402
+from edge0.streaming.cache import SharedExpertCache  # noqa: E402
+from edge0.streaming.layer import StreamingSwitchGLU  # noqa: E402
 from edge0.streaming.mmap import SafetensorsMmap
 from edge0.streaming.options import LayerOptions
 
diff --git a/tests/test_task6_budget.py b/tests/test_task6_budget.py
new file mode 100644
index 0000000..653d389
--- /dev/null
+++ b/tests/test_task6_budget.py
@@ -0,0 +1,126 @@
+"""Task 6 pricing in the memory budget (pure, no backend, no weights).
+
+* ``Reserves.kernel_transient_bytes`` deducts the batched gather's
+  per-call transient cap once, like every other transient.
+* ``budget.dense_cache_request`` turns the two dense-weight-cache knobs
+  (``EDGE0_TORCH_WEIGHT_CACHE=1`` full, ``..._BYTES=<n>`` capped) and the
+  loader's measured candidate total into what the budget prices and how
+  the policy is finalized afterwards (``engine.ling`` calls it) -- the
+  full cache keeps its veto, the capped one shrinks to the headroom.
+"""
+
+from __future__ import annotations
+
+import pytest
+
+from edge0.streaming import budget as b
+from edge0.streaming.budget import (
+    dense_cache_request as _dense_cache_request,
+)
+from edge0.streaming.budget import (
+    effective_capped_bytes as _effective_capped_bytes,
+)
+
+OBS = b.Observation(available_bytes=8_000_000_000)
+EXPERTS = b.ExpertFootprint(bundle_bytes=1_300_000, num_experts=128,
+                            num_moe_layers=23)
+WORKLOAD = b.WorkloadDecl(max_context_tokens=1024, kv_bytes_per_token=1_100_000)
+
+
+def _resolve(**kw):
+    kw.setdefault("requested_cache_slots", 64)
+    kw.setdefault("requested_prefetch_cap", 48)
+    kw.setdefault("full_layer_prefill", True)
+    kw.setdefault("inflight_builds", 8)
+    return b.resolve_budget(OBS, EXPERTS, WORKLOAD, **kw)
+
+
+def test_kernel_transient_is_deducted_once_and_itemized():
+    plain = _resolve()
+    with_kernel = _resolve(reserves=b.Reserves(kernel_transient_bytes=256 << 20))
+    names = dict(with_kernel.deductions)
+    assert names["kernel_transient"] == 256 << 20
+    assert dict(plain.deductions)["kernel_transient"] == 0
+    assert (plain.cache_allowance_bytes - with_kernel.cache_allowance_bytes
+            == 256 << 20)
+    serialized = dict(map(tuple, with_kernel.as_dict()["deductions"]))
+    assert serialized["kernel_transient"] == 256 << 20
+
+
+def test_kernel_transient_must_be_a_non_negative_int():
+    with pytest.raises(b.BudgetError, match="kernel_transient_bytes"):
+        _resolve(reserves=b.Reserves(kernel_transient_bytes=-1))
+    with pytest.raises(b.BudgetError, match="kernel_transient_bytes"):
+        _resolve(reserves=b.Reserves(
+            kernel_transient_bytes=1.5))  # type: ignore[arg-type]
+
+
+# ---- dense cache request (engine helper) ----------------------------------------------
+
+
+def test_dense_cache_request_full_uses_the_measured_total():
+    req = _dense_cache_request(full_requested=True, cap_bytes=None,
+                               candidate_total=1_400_000_000)
+    assert req == {"mode": "full", "priced_bytes": 1_400_000_000,
+                   "resident_bytes": 1_400_000_000,
+                   "fill_transient_bytes": 0, "cap_bytes": None}
+
+
+def test_dense_cache_request_prices_the_build_transient_on_top():
+    """The weights are filled lazily at the first forward, one chunked
+    module at a time: exactly one transient is live, and it must still fit
+    beside everything resident."""
+    req = _dense_cache_request(full_requested=True, cap_bytes=None,
+                               candidate_total=1_400_000_000,
+                               max_fill_transient_bytes=106_000_000)
+    assert req["resident_bytes"] == 1_400_000_000
+    assert req["fill_transient_bytes"] == 106_000_000
+    assert req["priced_bytes"] == 1_506_000_000
+    capped = _dense_cache_request(full_requested=False,
+                                  cap_bytes=500_000_000,
+                                  candidate_total=1_400_000_000,
+                                  max_fill_transient_bytes=106_000_000)
+    assert capped["priced_bytes"] == 606_000_000
+    off = _dense_cache_request(full_requested=False, cap_bytes=None,
+                               candidate_total=1_400_000_000,
+                               max_fill_transient_bytes=106_000_000)
+    assert off["priced_bytes"] == 0 and off["fill_transient_bytes"] == 0
+    with pytest.raises(b.BudgetError, match="max_fill_transient_bytes"):
+        _dense_cache_request(full_requested=True, cap_bytes=None,
+                             candidate_total=1, max_fill_transient_bytes=-1)
+
+
+def test_dense_cache_request_full_without_candidates_keeps_the_gb10_figure():
+    req = _dense_cache_request(full_requested=True, cap_bytes=None,
+                               candidate_total=0)
+    assert req["mode"] == "full" and req["priced_bytes"] == 4_100_000_000
+
+
+def test_dense_cache_request_capped_prices_min_of_cap_and_total():
+    req = _dense_cache_request(full_requested=False, cap_bytes=1_000_000_000,
+                               candidate_total=1_400_000_000)
+    assert req == {"mode": "capped", "priced_bytes": 1_000_000_000,
+                   "resident_bytes": 1_000_000_000,
+                   "fill_transient_bytes": 0, "cap_bytes": 1_000_000_000}
+    req = _dense_cache_request(full_requested=False, cap_bytes=2_000_000_000,
+                               candidate_total=1_400_000_000)
+    assert req["priced_bytes"] == 1_400_000_000
+
+
+def test_dense_cache_request_off():
+    assert _dense_cache_request(full_requested=False, cap_bytes=None,
+                                candidate_total=5)["mode"] == "off"
+    assert _dense_cache_request(full_requested=False, cap_bytes=0,
+                                candidate_total=5)["mode"] == "off"
+
+
+def test_dense_cache_request_full_wins_over_a_cap():
+    req = _dense_cache_request(full_requested=True, cap_bytes=10,
+                               candidate_total=99)
+    assert req["mode"] == "full" and req["priced_bytes"] == 99
+
+
+def test_capped_cache_effective_cap_is_min_of_cap_and_headroom():
+    assert _effective_capped_bytes(cap_bytes=1_000, headroom_bytes=5_000) == 1_000
+    assert _effective_capped_bytes(cap_bytes=1_000, headroom_bytes=300) == 300
+    assert _effective_capped_bytes(cap_bytes=1_000, headroom_bytes=-5) == 0
diff --git a/tests/test_torch_cuda_smoke.py b/tests/test_torch_cuda_smoke.py
new file mode 100644
index 0000000..33cba12
--- /dev/null
+++ b/tests/test_torch_cuda_smoke.py
@@ -0,0 +1,192 @@
+"""Torch-only CUDA acceptance smoke (Task 3, Gate B).
+
+Runs representative ``edge0.backends.cuda`` operations on an actual CUDA
+device, synchronizes, and compares against deterministic references that
+are computed independently of the code under test (hand-packed int4
+codes dequantized by the documented formula, float64 matmul on the CPU).
+No MLX import anywhere in this module: this suite must be runnable on a
+Jetson where MLX does not exist.
+
+Contract:
+
+* plain ``pytest tests/test_torch_cuda_smoke.py`` skips when torch or a
+  CUDA device is missing (hosts, CI) — unchanged behavior for everyone
+  else;
+* ``pytest tests/test_torch_cuda_smoke.py --require-cuda`` FAILS in the
+  same situations.  This is the acceptance invocation on the Orin: a
+  quiet skip or a CPU fallback must not read as CUDA evidence.
+
+Passing here shows the toolchain executes kernels correctly on the
+device.  It is NOT model correctness (that is the 32-token reference
+check) and NOT a performance statement.
+"""
+
+from __future__ import annotations
+
+import pytest
+
+
+def _torch_with_cuda(request):
+    required = request.config.getoption("--require-cuda")
+    # ``edge0.backends`` binds to EDGE0_BACKEND at first import and
+    # defaults to mlx, which does not exist on a Jetson.  This suite is
+    # torch-only by contract, so select the cuda backend before any
+    # test body imports ``edge0.backends.cuda.*`` (an explicit
+    # EDGE0_BACKEND from the environment still wins).
+    import os
+    os.environ.setdefault("EDGE0_BACKEND", "cuda")
+    try:
+        import torch
+    except ImportError:
+        if required:
+            pytest.fail("--require-cuda: torch is not importable in this "
+                        "environment", pytrace=False)
+        pytest.skip("torch not installed")
+    if not torch.cuda.is_available():
+        if required:
+            pytest.fail("--require-cuda: torch.cuda.is_available() is False "
+                        f"(torch {torch.__version__}, built for CUDA "
+                        f"{torch.version.cuda})", pytrace=False)
+        pytest.skip("no CUDA device")
+    # A device can be visible yet unable to run kernels (driver policy,
+    # missing SASS/PTX for this arch).  Prove execution before any test
+    # trusts an op's output.
+    try:
+        probe = (torch.arange(4, device="cuda", dtype=torch.float32) * 2).sum()
+        torch.cuda.synchronize()
+        value = float(probe.item())
+    except Exception as exc:  # noqa: BLE001 - report whatever CUDA raised
+        if required:
+            pytest.fail(f"--require-cuda: CUDA device visible but kernel "
+                        f"execution failed: {exc!r}", pytrace=False)
+        pytest.skip(f"CUDA present but not executing: {exc!r}")
+    assert value == 12.0
+    return torch
+
+
+@pytest.fixture(scope="module")
+def torch_cuda(request):
+    return _torch_with_cuda(request)
+
+
+def _pack_int4(torch, codes):
+    """Pack int codes in [0, 15] along the last axis, 8 per uint32 word,
+    least significant bits first — the layout documented in
+    ``backends/cuda/quant.py`` and verified against ``mx.quantize``."""
+    assert codes.shape[-1] % 8 == 0
+    grouped = codes.reshape(*codes.shape[:-1], -1, 8).to(torch.int64)
+    shifts = torch.arange(8, dtype=torch.int64) * 4
+    words = (grouped << shifts).sum(-1)
+    return words.to(torch.int32).view(torch.uint32)
+
+
+def test_device_identity_and_finite(torch_cuda):
+    torch = torch_cuda
+    gen = torch.Generator().manual_seed(0)
+    a = torch.randn(64, 128, generator=gen)
+    b = torch.randn(128, 32, generator=gen)
+    out = a.cuda() @ b.cuda()
+    torch.cuda.synchronize()
+    assert out.device.type == "cuda"
+    assert torch.isfinite(out).all()
+    ref = (a.double() @ b.double()).float()
+    assert torch.allclose(out.cpu(), ref, rtol=1e-4, atol=1e-4)
+
+
+def test_unsigned_word_view_matches_cpu(torch_cuda):
+    """The int4 path stores packed words as uint32 and dequantizes through
+    an int32 view with shifts and masks; the top bit must survive the
+    round trip on the device exactly as it does on the CPU."""
+    torch = torch_cuda
+    words = torch.tensor([0x80000001, 0xFFFFFFFF, 0x7FFFFFFF, 0],
+                         dtype=torch.int64).to(torch.int32).view(torch.uint32)
+    shifts = torch.arange(8, dtype=torch.int32) * 4
+    def unpack(w, s):
+        return (w.view(torch.int32).unsqueeze(-1) >> s) & 0xF
+    got = unpack(words.cuda(), shifts.cuda())
+    torch.cuda.synchronize()
+    assert got.device.type == "cuda"
+    assert torch.equal(got.cpu(), unpack(words, shifts))
+
+
+def test_rmsnorm_runs_on_cuda(torch_cuda):
+    """`torch.nn.RMSNorm` is the API the backend's nn module subclasses
+    (Gate A lists it as a required import)."""
+    torch = torch_cuda
+    from edge0.backends.cuda import nn as cnn
+    norm = cnn.RMSNorm(64, eps=1e-6).cuda()
+    gen = torch.Generator().manual_seed(1)
+    x = torch.randn(3, 64, generator=gen).cuda()
+    out = norm(x)
+    torch.cuda.synchronize()
+    assert out.device.type == "cuda"
+    assert torch.isfinite(out).all()
+    xr = x.cpu().double()
+    ref = (xr * torch.rsqrt(xr.pow(2).mean(-1, keepdim=True) + 1e-6)).float()
+    assert torch.allclose(out.cpu(), ref, rtol=1e-4, atol=1e-5)
+
+
+def test_gather_qmm_cuda_matches_hand_reference(torch_cuda):
+    """End-to-end int4 expert gather on the device against a reference
+    dequantized by the documented formula (code * scale + bias) in
+    float64 on the CPU — independent of ``quant._dequantize``."""
+    torch = torch_cuda
+    from edge0.backends.cuda import quant as cq
+    E, O, D, GS = 4, 8, 64, 32
+    gen = torch.Generator().manual_seed(2)
+    codes = torch.randint(0, 16, (E, O, D), generator=gen)
+    packed = _pack_int4(torch, codes)
+    scales = (torch.randn(E, O, D // GS, generator=gen) * 0.1)
+    # negative scales and biases on purpose: nothing may assume otherwise
+    biases = torch.randn(E, O, D // GS, generator=gen) * 0.05
+    x = torch.randn(3, 1, D, generator=gen)
+    idx = torch.tensor([2, 0, 3], dtype=torch.int64)
+
+    got = cq.gather_qmm(x.cuda(), packed.cuda(), scales.cuda(), biases.cuda(),
+                        idx.cuda(), transpose=True, group_size=GS, bits=4)
+    torch.cuda.synchronize()
+    assert got.device.type == "cuda"
+    assert torch.isfinite(got).all()
+
+    w = (codes.double().reshape(E, O, D // GS, GS)
+         * scales.double().unsqueeze(-1)
+         + biases.double().unsqueeze(-1)).reshape(E, O, D)
+    ref = torch.stack([x[i, :, :].double() @ w[e].T
+                       for i, e in enumerate(idx.tolist())]).float()
+    assert got.shape == ref.shape
+    assert torch.allclose(got.cpu(), ref, rtol=1e-4, atol=1e-4)
+
+
+def test_gather_sort_roundtrip_on_cuda(torch_cuda):
+    torch = torch_cuda
+    from edge0.backends.cuda import quant as cq
+    gen = torch.Generator().manual_seed(3)
+    T, K, D = 6, 2, 16
+    x = torch.randn(T, 1, 1, D, generator=gen).cuda()
+    idx = torch.randint(0, 4, (T, K), generator=gen).cuda()
+    xs, idx_sorted, inv = cq.gather_sort(x, idx)
+    torch.cuda.synchronize()
+    assert xs.device.type == "cuda"
+    assert torch.equal(idx_sorted, idx.reshape(-1).long().sort(stable=True).values)
+    restored = cq.scatter_unsort(xs, inv, shape=(T, K))
+    assert torch.equal(restored[:, 0], x.squeeze(1))
+
+
+def test_core_ops_and_sampler_on_cuda(torch_cuda):
+    """The core facade ops the decode loop leans on (softmax, topk,
+    argmax, take_along_axis) on the CUDA device against CPU torch."""
+    torch = torch_cuda
+    from edge0.backends.cuda import core
+    gen = torch.Generator().manual_seed(4)
+    logits = torch.randn(1, 512, generator=gen)
+    lc = logits.cuda()
+    sm = core.softmax(lc, axis=-1)
+    torch.cuda.synchronize()
+    assert sm.device.type == "cuda"
+    assert torch.allclose(sm.cpu(), torch.softmax(logits, dim=-1),
+                          rtol=1e-5, atol=1e-6)
+    assert int(core.argmax(lc, axis=-1).item()) == int(logits.argmax(-1))
+    vals, _ = torch.topk(logits, 8)
+    got_topk = core.topk(lc, 8, axis=-1)
+    assert torch.allclose(torch.sort(got_topk.cpu(), descending=True).values,
+                          vals, rtol=0, atol=0)
diff --git a/tests/test_weight_cache_policy.py b/tests/test_weight_cache_policy.py
new file mode 100644
index 0000000..793a81c
--- /dev/null
+++ b/tests/test_weight_cache_policy.py
@@ -0,0 +1,346 @@
+"""Capped exact dequantized-weight cache (Task 6, workstation side).
+
+``EDGE0_TORCH_WEIGHT_CACHE=1`` keeps EVERY dense weight dequantized
+(a measured 4.1 GB resident delta on the GB10; edge0-8b's dequantized
+dense weights are 1.40 GB in bf16).  ``EDGE0_TORCH_WEIGHT_CACHE_BYTES=<n>``
+keeps only the modules that fit a byte cap, admitted in registration
+order with each module's own build transient counted, and the engine
+re-finalizes the cap against the Task 4 budget's headroom.
+
+The cached weight is built with the SAME per-chunk expression as the
+on-the-fly path, so the dequantized weight is bit-identical (asserted on
+CUDA below); the cached forward then issues one GEMM where the
+on-the-fly path issues one per 4096-row chunk, which cuBLAS may split
+differently for modules wider than a chunk -- outputs are identical here
+and on the CPU, and the reference check is what decides on the device.
+
+No MLX, no checkpoint; modules are built from hand-packed codes.
+"""
+
+from __future__ import annotations
+
+import os
+
+import pytest
+
+os.environ.setdefault("EDGE0_BACKEND", "cuda")
+torch = pytest.importorskip("torch")
+
+from edge0.backends.cuda import nn as cnn  # noqa: E402
+from tests.test_quant_paths import _dequant64, _pack  # noqa: E402
+
+
+def _linear(seed, out_f=32, in_f=128, group=64, dtype=torch.bfloat16):
+    gen = torch.Generator().manual_seed(seed)
+    codes = torch.randint(0, 16, (out_f, in_f), generator=gen)
+    scales = (torch.randn(out_f, in_f // group, generator=gen) * 0.1).to(dtype)
+    biases = (torch.randn(out_f, in_f // group, generator=gen) * 0.05).to(dtype)
+    mod = cnn.QuantizedLinear(_pack(codes, 4), scales, biases, in_f)
+    return mod, codes, scales, biases
+
+
+@pytest.fixture
+def policy(monkeypatch):
+    monkeypatch.setattr(cnn, "CACHE_DEQUANTIZED", False)
+    p = cnn.WeightCachePolicy(cap_bytes=None)
+    monkeypatch.setattr(cnn, "WEIGHT_CACHE", p)
+    return p
+
+
+# ---- env parsing --------------------------------------------------------------------
+
+
+def test_cap_env_parsing(monkeypatch):
+    monkeypatch.delenv("EDGE0_TORCH_WEIGHT_CACHE_BYTES", raising=False)
+    assert cnn._read_weight_cache_cap() is None
+    monkeypatch.setenv("EDGE0_TORCH_WEIGHT_CACHE_BYTES", "1000000")
+    assert cnn._read_weight_cache_cap() == 1_000_000
+    monkeypatch.setenv("EDGE0_TORCH_WEIGHT_CACHE_BYTES", "0")
+    assert cnn._read_weight_cache_cap() == 0
+    for bad in ("1GB", "-5", "1.5"):
+        monkeypatch.setenv("EDGE0_TORCH_WEIGHT_CACHE_BYTES", bad)
+        with pytest.raises(ValueError, match="EDGE0_TORCH_WEIGHT_CACHE_BYTES"):
+            cnn._read_weight_cache_cap()
+
+
+def test_dequantized_bytes_prices_out_in_itemsize():
+    mod, *_ = _linear(0, out_f=32, in_f=128)
+    assert cnn.dequantized_bytes(mod) == 32 * 128 * 2          # bf16 scales
+    mod32, *_ = _linear(0, out_f=32, in_f=128, dtype=torch.float32)
+    assert cnn.dequantized_bytes(mod32) == 32 * 128 * 4
+
+
+# ---- admission -----------------------------------------------------------------------
+
+
+def test_policy_admits_in_registration_order_until_the_cap(policy):
+    mods = [_linear(i, out_f=32, in_f=128)[0] for i in range(4)]   # 8192 B each
+    fill = cnn.fill_transient_bytes(mods[0])       # 4 * 32 * 128 * 4
+    for i, m in enumerate(mods):
+        policy.register(f"layers.{i}.q", m)
+    summary = policy.finalize(cap_bytes=8192 * 2 + fill)
+    assert [m.cache_weight for m in mods] == [True, True, False, False]
+    assert summary["effective_cap_bytes"] == 8192 * 2 + fill
+    assert summary["admitted_bytes"] == 8192 * 2
+    assert summary["max_fill_transient_bytes"] == fill
+    assert [a["path"] for a in summary["admitted"]] == ["layers.0.q", "layers.1.q"]
+    assert all(a["fill_transient_bytes"] == fill for a in summary["admitted"])
+    assert [s["path"] for s in summary["skipped"]] == ["layers.2.q", "layers.3.q"]
+    assert summary["candidate_bytes_total"] == 8192 * 4
+    assert summary["finalized"] is True
+
+
+def test_admission_counts_each_modules_own_build_transient(policy):
+    """Resident bytes alone would admit a module whose chunked fill then
+    OOMs; the cap must cover the build too."""
+    mod, *_ = _linear(11, out_f=32, in_f=128)
+    resident = cnn.dequantized_bytes(mod)          # 8192
+    fill = cnn.fill_transient_bytes(mod)           # 65536: 8x the resident
+    assert fill > resident
+    policy.register("m", mod)
+    assert policy.finalize(cap_bytes=resident + fill - 1)["admitted"] == []
+    assert mod.cache_weight is False
+    assert policy.finalize(cap_bytes=resident + fill)["admitted_bytes"] == resident
+    assert mod.cache_weight is True
+
+
+def _priced_fill(rows, in_f, group=64, itemsize=2):
+    groups = -(-in_f // group)
+    return (4 * rows * in_f * 4 + 2 * rows * groups * (itemsize + 4)
+            + rows * in_f * itemsize)
+
+
+def test_fill_transient_is_bounded_by_the_chunk_not_the_module():
+    chunk = cnn.QuantizedLinear.ROWS_PER_CHUNK
+    narrow, *_ = _linear(12, out_f=100, in_f=128)
+    wide, *_ = _linear(13, out_f=3 * chunk, in_f=128)
+    wider, *_ = _linear(14, out_f=9 * chunk, in_f=128)
+    assert cnn.fill_transient_bytes(narrow) == _priced_fill(100, 128)
+    assert cnn.fill_transient_bytes(wide) == _priced_fill(chunk, 128)
+    # three times the rows, same transient: the chunk bounds it
+    assert cnn.fill_transient_bytes(wider) == cnn.fill_transient_bytes(wide)
+    assert cnn.dequantized_bytes(wider) == 3 * cnn.dequantized_bytes(wide)
+
+
+def test_policy_first_fit_skips_an_oversize_module_but_admits_later_ones(policy):
+    big, *_ = _linear(1, out_f=256, in_f=128)      # 65536 B resident
+    small, *_ = _linear(2, out_f=32, in_f=128)      # 8192 B resident
+    policy.register("lm_head", big)
+    policy.register("layers.0.q", small)
+    cap = cnn.dequantized_bytes(small) + cnn.fill_transient_bytes(small)
+    s = policy.finalize(cap_bytes=cap)
+    assert big.cache_weight is False and small.cache_weight is True
+    assert s["skipped"][0]["reason"].startswith("does not fit")
+    assert "build transient" in s["skipped"][0]["reason"]
+
+
+def test_policy_off_when_cap_is_none_or_zero(policy):
+    mod, *_ = _linear(3)
+    policy.register("m", mod)
+    assert policy.finalize(cap_bytes=None)["enabled"] is False
+    assert mod.cache_weight is False
+    assert policy.finalize(cap_bytes=0)["enabled"] is False
+    assert mod.cache_weight is False
+
+
+def test_policy_from_env(monkeypatch):
+    monkeypatch.setenv("EDGE0_TORCH_WEIGHT_CACHE_BYTES", "4096")
+    p = cnn.WeightCachePolicy.from_env()
+    assert p.cap_bytes == 4096 and p.enabled
+
+
+def test_policy_begin_clears_candidates(policy):
+    mod, *_ = _linear(4)
+    policy.register("m", mod)
+    policy.begin()
+    assert policy.finalize(cap_bytes=1 << 30)["admitted"] == []
+
+
+# ---- exactness --------------------------------------------------------------------------
+
+
+def test_cached_output_is_bit_identical_to_on_the_fly(policy):
+    mod, codes, scales, biases = _linear(5, out_f=5000, in_f=256)  # > one chunk
+    gen = torch.Generator().manual_seed(15)
+    x = torch.randn(3, 256, generator=gen).to(torch.bfloat16)
+    with torch.no_grad():
+        plain = mod(x)
+        policy.register("m", mod)
+        policy.finalize(cap_bytes=1 << 31)
+        assert mod.cache_weight
+        first = mod(x)
+        second = mod(x)
+    assert torch.equal(plain, first) and torch.equal(first, second)
+    assert mod._dequantized is not None and mod._dequantized[0] == torch.bfloat16
+    ref = x.double() @ _dequant64(codes, scales, biases, 64).T
+    assert torch.allclose(first.double(), ref, rtol=2e-2, atol=1e-1)
+
+
+def test_activation_itemsize_mismatch_falls_through_without_caching(policy):
+    """An admitted module priced at bf16 must NOT cache a float32 weight:
+    that would silently double the bytes the budget reserved.
+
+    This is not hypothetical -- in the 8B engine 400 of 470 dense calls
+    per step arrive as float32, so most admitted modules never fill.  The
+    reservation is therefore conservative (it never under-reserves), and
+    the bench report states filled bytes next to admitted bytes so the
+    two are not confused.
+    """
+    mod, *_ = _linear(6)                    # priced at bf16 (2 bytes)
+    policy.register("m", mod)
+    policy.finalize(cap_bytes=1 << 20)
+    assert mod.cache_weight                 # admitted...
+    x = torch.randn(2, 128)                 # ...but called with float32
+    with torch.no_grad():
+        out = mod(x)
+    assert mod._dequantized is None         # nothing cached at the wrong size
+    assert out.dtype == torch.float32
+    with torch.no_grad():                   # and the matching dtype does fill
+        mod(x.to(torch.bfloat16))
+    assert mod._dequantized is not None
+    assert mod._dequantized[0] == torch.bfloat16
+
+
+def test_refinalize_with_a_smaller_cap_drops_the_cached_weight(policy):
+    a, *_ = _linear(7)
+    b, *_ = _linear(8)
+    policy.register("a", a)
+    policy.register("b", b)
+    policy.finalize(cap_bytes=1 << 20)
+    x = torch.randn(2, 128).to(torch.bfloat16)
+    with torch.no_grad():
+        a(x)
+        b(x)
+    assert a._dequantized is not None and b._dequantized is not None
+    fill = cnn.fill_transient_bytes(a)
+    s = policy.finalize(cap_bytes=8192 + fill)   # only the first fits now
+    assert a.cache_weight and not b.cache_weight
+    assert b._dequantized is None           # released, not stale
+    assert s["admitted_bytes"] == 8192
+
+
+def test_full_cache_env_still_wins(policy, monkeypatch):
+    monkeypatch.setattr(cnn, "CACHE_DEQUANTIZED", True)
+    mod, *_ = _linear(9)
+    x = torch.randn(2, 128).to(torch.bfloat16)
+    with torch.no_grad():
+        mod(x)
+    assert mod._dequantized is not None
+
+
+def test_summary_is_json_friendly(policy):
+    mod, *_ = _linear(10)
+    policy.register("layers.0.q", mod)
+    s = policy.finalize(cap_bytes=1 << 20)
+    import json
+    json.dumps(s, allow_nan=False)
+    assert s["requested_cap_bytes"] == 1 << 20
+    assert set(s) >= {"enabled", "requested_cap_bytes", "effective_cap_bytes",
+                      "admitted_bytes", "admitted", "skipped",
+                      "candidate_bytes_total", "candidate_count", "finalized"}
+
+
+# ---- loader registration ------------------------------------------------------------------
+
+
+def test_install_quantized_registers_candidates(policy):
+    from edge0.backends.cuda import io as cio
+    gen = torch.Generator().manual_seed(20)
+
+    class Tiny(torch.nn.Module):
+        def __init__(self):
+            super().__init__()
+            self.proj = torch.nn.Linear(128, 32, bias=False)
+            self.emb = torch.nn.Embedding(10, 128)
+
+    model = Tiny()
+    codes = torch.randint(0, 16, (32, 128), generator=gen)
+    scales = (torch.randn(32, 2, generator=gen) * 0.1).to(torch.bfloat16)
+    biases = (torch.randn(32, 2, generator=gen) * 0.05).to(torch.bfloat16)
+    ecodes = torch.randint(0, 16, (10, 128), generator=gen)
+    state = {
+        "proj.weight": _pack(codes, 4), "proj.scales": scales,
+        "proj.biases": biases,
+        "emb.weight": _pack(ecodes, 4),
+        "emb.scales": scales[:10], "emb.biases": biases[:10],
+    }
+    replaced = cio._install_quantized(model, state, None)
+    assert replaced == {"proj", "emb"}
+    s = policy.finalize(cap_bytes=1 << 20)
+    assert [a["path"] for a in s["admitted"]] == ["proj"]   # embeddings are not cached
+    assert s["admitted_bytes"] == 32 * 128 * 2
+
+
+# ---- CUDA: the fill transient the admission arithmetic promises --------------------
+# Skips without a device; FAILS with --require-cuda.
+
+
+@pytest.fixture(scope="module")
+def torch_cuda(request):
+    from tests.test_torch_cuda_smoke import _torch_with_cuda
+    return _torch_with_cuda(request)
+
+
+def test_cached_fill_peak_stays_within_the_priced_transient(torch_cuda, policy):
+    """The regression this pins: dequantizing the whole weight in one shot
+    peaked at ~8x the resident cache (3.7 GB for edge0-8b's lm_head), which
+    does not fit an 8 GB Orin's headroom even though the resident bytes do.
+    The chunked fill must stay inside resident + fill_transient_bytes."""
+    mod, *_ = _linear(30, out_f=3 * cnn.QuantizedLinear.ROWS_PER_CHUNK + 7,
+                      in_f=512)
+    mod = mod.cuda()
+    policy.register("wide", mod)
+    policy.finalize(cap_bytes=1 << 34)
+    assert mod.cache_weight
+    resident = cnn.dequantized_bytes(mod)
+    priced = resident + cnn.fill_transient_bytes(mod)
+    x = torch.randn(2, 512).to(torch.bfloat16).cuda()
+    torch.cuda.synchronize()
+    torch.cuda.reset_peak_memory_stats()
+    base = torch.cuda.memory_allocated()
+    with torch.no_grad():
+        out = mod(x)
+    torch.cuda.synchronize()
+    peak = torch.cuda.max_memory_allocated() - base
+    assert peak <= priced + out.numel() * out.element_size(), (peak, priced)
+    assert peak >= resident            # the cache really was built
+
+
+def test_chunked_fill_is_bit_identical_to_a_whole_weight_dequantization(
+        torch_cuda, policy):
+    """Chunking bounds the transient without changing a single element:
+    same expression per chunk as the on-the-fly path."""
+    from edge0.backends.cuda.quant import _dequantize
+    mod, *_ = _linear(31, out_f=2 * cnn.QuantizedLinear.ROWS_PER_CHUNK + 5,
+                      in_f=256)
+    mod = mod.cuda()
+    policy.register("wide", mod)
+    policy.finalize(cap_bytes=1 << 34)
+    x = torch.randn(2, 256).to(torch.bfloat16).cuda()
+    with torch.no_grad():
+        mod(x)
+    one_shot = _dequantize(mod.weight, mod.scales, mod.biases,
+                           mod.group_size, mod.bits).to(torch.bfloat16)
+    assert mod._dequantized is not None
+    assert torch.equal(mod._dequantized[1], one_shot)
+
+
+def test_full_cache_env_uses_the_same_chunked_fill(torch_cuda, monkeypatch,
+                                                   policy):
+    """EDGE0_TORCH_WEIGHT_CACHE=1 shares the branch, so it inherits the
+    bounded transient (it was the original 3.7 GB offender)."""
+    monkeypatch.setattr(cnn, "CACHE_DEQUANTIZED", True)
+    mod, *_ = _linear(32, out_f=3 * cnn.QuantizedLinear.ROWS_PER_CHUNK,
+                      in_f=512)
+    mod = mod.cuda()
+    assert mod.cache_weight is False          # the ENV path, not the policy
+    priced = cnn.dequantized_bytes(mod) + cnn.fill_transient_bytes(mod)
+    x = torch.randn(2, 512).to(torch.bfloat16).cuda()
+    torch.cuda.synchronize()
+    torch.cuda.reset_peak_memory_stats()
+    base = torch.cuda.memory_allocated()
+    with torch.no_grad():
+        out = mod(x)
+    torch.cuda.synchronize()
+    peak = torch.cuda.max_memory_allocated() - base
+    assert peak <= priced + out.numel() * out.element_size(), (peak, priced)