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 }

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

@@ -0,0 +1,169 @@
+package invariants
+
+import (
+	"context"
+	"encoding/json"
+	"reflect"
+	"strings"
+	"testing"
+
+	"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"
+	npccodec "gitea.maximumdirect.net/eric/notarius/internal/modules/dnd/codec/npcregistry"
+	"gitea.maximumdirect.net/eric/notarius/internal/modules/dnd/npcs/identity"
+	npcregistry "gitea.maximumdirect.net/eric/notarius/internal/modules/dnd/npcs/registry"
+)
+
+func TestValidatorApprovesCanonicalNormalizedOccurrences(t *testing.T) {
+	references := registryReferences(t, "Aria", "Borin")
+	result, err := newValidator(t, references).Validate(context.Background(), request(references, normalizedList()))
+	if err != nil || !result.Approved {
+		t.Fatalf("Validate() = %#v, %v", result, err)
+	}
+}
+
+func TestValidatorRejectsOwnedCanonicalNameReferenceOrderListOrderAndDuplicates(t *testing.T) {
+	references := registryReferences(t, "Aria", "Borin")
+	for _, test := range []struct {
+		name   string
+		mutate func(*dnd.NPCOccurrenceList)
+		want   string
+	}{
+		{"mismatched name", func(value *dnd.NPCOccurrenceList) { value.Occurrences[0].Name = " aria " }, "does not match npc_id"},
+		{"reference order", func(value *dnd.NPCOccurrenceList) {
+			value.Occurrences[0].SourceRefs = []source.SourceRef{{SourceID: "session", StartUnitID: 20, EndUnitID: 20}, {SourceID: "session", StartUnitID: 10, EndUnitID: 10}}
+		}, "not in canonical order"},
+		{"duplicate reference", func(value *dnd.NPCOccurrenceList) {
+			value.Occurrences[0].SourceRefs = append(value.Occurrences[0].SourceRefs, value.Occurrences[0].SourceRefs[0])
+		}, "duplicates the previous reference"},
+		{"list order", func(value *dnd.NPCOccurrenceList) {
+			value.Occurrences[0], value.Occurrences[1] = value.Occurrences[1], value.Occurrences[0]
+		}, "occurrences are not in canonical order"},
+		{"NPC ID tie breaker", func(value *dnd.NPCOccurrenceList) {
+			value.Occurrences[0] = dnd.NPCOccurrence{NPCID: identity.DeriveID("Aria"), Name: "Aria", Kind: dnd.NPCOccurrenceKindDialogue, SourceRefs: []source.SourceRef{{SourceID: "session", StartUnitID: 10, EndUnitID: 10}}}
+			value.Occurrences[1] = dnd.NPCOccurrence{NPCID: identity.DeriveID("Borin"), Name: "Borin", Kind: dnd.NPCOccurrenceKindDialogue, SourceRefs: []source.SourceRef{{SourceID: "session", StartUnitID: 10, EndUnitID: 10}}}
+		}, "occurrences are not in canonical order"},
+		{"duplicate record", func(value *dnd.NPCOccurrenceList) {
+			value.Occurrences = append(value.Occurrences, value.Occurrences[0])
+		}, "duplicates occurrence"},
+	} {
+		t.Run(test.name, func(t *testing.T) {
+			value := normalizedList()
+			test.mutate(&value)
+			result, err := newValidator(t, references).Validate(context.Background(), request(references, value))
+			if err != nil || result.Approved || result.ReasonCode != ReasonCode || !strings.Contains(result.Message, test.want) {
+				t.Fatalf("Validate() = %#v, %v; want %q", result, err, test.want)
+			}
+		})
+	}
+}
+
+func TestValidatorAcceptsValidEvidenceBeforeInvalidEvidence(t *testing.T) {
+	references := registryReferences(t, "Aria", "Borin")
+	value := dnd.NPCOccurrenceList{Occurrences: []dnd.NPCOccurrence{
+		{NPCID: "npc:test", Name: "Borin", Kind: dnd.NPCOccurrenceKindMentioned, SourceRefs: []source.SourceRef{{SourceID: "session", StartUnitID: 20, EndUnitID: 20}}},
+		{NPCID: "npc:test", Name: "Aria", Kind: dnd.NPCOccurrenceKindDialogue, SourceRefs: []source.SourceRef{{SourceID: "session", StartUnitID: 99, EndUnitID: 99}}},
+	}}
+	result, err := newValidator(t, references).Validate(context.Background(), request(references, value))
+	if err != nil || !result.Approved {
+		t.Fatalf("Validate() = %#v, %v", result, err)
+	}
+}
+
+func TestValidatorDefersShapeAndSourceReferenceFailuresAndRequiresRegistry(t *testing.T) {
+	references := registryReferences(t, "Aria", "Borin")
+	for _, value := range []dnd.NPCOccurrenceList{
+		{Occurrences: []dnd.NPCOccurrence{{NPCID: "npc:test", Name: "Aria"}}},
+		{Occurrences: []dnd.NPCOccurrence{{NPCID: "npc:test", Name: "Aria", Kind: dnd.NPCOccurrenceKindDialogue, SourceRefs: []source.SourceRef{{SourceID: "session", StartUnitID: 99, EndUnitID: 99}}}}},
+	} {
+		result, err := newValidator(t, references).Validate(context.Background(), request(references, value))
+		if err != nil || !result.Approved {
+			t.Fatalf("deferral = %#v, %v", result, err)
+		}
+	}
+	result, err := newValidator(t).Validate(context.Background(), request(contracts.ReferenceSet{}, normalizedList()))
+	if err != nil || result.Approved || result.ReasonCode != ReasonCode || !strings.Contains(result.Message, "required") {
+		t.Fatalf("unbound registry = %#v, %v", result, err)
+	}
+}
+
+func TestValidatorResolvesGeneratedRegistryAndKeepsMetadataAndInputsImmutable(t *testing.T) {
+	references := registryReferences(t, "Aria", "Borin")
+	validator := newValidator(t)
+	value := normalizedList()
+	before := cloneList(value)
+	result, err := validator.Validate(context.Background(), request(references, value))
+	if err != nil || !result.Approved || !reflect.DeepEqual(value, before) {
+		t.Fatalf("generated validation = %#v, %v; value=%#v", result, err, value)
+	}
+	metadata, err := json.Marshal(newValidator(t, references).ManifestMetadata())
+	if err != nil {
+		t.Fatal(err)
+	}
+	if strings.Contains(string(metadata), "Aria") || strings.Contains(string(metadata), "other-session") {
+		t.Fatalf("metadata leaked registry content: %s", metadata)
+	}
+	if got := newValidator(t, references).CheckpointFingerprints(); len(got) != 2 || got[0].Value != policy || !strings.HasPrefix(got[1].Value, "sha256:") {
+		t.Fatalf("CheckpointFingerprints() = %#v", got)
+	}
+	registry := pipeline.NewValidatorRegistry()
+	if err := Register(registry); err != nil {
+		t.Fatal(err)
+	}
+	if _, err := DecodeOptions(map[string]any{"unexpected": true}); err == nil {
+		t.Fatal("DecodeOptions() accepted unknown option")
+	}
+}
+
+func newValidator(t *testing.T, references ...contracts.ReferenceSet) *Validator {
+	t.Helper()
+	validator, err := New(Options{}, references...)
+	if err != nil {
+		t.Fatal(err)
+	}
+	return validator
+}
+
+func request(references contracts.ReferenceSet, value dnd.NPCOccurrenceList) contracts.TypedValidationRequest[dnd.NPCOccurrenceList] {
+	return contracts.TypedValidationRequest[dnd.NPCOccurrenceList]{Source: document(), References: references, Value: value}
+}
+
+func document() *source.SourceDocument {
+	return &source.SourceDocument{ID: "session", Units: []source.SourceUnit{{ID: 10}, {ID: 20}}}
+}
+
+func normalizedList() dnd.NPCOccurrenceList {
+	return dnd.NPCOccurrenceList{Occurrences: []dnd.NPCOccurrence{
+		{NPCID: identity.DeriveID("Aria"), Name: "Aria", Kind: dnd.NPCOccurrenceKindDialogue, SourceRefs: []source.SourceRef{{SourceID: "session", StartUnitID: 10, EndUnitID: 10}}},
+		{NPCID: identity.DeriveID("Borin"), Name: "Borin", Kind: dnd.NPCOccurrenceKindMentioned, SourceRefs: []source.SourceRef{{SourceID: "session", StartUnitID: 20, EndUnitID: 20}}},
+	}}
+}
+
+func cloneList(value dnd.NPCOccurrenceList) dnd.NPCOccurrenceList {
+	copyValue := dnd.NPCOccurrenceList{Occurrences: make([]dnd.NPCOccurrence, len(value.Occurrences))}
+	for index, occurrence := range value.Occurrences {
+		copyValue.Occurrences[index] = occurrence
+		copyValue.Occurrences[index].SourceRefs = append([]source.SourceRef(nil), occurrence.SourceRefs...)
+	}
+	return copyValue
+}
+
+func registryReferences(t *testing.T, names ...string) contracts.ReferenceSet {
+	t.Helper()
+	npcs := make([]dnd.NPC, len(names))
+	for index, name := range names {
+		npcs[index] = dnd.NPC{ID: identity.DeriveID(name), Name: name, SourceRefs: []source.SourceRef{{SourceID: "other-session", StartUnitID: index + 1, EndUnitID: index + 1}}}
+	}
+	content, err := npccodec.New().Encode(dnd.NPCRegistry{NPCs: npcs})
+	if err != nil {
+		t.Fatal(err)
+	}
+	return contracts.ReferenceSet{Slots: map[string]contracts.ResolvedReferenceSlot{
+		npcregistry.ReferenceSlot: {
+			Slot:  contracts.ReferenceSlot{Name: npcregistry.ReferenceSlot},
+			Items: []contracts.ReferenceItem{{SlotName: npcregistry.ReferenceSlot, MediaType: npccodec.MediaType, Content: content, Origin: contracts.ReferenceOrigin{Type: "generated"}}},
+		},
+	}}
+}

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

