Move item occurrences to canonical namespace

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

@@ -0,0 +1,105 @@
+package itemoccurrences
+
+import (
+	"sort"
+
+	"gitea.maximumdirect.net/eric/notarius/internal/core/source"
+	"gitea.maximumdirect.net/eric/notarius/internal/modules/dnd"
+	itemregistry "gitea.maximumdirect.net/eric/notarius/internal/modules/dnd/items/registry"
+	"gitea.maximumdirect.net/eric/notarius/internal/modules/dnd/shared"
+)
+
+type orderedItemOccurrenceResponse struct {
+	value       itemOccurrenceResponse
+	earliest    int
+	hasEvidence bool
+}
+
+func canonicalizeResponse(response *extractionResponse, order shared.SourceRefOrder, sourceID string) {
+	if response == nil {
+		return
+	}
+	ordered := make([]orderedItemOccurrenceResponse, len(response.Occurrences))
+	for index := range response.Occurrences {
+		earliest, hasEvidence := canonicalizeItemOccurrence(&response.Occurrences[index], order, sourceID)
+		ordered[index] = orderedItemOccurrenceResponse{
+			value:       response.Occurrences[index],
+			earliest:    earliest,
+			hasEvidence: hasEvidence,
+		}
+	}
+	sort.SliceStable(ordered, func(left, right int) bool {
+		if ordered[left].hasEvidence != ordered[right].hasEvidence {
+			return ordered[left].hasEvidence
+		}
+		if !ordered[left].hasEvidence {
+			return false
+		}
+		return ordered[left].earliest < ordered[right].earliest
+	})
+	for index := range ordered {
+		response.Occurrences[index] = ordered[index].value
+	}
+}
+
+func canonicalizeItemOccurrence(occurrence *itemOccurrenceResponse, order shared.SourceRefOrder, sourceID string) (int, bool) {
+	if occurrence == nil {
+		return 0, false
+	}
+	refs := order.Canonicalize(itemOccurrenceSourceRefs(occurrence.SourceRefs, sourceID))
+	occurrence.SourceRefs = itemOccurrenceResponseRefs(refs)
+	return order.EarliestValid(refs)
+}
+
+func canonicalItemOccurrenceList(response extractionResponse, sourceID string, registry *itemregistry.Registry) dnd.ItemOccurrenceList {
+	if response.Occurrences == nil {
+		return dnd.ItemOccurrenceList{}
+	}
+	occurrences := make([]dnd.ItemOccurrence, 0, len(response.Occurrences))
+	for _, occurrence := range response.Occurrences {
+		item, found := registry.LookupID(occurrence.ItemID)
+		if !found || item.Name != occurrence.Name {
+			continue
+		}
+		occurrences = append(occurrences, dnd.ItemOccurrence{
+			ItemID:     occurrence.ItemID,
+			Name:       occurrence.Name,
+			Kind:       dnd.ItemOccurrenceKind(occurrence.Kind),
+			Quantity:   cloneQuantity(occurrence.Quantity),
+			From:       occurrence.From,
+			To:         occurrence.To,
+			SourceRefs: itemOccurrenceSourceRefs(occurrence.SourceRefs, sourceID),
+		})
+	}
+	return dnd.ItemOccurrenceList{Occurrences: occurrences}
+}
+
+func itemOccurrenceSourceRefs(refs []itemOccurrenceSourceRefResponse, sourceID string) []source.SourceRef {
+	if refs == nil {
+		return nil
+	}
+	values := make([]source.SourceRef, len(refs))
+	for index, ref := range refs {
+		values[index] = source.SourceRef{SourceID: sourceID, StartUnitID: ref.StartSegment, EndUnitID: ref.EndSegment}
+	}
+	return values
+}
+
+func itemOccurrenceResponseRefs(refs []source.SourceRef) []itemOccurrenceSourceRefResponse {
+	if refs == nil {
+		return nil
+	}
+	values := make([]itemOccurrenceSourceRefResponse, len(refs))
+	for index, ref := range refs {
+		values[index] = itemOccurrenceSourceRefResponse{StartSegment: ref.StartUnitID, EndSegment: ref.EndUnitID}
+	}
+	return values
+}
+
+func cloneQuantity(value *int) *int {
+	if value == nil {
+		return nil
+	}
+	quantity := *value
+	return &quantity
+}

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

