knowledge-governance/internal/releasebundle/manifest.go

package releasebundle

import (
	"crypto/sha256"
	"encoding/hex"
	"encoding/json"
	"errors"
	"sort"
	"strings"
	"time"
)

const (
	FormatVersionV1        = "weknora-release-bundle/v1"
	WeKnoraVersionV071     = "v0.7.1"
	WeKnoraMigrationV071   = 74
	EmbeddingDimensionV071 = 1024
)

var allowedTables = map[string]bool{
	"knowledges":              true,
	"chunks":                  true,
	"knowledge_tags":          true,
	"knowledge_tag_relations": true,
	"resources":               true,
	"resource_bindings":       true,
	"wiki_pages":              true,
	"wiki_folders":            true,
}

type Manifest struct {
	FormatVersion       string        `json:"format_version"`
	ExecutionID         string        `json:"execution_id"`
	PublicationID       string        `json:"publication_id"`
	SourceItemVersionID string        `json:"source_item_version_id"`
	SourceRevision      string        `json:"source_revision"`
	ParseRevision       string        `json:"parse_revision"`
	ReleaseRevision     string        `json:"release_revision"`
	CreatedAt           time.Time     `json:"created_at"`
	Contract            Contract      `json:"contract"`
	Tables              []TableDigest `json:"tables"`
	Search              SearchDigest  `json:"search"`
	Assets              AssetDigest   `json:"assets"`
	BundleSHA256        string        `json:"bundle_sha256"`
}

type Contract struct {
	WeKnoraVersion             string `json:"weknora_version"`
	MigrationVersion           int    `json:"migration_version"`
	TenantID                   uint64 `json:"tenant_id"`
	KnowledgeBaseID            string `json:"knowledge_base_id"`
	KnowledgeID                string `json:"knowledge_id"`
	RetrieverEngine            string `json:"retriever_engine"`
	EmbeddingModel             string `json:"embedding_model"`
	EmbeddingDimension         int    `json:"embedding_dimension"`
	ElasticsearchMappingSHA256 string `json:"elasticsearch_mapping_sha256"`
}

type TargetContract struct {
	WeKnoraVersion             string
	MigrationVersion           int
	TenantID                   uint64
	KnowledgeBaseID            string
	RetrieverEngine            string
	EmbeddingModel             string
	EmbeddingDimension         int
	ElasticsearchMappingSHA256 string
}

type TableDigest struct {
	Name     string `json:"name"`
	RowCount int    `json:"row_count"`
	SHA256   string `json:"sha256"`
}

type SearchDigest struct {
	DocumentCount int    `json:"document_count"`
	SHA256        string `json:"sha256"`
}

type AssetDigest struct {
	ObjectCount int    `json:"object_count"`
	TotalBytes  int64  `json:"total_bytes"`
	SHA256      string `json:"sha256"`
}

func Seal(manifest Manifest) (Manifest, error) {
	manifest.BundleSHA256 = ""
	manifest.Tables = append([]TableDigest(nil), manifest.Tables...)
	sort.Slice(manifest.Tables, func(left, right int) bool { return manifest.Tables[left].Name < manifest.Tables[right].Name })
	if err := validateManifestFields(manifest); err != nil {
		return Manifest{}, err
	}
	digest, err := manifestDigest(manifest)
	if err != nil {
		return Manifest{}, err
	}
	manifest.BundleSHA256 = digest
	return manifest, nil
}

// KnowledgeBaseMapping is the declared 源库 → 目标库 pair for a release item.
// An empty TargetKnowledgeBaseID means the historical same-id semantics: the
// production base must carry exactly the tested base's id.
type KnowledgeBaseMapping struct {
	SourceKnowledgeBaseID string
	TargetKnowledgeBaseID string
}

// EffectiveTarget is the base the release writes into.
func (mapping KnowledgeBaseMapping) EffectiveTarget() string {
	if trimmed := strings.TrimSpace(mapping.TargetKnowledgeBaseID); trimmed != "" {
		return trimmed
	}
	return mapping.SourceKnowledgeBaseID
}

