Organize D&D extensions by domain

2026-07-17 05:05:48 +00:00
parent a81b9f1e1f
commit 15c369c509
64 changed files with 469 additions and 194 deletions
--- a/internal/modules/dnd/chunk/scenes/assets.go
+++ b/internal/modules/dnd/chunk/scenes/assets.go
@@ -0,0 +1,6 @@
+package scenes
+
+import "embed"
+
+//go:embed assets/schemas/*.json assets/prompts/*.yaml assets/prompts/*.md
+var embeddedAssets embed.FS
--- a/internal/modules/dnd/chunk/scenes/assets/prompts/dnd.scenes.yaml
+++ b/internal/modules/dnd/chunk/scenes/assets/prompts/dnd.scenes.yaml
@@ -0,0 +1,36 @@
+id: dnd.scenes
+version: "v1"
+default_profile: gemini-2-flash
+inputs:
+  - name: transcript
+    required: true
+    content_type: application/json
+  - name: players
+    required: false
+    content_type: text/plain
+  - name: party
+    required: false
+    content_type: text/plain
+  - name: glossary
+    required: false
+    content_type: text/plain
+messages:
+  - role: system
+    content_file: ./sharedassets/common-dnd-system.md
+  - role: user
+    content_file: ./sharedassets/common-dnd-transcript.md
+    cache_control:
+      type: ephemeral
+  - role: user
+    content_file: ./sharedassets/common-dnd-references.md
+    cache_control:
+      type: ephemeral
+  - role: user
+    content_file: ./task.md
+  - role: user
+    content_file: ./instructions.md
+output:
+  format: json
+  validation_mode: json_schema
+  schema_path: dnd_scenes.v1.json
+  repair_attempts: 0
--- a/internal/modules/dnd/chunk/scenes/assets/prompts/instructions.md
+++ b/internal/modules/dnd/chunk/scenes/assets/prompts/instructions.md
@@ -0,0 +1,52 @@
+Good reasons to start a new scene include:
+- the party moves to a new location;
+- a combat encounter begins or ends;
+- combat changes into a substantially different phase;
+- the party shifts between combat, exploration, social interaction, discussion,
+  planning, travel, rest, or downtime;
+- a new NPC, faction, threat, or objective becomes central;
+- the party completes one immediate goal and begins another;
+- a major table-level rules discussion interrupts and materially changes play.
+
+Do not start a new scene merely because:
+- the speaker changes;
+- a new combat round begins;
+- a player asks a brief rules question;
+- there is a joke, aside, or short table comment;
+- a character takes a routine turn;
+- the same encounter continues without a meaningful change in situation.
+
+dnd/scenes boundary policy:
+- cover the full provided transcript from the first source unit to the last
+  source unit;
+- return sequential scenes with no gaps;
+- do not overlap scenes;
+- preserve source-unit order;
+- use integer source-unit IDs from the transcript;
+- each scene must have start_unit_id and end_unit_id;
+- do not include final chunk IDs or chunk indexes.
+
+For each scene:
+- short_title should be brief and factual;
+- primary_mode must be Recap, Discussion, Combat, or Narrative;
+- main_participants should include only principal characters, NPCs, factions, or
+  groups involved;
+- summary should be factual and compact, usually one to three sentences;
+- boundary_note should explain why the scene begins at start_unit_id and ends at
+  end_unit_id;
+- boundary_confidence must be High, Medium, or Low.
+
+Primary mode guidance:
+- Use Recap for opening recap, initiative setup, session framing, or immediate
+  continuation from prior events.
+- Use Discussion when the party is primarily discussing options or choosing a
+  course of action.
+- Use Combat when active combat or combat-resolution mechanics dominate.
+- Use Narrative for all other non-combat gameplay, including exploration, social
+  interactions, shopping, preparation, travel, rest, and downtime.
+
+In boundary_caveats, list overall caveats about scene divisions. Include scenes
+that could reasonably be split differently, combat phases that were kept
+together, gradual transitions, or places where map context would have helped.
+
+Return exactly one JSON object and no explanatory text.
--- a/internal/modules/dnd/chunk/scenes/assets/prompts/task.md
+++ b/internal/modules/dnd/chunk/scenes/assets/prompts/task.md
@@ -0,0 +1,5 @@
+Divide the provided transcript into coherent Dungeons & Dragons scenes for the
+dnd/scenes chunk module.
+
+A scene is a coherent unit of play. Start a new scene when there is a meaningful
+change in location, objective, threat, activity, encounter, or mode of play.
--- a/internal/modules/dnd/chunk/scenes/assets/schemas/dnd_scenes.v1.json
+++ b/internal/modules/dnd/chunk/scenes/assets/schemas/dnd_scenes.v1.json
@@ -0,0 +1,84 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "notarius.dnd.scenes",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "scenes",
+    "boundary_caveats"
+  ],
+  "properties": {
+    "scenes": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "start_unit_id",
+          "end_unit_id",
+          "short_title",
+          "primary_mode",
+          "main_participants",
+          "summary",
+          "boundary_note",
+          "boundary_confidence"
+        ],
+        "properties": {
+          "start_unit_id": {
+            "type": "integer",
+            "minimum": 1
+          },
+          "end_unit_id": {
+            "type": "integer",
+            "minimum": 1
+          },
+          "short_title": {
+            "type": "string",
+            "minLength": 1
+          },
+          "primary_mode": {
+            "type": "string",
+            "enum": [
+              "Recap",
+              "Discussion",
+              "Combat",
+              "Narrative"
+            ]
+          },
+          "main_participants": {
+            "type": "array",
+            "minItems": 1,
+            "items": {
+              "type": "string",
+              "minLength": 1
+            }
+          },
+          "summary": {
+            "type": "string",
+            "minLength": 1
+          },
+          "boundary_note": {
+            "type": "string",
+            "minLength": 1
+          },
+          "boundary_confidence": {
+            "type": "string",
+            "enum": [
+              "High",
+              "Medium",
+              "Low"
+            ]
+          }
+        }
+      }
+    },
+    "boundary_caveats": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "minLength": 1
+      }
+    }
+  }
+}
--- a/internal/modules/dnd/chunk/scenes/chunker.go
+++ b/internal/modules/dnd/chunk/scenes/chunker.go
@@ -0,0 +1,354 @@
+package scenes
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"strings"
+
+	"gitea.maximumdirect.net/eric/notarius/internal/core/source"
+	"gitea.maximumdirect.net/eric/notarius/internal/framework/contracts"
+	"gitea.maximumdirect.net/eric/notarius/internal/framework/pipeline"
+	"gitea.maximumdirect.net/eric/notarius/internal/modules/dnd/shared"
+)
+
+const Key = "dnd/scenes"
+
+var requiredCapabilities = []string{
+	"source.transcript",
+}
+
+var providedCapabilities = []string{
+	"chunks",
+	"chunks.scenes",
+}
+
+var referenceSlotDescriptions = shared.ReferenceSlotDescriptions{
+	Glossary: "Optional campaign glossary reference material used only for scene disambiguation.",
+	Party:    "Optional party roster reference material used only for scene disambiguation.",
+	Players:  "Optional player list reference material used only for scene disambiguation.",
+	Roster:   "Deprecated alias for party roster reference material used only for scene disambiguation.",
+}
+
+var _ contracts.Chunker = (*Chunker)(nil)
+var _ contracts.ManifestMetadataProvider = (*Chunker)(nil)
+
+type Chunker struct{}
+
+func New() *Chunker {
+	return &Chunker{}
+}
+
+func (c *Chunker) Key() string {
+	return Key
+}
+
+func (c *Chunker) ReferenceSlots() []contracts.ReferenceSlot {
+	return shared.ReferenceSlots(referenceSlotDescriptions)
+}
+
+func (c *Chunker) ManifestMetadata() map[string]any {
+	promptSHA, err := scriptoriumPromptMetadata()
+	if err != nil {
+		promptSHA = ""
+	}
+	metadata := map[string]any{
+		"prompt_id":            PromptID,
+		"prompt_version":       ResponseSchemaVersion,
+		"prompt_sha256":        promptSHA,
+		"response_schema_key":  string(ResponseSchemaKey),
+		"response_schema_id":   ResponseSchemaID,
+		"response_schema_name": ResponseSchemaName,
+	}
+	if schema, err := loadResponseSchema(); err == nil {
+		metadata["response_schema_version"] = schema.Version
+		metadata["response_schema_sha256"] = schema.SHA256
+	}
+	return metadata
+}
+
+func (c *Chunker) Chunk(ctx context.Context, req contracts.ChunkRequest) (contracts.ChunkResult, error) {
+	if c == nil {
+		return contracts.ChunkResult{}, chunkerErrorf("chunker must not be nil")
+	}
+	if ctx == nil {
+		return contracts.ChunkResult{}, chunkerErrorf("context must not be nil")
+	}
+	if err := ctx.Err(); err != nil {
+		return contracts.ChunkResult{}, chunkerErrorf("context error before chunking: %w", err)
+	}
+	if req.Source == nil {
+		return contracts.ChunkResult{}, chunkerErrorf("source must not be nil")
+	}
+	if len(req.Source.Units) == 0 {
+		return contracts.ChunkResult{}, chunkerErrorf("source units must not be empty")
+	}
+	if err := source.ValidateDocument(req.Source); err != nil {
+		return contracts.ChunkResult{}, chunkerErrorf("validate source document: %w", err)
+	}
+	if req.LLMClient == nil {
+		return contracts.ChunkResult{}, chunkerErrorf("LLM client must not be nil")
+	}
+	if len(req.Options) > 0 {
+		return contracts.ChunkResult{}, chunkerErrorf("options are not supported")
+	}
+
+	var response chunkResponse
+	if _, err := req.LLMClient.CompleteStructured(ctx, contracts.StructuredCompletionRequest{
+		StageName:     Key,
+		PromptID:      PromptID,
+		PromptVersion: ResponseSchemaVersion,
+		ProfileID:     req.LLMProfile,
+		SessionID:     req.SessionID,
+		Inputs:        shared.PromptInputs(req.SourceInput, req.References),
+	}, &response); err != nil {
+		return contracts.ChunkResult{}, chunkerErrorf("complete structured output: %w", err)
+	}
+
+	warnings, err := warningsFromCaveats(response.BoundaryCaveats)
+	if err != nil {
+		return contracts.ChunkResult{}, chunkerErrorf("malformed structured output: %w", err)
+	}
+	chunks, err := chunksFromResponse(req.Source, response)
+	if err != nil {
+		return contracts.ChunkResult{}, chunkerErrorf("malformed structured output: %w", err)
+	}
+	return contracts.ChunkResult{
+		Chunks:   chunks,
+		Warnings: warnings,
+	}, nil
+}
+
+func ModuleSpec() pipeline.ModuleSpec {
+	return pipeline.ModuleSpec{
+		Key:            Key,
+		Stage:          pipeline.StageChunk,
+		Requires:       append([]string(nil), requiredCapabilities...),
+		Provides:       append([]string(nil), providedCapabilities...),
+		ReferenceSlots: shared.ReferenceSlots(referenceSlotDescriptions),
+	}
+}
+
+func Register(registry *pipeline.ChunkerRegistry) error {
+	return registry.RegisterWithSpec(ModuleSpec(), func() (contracts.Chunker, error) {
+		return New(), nil
+	})
+}
+
+func chunksFromResponse(doc *source.SourceDocument, response chunkResponse) ([]contracts.SourceChunk, error) {
+	if response.Scenes == nil {
+		return nil, fmt.Errorf("scenes must be present")
+	}
+	if len(response.Scenes) == 0 {
+		return nil, fmt.Errorf("scenes must not be empty")
+	}
+
+	unitIndexes := make(map[int]int, len(doc.Units))
+	for i, unit := range doc.Units {
+		unitIndexes[unit.ID] = i
+	}
+
+	chunks := make([]contracts.SourceChunk, 0, len(response.Scenes))
+	previousEnd := -1
+	for i, scene := range response.Scenes {
+		normalized, err := normalizeScene(doc, i, scene)
+		if err != nil {
+			return nil, err
+		}
+
+		startIndex, ok := unitIndexes[normalized.StartUnitID]
+		if !ok {
+			return nil, fmt.Errorf("scene[%d] start_unit_id %d was not found", i, normalized.StartUnitID)
+		}
+		endIndex, ok := unitIndexes[normalized.EndUnitID]
+		if !ok {
+			return nil, fmt.Errorf("scene[%d] end_unit_id %d was not found", i, normalized.EndUnitID)
+		}
+		if startIndex > endIndex {
+			return nil, fmt.Errorf("scene[%d] start_unit_id %d appears after end_unit_id %d", i, normalized.StartUnitID, normalized.EndUnitID)
+		}
+
+		if i == 0 && startIndex != 0 {
+			return nil, fmt.Errorf("first scene must start at first source unit %d", doc.Units[0].ID)
+		}
+		if i > 0 {
+			if startIndex <= previousEnd {
+				return nil, fmt.Errorf("scene[%d] overlaps previous scene", i)
+			}
+			if startIndex > previousEnd+1 {
+				return nil, fmt.Errorf("scene[%d] leaves a gap after previous scene", i)
+			}
+		}
+		previousEnd = endIndex
+
+		units := cloneUnits(doc.Units[startIndex : endIndex+1])
+		content, err := chunkContent(units)
+		if err != nil {
+			return nil, err
+		}
+		chunks = append(chunks, contracts.SourceChunk{
+			ID:          fmt.Sprintf("scene-%06d", i+1),
+			SourceID:    doc.ID,
+			Index:       i,
+			StartUnitID: units[0].ID,
+			EndUnitID:   units[len(units)-1].ID,
+			Content:     content,
+			MediaType:   "application/json",
+			Units:       units,
+			Metadata: map[string]any{
+				"scene_title":         normalized.ShortTitle,
+				"primary_mode":        normalized.PrimaryMode,
+				"main_participants":   append([]string(nil), normalized.MainParticipants...),
+				"summary":             normalized.Summary,
+				"boundary_note":       normalized.BoundaryNote,
+				"boundary_confidence": normalized.BoundaryConfidence,
+				"start_unit_id":       normalized.StartUnitID,
+				"end_unit_id":         normalized.EndUnitID,
+				"unit_count":          len(units),
+			},
+		})
+	}
+
+	if previousEnd != len(doc.Units)-1 {
+		return nil, fmt.Errorf("final scene must end at final source unit %d", doc.Units[len(doc.Units)-1].ID)
+	}
+	return chunks, nil
+}
+
+func chunkContent(units []source.SourceUnit) ([]byte, error) {
+	content, err := json.Marshal(struct {
+		Units []source.SourceUnit `json:"units"`
+	}{
+		Units: units,
+	})
+	if err != nil {
+		return nil, fmt.Errorf("encode chunk content: %w", err)
+	}
+	return content, nil
+}
+
+func normalizeScene(doc *source.SourceDocument, index int, scene sceneResponse) (normalizedScene, error) {
+	startUnitID, err := shared.ResolveUnitID(doc, "start_unit_id", scene.StartUnitID)
+	if err != nil {
+		return normalizedScene{}, fmt.Errorf("scene[%d] %w", index, err)
+	}
+	endUnitID, err := shared.ResolveUnitID(doc, "end_unit_id", scene.EndUnitID)
+	if err != nil {
+		return normalizedScene{}, fmt.Errorf("scene[%d] %w", index, err)
+	}
+
+	out := normalizedScene{
+		StartUnitID:        startUnitID,
+		EndUnitID:          endUnitID,
+		ShortTitle:         strings.TrimSpace(scene.ShortTitle),
+		PrimaryMode:        strings.TrimSpace(scene.PrimaryMode),
+		Summary:            strings.TrimSpace(scene.Summary),
+		BoundaryNote:       strings.TrimSpace(scene.BoundaryNote),
+		BoundaryConfidence: strings.TrimSpace(scene.BoundaryConfidence),
+	}
+
+	requiredInts := map[string]int{
+		"start_unit_id": out.StartUnitID,
+		"end_unit_id":   out.EndUnitID,
+	}
+	for field, value := range requiredInts {
+		if value <= 0 {
+			return normalizedScene{}, fmt.Errorf("scene[%d] %s must be positive", index, field)
+		}
+	}
+	required := map[string]string{
+		"short_title":         out.ShortTitle,
+		"primary_mode":        out.PrimaryMode,
+		"summary":             out.Summary,
+		"boundary_note":       out.BoundaryNote,
+		"boundary_confidence": out.BoundaryConfidence,
+	}
+	for field, value := range required {
+		if value == "" {
+			return normalizedScene{}, fmt.Errorf("scene[%d] %s must not be empty", index, field)
+		}
+	}
+	if !validPrimaryMode(out.PrimaryMode) {
+		return normalizedScene{}, fmt.Errorf("scene[%d] primary_mode %q is not supported", index, out.PrimaryMode)
+	}
+	if !validBoundaryConfidence(out.BoundaryConfidence) {
+		return normalizedScene{}, fmt.Errorf("scene[%d] boundary_confidence %q is not supported", index, out.BoundaryConfidence)
+	}
+	if len(scene.MainParticipants) == 0 {
+		return normalizedScene{}, fmt.Errorf("scene[%d] main_participants must not be empty", index)
+	}
+	out.MainParticipants = make([]string, 0, len(scene.MainParticipants))
+	for participantIndex, participant := range scene.MainParticipants {
+		trimmed := strings.TrimSpace(participant)
+		if trimmed == "" {
+			return normalizedScene{}, fmt.Errorf("scene[%d] main_participants[%d] must not be empty", index, participantIndex)
+		}
+		out.MainParticipants = append(out.MainParticipants, trimmed)
+	}
+	return out, nil
+}
+
+func validPrimaryMode(value string) bool {
+	switch value {
+	case "Recap", "Discussion", "Combat", "Narrative":
+		return true
+	default:
+		return false
+	}
+}
+
+func validBoundaryConfidence(value string) bool {
+	switch value {
+	case "High", "Medium", "Low":
+		return true
+	default:
+		return false
+	}
+}
+
+func warningsFromCaveats(caveats []string) ([]contracts.Warning, error) {
+	if len(caveats) == 0 {
+		return nil, nil
+	}
+	warnings := make([]contracts.Warning, 0, len(caveats))
+	for i, caveat := range caveats {
+		trimmed := strings.TrimSpace(caveat)
+		if trimmed == "" {
+			return nil, fmt.Errorf("boundary_caveats[%d] must not be empty after trimming", i)
+		}
+		warnings = append(warnings, contracts.Warning{
+			Scope:      Key,
+			ReasonCode: "scene_boundary_caveat",
+			Message:    trimmed,
+		})
+	}
+	return warnings, nil
+}
+
+func cloneUnits(units []source.SourceUnit) []source.SourceUnit {
+	out := make([]source.SourceUnit, 0, len(units))
+	for _, unit := range units {
+		out = append(out, source.SourceUnit{
+			ID:       unit.ID,
+			Kind:     unit.Kind,
+			Text:     unit.Text,
+			Metadata: cloneMetadata(unit.Metadata),
+		})
+	}
+	return out
+}
+
+func cloneMetadata(metadata map[string]any) map[string]any {
+	if len(metadata) == 0 {
+		return nil
+	}
+	out := make(map[string]any, len(metadata))
+	for key, value := range metadata {
+		out[key] = value
+	}
+	return out
+}
+
+func chunkerErrorf(format string, args ...any) error {
+	return fmt.Errorf("dnd scenes chunker: "+format, args...)
+}
--- a/internal/modules/dnd/chunk/scenes/chunker_test.go
+++ b/internal/modules/dnd/chunk/scenes/chunker_test.go
@@ -0,0 +1,628 @@
+package scenes
+
+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/shared"
+)
+
+func TestNewModuleSpecAndRegister(t *testing.T) {
+	chunker := New()
+	if chunker == nil {
+		t.Fatal("New() = nil, want chunker")
+	}
+	if chunker.Key() != Key {
+		t.Fatalf("Key() = %q, want %q", chunker.Key(), Key)
+	}
+
+	want := pipeline.ModuleSpec{
+		Key:            Key,
+		Stage:          pipeline.StageChunk,
+		Requires:       []string{"source.transcript"},
+		Provides:       []string{"chunks", "chunks.scenes"},
+		ReferenceSlots: wantReferenceSlots(),
+	}
+	if got := ModuleSpec(); !reflect.DeepEqual(got, want) {
+		t.Fatalf("ModuleSpec() = %#v, want %#v", got, want)
+	}
+	got := ModuleSpec()
+	got.Requires[0] = "changed"
+	got.Provides[0] = "changed"
+	got.ReferenceSlots[0].AcceptedMediaTypes[0] = "changed"
+	if again := ModuleSpec(); !reflect.DeepEqual(again, want) {
+		t.Fatalf("ModuleSpec() after caller mutation = %#v, want %#v", again, want)
+	}
+
+	registry := pipeline.NewChunkerRegistry()
+	if err := Register(registry); err != nil {
+		t.Fatalf("Register() error = %v, want nil", err)
+	}
+	registered, ok := registry.Spec(Key)
+	if !ok {
+		t.Fatalf("Spec(%q) ok = false, want true", Key)
+	}
+	if !reflect.DeepEqual(registered, want) {
+		t.Fatalf("registered spec = %#v, want %#v", registered, want)
+	}
+	built, err := registry.Build(Key)
+	if err != nil {
+		t.Fatalf("Build(%q) error = %v, want nil", Key, err)
+	}
+	if built.Key() != Key {
+		t.Fatalf("built Key() = %q, want %q", built.Key(), Key)
+	}
+	if slots := built.ReferenceSlots(); !reflect.DeepEqual(slots, want.ReferenceSlots) {
+		t.Fatalf("ReferenceSlots() = %#v, want %#v", slots, want.ReferenceSlots)
+	}
+}
+
+func TestRegisterNilRegistryReturnsError(t *testing.T) {
+	err := Register(nil)
+	if err == nil {
+		t.Fatal("Register(nil) error = nil, want error")
+	}
+	if !strings.Contains(err.Error(), "chunker registry") {
+		t.Fatalf("Register(nil) error = %q, want registry context", err.Error())
+	}
+}
+
+func wantReferenceSlots() []contracts.ReferenceSlot {
+	accepted := []string{"application/json", "application/x-yaml", "application/yaml", "text/markdown", "text/plain"}
+	return []contracts.ReferenceSlot{
+		{
+			Name:               "glossary",
+			Description:        "Optional campaign glossary reference material used only for scene disambiguation.",
+			AcceptedMediaTypes: append([]string(nil), accepted...),
+		},
+		{
+			Name:               "party",
+			Description:        "Optional party roster reference material used only for scene disambiguation.",
+			AcceptedMediaTypes: append([]string(nil), accepted...),
+		},
+		{
+			Name:               "players",
+			Description:        "Optional player list reference material used only for scene disambiguation.",
+			AcceptedMediaTypes: append([]string(nil), accepted...),
+		},
+		{
+			Name:               "roster",
+			Description:        "Deprecated alias for party roster reference material used only for scene disambiguation.",
+			AcceptedMediaTypes: append([]string(nil), accepted...),
+		},
+	}
+}
+
+func TestChunkReturnsSceneChunksFromStructuredOutput(t *testing.T) {
+	client := &fakeScenesLLMClient{
+		response: chunkResponse{
+			Scenes: []sceneResponse{
+				{
+					StartUnitID:        shared.UnitRefFromInt(1),
+					EndUnitID:          shared.UnitRefFromInt(2),
+					ShortTitle:         " Goblin parley ",
+					PrimaryMode:        "Discussion",
+					MainParticipants:   []string{" Aria ", "Goblin scout"},
+					Summary:            " The party negotiates with a scout. ",
+					BoundaryNote:       " The scene covers the discussion before fighting starts. ",
+					BoundaryConfidence: "High",
+				},
+				{
+					StartUnitID:        shared.UnitRefFromInt(3),
+					EndUnitID:          shared.UnitRefFromInt(4),
+					ShortTitle:         "Ambush at the gate",
+					PrimaryMode:        "Combat",
+					MainParticipants:   []string{"Aria", "Goblin ambushers"},
+					Summary:            "The goblins attack at the gate.",
+					BoundaryNote:       "Combat begins and resolves the immediate threat.",
+					BoundaryConfidence: "Medium",
+				},
+			},
+			BoundaryCaveats: []string{" The transition into combat is gradual. "},
+		},
+	}
+
+	result, err := New().Chunk(context.Background(), chunkRequestWithClient(client))
+	if err != nil {
+		t.Fatalf("Chunk() error = %v, want nil", err)
+	}
+
+	if len(client.requests) != 1 {
+		t.Fatalf("LLM calls = %d, want 1", len(client.requests))
+	}
+	req := client.requests[0]
+	if req.StageName != Key {
+		t.Fatalf("StageName = %q, want %q", req.StageName, Key)
+	}
+	if req.PromptID != PromptID || req.PromptVersion != ResponseSchemaVersion {
+		t.Fatalf("prompt = %q/%q, want %q/%q", req.PromptID, req.PromptVersion, PromptID, ResponseSchemaVersion)
+	}
+	if req.SessionID != "session-123" || req.ProfileID != "profile-scenes" {
+		t.Fatalf("session/profile = %q/%q, want session-123/profile-scenes", req.SessionID, req.ProfileID)
+	}
+	transcript, ok := req.Inputs["transcript"]
+	if !ok {
+		t.Fatalf("transcript input missing from %#v", req.Inputs)
+	}
+	if transcript.Name != "transcript" || transcript.MediaType != "application/json" || transcript.Digest != "sha256:transcript" || transcript.OriginURI != "file:///session-alpha.json" {
+		t.Fatalf("transcript metadata = %#v", transcript)
+	}
+	if got := string(transcript.Content); got != sceneTranscriptJSON {
+		t.Fatalf("transcript content = %q, want original source input", got)
+	}
+	if got := string(req.Inputs["players"].Content); got != " " {
+		t.Fatalf("players input = %q, want empty reference placeholder", got)
+	}
+	if got := string(req.Inputs["party"].Content); got != " " {
+		t.Fatalf("party input = %q, want empty reference placeholder", got)
+	}
+	if got := string(req.Inputs["glossary"].Content); got != " " {
+		t.Fatalf("glossary input = %q, want empty reference placeholder", got)
+	}
+
+	if got := chunkIDs(result.Chunks); !reflect.DeepEqual(got, []string{"scene-000001", "scene-000002"}) {
+		t.Fatalf("chunk IDs = %#v, want deterministic scene IDs", got)
+	}
+	gotUnits := [][]int{unitIDs(result.Chunks[0].Units), unitIDs(result.Chunks[1].Units)}
+	wantUnits := [][]int{{1, 2}, {3, 4}}
+	if !reflect.DeepEqual(gotUnits, wantUnits) {
+		t.Fatalf("chunk units = %#v, want %#v", gotUnits, wantUnits)
+	}
+	first := result.Chunks[0]
+	if first.SourceID != "session-alpha" || first.Index != 0 {
+		t.Fatalf("first chunk = %#v, want source and index fields", first)
+	}
+	if first.StartUnitID != 1 || first.EndUnitID != 2 {
+		t.Fatalf("first boundaries = %d-%d, want 1-2", first.StartUnitID, first.EndUnitID)
+	}
+	if first.MediaType != "application/json" || len(first.Content) == 0 {
+		t.Fatalf("first payload = media type %q length %d, want JSON content", first.MediaType, len(first.Content))
+	}
+	if first.Metadata["scene_title"] != "Goblin parley" ||
+		first.Metadata["primary_mode"] != "Discussion" ||
+		first.Metadata["summary"] != "The party negotiates with a scout." ||
+		first.Metadata["boundary_note"] != "The scene covers the discussion before fighting starts." ||
+		first.Metadata["boundary_confidence"] != "High" ||
+		first.Metadata["start_unit_id"] != 1 ||
+		first.Metadata["end_unit_id"] != 2 ||
+		first.Metadata["unit_count"] != 2 {
+		t.Fatalf("first metadata = %#v, want scene metadata", first.Metadata)
+	}
+	if got, ok := first.Metadata["main_participants"].([]string); !ok || !reflect.DeepEqual(got, []string{"Aria", "Goblin scout"}) {
+		t.Fatalf("main_participants = %#v, want trimmed participant slice", first.Metadata["main_participants"])
+	}
+	if got := result.Warnings; len(got) != 1 ||
+		got[0].Scope != Key ||
+		got[0].ReasonCode != "scene_boundary_caveat" ||
+		got[0].Message != "The transition into combat is gradual." {
+		t.Fatalf("Warnings = %#v, want boundary caveat warning", got)
+	}
+}
+
+func TestChunkPassesReferencesAsPromptInputs(t *testing.T) {
+	client := &fakeScenesLLMClient{response: chunkResponse{
+		Scenes: []sceneResponse{
+			{
+				StartUnitID:        shared.UnitRefFromInt(1),
+				EndUnitID:          shared.UnitRefFromInt(4),
+				ShortTitle:         "Ambush",
+				PrimaryMode:        "Combat",
+				MainParticipants:   []string{"Aria"},
+				Summary:            "The party is ambushed.",
+				BoundaryNote:       "One scene covers the short fixture.",
+				BoundaryConfidence: "High",
+			},
+		},
+	}}
+	req := chunkRequestWithClient(client)
+	req.References = contracts.ReferenceSet{
+		Slots: map[string]contracts.ResolvedReferenceSlot{
+			"players": {
+				Slot: contracts.ReferenceSlot{Name: "players"},
+				Items: []contracts.ReferenceItem{
+					{SlotName: "players", Content: []byte("Alice: Aria")},
+				},
+			},
+			"party": {
+				Slot: contracts.ReferenceSlot{Name: "party"},
+				Items: []contracts.ReferenceItem{
+					{SlotName: "party", Content: []byte("Aria: cleric")},
+				},
+			},
+			"glossary": {
+				Slot: contracts.ReferenceSlot{Name: "glossary"},
+				Items: []contracts.ReferenceItem{
+					{SlotName: "glossary", Content: []byte("Brightmantle: local temple")},
+				},
+			},
+		},
+	}
+
+	if _, err := New().Chunk(context.Background(), req); err != nil {
+		t.Fatalf("Chunk() error = %v, want nil", err)
+	}
+	request := client.requests[0]
+	if got := string(request.Inputs["players"].Content); got != "Alice: Aria" {
+		t.Fatalf("players input = %q, want reference content", got)
+	}
+	if got := string(request.Inputs["party"].Content); got != "Aria: cleric" {
+		t.Fatalf("party input = %q, want reference content", got)
+	}
+	if got := string(request.Inputs["glossary"].Content); got != "Brightmantle: local temple" {
+		t.Fatalf("glossary input = %q, want reference content", got)
+	}
+	if strings.Contains(string(request.Inputs["transcript"].Content), "Aria: cleric") {
+		t.Fatalf("transcript input contains reference content")
+	}
+}
+
+func TestPromptInputsMapLegacyRosterReferenceToParty(t *testing.T) {
+	inputs := shared.PromptInputs(sceneSourceInput(), contracts.ReferenceSet{
+		Slots: map[string]contracts.ResolvedReferenceSlot{
+			"roster": {
+				Slot: contracts.ReferenceSlot{Name: "roster"},
+				Items: []contracts.ReferenceItem{
+					{SlotName: "roster", Content: []byte("Legacy roster text")},
+				},
+			},
+		},
+	})
+
+	if got := string(inputs["party"].Content); got != "Legacy roster text" {
+		t.Fatalf("party input = %q, want legacy roster content", got)
+	}
+	if _, ok := inputs["roster"]; ok {
+		t.Fatalf("roster prompt input was present; want only party input")
+	}
+}
+
+func TestChunkRejectsWhitespaceOnlyBoundaryCaveats(t *testing.T) {
+	client := &fakeScenesLLMClient{
+		response: chunkResponse{
+			Scenes: validSceneResponse().Scenes,
+			BoundaryCaveats: []string{
+				"   ",
+			},
+		},
+	}
+
+	_, err := New().Chunk(context.Background(), chunkRequestWithClient(client))
+	if err == nil {
+		t.Fatal("Chunk() error = nil, want malformed structured output error")
+	}
+	if !strings.Contains(err.Error(), "dnd scenes chunker") || !strings.Contains(err.Error(), "malformed structured output") || !strings.Contains(err.Error(), "boundary_caveats[0]") {
+		t.Fatalf("Chunk() error = %q, want malformed boundary caveat context", err.Error())
+	}
+}
+
+func TestChunkDefensivelyCopiesSourceUnitsAndMetadata(t *testing.T) {
+	doc := sceneSourceDocument()
+	client := &fakeScenesLLMClient{response: validSceneResponse()}
+
+	result, err := New().Chunk(context.Background(), contracts.ChunkRequest{
+		Source:      doc,
+		SourceInput: sceneSourceInput(),
+		SessionID:   "session-123",
+		LLMProfile:  "profile-scenes",
+		LLMClient:   client,
+	})
+	if err != nil {
+		t.Fatalf("Chunk() error = %v, want nil", err)
+	}
+
+	doc.Units[0].ID = 99
+	doc.Units[0].Metadata["speaker"] = "mutated"
+	client.response.Scenes[0].MainParticipants[0] = "mutated"
+
+	if result.Chunks[0].Units[0].ID != 1 {
+		t.Fatalf("chunk unit ID changed after source mutation: %#v", result.Chunks[0].Units[0])
+	}
+	if result.Chunks[0].Units[0].Metadata["speaker"] != "Alice" {
+		t.Fatalf("chunk unit metadata changed after source mutation: %#v", result.Chunks[0].Units[0].Metadata)
+	}
+	participants, ok := result.Chunks[0].Metadata["main_participants"].([]string)
+	if !ok || participants[0] != "Aria" {
+		t.Fatalf("participants = %#v, want defensive copy", result.Chunks[0].Metadata["main_participants"])
+	}
+}
+
+func TestChunkerManifestMetadataIncludesPromptAndSchemaProvenance(t *testing.T) {
+	metadata := New().ManifestMetadata()
+
+	tests := map[string]string{
+		"prompt_id":               PromptID,
+		"prompt_version":          ResponseSchemaVersion,
+		"response_schema_key":     string(ResponseSchemaKey),
+		"response_schema_id":      ResponseSchemaID,
+		"response_schema_name":    ResponseSchemaName,
+		"response_schema_version": ResponseSchemaVersion,
+	}
+	for key, want := range tests {
+		if metadata[key] != want {
+			t.Fatalf("metadata[%q] = %#v, want %q", key, metadata[key], want)
+		}
+	}
+	for _, key := range []string{"prompt_sha256", "response_schema_sha256"} {
+		value, ok := metadata[key].(string)
+		if !ok || !strings.HasPrefix(value, "sha256:") {
+			t.Fatalf("metadata[%q] = %#v, want sha256 value", key, metadata[key])
+		}
+	}
+	for _, forbidden := range []string{"prompt", "schema", "source", "text"} {
+		if _, ok := metadata[forbidden]; ok {
+			t.Fatalf("metadata includes raw %q field: %#v", forbidden, metadata)
+		}
+	}
+}
+
+func TestChunkRejectsInvalidRequests(t *testing.T) {
+	validClient := &fakeScenesLLMClient{response: validSceneResponse()}
+	validReq := chunkRequestWithClient(validClient)
+	canceledCtx, cancel := context.WithCancel(context.Background())
+	cancel()
+	invalidDoc := sceneSourceDocument()
+	invalidDoc.Units[0].ID = 0
+	emptyDoc := sceneSourceDocument()
+	emptyDoc.Units = nil
+
+	tests := []struct {
+		name    string
+		chunker *Chunker
+		ctx     context.Context
+		req     contracts.ChunkRequest
+		want    string
+	}{
+		{name: "nil chunker", chunker: nil, ctx: context.Background(), req: validReq, want: "chunker"},
+		{name: "nil context", chunker: New(), ctx: nil, req: validReq, want: "context"},
+		{name: "canceled context", chunker: New(), ctx: canceledCtx, req: validReq, want: "context"},
+		{name: "nil source", chunker: New(), ctx: context.Background(), req: contracts.ChunkRequest{LLMClient: validClient}, want: "source"},
+		{name: "empty source units", chunker: New(), ctx: context.Background(), req: contracts.ChunkRequest{Source: emptyDoc, LLMClient: validClient}, want: "units"},
+		{name: "invalid source", chunker: New(), ctx: context.Background(), req: contracts.ChunkRequest{Source: invalidDoc, LLMClient: validClient}, want: "validate source document"},
+		{name: "nil LLM client", chunker: New(), ctx: context.Background(), req: contracts.ChunkRequest{Source: sceneSourceDocument()}, want: "LLM client"},
+		{name: "unsupported options", chunker: New(), ctx: context.Background(), req: requestWithOptions(validReq), want: "options"},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			_, err := tt.chunker.Chunk(tt.ctx, tt.req)
+			if err == nil {
+				t.Fatal("Chunk() error = nil, want error")
+			}
+			if !strings.Contains(err.Error(), "dnd scenes") || !strings.Contains(err.Error(), tt.want) {
+				t.Fatalf("Chunk() error = %q, want module context and %q", err.Error(), tt.want)
+			}
+		})
+	}
+}
+
+func TestChunkRejectsMalformedStructuredOutput(t *testing.T) {
+	tests := []struct {
+		name     string
+		response chunkResponse
+		want     string
+	}{
+		{name: "missing scenes", response: chunkResponse{}, want: "scenes"},
+		{name: "empty scenes", response: chunkResponse{Scenes: []sceneResponse{}}, want: "scenes"},
+		{
+			name: "unknown boundary id",
+			response: replaceScenes(validSceneResponse(), []sceneResponse{
+				scene(1, 999),
+			}),
+			want: "was not found",
+		},
+		{
+			name: "out of order boundaries",
+			response: replaceScenes(validSceneResponse(), []sceneResponse{
+				scene(3, 2),
+			}),
+			want: "appears after",
+		},
+		{
+			name: "gap",
+			response: replaceScenes(validSceneResponse(), []sceneResponse{
+				scene(1, 1),
+				scene(3, 4),
+			}),
+			want: "gap",
+		},
+		{
+			name: "overlap",
+			response: replaceScenes(validSceneResponse(), []sceneResponse{
+				scene(1, 2),
+				scene(2, 4),
+			}),
+			want: "overlap",
+		},
+		{
+			name: "incomplete coverage",
+			response: replaceScenes(validSceneResponse(), []sceneResponse{
+				scene(1, 3),
+			}),
+			want: "final scene",
+		},
+		{
+			name: "empty metadata field",
+			response: replaceScenes(validSceneResponse(), []sceneResponse{
+				{
+					StartUnitID:        shared.UnitRefFromInt(1),
+					EndUnitID:          shared.UnitRefFromInt(4),
+					ShortTitle:         " ",
+					PrimaryMode:        "Narrative",
+					MainParticipants:   []string{"Aria"},
+					Summary:            "Summary.",
+					BoundaryNote:       "Note.",
+					BoundaryConfidence: "High",
+				},
+			}),
+			want: "short_title",
+		},
+		{
+			name: "empty participant",
+			response: replaceScenes(validSceneResponse(), []sceneResponse{
+				{
+					StartUnitID:        shared.UnitRefFromInt(1),
+					EndUnitID:          shared.UnitRefFromInt(4),
+					ShortTitle:         "Title",
+					PrimaryMode:        "Narrative",
+					MainParticipants:   []string{"Aria", " "},
+					Summary:            "Summary.",
+					BoundaryNote:       "Note.",
+					BoundaryConfidence: "High",
+				},
+			}),
+			want: "main_participants",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			client := &fakeScenesLLMClient{response: tt.response}
+			_, err := New().Chunk(context.Background(), chunkRequestWithClient(client))
+			if err == nil {
+				t.Fatal("Chunk() error = nil, want error")
+			}
+			if !strings.Contains(err.Error(), "dnd scenes") || !strings.Contains(err.Error(), tt.want) {
+				t.Fatalf("Chunk() error = %q, want module context and %q", err.Error(), tt.want)
+			}
+		})
+	}
+}
+
+func TestChunkWrapsLLMClientError(t *testing.T) {
+	client := &fakeScenesLLMClient{err: errors.New("provider unavailable")}
+
+	_, err := New().Chunk(context.Background(), chunkRequestWithClient(client))
+	if err == nil {
+		t.Fatal("Chunk() error = nil, want LLM error")
+	}
+	if !strings.Contains(err.Error(), "dnd scenes") || !strings.Contains(err.Error(), "provider unavailable") {
+		t.Fatalf("Chunk() error = %q, want wrapped LLM context", err.Error())
+	}
+}
+
+func chunkRequestWithClient(client contracts.StructuredLLMClient) contracts.ChunkRequest {
+	return contracts.ChunkRequest{
+		Source:      sceneSourceDocument(),
+		SourceInput: sceneSourceInput(),
+		SessionID:   "session-123",
+		LLMProfile:  "profile-scenes",
+		LLMClient:   client,
+	}
+}
+
+const sceneTranscriptJSON = `{"id":"session-alpha","segments":[{"id":1,"text":"Aria asks whether the goblin will parley."}]}`
+
+func sceneSourceInput() contracts.LLMInputMaterial {
+	return contracts.NewLLMInputMaterial("source", "application/json", []byte(sceneTranscriptJSON), "sha256:transcript", "file:///session-alpha.json")
+}
+
+func requestWithOptions(req contracts.ChunkRequest) contracts.ChunkRequest {
+	req.Options = map[string]any{"max_units": 2}
+	return req
+}
+
+func sceneSourceDocument() *source.SourceDocument {
+	return &source.SourceDocument{
+		ID:     "session-alpha",
+		Kind:   "transcript",
+		Format: "application/vnd.seriatim.minimal+json",
+		Digest: "sha256:source",
+		Units: []source.SourceUnit{
+			{ID: 1, Kind: "transcript_segment", Text: "Aria asks whether the goblin will parley.", Metadata: map[string]any{"speaker": "Alice"}},
+			{ID: 2, Kind: "transcript_segment", Text: "The goblin scout describes the gate guards."},
+			{ID: 3, Kind: "transcript_segment", Text: "The guards rush out with blades drawn."},
+			{ID: 4, Kind: "transcript_segment", Text: "The party defeats the ambushers."},
+		},
+	}
+}
+
+func validSceneResponse() chunkResponse {
+	return chunkResponse{
+		Scenes: []sceneResponse{
+			scene(1, 4),
+		},
+		BoundaryCaveats: []string{},
+	}
+}
+
+func replaceScenes(response chunkResponse, scenes []sceneResponse) chunkResponse {
+	response.Scenes = scenes
+	return response
+}
+
+func scene(startUnitID int, endUnitID int) sceneResponse {
+	return sceneResponse{
+		StartUnitID:        shared.UnitRefFromInt(startUnitID),
+		EndUnitID:          shared.UnitRefFromInt(endUnitID),
+		ShortTitle:         "Scene title",
+		PrimaryMode:        "Narrative",
+		MainParticipants:   []string{"Aria"},
+		Summary:            "A compact summary.",
+		BoundaryNote:       "The source units form one coherent scene.",
+		BoundaryConfidence: "High",
+	}
+}
+
+func chunkIDs(chunks []contracts.SourceChunk) []string {
+	ids := make([]string, 0, len(chunks))
+	for _, chunk := range chunks {
+		ids = append(ids, chunk.ID)
+	}
+	return ids
+}
+
+func unitIDs(units []source.SourceUnit) []int {
+	ids := make([]int, 0, len(units))
+	for _, unit := range units {
+		ids = append(ids, unit.ID)
+	}
+	return ids
+}
+
+type fakeScenesLLMClient struct {
+	response chunkResponse
+	err      error
+	requests []contracts.StructuredCompletionRequest
+}
+
+func (client *fakeScenesLLMClient) CompleteStructured(ctx 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.(*chunkResponse)
+	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()
+	req.Vars = cloneVars(req.Vars)
+	return req
+}
+
+func cloneVars(in map[string]any) map[string]any {
+	if len(in) == 0 {
+		return nil
+	}
+	out := make(map[string]any, len(in))
+	for key, value := range in {
+		out[key] = value
+	}
+	return out
+}
--- a/internal/modules/dnd/chunk/scenes/model.go
+++ b/internal/modules/dnd/chunk/scenes/model.go
@@ -0,0 +1,30 @@
+package scenes
+
+import "gitea.maximumdirect.net/eric/notarius/internal/modules/dnd/shared"
+
+type chunkResponse struct {
+	Scenes          []sceneResponse `json:"scenes"`
+	BoundaryCaveats []string        `json:"boundary_caveats"`
+}
+
+type sceneResponse struct {
+	StartUnitID        shared.UnitRef `json:"start_unit_id"`
+	EndUnitID          shared.UnitRef `json:"end_unit_id"`
+	ShortTitle         string         `json:"short_title"`
+	PrimaryMode        string         `json:"primary_mode"`
+	MainParticipants   []string       `json:"main_participants"`
+	Summary            string         `json:"summary"`
+	BoundaryNote       string         `json:"boundary_note"`
+	BoundaryConfidence string         `json:"boundary_confidence"`
+}
+
+type normalizedScene struct {
+	StartUnitID        int
+	EndUnitID          int
+	ShortTitle         string
+	PrimaryMode        string
+	MainParticipants   []string
+	Summary            string
+	BoundaryNote       string
+	BoundaryConfidence string
+}
--- a/internal/modules/dnd/chunk/scenes/schema.go
+++ b/internal/modules/dnd/chunk/scenes/schema.go
@@ -0,0 +1,21 @@
+package scenes
+
+import "gitea.maximumdirect.net/eric/notarius/internal/framework/llm"
+
+const (
+	PromptID              = "dnd.scenes"
+	ResponseSchemaKey     = llm.ResponseSchemaKey("dnd_scenes")
+	ResponseSchemaID      = "notarius.dnd.scenes"
+	ResponseSchemaVersion = "v1"
+	ResponseSchemaName    = "notarius_dnd_scenes_v1"
+)
+
+func loadResponseSchema() (llm.ResponseSchema, error) {
+	return llm.LoadResponseSchema(embeddedAssets, llm.ResponseSchemaDefinition{
+		Key:       ResponseSchemaKey,
+		ID:        ResponseSchemaID,
+		Version:   ResponseSchemaVersion,
+		Name:      ResponseSchemaName,
+		AssetPath: "assets/schemas/dnd_scenes.v1.json",
+	})
+}
--- a/internal/modules/dnd/chunk/scenes/schema_test.go
+++ b/internal/modules/dnd/chunk/scenes/schema_test.go
@@ -0,0 +1,151 @@
+package scenes
+
+import (
+	"encoding/json"
+	"strings"
+	"testing"
+)
+
+func TestLoadResponseSchemaForScenes(t *testing.T) {
+	schema, err := loadResponseSchema()
+	if err != nil {
+		t.Fatalf("loadResponseSchema() error = %v, want nil", err)
+	}
+	if schema.Key != ResponseSchemaKey {
+		t.Fatalf("schema.Key = %q, want %q", schema.Key, ResponseSchemaKey)
+	}
+	if schema.ID != ResponseSchemaID {
+		t.Fatalf("schema.ID = %q, want %q", schema.ID, ResponseSchemaID)
+	}
+	if schema.Version != ResponseSchemaVersion {
+		t.Fatalf("schema.Version = %q, want %q", schema.Version, ResponseSchemaVersion)
+	}
+	if schema.Name != ResponseSchemaName {
+		t.Fatalf("schema.Name = %q, want %q", schema.Name, ResponseSchemaName)
+	}
+	if !strings.HasPrefix(schema.SHA256, "sha256:") {
+		t.Fatalf("schema.SHA256 = %q, want sha256 prefix", schema.SHA256)
+	}
+	if !json.Valid(schema.JSONSchema) {
+		t.Fatalf("schema.JSONSchema is invalid JSON: %s", schema.JSONSchema)
+	}
+}
+
+func TestResponseSchemaShapeUsesSourceUnitBoundaries(t *testing.T) {
+	schema, err := loadResponseSchema()
+	if err != nil {
+		t.Fatalf("loadResponseSchema() error = %v, want nil", err)
+	}
+
+	var decoded map[string]any
+	if err := json.Unmarshal(schema.JSONSchema, &decoded); err != nil {
+		t.Fatalf("Unmarshal() error = %v, want nil", err)
+	}
+	if decoded["$id"] != ResponseSchemaID {
+		t.Fatalf("$id = %#v, want %q", decoded["$id"], ResponseSchemaID)
+	}
+	if decoded["additionalProperties"] != false {
+		t.Fatalf("additionalProperties = %#v, want false", decoded["additionalProperties"])
+	}
+
+	properties := decoded["properties"].(map[string]any)
+	if _, ok := properties["artifact_type"]; ok {
+		t.Fatal("schema includes artifact_type, want only scene response fields")
+	}
+	if _, ok := properties["session_scope"]; ok {
+		t.Fatal("schema includes session_scope, want no session wrapper")
+	}
+
+	sceneProperties := properties["scenes"].(map[string]any)["items"].(map[string]any)["properties"].(map[string]any)
+	for _, field := range []string{"scene_id", "start_segment_id", "end_segment_id"} {
+		if _, ok := sceneProperties[field]; ok {
+			t.Fatalf("scene schema includes old field %q", field)
+		}
+	}
+	for _, field := range []string{"start_unit_id", "end_unit_id"} {
+		property := sceneProperties[field].(map[string]any)
+		if property["type"] != "integer" {
+			t.Fatalf("%s type = %#v, want integer", field, property["type"])
+		}
+		if property["minimum"] != float64(1) {
+			t.Fatalf("%s minimum = %#v, want 1", field, property["minimum"])
+		}
+	}
+
+	modeEnum := sceneProperties["primary_mode"].(map[string]any)["enum"].([]any)
+	if !sameStrings(modeEnum, []string{"Recap", "Discussion", "Combat", "Narrative"}) {
+		t.Fatalf("primary_mode enum = %#v, want Recap/Discussion/Combat/Narrative", modeEnum)
+	}
+	confidenceEnum := sceneProperties["boundary_confidence"].(map[string]any)["enum"].([]any)
+	if !sameStrings(confidenceEnum, []string{"High", "Medium", "Low"}) {
+		t.Fatalf("boundary_confidence enum = %#v, want High/Medium/Low", confidenceEnum)
+	}
+
+	boundaryCaveatItems := decoded["properties"].(map[string]any)["boundary_caveats"].(map[string]any)["items"].(map[string]any)
+	if boundaryCaveatItems["type"] != "string" {
+		t.Fatalf("boundary_caveats.items.type = %#v, want string", boundaryCaveatItems["type"])
+	}
+	if boundaryCaveatItems["minLength"] != float64(1) {
+		t.Fatalf("boundary_caveats.items.minLength = %#v, want 1", boundaryCaveatItems["minLength"])
+	}
+}
+
+func TestResponseStructAcceptsIntegerBoundaries(t *testing.T) {
+	raw := []byte(`{
+		"scenes": [
+			{
+				"start_unit_id": 1,
+				"end_unit_id": 3,
+				"short_title": "Ambush",
+				"primary_mode": "Combat",
+				"main_participants": ["Aria"],
+				"summary": "The party fights.",
+				"boundary_note": "Combat starts and resolves.",
+				"boundary_confidence": "High"
+			}
+		],
+		"boundary_caveats": []
+	}`)
+
+	var response chunkResponse
+	if err := json.Unmarshal(raw, &response); err != nil {
+		t.Fatalf("Unmarshal() error = %v, want nil", err)
+	}
+	if got := response.Scenes[0].StartUnitID.String(); got != "1" {
+		t.Fatalf("StartUnitID = %q, want 1", got)
+	}
+	if got := response.Scenes[0].EndUnitID.String(); got != "3" {
+		t.Fatalf("EndUnitID = %q, want 3", got)
+	}
+}
+
+func TestResponseSchemaJSONIsMutationSafe(t *testing.T) {
+	first, err := loadResponseSchema()
+	if err != nil {
+		t.Fatalf("loadResponseSchema() error = %v, want nil", err)
+	}
+	first.JSONSchema[0] = '['
+
+	second, err := loadResponseSchema()
+	if err != nil {
+		t.Fatalf("loadResponseSchema() error = %v, want nil", err)
+	}
+	if !json.Valid(second.JSONSchema) {
+		t.Fatalf("schema JSON was mutated: %s", second.JSONSchema)
+	}
+	if len(second.JSONSchema) > 0 && second.JSONSchema[0] == '[' {
+		t.Fatalf("schema JSON did not use defensive copy")
+	}
+}
+
+func sameStrings(got []any, want []string) bool {
+	if len(got) != len(want) {
+		return false
+	}
+	for i := range want {
+		if got[i] != want[i] {
+			return false
+		}
+	}
+	return true
+}
--- a/internal/modules/dnd/chunk/scenes/scriptorium_assets.go
+++ b/internal/modules/dnd/chunk/scenes/scriptorium_assets.go
@@ -0,0 +1,45 @@
+package scenes
+
+import (
+	"fmt"
+	"sync"
+
+	"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 scriptoriumPromptRoot = "assets/prompts"
+
+func RegisterPromptAssets(registry *llm.AssetRegistry) error {
+	promptFS, err := shared.ModulePromptFS("dnd.scenes", embeddedAssets, []promptfs.ModulePromptFile{
+		{Name: "dnd.scenes.yaml", Path: "assets/prompts/dnd.scenes.yaml"},
+		{Name: "task.md", Path: "assets/prompts/task.md"},
+		{Name: "instructions.md", Path: "assets/prompts/instructions.md"},
+	})
+	if err != nil {
+		return fmt.Errorf("prepare scene prompt assets: %w", err)
+	}
+	if err := registry.RegisterPromptFS(promptFS, scriptoriumPromptRoot); err != nil {
+		return err
+	}
+	return registry.RegisterSchemaFS(embeddedAssets, "assets/schemas")
+}
+
+func scriptoriumPromptMetadata() (string, error) {
+	scriptoriumPromptHashOnce.Do(func() {
+		parts := append([]llm.AssetHashPart{
+			{FS: embeddedAssets, Path: "assets/prompts/dnd.scenes.yaml"},
+			{FS: embeddedAssets, Path: "assets/prompts/task.md"},
+			{FS: embeddedAssets, Path: "assets/prompts/instructions.md"},
+		}, append(shared.CommonHashParts(), shared.ReferenceHashParts()...)...)
+		scriptoriumPromptHash, scriptoriumPromptHashErr = llm.HashAssets(parts)
+	})
+	return scriptoriumPromptHash, scriptoriumPromptHashErr
+}
+
+var (
+	scriptoriumPromptHashOnce sync.Once
+	scriptoriumPromptHash     string
+	scriptoriumPromptHashErr  error
+)
--- a/internal/modules/dnd/chunk/scenes/scriptorium_assets_test.go
+++ b/internal/modules/dnd/chunk/scenes/scriptorium_assets_test.go
@@ -0,0 +1,129 @@
+package scenes
+
+import (
+	"context"
+	"encoding/json"
+	"strings"
+	"testing"
+	"time"
+
+	"gitea.maximumdirect.net/eric/notarius/internal/framework/llm"
+	"gitea.maximumdirect.net/eric/scriptorium"
+)
+
+func TestScriptoriumPromptPreparesTranscriptAndTaskMessages(t *testing.T) {
+	transcript := []byte(`{"id":"session-1","segments":[{"id":"u1","text":"We enter the crypt."}]}`)
+	prepared := prepareScenesPrompt(t, transcript, "Alice: Aria", "Aria: cleric", "Brightmantle: temple")
+
+	if prepared.PromptID != PromptID {
+		t.Fatalf("prompt id = %q, want %q", prepared.PromptID, PromptID)
+	}
+	if got := len(prepared.Messages); got != 5 {
+		t.Fatalf("message count = %d, want 5", got)
+	}
+	if prepared.Messages[1].Role != "user" || prepared.Messages[1].CacheControl == nil {
+		t.Fatalf("transcript message did not render as cacheable user message: %#v", prepared.Messages[1])
+	}
+	if !strings.Contains(prepared.Messages[1].Content, string(transcript)) {
+		t.Fatalf("transcript message did not include source input")
+	}
+	if prepared.Messages[2].CacheControl == nil {
+		t.Fatalf("reference message did not render as cacheable user message: %#v", prepared.Messages[2])
+	}
+	if !strings.Contains(prepared.Messages[2].Content, "Alice: Aria") {
+		t.Fatalf("reference message missing player content")
+	}
+	if !strings.Contains(prepared.Messages[2].Content, "Aria: cleric") {
+		t.Fatalf("reference message missing party content")
+	}
+	if !strings.Contains(prepared.Messages[2].Content, "Brightmantle: temple") {
+		t.Fatalf("reference message missing glossary content")
+	}
+	if strings.Contains(prepared.Messages[3].Content, string(transcript)) {
+		t.Fatalf("task message leaked transcript bytes")
+	}
+}
+
+func TestScriptoriumPromptDiagnosticsOmitRawMaterials(t *testing.T) {
+	transcript := []byte(`{"secret":"source text"}`)
+	prepared := prepareScenesPrompt(t, transcript, "private player note", "private party note", "private glossary note")
+	metadata := New().ManifestMetadata()
+
+	payload, err := json.Marshal(map[string]any{
+		"prepared": map[string]any{
+			"prompt_id":              prepared.PromptID,
+			"prompt_version":         prepared.PromptVersion,
+			"prompt_hash":            prepared.PromptHash,
+			"rendered_prompt_hash":   prepared.RenderedPromptHash,
+			"selected_profile_id":    prepared.SelectedProfileID,
+			"output_contract":        prepared.OutputContract,
+			"input_hashes":           prepared.InputHashes,
+			"effective_model_params": prepared.EffectiveModelParams,
+		},
+		"manifest": metadata,
+	})
+	if err != nil {
+		t.Fatalf("marshal diagnostics: %v", err)
+	}
+	diagnostics := string(payload)
+	for _, forbidden := range []string{
+		"source text",
+		"private player note",
+		"private party note",
+		"private glossary note",
+		`"properties"`,
+		"start_unit_id",
+	} {
+		if strings.Contains(diagnostics, forbidden) {
+			t.Fatalf("diagnostics leaked %q: %s", forbidden, diagnostics)
+		}
+	}
+	if metadata["prompt_id"] != PromptID || metadata["prompt_version"] != ResponseSchemaVersion {
+		t.Fatalf("manifest prompt metadata = %#v", metadata)
+	}
+	if !strings.HasPrefix(metadata["prompt_sha256"].(string), "sha256:") {
+		t.Fatalf("manifest prompt hash = %#v, want sha256-prefixed", metadata["prompt_sha256"])
+	}
+}
+
+func prepareScenesPrompt(t *testing.T, transcript []byte, players string, party string, glossary string) *scriptorium.PreparedRun {
+	t.Helper()
+	registry := llm.NewAssetRegistry()
+	if err := RegisterPromptAssets(registry); err != nil {
+		t.Fatalf("register scene prompt assets: %v", err)
+	}
+	engine := newScenesScriptoriumEngine(t, registry)
+	prepared, err := engine.Prepare(context.Background(), scriptorium.RunRequest{
+		PromptID:      PromptID,
+		PromptVersion: ResponseSchemaVersion,
+		ProfileID:     "scene-test-profile",
+		Inputs: map[string]scriptorium.ArtifactRef{
+			"transcript": scriptorium.InlineWithURI("file:///session.json", string(transcript)),
+			"players":    scriptorium.Inline(players),
+			"party":      scriptorium.Inline(party),
+			"glossary":   scriptorium.Inline(glossary),
+		},
+	})
+	if err != nil {
+		t.Fatalf("Prepare() error = %v, want nil", err)
+	}
+	return prepared
+}
+
+func newScenesScriptoriumEngine(t *testing.T, registry *llm.AssetRegistry) *scriptorium.Engine {
+	t.Helper()
+	options, err := registry.ScriptoriumOptions()
+	if err != nil {
+		t.Fatalf("ScriptoriumOptions() error = %v, want nil", err)
+	}
+	options = append(options, scriptorium.WithProfiles(scriptorium.OpenAICompatibleProfile(scriptorium.OpenAICompatibleProfileConfig{
+		ID:       "scene-test-profile",
+		Endpoint: "http://127.0.0.1:1/v1",
+		Model:    "scene-test-model",
+	})))
+	engine, err := scriptorium.NewEngine(scriptorium.Config{Timeout: time.Second}, options...)
+	if err != nil {
+		t.Fatalf("NewEngine() error = %v, want nil", err)
+	}
+	return engine
+}
--- a/internal/modules/dnd/extract/spells/assets.go
+++ b/internal/modules/dnd/extract/spells/assets.go
@@ -0,0 +1,6 @@
+package spells
+
+import "embed"
+
+//go:embed assets/schemas/*.json assets/prompts/*.yaml assets/prompts/*.md
+var embeddedAssets embed.FS
--- a/internal/modules/dnd/extract/spells/assets/prompts/dnd.spells.yaml
+++ b/internal/modules/dnd/extract/spells/assets/prompts/dnd.spells.yaml
@@ -0,0 +1,36 @@
+id: dnd.spells
+version: "v1"
+default_profile: gemini-2-flash
+inputs:
+  - name: transcript
+    required: true
+    content_type: application/json
+  - name: players
+    required: false
+    content_type: text/plain
+  - name: party
+    required: false
+    content_type: text/plain
+  - name: glossary
+    required: false
+    content_type: text/plain
+messages:
+  - role: system
+    content_file: ./sharedassets/common-dnd-system.md
+  - role: user
+    content_file: ./sharedassets/common-dnd-transcript.md
+    cache_control:
+      type: ephemeral
+  - role: user
+    content_file: ./sharedassets/common-dnd-references.md
+    cache_control:
+      type: ephemeral
+  - role: user
+    content_file: ./task.md
+  - role: user
+    content_file: ./instructions.md
+output:
+  format: json
+  validation_mode: json_schema
+  schema_path: dnd_spells_llm.v1.json
+  repair_attempts: 0
--- a/internal/modules/dnd/extract/spells/assets/prompts/instructions.md
+++ b/internal/modules/dnd/extract/spells/assets/prompts/instructions.md
@@ -0,0 +1,12 @@
+Source references must use integer source-unit IDs from the transcript. Provide
+start_unit_id and end_unit_id for each source reference; the extractor assigns
+source_id automatically.
+
+Return only D&D spell-cast artifacts. For each spell cast, identify the in-world
+caster, spell name, effect, narrative description, and source references.
+
+Use player, party, and glossary reference material only to clarify source text.
+Do not return spells, casters, or effects that are mentioned only in reference
+material.
+
+Return exactly one JSON object and no explanatory text.
--- a/internal/modules/dnd/extract/spells/assets/prompts/task.md
+++ b/internal/modules/dnd/extract/spells/assets/prompts/task.md
@@ -0,0 +1,5 @@
+Extract Dungeons & Dragons spell-cast artifacts from the provided transcript.
+
+Extract only spell casts that are supported by the transcript. Do not infer
+spells from general D&D knowledge or from table chatter that does not identify a
+spell being cast.
--- a/internal/modules/dnd/extract/spells/assets/schemas/dnd_spells.v1.json
+++ b/internal/modules/dnd/extract/spells/assets/schemas/dnd_spells.v1.json
@@ -0,0 +1,64 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "notarius.dnd.spells",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["spell_casts"],
+  "properties": {
+    "spell_casts": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "caster",
+          "spell",
+          "effect",
+          "narrative_description",
+          "source_refs"
+        ],
+        "properties": {
+          "caster": {
+            "type": "string",
+            "minLength": 1
+          },
+          "spell": {
+            "type": "string",
+            "minLength": 1
+          },
+          "effect": {
+            "type": "string",
+            "minLength": 1
+          },
+          "narrative_description": {
+            "type": "string",
+            "minLength": 1
+          },
+          "source_refs": {
+            "type": "array",
+            "minItems": 1,
+            "items": {
+              "type": "object",
+              "additionalProperties": false,
+              "required": ["source_id", "start_unit_id", "end_unit_id"],
+              "properties": {
+                "source_id": {
+                  "type": "string",
+                  "minLength": 1
+                },
+                "start_unit_id": {
+                  "type": "integer",
+                  "minimum": 1
+                },
+                "end_unit_id": {
+                  "type": "integer",
+                  "minimum": 1
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}
--- a/internal/modules/dnd/extract/spells/assets/schemas/dnd_spells_llm.v1.json
+++ b/internal/modules/dnd/extract/spells/assets/schemas/dnd_spells_llm.v1.json
@@ -0,0 +1,60 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "notarius.dnd.spells.llm",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["spell_casts"],
+  "properties": {
+    "spell_casts": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "caster",
+          "spell",
+          "effect",
+          "narrative_description",
+          "source_refs"
+        ],
+        "properties": {
+          "caster": {
+            "type": "string",
+            "minLength": 1
+          },
+          "spell": {
+            "type": "string",
+            "minLength": 1
+          },
+          "effect": {
+            "type": "string",
+            "minLength": 1
+          },
+          "narrative_description": {
+            "type": "string",
+            "minLength": 1
+          },
+          "source_refs": {
+            "type": "array",
+            "minItems": 1,
+            "items": {
+              "type": "object",
+              "additionalProperties": false,
+              "required": ["start_unit_id", "end_unit_id"],
+              "properties": {
+                "start_unit_id": {
+                  "type": "integer",
+                  "minimum": 1
+                },
+                "end_unit_id": {
+                  "type": "integer",
+                  "minimum": 1
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}
--- a/internal/modules/dnd/extract/spells/canonicalize.go
+++ b/internal/modules/dnd/extract/spells/canonicalize.go
@@ -0,0 +1,92 @@
+package spells
+
+import (
+	"sort"
+
+	"gitea.maximumdirect.net/eric/notarius/internal/modules/dnd/shared"
+)
+
+func canonicalizeResponse(response *extractionResponse, sourceID string) {
+	if response == nil {
+		return
+	}
+	for index := range response.SpellCasts {
+		canonicalizeSpellCast(&response.SpellCasts[index], sourceID)
+	}
+	sort.SliceStable(response.SpellCasts, func(i, j int) bool {
+		left, leftOK := earliestSourceUnit(response.SpellCasts[i])
+		right, rightOK := earliestSourceUnit(response.SpellCasts[j])
+		if leftOK != rightOK {
+			return leftOK
+		}
+		if !leftOK {
+			return false
+		}
+		return left < right
+	})
+}
+
+func canonicalizeSpellCast(spell *spellCastResponse, sourceID string) {
+	for index := range spell.SourceRefs {
+		spell.SourceRefs[index].SourceID = sourceID
+		spell.SourceRefs[index].StartUnitID = canonicalUnitRef(spell.SourceRefs[index].StartUnitID)
+		spell.SourceRefs[index].EndUnitID = canonicalUnitRef(spell.SourceRefs[index].EndUnitID)
+	}
+	sort.SliceStable(spell.SourceRefs, func(i, j int) bool {
+		left := spell.SourceRefs[i]
+		right := spell.SourceRefs[j]
+		if left.StartUnitID.Int() != right.StartUnitID.Int() {
+			return unitSortValue(left.StartUnitID) < unitSortValue(right.StartUnitID)
+		}
+		return unitSortValue(left.EndUnitID) < unitSortValue(right.EndUnitID)
+	})
+	spell.SourceRefs = dedupeSourceRefs(spell.SourceRefs)
+}
+
+func canonicalUnitRef(ref shared.UnitRef) shared.UnitRef {
+	value := ref.Int()
+	if value <= 0 {
+		return ref
+	}
+	return shared.UnitRefFromInt(value)
+}
+
+func dedupeSourceRefs(refs []shared.SourceRefResponse) []shared.SourceRefResponse {
+	if len(refs) < 2 {
+		return refs
+	}
+	out := refs[:0]
+	var previous shared.SourceRefResponse
+	for index, ref := range refs {
+		if index > 0 && sameSourceRef(previous, ref) {
+			continue
+		}
+		out = append(out, ref)
+		previous = ref
+	}
+	return out
+}
+
+func sameSourceRef(left shared.SourceRefResponse, right shared.SourceRefResponse) bool {
+	return left.SourceID == right.SourceID &&
+		left.StartUnitID.Int() == right.StartUnitID.Int() &&
+		left.EndUnitID.Int() == right.EndUnitID.Int()
+}
+
+func earliestSourceUnit(spell spellCastResponse) (int, bool) {
+	for _, ref := range spell.SourceRefs {
+		start := ref.StartUnitID.Int()
+		if start > 0 {
+			return start, true
+		}
+	}
+	return 0, false
+}
+
+func unitSortValue(ref shared.UnitRef) int {
+	value := ref.Int()
+	if value <= 0 {
+		return int(^uint(0) >> 1)
+	}
+	return value
+}
--- a/internal/modules/dnd/extract/spells/extractor.go
+++ b/internal/modules/dnd/extract/spells/extractor.go
@@ -0,0 +1,174 @@
+package spells
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"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/shared"
+)
+
+const Key = "dnd/spells"
+const ArtifactType = "dnd.spell_cast"
+const SchemaVersion = "v1"
+
+var requiredCapabilities = []string{
+	"chunks",
+	"source.transcript",
+}
+
+var providedCapabilities = []string{
+	"dnd.spell_casts",
+}
+
+var referenceSlotDescriptions = shared.ReferenceSlotDescriptions{
+	Glossary: "Optional campaign glossary reference material used only for disambiguation.",
+	Party:    "Optional party roster reference material used only for disambiguation.",
+	Players:  "Optional player list reference material used only for disambiguation.",
+	Roster:   "Deprecated alias for party roster reference material used only for disambiguation.",
+}
+
+var _ contracts.Extractor = (*Extractor)(nil)
+
+type Extractor struct{}
+
+func New() *Extractor {
+	return &Extractor{}
+}
+
+func (e *Extractor) Key() string {
+	return Key
+}
+
+func (e *Extractor) ReferenceSlots() []contracts.ReferenceSlot {
+	return shared.ReferenceSlots(referenceSlotDescriptions)
+}
+
+func (e *Extractor) ManifestMetadata() map[string]any {
+	promptSHA, err := scriptoriumPromptMetadata()
+	if err != nil {
+		promptSHA = ""
+	}
+	metadata := map[string]any{
+		"prompt_id":            PromptID,
+		"prompt_version":       SchemaVersion,
+		"prompt_sha256":        promptSHA,
+		"response_schema_key":  string(ResponseSchemaKey),
+		"response_schema_id":   ResponseSchemaID,
+		"response_schema_name": ResponseSchemaName,
+	}
+	if schema, err := loadResponseSchema(); err == nil {
+		metadata["response_schema_version"] = schema.Version
+		metadata["response_schema_sha256"] = schema.SHA256
+	}
+	return metadata
+}
+
+func (e *Extractor) Extract(ctx context.Context, req contracts.ExtractionRequest) (contracts.ExtractionResult, error) {
+	if e == nil {
+		return contracts.ExtractionResult{}, extractorErrorf("extractor must not be nil")
+	}
+	if ctx == nil {
+		return contracts.ExtractionResult{}, extractorErrorf("context must not be nil")
+	}
+	if err := ctx.Err(); err != nil {
+		return contracts.ExtractionResult{}, extractorErrorf("context error before extraction: %w", err)
+	}
+	if req.Source == nil {
+		return contracts.ExtractionResult{}, extractorErrorf("source must not be nil")
+	}
+	if req.Chunk == nil {
+		return contracts.ExtractionResult{}, extractorErrorf("chunk must not be nil")
+	}
+	if len(req.Chunk.Units) == 0 {
+		return contracts.ExtractionResult{}, extractorErrorf("chunk %q units must not be empty", req.Chunk.ID)
+	}
+	if req.LLMClient == nil {
+		return contracts.ExtractionResult{}, extractorErrorf("LLM client must not be nil")
+	}
+	sourceInput, err := chunkSourceInput(req)
+	if err != nil {
+		return contracts.ExtractionResult{}, err
+	}
+
+	var response extractionResponse
+	if _, err := req.LLMClient.CompleteStructured(ctx, contracts.StructuredCompletionRequest{
+		StageName:     Key,
+		PromptID:      PromptID,
+		PromptVersion: SchemaVersion,
+		ProfileID:     req.LLMProfile,
+		SessionID:     req.SessionID,
+		Inputs:        shared.PromptInputs(sourceInput, req.References),
+	}, &response); err != nil {
+		return contracts.ExtractionResult{}, extractorErrorf("complete structured output: %w", err)
+	}
+	canonicalizeResponse(&response, req.Source.ID)
+	content, err := json.Marshal(response)
+	if err != nil {
+		return contracts.ExtractionResult{}, extractorErrorf("marshal canonical output: %w", err)
+	}
+	schema, err := loadResponseSchema()
+	if err != nil {
+		return contracts.ExtractionResult{}, extractorErrorf("load response schema: %w", err)
+	}
+	return contracts.ExtractionResult{
+		Output: contracts.ExtractOutput{
+			Schema: contracts.ResponseSchema{
+				ID:         ResponseSchemaID,
+				Name:       ResponseSchemaName,
+				Version:    SchemaVersion,
+				JSONSchema: append([]byte(nil), schema.JSONSchema...),
+			},
+			Payload: contracts.RawPayload{
+				Content:   content,
+				MediaType: "application/json",
+				Metadata: map[string]any{
+					"spell_cast_count": len(response.SpellCasts),
+				},
+			},
+		},
+	}, nil
+}
+
+func chunkSourceInput(req contracts.ExtractionRequest) (contracts.LLMInputMaterial, error) {
+	material := req.SourceInput.Clone()
+	if len(material.Content) == 0 {
+		material = contracts.NewLLMInputMaterial("source", req.Chunk.MediaType, req.Chunk.Content, "", "")
+	}
+	if !bytes.Equal(material.Content, req.Chunk.Content) {
+		return contracts.LLMInputMaterial{}, extractorErrorf("source input must match chunk %q content", req.Chunk.ID)
+	}
+	if material.Name == "" {
+		material.Name = "source"
+	}
+	if material.MediaType == "" {
+		material.MediaType = req.Chunk.MediaType
+	}
+	if material.SizeBytes == 0 {
+		material.SizeBytes = int64(len(material.Content))
+	}
+	return material, nil
+}
+
+func ModuleSpec() pipeline.ModuleSpec {
+	return pipeline.ModuleSpec{
+		Key:            Key,
+		Stage:          pipeline.StageExtract,
+		Requires:       append([]string(nil), requiredCapabilities...),
+		Provides:       append([]string(nil), providedCapabilities...),
+		ReferenceSlots: shared.ReferenceSlots(referenceSlotDescriptions),
+	}
+}
+
+func Register(registry *pipeline.ExtractorRegistry) error {
+	return registry.RegisterWithSpec(ModuleSpec(), func() (contracts.Extractor, error) {
+		return New(), nil
+	})
+}
+
+func extractorErrorf(format string, args ...any) error {
+	return fmt.Errorf("dnd spells extractor: "+format, args...)
+}
--- a/internal/modules/dnd/extract/spells/extractor_test.go
+++ b/internal/modules/dnd/extract/spells/extractor_test.go
@@ -0,0 +1,477 @@
+package spells
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"strings"
+	"testing"
+
+	"gitea.maximumdirect.net/eric/notarius/internal/framework/contracts"
+	"gitea.maximumdirect.net/eric/notarius/internal/modules/dnd/shared"
+)
+
+func TestExtractReturnsCanonicalOutputFromStructuredResponse(t *testing.T) {
+	client := &fakeSpellsLLMClient{
+		response: extractionResponse{
+			SpellCasts: []spellCastResponse{
+				{
+					Caster:               " Aria ",
+					Spell:                " Cure Wounds ",
+					Effect:               " Heals an injured ally. ",
+					NarrativeDescription: " Aria restores the fighter after the fight. ",
+					SourceRefs:           responseSourceRefsInt("transcript", 1, 2),
+				},
+			},
+		},
+		content: []byte(`{"spell_casts":[{"caster":" Aria ","spell":" Cure Wounds ","effect":" Heals an injured ally. ","narrative_description":" Aria restores the fighter after the fight. ","source_refs":[{"source_id":"session-alpha","start_unit_id":1,"end_unit_id":2}]}],"raw_marker":true}`),
+	}
+
+	extractReq := extractionRequestWithClient(client)
+	result, err := New().Extract(context.Background(), extractReq)
+	if err != nil {
+		t.Fatalf("Extract() error = %v, want nil", err)
+	}
+
+	if len(client.requests) != 1 {
+		t.Fatalf("LLM calls = %d, want 1", len(client.requests))
+	}
+	llmReq := client.requests[0]
+	if llmReq.StageName != Key {
+		t.Fatalf("StageName = %q, want %q", llmReq.StageName, Key)
+	}
+	if llmReq.PromptID != PromptID || llmReq.PromptVersion != SchemaVersion {
+		t.Fatalf("prompt = %q/%q, want %q/%q", llmReq.PromptID, llmReq.PromptVersion, PromptID, SchemaVersion)
+	}
+	if llmReq.SessionID != "session-123" || llmReq.ProfileID != "profile-spells" {
+		t.Fatalf("session/profile = %q/%q, want session-123/profile-spells", llmReq.SessionID, llmReq.ProfileID)
+	}
+	transcript := llmReq.Inputs["transcript"]
+	if transcript.Name != "transcript" || transcript.MediaType != "application/json" || transcript.Digest != "sha256:chunk" || transcript.OriginURI != "file:///session-alpha.json" {
+		t.Fatalf("transcript metadata = %#v", transcript)
+	}
+	if got := string(transcript.Content); got != string(extractReq.Chunk.Content) {
+		t.Fatalf("transcript content = %q, want chunk content %q", got, extractReq.Chunk.Content)
+	}
+
+	if result.Output.Payload.MediaType != "application/json" {
+		t.Fatalf("MediaType = %q, want application/json", result.Output.Payload.MediaType)
+	}
+	if result.Output.Schema.ID != ResponseSchemaID || result.Output.Schema.Name != ResponseSchemaName || result.Output.Schema.Version != SchemaVersion {
+		t.Fatalf("schema = %#v, want response schema provenance", result.Output.Schema)
+	}
+	if !json.Valid(result.Output.Schema.JSONSchema) {
+		t.Fatalf("schema JSON is invalid or missing: %s", result.Output.Schema.JSONSchema)
+	}
+	if strings.Contains(string(result.Output.Payload.Content), "raw_marker") {
+		t.Fatalf("content = %q, want canonical payload without raw completion marker", result.Output.Payload.Content)
+	}
+
+	var payload extractionResponse
+	if err := json.Unmarshal(result.Output.Payload.Content, &payload); err != nil {
+		t.Fatalf("Unmarshal(Content) error = %v, want nil", err)
+	}
+	if len(payload.SpellCasts) != 1 || payload.SpellCasts[0].Spell != " Cure Wounds " {
+		t.Fatalf("payload = %#v, want structured response fields", payload)
+	}
+	if got := payload.SpellCasts[0].SourceRefs[0].SourceID; got != "session-alpha" {
+		t.Fatalf("source_id = %q, want canonical source document ID", got)
+	}
+}
+
+func TestExtractorManifestMetadataIncludesPromptAndSchemaProvenance(t *testing.T) {
+	metadata := New().ManifestMetadata()
+
+	tests := map[string]string{
+		"prompt_id":               PromptID,
+		"prompt_version":          SchemaVersion,
+		"response_schema_key":     string(ResponseSchemaKey),
+		"response_schema_id":      ResponseSchemaID,
+		"response_schema_name":    ResponseSchemaName,
+		"response_schema_version": SchemaVersion,
+	}
+	for key, want := range tests {
+		if metadata[key] != want {
+			t.Fatalf("metadata[%q] = %#v, want %q", key, metadata[key], want)
+		}
+	}
+	for _, key := range []string{"prompt_sha256", "response_schema_sha256"} {
+		value, ok := metadata[key].(string)
+		if !ok || !strings.HasPrefix(value, "sha256:") {
+			t.Fatalf("metadata[%q] = %#v, want sha256 value", key, metadata[key])
+		}
+	}
+}
+
+func TestExtractPassesReferencesAsPromptInputs(t *testing.T) {
+	client := &fakeSpellsLLMClient{response: extractionResponse{SpellCasts: []spellCastResponse{}}}
+	req := extractionRequestWithClient(client)
+	req.References = contracts.ReferenceSet{
+		Slots: map[string]contracts.ResolvedReferenceSlot{
+			"players": {
+				Slot: contracts.ReferenceSlot{Name: "players"},
+				Items: []contracts.ReferenceItem{
+					{SlotName: "players", Content: []byte("Alice: Aria Brightmantle")},
+				},
+			},
+			"party": {
+				Slot: contracts.ReferenceSlot{Name: "party"},
+				Items: []contracts.ReferenceItem{
+					{SlotName: "party", Content: []byte("Aria Brightmantle: party cleric")},
+				},
+			},
+			"glossary": {
+				Slot: contracts.ReferenceSlot{Name: "glossary"},
+				Items: []contracts.ReferenceItem{
+					{SlotName: "glossary", Content: []byte("Brightmantle: local temple name")},
+				},
+			},
+		},
+	}
+
+	if _, err := New().Extract(context.Background(), req); err != nil {
+		t.Fatalf("Extract() error = %v, want nil", err)
+	}
+
+	if len(client.requests) != 1 {
+		t.Fatalf("LLM calls = %d, want 1", len(client.requests))
+	}
+	request := client.requests[0]
+	if request.PromptID != PromptID || request.PromptVersion != SchemaVersion {
+		t.Fatalf("prompt = %q/%q, want %q/%q", request.PromptID, request.PromptVersion, PromptID, SchemaVersion)
+	}
+	if got := string(request.Inputs["players"].Content); got != "Alice: Aria Brightmantle" {
+		t.Fatalf("players input = %q, want reference content", got)
+	}
+	if got := string(request.Inputs["party"].Content); got != "Aria Brightmantle: party cleric" {
+		t.Fatalf("party input = %q, want reference content", got)
+	}
+	if got := string(request.Inputs["glossary"].Content); got != "Brightmantle: local temple name" {
+		t.Fatalf("glossary input = %q, want reference content", got)
+	}
+	if strings.Contains(string(request.Inputs["transcript"].Content), "Aria Brightmantle: party cleric") {
+		t.Fatalf("transcript input contains reference content")
+	}
+}
+
+func TestPromptInputsMapLegacyRosterReferenceToParty(t *testing.T) {
+	inputs := shared.PromptInputs(spellSourceInput(), contracts.ReferenceSet{
+		Slots: map[string]contracts.ResolvedReferenceSlot{
+			"roster": {
+				Slot: contracts.ReferenceSlot{Name: "roster"},
+				Items: []contracts.ReferenceItem{
+					{SlotName: "roster", Content: []byte("Legacy roster text")},
+				},
+			},
+		},
+	})
+
+	if got := string(inputs["party"].Content); got != "Legacy roster text" {
+		t.Fatalf("party input = %q, want legacy roster content", got)
+	}
+	if _, ok := inputs["roster"]; ok {
+		t.Fatalf("roster prompt input was present; want only party input")
+	}
+}
+
+func TestExtractReturnsRawOutputForEmptyResponse(t *testing.T) {
+	client := &fakeSpellsLLMClient{response: extractionResponse{SpellCasts: []spellCastResponse{}}}
+
+	result, err := New().Extract(context.Background(), extractionRequestWithClient(client))
+	if err != nil {
+		t.Fatalf("Extract() error = %v, want nil", err)
+	}
+	var payload extractionResponse
+	if err := json.Unmarshal(result.Output.Payload.Content, &payload); err != nil {
+		t.Fatalf("Unmarshal(Content) error = %v, want nil", err)
+	}
+	if len(payload.SpellCasts) != 0 {
+		t.Fatalf("SpellCasts = %#v, want none", payload.SpellCasts)
+	}
+}
+
+func TestExtractReturnsCanonicalOutputForMalformedStructuredResponse(t *testing.T) {
+	client := &fakeSpellsLLMClient{response: extractionResponse{}}
+
+	result, err := New().Extract(context.Background(), extractionRequestWithClient(client))
+	if err != nil {
+		t.Fatalf("Extract() error = %v, want nil", err)
+	}
+	if string(result.Output.Payload.Content) != `{"spell_casts":null}` {
+		t.Fatalf("content = %s, want canonical structured output", result.Output.Payload.Content)
+	}
+}
+
+func TestExtractWrapsLLMClientError(t *testing.T) {
+	client := &fakeSpellsLLMClient{err: errors.New("provider unavailable")}
+
+	_, err := New().Extract(context.Background(), extractionRequestWithClient(client))
+	if err == nil {
+		t.Fatal("Extract() error = nil, want LLM error")
+	}
+	if !strings.Contains(err.Error(), "dnd spells") || !strings.Contains(err.Error(), "provider unavailable") {
+		t.Fatalf("Extract() error = %q, want wrapped LLM context", err.Error())
+	}
+}
+
+func TestExtractRejectsInvalidRequests(t *testing.T) {
+	validClient := &fakeSpellsLLMClient{response: extractionResponse{SpellCasts: []spellCastResponse{}}}
+	validReq := extractionRequestWithClient(validClient)
+	canceledCtx, cancel := context.WithCancel(context.Background())
+	cancel()
+
+	tests := []struct {
+		name      string
+		extractor *Extractor
+		ctx       context.Context
+		req       contracts.ExtractionRequest
+		want      string
+	}{
+		{name: "nil extractor", extractor: nil, ctx: context.Background(), req: validReq, want: "extractor"},
+		{name: "nil context", extractor: New(), ctx: nil, req: validReq, want: "context"},
+		{name: "canceled context", extractor: New(), ctx: canceledCtx, req: validReq, want: "context"},
+		{name: "nil source", extractor: New(), ctx: context.Background(), req: contracts.ExtractionRequest{Chunk: validReq.Chunk, LLMClient: validReq.LLMClient}, want: "source"},
+		{name: "nil chunk", extractor: New(), ctx: context.Background(), req: contracts.ExtractionRequest{Source: validReq.Source, LLMClient: validReq.LLMClient}, want: "chunk"},
+		{name: "empty chunk units", extractor: New(), ctx: context.Background(), req: emptyChunkRequest(validReq), want: "units"},
+		{name: "nil LLM client", extractor: New(), ctx: context.Background(), req: contracts.ExtractionRequest{Source: validReq.Source, Chunk: validReq.Chunk}, want: "LLM client"},
+		{name: "source input mismatches chunk", extractor: New(), ctx: context.Background(), req: mismatchedSourceInputRequest(validReq), want: "must match chunk"},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			_, err := tt.extractor.Extract(tt.ctx, tt.req)
+			if err == nil {
+				t.Fatal("Extract() error = nil, want error")
+			}
+			if !strings.Contains(err.Error(), "dnd spells") || !strings.Contains(err.Error(), tt.want) {
+				t.Fatalf("Extract() error = %q, want %q context", err.Error(), tt.want)
+			}
+		})
+	}
+}
+
+func TestExtractOrdersSpellCastsByEarliestSourceUnit(t *testing.T) {
+	client := &fakeSpellsLLMClient{
+		response: extractionResponse{
+			SpellCasts: []spellCastResponse{
+				{
+					Caster:               "Bandit Shaman",
+					Spell:                "Fire Bolt",
+					Effect:               "Burns.",
+					NarrativeDescription: "Second spell.",
+					SourceRefs:           responseSourceRefs("session-alpha", 2, 2),
+				},
+				{
+					Caster:               "Aria",
+					Spell:                "Cure Wounds",
+					Effect:               "Heals.",
+					NarrativeDescription: "First spell.",
+					SourceRefs:           responseSourceRefs("session-alpha", 1, 1),
+				},
+				{
+					Caster:               "Narrator",
+					Spell:                "Unknown Spell",
+					Effect:               "No cited range.",
+					NarrativeDescription: "This should sort after cited spell casts.",
+				},
+			},
+		},
+	}
+
+	result, err := New().Extract(context.Background(), extractionRequestWithClient(client))
+	if err != nil {
+		t.Fatalf("Extract() error = %v, want nil", err)
+	}
+	var payload extractionResponse
+	if err := json.Unmarshal(result.Output.Payload.Content, &payload); err != nil {
+		t.Fatalf("Unmarshal(Content) error = %v, want nil", err)
+	}
+	if len(payload.SpellCasts) != 3 ||
+		payload.SpellCasts[0].Spell != "Cure Wounds" ||
+		payload.SpellCasts[1].Spell != "Fire Bolt" ||
+		payload.SpellCasts[2].Spell != "Unknown Spell" {
+		t.Fatalf("spell order = %#v, want earliest source-unit order with uncited spell last", payload.SpellCasts)
+	}
+}
+
+func TestExtractCanonicalizesSourceRefs(t *testing.T) {
+	client := &fakeSpellsLLMClient{
+		response: extractionResponse{
+			SpellCasts: []spellCastResponse{
+				{
+					Caster:               "Aria",
+					Spell:                "Cure Wounds",
+					Effect:               "Heals.",
+					NarrativeDescription: "Aria heals.",
+					SourceRefs: []shared.SourceRefResponse{
+						{SourceID: "gameplay_transcript", StartUnitID: shared.UnitRefFromInt(2), EndUnitID: shared.UnitRefFromInt(2)},
+						{SourceID: "", StartUnitID: shared.UnitRefFromInt(1), EndUnitID: shared.UnitRefFromInt(2)},
+						{SourceID: "transcript", StartUnitID: shared.UnitRefFromInt(1), EndUnitID: shared.UnitRefFromInt(2)},
+					},
+				},
+			},
+		},
+	}
+
+	result, err := New().Extract(context.Background(), extractionRequestWithClient(client))
+	if err != nil {
+		t.Fatalf("Extract() error = %v, want nil", err)
+	}
+	var payload extractionResponse
+	if err := json.Unmarshal(result.Output.Payload.Content, &payload); err != nil {
+		t.Fatalf("Unmarshal(Content) error = %v, want nil", err)
+	}
+	refs := payload.SpellCasts[0].SourceRefs
+	if len(refs) != 2 {
+		t.Fatalf("source refs = %#v, want duplicate collapsed", refs)
+	}
+	for _, ref := range refs {
+		if ref.SourceID != "session-alpha" {
+			t.Fatalf("source ref = %#v, want canonical source_id", ref)
+		}
+	}
+	if refs[0].StartUnitID.Int() != 1 || refs[0].EndUnitID.Int() != 2 ||
+		refs[1].StartUnitID.Int() != 2 || refs[1].EndUnitID.Int() != 2 {
+		t.Fatalf("source refs = %#v, want sorted unit ranges", refs)
+	}
+}
+
+func TestExtractPreservesInvalidSourceRefsForValidators(t *testing.T) {
+	client := &fakeSpellsLLMClient{
+		response: extractionResponse{
+			SpellCasts: []spellCastResponse{
+				{
+					Caster:               "Aria",
+					Spell:                "Cure Wounds",
+					Effect:               "Heals.",
+					NarrativeDescription: "Aria heals.",
+					SourceRefs: []shared.SourceRefResponse{
+						{SourceID: "transcript", StartUnitID: shared.UnitRefFromInt(99), EndUnitID: shared.UnitRefFromString("missing")},
+					},
+				},
+			},
+		},
+	}
+
+	result, err := New().Extract(context.Background(), extractionRequestWithClient(client))
+	if err != nil {
+		t.Fatalf("Extract() error = %v, want nil", err)
+	}
+	var payload map[string][]map[string]any
+	if err := json.Unmarshal(result.Output.Payload.Content, &payload); err != nil {
+		t.Fatalf("Unmarshal(Content) error = %v, want nil", err)
+	}
+	ref := payload["spell_casts"][0]["source_refs"].([]any)[0].(map[string]any)
+	if ref["source_id"] != "session-alpha" || ref["start_unit_id"] != float64(99) || ref["end_unit_id"] != "" {
+		t.Fatalf("source ref = %#v, want source_id canonicalized without unit repair", ref)
+	}
+}
+
+func TestExtractDefensivelyCopiesRawContent(t *testing.T) {
+	client := &fakeSpellsLLMClient{
+		response: extractionResponse{
+			SpellCasts: []spellCastResponse{
+				{
+					Caster:               "Aria",
+					Spell:                "Cure Wounds",
+					Effect:               "Heals.",
+					NarrativeDescription: "Aria heals.",
+					SourceRefs:           responseSourceRefs("session-alpha", 1, 2),
+				},
+			},
+		},
+	}
+
+	result, err := New().Extract(context.Background(), extractionRequestWithClient(client))
+	if err != nil {
+		t.Fatalf("Extract() error = %v, want nil", err)
+	}
+	client.response.SpellCasts[0].SourceRefs[0].StartUnitID = shared.UnitRefFromInt(99)
+
+	var payload extractionResponse
+	if err := json.Unmarshal(result.Output.Payload.Content, &payload); err != nil {
+		t.Fatalf("Unmarshal(Content) error = %v, want nil", err)
+	}
+	if got := payload.SpellCasts[0].SourceRefs[0].StartUnitID.String(); got != "1" {
+		t.Fatalf("source ref start = %q, want copied 1", got)
+	}
+}
+
+func extractionRequestWithClient(client contracts.StructuredLLMClient) contracts.ExtractionRequest {
+	req := promptExtractionRequest()
+	req.LLMClient = client
+	req.SourceInput = spellChunkInput(req.Chunk)
+	req.SessionID = "session-123"
+	req.LLMProfile = "profile-spells"
+	return req
+}
+
+const spellTranscriptJSON = `{"id":"session-alpha","segments":[{"id":1,"text":"Aria raises her hand and casts Cure Wounds."}]}`
+
+func spellSourceInput() contracts.LLMInputMaterial {
+	return contracts.NewLLMInputMaterial("source", "application/json", []byte(spellTranscriptJSON), "sha256:transcript", "file:///session-alpha.json")
+}
+
+func spellChunkInput(chunk *contracts.SourceChunk) contracts.LLMInputMaterial {
+	return contracts.NewLLMInputMaterial("source", chunk.MediaType, chunk.Content, "sha256:chunk", "file:///session-alpha.json")
+}
+
+func emptyChunkRequest(req contracts.ExtractionRequest) contracts.ExtractionRequest {
+	req.Chunk = &contracts.SourceChunk{
+		ID:       req.Chunk.ID,
+		SourceID: req.Chunk.SourceID,
+		Index:    req.Chunk.Index,
+	}
+	return req
+}
+
+func mismatchedSourceInputRequest(req contracts.ExtractionRequest) contracts.ExtractionRequest {
+	req.SourceInput = spellSourceInput()
+	return req
+}
+
+type fakeSpellsLLMClient struct {
+	response extractionResponse
+	content  []byte
+	err      error
+	requests []contracts.StructuredCompletionRequest
+}
+
+func (client *fakeSpellsLLMClient) CompleteStructured(ctx 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 := 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
+		}
+	}
+	return contracts.StructuredCompletionResponse{Content: content}, nil
+}
+
+func cloneStructuredCompletionRequest(req contracts.StructuredCompletionRequest) contracts.StructuredCompletionRequest {
+	req.Inputs = req.Inputs.Clone()
+	req.Vars = cloneVars(req.Vars)
+	return req
+}
+
+func cloneVars(in map[string]any) map[string]any {
+	if len(in) == 0 {
+		return nil
+	}
+	out := make(map[string]any, len(in))
+	for key, value := range in {
+		out[key] = value
+	}
+	return out
+}
--- a/internal/modules/dnd/extract/spells/model.go
+++ b/internal/modules/dnd/extract/spells/model.go
@@ -0,0 +1,22 @@
+package spells
+
+import "gitea.maximumdirect.net/eric/notarius/internal/modules/dnd/shared"
+
+type SpellCast struct {
+	Caster               string `json:"caster"`
+	Spell                string `json:"spell"`
+	Effect               string `json:"effect"`
+	NarrativeDescription string `json:"narrative_description"`
+}
+
+type extractionResponse struct {
+	SpellCasts []spellCastResponse `json:"spell_casts"`
+}
+
+type spellCastResponse struct {
+	Caster               string                     `json:"caster"`
+	Spell                string                     `json:"spell"`
+	Effect               string                     `json:"effect"`
+	NarrativeDescription string                     `json:"narrative_description"`
+	SourceRefs           []shared.SourceRefResponse `json:"source_refs"`
+}
--- a/internal/modules/dnd/extract/spells/registry_test.go
+++ b/internal/modules/dnd/extract/spells/registry_test.go
@@ -0,0 +1,120 @@
+package spells
+
+import (
+	"reflect"
+	"strings"
+	"testing"
+
+	"gitea.maximumdirect.net/eric/notarius/internal/framework/contracts"
+	"gitea.maximumdirect.net/eric/notarius/internal/framework/pipeline"
+)
+
+func TestNewReturnsExtractorWithMetadata(t *testing.T) {
+	extractor := New()
+	if extractor == nil {
+		t.Fatal("New() = nil, want extractor")
+	}
+	if extractor.Key() != Key {
+		t.Fatalf("extractor.Key() = %q, want %q", extractor.Key(), Key)
+	}
+}
+
+func TestModuleSpec(t *testing.T) {
+	got := ModuleSpec()
+	want := pipeline.ModuleSpec{
+		Key:   Key,
+		Stage: pipeline.StageExtract,
+		Requires: []string{
+			"chunks",
+			"source.transcript",
+		},
+		Provides: []string{
+			"dnd.spell_casts",
+		},
+		ReferenceSlots: []contracts.ReferenceSlot{
+			{
+				Name:               "glossary",
+				Description:        "Optional campaign glossary reference material used only for disambiguation.",
+				AcceptedMediaTypes: []string{"application/json", "application/x-yaml", "application/yaml", "text/markdown", "text/plain"},
+			},
+			{
+				Name:               "party",
+				Description:        "Optional party roster reference material used only for disambiguation.",
+				AcceptedMediaTypes: []string{"application/json", "application/x-yaml", "application/yaml", "text/markdown", "text/plain"},
+			},
+			{
+				Name:               "players",
+				Description:        "Optional player list reference material used only for disambiguation.",
+				AcceptedMediaTypes: []string{"application/json", "application/x-yaml", "application/yaml", "text/markdown", "text/plain"},
+			},
+			{
+				Name:               "roster",
+				Description:        "Deprecated alias for party roster reference material used only for disambiguation.",
+				AcceptedMediaTypes: []string{"application/json", "application/x-yaml", "application/yaml", "text/markdown", "text/plain"},
+			},
+		},
+	}
+	if !reflect.DeepEqual(got, want) {
+		t.Fatalf("ModuleSpec() = %#v, want %#v", got, want)
+	}
+
+	got.Requires[0] = "changed"
+	got.Provides[0] = "changed"
+	got.ReferenceSlots[0].AcceptedMediaTypes[0] = "changed"
+	again := ModuleSpec()
+	if !reflect.DeepEqual(again, want) {
+		t.Fatalf("ModuleSpec() after caller mutation = %#v, want %#v", again, want)
+	}
+}
+
+func TestRegisterMakesExtractorBuildable(t *testing.T) {
+	registry := pipeline.NewExtractorRegistry()
+
+	if err := Register(registry); err != nil {
+		t.Fatalf("Register() error = %v, want nil", err)
+	}
+
+	extractor, err := registry.Build(Key)
+	if err != nil {
+		t.Fatalf("Build() error = %v, want nil", err)
+	}
+	if extractor.Key() != Key {
+		t.Fatalf("extractor.Key() = %q, want %q", extractor.Key(), Key)
+	}
+}
+
+func TestRegisterStoresModuleSpec(t *testing.T) {
+	registry := pipeline.NewExtractorRegistry()
+
+	if err := Register(registry); err != nil {
+		t.Fatalf("Register() error = %v, want nil", err)
+	}
+
+	got, ok := registry.Spec(Key)
+	if !ok {
+		t.Fatal("Spec() ok = false, want true")
+	}
+	want := ModuleSpec()
+	if !reflect.DeepEqual(got, want) {
+		t.Fatalf("Spec() = %#v, want %#v", got, want)
+	}
+}
+
+func TestRuntimeReferenceSlotsMatchModuleSpec(t *testing.T) {
+	extractor := New()
+	spec := ModuleSpec()
+
+	if !reflect.DeepEqual(extractor.ReferenceSlots(), spec.ReferenceSlots) {
+		t.Fatalf("ReferenceSlots() = %#v, want spec slots %#v", extractor.ReferenceSlots(), spec.ReferenceSlots)
+	}
+}
+
+func TestRegisterNilRegistryReturnsError(t *testing.T) {
+	err := Register(nil)
+	if err == nil {
+		t.Fatal("Register(nil) error = nil, want error")
+	}
+	if !strings.Contains(err.Error(), "extractor registry") {
+		t.Fatalf("Register(nil) error = %q, want registry context", err.Error())
+	}
+}
--- a/internal/modules/dnd/extract/spells/schema.go
+++ b/internal/modules/dnd/extract/spells/schema.go
@@ -0,0 +1,20 @@
+package spells
+
+import "gitea.maximumdirect.net/eric/notarius/internal/framework/llm"
+
+const (
+	PromptID           = "dnd.spells"
+	ResponseSchemaKey  = llm.ResponseSchemaKey("dnd_spells")
+	ResponseSchemaID   = "notarius.dnd.spells"
+	ResponseSchemaName = "notarius_dnd_spells_v1"
+)
+
+func loadResponseSchema() (llm.ResponseSchema, error) {
+	return llm.LoadResponseSchema(embeddedAssets, llm.ResponseSchemaDefinition{
+		Key:       ResponseSchemaKey,
+		ID:        ResponseSchemaID,
+		Version:   SchemaVersion,
+		Name:      ResponseSchemaName,
+		AssetPath: "assets/schemas/dnd_spells.v1.json",
+	})
+}
--- a/internal/modules/dnd/extract/spells/schema_test.go
+++ b/internal/modules/dnd/extract/spells/schema_test.go
@@ -0,0 +1,130 @@
+package spells
+
+import (
+	"encoding/json"
+	"strings"
+	"testing"
+)
+
+func TestLoadResponseSchemaForSpells(t *testing.T) {
+	schema, err := loadResponseSchema()
+	if err != nil {
+		t.Fatalf("loadResponseSchema() error = %v, want nil", err)
+	}
+	if schema.Key != ResponseSchemaKey {
+		t.Fatalf("schema.Key = %q, want %q", schema.Key, ResponseSchemaKey)
+	}
+	if schema.ID != ResponseSchemaID {
+		t.Fatalf("schema.ID = %q, want %q", schema.ID, ResponseSchemaID)
+	}
+	if schema.Version != SchemaVersion {
+		t.Fatalf("schema.Version = %q, want %q", schema.Version, SchemaVersion)
+	}
+	if schema.Name != ResponseSchemaName {
+		t.Fatalf("schema.Name = %q, want %q", schema.Name, ResponseSchemaName)
+	}
+	if !strings.HasPrefix(schema.SHA256, "sha256:") {
+		t.Fatalf("schema.SHA256 = %q, want sha256 prefix", schema.SHA256)
+	}
+	if !json.Valid(schema.JSONSchema) {
+		t.Fatalf("schema.JSONSchema is invalid JSON: %s", schema.JSONSchema)
+	}
+
+	var decoded map[string]any
+	if err := json.Unmarshal(schema.JSONSchema, &decoded); err != nil {
+		t.Fatalf("Unmarshal(schema.JSONSchema) error = %v, want nil", err)
+	}
+	properties := decoded["properties"].(map[string]any)
+	spellCastProperties := properties["spell_casts"].(map[string]any)["items"].(map[string]any)["properties"].(map[string]any)
+	sourceRefProperties := spellCastProperties["source_refs"].(map[string]any)["items"].(map[string]any)["properties"].(map[string]any)
+	sourceRefRequired := spellCastProperties["source_refs"].(map[string]any)["items"].(map[string]any)["required"].([]any)
+	if !containsJSONField(sourceRefRequired, "source_id") {
+		t.Fatalf("canonical source refs required = %#v, want source_id", sourceRefRequired)
+	}
+	for _, field := range []string{"start_unit_id", "end_unit_id"} {
+		property := sourceRefProperties[field].(map[string]any)
+		if property["type"] != "integer" {
+			t.Fatalf("%s type = %#v, want integer", field, property["type"])
+		}
+		if property["minimum"] != float64(1) {
+			t.Fatalf("%s minimum = %#v, want 1", field, property["minimum"])
+		}
+	}
+}
+
+func TestLLMResponseSchemaOmitsSourceID(t *testing.T) {
+	raw, err := embeddedAssets.ReadFile("assets/schemas/dnd_spells_llm.v1.json")
+	if err != nil {
+		t.Fatalf("ReadFile(LLM schema) error = %v, want nil", err)
+	}
+	if !json.Valid(raw) {
+		t.Fatalf("LLM schema is invalid JSON: %s", raw)
+	}
+
+	var decoded map[string]any
+	if err := json.Unmarshal(raw, &decoded); err != nil {
+		t.Fatalf("Unmarshal(LLM schema) error = %v, want nil", err)
+	}
+	properties := decoded["properties"].(map[string]any)
+	spellCastProperties := properties["spell_casts"].(map[string]any)["items"].(map[string]any)["properties"].(map[string]any)
+	sourceRefItems := spellCastProperties["source_refs"].(map[string]any)["items"].(map[string]any)
+	sourceRefProperties := sourceRefItems["properties"].(map[string]any)
+	sourceRefRequired := sourceRefItems["required"].([]any)
+	if _, ok := sourceRefProperties["source_id"]; ok {
+		t.Fatalf("LLM source ref schema contains source_id property: %#v", sourceRefProperties)
+	}
+	if containsJSONField(sourceRefRequired, "source_id") {
+		t.Fatalf("LLM source refs required = %#v, want no source_id", sourceRefRequired)
+	}
+}
+
+func TestResponseSchemaJSONIsMutationSafe(t *testing.T) {
+	first, err := loadResponseSchema()
+	if err != nil {
+		t.Fatalf("loadResponseSchema() error = %v, want nil", err)
+	}
+	first.JSONSchema[0] = '['
+
+	second, err := loadResponseSchema()
+	if err != nil {
+		t.Fatalf("loadResponseSchema() error = %v, want nil", err)
+	}
+	if !json.Valid(second.JSONSchema) {
+		t.Fatalf("schema JSON was mutated: %s", second.JSONSchema)
+	}
+	if len(second.JSONSchema) > 0 && second.JSONSchema[0] == '[' {
+		t.Fatalf("schema JSON did not use defensive copy")
+	}
+}
+
+func TestResponseSchemaDiagnosticsOmitRawSchema(t *testing.T) {
+	schema, err := loadResponseSchema()
+	if err != nil {
+		t.Fatalf("loadResponseSchema() error = %v, want nil", err)
+	}
+	diagnostics := schema.DiagnosticsMap()
+
+	if diagnostics["key"] != ResponseSchemaKey {
+		t.Fatalf("diagnostics[key] = %#v, want %q", diagnostics["key"], ResponseSchemaKey)
+	}
+	for _, key := range []string{"id", "version", "name", "sha256"} {
+		if diagnostics[key] == "" {
+			t.Fatalf("diagnostics[%q] = %#v, want value", key, diagnostics[key])
+		}
+	}
+	if _, ok := diagnostics["json_schema"]; ok {
+		t.Fatalf("diagnostics should omit raw schema content: %#v", diagnostics)
+	}
+	if _, ok := diagnostics["JSONSchema"]; ok {
+		t.Fatalf("diagnostics should omit raw schema content: %#v", diagnostics)
+	}
+}
+
+func containsJSONField(fields []any, want string) bool {
+	for _, field := range fields {
+		if field == want {
+			return true
+		}
+	}
+	return false
+}
--- a/internal/modules/dnd/extract/spells/scriptorium_assets.go
+++ b/internal/modules/dnd/extract/spells/scriptorium_assets.go
@@ -0,0 +1,45 @@
+package spells
+
+import (
+	"fmt"
+	"sync"
+
+	"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 scriptoriumPromptRoot = "assets/prompts"
+
+func RegisterPromptAssets(registry *llm.AssetRegistry) error {
+	promptFS, err := shared.ModulePromptFS("dnd.spells", embeddedAssets, []promptfs.ModulePromptFile{
+		{Name: "dnd.spells.yaml", Path: "assets/prompts/dnd.spells.yaml"},
+		{Name: "task.md", Path: "assets/prompts/task.md"},
+		{Name: "instructions.md", Path: "assets/prompts/instructions.md"},
+	})
+	if err != nil {
+		return fmt.Errorf("prepare spell prompt assets: %w", err)
+	}
+	if err := registry.RegisterPromptFS(promptFS, scriptoriumPromptRoot); err != nil {
+		return err
+	}
+	return registry.RegisterSchemaFS(embeddedAssets, "assets/schemas")
+}
+
+func scriptoriumPromptMetadata() (string, error) {
+	scriptoriumPromptHashOnce.Do(func() {
+		parts := append([]llm.AssetHashPart{
+			{FS: embeddedAssets, Path: "assets/prompts/dnd.spells.yaml"},
+			{FS: embeddedAssets, Path: "assets/prompts/task.md"},
+			{FS: embeddedAssets, Path: "assets/prompts/instructions.md"},
+		}, append(shared.CommonHashParts(), shared.ReferenceHashParts()...)...)
+		scriptoriumPromptHash, scriptoriumPromptHashErr = llm.HashAssets(parts)
+	})
+	return scriptoriumPromptHash, scriptoriumPromptHashErr
+}
+
+var (
+	scriptoriumPromptHashOnce sync.Once
+	scriptoriumPromptHash     string
+	scriptoriumPromptHashErr  error
+)
--- a/internal/modules/dnd/extract/spells/scriptorium_assets_test.go
+++ b/internal/modules/dnd/extract/spells/scriptorium_assets_test.go
@@ -0,0 +1,132 @@
+package spells
+
+import (
+	"context"
+	"encoding/json"
+	"strings"
+	"testing"
+	"time"
+
+	"gitea.maximumdirect.net/eric/notarius/internal/framework/llm"
+	"gitea.maximumdirect.net/eric/scriptorium"
+)
+
+func TestScriptoriumPromptPreparesTranscriptReferencesAndTaskMessages(t *testing.T) {
+	transcript := []byte(`{"id":"session-1","segments":[{"id":"u1","text":"Mira casts shield."}]}`)
+	prepared := prepareSpellsPrompt(t, transcript, "Dana: Mira", "Mira: wizard", "Shield: abjuration")
+
+	if prepared.PromptID != PromptID {
+		t.Fatalf("prompt id = %q, want %q", prepared.PromptID, PromptID)
+	}
+	if prepared.OutputContract.SchemaPath != "dnd_spells_llm.v1.json" {
+		t.Fatalf("schema path = %q, want LLM-only schema", prepared.OutputContract.SchemaPath)
+	}
+	if got := len(prepared.Messages); got != 5 {
+		t.Fatalf("message count = %d, want 5", got)
+	}
+	if !strings.Contains(prepared.Messages[1].Content, string(transcript)) {
+		t.Fatalf("transcript message did not include source input")
+	}
+	if prepared.Messages[1].CacheControl == nil || prepared.Messages[2].CacheControl == nil {
+		t.Fatalf("expected transcript and reference messages to be cacheable: %#v", prepared.Messages)
+	}
+	if !strings.Contains(prepared.Messages[2].Content, "Dana: Mira") {
+		t.Fatalf("reference message missing player content")
+	}
+	if !strings.Contains(prepared.Messages[2].Content, "Mira: wizard") {
+		t.Fatalf("reference message missing party content")
+	}
+	if !strings.Contains(prepared.Messages[2].Content, "Shield: abjuration") {
+		t.Fatalf("reference message missing glossary content")
+	}
+	if strings.Contains(prepared.Messages[3].Content, string(transcript)) {
+		t.Fatalf("task message leaked transcript bytes")
+	}
+}
+
+func TestScriptoriumPromptPreparesWithMissingOptionalReferences(t *testing.T) {
+	transcript := []byte(`{"id":"session-1","segments":[]}`)
+	prepared := prepareSpellsPrompt(t, transcript, " ", " ", " ")
+
+	if !strings.Contains(prepared.Messages[2].Content, " ") {
+		t.Fatalf("reference message did not include empty optional reference placeholders")
+	}
+}
+
+func TestScriptoriumPromptDiagnosticsOmitRawMaterials(t *testing.T) {
+	transcript := []byte(`{"secret":"source text"}`)
+	reference := "private party note"
+	prepared := prepareSpellsPrompt(t, transcript, "private player note", reference, " ")
+	metadata := New().ManifestMetadata()
+
+	payload, err := json.Marshal(map[string]any{
+		"prepared": map[string]any{
+			"prompt_id":              prepared.PromptID,
+			"prompt_version":         prepared.PromptVersion,
+			"prompt_hash":            prepared.PromptHash,
+			"rendered_prompt_hash":   prepared.RenderedPromptHash,
+			"selected_profile_id":    prepared.SelectedProfileID,
+			"output_contract":        prepared.OutputContract,
+			"input_hashes":           prepared.InputHashes,
+			"effective_model_params": prepared.EffectiveModelParams,
+		},
+		"manifest": metadata,
+	})
+	if err != nil {
+		t.Fatalf("marshal diagnostics: %v", err)
+	}
+	diagnostics := string(payload)
+	for _, forbidden := range []string{
+		"source text",
+		"private player note",
+		reference,
+		`"properties"`,
+		"spell_casts",
+	} {
+		if strings.Contains(diagnostics, forbidden) {
+			t.Fatalf("diagnostics leaked %q: %s", forbidden, diagnostics)
+		}
+	}
+	if metadata["prompt_id"] != PromptID || metadata["prompt_version"] != SchemaVersion {
+		t.Fatalf("manifest prompt metadata = %#v", metadata)
+	}
+	if !strings.HasPrefix(metadata["prompt_sha256"].(string), "sha256:") {
+		t.Fatalf("manifest prompt hash = %#v, want sha256-prefixed", metadata["prompt_sha256"])
+	}
+}
+
+func prepareSpellsPrompt(t *testing.T, transcript []byte, players string, party string, glossary string) *scriptorium.PreparedRun {
+	t.Helper()
+	registry := llm.NewAssetRegistry()
+	if err := RegisterPromptAssets(registry); err != nil {
+		t.Fatalf("register spell prompt assets: %v", err)
+	}
+	options, err := registry.ScriptoriumOptions()
+	if err != nil {
+		t.Fatalf("ScriptoriumOptions() error = %v, want nil", err)
+	}
+	options = append(options, scriptorium.WithProfiles(scriptorium.OpenAICompatibleProfile(scriptorium.OpenAICompatibleProfileConfig{
+		ID:       "spell-test-profile",
+		Endpoint: "http://127.0.0.1:1/v1",
+		Model:    "spell-test-model",
+	})))
+	engine, err := scriptorium.NewEngine(scriptorium.Config{Timeout: time.Second}, options...)
+	if err != nil {
+		t.Fatalf("NewEngine() error = %v, want nil", err)
+	}
+	prepared, err := engine.Prepare(context.Background(), scriptorium.RunRequest{
+		PromptID:      PromptID,
+		PromptVersion: SchemaVersion,
+		ProfileID:     "spell-test-profile",
+		Inputs: map[string]scriptorium.ArtifactRef{
+			"transcript": scriptorium.InlineWithURI("file:///session.json", string(transcript)),
+			"players":    scriptorium.Inline(players),
+			"party":      scriptorium.Inline(party),
+			"glossary":   scriptorium.Inline(glossary),
+		},
+	})
+	if err != nil {
+		t.Fatalf("Prepare() error = %v, want nil", err)
+	}
+	return prepared
+}
--- a/internal/modules/dnd/extract/spells/test_helpers_test.go
+++ b/internal/modules/dnd/extract/spells/test_helpers_test.go
@@ -0,0 +1,86 @@
+package spells
+
+import (
+	"encoding/json"
+	"testing"
+
+	"gitea.maximumdirect.net/eric/notarius/internal/core/source"
+	"gitea.maximumdirect.net/eric/notarius/internal/framework/contracts"
+	"gitea.maximumdirect.net/eric/notarius/internal/modules/dnd/shared"
+)
+
+func promptExtractionRequest() contracts.ExtractionRequest {
+	doc := promptSourceDocument()
+	chunk := &contracts.SourceChunk{
+		ID:          "session-alpha:chunk:0",
+		SourceID:    doc.ID,
+		Index:       0,
+		StartUnitID: doc.Units[0].ID,
+		EndUnitID:   doc.Units[len(doc.Units)-1].ID,
+		Content:     []byte(`{"units":[1,2]}`),
+		MediaType:   "application/json",
+		Units:       append([]source.SourceUnit(nil), doc.Units...),
+		Metadata:    map[string]any{"ignored": "chunk metadata"},
+	}
+	return contracts.ExtractionRequest{
+		Source: doc,
+		Chunk:  chunk,
+	}
+}
+
+func promptSourceDocument() *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: "Aria raises her hand and casts Cure Wounds.",
+				Metadata: map[string]any{
+					"speaker": "Alice",
+					"start":   json.Number("1.25"),
+					"end":     json.Number("3.5"),
+					"ignored": "not rendered",
+				},
+			},
+			{
+				ID:       2,
+				Kind:     "transcript_segment",
+				Text:     "The fighter's wounds begin to close.",
+				Metadata: map[string]any{"ignored": "not rendered"},
+			},
+		},
+	}
+}
+
+func mustJSON(t *testing.T, value any) string {
+	t.Helper()
+	encoded, err := json.Marshal(value)
+	if err != nil {
+		t.Fatalf("Marshal() error = %v, want nil", err)
+	}
+	return string(encoded)
+}
+
+func responseSourceRefs(sourceID string, startUnitID int, endUnitID int) []shared.SourceRefResponse {
+	return []shared.SourceRefResponse{
+		{
+			SourceID:    sourceID,
+			StartUnitID: shared.UnitRefFromInt(startUnitID),
+			EndUnitID:   shared.UnitRefFromInt(endUnitID),
+		},
+	}
+}
+
+func responseSourceRefsInt(sourceID string, startUnitID int, endUnitID int) []shared.SourceRefResponse {
+	return []shared.SourceRefResponse{
+		{
+			SourceID:    sourceID,
+			StartUnitID: shared.UnitRefFromInt(startUnitID),
+			EndUnitID:   shared.UnitRefFromInt(endUnitID),
+		},
+	}
+}
--- a/internal/modules/dnd/register/register.go
+++ b/internal/modules/dnd/register/register.go
@@ -6,13 +6,13 @@ import (

 	"gitea.maximumdirect.net/eric/notarius/internal/framework/llm"
 	"gitea.maximumdirect.net/eric/notarius/internal/framework/pipeline"
-	"gitea.maximumdirect.net/eric/notarius/internal/modules/chunk/dnd/scenes"
-	"gitea.maximumdirect.net/eric/notarius/internal/modules/extract/dnd/spells"
+	"gitea.maximumdirect.net/eric/notarius/internal/modules/dnd/chunk/scenes"
+	"gitea.maximumdirect.net/eric/notarius/internal/modules/dnd/extract/spells"
+	spellshape "gitea.maximumdirect.net/eric/notarius/internal/modules/dnd/validate/spells/shape"
+	spellsourcerefs "gitea.maximumdirect.net/eric/notarius/internal/modules/dnd/validate/spells/source_refs"
+	spellrelatedness "gitea.maximumdirect.net/eric/notarius/internal/modules/dnd/validate/spells/source_relatedness"
 	validjson "gitea.maximumdirect.net/eric/notarius/internal/modules/generic/validate/valid_json"
 	validjsonschema "gitea.maximumdirect.net/eric/notarius/internal/modules/generic/validate/valid_json_schema"
-	spellshape "gitea.maximumdirect.net/eric/notarius/internal/validators/extract/dnd/spells/shape"
-	spellsourcerefs "gitea.maximumdirect.net/eric/notarius/internal/validators/extract/dnd/spells/source_refs"
-	spellrelatedness "gitea.maximumdirect.net/eric/notarius/internal/validators/extract/dnd/spells/source_relatedness"
 )

 // Register adds all production D&D modules, validators, policy, and assets.
