diff --git a/docs/architecture/rfcs/ledger/README.md b/docs/architecture/rfcs/ledger/README.md index 48ba494f19..d111c614b6 100644 --- a/docs/architecture/rfcs/ledger/README.md +++ b/docs/architecture/rfcs/ledger/README.md @@ -18,8 +18,10 @@ same day touch two different files and merge cleanly with no resolution at all. ## Convention - `/YYYY-MM-DD-slug.md` — one directory per RFC, named exactly like - the RFC file it belongs to. Six RFCs carry an execution-ledger appendix, so - an entry has to say which one it extends. + the RFC file it belongs to. Several RFCs carry an execution-ledger appendix, + so an entry has to say which one it extends. The appendix inside the RFC is + titled `Appendix : Execution ledger` and takes whichever letter the + RFC has free. - The name carries the date the work was measured, not the merge date. - Each entry carries a Chinese mirror at `/YYYY-MM-DD-slug.zh-CN.md`, the same rule the RFCs themselves follow. diff --git a/docs/architecture/rfcs/ledger/README.zh-CN.md b/docs/architecture/rfcs/ledger/README.zh-CN.md index 0f6f33243b..b1f1f1f0a3 100644 --- a/docs/architecture/rfcs/ledger/README.zh-CN.md +++ b/docs/architecture/rfcs/ledger/README.zh-CN.md @@ -16,7 +16,8 @@ ## 约定 - `/YYYY-MM-DD-slug.md` —— 每份 RFC 一个目录，目录名与其所属 RFC - 文件名完全一致。有六份 RFC 带执行账本附录，所以条目必须写明它补的是哪一份。 + 文件名完全一致。多份 RFC 带执行账本附录，所以条目必须写明它补的是哪一份。 + RFC 内那一节的标题是 `附录 <字母>：执行账本`，用该 RFC 还没占用的字母。 - 文件名中的日期是**测量**当天，不是合并当天。 - 每条配一份中文镜像 `/YYYY-MM-DD-slug.zh-CN.md`，与 RFC 自身同一规则。 - 每个 RFC 的目录就是该 RFC 的索引。跨 RFC 不设枚举，因为索引行正是本目录要消除的那种 diff --git a/docs/architecture/rfcs/ledger/shared-goal-authority-state-provider-v0/2026-09-19-shared-goal-authority-entries-get-a-ledger.md b/docs/architecture/rfcs/ledger/shared-goal-authority-state-provider-v0/2026-09-19-shared-goal-authority-entries-get-a-ledger.md new file mode 100644 index 0000000000..ae4205e630 --- /dev/null +++ b/docs/architecture/rfcs/ledger/shared-goal-authority-state-provider-v0/2026-09-19-shared-goal-authority-entries-get-a-ledger.md @@ -0,0 +1,38 @@ +# Shared-goal-authority delivery records get a ledger directory + +Non-normative for the shared Goal authority model: it adds no runtime invariant. +It relaxes one condition the ledger check imposed — a ledger directory had to +name an RFC whose *Appendix A* is the execution ledger — and points this RFC's +future delivery records at files. + +- **The cost was measured by the maintainer, not by this entry.** #4677 surveyed + every open PR against `origin/main = d8e7af141` on 2026-09-17 and found 19 of + 34 heads `mergeStateStatus=DIRTY`, three of them (`#3820`, `#4061`, `#4672`) + colliding on this one file. This entry re-measures no head: GitHub computes + mergeability lazily, so a same-day recount is not available without forcing a + computation per PR. +- **Why records collide in this file.** Delivery records for this RFC are dated + subsections inside Appendix C — `Provider-first terminal lifecycle checkpoint + (2026-09-07)`, `Cross-RFC semantic and presentation conformance checkpoint + (2026-09-12)`, `Next delivery and parallel provider work`. They sit at the end + of a 3,125-line English file and a 2,474-line Chinese one, so two branches + recording a delivery insert at the same position by construction. +- **The convention already existed and could not be adopted here.** + `check_rfc_ledger_entries` in `examples/docs-governance-smoke.py` required a + ledger directory's RFC to contain the literal heading + `Appendix A: Execution ledger`. This RFC's Appendix A is + `What This Evidence Proves`, so per-file entries would have meant renumbering + Appendices A-C across both language files — a large mechanical diff that + itself forces rework on the branches the change exists to help. The check now + accepts `Appendix : Execution ledger` in the English document, and this RFC's + Appendix D is the pointer. +- **Existing records stay put**, for the reason the semantic-vocabulary round + recorded on 2026-09-18: they are append-only history nobody edits, so they + were never the thing a later branch conflicts with — the shared insertion + point ahead of them is. +- **What this does not do.** It resolves no conflict that already exists; each + affected branch still rebases once. It does not make a ledger entry + reviewable evidence — entries remain non-normative records of what a change + measured and what it did not establish. And it adds no navigation entry: the + hosted-docs check requires a file for every nav entry, not a nav entry for + every file. diff --git a/docs/architecture/rfcs/ledger/shared-goal-authority-state-provider-v0/2026-09-19-shared-goal-authority-entries-get-a-ledger.zh-CN.md b/docs/architecture/rfcs/ledger/shared-goal-authority-state-provider-v0/2026-09-19-shared-goal-authority-entries-get-a-ledger.zh-CN.md new file mode 100644 index 0000000000..516e204cbf --- /dev/null +++ b/docs/architecture/rfcs/ledger/shared-goal-authority-state-provider-v0/2026-09-19-shared-goal-authority-entries-get-a-ledger.zh-CN.md @@ -0,0 +1,28 @@ +# shared-goal-authority 的交付记录有了自己的账本目录 + +对共享 Goal authority 模型是非规范性的：它不新增任何 runtime 不变量。它放宽了账本 +检查附加的一个条件——账本目录原本必须指向一份"附录 A 就是执行账本"的 RFC——并把本 RFC +后续的交付记录指向这里的文件。 + +- **这笔成本是 maintainer 量出来的，不是本条目量的。** #4677 在 2026-09-17 以 + `origin/main = d8e7af141` 为基线普查了全部 open PR：34 个 head 里 19 个 + `mergeStateStatus=DIRTY`，其中三个（`#3820`、`#4061`、`#4672`）撞在同一份文件上。 + 本条目不重新度量任何 head：GitHub 是惰性计算可合并性的，不在每个 PR 上强制触发一次 + 计算，就得不到当天的复核数字。 +- **记录为什么在这份文件里相撞。** 本 RFC 的交付记录是附录 C 内部的带日期小节—— + `Provider-first terminal lifecycle checkpoint (2026-09-07)`、 + `Cross-RFC semantic and presentation conformance checkpoint (2026-09-12)`、 + `Next delivery and parallel provider work`。它们位于一份 3,125 行英文文件与一份 + 2,474 行中文文件的末尾，于是两个记录交付的分支按构造就会插在同一位置。 +- **约定早就有，但这份 RFC 用不上。** `examples/docs-governance-smoke.py` 里的 + `check_rfc_ledger_entries` 要求账本目录所指向的 RFC 含字面标题 + `Appendix A: Execution ledger`。而本 RFC 的附录 A 是 `What This Evidence Proves`， + 因此要改成一条一个文件，就得把附录 A–C 在两份语言文件里一起重新编号——那是一次很大的 + 机械 diff，本身就会逼这个改动本想帮的那些在途分支重做一遍。现在检查在英文文档里接受 + `Appendix <字母>: Execution ledger`，本 RFC 的附录 D 就是那个指针。 +- **已有记录原样保留**，理由与 2026-09-18 语义词表那一轮记录的一样：它们是没人再编辑的 + 只追加历史，所以从来不是后来分支相撞的对象——撞的是它们前面那个共享插入点。 +- **这次没有做的事。** 它不解决任何已经存在的冲突，受影响的分支仍各自 rebase 一次； + 它不会让账本条目变成可评审证据——条目仍然是"某次改动测到了什么、没有确立什么"的 + 非规范性记录；它也不新增托管文档导航项——那边的检查要求每个导航项都有对应文件， + 而不是每个文件都要有导航项。 diff --git a/docs/architecture/rfcs/shared-goal-authority-state-provider-v0.md b/docs/architecture/rfcs/shared-goal-authority-state-provider-v0.md index a9725b7b22..840ca41f4f 100644 --- a/docs/architecture/rfcs/shared-goal-authority-state-provider-v0.md +++ b/docs/architecture/rfcs/shared-goal-authority-state-provider-v0.md @@ -3125,3 +3125,21 @@ soak, release, merge and live promotion retain their respective authorization. | C. Canonical transaction capture | Qualify the implementation merged in #3870 | Transaction-bound outbox capture targets the one `coordination.runtime_shadow` lineage and retains complete versioned Todo/lease records. Finish sustained mixed-writer parity, explicit-clear/omission coverage, and event-only Todo recovery evidence. | Can run in parallel with P, but both C and the selected provider profile must finish before parity or promotion integration. | | I. Binding and qualification integration | After C and the selected profile's qualification | Bind one exact provider lineage, field manifest, source revision, digest, and cursor; qualify explicit v0 import, ordering/archival/consumer parity, and recovery/capacity without consulting legacy state for missing fields. | Long-goal local integration requires L and does not wait for P. PostgreSQL joins only when its own P holds pass. | | F. Promotion and cleanup | After I and explicit maintainer approval | Complete provider-first CLI routing, the lock-owning promotion orchestrator, compatibility projection outbox, post-promotion fenced export/rollback, then delete duplicate reference aggregates and flip the reviewed stage/hold declarations. | Each profile must pass C, I, and its own provider qualification; long-goal local promotion additionally requires L, and PostgreSQL requires P. | + +## Appendix D: Execution ledger + +Delivery records for this RFC are files under +[`ledger/shared-goal-authority-state-provider-v0/`](ledger/shared-goal-authority-state-provider-v0/), +one dated entry per change, named and paired per +[the ledger convention](ledger/README.md). An entry states what the change +measured, what it changed, and what it did not establish. + +New records go there instead of into the dated sections of Appendix C. Those +sections stay as they are: append-only history that nobody edits, and rewriting +them into files would produce a large mechanical diff that forces rework on the +open branches it is meant to help, while fixing nothing. The reason is measured, +not assumed — see +[`2026-09-19-shared-goal-authority-entries-get-a-ledger.md`](ledger/shared-goal-authority-state-provider-v0/2026-09-19-shared-goal-authority-entries-get-a-ledger.md). + +`examples/docs-governance-smoke.py` checks the entry naming, the Chinese mirror +beside each entry, and that this appendix exists for the directory it names. diff --git a/docs/architecture/rfcs/shared-goal-authority-state-provider-v0.zh-CN.md b/docs/architecture/rfcs/shared-goal-authority-state-provider-v0.zh-CN.md index e1164ae2d7..30fe774ee4 100644 --- a/docs/architecture/rfcs/shared-goal-authority-state-provider-v0.zh-CN.md +++ b/docs/architecture/rfcs/shared-goal-authority-state-provider-v0.zh-CN.md @@ -2478,3 +2478,16 @@ adapter，也不依赖 PostgreSQL service 部署。 | C. Canonical transaction capture | 资格化 #3870 已合入实现 | transaction-bound outbox 已指向唯一 `coordination.runtime_shadow` lineage，并保留完整带版本的 Todo/lease record；继续完成 sustained mixed-writer parity、explicit-clear/omission 与 event-only Todo recovery 证据。 | 可与 P 并行；但 C 与选定 provider profile 都完成后，才能进入 parity 或 promotion 集成。 | | I. Binding 与资格集成 | C 与选定 profile 的资格化完成后 | 绑定一个精确 provider lineage、field manifest、source revision、digest 与 cursor；资格化显式 v0 import、排序/归档/consumer parity 与 recovery/capacity；缺字段时不得查询 legacy state 补齐。 | 长程本地集成需要 L，不等待 P；PostgreSQL 仅在自己的 P hold 全通过后汇合。 | | F. Promotion 与清理 | I 完成且 maintainer 显式批准后 | 完成 provider-first CLI routing、持锁 promotion orchestrator、兼容投影 outbox、晋升后 fenced export/rollback；随后删除重复 reference aggregate，并翻转经评审的 stage/hold 声明。 | 每个 profile 必须通过 C、I 与自身 provider 资格化；长程本地晋升还需 L，PostgreSQL 还需 P。 | + +## 附录 D：执行账本 + +本 RFC 的交付记录是 [`ledger/shared-goal-authority-state-provider-v0/`](ledger/shared-goal-authority-state-provider-v0/) 下的文件， +一次改动一条带日期的条目，命名与镜像配对遵循 +[账本约定](ledger/README.zh-CN.md)。一条条目写清这次改动测到了什么、改了什么、以及没有确立什么。 + +新记录写在这里，而不再写进附录 C 的那些带日期小节。附录 C 里已有的内容原样保留：它们是没人再编辑的只追加历史， +把它们改写成文件只会产生一次很大的机械 diff，逼那些在途分支重做一遍合并——而这正是本改动想帮的对象，且什么都没能修好。 +理由是量出来的，不是猜的，见 +[`2026-09-19-shared-goal-authority-entries-get-a-ledger.zh-CN.md`](ledger/shared-goal-authority-state-provider-v0/2026-09-19-shared-goal-authority-entries-get-a-ledger.zh-CN.md)。 + +`examples/docs-governance-smoke.py` 校验条目的命名、每条旁边的中文镜像，以及账本目录所指向的这份附录确实存在。 diff --git a/examples/docs-governance-smoke.py b/examples/docs-governance-smoke.py index 557e960c57..3402e469d4 100644 --- a/examples/docs-governance-smoke.py +++ b/examples/docs-governance-smoke.py @@ -203,6 +203,10 @@ def check_rfc_language_mirrors() -> None: LEDGER_ENTRY_NAME = re.compile(r"^\d{4}-\d{2}-\d{2}-[a-z0-9]+(?:-[a-z0-9]+)*$") +# The appendix that points at the ledger directory is whichever one an RFC has +# free: an RFC whose Appendix A carries other content adopts a later letter +# rather than renumbering history and forcing every open branch to re-resolve it. +LEDGER_APPENDIX_HEADING = re.compile(r"^## Appendix [A-Z]: Execution ledger", re.MULTILINE) def check_rfc_ledger_entries() -> None: @@ -219,19 +223,21 @@ def check_rfc_ledger_entries() -> None: return assert (ledger / "README.md").exists(), "ledger README missing" assert (ledger / "README.zh-CN.md").exists(), "ledger README missing its Chinese mirror" - # Six RFCs carry an execution-ledger appendix, so entries are shared and + # Several RFCs carry an execution-ledger appendix, so entries are shared and # must say which one they belong to. The RFC slug is a directory, and the # directory has to name a real RFC: an entry cannot claim an RFC that does # not exist, and the per-RFC listing stays the index. scopes = sorted(path for path in ledger.iterdir() if path.is_dir()) assert scopes, "ledger has no per-RFC directories" for scope in scopes: - appendix_a = DOCS / "architecture" / "rfcs" / f"{scope.name}.md" - assert appendix_a.is_file(), ( + rfc_document = DOCS / "architecture" / "rfcs" / f"{scope.name}.md" + assert rfc_document.is_file(), ( f"ledger directory {scope.name}/ does not name an RFC: " - f"{appendix_a.relative_to(DOCS.parent)} does not exist" + f"{rfc_document.relative_to(DOCS.parent)} does not exist" ) - assert "Appendix A: Execution ledger" in appendix_a.read_text(encoding="utf-8"), ( + assert LEDGER_APPENDIX_HEADING.search( + rfc_document.read_text(encoding="utf-8") + ), ( f"{scope.name} has a ledger directory but no execution-ledger appendix" ) for entry in sorted(scope.glob("*.md")):