Move NPC occurrences to their canonical namespace

internal/modules/dnd/extract/npcoccurrences/canonicalize.go

@@ -0,0 +1,89 @@
+package npcoccurrences
+
+import (
+	"sort"
+
+	"gitea.maximumdirect.net/eric/notarius/internal/core/source"
+	"gitea.maximumdirect.net/eric/notarius/internal/modules/dnd"
+	"gitea.maximumdirect.net/eric/notarius/internal/modules/dnd/shared"
+)
+
+type orderedOccurrenceResponse struct {
+	value       occurrenceResponse
+	earliest    int
+	hasEvidence bool
+}
+
+func canonicalizeResponse(response *extractionResponse, order shared.SourceRefOrder, sourceID string) {
+	if response == nil {
+		return
+	}
+	ordered := make([]orderedOccurrenceResponse, len(response.Occurrences))
+	for index := range response.Occurrences {
+		earliest, hasEvidence := canonicalizeOccurrence(&response.Occurrences[index], order, sourceID)
+		ordered[index] = orderedOccurrenceResponse{
+			value:       response.Occurrences[index],
+			earliest:    earliest,
+			hasEvidence: hasEvidence,
+		}
+	}
+	sort.SliceStable(ordered, func(i, j int) bool {
+		if ordered[i].hasEvidence != ordered[j].hasEvidence {
+			return ordered[i].hasEvidence
+		}
+		if !ordered[i].hasEvidence {
+			return false
+		}
+		return ordered[i].earliest < ordered[j].earliest
+	})
+	for index := range ordered {
+		response.Occurrences[index] = ordered[index].value
+	}
+}
+
+func canonicalizeOccurrence(occurrence *occurrenceResponse, order shared.SourceRefOrder, sourceID string) (int, bool) {
+	if occurrence == nil {
+		return 0, false
+	}
+	refs := order.Canonicalize(canonicalSourceRefs(occurrence.SourceRefs, sourceID))
+	occurrence.SourceRefs = occurrenceResponseRefs(refs)
+	return order.EarliestValid(refs)
+}
+
+func canonicalOccurrenceList(response extractionResponse, sourceID string) dnd.NPCOccurrenceList {
+	occurrences := make([]dnd.NPCOccurrence, len(response.Occurrences))
+	for index, occurrence := range response.Occurrences {
+		occurrences[index] = dnd.NPCOccurrence{
+			NPCID:      occurrence.NPCID,
+			Name:       occurrence.Name,
+			Kind:       dnd.NPCOccurrenceKind(occurrence.Kind),
+			SourceRefs: canonicalSourceRefs(occurrence.SourceRefs, sourceID),
+		}
+	}
+	if response.Occurrences == nil {
+		occurrences = nil
+	}
+	return dnd.NPCOccurrenceList{Occurrences: occurrences}
+}
+
+func canonicalSourceRefs(refs []occurrenceSourceRefResponse, sourceID string) []source.SourceRef {
+	if refs == nil {
+		return nil
+	}
+	out := make([]source.SourceRef, len(refs))
+	for index, ref := range refs {
+		out[index] = source.SourceRef{SourceID: sourceID, StartUnitID: ref.StartUnitID, EndUnitID: ref.EndUnitID}
+	}
+	return out
+}
+
+func occurrenceResponseRefs(refs []source.SourceRef) []occurrenceSourceRefResponse {
+	if refs == nil {
+		return nil
+	}
+	values := make([]occurrenceSourceRefResponse, len(refs))
+	for index, ref := range refs {
+		values[index] = occurrenceSourceRefResponse{StartUnitID: ref.StartUnitID, EndUnitID: ref.EndUnitID}
+	}
+	return values
+}

internal/modules/dnd/extract/npcoccurrences/extractor.go

