From 84a2854b5e3f0f8272411bb3b73c06ba4f5332ee Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Fri, 24 Jul 2026 14:48:13 +0000 Subject: [PATCH] Close D&D extraction audit documentation --- docs/internal/modules.md | 24 +++++++++++++----------- docs/internal/overview.md | 7 ++++--- 2 files changed, 17 insertions(+), 14 deletions(-) diff --git a/docs/internal/modules.md b/docs/internal/modules.md index 76bf209..39d99a0 100644 --- a/docs/internal/modules.md +++ b/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 -canonical source-reference and occurrence ordering, valid-evidence eligibility, -and collision-safe exact identity. The interaction normalizer and normalized -invariants validator both consume those rules, so their production and checking -paths cannot drift. Normalizer and relatedness warning lists use the shared D&D -diagnostic cap and emit a final omission-summary warning when truncated. +The shared D&D source-reference order defines canonical evidence ordering. The +domain-owned `internal/modules/dnd/npcinteractions` package defines occurrence +ordering, valid-evidence eligibility, and collision-safe exact identity. The +interaction normalizer and normalized invariants validator consume those +rules, so their production and checking paths cannot drift. Normalizer and +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 -unit boundaries; removes only exact reference duplicates; and emits bounded, -scoped warnings for each mutation or unresolved name. +apostrophe, and alias rules; canonicalizes source references with the shared +document-aware order; removes only exact reference duplicates; and emits +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 diff --git a/docs/internal/overview.md b/docs/internal/overview.md index d80dd4c..e312c3a 100644 --- a/docs/internal/overview.md +++ b/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, -and bounded diagnostics under `internal/modules/dnd/shared/diagnostics`. +reference declarations, prompt input assembly, document-aware source-reference +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`.