Document D&D enemy event artifacts

docs/integrations/dnd-combat-turn-artifacts.md

@@ -64,6 +64,8 @@ kind, and complete valid evidence. It does not infer turns, initiative, or
 actions from registry or scene data.
 
 The [NPC-interaction artifact](dnd-npc-interaction-artifacts.md) records
-broader NPC occurrences. The [JSON output contract](json-output.md) defines
-publication, and [D&D module internals](../internal/dnd.md) describes routing
-and validation mechanics.
+broader NPC occurrences. The [enemy-event artifact](dnd-enemy-event-artifacts.md)
+uses combat turns as grounding only; turns do not establish an enemy event or
+its outcome. The [JSON output contract](json-output.md) defines publication,
+and [D&D module internals](../internal/dnd.md) describes routing and validation
+mechanics.

docs/integrations/dnd-enemy-event-artifacts.md

@@ -0,0 +1,113 @@
+# D&D Enemy-Event Artifact
+
+This contract defines the durable, source-grounded enemy-event occurrence list.
+It records enemies directly established as opposing the party and explicitly
+observed combat outcomes. It is an ordered observation artifact from which a
+consumer may derive a ledger; it is not a ledger, encounter roster, or terminal
+state model.
+
+## Identity and compatibility
+
+| Property | Value |
+| --- | --- |
+| Artifact kind | `dnd/enemy-event-list` |
+| Schema ID | `notarius.dnd.enemy_events` |
+| Schema name | `notarius_dnd_enemy_events_v1` |
+| Schema version | `v1` |
+| Media type | `application/json` |
+
+`v1` is a strict JSON object with required `events`; the array may be empty.
+Event and source-reference objects reject unknown fields. An incompatible shape
+change requires a new schema version.
+
+## Wire shape
+
+Every event has these required fields:
+
+| Field | Contract |
+| --- | --- |
+| `name` | Non-empty display name or directly grounded collective subject label. |
+| `kind` | `engaged`, `killed`, `fled`, `captured`, or `incapacitated`. |
+| `source_refs` | One or more current-transcript evidence ranges. |
+
+Each source reference has exactly `source_id`, `start_unit_id`, and
+`end_unit_id`. It identifies an inclusive current-transcript range; unit IDs
+are positive and the start may not follow the end.
+
+```json
+{
+  "events": [
+    {
+      "name": "Ashfang",
+      "kind": "engaged",
+      "source_refs": [
+        {"source_id": "session-7", "start_unit_id": 41, "end_unit_id": 42}
+      ]
+    },
+    {
+      "name": "Ashfang",
+      "kind": "fled",
+      "source_refs": [
+        {"source_id": "session-7", "start_unit_id": 57, "end_unit_id": 58}
+      ]
+    }
+  ]
+}
+```
+
+## Event semantics and evidence
+
+| Kind | Required evidence |
+| --- | --- |
+| `engaged` | The subject is directly established as actively opposing the party in combat. At most one engagement is emitted for one subject in one combat scene. |
+| `killed` | The transcript explicitly establishes that the subject died or was killed. Damage, defeat, disappearance, or combat ending is insufficient. |
+| `fled` | The subject explicitly escapes, retreats, or otherwise leaves combat to avoid continued engagement. Movement or absence from later turns is insufficient. |
+| `captured` | The subject is explicitly taken prisoner or secured under the party's control. A grapple or temporary restraint alone is insufficient. |
+| `incapacitated` | The subject is explicitly rendered unable to continue acting without being established as killed or captured. A missed turn is insufficient. |
+
+The current transcript is the only event evidence. Campaign context and
+normalized NPC, scene-description, combat-turn, and NPC-interaction artifacts
+can ground names or control combat eligibility, but none may supply event
+evidence. An outcome may share evidence with an engagement, in which case both
+events are retained.
+
+Extraction is limited to chunks with an exact combat-scene classification. An
+exact non-combat classification produces an accepted empty list. Missing or
+mismatched classification also produces an accepted empty list and a
+`scene_classification_unavailable` warning.
+
+## Subjects, normalization, and order
+
+A subject matching the normalized NPC registry uses that registry's canonical
+display name. Unmatched hostile creatures, summoned entities, and directly
+grounded groups remain valid subjects. An unnamed homogeneous group uses the
+narrowest transcript-grounded label, such as `Orcs`, `One orc`, or `Remaining
+orcs`; the artifact never invents synthetic member identities or quantities.
+Party members, allies, neutral observers, mentioned-but-absent enemies, hazards,
+traps, and environmental effects are excluded.
+
+Normalization trims subject whitespace, canonicalizes recognized registry
+names, canonicalizes and deduplicates exact source ranges, then orders events
+by valid evidence chronology, normalized subject identity, display name, kind,
+and reference sequence. The deterministic kind tie order is `engaged`,
+`incapacitated`, `captured`, `fled`, then `killed`. Only entries with the same
+normalized name, kind, and complete canonical evidence sequence are collapsed.
+Different kinds, evidence, repeated engagement in separate scenes, and later
+outcomes remain separate. A later engagement for the same named subject is
+preserved after an earlier outcome because the artifact does not assert an
+irreversible state transition.
+
+## Non-goals
+
+The artifact has no NPC or scene ID, quantity, confidence, description,
+rationale, summary, current state, or inferred terminal outcome. It does not
+emit `active` or `unresolved`; consumers may derive an unresolved ledger view
+only when an engagement has no later explicit outcome. It never infers an
+outcome from turn absence, scene termination, initiative order, hit-point
+guesses, or other artifacts.
+
+The [JSON output contract](json-output.md) defines publication. Configuration
+keys, required generated-reference slots, and validator-chain selection are
+defined in the [configuration reference](../config.md). Implementation and
+prompt-grounding mechanics are described in the
+[D&D module internals](../internal/dnd.md).

