cann-workbench 0.0.0-stage → 0.0.2-alpha

package/skills/asc-tools/tool-precision-debug/skills/tool-precision-debug/references/patterns/cases/sync-dataflow-handshake.md

@@ -0,0 +1,89 @@
+---
+type: Case
+title: 同步诊断：保护区域、条件路径与缓冲回收
+description: 通过同步代码分析示例，区分保护区域混用、条件路径漏通知与缓冲回收过晚，指导当前工程验证。
+tags: [同步, Buffer, 条件路径, 生命周期]
+---
+
+# 同步诊断：保护区域、条件路径与缓冲回收
+
+这组代码分析示例说明三类同步问题：保护区域混用、条件路径漏通知、缓冲回收过晚。用于选择排查方法，具体写法仍需按当前产品和工程验证。
+
+## 什么时候借用这些案例
+
+Set/Wait 看似配对，仍出现旧 tile、某个输出分支异常、条件卡死或多轮才失败时，先区分下面三条调查分叉。下面通过三种同步代码关系选择验证方法；它们用于提出待验证的候选，具体 event/flag 语义和修复效果须在当前版本、架构与工程中确认。
+
+| 当前观察 | 可能原因 | 先检查什么 |
+|---|---|---|
+| 只在多输出并存时异常 | 同步对象绑定错区域；临时 buffer 覆盖；输出地址/索引错误 | 各输出的最后写者、首次读者、真实 region、event 方向和申请身份 |
+| 特定条件或首尾轮卡住 | 发布路径被跳过；合法跨轮等待；参与核提前退出 | 初始化、条件成立/不成立、首尾轮各自的等待与发布路径 |
+| 首轮正常、复用 slot 后异常 | 数据就绪等待缺失；回收等待太晚；bias/索引绑定错误 | 同一 slot 上上一轮最后一次读取与本轮首次重写的先后关系 |
+
+区域账本和路径账本分别见 [Buffer 生命周期、绑定与别名](../mechanisms/buffer-lifetime-alias.md)、[多核分区、所有权与核间协同](../mechanisms/multicore-ownership.md)；依赖类型与 API 分流见 [流水同步与数据可见性](../mechanisms/pipeline-sync-visibility.md)。只展开与当前症状有关的分叉。
+
+## A. 多条输出路径共用同步对象
+
+修复前的 attention 输出使用 `stage2OutBuf`，LSE 输出使用 `commonTBuf`，两条路径共用 `mte3ToVId[0]`。LSE 的 `V_MTE3` Set/Wait 还引用这个按 `MTE3_V` 申请的变量。修复同时做了三件事：
+
+1. attention 与 LSE 分别申请并使用各自的两个方向 event；
+2. LSE 的 `V_MTE3` 使用对应方向申请的 `vToMte3LseOutId`；
+3. LSE 改用独立 `lseBuf/lseUb`，离开通用临时区。
+
+这支持同时检查“事件与数据路径的绑定”及“临时区复用”，不能把整份修复简化为改一个 event 名称。不同依赖类型下数字 ID 恰好相等也不自动是错误；核对的是申请类型、使用方向与生命周期。
+
+当前任务可先为两个输出填出各自的 `(物理根/基址, offset, 有效范围, generation)`，再追到 event 的申请、初始化、发布、等待和复用点。区分实验可按证据选择：
+
+- 只隔离一条输出的事件身份，保持数据区域与算法不变；若跨输出通知混用被消除而内容仍错，继续查临时区。
+- 只隔离可疑临时区，保持事件关系不变；若错误随最后写者或槽位复用消失，支持覆盖候选，但需排除同时改变对齐或越界落点的混杂。
+- 两条输出分别运行与同时运行，给输出使用不同哨兵模式；若异常完全不随二者交叠变化，降低事件共享候选的优先级，回查 producer 内容和输出地址。
+
+若两项隔离都需要才能恢复，分别检查中间 region 和通知顺序，允许组合缺陷。没有完整读写上下文时，“共用 event”只能是候选；已串行、无重叠且生命周期闭合的共享不能仅因名称相同被判错。
+
+## B. 装载可跳过，但后续仍需要发布
+
+在 Conv3D 的条件装载路径中，装载操作可以被跳过，但协作方仍可能等待通知。
+
+`ReduceKCloseL0PingPong`、`ReduceKOpenL0APingPong` 和 `ReduceKOpenL0BPingPong` 中，修复将 `DmaSyncSet` 或 group/weight 等 `*SyncSet` 从可跳过的 AL0/BL0 装载条件内部移到条件之后。装载分支不执行，不代表与它协作的后续搬运等待也被跳过。这是路径闭合问题，不能直接概括成“缺一条 barrier”。
+
+在当前工程列出至少两条路径：装载条件成立；装载条件不成立。对每条路径记录：等待者是否仍可达、等待的 region/轮次/方向是什么、哪个步骤证明可发布，以及初始化或其它路径是否已提供对应通知。
+
+- 若条件为假时等待仍发生，且找不到对应发布，支持条件遗漏；可只调整这条通知的条件或位置，再比较同一路径是否越过原等待点，保留条件成立路径作为 control。
+- 若条件为假时生产、消费和等待都跳过，条件发布可能完全合法；不应机械地外移。
+- 若等待依赖上一轮回收，先补首轮 seed、跨轮映射和尾轮收尾；不要把当前轮没有前置 Set 当成遗漏。
+
+移动 Set 前还要确认它表达的就绪或释放条件已经满足，避免用过早通知把死锁改成读旧值。不能把这份实现中的 `*SyncSet` 调用位置当作其它版本、其它协作路径的 API 规则。
+
+## C. 写入后再等回收，已无法保护这次重写
+
+bias 缓冲复用时，应分别检查上一轮消费结束和本轮搬入完成的通知。以下只分析这条局部依赖；跨核、跨卡同步需要另外验证。
+
+目标文件的修复把 `WaitFlag<V_MTE2>(eventUbBiasVMTE2List[ubListId])` 从下游位置移到 `copyGmToUbBias` 之前，并放入 `ptrBias != nullptr` 分支。写后仍发布 `MTE2_V`。结合初始化、消费者和 `ubListId` 轮转上下文，可以分出两条不同的依赖：
+
+```text
+上一轮 V 消费完 slot r → 回收通知 → 本轮 MTE2 可重写 slot r
+本轮 MTE2 写完 slot r → 就绪通知 → 本轮 V 可读取 slot r
+```
+
+半精度/bfloat16 bias 在 Cast 后发布回收；另一条 dtype 路径在广播加法消费后发布回收，因此最后读者应按实际 dtype 展开。首轮由 `InitFlag` 提供初始可写通知；收尾函数等待各 slot 的回收。
+
+当前工程若怀疑覆盖，可只把回收等待放到被保护的写入之前，记录复用 slot 的最后读者与新写者。预测是旧一轮消费不再读到新 bias，而 producer→consumer 就绪通知仍完整。若读写确无时间重叠，或错值仍精确等于另一个绑定的参数，降低回收候选，转查数据绑定与内容。
+
+对照应包括有/无 bias、不同消费分支、一个 tile 与足以重复使用 slot 的多个 tile。无 bias 时不可凭空等待一个不会产生的消费通知；只有一轮不发生复用的通过，也不能证明回收关系正确。具体实现是否需要显式等待、是否已由 queue/框架保证，须按当前版本及代码路径核实。
+
+## 防止误报的最小对照
+
+以下索引与循环对照用于检验候选能否成立，不能单凭静态形态判定设备故障。
+
+| 对照 | 正确的调查结论 |
+|---|---|
+| 同一个 index 变量后来从另一 loop index 重新赋值 | 分开追踪两次赋值；若两个 loop 值均为 1，仅凭重绑定不能证明运行地址不同 |
+| 同一 buffer 根上写 `idx * TILE`，读 `(idx - 1) * TILE` | region 不同是地址线索；还需核对 generation、环形复用及真实 producer/consumer，不能只看根变量 |
+| 多输出 bundle 使用不同 loop 派生地址，同步只使用其中一个 | 逐输出追踪；未展开完整 consumer/Wait 时，仅能产生错配候选 |
+| 非负整型索引的 `idx & 3` 与 `idx % 4` | 该范围内可等价；文本不同不能作为错配证据，不能泛化到任意模数或负有符号索引 |
+| 循环前 seed Set；每轮先 Wait、搬运后 Set；循环后 Wait | 可以消费上一轮通知并闭合收尾；首轮、每轮与尾轮均可达时，“Wait 在 Set 前”不是死锁证据 |
+
+最后一例使用核内 `MTE3_MTE2` event；它不证明跨核通知的作用域或参与集合。宏、alias、类型转换、有效范围和循环边界无法展开时，保留 UNKNOWN 并补地址/轮次观察。静态 finding 可被证据否定，静态零告警也不能替代这些关系的验证。
+
+## 回到当前任务验证
+
+选择与候选有关的首轮、重复复用、尾轮、条件真/假、参与核与输出分支回归；保留原失败输入和重复运行。用最小依赖修复验证首个分叉是否消失，撤销诊断用全局停顿或临时隔离，再检查精度、挂起、资源回收和产物采用。若多项修改同时生效，分别保留中间证据，结论只覆盖实际执行的路径。

