docs: repoint the last citations to the retired Python prototype - #5131
huangruiteng merged 1 commit into
Conversation
huangruiteng
left a comment
There was a problem hiding this comment.
结论: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.
858b247 to
09a3725
Compare
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>
09a3725 to
97abaed
Compare
huangruiteng
left a comment
There was a problem hiding this comment.
结论: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.
Goal And Delivered Outcome
docs/architecture/rfcs/shared-goal-authority-state-provider-v0-evidence.zh-CN.mdas a historical archive. Three current-facing documents still pointed at files that no longer exist, so a reader following them lands on nothing: bothcore-state-machinesbook chapters listcoordination/executor.pyamong their source anchors, anddocs/concepts/interaction-pattern-catalog.mdcitestest_coordination_recoverable_execution.py:693/:694andtest_coordination_provider_parity.py:222, in the pattern itself and again in its Validation section.mainbefore the edit.main.Scope And Continuation
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 totests/control_plane_ts/authority_store_conformance.ts, which registers one shared suite per provider store and asserts that a replayed call reportsreplayedwith an identicaloriginal_receiptand an unchanged authority, while the same operation id carrying a changed intent is rejected withcoordination_operation_identity_mismatch.receipt_indexclause was dropped rather than re-pointed, because I could not find a current assertion of that specific claim.Validation
858b2478ed6878a40efa04274b96bd9b6ba86b61staticpassedloopx check --scan-path docs/book/chapters --scan-path docs/book/en/chapters --scan-path docs/concepts→errors=0with a clean 47-file public boundary scan; both replacement paths resolved against currentmain.manualpassedmaincontains 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).manualpassedauthority_core.py's module docstring, and lines 833–843 ofauthority_store_conformance.ts, which I read rather than inferred from a search hit.: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.