WIP: PD-DFlash Phase A — measure-first runner (Task 2/3)

[drunkcoding]

WIP: PD-DFlash Phase A — measure-first runner (Task 2/3)

Draft. Do not merge. Prepares the Phase-A "measure-first" benchmark harness
so a human can run the go/no-go §8 matrix on the RTX PRO 6000 box. No hardware
was run by this change; all GPU work is gated/opt-in.

Plan: docs/superpowers/plans/2026-08-14-pd-dflash-serving-scheduler.md
(Task 2 + the CPU-safe parts of Task 3). Branched off origin/dev;
reuses the Task-1 contract commit (benchmarks/dflash/report.py).

What's here

• Byte-accurate route-ahead accounting (feat(dflash)…): RouteAheadStats
  now records exact stored FP4/FP8 expert payload bytes
  (predicted/kept/wasted_bytes, wasted_prefetch_bytes in as_dict), sourced
  from a new registration-time ExpertPrefetcher.expert_nbytes_map populated in
  model_offload from live params (before offload placeholders erase shape) and
  forwarded through the executor route-ahead seam. Strictly additive,
  None-safe, off by default; MagicMock/resident paths stay None via an
  isinstance(dict) guard, so no offload-path default behavior changes.
• Opt-in B0–B3 runner benchmarks/dflash/pd_dflash_serving.py (+ private
  _serving_measure.py): import-safe CLI (torch/moe imported only on the GPU
  path), emits one JSON row per (model,baseline,B,concurrency,repeat) matching
  report.REQUIRED_METRICS, validates RTX PRO 6000 (12,0), refuses resident
  B0/B1/B2, wraps the five NVTX ranges the BM4 parser keys on, and blocks B2 as
  BLOCKED_UNTIL_2D_SCHEDULER until the 2-D scheduler (Task 6) lands.
• CPU-safe Task-3 reporting: BM1 summarise_row (pass iff
  t_router < t_verify) plus a pure aggregation CLI
  (python -m benchmarks.dflash.report) that groups raw rows into §8 matrices,
  permits blocked B2 via --allow-blocked, and writes
  result_matrix.json/CSV/Markdown for validate_result_matrix.
• One-command launcher benchmarks/dflash/run_phase_a.sh: runs the full
  matrix for both required targets with the documented env
  (HF_HOME=/mnt/raid0nvme0/public/huggingface, MOE_ENABLE_SM120=1,
  device-memory-ratio<0.9 to force offload) and aggregates the result matrix.
  All inputs are documented env vars in the script header.

Tests / verification (CPU)

• test_route_ahead_metrics.py (18, incl. 5 new byte tests) — TDD RED→GREEN.
• test_pd_dflash_report.py (16, incl. BM1 + aggregation).
• test_pd_dflash_serving_contract.py (11, pure runner logic).
• test_pd_dflash_serving_gpu.py — 1 skipped ungated (side-effect-free
  collection), asserts the §8 contract when MOE_DFLASH_SERVING_GPU=1.
• Full focused set: 124 passed, 1 skipped. ruff check + ruff format
  clean; lsp diagnostics clean on all changed files.

Explicitly NOT in scope

No hardware benchmarks run; no offload-path default behavior changed; no
Phase B/C scheduler or C++ work; no GLM / feat/dflash-spec-decode changes.
B2 rows and the full go/no-go coverage/waste gate are completed on-device in
Task 3 / Task 6.

Runner notes for the operator (Task 3)

• Pass --measured-h2d-gbps from a real bandwidth probe (never a theoretical
  PCIe number) for the hide inequality.
• _serving_measure uses MoE.generate(..., speculative_draft=…); note the
  repo's MoE.generate deprecation in favor of MoE.serve() — confirm the
  preferred serving entry on-box.
• Metrics without a native accessor (hit-rate/occupancy) fall back to 0.0 and
  are flagged per-row in a warnings field; wire native accessors as needed.