Complete D&D NPC interaction integration

docs/integrations/dnd-npc-artifacts.md

@@ -5,6 +5,10 @@ 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 registry. It
 remains a reference, not spell or combat evidence.
+The NPC interaction extractor and normalizer also consume this registry for
+canonical identity; registry source references remain provenance and never
+become interaction evidence. Their occurrence contract is defined in the
+[D&D NPC interaction artifact](dnd-npc-interaction-artifacts.md).
 
 ## Identity
 

docs/integrations/dnd-npc-interaction-artifacts.md

@@ -0,0 +1,115 @@
+# 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).