Move item occurrences to canonical namespace

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

@@ -0,0 +1,60 @@
+# 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` |
+
+The strict root has required `occurrences`. Records require `item_id`, `name`,
+`kind`, and `source_refs`; unknown fields are rejected. `quantity`, `from`, and
+`to` appear only when their kind permits them.
+
+## 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 only its ordered `{id,name}` projection after
+the shared evidence message. It is never occurrence evidence.
+
+Each occurrence must use one exact registry ID/name pair. Extraction omits an
+unknown ID or mismatched name rather than creating an item. 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
+
+```json
+{
+  "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.
+Each source reference is an inclusive current-transcript range.
+
+See [item registry](dnd-item-registry-artifacts.md) for the grounding artifact
+and [D&D module internals](../internal/dnd.md) for implementation details.