Hardened D&D spell extraction prompts

docs/integrations/dnd-spell-artifacts.md

@@ -50,11 +50,21 @@ Each spell cast contains exactly these required fields:
 - `source_refs`: transcript source references with extractor-assigned source
   IDs and evidence unit ranges. It must contain at least one entry.
 
-All four string fields must be non-empty. `caster` is the in-world caster, not
-the transcript speaker. The `spell` value must resolve through the effective
-SRD-plus-overlay catalog as either a canonical name or alias. Catalog
-validation accepts aliases but does not rewrite them; unknown fields are
-rejected.
+All four string fields must be non-empty. `caster` is the canonical in-world
+caster, not the human player, transcript speaker, or GM when the associated
+character or creature can be identified. Player and party references may
+disambiguate that identity, but do not independently establish that a cast
+occurred. The `spell` value must resolve through the effective SRD-plus-overlay
+catalog as either a canonical name or alias. Catalog validation accepts aliases
+but does not rewrite them; unknown fields are rejected.
+
+`effect` and `narrative_description` record what the transcript establishes
+about the session as played. They do not correct the table from published D&D
+rules or supplement the transcript with model knowledge. When the transcript
+contains a nonstandard or disputed ruling, the artifact may preserve the
+observed resolution and attribute relevant reasoning to the GM or table; it
+must not present that reasoning as a universal game rule. The spell catalog is
+name-recognition policy, not evidence for spell mechanics or outcomes.
 
 ## Source References
 
@@ -63,6 +73,17 @@ Each source reference contains exactly three required fields: `source_id`,
 The unit IDs must be positive integers present in the input, and the start unit
 must not appear after the end unit. Unknown fields are rejected.
 
+For each cast, the complete `source_refs` collection identifies the transcript
+evidence for every factual claim in `caster`, `spell`, `effect`, and
+`narrative_description`. A cast declaration and a later resolution may be
+cited with separate narrow ranges when intervening units are unrelated. A
+reported target, roll, amount, condition, interruption, or outcome must be
+supported by the cited units; otherwise the artifact describes only the
+supported attempt or declaration. The deterministic validators establish that
+ranges are structurally valid and that the spell name is related to cited
+text. Semantic claim completeness is an extraction policy and remains subject
+to evaluation rather than deterministic proof.
+
 Reference slot keys and accepted file types are defined in
 [Configuration](../config.md#implemented-production-modules). References are
 supporting disambiguation material, not source evidence, and are not
@@ -145,3 +166,9 @@ included in manifest metadata. The `normalizer` metadata uses the same catalog
 identity fields when that module is selected. Overlay origin, media type, byte
 size, and raw digest are recorded separately in the manifest's reference
 provenance; see the [JSON output contract](json-output.md#manifestjson).
+
+The extractor's prompt hash, private response-schema hash, and effective catalog
+digest also contribute independently scoped semantic checkpoint fingerprints.
+Changing any of those prepared contracts intentionally produces a cold
+checkpoint miss. Fingerprints contain only digests, never prompt, schema,
+catalog, or reference content.

docs/internal/modules.md

@@ -158,11 +158,25 @@ reference into an immutable effective catalog and adds a generated
 canonical-name-only JSON input to every structured completion request. Overlay
 failures therefore stop construction before source parsing or an LLM call;
 campaign references remain separate disambiguation inputs and never become
-source evidence. Both the extractor and deterministic catalog validator expose
+source evidence.
+
+The prompt requires each cast's source references collectively to support all
+reported facts, using separate narrow ranges when a declaration and resolution
+are non-contiguous. It grounds caster names in in-world identities, using the
+player and party references to disambiguate transcript speakers without
+treating those references as event evidence. Effects describe the session as
+played: model rules knowledge cannot supplement or correct the transcript, and
+nonstandard adjudication is attributed to the GM or table rather than stated as
+a universal rule. Structural source validation remains deterministic; semantic
+claim completeness is enforced through extraction policy and evaluation.
+
+Both the extractor and deterministic catalog validator expose
 the effective base-plus-overlay semantic digest as scoped prepared-component
 checkpoint identity. Raw overlay provenance independently covers file-byte
 changes, while the semantic digest also invalidates reuse when the embedded
-catalog or catalog composition changes. The separate
+catalog or catalog composition changes. The extractor additionally fingerprints
+its complete prompt assets and private response schema, so either semantic
+contract changing invalidates previously recorded extraction checkpoints. The separate
 `internal/modules/dnd/codec/spells` package
 owns the durable schema and stable JSON representation for artifact kind
 `dnd/spell-list`. The runner keeps the result typed through validators and later