Add D&D NPC extraction and validation

internal/modules/dnd/validate/npcs/diagnostics/diagnostics.go

@@ -0,0 +1,53 @@
+// Package diagnostics provides bounded, safe text for deterministic NPC
+// validator decisions and warnings.
+package diagnostics
+
+import (
+	"fmt"
+	"strconv"
+	"strings"
+)
+
+const (
+	MaxIssues         = 20
+	MaxDisplayedRunes = 128
+	MaxMessageBytes   = 4096
+)
+
+func Truncate(value string) string {
+	runes := []rune(value)
+	if len(runes) <= MaxDisplayedRunes {
+		return value
+	}
+	return string(runes[:MaxDisplayedRunes-1]) + "…"
+}
+
+func Quote(value string) string { return strconv.Quote(Truncate(value)) }
+
+func Aggregate(prefix string, issues []string) string {
+	displayed := make([]string, 0, min(len(issues), MaxIssues))
+	for len(displayed) < len(issues) && len(displayed) < MaxIssues {
+		issue := Truncate(issues[len(displayed)])
+		candidate := aggregateMessage(prefix, append(displayed, issue), len(issues)-len(displayed)-1)
+		if len([]byte(candidate)) > MaxMessageBytes {
+			break
+		}
+		displayed = append(displayed, issue)
+	}
+	return aggregateMessage(prefix, displayed, len(issues)-len(displayed))
+}
+
+func aggregateMessage(prefix string, issues []string, omitted int) string {
+	message := prefix + ": " + strings.Join(issues, ", ")
+	if omitted > 0 {
+		message += fmt.Sprintf("; %d additional issue(s) omitted", omitted)
+	}
+	return message
+}
+
+func min(left, right int) int {
+	if left < right {
+		return left
+	}
+	return right
+}

internal/modules/dnd/validate/npcs/shape/validator.go

@@ -0,0 +1,121 @@
+package shape
+
+import (
+	"context"
+	"fmt"
+	"strings"
+
+	"gitea.maximumdirect.net/eric/notarius/internal/framework/contracts"
+	"gitea.maximumdirect.net/eric/notarius/internal/framework/pipeline"
+	"gitea.maximumdirect.net/eric/notarius/internal/modules/dnd"
+	"gitea.maximumdirect.net/eric/notarius/internal/modules/dnd/validate/npcs/diagnostics"
+)
+
+const (
+	Key        = "extract/dnd/npcs/shape"
+	ReasonCode = "invalid_npc_shape"
+	policy     = "dnd.npcs.validator.shape.v1"
+)
+
+type Options struct{}
+type Validator struct{}
+
+var _ contracts.TypedValidator[dnd.NPCList] = (*Validator)(nil)
+var _ pipeline.CheckpointFingerprintProvider = (*Validator)(nil)
+
+func New(Options) *Validator      { return &Validator{} }
+func (v *Validator) Name() string { return Key }
+func (v *Validator) ExecutionClass() contracts.ExecutionClass {
+	return contracts.ExecutionClassDeterministic
+}
+func (v *Validator) CheckpointFingerprints() []pipeline.CheckpointFingerprint {
+	return []pipeline.CheckpointFingerprint{{Name: "policy", Value: policy}}
+}
+
+func (v *Validator) Validate(_ context.Context, req contracts.TypedValidationRequest[dnd.NPCList]) (contracts.ValidationResult, error) {
+	issues := issuesFor(req.Value)
+	if len(issues) > 0 {
+		return rejection(diagnostics.Aggregate("invalid NPC shape", issues)), nil
+	}
+	return contracts.ValidationResult{Approved: true}, nil
+}
+
+func Validate(value dnd.NPCList) error {
+	issues := issuesFor(value)
+	if len(issues) == 0 {
+		return nil
+	}
+	return fmt.Errorf("%s", diagnostics.Aggregate("invalid NPC shape", issues))
+}
+
+func issuesFor(value dnd.NPCList) []string {
+	issues := make([]string, 0)
+	if value.NPCs == nil {
+		return []string{"npcs must be present"}
+	}
+	for index, npc := range value.NPCs {
+		prefix := fmt.Sprintf("npcs[%d]", index)
+		if strings.TrimSpace(npc.ID) == "" {
+			issues = append(issues, prefix+".id must not be empty")
+		}
+		if strings.TrimSpace(npc.Name) == "" {
+			issues = append(issues, prefix+".name must not be empty")
+		}
+		if npc.Aliases == nil {
+			issues = append(issues, prefix+".aliases must be present")
+		} else {
+			for aliasIndex, alias := range npc.Aliases {
+				if strings.TrimSpace(alias) == "" {
+					issues = append(issues, fmt.Sprintf("%s.aliases[%d] must not be empty: %s", prefix, aliasIndex, diagnostics.Quote(alias)))
+				}
+			}
+		}
+		if strings.TrimSpace(npc.Description) == "" {
+			issues = append(issues, prefix+".description must not be empty")
+		}
+		if npc.Relationships == nil {
+			issues = append(issues, prefix+".relationships must be present")
+		} else {
+			for relationshipIndex, relationship := range npc.Relationships {
+				relationshipPrefix := fmt.Sprintf("%s.relationships[%d]", prefix, relationshipIndex)
+				if strings.TrimSpace(relationship.Target) == "" {
+					issues = append(issues, relationshipPrefix+".target must not be empty: "+diagnostics.Quote(relationship.Target))
+				}
+				if strings.TrimSpace(relationship.Relationship) == "" {
+					issues = append(issues, relationshipPrefix+".relationship must not be empty: "+diagnostics.Quote(relationship.Relationship))
+				}
+			}
+		}
+		if len(npc.SourceRefs) == 0 {
+			issues = append(issues, prefix+".source_refs must not be empty")
+		}
+	}
+	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.NPCListKind, Spec(), validateOptions, func(request pipeline.BuildRequest) (contracts.TypedValidator[dnd.NPCList], error) {
+		options, err := DecodeOptions(request.Options)
+		if err != nil {
+			return nil, err
+		}
+		return New(options), nil
+	})
+}
+
+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 }
+
+func rejection(message string) contracts.ValidationResult {
+	return contracts.ValidationResult{Approved: false, ReasonCode: ReasonCode, Message: message}
+}

