# Frontier simulator residual-gap campaign

目标：在已经完成的 1h+ production chat-trace fidelity matrix 上，按信息增益和工程可修性依次关闭三个残余误差源。三个实验严格串行；前一项的产物是后一项的 baseline，不允许同时改多个 profile/component。

## 冻结基线

- Frontier：`deadc4a321f0baaa534c6ebd17f974123733cdc2`
- Profile：`runs/frontier-prefill-kvgrowth-fix-v0/profiles/profile-v5-kvgrowth`
- Workload：与 `docs/assets/frontier-fidelity/full-matrix.csv` 相同的 7 个 TP×load cells
- Real：复用现有每 cell 两次 60-min trial；不重新采集，不做逐 cell E2E calibration
- 指标：TTFT/TPOT/E2E 的 mean/p50/p90/p99；real trial 分别与同一 sim request ID 配对后汇总，不再把两次 real trial pool 成一个分布
- 有效域：TP1 两个 cell 的 simulated waiting p99 已超过原 1 s subcritical gate，必须标成 `gate-fail diagnostic`，不能继续称为 subcritical evidence

## 串行任务列表

### EXP-1：structured attention-prefill predictor

- [x] 锁定 Frontier/profile/trace provenance
- [x] 审计训练与运行时 feature contract
- [x] 冻结 experiment card、事前判据和 mock figure
- [x] 实现最小 predictor patch：
  - standard prefill 只训练 `batch_size=1`；多请求继续走既有 mixed predictor
  - `base(q)` 使用单请求 `KV=0` profile 的单调分段插值
  - KV growth 使用非负 `KV + q×KV` 项
- [x] 单元测试：exact anchors、q/KV 单调、非负、pickle round-trip
- [x] 离线 ablation：RF-all / RF-single / structured-single；held-out context MAPE
- [x] 7-cell CPU replay
- [x] trial-aware paired verdict 与旧 v5 baseline 对照

Decision：**profile gate PASS，trace/merge gate FAIL**。TP1/TP2 TTFT mean/p99
绝对误差改善约 7--10 pp；TP4 三个 cell 的 TTFT mean 绝对误差稳定恶化
5.3--5.8 pp。该 patch 保留为机制 ablation，不作为全局默认 predictor。
EXP-2 先执行 entry audit；仅当 structured 分支上的 TP2 chunk residual 仍 ≥10%
才进入 GPU 三臂测量。

Go/no-go：

- profile gate：held-out context MAPE ≤5%，且所有 TP 的 q/KV 单调检查通过
- trace gate：TP1 TTFT mean/p99 的绝对偏差各改善 ≥5 pp；TP2/TP4 任一 TTFT/E2E quantile 不得恶化 >5 pp
- 若 profile gate 不过，不进入 trace replay；若 trace gate 不过，保留 profile diagnosis，回退 patch，不进入 EXP-2

### EXP-2：TP2 base-prefill serving-path profile

- [x] 在 EXP-1 冻结输出上重新确认 chunk #1 residual：TP2 是否仍为孤立点
- [x] probe `dash1`--`dash4`；只选择 8 张 H20 全部 idle/healthy 的主机
- [x] 三臂中的 A/C 同形状 profile：
  - A：当前 standalone microbenchmark
  - C：真实 serving path extract
- [x] q8k smoke 与两个 TP rank 的 component contract
- [x] 注入 q8k ratio，重放 TP2 两个 load cell；其余 profile 冻结
- [x] paired verdict

Decision：**mechanism gate PASS，global constant injection FAIL**。serving q8k
execute=`408.19 ms`（real=`410 ms`），MoE=`214.52 ms` vs sim=`171.12 ms`，
解释 `80.75%` residual。全 prefill-domain constant `1.25366×` 会过校正：
subcritical TTFT mean `−4.54%→+5.23%` 且 E2E mean
`+12.70%→+15.55%`。保留的工程方向是 TP2 token/routing-conditioned MoE
curve，不合入 constant scale。B arm 合并为该 follow-up curve 的真实 routing
采样，不再为已被 C 直接确认的机制单独占一次 GPU run。

Go/no-go：

- 若 B/C 相对 A 都没有稳定的 ≥10% shift，拒绝“tactic/warmup 或 serving composition”假设，不做 profile 注入
- 若 C 能解释 real chunk residual，TP2 TTFT mean 目标收敛至 ±10%，且 E2E/TPOT 不恶化 >5 pp

### EXP-3：decode whole-layer residual × batch curve

- [x] 在 EXP-2 冻结输出上确认 TP4 low-load TPOT/E2E 正偏仍存在
- [x] probe dash1--dash4；补 TP2/TP4 × batch 2/4/6/8 whole-layer grid，
  b1 复用既有 serving anchor
- [x] 将 whole-layer time 与 component sum 对齐，定位 TP4/b6 collective tail
- [x] 稳定性 gate：TP4/b2 fresh-process CV=`0.067%`；TP4/b6 依规则加 r3
- [x] 重放历史 BC-8 knee，检查 `TP2<TP4<TP1` 排序
- [x] 审计 7-cell runtime support；因 batch 最大到 b15 且 TP4/b6
  deterministic mean 不稳定，拒绝 b8 constant extrapolation，不做 global injection
- [x] 分层判决：BC-8 排序不升级 event telemetry；绝对残差/MNS/high-batch
  tail 保留 event/distribution-aware follow-up

Decision：**BC-8 engineering fix PASS，global curve merge NO-GO**。稳定 TP4/b2
median=`4.623 ms`；exact b2 injection 使 TP4 P4 sim TPOT
`5.864→5.367 ms`，完整 MNS16 排序恢复为真实的 `TP2<TP4<TP1`。
绝对 residual 仍为 `+0.918--+1.001 ms`，MNS16/32 仍 tie。TP4/b6 的
5.433/10.157/8.634 ms 跨进程均值由 collective tail 主导；1h trace 又访问
b9--b15，故当前只接受 scoped TP4/b2 correction，不接受全局 b2--b8 lookup。

Go/no-go：

- low-load TPOT/E2E mean 绝对偏差各改善 ≥5 pp
- BC-8 topology order 恢复，且原 7-cell TTFT 任一 quantile 不恶化 >5 pp

## 统一输出格式

每个实验最终报告都分为：

1. `Fact`：原始测量与 paired metric
2. `Interpretation`：支持/反驳哪条机制假设
3. `Decision`：merge、回退、继续下一实验或停止