--- a/internal/modules/dnd/register/register_test.go
+++ b/internal/modules/dnd/register/register_test.go
@@ -9,7 +9,7 @@ import (

 	"gitea.maximumdirect.net/eric/notarius/internal/framework/llm"
 	"gitea.maximumdirect.net/eric/notarius/internal/framework/pipeline"
-	"gitea.maximumdirect.net/eric/notarius/internal/modules/extract/dnd/spells"
+	"gitea.maximumdirect.net/eric/notarius/internal/modules/dnd/extract/spells"
 )

 func TestRegisterAddsDNDFamily(t *testing.T) {
--- a/internal/modules/dnd/shared/assets.go
+++ b/internal/modules/dnd/shared/assets.go
@@ -0,0 +1,47 @@
+package shared
+
+import (
+	"embed"
+	"io/fs"
+
+	"gitea.maximumdirect.net/eric/notarius/internal/framework/llm"
+	"gitea.maximumdirect.net/eric/notarius/internal/framework/promptfs"
+)
+
+//go:embed assets/prompts/*.md
+var embeddedAssets embed.FS
+
+var sharedPromptFiles = []string{
+	"common-dnd-system.md",
+	"common-dnd-transcript.md",
+	"common-dnd-references.md",
+}
+
+func SharedPromptFiles() []promptfs.SharedPromptFile {
+	files := make([]promptfs.SharedPromptFile, 0, len(sharedPromptFiles))
+	for _, name := range sharedPromptFiles {
+		files = append(files, promptfs.SharedPromptFile{
+			Name: name,
+			FS:   embeddedAssets,
+			Path: "assets/prompts/" + name,
+		})
+	}
+	return files
+}
+
+func CommonHashParts() []llm.AssetHashPart {
+	return []llm.AssetHashPart{
+		{FS: embeddedAssets, Path: "assets/prompts/common-dnd-system.md"},
+		{FS: embeddedAssets, Path: "assets/prompts/common-dnd-transcript.md"},
+	}
+}
+
+func ReferenceHashParts() []llm.AssetHashPart {
+	return []llm.AssetHashPart{
+		{FS: embeddedAssets, Path: "assets/prompts/common-dnd-references.md"},
+	}
+}
+
+func ModulePromptFS(moduleDir string, moduleFS fs.FS, files []promptfs.ModulePromptFile) (fs.FS, error) {
+	return promptfs.ModulePromptFS(moduleDir, moduleFS, files, SharedPromptFiles()...)
+}
--- a/internal/modules/dnd/shared/assets/prompts/common-dnd-references.md
+++ b/internal/modules/dnd/shared/assets/prompts/common-dnd-references.md
@@ -0,0 +1,12 @@
+Optional reference material for this Dungeons & Dragons campaign is provided
+below. Use it only to disambiguate names, aliases, speakers, campaign terms, or
+spell names already present in the transcript.
+
+Player list reference:
+{{ input "players" }}
+
+Party roster reference:
+{{ input "party" }}
+
+Glossary reference:
+{{ input "glossary" }}
--- a/internal/modules/dnd/shared/assets/prompts/common-dnd-system.md
+++ b/internal/modules/dnd/shared/assets/prompts/common-dnd-system.md
@@ -0,0 +1,8 @@
+You work with Dungeons & Dragons gameplay transcripts.
+
+Use only the provided transcript and reference material. Source text may contain
+transcription errors, repeated lines, incomplete sentences, and misheard proper
+nouns. Reference material, when present, is supporting context only and must not
+be treated as a source of extracted events by itself.
+
+Return only valid JSON matching the configured response schema.
--- a/internal/modules/dnd/shared/assets/prompts/common-dnd-transcript.md
+++ b/internal/modules/dnd/shared/assets/prompts/common-dnd-transcript.md
@@ -0,0 +1,3 @@
+A transcript of a Dungeons & Dragons gameplay session is provided below.
+
+{{ input "transcript" }}
--- a/internal/modules/dnd/shared/assets_test.go
+++ b/internal/modules/dnd/shared/assets_test.go
@@ -0,0 +1,87 @@
+package shared
+
+import (
+	"io/fs"
+	"testing"
+	"testing/fstest"
+
+	"gitea.maximumdirect.net/eric/notarius/internal/framework/llm"
+	"gitea.maximumdirect.net/eric/notarius/internal/framework/promptfs"
+)
+
+func TestSharedPromptFilesReturnsNewSlice(t *testing.T) {
+	first := SharedPromptFiles()
+	second := SharedPromptFiles()
+
+	if len(first) != 3 || len(second) != 3 {
+		t.Fatalf("SharedPromptFiles() lengths = %d and %d, want 3", len(first), len(second))
+	}
+	first[0].Name = "changed.md"
+	if second[0].Name != "common-dnd-system.md" {
+		t.Fatalf("SharedPromptFiles() reused descriptor slice: %#v", second)
+	}
+}
+
+func TestSharedPromptFilesReferenceEmbeddedAssets(t *testing.T) {
+	for _, file := range SharedPromptFiles() {
+		if file.FS == nil {
+			t.Fatalf("SharedPromptFiles() descriptor %q has nil FS", file.Name)
+		}
+		if _, err := fs.ReadFile(file.FS, file.Path); err != nil {
+			t.Fatalf("ReadFile(%q) error = %v, want nil", file.Path, err)
+		}
+	}
+}
+
+func TestHashPartsReferenceSharedPrompts(t *testing.T) {
+	assertHashParts(t, "common", CommonHashParts(), []string{
+		"assets/prompts/common-dnd-system.md",
+		"assets/prompts/common-dnd-transcript.md",
+	})
+	assertHashParts(t, "reference", ReferenceHashParts(), []string{
+		"assets/prompts/common-dnd-references.md",
+	})
+
+	for _, part := range append(CommonHashParts(), ReferenceHashParts()...) {
+		if _, err := fs.ReadFile(part.FS, part.Path); err != nil {
+			t.Fatalf("ReadFile(%q) error = %v, want nil", part.Path, err)
+		}
+	}
+}
+
+func assertHashParts(t *testing.T, name string, parts []llm.AssetHashPart, want []string) {
+	t.Helper()
+	if len(parts) != len(want) {
+		t.Fatalf("%s hash parts length = %d, want %d", name, len(parts), len(want))
+	}
+	for i, part := range parts {
+		if part.Path != want[i] {
+			t.Fatalf("%s hash part %d path = %q, want %q", name, i, part.Path, want[i])
+		}
+		if part.FS == nil {
+			t.Fatalf("%s hash part %d has nil FS", name, i)
+		}
+	}
+}
+
+func TestModulePromptFSMountsDNDSharedPrompts(t *testing.T) {
+	fsys, err := ModulePromptFS("dnd.test", fstest.MapFS{
+		"assets/prompts/dnd.test.yaml": {Data: []byte("id: dnd.test")},
+	}, []promptfs.ModulePromptFile{
+		{Name: "dnd.test.yaml", Path: "assets/prompts/dnd.test.yaml"},
+	})
+	if err != nil {
+		t.Fatalf("ModulePromptFS() error = %v, want nil", err)
+	}
+
+	for _, path := range []string{
+		"assets/prompts/dnd.test/dnd.test.yaml",
+		"assets/prompts/dnd.test/sharedassets/common-dnd-system.md",
+		"assets/prompts/dnd.test/sharedassets/common-dnd-transcript.md",
+		"assets/prompts/dnd.test/sharedassets/common-dnd-references.md",
+	} {
+		if _, err := fs.ReadFile(fsys, path); err != nil {
+			t.Fatalf("ReadFile(%q) error = %v, want nil", path, err)
+		}
+	}
+}
--- a/internal/modules/dnd/shared/prompt_inputs.go
+++ b/internal/modules/dnd/shared/prompt_inputs.go
@@ -0,0 +1,84 @@
+package shared
+
+import (
+	"bytes"
+	"fmt"
+	"sort"
+
+	"gitea.maximumdirect.net/eric/notarius/internal/framework/contracts"
+)
+
+func PromptInputs(sourceInput contracts.LLMInputMaterial, references contracts.ReferenceSet) contracts.LLMInputSet {
+	partySlot := references.Slots["party"]
+	if len(partySlot.Items) == 0 {
+		partySlot = references.Slots["roster"]
+	}
+	return contracts.LLMInputSet{
+		"transcript": TranscriptPromptMaterial(sourceInput),
+		"players":    ReferencePromptMaterial("players", references.Slots["players"]),
+		"party":      ReferencePromptMaterial("party", partySlot),
+		"glossary":   ReferencePromptMaterial("glossary", references.Slots["glossary"]),
+	}
+}
+
+func TranscriptPromptMaterial(material contracts.LLMInputMaterial) contracts.LLMInputMaterial {
+	out := material.Clone()
+	out.Name = "transcript"
+	return out
+}
+
+func ReferencePromptMaterial(name string, slot contracts.ResolvedReferenceSlot) contracts.LLMInputMaterial {
+	body := ReferencePromptInput(slot)
+	digest := ""
+	originURI := ""
+	if len(slot.Items) == 1 {
+		digest = slot.Items[0].Digest
+		originURI = slot.Items[0].Origin.URI
+	}
+	return contracts.NewLLMInputMaterial(name, "text/plain", body, digest, originURI)
+}
+
+func ReferencePromptInput(slot contracts.ResolvedReferenceSlot) []byte {
+	if len(slot.Items) == 0 {
+		return []byte(" ")
+	}
+	items := append([]contracts.ReferenceItem(nil), slot.Items...)
+	sort.SliceStable(items, func(i, j int) bool {
+		if items[i].Origin.URI != items[j].Origin.URI {
+			return items[i].Origin.URI < items[j].Origin.URI
+		}
+		if items[i].Digest != items[j].Digest {
+			return items[i].Digest < items[j].Digest
+		}
+		return string(items[i].Content) < string(items[j].Content)
+	})
+	if len(items) == 1 {
+		return append([]byte(nil), items[0].Content...)
+	}
+
+	var b bytes.Buffer
+	for i, item := range items {
+		if i > 0 {
+			b.WriteString("\n\n")
+		}
+		fmt.Fprintf(&b, "Reference %d\n", i+1)
+		if item.Origin.Type != "" {
+			fmt.Fprintf(&b, "Origin-Type: %s\n", item.Origin.Type)
+		}
+		if item.Origin.URI != "" {
+			fmt.Fprintf(&b, "Origin-URI: %s\n", item.Origin.URI)
+		}
+		if item.Digest != "" {
+			fmt.Fprintf(&b, "Digest: %s\n", item.Digest)
+		}
+		if item.MediaType != "" {
+			fmt.Fprintf(&b, "Media-Type: %s\n", item.MediaType)
+		}
+		if item.SizeBytes > 0 {
+			fmt.Fprintf(&b, "Size-Bytes: %d\n", item.SizeBytes)
+		}
+		b.WriteString("\n")
+		b.Write(item.Content)
+	}
+	return b.Bytes()
+}
--- a/internal/modules/dnd/shared/prompt_inputs_test.go
+++ b/internal/modules/dnd/shared/prompt_inputs_test.go
@@ -0,0 +1,151 @@
+package shared
+
+import (
+	"strings"
+	"testing"
+
+	"gitea.maximumdirect.net/eric/notarius/internal/framework/contracts"
+)
+
+func TestPromptInputsBuildExpectedInputs(t *testing.T) {
+	source := contracts.NewLLMInputMaterial("source", "application/json", []byte("source text"), "sha256:source", "file:///source.json")
+	references := contracts.ReferenceSet{Slots: map[string]contracts.ResolvedReferenceSlot{
+		"players":  slotWithContent("players", "Alice: Aria"),
+		"party":    slotWithContent("party", "Aria: cleric"),
+		"glossary": slotWithContent("glossary", "Brightmantle: temple"),
+	}}
+
+	inputs := PromptInputs(source, references)
+	for _, name := range []string{"transcript", "players", "party", "glossary"} {
+		if _, ok := inputs[name]; !ok {
+			t.Fatalf("PromptInputs() missing %q: %#v", name, inputs)
+		}
+	}
+	if _, ok := inputs["roster"]; ok {
+		t.Fatalf("PromptInputs() included roster input: %#v", inputs)
+	}
+	if got := inputs["transcript"].Name; got != "transcript" {
+		t.Fatalf("transcript name = %q, want transcript", got)
+	}
+	if got := string(inputs["transcript"].Content); got != "source text" {
+		t.Fatalf("transcript content = %q, want source text", got)
+	}
+	if got := string(inputs["players"].Content); got != "Alice: Aria" {
+		t.Fatalf("players content = %q, want player reference", got)
+	}
+	if got := string(inputs["party"].Content); got != "Aria: cleric" {
+		t.Fatalf("party content = %q, want party reference", got)
+	}
+	if got := string(inputs["glossary"].Content); got != "Brightmantle: temple" {
+		t.Fatalf("glossary content = %q, want glossary reference", got)
+	}
+}
+
+func TestPromptInputsUseRosterWhenPartyIsEmpty(t *testing.T) {
+	inputs := PromptInputs(contracts.LLMInputMaterial{}, contracts.ReferenceSet{Slots: map[string]contracts.ResolvedReferenceSlot{
+		"party":  {},
+		"roster": slotWithContent("roster", "Legacy roster text"),
+	}})
+
+	if got := string(inputs["party"].Content); got != "Legacy roster text" {
+		t.Fatalf("party content = %q, want roster fallback content", got)
+	}
+	if _, ok := inputs["roster"]; ok {
+		t.Fatalf("PromptInputs() included roster input: %#v", inputs)
+	}
+}
+
+func TestTranscriptPromptMaterialClonesSource(t *testing.T) {
+	source := contracts.NewLLMInputMaterial("source", "text/plain", []byte("source text"), "sha256:source", "file:///source.txt")
+	got := TranscriptPromptMaterial(source)
+
+	if got.Name != "transcript" {
+		t.Fatalf("Name = %q, want transcript", got.Name)
+	}
+	if got.MediaType != source.MediaType || got.Digest != source.Digest || got.OriginURI != source.OriginURI || got.SizeBytes != source.SizeBytes {
+		t.Fatalf("TranscriptPromptMaterial() = %#v, want cloned metadata from %#v", got, source)
+	}
+	source.Content[0] = 'X'
+	if string(got.Content) != "source text" {
+		t.Fatalf("TranscriptPromptMaterial() reused content slice: %q", got.Content)
+	}
+}
+
+func TestReferencePromptMaterialUsesTextPlainAndSingleReferenceMetadata(t *testing.T) {
+	slot := contracts.ResolvedReferenceSlot{Items: []contracts.ReferenceItem{{
+		Content: []byte("single reference"),
+		Digest:  "sha256:reference",
+		Origin:  contracts.ReferenceOrigin{Type: "file", URI: "file:///reference.md"},
+	}}}
+
+	got := ReferencePromptMaterial("party", slot)
+	if got.Name != "party" || got.MediaType != "text/plain" {
+		t.Fatalf("ReferencePromptMaterial() name/media = %q/%q, want party/text/plain", got.Name, got.MediaType)
+	}
+	if got.Digest != "sha256:reference" || got.OriginURI != "file:///reference.md" {
+		t.Fatalf("ReferencePromptMaterial() digest/origin = %q/%q, want single reference metadata", got.Digest, got.OriginURI)
+	}
+	if string(got.Content) != "single reference" {
+		t.Fatalf("ReferencePromptMaterial() content = %q, want raw single reference", got.Content)
+	}
+}
+
+func TestReferencePromptMaterialOmitsAggregateMetadata(t *testing.T) {
+	got := ReferencePromptMaterial("party", contracts.ResolvedReferenceSlot{Items: []contracts.ReferenceItem{
+		{Content: []byte("one"), Digest: "sha256:one", Origin: contracts.ReferenceOrigin{URI: "file:///one.md"}},
+		{Content: []byte("two"), Digest: "sha256:two", Origin: contracts.ReferenceOrigin{URI: "file:///two.md"}},
+	}})
+
+	if got.Digest != "" || got.OriginURI != "" {
+		t.Fatalf("ReferencePromptMaterial() digest/origin = %q/%q, want empty aggregate metadata", got.Digest, got.OriginURI)
+	}
+}
+
+func TestReferencePromptInputRendering(t *testing.T) {
+	if got := string(ReferencePromptInput(contracts.ResolvedReferenceSlot{})); got != " " {
+		t.Fatalf("empty rendering = %q, want single space", got)
+	}
+	if got := string(ReferencePromptInput(slotWithContent("party", "single reference"))); got != "single reference" {
+		t.Fatalf("single rendering = %q, want raw content", got)
+	}
+
+	slot := contracts.ResolvedReferenceSlot{Items: []contracts.ReferenceItem{
+		{
+			SlotName:  "party",
+			MediaType: "text/plain",
+			Content:   []byte("second"),
+			Digest:    "sha256:bbb",
+			Origin:    contracts.ReferenceOrigin{Type: "file", URI: "file:///b.txt"},
+			SizeBytes: 6,
+		},
+		{
+			SlotName:  "party",
+			MediaType: "text/plain",
+			Content:   []byte("first"),
+			Digest:    "sha256:aaa",
+			Origin:    contracts.ReferenceOrigin{Type: "file", URI: "file:///a.txt"},
+			SizeBytes: 5,
+		},
+	}}
+	first := string(ReferencePromptInput(slot))
+	second := string(ReferencePromptInput(slot))
+	if first != second {
+		t.Fatalf("ReferencePromptInput() was not deterministic:\nfirst=%q\nsecond=%q", first, second)
+	}
+	if !strings.Contains(first, "Reference 1\nOrigin-Type: file\nOrigin-URI: file:///a.txt\nDigest: sha256:aaa\nMedia-Type: text/plain\nSize-Bytes: 5\n\nfirst") {
+		t.Fatalf("first reference block = %q, want sorted first reference metadata", first)
+	}
+	if strings.Index(first, "first") > strings.Index(first, "second") {
+		t.Fatalf("references were not sorted deterministically: %q", first)
+	}
+}
+
+func slotWithContent(name string, content string) contracts.ResolvedReferenceSlot {
+	return contracts.ResolvedReferenceSlot{
+		Slot: contracts.ReferenceSlot{Name: name},
+		Items: []contracts.ReferenceItem{{
+			SlotName: name,
+			Content:  []byte(content),
+		}},
+	}
+}
--- a/internal/modules/dnd/shared/references.go
+++ b/internal/modules/dnd/shared/references.go
@@ -0,0 +1,47 @@
+package shared
+
+import "gitea.maximumdirect.net/eric/notarius/internal/framework/contracts"
+
+type ReferenceSlotDescriptions struct {
+	Glossary string
+	Party    string
+	Players  string
+	Roster   string
+}
+
+var referenceMediaTypes = []string{
+	"application/json",
+	"application/x-yaml",
+	"application/yaml",
+	"text/markdown",
+	"text/plain",
+}
+
+func ReferenceMediaTypes() []string {
+	return append([]string(nil), referenceMediaTypes...)
+}
+
+func ReferenceSlots(descriptions ReferenceSlotDescriptions) []contracts.ReferenceSlot {
+	return contracts.CloneReferenceSlots([]contracts.ReferenceSlot{
+		{
+			Name:               "glossary",
+			Description:        descriptions.Glossary,
+			AcceptedMediaTypes: ReferenceMediaTypes(),
+		},
+		{
+			Name:               "party",
+			Description:        descriptions.Party,
+			AcceptedMediaTypes: ReferenceMediaTypes(),
+		},
+		{
+			Name:               "players",
+			Description:        descriptions.Players,
+			AcceptedMediaTypes: ReferenceMediaTypes(),
+		},
+		{
+			Name:               "roster",
+			Description:        descriptions.Roster,
+			AcceptedMediaTypes: ReferenceMediaTypes(),
+		},
+	})
+}
--- a/internal/modules/dnd/shared/references_test.go
+++ b/internal/modules/dnd/shared/references_test.go
@@ -0,0 +1,60 @@
+package shared
+
+import (
+	"reflect"
+	"testing"
+
+	"gitea.maximumdirect.net/eric/notarius/internal/framework/contracts"
+)
+
+func TestReferenceMediaTypesReturnsDefensiveCopy(t *testing.T) {
+	want := []string{
+		"application/json",
+		"application/x-yaml",
+		"application/yaml",
+		"text/markdown",
+		"text/plain",
+	}
+	got := ReferenceMediaTypes()
+	if !reflect.DeepEqual(got, want) {
+		t.Fatalf("ReferenceMediaTypes() = %#v, want %#v", got, want)
+	}
+	got[0] = "changed"
+	if again := ReferenceMediaTypes(); again[0] != "application/json" {
+		t.Fatalf("ReferenceMediaTypes() reused backing storage: %#v", again)
+	}
+}
+
+func TestReferenceSlotsUseDescriptionsAndExpectedOrder(t *testing.T) {
+	descriptions := ReferenceSlotDescriptions{
+		Glossary: "Glossary reference",
+		Party:    "Party reference",
+		Players:  "Players reference",
+		Roster:   "Roster reference",
+	}
+	got := ReferenceSlots(descriptions)
+	want := []contracts.ReferenceSlot{
+		{Name: "glossary", Description: descriptions.Glossary, AcceptedMediaTypes: ReferenceMediaTypes()},
+		{Name: "party", Description: descriptions.Party, AcceptedMediaTypes: ReferenceMediaTypes()},
+		{Name: "players", Description: descriptions.Players, AcceptedMediaTypes: ReferenceMediaTypes()},
+		{Name: "roster", Description: descriptions.Roster, AcceptedMediaTypes: ReferenceMediaTypes()},
+	}
+	if !reflect.DeepEqual(got, want) {
+		t.Fatalf("ReferenceSlots() = %#v, want %#v", got, want)
+	}
+}
+
+func TestReferenceSlotsReturnDefensiveCopies(t *testing.T) {
+	first := ReferenceSlots(ReferenceSlotDescriptions{})
+	second := ReferenceSlots(ReferenceSlotDescriptions{})
+
+	first[0].Name = "changed"
+	first[0].AcceptedMediaTypes[0] = "changed"
+
+	if second[0].Name != "glossary" {
+		t.Fatalf("ReferenceSlots() reused slot slice: %#v", second)
+	}
+	if second[0].AcceptedMediaTypes[0] != "application/json" {
+		t.Fatalf("ReferenceSlots() reused media type slice: %#v", second)
+	}
+}
--- a/internal/modules/dnd/shared/unit_refs.go
+++ b/internal/modules/dnd/shared/unit_refs.go
@@ -0,0 +1,118 @@
+package shared
+
+import (
+	"bytes"
+	"encoding/json"
+	"fmt"
+	"strconv"
+	"strings"
+
+	"gitea.maximumdirect.net/eric/notarius/internal/core/source"
+)
+
+type UnitRef struct {
+	value      int
+	fromNumber bool
+}
+
+type SourceRefResponse struct {
+	SourceID    string  `json:"source_id"`
+	StartUnitID UnitRef `json:"start_unit_id"`
+	EndUnitID   UnitRef `json:"end_unit_id"`
+}
+
+func UnitRefFromString(value string) UnitRef {
+	parsed, _ := parseUnitRefNumber(value)
+	return UnitRef{value: parsed}
+}
+
+func UnitRefFromInt(value int) UnitRef {
+	return UnitRef{
+		value:      value,
+		fromNumber: true,
+	}
+}
+
+func (ref UnitRef) String() string {
+	if ref.value == 0 {
+		return ""
+	}
+	return strconv.Itoa(ref.value)
+}
+
+func (ref UnitRef) Int() int {
+	return ref.value
+}
+
+func (ref *UnitRef) UnmarshalJSON(raw []byte) error {
+	raw = bytes.TrimSpace(raw)
+	if len(raw) == 0 {
+		return fmt.Errorf("unit ref must be a string or integer")
+	}
+	if raw[0] == '"' {
+		var value string
+		if err := json.Unmarshal(raw, &value); err != nil {
+			return err
+		}
+		number, err := parseUnitRefNumber(value)
+		if err != nil {
+			return err
+		}
+		*ref = UnitRef{value: number}
+		return nil
+	}
+
+	number, err := parseUnitRefNumber(string(raw))
+	if err != nil {
+		return err
+	}
+	*ref = UnitRefFromInt(number)
+	return nil
+}
+
+func (ref UnitRef) MarshalJSON() ([]byte, error) {
+	if ref.fromNumber {
+		return []byte(strconv.Itoa(ref.value)), nil
+	}
+	return json.Marshal(ref.String())
+}
+
+func ResolveUnitID(doc *source.SourceDocument, field string, ref UnitRef) (int, error) {
+	if ref.value <= 0 {
+		return 0, fmt.Errorf("%s must be positive", field)
+	}
+	if _, ok := source.UnitIndex(doc, ref.value); !ok {
+		return 0, fmt.Errorf("%s %d was not found", field, ref.value)
+	}
+	return ref.value, nil
+}
+
+func SourceRefCandidate(doc *source.SourceDocument, ref SourceRefResponse) source.SourceRef {
+	return source.SourceRef{
+		SourceID:    strings.TrimSpace(ref.SourceID),
+		StartUnitID: unitIDCandidate(ref.StartUnitID),
+		EndUnitID:   unitIDCandidate(ref.EndUnitID),
+	}
+}
+
+func unitIDCandidate(ref UnitRef) int {
+	return ref.value
+}
+
+func parseUnitRefNumber(value string) (int, error) {
+	trimmed := strings.TrimSpace(value)
+	if trimmed == "" {
+		return 0, fmt.Errorf("unit ref must not be empty")
+	}
+	if trimmed != value {
+		return 0, fmt.Errorf("unit ref must not contain leading or trailing whitespace")
+	}
+	number, err := strconv.Atoi(value)
+	if err != nil {
+		return 0, fmt.Errorf("unit ref must be an integer")
+	}
+	if number <= 0 {
+		return 0, fmt.Errorf("unit ref must be positive")
+	}
+	return number, nil
+}
--- a/internal/modules/dnd/shared/unit_refs_test.go
+++ b/internal/modules/dnd/shared/unit_refs_test.go
@@ -0,0 +1,114 @@
+package shared
+
+import (
+	"encoding/json"
+	"strings"
+	"testing"
+
+	"gitea.maximumdirect.net/eric/notarius/internal/core/source"
+)
+
+func TestUnitRefUnmarshalAcceptsIntegerAndNumericString(t *testing.T) {
+	var integerRef UnitRef
+	if err := json.Unmarshal([]byte(`12`), &integerRef); err != nil {
+		t.Fatalf("Unmarshal(integer) error = %v, want nil", err)
+	}
+	if got := integerRef.String(); got != "12" {
+		t.Fatalf("integer ref = %q, want 12", got)
+	}
+	if got := integerRef.Int(); got != 12 {
+		t.Fatalf("integer ref value = %d, want 12", got)
+	}
+
+	var stringRef UnitRef
+	if err := json.Unmarshal([]byte(`"12"`), &stringRef); err != nil {
+		t.Fatalf("Unmarshal(string) error = %v, want nil", err)
+	}
+	if got := stringRef.String(); got != "12" {
+		t.Fatalf("string ref = %q, want 12", got)
+	}
+}
+
+func TestUnitRefUnmarshalRejectsNonIntegerValues(t *testing.T) {
+	for _, raw := range []string{`true`, `null`, `1.5`, `{}`, `"seg-001"`, `" 1 "`, `0`, `-1`} {
+		t.Run(raw, func(t *testing.T) {
+			var ref UnitRef
+			err := json.Unmarshal([]byte(raw), &ref)
+			if err == nil {
+				t.Fatal("Unmarshal() error = nil, want error")
+			}
+		})
+	}
+}
+
+func TestResolveUnitIDReturnsExistingIntegerSourceUnitID(t *testing.T) {
+	doc := unitRefSourceDocument(2, 10)
+
+	got, err := ResolveUnitID(doc, "start_unit_id", UnitRefFromInt(2))
+	if err != nil {
+		t.Fatalf("ResolveUnitID() error = %v, want nil", err)
+	}
+	if got != 2 {
+		t.Fatalf("ResolveUnitID() = %d, want exact source unit ID", got)
+	}
+}
+
+func TestResolveUnitIDDoesNotFallbackToOneBasedUnitNumber(t *testing.T) {
+	doc := unitRefSourceDocument(10, 20)
+
+	_, err := ResolveUnitID(doc, "end_unit_id", UnitRefFromInt(2))
+	if err == nil {
+		t.Fatal("ResolveUnitID() error = nil, want missing source-unit ID")
+	}
+}
+
+func TestResolveUnitIDRejectsMissingUnit(t *testing.T) {
+	doc := unitRefSourceDocument(1)
+
+	_, err := ResolveUnitID(doc, "start_unit_id", UnitRefFromInt(9))
+	if err == nil {
+		t.Fatal("ResolveUnitID() error = nil, want error")
+	}
+	if !strings.Contains(err.Error(), "start_unit_id 9") {
+		t.Fatalf("ResolveUnitID() error = %q, want field and value context", err.Error())
+	}
+}
+
+func TestSourceRefCandidateCanonicalizesValidRefsAndPreservesInvalidRefs(t *testing.T) {
+	doc := unitRefSourceDocument(1, 2)
+
+	valid := SourceRefCandidate(doc, SourceRefResponse{
+		SourceID:    " session-alpha ",
+		StartUnitID: UnitRefFromInt(1),
+		EndUnitID:   UnitRefFromInt(2),
+	})
+	if valid != (source.SourceRef{SourceID: "session-alpha", StartUnitID: 1, EndUnitID: 2}) {
+		t.Fatalf("valid candidate = %#v, want canonical source ref", valid)
+	}
+
+	invalid := SourceRefCandidate(doc, SourceRefResponse{
+		SourceID:    "session-alpha",
+		StartUnitID: UnitRefFromInt(9),
+		EndUnitID:   UnitRefFromString("missing"),
+	})
+	if invalid != (source.SourceRef{SourceID: "session-alpha", StartUnitID: 9, EndUnitID: 0}) {
+		t.Fatalf("invalid candidate = %#v, want unresolved values for validator", invalid)
+	}
+}
+
+func unitRefSourceDocument(ids ...int) *source.SourceDocument {
+	doc := &source.SourceDocument{
+		ID:     "session-alpha",
+		Kind:   "transcript",
+		Format: "application/json",
+		Digest: "sha256:test",
+	}
+	for _, id := range ids {
+		doc.Units = append(doc.Units, source.SourceUnit{
+			ID:   id,
+			Kind: "transcript_segment",
+			Text: "text",
+		})
+	}
+	return doc
+}
--- a/internal/modules/dnd/validate/spells/shape/validator.go
+++ b/internal/modules/dnd/validate/spells/shape/validator.go
@@ -0,0 +1,60 @@
+package shape
+
+import (
+	"context"
+
+	"gitea.maximumdirect.net/eric/notarius/internal/framework/contracts"
+	"gitea.maximumdirect.net/eric/notarius/internal/framework/pipeline"
+	"gitea.maximumdirect.net/eric/notarius/internal/modules/dnd/validate/spells/spellpayload"
+)
+
+const Key = "extract/dnd/spells/shape"
+const ReasonCode = "invalid_spell_shape"
+
+var _ contracts.Validator = (*Validator)(nil)
+
+type Validator struct{}
+
+func New() *Validator {
+	return &Validator{}
+}
+
+func (v *Validator) Name() string {
+	return Key
+}
+
+func (v *Validator) ExecutionClass() contracts.ExecutionClass {
+	return contracts.ExecutionClassDeterministic
+}
+
+func (v *Validator) Validate(ctx context.Context, req contracts.ValidationRequest) (contracts.ValidationResult, error) {
+	payload, err := spellpayload.ValidationRequestPayload(req)
+	if err != nil {
+		return rejection(err.Error()), nil
+	}
+	if err := spellpayload.ValidateShape(payload); err != nil {
+		return rejection(err.Error()), nil
+	}
+	return contracts.ValidationResult{Approved: true}, nil
+}
+
+func Spec() pipeline.ValidatorSpec {
+	return pipeline.ValidatorSpec{
+		Key:            Key,
+		ExecutionClass: contracts.ExecutionClassDeterministic,
+	}
+}
+
+func Register(registry *pipeline.ValidatorRegistry) error {
+	return registry.RegisterWithSpec(Spec(), func() (contracts.Validator, error) {
+		return New(), nil
+	})
+}
+
+func rejection(message string) contracts.ValidationResult {
+	return contracts.ValidationResult{
+		Approved:   false,
+		ReasonCode: ReasonCode,
+		Message:    message,
+	}
+}
--- a/internal/modules/dnd/validate/spells/shape/validator_test.go
+++ b/internal/modules/dnd/validate/spells/shape/validator_test.go
@@ -0,0 +1,68 @@
+package shape
+
+import (
+	"context"
+	"testing"
+
+	"gitea.maximumdirect.net/eric/notarius/internal/framework/contracts"
+	"gitea.maximumdirect.net/eric/notarius/internal/framework/pipeline"
+)
+
+func TestValidatorApprovesWellFormedSpellPayload(t *testing.T) {
+	result, err := New().Validate(context.Background(), requestWithPayload(`{"spell_casts":[{"caster":"Aria","spell":"Cure Wounds","effect":"heals","narrative_description":"Aria heals Borin.","source_refs":[{"source_id":"session","start_unit_id":1,"end_unit_id":1}]}]}`))
+	if err != nil {
+		t.Fatalf("Validate() error = %v, want nil", err)
+	}
+	if !result.Approved {
+		t.Fatalf("Validate() = %#v, want approved", result)
+	}
+}
+
+func TestValidatorRejectsMalformedPayload(t *testing.T) {
+	result, err := New().Validate(context.Background(), requestWithPayload(`{"spell_casts":`))
+	if err != nil {
+		t.Fatalf("Validate() error = %v, want nil", err)
+	}
+	if result.Approved {
+		t.Fatalf("Approved = true, want false")
+	}
+	if result.ReasonCode != ReasonCode {
+		t.Fatalf("ReasonCode = %q, want %q", result.ReasonCode, ReasonCode)
+	}
+}
+
+func TestValidatorRejectsMissingRequiredSpellFields(t *testing.T) {
+	result, err := New().Validate(context.Background(), requestWithPayload(`{"spell_casts":[{"caster":"Aria","effect":"heals","narrative_description":"Aria heals Borin.","source_refs":[{"source_id":"session","start_unit_id":1,"end_unit_id":1}]}]}`))
+	if err != nil {
+		t.Fatalf("Validate() error = %v, want nil", err)
+	}
+	if result.Approved {
+		t.Fatalf("Approved = true, want false")
+	}
+	if result.ReasonCode != ReasonCode {
+		t.Fatalf("ReasonCode = %q, want %q", result.ReasonCode, ReasonCode)
+	}
+}
+
+func TestSpecAndRegister(t *testing.T) {
+	registry := pipeline.NewValidatorRegistry()
+	if err := Register(registry); err != nil {
+		t.Fatalf("Register() error = %v, want nil", err)
+	}
+	validator, err := registry.Build(Key)
+	if err != nil {
+		t.Fatalf("Build(%q) error = %v, want nil", Key, err)
+	}
+	if validator.Name() != Key || validator.ExecutionClass() != contracts.ExecutionClassDeterministic {
+		t.Fatalf("validator = %q/%q, want key and deterministic execution", validator.Name(), validator.ExecutionClass())
+	}
+}
+
+func requestWithPayload(payload string) contracts.ValidationRequest {
+	return contracts.ValidationRequest{
+		Payload: contracts.RawPayload{
+			Content:   []byte(payload),
+			MediaType: "application/json",
+		},
+	}
+}
--- a/internal/modules/dnd/validate/spells/source_refs/validator.go
+++ b/internal/modules/dnd/validate/spells/source_refs/validator.go
@@ -0,0 +1,69 @@
+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/validate/spells/spellpayload"
+)
+
+const Key = "extract/dnd/spells/source_refs"
+const ReasonCode = "invalid_source_refs"
+
+var _ contracts.Validator = (*Validator)(nil)
+
+type Validator struct{}
+
+func New() *Validator {
+	return &Validator{}
+}
+
+func (v *Validator) Name() string {
+	return Key
+}
+
+func (v *Validator) ExecutionClass() contracts.ExecutionClass {
+	return contracts.ExecutionClassDeterministic
+}
+
+func (v *Validator) Validate(ctx context.Context, req contracts.ValidationRequest) (contracts.ValidationResult, error) {
+	payload, err := spellpayload.ValidationRequestPayload(req)
+	if err != nil {
+		return rejection(err.Error()), nil
+	}
+	if err := spellpayload.ValidateShape(payload); err != nil {
+		return rejection(err.Error()), nil
+	}
+	for spellIndex, spell := range payload.SpellCasts {
+		for refIndex, ref := range spellpayload.SourceRefCandidates(req.Source, spell) {
+			if err := source.ValidateRef(req.Source, ref); err != nil {
+				return rejection(fmt.Sprintf("spell_casts[%d].source_refs[%d]: %v", spellIndex, refIndex, err)), nil
+			}
+		}
+	}
+	return contracts.ValidationResult{Approved: true}, nil
+}
+
+func Spec() pipeline.ValidatorSpec {
+	return pipeline.ValidatorSpec{
+		Key:            Key,
+		ExecutionClass: contracts.ExecutionClassDeterministic,
+	}
+}
+
+func Register(registry *pipeline.ValidatorRegistry) error {
+	return registry.RegisterWithSpec(Spec(), func() (contracts.Validator, error) {
+		return New(), nil
+	})
+}
+
+func rejection(message string) contracts.ValidationResult {
+	return contracts.ValidationResult{
+		Approved:   false,
+		ReasonCode: ReasonCode,
+		Message:    message,
+	}
+}
--- a/internal/modules/dnd/validate/spells/source_refs/validator_test.go
+++ b/internal/modules/dnd/validate/spells/source_refs/validator_test.go
@@ -0,0 +1,83 @@
+package sourcerefs
+
+import (
+	"context"
+	"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"
+)
+
+func TestValidatorApprovesValidSourceRefs(t *testing.T) {
+	result, err := New().Validate(context.Background(), requestWithPayload(validDocument(), `{"spell_casts":[{"caster":"Aria","spell":"Cure Wounds","effect":"heals","narrative_description":"Aria casts Cure Wounds.","source_refs":[{"source_id":"session","start_unit_id":1,"end_unit_id":2}]}]}`))
+	if err != nil {
+		t.Fatalf("Validate() error = %v, want nil", err)
+	}
+	if !result.Approved {
+		t.Fatalf("Validate() = %#v, want approved", result)
+	}
+}
+
+func TestValidatorRejectsInvalidSourceRefs(t *testing.T) {
+	result, err := New().Validate(context.Background(), requestWithPayload(validDocument(), `{"spell_casts":[{"caster":"Aria","spell":"Cure Wounds","effect":"heals","narrative_description":"Aria casts Cure Wounds.","source_refs":[{"source_id":"session","start_unit_id":99,"end_unit_id":99}]}]}`))
+	if err != nil {
+		t.Fatalf("Validate() error = %v, want nil", err)
+	}
+	if result.Approved {
+		t.Fatalf("Approved = true, want false")
+	}
+	if result.ReasonCode != ReasonCode {
+		t.Fatalf("ReasonCode = %q, want %q", result.ReasonCode, ReasonCode)
+	}
+}
+
+func TestValidatorRejectsMissingSourceDocument(t *testing.T) {
+	result, err := New().Validate(context.Background(), requestWithPayload(nil, `{"spell_casts":[{"caster":"Aria","spell":"Cure Wounds","effect":"heals","narrative_description":"Aria casts Cure Wounds.","source_refs":[{"source_id":"session","start_unit_id":1,"end_unit_id":1}]}]}`))
+	if err != nil {
+		t.Fatalf("Validate() error = %v, want nil", err)
+	}
+	if result.Approved {
+		t.Fatalf("Approved = true, want false")
+	}
+	if result.ReasonCode != ReasonCode {
+		t.Fatalf("ReasonCode = %q, want %q", result.ReasonCode, ReasonCode)
+	}
+}
+
+func TestSpecAndRegister(t *testing.T) {
+	registry := pipeline.NewValidatorRegistry()
+	if err := Register(registry); err != nil {
+		t.Fatalf("Register() error = %v, want nil", err)
+	}
+	validator, err := registry.Build(Key)
+	if err != nil {
+		t.Fatalf("Build(%q) error = %v, want nil", Key, err)
+	}
+	if validator.Name() != Key || validator.ExecutionClass() != contracts.ExecutionClassDeterministic {
+		t.Fatalf("validator = %q/%q, want key and deterministic execution", validator.Name(), validator.ExecutionClass())
+	}
+}
+
+func requestWithPayload(doc *source.SourceDocument, payload string) contracts.ValidationRequest {
+	return contracts.ValidationRequest{
+		Source: doc,
+		Payload: contracts.RawPayload{
+			Content:   []byte(payload),
+			MediaType: "application/json",
+		},
+	}
+}
+
+func validDocument() *source.SourceDocument {
+	return &source.SourceDocument{
+		ID:     "session",
+		Kind:   "transcript",
+		Format: "application/json",
+		Digest: "sha256:session",
+		Units: []source.SourceUnit{
+			{ID: 1, Kind: "message", Text: "Aria raises her holy symbol."},
+			{ID: 2, Kind: "message", Text: "Aria casts Cure Wounds on Borin."},
+		},
+	}
+}
--- a/internal/modules/dnd/validate/spells/source_relatedness/validator.go
+++ b/internal/modules/dnd/validate/spells/source_relatedness/validator.go
@@ -0,0 +1,83 @@
+package sourcerelatedness
+
+import (
+	"context"
+	"fmt"
+	"strings"
+
+	"gitea.maximumdirect.net/eric/notarius/internal/core/source"
+	"gitea.maximumdirect.net/eric/notarius/internal/framework/contracts"
+	"gitea.maximumdirect.net/eric/notarius/internal/framework/pipeline"
+	"gitea.maximumdirect.net/eric/notarius/internal/modules/dnd/validate/spells/spellpayload"
+)
+
+const Key = "extract/dnd/spells/source_relatedness"
+const WarningReasonCode = "spell_not_near_source"
+
+var _ contracts.Validator = (*Validator)(nil)
+
+type Validator struct{}
+
+func New() *Validator {
+	return &Validator{}
+}
+
+func (v *Validator) Name() string {
+	return Key
+}
+
+func (v *Validator) ExecutionClass() contracts.ExecutionClass {
+	return contracts.ExecutionClassDeterministic
+}
+
+func (v *Validator) Validate(ctx context.Context, req contracts.ValidationRequest) (contracts.ValidationResult, error) {
+	payload, err := spellpayload.ValidationRequestPayload(req)
+	if err != nil {
+		return contracts.ValidationResult{Approved: true}, nil
+	}
+	if err := spellpayload.ValidateShape(payload); err != nil {
+		return contracts.ValidationResult{Approved: true}, nil
+	}
+
+	var warnings []contracts.Warning
+	for spellIndex, spell := range payload.SpellCasts {
+		if !spellAppearsInCitedText(req.Source, spell) {
+			warnings = append(warnings, contracts.Warning{
+				Scope:      fmt.Sprintf("spell_casts[%d]", spellIndex),
+				ReasonCode: WarningReasonCode,
+				Message:    fmt.Sprintf("spell %q was not found in cited source text", strings.TrimSpace(spell.Spell)),
+			})
+		}
+	}
+	return contracts.ValidationResult{Approved: true, Warnings: warnings}, nil
+}
+
+func Spec() pipeline.ValidatorSpec {
+	return pipeline.ValidatorSpec{
+		Key:            Key,
+		ExecutionClass: contracts.ExecutionClassDeterministic,
+	}
+}
+
+func Register(registry *pipeline.ValidatorRegistry) error {
+	return registry.RegisterWithSpec(Spec(), func() (contracts.Validator, error) {
+		return New(), nil
+	})
+}
+
+func spellAppearsInCitedText(doc *source.SourceDocument, spell spellpayload.SpellCast) bool {
+	name := strings.ToLower(strings.TrimSpace(spell.Spell))
+	if name == "" {
+		return true
+	}
+	for _, ref := range spellpayload.SourceRefCandidates(doc, spell) {
+		text, ok := spellpayload.CitedText(doc, ref)
+		if !ok {
+			continue
+		}
+		if strings.Contains(strings.ToLower(text), name) {
+			return true
+		}
+	}
+	return false
+}
--- a/internal/modules/dnd/validate/spells/source_relatedness/validator_test.go
+++ b/internal/modules/dnd/validate/spells/source_relatedness/validator_test.go
@@ -0,0 +1,86 @@
+package sourcerelatedness
+
+import (
+	"context"
+	"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"
+)
+
+func TestValidatorApprovesWithoutWarningWhenSpellAppearsInCitedText(t *testing.T) {
+	result, err := New().Validate(context.Background(), requestWithPayload(validDocument(), `{"spell_casts":[{"caster":"Aria","spell":"Cure Wounds","effect":"heals","narrative_description":"Aria casts Cure Wounds.","source_refs":[{"source_id":"session","start_unit_id":2,"end_unit_id":2}]}]}`))
+	if err != nil {
+		t.Fatalf("Validate() error = %v, want nil", err)
+	}
+	if !result.Approved {
+		t.Fatalf("Approved = false, want true")
+	}
+	if len(result.Warnings) != 0 {
+		t.Fatalf("Warnings = %#v, want none", result.Warnings)
+	}
+}
+
+func TestValidatorWarnsWhenSpellDoesNotAppearInCitedText(t *testing.T) {
+	result, err := New().Validate(context.Background(), requestWithPayload(validDocument(), `{"spell_casts":[{"caster":"Borin","spell":"Fire Bolt","effect":"scorches","narrative_description":"Borin casts Fire Bolt.","source_refs":[{"source_id":"session","start_unit_id":1,"end_unit_id":1}]}]}`))
+	if err != nil {
+		t.Fatalf("Validate() error = %v, want nil", err)
+	}
+	if !result.Approved {
+		t.Fatalf("Approved = false, want true")
+	}
+	if len(result.Warnings) != 1 {
+		t.Fatalf("Warnings = %#v, want one warning", result.Warnings)
+	}
+	if result.Warnings[0].ReasonCode != WarningReasonCode {
+		t.Fatalf("ReasonCode = %q, want %q", result.Warnings[0].ReasonCode, WarningReasonCode)
+	}
+}
+
+func TestValidatorApprovesMalformedPayloadWithoutWarning(t *testing.T) {
+	result, err := New().Validate(context.Background(), requestWithPayload(validDocument(), `{"spell_casts":`))
+	if err != nil {
+		t.Fatalf("Validate() error = %v, want nil", err)
+	}
+	if !result.Approved {
+		t.Fatalf("Approved = false, want true")
+	}
+}
+
+func TestSpecAndRegister(t *testing.T) {
+	registry := pipeline.NewValidatorRegistry()
+	if err := Register(registry); err != nil {
+		t.Fatalf("Register() error = %v, want nil", err)
+	}
+	validator, err := registry.Build(Key)
+	if err != nil {
+		t.Fatalf("Build(%q) error = %v, want nil", Key, err)
+	}
+	if validator.Name() != Key || validator.ExecutionClass() != contracts.ExecutionClassDeterministic {
+		t.Fatalf("validator = %q/%q, want key and deterministic execution", validator.Name(), validator.ExecutionClass())
+	}
+}
+
+func requestWithPayload(doc *source.SourceDocument, payload string) contracts.ValidationRequest {
+	return contracts.ValidationRequest{
+		Source: doc,
+		Payload: contracts.RawPayload{
+			Content:   []byte(payload),
+			MediaType: "application/json",
+		},
+	}
+}
+
+func validDocument() *source.SourceDocument {
+	return &source.SourceDocument{
+		ID:     "session",
+		Kind:   "transcript",
+		Format: "application/json",
+		Digest: "sha256:session",
+		Units: []source.SourceUnit{
+			{ID: 1, Kind: "message", Text: "Borin draws his dagger."},
+			{ID: 2, Kind: "message", Text: "Aria casts Cure Wounds on Borin."},
+		},
+	}
+}
--- a/internal/modules/dnd/validate/spells/spellpayload/payload.go
+++ b/internal/modules/dnd/validate/spells/spellpayload/payload.go
@@ -0,0 +1,98 @@
+package spellpayload
+
+import (
+	"bytes"
+	"encoding/json"
+	"fmt"
+	"io"
+	"strings"
+
+	"gitea.maximumdirect.net/eric/notarius/internal/core/source"
+	"gitea.maximumdirect.net/eric/notarius/internal/framework/contracts"
+	"gitea.maximumdirect.net/eric/notarius/internal/modules/dnd/shared"
+)
+
+type Payload struct {
+	SpellCasts []SpellCast `json:"spell_casts"`
+}
+
+type SpellCast struct {
+	Caster               string                     `json:"caster"`
+	Spell                string                     `json:"spell"`
+	Effect               string                     `json:"effect"`
+	NarrativeDescription string                     `json:"narrative_description"`
+	SourceRefs           []shared.SourceRefResponse `json:"source_refs"`
+}
+
+func Parse(raw []byte) (Payload, error) {
+	decoder := json.NewDecoder(bytes.NewReader(raw))
+	decoder.DisallowUnknownFields()
+
+	var payload Payload
+	if err := decoder.Decode(&payload); err != nil {
+		return Payload{}, fmt.Errorf("parse spell payload: %w", err)
+	}
+	var extra any
+	if err := decoder.Decode(&extra); err != io.EOF {
+		return Payload{}, fmt.Errorf("parse spell payload: multiple JSON values")
+	}
+	return payload, nil
+}
+
+func ValidateShape(payload Payload) error {
+	if payload.SpellCasts == nil {
+		return fmt.Errorf("spell_casts must be present")
+	}
+	for index, spell := range payload.SpellCasts {
+		if strings.TrimSpace(spell.Caster) == "" {
+			return fmt.Errorf("spell_casts[%d].caster must not be empty", index)
+		}
+		if strings.TrimSpace(spell.Spell) == "" {
+			return fmt.Errorf("spell_casts[%d].spell must not be empty", index)
+		}
+		if strings.TrimSpace(spell.Effect) == "" {
+			return fmt.Errorf("spell_casts[%d].effect must not be empty", index)
+		}
+		if strings.TrimSpace(spell.NarrativeDescription) == "" {
+			return fmt.Errorf("spell_casts[%d].narrative_description must not be empty", index)
+		}
+		if len(spell.SourceRefs) == 0 {
+			return fmt.Errorf("spell_casts[%d].source_refs must not be empty", index)
+		}
+	}
+	return nil
+}
+
+func SourceRefCandidates(doc *source.SourceDocument, spell SpellCast) []source.SourceRef {
+	refs := make([]source.SourceRef, 0, len(spell.SourceRefs))
+	for _, ref := range spell.SourceRefs {
+		refs = append(refs, shared.SourceRefCandidate(doc, ref))
+	}
+	return refs
+}
+
+func CitedText(doc *source.SourceDocument, ref source.SourceRef) (string, bool) {
+	if doc == nil {
+		return "", false
+	}
+	startIndex, ok := source.UnitIndex(doc, ref.StartUnitID)
+	if !ok {
+		return "", false
+	}
+	endIndex, ok := source.UnitIndex(doc, ref.EndUnitID)
+	if !ok || startIndex > endIndex {
+		return "", false
+	}
+	var b strings.Builder
+	for i := startIndex; i <= endIndex; i++ {
+		if b.Len() > 0 {
+			b.WriteByte('\n')
+		}
+		b.WriteString(doc.Units[i].Text)
+	}
+	return b.String(), true
+}
+
+func ValidationRequestPayload(req contracts.ValidationRequest) (Payload, error) {
+	return Parse(req.Payload.Content)
+}