D&D NPC Artifact

This document defines the durable D&D NPC-list artifact, its JSON codec, and the selectable production NPC pipeline. The normalized JSON payload can be passed explicitly to the spell extractor as an optional caster-name registry or to the combat extractor and normalizer as an actor/target registry. It remains a reference, not spell or combat evidence.

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.

Production Pipeline

The production identities are:

extractor: dnd/npcs;
artifact kind: dnd/npc-list;
normalizer: dnd/npcs; and
durable schema: notarius.dnd.npcs, version v1, media type application/json.

The extractor maps private model records to the current source identity and assigns deterministic IDs. Extraction validation checks shape, source references, and source relatedness. The normalizer then consolidates records by canonical identity or canonical-name/alias matches, preserves the first record's display and output position, unions relationships and exact evidence, rewrites unambiguous relationship targets to canonical names, and validates the retained registry's identity. No LLM is used for consolidation.

The default extraction chain is generic/valid_json, generic/valid_json_schema, extract/dnd/npcs/shape, extract/dnd/npcs/source_refs, and extract/dnd/npcs/source_relatedness. The normalize chain adds normalize/dnd/npcs/identity before the source-reference and relatedness checks. Relatedness emits bounded warnings when an NPC canonical name or alias is not present near its cited transcript text; opaque campaign references may explain such a warning but do not become evidence.

Manifest And Sequential Consumption

The NPC extractor records prompt and response-schema identities. The durable codec records only npc_count; raw names, aliases, descriptions, source references, and payload bytes stay in the lane file rather than manifest metadata. The normalized lane is independently reusable as a file reference:

go run ./cmd/notarius run dnd-spells \
  --config examples/dnd-npc-spell-sequential.config.yml \
  --input examples/seriatim-minimal-transcript.json \
  --reference spells.extract.npcs=./npc-output/<run-id>/lanes/npcs.json

The spell extractor strictly decodes and identity-validates this file, accepts source references belonging to another session as registry provenance, and uses only canonical names and aliases for caster grounding. Those NPC source references are never accepted as spell evidence. The spell run's manifest keeps raw file provenance under references and records only the prepared registry's semantic digest and count in extractor metadata.

4.5 KiB Raw Blame History