docs: 补齐本轮优化的迭代复盘（8 篇迭代记录 + 1 篇测量纪律）

[NeverENG]

本轮所有优化的量化依据与修法理由此前只存在于 PR 描述里，按 docs/ 既有「一篇一事」格式落成文档。

迭代记录

文档	结论
read-path-syscalls	常驻句柄 + 单次整块读 + 块缓存 + 去分配：点查 12.6k → 18.7 万 QPS
write-path-attribution	一个拼错的配置键吃掉 4.83× 写吞吐；分片 WAL 被实测证伪（0.23×）
silent-data-loss	故障注入测出四处静默丢数据，含故障注入手法表
data-races	两处数据竞争，均在最热路径上
scan-covers-sstable	扫描曾只看内存表，下游投递漏投全部已落盘记录
retention	按已投递位点丢弃整份文件，及其六条保守约束的理由
iterator-buffered-read	一层缓冲读换来顺序扫描 24×、八路归并 17.4×
structure-and-sdk	包边界、依赖注入、对外 SDK、压测脚本此前跑不起来

测量纪律

docs/measurement-discipline.md 收录 9 条被真实误判换来的规矩：交替 A/B 抵消热漂移、压测口径要确认压到目标路径、先归因再优化、「优化无效」与「优化没生效」不可混淆、变异测试、故障注入的可移植手法、-race 是并发缺陷的必要条件、E2E 先怀疑自己、grep 计数要复核。

每篇都保留了「后续」里未解决的问题（投递游标按 key 序的语义边界、Raft WAL 缺故障注入、service 层未参数化等），不粉饰。

纯文档改动，无代码变更。

🤖 Generated with Claude Code

[coderabbitai]

Warning

Review limit reached

@NeverENG, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 33 minutes

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 375d8e81-ddef-4107-b9f3-95bd4944816c

📥 Commits

Reviewing files that changed from the base of the PR and between 1561b14 and 7e27d12.

📒 Files selected for processing (9)

• docs/iteration-2026-08-13-data-races.md
• docs/iteration-2026-08-13-iterator-buffered-read.md
• docs/iteration-2026-08-13-read-path-syscalls.md
• docs/iteration-2026-08-13-retention.md
• docs/iteration-2026-08-13-scan-covers-sstable.md
• docs/iteration-2026-08-13-silent-data-loss.md
• docs/iteration-2026-08-13-structure-and-sdk.md
• docs/iteration-2026-08-13-write-path-attribution.md
• docs/measurement-discipline.md

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}