zl_bench/campaigns/musa_rlc_product/README.md

S5000 MUSA RLC 产品验证 campaign

在 Moore Threads S5000 上，经由 FlagGems public dispatch，测量 FlagTree RemoveLayoutConversions（RLC）增强对 32 个冻结 workload 的影响。

本目录只提供 campaign 层：契约、冻结、执行、判定、重记账。单算子插件、shape、 inventory 仍然复用仓库根目录的既有能力。

组成

文件	作用
manifest/musa-rlc-32-product-v1.json	冻结契约：源码提交、设备、cell、计时口径、32 个 workload
prepare_musa_rlc_product.py	校验 manifest 与 ops/inventory_main.csv，冻结不可变 task matrix
run_musa_rlc_product.py	串行执行 task matrix，产出逐 cell、逐 task、campaign 三级收据
run_pytest_musa_rlc_product.sh	单个算子单个 cell 的 worker，挂载根目录插件
reaccount_musa_rlc_topology.py	对已封存 run 按新口径重记账，不占用设备
tests/	上述四者的单元测试

根目录的 _musa_benchmark_compat_plugin.py 属于插件族，不在本目录。

三个 cell

cell	FLAGTREE_MUSA_RLC_ENHANCE	phase mask	含义
off	0	—	增强关闭的基线
mask0	1	0	增强开启但所有 phase 关闭；它的 topology 必须等于 off，否则控制面本身有问题
candidate	1	13	1a、2、3 启用，1b 未启用

off 记录 autotune config，mask0 与 candidate 回放同一套 config。回放回退即判定失败， 这样 A/B 之间的差异才收敛到编译器改动这一个变量。

跑法

python campaigns/musa_rlc_product/prepare_musa_rlc_product.py \
  campaigns/musa_rlc_product/manifest/musa-rlc-32-product-v1.json \
  --inventory-dir ops --selection canary --dry-run

--dry-run 只做校验与预算估算。去掉它并给出 --output-root 才会冻结 task matrix。 --selection all 需要 --canary-receipt 指向一份通过的 canary 收据。

执行：

python campaigns/musa_rlc_product/run_musa_rlc_product.py \
  --manifest <frozen>/manifest.json \
  --task-matrix <frozen>/task-matrix.json \
  --build-root <flagtree build root> \
  --flaggems <flaggems> --zl-bench <this repo> \
  --worker campaigns/musa_rlc_product/run_pytest_musa_rlc_product.sh \
  --output-root <run root>

runner 在开跑前校验：manifest 与 matrix 的哈希绑定、FlagTree/FlagGems/zl_bench 三处源码身份、 Triton 与 FlagGems 确实从冻结路径导入、设备可见数为 1、所有 benchmark 与 correctness 目标 在真实源码树里存在、设备当前没有其它进程。任何一条不成立就整批拒绝。

单元测试直接跑文件：

python campaigns/musa_rlc_product/tests/test_musa_rlc_product.py
python campaigns/musa_rlc_product/tests/test_reaccount_musa_rlc_topology.py

判定

类	含义
G	正确，convert topology 下降，且双执行顺序下均稳定提速 ≥5%
C	正确，topology 下降，但收益不足 5%
B	正确，但 candidate 没有减少被测算子的 convert topology
R	正确，但双顺序稳定退化 ≤ -3%
K	candidate 特有的正确性失败
X	不支持、超时、harness 失败，或同配置回放被破坏

只有 topology 相对 incumbent 下降时才追加反向顺序计时。convert 数下降不等于变快， 这一点在本 campaign 内已有反例。

三条口径边界

convert 计数只算被测算子。 benchmark 调用会先构造一次输入再在计时区内反复执行算子。 把所有执行过的 kernel 都计入，会把输入构造 kernel 里消掉的 convert 算成收益，而计时器 根本观测不到它。因此每个 dump 的 TTGIR 都与 index.tsv 的 launch 数关联，只有 launch 数超过 measured_launch_floor 的变体才计入。未收敛总数与被排除文件保留在收据里； 无法与 index 关联的 cell 判为 X，而不是相信一个界定不了的 topology 声明。

correctness 只跑该 workload 实际测量的变体。 以整个测试文件为粒度，会让无关变体 决定被测算子的结论。workload 可以钉 node id 或 -k 选择器，两者互斥，且任何收窄都必须 写明理由。完整 argv 落在收据里。

目标在开跑前解析。 inventory 可能落后于固定的 FlagGems 提交，例如上游把一个 benchmark 文件拆成多个。这类任务过去只在 worker 前置检查里静默失败，留下空日志。现在 runner 会 对真实源码树解析全部目标，workload 可以声明 inventory 里没有的目标但必须给出理由， worker 的每个前置检查失败时自报名称。

不属于本 campaign 的结论

一次 terminal 的 campaign 只证明：该冻结语料在该设备该提交下的 dispatch 正确性、 layout topology 响应、以及同契约下的 native-event 延迟。它不证明跨厂商正确性、 性能对等、CI 状态，也不构成打开生产默认开关的依据。manifest 的 production_default_policy 固定为 unchanged-off。