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 Artifact Handoff

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 can be consumed by a later ordered step through the registered canonical codec:

steps:
  - id: identify-npcs
    artifacts:
      npcs:
        extract: dnd/npcs
        normalize: dnd/npcs
  - id: grounded-events
    references:
      npcs:
        artifact:
          step: identify-npcs
          lane: npcs
    artifacts:
      spells:
        extract: dnd/spells
        normalize: dnd/spells
      combat:
        extract: dnd/combat-turns
        normalize: dnd/combat-turns

The framework hands only an accepted normalized artifact across the barrier. It validates the canonical bytes against each consumer slot and clones the operation-time reference for the spell and combat consumers. Generated provenance records the artifact kind, schema identity, media type, canonical digest, size, and producer step/lane/module, but not names, aliases, source ranges, or payload bytes. External normalized files remain supported as explicit references and retain their file provenance.

NPC source references are registry provenance and are never accepted as spell or combat evidence. Current transcript units remain the only event evidence.

4.9 KiB Raw Blame History