72 lines
2.8 KiB
Markdown
72 lines
2.8 KiB
Markdown
# D&D Combat-Turn Artifact
|
|
|
|
This contract defines the durable combat-action occurrence list produced by
|
|
`dnd/combat-turns`. It records source-grounded turns and actions; it is not a
|
|
complete initiative tracker, combat summary, or state model.
|
|
|
|
## Identity and compatibility
|
|
|
|
| Property | Value |
|
|
| --- | --- |
|
|
| Artifact kind | `dnd/combat-turn-list` |
|
|
| Schema ID | `notarius.dnd.combat_turns` |
|
|
| Schema name | `notarius_dnd_combat_turns_v1` |
|
|
| Schema version | `v1` |
|
|
| Media type | `application/json` |
|
|
|
|
`v1` is a strict JSON object with required `combat_turns`; the array may be
|
|
empty. Turn and source-reference objects reject unknown fields. An incompatible
|
|
shape change requires a new schema version.
|
|
|
|
## Wire shape
|
|
|
|
Each combat turn has these required fields:
|
|
|
|
| Field | Contract |
|
|
| --- | --- |
|
|
| `actor` | Non-empty acting character or creature name. |
|
|
| `turn_kind` | `turn`, `reaction`, `legendary_action`, `lair_action`, or `other`. |
|
|
| `source_refs` | One or more transcript evidence ranges. |
|
|
|
|
Each source reference has exactly `source_id`, `start_unit_id`, and
|
|
`end_unit_id`. It identifies an inclusive current-transcript range; unit IDs
|
|
are positive and the start may not follow the end.
|
|
|
|
```json
|
|
{
|
|
"combat_turns": [
|
|
{
|
|
"actor": "Mira Thorn",
|
|
"turn_kind": "turn",
|
|
"source_refs": [
|
|
{"source_id": "session-7", "start_unit_id": 31, "end_unit_id": 32}
|
|
]
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
## Eligibility, evidence, and normalized form
|
|
|
|
The extractor requires an approved [scene-description artifact](dnd-scene-description-artifacts.md).
|
|
It emits combat turns only for a chunk with an exact matching scene classified
|
|
`combat`; an exact non-combat scene produces an accepted empty list. The scene
|
|
record controls eligibility only: its title, summary, and reference do not
|
|
become turn evidence. No exact matching scene also produces an empty list and
|
|
the `scene_classification_unavailable` warning.
|
|
|
|
An optional normalized [NPC registry artifact](dnd-npc-registry-artifacts.md) can ground an
|
|
actor name. Its registry references are provenance, never combat evidence.
|
|
Normalization trims and, where possible, canonicalizes actor names; orders and
|
|
deduplicates exact source references; orders valid-evidence turns by source
|
|
chronology; and collapses only duplicates with the same actor identity, turn
|
|
kind, and complete valid evidence. It does not infer turns, initiative, or
|
|
actions from registry or scene data.
|
|
|
|
The [NPC-occurrence artifact](dnd-npc-occurrence-artifacts.md) records
|
|
broader NPC occurrences. The [enemy-event artifact](dnd-enemy-event-artifacts.md)
|
|
uses combat turns as grounding only; turns do not establish an enemy event or
|
|
its outcome. The [JSON output contract](json-output.md) defines publication,
|
|
and [D&D module internals](../internal/dnd.md) describes routing and validation
|
|
mechanics.
|