# 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 之间的差异才收敛到编译器改动这一个变量。

## 跑法

```bash
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 收据。

执行：

```bash
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 目标
在真实源码树里存在、设备当前没有其它进程。任何一条不成立就整批拒绝。

单元测试直接跑文件：

```bash
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`。