eric/notarius
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Document D&D location tracking contracts

Browse Source
This commit is contained in:
Eric Rakestraw
2026-08-04 00:51:43 +00:00
parent 9c5e3cff14
commit d52387c1f7
7 changed files with 228 additions and 42 deletions
Download Patch File Download Diff File Expand all files Collapse all files

44
docs/internal/dnd.md
View File

@@ -7,7 +7,7 @@ selectable keys, bindings, reference syntax, and default validator chains.
## Durable Artifact Contracts
The seven lanes have separate durable wire contracts. This guide deliberately
The nine lanes have separate durable wire contracts. This guide deliberately
does not repeat their JSON shapes or schemas.
| Lane | Durable contract |
@@ -19,6 +19,8 @@ does not repeat their JSON shapes or schemas.
| NPC interactions | [NPC-interaction artifacts](../integrations/dnd-npc-interaction-artifacts.md) |
| Scene descriptions | [scene-description artifacts](../integrations/dnd-scene-description-artifacts.md) |
| Enemy events | [enemy-event artifacts](../integrations/dnd-enemy-event-artifacts.md) |
| Locations | [location artifacts](../integrations/dnd-location-artifacts.md) |
| Location occurrences | [location-occurrence artifacts](../integrations/dnd-location-occurrence-artifacts.md) |
## Family Composition
@@ -26,9 +28,9 @@ The D&D registrar registers the family’s artifact codecs, extractors, typed
append-order mergers, normalizers, validators, prompt assets, fallback LLM
profile asset, and default validator chains. Each extractor and normalizer has
a stable module spec, explicit execution class, strict option decoding, and a
typed builder. Scene chunking, every extractor, and NPC normalization are
registered as `llm_backed`; the remaining current D&D mergers and normalizers
are `deterministic`. The metadata is available to catalog inspection and
typed builder. Scene chunking, every extractor, NPC normalization, and location
normalization are registered as `llm_backed`; the remaining current D&D mergers
and normalizers are `deterministic`. The metadata is available to catalog inspection and
resolved-pipeline debug data and determines which selected bindings inherit the
pipeline profile. Configuration remains the canonical owner of the exact keys,
profile precedence, and validator order.
@@ -42,10 +44,10 @@ the contracts above define durable data.
## Prompt Construction
D&D extractors assemble prompts from an ordered manifest of shared and
module-owned assets. Reuse the shared D&D system, evidence, identity,
reference, and transcript assets instead of copying their text into individual
modules. A manifest’s declared sequence, including cache-control placement, is
part of the prompt behavior.
module-owned assets. The location extractor and occurrence extractor reuse the
shared D&D system, evidence, identity, reference, and transcript assets instead
of copying their text into individual modules. A manifest’s declared sequence,
including cache-control placement, is part of the prompt behavior.
Every maintained D&D LLM prompt selects `dnd-extraction` as its default
profile. The D&D registrar embeds that fallback profile with the maintained
@@ -72,7 +74,9 @@ remains stable.
The other D&D LLM prompts intentionally follow different patterns. Scene
chunking has no sibling extraction lane with which to share its full transcript,
so it renders campaign references before its task and instructions, then places
the cacheable full transcript last. NPC normalization keeps its task and
the cacheable full transcript last. NPC and location normalization share the
entity-reconciliation response schema and safety boundary while retaining their
own task and identity rules. NPC normalization keeps its task and
cacheable instructions before the candidate collection, followed by the
cacheable transcript windows: candidates must be available before their
supporting evidence is evaluated, and those windows are not a cross-lane
@@ -108,13 +112,14 @@ combine results from distinct scenes, so it intentionally does not apply that
rule. Configuration owns the exact validator key and chain position.
Normalizers are deterministic for spells, combat turns, item events, NPC
interactions, scene descriptions, and enemy events. They canonicalize display
interactions, scene descriptions, enemy events, and location occurrences. They canonicalize display
values and evidence, use source-document order for stable output, and issue
bounded warnings for changes or collapsed duplicates. The NPC normalizer is
the intentional exception: it first produces a deterministic candidate set,
then uses a bounded structured-LLM proposal to reconcile identity groups.
Invalid or unusable proposals retain the deterministic result and surface retry
or fallback diagnostics; the model does not directly replace durable records.
bounded warnings for changes or collapsed duplicates. The NPC and location
normalizers are intentional exceptions: each first produces a deterministic
candidate set, then may use a bounded structured-LLM proposal to reconcile
identity groups. Invalid or unusable proposals retain the deterministic result
and surface retry or fallback diagnostics; the model does not directly replace
durable records.
## Generated References And Grounding
@@ -130,8 +135,11 @@ they do not supply evidence. Scene-description registries are eligibility-only
projections: they retain the current chunk’s classification data, not scene
prose or evidence, and exist to route combat extraction. Enemy-event extraction
also projects combat turns to `actor` and `turn_kind` and filters NPC
interactions to `combat_opponent` names and kinds. These compact projections,
like NPC grounding, are source-free guidance and never event evidence.
interactions to `combat_opponent` names and kinds. Location registries project
ordered `{id, name}` pairs to location-occurrence extraction and normalization;
exact ID/name matching keeps same-name locations distinguishable. These compact
projections, like NPC grounding, are source-free guidance and never event
evidence.
## Lane-Specific Rules
@@ -147,6 +155,8 @@ shared helper changes.
| NPC interactions | Requires the normalized NPC registry at extraction and normalization, using it for canonical actor grounding only. |
| Scene descriptions | Produces the classifications consumed by combat routing; it does not consume an NPC registry or provide evidence for combat artifacts. |
| Enemy events | Requires NPC, scene-description, combat-turn, and NPC-interaction artifacts. It calls the LLM only for an exact `combat` classification, records ordered observations rather than terminal state, and normalizes recognized names through the NPC registry while preserving grounded collective labels. |
| Locations | Produces a source-anchored, session-scoped registry. Its LLM-assisted reconciliation is proposal-only and never collapses same-name places without validated identity and evidence rules. |
| Location occurrences | Requires the normalized location registry for both extraction and normalization. It classifies only transcript-established occurrences as visited, planned, recalled, or mentioned; the deterministic normalizer enforces exact registry grounding and never turns registry provenance into occurrence evidence. |
The combat and scene-description contracts describe their exact handoff and
empty-result behavior in more detail: