M7 前置设计备忘：ms_benchmark() 网格驱动器
Source:vignettes/articles/devlog-2026-10-05-benchmark-design-memo.qmd
日期：2026-10-05 晨（窗口尾批——设计冻结，实现为 M7 本体）。范围：CAPABILITY-MATRIX L3 “ms_benchmark() | mlr3 式基准网格；non-certified 引擎显式 warning | M0 骨架/M7 完备”。M0 已交付 MsBenchmark 容器（R/classes-benchmark.R：results/.engine/.scenario/.metric/.estimate + settings）；本备忘冻结 M7 网格驱动器的 API、场景语义与验收锚——实现开工前须 PI 对两个开放裁决点表态（§5）。
§1 API 冻结草案
ms_benchmark(grid, engines = NULL, seed = 1, ...)-
grid：ms_benchmark_grid()构造的场景网格对象（list-of-scenarios，每 scenario = 生成参数集，§2）。 -
engines：引擎名字符向量（注册表解析，match_ms_engine语义）；NULL = 全部 certified 引擎。non-certified 引擎显式 warning 一次（M0 骨架语义，v0.2 已定：一次性告警 + 继续）。 - 每 (scenario × engine) cell：
ms_extract/ms_fit端到端 → 评分 → MsBenchmark。 - 每引擎 setup/teardown 钩子（engine 契约的
required_pkgs检查前置，缺席 → cell 标skipped不中断网格）。 - 评分矩阵经
ms_compare()三协议 + exposure L1/cosine（ARCH §指标）+ 运行时（ms_extract_fit_time语义）。
§2 场景网格语义（ARCH §8 的机器可读化，分层冻结）
场景 = 命名参数结构，字段全部有冻结默认（CI sanity bound 用小子集；钉硬件 bench 用全网格）：
| 轴 | 取值（冻结默认） | 备注 |
|---|---|---|
| TMB | 10²–10⁶ 对数 5 点 | sanity = {1000, 10000} |
| 签名数 k | 1–20（5 点） | sanity = 3 |
| 相关性 | {0, 0.5, 0.8, 0.95} | 平坦组内 r=0.8 + 稀有共存 = 联合场景字段 |
| purity | {1.0, 0.7, 0.4, 0.2} | 正常 cell 混入 |
| caller | ≥2 SNV + ≥2 indel | 场景生成器的 caller 噪声模型字段 |
| 平台 | WGS/WES/panel | 机会归一经 ms_convert 语义 |
| 参考误设 + 目录外 | 布尔 | 目录外签名 cell = FP 压力 |
| 超突变臂 | 5–10% 样本 100× TMB | APOBEC/POLE cutoff 敏感性 |
| 亚克隆结构 | 布尔 | exposure 分层 |
| 类别计数区间 | SV 10–10³、CN 10–10⁴ | 模态专属 |
三层生成器隔离（ARCH §8，协议发表前冻结随包）：校准/模型选择/评估场景分别绑定 ms_simulate（计数层，已交付）/SynSig 适配器/PCAWG 锚定混合。第一版交付校准场景驱动器（ms_simulate 直驱），后两层为 M7 适配器单元。
§3 评分契约
- 主指标 = Hungarian 一对一 P/R/F1（
ms_compare(protocol="hungarian")主表直读）；Islam 贪心 + 阈值扫 0.80–0.90 附录；Jiang CS（fit-evaluation 场景）。 - exposure L1/cosine：absolute 与 compositional 双口径（与引擎 estimand 对齐——D16 语义注记）。
- 缺席签名误分配 = specificity 面（Jiang）。
- 运行时/内存：
proc_time+ gc峰值（钉硬件口径 CI 只 sanity）。 - results 表 schema = MsBenchmark 现有契约（.engine/.scenario/.metric/.estimate）。
§4 验收锚（M7 实现时）
- 【整数/逐位】：seed 确定性（同 grid+seed → results 逐位同）；scenario 序稳定；non-certified warning 一次性；skipped cell 不产生 estimate 行。
- 【工程】：网格完整性（cells = scenarios × engines 全笛卡尔）；错误隔离（单 cell 失败 → 该 cell error 行 + 网格继续）；MsBenchmark validator 全绿。
- CI sanity bound：TMB{1000,10000}×k3×2 引擎×多臂 < 5 分钟。
§5 开放裁决点（默认路径已细化——PI 回归后”采纳默认”即开工）
裁决点 1：评估引擎集合 → 默认路径 D1：三阶段扩展
- 阶段 1（实现即含）：自有 certified 引擎互评——NMF / ARD / Sparse（注册表 certified 三态现成，non-certified warning 语义已定）。竞品容器不在网格驱动器首版。
- 阶段 2（M7 本体）：sigminer 适配器入格（bench/xval 已有互证先例，容器 = 引擎注册表 + required_pkgs 门）。
- 阶段 3（M7 完备门）：MuSiCal / SigProfilerAssignment 容器（Python 桥 = 独立单元，需 basilisk/reticulate 裁决——届时另立备忘）。
- 可执行默认：
ms_benchmark(engines = NULL)= 全 certified；engines = c("nmf", "ard", "sparse")为 sanity bound 标准集；适配器引擎以注册表 certified=TRUE 进入（D17 语义不变）。 - 回滚成本：零（阶段间纯增量）。
裁决点 2：exposure 对齐语义 → 默认路径 D2：Hungarian 配对 L1（同源主指标）
- de novo 提取与真值无 1:1 对齐——L1/cosine 的 exposure 误差只在 Hungarian 一对一配对成功的 (估计, 真值) 对上计算（与 P/R/F1 主指标同一
ms_compare(protocol = "hungarian")运行导出，零额外计算）；未配对估计签名不入 L1 均值（其 FP 身份已被主指标惩罚——双重计惩罚即重复计数）。 - absolute 口径 = 配对对的暴露差绝对值之和 / 负荷；compositional 口径 = 份额化后同式。两口径都报（.metric 后缀
_abs/_comp）。 -贪心 max-cosine 对齐的 L1 = 鲁棒性附录（阈值扫同款），不进主表。 - 回滚成本：低（评分函数单一出口，语义切换 = 换一个内部函数）。
PI 确认格式（一键）：D1+D2 采纳 / 对任一条给出替代——两路径均已细化为实现即用的规格，无二次设计依赖。
§6 依赖
ms_simulate（✅ 已交付计数层）、ms_compare 三协议（✅）、引擎注册表（✅ M0）、SynSig/PCAWG 适配器（⏳ M7）、钉硬件访问（⏳ 运维）。