Move NPC occurrences to their canonical namespace

internal/modules/dnd/validate/npcoccurrences/invariants/validator.go

@@ -0,0 +1,176 @@
+// Package invariants validates normalized D&D NPC occurrence artifacts.
+package invariants
+
+import (
+	"context"
+	"fmt"
+	"sort"
+
+	"gitea.maximumdirect.net/eric/notarius/internal/core/source"
+	"gitea.maximumdirect.net/eric/notarius/internal/framework/contracts"
+	"gitea.maximumdirect.net/eric/notarius/internal/framework/pipeline"
+	"gitea.maximumdirect.net/eric/notarius/internal/modules/dnd"
+	interactionmodel "gitea.maximumdirect.net/eric/notarius/internal/modules/dnd/npcoccurrences"
+	npcregistry "gitea.maximumdirect.net/eric/notarius/internal/modules/dnd/npcs/registry"
+	"gitea.maximumdirect.net/eric/notarius/internal/modules/dnd/shared"
+	"gitea.maximumdirect.net/eric/notarius/internal/modules/dnd/shared/diagnostics"
+	occurrenceshape "gitea.maximumdirect.net/eric/notarius/internal/modules/dnd/validate/npcoccurrences/shape"
+)
+
+const (
+	Key        = "normalize/dnd/npc-occurrences/invariants"
+	ReasonCode = "invalid_npc_interaction_normalization"
+	policy     = "dnd.npc_occurrences.validator.normalized.v1"
+)
+
+type Options struct{}
+
+type Validator struct {
+	npcResolver *npcregistry.Resolver
+}
+
+var _ contracts.TypedValidator[dnd.NPCOccurrenceList] = (*Validator)(nil)
+var _ contracts.ManifestMetadataProvider = (*Validator)(nil)
+var _ pipeline.CheckpointFingerprintProvider = (*Validator)(nil)
+
+func New(_ Options, references ...contracts.ReferenceSet) (*Validator, error) {
+	if len(references) > 1 {
+		return nil, fmt.Errorf("NPC occurrence invariants validator accepts at most one reference set")
+	}
+	var referenceSet contracts.ReferenceSet
+	if len(references) == 1 {
+		referenceSet = references[0]
+	}
+	resolver, err := npcregistry.NewResolver(referenceSet)
+	if err != nil {
+		return nil, fmt.Errorf("prepare NPC registry: %w", err)
+	}
+	return &Validator{npcResolver: resolver}, nil
+}
+
+func (v *Validator) Name() string { return Key }
+func (v *Validator) ExecutionClass() contracts.ExecutionClass {
+	return contracts.ExecutionClassDeterministic
+}
+
+func (v *Validator) ManifestMetadata() map[string]any {
+	if v == nil || v.npcResolver == nil {
+		return nil
+	}
+	metadata := map[string]any{"policy": policy}
+	seeded := v.npcResolver.Seeded()
+	if seeded.Bound() {
+		metadata["npc_registry_digest"] = seeded.Digest()
+		metadata["npc_count"] = seeded.Count()
+	}
+	return metadata
+}
+
+func (v *Validator) CheckpointFingerprints() []pipeline.CheckpointFingerprint {
+	if v == nil || v.npcResolver == nil {
+		return nil
+	}
+	return []pipeline.CheckpointFingerprint{
+		{Name: "policy", Value: policy},
+		{Name: "npc_registry", Value: v.npcResolver.Seeded().IdentityPromptInput().Digest},
+	}
+}
+
+func (v *Validator) Validate(_ context.Context, req contracts.TypedValidationRequest[dnd.NPCOccurrenceList]) (contracts.ValidationResult, error) {
+	if occurrenceshape.Validate(req.Value) != nil {
+		return contracts.ValidationResult{Approved: true}, nil
+	}
+	index := source.NewDocumentIndex(req.Source)
+	if !allSourceRefsValid(index, req.Value) {
+		return contracts.ValidationResult{Approved: true}, nil
+	}
+	if v == nil || v.npcResolver == nil {
+		return contracts.ValidationResult{}, fmt.Errorf("NPC occurrence invariants validator must not be nil")
+	}
+	npcRegistry, err := v.npcResolver.Resolve(req.References)
+	if err != nil {
+		return contracts.ValidationResult{}, fmt.Errorf("resolve NPC registry: %w", err)
+	}
+	if !npcRegistry.Bound() {
+		return contracts.ValidationResult{Approved: false, ReasonCode: ReasonCode, Message: "invalid NPC occurrence normalization: NPC registry reference is required"}, nil
+	}
+	issues := issuesFor(shared.NewSourceRefOrderFromIndex(index), req.Value, npcRegistry)
+	if len(issues) == 0 {
+		return contracts.ValidationResult{Approved: true}, nil
+	}
+	return contracts.ValidationResult{
+		Approved:   false,
+		ReasonCode: ReasonCode,
+		Message:    diagnostics.Aggregate("invalid NPC occurrence normalization", issues),
+	}, nil
+}
+
+func allSourceRefsValid(index source.DocumentIndex, value dnd.NPCOccurrenceList) bool {
+	for _, occurrence := range value.Occurrences {
+		if !interactionmodel.ValidSourceRefs(index, occurrence.SourceRefs) {
+			return false
+		}
+	}
+	return true
+}
+
+func issuesFor(order shared.SourceRefOrder, value dnd.NPCOccurrenceList, npcRegistry *npcregistry.Registry) []string {
+	issues := make([]string, 0)
+	for index, occurrence := range value.Occurrences {
+		prefix := fmt.Sprintf("occurrences[%d]", index)
+		canonical, ok := npcRegistry.LookupID(occurrence.NPCID)
+		if !ok {
+			issues = append(issues, prefix+".npc_id is not in the NPC registry: "+diagnostics.Quote(occurrence.NPCID))
+		} else if occurrence.Name != canonical.Name {
+			issues = append(issues, prefix+".name does not match npc_id: "+diagnostics.Quote(occurrence.Name))
+		}
+		for refIndex := 1; refIndex < len(occurrence.SourceRefs); refIndex++ {
+			previous := occurrence.SourceRefs[refIndex-1]
+			current := occurrence.SourceRefs[refIndex]
+			if order.Less(current, previous) {
+				issues = append(issues, fmt.Sprintf("%s.source_refs are not in canonical order at index %d", prefix, refIndex))
+			} else if current == previous {
+				issues = append(issues, fmt.Sprintf("%s.source_refs[%d] duplicates the previous reference", prefix, refIndex))
+			}
+		}
+	}
+
+	if !sort.SliceIsSorted(value.Occurrences, func(left, right int) bool {
+		return interactionmodel.Less(order, value.Occurrences[left], value.Occurrences[right])
+	}) {
+		issues = append(issues, "occurrences are not in canonical order")
+	}
+	seen := make(map[string]int)
+	for index, occurrence := range value.Occurrences {
+		key := interactionmodel.ExactIdentity(occurrence)
+		if previous, ok := seen[key]; ok {
+			issues = append(issues, fmt.Sprintf("occurrences[%d] duplicates occurrence %d", index, previous))
+			continue
+		}
+		seen[key] = index
+	}
+	return issues
+}
+
+func Spec() pipeline.ValidatorSpec {
+	return pipeline.ValidatorSpec{Key: Key, ExecutionClass: contracts.ExecutionClassDeterministic}
+}
+
+func Register(registry *pipeline.ValidatorRegistry) error {
+	return pipeline.RegisterTypedValidatorBuilder(registry, dnd.NPCOccurrenceListKind, Spec(), validateOptions, func(request pipeline.BuildRequest) (contracts.TypedValidator[dnd.NPCOccurrenceList], error) {
+		options, err := DecodeOptions(request.Options)
+		if err != nil {
+			return nil, err
+		}
+		return New(options, request.References)
+	})
+}
+
+func DecodeOptions(options map[string]any) (Options, error) {
+	if err := pipeline.RejectUnknownOptions(options); err != nil {
+		return Options{}, err
+	}
+	return Options{}, nil
+}
+
+func validateOptions(options map[string]any) error { _, err := DecodeOptions(options); return err }