# 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).