package/skills/asc-tools/tool-precision-debug/skills/tool-precision-debug/references/patterns/cases/tail-valid-region-state.md

@@ -0,0 +1,30 @@
+---
+type: Case
+title: 尾块有效区与旧状态：先证明本轮写入
+description: 通过状态模型检查本轮有效区是否实际写入，区分尾块未写、读取范围错误与跨 tile 旧状态。
+tags: [尾块, 有效区, 旧状态, 状态模型]
+---
+
+# 尾块有效区与旧状态：先证明本轮写入
+
+最后一个 tile、最后一个 core 或条件分支后才出现旧值、零值或前一轮图样时，先把问题写成“本轮 producer 是否向消费者要读的有效 region 写过值”。本页用状态模型说明排查方法，实际接口行为按当前产品和版本核对。
+
+## 从症状建立竞争候选
+
+冻结当前 shape、分派、输入、产物身份和首个失配坐标，再记录该坐标所属 `(core, row, tile, stage)`、逻辑有效区和物理 padding。把生产边和消费边展开到 `(物理根/基址, offset, 有效范围, generation)`：若本轮 producer 写入不足以覆盖 consumer 的首次读，则同步文本是否配对不能解释内容正确性。
+
+尾块异常至少有四个竞争候选：Host 与 Kernel 对有效长度不一致；mask、搬出长度或地址把无效 lane 当成结果；本轮零工作量或跳过分支没有写目标 region，消费者读到了上一 generation；以及 buffer 在消费者结束前已被复用。它们可同时出现，因此不要用“加一条 Wait 后变好”合并结论。
+
+一个有限状态模型给出可复现的触发器：前一完整物理 tile 为 `[1, 2, 3, 4]`，本轮只产生两个有效值 `[10, 20]`。模型中的写后物理区为 `[10, 20, 3, 4]`，所以逻辑 consumer 应以 `valid=2` 得到 sum `30`、mean `15`；若错误地把整个物理 tile 都读进来，则得到 sum `37`、mean `37/4`。这不是设备内存或某个 DataCopy 的观察，而是把“本轮只写有效前缀”和“消费者误读整块”分开的精确有限对照。
+
+## 两个互斥的最小路径
+
+选择同一地址、同一输入和同一同步对象，只改变使 producer 做最小合法正工作或零工作/跳过的当前谓词。每次在 producer 前后记录目标有效区的值和 generation，并在 consumer 的第一次读前保存同一 region。正工作路径更新正确有效区而零工作路径不更新时，支持“未写本轮 region”；两条路径均已写却仍从边界开始错误时，转查 mask、地址映射或生命周期。
+
+对无效 lane 另设探针：使有效 lane 和 padding 的标识不同，再按当前输出约定只比较有效区。上例将后两个物理位置置零时，全范围 sum 恰好也为 `30`，会掩盖 sum 的错误；但全范围 mean 仍为 `15/2`，不等于逻辑 mean `15`。置成 `[100, 200]` 时，错误全范围 mean 变成 `165/2`。因此仅填零且一个 sum 通过不足以证明有效区正确；若当前算子约定允许中性 padding，它能否成为实现的一部分仍取决于约定，而 mean 必须使用实际 valid count。物理 padding 本身不是数学输出。
+
+## 对照与否证
+
+一 tile、恰好整除、余一个元素和最大合法尾块必须成对运行；同时保留一个会复用 slot 的多 tile control。若只在多 tile 才出现前一轮的标识，优先审计 slot 的最后读者与下一次写入；若单 tile 的尾块已错而 region 从未复用，优先审计有效长度和地址。改变 tile 大小、核数或 buffer 数会同时改变分派和调度，只能作为候选实验，不能单独确认 UB 容量或同步根因。
+
+修复应只让实际 producer 覆盖本轮有效 region，或让消费者只读取约定允许的有效区；随后回放原失败、边界两侧、连续重复、不同 core 所有权和实际会复用 slot 的路径。无法观察到地址、循环谓词或产物采用时，保留 `UNKNOWN`，不把稳定的旧值图样写成已确认根因。

