Move NPC occurrences to their canonical namespace

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

@@ -0,0 +1,85 @@
+# D&D NPC Occurrence Artifact
+
+This contract defines the durable occurrence list produced by
+`dnd/npc-occurrences`. It records discrete, source-grounded occurrences with
+NPCs already present in a normalized registry; it does not extend that registry
+or summarize the session.
+
+## Identity and compatibility
+
+| Property | Value |
+| --- | --- |
+| Artifact kind | `dnd/npc-occurrence-list` |
+| Schema ID | `notarius.dnd.npc_occurrences` |
+| Schema name | `notarius_dnd_npc_occurrences_v1` |
+| Schema version | `v1` |
+| Media type | `application/json` |
+
+`v1` is a strict JSON object with required `occurrences`; the array may be
+empty. Occurrence and source-reference objects reject unknown fields. An
+incompatible shape change requires a new schema version.
+
+## Wire shape
+
+Each occurrence has these required fields:
+
+| Field | Contract |
+| --- | --- |
+| `npc_id` | Exact durable ID from the required NPC registry. |
+| `name` | Non-empty canonical display name from the required NPC registry. |
+| `kind` | One of the occurrence categories below. |
+| `source_refs` | One or more transcript evidence ranges. |
+
+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. Extraction evidence
+for an occurrence is confined to its accepted chunk.
+
+```json
+{
+  "occurrences": [
+    {
+      "npc_id": "npc:sha256:example",
+      "name": "Mira Thorn",
+      "kind": "dialogue",
+      "source_refs": [
+        {"source_id": "session-7", "start_unit_id": 12, "end_unit_id": 13}
+      ]
+    }
+  ]
+}
+```
+
+## Occurrence categories
+
+| Kind | Meaning |
+| --- | --- |
+| `mentioned` | The NPC is referred to but is not established as present or communicating. |
+| `noncombat_presence` | The NPC is present and relevant without meaningful dialogue or combat participation. |
+| `dialogue` | The NPC speaks, responds, or meaningfully participates in a non-combat exchange. |
+| `combat_ally` | The NPC actively participates in combat on the party's side. |
+| `combat_opponent` | The NPC actively participates in combat against the party. |
+| `other` | A clearly evidenced direct occurrence not covered by another category. |
+
+The categories do not represent motives, relationships, state, or events that
+the cited transcript does not establish. An `other` entry is not a substitute
+for uncertain classification.
+
+## Identity, evidence, and order
+
+The required normalized [NPC registry artifact](dnd-npc-registry-artifacts.md) resolves
+the exact `{npc_id, name}` pair. Unknown IDs and names that do not match their
+ID are rejected; normalization does not repair names by similarity. Registry
+references are provenance only and never replace an occurrence's own evidence.
+Normalization validates the exact pair, orders and
+deduplicates exact source references, then orders occurrences by valid source
+chronology, NPC comparison identity, display name, kind, and reference sequence.
+Only entries with the same NPC ID, canonical name, kind, and complete valid evidence
+sequence are collapsed; distinct categories or evidence remain separate.
+
+See the [combat-turn artifact](dnd-combat-turn-artifacts.md) for combat-action
+occurrences. The [enemy-event artifact](dnd-enemy-event-artifacts.md) consumes
+only `combat_opponent` occurrences as grounding; they never establish an enemy
+event or outcome. The [JSON output contract](json-output.md) defines
+publication. Pipeline mechanics are described in
+[D&D module internals](../internal/dnd.md).