Skip to content

docs(rfc): add Stage-then-Swap next_command prefetch contract to history working-set RFC - #9148

Open
loopx-agent wants to merge 1 commit into
mainfrom
codex/rfc-context-reclaim-prefetch-20261121
Open

loopx-agent wants to merge 1 commit into
mainfrom
codex/rfc-context-reclaim-prefetch-20261121

Conversation

@loopx-agent

Copy link
Copy Markdown
Collaborator

Summary

Refines the bilingual History Working-Set & Context Policy RFC (English, 中文) in Proposal maturity (default-off, zero runtime changes) to formalize atomic Stage-then-Swap context reclamation with next-step command hydration (reclaim + next_command / FoldAndPrefetch / EpochReset prefetch):

  1. §5.1 Atomic fold-and-prefetch (Stage-then-Swap):
    • Replaces scattered exploratory tool calls ($B_{\text{old}}$) with a compact verified receipt ($\mu$) plus fresh deterministic command observation ($\text{Obs}(\text{next_cmd})$) in a single transition ($Q \mathbin{\Vert} B_{\text{old}} \rightarrow Q \mathbin{\Vert} \mu \mathbin{\Vert} \text{Obs}(\text{next_cmd})$), eliminating the extra post-reclaim read round-trip and preventing premature prose-summary re-read thrashing (comparing Spine's Next(μ, d)).
    • Specifies five normative invariants:
      1. Execute before evict: run next_command first under explicit timeout_ms / max_output_bytes limits and commit only if net token savings clear $\Delta_{\min}$ (including rebase prefill break-even), aborting atomically back to KeepRaw on failure, overflow, or negative gain.
      2. Prefix KV-cache locality across two host carriers: contiguous suffix pop [since_anchor..now] keeping parent prefix $Q$ byte-identical on controllable sampling-stack hosts (DSH / Pi / managed loop), and turn_driver-bounded prefetch_command / context-read --select injection at EpochReset on opaque CLI hosts (codex-cli / Claude Code).
      3. Caller authority, read/probe side-effect bounds, and replay idempotency (§2.4, §5.3, A7): strictly agent-initiated or Turn-closeout requested (never emitted by passive HistoryViewPolicy plugins), sandbox/lease-gated, restricted by default to idempotent reads/probes, recorded immutably in decision_capture / journal so replay restores output without re-executing next_command, and kept at tool trust level.
      4. Reasoning & tool-pairing integrity: collapse [since_anchor..reclaim_call] into a well-formed pair without orphan splits while preserving raw $B_{\text{old}}$ under source_ref + sha256 (A2).
      5. Receipt-backed anti-whitewashing header: runtime deterministically prepends objective facts from $B_{\text{old}}$ (last verification exit code, unresolved error/gate counts, exact source_ref) into $\mu$.
  2. §5.3, §9.1 (A13), §11 (M0), §12 (D8), Appendix B & C:
    • Clarifies agent-initiated prefetch vs. declarative HistoryViewPolicy in §5.3; adds acceptance criterion A13 and open decision D8 (admission scope: quota context-read --select pointers + sandboxed read-only workspace probes first); updates A1–A13 and D1–D8 ranges across §11 and Appendices A–C; adds fixed Spine / SpineCodex references ([SP1]/[SP2]).

Verification

  • uv run --extra test python scripts/check_rfc_bilingual.py --base origin/main --head HEAD -> passed (RFC bilingual diff check passed.)
  • python3 examples/semantic-vocabulary-drift-smoke.py -> passed (semantic-vocabulary-drift-smoke: ok)
  • loopx check --scan-path docs/architecture/rfcs/history-working-set-context-policy-v0.md --scan-path docs/architecture/rfcs/history-working-set-context-policy-v0.zh-CN.md -> passed (errors=0, warnings=0, checks=5)
  • loopx canary premerge --from-git-diff --git-diff-base origin/main --goal-id personal-loopx-maintenance -> passed (selected=11, failures=0, including Change Quality Receipt cqr_a2de25392311ef1dc1c7)
  • Note: repo-wide python3 scripts/generate_rfc_status_index.py --check fails on unmodified origin/main due to a pre-existing dated heading in monorepo-distribution-split-v0.{md,zh-CN.md} (unrelated to this PR; zero index/heading findings on history-working-set-context-policy-v0*).

Related: #8450, #4391

@loopx-agent loopx-agent left a comment

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approval conclusion (author-owned PR; GitHub blocks formal self-approval)

Reviewer: model_agent Antigravity Google Deepmind (self_reported)

Reviewed exact head: 67065545b0e250864f521acd25a43ab59cf7caf5

动机 / Motivation

受长程上下文回收与 EpochReset 影响的控制面维护者、可控采样栈运行时以及不透明 CLI 宿主接入方在设计 M1 与 M2 上下文折叠切片时会遇到这一衔接缺口。

改前在历史回收后模型只能凭摘要空手重启并额外消耗一轮模型往返重读状态,或因过早总结丢失行号与失败细节而反复重读;改后通过先执行后回收的 Stage-then-Swap 原语在单次迁移内用已核验回执与确定性命令观测替换散乱探索后缀,且在失败、超时、超限或净收益为负时原子回退为 KeepRaw。

双语 RFC 正式确立五条可审计的 Stage-then-Swap 规范不变量、两条宿主对齐承载形态、新增验收项 A13、开放决定 D8 与固定文献索引,且不改变默认关闭状态与运行时代码。

本 PR 不修改任何运行时、CLI 或控制面实现代码,不批准 §12 的开放实施选择,也不声称已完成 A13 运行时基准测试或改变默认关闭策略。

FoldAndPrefetch 与 EpochReset prefetch_command 的运行时接入、沙箱准入边界 D8 的维护者拍板以及 A13 的重放与延迟开销实测仍需在后续 M1 与 M2 实施 PR 中完成。

改动思路 / Approach

本 PR 没有为上下文预取另起一份平行文档,而是直接演进既有的 history-working-set-context-policy-v0(关联 #8450 与 #4391 T02 / M1-B),将“弹性回收”与“下一阶段工作视图装载”收口为单次原子状态迁移:

  1. 两类与宿主对齐的承载形式: 对 DSH / Pi / 自管 Agent Loop 这类可控采样栈宿主,定义连续尾部 FoldAndPrefetch(仅弹出 [since_anchor..now] 后缀,维持父前缀字节恒定以保住 KV-cache,增量 prefill 只需覆盖 $\mu + \text{Obs}(\text{next_cmd})$);对 codex-cli / Claude Code 等不透明外部 CLI 宿主,则通过 turn_driver 在 Turn 收尾 / EpochReset 边界预执行有界的 prefetch_command / context-read --select 并直接注入下一 epoch 的初始 prompt。
  2. 能力与权限边界严格分离: 在 §5.3 中明确 HistoryViewPolicy.propose() 依然是纯粹的声明式插件接口,严禁注入可执行命令;只有 Agent 显式发起或随 Turn 收尾提交的请求才可进入运行时沙箱与 decision_capture / Turn journal 审计路径。
维度 纯上下文回收 / 文字过渡 新增 Stage-then-Swap next_command 契约
唤醒连续性 空手重启,多耗一轮读指令或文字摘要失真返工 单次迁移直接呈现 $\mu \mathbin{|} \text{Obs}(\text{next_cmd})$
原子性与回退 无命令预算与净收益门控 先执行后回收;超时、溢出、失败或净收益为负时回退 KeepRaw
失败防遮蔽 存在挑好结果盖住既有红灯风险 运行时确定性将退码、未消解失败计数与 source_ref 写入 $\mu$ 头部
重放幂等性 恢复流程易二次执行命令 写入 decision_capture / journal,重放直接回填且保持 tool 信任级别

当前 PR 边界刻意止步于静态规范修订(Proposal 成熟度且默认关闭),将 FoldAndPrefetch 具体沙箱白名单与运行时执行切片留给后续受 D8 与 A13 约束的 M1/M2 PR。

具体改动 / Changes

关键内容讲解

本次对照改动前已接收的基准规范 docs/architecture/rfcs/history-working-set-context-policy-v0.md (修订基线提交 5eb6b24 )检验各既定条目,并在中英文镜像各精确增改 +36 / -6 行(共 2 文件 +72 / -12 行):

  1. §5.1 新增 Stage-then-Swap 契约与五条不变量: 给出状态迁移形式化定义 $Q \mathbin{|} B_{\text{old}} \rightarrow Q \mathbin{|} \mu \mathbin{|} \text{Obs}(\text{next_cmd})$,明确五条硬约束:(1) 先执行后回收(timeout_ms、max_output_bytes 及含重定基回本阈值的净 token 门控 $\Delta_{\min}$);(2) 前缀 KV-cache 局部性(禁止中段抽删,区分尾部 FoldAndPrefetch 与 EpochReset 预取);(3) 权限与重放幂等(沙箱与幂等只读约束、journal 固化、tool 信任级别);(4) 推理项与工具配对完整性(整体规约闭合后缀 [since_anchor..reclaim_call] 防止半边孤立,B_old 保留于 source_ref + sha256);(5) 防粉饰太平头(由控制面确定性注入既有验证退码与未消解门禁统计)。
  2. §5.3 与 §9.1 / §11 / §12 / 附录 B–C 同步对齐: 在 §5.3 划清 Agent 显式预取与被动 HistoryViewPolicy 插件的职责界线;在 §9.1 新增 A13 验收行,将全量运行时/模型验收范围扩展至 A1–A13;在 §11 M0 与附录 B 同步登记 D1–D8 并新增 2026-11-21 提案修订说明;在 §12 新增 D8(优先开放 quota context-read --select 指针与沙箱只读工作区探针);在附录 C 补充 [SP1] / [SP2] 固定 Spine 参考文献。
  3. 基线准则映射(相对基线 5eb6b24 ):
    • M0 (RFC 评审阶段边界与开放决定治理)-> implemented:中英文规范、所有者分工、回退口与新增 D8 / A13 同步落地且双语与术语校验通过。
    • A2 (基于 source_ref 与 sha256 无损保留原始历史以便按需展开)-> deferred:本纯文档 PR 已在 §5.1(4) 与 A13 中重申并固化该契约要求,实际持久化与展开验证随后续 M1/M2 代码切片交付。
    • A7 (崩溃恢复与重放幂等性,不重跑副作用命令)-> deferred:本纯文档 PR 已要求 Obs(next_command) 不可变落入 decision_capture / Turn journal,运行时回填回归测试随后续 M1/M2 turn_driver 切片交付。

对主干的风险 / Risks

  • 零阻断性缺陷(No blocking finding): 本次变动完全限定在 docs/architecture/rfcs/history-working-set-context-policy-v0.md 与 .zh-CN.md,不改动任何运行时代码、schema 定义、配置文件或默认策略开关;若需回退只需 revert 单个提交 67065545b0e250864f521acd25a43ab59cf7caf5。
  • 负向防线核查: 已验证三条关键负向约束均有清晰文档契约落脚点:被动的 HistoryViewPolicy 插件被 §5.3 明确禁止发命令;next_command 失败、超时、溢出或净收益为负按 §5.1(1) 原地回退 KeepRaw;既有红灯事实由 §5.1(5) 运行时确定性头保真,防止“选一条成功命令洗白历史失败”。
  • 本地验证摘要(exact head 67065545b0e250864f521acd25a43ab59cf7caf5):
    • uv run --extra test python scripts/check_rfc_bilingual.py --base origin/main --head HEAD -> PASS(双语逐节对称校验通过)
    • python3 examples/semantic-vocabulary-drift-smoke.py -> PASS(语义词表无漂移)
    • loopx check --scan-path docs/architecture/rfcs/history-working-set-context-policy-v0.md --scan-path docs/architecture/rfcs/history-working-set-context-policy-v0.zh-CN.md -> PASS(errors=0, warnings=0, checks=5)
    • loopx canary premerge --from-git-diff --git-diff-base origin/main -> PASS(selected=11, failures=0,含 cqr_a2de25392311ef1dc1c7)

我的整体评价 / Verdict

  • Long-horizon 影响(improved): 将业界与架构讨论中的 reclaim + next_command 思路精准沉淀为带有先执行后回收、KV-cache 前缀局部性、工具配对约束与防粉饰太平头的 RFC 规范契约,有效降低了后续长程上下文运行时落地时的语义返工与缓存击穿风险。
  • User experience(not_applicable): 本 PR 仅涉及 Proposal 阶段双语 RFC 规范文档修改,未改动任何 UI、CLI 或飞书终端交互表面。
  • 代码体量与兼容评估: 全量仅 +72 / -12 行文档修订,完整复用原有 RFC 状态模型与边界(necessary;未新增运行时兼容分支)。
  • 残余风险: D8 的命令准入边界以及 A13 的真实回放幂等、KV-cache 命中收益和端到端成本控制均尚未有运行时代码实现,后续仍须按 M1 / M2 切片逐一用独立反例测试验证。

英文简短结论:

English verdict: APPROVE — bounded Proposal-maturity bilingual RFC refinement specifying atomic Stage-then-Swap next_command reclamation with explicit sandbox, KV-cache locality, replay idempotency, and anti-whitewashing gates (0 runtime changes).

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant