docs(design): TLLM-DPA direct paged decode attention design package (TLLM-P0-004 设计门禁)

[holtwood]

这是什么

TLLM-P0-004（direct paged decode attention kernel）实现前的设计门禁产物。

按 ai-infra-interview-prep/L3_L4_DESIGN_REVIEW_PACKAGES.md §3 的标准模板填充，
覆盖 G0–G8 全部通用门禁，并逐条回答 §4（TLLM-DPA）要求冻结的决策点。

Status: DRAFT —— 未批准。 §12 的 Decision 保持 pending。
按 NEXT_AGENT_START_HERE.md §12「实现 Agent 不应成为唯一 reviewer」，
作者不代签；请在 §12 末尾的 6 个问题下给出判定。

为什么现在写它

任务卡的前置写得很明确：

前置与范围：必须先通过 direct-paged design package 和 TLLM-P0-002；
第一 PR 只允许 kernel/header/tests/benchmark seam，禁止同时改 FFI 与 serving。

TLLM-P0-002（独立 oracle）已在 PR #4 完成；没有批准的设计包时，L3/L4 Agent
只能读代码、列方案，不能改生产 kernel 的算法。所以这份包是唯一的前置。

冻结了什么（对应 §4 的必答项）

§4.2 待决问题	本包结论
block_table per-request 还是 batch-flattened	第一阶段 per-request（batch=1）；per-sequence 循环留在上层，不改架构
layer offset 谁算	caller 算，kernel 收本层指针（与现有 scatter/gather 一致）
table length 是否显式传入	显式传入 table_len，host 校验 >= ceil(visible/block_size)
visible_tokens 与 current position 的关系	冻结不变量：*device_visible_tokens == position + 1
是否只支持 batch=1、query_len=1	是（第一阶段）
支持几何	任何正 head_dim（smem 容量校验）；正式测试集 {32,64,128}
output/logsumexp	仅 output；不产 logsumexp
unsupported 是 error 还是 fallback	host 校验返回 Result；dispatch 回落 legacy 且计数/记日志

另外冻结了 §4.3 要求的完整线性地址公式与各级 stride、整数宽度（指针运算一律
size_t）、visible_tokens = 0 行为、以及 非法块 id 的语义。

三个值得 reviewer 注意的判断

1. 非法块 id = 零行但仍参与 softmax。PagedKvTest.InvalidBlockIdIsGuardedNotDereferenced
   已冻结 gather 写 0；而「K 行 = 0」在 softmax 里并非无贡献条目。若 direct 跳过它，
   归一化就会和 legacy 不同。这是有意的 legacy 等价，不是可选优化。
2. 不在 host 校验块 id。那需要 D2H 回读 → 破坏 CUDA Graph 捕获，而
   visible_tokens 走 device int 正是既有的 graph 前置条件。
3. 要求 direct 与 legacy 逐元素相等（而不是容差比较）。两条路径共用同一 tile loop
   与同一输入，因此可以要求零差异——这比容差门禁强得多，也是定位寻址错误的主门禁。

本 PR 的范围

• 只含设计文档 + docs 侧栏条目；不含任何 kernel 实现。
• 不改 C ABI，不改 paged-serving。设计结论是 C ABI 无需变更（PR-4 计划为空）。

验证

• docs: npm install && npm run build（vitepress 1.6.4）→ build complete in 10.93s，exit 0
• 无源码改动，CI Format / Build and Test 应保持原状

依赖

设计引用的独立 oracle 来自 PR #4（TLLM-P0-002，未合并）；PR-2 实现必须基于
PR #4 合并后的 master。

[holtwood]

修订：全部 8 项决议已关闭（2026-09-14）

按仓库 owner 委托，§12 的全部待决项已决议并回填进本设计包。

决议

#	议题	决议
Q1	flat vs POD view	flat（补上真正的理由：逐元素相等门禁覆盖了传参顺序这一失败模式）
Q2	共享 tile loop vs 复制	抽取；PR-1 必须附 attention_decode 前后性能对比，有可测回归则退回复制
Q3	非法块 id = 零行	冻结为稳定契约；可观测计数留作 follow-up
Q4	逐元素相等 vs 容差	严格相等
Q5	GQA 校验位置	改在 C ABI 载入边界 → 独立 PR #6
Q6	收益表述边界	接受：不得外推为 TTFT/TPOT
Q7	direct 下 scratch 冗余	本任务保留分配，显存收益记为 follow-up
Q8	按几何自动回落	取消（不可达且不可测），fallback 只由开关表达

本轮修正了设计包自身的三个缺陷

1. Q5 原表述是错的。原文写"连续版 attention_decode 静默取整，属既有缺口"，
   并提议在 forwardPaged 新增校验。查证后：Validator::validateModelConfig
   早已实现这组校验，只是全仓只有 InferenceEngine::Load 调用它，C ABI 路径
   tinyllm_load 不调用。而且后果比我原描述严重得多——不是"映射错位"，是越界读：
   已用最小复现 + Compute Sanitizer 证实（Hq=14/Hkv=3，13 errors，
   cudaDeviceSynchronize -> unknown error，CUDA 上下文被毒化）。修复已拆成
   独立 PR fix(ffi): validate model geometry at the C ABI load boundary #6（tinyllm_load 调用 validateModelConfig + Validator 首次有测试）。
   新增 §7.1 记录完整证据链。
2. Q8 原来是死代码。"几何不被支持则回落"要 head_dim > 7800 才可达——既不可
   测试，也不构成真实 fallback。已删除，只保留 TLLM_PAGED_ATTENTION 开关。
3. Q7 原未记录：direct 路径令 k_scratch/v_scratch 冗余，原文只写"保留校验"
   却没记录显存代价与 follow-up。

关于批准本身（需要你知情）

我把 Decision 记为 approved，因为决议是你的委托。但 §12 新增的独立性声明
如实写明：本包由作者编写、也由作者汇总决议，不满足「实现 Agent 不应成为唯一
reviewer」的要求。残余风险收敛到一点：

Q2 是唯一有真实爆炸半径的决定（改现有热路径 kernel）。建议在 PR-1 合并前
由第二方复核其 diff 与前后性能数据。其余决定要么有门禁兜底，要么只影响新增代码。

当前 PR 依赖关系

• test(paged): add GGUF-free paged/contiguous attention oracle (TLLM-P0-002) #4 TLLM-P0-002 oracle — PR-2/PR-3 的正确性前置
• docs(design): TLLM-DPA direct paged decode attention design package (TLLM-P0-004 设计门禁) #5 本设计包 — 本次修订
• fix(ffi): validate model geometry at the C ABI load boundary #6 C ABI 几何校验 — 与 TLLM-P0-004 解耦，可独立合并

验证：仅文档改动；docs npm run build exit 0（vitepress 1.6.4）。