knowledge-governance/cmd/worker/library_writeset.go

package main

import (
	"context"
	"encoding/json"
	"errors"
	"fmt"
	"sort"
	"time"

	"knowledge-governance/internal/governance"
	"knowledge-governance/internal/libraryrelease"
	v071 "knowledge-governance/internal/releaseadapter/v071"
)

// 写集合台账在治理侧的锚点：摘要登记在"这次作业的预备份版本"证据里。
// 为什么不用新表：版本记录本来就绑定 scope + snapshot + 作业，且 id 由这三者
// 决定；把摘要挂上去，重启后按同一身份就能取回，不需要改 schema。

// libraryVersionLookup 只暴露"按身份取一条版本记录"这一件事。
//
// 为什么不是"按 scope 列表"：列表是有排序窗口的（真实 Store 上限 100），
// 历史超过窗口后登记/接管/恢复会把"存在"读成"不存在"。身份查询必须是精确条件，
// 而 found=false 只表示"这个身份没有记录"，冲突由 store 返回错误（不许挑一条）。
type libraryVersionLookup interface {
	LibraryVersionByRef(ctx context.Context, scope string, kind governance.LibraryVersionKind,
		sourceJobID, snapshotID string) (governance.LibraryVersion, bool, error)
}

// libraryVersionLedger 是写集合锚点需要的两件事：按身份取一条、登记一条。
// 分开声明是为了让"身份不符/摘要冲突就失败"能在没有真实库时也被证明。
type libraryVersionLedger interface {
	libraryVersionLookup
	RecordLibraryVersion(ctx context.Context, version governance.LibraryVersion) error
}

// writeSetDigestOf 读某次作业/某份预备份登记的写集合摘要。
// 读不到就返回错误：缺失必须让调用方失败，不能降级成"没有记录就当没写过"。
func writeSetDigestOf(ctx context.Context, store libraryVersionLookup, scope, jobID, snapshotID string) (string, error) {
	version, found, err := store.LibraryVersionByRef(ctx, scope, governance.LibraryVersionProductionPrebackup, jobID, snapshotID)
	if err != nil {
		return "", fmt.Errorf("读不到版本记录：%w", err)
	}
	if !found {
		return "", fmt.Errorf("找不到作业 %s 的预备份版本记录（快照 %s）", jobID, snapshotID)
	}
	raw, _ := version.Evidence["writeset_digest"].(string)
	if raw == "" {
		return "", fmt.Errorf("预备份 %s 没有登记写集合摘要（作业 %s）", snapshotID, jobID)
	}
	return raw, nil
}

// loadWriteSetForJob 按"作业 + 目标 + 预备份"取回写集合并逐项核对绑定。
// 任何一步不符都返回错误：恢复宁可保持维护，也不许用一份对不上的记录去删目标数据。
func loadWriteSetForJob(ctx context.Context, store libraryVersionLookup, archiveRoot, scope, jobID, snapshotID string) (*libraryrelease.WriteSet, error) {
	digest, err := writeSetDigestOf(ctx, store, scope, jobID, snapshotID)
	if err != nil {
		return nil, err
	}
	set, err := v071.LoadWriteSet(archiveRoot, digest)
	if err != nil {
		return nil, err
	}
	if set.JobID != jobID {
		return nil, fmt.Errorf("写集合记录属于作业 %s，不是 %s", set.JobID, jobID)
	}
	if set.Target != scope {
		return nil, fmt.Errorf("写集合记录属于目标 %s，不是 %s", set.Target, scope)
	}
	if set.BackupSnapshotID != snapshotID {
		return nil, fmt.Errorf("写集合记录绑定预备份 %s，不是 %s", set.BackupSnapshotID, snapshotID)
	}
	return set, nil
}

