notarius/docs/integrations/dnd-item-event-artifacts.md

D&D Item-Event Artifact

This contract defines the durable item and currency occurrence list produced by dnd/item-events. It records source-grounded discoveries and possession changes; it does not maintain an inventory, balance, or ledger.

Identity and compatibility

Property	Value
Artifact kind	dnd/item-event-list
Schema ID	notarius.dnd.item_events
Schema name	notarius_dnd_item_events_v1
Schema version	v1
Media type	application/json

v1 is a strict JSON object with required events; the array may be empty. Event and source-reference objects reject unknown fields. An incompatible shape change requires a new schema version.

Wire shape

Every event has required name, kind, and source_refs. quantity, from, and to are optional where the event kind permits them.

Field	Contract
name	Non-empty item or currency display name.
kind	discovered, acquired, lost, consumed, or transferred.
quantity	Optional positive integer; omit it when no count is established.
from	Optional non-empty losing holder, when allowed by kind.
to	Optional non-empty gaining holder, when allowed by kind.
source_refs	One or more transcript evidence ranges.

Each source reference has exactly source_id, start_unit_id, and end_unit_id. It identifies an inclusive current-transcript range; unit IDs are positive and the start may not follow the end.

{
  "events": [
    {
      "name": "Silver Pieces",
      "kind": "acquired",
      "quantity": 20,
      "to": "party",
      "source_refs": [
        {"source_id": "session-7", "start_unit_id": 2, "end_unit_id": 2}
      ]
    }
  ]
}

Holder rules and minimal extraction

discovered has neither holder; acquired requires to and forbids from; lost and consumed require from and forbid to; transferred requires both holders. party denotes collective possession. A transfer cannot use party for either holder and its two normalized holders must differ.

Only an evidenced discovery or possession change belongs in this artifact. It does not infer quantities or holders, convert currency denominations, calculate balances, or merge nearby events. Campaign references may disambiguate names but are never event evidence. Currency uses the ordinary name field and an explicit quantity only when the transcript establishes one; each denomination remains a separate event.

Normalization trims display whitespace, orders and removes exact duplicate source references, then orders events by valid source chronology, name identity and display value, kind, holders, quantity, and reference sequence. It collapses only entries with the same normalized durable fields and complete valid evidence.

The JSON output contract defines publication. See D&D module internals for implementation details and the NPC-occurrence artifact for a distinct kind of occurrence.