81 lines
3.1 KiB
Markdown
81 lines
3.1 KiB
Markdown
# Audita Modules
|
|
|
|
## Scope
|
|
|
|
This document covers internal module contracts and packages. User-selectable keys
|
|
and the default sequence belong to [configuration](../config.md#settings).
|
|
|
|
## Module Contract
|
|
|
|
Modules implement `contracts.TranscriptModule`:
|
|
- `Key()`
|
|
- `ReplacementPolicy()`
|
|
- `Validators()`
|
|
- `Propose(ctx, req)`
|
|
|
|
Runner resolves configured module specs to module instances through `internal/framework/modules`.
|
|
|
|
## Built-In Modules
|
|
|
|
Current module packages:
|
|
- `internal/modules/glossary`
|
|
- `internal/modules/homophones`
|
|
- `internal/modules/spoken_word`
|
|
- `internal/modules/grammar`
|
|
|
|
Current replacement policies:
|
|
- `glossary`: `replace_all`
|
|
- `homophones`: `require_unique`
|
|
- `spoken_word`: `require_unique`
|
|
- `grammar`: `require_unique`
|
|
|
|
## Proposal Generation Ownership
|
|
|
|
Shared proposal-generation plumbing is centralized in:
|
|
- `internal/framework/proposal_generation`
|
|
|
|
Module packages own:
|
|
- prompt selection (`internal/prompts` prompt IDs).
|
|
|
|
`proposal_generation.BuildProposalVariables` encodes the glossary, selected
|
|
transcript section, and trimmed description once for all four modules. PromptKit
|
|
renders their embedded definitions from those variables and validates the
|
|
correction-set schema before Audita maps proposals. Domain validators still
|
|
check confidence, applicability, protected glossary terms, and replacement
|
|
policy. Shared context encoding lives in `internal/framework/promptcontext`.
|
|
|
|
## Validator Chain Ownership
|
|
|
|
Built-in chains are resolved in `internal/validators` per module key.
|
|
Module packages call the built-in chain resolver at construction.
|
|
|
|
## Failure and Warning Behavior
|
|
|
|
Module construction failures propagate to orchestration; execution failures can
|
|
preserve partial module results. Exhausted structural repair becomes a warning
|
|
and section-level rejection; provider and protocol failures propagate. Consumer-visible outcomes are defined by
|
|
the [report contract](../integrations/output-files.md#module-outcomes).
|
|
|
|
## Changing Modules
|
|
|
|
1. Add or update the narrowly scoped package under `internal/modules/<module_key>`.
|
|
2. Keep module prompt selection in the module and its definition in
|
|
`internal/prompts`; see [prompt assets](prompts.md).
|
|
3. Wire module registration and catalog resolution through framework module
|
|
registration and the core module catalog. Update selectable keys in the
|
|
[configuration contract](../config.md) when they change.
|
|
4. Verify replacement policy and validator-chain selection against the
|
|
[architecture requirements](../policy/architecture.md#correction-and-concurrency-invariants).
|
|
5. Review module, prompt-variable, and proposal-generation tests. Inspect parity
|
|
and release fixtures when public output changes, choosing sufficient coverage
|
|
under the [testing policy](../policy/testing.md).
|
|
6. Update this document for implementation changes and the appropriate public
|
|
contract owner for externally visible changes.
|
|
|
|
## Key Tests
|
|
|
|
- `internal/modules/*/module_test.go`
|
|
- `internal/framework/modules/registry_test.go`
|
|
- `internal/framework/proposal_generation/*_test.go`
|
|
- `internal/cli/run_test.go` (pipeline/report integration)
|