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

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.

{
  "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 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 for combat-action occurrences. The enemy-event artifact consumes only combat_opponent occurrences as grounding; they never establish an enemy event or outcome. The JSON output contract defines publication. Pipeline mechanics are described in D&D module internals.