# Module Internals 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. ## Typed Boundary And Registration 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. [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. [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. Typed helpers retain the exact artifact type at registration: - [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. 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. ## Native Producer Recipe 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): 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. 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. 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. ## 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 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 [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. ## Production Composition And Change Checklist 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. 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. 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.