Document scene-aware combat extraction

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

@@ -73,15 +73,29 @@ The standalone extractor uses these identities:
 | 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.
-An external file is validated during preparation. In an ordered pipeline, the
-same slot may receive the producer's canonical generated artifact at the step
-handoff.
+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`
@@ -151,13 +165,16 @@ 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. A bound `npcs`
-reference contributes raw-file provenance to the run manifest. A generated
-binding contributes artifact kind, schema identity, media type, canonical
-digest, size, and bounded producer provenance. Consumer metadata and checkpoint
-fingerprints contain no registry names, content, paths, or NPC source ranges.
-The component-local registry fingerprint covers only the names projected to the
-consumer, while manifest provenance retains the full artifact digest. The
-normalized lane is emitted as `lanes/<lane-id>.json` by the JSON
-output module, and warnings and rejection summaries remain in their shared
-companion files.
+`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/<lane-id>.json` by the JSON output module, and warnings
+and rejection summaries remain in their shared companion files.

docs/integrations/dnd-npc-artifacts.md

@@ -109,12 +109,19 @@ steps:
       npcs:
         extract: dnd/npcs
         normalize: dnd/npcs
+      scene-descriptions:
+        extract: dnd/scene-descriptions
+        normalize: dnd/scene-descriptions
   - id: grounded-events
     references:
       npcs:
         artifact:
           step: identify-npcs
           lane: npcs
+      scene_descriptions:
+        artifact:
+          step: identify-npcs
+          lane: scene-descriptions
     artifacts:
       spells:
         extract: dnd/spells
@@ -124,13 +131,16 @@ steps:
         normalize: dnd/combat-turns
 ```
 
-The framework hands only an accepted normalized artifact across the barrier. It
-validates the canonical bytes against each consumer slot and clones the
-operation-time reference for the spell and combat consumers. Generated
+The framework hands only accepted normalized artifacts across the barrier. It
+validates the canonical bytes against each consumer slot and clones the NPC
+operation-time reference for spell and combat consumers. The accompanying
+scene-description reference is required by the combat extractor for eligibility
+only; its consumer contract is defined in the
+[D&D combat-turn artifact contract](dnd-combat-turn-artifacts.md). Generated
 provenance records the artifact kind, schema identity, media type, canonical
-digest, size, and producer step/lane/module, but not names, source
-ranges, or payload bytes. External normalized files remain supported as
-explicit references and retain their file provenance.
+digest, size, and producer step/lane/module, but not names, source ranges, or
+payload bytes. External normalized files remain supported as explicit references
+and retain their file provenance.
 
 NPC source references are registry provenance and are never accepted as spell
 or combat evidence. Current transcript units remain the only event evidence.

docs/integrations/dnd-scene-description-artifacts.md

@@ -118,3 +118,13 @@ Use `dnd/scenes` to form accepted scene chunks, then select
 [complete D&D configuration](../../examples/dnd-complete.config.yml) includes
 this lane alongside the other D&D artifacts. Selectable keys and default
 validator chains are defined in [Configuration](../config.md).
+
+## Downstream combat use
+
+The combat-turn extractor consumes this approved artifact as required
+eligibility control context through an explicit ordered reference binding. It
+uses only an exact chunk ID and source-range match with `kind: combat` to permit
+combat extraction; titles, summaries, and scene references do not become combat
+prompt material or evidence. The complete downstream behavior, including empty
+results and warnings for unavailable coverage, is defined in the
+[D&D combat-turn artifact contract](dnd-combat-turn-artifacts.md).