// evidenceOwnerMatches 核对一份已持久化的证据是不是"这个作业 + 这份预备份"的。
//
// 为什么必须核这两维：版本行的 id 只由 (kind, scope, 快照) 决定，登记走 upsert。
// 只要调用方手里有一份"看起来对"的证据，就能把它盖到别人的行上；反过来，
// 合并证据时不核身份，就会把别的作业的写集合/字节数带进这一行。
func evidenceOwnerMatches(existing map[string]any, jobID, snapshotID string) error {
	if job, ok := existing["job"].(string); ok && job != "" && job != jobID {
		return fmt.Errorf("版本证据属于作业 %s，不是 %s：拒绝合并/覆盖", job, jobID)
	}
	if snapshot, ok := existing["backup_snapshot"].(string); ok && snapshot != "" && snapshot != snapshotID {
		return fmt.Errorf("版本证据绑定预备份 %s，不是 %s：拒绝合并/覆盖", snapshot, snapshotID)
	}
	return nil
}

// evidenceBytes 取证据里的备份字节数。从库里读回来的是 float64（JSON 数字），
// 进程内构造的是 int64 —— 两种形状都要认，否则"字节数缺失"会被读成 0。
func evidenceBytes(evidence map[string]any) int64 {
	switch value := evidence["backup_bytes"].(type) {
	case int64:
		return value
	case int:
		return int64(value)
	case float64:
		return int64(value)
	case json.Number:
		if parsed, err := value.Int64(); err == nil {
			return parsed
		}
	}
	return 0
}

// prebackupBytesOf 读某次作业/某份预备份已登记的备份字节数。
//
// 接管的预备份是"复用"的，ledgerBackupStore 手里只有快照 id 与写集合；
// 字节数只能来自首次登记的那条证据。读不到或非正数一律失败：把 0 写进
// 生效版本证据，事后就分不清"空备份"和"没记下来"（现场正是 backup_bytes:0）。
func prebackupBytesOf(ctx context.Context, store libraryVersionLookup, scope, jobID, snapshotID string) (int64, error) {
	version, found, err := store.LibraryVersionByRef(ctx, scope, governance.LibraryVersionProductionPrebackup, jobID, snapshotID)
	if err != nil {
		return 0, fmt.Errorf("读不到预备份版本证据：%w", err)
	}
	if !found {
		return 0, fmt.Errorf("找不到作业 %s 的预备份版本记录（快照 %s）", jobID, snapshotID)
	}
	if err := evidenceOwnerMatches(version.Evidence, jobID, snapshotID); err != nil {
		return 0, err
	}
	bytes := evidenceBytes(version.Evidence)
	if bytes <= 0 {
		return 0, fmt.Errorf("预备份 %s 没有可信的字节数（作业 %s）：拒绝把 0 字节当恢复基线", snapshotID, jobID)
	}
	return bytes, nil
}

// writeSetEvidence 在预备份原有证据上追加写集合锚点（纯函数，便于单独验证）。
// 不能整份替换：备份字节、索引映射这些字段是页面与恢复都在用的。
func writeSetEvidence(existing map[string]any, set libraryrelease.WriteSet, mappingDigest string) map[string]any {
	evidence := map[string]any{}
	for key, value := range existing {
		evidence[key] = value
	}
	evidence["backup_snapshot"] = set.BackupSnapshotID
	evidence["job"] = set.JobID
	if mappingDigest != "" {
		evidence["index_mapping_sha256"] = mappingDigest
	}
	evidence["writeset_digest"] = set.Digest
	evidence["writeset_universe_digest"] = set.UniverseDigest()
	evidence["writeset_target_snapshot"] = set.TargetSnapshotID
	evidence["writeset_rows"] = len(set.Rows)
	evidence["writeset_reused_rows"] = len(set.ReusedIDs("resources"))
	return evidence
}

