[BeatSeat]

Governing Issue and delivery slice

Refs #454

• Accepted scope / delegation: rfc: 可解释的改进——用 profile 证据和配对统计判定 PASS #454 仍是 Proposed，scope 尚未被接受。为了让 owner 一次看到完整设计，这个 PR 把实现整体提交；如果 owner 希望拆分，三层逻辑分别在独立提交中，可以直接按提交拆开。
• What this PR delivers: 普通项目优化（campaign start/round/final）新增三项能力，默认都不改变现有判定：
  1. 配对统计（只报告）：按 steps() 已有的 AB/BA 交替，把同一次重复里的基线和候选样本配对，报告逐对加速比、bootstrap 区间，以及区间与门槛的关系。
  2. 用 profile 解释改进：测量脚本可以额外输出 breakdown（分区域耗时）和 counters（工作量计数）；每轮可以用 --mechanism-file 声明机制和预期方向；Harness 机械核对并给出 explanation.status。
  3. 两个冻结开关：--require-explanation 只采纳 explained 的候选；--decision paired 用配对区间判定，跨门槛判 FAIL（within_noise）但不阻塞搜索。
• What it does not deliver: 默认判定变更；基准题包支持（benchmarks session 拒绝 --mechanism-file）；Dashboard 展示；与具体 profiler 绑定的采集脚本；GPU/NPU 实测。

Knowledge authorship declaration

本 PR 不触及 knowledge-model policy 的受保护路径，预期为 Not applicable。

{
  "schema_version": 1,
  "head_sha": "1b2b4593cb72ef7b956f82f000313a9910cffbd7",
  "human_only": false,
  "material_ai_authors": [
    {
      "tool": "Claude Code",
      "model_id": "claude-opus-5-5",
      "effort": "unknown",
      "role": "author"
    }
  ]
}

Changed artifacts and evidence

文件	改动	作用
src/inferrsi/harness/measurement.py	新增 303 行	配对统计、profile_evidence、validate_mechanism、explain；无法计算的值一律返回 unavailable，记录保持严格 JSON
src/inferrsi/harness/project.py	+60/−5	assess() 接入两个开关和机制核对；新增设置项的校验
src/inferrsi/harness/optimization.py	+25/−2	在执行前把声明和摘要写入 pending；settle 时核对摘要，并把内存中的声明传给判定器；final 使用被选中轮次绑定的声明
src/inferrsi/harness/optimization_session.py	+15/−6	冻结两个开关；读取并校验 --mechanism-file；_runtime_identity 纳入 measurement.py
src/inferrsi/arguments.py	+8	--decision、--require-explanation、--mechanism-file
docs/optimization-workflow-unification.md	+32	中文说明：字段、取值、开关、局限
tests/test_harness_measurement.py	新增 39 个用例	统计、方向判定、零基线、参照区域不互证、机制校验与分类
tests/test_project_explanation.py	新增 12 个用例	端到端：确认的机制在 final 复核；四类不可采纳情形都让搜索继续；开关关闭时只报告；within_noise；篡改 state.json 或副本；中断后伪造声明的恢复
tests/test_project_optimization.py、tests/test_optimization_session.py	+4、+1 个用例	配对统计不改判、不可达门槛、旧记录可读；题包会话拒绝机制声明
tools/measurement_simulation.py	新增 120 行	可复算的合成消融

判定逻辑

explanation.status	含义	--require-explanation 下
explained	每条预期都被配对区间确认，且至少一条预期是变化	可采纳
unsupported	预期的变化没有出现	FAIL，继续搜索
contradicted	方向相反，或声明不变的项明显变化	FAIL，继续搜索
unverifiable	缺少数据、比值无定义，或少于 5 对	INCONCLUSIVE，继续搜索
not_declared	本轮没有声明机制	INCONCLUSIVE，继续搜索

