Finalize semantic reconciliation documentation

docs/internal/dnd.md

@@ -84,14 +84,15 @@ replace it with a complete profile of the same ID from the configured PromptKit
 source. Deployment profile selection is documented in
 [Configuration](../config.md#promptkit-profiles).
 
-The transcript assets have distinct consumers. Scene chunking consumes the
-complete-session `common-dnd-transcript-full.md`; extraction prompts consume
-the current-chunk `common-dnd-transcript-chunk.md`; and NPC, location, and item
-normalization consume `common-dnd-transcript-windows.md` alongside their
-candidate collections. Player, party, glossary, and compatible campaign
-references provide disambiguating context only when declared by the active
-prompt; they never establish evidence. Reference material is canonically
-ordered before rendering so equivalent inputs remain stable.
+The D&D transcript assets have distinct consumers. Scene chunking consumes the
+complete-session `common-dnd-transcript-full.md`, while extraction prompts
+consume the current-chunk `common-dnd-transcript-chunk.md`. NPC, location, and
+item normalization instead mount the generic semantic-reconciliation
+candidate and transcript-window presentation assets. Player, party, glossary,
+and compatible campaign references provide disambiguating context only when
+declared by the active prompt; they never establish evidence. Reference
+material is canonically ordered before rendering so equivalent inputs remain
+stable.
 
 Extraction prompts render the common system and identity messages first, then
 cached campaign references and the cached chunk transcript. Evidence policy and
@@ -101,10 +102,11 @@ reusable extraction prefix identical while preserving the lane-specific suffix.
 
 Scene chunking intentionally uses a different order: system, cached campaign
 references, uncached module instructions, then the final ephemeral full
-transcript. Entity normalization also has its own order: system, uncached
-module instructions, ephemeral reconciliation policy, uncached candidates, and
-final ephemeral transcript windows. These orders and cache controls are prompt
-behavior; change them only through the owning manifest and prompt declaration.
+transcript. Entity normalization also has its own order: D&D system, mandatory
+generic protocol, ephemeral domain semantic instructions, generic candidate
+presentation, and final ephemeral generic transcript windows. These orders and
+cache controls are prompt behavior; change them only through the owning
+manifest and prompt declaration.
 
 ## Evidence, Candidates, And Normalization
 
@@ -134,12 +136,46 @@ canonicalize display values and evidence, use source-document order for stable
 output, and issue bounded warnings for changes or collapsed duplicates. NPC,
 item, and location registry normalizers are intentional exceptions: each first
 produces a deterministic candidate set, then may use a bounded structured-LLM
-proposal to reconcile identity groups. The proposal selects supplied
-descriptors—names with their candidate source references—not durable IDs.
-Request-local candidate keys may support resolution internally, but are never
-included in model input or output. Colliding descriptors are ineligible, and
-invalid or unusable proposals retain the deterministic result with retry or
-fallback diagnostics; the model does not directly replace durable records.
+proposal to reconcile identity groups.
+
+## Semantic Registry Reconciliation
+
+The three registry normalizers instantiate the domain-neutral
+`internal/framework/semanticreconcile` engine with default bounds. Each
+eligible candidate receives a contiguous, one-based `candidate_id` for that
+request. The model sees that handle, the candidate label and source-free
+evidence ranges, plus bounded transcript windows; it returns only duplicate
+groups of supplied handles and one supplied canonical handle per group. It
+never returns names, evidence, durable IDs, or replacement records. Identical
+labels and evidence remain independently selectable because their handles are
+distinct.
+
+The generic core owns the mandatory handle protocol, candidate and transcript
+presentation, the private response schema, source-reference validation,
+candidate and combined-material limits, structured completion, proposal
+assessment, stable group ordering, and typed plan-application mechanics. The
+D&D prompt contributes its system message and registry-specific semantic
+instructions. The generic registrar registers the shared prompt and schema;
+the D&D registrar registers each consuming prompt and the fallback profile.
+
+Fewer than two eligible candidates skips the LLM without a semantic warning.
+An exceeded bound also skips the call and preserves the deterministic
+preprocessed registry, adding the registry's bounded fallback warning. Invalid
+structured output or discarded proposal groups use the normalizer's existing
+retry contract; retry exhaustion preserves the safe deterministic or
+partially applied result and emits its bounded fallback warning. Provider,
+transport, cancellation, and context-material failures remain execution
+errors.
+
+Application remains typed and registry-owned. All three policies select the
+canonical member's normalized display name, union member evidence in source
+order, preserve ungrouped records, and derive durable identity only after
+consolidation. NPC IDs derive from the final name. Item IDs also derive from
+the final name, and a typed guard prevents currency aliases from crossing
+denominations or mixing currency with non-currency records. Location IDs
+derive from the final name and final evidence, preserving same-name,
+parent/child, and distinct physical-place identities. Registry warning scopes,
+reason codes, and postconditions remain outside the generic core.
 
 ## Generated References And Grounding