@@ -0,0 +1,135 @@
+// Package registry validates D&D NPC occurrence names against NPC grounding.
+package registry
+
+import (
+	"context"
+	"fmt"
+
+	"gitea.maximumdirect.net/eric/notarius/internal/framework/contracts"
+	"gitea.maximumdirect.net/eric/notarius/internal/framework/pipeline"
+	"gitea.maximumdirect.net/eric/notarius/internal/modules/dnd"
+	npcregistry "gitea.maximumdirect.net/eric/notarius/internal/modules/dnd/npcs/registry"
+	"gitea.maximumdirect.net/eric/notarius/internal/modules/dnd/shared/diagnostics"
+	occurrenceshape "gitea.maximumdirect.net/eric/notarius/internal/modules/dnd/validate/npcoccurrences/shape"
+)
+
+const (
+	Key        = "extract/dnd/npc-occurrences/registry"
+	ReasonCode = "invalid_npc_interaction_registry"
+	policy     = "dnd.npc_occurrences.validator.registry.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 registry 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
+	}
+	if v == nil || v.npcResolver == nil {
+		return contracts.ValidationResult{}, fmt.Errorf("NPC occurrence registry 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 rejection([]string{"NPC registry reference is required"}), nil
+	}
+	issues := make([]string, 0)
+	for index, occurrence := range req.Value.Occurrences {
+		canonical, ok := npcRegistry.LookupID(occurrence.NPCID)
+		if !ok {
+			issues = append(issues, fmt.Sprintf("occurrences[%d].npc_id is not in the NPC registry: %s", index, diagnostics.Quote(occurrence.NPCID)))
+			continue
+		}
+		if occurrence.Name != canonical.Name {
+			issues = append(issues, fmt.Sprintf("occurrences[%d].name does not match npc_id: %s", index, diagnostics.Quote(occurrence.Name)))
+		}
+	}
+	if len(issues) == 0 {
+		return contracts.ValidationResult{Approved: true}, nil
+	}
+	return rejection(issues), nil
+}
+
+func rejection(issues []string) contracts.ValidationResult {
+	return contracts.ValidationResult{
+		Approved:   false,
+		ReasonCode: ReasonCode,
+		Message:    diagnostics.Aggregate("invalid NPC occurrence registry", 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 }

internal/modules/dnd/validate/npcoccurrences/registry/validator_test.go

@@ -0,0 +1,143 @@
+package registry
+
+import (
+	"context"
+	"encoding/json"
+	"reflect"
+	"strings"
+	"testing"
+
+	"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"
+	npccodec "gitea.maximumdirect.net/eric/notarius/internal/modules/dnd/codec/npcregistry"
+	"gitea.maximumdirect.net/eric/notarius/internal/modules/dnd/npcs/identity"
+	npcregistry "gitea.maximumdirect.net/eric/notarius/internal/modules/dnd/npcs/registry"
+)
+
+func TestValidatorRecognizesExactRegistryPairsAndRejectsUnknownIDs(t *testing.T) {
+	references := registryReferences(t, "Mira Thorn")
+	validator := newValidator(t, references)
+	value := validList("Mira Thorn")
+	result, err := validator.Validate(context.Background(), request(references, value))
+	if err != nil || !result.Approved {
+		t.Fatalf("recognized result = %#v, %v", result, err)
+	}
+	value.Occurrences[0].NPCID = "npc:unknown"
+	result, err = validator.Validate(context.Background(), request(references, value))
+	if err != nil || result.Approved || result.ReasonCode != ReasonCode || !strings.Contains(result.Message, "occurrences[0].npc_id") {
+		t.Fatalf("unknown result = %#v, %v", result, err)
+	}
+	value = validList("Mira Thorn")
+	value.Occurrences[0].Name = "Hooded Guard"
+	result, err = validator.Validate(context.Background(), request(references, value))
+	if err != nil || result.Approved || result.ReasonCode != ReasonCode || !strings.Contains(result.Message, "does not match npc_id") {
+		t.Fatalf("mismatched result = %#v, %v", result, err)
+	}
+}
+
+func TestValidatorRequiresRegistryAndResolvesGeneratedReferenceAtOperationTime(t *testing.T) {
+	validator := newValidator(t)
+	value := validList("Mira Thorn")
+	result, err := validator.Validate(context.Background(), request(contracts.ReferenceSet{}, value))
+	if err != nil || result.Approved || result.ReasonCode != ReasonCode || !strings.Contains(result.Message, "required") {
+		t.Fatalf("unbound result = %#v, %v", result, err)
+	}
+	references := registryReferences(t, "Mira Thorn")
+	result, err = validator.Validate(context.Background(), request(references, value))
+	if err != nil || !result.Approved {
+		t.Fatalf("generated result = %#v, %v", result, err)
+	}
+
+	empty := registryReferences(t)
+	result, err = newValidator(t, empty).Validate(context.Background(), request(empty, dnd.NPCOccurrenceList{Occurrences: []dnd.NPCOccurrence{}}))
+	if err != nil || !result.Approved {
+		t.Fatalf("empty registry result = %#v, %v", result, err)
+	}
+}
+
+func TestValidatorRejectsMalformedRegistryWithoutContentAndKeepsMetadataSafe(t *testing.T) {
+	malformed := contracts.ReferenceSet{Slots: map[string]contracts.ResolvedReferenceSlot{
+		npcregistry.ReferenceSlot: {
+			Slot:  contracts.ReferenceSlot{Name: npcregistry.ReferenceSlot},
+			Items: []contracts.ReferenceItem{{SlotName: npcregistry.ReferenceSlot, MediaType: "application/json", Content: []byte(`{"secret":"private source"}`)}},
+		},
+	}}
+	if _, err := New(Options{}, malformed); err == nil || strings.Contains(err.Error(), "private source") {
+		t.Fatalf("New() error = %v", err)
+	}
+	references := registryReferences(t, "Mira Thorn")
+	validator := newValidator(t, references)
+	metadata, err := json.Marshal(validator.ManifestMetadata())
+	if err != nil {
+		t.Fatal(err)
+	}
+	if strings.Contains(string(metadata), "Mira Thorn") || strings.Contains(string(metadata), "other-session") {
+		t.Fatalf("metadata leaked registry content: %s", metadata)
+	}
+	if got := validator.CheckpointFingerprints(); len(got) != 2 || got[0].Value != policy || !strings.HasPrefix(got[1].Value, "sha256:") {
+		t.Fatalf("CheckpointFingerprints() = %#v", got)
+	}
+}
+
+func TestValidatorDefersShapeAndDoesNotMutateOrMisregister(t *testing.T) {
+	references := registryReferences(t, "Mira Thorn")
+	validator := newValidator(t, references)
+	malformed := dnd.NPCOccurrenceList{Occurrences: []dnd.NPCOccurrence{{NPCID: "npc:test", Name: "Mira Thorn"}}}
+	result, err := validator.Validate(context.Background(), request(references, malformed))
+	if err != nil || !result.Approved {
+		t.Fatalf("shape deferral = %#v, %v", result, err)
+	}
+	value := validList("Mira Thorn")
+	before := value
+	_, err = validator.Validate(context.Background(), request(references, value))
+	if err != nil || !reflect.DeepEqual(value, before) {
+		t.Fatalf("Validate() mutated value: %#v", value)
+	}
+	registry := pipeline.NewValidatorRegistry()
+	if err := Register(registry); err != nil {
+		t.Fatal(err)
+	}
+	if _, err := DecodeOptions(map[string]any{"unexpected": true}); err == nil {
+		t.Fatal("DecodeOptions() accepted unknown option")
+	}
+}
+
+func newValidator(t *testing.T, references ...contracts.ReferenceSet) *Validator {
+	t.Helper()
+	validator, err := New(Options{}, references...)
+	if err != nil {
+		t.Fatal(err)
+	}
+	return validator
+}
+
+func request(references contracts.ReferenceSet, value dnd.NPCOccurrenceList) contracts.TypedValidationRequest[dnd.NPCOccurrenceList] {
+	return contracts.TypedValidationRequest[dnd.NPCOccurrenceList]{References: references, Value: value}
+}
+
+func validList(name string) dnd.NPCOccurrenceList {
+	return dnd.NPCOccurrenceList{Occurrences: []dnd.NPCOccurrence{{
+		NPCID: identity.DeriveID(name), Name: name, Kind: dnd.NPCOccurrenceKindDialogue,
+		SourceRefs: []source.SourceRef{{SourceID: "session", StartUnitID: 1, EndUnitID: 1}},
+	}}}
+}
+
+func registryReferences(t *testing.T, names ...string) contracts.ReferenceSet {
+	t.Helper()
+	npcs := make([]dnd.NPC, len(names))
+	for index, name := range names {
+		npcs[index] = dnd.NPC{ID: identity.DeriveID(name), Name: name, SourceRefs: []source.SourceRef{{SourceID: "other-session", StartUnitID: index + 1, EndUnitID: index + 1}}}
+	}
+	content, err := npccodec.New().Encode(dnd.NPCRegistry{NPCs: npcs})
+	if err != nil {
+		t.Fatal(err)
+	}
+	return contracts.ReferenceSet{Slots: map[string]contracts.ResolvedReferenceSlot{
+		npcregistry.ReferenceSlot: {
+			Slot:  contracts.ReferenceSlot{Name: npcregistry.ReferenceSlot},
+			Items: []contracts.ReferenceItem{{SlotName: npcregistry.ReferenceSlot, MediaType: npccodec.MediaType, Content: content, Origin: contracts.ReferenceOrigin{Type: "generated"}}},
+		},
+	}}
+}

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

@@ -0,0 +1,109 @@
+// Package shape validates required D&D NPC occurrence candidate fields.
+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/shared/diagnostics"
+)
+
+const (
+	Key        = "extract/dnd/npc-occurrences/shape"
+	ReasonCode = "invalid_npc_interaction_shape"
+	policy     = "dnd.npc_occurrences.validator.shape.v1"
+)
+
+type Options struct{}
+type Validator struct{}
+
+var _ contracts.TypedValidator[dnd.NPCOccurrenceList] = (*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.NPCOccurrenceList]) (contracts.ValidationResult, error) {
+	if err := Validate(req.Value); err != nil {
+		return contracts.ValidationResult{Approved: false, ReasonCode: ReasonCode, Message: err.Error()}, nil
+	}
+	return contracts.ValidationResult{Approved: true}, nil
+}
+
+func Validate(value dnd.NPCOccurrenceList) error {
+	issues := issuesFor(value)
+	if len(issues) == 0 {
+		return nil
+	}
+	return fmt.Errorf("%s", diagnostics.Aggregate("invalid NPC occurrence shape", issues))
+}
+
+func issuesFor(value dnd.NPCOccurrenceList) []string {
+	if value.Occurrences == nil {
+		return []string{"occurrences must be present"}
+	}
+	issues := make([]string, 0)
+	for index, occurrence := range value.Occurrences {
+		prefix := fmt.Sprintf("occurrences[%d]", index)
+		if strings.TrimSpace(occurrence.NPCID) == "" {
+			issues = append(issues, prefix+".npc_id must not be empty: "+diagnostics.Quote(occurrence.NPCID))
+		}
+		if strings.TrimSpace(occurrence.Name) == "" {
+			issues = append(issues, prefix+".name must not be empty: "+diagnostics.Quote(occurrence.Name))
+		}
+		if !validKind(occurrence.Kind) {
+			issues = append(issues, prefix+".kind is unsupported: "+diagnostics.Quote(string(occurrence.Kind)))
+		}
+		if len(occurrence.SourceRefs) == 0 {
+			issues = append(issues, prefix+".source_refs must contain at least one reference")
+		}
+	}
+	return issues
+}
+
+func validKind(value dnd.NPCOccurrenceKind) bool {
+	switch value {
+	case dnd.NPCOccurrenceKindMentioned,
+		dnd.NPCOccurrenceKindNoncombatPresence,
+		dnd.NPCOccurrenceKindDialogue,
+		dnd.NPCOccurrenceKindCombatAlly,
+		dnd.NPCOccurrenceKindCombatOpponent,
+		dnd.NPCOccurrenceKindOther:
+		return true
+	default:
+		return false
+	}
+}
+
+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), 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/npcoccurrences/shape/validator_test.go

