docs(design): split-KV decode attention design record (TLLM-ATTN-SPLITKV)

[holtwood]

设计记录（PR-A），不含任何代码。 按 L3_L4_DESIGN_REVIEW_PACKAGES.md §3 模板填写，为后续 hot-path kernel 改动取得批准载体。stacked on #10。

为什么（诊断，非猜测）

PR-5 的收尾建议是"修第 4 步的 V 访问"。profiler 数据推翻了它。 ncu（2026-09-14，visible=2048 / block_size=16）：

指标	值	读数
grid / block	(14,1,1) / 128	一个 block 一个 head，仅此而已
sm__warps_active（achieved occupancy）	8.33%	约 70 个 SM 里 56+ 个完全空闲
registers / smem	39 / 928 B	都不是限制因素
DRAM / L2 / L1 throughput	0.44% / 0.96% / 4.0%	没有任何资源饱和
long-scoreboard / barrier stall	45.8% / 38.6%	延迟无法隐藏 + 每个 tile 的 __syncthreads()

结论：并行度不足导致的延迟受限。第 4 步的低效是"只有 4 个 warp"的症状，不是原因——只重写它会治标不治本（grid 仍是 14 个 block）。

设计

• partial kernel：grid = (Hq, num_splits)，每块按 device 端 visible_tokens 现场算自己的逻辑区间（chunk = ceil(visible/splits)），产出局部 (m_i, l_i, acc_i)；combine kernel：grid = (Hq,1) 按 flash-decoding 公式合并。
• 保住 CUDA Graph 可捕获：num_splits 是 host 参数（grid 捕获时固定），可见长度仍走 device int，partial 缓冲预分配、捕获期零分配零 D2H。
• 不复制归约：decode_online_softmax → decode_online_softmax_range<Rows, kFinalize>，ContiguousRows/PagedRows、冻结的地址公式与零行语义全部不动。
• API 只增不改：新增两个 _splitkv 入口；既有 attention_decode/attention_decode_paged 保持 num_splits = 1 的等价语义，因此 ~18 个既有调用点不用改，单遍路径同时充当回归锚点与回滚点。C ABI 不变，与 paged-serving 无强制顺序。

需要 reviewer 明确决议的点

• Q3（唯一有真实爆炸半径的数值决定）：num_splits > 1 会故意打破 §10.2 的「contiguous 路径逐位不变」指纹（求和顺序变了，仍在 oracle 2e-3 容差内）；direct vs legacy 的逐位相等仍然成立（同一份循环）。
  缓解是 §4.4 的逐位锚点：num_splits = 1 时 exp(0)==1.0f、1/(l+1e-9) 不变 ⇒ 与今天逐位相同，从而把"重构风险"与"数值改动"干净分开。建议接受 Q3。
• Q1 combine 用独立 kernel（建议）还是单 kernel 信号量归约；Q2 num_splits 走 host 参数；Q4 partial 放 LayerWorkspace 新缓冲（不复用 direct 路径冗余的 k_scratch）；Q5 小 S 是否允许调用方回落到 num_splits = 1（不做内核内分支）。

验证

• 本 PR 只改文档：docs npm run build exit 0（修掉了一处指向 PR docs(design): TLLM-DPA direct paged decode attention design package (TLLM-P0-004 设计门禁) #5 未合入文档的死链）。
• 设计包自检 G0–G8 全过，明细见文末 §12。
• 未运行：任何 kernel 改动、测试与性能实验（本 PR 不产生代码与数字）。

限制

• 本包由实现者本人编写，不满足"实现 Agent 不应是唯一 reviewer"；§12 已记录该独立性缺陷。改动落在两条生产 attention 路径共用的热路径 kernel 上，与 PR-1 属同一类爆炸半径 ⇒ 合并前需第二方复核。
• 不声称任何端到端收益；kernel 级数字不得写成 TTFT/TPOT（G7）。
• num_splits 最优值、小 S 是否回归，均列为 §2 的 Unknown，由 PR-D 实测关闭。

后续

批准后：PR-B（kernel + 测试）→ PR-C（LayerWorkspace + 开关 + 路由）→ PR-D（benchmark + 结果报告）。默认值只在 PR-D 通过后才讨论打开。