// prebackupEvidence 把"这一轮预备份"的字段合并进已持久化的那份证据。
//
// 为什么必须是合并而不是覆盖：接管复用同一份预备份时，BackupRef 手里只有快照 id
// （字节数、写集合摘要都是首次那一轮登记的事实）。每次造新 map 就等于用
// "这一轮知道的东西"替换"上一次已经证明过的东西" —— 而 writeset_* 只会在
// 首轮规划时写入，接管路径根本不会重算，丢了就再也补不回来。
//
// 为什么不能无条件合并所有字段：版本行 id 只由 (kind, scope, 快照) 决定，
// 那一行可能属于另一个作业。所以先核身份（job/backup_snapshot），再只保留
// 与本作业、本预备份一致的部分；字节数出现两个不同真值也直接失败。
func prebackupEvidence(existing map[string]any, backup libraryrelease.BackupRef, jobID, mappingDigest string) (map[string]any, error) {
	evidence := make(map[string]any, len(existing)+4)
	for key, value := range existing {
		evidence[key] = value
	}
	if err := evidenceOwnerMatches(evidence, jobID, backup.SnapshotID); err != nil {
		return nil, err
	}
	bytes := backup.Bytes
	if backup.Reused {
		persisted := evidenceBytes(existing)
		if bytes > 0 && persisted > 0 && bytes != persisted {
			return nil, fmt.Errorf("复用预备份字节数不一致（本次 %d，已登记 %d）：拒绝把两份不同的备份当成一份",
				bytes, persisted)
		}
		if bytes <= 0 {
			bytes = persisted
		}
		if bytes <= 0 {
			return nil, fmt.Errorf("预备份 %s 复用登记缺少可信字节数：拒绝把 0 字节写进证据", backup.SnapshotID)
		}
		evidence["backup_reused"] = true
	}
	if bytes > 0 {
		evidence["backup_bytes"] = bytes
	}
	evidence["backup_snapshot"] = backup.SnapshotID
	evidence["job"] = jobID
	if mappingDigest != "" {
		evidence["index_mapping_sha256"] = mappingDigest
	}
	return evidence, nil
}

// WriteSetPlanned 把写集合摘要登记进"这次作业的预备份版本"证据。
// 它在第一笔写入之前被调用；失败即中止（调用方据此不写目标）。
//
// 这里读的是"这一条预备份记录"（scope+kind+作业+快照），不是"最近 N 条"：
// 现场正是历史上限把这条记录顶出窗口，才在预备份已经落盘之后登记失败。
// 记录不存在同样拒绝——把锚点写到一个不存在的证据行上，会让后续接管/恢复
// 读不到备份字节与索引映射，等于伪造一份台账。
func (r libraryStageRecorder) WriteSetPlanned(ctx context.Context, set libraryrelease.WriteSet) error {
	return anchorWriteSet(ctx, r.store, r.operationID, r.scope, r.jobID, r.mappingDigest, set)
}

// anchorWriteSet 是登记的实现：与 loadWriteSetForJob 一样只依赖"按身份取一条版本"
// 这一件事，便于在没有真实库时也能证明"身份不符/摘要冲突就失败"。
func anchorWriteSet(ctx context.Context, store libraryVersionLedger, operationID, scope, jobID, mappingDigest string,
	set libraryrelease.WriteSet) error {
	version, found, err := store.LibraryVersionByRef(ctx, scope, governance.LibraryVersionProductionPrebackup,
		jobID, set.BackupSnapshotID)
	if err != nil {
		return fmt.Errorf("读不到现有版本证据：%w", err)
	}
	if !found {
		return fmt.Errorf("预备份 %s 的版本证据不存在（作业 %s）：拒绝把写集合挂到不存在的记录上",
			set.BackupSnapshotID, jobID)
	}
	// 同一作业的写集合只能落定一次：第二次预检出不同摘要，说明被登记的台账
	// 不再描述"实际写了什么"，恢复就无从按它清理——宁可停在写入之前。
	if err := evidenceOwnerMatches(version.Evidence, jobID, set.BackupSnapshotID); err != nil {
		return err
	}
	if recorded, ok := version.Evidence["writeset_digest"].(string); ok && recorded != "" && recorded != set.Digest {
		return fmt.Errorf("预备份 %s 已登记写集合 %s，本次预检得到 %s：同一作业的写集合只能落定一次",
			set.BackupSnapshotID, recorded, set.Digest)
	}
	evidence := writeSetEvidence(version.Evidence, set, mappingDigest)
	return store.RecordLibraryVersion(ctx, governance.LibraryVersion{
		ID:    governance.LibraryVersionEventID(governance.LibraryVersionProductionPrebackup, scope, set.BackupSnapshotID, operationID),
		Scope: scope, Kind: governance.LibraryVersionProductionPrebackup, SnapshotID: set.BackupSnapshotID,
		SourceJobID: jobID, CreatedBy: "worker", Evidence: evidence, CreatedAt: time.Now().UTC(),
	})
}

