61 lines
2.1 KiB
Markdown
61 lines
2.1 KiB
Markdown
# 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
|
|
|
|
```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.
|