290 lines
19 KiB
Markdown
290 lines
19 KiB
Markdown
# D&D Module Internals
|
|
|
|
This guide explains shared D&D implementation conventions.
|
|
[Module Internals](modules.md) owns generic typed extension mechanics;
|
|
[Configuration](../config.md) owns keys, bindings, reference syntax, and default
|
|
validator chains. [Pipeline Internals](pipeline.md) owns assessment/disposition
|
|
and [LLM Integration](llm.md) 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](../integrations/dnd-spell-artifacts.md) |
|
|
| NPC registry | [NPC registry artifacts](../integrations/dnd-npc-registry-artifacts.md) |
|
|
| Combat turns | [combat-turn artifacts](../integrations/dnd-combat-turn-artifacts.md) |
|
|
| Item occurrences | [item-occurrence artifacts](../integrations/dnd-item-occurrence-artifacts.md) |
|
|
| Item registry | [item-registry artifacts](../integrations/dnd-item-registry-artifacts.md) |
|
|
| NPC occurrences | [NPC-occurrence artifacts](../integrations/dnd-npc-occurrence-artifacts.md) |
|
|
| Scene descriptions | [scene-description artifacts](../integrations/dnd-scene-description-artifacts.md) |
|
|
| Enemy events | [enemy-event artifacts](../integrations/dnd-enemy-event-artifacts.md) |
|
|
| Location registry | [location-registry artifacts](../integrations/dnd-location-registry-artifacts.md) |
|
|
| Location occurrences | [location-occurrence artifacts](../integrations/dnd-location-occurrence-artifacts.md) |
|
|
|
|
## Family Composition
|
|
|
|
The [D&D registrar](../../internal/modules/dnd/register/register.go) 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](../../assets/dnd/), with ordinary native
|
|
declarations imported by [assets/notarius.yml](../../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](../config.md#prompt-output-contracts-and-schemas) owns public
|
|
schema-root/replacement behavior.
|
|
|
|
Use the [spell declaration](../../assets/dnd/spells/prompts/prompt.yaml),
|
|
[scene declaration](../../assets/dnd/scenes/prompts/prompt.yaml), and
|
|
[item-normalization declaration](../../assets/dnd/item-registry/normalize/prompts/prompt.yaml)
|
|
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](../../internal/modules/dnd/extract/spells/extractor.go)
|
|
uses [PrepareChunkExtraction](../../internal/modules/dnd/shared/extraction_inputs.go)
|
|
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](../config.md#production-validator-keys-and-default-chains)
|
|
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](../../internal/modules/dnd/shared/diagnostics/diagnostics.go)
|
|
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](../../internal/modules/dnd/normalize/npcregistry/normalizer.go),
|
|
[item](../../internal/modules/dnd/normalize/itemregistry/normalizer.go), and
|
|
[location](../../internal/modules/dnd/normalize/locationregistry/normalizer.go)
|
|
normalization use ordinary functions from
|
|
[semanticreconcile](../../internal/framework/semanticreconcile/preparation.go),
|
|
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](../../internal/framework/semanticreconcile/proposal.go)
|
|
rejects unsafe/unknown/overlapping selections; typed
|
|
[application](../../internal/framework/semanticreconcile/application.go) 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](../../internal/modules/dnd/chunk/scenes/chunker.go) 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](../../internal/modules/dnd/extract/scenedescriptions/extractor.go)
|
|
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](../../internal/modules/dnd/validate/scenedescriptions/combat_semantics/validator.go)
|
|
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](../config.md#production-validator-keys-and-default-chains) owns selection.
|
|
|
|
### Combat-semantics provider evaluation
|
|
|
|
The [human-reviewed synthetic corpus](../../internal/modules/dnd/validate/scenedescriptions/combat_semantics/testdata/evaluation_cases.json)
|
|
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:
|
|
|
|
1. 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.
|
|
2. 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.
|
|
3. Compare classification and deterministic approval/rejection separately. Retain
|
|
false acceptance, false rejection, and unavailable/execution-failure cases.
|
|
4. Evaluate producer correction separately through the configured full chain,
|
|
including the final permitted response. Native structural repair is not an
|
|
application semantic turn.
|
|
5. 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](../integrations/dnd-location-occurrence-artifacts.md#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](../integrations/dnd-combat-turn-artifacts.md) and
|
|
[scene descriptions](../integrations/dnd-scene-description-artifacts.md).
|
|
The [enemy-event contract](../integrations/dnd-enemy-event-artifacts.md)
|
|
defines its durable semantics; [Configuration](../config.md) owns its
|
|
selectable bindings and validation chains.
|
|
|
|
## Focused Verification
|
|
|
|
Walk extensions through real [spell extraction](../../internal/modules/dnd/extract/spells/extractor_test.go),
|
|
[item reconciliation](../../internal/modules/dnd/normalize/itemregistry/normalizer_test.go),
|
|
[scene planning](../../internal/modules/dnd/chunk/scenes/chunker_test.go), and
|
|
[native semantic validation](../../internal/modules/dnd/validate/scenedescriptions/combat_semantics/native_execution_test.go).
|
|
Retain family codec/identity/source/holder/eligibility regressions, contextual
|
|
registry projection tests, and [assembled handoffs](../../internal/modules/integration/).
|
|
[Dependency registration](../../internal/modules/dnd/register/dependencies_test.go)
|
|
and [native asset tests](../../assets/) 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](../development.md#validation) owns repository-wide validation.
|