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

package/assets/ops-direct-invoke/skills/ops-design-paradigms/references/paradigms/broadcast/generic/compute-flow.md

@@ -0,0 +1,216 @@
+# broadcast 范式 standard 计算流伪码
+
+> **层级**：通用知识层（generic/），语言中立。文中操作动词（DataCopy / Mul / MulAddDst 等）均为 **AscendC 示例标注**，其他语言按各自适配层映射为对应动词。
+
+> 计算流伪码是物理存活节点（P）分析的序列化产物，物理分析到 kernel 编码之间的桥梁。
+
+依赖输入：[liveness-fusion.md](liveness-fusion.md)（P trace 结论）、[../adapters/ascendc/kernel-template.md](../adapters/ascendc/kernel-template.md)（§1.2 IR 描述、§8 产出校验，AscendC 实例）
+
+## 1 定义与定位
+
+### 1.1 什么是计算流伪码
+
+计算流伪码是 [liveness-fusion.md](liveness-fusion.md) 物理存活节点分析的序列化产物。P trace 选定了三要素组合（API 能力 + 融合策略 + buffer 分配），伪码把这一选择写成 `搬运 → 计算 → 释放` 的完整序列。每步标注片上驻留数，验证全程 ≤ P。
+
+伪码不是实现——它是物理分析到 kernel 编码之间的桥梁。后续所有设计（计算流验证、输入预处理、UB 切分、kernel 编码）都以这份伪码为唯一参照。
+
+### 1.2 与 kernel IR 描述的关系
+
+[../adapters/ascendc/kernel-template.md](../adapters/ascendc/kernel-template.md) §1.2 的 kernel IR 描述是高层概述（`out[i] = f(x, y)`），说明计算语义。计算流伪码是详细序列化展开，包含：
+- 每步的 buffer 分配/释放
+- UB 驻留计数
+- 融合和 broadcast 的具体嵌入
+
+IR 描述回答"算什么"，计算流伪码回答"怎么算、用哪些 buffer、何时释放"。
+
+### 1.3 与 kernel 产出校验的关系
+
+[../adapters/ascendc/kernel-template.md](../adapters/ascendc/kernel-template.md) §8 的 golden for 循环是验证基准，纯计算逻辑。计算流伪码是验证的输入——§8 的 golden 应与计算流伪码语义等价。
+
+### 1.4 物理意义
+
+P trace 的物理节点分析是"每一步 peak 多少"的抽象论证。伪码把它落实到每一行的具体操作：哪个 buffer 在哪个时刻被创建、被消费、被释放。它回答三个问题：
+- P 能否兑现为一个具体的步骤序列？
+- 每步的 UB 驻留是否始终 ≤ P？
+- 融合（如硬件融合乘加，AscendC: MulAddDst）和 broadcast（搬运随路，AscendC: NDDMA）是否正确嵌入？
+
+## 2 何时需要
+
+agent 自行判断是否执行：
+
+| 条件 | 是否执行 |
+|------|---------|
+| 链长 ≤3、单输出、无 Cast+VF 混合 | 跳过，P trace 已充分表达 |
+| P trace 已充分表达计算步骤 | 跳过 |
+| 链长 >5、含分支/并行路径、多输出 | 建议执行 |
+
+## 3 规范格式
+
+### 3.1 头部声明
+
+```
+输入:  <输入变量列表>
+输出:  <输出变量列表>
+约束:  UB 最多同时驻留 P 块 buffer
+```
+
+### 3.2 步骤格式
+
+每步包含：
+1. **注释标题**：`// ─── Step N: <操作描述> ───`
+2. **操作行**：`<操作>(<参数>) → <bufXxx>`，DataCopy 标注搬运方向和 broadcast 策略
+3. **UB 驻留计数**：`// UB: [<buf1>, <buf2>, ...] = N`
+4. **释放注释**（如有）：`// 释放 <bufXxx>, <bufYyy>`
+5. **释放后驻留**（如有释放）：`// UB: [<buf1>, ...] = N`
+6. **峰值标注**（如达到 P）：在 Step 标题行标注 `← 峰值 P`
+
+### 3.3 dtype 分路径
+
+每种 dtype 路径分别写一份计算流伪码。不同 dtype 路径可能因 Cast 插入而步骤数不同——Cast 不参与 VF 融合，作为链的断点，可能增加中间 buffer 和步骤。
+
+### 3.4 搬出段
+
+所有计算完成后，统一搬出所有输出：
+```
+// ─── 搬出 ───
+DataCopy(output0, UB→GM)
+DataCopy(output1, UB→GM)
+```
+
+多输出时，搬出单元顺序执行（AscendC: MTE3），CopyOut 之间不需额外同步。输出 buffer 在 CopyOut 前不可被覆写。
+
+## 4 关键设计决策表
+
+| 决策 | 选择 | 理由 |
+|------|------|------|
+| broadcast 策略 | NDDMA 随路 / 独立 broadcast | <理由> |
+| 融合策略 | MulAddDst / 无融合 | <理由> |
+| output 持久化 | 保留至搬出 / 提前释放 | <理由> |
+| RegBase | 使用 / 不使用 | <理由> |
+
+## 5 结论
+
+N 步序列全程 UB 驻留 ≤ P，P=<值> 可兑现。<融合策略> 消化了 <具体中间 buffer>，<broadcast 策略> 消化了 <具体 broadcast 操作>。
+
+## 6 完整示例
+
+### 6.1 简化示例（二元算子，P=3）
+
+```pseudocode
+输入:  x, y
+输出:  out
+约束:  UB 最多同时驻留 3 块 buffer
+
+// ─── Step 1: 载入 x ───
+DataCopy(x, GM→UB, NDDMA_broadcast)   → bufX
+// UB: [bufX] = 1
+
+// ─── Step 2: 载入 y，算 mul ───  ← 峰值 3
+DataCopy(y, GM→UB, NDDMA_broadcast)   → bufY
+AscendC::Mul(bufOut, bufX, bufY)       → bufOut
+// UB: [bufX, bufY, bufOut] = 3
+// 释放 bufX, bufY
+// UB: [bufOut] = 1
+
+// ─── 搬出 ───
+DataCopy(out, UB→GM)
+```
+
+关键设计决策：
+
+| 决策 | 选择 | 理由 |
+|------|------|------|
+| broadcast 策略 | NDDMA 随路 | 不另占 UB buffer |
+| 融合策略 | 无融合 | 单步二元操作，无相邻 Vector 可融合 |
+| output 持久化 | 立即搬出 | 无下游消费 |
+| RegBase | 不使用 | 二元操作 src 本就在 UB，RegBase 不降节点 |
+
+结论：2 步序列全程 UB 驻留 ≤ 3，P=3 可兑现。
+
+### 6.2 复杂示例（AdamApplyOneAssign算子，P=5，含 MulAddDst 融合）
+
+```pseudocode
+输入:  dataInput0..4, dataInputMul, dataInputMul1..3, dataInputAdd2
+输出:  output0, output1, output2
+约束:  UB 最多同时驻留 5 块 buffer
+
+// ─── Step 1: 载入 dataInput0，算 square ───
+DataCopy(dataInput0,  GM→UB, NDDMA_broadcast)   → bufInput0
+AscendC::Mul(bufSquare, bufInput0, bufInput0)           → bufSquare
+// UB: [bufInput0, bufSquare] = 2
+
+// ─── Step 2: 载入 mul1_x，算 mul1 ───
+DataCopy(dataInputMul1, GM→UB, NDDMA_broadcast) → bufMul1X
+AscendC::Mul(bufMul1, bufInput0, bufMul1X)             → bufMul1
+// 释放 bufInput0, bufMul1X
+// UB: [bufSquare, bufMul1] = 2
+
+// ─── Step 3: 载入 dataM + mul0_x，MulAddDst 融合 S7+S9 → output1 ───
+DataCopy(dataInput2,    GM→UB, NDDMA_broadcast) → bufDataM
+DataCopy(dataInputMul, GM→UB, NDDMA_broadcast) → bufMul0X
+MulAddDst(bufMul1, bufDataM, bufMul0X)      → output1
+// dst=output1 就地覆写 bufMul1
+// 释放 bufDataM, bufMul0X
+// UB: [bufSquare, output1] = 2
+
+// ─── Step 4: 载入 mul3_x，算 mul3 ───
+DataCopy(dataInputMul3, GM→UB, NDDMA_broadcast) → bufMul3X
+AscendC::Mul(bufMul3, bufSquare, bufMul3X)             → bufMul3
+// 释放 bufSquare, bufMul3X
+// UB: [output1, bufMul3] = 2
+
+// ─── Step 5: 载入 dataV + mul2_x，MulAddDst 融合 S3+S4 → output0 ───
+DataCopy(dataInput1,     GM→UB, NDDMA_broadcast) → bufDataV
+DataCopy(dataInputMul2, GM→UB, NDDMA_broadcast) → bufMul2X
+MulAddDst(bufMul3, bufDataV, bufMul2X)       → output0
+// dst=output0 就地覆写 bufMul3
+// 释放 bufDataV, bufMul2X
+// UB: [output1, output0] = 2
+
+// ─── Step 6: sqrt ───
+AscendC::Sqrt(bufSqrt, output0)                           → bufSqrt
+// UB: [output1, output0, bufSqrt] = 3
+
+// ─── Step 7: 载入 add2_y，算 add2 ───  ← 峰值 5
+DataCopy(dataInputAdd2, GM→UB, NDDMA_broadcast) → bufAdd2Y
+AscendC::Add(bufAdd2, bufSqrt, bufAdd2Y)               → bufAdd2
+// UB: [output1, output0, bufSqrt, bufAdd2Y, bufAdd2] = 5
+// 释放 bufSqrt, bufAdd2Y
+// UB: [output1, output0, bufAdd2] = 3
+
+// ─── Step 8: output1 恒等乘 + truediv ───
+Muls(output1, output1, 1.0)                       → output1   (in-place)
+AscendC::Div(bufTruediv, output1, bufAdd2)               → bufTruediv
+// 释放 bufAdd2
+// UB: [output1, output0, bufTruediv] = 3
+
+// ─── Step 9: 载入 input4，算 mul4 ───  ← 峰值 5
+DataCopy(dataInput4, GM→UB, NDDMA_broadcast)     → bufInput4
+AscendC::Mul(bufMul4, bufTruediv, bufInput4)            → bufMul4
+// UB: [output1, output0, bufTruediv, bufInput4, bufMul4] = 5
+// 释放 bufTruediv, bufInput4
+// UB: [output1, output0, bufMul4] = 3
+
+// ─── Step 10: 载入 dataVar，算 sub → output2 ───  ← 峰值 5
+DataCopy(dataInput3, GM→UB, NDDMA_broadcast)     → bufDataVar
+Sub(output2, bufDataVar, bufMul4)              → output2
+// UB: [output1, output0, bufDataVar, bufMul4, output2] = 5
+// 释放 bufDataVar, bufMul4
+// UB: [output0, output1, output2] = 3
+
+// ─── 搬出 ───
+DataCopy(output0, UB→GM)
+DataCopy(output1, UB→GM)
+DataCopy(output2, UB→GM)
+```
+
+关键设计决策：
+
+| 决策 | 选择 | 理由 |
+|------|------|------|
+| broadcast 策略 | 全部 DataCopy 时随路 NDDMA broadcast | 不另占 UB buffer |
+| 融合策略 | S7+S9 → MulAddDst, S3+S4 → MulAddDst | 各省 1 中间 buffer |
+| output0/output1 持久化 | 保留至搬出，不提前释放 | 下游 truediv 和最终搬出都需要 |
+| RegBase | 不使用 | 该算子二元操作 src 本就在 UB，RegBase 不降节点 |
+
+结论：10 步序列全程 UB 驻留 ≤ 5，P=5 可兑现。NDDMA broadcast 消化了所有独立 broadcast 操作，MulAddDst 消化了 S7+S9 和 S3+S4 的中间 buffer。