声明为 unchanged 的区域是本轮的假设：其他区域会另外给出"除以同一步骤参照区域"后的比较，share_based_speedup 用参照占比推算整体加速。只有让一个步骤内所有区域按同一比例缩放的变化，才会被这样抵消。参照区域本身只做原始比较，不会互相归一化。

合成消融（python tools/measurement_simulation.py，CPU 仿真，非设备实测）

每行 200 次 campaign，门槛 1%，数据 seed 20261115，bootstrap 10000 次、seed 0，Monte Carlo 标准误 ≤ 0.035。

• A/A（两侧代码相同）时，现行规则判 PASS 的比例为 0.200–0.380；只做配对、不算区间时为 0.185–0.390；配对区间为 ≤0.020（≥5 对）。压低误报的是区间，配对不起这个作用。
• 真实加速 1.05×、lognormal 噪声、20 次重复时，配对区间的检出率是 0.930，不配对的区间是 0.575。配对带来的是检出力。
• 3 对样本时，区间实际覆盖率只有 0.685–0.775，所以少于 5 对时不报告区间。

Checks and dependencies

• Checks actually run (result and tested scope):

  • ruff check src tests tools：通过。
  • 定向测试 tests/test_harness_measurement.py、tests/test_project_explanation.py、tests/test_project_optimization.py、tests/test_optimization_session.py、tests/test_cli_catalog.py：全部通过。
  • 7 个 Dashboard 测试文件：在旧记录（没有新字段）上全部通过。
  • 本地全量 pytest：本分支与 origin/main a92c77cc 的失败集合相同（各 295 个），本分支没有引入新失败。这些失败来自本机 Git 2.43 不支持 --no-lazy-fetch（仓库要求 Git ≥ 2.45），不能视为通过，以 hosted CI 为准。

• 独立评审： Codex CLI（gpt-6.1-sol，high/xhigh）在本地做了六轮只读评审，每一轮都用对抗输入去复现问题。发现并已修复的问题：

  • 门槛 100% 或比值溢出时会写出 Infinity；
  • 3 对样本时区间欠覆盖；
  • 零基线计数在 1 对时就给出了确定方向；
  • 候选的 breakdown 全为零时抛出异常；
  • 多个参照区域互相归一化，结果自己证明自己不变；
  • 候选在执行期间改写 mechanism.json 或 state.json 里的声明，从而绕过 --require-explanation；
  • 中断后由 recover 结算时，连同摘要一起伪造的声明会被接受。现在恢复的轮次按未声明处理，并记录 mechanism_unverified_after_recovery。

  plan.json 已有 plan_digest 保护。

• Not run: hosted CI；GPU/NPU 实测；真实 profiler 采集。

