Files
knowledge-governance/internal/releaseadapter/v071/library_capture.go
T
姚章浩 c2402947a9
build / build (push) Successful in 1m26s
feat(library): 死信按精确指纹解除,保留上游记录
上游 task_dead_letters 没有解决标记,purge/DELETE 会销毁"失败过"的唯一证据。
治理侧新增解除记录(迁移 073):绑定实时行逐字节指纹、重放引用、源侧观测摘要与
操作人;行被改过、重放后又出现新死信、源侧未结清都不命中,封存照旧阻断。
指纹先压紧空白再摘要,避免 PG to_jsonb::text 与 json.Marshal 的空白差异。

试过:go test ./internal/{librarydeadletter,libraryagent,httpapi,releaseadapter/v071,
platform/postgres},make verify 15 项全绿。
2026-10-29 06:55:13 +08:00

93 lines
4.4 KiB
Go

package v071
import (
"context"
"errors"
"time"
"knowledge-governance/internal/libraryfreeze"
"knowledge-governance/internal/librarysnapshot"
)
type LibraryCaptureRequest struct {
JobID, Scope string
Identity PostgresIdentity
Compatibility librarysnapshot.Compatibility
CreatedAt time.Time
MaxDocuments int
// VerifyContract, when set, runs inside the stopped window immediately before
// the export. The caller re-reads the source contract and returns an error if
// it differs from Compatibility, so a model/index change between the
// preflight read and the maintenance window cannot be sealed silently.
VerifyContract func(context.Context) error
// ReleasedDeadLetters 是治理平台已审计的精确解除指纹。它只把"这些确切的行"
// 从死信阻断里摘出来:实时行必须逐字节命中,否则照旧阻断。
ReleasedDeadLetters []string
}
// CaptureLibrary connects maintenance to the actual PG/PIT/object archive path.
// sourceReady is mandatory and must verify the whole writer group (both scopes,
// ingress and background jobs), not only this KB. It runs before stopping and
// again inside the stopped window. Deployment must establish that the group
// contains every source writer. This function does not certify Wiki semantics,
// approve a release, or give the worker any production credentials.
func CaptureLibrary(ctx context.Context, freeze *libraryfreeze.Coordinator, archive *librarysnapshot.Archive, db librarySnapshotDB, search *SearchExporter, objects ObjectReader, sourceReady func(context.Context) error, req LibraryCaptureRequest) (libraryfreeze.Result, error) {
if freeze == nil || archive == nil || db == nil || search == nil || objects == nil || sourceReady == nil || req.CreatedAt.IsZero() || req.MaxDocuments < 1 || req.Identity.TenantID == 0 || !validSearchIdentifier(req.Identity.KnowledgeBaseID) || req.Identity.KnowledgeID != "" || (req.Scope != "internal" && req.Scope != "external") {
return libraryfreeze.Result{}, errors.New("invalid library capture configuration")
}
result, err := freeze.RunPrepared(ctx, req.JobID, func(ctx context.Context) error {
if err := checkLibrarySourceSettlementReleased(ctx, db, req.ReleasedDeadLetters); err != nil {
return err
}
if err := sourceReady(ctx); err != nil {
return err
}
// Check readiness before a maintenance window, then repeat the export inside
// that window: work can arrive between preflight and the graceful stop.
_, err := ExportLibraryWithReleases(ctx, db, req.Identity, req.ReleasedDeadLetters)
return err
}, func(ctx context.Context) (string, error) {
if err := checkLibrarySourceSettlementReleased(ctx, db, req.ReleasedDeadLetters); err != nil {
return "", err
}
if err := sourceReady(ctx); err != nil {
return "", err
}
if req.VerifyContract != nil {
if err := req.VerifyContract(ctx); err != nil {
return "", err
}
}
pg, err := ExportLibraryWithReleases(ctx, db, req.Identity, req.ReleasedDeadLetters)
if err != nil {
return "", err
}
es, err := search.ExportLibrary(ctx, SearchIdentity{TenantID: req.Identity.TenantID, KnowledgeBaseID: req.Identity.KnowledgeBaseID}, req.MaxDocuments)
if err != nil {
return "", err
}
return ArchiveLibraryCandidate(ctx, archive, req.Scope, req.Identity, req.Compatibility, pg, es, objects, req.CreatedAt)
})
if err != nil {
return result, err
}
// A successful old operation is replayable only while its exact independent
// archive still verifies, and never under another KB/scope/model contract.
saved, err := archive.Load(result.SnapshotID)
if err != nil {
return libraryfreeze.Result{}, errors.New("captured library archive no longer verifies")
}
if saved.ValidationPolicy != librarysnapshot.ArtifactAcceptancePolicy {
return libraryfreeze.Result{}, errors.New("library capture validation policy conflicts with existing job")
}
if saved.Scope != req.Scope || saved.TenantID != req.Identity.TenantID || saved.KnowledgeBaseID != req.Identity.KnowledgeBaseID || saved.Compatibility != req.Compatibility || !saved.CreatedAt.Equal(req.CreatedAt) {
return libraryfreeze.Result{}, errors.New("library capture request conflicts with existing job")
}
for _, part := range saved.Parts {
if part.Kind == "index" && part.Count > int64(req.MaxDocuments) {
return libraryfreeze.Result{}, errors.New("replayed library exceeds requested document limit")
}
}
return result, nil
}