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 # D&D Module Internals
This guide records the conventions shared by the production D&D module family. This guide explains shared D&D implementation conventions.
It complements [Module Internals](modules.md), which owns generic registration [Module Internals](modules.md) owns generic typed extension mechanics;
and extension mechanics, and [Configuration](../config.md), which owns the [Configuration](../config.md) owns keys, bindings, reference syntax, and default
selectable keys, bindings, reference syntax, and default validator chains. validator chains. [Pipeline Internals](pipeline.md) owns assessment/disposition
and [LLM Integration](llm.md) owns native execution.
## Durable Artifact Contracts ## Durable Artifact Contracts
@@ -25,317 +26,222 @@ does not repeat their JSON shapes or schemas.
## Family Composition ## Family Composition
The D&D registrar registers the family’s artifact codecs, extractors, typed The [D&D registrar](../../internal/modules/dnd/register/register.go) composes
append-order mergers, normalizers, validators, prompt assets, fallback LLM codecs, evidence projections, typed extractors/append-order mergers/normalizers,
profile asset, and default validator chains. Each extractor and normalizer has validators, and default chains. Scene planning, extractors, and the three
a stable module spec, explicit execution class, strict option decoding, and a registry normalizers are model-backed; current mergers and remaining normalizers
typed builder. Scene chunking, every extractor, and NPC, location, and are deterministic. A model-backed module can still have an ordinary no-model
item-registry normalization are registered as `llm_backed`; the remaining branch. Registration does not construct engines or register prompt/schema assets.
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.
Private structured-LLM response schemas are deliberately minimal. They reject Each model producer receives the shared native engine, prepares fixed operation
invalid JSON structure, missing required fields, incompatible types, and inputs, and calls the common producer helper with initial request, interpretation,
unknown fields, while preserving semantic candidates for deterministic correction builder, and supported fallback. Static prompt dependencies match its
validation. Do not promote a private response envelope into a durable schema; request constants. The pipeline supplies complete candidate assessment; returning
the contracts above define durable data. from the helper does not trigger a duplicate validator pass.
Pure codecs, identities, reference resolvers, and deterministic transforms remain
A D&D producer that declares `single_response_v1` forwards any supplied separate from execution integration.
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.
## Prompt Construction ## Prompt Construction
D&D LLM-facing content lives beneath `assets/dnd/`. Each module contributes a Content lives beneath [assets/dnd](../../assets/dnd/), with ordinary native
local `prompt.yaml` declaration and `instructions.md`; input-specific files declarations imported by [assets/notarius.yml](../../assets/notarius.yml).
such as a catalog, registry, grounding projection, or candidate collection are The root assets package stays a content-only leaf. Declaration-relative content
local only when that module needs them. New extractor content uses its feature paths and the collection schema context replace mounted filesystems/manifests.
subtree, while families with both extraction and normalization content use their Native declarations own output contracts and initial/correction pairs.
`extract` and `normalize` subtrees. Shared visual-provenance fragments use [Configuration](../config.md#prompt-output-contracts-and-schemas) owns public
the `common-dnd-` prefix. Production lane code belongs with its D&D codec, schema-root/replacement behavior.
extractor, normalizer, and validator packages; registry projections and
identity helpers remain in their owning entity packages rather than in a
consumer lane.
The owning module’s manifest is the source of truth for which local and shared Use the [spell declaration](../../assets/dnd/spells/prompts/prompt.yaml),
assets are selected, their mount paths, their message order, cache controls, [scene declaration](../../assets/dnd/scenes/prompts/prompt.yaml), and
and the files included in its prompt fingerprint. Shared fragments belong to [item-normalization declaration](../../assets/dnd/item-registry/normalize/prompts/prompt.yaml)
the D&D shared implementation and are selected by name rather than copied into as distinct examples. IDs in module constants/static dependencies select their
module directories. The root `assets` package is a content-only boundary; its qualified native resources. Embedded profile content participates in the same
physical ownership and rationale are defined by native load as operator resources, not registrar fallback logic.
[ADR-0011](../adr/0011-centralize-llm-assets.md).
Put each rule at its narrowest owner: Put each rule at its narrowest owner:
- universal behavior belongs in the shared system asset; - Universal behavior belongs in shared system content.
- D&D-family behavior belongs in a selected `common-dnd-` asset; - D&D-family and input-specific rules belong in selected shared/input files.
- rules for an input projection belong with that input asset; - Enduring domain principles belong in the initial system context.
- lane-specific policy belongs in the module’s `instructions.md`; and - The initial assignment and correction assignment belong in their own messages.
- transport-envelope shape belongs in the private response schema. - 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 Initial/correction pairs share schema/profile defaults. Follow-ups supply new
it regardless of lane, inputs, or response shape. Module instructions must not guidance, not a fresh transcript/reference bundle or a manually replayed assistant.
repeat rules selected from shared assets or schemas. Reintroduce such repetition Native coordination retains the growing exchange; structural repair is separate.
only after observational evaluation with representative transcripts shows that Private model schemas keep structure minimal and provider-compatible. Durable
it improves results at the intended target models and cost; structural prompt artifact schemas remain codec-owned contracts. Preserve supported semantic
tests alone are not that evidence. candidates for typed validation instead of silently transforming domain mistakes.
Every maintained D&D LLM prompt selects `dnd-extraction` as its default Shared content is selected by real relative paths rather than copied into modules.
profile. The D&D registrar registers the fallback, while an operator can Message ordering/cache hints remain meaningful prompt behavior; inspect the
replace it with a complete profile of the same ID from the configured PromptKit owning declaration before changing them. Extraction generally separates reusable
source. Deployment profile selection is documented in campaign/chunk context from lane-specific projections. Scene planning uses the
[Configuration](../config.md#promptkit-profiles). 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 ## Representative Extraction And Correction
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.
Extraction prompts render the common system and identity messages first, then The [spell extractor](../../internal/modules/dnd/extract/spells/extractor.go)
cached campaign references and the cached chunk transcript. Evidence policy and uses [PrepareChunkExtraction](../../internal/modules/dnd/shared/extraction_inputs.go)
any lane-specific registry, catalog, or grounding projection follow that to validate source/chunk input, resolves catalog/NPC context once, and creates
prefix. The final module instructions message is ephemeral. This keeps the native artifact inputs. Its interpreter canonicalizes the private response into
reusable extraction prefix identical while preserving the lane-specific suffix. 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 Other extractors keep their own mapping/identity rules rather than consolidating
references, uncached module instructions, then the final ephemeral full unlike response envelopes into a generic parser. Unknown/ambiguous contextual
transcript. Entity normalization also has its own order: D&D system, mandatory selections produce actionable interpretation guidance without partial output or
generic protocol, ephemeral domain semantic instructions, generic candidate guessed identity. Run-wide native selections reach producer, continuation, and
presentation, and final ephemeral generic transcript windows. These orders and validator requests through the operation, without changing captured configuration.
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.
## Evidence, Candidates, And Normalization ## Evidence, Candidates, And Normalization
The current transcript is the only durable evidence source. Extractors assign The current transcript is the sole durable evidence source. Extractors attach
the current source identity and losslessly order any reversed range whose two its source identity and canonicalize resolvable reversed endpoints by document
endpoints resolve in that source, using transcript position rather than numeric position, not numeric unit-ID order. They order/deduplicate references without
unit-ID order. They then canonically order ranges and remove exact duplicates. turning ordinary canonicalization into a warning or correction. Wrong-source
This routine canonicalization does not request a retry or emit a warning. or unresolvable citations remain detectable, not silently repaired.
Unresolvable or wrong-source ranges remain unchanged for validators to reject. Campaign references and generated context can disambiguate or route work, never
Campaign context and generated artifacts may ground names or control routing, supply new source evidence.
but they never establish evidence for a D&D result.
Default chains keep responsibilities separate: structural validators assess the Typed chains retain separate structural, source, identity/domain, durable-schema,
candidate, source-reference validators resolve cited ranges against the current and advisory responsibilities; [Configuration](../config.md#production-validator-keys-and-default-chains)
source and require extraction evidence to stay within the current chunk, owns their order and replacement rules. Extraction containment requires the
durable-schema validation checks an approved representation, and entire cited span inside the current chunk after ordinary reference validation.
relatedness validators report advisory evidence concerns. The configured order Scene descriptions instead require the exact one-scene identity/range.
is documented in
[Configuration](../config.md#production-validator-keys-and-default-chains).
The optional `extract/dnd/scene-descriptions/combat_semantics` validator is the Guidance describes all currently detectable model-controlled defects using
D&D family's LLM-backed review of only combat versus non-combat classification. contextual names, response fields, and source ranges. It does not copy operator
It selects the shared combat-policy prompt fragment and asks the model to paths, hashes, validator keys, reason codes, or durable IDs. Shared
classify the current chunk independently as `combat` or `non_combat` without [diagnostic helpers](../../internal/modules/dnd/shared/diagnostics/diagnostics.go)
receiving the proposed scene kind. Deterministic code compares that support classified/bounded operator findings and separate model guidance.
classification with the proposed kind and either approves it or produces the Deterministic identity/order invariants do not imply that the model owns those
appropriate correction guidance. This keeps every schema-valid classification derived fields.
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.
### 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 Deterministic normalizers canonicalize display/evidence and source ordering and
`internal/modules/dnd/validate/scenedescriptions/combat_semantics/testdata/evaluation_cases.json` can emit cleanup observations. They run directly without synthetic requests.
owns the proposed kind, expected combat classification, and reviewer rationale The three registry normalizers retain their intentional model-assisted exception.
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.
## Semantic Registry Reconciliation ## Semantic Registry Reconciliation
The three registry normalizers instantiate the domain-neutral [NPC](../../internal/modules/dnd/normalize/npcregistry/normalizer.go),
`internal/framework/semanticreconcile` engine with default bounds. Each [item](../../internal/modules/dnd/normalize/itemregistry/normalizer.go), and
eligible candidate receives a contiguous, one-based `candidate_number` for that [location](../../internal/modules/dnd/normalize/locationregistry/normalizer.go)
request, and candidate material declares the exact inclusive range. The model normalization use ordinary functions from
sees that handle, the candidate label and source-free evidence ranges, plus [semanticreconcile](../../internal/framework/semanticreconcile/preparation.go),
bounded transcript windows; it returns only duplicate not a separate reconciliation engine/service.
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.
The generic core owns the mandatory handle protocol, candidate and transcript The operation retains the incoming merged artifact separately, preprocesses
presentation, the private response schema, source-reference validation, fixed originals once, and calls `Prepare` once. Preparation filters unusable
candidate and combined-material limits, structured completion, proposal candidate evidence, assigns contiguous one-based request-local handles, declares
assessment, stable group ordering, and typed plan-application mechanics. The their inclusive range, and builds bounded transcript windows/material.
D&D prompt contributes its system message and registry-specific semantic Candidate handles are not transcript unit IDs or durable identity. Identical
instructions. The generic registrar registers the shared prompt and schema; labels/evidence remain separately selectable.
the D&D registrar registers each consuming prompt and the fallback profile.
Fewer than two eligible candidates skips the LLM without a semantic warning. The native model proposes only duplicate groups and a supplied canonical handle.
An exceeded bound also skips the call and preserves the deterministic [Proposal assessment](../../internal/framework/semanticreconcile/proposal.go)
preprocessed registry, adding the registry's bounded fallback warning. Invalid rejects unsafe/unknown/overlapping selections; typed
structured output or discarded proposal groups use the normalizer's existing [application](../../internal/framework/semanticreconcile/application.go) uses
retry contract; retry exhaustion preserves the safe deterministic or family policies on the original records. Each response is a complete replacement
partially applied result and emits its bounded fallback warning. Provider, proposal, applied afresh before pipeline assessment, never a union of prior plans.
transport, cancellation, and context-material failures remain execution Correction uses the same handle mapping/windows and adds domain guidance only.
errors.
Application remains typed and registry-owned. All three policies select the Domain application chooses canonical display, unions evidence in source order,
canonical member's normalized display name, union member evidence in source preserves ungrouped originals, and derives durable identity after consolidation.
order, preserve ungrouped records, and derive durable identity only after NPC/item identity follows the final name; locations also use final evidence to
consolidation. NPC IDs derive from the final name. Item IDs also derive from preserve same-name distinct places. Item guards prevent currency denominations
the final name, and a typed guard prevents currency aliases from crossing from crossing or merging with non-currency records. Diagnostics and postconditions
denominations or mixing currency with non-currency records. Location IDs remain registry-owned; model output supplies no replacement names/evidence/IDs.
derive from the final name and final evidence, preserving same-name,
parent/child, and distinct physical-place identities. Registry warning scopes, Insufficient candidates use direct assessment without native execution.
reason codes, and postconditions remain outside the generic core. 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 ## Generated References And Grounding
Normalized D&D artifacts can be handed to a later step through a generated Normalized artifacts reach later steps through typed compatibility-checked
reference binding. The framework verifies artifact compatibility and retains handoffs. Consumers resolve supplied bytes into immutable contextual projections.
producer provenance; consumers resolve the handed-off artifact into an Valid fallback context remains usable in the current run but disables reuse for
immutable, validated projection for each operation. External files are checked actual consumers and their dependents; unrelated work is unaffected.
during preparation, while generated artifacts are resolved at the handoff.
NPC and item registry consumers receive names-only grounding. Location NPC/item selectors are names-only; location selectors include the name and
consumers receive a contextual selector containing the canonical name and the ordered registry references needed to distinguish same-name places. Consumers
registry references needed to distinguish same-name places. The calling module resolve selections locally to the unchanged durable ID/name pair. Unknown or
resolves those supplied selections locally and maps them into the unchanged ambiguous selections do not yield guessed IDs or partial occurrence results.
durable ID/name pair; an unknown or ambiguous selection rejects the complete Registry evidence disambiguates identity but never replaces each occurrence's
occurrence result rather than accepting a partial mapping. The NPC registry own current-transcript citations.
additionally supplies names-only actor grounding to spells, combat turns, and
enemy events.
Registry references establish a registry identity and may disambiguate a Scene projections route combat without conveying scene prose as evidence.
selection, but never become occurrence evidence. Each occurrence keeps its own Combat-turn projections retain actor/turn kind; NPC-occurrence projections select
current-transcript source references, even when it was grounded through the combat-opponent names/kinds for enemy grounding. These remain guidance, not
same registry record. event evidence.
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.
## Lane-Specific Rules ## Lane-Specific Rules
@@ -344,14 +250,14 @@ shared helper changes.
Shared D&D text comparison is identified by `dnd.text_comparison.v1`. Any Shared D&D text comparison is identified by `dnd.text_comparison.v1`. Any
semantic change requires an explicit policy-version review for every affected semantic change requires an explicit policy-version review for every affected
identity, mapping, normalization, and validator policy; helper source is not a identity, mapping, normalization, and validator policy. This is domain policy,
checkpoint fingerprint. not accepted-result cache identity.
| Lane | Intentional behavior | | Lane | Intentional behavior |
| --- | --- | | --- | --- |
| Spells | May use a spell-catalog overlay and optional NPC grounding; the catalog validator supplies domain-specific semantic checks. | | 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. | | 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 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. | | 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. | | 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 ## Focused Verification
When changing D&D behavior, test the affected codec, extractor, normalizer, Walk extensions through real [spell extraction](../../internal/modules/dnd/extract/spells/extractor_test.go),
validator, prompt-asset manifest, and registry projection. Also test generated [item reconciliation](../../internal/modules/dnd/normalize/itemregistry/normalizer_test.go),
handoffs at the integration boundary and run the full D&D module suite: [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).
~~~sh Retain family codec/identity/source/holder/eligibility regressions, contextual
go test ./internal/modules/dnd/... registry projection tests, and [assembled handoffs](../../internal/modules/integration/).
go test ./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.

View File

@@ -1,195 +1,165 @@
# Module Internals # Module Internals
This guide owns the mechanics for implementing and registering production This guide owns typed module construction, registration, and extension recipes.
modules. [Configuration](../config.md) owns selectable keys, binding syntax, [Configuration](../config.md#production-module-keys) owns selectable keys,
reference configuration, and default validator chains. Durable input and output binding syntax, references, and default chains.
shapes belong in [integration contracts](../integrations/). [Integration contracts](../integrations/json-output.md) own durable shapes;
[D&D Module Internals](dnd.md) owns that family's domain conventions.
The D&D family has additional shared conventions and domain-specific ## Typed Boundary And Registration
exceptions. See [D&D Module Internals](dnd.md) rather than adding them here.
## Module Boundary A module implements one fixed pipeline operation; an artifact family owns the
related domain types, codec, modules, validators, prompts, and reference
projections. Family ownership does not combine extraction/merge/normalization
or turn the pipeline into a workflow language.
A module is a typed implementation registered for one pipeline stage. Its [ModuleSpec](../../internal/framework/pipeline/module.go) declares the stable
`ModuleSpec` is the public-to-the-framework declaration of its stable key, key, operation, execution class, artifact kind, capabilities, reference slots,
stage, execution class, required and provided capabilities, artifact kind, and and statically selected prompt IDs. Specs can be inspected without constructing
accepted reference slots. The execution class states whether a module is modules. The resolver applies model-profile selections only to model roles.
`deterministic` or `llm_backed`; registries retain it for catalog inspection and Static initial/correction dependencies use the same constants as request builders;
resolved-pipeline debug data without constructing the module. The framework they are preflight declarations, not asset manifests or execution fingerprints.
uses the declaration to resolve a configured binding before it builds the
implementation. After selection, the resolver applies profile inheritance only
to bindings whose declared execution class is `llm_backed` and rejects a
binding-specific profile on a deterministic module. The user-facing precedence
contract belongs in [Configuration](../config.md#pipelines).
An eligible LLM-backed chunk, extract, merge, or normalize producer may also [BuildRequest](../../internal/framework/pipeline/construction.go) supplies the
declare correction protocol `single_response_v1`. That declaration is a shared native engine, option values, and prepared references. Option-aware
promise that the implementation accepts one attempt-local semantic correction modules provide a resolver validator and a builder using the same strict decoder.
and returns an owned copy of the exact one model response that directly They do not rediscover configuration or reopen reference files. Generated
controlled the candidate. It must forward correction only to its structured references arrive through operation requests, not construction-time file reads.
completion request; it must not manufacture prior-response material by
serializing a normalized artifact or expose opaque application IDs. Input,
output, validator, and deterministic specs cannot declare the protocol.
Implementations that accept options must provide both an option validator and Typed helpers retain the exact artifact type at registration:
a builder. The validator is used while resolving configuration; the builder
decodes the same options and constructs the implementation from the prepared
`BuildRequest`. Reject unknown options in both paths. A builder receives only
the dependencies and materialized references that the framework prepared for
that operation, so it must not re-read configuration or files.
Registry helpers register the typed builder for a stage-specific registry. - [RegisterExtractorBuilder](../../internal/framework/pipeline/extractor_registry.go),
They are preferable to hand-written untyped registration because they retain [RegisterMergerBuilder](../../internal/framework/pipeline/merger_registry.go), and
the artifact type at the framework boundary. Registrars validate the registries [RegisterNormalizerBuilder](../../internal/framework/pipeline/normalizer_registry.go)
they need, register each leaf implementation, and add any family-owned assets connect typed production to private framework erasure.
or default validator chains. They return contextual errors so production - [Typed validators](../../internal/framework/pipeline/validator_registry.go)
composition fails at startup rather than at the first run. register compatible kind/type-specific assessment.
- [Artifact codecs](../../internal/framework/pipeline/artifact_codec_registry.go)
own durable encoding/decoding and intrinsic schema checks.
- Optional [evidence projectors](../../internal/framework/pipeline/artifact_evidence_registry.go)
copy direct generic source references using the codec's exact Go type.
A validator that returns a completed rejection must supply two separate Preparation rejects incompatible types/registrations before parsing source.
bounded values: a stable `ReasonCode` for provenance and actionable Projectors do not inspect arbitrary domain JSON or publish files; the
`CorrectionGuidance` for the producer. Guidance identifies the semantic defect [evidence contract](../integrations/evidence-context.md) owns the excerpt.
and the constraints on one complete corrected replacement. It must not contain
validator keys, diagnostic paths, opaque application IDs, or other internal
identifiers. An operator-facing `Message` may explain the same event, but the
framework never copies it into a model request. Missing or invalid guidance is
a validator contract failure.
An artifact family can register an optional typed evidence projector alongside ## Native Producer Recipe
its codec. The projector returns defensive copies of the artifact's direct
generic source references and must use the codec's exact Go type. It does not
interpret surrounding context or publish files; the pipeline validates the
capability during preparation and the output boundary owns publication. See
the [Published Evidence Context contract](../integrations/evidence-context.md)
for the durable source-unit excerpt. Lane artifacts retain citation and lane
provenance; the framework does not add either to that published excerpt.
An artifact family is broader than a module: it owns the cohesive domain Follow the actual [spell extractor](../../internal/modules/dnd/extract/spells/extractor.go)
feature across its artifact type, codec, stage modules, validators, prompt alongside [typed requests/results](../../internal/framework/contracts/typed_pipeline.go)
policy, schemas, identity helpers, and reference projections. An extractor and and [operation contracts](../../internal/framework/contracts/producer.go):
normalizer in one artifact family remain independently registered modules in
their respective pipeline stages. This ownership vocabulary does not create a
new registry or change the fixed pipeline.
## Production Composition 1. Validate operation input and prepare owned transcript/reference/contextual
projections once. Retain those fixed bytes and resolution mappings locally.
2. Build the initial `promptkit.RunRequest` using the declared prompt ID,
operation profile/session, native artifacts, and variables.
3. Call [RunProducer](../../internal/framework/pipeline/producer.go) with the shared
engine and the supplied typed operation. Supply ordinary interpretation,
correction-request, and supported fallback functions.
4. Interpret `*promptkit.RunResult` into the typed domain candidate. Attach
deterministic identities and canonical source references here, not by asking
the model to reproduce opaque IDs. Return actionable interpretation guidance
separately from operator diagnostics where the module can correct a selection.
5. Build the follow-up request from new findings/assignment only. Preserve
profile/session selections; native coordination carries prior conversation.
Do not rerender source inputs, serialize a domain artifact as a previous
assistant response, or implement another turn loop.
6. Return the helper's value and outcome in the typed operation result. The
runner has already supplied assessment; do not validate again after the helper.
Production composition is intentionally split by family: The helper checks native structural status before interpretation, binds native
execution overrides/observers, assesses every delivered usable candidate, and
handles prepared reuse. Modules do not replace its assessor/cache or infer
acceptance from provider success. [Pipeline Internals](pipeline.md) owns the
complete assessment/disposition algorithm; [LLM Integration](llm.md) owns native
execution and [State Internals](state.md) owns storage/capture lifecycle.
- The generic registrar provides the unit chunker, generic JSON validators, Fallback construction is explicit and family-owned. It must satisfy intrinsic
JSON output encoder, and shared semantic-reconciliation prompt and response shape/source/downstream invariants, but does not rerun ordinary validators or
schema assets. claim semantic approval. Unsupported/invalid construction fails. No earlier
- The Seriatim registrar provides the transcript input adapter. Its external candidate is recovered after an unusable continuation; cancellation produces no
input behavior is defined by the [Seriatim contract](../integrations/seriatim.md). fallback. Modules do not pick a permissive default or hide an ordinary operation
- The D&D registrar provides its codecs, extractors, mergers, normalizers, error as recovery.
validators, prompt assets, fallback profile asset, and default chains. Its behavioral conventions
are documented in [D&D Module Internals](dnd.md).
The CLI owns the composition that invokes these registrars. A module package ## Validators And Deterministic Work
may register its own family but must not assemble the CLI or make framework
packages depend on production extensions. Validators receive native execution options and detached candidate/context views,
not a producer operation or semantic-turn loop. Return approval, or rejection
with separate stable reason and actionable `CorrectionGuidance`. Operator
`Message` is not model feedback. The detecting rule owns guidance about fields
the producer controls, without internal paths/keys/opaque identities.
Invalid rejection guidance is a contract failure.
A model validator calls the shared native engine directly, checks native errors/
validation before interpretation, and distinguishes unavailable judgment from
semantic rejection while preserving causes. See the
[combat validator](../../internal/modules/dnd/validate/scenedescriptions/combat_semantics/validator.go).
Do not rerun a validator to extend native repair budgets.
Deterministic modules produce once through ordinary typed interfaces. The runner
assesses the value and can invoke an explicitly supported result fallback after
nonacceptance. Production errors propagate without generic retries. Model-backed
modules with legitimate no-model branches use direct `AssessProducer` on that
value; preparation-limit terminal handling uses `FinishProducerFailure` rather
than synthetic requests. The [noop normalizer](../../internal/modules/generic/normalize/noop/normalizer.go)
and registry normalizers show the distinct paths.
## Prompt And Schema Ownership
[assets/notarius.yml](../../assets/notarius.yml) imports ordinary native prompt
declarations and profiles with their filesystem contexts. The content-only
assets package has no registration behavior. Declarations own ordered messages,
cache hints, default profiles, and output contracts/schema selection. Use real
relative content-file paths; no virtual mounts or Go prompt manifests.
A producer's initial/correction pair requests complete responses with matching
schema/profile defaults. Put enduring rules in initial system context and only
current guidance/new assignment in follow-ups. Native structural repair remains
upstream-owned. Private response envelopes are not durable artifact contracts.
See [schema selection](../config.md#prompt-output-contracts-and-schemas) and the
[D&D prompt recipe](dnd.md#prompt-construction) for concrete examples.
## Semantic Reconciliation ## Semantic Reconciliation
`internal/framework/semanticreconcile` is a domain-neutral strategy used by a The [shared core](../../internal/framework/semanticreconcile/preparation.go)
typed normalize module; it is not itself a selectable stage module. A offers preparation, native request builders, proposal assessment, and typed
source-backed artifact-family normalizer projects its deterministic records application functions, not a replacement execution service.
into contextual candidates and owned typed record envelopes, supplies its [Requests](../../internal/framework/semanticreconcile/requests.go) consume one
chosen prompt identity and resolved LLM profile, and constructs an engine with retained preparation. [Proposal safety](../../internal/framework/semanticreconcile/proposal.go)
explicit limits. The core filters invalid evidence, assigns contiguous resolves request-local handles; [application](../../internal/framework/semanticreconcile/application.go)
one-based request-local candidate numbers, renders bounded candidate and clones/preserves originals and applies domain policies.
transcript materials, invokes the structured-completion boundary, and assesses
the returned duplicate groups into a stable non-overlapping plan. Candidate
material declares the exact inclusive number range for the request. Transcript
unit IDs and evidence range endpoints remain source positions in a separate
namespace and are never valid candidate numbers.
The normalizer then applies that plan through a typed `ApplicationPolicy`. The The [item normalizer](../../internal/modules/dnd/normalize/itemregistry/normalizer.go)
core preserves ungrouped records, contribution order, and provenance while the preprocesses fixed originals once, prepares bounded windows/handles once, then
artifact family owns group guards, field and evidence consolidation, durable uses the same producer helper as extraction. Each complete proposal is assessed
ID derivation, retry and fallback presentation, classified diagnostics, and and applied afresh to originals before pipeline assessment. Domain guards,
postconditions. identity, evidence, diagnostics, and supported final-only fallback remain with
These candidate numbers are the concrete private representation of ADR-0013's the artifact family. Do not union plans across turns, reuse prior mutated output,
request-local handles; they do not enter the typed value or durable artifact. or introduce module retry/repair protocols. [D&D reconciliation](dnd.md#semantic-registry-reconciliation)
Fewer than two eligible candidates skips model invocation; exceeding a explains the concrete policy differences.
candidate or combined-material bound preserves the deterministic result under
the family's fallback policy. Provider, transport, cancellation, and
context-construction failures remain execution errors.
When the engine actually makes a proposal call, its typed result carries the ## Production Composition And Change Checklist
owned exact proposal response under the same correction contract as other
eligible producers. Deterministic skip, limit, and fallback outcomes carry no
model candidate, so a later rejection applies terminal policy without spending
an ineffective semantic retry.
When proposal assessment or typed group application rejects a structurally The CLI invokes generic, Seriatim, and D&D registrars. They register typed modules,
valid group, the normalizer may return its safe partial value with a codecs, evidence, and owned validator defaults, not prompts/schemas/profiles.
module-requested retry. A feedback-capable directive supplies bounded [Seriatim](../integrations/seriatim.md) retains input-format ownership; generic
model-facing correction guidance separately from operator diagnostics and operations remain domain-neutral; D&D does not compose process behavior.
retains the exact proposal response as its candidate. The shared stage retry
mechanism appends that response and guidance to a fresh complete request. A
structurally invalid completion has no valid candidate and therefore requests a
feedback-free fresh attempt. On exhaustion, only the final safe fallback and
its bounded process diagnostic advance to validation.
The core supplies a conservative generic prompt and the single private For an extension, add the typed domain/codec boundary, strict options and spec,
response schema. A domain prompt may substitute its semantic instructions but native declarations/static dependencies where needed, stage implementation,
mounts the core-owned protocol and candidate/transcript presentation assets. and owning registrar entry. Add default chains only where the family owns them.
Prompt, schema, policy, and limit identities participate in manifest metadata Reference slots declare artifact/media/size requirements; generated handoffs
and checkpoint fingerprints. The generic registrar owns production must retain prior-step compatibility. Preserve ownership of request maps/slices
registration of those shared assets; a consuming domain registrar owns only and returned stored data. Modules receive no physical roots or CLI reporters.
its domain prompt.
## Adding Or Changing A Module Update canonical [keys/chains](../config.md#production-validator-keys-and-default-chains)
and durable contracts when their behavior changes; complete runnable configurations
1. Choose the pipeline stage and the typed artifact boundary. Put external belong in [examples](../../examples/). Test the actual leaf and registration path,
input or durable artifact formats in the relevant integration contract, exact-type compatibility, domain invariants, fixed-input correction, unavailable/
not in this guide or in a private LLM response type. failed outcomes, supported fallback, and cancellation where applicable.
2. Define a stable `ModuleSpec` with an explicit execution class, the exact [Spell tests](../../internal/modules/dnd/extract/spells/extractor_test.go),
capabilities, and reference slots needed for the operation. Model a [item normalization tests](../../internal/modules/dnd/normalize/itemregistry/normalizer_test.go),
producer/consumer handoff as an artifact-compatible slot; configuration and [registration dependencies](../../internal/modules/dnd/register/dependencies_test.go)
then chooses an external file or a generated binding. are concrete starting points. Use real kits with native provider fakes, not a
3. Implement strict option decoding, construction, and the typed stage replacement completion mock or full prompt-prose snapshots.
interface. Preserve caller ownership: do not retain mutable request data [Development](../development.md#validation) owns wider checks.
and return defensive copies where an implementation exposes stored data.
If declaring correction capability, forward the request correction and
retain only the exact validated response that controlled the result.
4. Register the module through its typed registry helper and add it to the
owning family registrar. Add a default validator chain only when that
family owns the behavior; otherwise require an explicit compatible chain.
Every rejection path in a validator must provide actionable correction
guidance while retaining its stable internal reason code.
5. Update the selectable-key and chain reference in
[Configuration](../config.md#production-module-keys), the applicable
integration contract, and focused tests. Keep the configuration document
as the sole list of production keys and validator order.
## Validation And References
Validators operate on the value produced at their configured stage. A default
chain is ordered behavior, not a set: JSON parsing, structural checks,
domain-specific checks, durable-schema checks, and advisory checks may have
different responsibilities and failure handling. The active default chains and
override rules are maintained in
[Configuration](../config.md#production-validator-keys-and-default-chains).
Reference slots are part of the module specification. They describe the
accepted artifact kind, media type, size, and whether a binding is required;
the framework validates those constraints before construction. An external
reference is materialized during preparation. A generated reference is a
compatible normalized artifact handed from an earlier pipeline step at
operation time. The configuration reference rules, including precedence and
ordered-handoff requirements, are maintained in
[Configuration](../config.md#references-and-ordered-handoffs).
## Focused Verification
Exercise the leaf implementation and its registration path when changing a
module. Registry and registrar tests cover duplicate keys, required registries,
and typed construction; pipeline resolution tests cover capabilities, options,
and reference compatibility. Domain packages should additionally test their
codecs, validators, normalizers, and any integration handoffs they own.
Run the affected package tests while iterating. The complete module suite is:
~~~sh
go test ./internal/modules/...
~~~

View File

@@ -2096,6 +2096,29 @@ tests; verify no stale state collaborator or operation ordering is carried forwa
## Stage 43: Refresh Module And D&D Contributor Guides ## Stage 43: Refresh Module And D&D Contributor Guides
**Status:** Complete. Replaced obsolete correction-capability, private completion,
asset/schema registration, fingerprint, and reconciliation-service recipes with
the actual typed builder/spec interfaces and shared native producer path.
The extension guide now walks fixed input preparation, native initial/follow-up
requests, interpretation, supplied pipeline assessment, explicit supported
fallback, static resource dependencies, direct model validators, and deterministic
or legitimate no-model paths without synthetic requests or module-owned loops.
D&D guidance retains all ten durable contract links and family identity,
source/evidence, contextual grounding, holder, combat-routing, and reconciliation
differences. It explains one-time windows/handles, fresh final-proposal application,
domain guidance, whole-source planning fallback, and the scene-description
construction limit without changing payloads. Updated the existing opt-in
combat-semantics evaluation procedure to native execution/capture/cache controls;
fake tests make no provider-quality claim. Walked the recipes against spell
extraction, item normalization, shared preparation/application, scene planning,
direct combat validation, registration, and native asset declarations.
All 86 local links/anchors and retained incoming anchors resolve. Asset, complete
module/integration, reconciliation, and pipeline package tests and vet pass;
removal searches and `git diff --check` pass. No production code, schemas,
evaluation corpus, or default-chain policy changed. Kit integration documentation
remains assigned to the next stage.
**Goal:** future modules can follow the native architecture without copying drift. **Goal:** future modules can follow the native architecture without copying drift.
**Inspect/change:** `docs/internal/{modules,dnd}.md`; production registration, **Inspect/change:** `docs/internal/{modules,dnd}.md`; production registration,