@@ -0,0 +1,229 @@
+package npcoccurrences
+
+import (
+	"context"
+	"fmt"
+	"sort"
+
+	"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"
+)
+
+const (
+	Key           = "dnd/npc-occurrences"
+	mappingPolicy = "dnd.npc_occurrences.extract_mapping.v2"
+)
+
+const (
+	NPCRegistryReferenceSlot = npcregistry.ReferenceSlot
+	NPCRegistryMaxBytes      = npcregistry.MaxBytes
+)
+
+var requiredCapabilities = []string{
+	"chunks",
+	"source.transcript",
+}
+
+var providedCapabilities = []string{
+	"dnd.npc_occurrences",
+}
+
+var referenceSlotDescriptions = shared.ReferenceSlotDescriptions{
+	Glossary: "Optional campaign glossary reference material used only for occurrence disambiguation.",
+	Party:    "Optional party roster reference material used only for occurrence disambiguation.",
+	Players:  "Optional player list reference material used only for occurrence disambiguation.",
+	Roster:   "Deprecated alias for party roster reference material used only for occurrence disambiguation.",
+}
+
+func referenceSlots() []contracts.ReferenceSlot {
+	slots := shared.ReferenceSlots(referenceSlotDescriptions)
+	slots = append(slots, contracts.ReferenceSlot{
+		Name:                  NPCRegistryReferenceSlot,
+		Description:           "Required normalized NPC registry used only for occurrence identity grounding, never as occurrence evidence.",
+		Required:              true,
+		AcceptedMediaTypes:    []string{"application/json"},
+		AcceptedArtifactKinds: []contracts.ArtifactKind{dnd.NPCRegistryKind},
+		MaxBytes:              NPCRegistryMaxBytes,
+	})
+	sort.Slice(slots, func(i, j int) bool { return slots[i].Name < slots[j].Name })
+	return slots
+}
+
+var _ contracts.Extractor[dnd.NPCOccurrenceList] = (*Extractor)(nil)
+var _ contracts.ManifestMetadataProvider = (*Extractor)(nil)
+var _ pipeline.CheckpointFingerprintProvider = (*Extractor)(nil)
+
+type Options struct{}
+
+type Extractor struct {
+	llm               contracts.StructuredLLMClient
+	npcResolver       *npcregistry.Resolver
+	promptSHA         string
+	responseSchemaSHA string
+}
+
+func New(llmClient contracts.StructuredLLMClient, _ Options, references ...contracts.ReferenceSet) (*Extractor, error) {
+	if llmClient == nil {
+		return nil, extractorErrorf("LLM client must not be nil")
+	}
+	if len(references) > 1 {
+		return nil, extractorErrorf("at most one reference set may be supplied")
+	}
+	var referenceSet contracts.ReferenceSet
+	if len(references) == 1 {
+		referenceSet = references[0]
+	}
+	npcResolver, err := npcregistry.NewResolver(referenceSet)
+	if err != nil {
+		return nil, extractorErrorf("prepare NPC registry prompt input: %w", err)
+	}
+	promptSHA, err := promptAssetMetadata()
+	if err != nil {
+		return nil, extractorErrorf("load prompt metadata: %w", err)
+	}
+	responseSchema, err := loadResponseSchema()
+	if err != nil {
+		return nil, extractorErrorf("load response schema: %w", err)
+	}
+	return &Extractor{
+		llm:               llmClient,
+		npcResolver:       npcResolver,
+		promptSHA:         promptSHA,
+		responseSchemaSHA: responseSchema.SHA256,
+	}, nil
+}
+
+func (e *Extractor) Key() string { return Key }
+
+func (e *Extractor) ReferenceSlots() []contracts.ReferenceSlot { return referenceSlots() }
+
+func (e *Extractor) ManifestMetadata() map[string]any {
+	if e == nil {
+		return nil
+	}
+	metadata := map[string]any{
+		"prompt_id":               PromptID,
+		"prompt_version":          SchemaVersion,
+		"prompt_sha256":           e.promptSHA,
+		"mapping_policy":          mappingPolicy,
+		"response_schema_key":     string(ResponseSchemaKey),
+		"response_schema_id":      ResponseSchemaID,
+		"response_schema_name":    ResponseSchemaName,
+		"response_schema_version": SchemaVersion,
+		"response_schema_sha256":  e.responseSchemaSHA,
+	}
+	seeded := e.npcResolver.Seeded()
+	if seeded.Bound() {
+		metadata["npc_registry_digest"] = seeded.Digest()
+		metadata["npc_count"] = seeded.Count()
+	}
+	return metadata
+}
+
+func (e *Extractor) CheckpointFingerprints() []pipeline.CheckpointFingerprint {
+	if e == nil {
+		return nil
+	}
+	seeded := e.npcResolver.Seeded()
+	return []pipeline.CheckpointFingerprint{
+		{Name: "prompt", Value: e.promptSHA},
+		{Name: "response_schema", Value: e.responseSchemaSHA},
+		{Name: "mapping_policy", Value: mappingPolicy},
+		{Name: "npc_registry", Value: seeded.IdentityPromptInput().Digest},
+	}
+}
+
+func (e *Extractor) Extract(ctx context.Context, req contracts.TypedExtractionRequest) (contracts.TypedExtractionResult[dnd.NPCOccurrenceList], error) {
+	if e == nil {
+		return contracts.TypedExtractionResult[dnd.NPCOccurrenceList]{}, extractorErrorf("extractor must not be nil")
+	}
+	if e.llm == nil {
+		return contracts.TypedExtractionResult[dnd.NPCOccurrenceList]{}, extractorErrorf("LLM client must not be nil")
+	}
+	sourceInput, err := shared.PrepareChunkExtraction(ctx, req)
+	if err != nil {
+		return contracts.TypedExtractionResult[dnd.NPCOccurrenceList]{}, extractorErrorf("%w", err)
+	}
+	order := shared.NewSourceRefOrder(req.Source)
+	npcRegistry, err := e.npcResolver.Resolve(req.References)
+	if err != nil {
+		return contracts.TypedExtractionResult[dnd.NPCOccurrenceList]{}, extractorErrorf("resolve NPC registry: %w", err)
+	}
+	if !npcRegistry.Bound() {
+		return contracts.TypedExtractionResult[dnd.NPCOccurrenceList]{}, extractorErrorf("NPC registry reference is required")
+	}
+
+	var response extractionResponse
+	inputs := shared.PromptInputs(sourceInput, req.References)
+	inputs[NPCRegistryReferenceSlot] = npcRegistry.IdentityPromptInput()
+	if _, err := e.llm.CompleteStructured(ctx, contracts.StructuredCompletionRequest{
+		StageName:     Key,
+		PromptID:      PromptID,
+		PromptVersion: SchemaVersion,
+		ProfileID:     req.LLMProfile,
+		SessionID:     req.SessionID,
+		Inputs:        inputs,
+	}, &response); err != nil {
+		return contracts.TypedExtractionResult[dnd.NPCOccurrenceList]{}, extractorErrorf("complete structured output: %w", err)
+	}
+	canonicalizeResponse(&response, order, req.Source.ID)
+	value := canonicalOccurrenceList(response, req.Source.ID)
+	if err := validateRegistryPairs(value, npcRegistry); err != nil {
+		return contracts.TypedExtractionResult[dnd.NPCOccurrenceList]{}, extractorErrorf("validate NPC registry pairs: %w", err)
+	}
+	return contracts.TypedExtractionResult[dnd.NPCOccurrenceList]{Value: value}, nil
+}
+
+func validateRegistryPairs(value dnd.NPCOccurrenceList, registry *npcregistry.Registry) error {
+	for index, occurrence := range value.Occurrences {
+		canonical, ok := registry.LookupID(occurrence.NPCID)
+		if !ok {
+			return fmt.Errorf("occurrences[%d].npc_id is not in the NPC registry", index)
+		}
+		if occurrence.Name != canonical.Name {
+			return fmt.Errorf("occurrences[%d].name does not match npc_id", index)
+		}
+	}
+	return nil
+}
+
+func ModuleSpec() pipeline.ModuleSpec {
+	return pipeline.ModuleSpec{
+		Key:            Key,
+		Stage:          pipeline.StageExtract,
+		ExecutionClass: contracts.ExecutionClassLLMBacked,
+		Requires:       append([]string(nil), requiredCapabilities...),
+		Provides:       append([]string(nil), providedCapabilities...),
+		ArtifactKind:   dnd.NPCOccurrenceListKind,
+		ReferenceSlots: referenceSlots(),
+	}
+}
+
+func Register(registry *pipeline.ExtractorRegistry) error {
+	return pipeline.RegisterExtractorBuilder(registry, ModuleSpec(), validateOptions, func(request pipeline.BuildRequest) (contracts.Extractor[dnd.NPCOccurrenceList], error) {
+		options, err := DecodeOptions(request.Options)
+		if err != nil {
+			return nil, err
+		}
+		return New(request.Dependencies.LLM, options, request.References)
+	})
+}
+
+func validateOptions(options map[string]any) error {
+	_, err := DecodeOptions(options)
+	return err
+}
+
+func DecodeOptions(options map[string]any) (Options, error) {
+	if err := pipeline.RejectUnknownOptions(options); err != nil {
+		return Options{}, extractorErrorf("%w", err)
+	}
+	return Options{}, nil
+}
+
+func extractorErrorf(format string, args ...any) error {
+	return fmt.Errorf("dnd NPC occurrences extractor: "+format, args...)
+}

