Add NPC registry grounding for spell extraction

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

@@ -4,6 +4,7 @@ import (
 	"bytes"
 	"context"
 	"fmt"
+	"sort"
 
 	"gitea.maximumdirect.net/eric/notarius/internal/framework/contracts"
 	"gitea.maximumdirect.net/eric/notarius/internal/framework/pipeline"
@@ -34,12 +35,19 @@ var referenceSlotDescriptions = shared.ReferenceSlotDescriptions{
 
 func referenceSlots() []contracts.ReferenceSlot {
 	slots := shared.ReferenceSlots(referenceSlotDescriptions)
-	return append(slots, contracts.ReferenceSlot{
+	slots = append(slots, contracts.ReferenceSlot{
 		Name:               spellcatalog.SpellCatalogReferenceSlot,
 		Description:        "Optional canonical spell-name catalog used for extraction grounding.",
 		AcceptedMediaTypes: []string{"application/json"},
 		MaxBytes:           1048576,
+	}, contracts.ReferenceSlot{
+		Name:               NPCRegistryReferenceSlot,
+		Description:        "Optional normalized NPC registry used for canonical caster-name grounding.",
+		AcceptedMediaTypes: []string{"application/json"},
+		MaxBytes:           NPCRegistryMaxBytes,
 	})
+	sort.Slice(slots, func(i, j int) bool { return slots[i].Name < slots[j].Name })
+	return slots
 }
 
 var _ contracts.Extractor[dnd.SpellList] = (*Extractor)(nil)
@@ -51,6 +59,7 @@ type Extractor struct {
 	llm                contracts.StructuredLLMClient
 	effectiveCatalog   spellcatalog.EffectiveCatalog
 	catalogPromptInput contracts.LLMInputMaterial
+	npcRegistry        npcRegistryPromptInput
 	promptSHA          string
 	responseSchemaSHA  string
 }
@@ -74,6 +83,10 @@ func New(llmClient contracts.StructuredLLMClient, _ Options, references ...contr
 	if err != nil {
 		return nil, extractorErrorf("prepare spell catalog prompt input: %w", err)
 	}
+	npcRegistry, err := resolveNPCRegistry(referenceSet)
+	if err != nil {
+		return nil, extractorErrorf("prepare NPC registry prompt input: %w", err)
+	}
 	promptSHA, err := scriptoriumPromptMetadata()
 	if err != nil {
 		return nil, extractorErrorf("load prompt metadata: %w", err)
@@ -86,6 +99,7 @@ func New(llmClient contracts.StructuredLLMClient, _ Options, references ...contr
 		llm:                llmClient,
 		effectiveCatalog:   effectiveCatalog,
 		catalogPromptInput: catalogPromptInput,
+		npcRegistry:        npcRegistry,
 		promptSHA:          promptSHA,
 		responseSchemaSHA:  responseSchema.SHA256,
 	}, nil
@@ -113,6 +127,10 @@ func (e *Extractor) ManifestMetadata() map[string]any {
 		"response_schema_version": SchemaVersion,
 		"response_schema_sha256":  e.responseSchemaSHA,
 	}
+	if e.npcRegistry.bound {
+		metadata["npc_registry_digest"] = e.npcRegistry.digest
+		metadata["npc_count"] = e.npcRegistry.count
+	}
 	return metadata
 }
 
@@ -120,11 +138,15 @@ func (e *Extractor) CheckpointFingerprints() []pipeline.CheckpointFingerprint {
 	if e == nil {
 		return nil
 	}
-	return []pipeline.CheckpointFingerprint{
+	fingerprints := []pipeline.CheckpointFingerprint{
 		{Name: "effective_catalog", Value: e.effectiveCatalog.Digest()},
 		{Name: "prompt", Value: e.promptSHA},
 		{Name: "response_schema", Value: e.responseSchemaSHA},
 	}
+	if e.npcRegistry.bound {
+		fingerprints = append(fingerprints, pipeline.CheckpointFingerprint{Name: "npc_registry", Value: e.npcRegistry.digest})
+	}
+	return fingerprints
 }
 
 func (e *Extractor) Extract(ctx context.Context, req contracts.TypedExtractionRequest) (contracts.TypedExtractionResult[dnd.SpellList], error) {
@@ -157,6 +179,7 @@ func (e *Extractor) Extract(ctx context.Context, req contracts.TypedExtractionRe
 	var response extractionResponse
 	inputs := shared.PromptInputs(sourceInput, req.References)
 	inputs[spellcatalog.SpellCatalogReferenceSlot] = e.catalogPromptInput.Clone()
+	inputs[NPCRegistryReferenceSlot] = e.npcRegistry.input.Clone()
 	if _, err := e.llm.CompleteStructured(ctx, contracts.StructuredCompletionRequest{
 		StageName:     Key,
 		PromptID:      PromptID,