notarius/docs/roadmap/dnd-combat-turn-extraction.md

D&D Combat-Turn Extraction

Status: Accepted.

Purpose

Add a production D&D combat-turn pipeline that converts session transcripts into an ordered, evidence-backed account of combat activity. This is the next recommended increment because spell and NPC extraction now provide the two most important grounding vocabularies, while combat turns are the next useful artifact explicitly identified by the sequential-pipeline strategy.

The feature uses the existing fixed pipeline and scene chunks for a more structurally demanding artifact without requiring automatic workflow composition, richer scene routing, or generic semantic deduplication.

Target Outcome

An operator can:

1. run the NPC pipeline against a transcript;
2. run a combat-turn pipeline over the same transcript, explicitly binding the normalized NPC artifact as a reference;
3. receive an ordered JSON list of validated combat turns and interrupting combat events; and
4. trace every reported declaration and immediate resolution back to the transcript units that support it.

The runs remain independent CLI invocations. Notarius does not discover prior outputs, schedule dependent pipelines, or reconcile spell and combat artifacts automatically.

Combat-Turn Artifact

The new typed artifact represents an ordered list of combat-turn records. Each record contains:

• the canonical in-world actor;
• a turn kind distinguishing an ordinary turn from a reaction, legendary action, lair action, or other interrupting combat event;
• the combat round as a positive integer when it is explicit or unambiguous, and null otherwise;
• one or more ordered actions;
• a concise turn-level summary; and
• one or more transcript source references that collectively support every reported field.

Each action contains a conservative category, a concise declaration, zero or more targets, and its immediate observed resolution. Resolution is null when the cited passage establishes the declaration but no immediate resolution. Categories cover attacks, spells, movement, items, ability checks, saving throws, condition or state changes, and an other fallback without requiring the transcript to use formal rules terminology.

Reactions and similar out-of-turn events appear at the point where they occur in transcript chronology rather than being moved to the reacting creature's later turn. Output order is derived from cited source position; numeric source unit IDs are identifiers, not chronology.

Inclusion And Evidence Policy

Include a record when the transcript establishes that an in-world participant takes a combat turn or performs a discrete interrupting combat event. Report only declarations and their immediate resolutions, including directly associated rolls, damage, healing, movement, conditions, or target outcomes. For every detail reported, cite all supporting transcript units.

Exclude:

• initiative setup that contains no turn or combat event;
• tactical planning, table talk, rules lookup, and hypothetical actions;
• corrected or abandoned declarations that never become an attempted action, except where the correction is necessary to describe the final declaration;
• recap of combat that occurred outside the current source passage; and
• downstream consequences that occur on later turns or elsewhere in the scene.

Do not infer a round number, action-economy classification, target, roll, amount, condition, or outcome merely from D&D rules knowledge. Preserve the session as played, and attribute nonstandard rulings to the GM or table when that detail is relevant to the immediate resolution.

Identity And Reference Grounding

The extractor uses the existing D&D transcript, player, party, and glossary prompt inputs. It also accepts the normalized NPC artifact through an optional structured npcs reference slot with the same validation, size, provenance, content-safety, and semantic-checkpoint rules used by spell extraction.

The NPC registry helps select canonical actors and targets and recognize aliases. It does not establish that combat occurred and never becomes source evidence. Unmatched actors and targets remain permitted because a session may introduce combatants that were omitted from an earlier NPC run.

The deterministic normalizer also accepts the registry. Exact canonical-name or alias matches are rewritten to the registry's canonical display name for actors and targets; ambiguous aliases and unmatched values remain unchanged for validation and human review. Opaque player and party references continue to guide the LLM but are not parsed into a new roster contract in this scope.

Extraction, Validation, And Normalization

The extractor uses one structured LLM call per supplied chunk and returns typed combat-turn candidates. It must preserve malformed candidates for the normal validation and retry boundary rather than silently repairing unsupported content in mapping code.

The production default validator chain is deterministic and covers:

• required fields, arrays, nullable-round shape, and supported enum values;
• a required non-empty evidence collection, source identity, unit existence, and range order;
• actor and declared-action relatedness to cited transcript text, expressed as bounded warnings where deterministic substring checks are only advisory; and
• normalized identity and duplicate invariants.

Normalization is deterministic and conservative. It normalizes display whitespace, canonicalizes exact NPC identity matches, orders and deduplicates exact source references, and collapses only exact duplicate records with the same normalized actor, turn kind, round value, and complete valid evidence set. The first record is retained without synthesizing or merging prose. Every mutation or collapse emits a scoped warning.

An LLM-backed validator and semantic reconciliation normalizer are outside the production chain. Human evaluation owns judgments such as whether the model grouped a long turn correctly or omitted a subtle reaction.

Scene Strategy

The combat extractor processes every chunk delivered by the configured chunker. Existing D&D scene annotations remain useful context, but a primary_mode value does not suppress an LLM call. Avoiding a call based on an imperfect non-combat classification could silently lose the very turns this artifact is intended to recover.

Scene-classification and routing improvements remain separate future work. The combat pipeline stays compatible with generic chunks that carry no D&D annotation.

Provenance And Checkpoints

The extractor, normalizer, and validators report stable semantic identities through the existing manifest and prepared-component fingerprint contracts. Prompt, private response schema, artifact policy, normalization policy, and a bound NPC registry's semantic digest must invalidate incompatible checkpoints.

Metadata and fingerprints contain identities, counts, and digests only. They must not contain transcript text, combat records, NPC names, reference paths, or raw reference content. Preparation failures remain bounded and content-safe and occur before checkpoint handlers or pipeline execution are constructed.

Evaluation

Use human-reviewed development runs rather than exact model-output goldens. Evaluate at least the existing transcripts used for spell and NPC development, with separate attention to:

• combat-turn detection precision and recall;
• actor and target identity;
• turn boundaries and chronological order;
• reactions and other interrupting events;
• declaration and immediate-resolution fidelity;
• round-number restraint;
• completeness and precision of evidence; and
• duplicate behavior at chunk or scene boundaries.

Frontier and inexpensive development models may differ substantially in semantic quality. Deterministic tests should protect structure, provenance, identity, ordering, normalization, and orchestration rather than require exact combat prose.

Out Of Scope

• Initiative trackers, current hit points, complete encounter-state replay, or rules-engine validation.
• Automatic comparison or reconciliation with spell artifacts.
• NPC discovery, campaign-wide entity persistence, or deterministic PC-roster parsing.
• LLM-backed validation or generic LLM-assisted deduplication.
• Automatic pipeline scheduling, prior-output discovery, or DAG execution.
• Scene-classification changes or skipping provider calls for non-combat chunks.
• Narrative summaries outside the immediate combat-turn scope.

Acceptance Criteria

• A selectable D&D combat lane produces a typed, durable JSON artifact with the turn, action, chronology, and evidence semantics above.
• The default deterministic validator chain rejects malformed or invalidly sourced records and emits bounded advisory relatedness warnings.
• Deterministic normalization canonicalizes exact NPC identities and collapses only safely identical combat records while preserving chronology and evidence.
• A normalized NPC artifact can be bound explicitly to both extraction and normalization without becoming combat evidence.
• Semantic contracts and structured references participate in checkpoint identity without leaking application content.
• Maintained configuration and operational examples demonstrate independent NPC and combat invocations over the same transcript.
• Human review on representative sessions demonstrates useful turn extraction without requiring scene-based call suppression or semantic reconciliation.