# D&D Spell-Cast Artifacts

This document is the durable artifact contract for approved
`dnd.spell_cast` artifacts produced by the implemented `dnd/spells` extractor.

## Artifact Identity

- Extractor 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 extractor requires source chunks and transcript source capability. It
returns generic artifact candidates that are serialized by the JSON output
module.

## Artifact Envelope

Approved artifacts use the generic artifact envelope documented in
[JSON Output](json-output.md#artifact-files):

```json
{
  "extractor_key": "dnd/spells",
  "artifact_type": "dnd.spell_cast",
  "schema_version": "v1",
  "payload": {
    "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": "seg-001",
      "end_unit_id": "seg-001"
    }
  ]
}
```

## Payload Fields

The `payload` object 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.

All payload fields are strings and must be non-empty after trimming.

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

## Source References

Source references live on the artifact envelope as `source_refs`; they are not
duplicated inside the `payload`.

Each source reference uses the generic source-reference shape:

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

Validation requires:

- at least one source reference;
- non-empty source ID and unit IDs;
- source ID matching the source document ID;
- start and end unit IDs existing in the source document;
- start unit appearing before or at the same position as end unit.

## Structured LLM Response Shape

The extractor asks the LLM for this top-level response 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": "seg-001",
          "end_unit_id": "seg-001"
        }
      ]
    }
  ]
}
```

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

The response schema asset is embedded at
`internal/modules/extract/dnd/spells/assets/schemas/dnd_spells.v1.json`.

## Validators

The extractor supplies two deterministic validators by default:

- `dnd/spells/shape`
- `dnd/spells/source_refs`

Rejection reason codes:

- `invalid_payload`: payload JSON cannot be decoded as a spell-cast payload.
- `missing_required_field`: `caster`, `spell`, `effect`, or
  `narrative_description` is blank.
- `missing_source_ref`: candidate has no source references.
- `invalid_source_ref`: at least one source reference fails generic source
  reference validation.

Rejected candidates are written to `rejected.json` by the JSON output module.

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

## Compatibility Limit

This contract covers only `dnd.spell_cast` artifacts produced by the
implemented spell-cast extractor.