115 lines
5.1 KiB
Markdown
115 lines
5.1 KiB
Markdown
# 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-occurrence 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 collapses surrounding and repeated internal whitespace in subject
|
|
display values, 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).
|