Files
knowledge-governance/internal/libraryrelease/writeset.go
T
姚章浩 98294b9583
build / build (push) Failing after 24s
fix(library): 统一执行身份、终态收尾、准入与数据身份
why:审计 19 项(12 P1 / 7 P2)来自同一批根因,逐点试错会把协议撕成十几份:
  · 意图与执行混为一谈(F01/F15):`library.sync:<scope>:<快照>` 是终身幂等键,
    A→B→A 的第三次发布拿到第一次的历史成功作业,什么都不做;
  · 版本行既是实体又是事件(F02/F09):主键只由 (kind,scope,快照) 决定、写入是
    upsert,第二个作业覆盖 `source_job_id`/`evidence`/`created_at`;
  · 接管没有代次(F13):两个 worker 都能认领同一 pending 作业,失租的旧执行还能
    写业务状态、释放别人的维护锁;
  · 早退与终态没有统一政策(F03/F04/F05/F06):半写窗口的前置检查失败会重新开门、
    服务起不来也照样开入口、journal 终态后收尾不可重建、恢复成功不回写 current;
  · 数据身份与准入各写一套(F07/F08/F14/F17):接管丢了复用语义、全库搬运不改
    location_hash、通用入口可造 library.* 作业、目标模型从没被问过;
  · 存储/容量/UI/CI 判据各自为政(F10/F11/F12/F16/F18/F19)。

what:按批准的一套协议集中实施(详见 handoffs/release-consolidated-implementation/
current-contract.md):
  · operation(一次明确意图)/ attempt(epoch 代次)/ 不可变版本事件 / current 指针;
    治理库迁移 76,只动治理库,不碰 WeKnora Schema/源码/镜像;
  · 所有业务状态、阶段、版本事件、维护锁写入带 epoch 守卫(失租代次写不进去);
    心跳失租立刻取消 handler;
  · 半写窗口早退保持关闭;服务未全部健康绝不开入口;journal 终态可从持久事实重建
    收尾;恢复成功登记 recovery 事件并推进 current;
  · worker 在动维护前核对业务行/kind/scope/队列关联;通用入口拒绝 library.*;
  · 全库搬运重算 location_hash 并与文档级导入共用实现;接管消费写集合的复用决定;
    发布前核目标实时模型契约、容量门禁前置;
  · 存储保护闭包改为全量依赖、类型只认显式登记、保护未知则不出可删候选;
  · 页面核 HTTP 状态与结构、恢复纳入轮询、Wiki 差异覆盖标题/摘要/父级。

how:`make verify` rc=0(16 项必需检查全绿,含 go test 全量与前端 485 例);
`go vet ./...` rc=0;`npx tsc -p tsconfig.json --noEmit` rc=0;逐项负例见各包测试
(F03/F04/F08/F12/F13/F14/F16/F18/F19 都有先红后绿记录)。
未执行:治理库迁移到任何已有库、真实 PG/ES/S3/WeKnora 集成、故障注入、部署。
2026-10-30 16:14:54 +08:00

265 lines
10 KiB
Go

