Files
knowledge-governance/docs/architecture/ds01-restore-dispatch.md
T
姚章浩 1c58f1ef7e fix(library): DS01 激活消费真实维护 journal 证据
为什么:v1 激活门只重算调用方自填 JSON 的 sha256,stopped/queue_drained 仍是声明,
不是排空事实。v2 证据只声明身份,事实改由 Store 读取维护窗口 journal(入口
drained+active_at_close=0、quiesce 全零且停写后复核、writer stop_requested+退出码)
与治理库实例维护行(同作业/实例/指纹/level、未释放、writer 集合一致)核出;缺受信
journal 根或构建身份未注入即失败关闭。

同时把 r38 激活移到维护窗口 held 的当下(barrier 点,真实只读观察),更新 PG/adapter
夹具与 F3 反例(伪造/替换摘要、错 writer 集合、未退出、未排空、过期、库/指纹/构建
不符、窗口已释放、journal 已 recovered、未配置受信根),并更名 beforeCommit 用例。
2026-11-02 18:48:10 +08:00

90 lines
5.6 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. 部署流程在**维护窗口 held 的当下**登记激活:`Store` 必须绑定
`LIBRARY_TARGET_JOURNAL_ROOT`(`WithRestoreDispatchEvidence`),由
`ActivateRestoreDispatch` 消费一份 v2 证据文件。
v2 证据只声明身份(目标/实例/治理库/构建、维护作业、journal 文件名与 sha256、
旧 writer 集合);"已退出、已排空"由代码直接读维护 journal 与治理库
`library_instance_maintenance` 行核出:窗口必须 `held`、入口 `closed/drained/
active_at_close=0`、后台 quiesce 全零且有停写后复核、每个 writer 有
`stop_requested` 与退出码、writer 集合与治理库一致、观察在 2 小时内。
没有配置受信 journal 根时返回 `ErrRestoreDispatchActivationDisabled`(能力关闭),
不会退回"三个非空字符串就开门"。逐项不变量见
`docs/architecture/ds01-activation-evidence.md`。
撤销是终局:`revoked_at` 一旦写入,SQL 不能改回 `NULL`、不能改时间,activation 行也不能删除;
重新开放同一物理目标只能换新的目标身份。
边界:代码核验 journal 完整性、身份绑定与维护链自己的停写/排空观察;它不独立扫描
外部进程,也不提供 ES 端 fence。
## 迁移与回滚
- `000078_library_restore_dispatch.up.sql` 只建治理库表与触发器,不碰 WeKnora Schema。
- `000078_..._down.sql` 在 `library_index_restore_dispatch` 或 activation 表有**任意行**时拒绝执行:
这些行是"是否发送过 / 是否曾被授权"的唯一证明,抹掉等于把 unknown 伪装成 prepared,或把
已撤销的激活悄悄删掉。