@cannbot-plugin/cannbot-harness 0.0.0-stage → 0.1.5

package/assets/ops-direct-invoke/skills/ops-design-paradigms/references/paradigms/reduction/generic/liveness-fusion.md

@@ -0,0 +1,111 @@
+# Reduction 范式存活节点分析与融合决策
+
+> **层级**：通用知识层（generic/），语言中立。
+>
+> 来源：adapters/ascendc/survival-node.md（原 reduction-survival-node.md）全文、adapters/ascendc/vf-fusion-rules.md（原 reduction-vf-fusion-rules.md）全文。RegBase 指令清单、白皮书核对方式在适配层。
+
+## 1 L/P 双层存活节点模型
+
+**逻辑存活节点（L）**：
+- 计数域：计算图 tensor（每个独立数据实体计 1）
+- 由计算图拓扑 + 最优调度决定，与物理媒介无关，**L 对给定计算图是固定的**，不随硬件/API/实现改变
+- 跨阶段驻留的 tensor 归属其分配阶段，不计入其他阶段（如归约结果驻树缓存，计入归约段）
+
+**物理存活节点（P）**：
+- 计数域：片上 buffer。寄存器不在计数域——片上→寄存器→片上是过路中转，中间值留在寄存器时不占 P
+- **P 不由计算图唯一确定**——同一计算图，不同 API 策略/融合决策 → 不同 P。寻找在给定约束下可达的**最小峰值**
+- buffer 计入其分配阶段的 P，跨阶段复用不占复用阶段的 P；独占分配的 buffer（生命周期内不允许复用）视为全程驻留
+- L 是 P 的下界和收敛目标——P == L 时已到最优，P > L 时还有优化空间
+
+**公平基线（L 和 P 共用）**：
+1. 二元及以上操作，不假设 dst 与 src 复用——每个 op 的 src 和 dst 各占独立节点
+2. 单步内不假设 in-place
+3. 跨步的"用完释放"允许——一个节点的所有消费者执行完后从存活列表移除
+
+**物理基线 = 逻辑基线 + 以下差异**（只能来自 API/硬件能力）：
+
+| 差异来源 | 公平？ | 说明 |
+|---------|--------|------|
+| 跨步 buffer 复用 | ✓ | 生命周期不重叠可共用物理 buffer |
+| 硬件融合指令（dst 就地覆写） | ✓ | 硬件保证，计为 API 能力（`FUSED_ARITH` 谓词） |
+| 软件覆写复用 | ✗ | 逻辑侧/物理基线均不假设 in-place |
+| 寄存器链融合 | ✓ | 中间值全程在寄存器（`REG_CHAIN_FUSION` 谓词） |
+
+### P ≥ L 与例外
+
+P ≥ L 一般成立。`REG_CHAIN_FUSION`=true 的语言可打破：中间值全程在寄存器，不落片上。L 仍包含（按 tensor 计数），P 不包含（寄存器不计入 P）。此时 **P < L 合法**。设计产出必须说明哪些中间值被融合消掉。
+
+### 精度转换（Cast）对 P 的影响
+
+- **转换串入融合链**（`CONVERT_IN_CHAIN`=true 的语言）：转换在寄存器内完成，src 和 dst 不同时占两个片上 buffer，不额外增加 P
+- **转换不串链**（独立转换操作）：src 和 dst 是两块独立片上 buffer，纳入物理 trace 取峰值
+
+## 2 归约范式的三段式分析结构
+
+计算图按三段式划分（见 [scene.md](scene.md) §4），存活节点分析按段独立进行：
+
+- **归约前段 / 归约后段各自独立分析**：各自追踪存活峰值，两段独立分配 buffer、不复用（前段 buffer 含 R 维，后段不含——归约后 R 维消失，空间大小不同）
+- **归约前段结果独占分配**：不与本段内任何节点复用（含写入前）——Phase A 主尾配对时要保持不动等待尾块，提前写入会被覆写
+- **其余节点**：生命周期不重叠时可复用同一物理 buffer；所有片上 buffer 统一按本算子参与计算的最大 dtype 宽度分配容量（`COMPUTE_PRECISION` 与输入 dtype 取宽者），跨 dtype 复用不受尺寸约束，buffer 份数统一覆盖全部 dtype 实例
+- **归约段固定 3 buffer**：归约 src + 归约指令 scratch（由尾配对块兼作，见下）+ 归约 dst（树缓存兼作，不额外分配）——buffer 份数与 src 复用语义（isReuseSource）无关
+- **树缓存的额外影响**（二分缓存树引入，见 [tree-reduction.md](tree-reduction.md)）：主尾配对块是归约前段的额外 +1 份（P_pre_ext，固定 1）；树根（归约结果）驻树缓存最高层，不占归约后段 P
+
+## 3 融合决策方法论
+
+### 3.1 穷举所有相邻操作对
+
+列出计算图中**所有连续 Vector 操作对，逐对判据。禁止只检查"看起来像"的那一对**。方法：从计算图第一条 Vector 操作开始，相邻两两配对，每一对都走三条硬判据，全部检查完才进决策。
+
+**三条硬判据**：
+1. **链长 ≤ `FUSION_CHAIN_MAX_LEN`**——超过上限必须拆为多次调用
+2. **精度转换可参与**（`CONVERT_IN_CHAIN`）——可串入寄存器链路，不作为断点
+3. **指令必须存在**——对应操作在该语言的可用指令集（`FUSED_ARITH` / 指令白名单）中存在
+
+**多消费者不打断链**。即使某个中间结果被链外步骤引用，链仍可继续——链内把该值写回片上即可，寄存器链路不受影响。代价是多写一次片上会多占一个 P 槽，需纳入物理 trace 做峰值验证。
+
+### 3.2 融合改变存活节点大小
+
+融合前每个中间结果各占 1 个片上 buffer；融合后中间结果在寄存器内不进片上——存活节点 = 所有输入操作数 + 最终输出 + 其他还活着的 buffer。
+
+```
+A+B+C+D = E
+全融 A+B+C+D： 5 个节点（A, B, C, D, E 同时活着）
+融 A+B+C：     4 个节点（A, B, C, TMP1 活着）→ 再 TMP1+D = E
+只融 A+B：     3 个节点（A, B, TMP1）→ 再 TMP1+C = TMP2 → TMP2+D = E
+```
+
+### 3.3 P 压力取舍：融合 vs 主动拆分
+
+多消费者融合虽然合法，但会增加 P 压力：融合链需同时持有所有输入 buffer + 所有输出 buffer（包括为外部消费者多写的）。若合并后峰值超过目标 P，需**主动拆分**链来降压。
+
+**判据流程**：
+1. 先推满最长链（≤ `FUSION_CHAIN_MAX_LEN`）
+2. 做物理 trace，检查峰值是否 ≤ 目标 P
+3. 若超 P → 在分叉输出最多的位置拆分链，释放部分 buffer 后再续链
+4. 重复直到峰值 ≤ P
+
+**存活节点扩大限制**：融合使更多输入 buffer 同时活着——融合后的物理存活节点数不得超过融合前的 P + 3。超过 → 只部分融合，或调整调度先释放不再需要的 buffer。**关键不是公式，是结合实际持有 trace 看**——在融合发生的那一步，加上所有输入 operands 之后的持有数是否超 P。
+
+### 3.4 转换在融合链中的位置
+
+- **扩位转换（窄→宽，如 b16→fp32）**：通常在链头部——载入 → 寄存器内扩位 → 后续计算
+- **缩位转换（宽→窄，如 fp32→b16）**：通常在链尾部——寄存器内缩位 → 写回片上
+
+## 4 互斥分支流规则（Tuple Reduce 场景）
+
+对 N 次独立归约（Tuple Reduce，见 [tuple-reduce.md](tuple-reduce.md)）的场景，存活节点分析**分阶段**（前/归约/后段，Group 为 Phase 1/Phase 2）各自画**一条流**，禁止按 for 循环展开成多轮：
+
+1. **公共步骤**（所有过程都执行）在流中只出现一次
+2. **过程独有步骤**写成 `if (processIdx == …) {…} else if …` 并列分支，分割粒度 = 归约过程（同一过程的多个分叉输出在该分支内合并 trace）
+3. **分支峰值取 max**：分支互斥——任一时刻只执行一个分支，各分支的 buffer 不可能同时存活；一处 if/else 的峰值 = 各分支峰值的 max，**禁止相加、不按分支单独记账**
+4. **存活期照常判定**：分支的中间 buffer 在分支结束即释放；释放后的普通复用池 buffer 可被后续任意步骤复用，与它来自哪个分支无关
+5. 每个阶段一条流走完，阶段峰值 = 该阶段存活节点数；buffer 份数按汇总表分阶段相加
+
+以上规则对 L、P 均适用；"共用物理片上/记账/份数"只作用于 P——L 无物理复用概念，仍按公平基线逐 op 计节点。
+
+## 5 追踪方法（L 与 P 共用）
+
+1. 画出完整计算图（含归约）
+2. 识别分叉结构（同一数据被多处引用）
+3. 按最优调度逐步追踪每步的**执行中**存活数："执行中"取峰值瞬间 = 输入未释放 + 输出写入；输入仅在"执行后"其**所有消费者完成**时才移除
+4. 取全流程最大值 = 存活节点数

