Skip to content

docs: repoint the last citations to the retired Python prototype - #5131

Merged
huangruiteng merged 1 commit into
loopx-project:mainfrom
kokokoXUY:codex/retired-prototype-doc-citations
Sep 27, 2026
Merged

huangruiteng merged 1 commit into
loopx-project:mainfrom
kokokoXUY:codex/retired-prototype-doc-citations

Conversation

@kokokoXUY

Copy link
Copy Markdown
Contributor

Goal And Delivered Outcome

  • Goal/source and gap: refactor(authority): retire Python prototype and qualify native File/SQLite #5105 retired the Stage 0 Python prototype and removed its tests, and already marked docs/architecture/rfcs/shared-goal-authority-state-provider-v0-evidence.zh-CN.md as a historical archive. Three current-facing documents still pointed at files that no longer exist, so a reader following them lands on nothing: both core-state-machines book chapters list coordination/executor.py among their source anchors, and docs/concepts/interaction-pattern-catalog.md cites test_coordination_recoverable_execution.py:693/:694 and test_coordination_provider_parity.py:222, in the pattern itself and again in its Validation section.
  • Observable before → after: the chapter anchor links 404 and the catalog's evidence citations cannot be opened; after the change every path resolves, and each replacement was checked to exist on main before the edit.
  • Issue/task and intended base: related to docs: repoint the GH-C100 validation at the ladder that owns it now #5125, which fixed the same retirement's stale references in CI and on the contributor task board. Intended base main.

Scope And Continuation

  • Completed scope and remaining work: the two chapters point at coordination/authority_core.py — whose own contract states a returned transition "is a proposal, not proof that any write committed", the boundary the chapters describe — and the catalog's two citations move to tests/control_plane_ts/authority_store_conformance.ts, which registers one shared suite per provider store and asserts that a replayed call reports replayed with an identical original_receipt and an unchanged authority, while the same operation id carrying a changed intent is rejected with coordination_operation_identity_mismatch.
  • Slice boundary / successor: complete. I deliberately left the RFC evidence log alone: its remaining paths are correct inside a document that declares itself a historical archive. The catalog's receipt_index clause was dropped rather than re-pointed, because I could not find a current assertion of that specific claim.

Validation

  • Tested revision: 858b2478ed6878a40efa04274b96bd9b6ba86b61
  • Run state: finished
  • Input classes: none
Check kind Result Public-safe evidence / limitation
static passed loopx check --scan-path docs/book/chapters --scan-path docs/book/en/chapters --scan-path docs/concepts → errors=0 with a clean 47-file public boundary scan; both replacement paths resolved against current main.
manual passed The branch diff against main contains only the intended lines — two anchor lines in the chapters, and the two citation blocks in the catalog — with no other document text touched. The Chinese and English chapters remain distinct files (29531 and 44456 characters).
manual passed Every replacement was verified at its source before being cited: authority_core.py's module docstring, and lines 833–843 of authority_store_conformance.ts, which I read rather than inferred from a search hit.
  • Coverage and gaps: documentation only, no runtime path. The line references in the new citations are pinned to the file as of the tested revision and will drift with the file, which is the same exposure the previous citations had; I chose :833 (the replay request) rather than a single assertion line so the reference stays meaningful if the block moves by a line or two.

Frontend / Visual Evidence

Not applicable: documentation only.

huangruiteng
huangruiteng previously approved these changes Sep 26, 2026

@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.

结论:APPROVE,没有阻塞性发现。新引用不仅存在,也确实覆盖了原文要解释的 proposal/commit 边界和回执重放。

动机

#5105 删除了未被生产入口使用的 Python 原型,两个书籍章节和 IP-036 却仍引用已删除的源码、测试。我在基线与当前提交都确认了旧文件不存在。本 PR 完成的是“修复当前文档的证据入口”这一独立结果,不是在宣称整个 shared-authority 迁移已经完成。

改动思路

复用现有 owner,比恢复原型或补一层兼容文件更合理。章节指向的 authority_core.py 明确说明返回 transition 只是 proposal,不证明写入已提交;持久化结果仍由实际 writer/store 负责。目录则转向由各 provider suite 注册的共同 conformance,文档本身不取得新的状态或重试权限。

具体改动

关键内容讲解

两个中英文章节各替换一个源码锚点,保留原先“读 basis → proposal → guarded commit → receipt → readback”的解释。IP-036 的新引用位于 authority_store_conformance.ts:833–844:同一 archive 请求再次执行返回 replayed,original_receipt 相同,独立 loadAuthority() 结果不变;同一 operation id 携带不同 intent 则返回 coordination_operation_identity_mismatch。原先没有当前断言支撑的 receipt_index 数量描述被删除,没有拿文件存在来冒充同等证据。

对主干的风险

完整差异只有三份文档的 11 增/12 删,没有改变默认行为、类型化状态规则、权限、调度或机器义务。最强反例是“新路径存在,但实际测试不支持原文”。对此我读取了断言和 File、SQLite、NoKV、PostgreSQL 的注册入口,并实际运行引用的 replay 用例:File/SQLite/模拟 NoKV 共 3/3 通过,零失败、零跳过。

