77 lines
2.7 KiB
Markdown
77 lines
2.7 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#pipeline-and-output).
|
|
|
|
## 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);
|
|
- module-specific prompt payload construction.
|
|
|
|
Shared prompt helpers live 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. Malformed structured proposal payloads become
|
|
warnings and section-level rejection. 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-specific prompt ownership in the module and `internal/prompts`;
|
|
see [prompt rendering and metadata](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-rendering, 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)
|