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

5.8 KiB
Raw Blame History

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。