fix(library): 当前生效版本改按精确查询

接管分类、基线判定、已知索引映射、同步闸口的创建判据与归档保留的保护标记,
原来都用 LibraryVersions(scope, 50/100) 这个分页窗口再在内存里筛。生效版本每
scope 只有一行、可能很久以前登记,历史一长就被挤出窗口 —— 于是"已生效"被读成
"没有生效":接管会把已经上线的目标重写一遍,基线入口会给已有权威版本的目标
再建一次基线。

现在统一走两条精确查询:LibraryCurrentVersion(kind='production_effective' AND
superseded_at IS NULL,每 scope 至多一行)与 LibraryVersionOfSnapshot(按快照
身份取回"已顶替"证据)。多行、自相矛盾、读不到一律 fail closed;同一含义只留
一份实现(knownIndexMapping 同步与恢复共用)。LibraryVersions 仍是 1..100 的
展示窗口,只用于列表。

验证:真实 PG 上先复现(窗口实现 ⇒ found=false),改后 7 条 store 契约用例与
worker 端到端判定用例全绿;本机 make verify 15 项 success(用例 1264 通过 /
0 失败 / 93 已声明可选跳过)。
This commit is contained in:
姚章浩
2026-10-30 03:09:21 +08:00
parent 67743f2285
commit 0088004cd6
15 changed files with 655 additions and 130 deletions
+16 -16
View File
@@ -22,7 +22,10 @@ type libraryBaselinePayload struct {
Scope string `json:"scope"`
}
// baselineVersionState 回答"这个 scope 现在有没有生效版本、是不是本作业登记的"。
// classifyBaselineVersions 回答"这个 scope 现在有没有生效版本、是不是本作业登记的"。
//
// 输入是**当前生效版本**这一个精确查询的结果(每 scope 至多一行),不是"最近 N 条":
// 窗口一满,已登记过的基线会被读成"没有",于是重复捕获、覆盖别人的版本。
//
// 三种情况必须分开,否则崩溃续作会被自己的版本挡住:
// - own:本作业 + 同一快照已经登记过 → 只收尾,绝不重复捕获或重写版本;
@@ -33,19 +36,15 @@ type baselineVersionState struct {
Foreign *governance.LibraryVersion
}
func classifyBaselineVersions(versions []governance.LibraryVersion, jobID, snapshotID string) baselineVersionState {
for index := range versions {
item := versions[index]
if item.Kind != governance.LibraryVersionProductionEffective || item.SupersededAt != nil {
continue
}
if jobID != "" && snapshotID != "" && item.SourceJobID == jobID && item.SnapshotID == snapshotID {
return baselineVersionState{Own: true}
}
foreign := item
return baselineVersionState{Foreign: &foreign}
func classifyBaselineVersions(current governance.LibraryVersion, hasCurrent bool, jobID, snapshotID string) baselineVersionState {
if !hasCurrent {
return baselineVersionState{}
}
return baselineVersionState{}
if jobID != "" && snapshotID != "" && current.SourceJobID == jobID && current.SnapshotID == snapshotID {
return baselineVersionState{Own: true}
}
foreign := current
return baselineVersionState{Foreign: &foreign}
}
// settleBaselineWindow 是基线窗口的**唯一**收尾入口,负责让治理状态与实际入口一致:
@@ -122,11 +121,12 @@ func runLibraryBaseline(ctx context.Context, store *postgresstore.Store, config
_ = store.AdvanceLibraryJob(ctx, payload.LibraryJobID, governance.LibraryJobRunning, "capture", "", "", "", "", now)
// 版本判定:别人的生效版本一律拒绝;本作业已登记过的快照只收尾。
versions, versionErr := store.LibraryVersions(ctx, payload.Scope, 50)
// 用精确查询(当前生效版本),不用"最近 N 条":窗口一满会把已登记读成没登记。
current, hasCurrent, versionErr := store.LibraryCurrentVersion(ctx, payload.Scope)
if versionErr != nil {
return fail("读不到版本记录,无法确认是否需要建立基线;未对目标执行任何操作", "capture")
return fail("读不到生效版本记录,无法确认是否需要建立基线;未对目标执行任何操作", "capture")
}
state := classifyBaselineVersions(versions, payload.LibraryJobID, persistedSnapshot)
state := classifyBaselineVersions(current, hasCurrent, payload.LibraryJobID, persistedSnapshot)
if state.Foreign != nil {
return fail("该目标已有生效版本 "+shortSnapshotID(state.Foreign.SnapshotID)+
"(作业 "+state.Foreign.SourceJobID+"),不需要再建基线;换版本请走同步或恢复", "capture")
+13 -15
View File
@@ -11,38 +11,36 @@ import (
)
// 崩溃续作的版本判定:本作业+同一快照 = 只收尾;别人的生效版本 = 拒绝;都没有 = 正常建基线。
// "已顶替"的旧版本由 Store 的精确查询过滤掉(LibraryCurrentVersion 只返回未顶替的那一行),
// 所以这里只需要一个事实:当前生效的是谁。
func TestClassifyBaselineVersions(t *testing.T) {
const jobA, jobB, snap = "libbase-internal-1", "libbase-internal-2", "snap-abc"
effective := func(sourceJob, snapshot string, superseded bool) governance.LibraryVersion {
item := governance.LibraryVersion{
effective := func(sourceJob, snapshot string) governance.LibraryVersion {
return governance.LibraryVersion{
Scope: "internal", Kind: governance.LibraryVersionProductionEffective,
SnapshotID: snapshot, SourceJobID: sourceJob, CreatedAt: time.Now().UTC(),
}
if superseded {
at := time.Now().UTC()
item.SupersededAt = &at
}
return item
}
if state := classifyBaselineVersions(nil, jobA, snap); state.Own || state.Foreign != nil {
t.Fatalf("no versions must mean neither own nor foreign: %+v", state)
if state := classifyBaselineVersions(governance.LibraryVersion{}, false, jobA, snap); state.Own || state.Foreign != nil {
t.Fatalf("没有生效版本必须既不是 own 也不是 foreign: %+v", state)
}
if state := classifyBaselineVersions([]governance.LibraryVersion{effective(jobA, snap, false)}, jobA, snap); !state.Own {
if state := classifyBaselineVersions(effective(jobA, snap), true, jobA, snap); !state.Own {
t.Fatalf("same job + same snapshot must be recognized as own: %+v", state)
}
// 快照不同就不是"我登记的那份",不能当成可收尾。
if state := classifyBaselineVersions([]governance.LibraryVersion{effective(jobA, "snap-other", false)}, jobA, snap); state.Own || state.Foreign == nil {
if state := classifyBaselineVersions(effective(jobA, "snap-other"), true, jobA, snap); state.Own || state.Foreign == nil {
t.Fatalf("different snapshot of same job must not be own: %+v", state)
}
// 别人的生效版本:即使快照相同也必须拒绝。
foreign := classifyBaselineVersions([]governance.LibraryVersion{effective(jobB, snap, false)}, jobA, snap)
foreign := classifyBaselineVersions(effective(jobB, snap), true, jobA, snap)
if foreign.Own || foreign.Foreign == nil || foreign.Foreign.SourceJobID != jobB {
t.Fatalf("foreign effective version must be reported: %+v", foreign)
}
// 已被顶替的旧版本不算生效版本。
if state := classifyBaselineVersions([]governance.LibraryVersion{effective(jobB, snap, true)}, jobA, snap); state.Own || state.Foreign != nil {
t.Fatalf("superseded version must not block a baseline: %+v", state)
// 作业行里还没有持久化快照(persistedSnapshot 为空)时,自己登记的版本也算 foreign:
// 没有绑定身份的证据不能被当成"我可以只收尾"。
if state := classifyBaselineVersions(effective(jobA, snap), true, jobA, ""); state.Own || state.Foreign == nil {
t.Fatalf("no persisted snapshot must not be own: %+v", state)
}
}
+26 -14
View File
@@ -123,31 +123,43 @@ const (
// - 本快照存在 released/被顶替的版本 ⇒ superseded;
// - 本快照存在未被顶掉的生效版本 ⇒ pending_final;
// - 查询失败且无阶段证据 ⇒ unknown(可重试,不当成没有证据)。
func classifyTakeover(job governance.LibraryJob, versions []governance.LibraryVersion, versionsErr error) takeoverKind {
//
// 事实来自两个精确查询(LibraryCurrentVersion / LibraryVersionOfSnapshot),**不是**
// "最近 N 条再在内存里筛":窗口一满,已生效的快照会被判成"没有证据",接管就会把
// 已经上线的内容重写一遍。
func classifyTakeover(job governance.LibraryJob, facts libraryVersionFacts) takeoverKind {
finalized := false
for _, stage := range job.Stages {
if stage.Stage == "finalize" && stage.State == "succeeded" {
finalized = true
}
}
if versionsErr != nil && !finalized {
if facts.Err != nil && !finalized {
return takeoverUnknown
}
superseded, effective := false, false
for _, version := range versions {
if version.Kind != governance.LibraryVersionProductionEffective || version.SnapshotID != job.TargetSnapshotID {
continue
if facts.Err == nil {
// 本快照登记过生效版本:被顶替过就绝不能用它覆盖更新的生产版本。
if facts.HasSnapshot && facts.Snapshot.SupersededAt != nil {
// 台账自相矛盾(这一行说已顶替,当前生效的却还是它):状态不可判定。
if facts.HasCurrent && facts.Current.SnapshotID == job.TargetSnapshotID {
return takeoverUnknown
}
return takeoverSuperseded
}
if version.SupersededAt != nil {
superseded = true
} else {
effective = true
if facts.HasSnapshot {
// 未顶替 ⇒ 必须就是当前生效的那一行;不是的话台账不一致,不许挑一条继续写。
if !facts.HasCurrent || facts.Current.SnapshotID != job.TargetSnapshotID {
return takeoverUnknown
}
return takeoverPendingFinal
}
// 本快照没有自己的生效登记,但当前生效的正是它(恢复/重放会改写作业归属):
// 内容已经在生产上,只差收尾。
if facts.HasCurrent && facts.Current.SnapshotID == job.TargetSnapshotID {
return takeoverPendingFinal
}
}
if superseded && !effective {
return takeoverSuperseded
}
if effective || finalized {
if finalized {
return takeoverPendingFinal
}
return takeoverFresh
+41 -20
View File
@@ -152,38 +152,59 @@ func TestFinishLibrarySuccessReportsTerminalWriteFailure(t *testing.T) {
}
}
// 接管分类:阶段证据独立成立;查询失败=未知(不得写入);被顶替=不得覆盖。
// 接管分类:阶段证据独立成立;查询失败=未知(不得写入);被顶替=不得覆盖;
// 台账自相矛盾(未顶替但不是当前生效 / 已顶替却是当前生效)=未知,fail closed。
func TestClassifyTakeoverSeparatesUnknownPendingSupersededAndFresh(t *testing.T) {
job := governance.LibraryJob{Scope: "internal", Kind: governance.LibraryJobSync, TargetSnapshotID: "snap-1"}
finalized := job
finalized.Stages = []governance.LibraryStage{{Stage: "finalize", State: "succeeded"}}
effective := []governance.LibraryVersion{{Kind: governance.LibraryVersionProductionEffective, SnapshotID: "snap-1"}}
supersededVersion := []governance.LibraryVersion{{Kind: governance.LibraryVersionProductionEffective,
SnapshotID: "snap-1", SupersededAt: ptrTime(time.Now())}}
unrelated := []governance.LibraryVersion{{Kind: governance.LibraryVersionProductionEffective, SnapshotID: "snap-9"}}
queryErr := errors.New("version storage temporarily unavailable")
supersededAt := time.Now().UTC()
facts := func(current string, hasCurrent bool, snapshot string, hasSnapshot bool, superseded bool) libraryVersionFacts {
result := libraryVersionFacts{HasCurrent: hasCurrent, HasSnapshot: hasSnapshot}
if hasCurrent {
result.Current = governance.LibraryVersion{Kind: governance.LibraryVersionProductionEffective,
SnapshotID: current, SourceJobID: "job-cur"}
}
if hasSnapshot {
result.Snapshot = governance.LibraryVersion{Kind: governance.LibraryVersionProductionEffective,
SnapshotID: snapshot, SourceJobID: job.ID}
if superseded {
result.Snapshot.SupersededAt = &supersededAt
}
}
return result
}
queryErr := libraryVersionFacts{Err: errors.New("version storage temporarily unavailable")}
cases := []struct {
name string
job governance.LibraryJob
versions []governance.LibraryVersion
err error
want takeoverKind
name string
job governance.LibraryJob
facts libraryVersionFacts
want takeoverKind
}{
// 关键回归:查询失败 + 没有阶段证据 ⇒ 未知,不能当成"没有收尾证据"继续写。
{"query fails without stage evidence", job, nil, queryErr, takeoverUnknown},
{"query fails without stage evidence", job, queryErr, takeoverUnknown},
// 阶段证据先独立成立:查询失败不影响"只差收尾"的判定。
{"query fails but finalize stage succeeded", finalized, nil, queryErr, takeoverPendingFinal},
{"effective version for this snapshot", job, effective, nil, takeoverPendingFinal},
{"finalize stage succeeded", finalized, nil, nil, takeoverPendingFinal},
{"this snapshot was superseded", job, supersededVersion, nil, takeoverSuperseded},
{"no evidence at all", job, nil, nil, takeoverFresh},
{"another snapshot effective but this one has no row", job, unrelated, nil, takeoverFresh},
{"empty target snapshot", governance.LibraryJob{Scope: "internal"}, nil, nil, takeoverFresh},
{"query fails but finalize stage succeeded", finalized, queryErr, takeoverPendingFinal},
{"effective version for this snapshot", job, facts("snap-1", true, "snap-1", true, false), takeoverPendingFinal},
// 当前生效的就是本快照,但没有本作业的登记行(恢复/重放会改写作业归属)。
{"current is this snapshot without own row", job, facts("snap-1", true, "", false, false), takeoverPendingFinal},
{"finalize stage succeeded", finalized, libraryVersionFacts{}, takeoverPendingFinal},
{"this snapshot was superseded", job, facts("snap-9", true, "snap-1", true, true), takeoverSuperseded},
{"no evidence at all", job, libraryVersionFacts{}, takeoverFresh},
{"another snapshot effective but this one has no row", job, facts("snap-9", true, "", false, false), takeoverFresh},
{"empty target snapshot", governance.LibraryJob{Scope: "internal"}, libraryVersionFacts{}, takeoverFresh},
// 未顶替的登记行却不是当前生效版本:两个事实互相矛盾,不许挑一个继续写。
{"own row not superseded but current differs", job, facts("snap-9", true, "snap-1", true, false), takeoverUnknown},
// 已顶替却又是当前生效版本:同样是矛盾台账。
{"own row superseded but current is it", job, facts("snap-1", true, "snap-1", true, true), takeoverUnknown},
// 有登记行但读不到当前生效版本:无法确认它是不是生效版本。
{"own row without current", job, facts("", false, "snap-1", true, false), takeoverUnknown},
}
for _, test := range cases {
t.Run(test.name, func(t *testing.T) {
if got := classifyTakeover(test.job, test.versions, test.err); got != test.want {
if got := classifyTakeover(test.job, test.facts); got != test.want {
t.Fatalf("classify = %q, want %q", got, test.want)
}
})
+21 -25
View File
@@ -18,6 +18,7 @@ import (
"knowledge-governance/internal/librarysnapshot"
"knowledge-governance/internal/pgdsn"
postgresstore "knowledge-governance/internal/platform/postgres"
"knowledge-governance/internal/testbarrier"
)
// 目标内容在窗口内的几种"已知状态",决定目标能否被重新开放:
@@ -34,8 +35,13 @@ const (
// contentTrackedTarget 只做一件事:在第一次写目标时把"内容有风险"标出来。
// 这样"授权过期/进程被杀/校验失败"这些早退路径不会把半写目标当成没动过。
//
// 另外它是本机中断演练的固定点位:每个阶段写完、下一个阶段还没开始时调用
// testbarrier.Wait(默认关闭,两个环境变量同时在场才生效)。放在这一层而不是
// 发布代码里,是因为"阶段之间"正是真实半写状态的边界,而发布链路本身不需要知道演练。
type contentTrackedTarget struct {
inner libraryrelease.Target
jobID string
onApply func()
}
@@ -45,7 +51,14 @@ func (t *contentTrackedTarget) Current(ctx context.Context) (libraryrelease.Curr
func (t *contentTrackedTarget) Apply(ctx context.Context, stage libraryrelease.Stage, snapshotID string) error {
t.onApply()
return t.inner.Apply(ctx, stage, snapshotID)
if err := t.inner.Apply(ctx, stage, snapshotID); err != nil {
return err
}
// 屏障错误只记日志:演练设施坏掉不许让一次真实发布失败。
if barrierErr := testbarrier.Wait(ctx, "after:"+string(stage), t.jobID); barrierErr != nil {
log.Printf("library test barrier point=after:%s job=%s unavailable: %v", stage, t.jobID, barrierErr)
}
return nil
}
func (t *contentTrackedTarget) Verify(ctx context.Context, expect libraryrelease.Expectation) error {
@@ -116,8 +129,8 @@ func runLibraryRelease(ctx context.Context, store *postgresstore.Store, config a
previous, err := store.LibraryJob(ctx, payload.LibraryJobID)
resumed := err == nil && previous.SnapshotID != ""
if resumed {
versions, versionErr := store.LibraryVersions(ctx, payload.Scope, 50)
switch classifyTakeover(previous, versions, versionErr) {
facts := loadLibraryVersionFacts(ctx, store, payload.Scope, previous.TargetSnapshotID)
switch classifyTakeover(previous, facts) {
case takeoverUnknown:
// 版本状态读不到、又没有阶段证据:不能当成"没有收尾证据"继续写目标。
return failLibraryJob(ctx, store, recorder, payload.LibraryJobID,
@@ -174,27 +187,9 @@ func runLibraryRelease(ctx context.Context, store *postgresstore.Store, config a
SnapshotID: source.SnapshotID, Kind: source.Kind, FinishedAt: source.FinishedAt})
}
}
// 生产索引映射基线:优先当前生效版本,其次任何一次成功预备份(它也记录了生产实际映射)。
// 只认"生效版本"会在恢复把版本 supersede 掉之后误判"索引被改动"。
knownMapping := ""
if versions, versionErr := store.LibraryVersions(ctx, payload.Scope, 50); versionErr == nil {
for _, item := range versions {
if item.Kind == governance.LibraryVersionProductionEffective && item.SupersededAt == nil {
if raw, ok := item.Evidence["index_mapping_sha256"].(string); ok && raw != "" {
knownMapping = raw
break
}
}
}
if knownMapping == "" {
for _, item := range versions {
if raw, ok := item.Evidence["index_mapping_sha256"].(string); ok && raw != "" {
knownMapping = raw
break
}
}
}
}
// 生产索引映射基线:权威来源是当前生效版本(精确查),其次任何一次成功记录的映射。
// 只认"生效版本"会在恢复把版本顶替掉之后误判"索引被改动"。
knownMapping := knownIndexMapping(ctx, store, payload.Scope)
target, backups, wireErr := buildLibraryProductionStack(ctx, config, payload.Scope, payload.TargetSnapshotID, knownMapping)
if wireErr == nil {
if mapping, mapErr := target.Search().MappingSHA256(ctx); mapErr == nil {
@@ -282,7 +277,8 @@ func runLibraryRelease(ctx context.Context, store *postgresstore.Store, config a
contentState = contentHalfWritten
}
pending := successBoundary{}
tracked := &contentTrackedTarget{inner: target, onApply: func() { contentState = contentHalfWritten }}
tracked := &contentTrackedTarget{inner: target, jobID: payload.LibraryJobID,
onApply: func() { contentState = contentHalfWritten }}
allowRestore := func(error) bool {
return contentState == contentUntouched || contentState == contentSucceeded || contentState == contentRolledBack
}
+2 -21
View File
@@ -11,7 +11,6 @@ import (
"time"
"knowledge-governance/internal/appconfig"
"knowledge-governance/internal/governance"
"knowledge-governance/internal/jobs"
"knowledge-governance/internal/libraryrelease"
postgresstore "knowledge-governance/internal/platform/postgres"
@@ -159,23 +158,5 @@ func (v recoveryVerifier) Verify(ctx context.Context, backupID string) (string,
return hex.EncodeToString(sum[:]), nil
}
// knownIndexMapping 取"上一次登记过的索引映射",作为装配目标时的映射基线。
func knownIndexMapping(ctx context.Context, store *postgresstore.Store, scope string) string {
versions, err := store.LibraryVersions(ctx, scope, 50)
if err != nil {
return ""
}
for _, item := range versions {
if item.Kind == governance.LibraryVersionProductionEffective && item.SupersededAt == nil {
if raw, ok := item.Evidence["index_mapping_sha256"].(string); ok && raw != "" {
return raw
}
}
}
for _, item := range versions {
if raw, ok := item.Evidence["index_mapping_sha256"].(string); ok && raw != "" {
return raw
}
}
return ""
}
// knownIndexMapping 在 library_versions.go:同步与恢复共用同一份(当前生效版本精确查,
// 取不到映射才退回最近记录)。这里不再复制第二份。
@@ -0,0 +1,104 @@
package main
import (
"context"
"fmt"
"testing"
"time"
"knowledge-governance/internal/governance"
)
// 接管/基线的版本判定必须走"当前生效版本"的精确查询:历史一长,窗口列表就看不到
// 那唯一一行未顶替的生效版本,于是判定会退回"没有证据"——接管就会把已经生效的
// 目标再写一遍(重写风险最高的一条)。这里用真实 PostgreSQL 把窗口挤满,证明判定不变。
func TestTakeoverClassificationUsesExactCurrentVersionBeyondHistoryWindow(t *testing.T) {
store, _ := openLedgerStore(t)
ctx := context.Background()
now := time.Now().UTC()
const scope = "internal"
const targetSnapshot = "snap-effective"
const jobID = "libsync-internal-takeover"
job := governance.LibraryJob{ID: jobID, Scope: scope, Kind: governance.LibraryJobSync,
TargetSnapshotID: targetSnapshot, SnapshotID: "snap-prebackup"}
recordEffective := func(sourceJob, snapshot string, created time.Time) {
t.Helper()
if err := store.RecordLibraryVersion(ctx, governance.LibraryVersion{
ID: governance.LibraryVersionID(governance.LibraryVersionProductionEffective, scope, snapshot),
Scope: scope, Kind: governance.LibraryVersionProductionEffective, SnapshotID: snapshot,
SourceJobID: sourceJob, CreatedBy: "worker",
Evidence: map[string]any{"action": "sync", "index_mapping_sha256": "mapping-live"},
CreatedAt: created,
}); err != nil {
t.Fatalf("record effective %s: %v", snapshot, err)
}
}
// 生效版本登记在 48 小时前,然后 250 条更新的历史记录把它挤出任何窗口。
recordEffective(jobID, targetSnapshot, now.Add(-48*time.Hour))
seedVersionHistory(t, ctx, store, scope, now.Add(-time.Hour), 250)
window, err := store.LibraryVersions(ctx, scope, 100)
if err != nil {
t.Fatalf("list versions: %v", err)
}
if len(window) != 100 {
t.Fatalf("窗口条数 = %d, want 100", len(window))
}
if containsSnapshot(window, targetSnapshot) {
t.Fatal("窗口里仍能看到生效版本:本用例证明不了窗口之外仍可判定(夹具失效)")
}
// 本作业的目标快照就是当前生效版本 ⇒ 只差收尾,不许重写。
facts := loadLibraryVersionFacts(ctx, store, scope, targetSnapshot)
if facts.Err != nil {
t.Fatalf("窗口之外必须读得到生效事实:%v", facts.Err)
}
if !facts.HasCurrent || facts.Current.SnapshotID != targetSnapshot {
t.Fatalf("当前生效版本读取错误:%+v", facts)
}
if got := classifyTakeover(job, facts); got != takeoverPendingFinal {
t.Fatalf("取手接管分类 = %q, want %q(窗口一满就重写 = 本缺陷)", got, takeoverPendingFinal)
}
// 索引映射基线也走同一条精确查询:窗口之外仍要拿到生产实际用的映射。
if got := knownIndexMapping(ctx, store, scope); got != "mapping-live" {
t.Fatalf("索引映射基线 = %q, want mapping-live", got)
}
// 本快照被更新的快照顶替:接管必须拒绝用旧快照覆盖,而不是重写。
recordEffective("libsync-internal-newer", "snap-newer", now)
facts = loadLibraryVersionFacts(ctx, store, scope, targetSnapshot)
if facts.Err != nil {
t.Fatalf("顶替后仍必须读得到事实:%v", facts.Err)
}
if got := classifyTakeover(job, facts); got != takeoverSuperseded {
t.Fatalf("被顶替后的接管分类 = %q, want %q", got, takeoverSuperseded)
}
if facts.Current.SnapshotID != "snap-newer" {
t.Fatalf("当前生效版本 = %s, want snap-newer", facts.Current.SnapshotID)
}
// 一个从没生效过的快照:才是 fresh(正常流程 + 预检)。
unknown := governance.LibraryJob{ID: "libsync-internal-fresh", Scope: scope,
Kind: governance.LibraryJobSync, TargetSnapshotID: "snap-never", SnapshotID: "snap-prebackup-2"}
if got := classifyTakeover(unknown, loadLibraryVersionFacts(ctx, store, scope, "snap-never")); got != takeoverFresh {
t.Fatalf("未生效过的快照分类 = %q, want %q", got, takeoverFresh)
}
// 基线侧同一个事实:别人的生效版本必须挡住建基线;本作业登记的同一快照只收尾。
current, hasCurrent, err := store.LibraryCurrentVersion(ctx, scope)
if err != nil || !hasCurrent {
t.Fatalf("当前生效版本读取失败:found=%v err=%v", hasCurrent, err)
}
if state := classifyBaselineVersions(current, hasCurrent, "libbase-internal-x", "snap-newer"); state.Own || state.Foreign == nil {
t.Fatalf("别人的生效版本必须挡住基线:%+v", state)
}
recordEffective("libbase-internal-y", "snap-baseline", now)
current, hasCurrent, err = store.LibraryCurrentVersion(ctx, scope)
if err != nil || !hasCurrent {
t.Fatalf("再读当前生效版本失败:found=%v err=%v", hasCurrent, err)
}
if state := classifyBaselineVersions(current, hasCurrent, "libbase-internal-y", "snap-baseline"); !state.Own {
t.Fatalf("本作业同一快照必须判成只收尾:%+v (%s)", state, fmt.Sprint(current))
}
}
+83
View File
@@ -0,0 +1,83 @@
package main
import (
"context"
"fmt"
"knowledge-governance/internal/governance"
)
// libraryVersionIndex 是"当前生效版本"与"某个快照自己的登记"的精确查询口。
//
// 为什么不是 LibraryVersions(scope, N):那是分页展示用的窗口,历史超过上限后
// "存在"会被读成"不存在"。接管/基线/同步闸口的判定都必须走这里,同一含义只有
// 一份实现(两个查询在 Store 里都是按条件精确命中,没有排序窗口)。
type libraryVersionIndex interface {
LibraryCurrentVersion(ctx context.Context, scope string) (governance.LibraryVersion, bool, error)
LibraryVersionOfSnapshot(ctx context.Context, scope string, kind governance.LibraryVersionKind,
snapshotID string) (governance.LibraryVersion, bool, error)
}
// libraryVersionReader 是"当前生效版本 + 展示窗口"的组合:已知索引映射只需要这两样。
type libraryVersionReader interface {
LibraryCurrentVersion(ctx context.Context, scope string) (governance.LibraryVersion, bool, error)
LibraryVersions(ctx context.Context, scope string, limit int) ([]governance.LibraryVersion, error)
}
// libraryVersionFacts 是接管判定需要的两个事实:
// - Current/HasCurrent:这个 scope 现在生效的是哪一份(每 scope 至多一行);
// - Snapshot/HasSnapshot:本次作业的目标快照自己有没有生效登记(含"已顶替")。
//
// Err 非空表示"读不到",调用方必须按未知处理,不许降级成"没有证据"。
type libraryVersionFacts struct {
Current governance.LibraryVersion
HasCurrent bool
Snapshot governance.LibraryVersion
HasSnapshot bool
Err error
}
// loadLibraryVersionFacts 用两次精确查询拼出判定事实;任一查询失败都返回 Err。
func loadLibraryVersionFacts(ctx context.Context, store libraryVersionIndex, scope, targetSnapshotID string) libraryVersionFacts {
facts := libraryVersionFacts{}
current, hasCurrent, err := store.LibraryCurrentVersion(ctx, scope)
if err != nil {
facts.Err = fmt.Errorf("读不到当前生效版本:%w", err)
return facts
}
facts.Current, facts.HasCurrent = current, hasCurrent
if targetSnapshotID == "" {
return facts
}
snapshot, hasSnapshot, err := store.LibraryVersionOfSnapshot(ctx, scope,
governance.LibraryVersionProductionEffective, targetSnapshotID)
if err != nil {
facts.Err = fmt.Errorf("读不到快照 %s 的生效登记:%w", targetSnapshotID, err)
return facts
}
facts.Snapshot, facts.HasSnapshot = snapshot, hasSnapshot
return facts
}
// knownIndexMapping 取"上一次登记过的索引映射",作为装配目标时的映射基线。
//
// 权威来源是**当前生效版本**的登记证据;只有在它没有记录映射时,才退回到最近
// 成功记录里的那一份(恢复会把旧版本顶替掉,这时仍要拿到生产实际用的映射)。
// 退化只会让"索引被改动"判定偏严,不会误放行覆盖。同步与恢复共用这一份实现。
func knownIndexMapping(ctx context.Context, store libraryVersionReader, scope string) string {
if current, found, err := store.LibraryCurrentVersion(ctx, scope); err == nil && found {
if raw, ok := current.Evidence["index_mapping_sha256"].(string); ok && raw != "" {
return raw
}
}
versions, err := store.LibraryVersions(ctx, scope, 50)
if err != nil {
return ""
}
for _, item := range versions {
if raw, ok := item.Evidence["index_mapping_sha256"].(string); ok && raw != "" {
return raw
}
}
return ""
}
+9 -9
View File
@@ -52,18 +52,18 @@ func libraryBaselineEnqueue(w http.ResponseWriter, r *http.Request, config Confi
"error": "版本登记存储不可用"})
return
}
versions, err := store.LibraryVersions(r.Context(), request.Scope, 50)
// 建基线的前提是"这个目标还没有生效版本"。这是创建判据,必须精确查当前生效版本:
// 用"最近 N 条"会在窗口满时把已生效读成没有,放行一次会覆盖他人版本的基线捕获。
current, hasCurrent, err := store.LibraryCurrentVersion(r.Context(), request.Scope)
if err != nil {
writeJSON(w, http.StatusInternalServerError, map[string]string{"error": "cannot read library versions"})
writeJSON(w, http.StatusInternalServerError, map[string]string{"error": "cannot read current library version"})
return
}
for _, item := range versions {
if item.Kind == governance.LibraryVersionProductionEffective && item.SupersededAt == nil {
writeJSON(w, http.StatusConflict, map[string]any{"code": "library_baseline_exists",
"error": "该目标已有生效版本,不需要再建基线;换版本请走同步或恢复",
"snapshot_id": item.SnapshotID})
return
}
if hasCurrent {
writeJSON(w, http.StatusConflict, map[string]any{"code": "library_baseline_exists",
"error": "该目标已有生效版本,不需要再建基线;换版本请走同步或恢复",
"snapshot_id": current.SnapshotID})
return
}
// 目标必须真的读得到:读不到就不是"非空无权威版本",而是另一个问题,
// 不允许用建基线去掩盖连接/配置故障。
+30
View File
@@ -3,6 +3,7 @@ package httpapi
import (
"context"
"encoding/json"
"errors"
"net/http"
"net/http/httptest"
"strings"
@@ -160,3 +161,32 @@ func TestLibraryMaintenanceCapabilityReportsWiringInsteadOfOneVagueSentence(t *t
t.Fatalf("missing=%v", broken["missing"])
}
}
// 建基线的存在性判断同样不能靠展示窗口:生效版本可能在"最近 N 条"之外。
// 读不到(而不是"没有")时也必须 fail closed,不许当成可以建基线。
func TestLibraryBaselineUsesExactCurrentVersionBeyondWindow(t *testing.T) {
store := &fakeLibraryStore{current: &governance.LibraryVersion{ID: "libver-1", Scope: "internal",
Kind: governance.LibraryVersionProductionEffective, SnapshotID: "snap-effective",
CreatedAt: time.Now().UTC().Add(-96 * time.Hour)}}
recorder := httptest.NewRecorder()
libraryBaselineEnqueue(recorder, baselineRequest(`{"scope":"internal"}`, roleAdmin, "admin"), Config{Store: store})
if recorder.Code != http.StatusConflict {
t.Fatalf("status=%d body=%s", recorder.Code, recorder.Body.String())
}
if body := decodeBody(t, recorder); body["code"] != "library_baseline_exists" || body["snapshot_id"] != "snap-effective" {
t.Fatalf("body=%v", body)
}
if store.createN != 0 {
t.Fatal("must not create a baseline job when an effective version exists")
}
failing := &fakeLibraryStore{currentErr: errors.New("version storage down")}
recorder = httptest.NewRecorder()
libraryBaselineEnqueue(recorder, baselineRequest(`{"scope":"internal"}`, roleAdmin, "admin"), Config{Store: failing})
if recorder.Code != http.StatusInternalServerError {
t.Fatalf("status=%d body=%s", recorder.Code, recorder.Body.String())
}
if failing.createN != 0 {
t.Fatal("must not create a baseline job while the current version is unreadable")
}
}
+29 -7
View File
@@ -342,6 +342,11 @@ type libraryJobStore interface {
ListLibraryJobs(ctx context.Context, scope string, limit int) ([]governance.LibraryJob, error)
RecordLibraryVersion(ctx context.Context, version governance.LibraryVersion) error
LibraryVersions(ctx context.Context, scope string, limit int) ([]governance.LibraryVersion, error)
// 当前生效版本与"某快照自己的登记"必须是精确查询:LibraryVersions 是分页展示窗口,
// 窗口一满就会把"已生效"读成"没有",同步闸口/基线入口就会放行一次不必要的重写。
LibraryCurrentVersion(ctx context.Context, scope string) (governance.LibraryVersion, bool, error)
LibraryVersionOfSnapshot(ctx context.Context, scope string, kind governance.LibraryVersionKind,
snapshotID string) (governance.LibraryVersion, bool, error)
UpdateLibraryStage(ctx context.Context, jobID, stage, state string, total, completed, bytesTotal, bytesDone *int64, detail string, now time.Time) error
AdvanceLibraryJob(ctx context.Context, jobID string, state governance.LibraryJobState, stage, message, recovery, snapshotID, targetSnapshotID string, now time.Time) error
AttachLibraryQueueJob(ctx context.Context, jobID, queueJobID string, now time.Time) error
@@ -678,16 +683,27 @@ func libraryOverviewHandler(w http.ResponseWriter, r *http.Request, config Confi
}
// 生产生效 / 预备份 / 作业来自持久登记。
// 历史列表仍是分页展示(窗口),但"当前生效版本"必须精确查:窗口一满,
// 生效版本会掉出列表,页面就会显示成"没有生效版本",与真实状态不符。
versions, err := store.LibraryVersions(r.Context(), scope, 50)
if err != nil {
writeJSON(w, http.StatusInternalServerError, map[string]string{"error": "cannot read library versions"})
return
}
current, hasCurrent, currentErr := store.LibraryCurrentVersion(r.Context(), scope)
if currentErr != nil {
writeJSON(w, http.StatusInternalServerError, map[string]string{"error": "cannot read current library version"})
return
}
if archiveReadable {
overview.TestSealed, overview.TestSealedReason = testSealedOf(versions, byID)
}
overview.Production = libraryKnownView{State: "unknown", Reason: "还没有生产验证通过的生效版本记录"}
overview.Prebackup = libraryKnownView{State: "unknown", Reason: "这个范围还没有任何生产预备份"}
if hasCurrent {
view := libraryVersionViewOf(current)
overview.Production = libraryKnownView{State: "known", Version: &view}
}
target := ""
if overview.TestSealed != nil {
target = overview.TestSealed.SnapshotID
@@ -701,9 +717,7 @@ func libraryOverviewHandler(w http.ResponseWriter, r *http.Request, config Confi
})
switch item.Kind {
case governance.LibraryVersionProductionEffective:
if item.SupersededAt == nil {
overview.Production = libraryKnownView{State: "known", Version: &view}
}
// 生效状态只认上面那条精确查询;这里只负责把历史行放进列表。
case governance.LibraryVersionProductionPrebackup:
// 页面要显示"最近一次生产写入前的备份",不是"与拟发布快照同内容的那一份":
// 恢复作业登记的是**恢复前**的备份,它和测试封存快照本来就不同;
@@ -833,12 +847,24 @@ func librarySyncEnqueue(w http.ResponseWriter, r *http.Request, config Config) {
return
}
overview := libraryOverview{Scope: request.Scope}
// 闸口依赖"生产是否已有生效版本":这是**创建**判据,必须精确查。
// 用窗口列表会把它读成"没有",于是把一次不必要的覆盖当成合法首发;
// 查询失败同样拒绝(fail closed),不猜。
current, hasCurrent, currentErr := store.LibraryCurrentVersion(r.Context(), request.Scope)
if currentErr != nil {
writeJSON(w, http.StatusInternalServerError, map[string]string{"error": "cannot read current library version"})
return
}
versions, err := store.LibraryVersions(r.Context(), request.Scope, 50)
if err != nil {
writeJSON(w, http.StatusInternalServerError, map[string]string{"error": "cannot read library versions"})
return
}
overview.Production = libraryKnownView{State: "unknown"}
if hasCurrent {
view := libraryVersionViewOf(current)
overview.Production = libraryKnownView{State: "known", Version: &view}
}
overview.Prebackup = libraryKnownView{State: "unknown"}
if empty, probeErr := productionScopeEmpty(r.Context(), config, request.Scope); probeErr == nil && empty {
overview.Production = libraryKnownView{State: "unknown", EmptyBaseline: true,
@@ -846,10 +872,6 @@ func librarySyncEnqueue(w http.ResponseWriter, r *http.Request, config Config) {
}
for index := range versions {
item := versions[index]
if item.Kind == governance.LibraryVersionProductionEffective && item.SupersededAt == nil {
view := libraryVersionViewOf(item)
overview.Production = libraryKnownView{State: "known", Version: &view}
}
if item.Kind == governance.LibraryVersionProductionPrebackup && request.Target != "" && item.SnapshotID == request.Target {
view := libraryVersionViewOf(item)
overview.Prebackup = libraryKnownView{State: "known", Version: &view}
+91
View File
@@ -3,6 +3,7 @@ package httpapi
import (
"context"
"encoding/json"
"errors"
"net/http"
"net/http/httptest"
"strings"
@@ -24,6 +25,10 @@ type fakeLibraryStore struct {
createN int
lastJob governance.LibraryJob
lastState governance.LibraryJobState
// current 让用例表达"窗口列表里看不到、但精确查询能查到当前生效版本"这一现场形状;
// currentErr 表达"读不到"(调用方必须 fail closed,不许当成没有生效版本)。
current *governance.LibraryVersion
currentErr error
}
func (f *fakeLibraryStore) CreateLibraryJob(_ context.Context, job governance.LibraryJob, _ []string, _ time.Time) (governance.LibraryJob, bool, error) {
@@ -61,6 +66,33 @@ func (f *fakeLibraryStore) LibraryVersions(_ context.Context, scope string, _ in
return result, nil
}
// 当前生效版本是精确查询:这里刻意只按 (scope, kind, 未顶替) 过滤,不模拟分页窗口,
// 与真实 Store 的契约一致(窗口只用于展示列表)。
func (f *fakeLibraryStore) LibraryCurrentVersion(_ context.Context, scope string) (governance.LibraryVersion, bool, error) {
if f.currentErr != nil {
return governance.LibraryVersion{}, false, f.currentErr
}
if f.current != nil {
return *f.current, true, nil
}
for _, version := range f.versions {
if version.Scope == scope && version.Kind == governance.LibraryVersionProductionEffective && version.SupersededAt == nil {
return version, true, nil
}
}
return governance.LibraryVersion{}, false, nil
}
func (f *fakeLibraryStore) LibraryVersionOfSnapshot(_ context.Context, scope string, kind governance.LibraryVersionKind,
snapshotID string) (governance.LibraryVersion, bool, error) {
for _, version := range f.versions {
if version.Scope == scope && version.Kind == kind && version.SnapshotID == snapshotID {
return version, true, nil
}
}
return governance.LibraryVersion{}, false, nil
}
func (f *fakeLibraryStore) UpdateLibraryStage(_ context.Context, _, _, _ string, _, _, _, _ *int64, _ string, _ time.Time) error {
return nil
}
@@ -414,3 +446,62 @@ func TestLibraryOverviewKeepsVersionKindsSeparate(t *testing.T) {
t.Fatal("gate must stay closed")
}
}
// 现场形状:历史把生效版本挤出了展示窗口(LibraryVersions 返回空),但"当前生效版本"
// 精确查询仍读得到它。同步闸口必须据此认为生产已有权威版本:
// 读成"没有"会把一次不必要的覆盖放行,并把人推向"重新建基线"。
func TestLibrarySyncEnqueueUsesExactCurrentVersionBeyondWindow(t *testing.T) {
target := "snap-1"
digest, err := librarySyncParamsDigest("internal", target)
if err != nil {
t.Fatal(err)
}
now := time.Now().UTC()
store := &fakeLibraryStore{
// 窗口:故意什么都不返回(模拟生效版本掉出"最近 N 条")。
versions: []governance.LibraryVersion{},
current: &governance.LibraryVersion{ID: "ver-prod", Scope: "internal",
Kind: governance.LibraryVersionProductionEffective, SnapshotID: "prod-snap",
VersionLabel: "prod-2026.10", CreatedAt: now.Add(-72 * time.Hour)},
}
store.enqueueEchoRequestedID = true
store.grant = &governance.LibraryReleaseAuthorization{ID: "auth-1", Scope: "internal", SnapshotID: target,
ParamsDigest: digest, AuthorizedBy: "admin", ExpiresAt: now.Add(30 * time.Minute), CreatedAt: now}
config := Config{Store: store, ProductionReleaseRequestsEnabled: true, ProductionBackupRestoreVerified: true,
LibraryProductionDatabaseURL: "postgres://prod.invalid/db", LibraryProductionInternalKB: "kb-int",
LibraryCapacityBudgetBytes: 1 << 40}
body := `{"scope":"internal","target_snapshot_id":"` + target + `"}`
recorder := httptest.NewRecorder()
librarySyncEnqueue(recorder, httptest.NewRequest(http.MethodPost, "/api/v1/library/syncs", strings.NewReader(body)), config)
if recorder.Code != http.StatusAccepted {
t.Fatalf("status=%d body=%s(窗口外读到生效版本时闸口不该拒绝)", recorder.Code, recorder.Body.String())
}
if store.createN != 1 {
t.Fatalf("created=%d, want 1", store.createN)
}
}
// 读不到当前生效版本时不许猜:fail closed(500)且不创建作业。
func TestLibrarySyncEnqueueFailsClosedWhenCurrentVersionUnreadable(t *testing.T) {
target := "snap-1"
digest, err := librarySyncParamsDigest("internal", target)
if err != nil {
t.Fatal(err)
}
now := time.Now().UTC()
store := &fakeLibraryStore{currentErr: errors.New("version storage down")}
store.grant = &governance.LibraryReleaseAuthorization{ID: "auth-1", Scope: "internal", SnapshotID: target,
ParamsDigest: digest, AuthorizedBy: "admin", ExpiresAt: now.Add(30 * time.Minute), CreatedAt: now}
config := Config{Store: store, ProductionReleaseRequestsEnabled: true, ProductionBackupRestoreVerified: true,
LibraryProductionDatabaseURL: "postgres://prod.invalid/db", LibraryProductionInternalKB: "kb-int",
LibraryCapacityBudgetBytes: 1 << 40}
recorder := httptest.NewRecorder()
librarySyncEnqueue(recorder, httptest.NewRequest(http.MethodPost, "/api/v1/library/syncs",
strings.NewReader(`{"scope":"internal","target_snapshot_id":"`+target+`"}`)), config)
if recorder.Code != http.StatusInternalServerError {
t.Fatalf("status=%d body=%s", recorder.Code, recorder.Body.String())
}
if store.createN != 0 {
t.Fatalf("created %d jobs while the current version was unreadable", store.createN)
}
}
+19 -3
View File
@@ -103,14 +103,19 @@ func libraryStorageHandler(w http.ResponseWriter, r *http.Request, config Config
if listErr == nil {
for _, item := range versions {
kinds[item.SnapshotID] = item
if item.Kind == governance.LibraryVersionProductionEffective && item.SupersededAt == nil {
protectedBy[item.SnapshotID] = append(protectedBy[item.SnapshotID], "生产生效版本")
}
if item.Kind == governance.LibraryVersionProductionPrebackup {
protectedBy[item.SnapshotID] = append(protectedBy[item.SnapshotID], "生产预备份")
}
}
}
// 生产生效版本 = 唯一一条未顶替的记录,必须精确查:它可能早已掉出上面的
// 展示窗口,靠列表判"是否受保护"会让当前生效的那份被当成普通版本清掉。
if current, found, currentErr := store.LibraryCurrentVersion(r.Context(), scope); currentErr == nil && found {
if _, seen := kinds[current.SnapshotID]; !seen {
kinds[current.SnapshotID] = current
}
protectedBy[current.SnapshotID] = appendUnique(protectedBy[current.SnapshotID], "生产生效版本")
}
jobs, jobErr := store.ListLibraryJobs(r.Context(), scope, 20)
if jobErr == nil {
for _, job := range jobs {
@@ -205,3 +210,14 @@ func libraryStorageHandler(w http.ResponseWriter, r *http.Request, config Config
response.Capacity = libraryretention.CheckCapacity(total.ContentBytes, requiredBytes, config.LibraryCapacityBudgetBytes)
writeJSON(w, http.StatusOK, response)
}
// appendUnique 只追加还没出现过的标签:同一条版本可能同时被展示窗口与精确查询命中,
// 重复标签会让"保护依据"看起来像两条不同理由。
func appendUnique(labels []string, value string) []string {
for _, item := range labels {
if item == value {
return labels
}
}
return append(labels, value)
}
@@ -460,6 +460,8 @@ func scanLibraryVersions(rows pgx.Rows, capacity int) ([]governance.LibraryVersi
return result, rows.Err()
}
// LibraryVersions 是**分页展示**用的窗口列表(1..100),语义是"最近 N 条"。
// 任何"当前生效 / 本快照是否生效过"的判断都不许用它:窗口一满就会把存在读成不存在。
func (s *Store) LibraryVersions(ctx context.Context, scope string, limit int) ([]governance.LibraryVersion, error) {
if limit < 1 || limit > 100 {
return nil, errors.New("library version limit out of range")
@@ -473,6 +475,73 @@ FROM library_versions WHERE scope=$1 ORDER BY created_at DESC, id DESC LIMIT $2`
return scanLibraryVersions(rows, limit)
}
// LibraryCurrentVersion 返回这个 scope **当前生效**(未被顶替)的生产版本。
//
// 为什么不能用窗口列表:生效版本每 scope 只有一行,但它可能很久以前就登记了;
// 之后写进来的预备份/封存记录会把它挤出任何"最近 N 条",于是接管/基线/同步闸口
// 会把"已生效"读成"没有生效"——症状是重写已经上线的内容。
// 这里按 (scope, kind, superseded_at IS NULL) 精确取,窗口大小与它无关。
//
// 唯一索引 library_versions_effective 保证每 scope 至多一行;真出现多行说明台账
// 被写坏,返回错误让调用方 fail closed,不许挑一条"看起来对"的。
func (s *Store) LibraryCurrentVersion(ctx context.Context, scope string) (governance.LibraryVersion, bool, error) {
if scope == "" {
return governance.LibraryVersion{}, false, errors.New("library current version requires scope")
}
rows, err := s.db.Query(ctx, `
SELECT id, scope, kind, snapshot_id, version_label, source_job_id, evidence, created_by, created_at, superseded_at
FROM library_versions
WHERE scope=$1 AND kind='production_effective' AND superseded_at IS NULL
ORDER BY created_at DESC, id DESC LIMIT 2`, scope)
if err != nil {
return governance.LibraryVersion{}, false, fmt.Errorf("load current library version: %w", err)
}
items, err := scanLibraryVersions(rows, 2)
if err != nil {
return governance.LibraryVersion{}, false, err
}
if len(items) > 1 {
return governance.LibraryVersion{}, false, fmt.Errorf("%d 条未顶替的生效版本并存(scope=%s):拒绝挑选",
len(items), scope)
}
if len(items) == 1 {
return items[0], true, nil
}
return governance.LibraryVersion{}, false, nil
}
// LibraryVersionOfSnapshot 按 (scope, kind, 快照) 取这个快照**自己的**登记记录(不限作业)。
//
// 用途是"本快照曾经生效过吗/是否已被顶替":版本 id 由 (kind, scope, 快照) 决定,
// 一个快照在一种类型下只该有一行,作业归属会随恢复/重放被改写,所以不能用作业当条件。
// 命中多行同样拒绝挑选。
func (s *Store) LibraryVersionOfSnapshot(ctx context.Context, scope string,
kind governance.LibraryVersionKind, snapshotID string) (governance.LibraryVersion, bool, error) {
if scope == "" || kind == "" || snapshotID == "" {
return governance.LibraryVersion{}, false, errors.New("library version snapshot requires scope, kind and snapshot")
}
rows, err := s.db.Query(ctx, `
SELECT id, scope, kind, snapshot_id, version_label, source_job_id, evidence, created_by, created_at, superseded_at
FROM library_versions
WHERE scope=$1 AND kind=$2 AND snapshot_id=$3
ORDER BY created_at DESC, id DESC LIMIT 2`, scope, string(kind), snapshotID)
if err != nil {
return governance.LibraryVersion{}, false, fmt.Errorf("load library version of snapshot: %w", err)
}
found, err := scanLibraryVersions(rows, 2)
if err != nil {
return governance.LibraryVersion{}, false, err
}
if len(found) > 1 {
return governance.LibraryVersion{}, false, fmt.Errorf("同一快照存在 %d 条 %s 版本记录(%s):拒绝挑选",
len(found), kind, snapshotID)
}
if len(found) == 1 {
return found[0], true, nil
}
return governance.LibraryVersion{}, false, nil
}
// CreateLibraryAuthorization 记录一次生产发布授权;同一 (scope,snapshot,digest) 只保留最新有效。
func (s *Store) CreateLibraryAuthorization(ctx context.Context, item governance.LibraryReleaseAuthorization) error {
if item.ID == "" || item.Scope == "" || item.SnapshotID == "" || item.ParamsDigest == "" || item.ExpiresAt.IsZero() {
@@ -147,3 +147,105 @@ func TestLibraryVersionByRefRejectsIncompleteRef(t *testing.T) {
}
}
}
func recordEffective(t *testing.T, ctx context.Context, store *Store, scope, jobID, snapshot string, created time.Time) {
t.Helper()
if err := store.RecordLibraryVersion(ctx, governance.LibraryVersion{
ID: governance.LibraryVersionID(governance.LibraryVersionProductionEffective, scope, snapshot),
Scope: scope, Kind: governance.LibraryVersionProductionEffective, SnapshotID: snapshot,
SourceJobID: jobID, CreatedBy: "worker",
Evidence: map[string]any{"action": "sync", "job": jobID},
CreatedAt: created,
}); err != nil {
t.Fatalf("record effective %s: %v", snapshot, err)
}
}
// 当前生效版本必须按"未顶替"这个事实精确查,不能靠"最近 N 条":历史一旦超过窗口,
// 生效版本会被读成"没有",接管/基线/同步闸口就会把已经生效的目标再写一遍。
func TestLibraryCurrentVersionFindsEffectiveOutsideHistoryWindow(t *testing.T) {
store, _ := openVersionStore(t)
ctx := context.Background()
now := time.Now().UTC()
// 生效版本登记在很早的时刻,之后同 scope 又写了 300 条其它版本(真实列表上限 100)。
recordEffective(t, ctx, store, "internal", "job-cur", "snap-cur", now.Add(-72*time.Hour))
for i := 0; i < 300; i++ {
recordPrebackup(t, ctx, store, "internal", fmt.Sprintf("job-new-%03d", i), fmt.Sprintf("snap-new-%03d", i),
now.Add(-time.Duration(i)*time.Minute))
}
window, err := store.LibraryVersions(ctx, "internal", 100)
if err != nil {
t.Fatalf("list versions: %v", err)
}
for _, item := range window {
if item.SnapshotID == "snap-cur" {
t.Fatal("窗口里仍能看到生效版本:本用例证明不了窗口之外仍可精确取回(夹具失效)")
}
}
current, found, err := store.LibraryCurrentVersion(ctx, "internal")
if err != nil || !found {
t.Fatalf("窗口之外也必须取到当前生效版本:found=%v err=%v", found, err)
}
if current.SnapshotID != "snap-cur" || current.SourceJobID != "job-cur" || current.SupersededAt != nil {
t.Fatalf("取到的不是当前生效版本:%+v", current)
}
// 新版本生效后,旧快照按身份查仍然"存在但已顶替"——接管据此拒绝用旧快照覆盖。
recordEffective(t, ctx, store, "internal", "job-new", "snap-newest", now)
current, found, err = store.LibraryCurrentVersion(ctx, "internal")
if err != nil || !found || current.SnapshotID != "snap-newest" {
t.Fatalf("当前生效版本必须切到最新一份:found=%v err=%v %+v", found, err, current)
}
previous, found, err := store.LibraryVersionOfSnapshot(ctx, "internal",
governance.LibraryVersionProductionEffective, "snap-cur")
if err != nil || !found {
t.Fatalf("旧快照必须仍能按身份取回:found=%v err=%v", found, err)
}
if previous.SupersededAt == nil {
t.Fatalf("旧快照必须标成已顶替:%+v", previous)
}
}
// 没有生效版本 ≠ 查询失败:前者是"首次发布",后者必须让调用方 fail closed。
func TestLibraryCurrentVersionSeparatesMissingFromOtherKinds(t *testing.T) {
store, _ := openVersionStore(t)
ctx := context.Background()
now := time.Now().UTC()
recordPrebackup(t, ctx, store, "internal", "job-a", "snap-1", now)
if _, found, err := store.LibraryCurrentVersion(ctx, "internal"); err != nil || found {
t.Fatalf("只有预备份时不能当成有生效版本:found=%v err=%v", found, err)
}
recordEffective(t, ctx, store, "internal", "job-a", "snap-eff", now)
// 跨 scope 不许命中。
if _, found, err := store.LibraryCurrentVersion(ctx, "external"); err != nil || found {
t.Fatalf("跨 scope 不许命中:found=%v err=%v", found, err)
}
if _, found, err := store.LibraryVersionOfSnapshot(ctx, "external",
governance.LibraryVersionProductionEffective, "snap-eff"); err != nil || found {
t.Fatalf("跨 scope 的快照查询不许命中:found=%v err=%v", found, err)
}
if _, found, err := store.LibraryVersionOfSnapshot(ctx, "internal",
governance.LibraryVersionProductionEffective, "snap-missing"); err != nil || found {
t.Fatalf("未登记的快照必须 found=false 且无错误:found=%v err=%v", found, err)
}
}
// 同一快照两行(台账被写坏):按身份查必须拒绝挑选,不许挑一条"看起来对"的。
func TestLibraryVersionOfSnapshotRejectsAmbiguousRows(t *testing.T) {
store, pool := openVersionStore(t)
ctx := context.Background()
now := time.Now().UTC()
recordPrebackup(t, ctx, store, "internal", "job-a", "snap-dup", now)
if _, err := pool.Exec(ctx, `
INSERT INTO library_versions (id, scope, kind, snapshot_id, source_job_id, evidence, created_by, created_at)
VALUES ('libver-dup-current','internal','production_prebackup','snap-dup','job-b','{}'::jsonb,'worker',$1)`, now); err != nil {
t.Fatalf("insert duplicate row: %v", err)
}
if _, found, err := store.LibraryVersionOfSnapshot(ctx, "internal",
governance.LibraryVersionProductionPrebackup, "snap-dup"); err == nil || found {
t.Fatalf("同一快照多行时必须拒绝:found=%v err=%v", found, err)
} else if !strings.Contains(err.Error(), "拒绝挑选") {
t.Fatalf("错误要说清是重复身份,实际:%v", err)
}
}