package/assets/ops-direct-invoke/skills/ops-design-paradigms/references/paradigms/reduction/generic/scene.md

@@ -0,0 +1,92 @@
+# Reduction 范式场景模型
+
+> **层级**：通用知识层（generic/），语言中立。
+>
+> 来源：adapters/ascendc/overview.md §1/§2/§3/§4（原 reduction-template-overview.md）、原范式入口 patterns.md 范式总览。TilingKey/TilingData 的具体实现（模板宏、struct 定义）在适配层。
+
+## 1 准入条件
+
+本范式覆盖的算子需满足：
+
+1. **跨元素归约语义**——输出元素由输入沿归约轴（R 轴）折叠计算得到（sum/mean/max/min/prod/any/all 及其复合），归约结果沿非归约轴（A 轴）保留
+2. **归约轴可标记**——输入张量的每一根轴可按算子语义标记为 A 轴（preserve）或 R 轴（reduce）
+3. **输出 shape 由 A 轴决定**——归约后 R 轴消失（keep_dims 场景 R 轴变 1，仍按消失处理）
+
+典型场景：单/多轴 reduce、全轴归约（All Reduce）、含归约的复合计算（reduce 前/后有 elementwise 变换）。仅 element-wise 无归约的算子走其他范式。
+
+## 2 坐标系与术语（语言中立）
+
+| 术语 | 含义 |
+|------|------|
+| **A 轴** | 非 reduce 轴（preserve），归约后保留 |
+| **R 轴** | reduce 轴，沿此轴归约 |
+| **pattern** | 合轴预处理后轴的类型序列，形如 `A R A R …`（A 起头、严格交替） |
+| **TailA / TailR** | 合轴后尾轴是 A（如 `ARA`）/ R（如 `ARAR`），决定片上数据排布与归约方向 |
+| **All Reduce** | 所有轴都 reduce 的算子，合轴后 pattern 恒为 `AR` |
+| **空 tensor** | shape 中含 0 的输入，分 EMPTY_A（A 轴含 0）/ EMPTY_R（R 轴含 0 且 A 全非 0） |
+| **post_reduce_input** | 归约后阶段的额外输入（如 mean/variance 等统计量），shape 与输出相同（A 轴，size = aTotal） |
+| **aTotal** | ∏(所有 A 轴 size)，输出元素总数 |
+| **MAX_PATTERN_RANK** | 本算子合轴后 pattern 的最大可能轴数（推导见 [axis-preprocessing.md](axis-preprocessing.md) §5） |
+
+坐标系经合轴预处理归一（见 [axis-preprocessing.md](axis-preprocessing.md)）：A 起头、A/R 严格交替、除补位轴外每轴 size ≥ 2。轴类型由位置奇偶唯一决定（i 偶 → A，i 奇 → R）。
+
+## 3 模板分类
+
+按多核切分轴分三类模板（每算子选 1~3 个）：
+
+| 模板 | 使用场景 | 准入条件 | 多核切分 |
+|------|---------|---------|---------|
+| **Base** | 通用归约主路径 | 非空 tensor，A 轴并行度足够开多核 | 仅 A 轴参与分核，核间无依赖，核内完成全部 R 轴归约 |
+| **Group** | A 轴小时借 R 轴补并行度 | 非空 tensor，A 用不满核且 R 有并行度 | A×R 2D 分核，核间有依赖，经中间存储二次归约 |
+| **Empty** | 空 tensor 简化路径 | 空 tensor（EMPTY_A / EMPTY_R 共用） | EMPTY_A 全核早退；EMPTY_R 按 a 元素数切分 |
+
+**模板选择键**只有两个维度：是否 Group、是否 Empty tensor。**dtype 不进选择键**——由框架按输入 dtype 注入编译实例；axisNum 不进选择键——运行时分支处理。选择键的落地机制（模板参数/分发宏）由语言适配层定义。
+
+**统一树形累加**：所有归约算子（sum/mean/max/min/prod/any/all）统一使用二分缓存树累加（见 [tree-reduction.md](tree-reduction.md)）。对 sum/mean 有精度收益（浮点累加误差 O(M)→O(log M)）；对 max/min/any/all 结果不变（满足结合律）；prod 因浮点舍入不满足结合律、结果可能有差异，但统一路径简化模板设计。
+
+## 4 数据流骨架
+
+计算图按三段式划分，两个桥接节点连接：
+
+```
+┌─ 归约前段（preReducePhase）──────────────────────────────┐
+│  输入 → 搬入 → PreElewise → preReduceResult（可选旁路输出）│
+└──────────────────────────┬───────────────────────────────┘
+                           ↓
+┌─ 归约段（reducePhase）───────────────────────────────────┐
+│  preReduceResult → 片上归约 → 树缓存 → reduceResult（树根）│
+└──────────────────────────┬───────────────────────────────┘
+                           ↓
+┌─ 归约后段（postReducePhase）─────────────────────────────┐
+│  reduceResult + 可选 post 输入 → PostElewise → 搬出        │
+└───────────────────────────────────────────────────────────┘
+```
+
+- **preReduceResult / reduceResult** 是两个桥接节点；归约前段与归约后段**独立**做存活节点分析与融合分析，不跨归约段融合
+- **Base 模板**单阶段完成三段；**Group 模板**拆两阶段：Phase 1 = 归约前段 + 局部 R 段归约（partial 结果写中间存储），Phase 2 = 剩余 R 维归约 + 归约后段，两阶段经跨核栅栏衔接（见 [sync-model.md](sync-model.md) §5）
+- **Empty 模板**无归约：EMPTY_A 零计算零 IO；EMPTY_R 以固定值填充（`empty_r_output_value`，由算子语义决定，如 sum=0 / max=identity）替代归约，后接可选 PostElewise
+
+## 5 编译期特化
+
+- 特化维度只有**模板选择键**（是否 Group / 是否 Empty），与 dtype 无关（dtype 由框架注入）
+- 合轴后 pattern 轴数上限 MAX_PATTERN_RANK 决定 pattern 描述数组的定长
+
+## 6 能力边界
+
+1. 归约精度：树形累加对结合律运算（max/min/any/all）结果不变；对 sum/mean 有精度收益；prod 有浮点舍入差异——产品语义若要求严格顺序累加，不在本范式 standard 路径内
+2. 本范式不做切分之外的调度优化（Group 触发判定即 A 方向并行度不足时的借 R 补并行度策略）
+3. 空 tensor 语义由算子级判定：空 axes（axesNum==0）按 all-reduce 还是 noop 展开必须给出单一结论（见 [axis-preprocessing.md](axis-preprocessing.md) §1）
+4. 确定性：固定切分 + 固定树形累加顺序 → 同设备同输入多次执行 bitwise 可复现
+
+## 7 依赖谓词
+
+| 谓词 | 用途 |
+|------|------|
+| `REDUCE_OP` | 片上归约指令实体（三段式中归约段的执行者） |
+| `TREE_CACHE_CAPACITY` | 树形累加缓存的容量约定 |
+| `COMPUTE_PRECISION` | 归约统一计算精度 |
+| `ALIGN_GRANULARITY` | 片上数据对齐粒度 |
+| `CROSS_CORE_FENCE` | Group 两阶段跨核栅栏 |
+| `WORKSPACE_MODEL` | Group 中间存储（跨核 partial 结果传递） |
+
+谓词定义见 [capability-contract.md](capability-contract.md)；各语言真值见对应适配层 capability-mapping。

