diff --git a/docs/internal/dnd.md b/docs/internal/dnd.md index c4b9fcdf..1ee2b886 100644 --- a/docs/internal/dnd.md +++ b/docs/internal/dnd.md @@ -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. diff --git a/docs/internal/modules.md b/docs/internal/modules.md index aa607d2d..9e9048c3 100644 --- a/docs/internal/modules.md +++ b/docs/internal/modules.md @@ -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. diff --git a/docs/roadmap/implementation.md b/docs/roadmap/implementation.md index c67fd138..b1ecf503 100644 --- a/docs/roadmap/implementation.md +++ b/docs/roadmap/implementation.md @@ -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 +**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. **Inspect/change:** `docs/internal/{modules,dnd}.md`; production registration,