Complete D&D NPC interaction integration

2026-07-23 13:59:02 +00:00
parent b02f667107
commit 36e0512454
13 changed files with 511 additions and 29 deletions
--- a/README.md
+++ b/README.md
@@ -31,4 +31,5 @@ Useful references:
 - [Internal implementation docs](docs/internal/overview.md)
 - [Maintained example config](examples/dnd-spells.config.yml)
 - [NPC-grounded example config](examples/dnd-npc-grounded.config.yml)
+- [NPC interaction example config](examples/dnd-npc-interactions.config.yml)
 - [Maintained example input](examples/seriatim-minimal-transcript.json)
--- a/docs/config.md
+++ b/docs/config.md
@@ -24,6 +24,7 @@ The explicit-path option is defined in the [CLI reference](cli.md).
 - [D&D NPC configuration](../examples/dnd-npcs.config.yml)
 - [D&D combat-turn configuration](../examples/dnd-combat-turns.config.yml)
 - [D&D NPC-grounded spell and combat configuration](../examples/dnd-npc-grounded.config.yml)
+- [D&D NPC interaction configuration](../examples/dnd-npc-interactions.config.yml)

 All are complete version 3 files. The fragments below illustrate individual
 fields and are not alternate complete configurations.
@@ -355,11 +356,13 @@ production validators do not call the LLM and must not set `llm_profile`.
 | extract | `dnd/spells` | Extracts typed D&D spell-list artifacts. |
 | extract | `dnd/npcs` | Extracts typed D&D NPC-list artifacts. |
 | extract | `dnd/combat-turns` | Extracts typed D&D combat-turn-list artifacts. |
+| extract | `dnd/npc-interactions` | Extracts typed D&D NPC-interaction-list artifacts from a supplied NPC registry. |
 | merge | `appendorder` | Combines typed artifacts in chunk order. |
 | normalize | `noop` | Passes merged typed artifacts through unchanged. |
 | normalize | `dnd/spells` | Deterministically canonicalizes and de-duplicates typed D&D spell-list artifacts. |
 | normalize | `dnd/npcs` | Deterministically consolidates typed D&D NPC-list artifacts by canonical name and unions exact evidence. |
 | normalize | `dnd/combat-turns` | Deterministically canonicalizes, orders, and de-duplicates typed D&D combat-turn artifacts. |
+| normalize | `dnd/npc-interactions` | Canonicalizes registry NPC names, orders interaction occurrences, and removes only exact duplicates. |
 | output | `json` | Produces JSON output files for normalized `application/json` lanes. |

 ## Implemented Production Validators
@@ -382,6 +385,11 @@ production validators do not call the LLM and must not set `llm_profile`.
 | `extract/dnd/combat-turns/source_refs` | deterministic | Rejects missing or invalid D&D combat-turn source references. |
 | `extract/dnd/combat-turns/source_relatedness` | deterministic | Emits warnings when an actor is not found near cited source text. |
 | `normalize/dnd/combat-turns/invariants` | deterministic | Rejects normalized combat-turn identity, evidence-order, and chronology violations. |
+| `extract/dnd/npc-interactions/shape` | deterministic | Rejects malformed D&D NPC-interaction-list artifacts. |
+| `extract/dnd/npc-interactions/registry` | deterministic | Rejects interaction names absent from the supplied NPC registry. |
+| `extract/dnd/npc-interactions/source_refs` | deterministic | Rejects missing or invalid D&D interaction source references. |
+| `extract/dnd/npc-interactions/source_relatedness` | deterministic | Emits warnings when an interaction name is not found near cited source text. |
+| `normalize/dnd/npc-interactions/invariants` | deterministic | Rejects normalized interaction identity, evidence-order, and chronology violations. |

 The production default chain for `dnd/spells` is used for both its extract and
 normalize stages:
@@ -436,6 +444,28 @@ normalize:
    - extract/dnd/combat-turns/source_relatedness
 ```

+The production default chains for `dnd/npc-interactions` are:
+
+```yaml
+extract:
+  validators:
+    - generic/valid_json
+    - extract/dnd/npc-interactions/shape
+    - extract/dnd/npc-interactions/registry
+    - extract/dnd/npc-interactions/source_refs
+    - generic/valid_json_schema
+    - extract/dnd/npc-interactions/source_relatedness
+normalize:
+  validators:
+    - generic/valid_json
+    - extract/dnd/npc-interactions/shape
+    - extract/dnd/npc-interactions/registry
+    - extract/dnd/npc-interactions/source_refs
+    - generic/valid_json_schema
+    - normalize/dnd/npc-interactions/invariants
+    - extract/dnd/npc-interactions/source_relatedness
+```
+
 Empty chains approve output by default.

 The `generic` chunker accepts:
@@ -516,6 +546,16 @@ identity; names, content, and paths are not recorded there. When
 absent, the combat prompt receives the exact empty registry value
 `{"npcs":[]}` with its projection digest and no registry provenance.

+Both `dnd/npc-interactions` stages require the structured `npcs` slot. Bind one
+accepted normalized NPC artifact from an earlier ordered step; the interaction
+extractor receives only its names-only projection, while the normalizer uses
+the immutable registry for exact canonical-name lookup. A missing, rejected,
+or incompatible producer prevents the interaction step from running. Registry
+source references remain identity provenance and never supply interaction
+evidence: every interaction must cite current transcript units. The complete
+durable contract and two-step configuration are defined in the
+[D&D NPC interaction artifact contract](integrations/dnd-npc-interaction-artifacts.md).
+
 ## State Surfaces

 The `output`, `cache`, and `debug` top-level fields select independent physical
--- a/docs/integrations/dnd-npc-artifacts.md
+++ b/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

--- a/docs/integrations/dnd-npc-interaction-artifacts.md
+++ b/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).
--- a/docs/internal/llm.md
+++ b/docs/internal/llm.md
@@ -98,7 +98,7 @@ D&D prompt content. `internal/framework/promptfs` provides the domain-neutral
 filesystem composition helper used to combine module-owned files with shared
 domain prompt fragments.

-The D&D scene chunker and spell, NPC, and combat-turn extractors each declare an
+The D&D scene chunker and spell, NPC, combat-turn, and NPC-interaction extractors each declare an
 ordered prompt asset manifest. The manifest lists the package-owned YAML and
 Markdown files, then the exact shared fragments rendered by that prompt; the
 same ordered list drives both filesystem mounting and the prompt fingerprint.
@@ -126,17 +126,18 @@ per-chunk transcript changes. Cache reuse requires the preceding message
 sequence and content to be exactly identical; semantic similarity is not
 sufficient. Cache boundaries belong at the ends of reusable stable tiers,
 subject to the provider's cache-boundary limit. The shared identity and
-campaign-reference messages form the first two extraction boundaries. Spell
-and combat prompts add a boundary at the shared NPC registry. Each extraction
+campaign-reference messages form the first two extraction boundaries. Spell,
+combat, and interaction prompts add a boundary at the shared NPC registry. Each extraction
 prompt places its final boundary on its lane-specific instructions, immediately
 before the transcript. The transcript does not carry cache control because no
 reusable content follows it.

-Accordingly, the common prefix of all three extraction prompts is system,
+Accordingly, the common prefix of all four extraction prompts is system,
 extraction evidence, identity, and campaign references. The NPC prompt then
 renders task, instructions, and transcript. Spell renders the NPC registry,
 catalog, task, instructions, and transcript. Combat renders the NPC registry,
-task, instructions, and transcript. The
+task, instructions, and transcript. NPC interaction renders the names-only NPC
+registry, task, instructions, and transcript. The
 scene chunker is not an extraction lane: it retains its separate system,
 transcript, campaign-reference, task, and instruction order and marks its
 transcript and campaign-reference messages ephemeral.
@@ -154,7 +155,7 @@ return defensive copies, and expose a diagnostics map that omits schema bytes.
 The small framework registry contains only generic test schemas; production
 schemas remain package-owned.

-The spell, NPC, and combat extractors' package-owned prompts declare their
+The spell, NPC, combat, and NPC-interaction extractors' package-owned prompts declare their
 structured JSON inputs and private response schemas. Each private response
 schema remains separate from its durable artifact codec schema; this work does
 not use shared schema fragments or schema generation. Those private schemas own
@@ -167,14 +168,14 @@ numbers. The spell extractor's prompt declares a required
 the catalog input from its prepared
 effective catalog as `{"spell_names":[...]}` using sorted canonical names only.
 The shared D&D prompt assets include a generic NPC grounding fragment directly
-after the campaign reference message for spell and combat prompts. When an NPC
+after the campaign reference message for spell, combat, and interaction prompts. When an NPC
 registry is bound, the
 domain registry boundary strictly decodes and identity-validates one durable
 artifact, re-encodes canonical JSON for provenance, and separately generates a
 names-only prompt projection. The unbound projection is exactly `{"npcs":[]}`.
 Prompt input and component-local checkpoint digests cover the projected bytes;
 manifests retain the optional full registry digest/count rather than names,
-overlay bytes, registry paths, or source metadata. Combat prompt,
+overlay bytes, registry paths, or source metadata. Combat and interaction prompt,
 response-schema, mapping, normalization, identity, and registry-projection
 fingerprints remain separate semantic inputs to checkpoint identity.

--- a/docs/internal/modules.md
+++ b/docs/internal/modules.md
@@ -17,16 +17,16 @@ validator registry. Package-family registrars compose those leaf registrations
 into the production catalog and own family-level policy such as default
 validator chains and prompt asset collection.

-Production input, chunk, output, and D&D spell- and combat-extract packages
+Production input, chunk, output, and D&D spell-, combat-, and interaction-extract packages
 register strict option decoders and run-local builders. Preparation decodes their options into
 implementation-owned values and injects dependencies plus the materialized
 reference set for the selected target. Each builder receives an isolated clone
-of that set; input and output builders receive no references. The spell and
-combat extractors are typed over the canonical D&D model. D&D validators, merge,
+of that set; input and output builders receive no references. The spell,
+combat, and interaction extractors are typed over the canonical D&D model. D&D validators, merge,
 and normalize use typed variants; JSON representation validators use serialized
 requests; and unconditional validators expose separate chunk and typed
 variants. The D&D production registrar registers the canonical typed spell,
-NPC, and combat implementations, including their kind-specific merge and
+NPC, combat, and interaction implementations, including their kind-specific merge and
 normalize behavior.

 For D&D artifact defaults, generic JSON syntax validation runs first. Rejecting
@@ -54,7 +54,7 @@ package-local embedded assets. Shared filesystem composition belongs in
 `internal/framework/promptfs`; reusable D&D prompt fragments, reference
 declarations, prompt-input assembly, and source-unit/citation helpers belong in
 `internal/modules/dnd/shared`, which also owns bounded D&D diagnostics. The
-D&D scene chunker and spell, NPC, and combat-turn extractors use ordered
+D&D scene chunker and spell, NPC, combat-turn, and NPC-interaction extractors use ordered
 package-local prompt manifests for both rendering and prompt fingerprinting, so
 only the shared fragments each prompt actually renders participate in either
 operation. Extraction prompts place stable shared and lane-specific context
@@ -65,7 +65,7 @@ contracts expose only Notarius structured-completion types, not Scriptorium
 public types.

 The shared `ChunkPromptMaterial` helper owns common transcript material
-preparation for the spell, NPC, and combat-turn extractors. It clones supplied
+preparation for the spell, NPC, combat-turn, and NPC-interaction extractors. It clones supplied
 source metadata, falls back to the materialized chunk when content is absent,
 checks that content remains chunk-identical, and fills only the common default
 fields. Extractors retain their request validation and wrap helper errors with
@@ -122,6 +122,12 @@ The `internal/modules/dnd/codec/combatturns` package owns the durable
 is registered by the production D&D family registrar for the selectable combat
 lane.

+The `internal/modules/dnd/codec/npcinteractions` package owns the durable
+`dnd/npc-interaction-list` schema and candidate versus approved JSON boundary.
+It is registered by the production D&D family registrar for the selectable
+interaction lane. Its external contract is documented in the
+[D&D NPC interaction artifact contract](../integrations/dnd-npc-interaction-artifacts.md).
+
 ## Input Adapter

 ### `internal/modules/seriatim/input/transcript`
@@ -284,6 +290,19 @@ The combat normalizer accepts only the optional structured NPC registry.
 Campaign references remain extractor-only LLM context and are not materialized
 for deterministic normalization.

+### `internal/modules/dnd/extract/npcinteractions`
+
+The NPC interaction extractor requires the structured `npcs` registry slot. It
+uses the registry's names-only prompt projection with shared extraction
+evidence, identity, and transcript material, then maps private model records to
+`dnd.NPCInteractionList` with the current source identity. Registry source
+references are never reused as interaction evidence. The private response
+schema carries only name, bounded interaction kind, and source-unit ranges;
+deterministic validators own registry membership, source validity, and
+relatedness. Prompt, schema, mapping, and the names-only registry projection
+participate in checkpoint identity, while generated producer identity remains
+framework provenance.
+
 ### `internal/modules/dnd/normalize/npcs`

 The NPC normalizer performs deterministic identity-aware consolidation in
@@ -344,6 +363,16 @@ digest/count metadata; generated identity is retained in framework provenance
 and dependency fingerprints. The normalizer is included in the production D&D
 registrar with the default combat normalization chain.

+### `internal/modules/dnd/normalize/npcinteractions`
+
+The interaction normalizer requires the same immutable NPC registry. It
+canonicalizes exact registry-name matches, orders and de-duplicates source
+references, stable-sorts occurrences by source-document position, and collapses
+only exact interaction identities with valid evidence. It does not infer,
+merge, or summarize distinct occurrences. Its metadata and fingerprints expose
+the normalization and NPC identity policies; generated registry identity stays
+in framework provenance and checkpoint dependencies.
+
 ## Output Encoder

 ### `internal/modules/generic/output/json`
@@ -428,6 +457,18 @@ expose local policy fingerprints. In the registered defaults, JSON syntax runs
 first; combat shape, normalized invariants when applicable, and source-reference
 validation precede JSON Schema validation; warning-only relatedness runs last.

+## D&D NPC Interaction Validators
+
+Interaction shape validation owns the required list, registry name, supported
+kind, and non-empty source-reference collection. Registry validation checks
+exact membership in the required immutable NPC registry. Source-reference and
+relatedness validation use the current transcript only; malformed candidates
+are deferred by later validators and produce no relatedness warning. The
+normalized-invariants validator owns canonical registry names, source-reference
+order, chronology, and exact duplicate identity. The production chains run
+shape, registry, and source-reference checks before JSON Schema validation;
+relatedness remains warning-only and last.
+
 ## Production Registration

 Production composition occurs through family registrars. The CLI allocates one
@@ -436,7 +477,7 @@ complete framework registry set and one LLM asset registry. It invokes
 `internal/modules/seriatim/register`, and `internal/modules/dnd/register` in
 that order, then exposes the matching catalog for resolution. The generic and
 Seriatim registrars own their production leaf registrations. The D&D registrar
-owns D&D leaf registrations, typed spell, NPC, and combat default-validator
+owns D&D leaf registrations, typed spell, NPC, combat, and interaction default-validator
 chains, typed append-order specializations, and D&D prompt/schema asset
 collection. Its registration helpers group module, validator, prompt-asset, and
 chain composition while retaining artifact-specific merge and clone behavior in
--- a/docs/internal/overview.md
+++ b/docs/internal/overview.md
@@ -67,8 +67,9 @@ run-local construction closures. Preparation injects shared dependencies and
 constructs input, chunk, validators, ordered lanes, and output before source
 parsing. Production modules use strict construction-time option decoding, and
 LLM-backed modules retain the injected shared client. The D&D family registers
-the canonical `dnd/spell-list`, `dnd/npc-list`, and `dnd/combat-turn-list`
-codecs, typed spell, NPC, and combat extractors and normalizers, validators,
+the canonical `dnd/spell-list`, `dnd/npc-list`, `dnd/combat-turn-list`, and
+`dnd/npc-interaction-list` codecs, typed spell, NPC, combat, and interaction
+extractors and normalizers, validators,
 plus kind-specific generic merge strategies; generic JSON validators use the
 serialized-validation contract. The runner executes lanes through
 private exact-type-checked closures, coordinates extract results independently
@@ -87,15 +88,19 @@ Configuration. The implemented module packages are:
 | `internal/modules/seriatim/input/transcript` | Parses the supported Seriatim transcript format into the generic source model. |
 | `internal/modules/generic/chunk/units` | Splits ordered source units by unit count and overlap. |
 | `internal/modules/dnd/chunk/scenes` | Produces contiguous D&D scene chunks from structured model output. |
-| `internal/modules/dnd` | Owns the canonical D&D spell-list, spell-cast, NPC-list, NPC, combat-turn-list, and combat-turn artifact types. |
+| `internal/modules/dnd` | Owns the canonical D&D spell-list, spell-cast, NPC-list, NPC, combat-turn-list, combat-turn, NPC-interaction-list, and NPC-interaction artifact types. |
 | `internal/modules/dnd/codec/spells` | Strictly decodes and stably encodes the durable D&D spell-list representation. |
 | `internal/modules/dnd/codec/npcs` | Strictly decodes and stably encodes the durable D&D NPC-list representation. |
 | `internal/modules/dnd/codec/combatturns` | Strictly decodes and stably encodes the durable D&D combat-turn-list representation. |
+| `internal/modules/dnd/codec/npcinteractions` | Strictly decodes and stably encodes the durable D&D NPC-interaction-list representation. |
 | `internal/modules/dnd/extract/spells` | Maps private structured model output to canonical source-grounded D&D spell lists. |
 | `internal/modules/dnd/extract/npcs` | Maps private structured model output to canonical source-grounded D&D NPC lists. |
 | `internal/modules/dnd/extract/combatturns` | Maps private structured model output to source-grounded D&D combat-turn candidates and preserves chronology and invalid candidate values for validators. |
+| `internal/modules/dnd/extract/npcinteractions` | Maps private structured model output to current-source NPC interaction candidates grounded by a required registry. |
 | `internal/modules/dnd/normalize/combatturns` | Canonicalizes and orders merged combat turns, applies exact NPC identity matches, and collapses only exact valid-evidence duplicates. |
+| `internal/modules/dnd/normalize/npcinteractions` | Canonicalizes required-registry names, orders interaction occurrences, and collapses only exact valid-evidence duplicates. |
 | `internal/modules/dnd/validate/combatturns` | Provides deterministic shape, source-reference, source-relatedness, and normalized-invariant validation for the production combat chains. |
+| `internal/modules/dnd/validate/npcinteractions` | Provides deterministic shape, registry, source-reference, source-relatedness, and normalized-invariant validation for interaction chains. |
 | `internal/modules/dnd/npcs/registry` | Resolves validated normalized NPC references into immutable grounding data and exact identity lookup. |
 | `internal/modules/dnd/npcs/identity` | Owns Unicode-aware NPC identity, ID derivation, and registry collision validation. |
 | `internal/modules/dnd/spells/catalog` | Embeds and validates the versioned D&D 5e 2014 SRD catalog, composes optional overlays, and provides immutable effective lookup. |
@@ -116,14 +121,16 @@ The `dnd/npcs/registry` package owns the optional `npcs` registry boundary.
 External references are strictly decoded and identity-validated during
 preparation; generated references are decoded and identity-validated at the
 ordered step handoff. Both paths retain canonical registry JSON for provenance
-and emit a names-only projection to operation-time spell and combat prompts.
-Combat normalization uses the canonical registry for exact actor lookup. The
+and emit a names-only projection to operation-time spell, combat, and
+interaction prompts. Combat and interaction normalization use the canonical
+registry for exact name lookup. The
 framework records generated identity and bounded producer provenance, while
 the raw external reference remains independently tracked by pipeline
 provenance. An absent registry is represented only by the empty prompt value
 `{"npcs":[]}`. Spell
 and combat consumers use this shared boundary without changing their public
-module contracts.
+module contracts. Interaction consumers require it and retain only current
+transcript references as durable evidence.

 Generic validators under `internal/modules/generic/validate` provide
 unconditional test decisions, JSON syntax validation, and JSON Schema
--- a/docs/roadmap/dnd-npc-interactions.md
+++ b/docs/roadmap/dnd-npc-interactions.md
@@ -1,6 +1,9 @@
 # D&D NPC Interactions

-Status: Accepted
+Status: Implemented
+
+The current durable and configuration contract is documented in the
+[D&D NPC interaction artifact](../integrations/dnd-npc-interaction-artifacts.md).

 ## Purpose

--- a/docs/roadmap/future.md
+++ b/docs/roadmap/future.md
@@ -16,13 +16,6 @@ not as committed release dates.
  validator, and normalizer development. Treat model-quality review as an
  iterative human evaluation aid, not a deterministic correctness gate.

-### Extract NPC Interactions
-
-Add a minimal, ordered `dnd/npc-interactions` artifact after NPC identity
-extraction. The proposed contract, occurrence semantics, category policy,
-grounding rules, evidence requirements, and non-goals are defined in
-[D&D NPC Interactions](dnd-npc-interactions.md).
-
 ### Export Accepted Chunk Maps

 - Add an option to emit the accepted materialized chunk map as a proper,
--- a/examples/dnd-npc-interactions.config.yml
+++ b/examples/dnd-npc-interactions.config.yml
@@ -0,0 +1,34 @@
+version: 3
+output:
+  directory: ./notarius-output
+cache:
+  chunk_plans:
+    mode: bypass
+  checkpoints:
+    enabled: false
+    directory: ""
+debug:
+  directory: ./notarius-debug
+pipelines:
+  dnd-npc-interactions:
+    input: seriatim
+    steps:
+      - id: identify-npcs
+        artifacts:
+          npcs:
+            extract:
+              module: dnd/npcs
+              retries: 2
+            normalize: dnd/npcs
+      - id: extract-interactions
+        references:
+          npcs:
+            artifact:
+              step: identify-npcs
+              lane: npcs
+        artifacts:
+          interactions:
+            extract:
+              module: dnd/npc-interactions
+              retries: 2
+            normalize: dnd/npc-interactions
--- a/internal/cli/production_contract_test.go
+++ b/internal/cli/production_contract_test.go
@@ -506,6 +506,7 @@ func maintainedExampleFiles(t *testing.T) []maintainedExample {
 		{name: "npcs", path: repositoryPath("examples", "dnd-npcs.config.yml"), pipelineIDs: []string{"dnd-session"}},
 		{name: "combat", path: repositoryPath("examples", "dnd-combat-turns.config.yml"), pipelineIDs: []string{"dnd-combat"}},
 		{name: "npc-grounded", path: repositoryPath("examples", "dnd-npc-grounded.config.yml"), pipelineIDs: []string{"dnd-npc-grounded"}},
+		{name: "npc-interactions", path: repositoryPath("examples", "dnd-npc-interactions.config.yml"), pipelineIDs: []string{"dnd-npc-interactions"}},
 	}
 }

--- a/internal/modules/integration/dnd_npc_interactions_runner_test.go
+++ b/internal/modules/integration/dnd_npc_interactions_runner_test.go
@@ -0,0 +1,214 @@
+package integration_test
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"os"
+	"sync"
+	"testing"
+
+	"gitea.maximumdirect.net/eric/notarius/internal/core/config"
+	"gitea.maximumdirect.net/eric/notarius/internal/core/source"
+	"gitea.maximumdirect.net/eric/notarius/internal/framework/contracts"
+	"gitea.maximumdirect.net/eric/notarius/internal/framework/pipeline"
+	interactioncodec "gitea.maximumdirect.net/eric/notarius/internal/modules/dnd/codec/npcinteractions"
+	npccodec "gitea.maximumdirect.net/eric/notarius/internal/modules/dnd/codec/npcs"
+	interactionextract "gitea.maximumdirect.net/eric/notarius/internal/modules/dnd/extract/npcinteractions"
+	"gitea.maximumdirect.net/eric/notarius/internal/modules/dnd/extract/npcs"
+)
+
+func TestNPCInteractionPipelineUsesAcceptedRegistryAndCurrentEvidence(t *testing.T) {
+	registries := productionNPCRegistries(t)
+	resolved := resolveNPCInteractionPipeline(t, registries)
+	client := &npcInteractionLLMClient{}
+
+	output, err := runPreparedPipeline(t, registries, resolved, client, pipeline.RunInput{RawInput: readNPCFixture(t)})
+	if err != nil {
+		t.Fatalf("Run() error = %v", err)
+	}
+	if len(output.Rejected) != 0 || len(output.NormalizeOutputs) != 2 {
+		t.Fatalf("run outputs = %#v rejected = %#v, want NPC and interaction artifacts", output.NormalizeOutputs, output.Rejected)
+	}
+
+	request := client.requestFor(t, interactionextract.PromptID)
+	wantRegistry := `{"npcs":[{"name":"Mira Thorn"},{"name":"Hooded Guard"}]}`
+	if got := string(request.Inputs["npcs"].Content); got != wantRegistry {
+		t.Fatalf("interaction registry input = %s, want names-only projection %s", got, wantRegistry)
+	}
+	if request.Inputs["npcs"].MediaType != npccodec.MediaType {
+		t.Fatalf("interaction registry media type = %q, want %q", request.Inputs["npcs"].MediaType, npccodec.MediaType)
+	}
+
+	serialized := normalizedLane(t, output, "interactions")
+	if serialized.Artifact.Schema.ID != interactioncodec.SchemaID || serialized.Artifact.Schema.Version != interactioncodec.SchemaVersion {
+		t.Fatalf("interaction artifact schema = %#v", serialized.Artifact.Schema)
+	}
+	interactions, err := interactioncodec.New().Decode(serialized.Artifact.Content)
+	if err != nil {
+		t.Fatalf("Decode(interaction output) error = %v", err)
+	}
+	if len(interactions.Interactions) != 2 {
+		t.Fatalf("interactions = %#v, want two occurrences", interactions)
+	}
+	first, second := interactions.Interactions[0], interactions.Interactions[1]
+	if first.Name != "Mira Thorn" || string(first.Kind) != "dialogue" || second.Name != "Hooded Guard" || string(second.Kind) != "noncombat_presence" {
+		t.Fatalf("interactions = %#v, want canonical names, kinds, and source chronology", interactions)
+	}
+	assertInteractionEvidence(t, first.SourceRefs)
+	assertInteractionEvidence(t, second.SourceRefs)
+	if first.SourceRefs[0].StartUnitID >= second.SourceRefs[0].StartUnitID {
+		t.Fatalf("interaction chronology = %#v, want source order", interactions.Interactions)
+	}
+
+	var durable map[string]json.RawMessage
+	if err := json.Unmarshal(serialized.Artifact.Content, &durable); err != nil {
+		t.Fatalf("unmarshal durable interaction payload: %v", err)
+	}
+	if len(durable) != 1 || durable["interactions"] == nil {
+		t.Fatalf("durable interaction payload = %#v, want only interactions", durable)
+	}
+}
+
+func TestNPCInteractionPipelineSkipsConsumerWhenNPCProducerIsRejected(t *testing.T) {
+	registries := productionNPCRegistries(t)
+	resolved := resolveNPCInteractionPipeline(t, registries)
+	client := &npcInteractionLLMClient{rejectNPCs: true}
+
+	output, err := runPreparedPipeline(t, registries, resolved, client, pipeline.RunInput{RawInput: readNPCFixture(t)})
+	if err == nil {
+		t.Fatalf("Run() output = %#v, want missing generated NPC producer error", output)
+	}
+	if client.requestCount(npcs.PromptID) != 1 {
+		t.Fatalf("NPC requests = %d, want rejected producer", client.requestCount(npcs.PromptID))
+	}
+	if client.requestCount(interactionextract.PromptID) != 0 {
+		t.Fatalf("interaction requests = %d, want none after rejected producer", client.requestCount(interactionextract.PromptID))
+	}
+}
+
+func resolveNPCInteractionPipeline(t *testing.T, registries pipeline.Registries) pipeline.ResolvedPipeline {
+	t.Helper()
+	configValue := loadNPCInteractionPipelineConfig(t)
+	effective, err := configValue.Resolve(config.ResolveInput{PipelineID: "dnd-npc-interactions-fixture", Catalog: moduleCatalog(registries)})
+	if err != nil {
+		t.Fatalf("Resolve() error = %v", err)
+	}
+	resolved, warnings, err := pipeline.MaterializeReferences(effective.ResolvedPipeline, moduleCatalog(registries), pipeline.ReferenceMaterializationOptions{})
+	if err != nil || len(warnings) != 0 {
+		t.Fatalf("MaterializeReferences() error = %v warnings = %#v", err, warnings)
+	}
+	return resolved
+}
+
+func loadNPCInteractionPipelineConfig(t *testing.T) config.Config {
+	t.Helper()
+	data, err := os.ReadFile("testdata/dnd_npc_interactions_pipeline.yml")
+	if err != nil {
+		t.Fatalf("ReadFile(dnd_npc_interactions_pipeline.yml) error = %v", err)
+	}
+	fileConfig, err := config.ParseFileConfigYAML(data)
+	if err != nil {
+		t.Fatalf("ParseFileConfigYAML() error = %v", err)
+	}
+	result := config.Default()
+	if err := result.ApplyFileConfig(fileConfig); err != nil {
+		t.Fatalf("ApplyFileConfig() error = %v", err)
+	}
+	return result
+}
+
+func normalizedLane(t *testing.T, output pipeline.RunOutput, laneID string) contracts.SerializedOutput {
+	t.Helper()
+	for _, serialized := range output.NormalizeOutputs {
+		if serialized.LaneID == laneID {
+			return serialized
+		}
+	}
+	t.Fatalf("normalized lanes = %#v, missing %q", output.NormalizeOutputs, laneID)
+	return contracts.SerializedOutput{}
+}
+
+func assertInteractionEvidence(t *testing.T, references []source.SourceRef) {
+	t.Helper()
+	if len(references) == 0 {
+		t.Fatal("interaction has no current-source evidence")
+	}
+	for _, reference := range references {
+		if reference.SourceID != "npc-session" {
+			t.Fatalf("interaction evidence = %#v, want current source only", reference)
+		}
+	}
+}
+
+type npcInteractionLLMClient struct {
+	mu         sync.Mutex
+	requests   []contracts.StructuredCompletionRequest
+	rejectNPCs bool
+}
+
+func (client *npcInteractionLLMClient) CompleteStructured(ctx context.Context, request contracts.StructuredCompletionRequest, out any) (contracts.StructuredCompletionResponse, error) {
+	if err := ctx.Err(); err != nil {
+		return contracts.StructuredCompletionResponse{}, err
+	}
+	client.mu.Lock()
+	client.requests = append(client.requests, cloneStructuredCompletionRequest(request))
+	client.mu.Unlock()
+
+	var payload any
+	switch request.PromptID {
+	case npcs.PromptID:
+		if client.rejectNPCs {
+			payload = map[string]any{"npcs": []any{map[string]any{
+				"name": "", "source_refs": []any{map[string]int{"start_unit_id": 1, "end_unit_id": 1}},
+			}}}
+		} else {
+			payload = map[string]any{"npcs": []any{
+				map[string]any{"name": "Mira Thorn", "source_refs": []any{map[string]int{"start_unit_id": 1, "end_unit_id": 1}}},
+				map[string]any{"name": "Hooded Guard", "source_refs": []any{map[string]int{"start_unit_id": 3, "end_unit_id": 3}}},
+			}}
+		}
+	case interactionextract.PromptID:
+		payload = map[string]any{"interactions": []any{
+			map[string]any{"name": "Hooded Guard", "kind": "noncombat_presence", "source_refs": []any{map[string]int{"start_unit_id": 3, "end_unit_id": 3}}},
+			map[string]any{"name": " mira thorn ", "kind": "dialogue", "source_refs": []any{map[string]int{"start_unit_id": 2, "end_unit_id": 2}}},
+		}}
+	default:
+		return contracts.StructuredCompletionResponse{}, fmt.Errorf("unexpected interaction prompt %q", request.PromptID)
+	}
+	content, err := json.Marshal(payload)
+	if err != nil {
+		return contracts.StructuredCompletionResponse{}, err
+	}
+	if err := json.Unmarshal(content, out); err != nil {
+		return contracts.StructuredCompletionResponse{}, fmt.Errorf("populate interaction response: %w", err)
+	}
+	return contracts.StructuredCompletionResponse{Content: content, Provider: "test", Model: "interaction-fake"}, nil
+}
+
+func (client *npcInteractionLLMClient) requestFor(t *testing.T, promptID string) contracts.StructuredCompletionRequest {
+	t.Helper()
+	client.mu.Lock()
+	defer client.mu.Unlock()
+	for _, request := range client.requests {
+		if request.PromptID == promptID {
+			return request
+		}
+	}
+	t.Fatalf("requests = %#v, missing prompt %q", client.requests, promptID)
+	return contracts.StructuredCompletionRequest{}
+}
+
+func (client *npcInteractionLLMClient) requestCount(promptID string) int {
+	client.mu.Lock()
+	defer client.mu.Unlock()
+	count := 0
+	for _, request := range client.requests {
+		if request.PromptID == promptID {
+			count++
+		}
+	}
+	return count
+}
+
+var _ contracts.StructuredLLMClient = (*npcInteractionLLMClient)(nil)
--- a/internal/modules/integration/testdata/dnd_npc_interactions_pipeline.yml
+++ b/internal/modules/integration/testdata/dnd_npc_interactions_pipeline.yml
@@ -0,0 +1,28 @@
+version: 3
+output:
+  directory: ./notarius-output
+cache:
+  chunk_plans:
+    mode: bypass
+  checkpoints: {}
+debug:
+  directory: ./notarius-debug
+pipelines:
+  dnd-npc-interactions-fixture:
+    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