Add standalone D&D combat turn extraction

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

@@ -1,8 +1,8 @@
 # D&D Combat-Turn Artifact Contract
 
-This document defines the durable artifact and serialization boundary for
-D&D combat turns. It does not define extraction, validation beyond the codec's
-structural checks, normalization, prompts, or a selectable pipeline lane.
+This document defines the durable artifact, serialization, extraction, and
+candidate-validation boundaries for D&D combat turns. Normalization and a
+selectable production pipeline lane are not part of this contract yet.
 
 ## Artifact identity
 
@@ -71,3 +71,53 @@ The codec owns the durable JSON Schema, whose object layers all set
 
 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 makes one
+structured completion for each supplied 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.
+
+The private response shape is the same as the durable turn/action shape except
+that source references contain only `start_unit_id` and `end_unit_id`. 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.
+Malformed candidate fields remain in the typed result for deterministic
+validators to report.
+
+## Deterministic candidate validation
+
+The standalone validator keys are:
+
+| Validator | Responsibility |
+| --- | --- |
+| `extract/dnd/combat-turns/shape` | Required arrays, strings, nullable fields, positive rounds, and supported enum 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 or declared action 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, compares actors with
+the shared Unicode-aware NPC identity policy, and checks declaration tokens of
+at least four Unicode code points against complete cited-text tokens. Targets
+are not checked deterministically.
+
+The extractor and validators are package-complete but are not registered by the
+production D&D family registrar yet. Normalization, production composition,
+and selectable configuration are defined when implemented.