Refresh typed module and D&D contributor recipes
This commit is contained in:
@@ -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.
|
||||||
|
|||||||
@@ -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/...
|
|
||||||
~~~
|
|
||||||
|
|||||||
@@ -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,
|
||||||
|
|||||||
Reference in New Issue
Block a user