notarius/docs/integrations/dnd-combat-turn-artifacts.md

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.

{
  "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. 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 artifact 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-interaction artifact records broader NPC occurrences. The JSON output contract defines publication, and D&D module internals describes routing and validation mechanics.