docs(architecture): audit context compaction

[fxl112233]

Summary

• Audit the paired Context and compaction architecture chapters against the current Runtime, Runtime Host, and SQLite storage implementation.
• Correct checkpoint-before-prune ordering, atomic AgentRun event/projection persistence, and the current replay-fit policy.
• Document structured-summary admission, one bounded repair, malformed-input retry fingerprinting, and the absence of a compaction-only output cap.
• Refresh both code/test maps and set the paired documents' last_verified date to 2026-08-28.

Refs #3522

Verification

• npm run format:check — passed (1,706 files)
• npm run lint — passed (2,845 files)
• npm run check:asf-headers — passed
• npm run build — passed
• npm run typecheck — passed after building workspace dependencies
• Focused Runtime/Storage suite covering the 10 documented verification files — 611 passed, 0 failed
• Explicit path/symbol audit — all 24 documented paths and 10 named runtime symbols resolved

AI use

Select exactly one:

• No generative tool made a substantive contribution
• Generative tooling made a substantive contribution

Tool(s) and scope: OpenAI Codex audited the current implementation, drafted the synchronized English and Chinese corrections, ran verification, and submitted the PR under @fxl112233's direction. The commit includes the required Generated-by: OpenAI Codex trailer.

Checklist

• Tests cover the change and fail without it
• Lint, format, typecheck and the affected suites pass locally

Does this PR entail a change in behavior?

• Yes — described under Summary above
• No

[Astro-Han]

This is a synthesis of the independent blind review by @Sol-404ARE at exact head 81546ed34be0079b53878791653235ab00bf6c84 (base ff226aff2f3082e54300dea0ee9e410898ae2c0f, 2 files +108/-76). I verified the diff and the exact-head CI myself; the file:line findings below are from Sol's sealed review.

What I checked myself:

• Read gh pr diff 4046 (audit: llm-compaction-events-log-projection-draft 2 files) and confirmed the edited failure table now claims implementation_status: current / last_verified: 2026-08-28 while stating that an empty/initial V2 summary retains a bounded raw tail and emits context_compaction_failed_open.
• Checked exact-head CI: label run 33112332075 SUCCESS, test run 33112332673 action_required (not green), Windows recovery likewise pending, OPEN/MERGEABLE/BLOCKED/REVIEW_REQUIRED.

Findings from Sol's review (file:line anchored):

Standards — GO (0 P0–P3)

• No Standards finding. ASF header audit, git diff --check PASS, worktree clean, Markdown ignored by Biome (0 files), PR body reports 611/611 focused tests.

Spec — NO-GO — 1×P2 (worst P2)

• P2 — The refreshed “current” architecture contract still describes the wrong automatic first-compaction failure outcome — docs/architecture/llm-compaction-events-log-projection-draft.md:394,405 (and .zh-CN.md:394,405) says an empty/initial V2 summary retains a bounded raw tail and emits one visible context_compaction_failed_open note. In the automatic pre-turn path this is false: packages/runtime/src/ai-sdk-compaction.ts:356-372 returns failure without replacing the raw context; ai-sdk-backend.ts:3625-3648 then returns context_budget_exhausted; :1823-1835 emits only the terminal complete and returns before the token-usage/note path at :2900-2914. The exact regression at ai-sdk-backend.test.ts:6128-6195 injects an empty summary plus BLANK_RETAINED_TAIL and then asserts zero provider calls, zero checkpoint writes, and terminal context_budget_exhausted — so the automatic initial failure neither continues on a tail nor persists the promised note. Manual compaction is different: runtime-kernel.ts:1075-1084 does append the note on failure. The docs should distinguish automatic over-budget terminal exhaustion from manual failure, or the runtime/tests should be changed. The wording predates the patch, but because this PR audits and refreshes the failure table and certifies current/2026-08-28, it newly certifies the incorrect contract.

Remaining changed claims were verified as consistent: checkpoint replay before stale-result prune, AgentRun canonical event plus bounded projection committed atomically and recoverable from ledger, replay budget/strictly-smaller gate, structured summary/one-repair/16-entry fingerprint — all match implementation; the Chinese and English hunks are structurally synchronized and all 14 production paths + 10 test entries exist. Entropy is neutral.

What I did not judge: the broader compaction loop beyond the two failure paths was not re-executed — verification was by code inspection and the referenced regression noted above.

Gate: one P2 docs Spec remains; label green but test/windows_recovery are action_required (not SUCCESS), so head 81546ed is not yet merge-ready despite Standards GO. Fix the automatic vs manual failure description in both docs and await workflow approval with terminal CI green. Seal: notes/pr-4046-provisional.md.

---

Automated review notice: This comment was posted by an automated review agent operated by Astro-Han. It is not an independent human review and does not replace one.

[fxl112233]

Addressed the P2 finding in commit 38b79fc.

The English and Chinese chapters now distinguish the two implemented failure paths:

