cann-workbench 0.0.0-stage → 0.0.2-alpha

package/skills/asc-tools/tool-precision-debug/skills/tool-precision-debug/references/diagnosis/sensitive-points.md

@@ -0,0 +1,146 @@
+# 计算链敏感点
+
+根据已理解的实际计算链选择下面相关的敏感点；计算关系仍不清楚时回到[算子建模方法](operator-modeling.md)。需要算子或子计算的专属经验时，再到页末目录选择对应内容，不要求每次逐项重读。
+
+这里的敏感点是可能改变数值、参与元素、分支或数据可见性的节点及连接。把链上位置、触发条件和可能的偏差标在图旁，注明已确认的信息与缺口；没有相关结构的条目跳过。此阶段以源码和已有资料核对为主，标记不等于确认错误，也不要求每个敏感点都立即插桩或运行实验。阶段 3 再按异常现象和区分力选择验证对象。
+
+## 目录
+
+- [通用敏感点](#通用敏感点)
+  - [运算顺序与中间数值范围](#1-运算顺序与中间数值范围)
+  - [dtype、Cast、量化与精度模式](#2-dtypecast量化与精度模式)
+  - [归约、统计量与误差放大](#3-归约统计量与误差放大)
+  - [分支、函数输入域与特殊值](#4-分支函数输入域与特殊值)
+  - [布局、索引、搬运与有效区](#5-布局索引搬运与有效区)
+  - [shape、分块、mask 与尾部](#6-shape分块mask-与尾部)
+  - [Buffer 生命周期、同步与所有权](#7-buffer-生命周期同步与所有权)
+  - [参数角色、实现分派与最终输出](#8-参数角色实现分派与最终输出)
+- [算子专属敏感点目录](#算子专属敏感点目录)
+- [标记保存位置](#标记保存位置)
+- [标记完成后](#标记完成后)
+- [产出示例](#产出示例)
+
+## 通用敏感点
+
+### 1. 运算顺序与中间数值范围
+
+在连续乘除、乘加、Exp 后乘大系数、相近数相减等位置，写出实际逐步计算，而不只写化简后的公式。分别核对 reference 和 Kernel 的中间 dtype、已确认的舍入点、是否融合及结果范围；输入和最终数学值都有限，仍可能发生中间溢出、下溢或有效数字丢失。
+
+例如 `a*(b/c)` 与 `(a*b)/c`：前者可能先除成零，后者可能先乘成 Inf。将敏感点标在首次可能分叉的 Div 或 Mul，而不是只标最终输出。按目标 dtype 构造能区分两条链的少量输入，必要时调用任务实际使用的 reference 确认；具体模型见[乘除重结合](../patterns/mechanisms/algorithm-parameter-contract.md#乘除重结合的有限精度分叉)。
+
+“数值更稳定”不自动等于符合当前要求。若任务要求匹配指定框架的浮点行为，reference 的 Inf 而 Kernel 为有限数也可能失败；若任务允许按高精度 reference 和容差验收，则以该判据为准，不强求内部操作完全一致。参考求值方式尚未确认时保留疑点，不凭算子名称或数学恒等式决定顺序。
+
+### 2. dtype、Cast、量化与精度模式
+
+在每次转换、混合精度计算、累加与输出编码处标出输入、中间和输出 dtype。检查先缩窄再扩大是否已经丢失信息，整数转浮点是否发生碰撞，scale/offset、舍入和饱和作用在哪一步；仅看最终 dtype 不足以判断这些变化。
+
+把半整数附近、相邻可表示值、整数精确范围边界和过早降精度标到对应节点，按当前输入域选择有区分力的对照。API 的近似模式、Fallback 或 dtype 改变可能同时改变实现路径，要核对实际采用的重载与分派。深入检查见[Cast 与舍入](../patterns/mechanisms/cast-rounding.md)及[精度模式与近似路径](../patterns/mechanisms/precision-mode-approximation.md)。
+
+### 3. 归约、统计量与误差放大
+
+在 Reduce、partial 合并、点积和统计量处，先标明参与元素、有效数量、累加 dtype、分块与合并顺序。漏项、重复、padding 参与计算和未初始化累加值，都可能看起来像普通精度误差。
+
+再标记大动态范围、正负抵消、相近大数相减及后续倒数、归一化等放大位置。参考使用不同归约树或主尾分派时，抽出一段数据重新求和未必对应原节点；FP32 也不能保证任意结合顺序相同。检查方法见[累加与归约顺序](../patterns/mechanisms/accumulation-order.md)，复合计算的完整贡献关系见[计算边界](../patterns/mechanisms/complex-operator-boundary.md)。
+
+### 4. 分支、函数输入域与特殊值
+
+在 Select、分段阈值、clamp、epsilon、Log、Sqrt、Exp、除法和倒数处，分别记录函数实际输入与分支判据读取的值。确认比较符号、保护位置、dtype，以及判据应读取原始输入还是变换后的量；稳定计算量不能无依据地覆盖原始语义量。
+
+边界点输出不同，也可能来自同一选中分支内部的算术差异。区分这两类解释时，按源码或有效观察核对判据值、比较结果和选中分支，再对照该分支的计算；仅凭边界输出失配，不能单独归因于分支条件。
+
+按合法输入域检查阈值两侧、零分母、极值、NaN/Inf、符号零或次正规数。先比较 reference 与 actual 的数值类别，再解释有限值误差；特殊值也可能是规定的正常输出。不要用统一加 epsilon、clamp 或清零掩盖来源不明的差异。详见[特殊值机制](../patterns/mechanisms/special-values.md)和[Clamp 与分支判据](../patterns/mechanisms/algorithm-parameter-contract.md#clamp-与分支判据的数据流分叉)。
+
+### 5. 布局、索引、搬运与有效区
+
+在 CopyIn/CopyOut、reshape、transpose、broadcast、gather/scatter 或格式转换边上，核对逻辑坐标、元素 offset、字节地址、stride、物理容量与有效范围。区分值算错和正确的值被放到错误位置，留意 padding 被读入、广播角色错误和最终写回范围不一致。
+
+将首尾行、相邻合法位置、布局转换前后和广播维度标在链上。可用可区分的坐标编码或合法 padding 哨兵检查映射，但不越过已分配区域。方法见[索引与地址归属](../patterns/mechanisms/index-address-ownership.md)及[搬运、对齐与有效区](../patterns/mechanisms/data-movement-alignment.md)。
+
+### 6. shape、分块、mask 与尾部
+
+在 Host 切分、tile/repeat 循环、mask 设置和尾块处理处，核对实际长度、迭代次数、掩码的消费方式、计数与地址推进。首块正确不代表后续块正确；逻辑长度相同也不代表使用相同路径。
+
+按已确认的分块边界标记边界前、边界上、边界后的输入，以及合法的空输入、维度 1、rank-0 或零工作量路径。检查最后一块是否漏算、重复写回、沿用旧 mask 或旧状态。不能把这些形状一概当作合法输入，范围由任务规定。详见[Shape 边界](../patterns/mechanisms/shape-boundary-contract.md)和[Tiling 与跨 tile 状态](../patterns/mechanisms/tiling-tail-state.md)。
+
+### 7. Buffer 生命周期、同步与所有权
+
+在生产者到消费者、队列交接、缓冲复用、跨核合并和异步写回边上，标记谁写、谁读、何时写完、何时允许复用。变量不同不证明存储独立，源码先后顺序也不证明不同流水上的数据已经可见。
+
+核对真实地址重叠、每轮初始化、同步参与者、事件轮次和输出区域的唯一写者。多核或多轮才出现的错误，应回到具体依赖边，而不是直接给整条链加同步。详见[Buffer 生命周期](../patterns/mechanisms/buffer-lifetime-alias.md)、[流水同步](../patterns/mechanisms/pipeline-sync-visibility.md)及[多核所有权](../patterns/mechanisms/multicore-ownership.md)。
+
+### 8. 参数角色、实现分派与最终输出
+
+在 Host 参数传递、VF/API 调用、属性缓存、实现分派及输出写回处，核对实参的逻辑角色、位置、dtype、地址和最后写者。相同类型的参数可以传反；变量名或 Kernel 已写某个缓冲，也不能证明 CopyOut 取的是目标结果。
+
+将 beta/threshold/scale 等影响分支或数据映射的属性、shape/dtype 选择的不同实现、可选输入及多输出分别标到链上。已有测试没有覆盖但当前可达的路径，保留为待验证点；某一路通过不能外推全部实现。查[公式与参数槽位](../patterns/mechanisms/algorithm-parameter-contract.md)和[Golden、Host 属性与构建采用](../patterns/mechanisms/golden-host-contract.md)。
+
+## 算子专属敏感点目录
+
+需要专属经验时，对照下表查当前算子及其子计算，无需先通读全部通用条目。匹配时进入对应页，把相关敏感点补到同一条链上；融合算子可匹配多个算子族，不要求顶层名字完全相同。没有匹配项时，保留已有检查结果，按实际公式继续分析。
+
+| 当前算子或子计算 | 对应资料与补充重点 |
+| --- | --- |
+| Reduce、带索引归约 | [归约算子族](../patterns/operators/reduction.md)：参与集合、索引布局、partial 与跨核合并 |
+| AdaptiveAvgPool、自适应平均池化 | [小窗口对照](../patterns/operators/reduction.md#自适应平均池化的小窗口对照)：H/W 边界、非整除窗口、count 与累加 dtype |
+| Broadcast、Transpose、布局重排 | [广播与转置](../patterns/operators/broadcast-transpose.md)：逻辑映射、物理行距、小通道与有效输出 |
+| Sort、Merge、TopK | [排序与归并](../patterns/operators/sort-merge.md)：value/index 配对、并列规则、消耗计数与偏移单位 |
+| Matmul、MMAD、分组矩阵乘 | [Matmul/MMAD](../patterns/operators/matmul-mmad.md)：分块、scale 装载、累加、异步写回及后处理 |
+| RMSNorm、LayerNorm、GroupNorm | [Normalization](../patterns/operators/normalization.md)：统计量、方差公式、epsilon、分母及仿射输出 |
+| Convolution | [卷积](../patterns/operators/convolution.md)：padding、窗口展开、group/dilation、K 参与集合及后处理 |
+| DynamicQuant、DynamicQuantV2 | [动态量化](../patterns/operators/dynamic-quant.md)：统计范围、scale/offset 角色、舍入/饱和与多输出 |
+| SoftplusV2Grad、SoftplusBackward | [Softplus 梯度](../patterns/operators/softplus-v2-grad.md#按残余症状进入案例)：角色、repeat/mask、乘除顺序、小量归零与属性复用 |
+
+## 标记保存位置
+
+在阶段 2 将相关计算链、敏感点和证据缺口写入报告第 3 节“相关计算链与数值约定”；报告位置与仅在对话交付的处理遵循[报告指引](reporting.md#任务产物目录)。
+
+计算链可以直接画在报告中，敏感点用图旁注释或小表说明链上位置、触发条件、可能的偏差以及已确认或待核实的信息。图较大时可单独放在产物目录内，由报告使用相对链接引用；不为每个敏感点另建文件。后续取得新证据时更新同一份报告，保留关键判断变化。
+
+## 标记完成后
+
+检查标记是否落到了实际节点或数据边，能否说明在什么条件下产生什么偏差。阶段 3 优先验证与当前异常相符、且有低成本区分方法的候选；资料尚不能确认的点保留未知。敏感点不等于已确认的错误，通用与算子页都检查过也不代表它们已被排除。
+
+## 产出示例
+
+下面以 FP32 Softplus 梯度的求值顺序诊断为例，展示可写入报告第 3 节的内容。为突出标记方式，图中简写了内部缓冲和极负输入支路；实际任务按自身源码展开。S1–S5 只是本例的图内编号，不是固定格式。
+
+### 3. 相关计算链与数值约定
+
+**分析范围**：FP32 普通分支。Kernel 采用先除后乘，项目 reference 为 PyTorch 2.7.1 CPU 的 `aten.softplus_backward`。极负支路和掩码跨 repeat 行为继续保留检查项。
+
+```text
+grad、self（FP32）
+    │
+    ▼
+CopyIn [S1：有效元素与数据就绪]
+    │
+    ▼
+bx = beta * self
+    ├──► mask = bx > threshold [S2：判据读取原始 bx]
+    │
+    └──► 按源码选择普通或极负输入支路
+             ├── 普通：Mins(bx, threshold) → Exp → Div → Mul [S3]
+             └── 极负：缩放计算链 [S4：次正规数与零的分叉]
+                          │
+                          ▼
+                合并为待选择的 value
+                          │
+grad、mask ───────────────┤
+                          ▼
+              Select(mask, grad, value) [S5：mask 消费与结果来源]
+                          │
+                          ▼
+                    CopyOut [S1]
+```
+
+| 标记 | 链上位置与触发条件 | 可能的偏差 | 当前依据与缺口 |
+| --- | --- | --- | --- |
+| S1 | CopyIn/CopyOut，关注有效长度、尾部和生产者完成时点 | 漏搬、错位、读到未完成数据或写回范围错误 | 检查实际地址、长度和依赖；本节未据此认定存在搬运错误 |
+| S2 | `bx > threshold`，关注阈值两侧及计算前的 clamp/Cast | 变换后的量代替原始 bx，导致选错分支 | 保留原始 bx 到谓词的依赖，确认实际比较符号；边界覆盖仍需核对 |
+| S3 | 普通支路的 Div/Mul，大幅有限 grad 与正 bx | 先乘发生溢出，先除保持有限，输出类别与 reference 不同 | 已有同版本 CPU 对照支持顺序分叉；仍须结合 Kernel 实际路径和原输入验证 |
+| S4 | 极负支路的 Exp、缩放和后续放大 | 中间次正规数被舍入或清零，偏差被大 grad 放大 | 需要核对实际 API 模式、逐步范围和分支边界，不把所有小值差异归为 FTZ |
+| S5 | Select 到 CopyOut，关注多 repeat 与最终写者 | mask 重复消费、误选支路或搬出旧缓冲 | 从实际重载和数据流检查，单个 repeat 正确不足以排除 |
+
+**S3 的已有对照**：在上述 CPU reference 环境中，`grad=3.2e38、self=2、beta=1、threshold=20` 得到 `+Inf`；CPU 上先除后乘得到约 `2.82e38`。这支持求值顺序是敏感点，不代表更改候选后的 NPU 修复已经通过。
+
+**阶段 3 的下一步**：先验证与当前 Inf/有限失配直接相关的 S3，将 Kernel 实际普通分支与 reference 对齐比较。S1、S2、S4、S5 保留为相关检查项，按源码和后续残差决定验证顺序，不把它们一并写成已确认根因。

package/skills/asc-tools/tool-precision-debug/skills/tool-precision-debug/references/patterns/cases/fp16-promotion-boundary.md

@@ -0,0 +1,46 @@
+---
+type: Case
+title: FP16 升精度：在首次信息损失前改变位置
+description: CANN 9.0.0、Ascend910B1 的固定输入实验，区分首次信息损失前后改变 FP16 升精度位置的结果。
+tags: [FP16, 中间精度, Cast, 位模式]
+---
+
+# FP16 升精度：在首次信息损失前改变位置
+
+资料范围：CANN 9.0.0；产品 Ascend910B1；NPU Arch 2201；调用或执行路径 kernel-direct。下述结果仅覆盖列出的输入与执行方式。
+
+这是一个用固定输入说明数值机制的小实验。当最终输出已经是 FP32、但小增量仍消失，或仅在大基数附近出现阶梯状残差时，先画出每个操作数、算术结果和输出的 dtype。这里要验证的是提升发生在首次舍入或信息损失之前，而不是笼统地把最终输出改宽。
+
+## 示例结果
+
+以下固定输入的加法/Cast 对照在 CANN 9.0.0、Ascend910B1/DAV2201、kernel-direct、单 block、256 lane 下执行。
+
+probe 比较两条加法链：`FP16 Add → Cast FP32`，以及两个 FP16 操作数先 Cast FP32 再 Add。对 `1024 + 0.0625`，前者输出 binary32 `0x44800000`（1024），后者为 `0x44800200`（1024.0625）；`-1024 + -0.0625` 也发生对应分叉。`1024+1` 和 `-1024+1` 两个精确 control 在两条链中一致。该探针的 256 lane 位模式均无失配、触发组不同、control 相同且无 GM 哨兵残留。
+
+这只观察了加法与 Cast 的上述固定组合。它没有运行减法、相消链、其它算术 callable、其它版本、SoC、长度、tiling、融合或 API 重载。
+
+## 区分实验
+
+为当前失败链添加三个 checkpoint：各操作数进入算术前、第一次算术后、最终输出前。保持同一输入与实际调用，只改变一个位置。
+
+| 触发/对照 | 早期窄化链预测 | 算术前升至宽 dtype 的预测 | 用途 |
+| --- | --- | --- | --- |
+| `1024 + 0.0625` | 1024 | 1024.0625 | 检查小增量是否在 Add 边界已丢失 |
+| `1024 + 1` | 1025 | 1025 | 精确 control |
+| 业务基数两侧的正负小增量 | 由当前 dtype/位模式计算 | 由当前 dtype/位模式计算 | 排除只适合单个常量的结论 |
+
+若宽化只发生在第一次 FP16 算术之后，触发输出仍像早期舍入链，说明信息已经丢失；若两个操作数在算术前提升后原先发生分叉的算术后 checkpoint 按预测改变，而 control 保持相同，才支持过早信息损失候选。实际代码中的隐式 Cast、融合、输入量化或不同 API 路径都可能另有舍入点，必须一并记录。
+
+若需要研究 `(1024+0.0625)-1024` 一类相消链，应针对当前任务建立局部算术模型，并按需用独立 NPU 探针核对；上面的 NPU 观察不包含减法，不能用它替代该结论。
+
+## 局部干预与修复代价
+
+只提升首次易丢失的操作数和算术边，保持最终 Cast、有效集合、tile 和其他算术不动。预测、否证条件和预期位模式都应在改动前写下。若原先发生分叉的算术后 checkpoint 未按预测改变，检查构建产物、真实 overload 和上游量化；不要继续把宽 dtype 向下游扩散。
+
+更宽的中间表示会增加局部存储、带宽、可用重载限制和可能的调度差异，也可能改变特殊值及任务要求的逐步舍入语义。因此修复后除了原触发/control，还要覆盖实际完整/tail、正负增量、边界邻点和当前约定涉及的特殊值。
+
+## 回归与结论边界
+
+若当前 oracle 规定 FP16 Add 后才转为 FP32，`1024` 就是该约定下的正确结果，不能因为 `1024.0625` 更接近实数和而擅改计算链。验收记录应包含输入位模式、每个 checkpoint 的 dtype/位模式、实际调用、产物身份与最终输出。只有“首次舍入或信息损失前提升有效、已丢失后提升无效”的对照同时成立，才把根因收敛到该边。
+
+通用 Cast、舍入和存储覆盖分流见 [Cast、舍入与中间精度](../mechanisms/cast-rounding.md)。

package/skills/asc-tools/tool-precision-debug/skills/tool-precision-debug/references/patterns/cases/fused-rmsnorm-gelu-residual.md

@@ -0,0 +1,162 @@
+---
+type: Case
+title: FusedRmsNormGeluResidual：用退化恒等式拆融合流水
+description: 历史排查示例，用退化恒等式和参数哨兵拆解融合流水，区分角色绑定、缓冲生命周期与跨 tile 状态。
+tags: [RMSNorm, GELU, 融合算子, Buffer]
+---
+
+# FusedRmsNormGeluResidual：用退化恒等式拆融合流水
+
+历史排查示例：CANN 9.0.0 / Ascend910B1 / DAV2201 / kernel-direct。共享 FP16 临时区覆盖仍是待验证支路，不能直接当作当前问题的根因。
+
+用退化恒等式与参数哨兵拆开融合流水，分别检查角色绑定、共享临时缓冲的生命周期和跨 tile 状态。每条支路都需要当前输入下的区分实验。
+
+## 什么时候使用
+
+多输入融合算子同时包含归一化、激活、门控、仿射和 residual 时，最终全域失配通常不足以指向某一级。出现以下指纹时优先使用本页：
+
+- 修改 gamma、scale 等参数，输出几乎不变，修改另一个参数却异常主导结果；
+- CPU/NumPy 逐级计算正确，但真实 Kernel 从某个 LocalTensor 或流水阶段开始分叉；
+- 参数已 preload，消费端却可能读取同类型 scratch；
+- 多个参数经过同一个临时缓冲转换，最终值像“最后一次加载的参数”；
+- 修正一个明显绑定后几乎没有改善，怀疑第二个缺陷仍在遮蔽结果。
+
+目标不是一次猜中根因，而是把融合链拆成能单独证伪的参数敏感性、角色绑定和生命周期实验。
+
+## 先冻结阶段约定
+
+把当前实现拆成有明确输入/输出的阶段，例如：
+
+    x
+     → LayerNorm
+     → RMSNorm(gamma)
+     → GELU
+     → Gate(beta, gate)
+     → Affine(scale, bias)
+     → ResidualAdd(residual)
+     → y
+
+阶段名称和顺序必须以当前 oracle 为准。为每一级记录逻辑角色、dtype、shape、物理槽位、producer、consumer 和 CopyOut 点。不要因为最终输出是 FP16，就忽略 FP32 中间量的第一次分叉。
+
+先确认实际 shape 是否只有一个 tile/row。只有在多 tile 或同核多 row 时才会执行的状态分支，不应在单 tile 复现中被列为首要根因。
+
+## 第一步：用退化恒等式定位阶段
+
+为参数选择能让某些阶段失效或退化的值，并在改代码前写出预期输出：
+
+| 探针 | 预期用途 |
+|---|---|
+| gate = 0 或 scale = 0 | 让融合激活贡献消失，结果应退化为 residual + bias |
+| gamma = 0 或能使归一化输出退化的参数 | 隔离归一化到激活链与末端仿射/residual |
+| 常量 x | 让归一化结果更容易手算，暴露均值/方差与参数读取问题 |
+| residual = 0 | 单独观察融合主链和 bias |
+| bias = 0 | 区分 bias 读取错误与 residual 错位 |
+| 每个参数使用不同哨兵模式 | 识别消费端实际读到了哪个参数或 scratch |
+
+退化结果不满足时，从最后一级向前检查；满足时，说明被消去的前级暂时不是该探针下的首个分叉。每个探针只回答一个问题，不把“看起来更接近”当作通过。
+
+## 第二步：建立参数敏感性矩阵
+
+保持其他输入不变，分别只扰动 gamma、beta、gate、scale、bias 和 residual，记录：
+
+- oracle 哪些输出元素应改变、方向和量级；
+- actual 哪些元素实际改变；
+- actual 是否更像另一个参数被扰动；
+- 哪个中间 checkpoint 首次失去敏感性。
+
+若 gamma、beta、scale 等多个参数的中间值都等于最后加载的 bias，优先进入共享临时缓冲生命周期支路；若 preload 目标正确但消费端对某参数完全不敏感，优先进入角色绑定支路。
+
+## 支路 A：逻辑角色绑定到错误物理槽位
+
+建立下表并从 producer 追到 consumer，不依赖相似变量名：
+
+| 逻辑参数 | GM 来源 | preload 最终槽位 | 消费端 LocalTensor | 消费阶段 | 最后写者 |
+|---|---|---|---|---|---|
+| gamma |  |  |  |  |  |
+| beta |  |  |  |  |  |
+| scale |  |  |  |  |  |
+| bias |  |  |  |  |  |
+| residual |  |  |  |  |  |
+
+常见失效是专用参数槽位已经正确写入，消费阶段却从 residual 或通用 scratch 取得同 dtype、同 shape 的 LocalTensor。编译和地址合法性检查可能都通过。
+
+单变量实验：
+
+1. 只把一个消费角色接回其 producer 最终槽位；
+2. 使用该参数的独立哨兵输入；
+3. 预测只有依赖该参数的阶段和输出会改变；
+4. 若 actual 仍等于旧 scratch 的候选值，检查产物采用或否定该绑定。
+
+不要同时清零所有 buffer、添加全局同步或改核数，否则无法知道是哪条角色边生效。
+
+## 支路 B：共享临时缓冲的生命周期与流水覆盖
+
+当多个参数采用类似流程：
+
+    GM → shared FP16 temp → Cast → dedicated FP32 parameter
+
+仅看到源码顺序或 barrier 名称，不能证明前一次 Cast 消费完毕后，下一次 MTE2 才覆盖 shared temp。画出真实生命周期：
+
+    MTE2 write temp
+      → ownership transfer
+      → V read temp / Cast
+      → V completion
+      → temp 可复用
+
+重点检查：
+
+- 同一个 TBuf 是否被连续用于多个 DataCopyPad/Load；
+- producer/consumer 是否通过正确的 queue 所有权转移；
+- Alloc、Load、EnQue、DeQue、Cast、Free 或等价机制是否包住每一次临时数据生命周期；
+- 局部 barrier 是否只约束某条流水，而没有阻止另一条流水提前覆盖；
+- 每个 FP32 参数槽位的值是否实际都来自最后一次加载。
+
+区分实验可选其一：
+
+- 为每个参数临时使用独立且可辨识的 FP16 槽位；
+- 将一次传输改成明确的 Alloc → Load → EnQue → DeQue → Cast → Free 生命周期；
+- 在最小复现中只保留两个参数加载，交换加载顺序并预测“最后加载者”是否随之改变。
+
+如果交换顺序后被错误复制的参数也随之改变，强力支持覆盖假设；若不变，回到绑定或 producer 数据本身。
+
+## 两个缺陷互相遮蔽时怎么判断
+
+绑定错误与临时缓冲覆盖可以同时存在：
+
+- 只修生命周期，消费端仍从错误 scratch 读取，最终输出可能毫无改善；
+- 只修消费绑定，专用参数槽位本身仍被最后一次加载覆盖，也可能只改善少量样本；
+- 两项一起修复后通过，并不能自动证明每一项的因果性。
+
+因此在正式修复前保存参数 checkpoint，并为两项干预分别预测中间值：
+
+| 干预 | 应先恢复的观察 |
+|---|---|
+| 只修消费绑定 | consumer 改为读取专用槽位，即使槽位内容仍错误 |
+| 只修生命周期 | 各专用参数槽位恢复各自哨兵，即使最终 consumer 仍错 |
+| 两者都修 | 参数槽位、阶段输出和最终输出同时闭合 |
+
+中间 checkpoint 能把“最终误差没下降”的遮蔽关系拆开。
+
+## 先证明候选在当前 shape 上可触发
+
+看到可疑代码不等于它解释当前失败：
+
+- tile > 0、跨 row 残留等分支只有在当前 tiling 真正产生多个 tile/row 时才可作为 active root；
+- 单核运行只排除部分跨核 ownership 问题，不能排除同核多 row 的状态复用；
+- 添加某个 V→S 或全局 barrier 后结果不变，应降低该同步候选优先级；
+- UB 容量估算、编译成功和静态检查无 finding，都不能替代“错误值来自哪个 writer”的证明。
+
+每条候选必须同时满足触发条件、错值预测和单变量干预三项。
+
+## 修复后的回归矩阵
+
+至少覆盖：
+
+- 所有退化恒等式与独立参数哨兵；
+- 每个参数的正负、零、常量、随机和边界取值；
+- 单 row/多 row、单 tile/多 tile、单核/多核和尾块；
+- 各阶段 FP32 checkpoint 与最终 dtype 输出；
+- 原失败输入、随机输入、连续重复运行；
+- 构建产物与运行时加载身份。
+
+结束条件是：首个分叉已定位到具体 producer-consumer 或生命周期边；每项修复有独立可否证证据；组合修复不再依赖掩蔽；原失败和回归矩阵均通过。

package/skills/asc-tools/tool-precision-debug/skills/tool-precision-debug/references/patterns/cases/index.md

@@ -0,0 +1,16 @@
+# 案例与历史调查线索
+
+按当前异常选择一条排查路线。案例中的输入、版本和执行方式各有范围；使用时先匹配当前条件，再用自己的失败输入验证。
+
+| 当前问题 | 参考案例 | 使用提示 |
+| --- | --- | --- |
+| 最终已是 FP32，小增量仍然消失 | [FP16 升精度位置](fp16-promotion-boundary.md) | 固定输入的加法与 Cast 示例；运行环境见正文 |
+| 整数转浮点后发生判重或寻址异常 | [相邻整数碰撞](integer-float-collision.md) | 检查首次丢失整数身份的位置；运行环境见正文 |
+| 尾块、零工作量或跳过分支后读到旧值 | [尾块有效区与旧状态](tail-valid-region-state.md) | 用状态模型区分本轮未写、有效长度和复用问题 |
+| 单块统计正确，合并后失配 | [Partial 统计合并](partial-statistics-merge.md) | 用可手算的分块模型区分漏项、权重和合并公式 |
+| 逐元素通过但 bias 失败，主列与尾列或 NaN/Inf 分叉 | [GRU p2/p3 的 bias 归约](thnn-fused-gru-bias-reduction.md) | 区分参考结合树、尾列分派与修复中新引入的计数漏写；保留历史验证范围 |
+| 事件看似配对，多轮或多输出仍异常 | [同步诊断](sync-dataflow-handshake.md) | 代码分析示例；区分区域绑定、条件通知和缓冲回收 |
+| 融合参数失效或输出像另一个中间量 | [FusedRmsNormGeluResidual](fused-rmsnorm-gelu-residual.md) | 历史排查示例；先查角色绑定，再查临时区和跨 tile 状态 |
+| 梯度输出、极值或 Host 属性出现异常 | [SoftplusV2Grad](softplus-v2-grad-family.md) | 历史排查示例；根据错值选择分支、精度或属性复用路径 |
+
+具体实验方法见[诊断方法](../../diagnosis/index.md)。修复后回放原失败输入，再按改动范围选择回归；症状相似不代表可以直接复制常量或补丁。

package/skills/asc-tools/tool-precision-debug/skills/tool-precision-debug/references/patterns/cases/integer-float-collision.md

@@ -0,0 +1,44 @@
+---
+type: Case
+title: 整数进入浮点链：相邻整数碰撞
+description: CANN 9.0.0、Ascend910B1 的固定输入探针，展示 int32 转 FP32 后相邻整数碰撞及其诊断边界。
+tags: [Cast, 整数表示, FP32, 位模式]
+---
+
+# 整数进入浮点链：相邻整数碰撞
+
+资料范围：CANN 9.0.0；产品 Ascend910B1；NPU Arch 2201；调用或执行路径 kernel-direct。下述结果仅覆盖列出的输入与执行方式。
+
+这是一个用固定输入说明数值机制的小实验。当离散索引、计数、标签或地址在进入浮点中间量后出现重复命中、相等判断异常或仅大数范围错值时，用本案例先验证“整数值是否已在 Cast 边界合并”。它只帮助定位表示丢失，不能替代当前 API 重载、舍入模式、地址单位和业务范围的确认。
+
+## 示例结果
+
+固定输入探针在 CANN 9.0.0、Ascend910B1/DAV2201、kernel-direct、单 block、256 lane 下比较原始整数与转换后的 binary32 位模式。
+
+probe 对 `2^24-1`、`2^24`、`2^24+1`、`2^24+2` 及负数对应项逐 lane 验收 binary32 位模式。该探针的 256 lane 均无失配、无 GM 哨兵残留，并观察到正负相邻碰撞：`2^24` 与 `2^24+1` 都编码为 `0x4b800000`，`-2^24` 与 `-(2^24+1)` 都编码为 `0xcb800000`。它不验证其它 CANN 版本、SoC、长度、tiling、融合、算子实现或 Cast 重载。
+
+## 最小可证伪案例
+
+将原始整数、Cast 后浮点位模式和下游判断结果同时保存；不能只保存转换后的数值。
+
+| 输入对 | 原始整数是否相等 | binary32 后是否相等 | 用途 |
+| --- | --- | --- | --- |
+| `16777216, 16777217` | 否 | 是 | 触发：相邻整数发生碰撞 |
+| `16777215, 16777216` | 否 | 否 | 边界前 control |
+| `16777217, 16777217` | 是 | 是 | 相同原值 control |
+
+若首行在当前真实链路中满足“原始整数不等、Cast 后相等”，而第二行仍保持不同，才提高整数表示丢失候选。若输出约定本就允许 `int32→FP32` 舍入，碰撞本身不是 API 故障；只有当前用途要求逐个整数可区分时，它才是需处理的表示损失。若原始整数已相等、Cast 前地址或比较已分叉，或边界前也失败，转查上游索引、单位、有效区或存储覆盖，不能把现象归为浮点碰撞。
+
+负数和业务实际最小/最大值也要配对。`2^24` 是 binary32 有效精度边界的案例值，不是任意 dtype、量化格式或 API 的通用阈值。
+
+## 局部干预与修复代价
+
+先只让需要逐个整数精确的那条比较、索引或寻址链保留整数表示，保持输入、shape、mask、tile、地址和其它计算路径不变。预测是触发对重新不同，而相同原值 control 仍相等；若结果不变，检查实际产物是否采用以及 Cast 是否真在该边发生。
+
+保留整数链会改变可用的算术、临时存储、接口重载和可能的 buffer 容量。若必须在某一边转换，先按当前版本的精确 Cast 约定核对 dtype、模式、目标区容量和读写生命周期；“同为四字节”或最终再升宽都不能恢复已丢失的低位。
+
+## 回归与结论边界
+
+回归至少覆盖原始失败值、`2^24` 两侧相邻对、正负对、相同原值对，以及当前算子实际会使用的完整/tail 与多 tile 路径。对每组保存整数原值、浮点位模式、第一次分叉 checkpoint 和最终逻辑输出。
+
+Cast 的一般诊断分流见 [Cast、舍入与中间精度](../mechanisms/cast-rounding.md)。

package/skills/asc-tools/tool-precision-debug/skills/tool-precision-debug/references/patterns/cases/partial-statistics-merge.md

@@ -0,0 +1,30 @@
+---
+type: Case
+title: Partial 统计合并：局部正确不等于全局正确
+description: 通过合成数学案例，区分分块统计合并中的漏项、权重与公式错误，保留当前算子验证边界。
+tags: [分块统计, 归约, 合并, 数学模型]
+---
+
+# Partial 统计合并：局部正确不等于全局正确
+
+分块统计、归一化或归约在单块正确、跨 chunk/跨核/尾块才失配时，先把每个 partial 当成有语义的状态，而不是只搬运一个最终均值或局部输出。本页是合成的数学诊断案例；它不规定任何 CANN API、并行树或空输出语义。
+
+## 症状与竞争候选
+
+先冻结可信 oracle 的统计定义、输入/内部/输出 dtype、有效元素集合、分块边界、partial 的存储位置和最终合并顺序。本例选择 Welford 状态 `(count, mean, M2)`；其它合法统计可使用 sum/sumsq 或不同状态字段，必须由当前算子约定给出。单块通过而合并后错，可能是遗漏 partial、把不同长度 partial 等权平均、遗漏跨组偏差项、把空块当作 count 大于零的普通数据，或是同一有效集合在不同树形/合并顺序下的舍入差异。
+
+不要把“结果随 chunk 数改变”直接叫低精度。先确认所有 partial 的有效元素集合及 count 是否正确；集合不同是有效区/地址问题，集合相同而 dtype 或顺序不同才进入累加顺序候选。
+
+## 一个可区分的合并实验
+
+将输入切为两个不等长块，并对每块独立计算状态、直接全量计算状态和当前实现的合并状态。对非空的 A、B，正确合并必须把 count 相加，并按 count 加权均值；二阶中心矩还必须包含由两个均值差产生的 cross term。只把两块均值等权平均，或只相加两个局部 M2，在不等长且均值不同的输入上都会给出可预测的错误。
+
+精确有理数模型的触发器是 chunks `[0, 0]` 与 `[10]`，其 partial state 分别为 `(count=2, mean=0, M2=0)` 和 `(count=1, mean=10, M2=0)`。直接全量 oracle 与正确合并都得到 `(3, 10/3, 200/3)`；错误等权均值给出 `5`，遗漏 cross term 的 M2 给出 `0`。只修均值权重时，M2 仍会错误；只补 M2 项时，均值仍错误，因而这两项干预和各自 checkpoint 是可区分的。
+
+空 partial 应按 count 作为恒等状态处理；其 mean/M2 字段可以依当前实现约定为零或其他占位，只要 count=0 时不被当作普通数据参与合并。模型的单个非空 state 与空 state 合并是 identity control。另一个 control 用等长 `[0]`、`[10]`：等权 mean 恰好为 `5`，却仍需要正确的 M2=`50`；同均值 chunks 的 cross term 则为零，不能区分漏项。尾块与整块使用同一状态合并公式，但各自 count 必须来自实际有效元素；若尾块被当成完整块，先回到 [尾块有效区与旧状态：先证明本轮写入](tail-valid-region-state.md) 审计有效区。
+
+若当前输出要求逐位一致，还要以当前 oracle 的 tree、partial dtype 和最终 Cast 为准。将并行合并改成串行、提高 dtype 或调整 chunk 只能是区分实验：它可能改变舍入点，却不能证明遗漏 partial 或错误统计公式。
+
+## 修复与回归
+
+正式处置前写清每个 partial 的 producer、存储 dtype、count、合并消费者和最终 Cast，并用直接全量 oracle 验证多个不等长切分、空块、尾块及反向到达顺序。修复后同时回归单块与多块；单块保持通过并不能证明全局 merge 已闭合。缺少当前算子对方差分母、空输出、NaN 或精确顺序的约定，保持 `UNKNOWN`。

package/skills/asc-tools/tool-precision-debug/skills/tool-precision-debug/references/patterns/cases/softplus-v2-grad-family.md

@@ -0,0 +1,156 @@
+---
+type: Case
+title: SoftplusV2Grad：从错值形态选择调试支路
+description: RegBase 历史排查示例，从错值形态选择参数、repeat、浮点语义、设备精度或 Host 属性调查支路。
+tags: [SoftplusV2Grad, RegBase, 分支, 浮点语义]
+---
+
+# SoftplusV2Grad：从错值形态选择调试支路
+
+历史排查示例：CANN 9.0.0 / Ascend950PR / DAV3510 / RegBase。下文按错值选择调查支路，具体原因需用当前输入确认。
+
+从错值形态选择 repeat/mask、参数角色、CopyOut、浮点链或 Host 属性复用支路，再用当前输入与 oracle 设计区分实验。
+
+## 什么时候使用
+
+当前向量实现满足下列任一现象时打开本页：
+
+- 小规模或首个 repeat 正确，跨 repeat、tail 或特定 lane 周期性失败；
+- FP32 输出像 sigmoid 中间量，低精度输出却像 grad*bx 等另一条中间表达式；
+- 常规值通过，极负区出现 0 对极小非零，或极值区出现 Inf 对有限值；
+- 单次调用正确，同 shape 改变 beta、threshold 等属性后仍沿用上一次结果；
+- 修完一个明显错误后，大范围随机或窄带输入仍有新的残差。
+
+这些现象只负责选择支路。不要因为算子名相同，就直接复制公式改写、clamp、精度模式或常量。
+
+## 先冻结真正的计算约定
+
+在动 Kernel 前，从当前测试和 golden 中逐操作写出：
+
+    bx = beta * self
+    if bx > threshold:
+        out = grad
+    else:
+        z = exp(bx)
+        out = (grad * z) / (z + 1)
+
+上式只是常见结构示意。必须重新确认当前任务的比较符号、二元求值顺序、dtype 提升、广播、NaN/Inf、signed zero 与容差。把以下信息保留在本次调试记录中：
+
+- 能稳定复现的最小输入、seed、dtype、shape 和标量属性；
+- 实际加载的 kernel/so 身份，避免把旧安装副本当作新构建；
+- 第一个与 oracle 分叉的中间量，而不只记录最终误差；
+- 每个候选的预测、单变量干预和否证条件。
+
+## 第一步：用错值反解，不要先猜公式
+
+为失败点计算一组候选值：
+
+    bx
+    z = exp(bx)
+    z / (z + 1)
+    grad * bx
+    grad * z
+    (grad * z) / (z + 1)
+    grad * (z / (z + 1))
+    grad
+
+逐位比较 actual 与这些候选，保留 NaN/Inf 和 signed zero 类别。若 actual 稳定贴合某个中间值，优先追踪数据流角色和最后写者；若只在极值或 subnormal 区分叉，再进入浮点语义/设备精度支路。
+
+| 观察 | 优先支路 | 暂不支持 |
+|---|---|---|
+| 错误按 repeat 或固定 lane 周期出现 | mask/repeat/tail 消费 | 全局公式错误 |
+| actual 逐位等于 sigmoid 或 z | CopyOut 槽位、最后写者 | 随机精度噪声 |
+| actual 数值接近 grad*bx，位模式另行比较 | VF 位置参数/逻辑角色错位 | 单纯 Exp 误差 |
+| 仅极负区为 ±0，golden 为极小非零 | FTZ/DAZ 或中间下溢 | 地址整体错位 |
+| Inf/有限类别随结合顺序改变 | oracle 求值顺序 | 用“数学等价”重写 |
+| 同 shape A→B 结果仍像 A，换 shape 恢复 | Host executor/cache 身份 | Kernel 内公式单点错误 |
+
+## 支路 A：数据流角色与槽位
+
+画出一张表，不依赖变量名猜语义：
+
+| 逻辑角色 | 物理 TBuf/LocalTensor | 首次写者 | 最后写者 | VF 形参位置 | 调用实参 | CopyOut 来源 |
+|---|---|---|---|---|---|---|
+| grad |  |  |  |  |  |  |
+| bx |  |  |  |  |  |  |
+| z/sigmoid |  |  |  |  |  |  |
+| result |  |  |  |  |  |  |
+
+重点检查两类“类型正确、角色错误”的问题：
+
+1. VF 形参和实参都是同一种指针类型，编译器无法发现 bx 与 z、grad 等位置互换。
+2. VF 已把最终结果写入结果槽位，但 FP32 或某条 dtype 路径从中间槽位 CopyOut。
+
+单变量实验：只修一个角色映射或一个搬出来源，预测相关读取值或搬出值应如何改变。先确认新产物被采用、改动生效且观察能区分预测；有效观察与必要预测矛盾时，才排除被检验的具体绑定解释。最终错值不变时，检查目标中间值是否已恢复及是否有其他缺陷遮蔽，不能直接排除该绑定问题；参见[两个缺陷互相遮蔽](fused-rmsnorm-gelu-residual.md#两个缺陷互相遮蔽时怎么判断)。
+
+## 支路 B：repeat、mask 与 tail
+
+构造 count 位于一个 repeat 内、刚跨 repeat、多个 repeat、非对齐 tail 的四组输入，并给真假分支填入容易识别的哨兵值。
+
+- 只在跨 repeat 后失败：检查 Select/比较 API 的 mask 模式是否覆盖每个 repeat，mask 是否被截断或复用。
+- 只在 tail 失败：检查有效元素数、repeat 次数、末 repeat mask 与搬出长度是否使用同一逻辑长度。
+- 首个 repeat 也失败：回到角色/公式支路，不要用扩大 mask 掩盖全域错误。
+
+干预前先预测具体哪些 lane 会改变；“误差数量下降”不足以证明 mask 根因。
+
+## 支路 C：浮点语义而不是实数恒等式
+
+分别比较这些执行链的位级结果：
+
+    (grad * z) / (z + 1)
+    grad * (z / (z + 1))
+
+它们在实数域等价，在浮点极值、Inf 和舍入边界上不等价。只有 golden 的逐操作约定允许时才能改写。
+
+同样地：
+
+- 不符合算法定义的下界 clamp 会把极负 bx 映射到错误的非零区；
+- 若先改写或钳位 bx，再用它判断 bx > threshold，会同时改变分支谓词；
+- 为“数值稳定”改公式前，必须覆盖 NaN、Inf、signed zero、极大 grad 和阈值两侧。
+
+判定标准不是平均误差更小，而是逐操作语义和特殊值类别与 oracle 一致。
+
+### 公开回归通过后仍漏掉求值顺序
+
+另一次 FP32 直调诊断中，候选修复了掩码和极负输入问题，公开回归全部通过，却把 reference 解释为“先计算 sigmoid 再乘 grad”，保留了先除后乘。独立检查实际使用的 PyTorch 2.7.1 CPU `aten.softplus_backward`，确认该分支先乘后除。
+
+以 FP32 的 `grad=3.2e38、self=2、beta=1、threshold=20` 调用该 reference，输出为 `+Inf`；CPU 上先除后乘得到约 `2.82e38`。二者的中间乘积范围不同，“结果有限”和“公开回归通过”均不能证明保持了该参考行为。普通量级样本不足以区分这两条链，应另选能暴露范围差异的合法输入。
+
+这个观察补充的是参考求值顺序的核对方法。上述具体数值来自同版本 CPU 探针，不是候选 NPU 输出的逐元素重放；尚未完成更改候选后的 NPU 回归，不作为已验证修复方案，也不外推所有 Softplus 实现都必须采用这个顺序。
+
+## 支路 D：设备精度与 subnormal
+
+当残差集中在 0 对极小非零或一个很窄的输入带时，把“产生、计算、搬运”拆开探测：
+
+1. 直接生成 subnormal 并 CopyOut，判断搬运是否保留；
+2. 分别只执行 Exp、Mul、Div，定位第一次变为零的位置；
+3. 对比不同受支持精度或非 FTZ 模式，确认模式实际作用于哪个指令；
+4. 保存一个确定性窄带复现器，按位检查 oracle 和设备输出。
+
+Exp 接近 1 的微小差异可能被巨大 grad 放大成 Inf/有限分叉。先证明误差在哪个原语产生，再决定是否存在符合约定的精度模式；不要从某个输入点反推 magic constant 或局部补丁。
+
+## 支路 E：Host 属性复用与产物采用
+
+用相同 shape 连续执行：
+
+    A(beta/threshold = a) → B(beta/threshold = b)
+    B → A
+    A → 改 shape 的 B
+
+若第二次调用跟随第一次属性，而改 shape 后恢复，检查 executor/cache key 是否包含所有影响结果的标量属性，以及 tiling/kernel 参数是否随调用刷新。
+
+每轮 Kernel 实验还要核对构建产物时间/哈希、安装目标和运行时加载路径。源码已改但 actual 完全不动，先排除旧副本，不要继续堆叠修复。
+
+## 修复后的回归矩阵
+
+至少覆盖：
+
+- 首 repeat、跨 repeat、多 repeat、非对齐 tail；
+- FP16/BF16/FP32 等实际支持 dtype 与广播组合；
+- bx 在阈值两侧、极负区、零附近和大正区；
+- 正常、极大、零、Inf/NaN grad，以及 signed zero；
+- subnormal 产生/计算/搬运探针和保存的窄带复现；
+- 同 shape 不同属性的 A→B、B→A 调用顺序；
+- 原失败输入、固定小集、随机集和连续重复运行。
+
+每修一项都重新对残差分群。只有原失败闭合、每条已采纳根因有独立证据、回归矩阵通过且实际产物身份明确，才能结束该线程。