bench: refuse to report a comparison whose two sides have different calibers

Two runs on different calibers produce a report that looks exactly like a
valid one — no step errors, the numbers just mean something else. This repo
has published three figures that were an artifact of such a difference:
router_gemm -8.2% (record vs record), mm "945 variants -> 33" (shared vs
inherited libtuner cache), replication_pad3d +43% vs +124.5% (timer).

batch_summary --ab / --ab-rounds now reads every participating run's
run_identity.json and compares backend/device/timer/bench_level/shape_mode/
tuner_cache/direct_repeat before parsing a single latency. Mismatch, or a
missing identity, prints !!! [caliber] and exits 4. autotune_mode is judged
separately: record pinning a replay is the normal shape, both sides record
is the exact trap above and is refused by name. --allow-caliber-mismatch
releases it, still printing what it found.

Recording on a *shared* tuner cache warns rather than refuses: the pinned
config depends on what else ran on the machine, which leaves relative
conclusions intact and absolute latencies unquotable. Refusing it would
reject the default every A/B here currently uses.

ab_repeat.sh closes the one axis that had no check: after round 1 it
fingerprints both sides' ttgir (relative path + content, so a changed
variant *set* counts too). Byte-identical means the switch changed no
generated code for this op, and the remaining N-1 rounds would measure
noise and report it as "no difference" — so the op is skipped with
SWITCH_NO_IR_DIFF unless SWITCH_ALLOW_NO_IR_DIFF=1.

README leads with a caliber table: each axis, its measured magnitude, what
pins it, and which code checks it. The fourth column is code because
documentation did not hold — the README already said "the B side must use
REPLAY_FROM" when the record-vs-record number was published.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

README.md

@@ -6,6 +6,30 @@
 2. **可解释**：自动按 shape 收集每次运行实际使用的 ttgir（带可读的变体命名），供 IR 级 diff；
 3. **口径统一**：cudagraph 计时消除 launch 开销，小 kernel 的对比不被 CPU 侧噪声淹没；capture 前按 warmup 预算显式预热吸收 autotune/JIT，首轮即稳态、多轮一致。
 
+## 先读这个：口径决定数字的含义
+
+同一个算子、同一台机器、同一份代码，换一条测试口径，测出来的数字可以完全不同。
+下表每一行都是本仓踩过的，量级是实测的，不是估计：
+
+| 口径轴 | 改一下的量级 | 由谁固定 | 由谁检查 |
+|---|---|---|---|
+| autotune config（record vs replay） | router_gemm 差 8pp | `REPLAY_FROM` | `caliber_complaints`：两侧都 record 直接拒绝出报告 |
+| timer（cuda_graph vs direct） | replication_pad3d 从 +43% 变成 +124.5% | `ZL_TIMER` / backend 能力 | 同上，`timer` 字段不一致即拒绝 |
+| libtuner 持久缓存（共享 vs 隔离） | mm 看起来从 945 个变体降到 33 个——实际是 B 侧继承了 A 侧的缓存 | `ZL_ISOLATE_TUNER_CACHE=1` | 共享缓存上 record 会打 `警告 [caliber]` |
+| `--level core` vs `comprehensive` | mm 的 shape 数 5 → 29，能不能覆盖到大 GEMM 全看这个 | `BENCH_LEVEL` | `bench_level` 字段不一致即拒绝 |
+| 重复轮数 | 收益落在零附近时，单次测量给不出方向：topk 42 个 shape 有 17 个在两次等效运行间翻了符号 | `ROUNDS` / `ZL_DIRECT_REPEAT` | `direct_repeat` 字段不一致即拒绝 |
+| 被测开关本身是否真的接上 | 开关名拼错，两侧跑同一份代码，脚本照样报出"无差异" | 开关名正确 | `ab_repeat.sh`：第 1 轮后比两侧 ttgir 指纹，相同即跳过该算子 |
+
+**结论：一次运行的数字没有意义，只有一对同口径运行的差值有意义。** 每次运行把自己的
+口径写进 `runs/<run>/run_identity.json`；`batch_summary.py --ab` / `--ab-rounds` 在出
+报告前核对这些字段，不一致就拒绝，因为**口径不同的两次运行会产出一份和有效报告长得
+一模一样的表**——没有任何一步会报错，只是数字换了含义。确认两次运行确实可比时，用
+`--allow-caliber-mismatch` 显式放行。
+
+文档拦不住人：README 里早就写着"B 侧必须走 REPLAY_FROM"和"只有 record 数据支撑的
+结论按未验证处理"，本仓仍然发布过一个 record 对 record 得到的 router_gemm 数字。
+所以上表第四列是代码，不是提醒。
+
 单算子精测流程之上另有批量筛查层（`run_batch.py`，见「批量多算子测试」），可对双仓库上千个算子做例行体检，产物结构与单算子完全同构。
 
 ## 快速开始
