Files
knowledge-governance/docs/architecture/ds01-activation-evidence.md
T
姚章浩 24608e132b fix(library): 区分维护窗口指纹与恢复目标指纹
为什么:维护窗口记录的是部署/实例指纹(journal 与 library_instance_maintenance),
observeRestoreTarget 返回的是内容/索引/桶身份;两者本来不同层(r38 实测
dbe7… vs bb3f…)。v2 证据拆成 target_fingerprint 与 restore_target_fingerprint:
前者绑定窗口与治理行,后者绑定激活时的实时只读观察,避免用一个值冒充两层。
2026-11-02 18:54:18 +08:00

86 lines
5.8 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# DS01 激活证据的不变量(v2)
状态:源码与隔离测试已实现;**未在正式治理库执行激活**。
相关实现:`internal/libraryrelease/restore_dispatch_activation.go`、
`internal/platform/postgres/library_restore_dispatch_activation.go`、
`internal/libraryfreeze/journal_evidence.go`。
## 1. 当前生产装配从哪里取得可核证据
```
worker(LIBRARY_RESTORE_DISPATCH_V2=true)
└─ librarymaintenance.Manager(LIBRARY_TARGET_*)
└─ libraryfreeze.Coordinator
├─ 关闭入口 → 读 gate drain.json(closed / drained / active_at_close)
├─ 等后台静默 → QuiesceProof(depth/pending_ops/unsettled=0,稳定窗口)
├─ 停写者 → Controller.Stop + Inventory 复核 + 退出码
└─ 写 <LIBRARY_TARGET_JOURNAL_ROOT>/<job>.json(state=held)
└─ library_instance_maintenance(治理库):instance / owner_job_id / target_fingerprint /
level=instance / services / state / released_at
```
激活是**部署动作**,不是业务请求:`Store.ActivateRestoreDispatch` 只在部署流程里调用。
`Store.WithRestoreDispatchEvidence(LIBRARY_TARGET_JOURNAL_ROOT)` 是唯一允许读取 journal 的根;
未配置该根 ⇒ `ErrRestoreDispatchActivationDisabled`(能力关闭),不退回"只看字符串"。
## 2. 证据文件只声明身份,不声明结论
v2 证据文档(`protocol_version=2`)字段。注意:台账行 `library_index_restore_dispatch_activation.protocol_version`
仍是 1(迁移 78 的派发协议身份约束),证据文档版本与台账协议版本不是同一个数字:
| 字段 | 含义 |
|---|---|
| `target_identity` | 目标身份 |
| `target_fingerprint` | 维护窗口/部署目标指纹(64 位 sha256 hex),必须等于 journal 与维护行 |
| `restore_target_fingerprint` | 激活时对恢复目标(库/索引/桶)的实时观察指纹 |
| `target_instance` | 治理库维护窗口的实例名,必须等于 journal 的 `source` |
| `governance_database` | 当前治理库名,与 `current_database()` 比对 |
| `protocol_build` | 必须是**运行中二进制**的 `version.DisplayVersion()` |
| `maintenance_job` / `maintenance_journal` | 维护窗口作业;journal 名必须恰好是 `<job>.json` |
| `maintenance_journal_sha256` | 磁盘 journal 字节的 sha256(不是文件内自报值) |
| `writers[] {name, kind, instance_id}` | 旧 writer 集合:名字对治理库 `services`,实例 ID 对 journal `services[].id` |
**没有** `stopped` / `queue_drained` / `exited_at` / `drain_evidence` 这些调用方布尔字段。
"已退出、已排空"只能从 journal 事实与治理库行推出来。
## 3. 激活门逐项不变量
- **A1 来源**:journal 由 `libraryfreeze` 写、位于配置的私有根(目录 0700、非符号链接);
文件以 `O_NOFOLLOW` 打开、≤1MiB、严格 JSON(未知字段拒绝)。
- **A2 摘要**:磁盘字节 sha256 == 证据声明值;写入台账的 `drain_evidence_digest` 是这个值。
- **A3 窗口状态**:journal `state=held`、`level=instance`;已 `recovered`/`released` 的窗口
不能证明"旧 writer 仍停着"。
- **A4 实例绑定**:journal `source` == 证据 `target_instance`,且 == 治理库
`library_instance_maintenance.instance`。
- **A5 作业绑定**:journal `job` == 证据 `maintenance_job` == 维护行 `owner_job_id`。
- **A6 目标绑定**:journal `target_fingerprint` == 证据 `target_fingerprint` == 维护行指纹;
证据 `restore_target_fingerprint` == 调用方激活时对恢复目标的只读观察值。两者是
不同层(实例/部署 vs 内容/索引/桶身份),不能用一个值互相顶替。
- **A7 入口排空**:`ingress_closed=true`、`drain_verified=true`、gate `closed && drained &&
active_at_close==0`。
- **A8 后台静默**:`quiesce` 存在且 depth/pending_ops/unsettled 全 0、有合法 digest、
停写后复核(`post_stop_at ≥ proven_at`、`post_stop_depth=0`、`post_stop_digest=digest`)。
- **A9 writer 集合**:证据 writer 名字集合 == 维护行 `services`;实例 ID 集合 == journal
`services[].id`;每个 writer `stop_requested=true` 且有 `exit_code`;数量必须一致。
- **A10 有效性**:停写/排空观察(`quiesce.post_stop_at`)在 2 小时有效期内;
证据 `attested_at` 不早于该观察、不晚于未来 5 分钟;窗口 `acquired_at` 早于观察。
- **A11 现场身份**:`current_database()` 等于证据库名;运行构建必须已注入身份且等于
`protocol_build`;调用方传入的目标指纹必须等于证据指纹。
- **A12 失败关闭**:任一不满足 ⇒ 不写 activation 行;已撤销行的终局性仍由迁移 78 的
trigger 保证(`revoked_at→NULL`、删行、状态倒退都拒绝)。
## 4. 它不证明什么
- 不独立观测"外部 writer 进程此刻不在运行";A7–A9 是维护链自己的受控观察
(入口 drain、退出码、后台静默),不是通用进程扫描。
- 不提供 ES 端 fence,也不保证已 `dispatching` 的旧 owner 不会迟到一次。
- 不抵抗超级管理员禁用 trigger 或恢复旧 PG 快照。
## 5. 测试如何证明它不是"验字符串"
反例(真 PG,见 `library_restore_dispatch_linearization_test.go`):伪造 journal 摘要、
摘要计算后替换真实文件、错 writer 名字/实例、无退出码、从未要求停、入口未排空
(`drained=false` / `active_at_close=1` / `drain_verified=false`)、停写观察过期、
证据过期、治理库身份不符、现场指纹不符、构建不符、维护窗口已释放、作业不属于窗口、
journal 已 recovered、未配置受信根。全部要求零 activation 行;正例才产生 1 行,并把
已核事实(journal 摘要、gate、quiesce、每个 writer 的退出码)写进 `evidence.verified`。