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

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.

{
  "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. Groups, generic roles, invented labels, and descriptive enrichment are excluded. Its source references prove registry provenance; they do not become evidence for a spell, occurrence, combat, or enemy-event occurrence.

This registry can ground actor or caster names in the spell and combat-turn artifacts. It is required to resolve the canonical name in an NPC occurrence. The enemy-event artifact also uses it only for subject grounding and canonical display names. The JSON output contract defines publication, and D&D module internals owns pipeline mechanics.