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

# D&D Item-Occurrence Artifact

`dnd/item-events` 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

```json
{
  "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](dnd-item-registry-artifacts.md) for the grounding artifact
and [D&D module internals](../internal/dnd.md) for implementation details.