Document D&D spells extraction contract

docs/integrations/dnd-spells.md

@@ -0,0 +1,116 @@
+# D&D Spell Cast Extraction
+
+This document describes the D&D spell-cast extractor currently implemented in
+Notarius.
+
+## Module
+
+- Module key: `dnd/spells`
+- Artifact type: `dnd.spell_cast`
+- Schema version: `v1`
+- Prompt ID: `dnd.spells`
+- Response schema key: `dnd_spells`
+- Response schema ID: `notarius.dnd.spells`
+- Response schema name: `notarius_dnd_spells_v1`
+
+The module is an extract module. It reads a generic source chunk, renders the
+`dnd.spells` prompt, calls the configured structured LLM client, and returns
+spell-cast artifact candidates.
+
+## Source Expectations
+
+The extractor expects a generic `SourceDocument` and active source chunk. It
+does not depend on concrete Seriatim package types.
+
+Pipeline resolution must provide these capabilities before the extractor runs:
+
+- `chunks`
+- `source.transcript`
+
+Source units may include transcript metadata such as speaker and timestamps.
+That metadata is optional prompt context. It is not part of the durable spell
+payload.
+
+## Artifact Payload
+
+Each approved artifact payload is a JSON object with these fields:
+
+- `caster`: in-world character or creature casting the spell;
+- `spell`: spell name;
+- `effect`: concise spell effect in the scene;
+- `narrative_description`: short description of the spell cast in context.
+
+`caster` is not the table speaker. NPCs, monsters, and other DM-voiced
+characters can be casters.
+
+## Source References
+
+The structured LLM response must include `source_refs` for each spell cast.
+Each source reference uses the generic source-reference shape:
+
+- `source_id`
+- `start_unit_id`
+- `end_unit_id`
+
+The extractor copies those references into the generic artifact envelope
+`source_refs` field. The durable `dnd.spell_cast` payload does not duplicate
+source references.
+
+Source-reference IDs must match the source document and source-unit IDs
+exactly. The validator chain rejects unknown source IDs, unknown unit IDs, and
+reversed unit ranges.
+
+## Validators
+
+The extractor provides these deterministic validators by default, in order:
+
+- `dnd/spells/shape`
+- `dnd/spells/source_refs`
+
+`dnd/spells/shape` rejects:
+
+- malformed JSON payloads with reason code `invalid_payload`;
+- blank `caster`, `spell`, `effect`, or `narrative_description` fields with
+  reason code `missing_required_field`.
+
+`dnd/spells/source_refs` rejects:
+
+- candidates with no source references using reason code `missing_source_ref`;
+- invalid source references using reason code `invalid_source_ref`.
+
+The source-reference validator uses the core `source.ValidateRef` behavior, so
+its rejection message includes the underlying source-reference validation
+error.
+
+## Capabilities
+
+The module declares these required capabilities:
+
+- `chunks`
+- `source.transcript`
+
+The module declares this provided capability:
+
+- `dnd.spell_casts`
+
+A pipeline artifact lane can reference the extractor with:
+
+```yaml
+artifacts:
+  spells:
+    extract: dnd/spells
+    merge: appendorder
+    normalize: noop
+```
+
+## Limits
+
+This checkpoint implements only D&D spell-cast extraction. It does not
+implement:
+
+- item extraction;
+- NPC extraction;
+- combat extraction;
+- encounter extraction;
+- broad D&D rules validation;
+- a CLI `run` workflow.

docs/roadmap/6-dnd-spells-extractor.md

@@ -2,7 +2,9 @@
 
 ## Status
 
-This document describes planned work, not implemented behavior.
+This document records the target scope for checkpoint 6. The implemented
+integration contract is documented in
+[`docs/integrations/dnd-spells.md`](../integrations/dnd-spells.md).
 
 ## Goal