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. During extraction, every range must be wholly contained in the current accepted chunk. This prevents a candidate from citing valid units that were not presented to that extraction call. Unknown fields are rejected.

Interaction Categories

kind is exactly one of:

Kind	Meaning
`mentioned`	The NPC is referred to, but is not established as present or communicating in the evidenced passage.
`noncombat_presence`	The NPC is present and relevant to the passage but does not meaningfully participate in dialogue or combat.
`dialogue`	The NPC speaks, responds, or is directly engaged in a meaningful non-combat exchange.
`combat_ally`	The NPC actively participates in combat on the party's side.
`combat_opponent`	The NPC actively participates in combat against the party.
`other`	The transcript clearly establishes a direct NPC occurrence that fits none of the preceding kinds.

other is a residual category for positively evidenced activity, not a fallback for uncertain classification. When activities overlap, active combat participation outranks dialogue, presence, and mention; dialogue outranks non-combat presence and mention; and non-combat presence outranks mention. Combat alignment is not resolved by precedence: a meaningful change between ally and opponent creates separate occurrences.

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

Occurrence Boundaries And Ordering

One occurrence represents one NPC, one kind, and one locally coherent passage within one accepted chunk. Repeated evidence belongs to the same occurrence only while it supports the same uninterrupted activity. A kind change, combat alignment change, intervening scene or meaningful absence, or transition from mention to presence starts a new occurrence. Occurrences never span chunks, and merge or normalization never semantically combines nearby, overlapping, or cross-chunk records.

Normalization orders records by:

earliest valid source-document position;
the NPC identity comparison key;
the exact canonical NPC display name;
interaction kind in lexical order; and
the complete canonical source-reference sequence, ordered by source ID and the source-document positions of each range's start and end.

Only records with identical canonical names, kinds, and complete valid evidence sequences are duplicates. Different categories, ranges, or separately grounded occurrences remain separate.

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 canonicalizes source references and applies the ordering and exact-duplicate rules above.

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 runs normalized invariants after registry validation and before source-reference and schema validation, followed by relatedness. Normalizer and relatedness warnings are bounded and end with an omission summary when necessary. 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.

6.1 KiB Raw Blame History