// Validate proves the bundle contract against the target data plane. The only
// thing a cross-base release relaxes is the base identity itself: the bundle
// keeps the SOURCE base and the target must match the DECLARED mapping, so an
// undeclared (or stale) mapping still fails closed.
func Validate(manifest Manifest, target TargetContract, mapping KnowledgeBaseMapping) error {
	if err := validateManifestFields(manifest); err != nil {
		return err
	}
	if !validSHA256(manifest.BundleSHA256) {
		return errors.New("invalid bundle digest")
	}
	expected, err := manifestDigest(manifest)
	if err != nil {
		return err
	}
	if expected != manifest.BundleSHA256 {
		return errors.New("bundle digest mismatch")
	}
	contract := manifest.Contract
	if mapping.SourceKnowledgeBaseID != contract.KnowledgeBaseID {
		return errors.New("release mapping does not match bundle")
	}
	if target.KnowledgeBaseID != mapping.EffectiveTarget() {
		return errors.New("target release contract mismatch")
	}
	if target.WeKnoraVersion != WeKnoraVersionV071 || target.MigrationVersion != WeKnoraMigrationV071 ||
		contract.WeKnoraVersion != target.WeKnoraVersion || contract.MigrationVersion != target.MigrationVersion ||
		contract.TenantID != target.TenantID ||
		contract.RetrieverEngine != target.RetrieverEngine || contract.EmbeddingModel != target.EmbeddingModel ||
		contract.EmbeddingDimension != target.EmbeddingDimension ||
		contract.ElasticsearchMappingSHA256 != target.ElasticsearchMappingSHA256 {
		return errors.New("target release contract mismatch")
	}
	return nil
}

func validateManifestFields(manifest Manifest) error {
	if manifest.FormatVersion != FormatVersionV1 || manifest.Contract.WeKnoraVersion != WeKnoraVersionV071 ||
		manifest.Contract.MigrationVersion != WeKnoraMigrationV071 || manifest.Contract.EmbeddingDimension != EmbeddingDimensionV071 ||
		manifest.Contract.RetrieverEngine != "elasticsearch_v8" || manifest.Contract.TenantID == 0 || manifest.CreatedAt.IsZero() {
		return errors.New("unsupported release contract")
	}
	for _, value := range []string{manifest.ExecutionID, manifest.PublicationID, manifest.SourceItemVersionID,
		manifest.SourceRevision, manifest.ParseRevision, manifest.ReleaseRevision, manifest.Contract.KnowledgeBaseID,
		manifest.Contract.KnowledgeID, manifest.Contract.EmbeddingModel} {
		if !validIdentifier(value) {
			return errors.New("invalid release identity")
		}
	}
	if !validSHA256(manifest.Contract.ElasticsearchMappingSHA256) || !validSHA256(manifest.Search.SHA256) || !validSHA256(manifest.Assets.SHA256) ||
		manifest.Search.DocumentCount < 0 || manifest.Assets.ObjectCount < 0 || manifest.Assets.TotalBytes < 0 {
		return errors.New("invalid release digest")
	}
	seen := make(map[string]bool, len(manifest.Tables))
	hasKnowledge, hasChunks := false, false
	for _, table := range manifest.Tables {
		if !allowedTables[table.Name] || seen[table.Name] || table.RowCount < 0 || !validSHA256(table.SHA256) {
			return errors.New("invalid release table")
		}
		seen[table.Name] = true
		hasKnowledge = hasKnowledge || table.Name == "knowledges" && table.RowCount == 1
		hasChunks = hasChunks || table.Name == "chunks" && table.RowCount > 0
	}
	if !hasKnowledge || !hasChunks {
		return errors.New("release manifest requires one knowledge and at least one chunk")
	}
	return nil
}

func manifestDigest(manifest Manifest) (string, error) {
	manifest.BundleSHA256 = ""
	manifest.Tables = append([]TableDigest(nil), manifest.Tables...)
	sort.Slice(manifest.Tables, func(left, right int) bool { return manifest.Tables[left].Name < manifest.Tables[right].Name })
	payload, err := json.Marshal(manifest)
	if err != nil {
		return "", errors.New("encode release manifest")
	}
	digest := sha256.Sum256(payload)
	return hex.EncodeToString(digest[:]), nil
}

func validSHA256(value string) bool {
	if len(value) != 64 {
		return false
	}
	for _, char := range value {
		if (char < '0' || char > '9') && (char < 'a' || char > 'f') {
			return false
		}
	}
	return true
}

func validIdentifier(value string) bool {
	return value == strings.TrimSpace(value) && value != "" && len(value) <= 128 && !strings.ContainsAny(value, "\x00\r\n\t/?#\\")
}