docs/integrations/dnd-npc-artifacts.md

@@ -60,10 +60,13 @@ relationship fields.
 Only individually identifiable NPC names with transcript evidence belong in
 this artifact. Groups, generic roles, invented labels, and descriptive
 enrichment are excluded. Its source references prove registry provenance; they
-do not become evidence for a spell, interaction, or combat occurrence.
+do not become evidence for a spell, interaction, combat, or enemy-event
+occurrence.
 
 This registry can ground actor or caster names in the [spell](dnd-spell-artifacts.md)
 and [combat-turn](dnd-combat-turn-artifacts.md) artifacts. It is required to
 resolve the canonical `name` in an [NPC interaction](dnd-npc-interaction-artifacts.md).
+The [enemy-event artifact](dnd-enemy-event-artifacts.md) also uses it only for
+subject grounding and canonical display names.
 The [JSON output contract](json-output.md) defines publication, and
 [D&D module internals](../internal/dnd.md) owns pipeline mechanics.

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

@@ -74,5 +74,8 @@ Only entries with the same canonical name, kind, and complete valid evidence
 sequence are collapsed; distinct categories or evidence remain separate.
 
 See the [combat-turn artifact](dnd-combat-turn-artifacts.md) for combat-action
-occurrences and the [JSON output contract](json-output.md) for publication.
-Pipeline mechanics are described in [D&D module internals](../internal/dnd.md).
+occurrences. The [enemy-event artifact](dnd-enemy-event-artifacts.md) consumes
+only `combat_opponent` interactions as grounding; they never establish an enemy
+event or outcome. The [JSON output contract](json-output.md) defines
+publication. Pipeline mechanics are described in
+[D&D module internals](../internal/dnd.md).

docs/integrations/dnd-scene-description-artifacts.md

@@ -62,8 +62,9 @@ durable fields, or the same source range with different kind, title, or
 summary, is invalid. It does not merge adjacent ranges, alter prose, or infer
 missing scenes.
 
-The [combat-turn artifact](dnd-combat-turn-artifacts.md) uses an exact matching
+The [combat-turn artifact](dnd-combat-turn-artifacts.md) and
+[enemy-event artifact](dnd-enemy-event-artifacts.md) use an exact matching
 `combat` scene only as eligibility control; scene title, summary, and source
-reference never become combat evidence. Publication is defined by the
+reference never become their evidence. Publication is defined by the
 [JSON output contract](json-output.md); implementation details live in
 [D&D module internals](../internal/dnd.md).

docs/integrations/json-output.md

@@ -75,7 +75,8 @@ than infer a lane schema from its name. The current D&D payload contracts are
 [NPC interactions](dnd-npc-interaction-artifacts.md),
 [combat turns](dnd-combat-turn-artifacts.md),
 [item events](dnd-item-event-artifacts.md), and
-[scene descriptions](dnd-scene-description-artifacts.md).
+[scene descriptions](dnd-scene-description-artifacts.md), and
+[enemy events](dnd-enemy-event-artifacts.md).
 
 ## `manifest.json`