Files
notarius/docs/internal/modules.md

166 lines
10 KiB
Markdown
Raw Normal View History

2026-07-26 13:30:36 +00:00
# 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.
2026-07-26 13:30:36 +00:00
## 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.