Harmonize D&D artifact contracts
This commit is contained in:
@@ -1,20 +1,38 @@
|
||||
# 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.
|
||||
This contract defines the durable occurrence list produced by
|
||||
`dnd/npc-interactions`. It records discrete, source-grounded interactions with
|
||||
NPCs already present in a normalized registry; it does not extend that registry
|
||||
or summarize the session.
|
||||
|
||||
## Identity And JSON
|
||||
## Identity and compatibility
|
||||
|
||||
- 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`
|
||||
| Property | Value |
|
||||
| --- | --- |
|
||||
| Artifact kind | `dnd/npc-interaction-list` |
|
||||
| Schema ID | `notarius.dnd.npc_interactions` |
|
||||
| Schema name | `notarius_dnd_npc_interactions_v1` |
|
||||
| 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`:
|
||||
`v1` is a strict JSON object with required `interactions`; the array may be
|
||||
empty. Interaction and source-reference objects reject unknown fields. A future
|
||||
incompatible shape requires a new schema version.
|
||||
|
||||
## Wire shape
|
||||
|
||||
Each interaction has these required fields:
|
||||
|
||||
| Field | Contract |
|
||||
| --- | --- |
|
||||
| `name` | Non-empty canonical display name from the required NPC registry. |
|
||||
| `kind` | One of the interaction categories below. |
|
||||
| `source_refs` | One or more transcript evidence ranges. |
|
||||
|
||||
Each source reference has exactly `source_id`, `start_unit_id`, and
|
||||
`end_unit_id`. It identifies an inclusive range in the current transcript;
|
||||
unit IDs are positive and the start may not follow the end. Extraction evidence
|
||||
for an interaction is confined to its accepted chunk.
|
||||
|
||||
```json
|
||||
{
|
||||
@@ -30,119 +48,31 @@ array may be empty. Each item has exactly `name`, `kind`, and `source_refs`:
|
||||
}
|
||||
```
|
||||
|
||||
`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.
|
||||
During extraction, every range must be wholly contained in the current accepted
|
||||
chunk. This prevents a candidate from citing valid units that were not presented
|
||||
to that extraction call.
|
||||
Unknown fields are rejected.
|
||||
|
||||
## Interaction Categories
|
||||
|
||||
`kind` is exactly one of:
|
||||
## Interaction categories
|
||||
|
||||
| Kind | Meaning |
|
||||
| --- | --- |
|
||||
| `mentioned` | The NPC is referred to, but is not established as present or communicating in the evidenced passage. |
|
||||
| `noncombat_presence` | The NPC is present and relevant to the passage but does not meaningfully participate in dialogue or combat. |
|
||||
| `dialogue` | The NPC speaks, responds, or is directly engaged in a meaningful non-combat exchange. |
|
||||
| `mentioned` | The NPC is referred to but is not established as present or communicating. |
|
||||
| `noncombat_presence` | The NPC is present and relevant without meaningful dialogue or combat participation. |
|
||||
| `dialogue` | The NPC speaks, responds, or meaningfully participates in a non-combat exchange. |
|
||||
| `combat_ally` | The NPC actively participates in combat on the party's side. |
|
||||
| `combat_opponent` | The NPC actively participates in combat against the party. |
|
||||
| `other` | The transcript clearly establishes a direct NPC occurrence that fits none of the preceding kinds. |
|
||||
| `other` | A clearly evidenced direct occurrence not covered by another category. |
|
||||
|
||||
`other` is a residual category for positively evidenced activity, not a fallback
|
||||
for uncertain classification. When activities overlap, active combat
|
||||
participation outranks dialogue, presence, and mention; dialogue outranks
|
||||
non-combat presence and mention; and non-combat presence outranks mention.
|
||||
Combat alignment is not resolved by precedence: a meaningful change between
|
||||
ally and opponent creates separate occurrences.
|
||||
The categories do not represent motives, relationships, state, or events that
|
||||
the cited transcript does not establish. An `other` entry is not a substitute
|
||||
for uncertain classification.
|
||||
|
||||
These categories do not encode summaries, relationships, state, motives, or
|
||||
unobserved events.
|
||||
## Identity, evidence, and order
|
||||
|
||||
## Occurrence Boundaries And Ordering
|
||||
The required normalized [NPC artifact](dnd-npc-artifacts.md) resolves `name`.
|
||||
Registry references are provenance only and never replace an interaction's own
|
||||
evidence. Normalization canonicalizes recognized registry names, orders and
|
||||
deduplicates exact source references, then orders interactions by valid source
|
||||
chronology, NPC comparison identity, display name, kind, and reference sequence.
|
||||
Only entries with the same canonical name, kind, and complete valid evidence
|
||||
sequence are collapsed; distinct categories or evidence remain separate.
|
||||
|
||||
One occurrence represents one NPC, one kind, and one locally coherent passage
|
||||
within one accepted chunk. Repeated evidence belongs to the same occurrence
|
||||
only while it supports the same uninterrupted activity. A kind change, combat
|
||||
alignment change, intervening scene or meaningful absence, or transition from
|
||||
mention to presence starts a new occurrence. Occurrences never span chunks, and
|
||||
merge or normalization never semantically combines nearby, overlapping, or
|
||||
cross-chunk records.
|
||||
|
||||
Normalization orders records by:
|
||||
|
||||
1. earliest valid source-document position;
|
||||
2. the NPC identity comparison key;
|
||||
3. the exact canonical NPC display name;
|
||||
4. interaction kind in lexical order; and
|
||||
5. the complete canonical source-reference sequence, ordered by source ID and
|
||||
the source-document positions of each range's start and end.
|
||||
|
||||
Only records with identical canonical names, kinds, and complete valid evidence
|
||||
sequences are duplicates. Different categories, ranges, or separately grounded
|
||||
occurrences remain separate.
|
||||
|
||||
## 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 canonicalizes source references
|
||||
and applies the ordering and exact-duplicate rules above.
|
||||
|
||||
## 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 runs normalized invariants after
|
||||
registry validation and before source-reference and schema validation, followed
|
||||
by relatedness. Normalizer and relatedness warnings are bounded and end with an
|
||||
omission summary when necessary. 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
|
||||
[complete D&D example](../../examples/dnd-complete.config.yml).
|
||||
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).
|
||||
|
||||
Reference in New Issue
Block a user