Refresh typed module and D&D contributor recipes
This commit is contained in:
@@ -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.
|
||||
|
||||
@@ -1,195 +1,165 @@
|
||||
# Module Internals
|
||||
|
||||
This guide owns the mechanics for implementing and registering production
|
||||
modules. [Configuration](../config.md) owns selectable keys, binding syntax,
|
||||
reference configuration, and default validator chains. Durable input and output
|
||||
shapes belong in [integration contracts](../integrations/).
|
||||
This guide owns typed module construction, registration, and extension recipes.
|
||||
[Configuration](../config.md#production-module-keys) owns selectable keys,
|
||||
binding syntax, references, and default chains.
|
||||
[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
|
||||
exceptions. See [D&D Module Internals](dnd.md) rather than adding them here.
|
||||
## Typed Boundary And Registration
|
||||
|
||||
## 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` is the public-to-the-framework declaration of its stable key,
|
||||
stage, execution class, required and provided capabilities, artifact kind, and
|
||||
accepted reference slots. The execution class states whether a module is
|
||||
`deterministic` or `llm_backed`; registries retain it for catalog inspection and
|
||||
resolved-pipeline debug data without constructing the module. The framework
|
||||
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).
|
||||
[ModuleSpec](../../internal/framework/pipeline/module.go) declares the stable
|
||||
key, operation, execution class, artifact kind, capabilities, reference slots,
|
||||
and statically selected prompt IDs. Specs can be inspected without constructing
|
||||
modules. The resolver applies model-profile selections only to model roles.
|
||||
Static initial/correction dependencies use the same constants as request builders;
|
||||
they are preflight declarations, not asset manifests or execution fingerprints.
|
||||
|
||||
An eligible LLM-backed chunk, extract, merge, or normalize producer may also
|
||||
declare correction protocol `single_response_v1`. That declaration is a
|
||||
promise that the implementation accepts one attempt-local semantic correction
|
||||
and returns an owned copy of the exact one model response that directly
|
||||
controlled the candidate. It must forward correction only to its structured
|
||||
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.
|
||||
[BuildRequest](../../internal/framework/pipeline/construction.go) supplies the
|
||||
shared native engine, option values, and prepared references. Option-aware
|
||||
modules provide a resolver validator and a builder using the same strict decoder.
|
||||
They do not rediscover configuration or reopen reference files. Generated
|
||||
references arrive through operation requests, not construction-time file reads.
|
||||
|
||||
Implementations that accept options must provide both an option validator and
|
||||
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.
|
||||
Typed helpers retain the exact artifact type at registration:
|
||||
|
||||
Registry helpers register the typed builder for a stage-specific registry.
|
||||
They are preferable to hand-written untyped registration because they retain
|
||||
the artifact type at the framework boundary. Registrars validate the registries
|
||||
they need, register each leaf implementation, and add any family-owned assets
|
||||
or default validator chains. They return contextual errors so production
|
||||
composition fails at startup rather than at the first run.
|
||||
- [RegisterExtractorBuilder](../../internal/framework/pipeline/extractor_registry.go),
|
||||
[RegisterMergerBuilder](../../internal/framework/pipeline/merger_registry.go), and
|
||||
[RegisterNormalizerBuilder](../../internal/framework/pipeline/normalizer_registry.go)
|
||||
connect typed production to private framework erasure.
|
||||
- [Typed validators](../../internal/framework/pipeline/validator_registry.go)
|
||||
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
|
||||
bounded values: a stable `ReasonCode` for provenance and actionable
|
||||
`CorrectionGuidance` for the producer. Guidance identifies the semantic defect
|
||||
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.
|
||||
Preparation rejects incompatible types/registrations before parsing source.
|
||||
Projectors do not inspect arbitrary domain JSON or publish files; the
|
||||
[evidence contract](../integrations/evidence-context.md) owns the excerpt.
|
||||
|
||||
An artifact family can register an optional typed evidence projector alongside
|
||||
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.
|
||||
## Native Producer Recipe
|
||||
|
||||
An artifact family is broader than a module: it owns the cohesive domain
|
||||
feature across its artifact type, codec, stage modules, validators, prompt
|
||||
policy, schemas, identity helpers, and reference projections. An extractor and
|
||||
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.
|
||||
Follow the actual [spell extractor](../../internal/modules/dnd/extract/spells/extractor.go)
|
||||
alongside [typed requests/results](../../internal/framework/contracts/typed_pipeline.go)
|
||||
and [operation contracts](../../internal/framework/contracts/producer.go):
|
||||
|
||||
## 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,
|
||||
JSON output encoder, and shared semantic-reconciliation prompt and response
|
||||
schema assets.
|
||||
- The Seriatim registrar provides the transcript input adapter. Its external
|
||||
input behavior is defined by the [Seriatim contract](../integrations/seriatim.md).
|
||||
- The D&D registrar provides its codecs, extractors, mergers, normalizers,
|
||||
validators, prompt assets, fallback profile asset, and default chains. Its behavioral conventions
|
||||
are documented in [D&D Module Internals](dnd.md).
|
||||
Fallback construction is explicit and family-owned. It must satisfy intrinsic
|
||||
shape/source/downstream invariants, but does not rerun ordinary validators or
|
||||
claim semantic approval. Unsupported/invalid construction fails. No earlier
|
||||
candidate is recovered after an unusable continuation; cancellation produces no
|
||||
fallback. Modules do not pick a permissive default or hide an ordinary operation
|
||||
error as recovery.
|
||||
|
||||
The CLI owns the composition that invokes these registrars. A module package
|
||||
may register its own family but must not assemble the CLI or make framework
|
||||
packages depend on production extensions.
|
||||
## Validators And Deterministic Work
|
||||
|
||||
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
|
||||
|
||||
`internal/framework/semanticreconcile` is a domain-neutral strategy used by a
|
||||
typed normalize module; it is not itself a selectable stage module. A
|
||||
source-backed artifact-family normalizer projects its deterministic records
|
||||
into contextual candidates and owned typed record envelopes, supplies its
|
||||
chosen prompt identity and resolved LLM profile, and constructs an engine with
|
||||
explicit limits. The core filters invalid evidence, assigns contiguous
|
||||
one-based request-local candidate numbers, renders bounded candidate and
|
||||
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 [shared core](../../internal/framework/semanticreconcile/preparation.go)
|
||||
offers preparation, native request builders, proposal assessment, and typed
|
||||
application functions, not a replacement execution service.
|
||||
[Requests](../../internal/framework/semanticreconcile/requests.go) consume one
|
||||
retained preparation. [Proposal safety](../../internal/framework/semanticreconcile/proposal.go)
|
||||
resolves request-local handles; [application](../../internal/framework/semanticreconcile/application.go)
|
||||
clones/preserves originals and applies domain policies.
|
||||
|
||||
The normalizer then applies that plan through a typed `ApplicationPolicy`. The
|
||||
core preserves ungrouped records, contribution order, and provenance while the
|
||||
artifact family owns group guards, field and evidence consolidation, durable
|
||||
ID derivation, retry and fallback presentation, classified diagnostics, and
|
||||
postconditions.
|
||||
These candidate numbers are the concrete private representation of ADR-0013's
|
||||
request-local handles; they do not enter the typed value or durable artifact.
|
||||
Fewer than two eligible candidates skips model invocation; exceeding a
|
||||
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.
|
||||
The [item normalizer](../../internal/modules/dnd/normalize/itemregistry/normalizer.go)
|
||||
preprocesses fixed originals once, prepares bounded windows/handles once, then
|
||||
uses the same producer helper as extraction. Each complete proposal is assessed
|
||||
and applied afresh to originals before pipeline assessment. Domain guards,
|
||||
identity, evidence, diagnostics, and supported final-only fallback remain with
|
||||
the artifact family. Do not union plans across turns, reuse prior mutated output,
|
||||
or introduce module retry/repair protocols. [D&D reconciliation](dnd.md#semantic-registry-reconciliation)
|
||||
explains the concrete policy differences.
|
||||
|
||||
When the engine actually makes a proposal call, its typed result carries the
|
||||
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.
|
||||
## Production Composition And Change Checklist
|
||||
|
||||
When proposal assessment or typed group application rejects a structurally
|
||||
valid group, the normalizer may return its safe partial value with a
|
||||
module-requested retry. A feedback-capable directive supplies bounded
|
||||
model-facing correction guidance separately from operator diagnostics and
|
||||
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 CLI invokes generic, Seriatim, and D&D registrars. They register typed modules,
|
||||
codecs, evidence, and owned validator defaults, not prompts/schemas/profiles.
|
||||
[Seriatim](../integrations/seriatim.md) retains input-format ownership; generic
|
||||
operations remain domain-neutral; D&D does not compose process behavior.
|
||||
|
||||
The core supplies a conservative generic prompt and the single private
|
||||
response schema. A domain prompt may substitute its semantic instructions but
|
||||
mounts the core-owned protocol and candidate/transcript presentation assets.
|
||||
Prompt, schema, policy, and limit identities participate in manifest metadata
|
||||
and checkpoint fingerprints. The generic registrar owns production
|
||||
registration of those shared assets; a consuming domain registrar owns only
|
||||
its domain prompt.
|
||||
For an extension, add the typed domain/codec boundary, strict options and spec,
|
||||
native declarations/static dependencies where needed, stage implementation,
|
||||
and owning registrar entry. Add default chains only where the family owns them.
|
||||
Reference slots declare artifact/media/size requirements; generated handoffs
|
||||
must retain prior-step compatibility. Preserve ownership of request maps/slices
|
||||
and returned stored data. Modules receive no physical roots or CLI reporters.
|
||||
|
||||
## Adding Or Changing A Module
|
||||
|
||||
1. Choose the pipeline stage and the typed artifact boundary. Put external
|
||||
input or durable artifact formats in the relevant integration contract,
|
||||
not in this guide or in a private LLM response type.
|
||||
2. Define a stable `ModuleSpec` with an explicit execution class, the exact
|
||||
capabilities, and reference slots needed for the operation. Model a
|
||||
producer/consumer handoff as an artifact-compatible slot; configuration
|
||||
then chooses an external file or a generated binding.
|
||||
3. Implement strict option decoding, construction, and the typed stage
|
||||
interface. Preserve caller ownership: do not retain mutable request data
|
||||
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/...
|
||||
~~~
|
||||
Update canonical [keys/chains](../config.md#production-validator-keys-and-default-chains)
|
||||
and durable contracts when their behavior changes; complete runnable configurations
|
||||
belong in [examples](../../examples/). Test the actual leaf and registration path,
|
||||
exact-type compatibility, domain invariants, fixed-input correction, unavailable/
|
||||
failed outcomes, supported fallback, and cancellation where applicable.
|
||||
[Spell tests](../../internal/modules/dnd/extract/spells/extractor_test.go),
|
||||
[item normalization tests](../../internal/modules/dnd/normalize/itemregistry/normalizer_test.go),
|
||||
and [registration dependencies](../../internal/modules/dnd/register/dependencies_test.go)
|
||||
are concrete starting points. Use real kits with native provider fakes, not a
|
||||
replacement completion mock or full prompt-prose snapshots.
|
||||
[Development](../development.md#validation) owns wider checks.
|
||||
|
||||
Reference in New Issue
Block a user