# 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`:

```json
{
  "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:

```yaml
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](../config.md#implemented-production-modules) for selectable
keys and chains, [the NPC artifact contract](dnd-npc-artifacts.md) for the
registry boundary, and the copyable
[maintained example](../../examples/dnd-npc-interactions.config.yml).