74 lines
2.7 KiB
Markdown
74 lines
2.7 KiB
Markdown
# D&D Spell Artifact
|
|
|
|
This contract defines the durable output of the `dnd/spells` extractor and
|
|
normalizer. It records source-grounded spell-casting occurrences; it is not a
|
|
spellbook, a rules lookup result, or a record of hypothetical casts.
|
|
|
|
## Identity and compatibility
|
|
|
|
| Property | Value |
|
|
| --- | --- |
|
|
| Artifact kind | `dnd/spell-list` |
|
|
| Schema ID | `notarius.dnd.spells` |
|
|
| Schema name | `notarius_dnd_spells_v1` |
|
|
| Schema version | `v1` |
|
|
| Media type | `application/json` |
|
|
|
|
`v1` is a single strict JSON object. It requires `spell_casts`; the array may
|
|
be empty. Each spell-cast object and source-reference object rejects unknown
|
|
fields. An incompatible shape change requires a new schema version.
|
|
|
|
## Wire shape
|
|
|
|
Each `spell_casts` entry has these required fields:
|
|
|
|
| Field | Contract |
|
|
| --- | --- |
|
|
| `caster` | Non-empty in-world character or creature name. |
|
|
| `spell` | Non-empty spell name. |
|
|
| `source_refs` | One or more transcript evidence ranges. |
|
|
|
|
Every source reference has exactly `source_id`, `start_unit_id`, and
|
|
`end_unit_id`. The source ID identifies the input transcript; the unit IDs are
|
|
positive inclusive unit identifiers, and the start may not follow the end in
|
|
that source. References are evidence for the cast, not campaign-reference or
|
|
NPC-registry provenance.
|
|
|
|
```json
|
|
{
|
|
"spell_casts": [
|
|
{
|
|
"caster": "Mira Thorn",
|
|
"spell": "Fireball",
|
|
"source_refs": [
|
|
{"source_id": "session-7", "start_unit_id": 12, "end_unit_id": 13}
|
|
]
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
## Evidence and normalized form
|
|
|
|
An entry represents an actual cast or an unambiguous declared attempt. A spell
|
|
mention, rules discussion, plan, or catalog match alone is not an occurrence.
|
|
The configured catalog checks the name; it does not establish evidence.
|
|
|
|
When normalization is selected, recognized spell names use the effective
|
|
catalog's canonical display name. Source references are put in canonical source
|
|
order and exact duplicate references are removed. A later entry is collapsed
|
|
only when it has the same canonical spell, the same case- and
|
|
whitespace-insensitive caster identity, and the same complete valid reference
|
|
sequence. Remaining entries retain their merged order.
|
|
|
|
The optional normalized [NPC registry artifact](dnd-npc-registry-artifacts.md) can ground a
|
|
caster name. Its own references remain registry provenance and are never copied
|
|
into `source_refs`.
|
|
|
|
## Related contracts
|
|
|
|
The [spell-catalog overlay contract](dnd-spell-catalog-overlays.md) defines
|
|
the configured catalog additions. The [JSON output contract](json-output.md)
|
|
defines where this logical artifact is published; [D&D module internals](../internal/dnd.md)
|
|
describes extraction and validation mechanics.
|