Document D&D scene description artifacts

docs/internal/modules.md

@@ -17,16 +17,16 @@ validator registry. Package-family registrars compose those leaf registrations
 into the production catalog and own family-level policy such as default
 validator chains and prompt asset collection.
 
-Production input, chunk, output, and D&D spell-, combat-, and interaction-extract packages
+Production input, chunk, output, and D&D spell-, NPC-, combat-, interaction-, and scene-description-extract packages
 register strict option decoders and run-local builders. Preparation decodes their options into
 implementation-owned values and injects dependencies plus the materialized
 reference set for the selected target. Each builder receives an isolated clone
-of that set; input and output builders receive no references. The spell,
-combat, and interaction extractors are typed over the canonical D&D model. D&D validators, merge,
+of that set; input and output builders receive no references. The spell, NPC,
+combat, interaction, and scene-description extractors are typed over the canonical D&D model. D&D validators, merge,
 and normalize use typed variants; JSON representation validators use serialized
 requests; and unconditional validators expose separate chunk and typed
 variants. The D&D production registrar registers the canonical typed spell,
-NPC, combat, and interaction implementations, including their kind-specific merge and
+NPC, combat, interaction, and scene-description implementations, including their kind-specific merge and
 normalize behavior.
 
 For D&D artifact defaults, generic JSON syntax validation runs first. Rejecting
@@ -54,7 +54,7 @@ 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
-D&D scene chunker and spell, NPC, combat-turn, and NPC-interaction extractors use ordered
+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
 operation. Extraction prompts place stable shared and lane-specific context
@@ -128,6 +128,12 @@ It is registered by the production D&D family registrar for the selectable
 interaction lane. Its external contract is documented in the
 [D&D NPC interaction artifact contract](../integrations/dnd-npc-interaction-artifacts.md).
 
+The `internal/modules/dnd/codec/scenedescriptions` package owns the durable
+`dnd/scene-description-list` schema and candidate versus approved JSON boundary.
+It is registered by the production D&D family registrar. Its external contract
+is documented in the
+[D&D scene-description artifact contract](../integrations/dnd-scene-description-artifacts.md).
+
 ## Input Adapter
 
 ### `internal/modules/seriatim/input/transcript`
@@ -268,6 +274,18 @@ integer source-unit candidates unchanged. Required semantic content, non-empty
 evidence, and valid source ranges are rejected by the deterministic shape and
 source-reference validators.
 
+### `internal/modules/dnd/extract/scenedescriptions`
+
+The scene-description extractor makes one structured completion for each
+accepted chunk and maps its private `kind`, `title`, and `summary` response to
+one `dnd.SceneDescription`. It assigns the current chunk ID and exact range,
+preserves kind without repair, and trims only title and summary whitespace.
+Optional players, party, and glossary references can disambiguate prompt terms
+but do not supply evidence. The package owns its private schema, prompt assets,
+and mapping fingerprint; deterministic validators own the durable semantic
+checks. The durable contract is defined in the
+[D&D scene-description artifact contract](../integrations/dnd-scene-description-artifacts.md).
+
 ### `internal/modules/dnd/extract/combatturns`
 
 The combat extractor prepares one structured request per supplied chunk using
@@ -382,6 +400,15 @@ merge, or summarize distinct occurrences. Its metadata and fingerprints expose
 the normalization and NPC identity policies; generated registry identity stays
 in framework provenance and checkpoint dependencies.
 
+### `internal/modules/dnd/normalize/scenedescriptions`
+
+The scene-description normalizer has no options or references. It validates
+each source range against the source document, trims title and summary
+whitespace, orders records by source position then ID, removes only exactly
+identical records, and rejects conflicting reused IDs or ranges. Its policy
+fingerprint identifies this deterministic behavior; the matching invariant
+validator checks the normalized result in the production chain.
+
 ## Output Encoder
 
 ### `internal/modules/generic/output/json`
@@ -484,6 +511,18 @@ order, chronology, and exact duplicate identity. The production chains run
 shape, registry, and source-reference checks before JSON Schema validation;
 relatedness remains warning-only and last.
 
+## D&D Scene Description Validators
+
+Scene-description shape validation owns the non-empty list, trimmed ID and
+prose, closed kind, and basic source-reference shape. Extract-stage source
+validation additionally requires the one record to attach exactly to the
+current accepted chunk; later source validation checks source membership.
+Relatedness checks the title and summary independently against only their cited
+transcript range and emits bounded advisory warnings. The normalized-invariants
+validator owns ordering, exact duplicate elimination, and conflicting ID or
+range detection. The production chains run shape and source-reference checks
+before JSON Schema validation; the warning-only relatedness check is last.
+
 ## Production Registration
 
 Production composition occurs through family registrars. The CLI allocates one
@@ -492,7 +531,7 @@ complete framework registry set and one LLM asset registry. It invokes
 `internal/modules/seriatim/register`, and `internal/modules/dnd/register` in
 that order, then exposes the matching catalog for resolution. The generic and
 Seriatim registrars own their production leaf registrations. The D&D registrar
-owns D&D leaf registrations, typed spell, NPC, combat, and interaction default-validator
+owns D&D leaf registrations, typed spell, NPC, combat, interaction, and scene-description default-validator
 chains, typed append-order specializations, and D&D prompt/schema asset
 collection. Its registration helpers group module, validator, prompt-asset, and
 chain composition while retaining artifact-specific merge and clone behavior in