@@ -89,7 +113,9 @@ softmax:
 ```
 runs/softmax_20260716-031752/
 ├── run.log                  # 完整日志（含 SUCCESS 行的 latency/speedup 表；已去 ANSI 色的纯文本）
-├── run_identity.json        # provider/backend/device/timer/vendor（插件合并写入）
+├── run_identity.json        # 本次运行的口径：provider/backend/device/timer/vendor/
+│                          # bench_level/shape_mode/tuner_cache/direct_repeat/autotune_mode
+│                          # （shell 写 stub，插件合并写入；对比工具据此判可比性）
 ├── shapes.yaml              # 本次实际使用的 shape（存档）
 ├── autotune_records/        # Triton autotune 选中的 config（供 replay）
 │   ├── softmax.json
@@ -162,6 +188,27 @@ benchmark 目录，注册 `--level`/`--mode` 的 `conftest.py` 就没被加载
 只校验节点的文件那一半；`::test_<fn>` 交给 pytest，函数不存在时它自己会清楚地报
 `not found: ...`。
 
+### 口径核对：出报告前的拒绝
+
+`batch_summary.py --ab` / `--ab-rounds` 在解析任何 latency 之前，先读参与对比的每个
+run 目录的 `run_identity.json`，逐字段核对 `backend / device / timer / bench_level /
+shape_mode / tuner_cache / direct_repeat`。任何一项不一致，或任何一侧缺 identity，
+就打 `!!! [caliber] ...` 并以 **4** 退出，不出报告。
+
+```
+!!! [caliber] sort: timer 不一致：before=cuda_graph, after=direct
+!!! [caliber] sort: 拒绝出报告。确认口径确实可比后加 --allow-caliber-mismatch
+```
+
+单独判 `autotune_mode`：一侧 record 定 config、另一侧 replay 它是正常形态；**两侧都
+record 直接拒绝**——那正是本仓发布过错误 router_gemm 数字的那次形态。
+
+不拒绝但会警告的一类：在**共享** libtuner 缓存上 record。被 pin 的 config 取决于此前
+在这台机器上跑过什么，相对结论仍成立，绝对延迟与变体数不可跨机器引用。
+
+`--allow-caliber-mismatch` 放行，仍会把问题打出来。用它之前先能说清为什么这两次运行
+可比；跨口径引用别人的数字，比自己重跑一遍贵得多。
+
 ### 多轮重复：ab_repeat.sh 与 --ab-rounds
 
 单对观测无法说明自己稳不稳。S5000 实测 `topk` 消除了 32 个 `convert_layout`，
@@ -177,6 +224,12 @@ SWITCH=FLAGTREE_MUSA_RLC_ENHANCE OPS="topk masked_select" ROUNDS=6   ZL_BACKEND=
 `REPLAY_FROM` 那一份，config 因此跨轮跨侧全部锁死；逐轮交替先后顺序抵消单向漂移。
 有轮次失败的算子不出报告——缺轮的报告会让人误以为是完整的 N 轮。
 
+第 1 轮 A/B 跑完后，脚本比两侧 `ttgir/` 的指纹（相对路径 + 内容）。**逐字节相同就
+跳过这个算子**，并打 `!!! SWITCH_NO_IR_DIFF op=... switch=...`：这个开关没改变该算子的
+生成代码，剩下 N-1 轮测的全是噪声，最后还会报成一个"无差异"的结论。先查开关名拼写
+与它在被测源码里的读取点；确属只影响运行时、不影响 IR 的开关，用
+`SWITCH_ALLOW_NO_IR_DIFF=1` 放行。
+
 报告分开给两种离散度，它们回答不同的问题：
 
 | 指标 | 含义 |