@@ -0,0 +1,70 @@
+package shape
+
+import (
+	"context"
+	"reflect"
+	"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 TestValidatorOwnsRequiredNameKindAndEvidence(t *testing.T) {
+	valid := validList()
+	result, err := New(Options{}).Validate(context.Background(), contracts.TypedValidationRequest[dnd.NPCOccurrenceList]{Value: valid})
+	if err != nil || !result.Approved {
+		t.Fatalf("Validate() = %#v, %v", result, err)
+	}
+	for _, test := range []struct {
+		name  string
+		value dnd.NPCOccurrenceList
+		want  string
+	}{
+		{"missing occurrences", dnd.NPCOccurrenceList{}, "occurrences must be present"},
+		{"blank name", dnd.NPCOccurrenceList{Occurrences: []dnd.NPCOccurrence{{NPCID: "npc:test", Name: " ", Kind: dnd.NPCOccurrenceKindDialogue, SourceRefs: valid.Occurrences[0].SourceRefs}}}, "name must not be empty"},
+		{"unsupported kind", dnd.NPCOccurrenceList{Occurrences: []dnd.NPCOccurrence{{NPCID: "npc:test", Name: "Mira Thorn", Kind: "unsupported", SourceRefs: valid.Occurrences[0].SourceRefs}}}, "kind is unsupported"},
+		{"missing evidence", dnd.NPCOccurrenceList{Occurrences: []dnd.NPCOccurrence{{NPCID: "npc:test", Name: "Mira Thorn", Kind: dnd.NPCOccurrenceKindDialogue}}}, "source_refs must contain"},
+	} {
+		t.Run(test.name, func(t *testing.T) {
+			result, err := New(Options{}).Validate(context.Background(), contracts.TypedValidationRequest[dnd.NPCOccurrenceList]{Value: test.value})
+			if err != nil || result.Approved || result.ReasonCode != ReasonCode || !strings.Contains(result.Message, test.want) {
+				t.Fatalf("Validate() = %#v, %v; want %q", result, err, test.want)
+			}
+		})
+	}
+}
+
+func TestValidatorBoundsDiagnosticsPreservesValueAndRegistersTypedContract(t *testing.T) {
+	value := dnd.NPCOccurrenceList{Occurrences: make([]dnd.NPCOccurrence, 24)}
+	for index := range value.Occurrences {
+		value.Occurrences[index] = dnd.NPCOccurrence{NPCID: "npc:test", Name: strings.Repeat("火", 220) + "\n", Kind: "unsupported"}
+	}
+	result, err := New(Options{}).Validate(context.Background(), contracts.TypedValidationRequest[dnd.NPCOccurrenceList]{Value: value})
+	if err != nil || result.Approved || len([]byte(result.Message)) > 4096 || !utf8.ValidString(result.Message) || !strings.Contains(result.Message, "additional issue(s) omitted") {
+		t.Fatalf("Validate() = %#v, %v", result, err)
+	}
+	if value.Occurrences[0].Name != strings.Repeat("火", 220)+"\n" {
+		t.Fatal("Validate() mutated input")
+	}
+	if got := New(Options{}).CheckpointFingerprints(); !reflect.DeepEqual(got, []pipeline.CheckpointFingerprint{{Name: "policy", Value: policy}}) {
+		t.Fatalf("CheckpointFingerprints() = %#v", got)
+	}
+	registry := pipeline.NewValidatorRegistry()
+	if err := Register(registry); err != nil {
+		t.Fatal(err)
+	}
+	if _, err := DecodeOptions(map[string]any{"unexpected": true}); err == nil {
+		t.Fatal("DecodeOptions() accepted unknown option")
+	}
+}
+
+func validList() dnd.NPCOccurrenceList {
+	return dnd.NPCOccurrenceList{Occurrences: []dnd.NPCOccurrence{{
+		NPCID: "npc:test", Name: "Mira Thorn", Kind: dnd.NPCOccurrenceKindDialogue,
+		SourceRefs: []source.SourceRef{{SourceID: "session", StartUnitID: 1, EndUnitID: 1}},
+	}}}
+}

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

