Put stable D&D prompt content before transcripts

docs/internal/llm.md

@@ -102,19 +102,52 @@ The D&D scene chunker and spell, NPC, and combat-turn extractors each declare an
 ordered prompt asset manifest. The manifest lists the package-owned YAML and
 Markdown files, then the exact shared fragments rendered by that prompt; the
 same ordered list drives both filesystem mounting and the prompt fingerprint.
-The three extraction prompts share system, extraction evidence, in-world
-identity, transcript, and campaign-reference messages. Spell and combat prompts
-then render immediate resolution and the ephemeral NPC registry before their
-lane-specific material; the NPC prompt renders its task and instructions
-instead. The scene prompt uses system, transcript, and campaign-reference
-messages before its task and instructions. Identity, transcript, and
-campaign-reference messages are ephemeral in the extraction prompts; the scene
-prompt marks transcript and campaign references ephemeral, and the NPC registry
-is ephemeral where spell and combat prompts use it. Unused shared assets are
-neither mounted nor fingerprinted. Universal extraction-evidence and output
-policy lives only in the shared extraction assets; package-owned prompt files
-retain artifact-specific rules. The scene prompt keeps its separate output rule
-because it does not render the extraction-evidence asset.
+Unused shared assets are neither mounted nor fingerprinted. Universal
+extraction-evidence and output policy lives only in the shared extraction
+assets; package-owned prompt files retain artifact-specific rules. The scene
+prompt keeps its separate output rule because it does not render the
+extraction-evidence asset.
+
+### D&D Extraction Prompt Ordering And Cache Boundaries
+
+D&D extraction prompts order messages from the most reusable content to the
+most variable content. New extraction lanes use these tiers in order:
+
+1. universal shared content, including the system, extraction-evidence, and
+   in-world identity messages;
+2. stable campaign or run context shared across lanes, including campaign
+   references;
+3. stable subset- and lane-specific context and instructions, including an NPC
+   registry, catalog, task, or extraction instructions when applicable;
+4. the chunk transcript as the final user message.
+
+This ordering lets requests reuse the longest identical prefix before the
+per-chunk transcript changes. Cache reuse requires the preceding message
+sequence and content to be exactly identical; semantic similarity is not
+sufficient. Cache boundaries belong at the ends of reusable stable tiers,
+subject to the provider's cache-boundary limit. The shared identity and
+campaign-reference messages form the first two extraction boundaries. Spell
+and combat prompts add a boundary at the shared NPC registry. Each extraction
+prompt places its final boundary on its lane-specific instructions, immediately
+before the transcript. The transcript does not carry cache control because no
+reusable content follows it.
+
+Accordingly, the common prefix of all three extraction prompts is system,
+extraction evidence, identity, and campaign references. The NPC prompt then
+renders task, instructions, and transcript. Spell renders immediate resolution,
+NPC registry, catalog, task, instructions, and transcript. Combat renders
+immediate resolution, NPC registry, task, instructions, and transcript. The
+scene chunker is not an extraction lane: it retains its separate system,
+transcript, campaign-reference, task, and instruction order and marks its
+transcript and campaign-reference messages ephemeral.
+
+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.
+Package-local assets contain only lane-specific content. An extraction lane may
+depart from the tier order only when prompt-quality evidence or a provider
+constraint makes the exception necessary; document the exception and rationale
+here when it becomes implemented behavior.
 
 Schema helpers load embedded JSON Schema with identity and digest metadata,
 return defensive copies, and expose a diagnostics map that omits schema bytes.