# D&D Combat-Turn Artifact Contract This document defines the durable artifact, serialization, extraction, candidate-validation, normalization, and production lane boundaries for D&D combat turns. ## Artifact identity | 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` | The top-level JSON object contains the required `combat_turns` array, which may be empty. Every object rejects unknown fields. ## JSON shape Each combat turn contains these required fields: | Field | Shape | | --- | --- | | `actor` | Non-empty string. | | `turn_kind` | One of `turn`, `reaction`, `legendary_action`, `lair_action`, or `other`. | | `source_refs` | Required array with at least one source reference. | Source references use the shared source-reference shape: ```json { "source_id": "session-alpha", "start_unit_id": 1, "end_unit_id": 2 } ``` `source_id` must be non-empty and both unit IDs must be positive integers. The codec does not resolve references against a source document or enforce source range ordering; those checks belong to the later source-reference validation boundary. ## Codec behavior The codec exposes two representations of the same typed artifact: - Candidate encode/decode preserves invalid actor and turn-kind values, collection presence, and source references so later validators can report them. Candidate decoding still requires valid JSON, one JSON value, known fields, and compatible JSON types. - Approved encode/decode enforces the structural rules in this contract. The codec owns the durable JSON Schema, whose object layers all set `additionalProperties` to `false`. Codec metadata contains only `combat_turn_count`. The maintained compact fixture is `internal/modules/dnd/codec/combatturns/testdata/dnd_combat_turns.v1.json`. ## Extraction boundary The standalone extractor uses these identities: | Property | Value | | --- | --- | | Extractor key | `dnd/combat-turns` | | Capability | `dnd.combat_turns` | | Prompt ID | `dnd.combat_turns` | | Prompt version | `v1` | | Private response-schema key | `dnd_combat_turns_llm` | | Private response-schema ID | `notarius.dnd.combat_turns.llm` | | Default profile | `gemini-2-flash` | It requires `chunks` and `source.transcript`, accepts no options, and requires one `scene_descriptions` reference. That reference must be exactly one approved `dnd/scene-description-list` artifact with media type `application/json` and a maximum size of 1 MiB (1048576 bytes). It may be an external file validated during preparation or a canonical generated artifact supplied at an ordered step handoff. An unbound slot is a configuration error. The scene artifact controls eligibility, not evidence. The extractor calls the LLM only when exactly one record has the current chunk's ID, source ID, start unit ID, and end unit ID, and that record has `kind: combat`. An exact `narrative`, `recap`, or `meta` record returns an accepted empty `combat_turns` array without an LLM call, warning, or retry attempt. A missing or mismatched exact record returns the same accepted empty result without an LLM call or retry and emits one content-safe `scene_classification_unavailable` warning. The scene artifact, its title and summary, and its source references are never copied into combat turns. For an eligible combat chunk, the prompt receives the chunk-scoped transcript plus the existing `players`, `party`, and `glossary` inputs, and optionally the deprecated `roster` reference through the shared party mapping. The optional `npcs` reference is an approved normalized NPC artifact used only for identity grounding; it never supplies combat evidence. `scene_descriptions` is never a combat prompt input. The private response envelope has the same turn fields and JSON types as the durable shape except that source references contain only `start_unit_id` and `end_unit_id`. It enforces required field presence, types, and unknown-field rejection, while deterministic validators own enum membership, non-empty values and collections, and positive-number requirements. The extractor assigns the current source ID, removes exact duplicate ranges, and stable-sorts turns by the earliest valid source-document position. Numeric unit IDs are identifiers; source-document slice position determines chronology. Semantically malformed candidate fields remain in the typed result for the configured validation and retry boundary. ## Deterministic candidate validation The standalone validator keys are: | Validator | Responsibility | | --- | --- | | `extract/dnd/combat-turns/shape` | Required list, actor, turn kind, and source references, plus supported turn-kind values. | | `extract/dnd/combat-turns/source_refs` | Source identity, source-unit existence, and range order through the source document. | | `extract/dnd/combat-turns/source_relatedness` | At most one advisory warning per turn when the actor is not related to cited transcript text. | Source-reference and relatedness validators defer malformed shape to the shape validator. Relatedness also defers when any cited source range is invalid. It combines overlapping cited ranges once in document order and compares actors with the shared Unicode-aware NPC identity policy. The production D&D registrar exposes the extractor and these validators. Its default extraction chain preserves this order: JSON syntax, combat shape, source references, private response schema, then source relatedness. ## Normalization boundary The standalone normalizer uses key `dnd/combat-turns`, requires `merged`, provides `normalized`, accepts no options, and accepts only the optional structured `npcs` reference. Campaign references are LLM extraction context and are not normalizer inputs. For an external file, the NPC registry is resolved during preparation; for a generated binding, it is resolved at the operation- time handoff. Runtime normalization uses that immutable prepared or handed-off view. Normalization policy is `dnd.combat_turns.normalize.v1`. It display-normalizes the actor, canonicalizes exact registry actor matches, orders and deduplicates exact source references, stable-sorts records by earliest valid source-document position, and collapses only records with the same actor identity, turn kind, and complete valid evidence set. The first normalized record is retained. Invalid evidence is never eligible for duplicate collapse. Every mutation and collapse emits a bounded warning using the merged input index in its scope. The normalizer reports `normalization_policy` and `identity_policy` metadata and fingerprints. An external registry may additionally contribute `npc_registry_digest` and `npc_count`; generated registry identity is retained in framework handoff provenance and dependency fingerprints. The normalized-invariants validator is `normalize/dnd/combat-turns/invariants`; it defers shape and source-reference failures, then checks actor display normalization, canonical evidence ordering, chronology, and duplicate identity. It rejects with `invalid_combat_turn_normalization` under policy `dnd.combat_turns.validator.normalized.v1`. The production D&D registrar exposes the normalizer and normalized-invariants validator. Its default normalization chain is JSON syntax, combat shape, normalized invariants, source references, durable schema, then source relatedness. The lane uses the framework's typed append-order merger and has no merge validator chain. ## Production manifest and references The selectable lane uses extractor and normalizer key `dnd/combat-turns`, `appendorder` for the typed merger, and the durable codec above. Bound external references contribute raw-file provenance to the run manifest. Generated bindings contribute artifact kind, schema identity, media type, canonical digest, size, and bounded producer provenance. This includes the generated scene-description artifact for the combat extractor. Consumer metadata and checkpoint fingerprints contain no reference names, content, paths, source ranges, scene titles, or scene summaries. For an external scene artifact, component metadata records the gate policy plus a semantic eligibility digest and record count; generated scene identity remains in framework handoff provenance and dependencies. The eligibility digest changes with scene ID, exact source range, or kind, but not with title or summary. The normalized lane is emitted as `lanes/.json` by the JSON output module, and warnings and rejection summaries remain in their shared companion files.