72 lines
2.8 KiB
Markdown
72 lines
2.8 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` |
|
|
|
|
`v1` accepts one strict JSON object with required `occurrences`; the array may
|
|
be empty. Each occurrence has required `item_id`, `name`, `kind`, and
|
|
`source_refs`, and occurrence and source-reference objects reject unknown
|
|
fields. `quantity`, `from`, and `to` appear only when their kind permits them.
|
|
An incompatible shape change requires a new schema version.
|
|
|
|
## 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. An extraction response
|
|
with an unknown ID or mismatched name is rejected as invalid model output; the
|
|
configured pipeline may retry it and never accepts a partial artifact.
|
|
Normalization and validation remain defense in depth for artifacts entering
|
|
through other boundaries: 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
|
|
|
|
Each source reference has exactly `source_id`, `start_unit_id`, and
|
|
`end_unit_id`. It identifies an inclusive range in the current transcript;
|
|
unit IDs are positive and the start may not follow the end.
|
|
|
|
```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.
|
|
The only current downstream compatibility requirement is its registry handoff;
|
|
the normalized occurrence list is otherwise published for callers. See
|
|
[Configuration](../config.md#d-d-reference-slots) for the binding and
|
|
[JSON output](json-output.md) for publication.
|
|
|
|
See [item registry](dnd-item-registry-artifacts.md) for the grounding artifact
|
|
and [D&D module internals](../internal/dnd.md) for implementation details.
|