internal/modules/dnd/extract/npcoccurrences/extractor_test.go

@@ -0,0 +1,422 @@
+package npcoccurrences
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"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"
+)
+
+func TestExtractMapsEveryKindAndOrdersBySourcePosition(t *testing.T) {
+	client := &fakeOccurrencesLLMClient{response: extractionResponse{Occurrences: []occurrenceResponse{
+		{NPCID: identity.DeriveID("Other"), Name: "Other", Kind: "other", SourceRefs: occurrenceRefs(30, 30)},
+		{NPCID: identity.DeriveID("Opponent"), Name: "Opponent", Kind: "combat_opponent", SourceRefs: occurrenceRefs(20, 20)},
+		{NPCID: identity.DeriveID("Ally"), Name: "Ally", Kind: "combat_ally", SourceRefs: occurrenceRefs(5, 5)},
+		{NPCID: identity.DeriveID("Speaker"), Name: "Speaker", Kind: "dialogue", SourceRefs: append(occurrenceRefs(2, 2), occurrenceRefs(2, 2)...)},
+		{NPCID: identity.DeriveID("Present"), Name: "Present", Kind: "noncombat_presence", SourceRefs: occurrenceRefs(7, 7)},
+		{NPCID: identity.DeriveID("Mentioned"), Name: "Mentioned", Kind: "mentioned", SourceRefs: occurrenceRefs(10, 10)},
+		{NPCID: identity.DeriveID("Invalid"), Name: "Invalid", Kind: "unsupported", SourceRefs: occurrenceRefs(0, 0)},
+	}}}
+	references := requiredRegistryReferences(t, "Mentioned", "Speaker", "Present", "Ally", "Opponent", "Other", "Invalid")
+	req := extractionRequest()
+	req.References = references
+
+	result, err := newExtractor(t, client, references).Extract(context.Background(), req)
+	if err != nil {
+		t.Fatalf("Extract() error = %v", err)
+	}
+	if got := occurrenceNames(result.Value); !reflect.DeepEqual(got, []string{"Mentioned", "Speaker", "Present", "Ally", "Opponent", "Other", "Invalid"}) {
+		t.Fatalf("occurrence order = %#v", got)
+	}
+	if got := occurrenceKinds(result.Value); !reflect.DeepEqual(got, []dnd.NPCOccurrenceKind{
+		dnd.NPCOccurrenceKindMentioned,
+		dnd.NPCOccurrenceKindDialogue,
+		dnd.NPCOccurrenceKindNoncombatPresence,
+		dnd.NPCOccurrenceKindCombatAlly,
+		dnd.NPCOccurrenceKindCombatOpponent,
+		dnd.NPCOccurrenceKindOther,
+		"unsupported",
+	}) {
+		t.Fatalf("occurrence kinds = %#v", got)
+	}
+	if refs := result.Value.Occurrences[1].SourceRefs; !reflect.DeepEqual(refs, []source.SourceRef{{SourceID: "session-alpha", StartUnitID: 2, EndUnitID: 2}}) {
+		t.Fatalf("canonical source refs = %#v", refs)
+	}
+	if invalid := result.Value.Occurrences[6]; invalid.Name != "Invalid" || invalid.Kind != "unsupported" || !reflect.DeepEqual(invalid.SourceRefs, []source.SourceRef{{SourceID: "session-alpha"}}) {
+		t.Fatalf("invalid candidate = %#v, want preserved values with current source identity", invalid)
+	}
+	if len(client.requests) != 1 {
+		t.Fatalf("LLM calls = %d, want 1", len(client.requests))
+	}
+}
+
+func TestExtractUsesDocumentOrderForReferencesAndOccurrences(t *testing.T) {
+	client := &fakeOccurrencesLLMClient{response: extractionResponse{Occurrences: []occurrenceResponse{
+		{NPCID: identity.DeriveID("Later"), Name: "Later", Kind: "dialogue", SourceRefs: occurrenceRefs(10, 10)},
+		{NPCID: identity.DeriveID("First"), Name: "First", Kind: "mentioned", SourceRefs: []occurrenceSourceRefResponse{
+			{StartUnitID: 10, EndUnitID: 10},
+			{StartUnitID: 30, EndUnitID: 30},
+			{StartUnitID: 30, EndUnitID: 30},
+			{StartUnitID: 999, EndUnitID: 0},
+		}},
+		{NPCID: identity.DeriveID("Second"), Name: "Second", Kind: "other", SourceRefs: occurrenceRefs(30, 30)},
+	}}}
+	references := requiredRegistryReferences(t, "Later", "First", "Second")
+	req := extractionRequest()
+	req.References = references
+	req.Source.Units = []source.SourceUnit{{ID: 30}, {ID: 10}}
+	req.Chunk.Units = append([]source.SourceUnit(nil), req.Source.Units...)
+	req.Chunk.Ref = source.SourceRef{SourceID: req.Source.ID, StartUnitID: 30, EndUnitID: 10}
+
+	result, err := newExtractor(t, client, references).Extract(context.Background(), req)
+	if err != nil {
+		t.Fatalf("Extract() error = %v", err)
+	}
+	if got := occurrenceNames(result.Value); !reflect.DeepEqual(got, []string{"First", "Second", "Later"}) {
+		t.Fatalf("occurrence order = %#v, want document chronology with stable equal-evidence ties", got)
+	}
+	refs := result.Value.Occurrences[0].SourceRefs
+	if got := []int{refs[0].StartUnitID, refs[1].StartUnitID, refs[2].StartUnitID}; !reflect.DeepEqual(got, []int{30, 10, 999}) {
+		t.Fatalf("source refs = %#v, want document order with exact duplicate removed", refs)
+	}
+	refs[0].StartUnitID = 777
+	for _, occurrence := range client.response.Occurrences {
+		for _, ref := range occurrence.SourceRefs {
+			if ref.StartUnitID == 777 {
+				t.Fatal("result source references alias the model response")
+			}
+		}
+	}
+}
+
+func TestNewRequiresLLMAndRejectsAmbiguousReferenceSets(t *testing.T) {
+	if _, err := New(nil, Options{}); err == nil || !strings.Contains(err.Error(), "LLM client") {
+		t.Fatalf("New(nil) error = %v", err)
+	}
+	if _, err := New(&fakeOccurrencesLLMClient{}, Options{}, contracts.ReferenceSet{}, contracts.ReferenceSet{}); err == nil || !strings.Contains(err.Error(), "at most one reference set") {
+		t.Fatalf("New() error = %v", err)
+	}
+}
+
+func TestExtractUsesRegistryIDsAndCurrentTranscriptEvidence(t *testing.T) {
+	client := &fakeOccurrencesLLMClient{response: extractionResponse{Occurrences: []occurrenceResponse{{
+		NPCID: identity.DeriveID("Mira Thorn"), Name: "Mira Thorn", Kind: "dialogue", SourceRefs: occurrenceRefs(10, 10),
+	}}}}
+	references := requiredRegistryReferences(t, "Mira Thorn", "Hooded Guard")
+	req := extractionRequest()
+	req.References = references
+	if _, err := newExtractor(t, client, references).Extract(context.Background(), req); err != nil {
+		t.Fatalf("Extract() error = %v", err)
+	}
+	request := client.requests[0]
+	registry := request.Inputs[NPCRegistryReferenceSlot]
+	if registry.Name != NPCRegistryReferenceSlot || registry.MediaType != "application/json" || string(registry.Content) != `{"npcs":[{"id":"`+identity.DeriveID("Mira Thorn")+`","name":"Mira Thorn"},{"id":"`+identity.DeriveID("Hooded Guard")+`","name":"Hooded Guard"}]}` {
+		t.Fatalf("registry prompt input = %#v, want exact ID and name projection", registry)
+	}
+	for _, forbidden := range []string{"other-session", "start_unit_id"} {
+		if strings.Contains(string(registry.Content), forbidden) {
+			t.Fatalf("registry prompt input leaked %q: %s", forbidden, registry.Content)
+		}
+	}
+	if strings.Contains(string(request.Inputs["transcript"].Content), "other-session") {
+		t.Fatal("transcript input contains registry evidence")
+	}
+	metadata, err := json.Marshal(newExtractor(t, &fakeOccurrencesLLMClient{}, references).ManifestMetadata())
+	if err != nil {
+		t.Fatal(err)
+	}
+	if strings.Contains(string(metadata), "Mira Thorn") || strings.Contains(string(metadata), "other-session") {
+		t.Fatalf("manifest metadata leaked registry content: %s", metadata)
+	}
+}
+
+func TestExtractRequiresBoundRegistryBeforeLLMCall(t *testing.T) {
+	client := &fakeOccurrencesLLMClient{}
+	if _, err := newExtractor(t, client).Extract(context.Background(), extractionRequest()); err == nil || !strings.Contains(err.Error(), "NPC registry reference is required") {
+		t.Fatalf("Extract() error = %v, want required registry failure", err)
+	}
+	if len(client.requests) != 0 {
+		t.Fatalf("LLM calls = %d, want no call", len(client.requests))
+	}
+
+	malformed := contracts.ReferenceSet{Slots: map[string]contracts.ResolvedReferenceSlot{
+		NPCRegistryReferenceSlot: {
+			Slot:  contracts.ReferenceSlot{Name: NPCRegistryReferenceSlot},
+			Items: []contracts.ReferenceItem{{SlotName: NPCRegistryReferenceSlot, MediaType: "application/json", Content: []byte(`{"secret":"private source"}`)}},
+		},
+	}}
+	if _, err := New(client, Options{}, malformed); err == nil || !strings.Contains(err.Error(), "prepare NPC registry") || strings.Contains(err.Error(), "private source") {
+		t.Fatalf("New() error = %v, want content-safe malformed registry error", err)
+	}
+	if len(client.requests) != 0 {
+		t.Fatalf("LLM calls = %d, want no call", len(client.requests))
+	}
+}
+
+func TestExtractRejectsUnknownIDsAndMismatchedNames(t *testing.T) {
+	references := requiredRegistryReferences(t, "Mira Thorn")
+	for _, test := range []struct {
+		name       string
+		occurrence occurrenceResponse
+		want       string
+	}{
+		{"unknown ID", occurrenceResponse{NPCID: "npc:unknown", Name: "Mira Thorn", Kind: "dialogue", SourceRefs: occurrenceRefs(10, 10)}, "npc_id is not in the NPC registry"},
+		{"mismatched name", occurrenceResponse{NPCID: identity.DeriveID("Mira Thorn"), Name: "Hooded Guard", Kind: "dialogue", SourceRefs: occurrenceRefs(10, 10)}, "name does not match npc_id"},
+	} {
+		t.Run(test.name, func(t *testing.T) {
+			client := &fakeOccurrencesLLMClient{response: extractionResponse{Occurrences: []occurrenceResponse{test.occurrence}}}
+			req := extractionRequest()
+			req.References = references
+			if _, err := newExtractor(t, client, references).Extract(context.Background(), req); err == nil || !strings.Contains(err.Error(), test.want) {
+				t.Fatalf("Extract() error = %v, want %q", err, test.want)
+			}
+		})
+	}
+}
+
+func TestExtractResolvesGeneratedRegistryAtOperationTime(t *testing.T) {
+	client := &fakeOccurrencesLLMClient{response: extractionResponse{Occurrences: []occurrenceResponse{}}}
+	references := requiredRegistryReferences(t, "Mira Thorn")
+	req := extractionRequest()
+	req.References = references
+	extractor := newExtractor(t, client)
+	if _, err := extractor.Extract(context.Background(), req); err != nil {
+		t.Fatalf("Extract() error = %v", err)
+	}
+	if input := client.requests[0].Inputs[NPCRegistryReferenceSlot]; string(input.Content) != `{"npcs":[{"id":"`+identity.DeriveID("Mira Thorn")+`","name":"Mira Thorn"}]}` || input.OriginURI != "" {
+		t.Fatalf("generated registry prompt input = %#v", input)
+	}
+	metadata := extractor.ManifestMetadata()
+	if _, ok := metadata["npc_registry_digest"]; ok {
+		t.Fatalf("operation-time registry leaked into static metadata: %#v", metadata)
+	}
+}
+
+func TestExtractAcceptsEmptyBoundRegistryAndEmptyResponse(t *testing.T) {
+	content, err := npccodec.New().Encode(dnd.NPCRegistry{NPCs: []dnd.NPC{}})
+	if err != nil {
+		t.Fatal(err)
+	}
+	references := contracts.ReferenceSet{Slots: map[string]contracts.ResolvedReferenceSlot{
+		NPCRegistryReferenceSlot: {
+			Slot:  contracts.ReferenceSlot{Name: NPCRegistryReferenceSlot},
+			Items: []contracts.ReferenceItem{{SlotName: NPCRegistryReferenceSlot, MediaType: npccodec.MediaType, Content: content}},
+		},
+	}}
+	client := &fakeOccurrencesLLMClient{response: extractionResponse{Occurrences: []occurrenceResponse{}}}
+	req := extractionRequest()
+	req.References = references
+	result, err := newExtractor(t, client, references).Extract(context.Background(), req)
+	if err != nil || result.Value.Occurrences == nil || len(result.Value.Occurrences) != 0 {
+		t.Fatalf("Extract() = %#v, %v; want present empty occurrences", result, err)
+	}
+}
+
+func TestExtractRejectsInvalidRequestsAndProviderFailures(t *testing.T) {
+	references := requiredRegistryReferences(t, "Mira Thorn")
+	valid := extractionRequest()
+	valid.References = references
+	extractor := newExtractor(t, &fakeOccurrencesLLMClient{}, references)
+	var nilExtractor *Extractor
+	for _, test := range []struct {
+		name      string
+		extractor *Extractor
+		ctx       context.Context
+		req       contracts.TypedExtractionRequest
+		want      string
+	}{
+		{"nil extractor", nilExtractor, context.Background(), valid, "extractor"},
+		{"nil LLM client", &Extractor{}, context.Background(), valid, "LLM client"},
+		{"wrapped preflight failure", extractor, context.Background(), mismatchedSourceInputRequest(valid), "must match chunk"},
+	} {
+		t.Run(test.name, func(t *testing.T) {
+			if _, err := test.extractor.Extract(test.ctx, test.req); err == nil || !strings.Contains(err.Error(), test.want) {
+				t.Fatalf("Extract() error = %v, want %q", err, test.want)
+			}
+		})
+	}
+	if _, err := newExtractor(t, &fakeOccurrencesLLMClient{err: errors.New("provider unavailable")}, references).Extract(context.Background(), valid); err == nil || !strings.Contains(err.Error(), "provider unavailable") {
+		t.Fatalf("provider error = %v", err)
+	}
+}
+
+func TestModuleSpecRegistrationMetadataAndFingerprints(t *testing.T) {
+	got := ModuleSpec()
+	if got.Key != Key || got.Stage != pipeline.StageExtract || got.ArtifactKind != dnd.NPCOccurrenceListKind || !reflect.DeepEqual(got.Requires, []string{"chunks", "source.transcript"}) || !reflect.DeepEqual(got.Provides, []string{"dnd.npc_occurrences"}) {
+		t.Fatalf("ModuleSpec() = %#v", got)
+	}
+	var registrySlot contracts.ReferenceSlot
+	for _, slot := range got.ReferenceSlots {
+		if slot.Name == NPCRegistryReferenceSlot {
+			registrySlot = slot
+		}
+	}
+	if !registrySlot.Required || !reflect.DeepEqual(registrySlot.AcceptedArtifactKinds, []contracts.ArtifactKind{dnd.NPCRegistryKind}) || registrySlot.MaxBytes != NPCRegistryMaxBytes {
+		t.Fatalf("NPC registry slot = %#v", registrySlot)
+	}
+	got.ReferenceSlots[0].AcceptedMediaTypes[0] = "changed"
+	if ModuleSpec().ReferenceSlots[0].AcceptedMediaTypes[0] == "changed" {
+		t.Fatal("ModuleSpec() returned mutable reference slots")
+	}
+	extractorSlots := newExtractor(t, &fakeOccurrencesLLMClient{}).ReferenceSlots()
+	extractorSlots[0].AcceptedMediaTypes[0] = "changed"
+	if newExtractor(t, &fakeOccurrencesLLMClient{}).ReferenceSlots()[0].AcceptedMediaTypes[0] == "changed" {
+		t.Fatal("ReferenceSlots() returned mutable reference slots")
+	}
+	registry := pipeline.NewExtractorRegistry()
+	if err := Register(registry); err != nil {
+		t.Fatal(err)
+	}
+	if _, ok := registry.Spec(Key); !ok {
+		t.Fatalf("registry missing %q", Key)
+	}
+	if _, err := DecodeOptions(map[string]any{"unexpected": true}); err == nil {
+		t.Fatal("DecodeOptions() accepted unknown option")
+	}
+
+	references := requiredRegistryReferences(t, "Mira Thorn")
+	extractor := newExtractor(t, &fakeOccurrencesLLMClient{}, references)
+	metadata := extractor.ManifestMetadata()
+	for key, want := range map[string]string{
+		"prompt_id": PromptID, "prompt_version": SchemaVersion, "mapping_policy": mappingPolicy,
+		"response_schema_key": string(ResponseSchemaKey), "response_schema_id": ResponseSchemaID,
+		"response_schema_name": ResponseSchemaName, "response_schema_version": SchemaVersion,
+	} {
+		if metadata[key] != want {
+			t.Fatalf("metadata[%q] = %#v, want %q", key, metadata[key], want)
+		}
+	}
+	for _, key := range []string{"prompt_sha256", "response_schema_sha256", "npc_registry_digest"} {
+		if value, ok := metadata[key].(string); !ok || !strings.HasPrefix(value, "sha256:") {
+			t.Fatalf("metadata[%q] = %#v, want digest", key, metadata[key])
+		}
+	}
+	wantFingerprints := map[string]struct{}{"prompt": {}, "response_schema": {}, "mapping_policy": {}, "npc_registry": {}}
+	for _, fingerprint := range extractor.CheckpointFingerprints() {
+		delete(wantFingerprints, fingerprint.Name)
+	}
+	if len(wantFingerprints) != 0 {
+		t.Fatalf("missing fingerprints = %#v", wantFingerprints)
+	}
+}
+
+func extractionRequest() contracts.TypedExtractionRequest {
+	doc := sourceDocument()
+	chunk := &source.Chunk{
+		ID: "session-alpha:chunk:0", SourceID: doc.ID, Index: 0,
+		Ref:     source.SourceRef{SourceID: doc.ID, StartUnitID: 10, EndUnitID: 30},
+		Content: []byte(`{"units":[10,2,7,5,20,30]}`), MediaType: "application/json",
+		Units: append([]source.SourceUnit(nil), doc.Units...),
+	}
+	return contracts.TypedExtractionRequest{
+		Source: doc, Chunk: chunk,
+		SourceInput: contracts.NewLLMInputMaterial("source", chunk.MediaType, chunk.Content, "sha256:chunk", "file:///session-alpha.json"),
+		SessionID:   "session-123", LLMProfile: "profile-npc-occurrences",
+	}
+}
+
+func sourceDocument() *source.SourceDocument {
+	return &source.SourceDocument{
+		ID: "session-alpha", Kind: "transcript", Format: "application/vnd.seriatim.minimal+json", Digest: "sha256:source",
+		Units: []source.SourceUnit{
+			{ID: 10, Kind: "transcript_segment", Text: "Mira Thorn is mentioned."},
+			{ID: 2, Kind: "transcript_segment", Text: "Mira Thorn speaks to the party."},
+			{ID: 7, Kind: "transcript_segment", Text: "Mira Thorn watches nearby."},
+			{ID: 5, Kind: "transcript_segment", Text: "Mira Thorn joins the party in combat."},
+			{ID: 20, Kind: "transcript_segment", Text: "Mira Thorn attacks the party."},
+			{ID: 30, Kind: "transcript_segment", Text: "Mira Thorn performs a ritual."},
+		},
+	}
+}
+
+func requiredRegistryReferences(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{
+		NPCRegistryReferenceSlot: {
+			Slot:  contracts.ReferenceSlot{Name: NPCRegistryReferenceSlot},
+			Items: []contracts.ReferenceItem{{SlotName: NPCRegistryReferenceSlot, MediaType: npccodec.MediaType, Content: content, Origin: contracts.ReferenceOrigin{Type: "generated"}}},
+		},
+	}}
+}
+
+func occurrenceRefs(start, end int) []occurrenceSourceRefResponse {
+	return []occurrenceSourceRefResponse{{StartUnitID: start, EndUnitID: end}}
+}
+
+func occurrenceNames(value dnd.NPCOccurrenceList) []string {
+	names := make([]string, len(value.Occurrences))
+	for index, occurrence := range value.Occurrences {
+		names[index] = occurrence.Name
+	}
+	return names
+}
+
+func occurrenceKinds(value dnd.NPCOccurrenceList) []dnd.NPCOccurrenceKind {
+	kinds := make([]dnd.NPCOccurrenceKind, len(value.Occurrences))
+	for index, occurrence := range value.Occurrences {
+		kinds[index] = occurrence.Kind
+	}
+	return kinds
+}
+
+func mismatchedSourceInputRequest(req contracts.TypedExtractionRequest) contracts.TypedExtractionRequest {
+	req.SourceInput = contracts.NewLLMInputMaterial("source", "application/json", []byte(`{"different":true}`), "sha256:other", "")
+	return req
+}
+
+func newExtractor(t *testing.T, client contracts.StructuredLLMClient, references ...contracts.ReferenceSet) *Extractor {
+	t.Helper()
+	extractor, err := New(client, Options{}, references...)
+	if err != nil {
+		t.Fatalf("New() error = %v", err)
+	}
+	return extractor
+}
+
+type fakeOccurrencesLLMClient struct {
+	response extractionResponse
+	err      error
+	requests []contracts.StructuredCompletionRequest
+}
+
+func (client *fakeOccurrencesLLMClient) CompleteStructured(_ context.Context, req contracts.StructuredCompletionRequest, out any) (contracts.StructuredCompletionResponse, error) {
+	client.requests = append(client.requests, cloneStructuredCompletionRequest(req))
+	if client.err != nil {
+		return contracts.StructuredCompletionResponse{}, client.err
+	}
+	target, ok := out.(*extractionResponse)
+	if !ok {
+		return contracts.StructuredCompletionResponse{}, errors.New("unexpected output target")
+	}
+	*target = client.response
+	content, err := json.Marshal(client.response)
+	if err != nil {
+		return contracts.StructuredCompletionResponse{}, err
+	}
+	return contracts.StructuredCompletionResponse{Content: content}, nil
+}
+
+func cloneStructuredCompletionRequest(req contracts.StructuredCompletionRequest) contracts.StructuredCompletionRequest {
+	req.Inputs = req.Inputs.Clone()
+	return req
+}