// ledgerBackupStore 是"接管/恢复"用的预备份来源：只认已经持久化的那一份，
// 并把它绑定的写集合一起带出来。
//
// 为什么不能像以前那样只返回 snapshot id：那一刻目标已经被写过，恢复若拿不到
// 写集合就只能按目标现状推断残渣——那正是会误删历史资源的路径。所以这里取不到
// 记录就直接失败，而不是返回一个"没有 Universe 的引用"。
type ledgerBackupStore struct {
	ref   libraryrelease.BackupRef
	write *libraryrelease.WriteSet
}

func (s ledgerBackupStore) Prepare(context.Context, string, libraryrelease.CurrentState) (libraryrelease.BackupRef, error) {
	if s.write == nil {
		return libraryrelease.BackupRef{}, errors.New("恢复缺少持久化的写集合记录：拒绝在没有可追溯写集合的情况下继续")
	}
	// 字节数必须来自首次登记的证据：复用路径不重做备份，手上没有别的真值。
	// 拿 0 继续会把"备份有多大"从生效版本证据里洗掉（现场 backup_bytes:0）。
	if s.ref.Bytes <= 0 {
		return libraryrelease.BackupRef{}, errors.New("恢复缺少已登记的真实备份字节数：拒绝用 0 字节当基线")
	}
	ref := s.ref
	ref.WriteSet = s.write
	// 明确的"复用"：调用方据此把 backup_reused 落进版本证据，而不是让外部
	// 从 created_at 变了没变去猜（那正是被同快照收尾伪造过的地方）。
	ref.Reused = true
	return ref, nil
}

// 能力必须在编译期就成立：Run 用的是类型断言（BackupObserver / WriteSetObserver），
// 少实现一个方法不会报错，只会让"预备份证据/写集合锚点"静默不落库（trap 14 的同一族）。
var (
	_ libraryrelease.Recorder         = libraryStageRecorder{}
	_ libraryrelease.BackupObserver   = libraryStageRecorder{}
	_ libraryrelease.WriteSetObserver = libraryStageRecorder{}
	_ libraryrelease.BackupStore      = ledgerBackupStore{}
)

// effectiveEvidence 是"生产生效版本"证据的唯一构造点。
//
// 为什么单独成函数：生效版本证据里的 backup_bytes 是"这次恢复/同步用的是多大一份
// 基线"的唯一记录。接管复用路径上 BackupRef 若没带真实字节（历史缺陷），这里会
// 写进 0，事后与"空备份"无法区分（现场 production_effective 就是 backup_bytes:0）。
func effectiveEvidence(backup libraryrelease.BackupRef, action, mappingDigest string) map[string]any {
	evidence := map[string]any{"backup_snapshot": backup.SnapshotID, "action": action}
	if backup.Bytes > 0 {
		evidence["backup_bytes"] = backup.Bytes
	}
	if mappingDigest != "" {
		evidence["index_mapping_sha256"] = mappingDigest
	}
	return evidence
}

// sortedWriteSetSummary 只用于日志/证据：把本次写集合按表汇总成稳定的短摘要。
func sortedWriteSetSummary(set libraryrelease.WriteSet) string {
	counts := map[string]int{}
	for _, row := range set.Rows {
		counts[row.Table]++
	}
	tables := make([]string, 0, len(counts))
	for table := range counts {
		tables = append(tables, table)
	}
	sort.Strings(tables)
	summary := ""
	for _, table := range tables {
		if summary != "" {
			summary += ","
		}
		summary += fmt.Sprintf("%s=%d", table, counts[table])
	}
	return summary
}