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

D&D Item-Occurrence Artifact

dnd/item-occurrences currently produces this source-grounded item and currency occurrence list. It records discoveries and possession changes, not an inventory, balance, or ledger.

Identity and compatibility

Property	Value
Artifact kind	dnd/item-occurrence-list
Schema ID	notarius.dnd.item_occurrences
Schema name	notarius_dnd_item_occurrences_v1
Schema version	v1
Media type	application/json

The strict root has required occurrences. Records require item_id, name, kind, and source_refs; unknown fields are rejected. quantity, from, and to appear only when their kind permits them.

Registry grounding

Both extraction and normalization require an item_registry reference bound to an earlier normalized dnd/item-registry artifact. The registry is immutable for an operation and contributes only its ordered {id,name} projection after the shared evidence message. It is never occurrence evidence.

Each occurrence must use one exact registry ID/name pair. Extraction omits an unknown ID or mismatched name rather than creating an item. Normalization canonicalizes a recognized name by ID, preserves unknown values for the registry validator, and the registry validator rejects unknown or mismatched pairs.

Wire shape

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

The five kinds remain discovered, acquired, lost, consumed, and transferred. Holder, quantity, currency, ordering, and exact-duplicate rules are unchanged: discovered has no holder; acquired requires to; lost and consumed require from; transferred requires distinct non-party holders. Each source reference is an inclusive current-transcript range.

See item registry for the grounding artifact and D&D module internals for implementation details.