Close D&D extraction audit documentation

docs/internal/modules.md

@@ -53,7 +53,8 @@ LLM-backed extensions own their prompt definitions and response schemas under
 package-local embedded assets. Shared filesystem composition belongs in
 `internal/framework/promptfs`; reusable D&D prompt fragments, reference
 declarations, prompt-input assembly, and source-unit/citation helpers belong in
-`internal/modules/dnd/shared`, which also owns bounded D&D diagnostics. The
+`internal/modules/dnd/shared`, which also owns document-aware source-reference
+ordering and canonicalization plus bounded D&D diagnostics. The
 D&D scene chunker and spell, NPC, combat-turn, NPC-interaction, and scene-description extractors use ordered
 package-local prompt manifests for both rendering and prompt fingerprinting, so
 only the shared fragments each prompt actually renders participate in either
@@ -202,7 +203,7 @@ The spell extractor prepares a structured request from one chunk, the
 chunk-scoped source input, the session, and optional D&D reference inputs. It
 decodes the model response, assigns the generic source identity to every source
 reference, canonicalizes duplicate references, orders spell casts by their
-earliest cited unit, and returns `dnd.SpellList`.
+earliest valid source-document position, and returns `dnd.SpellList`.
 
 Its private response schema admits only the structural transport envelope:
 required fields, JSON types, array and object shapes, and unknown-field
@@ -323,12 +324,13 @@ mapping, and the names-only registry projection
 participate in checkpoint identity, while generated producer identity remains
 framework provenance.
 
-The domain-owned `internal/modules/dnd/npcinteractions` package defines
+The shared D&D source-reference order defines canonical evidence ordering. The
-canonical source-reference and occurrence ordering, valid-evidence eligibility,
+domain-owned `internal/modules/dnd/npcinteractions` package defines occurrence
-and collision-safe exact identity. The interaction normalizer and normalized
+ordering, valid-evidence eligibility, and collision-safe exact identity. The
-invariants validator both consume those rules, so their production and checking
+interaction normalizer and normalized invariants validator consume those
-paths cannot drift. Normalizer and relatedness warning lists use the shared D&D
+rules, so their production and checking paths cannot drift. Normalizer and
-diagnostic cap and emit a final omission-summary warning when truncated.
+relatedness warning lists use the shared D&D diagnostic cap and emit a final
+omission-summary warning when truncated.
 
 ### `internal/modules/dnd/normalize/npcs`
 
@@ -357,9 +359,9 @@ The typed spell normalizer resolves the optional `spell_catalog` reference into
 the same immutable SRD-plus-overlay effective catalog used by spell extraction
 and catalog validation. It performs no LLM calls. For each spell cast it
 canonicalizes recognized names using the catalog's case, whitespace,
-apostrophe, and alias rules; sorts source references by source identity and
+apostrophe, and alias rules; canonicalizes source references with the shared
-unit boundaries; removes only exact reference duplicates; and emits bounded,
+document-aware order; removes only exact reference duplicates; and emits
-scoped warnings for each mutation or unresolved name.
+bounded, scoped warnings for each mutation or unresolved name.
 
 After those per-cast changes, it collapses only casts with the same canonical
 spell, case-folded and whitespace-normalized caster, and complete non-empty

docs/internal/overview.md

@@ -101,7 +101,7 @@ Configuration. The implemented module packages are:
 | `internal/modules/dnd/extract/combatturns` | Maps private structured model output to source-grounded D&D combat-turn candidates and preserves chronology and invalid candidate values for validators. |
 | `internal/modules/dnd/extract/npcinteractions` | Maps private structured model output to current-source NPC interaction candidates grounded by a required registry. |
 | `internal/modules/dnd/extract/scenedescriptions` | Maps one private scene description to the current accepted chunk's ID and exact range. |
-| `internal/modules/dnd/npcinteractions` | Owns canonical source-reference ordering, occurrence ordering, valid-evidence checks, and exact interaction identity shared by normalization and invariant validation. |
+| `internal/modules/dnd/npcinteractions` | Owns interaction occurrence ordering, valid-evidence checks, and exact interaction identity shared by normalization and invariant validation. |
 | `internal/modules/dnd/normalize/combatturns` | Canonicalizes and orders merged combat turns, applies exact NPC identity matches, and collapses only exact valid-evidence duplicates. |
 | `internal/modules/dnd/normalize/npcinteractions` | Canonicalizes required-registry names, orders interaction occurrences, and collapses only exact valid-evidence duplicates. |
 | `internal/modules/dnd/normalize/scenedescriptions` | Trims, source-orders, and removes only exactly identical scene descriptions while rejecting ID and range conflicts. |
@@ -118,8 +118,9 @@ Configuration. The implemented module packages are:
 | `internal/modules/generic/output/json` | Encodes manifests, lane payloads, warnings, rejections, and an explicitly enabled accepted chunk map as logical JSON files. |
 
 `internal/modules/dnd/shared` owns reusable D&D prompt fragments,
-reference declarations, prompt input assembly, source-unit reference helpers,
+reference declarations, prompt input assembly, document-aware source-reference
-and bounded diagnostics under `internal/modules/dnd/shared/diagnostics`.
+ordering and canonicalization, and bounded diagnostics under
+`internal/modules/dnd/shared/diagnostics`.
 The shared NPC grounding fragment is mounted for D&D prompts and is owned by
 this package. Domain-neutral prompt filesystem composition lives in
 `internal/framework/promptfs`.