@@ -0,0 +1,104 @@
+// Package sourcerefs validates D&D NPC occurrence transcript evidence.
+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/shared/diagnostics"
+	occurrenceshape "gitea.maximumdirect.net/eric/notarius/internal/modules/dnd/validate/npcoccurrences/shape"
+)
+
+const (
+	Key        = "extract/dnd/npc-occurrences/source_refs"
+	ReasonCode = "invalid_npc_interaction_source_refs"
+	policy     = "dnd.npc_occurrences.validator.source_refs.v2"
+)
+
+type Options struct{}
+type Validator struct{}
+
+var _ contracts.TypedValidator[dnd.NPCOccurrenceList] = (*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.NPCOccurrenceList]) (contracts.ValidationResult, error) {
+	if req.Stage == string(pipeline.StageExtract) && req.Chunk == nil {
+		return contracts.ValidationResult{}, fmt.Errorf("NPC occurrence source-reference validator requires the current extraction chunk")
+	}
+	if occurrenceshape.Validate(req.Value) != nil {
+		return contracts.ValidationResult{Approved: true}, nil
+	}
+	index := source.NewDocumentIndex(req.Source)
+	issues := make([]string, 0)
+	for occurrenceIndex, occurrence := range req.Value.Occurrences {
+		for refIndex, ref := range occurrence.SourceRefs {
+			if err := index.ValidateRef(ref); err != nil {
+				issues = append(issues, fmt.Sprintf("occurrences[%d].source_refs[%d]: %s", occurrenceIndex, refIndex, diagnostics.Truncate(err.Error())))
+				continue
+			}
+			if req.Stage == string(pipeline.StageExtract) && !chunkContainsRef(req.Chunk, ref) {
+				issues = append(issues, fmt.Sprintf(
+					"occurrences[%d].source_refs[%d]: source reference is outside the current extraction chunk",
+					occurrenceIndex, refIndex,
+				))
+			}
+		}
+	}
+	if len(issues) == 0 {
+		return contracts.ValidationResult{Approved: true}, nil
+	}
+	return contracts.ValidationResult{
+		Approved:   false,
+		ReasonCode: ReasonCode,
+		Message:    diagnostics.Aggregate("invalid NPC occurrence source references", issues),
+	}, nil
+}
+
+func chunkContainsRef(chunk *source.Chunk, ref source.SourceRef) bool {
+	if chunk == nil || ref.SourceID != chunk.SourceID {
+		return false
+	}
+	startFound := false
+	endFound := false
+	for _, unit := range chunk.Units {
+		startFound = startFound || unit.ID == ref.StartUnitID
+		endFound = endFound || unit.ID == ref.EndUnitID
+	}
+	return startFound && endFound
+}
+
+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), 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/npcoccurrences/source_refs/validator_test.go

