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

D&D NPC Interaction Artifact

This contract defines the durable occurrence list produced by dnd/npc-interactions. It records discrete, source-grounded interactions 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-interaction-list
Schema ID	notarius.dnd.npc_interactions
Schema name	notarius_dnd_npc_interactions_v1
Schema version	v1
Media type	application/json

v1 is a strict JSON object with required interactions; the array may be empty. Interaction and source-reference objects reject unknown fields. An incompatible shape change requires a new schema version.

Wire shape

Each interaction has these required fields:

Field	Contract
name	Non-empty canonical display name from the required NPC registry.
kind	One of the interaction 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 interaction is confined to its accepted chunk.

{
  "interactions": [
    {
      "name": "Mira Thorn",
      "kind": "dialogue",
      "source_refs": [
        {"source_id": "session-7", "start_unit_id": 12, "end_unit_id": 13}
      ]
    }
  ]
}

Interaction 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 artifact resolves name. Registry references are provenance only and never replace an interaction's own evidence. Normalization canonicalizes recognized registry names, orders and deduplicates exact source references, then orders interactions by valid source chronology, NPC comparison identity, display name, kind, and reference sequence. Only entries with the same 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 and the JSON output contract for publication. Pipeline mechanics are described in D&D module internals.