notarius/docs/roadmap/scene-aware-combat-extraction.md

Scene-Aware Combat Extraction

Status

Implemented. This document preserves the feature contract and rationale; the current configuration, operational, integration, and internal behavior is maintained in their canonical documentation.

Purpose

Use an accepted D&D scene-description artifact as the eligibility boundary for combat-turn extraction. The combat LLM should run only for a chunk whose exact scene record has kind: combat; every other chunk should be ignored by the combat extractor. This work should connect the existing scene-description lane, ordered generated-reference handoff, and combat-turn lane without expanding the minimal combat-turn artifact contract or introducing D&D policy into generic pipeline code.

Target Workflow

The complete D&D pipeline has two ordered steps:

1. The first step extracts and normalizes NPCs and scene descriptions for the accepted scene chunks.
2. At the step barrier, the accepted NPC and scene-description artifacts become generated references.
3. The second step supplies the NPC artifact to its existing consumers and the scene-description artifact to combat-turn extraction.
4. For each chunk, combat-turn extraction performs its existing LLM extraction only for an exact combat classification. Every other chunk produces a deterministic empty artifact without an LLM call.

The scene-description dependency must remain explicit in pipeline configuration. The combat extractor must not discover another lane implicitly, read output files directly, inspect chunker-private state, or require generic chunk materialization to interpret D&D scene classifications.

Scene-Description Reference Contract

The combat extractor should declare a required structured reference slot named scene_descriptions. The slot accepts one approved dnd/scene-description-list artifact using the existing durable scene description schema.

The reference may be supplied as:

• a generated artifact from an earlier ordered step; or
• an external artifact through the existing reference-materialization boundary.

External artifacts must be decoded and validated before source parsing or LLM execution. Generated artifacts must cross the existing typed step-handoff boundary and be validated before use. A bound artifact that is malformed, incompatible, or internally inconsistent is an error; it must not be treated as though the slot were unbound.

Pipeline resolution must reject combat extraction when this slot is not bound. In an ordered same-run workflow, failure of the configured scene-description producer to yield an accepted normalized artifact must fail the run before the combat consumer step starts, consistent with existing required generated reference semantics.

The prepared reference view should be immutable and safe for concurrent extract jobs. Its metadata and checkpoint identity should be content-safe and must not expose scene titles, summaries, paths, or source text.

Chunk Matching And Gating Policy

A scene record authorizes combat extraction for the current chunk only when all of the following are true:

• the scene ID exactly equals the current accepted chunk ID;
• the scene source ID exactly equals the chunk source ID;
• the scene start and end unit IDs exactly equal the chunk's inclusive source range; and
• the approved artifact contains exactly one such record.

The normalized scene-description contract already rejects conflicting IDs and ranges. The combat extractor must nevertheless require the exact match above at its own decision boundary rather than relying on array position, range overlap, title, summary, or inferred chronology.

An exact match with kind: combat performs the existing combat-turn LLM extraction. An exact match with narrative, recap, or meta returns a typed dnd/combat-turn-list containing an empty combat_turns array without making an LLM call.

A valid artifact with no exact match, incomplete coverage, or a chunk identity or range mismatch also returns the deterministic empty artifact. It must not infer combat eligibility from an overlapping or adjacent scene. Emit a bounded, content-safe warning for missing or mismatched coverage so operators can distinguish an intentional non-combat classification from an unavailable exact classification. The warning must not include scene prose or transcript text.

This policy relies on the scene contract's mixed-scene precedence: any chunk in which combat is a substantive central activity is classified as combat. Scene-aware gating must not add a second classification policy.

Extraction, Validation, And Provenance

The deterministic empty result follows the same typed extractor and validator boundaries as an LLM-produced empty result. It is not a rejection, does not consume retry budget, and continues through merge and normalization normally. The durable combat-turn schema remains unchanged.

Existing combat extraction behavior—including prompt assets, NPC grounding, candidate mapping, validators, retries, warnings, and normalization—remains unchanged for chunks classified as combat. The scene-description artifact is control context only:

• it must not be added to the combat prompt;
• its title or summary must not become combat evidence;
• its source references must not be copied into combat turns; and
• it must not create, repair, or classify a combat turn.

Generated-reference provenance and dependency fingerprints should cover the scene artifact through the existing ordered-handoff machinery. External references should contribute their existing materialization provenance plus a component-local semantic fingerprint sufficient to invalidate combat extract checkpoints when a classification or chunk identity changes. Checkpoint reuse must never preserve a skipped result after the effective scene classification changes.

Run manifests may report bounded module metadata such as the number of approved scene records. They must not contain scene prose or duplicate the referenced artifact payload.

Configuration And Documentation

The maintained complete D&D example should bind the normalized scene-descriptions lane from the first step to the scene_descriptions slot in the second step. The minimal example should remain unchanged.

Current-behavior documentation is maintained in these canonical locations:

• Configuration owns the new selectable reference slot and binding example.
• Operations owns the ordered scene-aware workflow.
• The combat-turn integration contract owns externally observable extraction, empty-result, and provenance behavior.
• Internal pipeline and module documentation own preparation, handoff, matching, and checkpoint mechanics.
• future.md should remove the completed scene-aware combat item.

Quality Expectations

Tests should protect behavior and architectural boundaries rather than internal helper shape. Coverage should demonstrate:

• exact non-combat matches produce accepted empty combat artifacts without an LLM call;
• exact combat matches retain the existing LLM path;
• an unbound required reference is rejected during pipeline resolution;
• missing and mismatched chunk coverage produces an accepted empty combat artifact without an LLM call and emits a bounded warning;
• malformed external and generated artifacts fail at the appropriate preparation or handoff boundary;
• retries are neither consumed nor attempted for deterministic skips;
• scene artifact changes invalidate relevant checkpoint reuse;
• no scene prose is exposed through combat prompts, warnings, metadata, or manifests; and
• the complete maintained configuration resolves and materializes the intended ordered dependency.

Model-output fixtures should remain deterministic test doubles. This feature does not require live-provider tests or assertions over probabilistic model quality.

Non-Goals

This scope does not:

• change the durable scene-description or combat-turn schemas;
• add scene fields to combat-turn artifacts;
• annotate generic chunks with D&D classifications;
• make the combat lane depend implicitly on the scene-description lane;
• skip spell, NPC, NPC-interaction, or scene-description extraction;
• infer combat from scene titles, summaries, overlap, or campaign references;
• introduce arbitrary DAG scheduling or concurrent cross-step execution;
• add prior-run artifact discovery or new reference syntax; or
• add an LLM-backed validator, repair pass, or generic deduplication stage.

Completion Criteria

The scope is complete when an explicitly configured ordered D&D pipeline can hand an approved scene-description artifact to combat extraction, exact combat scene matches are the only chunks that invoke the combat LLM, every other chunk produces a deterministic empty result, provenance and checkpoint identity remain correct, the complete example demonstrates the workflow, and the canonical current-behavior documentation reflects the implemented contract.