notarius/docs/integrations/dnd-item-registry-artifacts.md

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.

{
  "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:

["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 names-only grounding; Notarius resolves the selected name into the unchanged exact durable ID/name pair. The registry’s source references are never occurrence evidence. Unknown or ambiguous selections are rejected by the occurrence contract. See the item-occurrence artifact for that strict wire contract, Configuration for binding rules and validator selection, and the JSON output contract for publication.