Document D&D item event support

docs/internal/modules.md

@@ -17,16 +17,16 @@ validator registry. Package-family registrars compose those leaf registrations
 into the production catalog and own family-level policy such as default
 validator chains and prompt asset collection.
 
-Production input, chunk, output, and D&D spell-, NPC-, combat-, interaction-, and scene-description-extract packages
+Production input, chunk, output, and D&D spell-, NPC-, combat-, item-event-, interaction-, and scene-description-extract packages
 register strict option decoders and run-local builders. Preparation decodes their options into
 implementation-owned values and injects dependencies plus the materialized
 reference set for the selected target. Each builder receives an isolated clone
 of that set; input and output builders receive no references. The spell, NPC,
-combat, interaction, and scene-description extractors are typed over the canonical D&D model. D&D validators, merge,
+combat, item-event, interaction, and scene-description extractors are typed over the canonical D&D model. D&D validators, merge,
 and normalize use typed variants; JSON representation validators use serialized
 requests; and unconditional validators expose separate chunk and typed
 variants. The D&D production registrar registers the canonical typed spell,
-NPC, combat, interaction, and scene-description implementations, including their kind-specific merge and
+NPC, combat, item-event, interaction, and scene-description implementations, including their kind-specific merge and
 normalize behavior.
 
 For D&D artifact defaults, generic JSON syntax validation runs first. Rejecting
@@ -56,7 +56,7 @@ declarations, prompt-input assembly, and source-unit/citation helpers belong in
 `internal/modules/dnd/shared`, which owns operation-scoped indexed
 source-reference validation, citation traversal, ordering and canonicalization,
 plus bounded D&D diagnostics. The
-D&D scene chunker and spell, NPC, combat-turn, NPC-interaction, and scene-description extractors use ordered
+D&D scene chunker and spell, NPC, combat-turn, item-event, NPC-interaction, and scene-description extractors use ordered
 package-local prompt manifests for both rendering and prompt fingerprinting, so
 only the shared fragments each prompt actually renders participate in either
 operation. Extraction prompts place stable shared and lane-specific context
@@ -67,7 +67,7 @@ contracts expose only Notarius structured-completion types, not Scriptorium
 public types.
 
 The shared `PrepareChunkExtraction` helper owns common extraction preflight and
-transcript material preparation for the spell, NPC, combat-turn,
+transcript material preparation for the spell, NPC, combat-turn, item-event,
 NPC-interaction, and scene-description extractors. It validates common request
 state, clones supplied source metadata, falls back to the materialized chunk
 when content is absent, checks that content remains chunk-identical, and fills
@@ -150,6 +150,11 @@ The `internal/modules/dnd/codec/combatturns` package owns the durable
 is registered by the production D&D family registrar for the selectable combat
 lane.
 
+The `internal/modules/dnd/codec/itemevents` package owns the durable
+`dnd/item-event-list` schema and candidate versus approved JSON boundary. It is
+registered by the production D&D family registrar. Its external contract is
+defined in the [D&D item-event artifact contract](../integrations/dnd-item-event-artifacts.md).
+
 The `internal/modules/dnd/codec/npcinteractions` package owns the durable
 `dnd/npc-interaction-list` schema and candidate versus approved JSON boundary.
 It is registered by the production D&D family registrar for the selectable
@@ -348,6 +353,23 @@ The combat normalizer accepts only the optional structured NPC registry.
 Campaign references remain extractor-only LLM context and are not materialized
 for deterministic normalization.
 
+### `internal/modules/dnd/extract/itemevents`
+
+The item-event extractor prepares one structured request from the accepted
+chunk and optional campaign references, then maps private records to
+`dnd.ItemEventList` with the current source identity. It declares only optional
+`glossary`, `party`, `players`, and deprecated `roster` reference slots; these
+can disambiguate names but never supply evidence. It has no NPC,
+scene-description, or item-registry dependency.
+
+The private response schema owns structural transport validation. The extractor
+preserves candidate category, holder, quantity, and source-range values for the
+deterministic validators, removes exact duplicate ranges, and source-orders
+events. The source-reference validator requires citations to fit the current
+accepted chunk. Prompt, response-schema, and mapping identities participate in
+checkpoint identity. The durable schema is owned separately by
+`internal/modules/dnd/codec/itemevents`.
+
 ### `internal/modules/dnd/extract/npcinteractions`
 
 The NPC interaction extractor requires the structured `npcs` registry slot. It
@@ -384,7 +406,7 @@ normalization warnings.
 ### `internal/modules/generic/merge/appendorder`
 
 The merger passes typed values to an injected combine function in framework
-source-chunk order. The D&D registrar specializes it for all five artifact
+source-chunk order. The D&D registrar specializes it for all six artifact
 lists; each append merger preserves collection presence and order while giving
 the result independently owned nested source-reference slices.
 
@@ -432,6 +454,16 @@ digest/count metadata; generated identity is retained in framework provenance
 and dependency fingerprints. The normalizer is included in the production D&D
 registrar with the default combat normalization chain.
 
+### `internal/modules/dnd/normalize/itemevents`
+
+The item-event normalizer accepts no options or references and makes no LLM
+calls. It trims display-edge whitespace in names and holders, canonicalizes
+source references, source-orders events, and collapses only exact duplicates
+with complete valid evidence. It does not create a ledger, calculate balances,
+resolve aliases, infer quantities or holders, or reconcile nearby events. Its
+policy fingerprint and bounded warnings identify deterministic normalization;
+the matching invariant validator checks the resulting order and duplicate rule.
+
 ### `internal/modules/dnd/normalize/npcinteractions`
 
 The interaction normalizer requires the same immutable NPC registry. It
@@ -541,6 +573,21 @@ expose local policy fingerprints. In the registered defaults, JSON syntax runs
 first; combat shape, normalized invariants when applicable, and source-reference
 validation precede JSON Schema validation; warning-only relatedness runs last.
 
+## D&D Item-Event Validators
+
+Item-event shape validation owns the required list, non-empty name, supported
+category, category-and-holder combination, positive optional quantity, and
+non-empty source-reference collection. Source-reference validation defers
+malformed shapes, checks current-source identity and ordered ranges, and during
+extraction requires every citation to fit the accepted chunk. Relatedness is
+advisory and warning-only: it checks the event name against cited transcript
+text while deferring malformed candidates and invalid ranges to their blocking
+owners. The normalized-invariants validator owns display normalization,
+canonical source-reference order, chronology, and exact duplicate identity.
+All four validators are deterministic and expose policy fingerprints. The
+registered chains run syntax and blocking checks before durable JSON Schema;
+relatedness remains last.
+
 ## D&D NPC Interaction Validators
 
 Interaction shape validation owns the required list, registry name, supported
@@ -573,7 +620,7 @@ complete framework registry set and one LLM asset registry. It invokes
 `internal/modules/seriatim/register`, and `internal/modules/dnd/register` in
 that order, then exposes the matching catalog for resolution. The generic and
 Seriatim registrars own their production leaf registrations. The D&D registrar
-owns D&D leaf registrations, typed spell, NPC, combat, interaction, and scene-description default-validator
+owns D&D leaf registrations, typed spell, NPC, combat, item-event, interaction, and scene-description default-validator
 chains, typed append-order specializations, and D&D prompt/schema asset
 collection. Its registration helpers group module, validator, prompt-asset, and
 chain composition while retaining artifact-specific merge and clone behavior in