package/assets/ops-direct-invoke/skills/ops-design-paradigms/references/paradigms/reduction/generic/splitting.md

@@ -0,0 +1,230 @@
+# Reduction 范式切分算法（UB 双切分 + 多核切分 + UB 预算）
+
+> **层级**：通用知识层（generic/），语言中立。
+>
+> 来源：adapters/ascendc/templates/binary-base/tiling.md §1/§2/§5（原 reduction-binary-base-tiling.md）、adapters/ascendc/templates/binary-group/tiling.md §2/§5、adapters/ascendc/templates/empty/tiling.md §1/§2/§5。C++ 实现（`ComputeAUbFactor()` / `ComputeRUbFactor()` 等）在适配层。
+
+## 1 记号与输入
+
+| 记号 | 含义 |
+|------|------|
+| `axisShape[]` / `axisNum` | 合轴后的 pattern（A 起头、严格交替），来自 [axis-preprocessing.md](axis-preprocessing.md) |
+| `isTailR / isTailA` | axisNum 偶数 → tail R；奇数 → tail A |
+| 片上容量 | 单核算可用的片上 buffer 总容量（AscendC: UB 大小） |
+| `P_pre` / `P_pre_ext`（固定 1）/ `P_post` | 三段式 buffer 份数，来自 [liveness-fusion.md](liveness-fusion.md) §2 |
+| `ALIGN_GRANULARITY` | 片上数据对齐粒度（能力谓词）；`bsElem = ALIGN_GRANULARITY / sizeof(D_T)`（元素数取整用） |
+| `CACHELINE_SIZE` | cache line 宽度（能力谓词），决定爬坡上界 |
+| `COMPUTE_PRECISION` | 归约统一计算精度（能力谓词）；`maxDtypeSize = max(sizeof(D_T), 精度宽度)`（字节容量用） |
+| `TREE_CACHE_CAPACITY` | 树缓存容量（能力谓词，固定值） |
+| `maxCores` | 可用核数 |
+
+⛔ **dtype 派生参数适用边界**：`bsElem`（元素数取整）按输入 dtype 算；`maxDtypeSize`（字节容量）按输入 dtype 与计算精度取宽者算——**禁止混用**。片上 buffer 统一按 `maxDtypeSize` 分配容量（跨 dtype 复用）。
+
+## 2 UB 双切分（Base / Group Phase 1 通用）
+
+### 2.1 切分原理
+
+A 轴与 R 轴**各有**一个片上切分点，互相独立：
+
+- **R 必须切**：片上必须做归约，必须把 R 搬到片上
+- **A 必须切**：tail-A 下 R 在外部存储非连续排布，A 切入片上才能保证搬运连续性
+- 统一 AR/RA 用同一套双切分框架
+
+被切分的轴记为切分轴（`aSplitIdx` / `rSplitIdx`），切分因子 `aUbFactor` / `rUbFactor`。**轴归属**：切分点**左侧**轴 + 切分轴的外层部分（`.o`）→ 外层 for 循环；切分轴的内层部分（`.i`）+ **右侧**所有轴 → 驻留片上。整轴全载是切多 chunk 的特例（factor = axisSize，`.o = 1`）。
+
+### 2.2 三步算法（顺序固定）
+
+**Step 1：定 A 切分（联合爬坡）**
+
+A 轴与 R 轴一起从最内轴向外爬坡，目标上界为 `cachelineTmp`（一个 cache line 的元素数，`FloorAlign(CACHELINE_SIZE / sizeof(D_T), bsElem)`）。爬坡中 R 轴参与累乘（估算片上 A+R 总元素量）但不进 `innerAProdAlign`（只统计 A 轴）。尾轴（无论 A/R）一律 CeilAlign 到对齐粒度（burst 尾轴方向），非尾轴按原值累乘。终止于 `product × axisSize > cachelineTmp`。
+
+停止轴 `idx` 的判定：
+
+| `idx` 情况 | `aSplitIdx` | `aUbFactor` | 说明 |
+|---|---|---|---|
+| `idx < 0`（所有轴全驻） | 0 | `axisShape[0]` | 全部装入仍未超上界，无轴可切 |
+| `idx` 是 A 轴 | `idx` | `min(cachelineTmp / product, axisShape[idx])` | 直接切该 A 轴 |
+| `idx` 是 R 轴 | `idx − 1` | 1 | R 轴不能作 A 切分点，左移到其左侧第一根 A（交替排列必存在），每 chunk 取 1 |
+
+`innerAProdAlign`（padded）只统计切分轴**右侧**的 A 轴，tail-A 时最内 A 轴 CeilAlign。定义 `aUnit = aUbFactor × innerAProdAlign`（片上 A 维元素数）。tail-A 下 aUnit 一定对齐；tail-R 下可能非对齐。**不需要 `aUbFactorAlign`**：三种情形（aSplitIdx==LastA / !=LastA / tail-R）均直接使用 `aUbFactor`。
+
+**Step 2：反解 R 切分（UB 预算反解）**
+
+1. **先算 `postBufSize`**（归约后段单份 buffer 字节）：`CeilAlign(aUnit × maxDtypeSize, ALIGN_GRANULARITY)`（1D，必须对齐）
+2. **反解 `r_i_max`**：可用片上容量先扣固定树缓存，再减归约后段独占字节，剩余除以"每 R 元素的归约前段字节开销"：
+
+```
+ubAvailable = 片上容量 − TREE_CACHE_CAPACITY
+aOnlyBytes  = P_post × postBufSize
+bytesPerRElem = (P_pre + P_pre_ext) × aUnit × maxDtypeSize
+r_i_max = (ubAvailable − aOnlyBytes) / bytesPerRElem      // 向下取整
+```
+
+> `aOnlyBytes` 用 `postBufSize`（1D 须对齐）；`bytesPerRElem` 用 `aUnit × maxDtypeSize`（2D，burst 尾轴方向已由 padded 字段保证对齐，非尾轴方向不对齐，无需额外 CeilAlign）。
+
+3. **R 端爬坡**：从最内 R 轴向外逐根吸入 `innerRProdAlign`（tail-R 时尾轴先 CeilAlign 再比较），终止于超预算
+4. **定 `rUbFactor` 与 padded 版**：`rUbFactor = min(r_i_max / innerRProdAlign, axisShape[rSplitIdx])`；
+   - tail-R 且 rSplitIdx 是尾轴（burst 尾轴方向）：切多 chunk 需 FloorAlign（对齐后为 0 → 切分失败）；整轴需 CeilAlign 并校验不超预算，放大超预算则退回切多 chunk
+   - 其他情况不需对齐，`rUbFactorAlign = rUbFactor`
+   - **Align > valid 条件**：仅 tail-R 且切尾轴且尾轴全载且非对齐时 `rUbFactorAlign > rUbFactor`，其余相等
+
+**Step 3：所有 R 全驻后扩 A**
+
+若 R 切分轴整轴全载且已无更外 R 轴（所有 R 全驻片上），回头扩 A 填满剩余空间：
+
+1. **解 `aUnitMax`**：R 端固定占用代回预算不等式，提出公因式：
+
+```
+aUnitMax ≤ ubAvailable / (maxDtypeSize × ((P_pre + P_pre_ext) × rPaddedElems + P_post))
+其中 rPaddedElems = rUbFactorAlign × innerRProdAlign
+```
+
+   并取 `min(aUnitMax, ∏所有 A 轴 size)`
+2. **钳制树缓存**：所有 R 全驻即树缓存只有 1 层，`aUnitMax ≤ TREE_CACHE_CAPACITY / 精度宽度`（不钳制会树缓存溢出）
+3. tail-A 时在 min(∏A) 钳制**之后** FloorAlign（∏A 可能非对齐）；重做 A 端爬坡（只爬 A 轴），切分点可能外移，重算 `innerAProdAlign`
+4. `aUnitMax ≤ 当前 aUnit` 时扩 A 无效，保持 Step 1 结果不变
+
+### 2.3 valid / padded 双字段语义
+
+| 字段对 | valid（原值）用途 | padded（对齐值）用途 |
+|---|---|---|
+| `rUbFactor` / `rUbFactorAlign` | 外部存储 stride、valid 元素数、partial chunk 判定 | 片上行 stride、归约指令 srcShape、片上占用预算 |
+| `innerAProd` / `innerAProdAlign` | （含尾轴 A 的有效连乘） | 片上 A 维预算、aUnit 构成 |
+
+## 3 多核切分（Base：A 方向 fused 分核）
+
+外层 A loop 全部 fuse 成一根线性计数，多核按此瓜分：
+
+```
+aSplitChunkCnt = CeilDiv(axisShape[aSplitIdx], aUbFactor)
+outerAProd     = ∏(切分轴左侧的外层 A 轴)
+aLoopCntTotal  = outerAProd × aSplitChunkCnt
+```
+
+线性编码 row-major（切分 chunk 在最内）；解码顺序相反：先取 chunk，再逐轴分解。
+
+**大小核均衡**（`MULTICORE_BALANCE` 谓词）：
+
+```
+aSmallCoreLoopCnt = aLoopCntTotal / maxCores        // floor
+aBigCoreCnt       = aLoopCntTotal % maxCores
+aBigCoreLoopCnt   = aSmallCoreLoopCnt + (aBigCoreCnt > 0 ? 1 : 0)
+usedCoreNum       = (aSmallCoreLoopCnt > 0) ? maxCores : aBigCoreCnt
+```
+
+前 `aBigCoreCnt` 核多担 1 份；blockIdx ≥ usedCoreNum 空闲；最大负载差 ≤ 1。
+
+**R 外层循环计数**：`rLoopCntTotal = ∏(切分轴左侧外层 R 轴) × CeilDiv(axisShape[rSplitIdx], rUbFactor)`。
+
+**约束**：使用核数为 0 时仍按 `BLOCK_DISPATCH_MIN` 发起（≥1），kernel 侧短路；发起核数严禁超过物理核数。
+
+## 4 Group 2D 分核
+
+**触发判定**（`ShouldUseGroup`）：A 方向外层总数 `aOuter = aLoopCntTotal`，R 方向 `rOuter = rLoopCntTotal`：
+
+```
+if aOuter > maxCores / 2    → Base   # A 够分核
+else if rOuter <= 1          → Base   # R 无并行度
+else                         → Group  # A 用不满核，借 R 补并行度
+```
+
+> 阈值取 `maxCores / 2` 的原因：A×R 2D 分核时 A 切片不可再拆（片上切分后的最小调度单元）。若 `aOuter > maxCores/2`，即使 R 组数为 2 也会超物理核数，跨核栅栏会挂死。
+
+**2D 分核**（`ComputeGroupSplit`）：
+
+```
+totalOuter = aOuter × rOuter
+perCoreNum = CeilDiv(totalOuter, maxCores)
+numBlocks  = CeilDiv(totalOuter, perCoreNum)
+# 对齐到 aOuter —— 保 2D 网格整齐、负载均匀
+if CeilAlign(numBlocks, aOuter) <= maxCores: numBlocks = CeilAlign(...)
+else:                                         numBlocks = FloorAlign(...)
+usedCoreNum = numBlocks
+rGroupCnt   = numBlocks / aOuter     # 整除
+```
+
+**`aPerCore = 1` 恒成立**：numBlocks 对齐到 aOuter 的倍数 → 每核只处理 1 个 A chunk。
+
+**Group workspace**（`WORKSPACE_MODEL` 谓词）：布局 `[rGroupCnt, aTotal]`、按计算精度 dense 行优先；大小 = `rGroupCnt × aTotal × 精度宽度`。总 workspace = 系统部分 + 用户部分。
+
+**R 方向分组分配**（kernel 侧）：R 方向**大小核式均匀分配**（每组 ≥ 1 chunk、无空组，`rGroupCnt ≤ rOuter` 恒成立），⛔ 禁止 CeilDiv 截断式分配。
+
+**调度模式**：Group 使用跨核栅栏（`CROSS_CORE_FENCE`），host 侧须按语言要求声明调度模式（等全部核空闲才启动）。
+
+## 5 Empty 切分
+
+**EMPTY_A**：无切分。使用核数为 0，按 `BLOCK_DISPATCH_MIN` 发起，所有核早退。
+
+**EMPTY_R**：按 **a 元素数**切（aTotal = 合所有 A 轴后的线性元素数）：
+
+```
+maxDtypeSize = max(sizeof(D_T), 精度宽度)
+四约束：
+  a) 单 buf 下界（保证搬运效率）     → min_a_per_core = CeilDiv(下界字节数, maxDtypeSize)
+  b) 优先多核                       → CeilDiv(aTotal, maxCores)
+  c) UB 上限                        → maxBufSize = min(片上容量 / P_post, SINGLE_BUF_MAX)
+                                       → max_ub_factor = maxBufSize / maxDtypeSize
+  d) aTotal 兜底                    → aTotal
+aUbFactor = min(max(min_a_per_core, CeilDiv(aTotal, maxCores)), max_ub_factor)
+aUbFactor = min(aUbFactor, aTotal)
+```
+
+之后按 `aLoopCntTotal = CeilDiv(aTotal, aUbFactor)` 做大小核均衡（同 §3）。`postBufSize = CeilAlign(max(aUbFactor × maxDtypeSize, ALIGN_GRANULARITY), ALIGN_GRANULARITY)`（单份至少一个对齐粒度）。
+
+## 6 UB 预算不等式与 buffer 大小公式
+
+**buffer 大小**：
+
+```
+aUnit        = aUbFactor × innerAProdAlign
+postBufSize  = CeilAlign(aUnit × maxDtypeSize, ALIGN_GRANULARITY)          # 1D，对齐
+preBufSize   = aUnit × rUbFactorAlign × innerRProdAlign × maxDtypeSize     # 2D dense
+树缓存        = TREE_CACHE_CAPACITY（固定）
+```
+
+**UB 预算不等式**（padded 尺寸）：
+
+```
+(P_pre + P_pre_ext) × preBufSize + P_post × postBufSize ≤ ubAvailable
+其中 ubAvailable = 片上容量 − TREE_CACHE_CAPACITY
+```
+
+**树缓存硬约束**：
+
+```
+cacheCount × CeilAlign(aUnit, 最小对齐元素数) × 精度宽度 ≤ TREE_CACHE_CAPACITY
+cacheCount = log2(FindNearestPower2(rLoopCntTotal)) + 1
+```
+
+计算精度下恒满足（aUnit ≤ 爬坡上界 → 层数有限）；窄 dtype 需极端 rLoopCntTotal 才违反、实际不可达，不设校验。R 全驻（cacheCount=1）由 §2.2 Step 3 的 aUnitMax 钳制保证。
+
+## 7 切分总流程（伪码）
+
+```
+TilingFunc(ctx):
+    # 0) 平台信息（全走接口，逐项非零校验）
+    # ★ 空 tensor 短路（必须在合轴四步之前）
+    if 空 tensor: return HandleEmptyTensor()      # §5
+
+    # 合轴四步（顺序不可换）
+    DropSizeOneAxes(); FuseAxis(); PadLeadingOneA(); PadRIfPureA()
+    校验 2 ≤ axisNum ≤ MAX_PATTERN_RANK
+
+    # 1) UB 切分三步
+    ComputeAUbFactor()        # Step 1: 定 A 切分
+    ComputeRUbFactor()        # Step 2: 反解 R 切分
+    ExpandAIfRFullyLoaded()   # Step 3: R 全驻后扩 A
+
+    # 2) 多核切分
+    ComputeFusedALoopSplit()  # A 方向 fused 分核 + 大小核均衡
+    ComputeRLoopCnt()
+
+    # 3) Group 判定（条件性）
+    if ShouldUseGroup():
+        ComputeGroupSplit()   # A×R 2D 分核 → usedCoreNum, rGroupCnt
+        声明调度模式
+
+    # 4) 收尾
+    ComputeUbSizes(); FillAndLogTilingData()
+    设 TilingKey / BlockDim / Workspace
+```

