Share the D&D NPC registry and prompt grounding

docs/internal/llm.md

@@ -107,10 +107,12 @@ The spell extractor's package-owned prompt declares a required
 `application/json` `spell_catalog` input and an optional `application/json`
 `npcs` input. The extractor generates the catalog input from its prepared
 effective catalog as `{"spell_names":[...]}` using sorted canonical names only.
-When an NPC registry is bound, it strictly decodes and identity-validates one
-durable artifact, re-encodes canonical JSON, and generates a semantic digest
-over those bytes. The unbound input is exactly `{"npcs":[]}`. Input digests
-cover the generated bytes; manifests record catalog identity and optional NPC
+The shared D&D prompt assets include a generic NPC grounding fragment directly
+after the campaign reference message. When an NPC registry is bound, the
+domain registry boundary strictly decodes and identity-validates one durable
+artifact, re-encodes canonical JSON, and generates a semantic digest over
+those bytes. The unbound input is exactly `{"npcs":[]}`. Input digests cover
+the generated bytes; manifests record catalog identity and optional NPC
 registry digest/count rather than names, aliases, overlay bytes, registry
 paths, or source metadata.
 

docs/internal/modules.md

@@ -47,7 +47,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 helpers belong in
-`internal/modules/dnd/shared`. Stage contracts expose only Notarius structured-
+`internal/modules/dnd/shared`, which also owns bounded D&D diagnostics. Stage
+contracts expose only Notarius structured-
 completion types, not Scriptorium public types.
 
 Reference material may inform a module or prompt but must not become source
@@ -82,14 +83,18 @@ semantic digest; overlay content remains contextual reference material rather
 than source evidence. Its external JSON contract is defined in the
 [spell-catalog overlay contract](../integrations/dnd-spell-catalog-overlays.md).
 
-### `internal/modules/dnd/npcs/identity` and `internal/modules/dnd/codec/npcs`
+### `internal/modules/dnd/npcs/identity`, `internal/modules/dnd/npcs/registry`, and `internal/modules/dnd/codec/npcs`
 
 The NPC identity package owns Unicode comparison keys, deterministic
 `npc:sha256:` IDs, display normalization, and whole-registry collision issues.
-The NPC codec owns the strict durable `dnd/npc-list` JSON boundary and exposes
-candidate versus approved encode/decode operations. NPC source references are
-durable provenance and may later be consumed by another pipeline as registry
-context without being treated as evidence for that pipeline.
+The registry package resolves one optional normalized artifact through the
+strict codec, validates whole-registry identity, canonicalizes its JSON, and
+provides immutable records, prompt input, semantic digest, count, and exact
+canonical-name/alias lookup. It owns the `npcs` slot and its bounded,
+content-safe preparation failures. NPC source references are durable
+provenance and are not treated as evidence for a consuming pipeline. The NPC
+codec owns the strict durable `dnd/npc-list` JSON boundary and exposes
+candidate versus approved encode/decode operations.
 
 ## Input Adapter
 
@@ -196,13 +201,13 @@ stages, using the codec only for checkpoint, debug, and output boundaries.
 Shared D&D helpers keep prompt input
 names and source-unit reference conversion consistent with the scene chunker.
 
-The extractor also declares the optional `npcs` registry slot. Preparation
-requires one approved `application/json` item no larger than 1 MiB, validates
-identity without relating registry source references to the current transcript,
-and supplies canonical JSON to a spell-owned prompt message. A bound registry
-adds only `npc_registry_digest` and `npc_count` to manifest metadata and an
-`npc_registry` checkpoint fingerprint. The unbound prompt input is exactly
-`{"npcs":[]}` and has no registry provenance or fingerprint.
+The extractor also declares the optional `npcs` registry slot and consumes the
+prepared immutable registry boundary from `internal/modules/dnd/npcs/registry`.
+A bound registry adds only `npc_registry_digest` and `npc_count` to manifest
+metadata and an `npc_registry` checkpoint fingerprint. The unbound prompt
+input is exactly `{"npcs":[]}` and has no registry provenance or fingerprint.
+The shared NPC grounding fragment is placed immediately after the common
+campaign reference message and is included in the spell prompt fingerprint.
 
 The durable payload and manifest metadata shapes are defined in the
 [D&D spell artifact contract](../integrations/dnd-spell-artifacts.md).
@@ -212,7 +217,7 @@ The durable payload and manifest metadata shapes are defined in the
 The NPC extractor maps private model output to the canonical `dnd.NPCList`,
 assigns source identity and deterministic NPC IDs, and preserves source
 references for deterministic validation. It uses the shared campaign
-references only for disambiguation and does not consume the spell-owned NPC
+references only for disambiguation and does not consume the optional NPC
 registry slot. Its prompt and private response schema are package-owned.
 
 ### `internal/modules/dnd/normalize/npcs`

docs/internal/overview.md

@@ -89,6 +89,7 @@ Configuration. The implemented module packages are:
 | `internal/modules/dnd/codec/npcs` | Strictly decodes and stably encodes the durable D&D NPC-list representation. |
 | `internal/modules/dnd/extract/spells` | Maps private structured model output to canonical source-grounded D&D spell lists. |
 | `internal/modules/dnd/extract/npcs` | Maps private structured model output to canonical source-grounded D&D NPC lists. |
+| `internal/modules/dnd/npcs/registry` | Resolves validated normalized NPC references into immutable grounding data and exact identity lookup. |
 | `internal/modules/dnd/npcs/identity` | Owns Unicode-aware NPC identity, ID derivation, and registry collision validation. |
 | `internal/modules/dnd/spells/catalog` | Embeds and validates the versioned D&D 5e 2014 SRD catalog, composes optional overlays, and provides immutable effective lookup. |
 | `internal/modules/generic/merge/appendorder` | Combines accepted extraction results in chunk order. |
@@ -98,17 +99,19 @@ Configuration. The implemented module packages are:
 | `internal/modules/generic/output/json` | Encodes manifests, lane payloads, warnings, and rejections as logical JSON files. |
 
 `internal/modules/dnd/shared` owns reusable D&D prompt fragments,
-reference declarations, prompt input assembly, and source-unit reference
-helpers. Domain-neutral prompt filesystem composition lives in
+reference declarations, prompt input assembly, source-unit reference helpers,
+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`.
 
-The spell extractor owns its optional `npcs` registry boundary. Preparation
-strictly decodes and identity-validates one normalized JSON artifact, emits
-canonical registry JSON to the spell prompt, and records only its semantic
-digest and count in prepared metadata. The raw reference remains independently
-tracked by pipeline provenance. An absent registry is represented only by the
-empty prompt value `{"npcs":[]}`; the shared D&D reference fragment is not
-changed.
+The `dnd/npcs/registry` package owns the optional `npcs` registry boundary.
+Preparation strictly decodes and identity-validates one normalized JSON
+artifact, emits canonical registry JSON to the spell prompt, and records only
+its semantic digest and count in prepared metadata. The raw reference remains
+independently tracked by pipeline provenance. An absent registry is represented
+only by the empty prompt value `{"npcs":[]}`. Spell extraction consumes this
+shared registry boundary without changing its public module contract.
 
 Generic validators under `internal/modules/generic/validate` provide
 unconditional test decisions, JSON syntax validation, and JSON Schema