Skip to content

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

Open
kokokoXUY wants to merge 1 commit into
loopx-project:mainfrom
kokokoXUY:codex/retired-prototype-doc-citations
Open

kokokoXUY wants to merge 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.

loopx-project#5105 retired the Stage 0 Python prototype and removed its tests, and marked the
evidence log as a historical archive. Three current-facing documents still
pointed at files that no longer exist.

- `docs/book/chapters/core-state-machines.md` and its English counterpart list
  `coordination/executor.py` among the source anchors of the guarded-commit
  path; that link no longer resolves. Point at
  `coordination/authority_core.py`, whose own contract states that a returned
  transition "is a proposal, not proof that any write committed" — the same
  boundary the chapter describes.
- `docs/concepts/interaction-pattern-catalog.md` cites
  `test_coordination_recoverable_execution.py:693` and `:694` plus
  `test_coordination_provider_parity.py:222` as the evidence for "recover by
  readback, not by blind retry", and names the same two files in its
  Validation section. Both citations move to
  `tests/control_plane_ts/authority_store_conformance.ts`: the shared suite is
  registered once per provider store, and it 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`.

`docs/architecture/rfcs/shared-goal-authority-state-provider-v0-evidence.zh-CN.md`
is deliberately unchanged: loopx-project#5105 already declared it a historical evidence
archive, so the paths inside it describe the retired baseline on purpose.

Validation: `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, and both replacement paths were checked to exist
on `main` before the edit.

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,没有阻塞性发现。新引用不仅存在,也确实覆盖了原文要解释的 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.

This branch has not been deployed

No deployments
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