package/assets/ops-direct-invoke/skills/ops-design-paradigms/references/paradigms/reduction/generic/sync-model.md

@@ -0,0 +1,86 @@
+# Reduction 范式同步模型（RAW/WAR 依赖 → 同步点推导）
+
+> **层级**：通用知识层（generic/），语言中立。
+>
+> 来源：adapters/ascendc/templates/*/kernel-template.md §7（原 reduction-*-kernel-template.md）、原范式入口 patterns.md 各"流水同步方案"节指引、adapters/ascendc/survival-node.md 持有法则。同步原语实体（AscendC: SetFlag/WaitFlag/HardEvent/eventID）在适配层与范式公共知识。
+
+## 1 同步的本质
+
+同步 = **跨执行单元的数据依赖**。同一个 buffer，执行单元 A 写、执行单元 B 读（RAW），或执行单元 A 读、执行单元 B 写（WAR）——就必须同步。
+
+- 同一执行单元内自动串行，不需同步
+- 不同 buffer 互不干扰
+- 无跨执行单元数据依赖时，不需要任何显式同步
+
+## 2 执行单元与事件对
+
+执行单元划分由 `EXEC_UNITS` 谓词定义。本范式涉及三个单元：搬入单元（片上←外部存储）、计算单元、搬出单元（片上→外部存储）。
+
+| 依赖类型 | 含义 | 事件对（源→目标） | 方向 |
+|---------|------|------|------|
+| RAW | 搬入写 buffer → 计算读 | 搬入→计算 | 正向 |
+| RAW | 计算写 buffer → 搬出读 | 计算→搬出 | 正向 |
+| WAR | 计算读 buffer → 搬入覆写同一 buffer | 计算→搬入 | 反向 |
+| WAR | 搬出读 buffer → 计算覆写（跨迭代） | 搬出→计算 | 反向 |
+| WAR | 搬出读 buffer → 搬入覆写（跨迭代） | 搬出→搬入 | 反向 |
+
+**融合链内部无同步**：同属计算单元的连续操作由硬件/流水线保证串行。
+
+## 3 同步点推导方法（持有法则驱动）
+
+同步点**必须由持有法则 trace 推导，禁止凭直觉预设**：
+
+1. 取**无同步版** Process 代码，逐行标注三态持有：`// 执行前/中/后: 持有=[...]`
+2. 遍历每个 buffer 的生命周期，标记跨执行单元的 RAW（生产者写→消费者读）与 WAR（消费者读→生产者覆写）
+3. 每个 crossing 插入对应的正向/反向同步对
+4. 产出**同步点推导表**：buffer × crossing 类型(RAW/WAR) × 事件类型 × 事件编号 × 循环内/循环间，**每行标注 buffer 名称**
+5. 产出**事件编号分配表**：事件类型 × 编号 × 数量 × 用途；未使用的事件类型标注"不需要"并附理由
+
+### 3.1 三层 WAR 必查
+
+⚠ 跨迭代 WAR 必须**验证 buffer 身份**——上轮消费者读的 buffer 与下轮生产者写的 buffer 是**同一个物理 buffer** 才构成 WAR；不同 buffer 不构成，不得插入同步。三层都必须检查：
+
+1. **同一迭代内**：如 Phase A 主块→尾块对同一片上块的覆写
+2. **跨内层迭代**：内层循环下一轮覆写同一 buffer
+3. **跨外层迭代**：外层循环下一轮覆写同一 buffer
+
+### 3.2 循环间反向同步（首轮/末轮规则）
+
+跨迭代的反向同步（如 搬出→计算、搬出→搬入）：**首轮跳过等待、末轮跳过置位**——仅第一轮不需要等上一轮（不存在），最后一轮不需要为下一轮置位（不存在）。
+
+⛔ Tuple Reduce 场景："首轮/末轮"按**全局（跨归约过程）**判定——仅第一个过程的首轮跳等待、最后一个过程的末轮跳置位，中间轮次正常置位/等待（见 [tuple-reduce.md](tuple-reduce.md) §3）。
+
+### 3.3 典型 buffer 非复用约束（推导的设计输入）
+
+以 Base 模板为例（具体 buffer 命名随语言适配层）：
+
+- 归约后段输出块与归约前段输入块**独立分配**、跨外层迭代不复用 → 搬出与下轮搬入**不构成 WAR**，不需要 搬出→搬入 反向同步
+- 输出块跨外层迭代复用：本轮搬出读 → 下轮归约后段计算写 → 构成 搬出→计算 WAR，需反向同步
+- 输入块跨内层迭代复用：本轮计算链末尾读 → 下轮搬入覆写 → 构成 计算→搬入 WAR，需反向同步
+- 输入块跨外层迭代复用：本轮最后内层块的计算 → 下轮第一内层块的搬入 → 构成跨外层的 计算→搬入 WAR
+
+> ⚠ 不同算子的 buffer 复用方式不同，同步点可能不同——以上是方法示例，不是可照抄的结论。
+
+### 3.4 循环控制流检查
+
+⚠ 各循环内 `continue`/`break` 可能导致同步对不匹配（置位了没等待、或等待了没置位），必须**逐轮检查配对完整性**。
+
+## 4 核内单流水的同步形态
+
+Base / Empty 模板：核内一条流水（搬入→计算→搬出），无跨核同步。同步全部由 §3 的持有法则推导；Empty 的 EMPTY_A 全核早退、无任何同步。
+
+## 5 跨核栅栏（Group 两阶段）
+
+Group 模板 Phase 1→Phase 2 用**跨核栅栏**（`CROSS_CORE_FENCE` 谓词）：
+
+- Phase 1 各核将 partial 归约结果写中间存储（workspace）→ 栅栏 → Phase 2 各核从 workspace 读入做剩余归约
+- 栅栏要求**全部参与核到齐**才放行；host 侧须按语言要求声明调度模式（如 AscendC 需 `SetScheduleMode(1)`，否则栅栏挂死）
+- Phase 1 内部/Phase 2 内部的核内流水同步仍按 §3 推导，与栅栏独立
+- Phase 1 的核内同步事件在栅栏前全部消费完毕，Phase 2 开始时事件池无残留
+
+## 6 同步产出的验收要点
+
+1. 同步原语必须成对（置位/等待各一次），事件编号经管理接口获取、不可硬编码
+2. 同类型事件可共用 1 个编号（前一个等待消费后可复用）
+3. 禁止插入任何未由持有法则推导出的同步点
+4. 无同步需求的分支（如 EMPTY_A）显式声明"无同步"并说明原因