# D&D Spell Raw Output

This document is the durable raw output contract for the implemented
`dnd/spells` extractor.

## Identity

- Extractor key: `dnd/spells`
- Prompt ID: `dnd.spells`
- Response schema key: `dnd_spells`
- Response schema ID: `notarius.dnd.spells`
- Response schema name: `notarius_dnd_spells_v1`
- Response schema version: `v1`
- Media type: `application/json`

The extractor requires source chunks and transcript source capability. It
returns canonical spell-cast JSON derived from the structured LLM response. The
extractor assigns source IDs deterministically and keeps source-unit ranges as
model-authored evidence locations. The default `appendorder` merger passes a
single chunk output through and concatenates multiple
`spell_casts` arrays in chunk order. The default `noop` normalizer passes the
merge output through unchanged.

## Output Shape

For a single chunk, `lanes/spells.json` has this shape:

```json
{
  "spell_casts": [
    {
      "caster": "Aria",
      "spell": "Cure Wounds",
      "effect": "heals an injured ally",
      "narrative_description": "Aria raises her holy symbol and casts Cure Wounds.",
      "source_refs": [
        {
          "source_id": "session-alpha",
          "start_unit_id": 1,
          "end_unit_id": 1
        }
      ]
    }
  ]
}
```

`spell_casts` must be present. It may be empty when no spell casts are found.

For multiple chunks with the default merger, the lane output keeps the same
top-level shape and concatenates `spell_casts` in chunk order:

```json
{
  "spell_casts": [
    {
      "caster": "Aria",
      "spell": "Cure Wounds",
      "effect": "heals an injured ally",
      "narrative_description": "Aria raises her holy symbol and casts Cure Wounds.",
      "source_refs": [
        {
          "source_id": "session-alpha",
          "start_unit_id": 1,
          "end_unit_id": 1
        }
      ]
    }
  ]
}
```

## Spell-Cast Fields

Each spell cast contains:

- `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;
- `source_refs`: transcript source references with extractor-assigned source
  IDs and model-supplied unit ranges.

`caster` is the in-world caster, not the transcript speaker.

## Source References

Each source reference uses the generic source-reference shape:

- `source_id`
- `start_unit_id`
- `end_unit_id`

The LLM-facing prompt schema asks only for integer `start_unit_id` and
`end_unit_id` values matching source-unit IDs. `source_id` is assigned by the
extractor from the source document ID before validation and output, and is
required in this durable output contract.

## References

The extractor accepts optional UTF-8 text references:

- `players`
- `party`
- `glossary`
- `roster`, a deprecated compatibility alias for `party`

References are supporting disambiguation material only. They are not source
evidence and are not addressable through `source_refs`.

## Manifest Metadata

The extractor adds prompt and response-schema provenance under the artifact lane
manifest metadata:

```json
{
  "metadata": {
    "extractor": {
      "prompt_id": "dnd.spells",
      "prompt_version": "v1",
      "prompt_sha256": "sha256:...",
      "response_schema_key": "dnd_spells",
      "response_schema_id": "notarius.dnd.spells",
      "response_schema_name": "notarius_dnd_spells_v1",
      "response_schema_version": "v1",
      "response_schema_sha256": "sha256:..."
    }
  }
}
```

Raw prompt and schema content are not included in manifest metadata.