19 KiB
D&D Module Internals
This guide explains shared D&D implementation conventions. Module Internals owns generic typed extension mechanics; Configuration owns keys, bindings, reference syntax, and default validator chains. Pipeline Internals owns assessment/disposition and LLM Integration owns native execution.
Durable Artifact Contracts
The ten lanes have separate durable wire contracts. This guide deliberately does not repeat their JSON shapes or schemas.
| Lane | Durable contract |
|---|---|
| Spells | spell artifacts |
| NPC registry | NPC registry artifacts |
| Combat turns | combat-turn artifacts |
| Item occurrences | item-occurrence artifacts |
| Item registry | item-registry artifacts |
| NPC occurrences | NPC-occurrence artifacts |
| Scene descriptions | scene-description artifacts |
| Enemy events | enemy-event artifacts |
| Location registry | location-registry artifacts |
| Location occurrences | location-occurrence artifacts |
Family Composition
The D&D registrar composes codecs, evidence projections, typed extractors/append-order mergers/normalizers, validators, and default chains. Scene planning, extractors, and the three registry normalizers are model-backed; current mergers and remaining normalizers are deterministic. A model-backed module can still have an ordinary no-model branch. Registration does not construct engines or register prompt/schema assets.
Each model producer receives the shared native engine, prepares fixed operation inputs, and calls the common producer helper with initial request, interpretation, correction builder, and supported fallback. Static prompt dependencies match its request constants. The pipeline supplies complete candidate assessment; returning from the helper does not trigger a duplicate validator pass. Pure codecs, identities, reference resolvers, and deterministic transforms remain separate from execution integration.
Prompt Construction
Content lives beneath assets/dnd, with ordinary native declarations imported by assets/notarius.yml. The root assets package stays a content-only leaf. Declaration-relative content paths and the collection schema context replace mounted filesystems/manifests. Native declarations own output contracts and initial/correction pairs. Configuration owns public schema-root/replacement behavior.
Use the spell declaration, scene declaration, and item-normalization declaration as distinct examples. IDs in module constants/static dependencies select their qualified native resources. Embedded profile content participates in the same native load as operator resources, not registrar fallback logic.
Put each rule at its narrowest owner:
- Universal behavior belongs in shared system content.
- D&D-family and input-specific rules belong in selected shared/input files.
- Enduring domain principles belong in the initial system context.
- The initial assignment and correction assignment belong in their own messages.
- Transport shape belongs in the private response schema, not repeated prose.
Initial/correction pairs share schema/profile defaults. Follow-ups supply new guidance, not a fresh transcript/reference bundle or a manually replayed assistant. Native coordination retains the growing exchange; structural repair is separate. Private model schemas keep structure minimal and provider-compatible. Durable artifact schemas remain codec-owned contracts. Preserve supported semantic candidates for typed validation instead of silently transforming domain mistakes.
Shared content is selected by real relative paths rather than copied into modules. Message ordering/cache hints remain meaningful prompt behavior; inspect the owning declaration before changing them. Extraction generally separates reusable campaign/chunk context from lane-specific projections. Scene planning uses the full transcript; normalization uses fixed generic candidate/window presentation. Do not force those different roles into a universal prefix or snapshot prose. Native asset tests check preparation, input placement, paired contracts, and meaningful cache controls without asserting a provider-quality result.
Representative Extraction And Correction
The spell extractor uses PrepareChunkExtraction to validate source/chunk input, resolves catalog/NPC context once, and creates native artifact inputs. Its interpreter canonicalizes the private response into the existing durable value. The follow-up adds only aggregated guidance. Catalog and source validators remain domain rules; accepted empty extraction and a qualified empty fallback are different outcomes.
Other extractors keep their own mapping/identity rules rather than consolidating unlike response envelopes into a generic parser. Unknown/ambiguous contextual selections produce actionable interpretation guidance without partial output or guessed identity. Run-wide native selections reach producer, continuation, and validator requests through the operation, without changing captured configuration.
Evidence, Candidates, And Normalization
The current transcript is the sole durable evidence source. Extractors attach its source identity and canonicalize resolvable reversed endpoints by document position, not numeric unit-ID order. They order/deduplicate references without turning ordinary canonicalization into a warning or correction. Wrong-source or unresolvable citations remain detectable, not silently repaired. Campaign references and generated context can disambiguate or route work, never supply new source evidence.
Typed chains retain separate structural, source, identity/domain, durable-schema, and advisory responsibilities; Configuration owns their order and replacement rules. Extraction containment requires the entire cited span inside the current chunk after ordinary reference validation. Scene descriptions instead require the exact one-scene identity/range.
Guidance describes all currently detectable model-controlled defects using contextual names, response fields, and source ranges. It does not copy operator paths, hashes, validator keys, reason codes, or durable IDs. Shared diagnostic helpers support classified/bounded operator findings and separate model guidance. Deterministic identity/order invariants do not imply that the model owns those derived fields.
Item-holder mistakes remain semantic rejections, not synthesized holders or silent rewrites; guidance states the response's null/non-null relationship and identifies records contextually. Enemy-event extraction rejects duplicate engagement observations within one scene result; normalization intentionally combines across scenes instead. Retain these differences when sharing helpers.
Deterministic normalizers canonicalize display/evidence and source ordering and can emit cleanup observations. They run directly without synthetic requests. The three registry normalizers retain their intentional model-assisted exception.
Semantic Registry Reconciliation
NPC, item, and location normalization use ordinary functions from semanticreconcile, not a separate reconciliation engine/service.
The operation retains the incoming merged artifact separately, preprocesses
fixed originals once, and calls Prepare once. Preparation filters unusable
candidate evidence, assigns contiguous one-based request-local handles, declares
their inclusive range, and builds bounded transcript windows/material.
Candidate handles are not transcript unit IDs or durable identity. Identical
labels/evidence remain separately selectable.
The native model proposes only duplicate groups and a supplied canonical handle. Proposal assessment rejects unsafe/unknown/overlapping selections; typed application uses family policies on the original records. Each response is a complete replacement proposal, applied afresh before pipeline assessment, never a union of prior plans. Correction uses the same handle mapping/windows and adds domain guidance only.
Domain application chooses canonical display, unions evidence in source order, preserves ungrouped originals, and derives durable identity after consolidation. NPC/item identity follows the final name; locations also use final evidence to preserve same-name distinct places. Item guards prevent currency denominations from crossing or merging with non-currency records. Diagnostics and postconditions remain registry-owned; model output supplies no replacement names/evidence/IDs.
Insufficient candidates use direct assessment without native execution. Preparation limits use resolved strict/permissive terminal handling, not implicit semantic success. For supported permissive output, only compatible safe groups from the final usable proposal can advance; otherwise the retained merged input is checked as fallback. A result-less/structurally failed continuation cannot recover an earlier proposal. Source/codec/identity construction checks still apply without ordinary semantic revalidation. Strict mode and cancellation do not silently preserve a result as accepted work.
Planning, Scene Validation, And Fallback Limits
Scene planning prepares the full input once and interprets complete ordered boundaries. The pipeline materializes/assesses plans before lane work. Supported permissive planning can construct one unannotated whole-source plan through normal source-addressing; it does not invent classifications, prose, or bounded request sizes.
Scene descriptions have a stricter intrinsic requirement: one usable current-scene artifact. Permissive construction can use only a final usable candidate satisfying shape, source identity/range, and downstream invariants. It cannot fabricate a kind/title/summary, emit an invalid empty list, or retrieve an earlier candidate. Codec-valid empty collections are supported for the list extraction families, but do not generalize to every producer.
Combat semantics is an opt-in independent combat/noncombat review of scene-local transcript input, without the proposed kind. Deterministic interpretation compares classification to the candidate. It does not evaluate title, summary, noncombat subtype, or boundary coherence. One direct native execution returns a judgment or unavailable assessment with causes; it has no producer continuation loop. Configuration owns selection.
Combat-semantics provider evaluation
The human-reviewed synthetic corpus records proposed kind, expected classification, and rationale. Offline fixture/ fake-provider tests verify contracts, not production classification quality. Live evaluation remains explicitly invoked maintainer work, not a default test.
Before proposing default-chain inclusion:
- Record commit/content revisions, provider/model/profile/execution settings, actual native repair selection, repetitions, and date. Do not change expected judgments just to agree with provider output; corpus corrections need independent review.
- Use a disposable explicit driver with the production typed validator and shared native engine. Materialize corpus units into one chunk and construct the matching scene identity/range/proposed kind. Title/summary can be placeholders: they are not reviewer inputs. Commit no credentials or always-on live test.
- Compare classification and deterministic approval/rejection separately. Retain false acceptance, false rejection, and unavailable/execution-failure cases.
- Evaluate producer correction separately through the configured full chain, including the final permitted response. Native structural repair is not an application semantic turn.
- Use requested capture and explicit bypass/refresh rather than cached acceptance. Compare added executions, latency, and native usage/terminal coverage with and without the validator; preserve unknown usage instead of inventing totals.
Default-chain review must weigh quality, correction success, availability, calls, latency, and cost together. Structural success alone does not justify inclusion.
Generated References And Grounding
Normalized artifacts reach later steps through typed compatibility-checked handoffs. Consumers resolve supplied bytes into immutable contextual projections. Valid fallback context remains usable in the current run but disables reuse for actual consumers and their dependents; unrelated work is unaffected.
NPC/item selectors are names-only; location selectors include the name and ordered registry references needed to distinguish same-name places. Consumers resolve selections locally to the unchanged durable ID/name pair. Unknown or ambiguous selections do not yield guessed IDs or partial occurrence results. Registry evidence disambiguates identity but never replaces each occurrence's own current-transcript citations.
Scene projections route combat without conveying scene prose as evidence. Combat-turn projections retain actor/turn kind; NPC-occurrence projections select combat-opponent names/kinds for enemy grounding. These remain guidance, not event evidence.
Lane-Specific Rules
The following differences are intentional and should remain explicit when a shared helper changes.
Shared D&D text comparison is identified by dnd.text_comparison.v1. Any
semantic change requires an explicit policy-version review for every affected
identity, mapping, normalization, and validator policy. This is domain policy,
not accepted-result cache identity.
| Lane | Intentional behavior |
|---|---|
| Spells | May use a spell-catalog overlay and optional NPC grounding; the catalog validator supplies domain-specific semantic checks. |
| NPC registry | Establishes transcript-grounded NPC identities, including factual third-party mentions, without assigning occurrence categories. It does not consume an NPC registry, and its normalizer is the LLM-assisted reconciliation exception described above. |
| Combat turns | Requires a scene-description artifact. It calls the LLM only for an exact combat classification; non-combat paths directly assess an empty result, while missing or mismatched classifications also retain a bounded warning. Optional NPC grounding never becomes evidence. |
| Item occurrences | Requires the normalized item registry for exact deterministic grounding at extraction and normalization. Campaign context may disambiguate, but the registry never becomes occurrence evidence. |
| Item registry | Produces source-grounded item types and unique designations. Its LLM-assisted reconciliation is proposal-only, preserves distinct currency denominations and item types, and does not create per-instance identities. |
| NPC occurrences | Requires the normalized NPC registry at extraction and normalization, using it for canonical actor grounding only. It separately emits cited current-transcript occurrence facts, including mentioned, rather than deriving them from registry provenance. |
| 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-occurrence 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. |
| Location registry | Produces a source-anchored, session-scoped registry from stable proper names or unique in-world designations. 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. Its durable occurrence categories distinguish explicit speculation from unsupported inference; 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: combat turns and scene descriptions. The enemy-event contract defines its durable semantics; Configuration owns its selectable bindings and validation chains.
Focused Verification
Walk extensions through real spell extraction, item reconciliation, scene planning, and native semantic validation. Retain family codec/identity/source/holder/eligibility regressions, contextual registry projection tests, and assembled handoffs. Dependency registration and native asset tests verify static resources and preparation without behavioral asset registration. Use real kits with native provider fakes; no ordinary test needs credentials, paid inference, or a private completion API. Development owns repository-wide validation.