internal/modules/dnd/validate/npcs/shape/validator_test.go

@@ -0,0 +1,92 @@
+package shape
+
+import (
+	"context"
+	"strings"
+	"testing"
+	"unicode/utf8"
+
+	"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"
+)
+
+func TestValidatorApprovesWellFormedNPCPayload(t *testing.T) {
+	result, err := New(Options{}).Validate(context.Background(), requestWithValue(validNPCList()))
+	if err != nil || !result.Approved {
+		t.Fatalf("Validate() = %#v, %v; want approval", result, err)
+	}
+}
+
+func TestValidatorRejectsRequiredShapeValues(t *testing.T) {
+	value := validNPCList()
+	value.NPCs[0].Aliases = nil
+	result, err := New(Options{}).Validate(context.Background(), requestWithValue(value))
+	if err != nil || result.Approved || result.ReasonCode != ReasonCode || !strings.Contains(result.Message, "aliases must be present") {
+		t.Fatalf("Validate() = %#v, %v; want bounded shape rejection", result, err)
+	}
+
+	missing := dnd.NPCList{}
+	result, err = New(Options{}).Validate(context.Background(), requestWithValue(missing))
+	if err != nil || result.Approved || result.ReasonCode != ReasonCode {
+		t.Fatalf("missing Validate() = %#v, %v; want shape rejection", result, err)
+	}
+}
+
+func TestValidatorBoundsDiagnosticsAndQuotesUnicode(t *testing.T) {
+	value := dnd.NPCList{NPCs: make([]dnd.NPC, 24)}
+	long := strings.Repeat("火", 220) + "\n\t"
+	for index := range value.NPCs {
+		value.NPCs[index] = dnd.NPC{ID: "candidate", Name: long, Aliases: []string{"\n\t"}, Description: "", Relationships: []dnd.NPCRelationship{{Target: " ", Relationship: " "}}, SourceRefs: []source.SourceRef{}}
+	}
+	result, err := New(Options{}).Validate(context.Background(), requestWithValue(value))
+	if err != nil || result.Approved || len([]byte(result.Message)) > diagnosticsMaxMessageBytes || !utf8.ValidString(result.Message) {
+		t.Fatalf("Validate() = %#v, %v; want bounded valid UTF-8 rejection", result, err)
+	}
+	if strings.Count(result.Message, "npcs[") > diagnosticsMaxIssues || !strings.Contains(result.Message, "additional issue(s) omitted") || !strings.Contains(result.Message, `\n\t`) {
+		t.Fatalf("message = %q, want bounded quoted diagnostics", result.Message)
+	}
+}
+
+func TestValidatorSpecCheckpointAndRegistration(t *testing.T) {
+	if got := New(Options{}).CheckpointFingerprints(); len(got) != 1 || got[0].Name != "policy" || got[0].Value != "dnd.npcs.validator.shape.v1" {
+		t.Fatalf("CheckpointFingerprints() = %#v, want local policy", got)
+	}
+	if spec := Spec(); spec.Key != Key || spec.ExecutionClass != contracts.ExecutionClassDeterministic {
+		t.Fatalf("Spec() = %#v, want deterministic shape validator", spec)
+	}
+	registry := pipeline.NewValidatorRegistry()
+	if err := Register(registry); err != nil {
+		t.Fatalf("Register() error = %v", err)
+	}
+	if _, err := DecodeOptions(map[string]any{"unexpected": true}); err == nil {
+		t.Fatal("DecodeOptions() accepted unknown option")
+	}
+}
+
+func TestValidatorDoesNotMutateValue(t *testing.T) {
+	value := validNPCList()
+	before := value
+	_, err := New(Options{}).Validate(context.Background(), requestWithValue(value))
+	if err != nil || value.NPCs[0].Aliases[0] != before.NPCs[0].Aliases[0] {
+		t.Fatalf("Validate() mutated value: %#v", value)
+	}
+}
+
+func requestWithValue(value dnd.NPCList) contracts.TypedValidationRequest[dnd.NPCList] {
+	return contracts.TypedValidationRequest[dnd.NPCList]{Value: value}
+}
+
+func validNPCList() dnd.NPCList {
+	return dnd.NPCList{NPCs: []dnd.NPC{{
+		ID: "candidate", Name: "Mira Thorn", Aliases: []string{"The Greencloak"}, Description: "A guarded ranger.",
+		Relationships: []dnd.NPCRelationship{{Target: "Captain Vale", Relationship: "reports to"}},
+		SourceRefs:    []source.SourceRef{{SourceID: "session", StartUnitID: 1, EndUnitID: 1}},
+	}}}
+}
+
+const (
+	diagnosticsMaxIssues       = 20
+	diagnosticsMaxMessageBytes = 4096
+)