@@ -0,0 +1,109 @@
+package sourcerefs
+
+import (
+	"context"
+	"reflect"
+	"strings"
+	"testing"
+
+	"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 TestValidatorOwnsCurrentSourceUnitAndRangeValidation(t *testing.T) {
+	value := validList()
+	result, err := New(Options{}).Validate(context.Background(), request(document(), value))
+	if err != nil || !result.Approved {
+		t.Fatalf("valid result = %#v, %v", result, err)
+	}
+	value.Occurrences[0].SourceRefs = []source.SourceRef{
+		{SourceID: "foreign", StartUnitID: 1, EndUnitID: 1},
+		{SourceID: "session", StartUnitID: 99, EndUnitID: 99},
+		{SourceID: "session", StartUnitID: 2, EndUnitID: 1},
+	}
+	result, err = New(Options{}).Validate(context.Background(), request(document(), value))
+	if err != nil || result.Approved || result.ReasonCode != ReasonCode || !strings.Contains(result.Message, "occurrences[0].source_refs[0]") {
+		t.Fatalf("invalid result = %#v, %v", result, err)
+	}
+}
+
+func TestValidatorRejectsDocumentValidEvidenceOutsideCurrentExtractionChunk(t *testing.T) {
+	doc := document()
+	chunk := &source.Chunk{
+		ID:       "chunk-0",
+		SourceID: doc.ID,
+		Units:    append([]source.SourceUnit(nil), doc.Units[:2]...),
+	}
+	value := validList()
+	result, err := New(Options{}).Validate(context.Background(), contracts.TypedValidationRequest[dnd.NPCOccurrenceList]{
+		Stage:  string(pipeline.StageExtract),
+		Source: doc,
+		Chunk:  chunk,
+		Value:  value,
+	})
+	if err != nil || !result.Approved {
+		t.Fatalf("contained evidence = %#v, %v", result, err)
+	}
+
+	value.Occurrences[0].SourceRefs = []source.SourceRef{{
+		SourceID: doc.ID, StartUnitID: 2, EndUnitID: 3,
+	}}
+	result, err = New(Options{}).Validate(context.Background(), contracts.TypedValidationRequest[dnd.NPCOccurrenceList]{
+		Stage:  string(pipeline.StageExtract),
+		Source: doc,
+		Chunk:  chunk,
+		Value:  value,
+	})
+	if err != nil || result.Approved || !strings.Contains(result.Message, "outside the current extraction chunk") {
+		t.Fatalf("out-of-chunk evidence = %#v, %v", result, err)
+	}
+}
+
+func TestValidatorRequiresChunkDuringExtractValidation(t *testing.T) {
+	_, err := New(Options{}).Validate(context.Background(), contracts.TypedValidationRequest[dnd.NPCOccurrenceList]{
+		Stage:  string(pipeline.StageExtract),
+		Source: document(),
+		Value:  validList(),
+	})
+	if err == nil || !strings.Contains(err.Error(), "requires the current extraction chunk") {
+		t.Fatalf("Validate() error = %v", err)
+	}
+}
+
+func TestValidatorDefersShapeAndDoesNotMutate(t *testing.T) {
+	malformed := dnd.NPCOccurrenceList{Occurrences: []dnd.NPCOccurrence{{NPCID: "npc:test", Name: "Mira Thorn"}}}
+	result, err := New(Options{}).Validate(context.Background(), request(document(), malformed))
+	if err != nil || !result.Approved {
+		t.Fatalf("shape deferral = %#v, %v", result, err)
+	}
+	value := validList()
+	before := value
+	_, err = New(Options{}).Validate(context.Background(), request(document(), value))
+	if err != nil || !reflect.DeepEqual(value, before) {
+		t.Fatalf("Validate() mutated value: %#v", value)
+	}
+	registry := pipeline.NewValidatorRegistry()
+	if err := Register(registry); err != nil {
+		t.Fatal(err)
+	}
+	if got := New(Options{}).CheckpointFingerprints(); len(got) != 1 || got[0].Value != policy {
+		t.Fatalf("CheckpointFingerprints() = %#v", got)
+	}
+}
+
+func request(doc *source.SourceDocument, value dnd.NPCOccurrenceList) contracts.TypedValidationRequest[dnd.NPCOccurrenceList] {
+	return contracts.TypedValidationRequest[dnd.NPCOccurrenceList]{Source: doc, Value: value}
+}
+
+func document() *source.SourceDocument {
+	return &source.SourceDocument{ID: "session", Units: []source.SourceUnit{{ID: 1}, {ID: 2}, {ID: 3}}}
+}
+
+func validList() dnd.NPCOccurrenceList {
+	return dnd.NPCOccurrenceList{Occurrences: []dnd.NPCOccurrence{{
+		NPCID: "npc:test", Name: "Mira Thorn", Kind: dnd.NPCOccurrenceKindDialogue,
+		SourceRefs: []source.SourceRef{{SourceID: "session", StartUnitID: 1, EndUnitID: 2}},
+	}}}
+}

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

