Files
knowledge-governance/docs/architecture/ds01-restore-dispatch.md
T
姚章浩 513aa9e6f5
build / build (push) Has been cancelled
fix(library): 收紧恢复派发真实绑定与同事务授权
为什么:Astra 复核证实五组实现缺陷——正式装配缺 scope/快照且来源与 before-image
混用;激活撤销不在 CAS 事务内、lease 用事务起始时间;激活只接受任意字符串且撤销可
被 SQL 重置/删除;准入忽略绑定冲突与 prepared 矛盾、收尾只看当前 plan;prepared 已
提交但 mark-intent 未落盘时被误判 legacy。

改了什么:
- 绑定来自原锚点(scope/来源快照/backup/实例/目标指纹/索引 UUID/恢复投递),每次
  重建都实时重读目标身份并与冻结值比较;
- activation 行锁与 CAS 同事务,lease 用 clock_timestamp(),同事务核对 job/operation/
  attempt/维护窗口/恢复 queue 与 operation,同 effect 换 plan 摘要拒绝;
- 激活消费带摘要的证据文件(writer 退出+排空、目标/治理库身份、有效期),撤销终局,
  down 在 activation 有行时拒绝;
- 前置/收尾共用权威窗口全集,绑定冲突与 prepared 矛盾零写 held,合法 dispatching+
  精确 marker 仍可确认;
- prepared 无 mark-intent 仅在绑定一致且无矛盾时补同内容意图,旧无台账意图仍 held。

验证:真 PG 锁等待覆盖撤销先胜/CAS 先胜/等锁跨租约/错锚点/plan 别名/恢复投递;
COMMIT 已到服务端但回包丢失与未决事务分别读回;真 ES+PG+对象存储的 DS01 用例全部
通过;go test ./... 全绿。未迁移正式库、未部署、未激活。
2026-11-02 18:09:26 +08:00

5.4 KiB
Raw Blame History

DS01:删除型恢复的派发台账(实现说明)

状态:源码与隔离测试已实现;未在 8088 / 正式治理库 / 业务 WeKnora 上执行 DDL 或激活。 设计正本:astra-ds01-design.md。有限验收表:握手目录 ds01-acceptance-freeze.md。

它证明什么、不证明什么

证明:对一个固定的删除型恢复 effect(Before 非空、After 空,恢复写入是独占 _create), 台账里 prepared 意味着没有任何遵守本协议的派发者取得过发送许可;dispatching 之后永不回退, 因此"曾经发送过"不可能再表现为 prepared。

不证明:ES 端 fencing;已 dispatching 的旧 owner 不会迟到一次;目标历史上没被外部写过; PG 快照回滚/手工删行之后的协议有效性(这类历史倒退必须 held 并人工处置)。

状态与唯一发送路径

prepared --(CAS, 同一短事务内校验 activation/job/operation/attempt/lease/binding)--> dispatching
dispatching --(真实 receipt + 当前 owner/lease)--> marker_confirmed
  • 发送许可只由 AcquireRestoreMarker 在 COMMIT 明确返回后给出,RestoreSendPermit 消费一次即作废。
  • CAS 事务按 job → operation → activation → active attempt → effect 取锁:
    • 激活撤销(revoked_at)与 CAS 在同一事务里线性化:撤销先完成则拒绝,CAS 先取锁则撤销排队;
    • lease 用 clock_timestamp() 在取锁之后判定,等锁跨过租约即拒绝;
    • attempt 必须属于原 window job;job 的 owner/epoch/lease、operation 的 scope/来源快照/ 已登记写集摘要、实例维护窗口(未释放且属于该作业)逐项核对;
    • 恢复路径另核 recovery queue job(运行中且有 lease)与 recovery operation(kind=recover、 绑定同一 backup);
    • 同一 effect 换 plan 摘要会被台账拒绝(不能靠新 key 重开证明)。
  • 不可变绑定来自原持久锚点:scope、来源快照(发布基线)、写前镜像(backup)、目标实例/ 实际指纹/索引 UUID、变更/标记/请求摘要与 attempt 身份。来源与写前镜像不允许是同一份快照。 目标指纹与索引 UUID 每次重建绑定都实时重读并与本次恢复冻结值比较:同名重建的目标/索引 无法复用旧证明。
  • 恢复期 _create 只从 sendRestoreMarkerOnce 发出;preflight/故障钩子都在 CAS 之前。
  • 请求设置 GetBody=nil,Go 传输层不会在 keep-alive 重连时重放该 mutation。

Restore 准入与收尾

Restore 在 AdoptWriteSet 之后、任何阶段写入之前调用纯读准入,并先对照原 window 的 权威台账全集(跨 plan 摘要):出现另一份 plan、计划外 effect 或不可识别状态立即 held。

台账/证据 结果
无意图、无证据、无台账 首次恢复,可建立 prepared
旧意图、无台账 held(旧协议未知历史,不补 prepared)
prepared + 绑定冲突(Held) held
prepared + 已存在 claimed/finalize/目标精确 marker held(协议证据矛盾)
prepared + 无矛盾 可竞争一次许可
prepared + mark-intent 未落盘(文件失败/崩溃区段) 核对绑定一致后补写同内容意图,再竞争
dispatching + 目标无精确 marker held(零新发送)
dispatching + 精确 marker/内容/世代 只走确认分支,不发 create
marker_confirmed + 无 restored 证据 held
restored 证据与目标内容/世代一致 终态,允许重放

收尾前(整库指纹比对之后)以同一份权威全集再检查一次:任何 prepared/dispatching 记录、 计划外记录、换 plan 摘要、或缺失 restored 文件证据的 effect 都拒绝返回成功,维护窗口不会 被释放。

激活(部署动作,不属于本开发包)

新能力默认关闭。启用需要两步,缺一不可:

  1. 部署配置 LIBRARY_RESTORE_DISPATCH_V2=true(只表示允许装配);
  2. 部署流程生成一份证据文件,并由 Store.ActivateRestoreDispatch 登记。代码会:
    • 重算文件 sha256 并与调用方给出的摘要比较(不接受文件自报值);
    • 严格解析并校验:协议版本、目标身份/实例/指纹、治理库名、协议构建、签署人与时间窗口;
    • 要求每个受控 writer 都登记 stopped + queue_drained + exited_at + drain_evidence;
    • 读取现场 current_database() 与证据里的治理库名比较;
    • 目标身份/指纹与调用方声明的现场身份一致。 任何一项不满足都不建立 active 行。

撤销是终局:revoked_at 一旦写入,SQL 不能改回 NULL、不能改时间,activation 行也不能删除; 重新开放同一物理目标只能换新的目标身份。

边界:代码核验的是证据文件完整性、结构完整性与目标/治理库身份;"这些 writer 确实已退出" 仍是部署流程的受控 attestation(附退出时间与排空摘要),不是本进程能独立观察到的外部事实。

迁移与回滚

  • 000078_library_restore_dispatch.up.sql 只建治理库表与触发器,不碰 WeKnora Schema。
  • 000078_..._down.sql 在 library_index_restore_dispatch 或 activation 表有任意行时拒绝执行: 这些行是"是否发送过 / 是否曾被授权"的唯一证明,抹掉等于把 unknown 伪装成 prepared,或把 已撤销的激活悄悄删掉。