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

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 names-only grounding after the shared evidence message. Notarius resolves the model's selected name into the unchanged exact durable ID/name pair. It is never occurrence evidence.

Each occurrence must use one exact registry ID/name pair. An extraction response with an unknown or ambiguous selected 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.

{
  "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 for the binding and JSON output for publication.

See item registry for the grounding artifact and D&D module internals for implementation details.