@@ -0,0 +1,202 @@
+// Package itemoccurrences extracts source-grounded D&D item occurrences.
+package itemoccurrences
+
+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"
+	itemregistry "gitea.maximumdirect.net/eric/notarius/internal/modules/dnd/items/registry"
+	"gitea.maximumdirect.net/eric/notarius/internal/modules/dnd/shared"
+)
+
+const Key = "dnd/item-occurrences"
+
+const (
+	ItemRegistryReferenceSlot = itemregistry.ReferenceSlot
+	ItemRegistryMaxBytes      = itemregistry.MaxBytes
+)
+
+const mappingPolicy = "dnd.item_occurrences.extract_mapping.v1"
+
+var requiredCapabilities = []string{
+	"chunks",
+	"source.transcript",
+}
+
+var providedCapabilities = []string{
+	"dnd.item_occurrences",
+}
+
+var referenceSlotDescriptions = shared.ReferenceSlotDescriptions{
+	Glossary: "Optional campaign glossary reference material used only for item and holder disambiguation.",
+	Party:    "Optional party roster reference material used only for item and holder disambiguation.",
+	Players:  "Optional player list reference material used only for item and holder disambiguation.",
+	Roster:   "Deprecated alias for party roster reference material used only for item and holder disambiguation.",
+}
+
+func referenceSlots() []contracts.ReferenceSlot {
+	slots := shared.ReferenceSlots(referenceSlotDescriptions)
+	slots = append(slots, contracts.ReferenceSlot{
+		Name:                  ItemRegistryReferenceSlot,
+		Description:           "Required normalized item registry used only for item identity grounding, never as occurrence evidence.",
+		Required:              true,
+		AcceptedMediaTypes:    []string{"application/json"},
+		AcceptedArtifactKinds: []contracts.ArtifactKind{dnd.ItemRegistryKind},
+		MaxBytes:              ItemRegistryMaxBytes,
+	})
+	sort.Slice(slots, func(left, right int) bool { return slots[left].Name < slots[right].Name })
+	return slots
+}
+
+var _ contracts.Extractor[dnd.ItemOccurrenceList] = (*Extractor)(nil)
+var _ contracts.ManifestMetadataProvider = (*Extractor)(nil)
+var _ pipeline.CheckpointFingerprintProvider = (*Extractor)(nil)
+
+type Options struct{}
+
+type Extractor struct {
+	llm               contracts.StructuredLLMClient
+	itemResolver      *itemregistry.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]
+	}
+	itemResolver, err := itemregistry.NewResolver(referenceSet)
+	if err != nil {
+		return nil, extractorErrorf("prepare item 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, itemResolver: itemResolver, 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,
+		"response_schema_key":     string(ResponseSchemaKey),
+		"response_schema_id":      ResponseSchemaID,
+		"response_schema_name":    ResponseSchemaName,
+		"response_schema_version": SchemaVersion,
+		"response_schema_sha256":  e.responseSchemaSHA,
+		"mapping_policy":          mappingPolicy,
+	}
+	seeded := e.itemResolver.Seeded()
+	if seeded.Bound() {
+		metadata["item_registry_digest"] = seeded.Digest()
+		metadata["item_count"] = seeded.Count()
+	}
+	return metadata
+}
+
+func (e *Extractor) CheckpointFingerprints() []pipeline.CheckpointFingerprint {
+	if e == nil {
+		return nil
+	}
+	return []pipeline.CheckpointFingerprint{
+		{Name: "prompt", Value: e.promptSHA},
+		{Name: "response_schema", Value: e.responseSchemaSHA},
+		{Name: "mapping_policy", Value: mappingPolicy},
+		{Name: "item_registry", Value: e.itemResolver.Seeded().ProjectionDigest()},
+	}
+}
+
+func (e *Extractor) Extract(ctx context.Context, req contracts.TypedExtractionRequest) (contracts.TypedExtractionResult[dnd.ItemOccurrenceList], error) {
+	if e == nil {
+		return contracts.TypedExtractionResult[dnd.ItemOccurrenceList]{}, extractorErrorf("extractor must not be nil")
+	}
+	if e.llm == nil {
+		return contracts.TypedExtractionResult[dnd.ItemOccurrenceList]{}, extractorErrorf("LLM client must not be nil")
+	}
+	sourceInput, err := shared.PrepareChunkExtraction(ctx, req)
+	if err != nil {
+		return contracts.TypedExtractionResult[dnd.ItemOccurrenceList]{}, extractorErrorf("%w", err)
+	}
+	order := shared.NewSourceRefOrder(req.Source)
+
+	registry, err := e.itemResolver.Resolve(req.References)
+	if err != nil {
+		return contracts.TypedExtractionResult[dnd.ItemOccurrenceList]{}, extractorErrorf("resolve item registry: %w", err)
+	}
+	if !registry.Bound() {
+		return contracts.TypedExtractionResult[dnd.ItemOccurrenceList]{}, extractorErrorf("item registry reference is required")
+	}
+	var response extractionResponse
+	inputs := shared.PromptInputs(sourceInput, req.References)
+	inputs[ItemRegistryReferenceSlot] = registry.PromptInput()
+	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.ItemOccurrenceList]{}, extractorErrorf("complete structured output: %w", err)
+	}
+	canonicalizeResponse(&response, order, req.Source.ID)
+	return contracts.TypedExtractionResult[dnd.ItemOccurrenceList]{Value: canonicalItemOccurrenceList(response, req.Source.ID, registry)}, 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.ItemOccurrenceListKind,
+		ReferenceSlots: referenceSlots(),
+	}
+}
+
+func Register(registry *pipeline.ExtractorRegistry) error {
+	return pipeline.RegisterExtractorBuilder(registry, ModuleSpec(), validateOptions, func(request pipeline.BuildRequest) (contracts.Extractor[dnd.ItemOccurrenceList], 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 item occurrences extractor: "+format, args...)
+}

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

@@ -0,0 +1,62 @@
+package itemoccurrences
+
+import (
+	"context"
+	"testing"
+
+	"gitea.maximumdirect.net/eric/notarius/internal/framework/contracts"
+	itemidentity "gitea.maximumdirect.net/eric/notarius/internal/modules/dnd/items/identity"
+)
+
+func TestExtractGroundsOccurrencesInRequiredRegistry(t *testing.T) {
+	id := itemidentity.DeriveID("Torch")
+	client := &fakeItemOccurrencesLLMClient{response: extractionResponse{Occurrences: []itemOccurrenceResponse{
+		{ItemID: id, Name: "Torch", Kind: "lost", From: "party", SourceRefs: responseRefs(1, 1)},
+		{ItemID: "unknown", Name: "Unknown", Kind: "lost", From: "party", SourceRefs: responseRefs(2, 2)},
+		{ItemID: "torch", Name: "Lantern", Kind: "lost", From: "party", SourceRefs: responseRefs(3, 3)},
+	}}}
+	req := extractionRequest()
+	req.References = itemRegistryReferences(t)
+	result, err := newExtractor(t, client, req.References).Extract(context.Background(), req)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(result.Value.Occurrences) != 1 || result.Value.Occurrences[0].ItemID != id || result.Value.Occurrences[0].Name != "Torch" {
+		t.Fatalf("occurrences = %#v", result.Value.Occurrences)
+	}
+	input := client.requests[0].Inputs[ItemRegistryReferenceSlot]
+	if input.Name != ItemRegistryReferenceSlot || string(input.Content) == "" {
+		t.Fatalf("registry prompt input = %#v", input)
+	}
+}
+
+func TestExtractRequiresItemRegistry(t *testing.T) {
+	_, err := newExtractor(t, &fakeItemOccurrencesLLMClient{}).Extract(context.Background(), extractionRequest())
+	if err == nil {
+		t.Fatal("Extract() error = nil, want required registry error")
+	}
+}
+
+func TestExtractPreservesNullableFields(t *testing.T) {
+	id := itemidentity.DeriveID("Torch")
+	client := &fakeItemOccurrencesLLMClient{content: []byte(`{"occurrences":[{"item_id":"` + id + `","name":"Torch","kind":"discovered","quantity":null,"from":null,"to":null,"source_refs":[{"start_segment":1,"end_segment":1}]}]}`)}
+	req := extractionRequest()
+	req.References = itemRegistryReferences(t)
+	result, err := newExtractor(t, client, req.References).Extract(context.Background(), req)
+	if err != nil || len(result.Value.Occurrences) != 1 || result.Value.Occurrences[0].Quantity != nil || result.Value.Occurrences[0].From != "" || result.Value.Occurrences[0].To != "" {
+		t.Fatalf("result = %#v, %v", result, err)
+	}
+}
+
+func TestExtractUsesOnlySupportedPromptInputs(t *testing.T) {
+	client := &fakeItemOccurrencesLLMClient{response: extractionResponse{Occurrences: []itemOccurrenceResponse{}}}
+	req := extractionRequest()
+	req.References = itemRegistryReferences(t)
+	req.References.Slots["unrelated"] = contracts.ResolvedReferenceSlot{Slot: contracts.ReferenceSlot{Name: "unrelated"}, Items: []contracts.ReferenceItem{{SlotName: "unrelated", Content: []byte("ignored")}}}
+	if _, err := newExtractor(t, client, req.References).Extract(context.Background(), req); err != nil {
+		t.Fatal(err)
+	}
+	if _, ok := client.requests[0].Inputs["unrelated"]; ok {
+		t.Fatalf("unexpected prompt input: %#v", client.requests[0].Inputs)
+	}
+}

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

@@ -0,0 +1,20 @@
+package itemoccurrences
+
+type extractionResponse struct {
+	Occurrences []itemOccurrenceResponse `json:"occurrences"`
+}
+
+type itemOccurrenceResponse struct {
+	ItemID     string                            `json:"item_id"`
+	Name       string                            `json:"name"`
+	Kind       string                            `json:"kind"`
+	Quantity   *int                              `json:"quantity,omitempty"`
+	From       string                            `json:"from,omitempty"`
+	To         string                            `json:"to,omitempty"`
+	SourceRefs []itemOccurrenceSourceRefResponse `json:"source_refs"`
+}
+
+type itemOccurrenceSourceRefResponse struct {
+	StartSegment int `json:"start_segment"`
+	EndSegment   int `json:"end_segment"`
+}

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

@@ -0,0 +1,75 @@
+package itemoccurrences
+
+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.item_occurrences",
+	ModuleFiles: []promptfs.ModulePromptFile{
+		{Name: "prompt.yaml", Path: "prompts/prompt.yaml"},
+		{Name: "instructions.md", Path: "prompts/instructions.md"},
+		{Name: "item-registry.md", Path: "prompts/item-registry.md"},
+	},
+	SharedFiles: []string{
+		"common-dnd-system.md",
+		"common-dnd-extraction-evidence.md",
+		"common-dnd-identity.md",
+		"common-dnd-references.md",
+		"common-dnd-transcript-chunk.md",
+	},
+}
+
+func moduleAssetFS() (fs.FS, error) {
+	assets, err := fs.Sub(rootassets.FS(), "dnd/item-occurrences")
+	if err != nil {
+		return nil, fmt.Errorf("scope item-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 item 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 item-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/itemoccurrences/prompt_assets_test.go

@@ -0,0 +1,63 @@
+package itemoccurrences
+
+import (
+	"context"
+	"encoding/json"
+	"strings"
+	"testing"
+	"time"
+
+	"gitea.maximumdirect.net/eric/notarius/internal/framework/llm"
+	"gitea.maximumdirect.net/eric/promptkit"
+)
+
+func TestPromptAssetsPrepareItemOccurrencePrompt(t *testing.T) {
+	registry := llm.NewAssetRegistry()
+	if err := RegisterPromptAssets(registry); err != nil {
+		t.Fatal(err)
+	}
+	options, err := registry.PromptKitOptions()
+	if err != nil {
+		t.Fatal(err)
+	}
+	options = append(options, promptkit.WithProfiles(promptkit.OpenAICompatibleProfile(promptkit.OpenAICompatibleProfileConfig{
+		ID: "item-occurrences-test-profile", Endpoint: "http://127.0.0.1:1/v1", Model: "item-occurrences-test-model",
+	})))
+	engine, err := promptkit.NewEngine(promptkit.Config{Timeout: time.Second}, options...)
+	if err != nil {
+		t.Fatal(err)
+	}
+	prepared, err := engine.Prepare(context.Background(), promptkit.RunRequest{
+		PromptID: PromptID, PromptVersion: SchemaVersion, ProfileID: "item-occurrences-test-profile",
+		Inputs: map[string]promptkit.ArtifactRef{
+			"transcript":    promptkit.InlineWithURI("file:///session.json", `{"units":[{"sentinel":"item-occurrence-transcript"}]}`),
+			"players":       promptkit.Inline("item-occurrence-player"),
+			"party":         promptkit.Inline(" "),
+			"glossary":      promptkit.Inline(" "),
+			"item_registry": promptkit.Inline(`{"items":[{"id":"item:sha256:test","name":"Torch"}]}`),
+		},
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if prepared.PromptID != PromptID || prepared.OutputContract.SchemaPath != "dnd_item_occurrences_llm.v1.json" {
+		t.Fatalf("prepared prompt = %#v", prepared)
+	}
+}
+
+func TestPromptAssetsDoNotLeakIntoMetadata(t *testing.T) {
+	hash, err := promptAssetMetadata()
+	if err != nil || !strings.HasPrefix(hash, "sha256:") {
+		t.Fatalf("promptAssetMetadata() = %q, %v", hash, err)
+	}
+	metadata := newExtractor(t, &fakeItemOccurrencesLLMClient{}).ManifestMetadata()
+	payload, err := json.Marshal(metadata)
+	if err != nil {
+		t.Fatal(err)
+	}
+	for _, forbidden := range []string{"common-dnd-system", "dnd_item_occurrences_llm.v1.json"} {
+		if strings.Contains(string(payload), forbidden) {
+			t.Fatalf("metadata leaked raw asset content %q: %s", forbidden, payload)
+		}
+	}
+}

internal/modules/dnd/extract/itemoccurrences/registry_test.go

@@ -0,0 +1,43 @@
+package itemoccurrences
+
+import (
+	"reflect"
+	"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"
+	itemcodec "gitea.maximumdirect.net/eric/notarius/internal/modules/dnd/codec/itemregistry"
+	itemidentity "gitea.maximumdirect.net/eric/notarius/internal/modules/dnd/items/identity"
+)
+
+func itemRegistryReferences(t *testing.T) contracts.ReferenceSet {
+	t.Helper()
+	content, err := itemcodec.New().Encode(dnd.ItemRegistry{Items: []dnd.Item{{ID: itemidentity.DeriveID("Torch"), Name: "Torch", SourceRefs: testSourceRefs()}}})
+	if err != nil {
+		t.Fatal(err)
+	}
+	return contracts.ReferenceSet{Slots: map[string]contracts.ResolvedReferenceSlot{ItemRegistryReferenceSlot: {Slot: contracts.ReferenceSlot{Name: ItemRegistryReferenceSlot}, Items: []contracts.ReferenceItem{{SlotName: ItemRegistryReferenceSlot, Content: content, MediaType: "application/json", ArtifactKind: dnd.ItemRegistryKind}}}}}
+}
+
+func testSourceRefs() []source.SourceRef {
+	return []source.SourceRef{{SourceID: "session-alpha", StartUnitID: 1, EndUnitID: 1}}
+}
+
+func TestModuleSpecDeclaresRequiredRegistry(t *testing.T) {
+	spec := ModuleSpec()
+	var slot contracts.ReferenceSlot
+	for _, candidate := range spec.ReferenceSlots {
+		if candidate.Name == ItemRegistryReferenceSlot {
+			slot = candidate
+		}
+	}
+	if !slot.Required || !reflect.DeepEqual(slot.AcceptedArtifactKinds, []contracts.ArtifactKind{dnd.ItemRegistryKind}) || slot.MaxBytes != ItemRegistryMaxBytes {
+		t.Fatalf("registry slot = %#v", slot)
+	}
+	registry := pipeline.NewExtractorRegistry()
+	if err := Register(registry); err != nil {
+		t.Fatal(err)
+	}
+}

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

@@ -0,0 +1,25 @@
+package itemoccurrences
+
+import "gitea.maximumdirect.net/eric/notarius/internal/framework/llm"
+
+const (
+	PromptID           = "dnd.item_occurrences"
+	ResponseSchemaKey  = llm.ResponseSchemaKey("dnd_item_occurrences_llm")
+	ResponseSchemaID   = "notarius.dnd.item_occurrences.llm"
+	ResponseSchemaName = "notarius_dnd_item_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_item_occurrences_llm.v1.json",
+	})
+}

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

@@ -0,0 +1,103 @@
+package itemoccurrences
+
+import (
+	"bytes"
+	"encoding/json"
+	"strings"
+	"testing"
+
+	"github.com/santhosh-tekuri/jsonschema/v6"
+)
+
+func TestResponseSchemaIsStrictlyStructuralAndPrivate(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 := map[string]any{"occurrences": []any{
+		map[string]any{
+			"item_id": "item:sha256:test", "name": "", "kind": "unsupported", "quantity": 0, "from": "party", "to": "Party",
+			"source_refs": []any{map[string]any{"start_segment": 0, "end_segment": -1}},
+		},
+		map[string]any{
+			"item_id": "item:sha256:test", "name": "Hidden Cache", "kind": "discovered", "quantity": nil, "from": nil, "to": nil,
+			"source_refs": []any{map[string]any{"start_segment": 1, "end_segment": 1}},
+		},
+	}}
+	content, err := json.Marshal(valid)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if err := validateJSONSchema(content, schema.JSONSchema); err != nil {
+		t.Fatalf("private schema rejected validator-owned values: %v", err)
+	}
+	for _, test := range []struct {
+		name  string
+		value map[string]any
+	}{
+		{"missing occurrences", map[string]any{}},
+		{"missing occurrence name", map[string]any{"occurrences": []any{withoutField(responseOccurrence(), "name")}}},
+		{"missing nullable field", map[string]any{"occurrences": []any{withoutField(responseOccurrence(), "quantity")}}},
+		{"unknown occurrence field", map[string]any{"occurrences": []any{withField(responseOccurrence(), "extra", true)}}},
+		{"unknown reference field", map[string]any{"occurrences": []any{withField(responseOccurrence(), "source_refs", []any{map[string]any{"start_segment": 1, "end_segment": 1, "extra": true}})}}},
+		{"noninteger range", map[string]any{"occurrences": []any{withField(responseOccurrence(), "source_refs", []any{map[string]any{"start_segment": 1.5, "end_segment": 1}})}}},
+	} {
+		t.Run(test.name, func(t *testing.T) {
+			content, err := json.Marshal(test.value)
+			if err != nil {
+				t.Fatal(err)
+			}
+			if err := validateJSONSchema(content, schema.JSONSchema); err == nil {
+				t.Fatal("private schema accepted invalid structure")
+			}
+		})
+	}
+	first := schema.JSONSchema
+	first[0] = '['
+	second, err := loadResponseSchema()
+	if err != nil || !json.Valid(second.JSONSchema) || bytes.Equal(first, second.JSONSchema) {
+		t.Fatalf("defensive schema copy = %s, %v", second.JSONSchema, err)
+	}
+	if _, ok := second.DiagnosticsMap()["json_schema"]; ok {
+		t.Fatalf("schema diagnostics leaked content: %#v", second.DiagnosticsMap())
+	}
+}
+
+func responseOccurrence() map[string]any {
+	return map[string]any{
+		"item_id": "item:sha256:test", "name": "Ring", "kind": "acquired", "quantity": nil, "from": nil, "to": "party", "source_refs": []any{},
+	}
+}
+
+func withoutField(value map[string]any, name string) map[string]any {
+	delete(value, name)
+	return value
+}
+
+func withField(value map[string]any, name string, fieldValue any) map[string]any {
+	value[name] = fieldValue
+	return value
+}
+
+func validateJSONSchema(instanceContent, schemaContent []byte) error {
+	instance, err := jsonschema.UnmarshalJSON(bytes.NewReader(instanceContent))
+	if err != nil {
+		return err
+	}
+	document, err := jsonschema.UnmarshalJSON(bytes.NewReader(schemaContent))
+	if err != nil {
+		return err
+	}
+	compiler := jsonschema.NewCompiler()
+	if err := compiler.AddResource("schema.json", document); err != nil {
+		return err
+	}
+	compiled, err := compiler.Compile("schema.json")
+	if err != nil {
+		return err
+	}
+	return compiled.Validate(instance)
+}

internal/modules/dnd/extract/itemoccurrences/test_helpers_test.go

@@ -0,0 +1,92 @@
+package itemoccurrences
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"testing"
+
+	"gitea.maximumdirect.net/eric/notarius/internal/core/source"
+	"gitea.maximumdirect.net/eric/notarius/internal/framework/contracts"
+)
+
+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: 1, EndUnitID: 5},
+		Content:   []byte(`{"segments":[1,2,3,4,5]}`),
+		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-item-occurrences",
+	}
+}
+
+func sourceDocument() *source.SourceDocument {
+	return &source.SourceDocument{
+		ID: "session-alpha", Kind: "transcript", Format: "application/vnd.seriatim.minimal+json", Digest: "sha256:test",
+		Units: []source.SourceUnit{
+			{ID: 1, Kind: "transcript_segment", Text: "The party discovers a hidden cache."},
+			{ID: 2, Kind: "transcript_segment", Text: "They acquire 20 gold pieces."},
+			{ID: 3, Kind: "transcript_segment", Text: "Aria gives Borin the moonblade."},
+			{ID: 4, Kind: "transcript_segment", Text: "The party consumes a healing potion."},
+			{ID: 5, Kind: "transcript_segment", Text: "The party loses a torch."},
+		},
+	}
+}
+
+func responseRefs(start, end int) []itemOccurrenceSourceRefResponse {
+	return []itemOccurrenceSourceRefResponse{{StartSegment: start, EndSegment: end}}
+}
+
+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
+}
+
+func cloneStructuredCompletionRequest(req contracts.StructuredCompletionRequest) contracts.StructuredCompletionRequest {
+	req.Inputs = req.Inputs.Clone()
+	return req
+}
+
+type fakeItemOccurrencesLLMClient struct {
+	response extractionResponse
+	content  []byte
+	err      error
+	requests []contracts.StructuredCompletionRequest
+}
+
+func (client *fakeItemOccurrencesLLMClient) 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")
+	}
+	content := append([]byte(nil), client.content...)
+	if len(content) == 0 {
+		var err error
+		content, err = json.Marshal(client.response)
+		if err != nil {
+			return contracts.StructuredCompletionResponse{}, err
+		}
+	}
+	if err := json.Unmarshal(content, target); err != nil {
+		return contracts.StructuredCompletionResponse{}, err
+	}
+	return contracts.StructuredCompletionResponse{Content: content}, nil
+}