# ADR-0009: Prefer minimal evidence-grounded extraction artifacts

**Status:** Accepted
**Date:** 2026-07-22

## Context

Notarius is intended to extract structured facts from source material. Several
early D&D artifacts grew to include descriptive prose, inferred relationships,
immediate outcomes, summaries, and other enrichment alongside the facts that
identify an event or entity. Those fields make one model call responsible for
both extraction and synthesis.

In practice, the richer contracts have produced overlapping or weakly grounded
fields and have made structurally valid, semantically coherent output harder for
cost-effective smaller models. They also increase prompt size, validation and
normalization policy, durable schema surface, downstream coupling, and the
number of claims whose provenance must be evaluated.

The application needs a consistent rule for deciding what belongs in an
extractor before redesigning the current D&D spell, NPC, and combat-turn
contracts or adding new artifact families.

## Decision

An extraction module answers one narrowly stated question and returns the
smallest durable structured artifact that usefully answers it.

Every model-produced field in an extraction artifact must:

- be necessary to answer the extractor's stated question or serve a known
  downstream consumer;
- represent a fact or bounded classification that can be supported directly by
  cited source ranges;
- remain independently meaningful without model-generated explanatory prose;
  and
- justify the additional prompt, schema, validation, normalization, and
  compatibility surface it creates.

Source references are required provenance for extracted records. Auxiliary
references may disambiguate identities or canonical names, but they do not
establish source facts and are not copied into evidence.

Extraction artifacts do not include narrative summaries, general analysis,
speculative enrichment, inferred biography or relationships, or redundant
free-text descriptions by default. When such output has a demonstrated use, it
belongs in an explicitly named extraction, classification, enrichment, or
analysis module with its own contract and evidence policy.

Occurrence-level facts are not forced into entity-level attributes. A fact
that can change between encounters, such as an NPC's role in a scene, belongs
on an occurrence artifact rather than as one scalar property of a normalized
NPC registry entry.

Deterministic mapping and normalization may assign application-owned
identifiers, canonicalize known catalog values, order and deduplicate evidence,
and collapse records under an explicit identity rule. They must not manufacture
removed descriptive fields or synthesize missing claims to satisfy an older
contract.

This is a default design rule, not a prohibition on rich artifacts. A richer
field is appropriate when its consumer, evidence semantics, and ownership are
explicit.

## Alternatives considered

- Keep rich schemas and improve prompts or use larger models. This retains
  potentially convenient prose but does not resolve overlapping field
  responsibilities, weak provenance, higher cost, or unnecessary downstream
  coupling.
- Make enrichment fields optional. This reduces rejection pressure but leaves
  ambiguous artifact semantics and inconsistent records, and many strict
  structured-output providers still require nullable placeholders.
- Keep minimal private LLM schemas while preserving rich durable artifacts.
  Deterministic code would have to invent, default, or separately derive the
  missing fields, hiding synthesis behind the extraction boundary.
- Use one broad session-analysis module. This reduces the number of lanes but
  couples unrelated facts, schemas, retries, evaluation, and downstream
  consumers into one model call.

## Consequences

Extraction prompts and response schemas become smaller, more focused, and more
suitable for lower-cost models. Artifacts carry fewer unsupported claims, and
their evidence and validation policies become easier to explain and evaluate.
Independent extractors can evolve, retry, and be consumed without requiring
unrelated enrichment.

Some descriptive convenience fields will disappear from primary artifacts.
Consumers that genuinely need them may require a separate module and explicit
pipeline step. Entity registries may no longer resolve aliases or relationships
unless a dedicated, evidence-grounded capability supplies them.

Removing durable fields is a schema compatibility change. Each affected
artifact requires an explicit version and reference policy; private prompt
changes alone are insufficient. Current-behavior integration and internal
documentation must change with implementation, while the roadmap owns the
proposed contract until then.
