feat(qwen35): launch only on the step contract

docs/index.md

@@ -46,18 +46,19 @@ Organized by domain (model line / subsystem / playbook / lesson) instead of by l
 | Path | TL;DR |
 | --- | --- |
 | `models/qwen35/roadmap.md` | Qwen3.5 dense roadmap v2 (#654): core correctness/admission/chunked-prefill/sampling/step-tail gates are landed; current 4B HTTP boundary is the retained #469 RTX 5090 sweep, which completed with zero failed requests but trails vLLM at high concurrency. Next: HTTP gap attribution, mixed-load ITL (#470), lifecycle recovery (#471), joint-state prefix reuse (#257), and design-first TP (#446). |
-| `models/qwen35/load-snapshot.md` | Qwen3.5 publishes logical running, current pending, and KV load after drain/cancellation pruning and before admission through the shared single-GPU/TP scheduler backend. |
+| `models/qwen35/load-snapshot.md` | Qwen3.5 publishes logical running, waiting, and KV load after each `step` (same cadence as Qwen3) from the shared single-GPU/TP backend. |
 | `models/qwen35/prefix-cache.md` | Qwen3.5 prefix-cache design: a hit is valid only when full-attention KV and a complete recurrent/conv snapshot exist at the same 256-token boundary; the first version uses a fixed-budget GPU snapshot pool with joint lookup, pinning, and LRU eviction. |
 | `models/qwen35/kv-admission.md` | Issue #254 complete: Qwen3.5 now uses full-lifetime KV admission, deferred pressure handling, impossible-request rejection, explicit error semantics, direct rejection-event coverage, RTX 5090 e2e, and real HTTP pressure/post-pressure validation. |
 | `models/qwen35/optimization.md` | Hybrid 24 linear + 8 full attn optimization ledger. Decode-tuning refresh fuses MLP gate/up and tunes decode cublasLt buckets, improving direct TPOT by 2-3%; vLLM still leads 1024/256 HTTP decode. |
 | `models/qwen35/accuracy.md` | Qwen3.5 HF bf16 logits goldens, size-keyed (0.8b/2b/4b/9b/27b all committed), through `past_key_values`: short replay covers sequential graph, bucket-straddling batched graph, and slot-compaction; long replay covers 4097/8192-token prompts; full GSM8K 8-shot now matches the HF baseline within 0.15 percentage points. |
-| `models/qwen35/model-crate.md` | `pegainfer-qwen35` owns Qwen3.5 model/scheduler/recurrent ops/tests/benches; feature-gated behind `qwen35` (Triton AOT is the only Python build dependency); root loads it through `EngineHandle`. Build/check/clippy, root bench sanity check, historical Qwen3.5 e2e, and scheduler e2e records live here. |
+| `models/qwen35/model-crate.md` | `pegainfer-qwen35` owns Qwen3.5 model/scheduler/recurrent ops/tests/benches; feature-gated behind `qwen35` (Triton AOT is the only Python build dependency); root loads it through `Engine` / `LaunchedEngine::Stepped`. Build/check/clippy, root bench sanity check, historical Qwen3.5 e2e, and scheduler e2e records live here. |
 | `models/qwen35/batched-step-tail.md` | Qwen3.5 issue #353 implementation record: final prefill tail is batched, decode/unified sample from batched logits, host full-vocab copies are logprobs-only, HF + scheduler e2e pass, and final serving A/B supports only the first-token/short-output TTFT claim. |
 | `models/qwen35/tp-design.md` | Qwen3.5 TP design: Phase 1 is eager dense TP on Qwen3's controller/worker runtime; validate TP2 first, fail closed for indivisible degrees and TP+CUDA Graph, shard dense full-attention/MLP, and leave sharded linear/GDR state to follow-up. |
 | `models/qwen35/tp-implementation.md` | Qwen3.5 TP Phase 1 and P2A are complete: TP2 has start-gated eager unified prefill+decode, strict ID-aligned artifacts, fail-closed lifecycle recovery, and pre-load ordinal validation; P2B GDR state sharding is next. |
 | `models/qwen35/mixed-load-itl-470.md` | Issue #470: full cold `--max-batch 8/bg=4` matrix on RTX 4090 (24/24 valid) + starvation negative control. Qwen3.5 is not immune; chunking bounds max/per-step stall but raises p99 at low QPS (~14→~80–92ms) and pulls p99/max back from the prefill wall to the chunk wall at high load; `qps·prefill_s≳1` is a throughput wall (chunking can't fix it, and ON's +15% TTFT can trip it earlier). The old "p99 immunity" was a slot-starvation artifact. |
 | `models/qwen35/adaptive-scheduler-policy.md` | Issue #727 adaptive scheduler policy record: default `off`, opt-in `auto`, hard `--max-prefill-tokens` cap, TP `auto` rejection, and pre-review whole-prefill benchmark tradeoff retained as non-default evidence. |
 | `models/qwen35/unified-prefill-overlap.md` | Issue #715 implementation record: opt-in single-GPU shared-SM overlap keeps one prefill chunk in flight while active decode continues; default serial policy and unsupported-combination guards remain explicit. |
+| `models/qwen35/step-contract-migration.md` | Qwen3.5 launches only as `LaunchedEngine::Stepped`; `Qwen35Scheduler` implements the step contract in `scheduler/`. Legacy `EngineHandle`/`TokenEvent` is gone from this crate. |
 
 ## models / gemma4
 
@@ -170,7 +171,7 @@ Organized by domain (model line / subsystem / playbook / lesson) instead of by l
 
 | Path | TL;DR |
 | --- | --- |
-| `subsystems/frontend/frontend-architecture.md` | `pegainfer-frontend` owns everything north of the model schedulers. Two contract generations coexist: the step contract (qwen3 + pegainfer-sim migrated) and the legacy `EngineHandle`/`TokenEvent` path (other five lines). Next: migrate glm52, then delete the legacy contract. |
+| `subsystems/frontend/frontend-architecture.md` | `pegainfer-frontend` owns everything north of the model schedulers. Two contract generations coexist: the step contract (qwen3 + qwen35 + pegainfer-sim migrated) and the legacy `EngineHandle`/`TokenEvent` path (glm52/kimi/dsv2/gemma4). Next: migrate glm52, then delete the legacy contract. |
 | `subsystems/frontend/simulated-inference-engine.md` | CPU-only simulated model crate on the step contract (`SimScheduler` → `LaunchedEngine::Stepped`) for vLLM/OpenAI frontend and `vllm bench serve` validation without CUDA or weights. |
 | `subsystems/frontend/sim-step-contract.md` | Cut `pegainfer-sim` from the legacy `EngineHandle`/`TokenEvent` path onto the step contract. |
 | `subsystems/frontend/sim-high-concurrency-bench.md` | Same-session A/B vs main: feat TPOT ~30–180× better, TTFT worse and linear in C; E2EL/throughput win at c=64 and c=1024. |

docs/models/qwen35/load-snapshot.md

@@ -1,6 +1,6 @@
 # Qwen3.5 Scheduler LoadSnapshot
 
-> **TL;DR:** Qwen3.5 publishes one logical post-drain/post-prune `LoadSnapshot` stream from its shared single-GPU/TP scheduler: running counts active and prefilling requests, waiting counts all current pending work, and KV usage is request-page capacity minus available pages.
+> **TL;DR:** Qwen3.5 publishes one logical `SchedulerMetrics` snapshot from its shared single-GPU/TP backend after each `step` (same cadence as Qwen3): running counts active, prefilling, and in-flight overlap prefill; waiting counts deferred/queued work; KV usage is request-page capacity minus available pages.
 >
 > **Last touched:** 2026-08
 
@@ -25,28 +25,28 @@
 The data path reuses the existing frontend contract:
 
 ```text
-Qwen3.5 SchedulerBackend
-  -> LoadSnapshot watch
-  -> EngineHandle
-  -> LocalEngineBridge
+Qwen3.5 Qwen35Backend
+  -> Scheduler::metrics after prune (inside step)
+  -> driver publishes once per iteration
+  -> SchedulerHandle::metrics / SteppedEngineBridge
   -> SchedulerStats
   -> /metrics
 ```
 
-Both Qwen3.5 execution modes own one logical request stream, so single-GPU and TP each attach one `EngineHandle::with_load_watch` receiver. The frontend bridge, metric names, labels, and scheduler-stat conversion remain unchanged.
+Both Qwen3.5 execution modes own one logical request stream, so single-GPU and TP each expose one scheduler. The frontend bridge, metric names, labels, and scheduler-stat conversion remain unchanged.
 
-Each scheduler tick first merges deferred work with every submission currently available, then prunes closed pending, active, and prefilling requests before publishing. The fixed boundary is `drain -> prune -> publish load -> admission -> plan`. If the idle scheduler wakes through `blocking_recv()`, it drains, prunes, and publishes again before admission so work closed before admission never consumes a slot or appears in the snapshot.
+The driver publishes *after* `step()` returns, same as Qwen3. `step` prunes aborted work before admission, then admits and executes; `metrics()` reads the queues at the end of that step. In-flight overlap prefill counts as running so an overlap wait inside `step` is never published as idle.
 
 Snapshot accounting is:
 
 | Metric field | Existing Qwen3.5 state |
 | --- | --- |
-| `num_running_reqs` | `active.len() + prefilling.len()` |
-| `num_waiting_reqs` | the merged pending queue: prior deferred work plus newly drained submissions |
+| `num_running_reqs` | `active.len() + prefilling.len() + inflight_prefill` |
+| `num_waiting_reqs` | deferred/queued work not yet admitted |
 | `kv_used_blocks` | request KV capacity minus currently available request pages |
 | `kv_total_blocks` | backend request KV capacity, excluding the CUDA Graph padding page |
 
-Publication reads the scheduler's queues and KV allocator after closed resident state has gone through its normal retirement path. The snapshot therefore describes the state used by the following admission decision: cancelled residents no longer count as running or hold capacity, while live pending requests count as waiting even if they were submitted during the current tick.
+Publication reads the scheduler's queues and KV allocator after aborted resident state has gone through its normal retirement path. Live pending requests count as waiting even if they were submitted during the current driver drain.
 
 The live gate uses `scripts/bench_http_serving.py` to create overlapping HTTP traffic and a 100 ms `curl /metrics` sampler to retain the three labeled gauges.
 

docs/models/qwen35/model-crate.md

@@ -1,8 +1,8 @@
 # Qwen3.5-4B Model Crate
 
 **Created**: 2026-05-05
-**TL;DR**: `pegainfer-qwen35` now owns Qwen3.5 config, weights, prefill/decode/unified forward, recurrent state, scheduler, recurrent op wrappers, scheduler integration tests, and Qwen3.5 op benches. The whole crate is behind the `qwen35` feature (`--features qwen35` on `pegainfer-server`) because its GDR prefill kernels are Triton AOT-generated — this keeps the default Qwen3 build Python-free. Root `pegainfer` loads Qwen3.5 through `pegainfer_qwen35::start_engine(...)` / generic `EngineHandle`; root no longer exposes `pegainfer::model::Qwen35Model` or `pegainfer::scheduler_qwen35`. The original exact-text e2e/regen tests described in this migration record were later retired by the HF logits gate in `docs/models/qwen35/accuracy.md`.
-**Last touched**: 2026-07
+**TL;DR**: `pegainfer-qwen35` now owns Qwen3.5 config, weights, prefill/decode/unified forward, recurrent state, scheduler, recurrent op wrappers, scheduler integration tests, and Qwen3.5 op benches. The whole crate is behind the `qwen35` feature (`--features qwen35` on `pegainfer-server`) because its GDR prefill kernels are Triton AOT-generated — this keeps the default Qwen3 build Python-free. Root `pegainfer` loads Qwen3.5 through `pegainfer_qwen35::start_engine(...)` / `Engine` (`LaunchedEngine::Stepped`); root no longer exposes `pegainfer::model::Qwen35Model` or `pegainfer::scheduler_qwen35`. The original exact-text e2e/regen tests described in this migration record were later retired by the HF logits gate in `docs/models/qwen35/accuracy.md`.
+**Last touched**: 2026-08
 
 ## Feature gate (2026-06)