package/skills/asc-tools/tool-precision-debug/skills/tool-precision-debug/references/patterns/cases/thnn-fused-gru-bias-reduction.md

@@ -0,0 +1,73 @@
+---
+type: Case
+title: GRU bias：参考归约次序、尾列与修复后的漏写
+description: 历史 GRU bias 归约案例，区分参考求和次序、主尾列分派及修复中新引入的可变计数漏写。
+tags: [GRU, 归约, 尾列, 可变计数]
+---
+
+# GRU bias：参考归约次序、尾列与修复后的漏写
+
+适合在“逐元素输出正常，bias 归约失败”“有限值指标正常，NaN/Inf 却失配”或“改归约后只剩规律性尾区错误”时阅读。p2 与 p3 的原始问题属于同一个归约顺序根因族；下文的计数副作用发生在另一次 Agent 修复中，不属于原始案例的第二个根因。
+
+## 实际计算链与观察边界
+
+ThnnFusedGruCellGrad 的输入为 `[B,H]` 的 grad_hy 和 `[B,5H]` 的 storage，后者包含 r、z、n、hx、hn。逐元素计算采用 FP32：
+
+```text
+gin = go*(1-z)*(1-n*n)
+gig = go*(hx-n)*(1-z)*z
+grg = gin*hn*(1-r)*r
+ghn = gin*r
+ig = concat(grg, gig, gin)
+hg = concat(grg, gig, ghn)
+```
+
+输出 0/1/2 分别为按目标 dtype 输出的 ig、hg 和 `go*z`。启用 bias 时，输出 3/4 分别沿 batch 维对未收窄的 FP32 ig、hg 求和，完成后才转换到目标 dtype；关闭 bias 时为空输出。
+
+因此输出 0–2 正常是优先调查 bias 支路的线索，不足以单独证明归约入口完全相同。特别是 FP16/BF16 输出，收窄会掩盖上游 FP32 差异；局部对照应检查未收窄值，而不是重新累加输出文件。
+
+## 两种表象，共用一个原始根因
+
+失败实现先做 chunk 内 `ReduceSum(RA)`，再做主尾配对和缓存树合并；group 路径还要经过 workspace partial 和第二阶段归约。参考代码则对连续 `(B,3H)` FP32 张量执行 CPU `sum(dim=0)`。双方参与元素相同，不保证中间舍入和溢出位置相同。
+
+| 案例 | 主要现象 | 有区分力的观察 |
+| --- | --- | --- |
+| p2 | 普通有限 FP32 输入，4 行公开失败集中在两个 bias；接近零的结果容易放大相对误差 | 比较未收窄输入、参考次序模型和设备的分块树；只换 FP64 不能证明满足原 FP32 reference |
+| p3 | 极值与低精度输入，bias 的 NaN/Inf 类别或位置失配 | 逐坐标分类，追踪首次溢出；公开 L0_030 的 bias 曾各有两个 NaN/-Inf 位置互换，有限值误差为零但没有可比较的有限元素 |
+
+有限输入经过不同加法树，也可能分别得到 finite、Inf 或 NaN，机理见[顺序与溢出](../mechanisms/special-values.md#有限输入的归约顺序也会改变非有限类别)。两例历史原始输出在各自两次回放中稳定；这支持确定性数值路径调查，但不凭稳定性单独排除地址、状态或同步。
+
+## 主列通过后，尾列仍可能采用另一棵树
+
+p3 尾列细化时记录的参考环境为 PyTorch 2.9.0+cpu、AVX2、单线程；设备记录为 CANN 9.0.0、Ascend950PR_9589、dav-3510、Kernel 直调。该参考环境的向量外归约在 `floor(3H/32)*32` 之前使用主列 cascade，后续列使用四路交错 `row_sum`；32 来自该路径的四路调度和 8 个 FP32 lanes，不是 NPU 的通用对齐要求。
+
+初版 p3 参考修复保留 batch 顺序并实现四层 cascade，公开集达到 595/595，但看护集仍为 17/20，剩余三行仅 input bias 的非有限类别失配。补齐尾列交错链、各链的 cascade、余数追加和最终合并次序后，历史记录为公开 595/595、看护 20/20。这个反例说明“用了四层 cascade”还不足以证明复现了整个 reference。
+
+从失败输出列反推路径时，保留原矩阵宽度与 stride。GRU 的两个 bias 各自是 `[3H]`，六个内部 segment 的逻辑列为 `(segment % 3)*H + aOff + col`；不能把 hidden bias 当作一个宽度为 `6H` 的参考张量继续累计列号。抽出单列再调用框架 sum 也可能改变参考路径，具体对照见[分层归约与主尾列分派](../mechanisms/accumulation-order.md#框架参考的分层归约与主尾列分派)。
+
+历史最终参考方案采用单行 R tile、关闭 group，并在设备端完成所需次序。这证明一种方案在记录范围内有效，不证明必须串行整个算子，也不提供性能合格结论。公开需求规定 FP32 归约和特殊值匹配，但未逐项写出该 CPU 结合树；固定 oracle 的实现依赖应由评测维护者确认，不能升级为 GRU 数学定义或自行修改测试的理由。
+
+## 修复过程中的另一种机制：可变计数污染后续输出
+
+另一次 p3 修复曾在 CPU 归约模型上通过大量非有限类别对照，设备端却出现新的整段漏写。`FinalBiasVfImpl` 在 input bias 尾段直接调用 `UpdateMask<float>(aLen)`，而后面的 hidden bias 段仍需要这个有效长度。该 API 消耗引用参数后，后续段看到的是零。
+
+在公开 L1_455 的修复快照中，`H=1743`，最后一个列块为 `aOff=1728, aLen=15`，每块容量为 64。前两个 input bias 段正常；第三段跨过参考主尾边界，在生成尾 mask 时消耗了 aLen；随后的三个 hidden bias 段均跳过写出。因此预测漏写位置为：
+
+```text
+[1728,1743)  [3471,3486)  [5214,5229)
+```
+
+这三个半开区间共 45 个位置，与该次保存的设备失配索引逐个一致。原始版本在同一用例仅有另一个位置失配；修复后的错误分布已经改变，不能继续只拟合求和树。
+
+同一候选的清零循环还在 `UpdateMask(remaining)` 后再次手工扣减一轮。按该快照的控制流和每轮 64 个 FP32 元素推算，3840 个缓存元素只覆盖了 1920 个；这是独立的初始化缺口，不能把它未经干预验证地称为全部 45 个错误的原因。
+
+保留跨段不变的有效长度，各段使用独立 remaining，并核对清零和写出覆盖，见[可变计数机制](../mechanisms/tiling-tail-state.md#可变计数被消费后续输出漏写与清零不完整)。上述定位由候选源码、API 语义和已存设备日志支持；修正该 Agent 候选后的完整 NPU 回归未记录，不能称为该候选已修复通过。
+
+## 怎样缩短下一次调查
+
+1. 先按输出区分逐元素、归约和写回支路；保存一组可复验失败，不必等全套测试结束才分析已经取得的错误。
+2. 从固定参考源码推导层级和主尾分派，用会区分候选的长度、列边界和有限/极值输入核对；避免将“16 行块顺序累加”外推到所有 B。
+3. 将通过的局部算术模型落实到设备时，核对相同输入、层级更新、余数、初始化、可变计数和写出范围。若错误结构变化，先检查新增 diff。
+4. 保存当前修改、实际通过范围与未决项，再运行必要回归；可复现挂起与数值超差分别报告，基线也挂起不证明候选已完整通过。
+
+历史最终参考补丁的两轮结果为 p2 公开 28/28、看护 20/20，p3 公开 595/595、看护 20/20；相应原始版本分别为公开 24/28、592/595，看护均为 4/20。这些是固定环境的既有设备记录，不是本次知识整理重新运行的结果，也不能证明更新后的 Skill 成功率已提升。

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

@@ -0,0 +1,34 @@
+---
+okf_version: "0.2"
+---
+
+# 故障模式与案例
+
+本目录沉淀容易出现精度异常的机制、算子特有风险和历史诊断经验。结合实际计算链、标记的敏感点与失败现象，查阅相关经验，形成有依据的候选并开展低成本验证；不必等到已有可疑区间才使用。
+
+系统定位取得新观察后，再针对异常环节核对相关经验。现象相似不等于根因相同，使用时检查当前输入、源码与环境是否满足适用条件。
+
+| 入口 | 什么时候读 |
+| --- | --- |
+| [通用故障模式](mechanisms/index.md) | 计算链涉及类型转换、累加、地址、缓冲复用、同步、尾块等敏感点，核对常见错误机制及触发条件 |
+| [算子特有风险](operators/index.md) | 根据算子族识别容易出错的计算阶段及诊断经验 |
+| [历史案例](cases/index.md) | 对照具体输入、错误现象与排查过程，借鉴关键观察和验证方式 |
+
+## 按症状选择检查
+
+下表将常见残差直接连到正文。选择与当前计算链吻合的入口，复用已有输入做一项有区分力的检查；不必遍读所有页面。相同症状可能有不同根因，检查结果再决定是否转向。
+
+| 当前症状或计算结构 | 相关章节 | 可先做的检查 |
+| --- | --- | --- |
+| Log/Atanh 近零误差突增，输出变零 | [近零逐步对照](mechanisms/accumulation-order.md#atanh-近零的逐步对照) | 保存 `x`、舍入后的 `1±x` 和输出，区分输入量化、加法吞没与函数近似 |
+| 加入多项式分支后，极大有限输入反而出 NaN | [未选分支与乘零混合](mechanisms/special-values.md#未选分支也可能污染结果) | 分别保存两支的类别，检查未选支路是否先溢出，再经乘零传播 |
+| Exp/Cosh 稳定改写后，只剩有限/Inf 交界失配 | [分类边界映射](mechanisms/special-values.md#有限与-inf-分类边界) | 在实际输入 dtype 的相邻可表示值上比较变换、Exp 和最终乘法 |
+| 分块 Norm 局部正常，合并统计或分母错误 | [状态更新时序](operators/normalization.md#统计状态的原地更新时序)、[迭代预算](operators/normalization.md#倒数与开方的迭代预算) | 用两个不等长、均值不同的块核对旧/新状态；统计正确后再查近似分母 |
+| 自适应平均池化在矩形、非整除或维度 1 上失败 | [小窗口对照](operators/reduction.md#自适应平均池化的小窗口对照) | 手列一个输出的半开窗口、坐标、count 与累加 dtype，先核对一个窗口 |
+| Softplus 首 repeat 正常、后段重复，或极负区小量归零 | [按残余症状查案例](operators/softplus-v2-grad.md#按残余症状进入案例) | 分别进入已有 repeat/mask 或 subnormal 支路，比较具体 lane 与首次归零步骤 |
+| SIMT/RegBase 等一条实现修好，另一 shape/dtype 仍失败 | [跨实现操作例](mechanisms/algorithm-parameter-contract.md#跨实现的小量放大对照) | 将同一数值条件对应到各可达实现，核对真实分派与各自中间量 |
+| 融合算子逐元素通过、只有 bias 超差，或主尾列类别分叉 | [GRU bias 案例](cases/thnn-fused-gru-bias-reduction.md) | 保留归约前未收窄值，核对当前参考的求和语义、主尾列与合并层级 |
+
+GRU 等历史案例先匹配当前需求与参考版本；要求已改变时，借鉴观察方法，不照搬旧求和树。修复后出现新的分段漏写时，再查[可变计数副作用](mechanisms/tiling-tail-state.md#可变计数被消费后续输出漏写与清零不完整)。
+
+快速验证的范围与退出条件见 [SKILL.md 阶段 3](../../SKILL.md#阶段-3定位问题与验证根因)，实验及系统定位的操作方法见 [diagnosis](../diagnosis/index.md)。接口参数与产品支持使用 `ascendc-api-knowledge-query`，算子实现示例使用 `knowledge-query` 查询；经验中的 CANN/NPU 或输入条件只覆盖正文明确说明的范围。

package/skills/asc-tools/tool-precision-debug/skills/tool-precision-debug/references/patterns/mechanisms/accumulation-order.md

@@ -0,0 +1,108 @@
+---
+type: Mechanism
+title: 累加、归约顺序与消减
+description: 通过归约树、主尾列与近零函数的逐步对照，区分累加顺序、消减和小增量吞没。
+tags: [归约, 累加顺序, 消减, Atanh, Log]
+---
+
+# 累加、归约顺序与消减
+
+误差随归约长度、tiling 或核数变化时，优先区分累加 dtype、分组顺序、尾块参与和跨核合并；同时记录输出尺度的变化。归一化曲线可辅助解释形态，不代替项目判据，也不能仅据曲线变平认定实现无误或阈值有错。
+
+## 确认比较目标
+
+按[比较与验收](../../diagnosis/baseline.md#数值相等与逐位一致)确认当前输出要求容差、数值相等还是逐位一致。最终位一致不自动要求内部归约树相同；项目明确规定求值顺序时，再核对该要求。
+
+查看当前相关节点的输入与累加 dtype、归约范围、输出 Cast 和 reference。FP32 累加改善但仍失败，只支持该干预与现象相关；残差还可能来自输入微差传播、求值顺序、中间收窄、参与集合或路径联动。即使残差仍随长度增长，也不能直接指定其来源。复用已有对照，按下面的局部比较选择下一项检查，避免重复尝试升精度。
+
+逐元素在阈值内不代表归约输入完全相同。需要区分输入微差传播与归约新增差异时，保留未收窄的实际归约输入 `x_obs` 和可信参考输入 `x_ref`：用已确认语义的同一独立参考 `R` 比较 `actual`、`R(x_obs)` 与 `R(x_ref)`。只比较前两项不能量化输入传播，也不能直接回查为上游原因；对照方法见[逐层分析](../../diagnosis/progressive-error-analysis.md#区分传播与新增偏差)。
+
+按某种分块顺序模拟的 `M` 与 actual 吻合，表示该候选能复现当前观察，不自动证明实际实现正确或残余必为固有舍入。高精度实数和是另一项数学观察；项目规定 FP32 求值顺序时，它不自动成为项目局部参考。先核对实际参与集、路径与参考语义，再解释差异。
+
+## 判断归约顺序是否相关
+
+浮点加法不满足结合律，元素集合相同也可能因分组不同而产生位差。根据疑点选择观察：
+
+| 当前疑点 | 有用的观察或对照 |
+| --- | --- |
+| 局部树、split 或尾块 | 比较相关边界前后的长度和每级配对，检查尾部元素是否参与 |
+| 分块或跨核合并 | 区分 chunk 内归约、partial 存储 dtype 和最终合并；局部结果正确不代表完整合并正确 |
+| 消减或特殊值传播 | 选择对顺序敏感的输入，追踪首次差异；必要时查[特殊值](special-values.md) |
+
+怀疑 pairwise 顺序，或项目要求复现该顺序时，从实际 reference 查 leaf、split、对齐与取整方式，不能仅凭 `n/2` 或库名推断。具体 CANN 重载的归约层级与支持条件使用 `ascendc-api-knowledge-query` 查询。
+
+## 框架参考的分层归约与主尾列分派
+
+逐元素输出正常、只有 sum/bias 超差，或者主列修复后只剩尾列失败时，检查参考实现自身的分派。`sum(axis=0)` 不足以描述实际加法次序；相同的归约长度也可能因未归约维宽度、stride、CPU SIMD 分派和线程划分而采用不同路径。
+
+先保留生成 golden 时的框架版本、设备、实际 CPU capability、线程数，以及归约输入的原始 shape/stride/dtype。Agent 本机的 CPU 或编译器检测值不能代替生成参考值的进程。源码可用时，直接沿该版本的分派条件和循环推导，再用少量对抗输入核对；反复拟合随机输出容易把局部规律当成完整算法。
+
+以 [PyTorch 2.9.0 的 SumKernel](https://github.com/pytorch/pytorch/blob/v2.9.0/aten/src/ATen/native/cpu/SumKernel.cpp) 为一个具体例子：对连续 FP32 矩阵沿非连续的 batch 轴求和，`vectorized_outer_sum` 在主列调用 `multi_row_sum`，剩余向量列和标量列调用 `row_sum`。以下只描述这条源码路径，不是所有 `torch.sum` 或 NPU ReduceSum 的规则。
+
+| 路径 | 实际次序中容易漏掉的部分 |
+| --- | --- |
+| `multi_row_sum` | 四层 FP32 accumulator 从 `+0` 初始化；正长度 `N` 的步长为 `2^max(4, floor(ceil(log2(N))/4))`。低层满块向高层累加并清零，末尾不足一块留在低层，最后按低层到高层合并 |
+| `row_sum` | 先将完整的四行组按 `row % 4` 拆成四条交错链，对长度 `floor(N/4)` 的链分别执行上述 cascade；空链保持零初值。各链层级合并完成后，剩余 `N % 4` 行依次追加到第 0 链，最后依次合并第 1、2、3 链 |
+| 主列与尾列边界 | 在上述向量外归约路径中，主列宽度是 `4 * V` 的整数倍，`V` 是参考进程实际使用的 FP32 SIMD lanes；参考宽度为 `C` 时，边界为 `floor(C/(4*V))*(4*V)`。不满足该分派条件时，应另查实际路径 |
+
+即使步长为 16，“每 16 行求和，再顺序累加所有 partial”也只实现了一部分层级：跨过 256、4096 等层级时，进位、清零和最终合并可能改变结果；更大归约长度还会改变步长。尾列也不是简单将所有行按模 4 分配到底，余数追加时机需要单独核对。
+
+### 能区分路径的低成本实验
+
+1. 固定同一列的 FP32 输入字节，比较实际 reference、按源码实现的主列/尾列模型与当前设备归约；高精度实数和另列为数学观察。逐步 FP32 舍入不可只在最后模拟一次。
+2. 按真实步长 `S` 选择 `S-1/S/S+1`、`S²` 附近和带不完整组的长度；按真实主尾边界选择相邻列。只覆盖当前候选会分叉的边界，无需枚举全部 `B×H`。
+3. 将相同数据复制到主列和尾列，保留整张矩阵的 shape/stride，再比较两列结果。另做原矩阵求和后取列与先抽取列再求和的对照；抽列、转置或 `.contiguous()` 可能改变参考分派，后者不能自动充当原节点的局部 oracle。
+
+下面的 FP32 示例同时假定输入能以 FP32 存储、相关加法按 FP32 舍入。输入 dtype 与累加 dtype 分别核对：只把 FP16 累加器改成 FP32，不会扩大 FP16 入口的可表示范围，`2^25` 不能原样用作有限 FP16 输入。先按实际入口量化、解码，再计算各顺序的预测；有意改成 FP32 输入时，说明它与原失败的范围差异。FP16 局部对照可参考[归约小窗口](../operators/reduction.md#自适应平均池化的小窗口对照)，按当前允许域和所需区分力选值、长度或观察面。
+
+一个可手算的区分输入是 `A=2^25`，某列沿 batch 为 `[A,1,-A,1,A,1,-A,1]`。在每步 FP32 最近偶数舍入、步长至少 16 的上述模型中，主列结果为 `1`，四路交错尾列结果为 `2`，精确实数和为 `4`。它说明“主尾列不同”和“更接近实数和”是不同观察；这是数值模型，不是特定 NPU 的实测结果。
+
+### 处置边界
+
+当前验收若要求与固定 reference 对齐，修复需覆盖实际触发的层级、主尾列、余数、输出 Cast 和合并阶段。可以并行处理互相独立的输出列；把归约轴重新切成任意 partial 再合并，仍可能改变目标次序。单行 tile、关闭 group 或更高精度累加是可选对照或特定实现方案，不能因一次通过就推广为通用修复，也不能忽略性能和 UB 代价。
+
+需求仅规定 FP32 求和，而固定 oracle 的特殊值规则事实上要求某种结合树时，保留这个可复现的要求差异，交由评测维护者确认；调试期间继续使用原判据，不擅自更换 golden、清洗特殊值或放宽阈值。案例及主列修复后的尾列反例见 [GRU bias 归约](../cases/thnn-fused-gru-bias-reduction.md)，溢出分叉见[特殊值中的归约顺序](special-values.md#有限输入的归约顺序也会改变非有限类别)。
+
+## 二叉树不等于按量级排序
+
+二分规定的是索引配对，不会自动把相近量级放在一起。例如令 `A=2^25`，每次加法按 FP32 最近偶数舍入：
+
+| 输入顺序 | 左折叠 `((x0+x1)+x2)+x3` | 半区折叠 `(x0+x2)+(x1+x3)` | 精确实数和 |
+|---|---:|---:|---:|
+| `[A,1,-A,1]` | `1` | `2` | `2` |
+| `[A,-A,1,1]` | `2` | `0` | `2` |
+
+同一树形在两组输入中分别改善和放大误差。这个模型不代表某个 NPU API 的执行顺序；用于当前定位时，应检查实际配对和中间 dtype 是否能解释观察。
+
+## 选择实验与回归范围
+
+可从正负大数夹小数、强消减、全同号或长度边界中选择能区分候选的输入。保持参与元素集合可比，单独改变累加 dtype、分块或合并顺序；怀疑尾块时增加完整块对照。
+
+修改共享归约函数或路由后，按实际受影响的调用方选择代表性回归。路由边界应有实现或资源条件依据；一个失败长度不足以确定整段输入都要改路由。`volatile` 或融合、展开开关可用于观察编译行为的影响，不能仅凭开关变化断定实际舍入顺序。
+
+对 count 重载，可由 dtype 计算每个 256B repeat 的元素数，核对 full repeats 和 tail；mask/repeat 重载则核对 mask、repeatTime 与 stride，避免混用两种调用方式。
+
+## 小增量吞没与量级扫描
+
+对 `log(1+x)`，比较 `s = round_dtype(1 + x)` 与 `y = log(s)`。若 `s` 已等于 `1`，信息在加法处丢失，扩大下游 dtype 不能恢复；若 `x` 更早已量化，还需区分输入量化与加法吞没。
+
+在正负两侧扫描邻近量级，找出 `1+x` 首次不再舍入为 `1` 的边界。阈值由实际 dtype、模式和位模式确定，不照搬常量。稳定公式或补偿算法的采用，仍以项目语义和目标 API 支持为准。
+
+### Atanh 近零的逐步对照
+
+若 Kernel 使用 `0.5 * log((1+x)/(1-x))` 或两项 Log 相减，先展开实际的 Add/Sub、Div、Log 和缩放，不直接把整条链当作一次高精度 Atanh。下面是保留 normal 值、逐步 FP32 最近偶数舍入的数值模型，不是某个 NPU API 的实测结论：
+
+| 输入 | `round_fp32(1+x)` | `round_fp32(1-x)` | 对数比值链 | 高精度数学参考 |
+| --- | --- | --- | --- | --- |
+| `x=2^-26` | `1` | `1` | `0` | 约为 `x`，非零 |
+| `x=-2^-26` | `1` | `1` | `0` | 约为 `x`，非零 |
+
+这里的 `x` 本身是 normal，信息在加减处已消失；不能把最终为零直接归为 FTZ。另选使 `1±x` 已可区分的普通量级对照，保存相同输入字节、`1±x`、比值和 Log 输出，找出首个分叉。实际实现若用两项 Log 相减，就保存那条链，不换模型来拟合结果。
+
+参考必须使用实际输入 dtype 量化后的 `x`，并先核对当前验收是否包含近零区。奇次展开或 `log1p` 风格的表达式可作为约定允许时的候选，截断误差、切换范围、特殊值和目标 API 支持需要分别确定；本例的输入不充当生产阈值。更早发生 FP16 桥接时，先查[升精度位置](../cases/fp16-promotion-boundary.md)。
+
+## 判断结果
+
+顺序或 dtype 的改变能按预测解释误差变化时，才支持相应候选；单个样例改善不能独自确认根因。
+
+若单块正确、partial 合并后才错，可查[Partial 统计合并](../cases/partial-statistics-merge.md)，区分不等长状态、空 partial 和合并公式问题。

package/skills/asc-tools/tool-precision-debug/skills/tool-precision-debug/references/patterns/mechanisms/algorithm-parameter-contract.md

@@ -0,0 +1,118 @@
+---
+type: Mechanism
+title: 算法公式、常量与参数槽位
+description: 核对公式、槽位与分段判据，区分重结合和临界中间值的类别分叉，并检查跨后端小量放大。
+tags: [算法公式, 参数槽位, 分支, 浮点语义, SIMT, RegBase]
+---
+
+# 算法公式、常量与参数槽位
+
+输出等于某个中间量、分支恒不触发、不同 dtype 路径出现完全不同症状，或 SIMD VF 编译无告警但全域失配时，优先核对公式和参数槽位。类型相同的裸指针、重复缓冲和复制出的调用点会让位置错配逃过编译检查。
+
+## 公式与槽位表
+
+先画当前实现实际执行的逐步公式，不用“数学等价”跳过浮点顺序。再为每个调用点列出：形参位置、实参变量、逻辑角色、dtype、地址/槽位、生产者、最后写入点和消费者。CopyOut 的源槽位必须单独列，不能假设它随 VF 输出角色自动变化。
+
+遇到 VF 时先按当前版本 API 文档确认 SIMD、SIMT 或混合调用模型与执行域，再跨调用文件和定义文件完成账本。寄存器、mask 和标量实参在调用点可能缺少类型语义提示；编译成功只能证明语法和静态约束通过，不能证明实参顺序、读写方向、有效 lane、UB 接力槽位或 helper 执行域兼容。
+
+## 乘除重结合的有限精度分叉
+
+遇到 `a*(b/c)` 与 `(a*b)/c` 的改写时，把两条链分别按目标 dtype 展开，不能只写实数域等式：
+
+```text
+q   = round_D(b / c)
+y_A = round_D(a * q)
+
+p   = round_D(a * b)
+y_B = round_D(p / c)
+```
+
+两条链的中间舍入、overflow、underflow 和非法运算位置不同；最终数值接近也不能证明位级约定相同。有限值的舍入差也可能超过较紧容差，是否失败要按实际比较器计算，不能只在逐位约定时检查。先冻结目标舍入模式、FTZ/subnormal 行为、是否融合以及 NaN 比较规则，再构造能让中间数值类别分叉的 trigger。以下是 IEEE binary32、逐操作 round-to-nearest-even 且保留 subnormal 时的通用区分输入；`Fmax=0x1.fffffep+127`，`minSub=0x1p-149`：
+
+| 目标 | `(a,b,c)` | `a*(b/c)` | `(a*b)/c` |
+|---|---|---|---|
+| 中间乘法 overflow | `(Fmax, 2, 2)` | `Fmax` | `+Inf` |
+| 中间除法 underflow | `(2^24, minSub, 2)` | `+0` | `2^-126` |
+| overflow 后非法除法 | `(Fmax, 2, +Inf)` | `+0` | `NaN` |
+
+平台若启用 FTZ、采用其它舍入模式或把表达式融合，以上具体位模式可能改变；此时用目标 dtype 的 `nextafter`/位模式扫描生成满足同一分叉谓词的输入，而不是照搬常量。逐步保存 `q/p/y` 的数值类别和 bit pattern；signed zero 与 NaN payload 是否参与 bitwise 验收由当前约定的特殊值相等关系决定，不能从 `bitwise` 标签自行推导。由运算产生的 NaN payload 若无项目 oracle 或版本来源约束，保持 `UNKNOWN`，只把数值类别作为当前实验结论。
+
+有限/Inf 分叉也可能来自中间值的微小差异。以相同的 binary32 乘法为例，`2*(Fmax/2)` 为 `Fmax`，而 `2*nextafter(Fmax/2,+Inf)` 溢出；因此两个 Exp 实现即使都返回有限值，也可能经后续乘法形成类别差异。这里是算术示例，不预设某个设备 Exp 的误差。区分 Exp、乘除顺序和阈值分支时，核对实际分支及对应中间值；只看最终类别或阈值相关性不能把这些解释分成互斥项。
+
+### 先核对参考的实际行为
+
+任务已规定的 dtype 与求值顺序直接沿用。项目 golden 若调用框架 API，确认实际版本和 dtype，再从对应实现或小规模调用核对求值方式；若与明确要求不一致，记录需求与参考实现的冲突，不把明确要求改成另一种待选约定。数学文档写成乘某个比例，不足以证明内部先算该比例；自建的“稳定版 golden”也不能替代项目 reference。
+
+区分输入应让两个候选给出不同的类别或数值预测，再配普通量级对照；仅在两条链都有限且接近的样本上回归，无法排除重结合问题。某个溢出 trigger 超出合法域，只排除了该输入作为失败证据，不能据此宣称其余域内安全；仍按当前疑点检查合法域内的有限舍入差或其它分叉。若 reference 允许中间溢出，有限结果不自动更符合验收要求；任务确实只规定高精度 reference 与容差时，按该要求判断，不强制复刻未被要求的中间顺序。一个实际漏查例见[Softplus 浮点语义支路](../cases/softplus-v2-grad-family.md#支路-c浮点语义而不是实数恒等式)。
+
+## 分段与稳定公式的跨实现一致性
+
+同一分段或稳定公式若由 SIMT、SIMD、RegBase 等并列实现，它们都应满足同一公式的定义；一条路径修复或通过不足以外推其它路径。分别审计各实现的分段谓词、常量、逐操作顺序与 dtype/舍入点，再按当前约定覆盖普通域、分段边界、深尾及适用的特殊值。没有 visible case 的实现仍须判断其是否可达；不可达或无法确认时保留 `UNVERIFIED`，不把某个后端的结果写成跨实现结论。
+
+修改影响多条公式实现时，选择能暴露同类差异的输入检查相关路径。普通输入通过不能说明深尾、分段边界或特殊值也正确；按实际影响补充代表性对照。
+
+若某条路径的公式修复后来因编译器、资源或回归问题被撤销、换写或改成路由替代，撤销前的验证不再证明最终实现。重新核对最终谓词和操作链，并把同一分段/深尾 trigger 回放到最终仍可达的每条实现；路由替代只证明该配置走向了合规实现，不证明被绕开的实现本身正确。
+
+### 跨实现的小量放大对照
+
+门控、sigmoid 或其他指数链在一条后端修好后，用同一数值条件核对另一条可达实现，而不是只搜索相同常量是否出现。先从实际 Host 条件确定各自的 shape/dtype/可选输入，再填写一张小表：
+
+| 实现 | 实际触发条件与分派证据 | 相关数值链 | 当前结果 |
+| --- | --- | --- | --- |
+| 路径 A，如 SIMT | 从当前 tiling/dispatch 读取，运行时核对 | Exp、缩放、恢复与输出消费 | 已确认的输入与误差，或未验证 |
+| 路径 B，如 RegBase | 独立核对，不由路径 A 推断 | 对应公式及各步 dtype/舍入 | 单独记录，不能沿用 A 的通过结果 |
+
+例如只考察 FP32 子表达式 `y=a*sigmoid(g)`，在合法域允许时选 `g=-100、a=2^100`，并配普通量级 `g=-4`。若某条实现先将极小 sigmoid 因子归零，大系数相乘也无法恢复；更高精度数学结果仍非零。保存 `g`、因子、放大前后值，区分“产生时归零”与后续搬运/消费。这里不预设 Exp/FTZ 行为，也不将此子表达式替代整个 SwiGLU 梯度 oracle。
+
+两条路径可能需要不同的合法 shape，无法在同一 shape 强制切换时，保留同一局部数值分布并说明布局/归约等差异。最终各自回到原分派、正式输出和比较器；临时强制后端只是一项诊断对照。小量的分阶段检查见[特殊值与窄带放大](special-values.md#次正规数与窄带放大)。
+
+## 小量级输入与稳定公式边界
+
+遇到 `log(1+x)` 等结构，记录实现真正执行的 `s = round_dtype(1+x)`、`y = log(s)`，不要用实数域等价式替代逐操作链。保存 `x`、`s`、`y` 的值与位模式；若 `x` 或 `s` 已在窄 dtype 中丢失信息，后续扩大 dtype 不能恢复。先用量级扫描定位首次分叉，再判断问题属于输入量化、加法吞没还是后续函数近似。
+
+`log1p` 风格的稳定公式只有在算子 oracle、输入域和特殊值约定允许时才是候选。对照至少覆盖接近零的正负值、`+0/-0` 和普通量级输入；只有当前约定明确覆盖 `x=-1` 邻域时才测试该边界及两侧，否则将域外点记为 out-of-scope/UNKNOWN，不能用未定义输入裁决实现。比较中间位模式而不只看最终容差。具体 Log/稳定变体是否存在、支持哪些 dtype 与模式属于版本 API 强事实；应查询对应版本的官方文档，缺少权威证据时标为 UNKNOWN，而不是从旧案例或函数名推断。
+
+## GMM shape、offset 与 per-token 参数槽位
+
+第二组开始整体错位、某组输出像取了相邻组 weight，或每行误差倍率能匹配另一 token 的 scale 时查询本节。对每组把 `M_g/N_g/K_g` 的生产者、字段单位和消费者写入同一表；再分别列出 A/B/C、bias、channel scale、token scale 的 base/prefix/span。一个 `groupList` 值究竟是组大小还是累计边界必须由当前算子约定或实际 host 生产代码证明，不能仅凭变量名决定。
+
+若当前约定是把各组 token 行连续拼接，并为每个逻辑 token 提供一个 scale，则候选索引应显式写成：
+
+```text
+token_base[g] = sum(M_h, h<g)
+token_global(g, i) = token_base[g] + i
+scale_used(g, i, j) = per_token_scale[token_global(g,i)] * channel_scale(g,j)
+```
+
+这是待验证的数据流公式，不是所有 GMM 的通用约定。固定 9.0.0 QuantGroupMatmul 样例确实使用累计 M offset 取得 per-token scale，当前 Matmul/Mmad 接口使用 `ascendc-api-knowledge-query` 核对；其它 GMM 若采用累计 groupList、per-group scale、per-block scale 或不同布局，应按其有依据的约定重建，缺证据保持 UNKNOWN。
+
+验证时为不同 group/token/column 赋予互不相同且可精确表示的 scale 哨兵，令单位基 Matmul 只激活一个 `(g,i,j)`，同时保存读取的 token index、scale 位模式、workspace 值和最终倍率。依次测试首行、组内末行、下一组首行、空组之后首行和尾组末行。若错值稳定等于相邻 token 的预测倍率，支持索引候选；若 Cube/workspace 已错，则该实验不能归因于 scale。把 channel scale 与 token scale 同时改成 1 只是一项组合观察，不能区分两条索引链。
+
+group shape、offset、scale 角色与量化 dtype 必须由当前算法和布局约定确定；scale 哨兵与局部 oracle 只用于区分候选，不能决定广播 API 或实现常量。
+
+## 支持与反证
+
+- 错值反解能稳定匹配“用了另一个操作数/常量/中间槽位”的预测，强烈支持参数约定候选。
+- 只修正注释或变量名不改变输出，不能证明问题已修复；必须确认数据流和生成物变化。
+- 形参与实参逐位一致时，转查公式顺序、初始化常量、分支谓词或上游值。
+- 只在某个 tile 后出现旧槽位值时，同时检查 buffer 生命周期和跨 tile 状态。
+
+## 区分实验
+
+使用可区分的哨兵填充每个逻辑槽位，选择能让分支输出不同结果的最小输入。一次只交换一个实参、常量或 CopyOut 槽位，并预先计算预测输出；枚举所有调用点，包括 cast 与非 cast 路径。对公式顺序，在 CPU 上逐操作复现目标 dtype 和特殊值规则，不用高精度化简式代替。
+
+对每轮 VF 另核对有效 lane、tail mask、寄存器是否由本轮写全，以及分支判据读取的是原始语义量还是已被 clamp、cast 或覆盖的中间值。启发式静态审计只能排序嫌疑，最终仍以数据流和区分实验为准。
+
+## Clamp 与分支判据的数据流分叉
+
+当分支几乎恒定、只有阈值附近失败，或日志显示进入分支前同一槽位已经被 clamp/cast 覆盖时，查询本节。把一个变量名拆成至少三个语义角色：原始输入 `x_raw`、用于安全或近似计算的 `x_eval`，以及分支谓词实际读取的 `x_pred`。分别记录它们的槽位、最后写者、dtype 和位模式；同名复用不能代替这张数据流表。
+
+默认应保留原始语义量供约定定义的谓词读取。若实现先执行 `x_eval = clamp(x_raw, ...)`，又让后续谓词读取被覆盖的 `x_eval`，clamp 可能把原本位于阈值两侧的输入压到同一点，使条件恒真或恒假。但“分支必须读原始量”仍以算法 oracle 为前提：若公开语义明确规定对 clamp 后的量分支，则 `x_pred=x_eval` 可以正确；缺少该依据时将分支输入语义标为 `UNKNOWN`，不靠数值稳定性猜约定。
+
+区分实验同时选择谓词两侧的 trigger/control，并先确认两个分支在这些点的预测输出确实不同；若两支因舍入、饱和或特殊值处理得到同一位模式，该输入只有 `NO_DISCRIMINATION`，即使运行通过也不能排除谓词错误。一次只改变 `x_pred` 的来源，保持 clamp、公式顺序、dtype 和 CopyOut 不变，再检查分支选择、首个分叉点和最终输出是否符合事前预测。
+
+反例：极大输入下两条分支都舍入到同一有限值，用该点观察到“切换前后无差异”，不能反证分支读错。另一个反例是为避免函数域错误而由算法约定明确要求先 clamp 再判断；此时强制读取 `x_raw` 反而扩大了语义。正式修复应保留两个角色或使用不易混淆的槽位，不能只改变量名；案例中的 clamp 常量和触发阈值不作为通用事实。
+
+## 修复与回归
+
+修正受影响的调用点，清理诊断哨兵，让变量名和注释明确区分槽位角色。根据改动选择相关 dtype 路径、分支边界或 tile/writeback 用例；API 调用语法与参数支持仍查询官方文档。