internal/modules/dnd/validate/npcs/source_refs/validator.go

@@ -0,0 +1,79 @@
+package sourcerefs
+
+import (
+	"context"
+	"fmt"
+
+	"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"
+	"gitea.maximumdirect.net/eric/notarius/internal/modules/dnd/validate/npcs/diagnostics"
+	npcshape "gitea.maximumdirect.net/eric/notarius/internal/modules/dnd/validate/npcs/shape"
+)
+
+const (
+	Key        = "extract/dnd/npcs/source_refs"
+	ReasonCode = "invalid_npc_source_refs"
+	policy     = "dnd.npcs.validator.source_refs.v1"
+)
+
+type Options struct{}
+type Validator struct{}
+
+var _ contracts.TypedValidator[dnd.NPCList] = (*Validator)(nil)
+var _ pipeline.CheckpointFingerprintProvider = (*Validator)(nil)
+
+func New(Options) *Validator      { return &Validator{} }
+func (v *Validator) Name() string { return Key }
+func (v *Validator) ExecutionClass() contracts.ExecutionClass {
+	return contracts.ExecutionClassDeterministic
+}
+func (v *Validator) CheckpointFingerprints() []pipeline.CheckpointFingerprint {
+	return []pipeline.CheckpointFingerprint{{Name: "policy", Value: policy}}
+}
+
+func (v *Validator) Validate(_ context.Context, req contracts.TypedValidationRequest[dnd.NPCList]) (contracts.ValidationResult, error) {
+	if err := npcshape.Validate(req.Value); err != nil {
+		return contracts.ValidationResult{Approved: true}, nil
+	}
+	issues := make([]string, 0)
+	for npcIndex, npc := range req.Value.NPCs {
+		for refIndex, ref := range npc.SourceRefs {
+			if err := source.ValidateRef(req.Source, ref); err != nil {
+				issues = append(issues, fmt.Sprintf("npcs[%d].source_refs[%d]: %s", npcIndex, refIndex, diagnostics.Truncate(err.Error())))
+			}
+		}
+	}
+	if len(issues) == 0 {
+		return contracts.ValidationResult{Approved: true}, nil
+	}
+	return rejection(diagnostics.Aggregate("invalid NPC source references", issues)), nil
+}
+
+func Spec() pipeline.ValidatorSpec {
+	return pipeline.ValidatorSpec{Key: Key, ExecutionClass: contracts.ExecutionClassDeterministic}
+}
+
+func Register(registry *pipeline.ValidatorRegistry) error {
+	return pipeline.RegisterTypedValidatorBuilder(registry, dnd.NPCListKind, Spec(), validateOptions, func(request pipeline.BuildRequest) (contracts.TypedValidator[dnd.NPCList], error) {
+		options, err := DecodeOptions(request.Options)
+		if err != nil {
+			return nil, err
+		}
+		return New(options), nil
+	})
+}
+
+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 }
+
+func rejection(message string) contracts.ValidationResult {
+	return contracts.ValidationResult{Approved: false, ReasonCode: ReasonCode, Message: message}
+}

