91 lines
3.8 KiB
Markdown
91 lines
3.8 KiB
Markdown
# 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)
|
|
supplies names-only contextual grounding to the model. Notarius resolves the
|
|
selected name and writes the exact `{npc_id, name}` pair. An unknown or
|
|
ambiguous selection rejects the complete model result; normalization does not
|
|
repair names by similarity. Registry references are provenance only and never
|
|
replace an occurrence's own evidence.
|
|
The registry may include an identity established by a factual third-party
|
|
mention; that provenance alone does not create a `mentioned` occurrence. Each
|
|
occurrence remains a separately cited fact in the current transcript.
|
|
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).
|