79 lines
3.0 KiB
Markdown
79 lines
3.0 KiB
Markdown
# 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. A future incompatible
|
|
shape 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.
|
|
|
|
```json
|
|
{
|
|
"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](json-output.md) defines publication. See
|
|
[D&D module internals](../internal/dnd.md) for implementation details and the
|
|
[NPC-interaction artifact](dnd-npc-interaction-artifacts.md) for a distinct
|
|
kind of occurrence.
|