package/assets/ops-direct-invoke/skills/ops-design-paradigms/references/paradigms/broadcast/generic/index.md

@@ -0,0 +1,23 @@
+# Broadcast 范式通用知识层索引
+
+> **层级**：通用知识层（generic/），语言中立。与语言适配层（`../adapters/<lang>/`）组合消费：先经 [../patterns.md](../patterns.md) 的语言路由确定适配层，再按下表按需展开。
+
+## 检索表
+
+| 文档 | purpose | read_when | keywords |
+|------|---------|-----------|----------|
+| [scene.md](scene.md) | 场景模型：准入条件、坐标系理论、数据流骨架、编译期特化、能力边界 | 判断算子是否属于本范式；建立全局心智模型 | 广播、准入、effective_shape、maximumBroShape、数据流、RANK |
+| [capability-contract.md](capability-contract.md) | 能力谓词定义：通用层算法引用的语言/硬件能力参数 | 编写新语言适配层；理解算法中的能力依赖 | 谓词、能力、对齐粒度、链长、融合 |
+| [shape-preprocessing.md](shape-preprocessing.md) | shape 归一化：补 1 / 去 1 / 归一 / 合轴四步算法与 broadcast 兼容校验 | Host 侧预处理设计；shape 归一化推导 | 补 1、去 1、合轴、坐标系、兼容校验 |
+| [splitting.md](splitting.md) | 片上内存单切分与多核均衡切分算法 | 切分策略设计；tiling 推导 | 切分轴、尾块、内轴、外轴、多核、tile、perBufElems |
+| [liveness-fusion.md](liveness-fusion.md) | L/P 存活节点模型、持有法则、融合决策方法论 | buffer 数量（P 值）推导；融合取舍分析 | 存活节点、L、P、持有法则、融合、峰值、buffer 复用 |
+| [sync-model.md](sync-model.md) | RAW/WAR 依赖识别与同步点推导模型 | 同步设计；从持有法则推导同步点 | RAW、WAR、同步、执行单元、流水线 |
+| [compute-flow.md](compute-flow.md) | 计算流伪码规范：P 分析到编码之间的桥梁 | 复杂算子需要写计算流伪码时 | 伪码、计算流、驻留计数、dtype 分路径 |
+| [verification.md](verification.md) | golden/opt 交叉验证方法论与验证 harness | 验证计算流 / 切分设计正确性 | golden、opt、交叉验证、随机 case、harness |
+
+## 使用规则
+
+1. 单个子问题最多展开 5 个叶子文档；仍未闭环则拆分为更小的子问题
+2. 通用层结论中的能力依赖一律引用 [capability-contract.md](capability-contract.md) 的谓词；具体真值以命中语言适配层的 capability-mapping 为准
+3. 通用层不含任何具体语言 API；文中出现 API 名处均为 AscendC 示例标注，其他语言按各自适配层映射
+4. 具体语言的实现（代码模板、参考源码、生成规范）在适配层，不在本文档族内

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

