166 lines
10 KiB
Markdown
166 lines
10 KiB
Markdown
# 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.
|