Repository navigation
docs(rfc): compare C4.3 settlement obligations before deletion - #7593
Conversation
C4.3 asked for an obligation-by-obligation comparison of host_adapter_settlement.py, turn_driver/host_todo_completion.ts and turn_driver/settlement.py before removing a supposedly duplicated condition/step interpreter. No such comparison was recorded, so the next PR had to guess. Reading the three owners at e19d94c shows the two settlement paths are not competing policy owners: both delegate every decision to a TypeScript owner, and Python is transport in both. The step vocabularies overlap only on durable_writeback, quota_spend and terminal_closeout; A's guard and lifecycle_completion have no counterpart, and B's validation is a phase marker it refuses to execute. The decisive difference is recovery. A is single-shot with no journal; B persists a checkpoint per provider and replays receipts. At the shipped capability call site the two already compose, so deleting A into B would first require giving the MCP host a journal it does not have. The only Python-side interpreter is _condition_matches over seven declarative kinds plus _decode_provider_steps order validation; moving evaluation into TypeScript needs one runtime call per step, which the RFC says is not automatically an improvement. Records the evidence, the preconditions a deletion would need, and the overlapping PRs to reconcile. No code, schema, wire or default changes. Validation: RFC bilingual check passed; loopx canary premerge --tier quick green; public boundary scan clean. Signed-off-by: xiaoan17 <anbc1224@gmail.com>
The two new C4.3 comparison notes linked their parent handoff note as '../2026-10-27-refactor-handoff.md', but the handoff note lives in the same ledger directory. mkdocs strict resolves the '../' form against architecture/rfcs/ledger/, so the strict documentation build failed with two unresolvable-target warnings and aborted. Dropping '../' points each note at the sibling file. Both the English and the Chinese note change together, so the RFC bilingual pair stays complete. No content, schema, wire or default change. Validation: mkdocs build --strict for the docs site and both developer books; RFC bilingual check passed; loopx canary premerge --from-git-diff green; public boundary scan clean. Signed-off-by: xiaoan17 <anbc1224@gmail.com>
loopx-agent
left a comment
loopx-agent
left a comment
There was a problem hiding this comment.
Reviewer: model_agent · gpt-6.1-sol · OpenAI · runtime_reported · reasoning_effort=max
当前精确 head cf9c79a 有一项P2阻断：文档把A适配器没有本地journal推成整个MCP路径没有replay，与现有实现及真实恢复测试矛盾。结论为 REQUEST_CHANGES。
动机 / Motivation
准备整合Host结算适配器、需要判断哪些恢复规则能够复用的维护者。
维护者在比较两条结算链时，会依据这份文档判断是否必须先给MCP Host新增journal；当前文档却把适配器没有本地journal写成整个调用链没有重放，现有丢响应后恢复路径因此被遗漏。
两份文档完成了部分入口和step对照，但当前恢复基线事实错误，尚不能作为后续整合方案的可靠依据。
本次只审查比较文档，不要求实现整个C4.3，不要求新增Host journal，也不声明真实Host采用、跨后端等价或长程收益已经通过。 问题在于恢复能力比较是否准确，不在于是否已经删除足够代码或一次实现全部重构。
改动思路 / Approach
按两条链的真实前门、状态owner和持久读回比较是合理方向。A为MCP Host准备并执行guard、completion、writeback、spend、closeout计划；B消费Turn settlement reducer并维护provider checkpoint。A确实没有与B相同的adapter-local checkpoint，但这不排除底层canonical receipts已经实现同身份重放。
完整调用关系应说明两层恢复：A的调用方用同一意图重新进入prepare/plan/finalize，原CLI依据持久receipt避免重复结算；B在自己的checkpoint/resolve_prepared边界恢复provider步骤。二者粒度和恢复owner不同，需要比较，而不能用“无journal”直接推出“无恢复”。这段文字即可表达关键区别，不附未经渲染核验的图。
具体改动 / Changes
spec_ref: docs/architecture/rfcs/ledger/controller-executor-unified-contract-v0/2026-10-27-refactor-handoff.md；spec_revision: e19d94c。本次按变更前accepted C4.3 判断：先比较identity、validation、guard/vision、completion、durable writeback、spend、closeout和recovery；保留原effect身份、提交前后失败、response loss和repeated completion的逐阶段readback。当前比较中的恢复部分为not_met，最小修复是纠正两镜像的基线和据此推导的后续方案，不是要求当前PR实现整个C4.3。
完整差异只有EN109行和CN98行，两份新ledger共+207/-0。已核对两语言和父文引用，最后一个commit修正了父ledger相对链接；没有runtime、schema、配置或默认行为变化。
关键内容讲解
- Obligation matrix 区分guard与validation marker、completion前门和provider checkpoint有依据；但Replay/Persistence两行把A描述为无恢复且只有临时文件，遗漏底层结算持久receipt。
- Finding3 将上述遗漏进一步变成“整合必须先给MCP Host新增journal”的前提，这是本次需要修正的具体结论。它不能由Python适配器没有自己的journal单独推得。
- 真实反例在已有 test_real_mcp_completion_recovers_a_lost_mutation_response：真实CLI先提交lifecycle/writeback/spend之一，再仅替换返回响应；再次调用complete_task成功，后续重复仍保持相同身份且只扣一槽。
相关源路径是 turnInstanceId 的稳定身份、spendContinueWhen 接受idempotent_replay/receipt_repaired，以及原finalizer/CLI持久readback。这些代码已经存在于不可变基线，并非本PR新增恢复。
对主干的风险 / Risks
[P2] 请区分本地checkpoint与已有端到端replay。 触发情形是维护者按Finding3规划适配器合并，而实际MCP mutation提交后响应丢失。现有路径用相同身份重试能够恢复；把它写成“完成或抛错、无replay”，会遗漏后续必须保留的行为，并给方案增加未被证实的新journal前置条件。同步改正EN/CN矩阵和Finding3，区分adapter-local checkpoint与canonical receipt重放；据既有恢复能力重新表述后续方案前提。
独立验证使用原真实入口和隔离持久fixture：head的MCP/settlement模块22 passed；不可变base单跑三种lost_after参数3 passed。测试断言第一次返回失败、durable readback为pending或settled、过早terminal完成被拦、同意图重试成功、再重复quota_spend.appended=false且spent_slots=1。故障注入仅替换真实commit后的响应，底层CLI和持久状态未模拟。
PASS：标准premerge四direct及14selected、双语、diff、DCO和两新文件公共边界扫描。FAIL：文档恢复结论的源代码准确性，严格精确CQR也已记录该阻断；结构检查通过不能推翻反例。未查询或等待CI。此处无需再次启动模型、PostgreSQL或真实Host来证明一条已有可达恢复路径存在；那些更宽的交付资格仍未声明。
我的整体评价 / Verdict
REQUEST_CHANGES。当前比较尚不能作为可靠的C4.3后续依据；long_horizon为regression，具体是错误基线会误导恢复路径的整合或删除，不代表本PR已经改变运行时。user_experience为preserved，因为Host工具、原恢复入口和交互轮次没有变化。
同步改正EN/CN矩阵和Finding3，区分adapter-local checkpoint与canonical receipt重放；据既有恢复能力重新表述后续方案前提。 同步修正两镜像并复跑既有response-loss三例即可重新评审，不要求先交付完整C4.3或人为新增任务。该文不增加共享vocabulary或执行权限，也不能授予后续安装、合并、付费执行或外部副作用权。
已检查两份Markdown ledger及其源代码引用；没有页面设计、导航或渲染组件变化，视觉评审不适用。 正式文档站渲染、真实Host/多后端全路径成本和长期采用未在本轮验证。 不把本地测试通过、文档新增或历史合并当作真实Host采用和净收益证据。
English verdict: REQUEST_CHANGES — cf9c79a. The claim that path A has no replay is contradicted by existing real MCP response-loss recovery on both base and head, with stable identity and exactly one quota spend. Correct both ledger mirrors and the resulting journal prerequisite; structural validation passing does not resolve this factual error.
| and `lifecycle_completion` have no B counterpart, and B's `validation` is a | ||
| phase marker it refuses to execute rather than A's admission call. | ||
|
|
||
| 3. **Recovery is the real difference, not duplication.** A has no journal and no |
There was a problem hiding this comment.
[P2] 请区分 adapter-local journal 与端到端 replay。现有 MCP complete_task 在真实 lifecycle/writeback/spend 已提交但响应丢失后，可用同一意图重试恢复；再次完成保持同一 settlement_identity，quota_spend.appended=false，spent_slots=1。host_todo_completion.ts 的 turnInstanceId、spendContinueWhen 和 finalize 已接受 idempotent_replay/receipt_repaired。既有 tests/test_goal_mode_mcp_settlement.py::test_real_mcp_completion_recovers_a_lost_mutation_response 三个参数在不可变 base e19d94c 与当前 head 均通过。因此“无本地journal”不能推出这里的“no replay”或新增Host journal必为整合前提；请同步修正两语言的矩阵、Finding3及后续方案，保留已有 canonical receipt 恢复义务。
An earlier revision of the C4.3 comparison read the adapter's lack of a local journal as a lack of recovery on the whole MCP path, and made "give the MCP host a journal it does not have" a precondition of any deletion. Both were wrong. The MCP path does recover. turnInstanceId derives a stable identity from the same intent, the CLI persists canonical settlement receipts, and spendContinueWhen accepts idempotent_replay and receipt_repaired, so a response lost after the real commit recovers by re-entering the same intent: the durable readback reports settlement_pending or settled, a premature terminal completion is blocked, the retry succeeds and one slot is spent. tests/test_goal_mode_mcp_settlement.py::test_real_mcp_completion_recovers_a_lost_mutation_response covers it over lifecycle, writeback and spend, and passes at this head. The real difference is owner and granularity: the adapter keeps no journal, the CLI owns the durable receipts, and B recovers per provider step inside one transaction. The matrix rows, Finding 3, the deletion preconditions and the characterization candidate now say that, and the characterization candidate targets the adapter-local partial-step behavior rather than the response-loss case that is already covered. Both mirrors are corrected together. No runtime, schema, wire, registry or default change. Validation: mkdocs build --strict for the docs site and both developer books; RFC bilingual check passed; loopx canary premerge --from-git-diff green; the response-loss recovery test passes locally. Signed-off-by: xiaoan17 <anbc1224@gmail.com>
更正 C4.3 恢复基线 — 请求复审新 head： 复审指出的 P2 阻断成立：文档把"A 适配器没有本地 journal"推成"整条 MCP 路径没有 纠正了什么
依据
验证
请在 Correcting the C4.3 recovery baseline — requesting re-reviewNew head: The P2 blocker is confirmed: the entry read the adapter's lack of a local The recovery baseline is the CLI-receipt replay that already exists: Validation: strict mkdocs builds for the docs site and both developer books; |
The derived status index counts ledger entries per RFC, so adding the C4.3 comparison entry makes the checked-in index stale and the docs-governance smoke fails for every later change until it is regenerated. Both index files are regenerated from the RFC headers. No prose change. Signed-off-by: xiaoan17 <anbc1224@gmail.com>
补充：派生状态索引已重新生成新 head： 派生状态索引按 RFC 统计 ledger 条目数，新增本条目后 两处恢复基线的更正见上一条评论。本提交只补索引，无散文改动。 Follow-up: the derived status index is regeneratedNew head: The derived status index counts ledger entries per RFC, so the new entry made The recovery-baseline correction is in the previous comment. This commit only |
Merge ordering: regenerate the status index after #7617 landsThe derived status index counts ledger entries per RFC. This PR and #7617 each I will regenerate it on whichever of the two lands last. Merge ordering: regenerate the status index after #7617 landsThis PR and #7617 each add one ledger entry to the same RFC and each regenerate |
loopx-agent
left a comment
loopx-agent
left a comment
There was a problem hiding this comment.
Reviewer: model_agent · gpt-6.1-sol · OpenAI · runtime_reported · reasoning_effort=max
精确 head 563f08799f21c171224407ba4188c863e12333f1：APPROVE，没有剩余阻断发现。前次“无本地 journal 推出无端到端 replay”的 P2 已在两份镜像中修正；本次重新检查完整 PR。
动机 / Motivation
准备整合 Host 结算适配器、需要判断现有恢复义务能否复用的维护者。
维护者准备删除一套步骤解释器时，旧版比较会把“没有适配器本地日志”误读成“整条 MCP 路径没有恢复”；新版明确已有回执重放，避免给后续方案增加未经证实的日志前置。
两份镜像现在区分稳定身份与规范回执恢复、provider 步骤级 checkpoint，并更新派生索引；本轮验证支持这份比较，不代表已经完成适配器整合。
本 PR 不实现整个 C4.3，不删除运行时，不新增 journal，不认证安装、真实 Host 采用或长程净收益。
改动思路 / Approach
比较沿用既有 C4.3 ledger 和 TypeScript 决定属主。A 的 Python 适配器执行计划，底层 CLI 保存规范结算回执；B 的 Python 适配器把 provider 执行、checkpoint 和读回交还 TS reducer。前者可用同一意图重新进入，后者有事务内步骤级恢复，两种粒度不能只凭相同 step 名称认作等价。
当前独立切片是可靠的义务对照。保留它比直接合并解释器或增加第三套日志更有依据；后续只删除已证明等价且调用者实际采用的部分。该结论不以文档行数、测试数量或记忆召回作为价值证明。
具体改动 / Changes
spec_ref: docs/architecture/rfcs/ledger/controller-executor-unified-contract-v0/2026-10-27-refactor-handoff.md；spec_revision: e19d94ca04ead2bb919aaa438e61bf229a6cfad1。按变更前 accepted C4.3 检查：identity、validation、guard/vision、completion、writeback、spend、closeout、recovery 的比较为 implemented；实际删除、部分步骤整合、完整成本比较仍属于后续实现边界，本 PR 没有冒充完成它们。
关键内容讲解
- 义务矩阵与恢复修正 现在区分 adapter-local journal 和 canonical receipt replay；Finding 3、删除前提、候选切片与末尾限制同步修正。
- 中文镜像 保留相同 owner、重入及一次扣额义务；没有把建议升级为新的机器 gate。
STATUS.md与中文索引各将该 RFC 的 ledger 数从 1 改为 2。完整 diff 为四份 Markdown +246/-2；无运行时、配置、schema 或共享词表改动。- 已核对
turnInstanceId、spendContinueWhen、settle_host_todo_completion、execute_turn_driver_settlement和 governed capability 的组合调用。源代码支持这些边界，不能据此声称模型理解或真实 Host 采用已经通过。
对主干的风险 / Risks
独立运行既有真实 MCP settlement 模块：PASS，8 passed。其中 lifecycle/writeback/spend 三类提交后丢响应均实际提交 CLI 状态，再仅替换响应；同意图重试恢复、过早终态完成拒绝、再次调用身份不变且只扣一个槽位。因此本次不是只核对措辞或继承旧评审。
PASS：standard premerge 四项 direct 加 17 项选中检查、RFC 双语、公共边界、DCO、docs-governance 和精确 strict CQR cqr_64a8ffee4780bdff2a1a。初始命令误写了一个不存在的测试文件，未运行测试；已改为实际 MCP 模块，准备错误不归因于 PR。未查询或等待 CI。
非阻断建议：PR 描述第 3 点仍保留“A single-shot/no journal，因此必须先给 MCP host 新 journal”的旧摘要，请同步为当前 ledger 的恢复结论。另与 #7617 同时落地时，后合入者要重生派生条目数；当前 checkout 的索引治理测试已通过，这属于集成时复核。
我的整体评价 / Verdict
本次比较任务的有用结果已成立。long_horizon：improved，限定为后续整合保留既有恢复义务的依据得到纠正；不代表运行时效率或净收益已测得。user_experience：preserved，现有 CLI/MCP 入口、恢复步骤和权限边界没有改变。
已检查四份 Markdown 与完整源代码引用；没有页面设计、布局、渲染组件或交互变化，视觉评审不适用。 未验证范围：正式文档站渲染、真实 Host 的部分步骤恢复、跨后端整合及完整成本未在本轮重新资格。
bounded refactor 判断为无需当前代码重构：保留有根据的比较，后续整合再证明删除收益。该批准不授予合并、安装、模型执行或新副作用权限。
English verdict: APPROVE — 563f087. The corrected bilingual comparison preserves existing MCP receipt replay and distinct Turn recovery ownership; local MCP, documentation, premerge and strict CQR checks pass. Integration and runtime benefit remain separately unqualified.
…obligations Signed-off-by: xiaoan17 <anbc1224@gmail.com>
…obligations Signed-off-by: xiaoan17 <anbc1224@gmail.com>
xiaoan17
left a comment
xiaoan17
left a comment
There was a problem hiding this comment.
Reviewer: model_agent · MiniMax-M3.1-Flash · MiniMax · self_reported · reasoning_effort=unavailable
Approval conclusion (author-owned PR; GitHub blocks formal self-approval)
精确 head 545527870eeeb8746019fc1957ce5e997d5b1e1c：APPROVE，没有剩余阻断发现。
这是一次 exact-head 复审。上一条 loopx-agent 评审绑定的 head 是
563f08799f21c171224407ba4188c863e12333f1；从那个 head 到当前 head，四份 Markdown
内容逐字未变，其间只并入了上游 main 的两次合并。上一条评审提出的唯一非阻断建议
（PR 描述第 3 点仍沿用“A 是 single-shot、无 journal，因此删除前必须先给 MCP host 一个
它没有的 journal”的旧摘要）已按当前 ledger 的恢复结论更正。本条把同一结论重新绑定到
当前 head，并补记本 head 上的验证。
动机 / Motivation
C4.3 要求在删除所谓重复的 condition/step 解释器之前，逐项比对 Host Todo
completion 与 Turn settlement 的义务。此前没有留下这样的对照，维护者只能凭猜测决定
是否删除第二个解释器。这条 PR 只交付那份对照记录，使下一个实现切片可以依据证据而不是
直觉推进。
保留对照本身，比直接合并解释器或引入第三套日志更有依据：对照结论是“两条路径都不是
第二个策略属主，恢复差异在属主与粒度”。按旧摘要直接删除，会先丢掉 A 侧 guard 与
lifecycle_completion 这两个在 B 无对应项的义务，或者丢掉 CLI 回执重放这条已经存在的
恢复路径——两者都会改变真实行为。
本 PR 不实现 C4.3 的整合，不删除运行时，不新增 journal，也不认证安装、真实 Host 采用
或长程净收益。
改动思路 / Approach
对照沿用既有 C4.3 ledger 与既有 TypeScript 决定属主：A 侧 Python 适配器执行有序 CLI
plan，CLI 持有规范结算回执；B 侧 Python 适配器把 provider 执行、checkpoint 与读回交还
TS reducer。两条路径都把决定交给 TypeScript，Python 只做传输。
恢复语义按属主与粒度区分，不按“有/无”区分。A 侧适配器自身不持有 journal，但调用链
靠 turnInstanceId 的稳定身份、CLI 规范回执，以及 spendContinueWhen 接受
idempotent_replay / receipt_repaired 完成重入恢复；B 侧在单个事务内按 provider 步骤
checkpoint 与 resolve_prepared 恢复。
未做的部分是有意的。删除适配器侧的解释器需要先证明调用方已经采用等价的 typed
boundary，并且要么给适配器补上等价的 effect receiver，要么让 B 侧接受带 continue_when
的有序 CLI 序列并接管 CLI 回执重放。把条件求值搬到 TypeScript 需要每步一次 runtime 调用，
按 RFC 的说法这并不自动等于改进。
具体改动 / Changes
spec_ref: docs/architecture/rfcs/ledger/controller-executor-unified-contract-v0/2026-10-27-refactor-handoff.md；
spec_revision: e19d94ca04ead2bb919aaa438e61bf229a6cfad1。按变更前已接受的 C4.3 检查项
逐条映射：identity、validation、guard/vision、completion、writeback、spend、closeout、
recovery 的比较为 implemented；实际删除、部分步骤整合与完整成本比较属于后续实现边界，
本 PR 不冒充完成它们。
关键内容讲解
- 义务矩阵与恢复更正
现在区分 adapter-local journal 与 canonical receipt replay；Finding 3、删除前提、候选切片
与末尾“未建立什么”的限制同步更正，并显式写出恢复基线是既有的 CLI 回执重放。 - 中文镜像
保持同样的属主、重入与一次扣额义务，没有把建议升级为新的机器 gate。 STATUS.md与STATUS.zh-CN.md各把该 RFC 的 ledger 条目数从 1 改为 2。完整 diff 是
四份 Markdown，+246/-2；没有运行时、配置、schema、wire 或共享词表改动。- 已核对
turnInstanceId、spendContinueWhen、settle_host_todo_completion、
execute_turn_driver_settlement与extensions/governed_capability_execution.py的组合
调用；源代码支持这些边界，但这不等于模型理解或真实 Host 采用已被证明。
对主干的风险 / Risks
PASS：tests/test_goal_mode_mcp_settlement.py 在本 head 实际运行，8 passed。其中
lifecycle / writeback / spend 三类“提交后丢响应”场景会真实提交 CLI 状态后只替换响应，
同意图重试恢复、过早的终态完成被拦下、再次调用身份不变且只扣一个槽位。
PASS：scripts/check_rfc_bilingual.py --base mirror/main --head HEAD 通过；
loopx canary premerge --from-git-diff --git-diff-base mirror/main 四组检查全部 ok、
0 failures、0 warnings；loopx check 公共边界扫描（两份 ledger + 两份 STATUS）clean。
PASS：DCO Signed-off-by 齐备；改动只落在 Markdown，没有运行时回归面，也没有新增默认值。
UNVERIFIED：正式文档站渲染、真实 Host 的部分步骤恢复、跨后端整合与完整成本，未在本轮
重新资格。
非阻断建议：无新增项。上一条评审指出的 PR 描述旧摘要已更正；若后续并入新的 ledger 条目，
后合入者需要重生派生条目数。
我的整体评价 / Verdict
本次比较任务的有用结果已成立。long_horizon：improved，限定为后续整合保留既有恢复
义务的依据得到纠正，不代表运行时效率或净收益已经测得；user_experience：preserved，
CLI/MCP 入口、恢复步骤与权限边界没有改变。
bounded refactor 判断为当前无需代码重构：保留有根据的比较，后续整合再用证据证明删除
收益。该批准不授予合并、安装、模型执行或新副作用权限。
English verdict: APPROVE — 5455278. The corrected bilingual comparison preserves the existing MCP receipt replay and the distinct Turn recovery ownership; the MCP settlement module (8 passed), the RFC bilingual check, canary premerge and the public-boundary scan pass at this head. Integration, runtime benefit and the full-cost comparison remain separately unqualified.
Goal and source
C4.3
requires comparing the settlement owners obligation by obligation before
deleting a supposedly duplicated condition/step interpreter.
No such comparison was recorded, so the next implementation slice had to guess
whether
host_adapter_settlement.py's plan interpreter is a duplicate of theTurn settlement boundary.
What the comparison found (baseline
e19d94ca0)TypeScript owner; Python is transport in both.
guard / lifecycle_completion / durable_writeback / quota_spend / terminal_closeout; B'sSettlementStepKindisvalidation / durable_writeback / quota_spend / terminal_closeout.guardand
lifecycle_completionhave no counterpart, and B'svalidationis aphase marker it refuses to execute — not A's admission call.
keeps no journal of its own, but the MCP path does recover:
turnInstanceIdderives a stable identity from the same intent, the CLI persists canonical
settlement receipts, and the continue-when conditions accept
idempotent_replay/receipt_repaired, so a response lost after the realcommit recovers by re-entering the same intent — the durable readback
reports
settlement_pendingorsettled, a premature terminal completionis blocked, the retry succeeds, and one slot is spent. This is covered by
tests/test_goal_mode_mcp_settlement.py::test_real_mcp_completion_recovers_a_lost_mutation_responseover
lifecycle,writebackandspend. B recovers at provider-stepgranularity inside one transaction, through its own checkpoint and
resolve_prepared. A consolidation must preserve the CLI-receipt replaypath; it must neither assume the MCP host needs a new journal nor assume the
CLI receipts disappear with the adapter.
governed_capability_execution.pyuses A'sclassify_host_guard_snapshotforadmission and B's
execute_turn_driver_settlementfor the transaction, withits own journal.
_condition_matchesover seven declarative kinds plus step-order validation;TypeScript still authors every condition, and moving evaluation into
TypeScript needs one runtime call per step — which the RFC says is not
automatically an improvement.
Deliverable
Two new ledger entries (English + Chinese mirror) recording the obligation
matrix, the evidence, the preconditions a deletion would need, the
characterization that is still missing (the adapter's own partial-step
behavior), and the overlapping PRs to reconcile (#3412, #5677, #7580, #7523).
This is a reading-only comparison: no code, schema, wire or default change,
and no claim that either path is redundant.
Validation
The branch also merges current
main(ce4c78088) so the diff stays reviewableon top of the latest control-plane changes.