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

D&D NPC Artifact

This document defines the durable D&D NPC-list artifact and its JSON codec. The artifact type and codec are implemented, but no selectable production pipeline currently produces this artifact.

Identity

• Artifact kind: dnd/npc-list
• Durable schema ID: notarius.dnd.npcs
• Durable schema name: notarius_dnd_npcs_v1
• Durable schema version: v1
• Media type: application/json
• Identity policy: dnd.npcs.identity.v1

The durable JSON Schema is owned by the D&D NPC codec. NPC IDs are derived from the Unicode-normalized, case-folded canonical name using the identity policy. The durable codec enforces the artifact shape and ID syntax; registry identity validation remains a separate deterministic concern.

Output Shape

The payload is one object with a required top-level npcs array:

{"npcs": []}

The array may be empty. Every object and nested object rejects unknown fields.

NPC Fields

Each NPC contains exactly these required fields:

• id: npc:sha256: followed by 64 lowercase hexadecimal characters;
• name: the canonical display name;
• aliases: an array of alternate display names, which may be empty;
• description: a concise description;
• relationships: an array of target/relationship objects, which may be empty;
• source_refs: at least one source reference supporting the NPC record.

Each relationship contains required target and relationship strings. Each source reference contains required source_id, start_unit_id, and end_unit_id; unit IDs are positive integers. Source document identity, unit existence, and range ordering are validated by the source-reference validator when the artifact is used by a pipeline.

Codec Boundary

EncodeCandidate and DecodeCandidate provide strict single-value JSON serialization while preserving typed values that still need semantic validation. Encode and Decode are the approved-artifact boundary and require all durable structural fields, non-empty required strings, valid source reference shapes, and the NPC ID pattern.

Codec metadata contains only npc_count. Schema bytes and returned metadata are independent values so callers cannot mutate codec-owned state.