82 lines
3.2 KiB
Markdown
82 lines
3.2 KiB
Markdown
# 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.
|
|
|
|
```json
|
|
{
|
|
"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](dnd-npc-artifacts.md) 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](dnd-combat-turn-artifacts.md) for combat-action
|
|
occurrences. The [enemy-event artifact](dnd-enemy-event-artifacts.md) consumes
|
|
only `combat_opponent` interactions 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).
|