93 lines
4.1 KiB
Markdown
93 lines
4.1 KiB
Markdown
# D&D NPC Registry Artifact
|
|
|
|
This contract defines the durable NPC registry produced by `dnd/npc-registry`. 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-registry` |
|
|
| Schema ID | `notarius.dnd.npc_registry` |
|
|
| Schema name | `notarius_dnd_npc_registry_v1` |
|
|
| Schema version | `v1` |
|
|
| Media type | `application/json` |
|
|
| Identity policy | `dnd.npc_registry.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:35ba5f679aee69e07ae3bd65c44278f29539d5dc9bb5225db1c0060555b23221",
|
|
"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, then serialize
|
|
`["dnd.npc_registry.identity.v1", comparison_name]` as compact JSON. SHA-256
|
|
those UTF-8 bytes and 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.
|
|
|
|
When evidence supports a semantically duplicate group, the canonical display
|
|
name is one of that group's supplied candidates. A complete, stable proper name
|
|
is preferred over an abbreviation. An unadorned proper name is preferred over
|
|
the same name plus a contextual class, role, title, or relationship descriptor
|
|
unless the transcript establishes that descriptor as part of the person's
|
|
name. A longer candidate is not preferred solely because it includes such a
|
|
descriptor.
|
|
|
|
## Scope and consumers
|
|
|
|
Only individually identifiable NPC names with transcript evidence belong in
|
|
this artifact. A factual third-party mention can establish an identity even if
|
|
the NPC is not present, speaking, or acting in the cited passage. Names used
|
|
only in hypothetical, speculative, or imagined examples are excluded, as are
|
|
groups, generic roles, invented labels, and descriptive enrichment. Its source
|
|
references prove registry provenance; they do not become evidence for a spell,
|
|
occurrence, combat, or enemy-event occurrence.
|
|
|
|
Registry evidence establishes an identity, not an [NPC occurrence](dnd-npc-occurrence-artifacts.md).
|
|
That later artifact independently records any current-transcript occurrence
|
|
with its own cited evidence and category.
|
|
|
|
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 occurrence](dnd-npc-occurrence-artifacts.md).
|
|
Occurrence consumers receive names-only grounding; Notarius resolves the
|
|
selected canonical name and writes the unchanged exact durable ID/name pair.
|
|
Spells, combat turns, and the [enemy-event artifact](dnd-enemy-event-artifacts.md)
|
|
also receive names-only grounding for actor or subject display. None of these
|
|
projections supply later-artifact evidence. [Configuration](../config.md#d-d-reference-slots)
|
|
owns the `npc_registry` binding rules.
|
|
The [JSON output contract](json-output.md) defines publication, and
|
|
[D&D module internals](../internal/dnd.md) owns pipeline mechanics.
|