@@ -0,0 +1,200 @@
+# Broadcast 范式存活节点分析与融合决策
+
+> **层级**：通用知识层（generic/），语言中立。
+>
+> 来源：adapters/ascendc/dag-buffers.md §1/§2（原 broadcast-standard-dag-buffers.md）。RegBase/MemBase 对比、具体融合指令清单、buffer 管理实体在适配层。
+
+## 1 L/P 双层存活节点模型
+
+buffer 划分采用 **L/P 双层分析模型**：
+
+**逻辑存活节点（L）**：
+- 计数域：计算图 tensor（每个独立数据实体计 1）
+- 由计算图拓扑决定，与物理媒介无关
+- **L 对给定计算图是固定的**，不随硬件/API/实现改变
+
+**物理存活节点（P）**：
+- 计数域：片上 buffer。寄存器不在计数域——片上→寄存器→片上是过路中转，中间值留在寄存器时不占 P
+- **P 不由计算图唯一确定**——同一计算图，不同 API 策略/融合决策 → 不同 P。寻找在给定约束下可达的**最小峰值**
+
+**公平基线（L 和 P 共用）**：
+1. 二元及以上操作，不假设 dst 与 src 复用——每个 op 的 src 和 dst 各占独立节点
+2. 单步内不假设 in-place
+3. 跨步的"用完释放"允许——一个节点的所有消费者执行完后从存活列表移除
+
+**L 与 P 的关系**：P ≥ L 恒成立（每个 op 的 src 和 dst 各占独立片上 buffer）。`CAP_REG_CHAIN_FUSION`=true 的语言可打破此规律：中间值全程在寄存器，不落片上。L 仍包含（按 tensor 计数），P 不包含（寄存器不计入 P）。此时 **P < L 合法**。
+
+**物理基线差异来源表**：
+
+| 差异来源 | 公平？ | 说明 |
+|---------|--------|------|
+| 跨步 buffer 复用 | ✓ | 生命周期不重叠可共用物理 buffer，物理侧允许 |
+| 硬件融合指令（dst 就地覆写） | ✓ | 硬件保证 dst 就地覆写，计为 API 能力（`CAP_FUSED_ARITH`） |
+| 搬运随路广播 | ✓ | 搬入阶段完成（`CAP_BROADCAST_IN_TRANSFER`），不另占 buffer |
+| 软件原地覆写 | ✗ | 逻辑侧/物理基线均不假设 in-place |
+| 寄存器链融合 | ✓ | 中间值全程在寄存器（`CAP_REG_CHAIN_FUSION`） |
+
+## 2 持有法则
+
+持有法则是通用分析工具：每个执行动作标注**执行前/执行中/执行后**三态持有，验证峰值 ≤ P。
+
+| 动作 | 执行单元 | 对片上 buffer 的行为 |
+|------|--------|-------------|
+| 搬入（CopyIn） | 搬入单元 | **写** buffer — 从 GM 搬入新数据 |
+| 计算（Compute） | 计算单元 | **读** src buffer + **写** dst buffer |
+| 搬出（CopyOut） | 搬出单元 | **读** buffer — 搬出到 GM |
+
+- **写**：写入后 buffer 是否保留在持有中，取决于新数据有无未来消费者
+- **读**：读本身不改变持有，但读完后该 buffer 少了一个未来消费者。如果是最后一个消费者，执行后 buffer 从持有消失
+- **原地读写**（如硬件融合指令的目的操作数）：buffer 被读的同时也被写，按写处理
+
+三态定义：
+
+| 态 | 含义 |
+|----|------|
+| 执行前持有 | 上一动作执行后留下的持有列表 |
+| 执行中持有 | 执行前 + 当前动作新占用的 buffer（dst 写入 + src 正在被读尚未释放）。P 压力最大时刻 |
+| 执行后持有 | 执行中 − 当前动作后无未来消费者的 buffer |
+
+前一动作的执行后 = 下一动作的执行前。第一步执行前为 `[]`。
+
+示例（三元输入，搬入→乘→乘→搬出；操作动词为 AscendC 示例，其他语言按适配层映射）：
+
+```pseudocode
+// S1: in0 → square（第一步，执行前为空）
+// 执行前: 持有=[]
+// 执行中: 持有=[UB0]                   ← 搬入单元正在写 UB0
+// 执行后: 持有=[UB0]                   ← in0 后面 S2 还会读, 有未来消费者, 保留
+CopyOneInput(coord, IN0, UB0);
+// 执行前: 持有=[UB0]
+// 执行中: 持有=[UB0, UB2]              ← 计算单元读 UB0, 写 UB2
+// 执行后: 持有=[UB0, UB2]              ← in0 后续 S2 会读, square 后续 S4 会读, 都有未来消费者
+Mul(UB2, UB0, UB0, count);
+
+// S2: in0·mul1_x → mul_1
+// 执行前: 持有=[UB0, UB2]
+// 执行中: 持有=[UB0, UB1, UB2, UB3]    ← 计算单元读 UB0,UB1, 写 UB3
+// 执行后: 持有=[UB2, UB3]              ← UB0(in0)和UB1(mul1_x)无未来消费者, 消失; square/mul_1 有, 保留
+Mul(UB3, UB0, UB1, count);
+
+// 搬出: 读 UB，对 UB 是最后一次读
+// 执行前: 持有=[UB2, UB3, UB4]
+// 执行中: 持有=[UB2, UB3, UB4]         ← 搬出单元正在读 UB4
+// 执行后: 持有=[UB2, UB3]              ← UB4 被搬出读后无未来消费者, 消失
+CopyOutOne(coord, OUT0, UB4);
+```
+
+**验证**：任意执行中持有数 ≤ P；执行后持有与释放时机一致。
+
+## 3 精度转换（Cast）对 P 的影响
+
+- `CONVERT_INPLACE`=false 的语言（AscendC 即是）：转换 src 和 dst 是两块独立片上 buffer，不能原地（源/目的字节宽不同，硬件不支持重叠读写）→ 需要额外**转换中转 buffer**
+- 并发放宽：若基线 P ≤ 6，可扩大 P（**最多 +2**），为转换分配更多 buffer，减少多输入争抢同一中转；按需取，用不到 2 时不强拉到上限
+- 转换前后的计算精度统一为 `COMPUTE_PRECISION`（见 [splitting.md](splitting.md) §2.4）
+
+## 4 寄存器链融合降节点三场景
+
+`CAP_REG_CHAIN_FUSION`=true 时：
+
+1. **常量/标量在寄存器构造**：标量不占片上 buffer
+2. **链式中间值留在寄存器**：连续计算，中间结果全程在寄存器链上
+3. **寄存器内 broadcast/replicate**：从片上取一个元素到寄存器，寄存器内复制，省掉广播源在片上的独立驻留
+
+不改变的情况：单次二元操作 src 本就在片上，仍需 片上→寄存器→计算→寄存器→片上，片上需求不变。
+
+## 5 融合决策方法论
+
+计算流以 element-wise + broadcast 为核心。以二元算子 `out = f(x, y)` 为例，融合后的 DAG 流图：
+
+```
+[段 1: 搬入（随路广播）]
+  搬入 x → 片上 B0（B 轴 stride=0）
+  搬入 y → 片上 B1（B 轴 stride=0）
+
+[段 2: 计算（寄存器链）]
+  取 x: B0 → 寄存器
+  取 y: B1 → 寄存器
+  融合计算 → B2
+
+[段 3: 搬出]
+  搬出 B2 → GM
+```
+
+**关键**：随路广播在搬入阶段直接完成，不另占片上 buffer；寄存器链将中间结果留在寄存器传递，不落片上，进一步降低 P。
+
+### 5.1 融合穷举判据
+
+列出计算图中**所有**连续计算操作对，逐对判据。禁止只检查"看起来像"的那一对。方法：从计算图第一条计算操作开始，相邻两两配对，每一对都走三条硬规则判据：
+
+1. **链长 ≤ `FUSION_CHAIN_MAX_LEN`**——超过上限必须拆为多次融合调用
+2. **精度转换不参与融合**——`CONVERT_BREAKS_CHAIN`=true 时，转换前后必须断链
+3. **对应融合指令必须存在**——操作在该语言的计算指令集合（含 `CAP_FUSED_ARITH` 融合指令）中能找到
+
+**多消费者不打断链**。即使某个中间结果被融合链外的其他步骤引用，链仍可继续——链内部把这个值写回片上即可，寄存器链路不受影响。代价是多写一次片上会多占一个 P slot，需要纳入物理 trace 做峰值验证。
+
+**连续可融对合并为单条融合链**：从第一条计算 op 开始，只要指令存在、非精度转换、累积未超链长上限，链就延续。不因分叉而断链。
+
+### 5.2 融合 vs 拆分取舍
+
+多消费者融合虽然合法，但会增加 P 压力：融合需要同时持有所有输入 buffer + 所有输出 buffer（包括为外部消费者多写的）。如果合并后峰值超过目标 P，则需要**主动拆分**融合来降压。
+
+判据流程：
+1. 先推满最长链（≤ `FUSION_CHAIN_MAX_LEN`）
+2. 做物理 trace，检查峰值是否 ≤ 目标 P
+3. 若超 P → 在分叉输出最多的位置拆分融合，释放部分 buffer 后再续链
+4. 重复直到峰值 ≤ P
+
+**融合改变存活节点大小**：融合前每个中间结果各占 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
+```
+
+**存活节点扩大限制**：融合后的物理存活节点数不得超过融合前的 P + 3。超过 → 只部分融合，或调整调度先释放不再需要的 buffer。
+
+## 6 额外 buffer 要求
+
+- 精度转换场景：`CONVERT_INPLACE`=false 时须额外分配一个转换中转 buffer（src/dst 不可原地）
+- 多输出算子：若 >1 个输出，每个输出需独立搬出调用，输出 buffer 在搬出前不可被覆写
+- Buffer 复用：同一物理 buffer 可多次复用，只要持有数 ≤ P 约束。代码中 buffer 角色变更须标注 `// UBx 释放` / `// UBx 重新分配为{新角色}`
+
+## 7 单缓冲策略（范式级决策）
+
+- **本范式 standard 路径固定单缓冲**：搬入与计算串行，由显式同步保序（见 [sync-model.md](sync-model.md)）
+- 单缓冲是精控 buffer 复用的核心优势——每个 buffer 就是片上一块固定大小的空间，先做搬入、再做中间结果、最后做搬出，动态复用；buffer 数 = P，每块 perBufBytes 最大化 tile 大小
+- 队列式管理（`BUFFER_MODEL`=队列）自带双缓冲，P 个队列会变成 2P 个 buffer，perBufBytes 减半、每轮处理数据量砍半——因此本范式不采用
+- 单缓冲无自动同步：所有跨单元同步手动插入（约束落地见各适配层）
+
+## 8 buffer 划分产出
+
+| 类别 | dtype | 双缓冲 | 份数 | 用途 |
+|------|-------|----|------|------|
+| buf_[0..P-1] | 计算精度 | 关 | P × 1 | P 个 buffer 槽位，按 perBufBytes 均分片上容量 |
+
+**perBufBytes** = `(片上容量 / P)` 按 `ALIGN_GRANULARITY` 向下对齐；**perBufElems** 按统一计算精度字节宽算（见 [splitting.md](splitting.md) §2.4）。
+
+## 9 产出校验 golden
+
+**对范式开发者的要求**：
+1. 给一个复杂输入的算子样例，以实际划分结果作为 golden，需要"人"保证正确性
+2. golden 如果有多个，需要全部列出
+3. 删除 golden，agent 读取本文档可以产出同样的 buffer 划分；产出不了则不断改进范式质量，直到成功
+4. 样例随本文档上库
+
+**golden 样例（Adam: 5 输入 3 输出, fp32, P=5）**：
+
+Adam 计算流：`square=IN0*IN0 → mul_1=square*MUL1 → mul_0=MUL*IN2+mul_1(融合乘加) → mul_3=square*mul_0*MUL3 → mul_4=mul_3*IN1(融合乘加) → sqrt=sqrt(mul_4) → add_2=sqrt+ADD2 → truediv=1/add_2 → mul_4=truediv*IN4 → output2=IN3-mul_4`
+
+P trace 峰值出现在 S7b(Add) 和 S9b(Mul) / S10b(Sub)，持有=[UB0, UB1, UB2, UB3, UB4]，**P=5**。
+
+| 类别 | dtype | 双缓冲 | 份数 | 用途 |
+|------|-------|----|------|------|
+| buf_[0..4] | 计算精度 | 关 | 5 × 1 | 5 个 buffer 槽位，动态复用（搬入/中间结果/搬出角色轮转） |
+| perBufBytes | — | — | — | (262144 / 5) & ~31 = 52416 bytes（32B 对齐粒度下） |
+| perBufElems | — | — | — | 52416 / 4 = 13104（按 4 字节计算精度算） |
+
+完整计算流伪码见 [compute-flow.md](compute-flow.md) §6.2。

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

