Document NPC semantic normalization

docs/internal/llm.md

@@ -154,6 +154,22 @@ identity, campaign-reference, and instruction messages are ephemeral cache
 boundaries; the transcript is last and has no cache control. Compatible shared
 messages remain canonical shared assets rather than copied package text.
 
+### D&D NPC Normalization Prompt Ordering And Cache Boundaries
+
+NPC normalization has a distinct prompt and response-schema identity from NPC
+extraction. Its stable message tiers are the common D&D system and identity
+assets, followed by package-owned task and normalization instructions. Cache
+boundaries follow the shared identity tier and the package instructions. The
+variable tail contains the private candidate-name-and-range input and a
+windowed transcript input whose cited units provide local context; neither has
+a cache boundary because it changes with the document.
+
+This prompt intentionally omits extraction-evidence and campaign-reference
+assets: it reconciles existing records rather than extracting events or adding
+evidence. Its package-owned manifest and schema identity are fingerprinted
+separately, so a normalization prompt or schema change cannot reuse a prior
+normalization checkpoint.
+
 Shared wording belongs in the canonical assets under
 `internal/modules/dnd/shared`; extraction packages reference those assets in
 their manifests instead of copying similar text into package-local files.

docs/internal/modules.md

@@ -395,11 +395,27 @@ omission-summary warning when truncated.
 
 ### `internal/modules/dnd/normalize/npcs`
 
-The NPC normalizer performs deterministic identity-aware consolidation in
-merged input order. It consolidates only equal canonical-name comparison keys,
-retains the first display record, and unions exact source references. It exposes
-the identity policy as its local checkpoint fingerprint and emits bounded
-normalization warnings.
+The NPC normalizer deterministically trims display names, recomputes IDs,
+canonicalizes evidence, and consolidates equal comparison keys before semantic
+work. Records are eligible for the document-level identity call only when they
+have a non-empty comparison key and wholly valid current-document references.
+It sends private candidate names and source ranges plus coalesced, cited
+transcript windows to its own prompt; stable NPC IDs and the durable artifact
+shape are not prompt inputs.
+
+The private structured response proposes groups of supplied names and a
+canonical supplied name. Deterministic comparison-key resolution validates each
+group, discards unsafe or overlapping groups, and independently applies safe
+ones. Application preserves earliest record order, unions canonical evidence,
+and derives the final canonical ID. Invalid structured output and discarded
+groups request framework retry with a safe fallback; bounded diagnostics become
+durable only on final fallback exhaustion.
+
+The normalizer records prompt and response-schema identities and digests,
+identity and normalization policies, and semantic-context policy and radius as
+manifest metadata. Its local checkpoint fingerprints cover the prompt, response
+schema, identity policy, normalization policy, and semantic-context policy so a
+meaningful behavior change invalidates prior normalize reuse.
 
 ## Merger And Normalizer
 

docs/internal/overview.md

@@ -119,7 +119,7 @@ Configuration. The implemented module packages are:
 | `internal/modules/generic/merge/appendorder` | Combines accepted extraction results in chunk order. |
 | `internal/modules/generic/normalize/noop` | Preserves accepted merged output. |
 | `internal/modules/dnd/normalize/spells` | Canonicalizes catalog-backed spell names and exact source references, conservatively collapses duplicate casts, and reports deterministic warnings and independently scoped catalog checkpoint identity. |
-| `internal/modules/dnd/normalize/npcs` | Consolidates NPC records deterministically by canonical name, unions exact evidence, and reports bounded warnings. |
+| `internal/modules/dnd/normalize/npcs` | Deterministically prepares and safely applies document-level LLM-assisted NPC identity consolidation, preserving canonical evidence, order, and diagnostics. |
 | `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,

docs/internal/pipeline.md

@@ -322,9 +322,24 @@ error when attempts are exhausted. A rejection becomes a recorded
 `RejectedOutput` when attempts are exhausted. Cancellation stops retry
 processing immediately.
 
-Rejected output is a non-fatal pipeline outcome and does not advance. Warnings
-from discarded attempts are not promoted. Configuration owns retry counts and
-validator overrides; see [Module Bindings](../config.md#module-bindings).
+Structured-completion adapters classify malformed or undecodable provider
+output with the provider-neutral `contracts.ErrInvalidStructuredOutput` error.
+A typed normalizer may turn that condition, or another unsafe proposal, into a
+normalize retry directive with a deterministic safe candidate, stable
+diagnostic, and fallback warnings. The directive consumes the same configured
+normalize retry budget: `retries` permits that many additional attempts after
+the initial attempt. It neither creates a normalizer-local retry loop nor
+records an accepted checkpoint for the discarded attempt.
+
+When a later normalize attempt succeeds, its candidate alone proceeds through
+the usual validation and checkpoint path. When the final attempt still returns
+a directive, the runner validates its supplied safe fallback through that same
+normalizer validator chain before accepting or rejecting it. Ordinary
+attempt-local warnings and fallback warnings remain unpromoted while another
+attempt is available; only final exhaustion promotes the supplied fallback
+warnings. Rejected output is a non-fatal pipeline outcome and does not advance.
+Configuration owns retry counts and validator overrides; see
+[Module Bindings](../config.md#module-bindings).
 
 ## Checkpoint And Debug Hooks
 
@@ -389,7 +404,9 @@ boundaries. Every executed chunk, extract, merge, and normalize attempt writes
 one terminal envelope for acceptance, validator rejection, module or validator
 error, or applicable candidate or final serialization error. The envelope
 contains its attempt-local warnings, any available candidate and rejection,
-and terminal error text; failures before a candidate exists omit that payload.
+and terminal error text; normalize retry directives retain their attempt-local
+candidate and diagnostic, while only the final safe fallback reaches validation.
+Failures before a candidate exists omit that payload.
 Only LLM calls made by the module operation belong to the module attempt.
 Validator calls retain independent scopes under `validate/` and are not
 duplicated into the module envelope. A failed terminal-envelope write is a