Refresh typed module and D&D contributor recipes

This commit is contained in:
2026-11-22 06:48:55 +00:00
parent 41f6079040
commit aa4ce04683
3 changed files with 369 additions and 467 deletions

View File

@@ -1,9 +1,10 @@
# D&D Module Internals
This guide records the conventions shared by the production D&D module family.
It complements [Module Internals](modules.md), which owns generic registration
and extension mechanics, and [Configuration](../config.md), which owns the
selectable keys, bindings, reference syntax, and default validator chains.
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
@@ -25,317 +26,222 @@ does not repeat their JSON shapes or schemas.
## Family Composition
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, location, and
item-registry 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. The registry normalizers
use `single_response_v1`, forwarding corrections to their reconciliation
completion and retaining the accepted raw proposal only as an owned model
candidate. When deterministic proposal safety or typed application rejects a
group, they provide separate model-facing prose for a corrective module retry;
internal issue categories, reason codes, and operator messages remain
diagnostic-only. Configuration remains the canonical owner of the exact keys,
profile precedence, and validator order.
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.
Private structured-LLM response schemas are deliberately minimal. They reject
invalid JSON structure, missing required fields, incompatible types, and
unknown fields, while preserving semantic candidates for deterministic
validation. Do not promote a private response envelope into a durable schema;
the contracts above define durable data.
A D&D producer that declares `single_response_v1` forwards any supplied
semantic correction to its structured completion and returns an owned copy of
that completion's exact validated raw response as its model candidate. It does
not serialize normalized artifacts to create that candidate, so deterministic
identity, evidence, warning, and durable-schema behavior remains separate from
the model transport material.
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
D&D LLM-facing content lives beneath `assets/dnd/`. Each module contributes a
local `prompt.yaml` declaration and `instructions.md`; input-specific files
such as a catalog, registry, grounding projection, or candidate collection are
local only when that module needs them. New extractor content uses its feature
subtree, while families with both extraction and normalization content use their
`extract` and `normalize` subtrees. Shared visual-provenance fragments use
the `common-dnd-` prefix. Production lane code belongs with its D&D codec,
extractor, normalizer, and validator packages; registry projections and
identity helpers remain in their owning entity packages rather than in a
consumer lane.
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.
The owning module’s manifest is the source of truth for which local and shared
assets are selected, their mount paths, their message order, cache controls,
and the files included in its prompt fingerprint. Shared fragments belong to
the D&D shared implementation and are selected by name rather than copied into
module directories. The root `assets` package is a content-only boundary; its
physical ownership and rationale are defined by
[ADR-0011](../adr/0011-centralize-llm-assets.md).
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 the shared system asset;
- D&D-family behavior belongs in a selected `common-dnd-` asset;
- rules for an input projection belong with that input asset;
- lane-specific policy belongs in the module’s `instructions.md`; and
- transport-envelope shape belongs in the private response schema.
- 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.
A rule is eligible for the system prompt only when every D&D LLM prompt needs
it regardless of lane, inputs, or response shape. Module instructions must not
repeat rules selected from shared assets or schemas. Reintroduce such repetition
only after observational evaluation with representative transcripts shows that
it improves results at the intended target models and cost; structural prompt
tests alone are not that evidence.
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.
Every maintained D&D LLM prompt selects `dnd-extraction` as its default
profile. The D&D registrar registers the fallback, while an operator can
replace it with a complete profile of the same ID from the configured PromptKit
source. Deployment profile selection is documented in
[Configuration](../config.md#promptkit-profiles).
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.
The D&D transcript assets have distinct consumers. Scene chunking consumes the
complete-session `common-dnd-transcript-full.md`, while extraction prompts
consume the current-chunk `common-dnd-transcript-chunk.md`. NPC, location, and
item normalization instead mount the generic semantic-reconciliation
candidate and transcript-window presentation assets. Player, party, glossary,
and compatible campaign references provide disambiguating context only when
declared by the active prompt; they never establish evidence. Reference
material is canonically ordered before rendering so equivalent inputs remain
stable.
## Representative Extraction And Correction
Extraction prompts render the common system and identity messages first, then
cached campaign references and the cached chunk transcript. Evidence policy and
any lane-specific registry, catalog, or grounding projection follow that
prefix. The final module instructions message is ephemeral. This keeps the
reusable extraction prefix identical while preserving the lane-specific suffix.
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.
Scene chunking intentionally uses a different order: system, cached campaign
references, uncached module instructions, then the final ephemeral full
transcript. Entity normalization also has its own order: D&D system, mandatory
generic protocol, ephemeral domain semantic instructions, generic candidate
presentation, and final ephemeral generic transcript windows. These orders and
cache controls are prompt behavior; change them only through the owning
manifest and prompt declaration.
NPC, item, and location registry reconciliation translate shared proposal
safety categories into bounded prose that references only the response-local
duplicate-group ordinals and candidate handles. Item reconciliation appends its
typed rule that currency may be consolidated only with aliases of the same
denomination and never with non-currency items. The next normalize attempt
receives that prose with the exact defective proposal under the shared
replacement-request protocol. Structurally invalid output has no valid proposal
candidate and receives a fresh feedback-free attempt instead. If the stage
budget is exhausted, safe groups stay applied, unsafe groups stay separate, and
one fallback warning summarizes the final defect without raw model content.
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 only durable evidence source. Extractors assign
the current source identity and losslessly order any reversed range whose two
endpoints resolve in that source, using transcript position rather than numeric
unit-ID order. They then canonically order ranges and remove exact duplicates.
This routine canonicalization does not request a retry or emit a warning.
Unresolvable or wrong-source ranges remain unchanged for validators to reject.
Campaign context and generated artifacts may ground names or control routing,
but they never establish evidence for a D&D result.
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.
Default chains keep responsibilities separate: structural validators assess the
candidate, source-reference validators resolve cited ranges against the current
source and require extraction evidence to stay within the current chunk,
durable-schema validation checks an approved representation, and
relatedness validators report advisory evidence concerns. The configured order
is documented in
[Configuration](../config.md#production-validator-keys-and-default-chains).
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.
The optional `extract/dnd/scene-descriptions/combat_semantics` validator is the
D&D family's LLM-backed review of only combat versus non-combat classification.
It selects the shared combat-policy prompt fragment and asks the model to
classify the current chunk independently as `combat` or `non_combat` without
receiving the proposed scene kind. Deterministic code compares that
classification with the proposed kind and either approves it or produces the
appropriate correction guidance. This keeps every schema-valid classification
interpretable and avoids anchoring the reviewer on the producer's answer. It
does not assess titles, summaries, non-combat subtype, or scene boundaries;
deferred boundary-coherence review remains separate. It is opt-in;
[Configuration](../config.md) owns selection and retry/failure behavior.
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.
### Combat-semantics provider evaluation
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.
The human-reviewed corpus at
`internal/modules/dnd/validate/scenedescriptions/combat_semantics/testdata/evaluation_cases.json`
owns the proposed kind, expected combat classification, and reviewer rationale
for each synthetic case. Its package test validates the fixture contract only.
Provider evaluation remains an explicit maintainer operation and must not be
added to the default offline test suite.
Use the following protocol before proposing default-chain inclusion:
1. Record the Notarius commit, prompt and schema fingerprints, provider, model,
profile settings, reasoning effort, structural-repair setting, number of
repetitions, and evaluation date before collecting results. Do not revise
expected classifications merely to agree with provider output; a substantive
corpus correction requires independent human review.
2. Exercise the production validator construction and prompt assets from an
explicitly invoked, disposable evaluation driver or test in the validator
package. For each corpus case, construct transcript source units from the
listed IDs and text, assign matching per-unit source references, and use
`source.MaterializeChunkPlan` with one range spanning those units. Construct
exactly one scene whose ID and source range match that chunk and whose kind
is the case's `proposed_kind`; title and summary may use fixed placeholders
because the validator neither receives nor evaluates them. Invoke the typed
validator at extract stage through the production registry and scheduled LLM
client. Do not commit provider credentials, generated source material, or an
always-on live test.
3. Compare the model classification with `expected_classification`, then verify
that its deterministic comparison with `proposed_kind` yields the expected
approval or rejection direction.
Record an unexpected approval of an expected rejection as a false
acceptance, an unexpected rejection of an expected approval as a false
rejection, and any validator execution failure separately from semantic
accuracy. Retain per-case results so repeated trials and systematic failure
modes remain visible.
4. Evaluate producer correction separately with representative complete
scene-description runs configured as shown in
[Configuration](../config.md#production-validator-keys-and-default-chains).
For every initial semantic rejection, record whether the next producer
attempt returns the requested combat status and is approved. Do not count a
PromptKit structural repair as a producer-correction attempt.
5. Run the correction evaluation with debug capture enabled and without reused
extraction checkpoints. Record added validator and producer calls, elapsed
latency, and cumulative prompt, completion, cached, and total token usage
from the debug attempt records. Compare these values with an otherwise
identical run whose scene-description chain omits the semantic validator.
The default-chain review must consider classification error, false acceptance,
false rejection, execution failure, producer-correction success, added calls,
latency, and token use together. A structurally successful provider run alone
is not evidence that the validator should become a default.
Every producer-correctable D&D rejection describes all currently detectable
corrections in transcript-grounded domain terms, using contextual names,
model-owned artifact fields, and source segment ranges when useful. Validators
collect independent record defects in one pass so one retry does not merely
reveal the next issue. Shared D&D diagnostic helpers keep repeated rules and
record descriptions stable, de-duplicated, and bounded; each artifact family
continues to own the semantic rule and its prose.
Operator diagnostics and model guidance are separate products of the same
assessment. Operator messages may use typed paths, reason details, and opaque
application identities. Correction guidance must not copy those messages or
ask the model to reproduce durable entity IDs, hashes, validator module keys,
reason codes, or Go field paths. A registry-normalization rejection instead
speaks in terms of the duplicate-group proposal response the normalizer can
actually revise. Normalization-only deterministic invariants retain useful
operator detail but do not imply that a model controls derived ordering or
identity. Only bounded actionable semantic guidance is eligible for a
correction prompt.
Private LLM schemas use simple enums for closed categorical fields when the
provider-compatible shape can express the rule directly. Deterministic typed
validators retain the same checks as defense in depth and for non-LLM
producers. Private schemas keep every property required and avoid optional
properties, `uniqueItems`, and conditional cross-field logic.
Item-occurrence shape validation groups repeated holder mistakes by occurrence
kind and gives the producer the required JSON null/non-null relationship. It
identifies affected records by contextual item name and cited transcript range,
never by the deterministically attached durable item ID. Holder mistakes remain
semantic rejections rather than silent rewrites because changing a holder can
also change the meaning of the occurrence kind.
Enemy-event extraction additionally rejects a second `engaged` observation for
the same comparison identity within one scene-scoped result. Normalization may
combine results from distinct scenes, so it intentionally does not apply that
rule. Configuration owns the exact validator key and chain position.
Extraction source-reference validators share one full-span chunk-containment
policy. After ordinary reference validity succeeds, the policy resolves both
endpoints through document order and requires every source unit in the
inclusive range to be present in the current chunk. It does not assume numeric
unit-ID ordering, mutate input, or weaken wrong-source and unresolved-reference
validation. Scene descriptions remain separate because their validator owns an
exact one-scene range contract rather than general extraction containment.
Normalizers are deterministic for spells, combat turns, item occurrences, NPC
occurrences, scene descriptions, enemy events, and location occurrences. They
canonicalize display values and evidence, use source-document order for stable
output, and emit bounded normalization observations for changes or collapsed duplicates. NPC,
item, and location registry normalizers are intentional exceptions: each first
produces a deterministic candidate set, then may use a bounded structured-LLM
proposal to reconcile identity groups.
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
The three registry normalizers instantiate the domain-neutral
`internal/framework/semanticreconcile` engine with default bounds. Each
eligible candidate receives a contiguous, one-based `candidate_number` for that
request, and candidate material declares the exact inclusive range. The model
sees that handle, the candidate label and source-free evidence ranges, plus
bounded transcript windows; it returns only duplicate
groups of supplied handles and one supplied canonical handle per group. It
never returns names, evidence, durable IDs, or replacement records. Identical
labels and evidence remain independently selectable because their handles are
distinct. Transcript unit `id` values and evidence `start_unit_id` and
`end_unit_id` values are source positions in a separate namespace and are
never valid candidate numbers.
[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 generic core owns the mandatory handle protocol, candidate and transcript
presentation, the private response schema, source-reference validation,
candidate and combined-material limits, structured completion, proposal
assessment, stable group ordering, and typed plan-application mechanics. The
D&D prompt contributes its system message and registry-specific semantic
instructions. The generic registrar registers the shared prompt and schema;
the D&D registrar registers each consuming prompt and the fallback profile.
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.
Fewer than two eligible candidates skips the LLM without a semantic warning.
An exceeded bound also skips the call and preserves the deterministic
preprocessed registry, adding the registry's bounded fallback warning. Invalid
structured output or discarded proposal groups use the normalizer's existing
retry contract; retry exhaustion preserves the safe deterministic or
partially applied result and emits its bounded fallback warning. Provider,
transport, cancellation, and context-material failures remain execution
errors.
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.
Application remains typed and registry-owned. All three policies select the
canonical member's normalized display name, union member evidence in source
order, preserve ungrouped records, and derive durable identity only after
consolidation. NPC IDs derive from the final name. Item IDs also derive from
the final name, and a typed guard prevents currency aliases from crossing
denominations or mixing currency with non-currency records. Location IDs
derive from the final name and final evidence, preserving same-name,
parent/child, and distinct physical-place identities. Registry warning scopes,
reason codes, and postconditions remain outside the generic core.
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 D&D artifacts can be handed to a later step through a generated
reference binding. The framework verifies artifact compatibility and retains
producer provenance; consumers resolve the handed-off artifact into an
immutable, validated projection for each operation. External files are checked
during preparation, while generated artifacts are resolved at the handoff.
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 and item registry consumers receive names-only grounding. Location
consumers receive a contextual selector containing the canonical name and the
registry references needed to distinguish same-name places. The calling module
resolves those supplied selections locally and maps them into the unchanged
durable ID/name pair; an unknown or ambiguous selection rejects the complete
occurrence result rather than accepting a partial mapping. The NPC registry
additionally supplies names-only actor grounding to spells, combat turns, and
enemy events.
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.
Registry references establish a registry identity and may disambiguate a
selection, but never become occurrence evidence. Each occurrence keeps its own
current-transcript source references, even when it was grounded through the
same registry record.
Scene descriptions are eligibility-only projections: they retain current-chunk
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 occurrences to `combat_opponent` names and kinds.
These projections are guidance only and never event evidence.
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
@@ -344,14 +250,14 @@ 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; helper source is not a
checkpoint fingerprint.
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; exact non-combat classifications return an accepted empty result, while missing or mismatched classifications return an empty result with a bounded warning. Optional NPC grounding never becomes evidence. |
| 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. |
@@ -370,11 +276,14 @@ selectable bindings and validation chains.
## Focused Verification
When changing D&D behavior, test the affected codec, extractor, normalizer,
validator, prompt-asset manifest, and registry projection. Also test generated
handoffs at the integration boundary and run the full D&D module suite:
~~~sh
go test ./internal/modules/dnd/...
go test ./internal/modules/integration/...
~~~
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.