internal/modules/dnd/validate/npcs/source_refs/validator_test.go

@@ -0,0 +1,88 @@
+package sourcerefs
+
+import (
+	"context"
+	"fmt"
+	"strings"
+	"testing"
+	"unicode/utf8"
+
+	"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"
+)
+
+func TestValidatorApprovesValidSourceReferences(t *testing.T) {
+	result, err := New(Options{}).Validate(context.Background(), requestWithValue(validDocument(), validNPCList()))
+	if err != nil || !result.Approved || len(result.Warnings) != 0 {
+		t.Fatalf("Validate() = %#v, %v; want approval", result, err)
+	}
+}
+
+func TestValidatorRejectsInvalidSourceReferences(t *testing.T) {
+	value := validNPCList()
+	value.NPCs[0].SourceRefs = []source.SourceRef{
+		{SourceID: "foreign", StartUnitID: 1, EndUnitID: 1},
+		{SourceID: "session", StartUnitID: 2, EndUnitID: 1},
+		{SourceID: "session", StartUnitID: 99, EndUnitID: 99},
+	}
+	result, err := New(Options{}).Validate(context.Background(), requestWithValue(validDocument(), value))
+	if err != nil || result.Approved || result.ReasonCode != ReasonCode || !strings.Contains(result.Message, "npcs[0].source_refs[0]") {
+		t.Fatalf("Validate() = %#v, %v; want source-reference rejection", result, err)
+	}
+}
+
+func TestValidatorDefersMalformedShape(t *testing.T) {
+	value := dnd.NPCList{NPCs: []dnd.NPC{{Name: "Mira Thorn"}}}
+	result, err := New(Options{}).Validate(context.Background(), requestWithValue(validDocument(), value))
+	if err != nil || !result.Approved || result.ReasonCode != "" || result.Message != "" {
+		t.Fatalf("Validate() = %#v, %v; want shape deferral", result, err)
+	}
+}
+
+func TestValidatorBoundsDiagnosticsAndHandlesMissingDocument(t *testing.T) {
+	value := validNPCList()
+	value.NPCs[0].SourceRefs = make([]source.SourceRef, 24)
+	for index := range value.NPCs[0].SourceRefs {
+		value.NPCs[0].SourceRefs[index] = source.SourceRef{SourceID: strings.Repeat("火", 220) + "\n\t", StartUnitID: index + 1, EndUnitID: index + 1}
+	}
+	result, err := New(Options{}).Validate(context.Background(), requestWithValue(nil, value))
+	if err != nil || result.Approved || len([]byte(result.Message)) > 4096 || !utf8.ValidString(result.Message) {
+		t.Fatalf("Validate() = %#v, %v; want bounded missing-document rejection", result, err)
+	}
+	if !strings.Contains(result.Message, "additional issue(s) omitted") || !strings.Contains(result.Message, fmt.Sprintf("npcs[0].source_refs[%d]", 19)) {
+		t.Fatalf("message = %q, want bounded aggregate diagnostics", result.Message)
+	}
+}
+
+func TestValidatorSpecCheckpointAndRegistration(t *testing.T) {
+	if got := New(Options{}).CheckpointFingerprints(); len(got) != 1 || got[0].Name != "policy" || got[0].Value != "dnd.npcs.validator.source_refs.v1" {
+		t.Fatalf("CheckpointFingerprints() = %#v, want local policy", got)
+	}
+	if Spec().ExecutionClass != contracts.ExecutionClassDeterministic {
+		t.Fatalf("Spec() = %#v, want deterministic validator", Spec())
+	}
+	registry := pipeline.NewValidatorRegistry()
+	if err := Register(registry); err != nil {
+		t.Fatalf("Register() error = %v", err)
+	}
+	if _, err := DecodeOptions(map[string]any{"unexpected": true}); err == nil {
+		t.Fatal("DecodeOptions() accepted unknown option")
+	}
+}
+
+func requestWithValue(doc *source.SourceDocument, value dnd.NPCList) contracts.TypedValidationRequest[dnd.NPCList] {
+	return contracts.TypedValidationRequest[dnd.NPCList]{Source: doc, Value: value}
+}
+
+func validDocument() *source.SourceDocument {
+	return &source.SourceDocument{ID: "session", Kind: "transcript", Format: "application/json", Digest: "sha256:session", Units: []source.SourceUnit{
+		{ID: 1, Kind: "message", Text: "Mira Thorn enters."},
+		{ID: 2, Kind: "message", Text: "The ranger watches."},
+	}}
+}
+
+func validNPCList() dnd.NPCList {
+	return dnd.NPCList{NPCs: []dnd.NPC{{ID: "candidate", Name: "Mira Thorn", Aliases: []string{"The Greencloak"}, Description: "A ranger.", Relationships: []dnd.NPCRelationship{}, SourceRefs: []source.SourceRef{{SourceID: "session", StartUnitID: 1, EndUnitID: 2}}}}}
+}

