# 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

The current implementation covers only D&D spell-cast extraction. It does not
yet implement:

- item extraction;
- NPC extraction;
- combat extraction;
- encounter extraction;
- broad D&D rules validation;
- a CLI `run` workflow.