Documentation
¶
Overview ¶
ledger.go —— 台账视图(单号状态的唯一真相)。
存在的理由:部署清单此前把**任何** issue 证据都当成缺口,于是台账里早已 「✅ 已合入」的单(#262 / #273)仍被算成缺口 ⇒ 能力永远停在 partial ⇒ 矩阵在骗宿主(说「你还缺这个」,其实早有了)。
口径只有一条:**issue 证据只有在对应单号「仍开着」时才算缺口**。 派生逻辑全部走 internal/ledgerstatus,本包不自己再读一遍台账—— 两份解析必然漂移,而漂移的方向恰好是「清单判的和台账写的不是一套」。
Command deploymatrix 校验部署配方能力清单(docs/DEPLOY-MATRIX.yaml)。
存在意义(issue #277):部署形态的推荐组合此前散落在 USAGE、examples 包 文档与外部评审的场景表里,没有一份可查、可比的清单回答「这套组合缺哪些 能力才能上生产」。本命令把清单变成**可执行声明**:
- 每条能力的证据必须可解析: - contract: path#Symbol —— 文件存在且该符号真的声明在文件里(go/ast); - gate: target —— Makefile 里有这个目标; - issue: #N —— 该单号出现在仓内 docs/*.md 或 CHANGELOG(本地可查); - doc: path —— 文件存在;
- 能力的 state(available / partial / missing)必须与证据形态一致: - available = 至少一条 contract/gate 且无 issue 缺口; - partial = 既有 contract/gate 又有 issue 缺口; - missing = 只有 issue(还没有可查的契约/门禁落点); 其中「issue 缺口」= **该单号在台账里仍开着**:台账(docs/DISTRIBUTED- EVOLUTION-*.md)是单号状态的唯一真相,已合入的单不再是缺口—— 把它算成缺口,能力就永远停在 partial,矩阵等于对宿主说「你还缺这个」 而它其实早有了(台账 §15 形态 (a) 的同一个坑的另一个面);
- 场景的 readiness 必须等于必需能力的最坏状态;
- docs/USAGE.md 的 deploy-matrix 机器口径块必须与清单逐行一致 (场景 id / 推荐存储 / Worker 模式 / 当前状态)——不一致即红;
- 未登记 / 重复 / 引用失效 / 状态谎报一律红。
失败形态是**变红**:清单缺失、USAGE 块缺失、证据引用失效都报错退出, 不静默跳过。
matrix.go —— 清单装载与判定(issue #277)。
usage.go —— USAGE 机器口径块与清单的逐行比对(issue #277)。
Click to show internal directories.
Click to hide internal directories.