87 lines
3.3 KiB
Markdown
87 lines
3.3 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. Currency denominations, materially
|
|
different item types, and merely nearby objects remain distinct. Source
|
|
references establish registry provenance, not evidence for later artifacts.
|
|
|
|
## Publication
|
|
|
|
The registry is a selectable D&D artifact. See
|
|
[Configuration](../config.md#production-module-keys) for module keys and
|
|
validator chains, and the [JSON output contract](json-output.md) for
|
|
publication. It does not yet define a consumer handoff contract.
|