本地 interaction-pattern-catalog-smoke.py、47 文件公开边界扫描及 git diff --check 均通过;对已取回的当前 main 0b715579d 做 merge-tree 也无冲突。没有查询、等待远端 CI。NoKV 是仓库的模拟 transport,PostgreSQL 只核对注册条件,不能把这些结果扩写成真实服务资格证明。

我的整体评价

长期运行语义保持不变,读者体验改善:原先不可打开的引用现在能到达真实 owner 与已执行的重放断言。未来化简检查已做:本次直接复用共享 conformance,未新增重复 smoke、兼容入口或控制面词汇。行号随源码移动仍可能漂移,后续可辅以测试名称定位;这不阻塞当前准确的文档修复。未做托管书籍渲染,且本次没有首屏或布局修改。

English verdict: APPROVE - exact head 858b247; current references resolve and match the independently executed native replay contract.

@kokokoXUY
kokokoXUY force-pushed the codex/retired-prototype-doc-citations branch from 858b247 to 09a3725 Compare September 27, 2026 02:26
loopx-project#5105 retired the Stage 0 Python prototype and removed its tests, and marked the
evidence log as a historical archive. Current-facing documents still pointed at
files that no longer exist.

- both `core-state-machines` book chapters list `coordination/executor.py` among
  their source anchors; the link no longer resolves, so they now point at
  `coordination/authority_core.py`.
- `docs/concepts/interaction-pattern-catalog.md` cited the retired Python tests
  for its replay-and-receipt evidence; it now cites
  `tests/control_plane_ts/authority_store_conformance.ts`, the shared suite that
  runs once per provider store, including the operation-identity rejection.
- the same catalog listed `examples/benchmark-lifecycle-state-smoke.py` as
  validation for its external-evidence entry; that script now lives under
  `deprecate/benchmark-legacy/`, so the line names where it actually is.

Rebased onto current main.

Signed-off-by: kokokoXUY <13682395396@163.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.

结论:APPROVE,没有阻塞性发现。本次按当前 head 重新核对了完整差异与引用证据,没有继承上一轮批准。

动机

#5105 退役 Python 原型后,当前书籍章节和交互模式目录仍指向不存在的实现与测试,读者无法沿证据理解 proposal、commit 和 replay 的区别。本 PR 修复的是这些当前文档的证据入口,不是重新建立已退役原型,也不代表整个 provider 迁移完成。

改动思路

复用真实的当前 owner 和共享 conformance,比恢复旧文件或新增一套兼容测试更合适。authority_core 的模块契约明确指出 transition 只是 proposal;持久化效果仍由 writer/store 负责。重放证据转向实际注册到 provider suite 的 TS 测试,未把路径存在当作语义等价证明。

具体改动

关键内容讲解

中英两个 core-state-machines 章节各替换一个源码锚点,保留“读 basis→proposal→guarded commit→receipt→readback”的解释。IP-036 指向 authority_store_conformance.ts:833–844:同一 archive 请求返回 replayed、original_receipt 相同、独立 loadAuthority 不变;同一 operation id 改变 intent 则拒绝,authority 仍不变。原先没有当前断言支撑的 receipt_index 数量描述已删除。

相较上次引用修复,当前 head 还把 IP-014 的 benchmark smoke 引用改到实际存在的 deprecate/benchmark-legacy 路径,并标为 retired。该补充是历史证据导航,不是把退役 runner 重新纳入活跃 CI。历史 RFC 已有清楚的 archive 声明,保留其中旧路径是有意的。基线已合入的 pattern admission 规则不是本 PR 新增政策。

对主干的风险

完整 base-to-head 只有三份 Markdown 的 12 增/13 删,没有运行时、机器义务、权限或默认行为修改,也没有首屏/布局改动。最强反例是“新引用存在但测试不支持原文”。我重新读取 exact-head 断言和 File、SQLite、NoKV、PostgreSQL 注册入口,并亲自执行所引用 replay 测试:真实 File/SQLite 以及模拟 NoKV 共 3/3 通过、零失败和零跳过。NoKV transport 是模拟的,PostgreSQL 只核对注册条件,不能扩写为真实服务资格证明。

interaction-pattern-catalog-smoke 与 diff check 通过。使用相同隔离空 registry 的基线/head 公共边界扫描均为 47 文件、errors=0;没有修改活动 Goal 作为测试。原 GitHub 仓库链接经 API 确认解析到 loopx-project/loopx;三个替代目标在 checkout 存在。与已取回 main 74d372c 的 merge-tree 无冲突。没有查询、等待远端 CI,也未执行退役 benchmark smoke。

我的整体评价

长期执行语义保持不变,读者体验改善:现行文档现在能到达真正的 proposal owner 和已执行的回执重放断言。未来化简检查已做:直接引用共享 suite,删除无当前证据支持的细节,未增加重复 smoke 或兼容入口。没有新增共享词汇;现有 replay/identity contract 的解释与实现一致。行号随源码移动仍可能漂移,辅以测试名称可以更稳健;本次未做托管书籍渲染,但这不阻塞纯引用修复。

English verdict: APPROVE - exact head 97abaed; current references resolve and match independently executed native replay assertions, with retired evidence explicitly labeled.

@huangruiteng
huangruiteng merged commit 76ff7c7 into loopx-project:main Sep 27, 2026
22 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