internal/modules/dnd/extract/npcoccurrences/model.go

@@ -0,0 +1,17 @@
+package npcoccurrences
+
+type extractionResponse struct {
+	Occurrences []occurrenceResponse `json:"occurrences"`
+}
+
+type occurrenceResponse struct {
+	NPCID      string                        `json:"npc_id"`
+	Name       string                        `json:"name"`
+	Kind       string                        `json:"kind"`
+	SourceRefs []occurrenceSourceRefResponse `json:"source_refs"`
+}
+
+type occurrenceSourceRefResponse struct {
+	StartUnitID int `json:"start_unit_id"`
+	EndUnitID   int `json:"end_unit_id"`
+}

internal/modules/dnd/extract/npcoccurrences/model_test.go

@@ -0,0 +1,18 @@
+package npcoccurrences
+
+import (
+	"encoding/json"
+	"testing"
+)
+
+func TestExtractionResponsePreservesValidatorOwnedSemantics(t *testing.T) {
+	content := []byte(`{"occurrences":[{"npc_id":"","name":"","kind":"unsupported","source_refs":[{"start_unit_id":0,"end_unit_id":-1}]}]}`)
+	var response extractionResponse
+	if err := json.Unmarshal(content, &response); err != nil {
+		t.Fatalf("json.Unmarshal() error = %v", err)
+	}
+	occurrence := response.Occurrences[0]
+	if occurrence.NPCID != "" || occurrence.Name != "" || occurrence.Kind != "unsupported" || occurrence.SourceRefs[0] != (occurrenceSourceRefResponse{StartUnitID: 0, EndUnitID: -1}) {
+		t.Fatalf("decoded response = %#v", occurrence)
+	}
+}

