docs(catalog): add IP-036 a lost response is not an absent commit - #5027
Conversation
GH-C37 asks for one new public-safe good/bad case. The catalog has entries for an unprojected write scope (IP-006), a lease idempotency key (IP-016), a Todo claim/supersede lifecycle (IP-020), and a recorded rejection that is not an absence (IP-033), but none for the transport-level case where the commit landed and nobody was told. `--operation-id` already carries that meaning in `loopx/cli_commands/delegation.py:25` and `handoff_mode.py:99`, and `operation_identity_reuse` is already a coordination provider parity dimension, so the rule exists in code without a catalog entry a controller can consult. loopx-project#5007 is the public counterexample: the canonical Todo write was dispatched before the private validation declaration was persisted, so a lost effect response left a committed digest with nothing behind it. Docs only; no production or test change. Signed-off-by: yuedai-pbc <54579099+yuedai-pbc@users.noreply.github.com>
huangruiteng
left a comment
There was a problem hiding this comment.
动机
审查精确 head e6ad8790b56369850b7a83e1ae2f0d866db61ac1。#5007 显示持久写入可能已经提交,调用方却丢失了响应;把命令错误直接理解为“未提交”,会诱发重复 Todo 或缺少私有材料的权威记录。原目录已有 IP-006、IP-016、IP-020、IP-033,但没有独立说明这一传输层歧义。新增可复用条目完成本 PR 的文档目标,不等于修复 #5007。
改动思路
IP-036 进入 State And Boundary 分类,以稳定 operation id、原始收据读回、被引用材料核验串起恢复路径,并把租约幂等键、Todo 生命周期、记录过的拒绝及投影范围问题留给既有条目。文档引用已有命令帮助、receipt_index 与 provider parity 测试;真正的提交与重试权威仍在调用者及协调 provider。正向路径是同一意图按同一身份核对单次提交;反向路径是不同意图复用身份被拒,或已提交记录缺材料时明确失败。
具体改动
唯一变更是 docs/concepts/interaction-pattern-catalog.md(+107/-1)。分类表为 IP-036 增加入口;正文增加触发条件、四条规则、Mermaid 流程、错误气味和测试指针,没有生产代码、schema、默认值或测试变更。
关键内容讲解
“Lost Response”明确把响应当成提交的通知,而不是提交本身;失败后需用同一 operation id 核对收据。第三项规则指出 #5007 的已提交 Todo 与缺失 validation declaration,且把 #5012 写作提案,未把现有 lease replay 测试冒充 Todo create 已修复的证据。与 IP-016、IP-020、IP-033、IP-006 的对照保留了各自边界。
对主干的风险
未发现阻断性代码或协议风险。最强的误读是把“重发并读回”理解为所有命令已具备幂等恢复;#5007 与 #5012 当前仍开放,因此后续实现落地时需更新此条目的时态。一个非阻断的协作问题是 GitHub PR 描述目前仅为字面量 @/tmp/pr-ip036-final.md,请改成公开可读的目标和验证说明。
精确 head 上的 interaction-pattern-catalog-smoke.py 返回 ok,base-to-head 的 git diff --check 通过,完整单文件 diff 与引用的现有代码/测试已检查。没有运行产品行为测试,也未轮询远端 CI;不能据此声称 #5007 已交付。
我的整体评价
APPROVE。这是独立且有用的文档增量;它不改变长周期执行或实际用户入口,不能借此宣称运行时体验已改善。条目与既有目录结构和边界相符,篇幅用于说明失联恢复的好坏路径。剩余风险是 #5012 合并后叙述可能过时,以及 PR 描述的临时路径;后者建议修正文案,不阻断本次审查。
English verdict: APPROVE - exact head e6ad8790b56369850b7a83e1ae2f0d866db61ac1; docs-only IP-036 distinguishes lost responses from absent commits, catalog smoke and diff check pass, and #5007/#5012 remain unresolved/proposed. Replace the literal temporary-path PR description as a non-blocking follow-up.
|
Merge-readiness qualification for exact head This is the docs-only IP-036 catalog change. The published exact-head review approved its one-file scope after the catalog smoke and The current |
|
已修正 PR 正文:之前那条是本地写法失误( 关于第 3 条规则的时态,同意你的判断并已按此边界写:本条目引用 复核数字与正文一致:exact head |
Goal And Delivered Outcome
interaction pattern catalog. The catalog tells a controller what to do with an
authority it can see — IP-006 for a projected write scope that disagrees
with its checkpoint, IP-016 for the idempotency key inside a task lease, IP-020
for a Todo claim / supersede / successor lifecycle, IP-033 for a rejection that
is recorded rather than absent — and has nothing for the transport-level case
all four assume away: the commit landed and nobody was told. The rule is already
in shipped code and tests (
loopx/cli_commands/delegation.py:25registers--operation-idas "Stable request identity; reuse after a lost response",handoff_mode.py:99the same shape for a canonical set intent,tests/control_plane/test_coordination_recoverable_execution.py:693asserts are-sent operation returns
already_appliedwith the original receipt,test_coordination_provider_parity.py:222makesoperation_identity_reuseaper-provider dimension), but no concept entry tells an agent that a lost
response is not an absent commit, so the default recovery move is a blind retry.
catalog has no IP whose agent channel says "name the write, recover by readback,
and never leave a committed record pointing at unpublished material"; after,
IP-036 A Lost Response Is Not An Absent Commitstates those rules with thesettled vocabulary (
delivered/replayed/ambiguous_reconciled) as thesingle owner of an ambiguous outcome. The
staticandreal_entrypointrowsprove the entry is structurally complete (row, detail heading, single-family
listing) while leaving production behavior untouched, and
regression_parityproves the three surfaces cannot drift.
Closes #5026(GH-C37), basemain.Scope And Continuation
entry with its family-table row, its Pattern-To-Canary matrix listing, a mermaid
visual model, and validation references — 1 file, +107 / −1. Docs only; no
production or test change, so no runtime behavior can regress.
adding
--operation-idto durable-write commands that lack one, and changingany create/recovery ordering. Both belong to
#5007/#5012and their owners;this entry cites them as the public counterexample and the proposed fix, not as
work done here. A catalog-level assertion that every durable write command
exposes a recovery identity would need the CLI owners' input and is recorded as
a gap, not built.
Validation
e6ad8790bstaticpassedpython3 examples/interaction-pattern-catalog-smoke.py→interaction-pattern-catalog-smoke: ok. Structure check asserts one `real_entrypointpassedloopx check --scan-path docs/concepts/interaction-pattern-catalog.md→public boundary scan clean: 1 files.regression_paritypassedpattern rows without a detail heading; (B) listIP-036under a second family →pattern ids listed under more than one family; (C) rename the table row's id →pattern rows without a detail heading(the row and heading must pair, in either direction); (D) dropIP-036from the family matrix while keeping row and heading → smoke still passes, disclosed rather than hidden: the matrix enforces "no duplicates and no unknown ids", not "every pattern is listed", so the family listing here is a consistency choice, not a gate. Reverting all four → smoke ok.unitnot_runtests/control_plane/andtests/cli_commands/are the independent oracle for the entry's claims and were not modified.smoke plus the repository boundary check cover it end to end. Untested path: the
mermaid diagram is rendered by the docs pipeline and was verified as text only,
not visually. Each factual claim in the entry is pinned to a
file:linein thetested revision, so a reviewer can falsify any one of them directly;
#5007/#5012are cited as issue state and as the author's own description ofthe create-path ordering, and this PR depends on neither landing.
Frontend / Visual Evidence
Type of Change
LoopX Area
Technical Direction
GH-C37 (interaction pattern catalog curation), under the architecture and research
incubator direction.
Shared-authority RFC fixture impact
Not applicable: no shared-authority fixture, provider arm, RFC ledger, or
semantic vocabulary entry is touched. The entry cites the settled-outcome
vocabulary as an existing owner rather than changing it.
Boundary Checklist
raw agent sessions, or local machine paths are added.
loopx check --scan-pathrun on every touched public file → clean.