cann-workbench 0.0.0-stage → 0.0.2-alpha

package/skills/asc-tools/tool-precision-debug/skills/tool-precision-debug/references/patterns/mechanisms/multicore-ownership.md

@@ -0,0 +1,117 @@
+---
+type: Mechanism
+title: 多核分区、所有权与核间协同
+description: 建立每核数据与参与路径账本，区分区间重叠、遗漏、尾核长度、跨核依赖与归约合并。
+tags: [多核, 所有权, 同步, 归约]
+---
+
+# 多核分区、所有权与核间协同
+
+单核正确而多核错误、错误集中在核边界、部分核空转或输出随核数变化时，先建立每核数据所有权，再讨论同步。多核问题至少分为区间重叠、区间遗漏、尾核长度、跨核依赖和归约合并；它们不能由一个全局 barrier 统一解释。
+
+如果错误位置在不同运行间错位，同时表现为单核正常、多核异常，应同时查询重复运行稳定性与多核所有权；“运行间错位”和“单核多核差异”都只是路由信号，不能跳过地址集合与 happens-before 实验。
+
+## 所有权账本
+
+对每个 `blockIdx` 写出输入区间、输出区间、有效长度、尾块、读集合、写集合和跨核共享状态。验证所有合法输出元素恰好由约定要求的核写入：普通写通常要求不重叠且无遗漏；原子或归约写则需另列合并算子、初值和完成条件。核类型、配比与架构差异使用 `knowledge-query` 查询，实际核数从运行端确认；启动和同步 API 的支持范围使用 `ascendc-api-knowledge-query` 核对。
+
+把每核区间写成半开集合并检查三项：所有 required 输出的并集完整、普通写集合两两不交、每次读都落在当前核拥有或由明确跨核依赖发布的区域。只验证 `offset = blockIdx * length` 的一行公式不足以覆盖尾核、空核、二维 stride 和输入输出分区不同的情况。
+
+## 从逻辑任务集合反推地址
+
+分区不一定是连续区间。先编号全部逻辑任务，再从真实循环写出每核任务集合，最后把每个 task 映射到输入/输出地址。对于跨步（交错）分配，若启动核数为 `N`、任务数为 `T`，应直接枚举 `Tasks(c)={c+q*N | q>=0, c+q*N<T}`，而不是用一段连续 GM 区间近似。该公式仅适用于这种跨步分配；当前 Kernel 的任务集合应从实际循环、步长和退出条件推导。
+
+对普通“一任务一 owner”路径验证：所有参与核任务集合的并集恰好等于 required tasks，任意两核的集合交集为空，每个 task 的 tail 有效长度正确。对归约或 scatter 等允许多个 contributor 的路径，改用带重数的参与清单，明确重复贡献是否属于数学约定；不能用集合去重掩盖重复 partial。
+
+## GMM 的 group → block 所有权
+
+当错误从某个 group 开始、空组会让后续块错位、最后一组只错尾块，或启动核数大于有效 GMM task 数时查询本节。先按当前 tiling 为每组列出 `TM_g=ceil(M_g/baseM)`、`TN_g=ceil(N_g/baseN)`，再构造诊断用 task prefix `Q_g=sum(TM_h*TN_h, h<g)`。flat task `t` 若落在 `[Q_g,Q_{g+1})`，才能继续反解该组的 `(mTile,nTile)`；实际 Kernel 若使用循环跨步、轮转余数或对角线顺序，必须从真实循环重建映射，不能强行套连续除法。
+
+每个 `(g,mTile,nTile)` 写一行 ownership ledger：候选 block/core、A/B/C 物理区间、M/N 尾部有效量、workspace slot、producer epoch、consumer epoch 和最终 GM 写集合。验证 required task 恰好覆盖一次；若一个 tile 合法地由多个 K-block contributor 产生，则另列 K-block 参与清单与合并规则，不能把它误报为重复 owner。
+
+边界用例至少包含：首组为空、中间组为空、末组为空；`M_g<baseM`、`N_g<baseN`；最后一组只产生一个 task；task 总数小于启动核数；task 总数刚好多 1。空组不产生输出 task 不代表其所有 tensor storage span 都为零；无任务核不得写伪结果或读取未发布 workspace，但它能否退出/是否仍需参与同步取决于当前 API 约定，缺证据时保持 UNKNOWN。
+
+### Cube producer → Vector epilogue consumer
+
+混合 AIC/AIV 路径必须把每个 workspace slot 当作带 epoch 的有界通道，而不是普通临时数组：
+
+```text
+AIC producer: 产生 (group,tile,epoch) → 写 slot → publish ready
+AIV consumer: wait ready → 读同一有效区 → dequant/activation/Cast → 写 GM → publish released
+AIC reuse:    wait released → 下一 epoch 才能覆盖 slot
+```
+
+逐槽验证 producer、consumer、逻辑 tile、有效 M/N、地址范围和 ready/released 次数一一对应。AIC 结果正确而 AIV 输入错误支持 workspace offset/epoch/发布候选；AIV 输入正确而最终输出错误则转查 epilogue 公式、scale 索引与 Cast。只增加 barrier 后“偶尔好了”不能证明所有权或同步公式；普通高层 Matmul 的对象生命周期也不能证明 GMM 的 workspace/跨核约定。
+
+固定来源中的 QuantGroupMatmul 样例只说明其自身实现，当前 Matmul/Mmad 接口使用 `ascendc-api-knowledge-query` 核对；其它分核公式、空核同步参与集和 workspace slot 数量须按当前 Kernel 与 API 约定确认。
+
+## 启动核、参与核与空核
+
+分别记录启动核集合、实际有任务的参与核集合和必须到达协同点的同步参与集合。`task_count` 小于启动核数时，空核可能不产生 partial，但它能否提前返回、是否仍须到达某个全局同步点，取决于当前版本同步 API 和 Kernel 模型；没有权威版本证据时保持 UNKNOWN。审计每条 early-return 路径与同步点，既不能让无任务核伪造一个 partial，也不能让需要参与协同的核提前退出。
+
+最终合并阶段不得仅按启动核数盲读 workspace。逐槽记录写者、有效标志、identity 初始化与最终消费者：参与核应恰好贡献约定要求的 partial；空槽应被明确排除，或证明每个被读取空槽的 identity 在精确 reducer、dtype 与特殊值约定下为中性。空任务不得进入 count 或 Mean 的除数。尾任务、break 条件和最后一轮中“部分核有任务、部分核为空”的场景必须单独覆盖。
+
+### 沿可达路径核对发布、等待与轮次
+
+对每个实际参与核和共享 slot/region，按执行路径列出：初始化发布、循环第 `i` 轮发布、第 `i` 轮消费、early return、`break`/`continue`，以及尾轮收尾的 Set/Wait。文本中的 Set/Wait 数量和出现顺序只用于定位。先区分通知表示“数据就绪”还是“消费完成、允许复用”，再检查每条**可达** Wait 是否有对应 region、依赖方向与轮次映射的可达 Set：就绪边应约束 producer 写与 consumer 读，回收边应约束上一轮消费与下一轮重写；首轮还可能由初始化通知启动。等待前后还要核对该核是否仍属于本次协同的参与集合。
+
+合法跨轮 ping-pong 是必要反例：循环前的初始 Set 可以使首轮 Wait 消费“上一轮”通知；循环内 Wait 上一 generation 的回收通知后 Set 当前 generation 的回收通知，循环结束后再 Wait 尾轮。这个核内 event 示例说明文本不相邻也可能形成闭合依赖；跨核场景还须另查作用域和参与集合。未覆盖的条件分支、提前返回、首轮索引下溢或尾轮缺少收尾，都应通过路径展开和 generation 账本验证，而不是仅按关键词计数。
+
+跨核 API 是否要求无任务核参与、一个具体 `SyncAll` 的参与集合，以及 Set/Wait 的精确作用域都属于当前版本约束。没有对应 API 证据时，把“空核可退出”或“所有启动核必须等待”等结论保留为 `UNKNOWN`。需要区分条件发布或复用回收问题时，按需参见 [同步诊断：保护区域、条件路径与缓冲回收](../cases/sync-dataflow-handshake.md)；本节不从案例外推具体 API 或参与核约定。
+
+## 跨核通知与等待范围
+
+- 消费者依赖其他核写入 GM 时，等待应覆盖所有实际贡献者和同一轮数据；先查漏核、重复贡献与提前退出，再调整通知。
+- 等待只约束指定流水的形态下，随后标量操作未必一起等待。分别记录真正消费者与被阻塞的流水，使用 `ascendc-api-knowledge-query` 核对 CrossCoreWaitFlag 的产品和重载；插全局停顿后恢复只支持时序相关。
+- 无界 tile 序号直接作为 flagId 时，检查实际编码是否与另一通道或保留资源碰撞。编码、次数、区域与轮次都要对应，不能只比较源码字面值。
+- 通知计数范围不直接等于循环总轮次上限。若一次发布已被消费，资源可能再次使用；按当前事件规则检查未消费通知与首尾轮，不用总迭代数代替配对分析。
+- 纯 Vector/Mix 或多流并发挂起时，列出实际参与核、可达退出和等待环。等待尚未获得执行资源的任务，可能形成调度上的循环依赖；使用 `ascendc-api-knowledge-query` 核对当前 SyncAll 的执行形态与调度条件。
+
+## 跨卡通信的缓冲所有权
+
+对 HCCL 集合通信或点对点交换，把 `(rank, core/block, round, buffer region)` 一起记录。主机通道建好、本 block 完成、所有生产者完成、远端可读，是不同条件。若 Kernel 下发后等待远端地址，检查各 rank 的建链与就绪次序；需要跨 rank 协调时按当前通信实现建立完成关系，不能用本地一个 block 的完成通知代替。
+
+| 现象 | 优先检查 |
+| --- | --- |
+| recvBuf 偶发旧值或随轮次变化 | 所用接口的 Commit/Wait 是否覆盖本次读区间，读是否发生在完成之前 |
+| 本卡分段一直是旧值 | 跳过本卡复制的配置是否与下游完整结果要求一致，本轮是否确实写过该段 |
+| 通信数据整体错位 | dataType、元素数/字节数、count/repeat/strideCount 与物理布局是否一致 |
+| 多轮切分只有部分分段更新 | 每轮收发地址递推和有效数是否属于同一轮，缓冲是否提前复用 |
+| 远端收到通知仍读到旧值 | 通知是否覆盖全部实际生产者，接收端是否过早消费 |
+
+跨卡路径中，Prepare、Commit 与 Wait 各自的职责按所用对象协议确认，下发不等于完成。启用 SetSkipLocalRankCopy 时还要核对本 rank 数据段由谁写入、是否会被消费以及产品支持；只改变该设置的对照必须保持缓冲容量、传输计数和参与 rank 一致。
+
+Device 通信的接口支持与提交/等待语义使用 `knowledge-query` 核对，Host 上下文另见[通信上下文的身份与生命周期](golden-host-contract.md#通信上下文的身份与生命周期)。Hcomm/URMA 的 Drain、通知和工作区含义需按实际实现确认；这里只使用读写与完成关系排查，不假定统一的容量、原子类型或等待范围。
+
+## 支持与反证
+
+- 错误索引与核区间端点一致，或地址集合能证明重叠/遗漏，支持所有权候选。
+- `blockDim=1` 改善只说明并发或分区相关，不能区分重叠、同步和每核状态初始化。
+- 单核仍在第二行或第二 tile 出错，优先检查跨 tile 状态，而不是继续归因于核间竞态。
+- 结合[msSanitizer](https://gitcode.com/Ascend/mssanitizer)的读写或同步告警核对相关指令和核，不直接据此证明逻辑所有权公式。
+
+## 区分实验
+
+使用相同输入比较 1、2、典型核数和尾核场景；为每核输出增加诊断标签或保存区间元数据，确认修改真正采用。对跨核 A 写 B 读，分别验证地址所有权和 happens-before；只增加一种最小协同，并预先声明应消失的边界。对归约同时检查合并顺序是否改变数值误差。
+
+多核对照还要区分“并发消失”和“每核工作量改变”：`blockDim=1` 会同时改变分片、尾块、循环次数和归约顺序。优先构造保持每核语义可比的 1→2→N 对照，并记录各核的实际 ownership ledger。
+
+因此，单核通过不是“已证明核间同步缺失”，单核失败也不是“已证明与多核无关”。单核会把原本分散的任务串到一个核上，可能消除地址竞争，却增加同核循环次数并暴露旧 tile/旧 buffer；还会改变 partial 数量与归约树。把 `blockDim=1` 只作为混杂较多的反事实：同时比较实际任务集合、每任务地址、循环 epoch 和合并顺序。若条件允许，再设计一个保持任务内容不变、只改变 ownership 或共享写入的对照，其因果信息量高于直接比较最终输出。
+
+## 归约中的两层顺序
+
+先区分跨核 ownership 与单核内部归约分组。即使 `blockDim=1`，向量 repeat 内仍可能采用分组或二叉树累加；这属于 [累加、归约顺序与消减](accumulation-order.md)，不是多核竞态。反过来，多核每核各自产生正确 partial sum，也不能证明最终参与集合、workspace 槽位、发布时序和跨核合并顺序正确。
+
+对“多行、每行独立归约”先写出每个输出行的唯一 owner，再写每个 owner 内的有效元素集合和归约顺序。只有错误随 blockDim、核边界或读写集合改变时才提高本页优先级；单核仍稳定失配时应继续比较元素集合、dtype、API 重载和 repeat 层级，而不是用“已经单核”排除所有顺序问题。
+
+Batch MatMul 可按两级边界检查：先核对实际启动核与 tiling 参与核，排除无 ownership 的核；再检查参与核的 GM 半开区间及尾部归属；核内继续按 UB 可承载行数核对完整迭代与 tail。各级分片和尾部处理规则都须从当前实现确认。
+
+自然症状“最后一核错”“增加核数后相邻区间被覆盖”应触发四项对照：多余核是否早退、start 是否已超有效区、尾核长度是否由总长减 start 得到、核内 tail 是否仍错误使用完整块长度。使用区间并集和交集验证，而不是只比较最终输出；dtype 或 buffer 数改变后还要重新计算 UB 二级分块。
+
+## 修复与回归
+
+针对已确认的根因修正区间公式、尾核长度或依赖。仅凭降低核数后通过不能认定修复成立；若保留降核或串行方案，应有根因依据，满足项目的功能、数值与运行要求，并完成相关回归。回归按实际改动覆盖元素数小于核数、整除、余 1、最大尾部、支持的 blockDim、原子/非原子路径和强消减数据；同步、Cache 和原子语义必须按当前 CANN/平台说明核实。
+
+## 事实边界
+
+核数、同步参与规则、地址对齐、原子支持和具体 API 行为必须查询当前版本的官方 API 文档及本地平台说明，缺少权威证据时保持 `UNKNOWN`。

package/skills/asc-tools/tool-precision-debug/skills/tool-precision-debug/references/patterns/mechanisms/pipeline-sync-visibility.md

@@ -0,0 +1,146 @@
+---
+type: Mechanism
+title: 流水同步与数据可见性
+description: 沿生产者、消费者、共享资源和依赖边，区分流水同步、事件复用与缓存可见性问题。
+tags: [同步, 流水, 数据可见性, 生命周期]
+---
+
+# 流水同步与数据可见性
+
+同步问题必须写成 producer 流水、consumer 流水、共享资源和缺失依赖四元组。错误位置随运行变化、只在多核出现或插入 barrier 后改善，都只是候选信号；全局停顿可能同时掩盖覆盖、生命周期和缓存问题。
+
+先把将要解释的观察放回竞争候选中：
+
+| 当前观察 | 可以支持 | 下一步仍需区分 |
+|---|---|---|
+| 全流水屏障后恢复 | 改变执行时序或重叠能影响结果 | 提前发布、复用覆盖、generation/地址错配、核内数据就绪等候选 |
+| 仅保护一条推定依赖后再次失败 | 该细化处置未保留原探针的效果，不能据此断定有多条缺失依赖 | 是否选对真实边及其方向、region/generation，干预是否实际生效，是否还有其他被原探针掩盖的边 |
+| 两个子块使用同一个 event 数字 | 存在需要审阅的资源身份线索 | 封装最终调用的 API、执行侧、依赖类型和资源作用域；不能直接假定子块共享事件 |
+
+一个抽象反例：实际只缺少依赖 E2，原探针同时建立 E1、E2 的顺序，而局部实验只保护了 E1，此时仍会得到“原探针 PASS、局部 FAIL”。所以这对观察不能区分选错一条边和仍有多条缺边。下一步先核对局部处置保护的真实读写、区域、轮次和实际生效情况，再判断是否需要调查其它依赖；具体同步 API 的覆盖范围另按目标版本核验。
+
+对当前 profile 的 subblock、Set/Wait 或 PipeBarrier 语义有疑问时，使用 `ascendc-api-knowledge-query` 取得对应接口正文，并展开工程的同步封装；源码中的 wrapper 名称不一定是公开 API。不要在尚未确认作用域时先给所有 event 重新编号。
+
+按三层审计依赖：编译器可能提供的自动同步、队列/资源框架表达的 producer-consumer 协议、开发者显式维护的 event/barrier/cache 可见性。任一层是否覆盖当前边都属于具体版本和编程范式事实，不能从另一工程或同名 API 外推。
+
+## 区分三类边界
+
+- 核内不同流水依赖：核对精确编程范式是否由编译器、TQue 或开发者负责插入同步。
+- 同一流水地址重叠：核对目标版本的 PipeBarrier 约束，不把跨流水 Set/Wait 与同流水 barrier 混用。
+- Scalar 与 DMA/其他核的 GM 可见性：单独检查 Data Cache、Cache Line 所有权和核间同步。
+
+### 先按依赖边选 API 族，再查版本事实
+
+| 实际依赖边 | 优先查询的版本 API 族 | 不能替代它的相邻机制 |
+|---|---|---|
+| 同一核、不同流水的 producer→consumer | `SetFlag/WaitFlag` | 同流水 `PipeBarrier`、跨核 flag |
+| 同一流水内部的地址/指令依赖 | `PipeBarrier` | 跨流水 event、全核 barrier |
+| 所有实际参与核必须到达同一阶段 | `SyncAll` soft/hard | Cache flush、Atomic、单核 Set/Wait |
+| 分离模式下跨核计数通知 | CrossCore Set/Wait flag | 同核 event ID、普通流水 barrier |
+| 多个 contributor 向共享 GM 累加 | 先区分 DMA Atomic 状态与直接标量 Atomic | 核间 barrier 不定义数值累加顺序 |
+
+该表只做诊断路由，数值、产品支持、workspace、mode、flag/event 范围和 dtype 均使用 `ascendc-api-knowledge-query` 查目标环境的原文。对每次实验记录 producer/consumer、地址、流水或核、event/flag generation、参与核集合，以及 Atomic 开启和关闭点。编译器可能自动插入某类同步时，仍须从生成物或同步日志证明它覆盖的是这条真实数据边。
+
+还要区分 LocalTensor 上的 Scalar 写后由 DMA 消费，与 GlobalTensor 标量写后要求 GM 可见；两者的地址空间和依赖边不同。若现象是“上一轮旧数据”，检查多 tile 复用边是否形成循环闭环；若现象只在多核，先证明跨核地址或依赖，再使用 [多核分区、所有权与核间协同](multicore-ownership.md)。
+
+`GlobalTensor::SetValue` 后输出全零或其他消费者仍看到旧值时，先记录写入发生在 Scalar DCache、后续消费者通过 Scalar、DMA 还是其他核读取，以及需要可见的最早时点。分别核对受影响的 Cache Line、多核是否共享同一行和当前产品的 Cache 一致性 API 约定；不能把“索引 0 正确”当成 GM 已可见，也不能默认改成 `LocalTensor::SetValue + DataCopy` 就是唯一正确修复。精确刷新原型、范围和产品支持必须从当前 CANN API 文档读取。
+
+## 从执行单元检查依赖
+
+不清楚目标架构的执行单元、指令队列、数据通路或 VF 形态时，先使用 `knowledge-query` 建立对应关系；本页据此检查实际 producer-consumer 依赖，具体同步接口继续使用 `ascendc-api-knowledge-query` 查询。
+
+Scalar 发射的计算和搬运指令进入不同队列，各执行单元可以异步工作。**代码先写搬入、后写计算，并不单独证明计算开始前搬入已完成。** 即使在同一流水内，指令按顺序进入，也不意味着前一条的全部读写已经结束。[硬件基本架构][sync-source-9]、[同步控制简介][sync-source-6]
+
+由这个执行模型，可以把缓冲区上的依赖分成三种来理解：
+
+| 依赖 | 必须满足的先后关系 | 典型场景 |
+| --- | --- | --- |
+| 写后读 | 生产者写完，消费者再读取 | GM → UB 搬入完成后，Vector 读取这一块 |
+| 读后写 | 消费者读完，下一轮再覆盖 | UB → GM 搬出尚在读取时，不能提前覆盖同一输出缓冲区 |
+| 写后写 | 需要保留的两次写入按预期顺序完成 | 不同阶段写同一地址，最终值需要明确由哪次写入产生 |
+
+双缓冲通过交替使用不同缓冲区为搬运与计算重叠提供空间，但每个缓冲区被再次使用时，仍要满足上述依赖。核对依赖时，应同时考虑框架、编译器已经建立的同步，以及直接指针、复用或手工搬运是否超出其覆盖范围。
+
+同步还要区分作用范围：
+
+| 范围 | 需要理解的保证 |
+| --- | --- |
+| 核内单流水 | `PipeBarrier` 约束相应流水中前后指令的读写完成顺序；具体可用形式看架构 |
+| 核内不同流水 | 队列同步或匹配的 SetFlag/WaitFlag 表达生产者完成、消费者再继续；要识别具体流水方向 |
+| Reg VF 内 | 寄存器依赖由硬件保证；不同寄存器访问同一 UB 区域产生的读写依赖仍可能需要显式同步 |
+| SIMT Block 内 | 同步屏障用于线程间阶段协作；内存栅栏约束当前线程的访存顺序和可见性，不等待其他线程到齐 |
+| 不同 Block 或不同核 | 需要该范围的通信与同步设计，核内流水同步和 Block 内屏障不能扩展为全局同步 |
+
+前三行依据[核内同步说明][sync-source-6]和[Reg 矢量计算编程][sync-source-10]；SIMT 的屏障、栅栏与 Block 边界见[SIMT 同步机制][sync-source-14]。具体核内、SIMT 或跨核接口使用 `ascendc-api-knowledge-query` 核对。同步只解决相应依赖；索引、布局、类型或计算公式错误仍需分别核对。
+
+[sync-source-9]: https://gitcode.com/cann/asc-devkit/blob/e5451c7feba11f9e259f4fbc19c4bf82f8c0496c/docs/guide/编程指南/高级编程/硬件实现/基本架构.md
+[sync-source-6]: https://gitcode.com/cann/asc-devkit/blob/c8c1b9df6bb9cd61c09751c7ef414b89e06af274/docs/api/context/同步控制简介.md
+[sync-source-10]: https://gitcode.com/cann/asc-devkit/blob/e5451c7feba11f9e259f4fbc19c4bf82f8c0496c/docs/guide/编程指南/编程模型/AI-Core-SIMD编程/基于指针的C语言编程/Reg矢量计算编程.md
+[sync-source-14]: https://gitcode.com/cann/asc-devkit/blob/e5451c7feba11f9e259f4fbc19c4bf82f8c0496c/docs/guide/编程指南/编程模型/AI-Core-SIMT编程/同步机制.md
+
+## 因果实验
+
+固定同一输入重复运行，记录错误索引集合和每核区间。只在推定边上加入一种同步，事先写出改善应发生在哪个张量、哪个阶段；同时查看编译器同步日志或生成物，确认干预确实进入目标产物。若删除可疑并行重叠后仍稳定失败，则降低竞态候选。
+
+对 Global 标量写可做三组单变量对照：保持地址不变只改变消费者通路，保持通路不变只改变可见性处理，保持每核数据不变只隔离 Cache Line 所有权。只有观察变化符合事前预测，才能区分 Cache 可见性、核间覆盖和批量搬运路径问题；诊断用全 Cache 操作不能直接成为正式修复。
+
+对 event 类候选记录每次获取、Set、Wait、释放和循环复用点，核对方向与生命周期，而不是只搜索相同数字。单 tile/多 tile、单次/重复运行、一个 producer/多个 consumer 三组对照可区分缺少依赖、事件复用和资源别名。[msSanitizer](https://gitcode.com/Ascend/mssanitizer)报告或编译日志提供原始观察，不把错误码直接映射成根因。
+
+event ledger 至少包含资源身份、依赖方向、申请/获取点、Set、Wait、释放和下一次复用；同一个数字出现在不同依赖类型中不自动代表同一资源，也不能用一次成功运行证明生命周期始终合法。
+
+### 把嵌套循环展开后再放置 Set/Wait
+
+同一对 Set/Wait 在源码中各出现一次，不代表实际执行次数配对。先展开一个真实的首轮、中间轮、尾轮，分别数清每个资源和 generation 的发布、等待与复用；空循环、条件跳过和最终收尾也算执行路径。下面是诊断模型，具体事件行为仍以当前版本 API 为准：
+
+| 实际发布粒度 | 容易漏掉的等待路径 | 区分检查 |
+|---|---|---|
+| producer 完成一整轮的多个 region 后 Set 一次 | consumer 对每个 region 都 Wait 一次 | 后续 Wait 是否有各自对应的 Set；先确认等待整轮完成是否覆盖所有首次读取，不能机械地把 Wait 放在每个内层循环开头 |
+| producer 每个 region 都独立 Set | consumer 只在整轮开始 Wait 一次 | 该等待是否只保护一部分数据；不能为了让次数相等，把仍会重叠的生产消费边移到循环外 |
+| 普通轮次有发布，尾轮进入单独收尾函数 | 收尾前漏 Wait，或收尾内部又重复 Wait | 沿调用链核对尾轮实际发布、首次读取与最后一次配对；单轮通过不覆盖跨轮和收尾 |
+
+例如，只在多 region 时卡住而单 region 通过，先比较两者展开后的配对与可达路径；只在后续轮出现旧值，则比较发布/回收对应的 region 和 generation。增加 event 数字或延长超时不会自动修复这些关系。超时本身也不能证明事件配对有误，仍需保留最后有进展的阶段、可达发布点和相邻 control。
+
+展开嵌套循环时，以 SetFlag/WaitFlag 的配对要求检查事件类型与轮次；目标为 CANN 9.0.0 时，使用 `ascendc-api-knowledge-query` 取得该版本要求。是否可在循环外等待，仍取决于当前工程的依赖关系与事件族的计数、广播语义。
+
+### 先证明同步对象保护了真实数据区域
+
+对每条可疑 producer→consumer 边，先建立一行区域账本：本轮 generation、producer 实际最后写入的 region（物理根/基址、offset 与有效范围）、consumer 第一次读取的 region、同步对象选择的 slot/index/generation，以及这两个动作所在的实际执行路径。只有区域和 generation 均能由地址或可复核映射确证为匹配对象，且 producer 的有效写入覆盖 consumer 的首次读取，Set/Wait 配对才从候选升级为 “保护了这条数据边”的证据。
+
+变量同名不能替代该核对：index 可以在另一条流水上重新绑定；同一根 buffer 的不同 offset 仍是不同 region；表达式写法不同也可能在当前取值域指向同一 region。例如，`idx & 3` 与 `idx % 4` 在非负整型索引的相应取值域可等价，不能仅因文本不同判为错配。反过来，producer 写 `(idx * TILE)` 而 consumer 读 `((idx - 1) * TILE)` 时，若两侧都引用 `idx`，仍须按实际轮次展开。宏、alias、类型转换或循环范围使映射无法确定时，结论为 `UNKNOWN`；用实际地址、region 标识和轮次探针区分，不以名称或正则匹配替代证据。
+
+若已证明同步对象保护的是另一 region 或另一 generation，优先回查 producer 实际发布点、consumer 首次读取点和索引重绑定处；不要先改 event 数量或插入全局停顿。静态工具对此类关系只能提供候选：它的 finding 需要地址/轮次验证，未命中也不能证明映射正确。
+
+生产 Cube→Vector ping-pong 代码提供一种实现观察：producer 只在结果写入共享 workspace 后发布，consumer 每轮等待对应 generation；buffer 将被复用前，consumer 再沿反方向确认完成。诊断时把两个方向、共享槽位、循环 generation、发布流水和等待条件分别记账。跨核通知不替代核内流水依赖，也不能从某份实现的 flag 数字、轮转深度或 PIPE 参数外推当前工程约定。
+
+当发布藏在可跳过的装载/计算条件中，或 slot 在消费者结束前将被复用时，按 [同步诊断：保护区域、条件路径与缓冲回收](../cases/sync-dataflow-handshake.md) 的调查分叉分别验证“等待仍可达但发布被跳过”和“消费结束前覆盖”；前者关注路径是否闭合，后者关注回收依赖的位置，不能由一次 barrier 的通过合并为同一根因。
+
+最小实验是只延迟 producer 发布或只隔离一个 workspace generation，并预声明旧值应在哪轮消失；同时保留尾轮和一个 producer/多个 consumer control。若全局 barrier 通过，只说明时序相关，仍需区分过早发布、错误 generation、地址重叠和核内可见性。
+
+同步插桩的观察点也必须有数据就绪边：写明 producer 的完成位置、消费者第一次读取位置、共享 buffer/generation 与预计依赖。额外 barrier、dump 或强制单核可能同时改变时序、tile 复用和 core 调度，故只能产生候选信号。采用 `Parent → probe → Parent` 回放；若两侧 Parent 的失败率或错误坐标不稳定，先报告分布与扰动，不把 probe 的通过解释为某个同步 API 已修复问题。
+
+## 接口使用中的同步遗漏
+
+TPipe/TQue 路径在 AllocTensor 后直接消费、漏过 EnQue/DeQue 交接，或手动路径少了一条事件依赖，都可能读到尚未完成的搬运结果。先确认当前编程形态下由谁建立就绪边，再检查真实读写流水；仅有 `PipeBarrier<PIPE_V>` 不能据此说明已保护 Vector 写与搬出之间的跨流水消费。
+
+相同事件连续发布、条件分支多等一次、两条搬运写同一区域时，按首轮、中间轮和收尾展开数据就绪与缓冲回收；不要机械要求每个循环内部 Set/Wait 相邻。合法跨轮配对和条件遗漏见[同步案例](../cases/sync-dataflow-handshake.md)，具体事件、保留 ID 和接口支持使用 `ascendc-api-knowledge-query` 查当前原文。
+
+## 缓存可见性
+
+GlobalTensor 标量访问与 DMA 可能经过不同的数据通路。地址和生产者结果都正确、消费者仍读到旧值时，分别检查写回、失效和读取的顺序与范围；跨核屏障不能自动替代当前通路需要的缓存操作。多核标量写相邻位置，还要考虑缓存维护单位相交造成覆盖，用分离写区的对照定位。
+
+使用 `ascendc-api-knowledge-query` 核对 DataCacheCleanAndInvalid、GlobalTensor GetValue/SetValue 的缓存条件与实际搬运通路。批量 DMA 可以作为不同访问路径的对照，但它会改变同步与布局；不能把官方的谨慎使用提示扩大成一律禁用标量访问。
+
+**混合 VF。** 在 CANN 9.1.0 的 950 模型中，Scalar 把 VF 发射到 Vector Function Queue，各 VF 串行执行，并与 MTE 异步工作。SIMD VF 与 SIMT VF 对应不同的计算方式；相邻 VF 的顺序不等于外部搬运已经完成。SIMD Reg VF 内的 Aux Scalar 与外层 Main Scalar 也属于不同执行域，函数标签和允许调用的 API 受此影响。[混合编程模型][vf-source-4]、[Reg 矢量计算编程][vf-source-10]
+
+[vf-source-4]: https://gitcode.com/cann/asc-devkit/blob/e5451c7feba11f9e259f4fbc19c4bf82f8c0496c/docs/guide/编程指南/高级编程/高级AI-Core编程模型/SIMD与SIMT混合编程/抽象硬件架构.md
+[vf-source-10]: https://gitcode.com/cann/asc-devkit/blob/e5451c7feba11f9e259f4fbc19c4bf82f8c0496c/docs/guide/编程指南/编程模型/AI-Core-SIMD编程/基于指针的C语言编程/Reg矢量计算编程.md
+
+## SIMT 屏障与参与范围
+
+SIMT 中 asc_syncthreads 的 Block 屏障与 asc_threadfence 的内存栅栏分别核对：前者需要参与线程到达，后者不等待所有线程完成。条件分支或提前返回改变参与集合时，先展开路径，不能只增加同名调用。SyncAll 还需匹配软/硬重载、纯 Vector/Mix 形态、参与核与调度资源；局部屏障通过不能证明全核协议成立。
+
+## 结论限制
+
+SetFlag/WaitFlag、PipeBarrier、核间 barrier 和 Cache 刷新解决的依赖不同，不能互换。API 是否自动同步、event ID 管理和可用流水均取决于版本与编程范式，须核对当前 CANN 的 API 文档。没有执行环境时，可依据适用文档、当前源码及已有可信观察继续分析，并说明未验证的运行条件；不能仅凭框架名称或调用成功，就断言某条依赖已有保证。
+
+准备正式处置时，先区分哪些同步仅用于诊断，哪些依赖已由证据支持；撤销未接受的探针，再验证原流水、不同 tile 数和重复运行，并检查死锁、串行化或事件资源泄漏。若打算保留范围更大的同步，需说明其保护的数据边、适用路径和性能代价，按任务要求完成验证；探针通过本身不足以接受该处置或确认具体根因。

package/skills/asc-tools/tool-precision-debug/skills/tool-precision-debug/references/patterns/mechanisms/precision-mode-approximation.md

@@ -0,0 +1,90 @@
+---
+type: Mechanism
+title: 精度模式、近似路径与 Fallback
+description: 结合实际 dtype、API 模式和实现路径，区分输入量化、近似误差、Fallback 与下游离散边界放大。
+tags: [精度模式, 近似计算, Fallback, 量化]
+---
+
+# 精度模式、近似路径与 Fallback
+
+同一数学公式在 dtype、API 模式或实现路径变化后出现窄带误差，不等于已经确认 fallback。先区分输入量化、显式 Cast、API 近似误差、非原生实现路径、特殊值模式和下游放大；优先单独改变待检验因素，无法分离的联动按组合干预解释，再按缺口补观察。
+
+若下游是整数舍入、量化或阈值分支，小的浮点扰动也可能跨过离散分界。先比较分界前的实际值及其邻域，保持输入位模式与其他路径不变；从最终输出反解出的 ULP 偏移只是候选，不能替代设备中间值或单指令测量。动态量化的敏感输入与参数链见 [动态量化：统计范围、scale 角色与舍入边界](../operators/dynamic-quant.md)；除法重载与精度配置按实际 profile 查询 API，不能跨架构借用。
+
+## 建立实际路径
+
+架构的数据类型能力、编程模型和条件编译含义使用 `knowledge-query` 查询；具体 API 是否支持该 dtype、模式及误差保证仍按目标版本使用 `ascendc-api-knowledge-query` 确认，不能仅凭架构具备某种能力就认定当前调用采用了它。
+
+记录精确 CANN、SoC、编程模型、API 重载、输入/中间/输出 dtype、显式模式、编译分支和生成物身份。API 是否支持某 dtype、采用何种算法以及误差保证属于版本强事实，只能从对应版本 API 文档获得；不能从历史案例症状、编译成功或另一个 dtype 的行为反推。
+
+## 放大链分析
+
+在 API 输入、API 输出和第一个敏感消费者处保存值与位模式。把局部误差传播到后续乘除、阈值、指数、归一化和特殊值分类，寻找“微小 ULP 差异何时变成分支、Inf/有限值或容差类别差异”。随机低比例失败应先收窄成可重复数值带，再评估模式。
+
+## 算术替换与近似路径
+
+设备 Div 改成 Host 求倒数后 Muls、标量广播改成另一种算术接口，可能改变舍入位置和调用路径。固定输入、dtype 与后续消费者，先比较替换点的局部输出，再看最终误差。Reciprocal/Rsqrt 的误差略超容差时，使用 `ascendc-api-knowledge-query` 取得当前算法模式的精度说明，再选择对照；Div、Sqrt 等替代组合也要满足原验收要求。
+
+大输入下 Sqrt 变成 0、Rsqrt 变成 Inf，先查所用重载和算法模式的输入范围。只在合法输入内做模式对照，不用截断合法输入掩盖错误。次正规值变零与整型溢出另查[特殊值机制](special-values.md)；半精度小增量丢失则继续按下方 Cast 阶段图定位。
+
+矩阵乘的 HF32 开关需要连同 Host、框架和 Kernel 实际状态检查，见[矩阵乘的 HF32 排查](../operators/matmul-mmad.md#hf32-与中间精度)。
+
+## dtype 与 tiling 的二维对照
+
+把 dtype 和 tiling/长度作为两个独立轴，而不是只做一次 FP16/FP32 对比。第一组固定实际低精度输入位模式，用逐步量化的 CPU oracle 对照 Kernel；第二组保持 dtype 与输入共同前缀不变，只改变长度或 tiling 边界；第三组冻结 tiling、模式和最终 Cast，只扩大一个中间量。记录每格的 tile 长度、tile 数量、核数、分支、API 重载和生成物身份。
+
+FP16 改为 FP32 会同时改变元素字节数、片上容量预算，并可能改变 tiling、分支、重载或实现路径；结果改善只能先标为混杂证据。若无法保持另一轴不变，应明确写成“未能因果区分”，再用相同 dtype 的长度扫描或相同 tiling 的单中间量实验补证，不能把 dtype A/B 直接写成精度根因。
+
+## FP16 输入、FP32 中间与输出 Cast 的阶段图
+
+当输入/输出都是 FP16，但最终误差像过早降精度、出口窄化或某个 FP32 中间被绕过时查询本节。先按实际执行画图，不把“混合精度”当成单一模式：
+
+```text
+GM half → CopyIn/UB half → Cast#in → FP32 stage 1 → ... → FP32 stage n
+        → Cast#out → UB half → CopyOut/GM half
+```
+
+为 `Cast#in` 前后、每个敏感 FP32 stage、`Cast#out` 前后保存 dtype、API 重载、有效区、数值和位模式。入口 half→float 与出口 float→half 的支持模式须使用 `ascendc-api-knowledge-query` 核对；“入口无损”不等于后续 FP32 算法与高精度 oracle 位级一致，“出口只差一次舍入”也须由 Cast 前已经一致来证明。
+
+用单变量 Cast 时机实验定位：一次只把一个 Cast 边界跨过一个操作，例如比较“操作 P 前升 FP32”与 “P 后才升 FP32”，或比较“操作 Q 前降 half”与“Q 后再降 half”；输入位模式、shape、tiling、mask、其余 dtype、模式和输出比较规则全部冻结，并为两条逐操作链各算局部 oracle。若移动边界同时改变 API 重载、tiling、UB 容量或生成物分支，结果标为混杂证据，不写成 Cast 时机根因。一次把整条链全部改成 FP32 只能证明组合路径改善。
+
+支持证据是首个分叉随同一个 Cast 边界移动，且两条链分别匹配事前 oracle；只有最终误差下降、或更换 RoundMode 与中间 dtype 同时发生，均不能区分舍入模式和时机。反例是 Cast 前已经出现错位，此时后移/前移出口 Cast 不会修复上游 layout、group offset 或 K-block 参与集合。
+
+需要固定范围内的早/晚提升触发与精确 control 时，按需查看 [FP16 升精度：在首次信息损失前改变位置](../cases/fp16-promotion-boundary.md)；该案例不覆盖本页的其它算术、模式或编程模型。
+
+### 升 FP32 是否保住了下一个消费者需要的信息
+
+不要只因两个输入“同量级”就认定加法无额外舍入。在最近偶数舍入的 FP16 数值模型中，`1 + 1.0009765625` 的精确和为 `2.0009765625`，舍入为 `2`；两个输入本身都可由 FP16 精确表示。“同量级”与“单次运算无损”不是同一条件。相反，扩大中间 dtype 后立即转回原 dtype，也可能得到完全相同的出口值；是否有收益取决于信息在哪个消费者之前被保留。
+
+用 `a=1024`、`b=0.0625` 的有限正常数对照 `(a+b)-a`，逐步按同一最近偶数模型计算：
+
+| 实际路径 | 预测输出 |
+|---|---|
+| 加法后存 FP16，再减 `a` | `0` |
+| FP32 加法后立即转 FP16，再减 `a` | `0` |
+| 加法和减法之间保留 FP32，最后才转 FP16 | `0.0625` |
+
+这是可手算的舍入点对照，不是某个 Ascend C 调用的 NPU 验证。当前任务应先冻结输入位模式、每步 dtype、实际 RoundMode 和输出约定，再预测中间 checkpoint。若只是切换模式或重载才改变结果，不能归功于“FP32 更准确”；若输出约定只要求一次 FP16 加法，上表第三条也不能擅自替换该接口语义。
+
+在二进制幂边界两侧，邻近可表示值的间距可不同，加法和减法的舍入边界也不必对称。按输入位模式和目标间距扫描正负及 tie 两侧；固定量级比不能代替逐操作预测。链长与误差增长见 [累加、归约顺序与消减](accumulation-order.md)。
+
+## MX/E8M0 边界
+
+当前 `9.0.0/Ascend910B1/2201/kernel-direct` 固定 Cast 来源的 Atlas A2 表没有给出 MX 或 `fp8_e8m0_t` 组合，因此该 profile 下的 E8M0 编码、scale 轴、Cast 重载、舍入和特殊值语义全部保持 UNKNOWN。固定仓库中面向 950 的 fp8/fp4/MX 文档或样例不能外推到 910B1；其它环境中的 E8M0 公式和实现建议也需要核对当前产品及接口支持。确认之前不得把 MX 路径作为正式修复。
+
+在当前产品确实支持 MX 路径时，再核对 amax 到 scale 编码的算法与舍入位置。数据格式转换和 scale 编码是两件事；ceil/floor 偏移不能由症状直接选定，需比较解码后的 scale、归一化数值与目标格式范围。数据和系数地址的配对见[矩阵装载](../operators/matmul-mmad.md#装载布局与-scale-配对)。
+
+对 e4m3、e5m2、HiF8 和打包双分量类型，原始位模式必须连同具体格式、分量位置解释。先核对实际转换函数的舍入、饱和与特殊值，再比较数据和 scale 两条链；不同格式的相同字节不表示相同数值。
+
+## 区分实验
+
+1. 固定 API 输入位模式，只切换一个已被当前版本证实可用的模式或 dtype 路径。
+2. 同时比较 API 局部误差和最终误差；局部改善但最终不变时，继续寻找下游首次放大点。
+3. 保持计算路径不变，仅扩大一个中间 dtype，用来区分近似模式和过早降精度。
+4. 在敏感带两侧增加相邻样本，确认结论不是单点巧合或特殊值比较假阴性。
+
+## 修复边界
+
+优先选择满足当前 oracle、输入域和误差约定的正式模式；没有合适模式时，只能在触发域和副作用已完整刻画后做局部修复。不要把“统一转 FP32”“固定 clamp”或案例常量当成通用方案。回归必须覆盖原失败带、带外正常值、dtype 组合、特殊值和当前版本支持边界。
+
+加减法示例采用逐步舍入模型；设备上的实际舍入与中间精度仍需按当前 API 和位模式观察确认。

package/skills/asc-tools/tool-precision-debug/skills/tool-precision-debug/references/patterns/mechanisms/shape-boundary-contract.md

@@ -0,0 +1,57 @@
+---
+type: Mechanism
+title: Shape、Rank 与边界维度约定
+description: 分别核对逻辑 Shape、Rank、空维与边界映射，区分 shape 约定、broadcast 和 tiling 切分问题。
+tags: [Shape, Rank, 空维, 边界]
+---
+
+# Shape、Rank 与边界维度约定
+
+当空维、维度为 1、最小或极大 shape、reshape/squeeze 后的 rank 变化触发异常时，先验证 shape 约定，不要直接归因于 tail。Shape 约定描述逻辑维度是否合法以及如何映射；tiling 描述合法 shape 如何切分，broadcast 描述两个逻辑 shape 如何对齐，三者必须分开。
+
+## 建立 shape 账本
+
+同时记录 Host 推导值和 Kernel 实收值：原始 rank、每个维度、axis 规范化结果、输入/输出元素总数、空张量策略、维度 1 的保留或消除、动态区间以及选中的实现分支。对 reshape/flatten/squeeze 写出变换前后的坐标等式，不能只比较元素总数。
+
+## 支持与反证
+
+- 只在 rank、空维或维度 1 边界突变，并且 Host 与 Kernel 对 shape 的解释不同，支持 shape 候选。
+- 合法 shape 已一致传入，但错误从最后一个不完整 tile 开始，转查 [Tiling、尾块与跨 tile 状态](tiling-tail-state.md)。
+- 错误沿广播轴周期重复，转查 [广播与转置算子族](../operators/broadcast-transpose.md)；沿物理 stride 重复则转查搬运布局。
+- 相邻 shape 选择了不同 tiling key 或 kernel 符号，先检查动态分派，而不是修改通用 shape 公式。
+
+## 区分实验
+
+构造维度为 0、1、边界前一值、边界值和边界后一值的最小矩阵；每次只改变一个维度，保持 dtype、layout、核数和其他属性不变。保存 Host shape 推导、tiling 数据和 Kernel 入口值。若需要强制分支，预先写明每个分支的预测，并确认实际二进制采用了强制结果。
+
+### Rank-0、空维与维度 1 分账
+
+- **何时查**：标量、含 0 的维度、维度 1、squeeze/unsqueeze 或负 axis 规范化后结果突变时查询。
+- **查什么**：分别记录 rank、完整维度向量、逻辑元素数、axis 规范化前后值和输出 shape；rank-0、`shape=[1]` 与含空维 Tensor 在约定裁决前必须作为不同状态，不能因元素数相同或都“很小”而合并。
+- **怎么证伪**：按公开约定构造最小合法邻域，并对每个输入检查 Host 推导与 Kernel 实收完全一致；如果错误只跟最后一个 tile 的有效长度移动而不跟 rank/axis 状态移动，就降低 shape 候选。
+- **避免混淆**：空输出无需计算不等于可以跳过当前约定对 Host 校验、workspace 要求和输出 shape 的裁决；维度 1 上的周期复用转广播，合法 shape 的非整尾块转 tiling/tail，运行时选错实现转动态分派。
+
+### 等价 shape 的变形关系
+
+- **何时查**：reshape/squeeze 后才失败，或两个元素总数相同的 shape 走出不同结果时查询。
+- **查什么**：只在算子约定明确允许时，建立插入/删除维度 1、reshape 后逆 reshape、axis 随 rank 同步平移等变形关系；为每条关系写出输入坐标、输出坐标及预期不变量，不只写 volume 相等。
+- **怎么证伪**：用同一坐标编码数据跑原 shape 与变形 shape，并把结果映回同一逻辑坐标；若差异随物理 layout/tiling 改变而变形前后的 Host/Kernel shape 约定均一致，则降低纯 shape 候选。
+- **避免混淆**：变形通常会同时改变 kernel、tiling、连续性或多核分区；这些变化必须作为混杂单列。一次等价变形通过也不证明其它 rank、axis 或动态区间正确。
+
+### 动态区间的等号审计
+
+当自然问题是“511 正常、512 或 513 失败”时，先确认 512 是否真是当前源码或配置中的边界，而不是因为数字接近常见 tile 大小就假设它是边界。设真实边界为 `B`，逐项核对：
+
+1. Host 对 `B-1`、`B`、`B+1` 的合法性、rank/axis 规范化和输出 shape 推导。
+2. 每个相邻区间的谓词是否无空洞且无重叠，尤其是 `< B`、`<= B`、`== B` 和默认分支。
+3. Host 选择的分支、tiling 字段与 Kernel 实收字段是否使用同一边界语义。
+4. 三个输入的逻辑元素集合是否只改变目标维度；若核数、layout 或属性也变化，将其单独列为混杂。
+5. 每条分支分别处理整块、余 1 和最大合法 tail 时，输出 shape 与有效区是否仍符合公开约定。
+
+只有 Host 与 Kernel 在等号处采用不同区间、某个合法 shape 落入空洞/重叠，或强制正确分支后首偏离边界按预测移动，才支持动态 shape 约定候选。若 shape 已被双方一致解释而错误只从最后一个不完整 tile 开始，应转向 tiling/tail；若源坐标在广播轴上已经错误，则转向广播语义。
+
+相邻 shape 选择不同 kernel 是观察，不证明任何一条分支错误；511/512/513 全部通过也只覆盖该边界邻域，不证明整个动态区间。诊断性强制分支可能同时改变资源和调度，不能直接成为正式修复。
+
+## 修复与回归
+
+在 Host 和 Kernel 之间只保留一个明确的 shape 约定，显式拒绝非法输入；不要用 `max(1, dim)` 或固定最小 tile 静默改变算子语义。回归覆盖 rank、空维、维度 1、动态区间两侧以及与 broadcast、tail 组合的合法输入。

package/skills/asc-tools/tool-precision-debug/skills/tool-precision-debug/references/patterns/mechanisms/special-values.md

@@ -0,0 +1,122 @@
+---
+type: Mechanism
+title: NaN、Inf、溢出与次正规数
+description: 追踪特殊值首次产生位置，用未选支路污染、分类边界与小量放大的对照区分溢出和传播。
+tags: [NaN, Inf, 次正规数, 溢出, 分支, Cosh]
+---
+
+# NaN、Inf、溢出与次正规数
+
+先定位第一个特殊值的产生位置，再区分输入已有特殊值、有限值运算产生溢出、非法域、除零、Cast 饱和以及次正规数处理。最终输出出现 NaN/Inf 不说明最后一个 API 是根因。
+
+## 证据采集
+
+在候选边界保存分类掩码和原始位模式：finite、NaN、正负 Inf、正负零、normal、subnormal。对每个特殊位置追溯参与运算的输入和公式，不用 `nan_to_num` 等清洗先改变基线。
+
+### 先做类别分叉，再算有限值误差
+
+先在代表性失配坐标上区分数值类别，再解释相对误差：
+
+1. `NaN`；
+2. `+Inf` 或 `-Inf`；
+3. `+0` 或 `-0`；
+4. 有限非零，再细分 normal 和 subnormal。
+
+`finite -> Inf/NaN`、`Inf -> finite`、`+Inf -> -Inf` 和 `normal/subnormal -> ±0` 都是类别分叉，应优先定位首个分叉 checkpoint。`NaN -> NaN` 只能说类别可能一致；NaN payload、符号位或任意 NaN 是否算通过，仍由当前 evaluator 约定决定。
+
+保存能定位差异的坐标、计算步骤、actual/reference 类别，必要时附位模式，据此追踪首次分叉。若中间值符合预期而最终编码不同，再查后续 Cast、mask 和写回；输出规范化按项目规定处理。
+
+### 有符号零不能只看十进制打印
+
+`+0` 与 `-0` 的普通打印可能无法支撑判断，应同时保存位模式或 `signbit`。先查符号在哪个 producer 丢失，再观察下游除法、倒数、符号敏感分支或 CopyOut 是否将它放大为可见差异。只有 evaluator 定义符号零等价、且后续数据流不再观察其符号时，才能把 `+0/-0` 归并。
+
+输出都显示为零时，可向前比较首次类别变化的位置，区分正常舍入与更早的缩窄、抵消或特殊值传播。
+
+## 区分实验
+
+1. 在域边界内外取相邻值，区分数学域错误和普通舍入。
+2. 缩放输入但保持符号/结构不变，观察首次溢出位置是否按预测移动。
+3. 对次正规数使用正常量级对照和位模式对照；只有在输入相同且边界位模式可预测时才讨论 FTZ。
+4. 将特殊值传播与有效区分开，排除未初始化 padding 被计算。
+
+### 未选分支也可能污染结果
+
+先计算两支再以 `m*a+(1-m)*b` 混合，不等同于从两支中选择一个值。即使 `m` 恰好是 0 或 1，未选支路的 NaN/Inf 仍可能通过乘零传播。
+
+一个逐步 FP32 的合成例：仅在 `|x|<=1` 时选择多项式 `p=x-x^3/3`，否则选择有限的 `s=sign(x)`。对合法的有限输入 `x=2^100`，若仍在全域计算 `p`，`x²` 已溢出，后续可得到 `p=-Inf`；此时 `m=0`，混合式含有 `0*(-Inf)`，结果成为 NaN，而选中的 `s=1` 本应有限。普通量级 `x=1/2` 是对照。这只解释分支组合风险，不是 Erf 或其他函数的近似公式。
+
+可先保存同一元素的谓词、两支输入与输出类别，再检查合并步骤；不要只看被选支路。若决定使用真实选择或保护未选支路的计算输入，核对具体重载和生成代码，并保证有效支路、阈值两侧与特殊值语义不变。比较模式和 mask 覆盖还需单独验证，不能用算术混合绕过一个疑点又引入极值污染。
+
+### 有限与 Inf 分类边界
+
+稳定改写降低中间范围，不保证与 reference 的有限/Inf 交界完全一致。已知风险很窄时，用输入 dtype 的相邻可表示值检查，重复普通随机回归难以代替这一观察。
+
+例如实数恒等式 `cosh(x)=exp(|x|-ln(2))*(1+exp(-2|x|))`。可先在更高精度下由目标 dtype 的最大有限值 `Fmax` 推导 `|x|≈log(2*Fmax)` 的邻域；不要在目标 dtype 中先算 `2*Fmax`，否则构造输入时就可能溢出。将邻域量化到真实输入 dtype，再沿相邻位模式在合法域内选取两侧对照。
+
+| 观察点 | 要区分的候选 |
+| --- | --- |
+| `u=round_D(abs(x)-ln2_D)` | 输入、常量量化或减法舍入是否已改变边界 |
+| `v=Exp(u)` | 实际 API 的近似与分类边界是否首先分叉 |
+| `w=1+Exp(-2*abs(x))`，`y=v*w` | 后续修正项与乘法是否引入最终溢出 |
+
+保留 reference 与 actual 的类别、输入位模式和首个中间分叉；公式只用于设计候选观察，不要求项目采用这条实现。若只有最终有限/Inf 日志而没有中间值，保留多个解释。其他 Exp、缩放和饱和表达式按各自公式重新映射边界，不复制 Cosh 的阈值。
+
+### 有限输入的归约顺序也会改变非有限类别
+
+所有归约输入均 finite，不能排除中间加法溢出；不同的结合顺序可能分别产生有限值、单一符号 Inf 或 NaN。先确认归约入口的原始 FP32 值，再追踪两棵树中第一次溢出及后续传播，不能只查最终 Cast 或输入是否含 NaN。
+
+例如令 `A=2^127`，每步采用 FP32 最近偶数舍入，同一组有限输入的三种求值方式如下。这是可复算的数值模型：
+
+| 求值顺序 | 结果 | 中间原因 |
+| --- | --- | --- |
+| `(A + (-A)) + (A + (-A))` | `0` | 每对先抵消 |
+| `((A + A) + (-A)) + (-A)` | `+Inf` | 首次同号相加溢出，之后减有限数仍为 Inf |
+| `(A + A) + ((-A) + (-A))` | `NaN` | 正负两支分别溢出，再合并反号 Inf |
+
+因此应逐坐标比较 finite/NaN/正负 Inf，不能仅比较非有限值总数。若 evaluator 仅在双方 finite 的交集上计算误差，`mere=mare=0` 可能只是没有可比较的有限元素；还要读取 `finite_compared` 和类别失配。原判据对 NaN、Inf 的定义优先于某个通用相等函数。
+
+固定参与元素和初始 FP32 位模式，只改变结合树；或按二进制幂缩小输入作为溢出对照。缩放后恢复只支持范围/顺序候选，不替代原极值回归。FP64 或补偿求和即使更接近数学结果，也可能改变既定 FP32 reference 的类别，不能直接认定它满足验收。参考分派与实例分别见[分层归约](accumulation-order.md#框架参考的分层归约与主尾列分派)和 [GRU bias 案例](../cases/thnn-fused-gru-bias-reduction.md)。
+
+### Normal / subnormal / zero 三点与三阶段探针
+
+对“极小非零变成零”的症状，不要只测一个极小值。在目标 dtype 下构造至少一个明确 normal、一个明确 subnormal 和零；如果涉及符号敏感下游，再对正负分别构造。每个点用目标 dtype 的原始位模式定义，不用十进制字面量或打印位数猜测它属于哪一类。
+
+对同一组固定输入分三段保存位模式：
+
+| 阶段 | 可选择的观察边界 | 首次归零时的候选方向 |
+|---|---|---|
+| 产生 | 算术 API 或 Cast 的直接输出 | 该生产步的 dtype、舍入、模式或输入范围 |
+| 搬运 | 产生值写入后与消费前的相同逻辑元素 | Cast、长度/有效区、布局、同步或 Buffer 生命周期 |
+| 消费 | 下一运算的入口与直接输出 | 消费 API 的行为或对已归零输入的放大 |
+
+例如“产生处仍是极小非零，搬出后首次成为 `-0`”先把边界收缩到搬运或其中的 Cast/解码，不足以宣称产生 API 执行 FTZ；还要用 `+0/-0` 位模式、normal 对照和有效区证据排除符号、布局与越界问题。
+
+只有 subnormal 与零分叉、normal 对照仍通过，且首次归零阶段在重复运行中稳定，才提高 FTZ 候选的优先级。这仍不证明某 API 或模式的通用行为；需要当前版本权威文档或精确范围的硬件探针才能将它提升为事实。
+
+FP32 格式能够编码 subnormal；某个中间 FP32 结果是否实际保留，不能从 dtype 名称推断，需由当前 API 模式、位模式观测或权威文档确认。它与最终输出接近零或最终舍入为零是不同命题；不能仅因数值“很小” 主动清零。遇到极小值突然归零时并列核对三类机制：逐操作公式是否已 overflow/underflow、当前版本 API 模式是否规定 FTZ/次正规数行为、源码是否有显式 clamp、阈值或 zeroing。每类都要以首个分叉的位模式和单变量 trigger/control 判断；不要把某次设备观察推广为所有 API、模式或平台的规则。
+
+### 非法域先追 producer
+
+`Log`、`Sqrt`、倒数或其他有输入域约束的步骤首次产生 NaN/Inf 时，先将它的输入与当前 oracle 的同一 checkpoint 分类。如果两边都给出约定允许的特殊值，它可能是正常传播；如果 kernel 独有的非法输入在这个消费者之前已经出现，沿它的 producer 链继续向上追溯。
+
+对理论上应非负却得到微小负值的 `Sqrt` 输入，至少并列保留数值抵消/舍入、错 offset、未初始化读、有效区或同步错误等候选。只在当前算子约定明确规定保护时才测试对应保护；不用通用 clamp 或新增 epsilon 截断 producer 证据链。
+
+## 结论限制
+
+FTZ、特殊值传播和饱和语义依赖 dtype、指令和平台。没有目标版本文档或实测时保留未知，不把 CPU 或其他 NPU 的行为外推。修复不能仅屏蔽特殊值；应处理已确认的首个产生机制并回归正常值与边界值。
+
+改动影响多条特殊值处理路径时，选能暴露同类错误的输入检查相关实现。例如，直接选择零与将 NaN/Inf 乘零可能产生不同结果；修改或撤销保护后，补验受影响部分。
+
+## Oracle 与保护约定
+
+先确认 oracle 在同一输入、dtype 和逐操作公式下究竟产生有限值还是特殊值。实现额外产生 NaN/Inf，与实现把 oracle 的 Inf/NaN 改成有限值，是方向相反的失败。普通相对误差在 Inf 或 NaN 上可能产生假阴性，比较必须先按类别和位模式处理，再计算有限值指标。
+
+epsilon、clamp、减最大值和稳定公式都会影响算子语义。只有当前语义允许、已排除错误统计集或搬运链，并且单变量实验与边界回归支持时才可采用；不能为了让当前样例通过统一添加。对 Norm、Softmax、除法和对数分别冻结保护的位置、dtype 和顺序。
+
+## 次正规数与窄带放大
+
+把次正规数的产生、搬运和消费拆成三个探针，并在正常量级设置对照。若失败只落在很窄的输入带，沿后续乘除或分支计算局部差异的放大条件。FTZ、近似模式和特殊值传播属于版本/平台事实；旧案例观察只用于设计当前环境探针，不能外推为默认行为。
+
+消费端即使只收到零或一个 subnormal 差异，也要问后续大系数、倒数、归一化或分支会否把它放大为最终可见偏差；反过来，最终接近零也不能证明先前中间量已经归零。用同一逻辑元素的 producer、consumer 位模式和局部 oracle 区分这两种方向。
+
+设备探针记录版本、API 模式、dtype、输入输出位模式及观察范围。已有官方说明可直接引用；文档与实测冲突时，保留两者并检查实际产物和版本，暂不外推 API 或平台行为。