D&D NPC Interaction Artifact

This document defines the durable D&D NPC-interaction-list artifact and its two-step production pipeline. It records discrete, source-grounded occurrences for NPCs already accepted into a normalized NPC registry; it does not expand the registry or summarize events.

Identity And JSON

Artifact kind: dnd/npc-interaction-list
Durable schema ID: notarius.dnd.npc_interactions
Durable schema name: notarius_dnd_npc_interactions_v1
Durable schema version: v1
Media type: application/json

The payload is one strict JSON object with only an interactions array. The array may be empty. Each item has exactly name, kind, and source_refs:

{
  "interactions": [
    {
      "name": "Mira Thorn",
      "kind": "dialogue",
      "source_refs": [
        {"source_id": "session-7", "start_unit_id": 12, "end_unit_id": 13}
      ]
    }
  ]
}

name is the canonical display name from the required NPC registry. source_refs contains one or more current-source ranges with required source_id, start_unit_id, and end_unit_id; unit IDs are positive integers. Unknown fields are rejected.

Interaction Categories

kind is exactly one of:

mentioned: the named NPC is referenced without stronger participation.
noncombat_presence: the NPC is present in the current scene without a dialogue or combat classification.
dialogue: the NPC participates in spoken interaction.
combat_ally: the NPC participates in combat aligned with the party.
combat_opponent: the NPC participates in combat against the party.
other: a transcript-supported interaction outside the bounded categories.

These categories do not encode summaries, relationships, state, motives, or unobserved events.

Evidence, Registry, And Normalization

The registry proves only the canonical NPC identity. Its source references are registry provenance and are never interaction evidence. Every durable interaction must cite current transcript units supporting both the name and its classification.

The extractor receives a names-only registry projection such as {"npcs":[{"name":"Mira Thorn"}]}. The normalizer uses the full immutable registry for exact canonical-name lookup. It orders source references, stable-sorts occurrences by their earliest source-document position, and collapses only exact duplicates with the same canonical name, kind, and complete valid evidence. Different categories, distinct ranges, and separately grounded occurrences remain separate; no semantic merge is performed.

Production Pipeline

The extractor and normalizer key is dnd/npc-interactions. Both require the structured npcs slot, so an accepted normalized registry must come from an earlier step:

pipelines:
  dnd-npc-interactions:
    input: seriatim
    steps:
      - id: identify-npcs
        artifacts:
          npcs:
            extract: dnd/npcs
            normalize: dnd/npcs
      - id: extract-interactions
        references:
          npcs:
            artifact:
              step: identify-npcs
              lane: npcs
        artifacts:
          interactions:
            extract: dnd/npc-interactions
            normalize: dnd/npc-interactions

The framework passes only the accepted normalized producer. A missing, rejected, or incompatible NPC artifact prevents the consumer step from executing. It records generated artifact identity and bounded producer provenance without copying registry names, source ranges, or payload content into the manifest.

Validation And Metadata

The default extract chain is generic/valid_json, interaction shape, registry, and source-reference validation, generic/valid_json_schema, then warning-only source relatedness. The normalize chain adds normalized invariants after schema validation and before relatedness. The codec metadata contains only interaction_count. Extractor metadata identifies its prompt and private response schema; component-local checkpoint identities include the names-only registry projection where relevant. Generated registry identity stays in framework provenance and dependency fingerprints.

See Configuration for selectable keys and chains, the NPC artifact contract for the registry boundary, and the copyable maintained example.

4.3 KiB Raw Blame History