1c58f1ef7e
为什么: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 用例。
90 lines
5.6 KiB
Markdown
90 lines
5.6 KiB
Markdown
# 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,或把
|
||
已撤销的激活悄悄删掉。 |