Share D&D cited source traversal

docs/internal/modules.md

@@ -46,7 +46,7 @@ that agreement. Runtime delivery uses the corresponding stage request's
 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 helpers belong in
+declarations, prompt-input assembly, and source-unit/citation helpers belong in
 `internal/modules/dnd/shared`, which also owns bounded D&D diagnostics. The
 spell, NPC, and combat-turn extractors use ordered package-local prompt
 manifests for both rendering and prompt fingerprinting, so only the shared
@@ -359,8 +359,11 @@ against the immutable effective SRD and overlay catalog. It accepts normalized
 canonical names and aliases without rewriting the artifact; unknown names
 reject the complete result with bounded, stable index/name diagnostics. The
 source-reference validator applies generic source-reference validation to every
-cited range. The relatedness validator warns when a case-insensitive spell name
-is absent from all cited source text.
+cited range. The relatedness validator resolves all cited ranges through the
+shared document-order traversal, then warns when a case-insensitive spell name
+is absent from the cited source text. Invalid shape or cited ranges produce no
+relatedness warnings; the shape and source-reference validators own those
+defects.
 
 These validators are deterministic. Their selectable keys and production order
 are defined in
@@ -372,21 +375,24 @@ payload rules are defined in the
 
 NPC shape validation checks required strings, arrays, and source-reference
 shape. The source-reference validator checks current-document identity, unit
-existence, and range ordering; source relatedness emits at most one bounded
-warning per record when neither the canonical name nor an alias occurs near
-its cited text. Normalize identity validation checks deterministic IDs,
-canonical names, aliases, and cross-record ownership or canonical collisions.
-All are deterministic and expose the policy fingerprints used by the
-production chains.
+existence, and range ordering; source relatedness uses the shared document-order
+traversal and normalized consecutive-token matching, emitting at most one
+bounded warning per record when neither the canonical name nor an alias occurs
+near its cited text. Invalid shape or cited ranges produce no relatedness
+warnings. Normalize identity validation checks deterministic IDs, canonical
+names, aliases, and cross-record ownership or canonical collisions. All are
+deterministic and expose the policy fingerprints used by the production chains.
 
 ## D&D Combat Validators
 
 Combat shape validation owns required arrays, strings, nullable values, positive
 rounds, and supported enums. Combat source-reference validation defers invalid
 shape and checks source identity, unit existence, and range order. Combat
-source-relatedness defers invalid shape or ranges, combines overlapping cited
-units in document order, and emits at most one bounded advisory warning per
-turn for unrelated actor or declaration text. The normalized-invariants
+source-relatedness defers invalid shape or ranges, uses the shared traversal to
+combine overlapping cited units in document order, and emits at most one
+bounded advisory warning per turn for unrelated actors or declaration text.
+Actors use normalized consecutive-token matching; declarations retain the
+minimum four-rune token heuristic. The normalized-invariants
 validator owns display normalization, comparison-unique targets, canonical
 source-reference order, chronology, and exact duplicate identity; it defers
 shape and source-reference failures. All four validators are deterministic and