internal/modules/dnd/validate/npcs/source_relatedness/validator.go

@@ -0,0 +1,114 @@
+package sourcerelatedness
+
+import (
+	"context"
+	"fmt"
+	"strings"
+
+	"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"
+	"gitea.maximumdirect.net/eric/notarius/internal/modules/dnd/npcs/identity"
+	"gitea.maximumdirect.net/eric/notarius/internal/modules/dnd/validate/npcs/diagnostics"
+	npcshape "gitea.maximumdirect.net/eric/notarius/internal/modules/dnd/validate/npcs/shape"
+)
+
+const (
+	Key               = "extract/dnd/npcs/source_relatedness"
+	WarningReasonCode = "npc_not_near_source"
+	policy            = "dnd.npcs.validator.source_relatedness.v1"
+)
+
+type Options struct{}
+type Validator struct{}
+
+var _ contracts.TypedValidator[dnd.NPCList] = (*Validator)(nil)
+var _ pipeline.CheckpointFingerprintProvider = (*Validator)(nil)
+
+func New(Options) *Validator      { return &Validator{} }
+func (v *Validator) Name() string { return Key }
+func (v *Validator) ExecutionClass() contracts.ExecutionClass {
+	return contracts.ExecutionClassDeterministic
+}
+func (v *Validator) CheckpointFingerprints() []pipeline.CheckpointFingerprint {
+	return []pipeline.CheckpointFingerprint{{Name: "policy", Value: policy}}
+}
+
+func (v *Validator) Validate(_ context.Context, req contracts.TypedValidationRequest[dnd.NPCList]) (contracts.ValidationResult, error) {
+	if err := npcshape.Validate(req.Value); err != nil {
+		return contracts.ValidationResult{Approved: true}, nil
+	}
+	var warnings []contracts.Warning
+	for npcIndex, npc := range req.Value.NPCs {
+		if npcAppearsInCitedText(req.Source, npc) {
+			continue
+		}
+		warnings = append(warnings, contracts.Warning{
+			Scope:      fmt.Sprintf("npcs[%d]", npcIndex),
+			ReasonCode: WarningReasonCode,
+			Message:    fmt.Sprintf("NPC %s was not found in cited source text", diagnostics.Quote(npc.Name)),
+		})
+	}
+	return contracts.ValidationResult{Approved: true, Warnings: warnings}, nil
+}
+
+func npcAppearsInCitedText(doc *source.SourceDocument, npc dnd.NPC) bool {
+	cited := citedTextKey(doc, npc.SourceRefs)
+	if cited == "" {
+		return false
+	}
+	if strings.Contains(cited, identity.ComparisonKey(npc.Name)) {
+		return true
+	}
+	for _, alias := range npc.Aliases {
+		if strings.Contains(cited, identity.ComparisonKey(alias)) {
+			return true
+		}
+	}
+	return false
+}
+
+func citedTextKey(doc *source.SourceDocument, refs []source.SourceRef) string {
+	if doc == nil {
+		return ""
+	}
+	var builder strings.Builder
+	for _, ref := range refs {
+		if err := source.ValidateRef(doc, ref); err != nil {
+			continue
+		}
+		start, _ := source.UnitIndex(doc, ref.StartUnitID)
+		end, _ := source.UnitIndex(doc, ref.EndUnitID)
+		for index := start; index <= end; index++ {
+			if builder.Len() > 0 {
+				builder.WriteByte(' ')
+			}
+			builder.WriteString(doc.Units[index].Text)
+		}
+	}
+	return identity.ComparisonKey(builder.String())
+}
+
+func Spec() pipeline.ValidatorSpec {
+	return pipeline.ValidatorSpec{Key: Key, ExecutionClass: contracts.ExecutionClassDeterministic}
+}
+
+func Register(registry *pipeline.ValidatorRegistry) error {
+	return pipeline.RegisterTypedValidatorBuilder(registry, dnd.NPCListKind, Spec(), validateOptions, func(request pipeline.BuildRequest) (contracts.TypedValidator[dnd.NPCList], error) {
+		options, err := DecodeOptions(request.Options)
+		if err != nil {
+			return nil, err
+		}
+		return New(options), nil
+	})
+}
+
+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 }