@@ -0,0 +1,92 @@
+// Package sourcerelatedness warns about NPC occurrence evidence unrelated to its NPC.
+package sourcerelatedness
+
+import (
+	"context"
+	"fmt"
+
+	"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/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               = "extract/dnd/npc-occurrences/source_relatedness"
+	WarningReasonCode = "npc_interaction_not_near_source"
+	OmittedReasonCode = "npc_interaction_relatedness_warnings_omitted"
+	policy            = "dnd.npc_occurrences.validator.source_relatedness.v2"
+)
+
+type Options struct{}
+type Validator struct{}
+
+var _ contracts.TypedValidator[dnd.NPCOccurrenceList] = (*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.NPCOccurrenceList]) (contracts.ValidationResult, error) {
+	if occurrenceshape.Validate(req.Value) != nil {
+		return contracts.ValidationResult{Approved: true}, nil
+	}
+	resolver, err := shared.NewCitationResolver(req.Source)
+	if err != nil {
+		return contracts.ValidationResult{Approved: true}, nil
+	}
+	citedTexts := make([]string, len(req.Value.Occurrences))
+	for index, occurrence := range req.Value.Occurrences {
+		citedText, err := resolver.CitedText(occurrence.SourceRefs)
+		if err != nil {
+			return contracts.ValidationResult{Approved: true}, nil
+		}
+		citedTexts[index] = citedText
+	}
+	warnings := make([]contracts.Warning, 0)
+	for index, occurrence := range req.Value.Occurrences {
+		if shared.ContainsTokenSequence(citedTexts[index], occurrence.Name) {
+			continue
+		}
+		warnings = append(warnings, contracts.Warning{
+			Scope:      fmt.Sprintf("occurrences[%d]", index),
+			ReasonCode: WarningReasonCode,
+			Message:    fmt.Sprintf("NPC occurrence name %s was not found in cited source text", diagnostics.Quote(occurrence.Name)),
+		})
+	}
+	return contracts.ValidationResult{
+		Approved: true,
+		Warnings: diagnostics.LimitWarnings(warnings, "npc_occurrences", OmittedReasonCode),
+	}, nil
+}
+
+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), 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/npcoccurrences/source_relatedness/validator_test.go

