Plan D&D item event tracking

docs/roadmap/dnd-item-events.md

@@ -0,0 +1,212 @@
+# D&D Item Events
+
+## Status
+
+Ready for implementation. This document defines the desired artifact and
+pipeline contract; the concrete work is specified in
+[the implementation plan](implementation.md).
+
+## Purpose
+
+Add a source-grounded D&D item-event lane that records meaningful changes in
+the party's knowledge or possession of items. The lane should answer what item
+was discovered, acquired, lost, consumed, or transferred, who held it when that
+is known, how many were involved when the transcript states a quantity, and
+where the event appears in the source.
+
+The feature should follow the application's minimal-extraction policy. It
+records structured occurrences supported by transcript ranges and does not ask
+the model to maintain an inventory, infer unstated ownership, resolve semantic
+item identity, summarize an item's significance, or analyze how it was used.
+
+## One Event Extractor
+
+The initial production lane should use one LLM extractor and one deterministic
+normalizer under the selectable key `dnd/item-events`. Its durable artifact
+should be an ordered `dnd/item-event-list`.
+
+Unlike NPC identification, item identification is not initially a separate
+artifact. An item matters to this feature because a tracked event happened to
+it, so a preliminary item-list extractor would duplicate evidence and add an
+ordered dependency without establishing a distinct useful contract.
+
+An item registry may be reconsidered after real transcripts demonstrate a need
+for canonical aliases, stable cross-event identity, or downstream consumers
+that need items independently of events. If introduced later, it should be an
+explicit earlier artifact consumed through the existing ordered generated-
+reference mechanism. It should not be anticipated through placeholder IDs or
+implicit coupling in the v1 event schema.
+
+## Durable Event Contract
+
+The durable payload should contain one required `events` array, which may be
+empty. Each event should contain:
+
+- `name`: a concise item name supported by the cited transcript;
+- `kind`: one of the five event categories below;
+- `quantity`: an optional positive integer, present only when the transcript
+  establishes a count;
+- `from`: an optional holder losing possession;
+- `to`: an optional holder gaining possession; and
+- `source_refs`: one or more supporting current-source ranges.
+
+`from` and `to` should use a transcript-supported party-member name when the
+holder is known. The reserved display value `party` should represent collective
+party possession when the event is clear but no individual holder is
+established. The extractor must not guess an individual holder.
+
+Every extraction-time source range must be wholly contained in the current
+accepted chunk. Campaign references may disambiguate item or holder names but
+must never become item-event evidence.
+
+The initial contract should not assign item IDs. Name-derived IDs would conflate
+distinct generic objects, while model-assigned instance IDs would require
+unreliable entity resolution. Separately evidenced events involving identically
+named items must remain representable.
+
+## Event Categories
+
+| Kind | Meaning |
+| --- | --- |
+| `discovered` | The party learns of or directly encounters an item without establishing possession. |
+| `acquired` | The party or a party member gains possession or control of an item. |
+| `lost` | The party or a party member ceases to possess or control an item without consuming it. |
+| `consumed` | Use depletes, expends, or destroys the tracked item. |
+| `transferred` | Possession moves from one party member to another without changing party-level ownership. |
+
+Category and holder rules should be:
+
+- `discovered` has neither `from` nor `to`.
+- `acquired` requires `to` and has no party-holder `from`. The item's external
+  source may be described by the transcript but is not modeled as a holder.
+- `lost` requires `from` and has no party-holder `to`.
+- `consumed` requires `from` and has no `to`.
+- `transferred` requires distinct `from` and `to` party members.
+- Giving an item to an NPC, spending currency, selling an item, or otherwise
+  moving it outside party possession is `lost`, not `transferred`.
+- An item destroyed through its intended or immediate use is `consumed`; an
+  item destroyed, abandoned, stolen, or otherwise removed from control is
+  `lost`.
+- Ordinary non-depleting use, such as swinging a sword, wearing armor, reading
+  a reusable book, or activating a reusable item, is not an event.
+
+When discovery and acquisition are separately established, each is a separate
+ordered event. A statement that establishes only acquisition must not cause the
+extractor to invent an additional discovery event.
+
+## Quantities And Currency
+
+Currency is an item for this contract. For example, recovering 20 silver pieces
+should produce an `acquired` event with the transcript-supported denomination,
+quantity `20`, the gaining holder or `party`, and source evidence.
+
+Each denomination should remain a separate item name and event. The feature
+must not convert values between denominations, infer omitted quantities, or
+calculate balances. An absent quantity means the source did not establish a
+reliable count; it does not mean one.
+
+Distinct explicit quantities remain distinct events. The normalizer must not
+sum nearby acquisitions, subtract losses, or reconcile contradictory counts.
+
+## Event Boundaries And Normalization
+
+One event represents one item, one category, one holder transition, and one
+locally coherent passage within one accepted chunk. Events never span chunks.
+A category change, holder change, distinct possession transition, intervening
+scene, or meaningful absence begins a new event.
+
+The deterministic normalizer should:
+
+- trim item and holder display values without semantic rewriting;
+- canonicalize and validate source-reference ordering;
+- order events by earliest source-document position, followed by stable
+  deterministic tie-breakers over item name, kind, holders, quantity, and the
+  complete evidence sequence; and
+- remove only exact duplicates after deterministic formatting.
+
+It must not merge nearby events, reconcile aliases, singularize or rename
+items, infer missing holders or quantities, calculate party inventory, or use
+an LLM. Case-folded comparison may support deterministic ordering, but it must
+not silently make differently displayed item names the same durable identity.
+
+## Prompt And Reference Policy
+
+The extractor should follow the established shared D&D prompt organization and
+prompt-caching conventions. Stable shared instructions and stable campaign
+references should precede the variable transcript input.
+
+It may declare the existing optional `players`, `party`, and `glossary`
+campaign-reference slots for name disambiguation. It should not require the NPC
+registry, scene-description artifact, or a new item registry. Item events are
+independent of those lanes and should not add an implicit cross-lane
+dependency.
+
+The prompt should emphasize literal extraction, category and holder rules,
+current-session evidence, and omission when the event or quantity is uncertain.
+It should not request descriptions, item properties, rarity, value, narrative
+importance, inferred ownership history, or inventory summaries.
+
+## Validation, Provenance, And Quality
+
+The lane should follow the established typed D&D module pattern:
+
+- a strict durable codec and a separate private structured-response schema;
+- deterministic shape, source-reference, and normalized-invariant validators;
+- warning-only source relatedness where it provides useful signal;
+- exact source identity and chunk containment during extraction;
+- deterministic candidate mapping that adds the current source ID rather than
+  asking the model to emit it;
+- bounded, content-safe diagnostics and metadata; and
+- prompt, schema, mapping, and normalization policy fingerprints for checkpoint
+  correctness.
+
+Validation should reject unsupported kinds, invalid category/holder
+combinations, non-positive quantities, malformed or out-of-chunk references,
+and normalized ordering or duplicate invariants. Relatedness checks should
+remain advisory because pronouns, currency notation, and contextual item names
+may make exact lexical matching incomplete.
+
+Tests should protect the durable schema, category and holder rules, explicit
+currency quantities, source containment, deterministic ordering, exact
+duplicate removal, prompt/reference boundaries, registration, and one
+representative assembled pipeline. They should remain deterministic and
+offline, use a fake only at the LLM boundary, and avoid assertions over private
+helper structure or probabilistic model quality.
+
+## Configuration And Documentation
+
+The feature should become a selectable D&D artifact lane in production module
+registration and configuration documentation. The maintained complete D&D
+example should include the item-event lane in the pipeline step appropriate for
+independent extraction; it must not add a generated-reference dependency merely
+to group item events with other event artifacts. The minimal example should
+remain unchanged.
+
+When implemented, the durable schema and consumer semantics should have a
+canonical integration contract. Internal documentation should describe package
+ownership and module mechanics without duplicating that external contract.
+
+## Non-Goals
+
+This scope does not:
+
+- produce a complete current inventory or starting inventory;
+- calculate running balances, net currency, encumbrance, or item value;
+- identify every mentioned item when no tracked event occurs;
+- record ordinary non-consuming item use;
+- model containers, equipment slots, attunement, charges, or item properties;
+- assign stable instance IDs or semantically reconcile aliases;
+- derive item ownership from NPC, combat-turn, or scene artifacts;
+- introduce a second LLM extractor, an LLM-backed normalizer, or an item
+  registry; or
+- introduce new pipeline orchestration or reference syntax.
+
+## Completion Criteria
+
+The feature is complete when a configured D&D lane can produce and normalize a
+strict ordered item-event artifact for discoveries, acquisitions, losses,
+consumption, intra-party transfers, and currency; every event is grounded in
+current transcript ranges; deterministic validation and normalization enforce
+the category, holder, quantity, ordering, and exact-duplicate policies; the
+complete maintained example selects the lane; and canonical current-behavior
+documentation replaces this roadmap as the source of implemented contracts.

docs/roadmap/future.md

@@ -7,6 +7,14 @@ not as committed release dates.
 
 ## Near-Term D&D Pipeline
 
+### Add D&D Item Events
+
+- Implement the selected
+  [D&D item-event contract](dnd-item-events.md) as the next near-term feature.
+  Track source-grounded discoveries, acquisitions, losses, consumption,
+  intra-party transfers, and explicit currency quantities without inferring an
+  inventory ledger or introducing a preliminary item registry.
+
 ### Evaluate Spell Extraction And Normalization
 
 - Evaluate ordinary extraction retries and the completed normalization path