• automatic pre-turn compaction keeps the original source-derived projection and terminates with context_budget_exhausted without persisting a failure note when it remains over budget;
• manual compaction records one visible context_compaction_failed_open note.

Verified against ai-sdk-compaction.ts, ai-sdk-backend.ts, runtime-kernel.ts, and the empty-summary regression in packages/runtime/src/__tests__/ai-sdk-backend.test.ts. git diff --check passes, and the paired chapters remain structurally aligned (559 LF lines and 27 headings each).

The upstream workflow still requires maintainer approval before CI can run.

[YayoiNanoka]

PR Assessment

What problem does this PR solve?

The paired context-compaction architecture chapters had drifted from the current Runtime and SQLite implementation. The stale claims covered checkpoint/prune ordering, checkpoint persistence, replay admission, structured-summary validation, and failure behavior.

How does this PR solve the problem?

It synchronizes the English and Chinese chapters with the current implementation. This is a documentation-only change; it does not alter Runtime behavior.

Is the problem correctly defined?

Correct.

The principal drift is confirmed against the implementation:

• checkpoint replay precedes stale Tool Result pruning;
• text compaction has no dedicated 4,096-token output cap, and output-length completions are rejected;
• structured summaries are validated, receive at most one repair attempt, and unchanged malformed inputs are circuit-broken;
• the canonical AgentRun event and bounded checkpoint projection are written in one SQLite transaction;
• replay is gated by the current history budget and, where comparable, must be strictly smaller than its source;
• automatic pre-turn failure and manual compaction failure have the distinct observable outcomes now documented by 38b79fc.

Review Findings

P1 Blocker

None.

P2 Should Fix

None.

Suggestion

Consider adding a focused failure-injection regression for the SQLite checkpoint projection: the cited sqlite-core-execution-store.test.ts verifies successful AgentRun persistence and a derived high-water update, but does not directly force a projection-write failure and prove that the canonical event rolls back with it. The source transaction is correct; this would strengthen executable evidence for the documented invariant.

Verification

• Base ref OID: 3e98eb225a78289b9b8f7ac76bb1014c8777ac78
• Head: 38b79fceba9e97339e9bd2f2678cebb0313f477a
• Checked the exact-head diff, implementation call paths, documented production/test paths, English/Chinese structural synchronization, git diff --check, and mergeability against the then-current main.
• All 14 documented production paths and 10 test paths resolve; both chapters have 559 lines and 27 headings.
• No temporary test or workspace change was created.
• Hosted checks are not currently attached to this exact head and are not claimed green by this review.

Conclusion

Merge conditionally.

Approved at exact head 38b79fc for the reviewed documentation and code-risk scope. Required hosted checks and the project's remaining merge gates must still complete.

点击展开中文

PR 判断

这个 PR 解决了什么问题？

上下文压缩架构的中英文配对章节已经与当前 Runtime 和 SQLite 实现发生漂移。过时描述涉及 checkpoint/prune 顺序、checkpoint 持久化、replay admission、结构化摘要校验以及失败行为。

这个 PR 如何解决这个问题？

它让中英文两份章节重新与当前实现同步。这是纯文档改动，不改变 Runtime 行为。

这个问题定义得对吗？

Correct（正确）。

主要漂移均已结合实现确认：

• checkpoint replay 先于 stale Tool Result prune；
• 文本压缩没有专用的 4,096-token 输出上限，因输出长度结束的 completion 会被拒绝；
• 结构化摘要会被校验，最多修复一次，相同的 malformed input 会被 circuit-break；
• canonical AgentRun event 与 bounded checkpoint projection 在同一个 SQLite transaction 中写入；
• replay 必须符合当前 history budget；可比较时，替换结果还必须严格小于 source；
• automatic pre-turn failure 与 manual compaction failure 的可见结果确实不同，38b79fc 现在已经正确描述二者。

Review Findings

P1 阻塞

无。

P2 应该改

无。

建议

可以考虑为 SQLite checkpoint projection 增加一个定向 failure-injection 回归测试：当前引用的 sqlite-core-execution-store.test.ts 验证了成功的 AgentRun 持久化和 derived high-water 更新，但没有直接制造 projection 写入失败，并证明 canonical event 会一同回滚。源码中的 transaction 是正确的；这个测试可以增强该文档不变量的可执行证据。

验证

• Base ref OID：3e98eb225a78289b9b8f7ac76bb1014c8777ac78
• Head：38b79fceba9e97339e9bd2f2678cebb0313f477a
• 已检查 exact-head diff、实现调用链、文档列出的生产/测试路径、中英文结构同步、git diff --check，以及相对当时当前 main 的可合并性。
• 文档列出的 14 个生产路径和 10 个测试路径均存在；两份章节均为 559 行、27 个标题。
• 未创建临时测试或工作区改动。
• 当前 exact head 没有关联 hosted checks，本 review 不声称 CI 已通过。

结论

有条件合入。

已针对审查过的文档与代码风险范围批准精确 head 38b79fc。必需的 hosted checks 和项目剩余 merge gates 仍须完成。