Skip to content

docs(catalog): add IP-036 a lost response is not an absent commit - #5027

Merged
huangruiteng merged 1 commit into
loopx-project:mainfrom
yuedai-pbc:codex/ip-036-lost-response-not-absent-commit
Sep 25, 2026
Merged

huangruiteng merged 1 commit into
loopx-project:mainfrom
yuedai-pbc:codex/ip-036-lost-response-not-absent-commit

Conversation

@yuedai-pbc

@yuedai-pbc yuedai-pbc commented Sep 25, 2026 •

Copy link
Copy Markdown
Contributor

Goal And Delivered Outcome

  • Goal/source and gap: GH-C37 asks for one new public-safe good/bad case in the
    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:25 registers
    --operation-id as "Stable request identity; reuse after a lost response",
    handoff_mode.py:99 the same shape for a canonical set intent,
    tests/control_plane/test_coordination_recoverable_execution.py:693 asserts a
    re-sent operation returns already_applied with the original receipt,
    test_coordination_provider_parity.py:222 makes operation_identity_reuse a
    per-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.
  • Observable before → after, with the validation row that proves it: before, the
    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 Commit states those rules with the
    settled vocabulary (delivered / replayed / ambiguous_reconciled) as the
    single owner of an ambiguous outcome. The static and real_entrypoint rows
    prove the entry is structurally complete (row, detail heading, single-family
    listing) while leaving production behavior untouched, and regression_parity
    proves the three surfaces cannot drift.
  • Issue/task and intended base: Closes #5026 (GH-C37), base main.

Scope And Continuation

  • Completed scope and remaining work: complete within this scope. One catalog
    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.
  • Slice boundary / successor: N/A for this entry. Deliberately not folded in:
    adding --operation-id to durable-write commands that lack one, and changing
    any create/recovery ordering. Both belong to #5007 / #5012 and 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

  • Tested revision: e6ad8790b
  • Run state: finished
  • Input classes: none
Check kind Result Public-safe evidence / limitation
static passed python3 examples/interaction-pattern-catalog-smoke.py → interaction-pattern-catalog-smoke: ok. Structure check asserts one `
real_entrypoint passed loopx check --scan-path docs/concepts/interaction-pattern-catalog.md → public boundary scan clean: 1 files.
regression_parity passed Four mutations of the entry itself, one at a time, each reverted before the final run: (A) delete the detail heading → pattern rows without a detail heading; (B) list IP-036 under 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) drop IP-036 from 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.
unit not_run Not required: no code or test changed. The cited tests in tests/control_plane/ and tests/cli_commands/ are the independent oracle for the entry's claims and were not modified.
  • Coverage and gaps: the changed path is one documentation file, so the structural
    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:line in the
    tested revision, so a reviewer can falsify any one of them directly;
    #5007 / #5012 are cited as issue state and as the author's own description of
    the create-path ordering, and this PR depends on neither landing.

Frontend / Visual Evidence

  • UI impact: none
  • Before: N/A
  • After: N/A
  • States and viewports shown: N/A
  • Source data: none

Type of Change

  • Bug fix
  • New feature
  • Breaking change
  • Documentation only
  • Other (describe above)

LoopX Area

  • Documentation

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

  • No private benchmark traces, verifier output, credentials, internal links,
    raw agent sessions, or local machine paths are added.
  • loopx check --scan-path run on every touched public file → clean.
  • No maintainer-owned lane, benchmark run, or private artifact is duplicated.

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 huangruiteng left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

动机

审查精确 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.

@huangruiteng

Copy link
Copy Markdown
Collaborator

Merge-readiness qualification for exact head e6ad8790b56369850b7a83e1ae2f0d866db61ac1: HOLD; no merge performed.

This is the docs-only IP-036 catalog change. The published exact-head review approved its one-file scope after the catalog smoke and git diff --check passed. No runtime or authority behavior changes were in scope; the suggested PR-description cleanup remains non-blocking. No additional refactor is warranted for this documentation boundary.

The current loopx pr-review --goal-id loopx-meta --check-merge-readiness 5027@e6ad8790b56369850b7a83e1ae2f0d866db61ac1 returns ready=false solely because GitHub reports merge_state=BEHIND (merge_state_requires_update). The published review remains valid for this head and there are no unresolved review threads. CI was not queried under this Goal's wait_for_ci=false policy; the earlier local checks were not rerun for this qualification. Update the branch/base relationship, then recheck the resulting exact head and its required validation before any maintainer merge decision. This comment grants no merge authority.

@yuedai-pbc

Copy link
Copy Markdown
Contributor Author

已修正 PR 正文:之前那条是本地写法失误(-f body=@<path> 没被展开,字面量直接进了描述),现在换成了公开可读的目标、范围、验证与边界披露(含 Closes #5026)。issue #5026 与 #4954 那条评论的内容不受影响。

关于第 3 条规则的时态,同意你的判断并已按此边界写:本条目引用 #5007 作为公开反例、引用 #5012 作为提案中的落盘顺序,没有把 lease replay 测试当作 Todo create 已修复的证据,也不依赖其中任何一条合并。等 create 路径的修复落地后,需要更新的就是这一段的时态("proposes" → 现有实现),我已把它记成本条目的唯一后继维护点;除此以外这个切片没有遗留工作。

复核数字与正文一致:exact head e6ad8790b 上 python3 examples/interaction-pattern-catalog-smoke.py → ok,base-to-head git diff --check 干净,未运行产品行为测试(无代码/测试变更),也未轮询远端 CI。

@huangruiteng
huangruiteng merged commit 6e9ac25 into loopx-project:main Sep 25, 2026
19 checks passed
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.

2 participants