70 lines
2.6 KiB
Markdown
70 lines
2.6 KiB
Markdown
# D&D NPC Artifact
|
|
|
|
This contract defines the durable NPC registry produced by `dnd/npcs`. It is a
|
|
minimal, source-grounded identity registry for other D&D artifacts, not a
|
|
character sheet or a relationship summary.
|
|
|
|
## Identity and compatibility
|
|
|
|
| Property | Value |
|
|
| --- | --- |
|
|
| Artifact kind | `dnd/npc-list` |
|
|
| Schema ID | `notarius.dnd.npcs` |
|
|
| Schema name | `notarius_dnd_npcs_v1` |
|
|
| Schema version | `v1` |
|
|
| Media type | `application/json` |
|
|
| Identity policy | `dnd.npcs.identity.v1` |
|
|
|
|
`v1` accepts one strict JSON object with required `npcs`; the array may be
|
|
empty. NPC and source-reference objects reject unknown fields. An incompatible
|
|
artifact shape or identity-policy change uses a new version or policy.
|
|
|
|
## Wire shape and identity
|
|
|
|
Each NPC has these required fields:
|
|
|
|
| Field | Contract |
|
|
| --- | --- |
|
|
| `id` | `npc:sha256:` followed by 64 lowercase hexadecimal characters. |
|
|
| `name` | Non-empty canonical display name. |
|
|
| `source_refs` | One or more transcript evidence ranges for the identity. |
|
|
|
|
A source reference has exactly `source_id`, `start_unit_id`, and `end_unit_id`.
|
|
The source ID identifies the transcript, unit IDs are positive inclusive unit
|
|
identifiers, and the start may not follow the end.
|
|
|
|
```json
|
|
{
|
|
"npcs": [
|
|
{
|
|
"id": "npc:sha256:99a16589618a04f535a7d21fdcc71a0b1c05d22f752cd492065b1086d97bc3d7",
|
|
"name": "Mira Thorn",
|
|
"source_refs": [
|
|
{"source_id": "session-7", "start_unit_id": 4, "end_unit_id": 5}
|
|
]
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
The ID is deterministic: normalize the name to Unicode NFKC, normalize the
|
|
supported apostrophe forms, collapse whitespace, case-fold it, SHA-256 the
|
|
result, then prefix the lowercase hexadecimal digest with `npc:sha256:`. Each
|
|
canonical identity and ID appears at most once. Normalization collapses records
|
|
with the same canonical identity, retains their earliest position, and merges
|
|
their canonicalized evidence; it does not add aliases, roles, descriptions, or
|
|
relationship fields.
|
|
|
|
## Scope and consumers
|
|
|
|
Only individually identifiable NPC names with transcript evidence belong in
|
|
this artifact. Groups, generic roles, invented labels, and descriptive
|
|
enrichment are excluded. Its source references prove registry provenance; they
|
|
do not become evidence for a spell, interaction, or combat occurrence.
|
|
|
|
This registry can ground actor or caster names in the [spell](dnd-spell-artifacts.md)
|
|
and [combat-turn](dnd-combat-turn-artifacts.md) artifacts. It is required to
|
|
resolve the canonical `name` in an [NPC interaction](dnd-npc-interaction-artifacts.md).
|
|
The [JSON output contract](json-output.md) defines publication, and
|
|
[D&D module internals](../internal/dnd.md) owns pipeline mechanics.
|