@@ -0,0 +1,76 @@
+package sourcerelatedness
+
+import (
+	"context"
+	"reflect"
+	"strings"
+	"testing"
+
+	"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/shared/diagnostics"
+)
+
+func TestValidatorUsesOnlyCurrentTranscriptAndWarnsOncePerOccurrence(t *testing.T) {
+	value := dnd.NPCOccurrenceList{Occurrences: []dnd.NPCOccurrence{
+		{NPCID: "npc:test", Name: "O'Rin Thorn", Kind: dnd.NPCOccurrenceKindDialogue, SourceRefs: []source.SourceRef{{SourceID: "session", StartUnitID: 1, EndUnitID: 1}}},
+		{NPCID: "npc:test", Name: "Missing\nNPC", Kind: dnd.NPCOccurrenceKindMentioned, SourceRefs: []source.SourceRef{{SourceID: "session", StartUnitID: 2, EndUnitID: 2}, {SourceID: "session", StartUnitID: 2, EndUnitID: 2}}},
+	}}
+	doc := &source.SourceDocument{ID: "session", Units: []source.SourceUnit{{ID: 1, Text: "O’Rin Thorn speaks."}, {ID: 2, Text: "The party waits."}}}
+	references := contracts.ReferenceSet{Slots: map[string]contracts.ResolvedReferenceSlot{"glossary": {Items: []contracts.ReferenceItem{{Content: []byte("Missing NPC")}}}}}
+	result, err := New(Options{}).Validate(context.Background(), contracts.TypedValidationRequest[dnd.NPCOccurrenceList]{Source: doc, References: references, Value: value})
+	if err != nil || !result.Approved || len(result.Warnings) != 1 {
+		t.Fatalf("Validate() = %#v, %v", result, err)
+	}
+	if warning := result.Warnings[0]; warning.Scope != "occurrences[1]" || warning.ReasonCode != WarningReasonCode || !strings.Contains(warning.Message, `Missing\nNPC`) {
+		t.Fatalf("warning = %#v", warning)
+	}
+}
+
+func TestValidatorDefersMalformedShapeAndInvalidRanges(t *testing.T) {
+	for _, value := range []dnd.NPCOccurrenceList{
+		{Occurrences: []dnd.NPCOccurrence{{NPCID: "npc:test", Name: "Mira Thorn"}}},
+		{Occurrences: []dnd.NPCOccurrence{{NPCID: "npc:test", Name: "Mira Thorn", Kind: dnd.NPCOccurrenceKindDialogue, SourceRefs: []source.SourceRef{{SourceID: "session", StartUnitID: 99, EndUnitID: 99}}}}},
+	} {
+		result, err := New(Options{}).Validate(context.Background(), contracts.TypedValidationRequest[dnd.NPCOccurrenceList]{Source: &source.SourceDocument{ID: "session", Units: []source.SourceUnit{{ID: 1}}}, Value: value})
+		if err != nil || !result.Approved || len(result.Warnings) != 0 {
+			t.Fatalf("deferral = %#v, %v", result, err)
+		}
+	}
+	value := dnd.NPCOccurrenceList{Occurrences: []dnd.NPCOccurrence{{NPCID: "npc:test", Name: "Mira Thorn", Kind: dnd.NPCOccurrenceKindDialogue, SourceRefs: []source.SourceRef{{SourceID: "session", StartUnitID: 1, EndUnitID: 1}}}}}
+	before := value
+	_, err := New(Options{}).Validate(context.Background(), contracts.TypedValidationRequest[dnd.NPCOccurrenceList]{Source: &source.SourceDocument{ID: "session", Units: []source.SourceUnit{{ID: 1, Text: "Mira Thorn"}}}, Value: value})
+	if err != nil || !reflect.DeepEqual(value, before) {
+		t.Fatalf("Validate() mutated value: %#v", value)
+	}
+	registry := pipeline.NewValidatorRegistry()
+	if err := Register(registry); err != nil {
+		t.Fatal(err)
+	}
+}
+
+func TestValidatorBoundsWarnings(t *testing.T) {
+	count := diagnostics.MaxWarnings + 5
+	occurrences := make([]dnd.NPCOccurrence, count)
+	for index := range occurrences {
+		occurrences[index] = dnd.NPCOccurrence{
+			NPCID:      "npc:test",
+			Name:       "Missing NPC",
+			Kind:       dnd.NPCOccurrenceKindMentioned,
+			SourceRefs: []source.SourceRef{{SourceID: "session", StartUnitID: 1, EndUnitID: 1}},
+		}
+	}
+	result, err := New(Options{}).Validate(context.Background(), contracts.TypedValidationRequest[dnd.NPCOccurrenceList]{
+		Source: &source.SourceDocument{ID: "session", Units: []source.SourceUnit{{ID: 1, Text: "The party waits."}}},
+		Value:  dnd.NPCOccurrenceList{Occurrences: occurrences},
+	})
+	if err != nil || !result.Approved {
+		t.Fatalf("Validate() = %#v, %v", result, err)
+	}
+	if len(result.Warnings) != diagnostics.MaxWarnings ||
+		result.Warnings[len(result.Warnings)-1].ReasonCode != OmittedReasonCode {
+		t.Fatalf("warnings = %#v", result.Warnings)
+	}
+}