internal/modules/dnd/extract/npcoccurrences/prompt_assets.go

@@ -0,0 +1,75 @@
+package npcoccurrences
+
+import (
+	"fmt"
+	"io/fs"
+	"sync"
+
+	rootassets "gitea.maximumdirect.net/eric/notarius/assets"
+	"gitea.maximumdirect.net/eric/notarius/internal/framework/llm"
+	"gitea.maximumdirect.net/eric/notarius/internal/framework/promptfs"
+	"gitea.maximumdirect.net/eric/notarius/internal/modules/dnd/shared"
+)
+
+const promptAssetRoot = "assets/prompts"
+
+var promptAssetManifest = shared.PromptAssetManifest{
+	ModuleDir: "dnd.npc_occurrences",
+	ModuleFiles: []promptfs.ModulePromptFile{
+		{Name: "prompt.yaml", Path: "prompts/prompt.yaml"},
+		{Name: "instructions.md", Path: "prompts/instructions.md"},
+	},
+	SharedFiles: []string{
+		"common-dnd-system.md",
+		"common-dnd-extraction-evidence.md",
+		"common-dnd-identity.md",
+		"common-dnd-transcript-chunk.md",
+		"common-dnd-references.md",
+		"common-dnd-npc-registry.md",
+	},
+}
+
+func moduleAssetFS() (fs.FS, error) {
+	assets, err := fs.Sub(rootassets.FS(), "dnd/npc-occurrences")
+	if err != nil {
+		return nil, fmt.Errorf("scope NPC-occurrence assets: %w", err)
+	}
+	return assets, nil
+}
+
+func RegisterPromptAssets(registry *llm.AssetRegistry) error {
+	assets, err := moduleAssetFS()
+	if err != nil {
+		return err
+	}
+	promptFS, err := promptAssetManifest.PromptFS(assets)
+	if err != nil {
+		return fmt.Errorf("prepare NPC-occurrence prompt assets: %w", err)
+	}
+	if err := registry.RegisterPromptFS(promptFS, promptAssetRoot); err != nil {
+		return err
+	}
+	schemas, err := fs.Sub(assets, "schemas")
+	if err != nil {
+		return fmt.Errorf("scope NPC-occurrence schemas: %w", err)
+	}
+	return registry.RegisterSchemaFS(schemas, ".")
+}
+
+func promptAssetMetadata() (string, error) {
+	promptAssetHashOnce.Do(func() {
+		assets, err := moduleAssetFS()
+		if err != nil {
+			promptAssetHashErr = err
+			return
+		}
+		promptAssetHash, promptAssetHashErr = promptAssetManifest.Hash(assets)
+	})
+	return promptAssetHash, promptAssetHashErr
+}
+
+var (
+	promptAssetHashOnce sync.Once
+	promptAssetHash     string
+	promptAssetHashErr  error
+)