• Dependencies / integration assumptions:

  • measurement.py 只用标准库。
  • 配对依赖 steps() 两侧等长且交替执行。
  • 候选以调用者权限运行，哈希核对是漂移检测，不是沙箱。
  • 修改 harness/*.py 会改变 runtime identity，旧 runtime 启动的会话需要用原来冻结的 runtime 恢复（既有规则）。

Remaining work and Issue closure

• Remaining Issue requirements / follow-up:

  • owner 对 rfc: 可解释的改进——用 profile 证据和配对统计判定 PASS #454 的三个决策点给出结论；
  • 是否在真实设备上做一次"A/A + 已知改进"的对照；
  • Dashboard 是否展示 explanation；
  • 题包是否支持机制声明。

  另有互补的知识 PR（task: add GPU measurement-validity and profiler-attribution guidance to inference-benchmark-design #455），两者互不依赖。

• Goal-acceptance owner or accepted closure delegation: TBD

• Goal ready for acceptance? Not claimed

[amy-why-3459]

我对照当前 main cd8fcb452bd2c7969a7a6e2544aa1cb5f8ad5332 和本 PR 的 head 1b2b4593cb72ef7b956f82f000313a9910cffbd7 做了完整 review（分支点是 a92c77ccaed68426c83154cff7619745f34d0058，其上 5 个提交：9e01b92bf08e505c259b948633d976019936dcac … 1b2b4593cb72ef7b956f82f000313a9910cffbd7）。#454 仍是 Proposed，这条评论只作设计/实现对照，不是 Approve。

先说已经对上我在 #454 里提的几条：explained / unsupported / contradicted / unverifiable 的机械定义在 explain() 和文档里写清楚了（全部确认才算 explained；任一条方向被打脸即为 contradicted；少于 5 对或零基线计数为 unverifiable）；默认关闭时，test_assessment_reports_paired_statistics_without_changing_the_verdict 和 test_explanation_is_report_only_without_the_switch 覆盖了原判定不变；机制在执行前绑定，并覆盖了改写 state.json / mechanism.json，以及 recover 后不信任声明；tools/measurement_simulation.py 已附上，设定（data seed 20261115、门槛 1%、200 次 campaign、bootstrap 10000、seed 0）可以复核。steps() 已按重复交替 AB/BA，completed 的 assess() 两侧样本等长；某一侧测量失败会按既有 incomplete_execution 整轮失败，--decision paired 在统计 unavailable 时是 INCONCLUSIVE，不会退回未配对中位数。

还需要处理的点：

1. Governing issue 尚未接受。 rfc: 可解释的改进——用 profile 证据和配对统计判定 PASS #454 仍是 Proposed，goal-acceptance owner 为 TBD，三个 owner 决策还没有结论。在 issue 被接受之前，这个草稿适合用来对照设计，但我不会 Approve。另外，rfc: 可解释的改进——用 profile 证据和配对统计判定 PASS #454 正文里还没有补上本 PR 的链接，请补上 https://github.com/InferMatrixLab/InferRSI/pull/457。

2. 请 rebase 到当前 main。 分支点是 a92c77ccaed68426c83154cff7619745f34d0058，之后 main 已合入 Package shared technical contracts and retire root modules #453（cd8fcb452bd2c7969a7a6e2544aa1cb5f8ad5332）。Package shared technical contracts and retire root modules #453 改了 src/inferrsi/arguments.py 的 RunSpec 导入路径（本 PR 也改了这个文件，hunk 看起来不重叠，但仍需要先 rebase）。正文里本地全量 pytest 的对比基线也是 a92c77cc；rebase 后请按新 head 再跑一遍定向测试，并视情况更新声明里的 head_sha。

3. 两个开关同时打开时的优先级，以及点估计与区间不一致时的判定，请写进文档并补测试。 这是我在 rfc: 可解释的改进——用 profile 证据和配对统计判定 PASS #454 评论里第 3 点仍未钉死的部分。assess()（src/inferrsi/harness/project.py 第 188–214 行）先按 --decision 得到 verdict，再仅在 verdict == "PASS" 时应用 --require-explanation。因此两者同时打开时，若配对结果已经是 FAIL / within_noise，即使 explanation 是 unverifiable，最终仍是 FAIL，不会变成 INCONCLUSIVE。请在 rfc: 可解释的改进——用 profile 证据和配对统计判定 PASS #454 和 docs/optimization-workflow-unification.md 里写明这条优先级，并加一个同时打开两个开关的回归测试。另外，--decision paired 只看区间（above_gate 即为 PASS，第 192–193 行），所以“点估计未过门槛、但配对区间整体越过门槛”时会判 PASS；这一点目前只是从代码读出来的，请在文档里写一句，并最好补一个 agrees_with_point_gate is False 且区间为 above_gate 的用例。

我没有重新跑 tools/measurement_simulation.py 的 200×10000 仿真，也没有跑 hosted CI。硬件 A/A + 已知改进对照仍是 #454 留给 owner 的决策，不作为这条评论的合入前提。默认关闭、机制绑定和合成测试设计看起来是对口的。

我不会在这个 head 上 Approve，直到 #454 被接受，并且上面的 rebase / 文档与测试缺口处理完毕。