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

84 lines
5.4 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:删除型恢复的派发台账(实现说明)
状态:源码与隔离测试已实现;**未在 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,或把
已撤销的激活悄悄删掉。