Update BMM_Theory: docs/01_软件架构.md (fix review issues #4-#10)

BMM/BMM_Theory/docs/01_软件架构.md

@@ -13,13 +13,16 @@
 │ 分支层 (branches/)  —— 每个分支一个文件, 三个接口          │
 │  ├─ merge_batch.py   MergeBatchBranch                    │
 │  ├─ iter_batch.py    IterBatchBranch                     │
-│  ├─ (asw_basic.py    待迭代)                              │
+│  ├─ to_matmul.py     ToMatmulBranch                      │
-│  └─ (stream_k.py     待迭代)                              │
+│  ├─ special.py       SpecialBranch                       │
+│  ├─ stream_k.py      StreamKBranch                       │
+│  └─ asw_basic.py     AswBasicBranch                      │
 │      统一接口: check_conditions / make_plan / evaluate    │
 ├─────────────────────────────────────────────────────────┤
 │ 模型层                                                   │
-│  ├─ models.py   BmmCase / ImplPlan / HardwareTiming      │
+│  ├─ models.py       BmmCase / ImplPlan / HardwareTiming  │
-│  └─ timing.py   MTE2 / MMAD / Fixpipe / Reduce 时延引擎   │
+│  ├─ timing.py       MTE2 / MMAD / Fixpipe / Reduce 时延引擎│
+│  └─ constraints.py  单一约束源 (生成与校验共用)            │
 ├─────────────────────────────────────────────────────────┤
 │ 硬件层 (hardware/)                                       │
 │  └─ ascend950pr.py  NpuSpec 参数表 (换芯片只换这份)        │
@@ -94,11 +97,19 @@ class Branch:
 - `eval_fixpipe(bytes, to_l2)` —— 搬出（直写 GM 或驻留 L2）
 - `eval_streamk_reduce(...)` —— StreamK 归约（部分和 4B 驻留 L2、AIV 求和）
 
-`assemble_timing(...)` 汇总并判瓶颈。带宽模型：每核独立 DMA 引擎、带宽按核数配平（尾轮文档 §2.4），活跃核数 < C 时聚合带宽按比例下降。
+`assemble_timing(...)` 汇总并判瓶颈。**归约计账约定**（issue#9）：REDUCE 默认串行追加（体现在 `t_drain`），不进稳态 `max()`；仅当显式声明可流水掩盖（`reduce_serial=False`）时才进 `max()`。带宽模型：每核独立 DMA 引擎、带宽按核数配平（尾轮文档 §2.4），活跃核数 < C 时聚合带宽按比例下降。
+
+### 3.5 单一约束源（constraints.py）
+
+约束知识（L0C/L0A/L0B/L1/dValue/min_TileSize/核数）**只有一个事实来源**：`constraints.check_plan_constraints(case, plan)`。生成侧（recommend 的 `_wrap_checked` 自检）与评估侧（evaluate 的 `_check_constraints`）共用同一函数，保证"推荐方案 vs 自带评估器"口径一致，不再出现生成说可行、校验说不可行的矛盾。
+
+生成侧的 tile 收敛辅助（`clamp_base_k` / `clamp_base_mn_l0c`）也在此模块，各分支 `make_plan` 调用同源函数保证生成的 tile 不越界。dValue 口径裁定（issue#6）：仅当 K 被切分成段（k_l1 < K、K 段为搬移连续维）时 128B 下限才生效；K 整驻留（k_l1 ≥ K）时连续维是 M/N，豁免 K 向下限。
 
 ## 4. 扩展指南（后续迭代）
 
-1. **接 ASW_Basic**: 新建 `branches/asw_basic.py`，实现三接口；进入条件 P = B·MN·4B/L0C ≥ C；方案含 BaseM/N → SingleCoreM/N → mCnt/nCnt → swizzle W → L2 分组 → 尾轮策略（A1b 为基准，v1.5 判定流程）；在 `router.py` 兜底分支注册。
+当前六分支已全部实现（转Matmul / 特殊 / MergeBatch / IterBatch / StreamK / ASW_Basic）。后续方向：
-2. **接 StreamK**: 进入条件 P ≤ C/2 + K 阈值 θ_c≈12；时延加 `eval_streamk_reduce`；workspace 按 4B·部分和计。
+
-3. **换芯片**: 复制 `hardware/ascend950pr.py` 改常数，`NpuSpec` 接口不变。
+1. **转Matmul 精切**: 当前折叠后只粗估（`to_matmul.py::evaluate` 按 Matmul 总量），接入 MM 理论体系做精确切分。
-4. **标定 T_cmd**: 当前取 50ns 估计值，实测后改 `t_cmd_ns` 一处即可。
+2. **换芯片**: 复制 `hardware/ascend950pr.py` 改常数，`NpuSpec` 接口不变。
+3. **标定 T_cmd**: 当前取 50ns 估计值，实测后改 `t_cmd_ns` 一处即可。
+4. **新分支**: 在 `branches/` 下加一个文件实现三接口 + 在 `router.py` 注册 + 在 `evaluator._BRANCH_EVAL` 注册；约束一律走 `constraints.py`，不在分支内另造规则。