notarius/docs/roadmap/dnd-item-events.md

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.

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.