95 lines
3.9 KiB
Markdown
95 lines
3.9 KiB
Markdown
# D&D Item Registry Artifact
|
||
|
||
This contract defines the durable, source-grounded item registry produced by
|
||
`dnd/item-registry`. It records transcript-established item types and unique
|
||
designations for one source document; it is not an inventory, holder record,
|
||
quantity ledger, or item-occurrence artifact.
|
||
|
||
## Identity and compatibility
|
||
|
||
| Property | Value |
|
||
| --- | --- |
|
||
| Artifact kind | `dnd/item-registry` |
|
||
| Schema ID | `notarius.dnd.item_registry` |
|
||
| Schema name | `notarius_dnd_item_registry_v1` |
|
||
| Schema version | `v1` |
|
||
| Media type | `application/json` |
|
||
| Identity policy | `dnd.item_registry.identity.v1` |
|
||
|
||
`v1` accepts one strict JSON object with required `items`; the array may be
|
||
empty. Item and source-reference objects reject unknown fields. An incompatible
|
||
artifact shape or identity-policy change uses a new version or policy.
|
||
|
||
## Wire shape and identity
|
||
|
||
Each item has these required fields:
|
||
|
||
| Field | Contract |
|
||
| --- | --- |
|
||
| `id` | `item:sha256:` followed by 64 lowercase hexadecimal characters. |
|
||
| `name` | Non-empty transcript-established item type or unique designation. |
|
||
| `source_refs` | One or more transcript evidence ranges that establish the item. |
|
||
|
||
A source reference has exactly `source_id`, `start_unit_id`, and `end_unit_id`.
|
||
The source ID identifies the transcript, unit IDs are positive inclusive unit
|
||
identifiers, and the start may not follow the end.
|
||
|
||
```json
|
||
{
|
||
"items": [
|
||
{
|
||
"id": "item:sha256:31e73b6280ef98e4d8070e07fd4de9b2c3e842cc03af1a09ca631cb95b73e3b3",
|
||
"name": "Star Compass",
|
||
"source_refs": [
|
||
{"source_id": "session-7", "start_unit_id": 4, "end_unit_id": 5}
|
||
]
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
The ID is deterministic for an item name or type, rather than for one physical
|
||
instance. Notarius normalizes the display name for comparison with Unicode
|
||
NFKC, supported apostrophe normalization, collapsed whitespace, and case
|
||
folding. It hashes compact JSON for this array:
|
||
|
||
```text
|
||
["dnd.item_registry.identity.v1", comparison_name]
|
||
```
|
||
|
||
The canonical ID is the lowercase SHA-256 digest of those bytes with the
|
||
`item:sha256:` prefix. Equal comparison names represent one item identity;
|
||
normalization unions their transcript evidence when it safely consolidates a
|
||
candidate group.
|
||
|
||
## Scope, reconciliation, and evidence
|
||
|
||
The registry includes named unique items, concrete reusable item types, stable
|
||
unique designations, and separately established currency denominations. It
|
||
excludes vague loot or treasure, generic weapons, quantities, inferred
|
||
properties, and inferred uniqueness. Capitalization alone does not establish
|
||
eligibility.
|
||
|
||
Normalization first applies deterministic display, evidence, and ID rules. It
|
||
then may use a bounded LLM-assisted proposal to reconcile semantically duplicate
|
||
records. The proposal may choose only a supplied candidate display name;
|
||
invalid, uncertain, overlapping, or unsafe proposals retain the deterministic
|
||
result with retry or fallback diagnostics. A proposal that mixes a recognized
|
||
currency denomination with a non-currency item, or combines recognized
|
||
denominations, is unsafe and retains every deterministic record. Currency
|
||
denominations, materially different item types, and merely nearby objects
|
||
remain distinct. Source references establish registry provenance, not evidence
|
||
for later artifacts.
|
||
|
||
## Consumers and publication
|
||
|
||
`dnd/item-occurrences` requires one approved item registry through its
|
||
`item_registry` reference slot for both extraction and normalization. Its
|
||
consumer receives only an ordered, source-free `{id,name}` projection; the
|
||
registry’s source references are never occurrence evidence. Unknown IDs and
|
||
mismatched pairs are rejected by the occurrence contract. See the
|
||
[item-occurrence artifact](dnd-item-occurrence-artifacts.md) for that strict
|
||
wire contract, [Configuration](../config.md#d-d-reference-slots) for binding
|
||
rules and validator selection, and the [JSON output contract](json-output.md)
|
||
for publication.
|