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

3.3 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, 同一短事务内校验 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 已退出并排空"的证据:
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 是部署证据的摘要。撤销:

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。