internal/modules/dnd/validate/npcs/source_relatedness/validator_test.go

@@ -0,0 +1,81 @@
+package sourcerelatedness
+
+import (
+	"context"
+	"strings"
+	"testing"
+	"unicode/utf8"
+
+	"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"
+)
+
+func TestValidatorMatchesCanonicalNamesAndAliasesWithUnicodeVariants(t *testing.T) {
+	value := dnd.NPCList{NPCs: []dnd.NPC{
+		{ID: "one", Name: "O'Rin Thorn", Aliases: []string{}, Description: "A ranger.", Relationships: []dnd.NPCRelationship{}, SourceRefs: []source.SourceRef{{SourceID: "session", StartUnitID: 1, EndUnitID: 1}}},
+		{ID: "two", Name: "Missing Name", Aliases: []string{"The Greencloak"}, Description: "A guard.", Relationships: []dnd.NPCRelationship{}, SourceRefs: []source.SourceRef{{SourceID: "session", StartUnitID: 2, EndUnitID: 2}}},
+	}}
+	doc := &source.SourceDocument{ID: "session", Kind: "transcript", Format: "application/json", Digest: "sha256:session", Units: []source.SourceUnit{
+		{ID: 1, Kind: "message", Text: "  o’rin\u2003thorn appears."},
+		{ID: 2, Kind: "message", Text: "The greencloak watches."},
+	}}
+	result, err := New(Options{}).Validate(context.Background(), contracts.TypedValidationRequest[dnd.NPCList]{Source: doc, Value: value})
+	if err != nil || !result.Approved || len(result.Warnings) != 0 {
+		t.Fatalf("Validate() = %#v, %v; want alias/canonical relatedness approval", result, err)
+	}
+}
+
+func TestValidatorWarnsAtMostOncePerNPCForUnrelatedCitations(t *testing.T) {
+	value := dnd.NPCList{NPCs: []dnd.NPC{
+		{ID: "one", Name: "Missing\nName", Aliases: []string{"Also Missing"}, Description: "A guard.", Relationships: []dnd.NPCRelationship{}, SourceRefs: []source.SourceRef{{SourceID: "session", StartUnitID: 1, EndUnitID: 1}, {SourceID: "session", StartUnitID: 1, EndUnitID: 1}}},
+	}}
+	result, err := New(Options{}).Validate(context.Background(), contracts.TypedValidationRequest[dnd.NPCList]{Source: relatednessDocument(), Value: value})
+	if err != nil || !result.Approved || len(result.Warnings) != 1 {
+		t.Fatalf("Validate() = %#v, %v; want one warning", result, err)
+	}
+	warning := result.Warnings[0]
+	if warning.Scope != "npcs[0]" || warning.ReasonCode != WarningReasonCode || !strings.Contains(warning.Message, `Missing\nName`) || strings.Contains(warning.Message, "Missing\nName") || !utf8.ValidString(warning.Message) {
+		t.Fatalf("warning = %#v, want safely quoted bounded warning", warning)
+	}
+}
+
+func TestValidatorDefersMalformedShapeAndInvalidRangesDoNotPanic(t *testing.T) {
+	invalidShape := dnd.NPCList{NPCs: []dnd.NPC{{Name: "Mira Thorn"}}}
+	result, err := New(Options{}).Validate(context.Background(), contracts.TypedValidationRequest[dnd.NPCList]{Source: relatednessDocument(), Value: invalidShape})
+	if err != nil || !result.Approved || len(result.Warnings) != 0 {
+		t.Fatalf("shape deferral = %#v, %v; want approval without warning", result, err)
+	}
+	invalidRange := dnd.NPCList{NPCs: []dnd.NPC{{ID: "one", Name: "Mira Thorn", Aliases: []string{}, Description: "A ranger.", Relationships: []dnd.NPCRelationship{}, SourceRefs: []source.SourceRef{{SourceID: "session", StartUnitID: 99, EndUnitID: 99}}}}}
+	result, err = New(Options{}).Validate(context.Background(), contracts.TypedValidationRequest[dnd.NPCList]{Source: relatednessDocument(), Value: invalidRange})
+	if err != nil || !result.Approved || len(result.Warnings) != 1 || result.Warnings[0].ReasonCode != WarningReasonCode {
+		t.Fatalf("invalid-range relatedness = %#v, %v; want one warning", result, err)
+	}
+}
+
+func TestValidatorUsesOnlyTranscriptEvidenceAndRegistersPolicy(t *testing.T) {
+	value := dnd.NPCList{NPCs: []dnd.NPC{{ID: "one", Name: "Opaque NPC", Aliases: []string{}, Description: "A guard.", Relationships: []dnd.NPCRelationship{}, SourceRefs: []source.SourceRef{{SourceID: "session", StartUnitID: 1, EndUnitID: 1}}}}}
+	references := contracts.ReferenceSet{Slots: map[string]contracts.ResolvedReferenceSlot{"glossary": {Items: []contracts.ReferenceItem{{Content: []byte("Opaque NPC")}}}}}
+	result, err := New(Options{}).Validate(context.Background(), contracts.TypedValidationRequest[dnd.NPCList]{Source: relatednessDocument(), References: references, Value: value})
+	if err != nil || len(result.Warnings) != 1 {
+		t.Fatalf("reference-only relatedness = %#v, %v; want warning", result, err)
+	}
+	if got := New(Options{}).CheckpointFingerprints(); len(got) != 1 || got[0].Name != "policy" || got[0].Value != "dnd.npcs.validator.source_relatedness.v1" {
+		t.Fatalf("CheckpointFingerprints() = %#v, want local policy", got)
+	}
+	if Spec().ExecutionClass != contracts.ExecutionClassDeterministic {
+		t.Fatalf("Spec() = %#v, want deterministic validator", Spec())
+	}
+	registry := pipeline.NewValidatorRegistry()
+	if err := Register(registry); err != nil {
+		t.Fatalf("Register() error = %v", err)
+	}
+	if _, err := DecodeOptions(map[string]any{"unexpected": true}); err == nil {
+		t.Fatal("DecodeOptions() accepted unknown option")
+	}
+}
+
+func relatednessDocument() *source.SourceDocument {
+	return &source.SourceDocument{ID: "session", Kind: "transcript", Format: "application/json", Digest: "sha256:session", Units: []source.SourceUnit{{ID: 1, Kind: "message", Text: "The party waits."}}}
+}