package libraryrelease
import (
"context"
"crypto/sha256"
"encoding/hex"
"encoding/json"
"errors"
"fmt"
"sort"
"time"
)
// WriteSetVersion 是写集合台账的格式版本。读到的版本不认识就拒绝恢复:
// 宁可保持维护,也不要用一份"格式变了但看起来还能读"的记录去删目标数据。
const WriteSetVersion = 1
// WriteSetRow 是台账里的一行:本次发布明确要写的精确身份 + 写前状态。
//
// 为什么需要"写前状态":恢复不能在目标里按"没人引用"推断残渣。历史孤儿资源、
// 同租户另一个知识库暂未绑定的资源、被多个知识库共享的资源,都满足"没人引用",
// 但它们不是这次作业写的,删掉就是数据丢失(快照里没有这些行,恢复不回来)。
// 只有写前不存在、且由本次写进去的行才允许清理。
type WriteSetRow struct {
Table string `json:"table"`
ID string `json:"id"`
// Existing 表示写前目标里已经有这一行(属于目标自己的数据,恢复一律不许删)。
Existing bool `json:"existing"`
// Owner 是写前该行的归属("<tenant>/<knowledge_base>"),不存在时为空。
Owner string `json:"owner,omitempty"`
// Reused 表示这一行虽然写前就在目标里、却不在预备份范围内,但已经用
// "持久作业/快照证据 + 整行内容 + 对象字节"证明与本次要写的内容完全一致,
// 因此本次既不重写它、也不在恢复时清理它。
//
// 不能只因为"它没被任何绑定/正文引用"就当成自己的:历史孤儿、同租户另一个
// 知识库暂未绑定的资源同样满足"没人引用",覆盖或删除同样是数据丢失。
Reused bool `json:"reused,omitempty"`
// ReuseEvidence 是可复用证据文档的摘要(reuse/<digest>.json),独立于写集合,
// 防止把这次推断伪装成历史台账。
ReuseEvidence string `json:"reuse_evidence,omitempty"`
}
// WriteSetPlan 是调用方在写第一笔之前交给目标的信息:绑定作业、目标、预备份与快照,
// 以及预备份时刻的整实例证据。
type WriteSetPlan struct {
JobID string
Target string
BackupSnapshotID string
TargetSnapshotID string
Universe map[string]TableFingerprint
// PriorSnapshots 是治理库里"这个目标的持久来源":成功同步过的快照,以及这个
// 目标自己的预备份。资源复用必须沿它把来源追到真实登记过的快照,而不是按
// "目标里没人引用"推断归属。
PriorSnapshots []PriorSnapshot
}
// 复用来源的两种合法类别。
const (
// PriorSnapshotSync:这个目标成功同步过这份快照(且登记了生效版本)。
PriorSnapshotSync = "sync"
// PriorSnapshotPrebackup:这份快照是从这个目标自己身上拍的预备份,把它写回去
// 就是回到本目标的历史状态。
PriorSnapshotPrebackup = "prebackup"
)
// PriorSnapshot 是一次**已登记**的来源:作业身份 + 快照身份 + 来源类别。
// 只有它也含有同一个资源 ID、且行内容完全一致,才允许把目标里那行当作
// "本次写入的等价物"。
type PriorSnapshot struct {
JobID string `json:"job_id"`
SnapshotID string `json:"snapshot_id"`
Kind string `json:"kind"`
FinishedAt time.Time `json:"finished_at,omitempty"`
}
// WriteSet 是"这一次发布的写集合 + 写前整实例内容证据",内容寻址、可校验、
// 与 job/target/backup 绑定。恢复只读它,不读目标现状去推断。
type WriteSet struct {
Version int `json:"version"`
JobID string `json:"job_id"`
Target string `json:"target"`
TenantID uint64 `json:"tenant_id"`
KnowledgeBaseID string `json:"knowledge_base_id"`
BackupSnapshotID string `json:"backup_snapshot_id"`
TargetSnapshotID string `json:"target_snapshot_id"`
CreatedAt time.Time `json:"created_at"`
Rows []WriteSetRow `json:"rows"`
Universe map[string]TableFingerprint `json:"universe"`
// Digest 是对除本字段外全部内容的 sha256:落盘文件名与治理库里的引用都用它,
// 记录被改一个字节就对不上。
Digest string `json:"digest"`
}
// Seal 把行序规范化为可复现的顺序并写入摘要。调用方在落盘与登记之前必须先 Seal。
// 排序在这里落地(而不是只在算摘要时排),否则落盘字节与摘要覆盖的内容不一致。
func (w *WriteSet) Seal() error {
sort.Slice(w.Rows, func(i, j int) bool {
if w.Rows[i].Table != w.Rows[j].Table {
return w.Rows[i].Table < w.Rows[j].Table
}
return w.Rows[i].ID < w.Rows[j].ID
})
digest, err := w.computeDigest()
if err != nil {
return err
}
w.Digest = digest
return nil
}
// CanonicalBytes 是不含摘要字段的规范字节:摘要覆盖的就是它,落盘文件另外
// 带上摘要本身(便于自描述),读回时用同一份规范字节重新推导。
func (w WriteSet) CanonicalBytes() ([]byte, error) {
copied := w
copied.Digest = ""
rows := make([]WriteSetRow, len(w.Rows))
copy(rows, w.Rows)
// 行序不影响语义但影响摘要:两边都按 (table,id) 排序才能算出同一个值。
sort.Slice(rows, func(i, j int) bool {
if rows[i].Table != rows[j].Table {
return rows[i].Table < rows[j].Table
}
return rows[i].ID < rows[j].ID
})
copied.Rows = rows
raw, err := json.Marshal(copied)
if err != nil {
return nil, fmt.Errorf("编码写集合失败: %w", err)
}
return raw, nil
}
func (w *WriteSet) computeDigest() (string, error) {
raw, err := w.CanonicalBytes()
if err != nil {
return "", err
}
sum := sha256.Sum256(raw)
return hex.EncodeToString(sum[:]), nil
}
// Verify 校验摘要与必备身份。缺任一身份都必须失败:没有绑定就没有"这份记录属于
// 这个作业/目标/预备份"的证明,拿它去删目标数据无法追责。
func (w *WriteSet) Verify() error {
if w.Version != WriteSetVersion {
return fmt.Errorf("写集合记录版本 %d 不受支持(当前 %d)", w.Version, WriteSetVersion)
}
if w.JobID == "" || w.BackupSnapshotID == "" || w.TargetSnapshotID == "" {
return errors.New("写集合记录缺少作业/预备份/快照绑定")
}
if w.TenantID == 0 || w.KnowledgeBaseID == "" {
return errors.New("写集合记录缺少目标范围身份")
}
if len(w.Universe) == 0 {
return errors.New("写集合记录缺少整实例内容证据")
}
if w.Digest == "" {
return errors.New("写集合记录没有摘要")
}
for _, row := range w.Rows {
if row.Reused && !row.Existing {
return fmt.Errorf("写集合记录把 %s/%s 标成可复用却不是写前已存在行", row.Table, row.ID)
}
if row.Reused && row.ReuseEvidence == "" {
return fmt.Errorf("写集合记录把 %s/%s 标成可复用却没有证据摘要", row.Table, row.ID)
}
}
digest, err := w.computeDigest()
if err != nil {
return err
}
if digest != w.Digest {
return errors.New("写集合记录摘要不符(内容被改动或截断)")
}
return nil
}
// CreatedIDs 返回"本次新建"的精确身份(写前不存在的行)。恢复只允许删这些。
func (w WriteSet) CreatedIDs(table string) []string {
ids := make([]string, 0, 8)
for _, row := range w.Rows {
if row.Table == table && !row.Existing {
ids = append(ids, row.ID)
}
}
sort.Strings(ids)
return ids
}
// ExistingIDs 返回写前已存在的身份(用于恢复后复核"目标自己的行都还在")。
func (w WriteSet) ExistingIDs(table string) []string {
ids := make([]string, 0, 8)
for _, row := range w.Rows {
if row.Table == table && row.Existing {
ids = append(ids, row.ID)
}
}
sort.Strings(ids)
return ids
}
// ReusedIDs 返回本次"证明可复用、因此既不重写也不清理"的精确身份。
// 它与 CreatedIDs 互斥,恢复清理一律不看这里(复用行必须原样保留)。
func (w WriteSet) ReusedIDs(table string) []string {
ids := make([]string, 0, 8)
for _, row := range w.Rows {
if row.Table == table && row.Reused {
ids = append(ids, row.ID)
}
}
sort.Strings(ids)
return ids
}
// UniverseDigest 是整实例证据的摘要,随台账一起登记,便于独立核对。
func (w WriteSet) UniverseDigest() string {
if len(w.Universe) == 0 {
return ""
}
tables := make([]string, 0, len(w.Universe))
for table := range w.Universe {
tables = append(tables, table)
}
sort.Strings(tables)
type pair struct {
Count int64 `json:"count"`
Digest string `json:"digest"`
}
ordered := make([]pair, 0, len(tables))
for _, table := range tables {
ordered = append(ordered, pair{Count: w.Universe[table].Count, Digest: w.Universe[table].Digest})
}
raw, err := json.Marshal(struct {
Tables []string `json:"tables"`
Values []pair `json:"values"`
}{Tables: tables, Values: ordered})
if err != nil {
return ""
}
sum := sha256.Sum256(raw)
return hex.EncodeToString(sum[:])
}
// WriteSetPlanner 由能访问目标与归档的实现提供:它在写第一笔之前算出写集合、
// 拒绝跨范围 ID 冲突,并把记录落盘。失败即"一笔都不许写"。
type WriteSetPlanner interface {
PlanWriteSet(ctx context.Context, plan WriteSetPlan) (WriteSet, error)
}
// WriteSetAdopter 让"计划已经存在"的执行也能带上复用语义(F07)。
//
// 触发场景:首次 planner 证明某些 resources 可复用 → 写集合落盘 → 进程中断 → 接管时用
// **新进程/新 target** 继续。写集合已存在,planner 因此被跳过;如果执行目标不消费这份
// 计划,它会按"没有复用"重新 upsert 资源行并重传对象——账本说"共享对象没动",实际却
// 重写了共享对象。必须显式接管计划,而不是重新按半写现状计划一遍。
type WriteSetAdopter interface {
AdoptWriteSet(set WriteSet) error
}
// WriteSetObserver 让调用方在写第一笔之前把写集合摘要持久化到治理库。
// 失败同样意味着"一笔都不许写":没有可追溯的写集合,恢复就只能靠推断。
type WriteSetObserver interface {
WriteSetPlanned(ctx context.Context, set WriteSet) error
}