213 lines
10 KiB
Markdown
213 lines
10 KiB
Markdown
# 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.
|