notarius/docs/integrations/dnd-spell-artifacts.md

# 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 the structured LLM response as raw JSON. 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 supplied by the model.

`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 extractor prompt and schema use integer `start_unit_id` and `end_unit_id`
values matching source-unit IDs.

## 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.