feat(snapshot): 按已确认口径保留索引产物并标记验收策略
build / build (push) Successful in 1m12s

This commit is contained in:
姚章浩
2026-10-28 08:01:46 +08:00
parent 2fc6dc068b
commit 76f687b52d
6 changed files with 130 additions and 35 deletions
+7
View File
@@ -1,5 +1,12 @@
# Changelog
## 开发快照 snapshot/v0.1.104 - 2026-10-28
### Changed
- 按已确认的验收口径 A,正文索引作为原始产物保留,不再因无法从数据库反推临时生成上下文而拒绝候选归档;身份、覆盖、摘要及持久化生成问题的精确核验保持不变。
- 候选清单加入受支持的验收策略标识并纳入快照身份。候选归档不代表语义验收或生产放行;真实冻结接线、快照绑定的内容/问答/性能验收与完整同步恢复仍待完成。
## 开发快照 snapshot/v0.1.103 - 2026-10-28
### Fixed
+9
View File
@@ -6,6 +6,15 @@
现有文档包发布与执行级补偿只能作为复用基础,不能作为本清单完成证据。静态样图不作为产品运行证据。组织绩效与周报外发不在本次范围。
## 已确认:验收口径 A(原始产物)
用户选择不修改 WeKnora,以冻结的完整知识版本绑定内容、问答与性能验收。源端索引可能含未持久化的生成上下文,不再要求从 PostgreSQL 正文反推每条正文索引的生成过程。
- 原样归档索引内容与向量,不重新生成;继续校验库/文档/分块身份关联、覆盖、数量、资源及摘要。已持久化生成问题仍按 ID 和原文精确校验。
- 新候选清单记录 `validation_policy=artifact-acceptance-v1`,该字段纳入内容寻址身份;历史无该字段的快照不冒称执行了新口径。
- 候选归档成功不证明冻结、内容质量、问答正确性或性能通过。测试验收必须绑定具体快照身份;旧快照验收不得放行新快照。生产发布仍须独立授权。
- 本次只完成候选产物保留和口径记录,真实冻结业务接线与持久化验收绑定尚未完成,不能因此放行生产。
## 已确认:封存隔离方案 A
用户选择封存期间自动暂停测试 WeKnora 服务,封存后恢复,不修改 WeKnora 源码。测试问答在暂停期间暂不可用,停用时长须实测;不暂停生产服务,也不因此取得生产同步、恢复或真实清理授权。
+14 -7
View File
@@ -20,6 +20,9 @@ import (
)
const Format = "weknora-library-snapshot/v1"
// ArtifactAcceptancePolicy requires separate snapshot-bound semantic acceptance.
const ArtifactAcceptancePolicy = "artifact-acceptance-v1"
const maxManifestBytes = 16 * 1024 * 1024
type Part struct {
@@ -39,13 +42,14 @@ type Compatibility struct {
}
type Manifest struct {
Compatibility Compatibility `json:"compatibility"`
Format string `json:"format"`
Scope string `json:"scope"`
TenantID uint64 `json:"tenant_id"`
KnowledgeBaseID string `json:"knowledge_base_id"`
CreatedAt time.Time `json:"created_at"`
Parts []Part `json:"parts"`
ValidationPolicy string `json:"validation_policy,omitempty"`
Compatibility Compatibility `json:"compatibility"`
Format string `json:"format"`
Scope string `json:"scope"`
TenantID uint64 `json:"tenant_id"`
KnowledgeBaseID string `json:"knowledge_base_id"`
CreatedAt time.Time `json:"created_at"`
Parts []Part `json:"parts"`
}
type Archive struct {
root, blobs, versions *os.Root
@@ -361,6 +365,9 @@ func identifier(s string) bool {
}
func encodeManifest(m Manifest) ([]byte, error) {
if m.ValidationPolicy != "" && m.ValidationPolicy != ArtifactAcceptancePolicy {
return nil, errors.New("unsupported snapshot validation policy")
}
c := m.Compatibility
if c.WeKnoraVersion != releasebundle.WeKnoraVersionV071 || c.SchemaVersion != releasebundle.WeKnoraMigrationV071 || c.RetrieverEngine != "elasticsearch_v8" || !identifier(c.EmbeddingModel) || c.EmbeddingDimension != releasebundle.EmbeddingDimensionV071 || !validDigest(c.IndexMappingSHA256) {
return nil, errors.New("unsupported snapshot compatibility contract")
@@ -24,7 +24,7 @@ func ArchiveLibraryCandidate(ctx context.Context, archive *librarysnapshot.Archi
if es.MappingSHA256 != contract.IndexMappingSHA256 {
return "", errors.New("library mapping contract mismatch")
}
manifest := librarysnapshot.Manifest{Format: librarysnapshot.Format, Scope: scope, TenantID: identity.TenantID, KnowledgeBaseID: identity.KnowledgeBaseID, CreatedAt: createdAt, Compatibility: contract}
manifest := librarysnapshot.Manifest{ValidationPolicy: librarysnapshot.ArtifactAcceptancePolicy, Format: librarysnapshot.Format, Scope: scope, TenantID: identity.TenantID, KnowledgeBaseID: identity.KnowledgeBaseID, CreatedAt: createdAt, Compatibility: contract}
put := func(kind, name string, count int64, data []byte) error {
if err := ctx.Err(); err != nil {
return err
@@ -123,24 +123,6 @@ type libraryRow struct {
Questions map[string]string `json:"-"`
}
func libraryIndexContentMatches(indexContent string, chunk, knowledge libraryRow) bool {
if indexContent == chunk.Content {
return true
}
if chunk.ChunkType != "text" {
return false
}
// v0.7.1 text indexing trims the body and may prepend the title. Only
// reconstruct transformations backed by archived fields. ContextHeader is
// transient upstream; suffix matching would silently accept stale content.
body := strings.TrimSpace(chunk.Content)
if indexContent == body {
return true
}
title := strings.TrimSpace(knowledge.Title)
return title != "" && indexContent == title+"\n"+body
}
func validateLibraryCandidate(identity PostgresIdentity, pg PostgresSnapshot, es SearchSnapshot) error {
required := map[string]bool{"resources": true}
for _, entry := range libraryContentQueries {
@@ -293,8 +275,10 @@ func validateLibraryCandidate(identity PostgresIdentity, pg PostgresSnapshot, es
}
indexedQuestions[row.ChunkID][row.SourceID] = true
} else {
if !libraryIndexContentMatches(row.Content, chunk, tables["knowledges"][chunk.KnowledgeID]) {
return errors.New("library index does not match database chunks")
// Preserve the captured artifact; transient generation context is not
// reconstructible from PG. This is not semantic acceptance or release approval.
if strings.TrimSpace(row.Content) == "" {
return errors.New("empty library index content")
}
indexedChunks[row.ChunkID] = true
}
@@ -0,0 +1,86 @@
package v071
import (
"bytes"
"context"
"encoding/json"
"io"
"os"
"testing"
"time"
"knowledge-governance/internal/librarysnapshot"
)
func TestLibraryCandidateArtifactPolicyPreservesContextIndex(t *testing.T) {
pg, es, objects := libraryCandidateFixture()
es.Documents[0].Source = json.RawMessage(`{"knowledge_base_id":"kb-safe","knowledge_id":"doc-safe","chunk_id":"chunk-safe","source_id":"chunk-safe","content":"Title\nTransient heading\n\nchunk","embedding":[0.1,0.2]}`)
es.DocumentsSHA256, _ = searchDocumentsDigest(es.Documents)
expected, err := json.Marshal(es.Documents)
if err != nil {
t.Fatal(err)
}
root := t.TempDir()
if err = os.Chmod(root, 0700); err != nil {
t.Fatal(err)
}
archive, err := librarysnapshot.Open(root, 1024*1024)
if err != nil {
t.Fatal(err)
}
defer archive.Close()
contract := librarysnapshot.Compatibility{WeKnoraVersion: "v0.7.1", SchemaVersion: 74, RetrieverEngine: "elasticsearch_v8", EmbeddingModel: "fixture-model", EmbeddingDimension: 1024, IndexMappingSHA256: es.MappingSHA256}
id, err := ArchiveLibraryCandidate(context.Background(), archive, "internal", PostgresIdentity{TenantID: 10000, KnowledgeBaseID: "kb-safe"}, contract, pg, es, objects, time.Now().UTC())
if err != nil {
t.Fatalf("artifact candidate rejected because generation cannot be reconstructed: %v", err)
}
m, err := archive.Load(id)
if err != nil {
t.Fatal(err)
}
encoded, err := json.Marshal(m)
if err != nil {
t.Fatal(err)
}
var fields map[string]any
if err = json.Unmarshal(encoded, &fields); err != nil {
t.Fatal(err)
}
if fields["validation_policy"] != "artifact-acceptance-v1" {
t.Fatal("candidate lacks explicit artifact acceptance policy")
}
found := false
for _, part := range m.Parts {
if part.Kind != "index" {
continue
}
found = true
r, e := archive.OpenPart(part)
if e != nil {
t.Fatal(e)
}
got, e := io.ReadAll(r)
r.Close()
if e != nil {
t.Fatal(e)
}
if !bytes.Equal(got, expected) {
t.Fatal("archived index content or vector rewritten")
}
}
m.ValidationPolicy = "unsupported-policy"
if _, err := archive.Seal(m); err == nil {
t.Fatal("unknown policy accepted")
}
m.ValidationPolicy = ""
legacyID, err := archive.Seal(m)
if err != nil {
t.Fatal(err)
}
if legacyID == id {
t.Fatal("validation policy was not bound into snapshot identity")
}
if !found {
t.Fatal("index missing")
}
}
@@ -5,7 +5,8 @@ import (
"testing"
)
func TestLibraryCandidateValidatesPersistedTextIndexTransform(t *testing.T) {
// Scheme A archives artifact bytes; these cases do not certify semantic quality.
func TestLibraryCandidatePreservesArtifactContentWithoutReconstruction(t *testing.T) {
for _, tc := range []struct {
name, kind, body, index string
valid bool
@@ -13,11 +14,12 @@ func TestLibraryCandidateValidatesPersistedTextIndexTransform(t *testing.T) {
{"current title prefix", "text", "\n chunk \t", "Document title\nchunk", true},
{"legacy raw body", "text", "\n chunk \t", "\n chunk \t", true},
{"trimmed body", "text", "\n chunk \t", "chunk", true},
{"wrong title", "text", "chunk", "Other title\nchunk", false},
{"missing body", "text", "chunk", "Document title\n", false},
{"different body", "text", "chunk", "Document title\nchanged", false},
{"unverifiable context header", "text", "chunk", "Document title\nTransient heading\n\nchunk", false},
{"nontext transform not assumed", "faq", "chunk", "Document title\nchunk", false},
{"wrong title", "text", "chunk", "Other title\nchunk", true},
{"missing body", "text", "chunk", "Document title\n", true},
{"different body", "text", "chunk", "Document title\nchanged", true},
{"unverifiable context header", "text", "chunk", "Document title\nTransient heading\n\nchunk", true},
{"nontext transform not assumed", "faq", "chunk", "Document title\nchunk", true},
{"empty artifact content", "text", "chunk", " \n", false},
} {
t.Run(tc.name, func(t *testing.T) {
pg, es, _ := libraryCandidateFixture()
@@ -33,7 +35,7 @@ func TestLibraryCandidateValidatesPersistedTextIndexTransform(t *testing.T) {
t.Fatalf("valid indexed text refused: %v", err)
}
if !tc.valid && err == nil {
t.Fatal("unverifiable index content accepted")
t.Fatal("empty index content accepted")
}
})
}