@@ -0,0 +1,68 @@
+# Broadcast 范式场景模型
+
+> **层级**：通用知识层（generic/），语言中立。
+>
+> 来源：adapters/ascendc/overview.md §1/§2/§6（原 broadcast-template-overview.md）、原 patterns.md 范式总览。
+
+## 1 准入条件
+
+本范式覆盖的算子需同时满足：
+
+1. **element-wise 计算语义**——输出元素由输入元素的逐点函数计算得到
+2. **多输入间存在 broadcast**——输入 shape 不一致，需广播对齐后计算
+3. **计算公式不含 Reduce**——无跨元素归约（归约类见 Reduction 范式）
+
+典型场景：输入输出 shape 不一致需广播对齐的 element-wise 算子。
+
+## 2 坐标系理论
+
+所有输入/输出统一到同一个**广播上界坐标系**下描述：
+
+| 术语（语言中立） | 含义 |
+|------|------|
+| **effective_shape** | 去 1 补 1 后的归一化 shape，所有输入/输出的统一坐标系 |
+| **maximumBroShape** | broadcast 上界 shape，作为片上内存切分与多核切分的坐标系 |
+| **B 轴（广播轴）** | 某张量在该维大小为 1 而坐标系大小 >1 的轴；偏移计算中该轴 **stride=0**，实现随路广播 |
+| **A 轴（非广播轴）** | 两端等长的轴 |
+| **RANK** | effective_shape 的维度数，编译期特化的唯一参数 |
+| **split 轴（ubSplitIdx）** | 片上内存单切分轴，将 effective_shape 分为内轴与外轴 |
+| **perBufElems / perBufBytes** | 单个片上 buffer 可容纳的元素数 / 字节数 = 片上容量 / P |
+| **L（逻辑存活节点）** | 计算图 tensor 层面的峰值同时驻留数 |
+| **P（物理存活节点）** | 片上 buffer 层面的峰值同时驻留数，决定 buffer 槽位数 |
+
+广播语义通过 **stride=0** 表达：坐标到偏移的映射 `offset = Σ coord[d] × stride[d]` 中，B 轴 stride 为 0，则该轴坐标变化不产生偏移——源数据只读一份，目标形态按坐标系展开。
+
+## 3 数据流骨架
+
+本范式 standard 路径的数据流为三段式，多输入并行搬入、多输出独立搬出：
+
+```
+[段 1: 搬入（随路广播）]   每个输入: GM → 片上 buffer，B 轴 stride=0 随路展开
+[段 2: 计算]             逐元素计算；若 CAP_REG_CHAIN_FUSION=true，链式中间值留在寄存器
+[段 3: 搬出]             每个输出: 片上 buffer → GM，独立搬出
+```
+
+- 随路广播依赖谓词 `CAP_BROADCAST_IN_TRANSFER`：广播在搬入阶段完成，不占额外 buffer，不产生独立的广播步骤
+- buffer 采用**单缓冲按 P 均分**策略：buffer 数 = P，每块 `perBufBytes = floor(片上容量/P)` 按 `ALIGN_GRANULARITY` 对齐；角色在搬入 / 中间结果 / 搬出之间轮转复用（详见 [liveness-fusion.md](liveness-fusion.md)）
+
+## 4 编译期特化
+
+- 特化维度只有 **RANK**，与数据类型无关；dtype 由框架按主输入类型注入，不在特化键中编码
+- RANK 分两档：常态档（低维）与保底档（高维），实际 rank 落入低档即选低档
+- 特化的落地机制（模板参数、分发宏等）由语言适配层定义
+
+## 5 能力边界
+
+1. **广播仅发生在搬入阶段**（GM → 片上）。若数据已在片上（中间计算结果）且需要广播形态，不在本范式 standard 路径内——此时需按算子整体数据流重新归入范式（AscendC 下的替代路线见 `paradigms/common/broadcast-rules.md` 路线 2）
+2. 本范式不做片上内存切分与多核切分之外的调度优化（切分微调预留扩展点，见 [splitting.md](splitting.md) §5）
+3. 广播不改变计算语义：所有精度、舍入行为与 element-wise 基础范式一致
+
+## 6 依赖谓词
+
+| 谓词 | 用途 |
+|------|------|
+| `CAP_BROADCAST_IN_TRANSFER` | 数据流路线成立的前提（§3 段 1） |
+| `CAP_REG_CHAIN_FUSION` | 段 2 融合策略与 P 值压缩的前提 |
+| `ALIGN_GRANULARITY` | buffer 预算对齐 |
+
+谓词定义见 [capability-contract.md](capability-contract.md)；各语言真值见对应适配层 capability-mapping。