internal/modules/dnd/extract/npcoccurrences/prompt_assets_test.go

@@ -0,0 +1,77 @@
+package npcoccurrences
+
+import (
+	"context"
+	"io/fs"
+	"strings"
+	"testing"
+	"time"
+
+	"gitea.maximumdirect.net/eric/notarius/internal/framework/llm"
+	"gitea.maximumdirect.net/eric/promptkit"
+)
+
+func TestRegisterPromptAssetsAndPrepareOccurrencePrompt(t *testing.T) {
+	registry := llm.NewAssetRegistry()
+	if err := RegisterPromptAssets(registry); err != nil {
+		t.Fatal(err)
+	}
+	schemaFS, err := registry.SchemaFS()
+	if err != nil {
+		t.Fatal(err)
+	}
+	if _, err := fs.ReadFile(schemaFS, "dnd_npc_occurrences_llm.v1.json"); err != nil {
+		t.Fatalf("response schema asset: %v", err)
+	}
+	options, err := registry.PromptKitOptions()
+	if err != nil {
+		t.Fatal(err)
+	}
+	options = append(options, promptkit.WithProfiles(promptkit.OpenAICompatibleProfile(promptkit.OpenAICompatibleProfileConfig{
+		ID: "npc-occurrences-test-profile", Endpoint: "http://127.0.0.1:1/v1", Model: "npc-occurrences-test-model",
+	})))
+	engine, err := promptkit.NewEngine(promptkit.Config{Timeout: time.Second}, options...)
+	if err != nil {
+		t.Fatal(err)
+	}
+	transcript := `{"units":[{"sentinel":"occurrence-transcript"}]}`
+	prepared, err := engine.Prepare(context.Background(), promptkit.RunRequest{
+		PromptID: PromptID, PromptVersion: SchemaVersion, ProfileID: "npc-occurrences-test-profile",
+		Inputs: map[string]promptkit.ArtifactRef{
+			"transcript":   promptkit.InlineWithURI("file:///session.json", transcript),
+			"players":      promptkit.Inline("occurrence-player"),
+			"party":        promptkit.Inline("Mira: ranger"),
+			"glossary":     promptkit.Inline("Greencloak: title"),
+			"npc_registry": promptkit.Inline(`{"npcs":[{"id":"npc:sha256:test","name":"occurrence-npc"}]}`),
+		},
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if prepared.PromptID != PromptID || prepared.OutputContract.SchemaPath != "dnd_npc_occurrences_llm.v1.json" {
+		t.Fatalf("prepared prompt = %#v", prepared)
+	}
+}
+
+func TestPromptMetadataDoesNotExposeAssetContent(t *testing.T) {
+	hash, err := promptAssetMetadata()
+	if err != nil || !strings.HasPrefix(hash, "sha256:") {
+		t.Fatalf("promptAssetMetadata() = %q, %v", hash, err)
+	}
+	metadata := newExtractor(t, &fakeOccurrencesLLMClient{}).ManifestMetadata()
+	for _, forbidden := range []string{"common-dnd-system", "dnd_npc_occurrences_llm.v1.json"} {
+		if strings.Contains(strings.Join(mapValues(metadata), " "), forbidden) {
+			t.Fatalf("metadata leaked prompt or schema content %q: %#v", forbidden, metadata)
+		}
+	}
+}
+
+func mapValues(values map[string]any) []string {
+	out := make([]string, 0, len(values))
+	for _, value := range values {
+		if text, ok := value.(string); ok {
+			out = append(out, text)
+		}
+	}
+	return out
+}

internal/modules/dnd/extract/npcoccurrences/schema.go

@@ -0,0 +1,25 @@
+package npcoccurrences
+
+import "gitea.maximumdirect.net/eric/notarius/internal/framework/llm"
+
+const (
+	PromptID           = "dnd.npc_occurrences"
+	ResponseSchemaKey  = llm.ResponseSchemaKey("dnd_npc_occurrences_llm")
+	ResponseSchemaID   = "notarius.dnd.npc_occurrences.llm"
+	ResponseSchemaName = "notarius_dnd_npc_occurrences_llm_v1"
+	SchemaVersion      = "v1"
+)
+
+func loadResponseSchema() (llm.ResponseSchema, error) {
+	assets, err := moduleAssetFS()
+	if err != nil {
+		return llm.ResponseSchema{}, err
+	}
+	return llm.LoadResponseSchema(assets, llm.ResponseSchemaDefinition{
+		Key:       ResponseSchemaKey,
+		ID:        ResponseSchemaID,
+		Version:   SchemaVersion,
+		Name:      ResponseSchemaName,
+		AssetPath: "schemas/dnd_npc_occurrences_llm.v1.json",
+	})
+}

internal/modules/dnd/extract/npcoccurrences/schema_test.go

@@ -0,0 +1,107 @@
+package npcoccurrences
+
+import (
+	"bytes"
+	"encoding/json"
+	"strings"
+	"testing"
+
+	"github.com/santhosh-tekuri/jsonschema/v6"
+)
+
+func TestResponseSchemaOwnsOnlyPrivateStructuralContract(t *testing.T) {
+	schema, err := loadResponseSchema()
+	if err != nil {
+		t.Fatal(err)
+	}
+	if schema.Key != ResponseSchemaKey || schema.ID != ResponseSchemaID || schema.Name != ResponseSchemaName || schema.Version != SchemaVersion || !strings.HasPrefix(schema.SHA256, "sha256:") || !json.Valid(schema.JSONSchema) {
+		t.Fatalf("schema = %#v", schema)
+	}
+	valid := validOccurrenceResponse()
+	content, err := json.Marshal(valid)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if err := validateJSONSchema(content, schema.JSONSchema); err != nil {
+		t.Fatalf("valid response rejected: %v", err)
+	}
+
+	semanticCandidate := validOccurrenceResponse()
+	occurrence := semanticCandidate["occurrences"].([]any)[0].(map[string]any)
+	occurrence["name"] = ""
+	occurrence["kind"] = "unsupported"
+	ref := occurrence["source_refs"].([]any)[0].(map[string]any)
+	ref["start_unit_id"] = 0
+	ref["end_unit_id"] = -1
+	content, err = json.Marshal(semanticCandidate)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if err := validateJSONSchema(content, schema.JSONSchema); err != nil {
+		t.Fatalf("schema rejected validator-owned semantics: %v", err)
+	}
+
+	for _, mutate := range []func(map[string]any){
+		func(record map[string]any) { delete(record, "npc_id") },
+		func(record map[string]any) { delete(record, "name") },
+		func(record map[string]any) { record["kind"] = 1 },
+		func(record map[string]any) { record["unexpected"] = true },
+		func(record map[string]any) {
+			record["source_refs"].([]any)[0].(map[string]any)["source_id"] = "assigned later"
+		},
+	} {
+		candidate := validOccurrenceResponse()
+		mutate(candidate["occurrences"].([]any)[0].(map[string]any))
+		content, err := json.Marshal(candidate)
+		if err != nil {
+			t.Fatal(err)
+		}
+		if err := validateJSONSchema(content, schema.JSONSchema); err == nil {
+			t.Fatal("schema accepted structurally invalid response")
+		}
+	}
+}
+
+func TestResponseSchemaIsDefensiveAndContentSafe(t *testing.T) {
+	first, err := loadResponseSchema()
+	if err != nil {
+		t.Fatal(err)
+	}
+	first.JSONSchema[0] = '['
+	second, err := loadResponseSchema()
+	if err != nil || !json.Valid(second.JSONSchema) || bytes.Equal(first.JSONSchema, second.JSONSchema) {
+		t.Fatalf("second schema = %s, %v", second.JSONSchema, err)
+	}
+	if diagnostics := second.DiagnosticsMap(); diagnostics["key"] != ResponseSchemaKey || diagnostics["id"] != ResponseSchemaID {
+		t.Fatalf("diagnostics = %#v", diagnostics)
+	} else if _, ok := diagnostics["json_schema"]; ok {
+		t.Fatalf("diagnostics leak schema content: %#v", diagnostics)
+	}
+}
+
+func validOccurrenceResponse() map[string]any {
+	return map[string]any{"occurrences": []any{map[string]any{
+		"npc_id": "npc:sha256:test", "name": "Mira Thorn", "kind": "dialogue",
+		"source_refs": []any{map[string]any{"start_unit_id": 1, "end_unit_id": 2}},
+	}}}
+}
+
+func validateJSONSchema(instanceContent, schemaContent []byte) error {
+	instance, err := jsonschema.UnmarshalJSON(bytes.NewReader(instanceContent))
+	if err != nil {
+		return err
+	}
+	schemaDocument, err := jsonschema.UnmarshalJSON(bytes.NewReader(schemaContent))
+	if err != nil {
+		return err
+	}
+	compiler := jsonschema.NewCompiler()
+	if err := compiler.AddResource("schema.json", schemaDocument); err != nil {
+		return err
+	}
+	schema, err := compiler.Compile("schema.json")
+	if err != nil {
+		return err
+	}
+	return schema.Validate(instance)
+}