Files
knowledge-governance/docs/architecture/ds01-restore-dispatch.md
T
姚章浩 7b2ab642f7 docs(changelog): 记录 DS01 恢复派发开发快照
写明能力边界(只续作新协议 prepared、不碰 r33、不声称 ES fence)、
激活两步与 down 拒绝抹证据;操作细节放在架构文档,避免散落在提交里。
2026-11-02 16:28:04 +08:00

71 lines
3.3 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, 同一短事务内校验 job/operation/attempt/lease/binding)--> dispatching
dispatching --(真实 receipt + 当前 owner/lease)--> marker_confirmed
```
- 发送许可只由 `AcquireRestoreMarker` 在 **COMMIT 明确返回后**给出,`RestoreSendPermit` 消费一次即作废。
- 恢复期 `_create` 只从 `sendRestoreMarkerOnce` 发出;preflight/故障钩子都在 CAS 之前。
- 请求设置 `GetBody=nil`,Go 传输层不会在 keep-alive 重连时重放该 mutation。
## Restore 准入与收尾
`Restore` 在 `AdoptWriteSet` 之后、任何阶段写入之前调用纯读准入:
| 台账/证据 | 结果 |
|---|---|
| 无意图、无台账 | 首次恢复,可建立 `prepared` |
| 旧意图、无台账 | held(旧协议未知历史,不补 prepared) |
| `prepared` | 可竞争一次许可 |
| `dispatching` + 目标无精确 marker | held(零新发送) |
| `dispatching` + 精确 marker/内容/世代 | 只走确认分支,不发 create |
| `marker_confirmed` + 无 `restored` 证据 | held |
| `restored` 证据与目标内容/世代一致 | 终态,允许重放 |
收尾前(整库指纹比对之后)再检查一次:仍有 `restored` 缺失或停在 `dispatching` 的 effect ⇒ 拒绝
返回成功,维护窗口不会被释放。
## 激活(部署动作,不属于本开发包)
新能力默认关闭。启用需要两步,缺一不可:
1. 部署配置 `LIBRARY_RESTORE_DISPATCH_V2=true`(只表示允许装配);
2. 部署流程在治理库登记"旧 writer 已退出并排空"的证据:
```sql
INSERT INTO library_index_restore_dispatch_activation
(target_identity, protocol_version, activated_by, drain_evidence_digest)
VALUES ($1, 1, $2, $3)
ON CONFLICT (target_identity) DO NOTHING;
```
`target_identity` 必须等于 `appconfig.Config.LibraryTargetIdentity()` 的值;`drain_evidence_digest`
是部署证据的摘要。撤销:
```sql
UPDATE library_index_restore_dispatch_activation SET revoked_at=now()
WHERE target_identity=$1 AND revoked_at IS NULL;
```
登记的是运维声明,代码只保证"没有登记就不发放许可",不验证声明本身为真。
## 迁移与回滚
- `000078_library_restore_dispatch.up.sql` 只建治理库表与触发器,不碰 WeKnora Schema。
- `000078_..._down.sql` 在 `library_index_restore_dispatch` 有任意行时**拒绝执行**:这些行是
"是否发送过"的唯一证明,抹掉等于把 unknown 伪装成 prepared。