WIP: PD-DFlash Task 7 — BM2 + batched prefetch

[drunkcoding]

WIP: PD-DFlash Task 7 — BM2 issuance micro-bench + batched prefetch_tensors

Draft. Do not merge. Implements Phase C's first C++ hop from
docs/superpowers/plans/2026-08-14-pd-dflash-serving-scheduler.md
(Task 7 = BM2 issuance micro-bench, Task 8 = the batched-issuance C++
candidate). Enforces the plan's hard rule — no C++ ships without its paired
benchmark passing — by measuring BM2 on hardware before keeping the C++.

Stacks on #157 (feat/pd-dflash-phaseA-runner). Until #157 merges, the diff
against dev also shows #157's Phase-A commits. Does not implement the later
priority-band (BM3) / overlap (BM4) / e2e (BM5) hops.

BM2 gate decision — JUSTIFIED ✅

Measured on a real offloaded openai/gpt-oss-20b (RTX PRO 6000, SM120,
CUDA_VISIBLE_DEVICES=0, device_memory_ratio=0.2), 768-tensor saturated block
(E_l×L), warmup=20, iterations=200:

mode	p50	p90	p99
python-per-expert	1132.1 µs	1891.6	2238.7
batched-pybind	101.5 µs	105.3	111.0
cpp-internal	null (no native timer)	—	—

Batching collapses issuance 1132 → 101.5 µs (~11.2×, ~1.03 ms/block saved) by
replacing 2·E_l·L pybind crossings with one C++-internal loop. The
justified-window interval [batched_p50, per_expert_p50) = [101.5, 1132) µs
covers any realistic route-ahead window t_draft+t_router, so per-expert
issuance is exposed and the batched call hides it → ship_batched=true.

Provenance / caveats (reported honestly):

• Target substitution: the plan's Qwen/Qwen3-Coder-30B-A3B is not in the HF
  cache; gpt-oss-20b (cached, offload-validated) is used. Qwen3-Coder-30B has
  ~8× more expert tensors, so per-expert issuance (and the batching win) would be
  strictly larger — the substitution is conservative.
• Window: no Phase-A t_draft+t_router JSON exists yet (Task 3 not run on
  hardware); the gate is reported as a window-independent crossover plus a
  1000 µs reference. Both yield candidate_required=true, ship_batched=true.

What's here

• BM2 (benchmarks/dflash/bench_prefetch_issuance.py): import-safe
  bm2_decision / percentiles_us / build_bm2_report at module scope; CLI
  runner synthesises the real saturated tensor-id list and times with
  perf_counter_ns; unavailable modes reported null, never zero.
• Batched C++ (core/prefetch/archer_prefetch_handle.{h,cpp},
  core/python/py_archer_prefetch.cpp): EnqueuePrefetchTensors(tensor_ids, priority=1) enqueues one Task/tensor entirely in C++ (order- and
  default-device-preserving); prefetch_tensors rebound to it, the old no-op
  binding retired, enqueue_prefetch retained.
• Python seam (moe_infinity/memory/expert_prefetcher.py):
  prefetch_experts_list issues one batched call when the engine exposes it,
  else the byte-for-byte per-expert fallback; empty input is a no-op.

Verification

• CPU: test_prefetch_perf_reports.py (20) + test_speculative_prefetch.py
  (batch/fallback/empty) + test_route_ahead_wire.py — 50 passed
  (wire assertions made mechanism-agnostic: a batched call carries the same
  ordered ids the per-expert fallback would).
• Native _store rebuilt on SM120; prefetch_tensors(tensor_ids, priority=1)
  signature verified; opt-in test_prefetch_native_gpu.py -k batched — 3
  passed on a real offloaded handle (single module-scoped load).
• Offload no-regression: tests/test_gpt_oss_offload_topology.py +
  tests/python/unit/test_gpt_oss_mxfp4_dispatch.py — 9 passed.
• ruff check + ruff format clean; lsp diagnostics clean on changed files.

Explicitly NOT in scope

No BM3 priority band, no BM4 overlap, no BM5 e2e; no scheduler work; no GLM /
feat/dflash-spec-decode / #156 / #158 changes. GPU work is opt-in
(MOE_DFLASH_SERVING_GPU=1) and collects/skips cleanly when ungated.