# 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)` Built-in modules also expose `RepairPromptID()` for the runner to select their repair definitions; proposal-only callers retain the existing interface. 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). Each stage prepares the encoded glossary context and protected spellings once. Proposal generation adds the selected transcript section and trimmed description for each request. PromptKit renders the selected definition and validates the correction-set schema before Audita maps proposals. Domain validators still check applicability, protected glossary terms, and replacement policy. Model-facing segment IDs are one-based positions within the proposal request. Generation and repair map those references back to the current chunk's actual segment IDs, preserving response order and multiple proposals per segment. Unknown references become invalid-target candidates for the existing domain checks; they are never interpreted as actual transcript IDs. Debug request metadata records `segment_ids` in local-reference order (reference 1 is the first entry). Shared context encoding lives in `internal/framework/promptcontext`. An empty `corrected_text` deletes the identified span when the resulting segment remains nonblank. Whitespace-only original spans can express spacing corrections; matching stays literal under each module's replacement policy. No automatic whitespace cleanup follows application. ## 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 Outcome Behavior Each actionable rejection can be revised or withdrawn within its original section. A revision retains the original proposal identity and must pass the full validator chain before application. Before each repair attempt, the runner derives the current proposal's full before/after text with the same domain preview used by validation. It refreshes the view after revisions, including changes of target segment. A failed preview retains available original text and findings without supplying a resulting segment. This context supplements the original exchange and does not mutate the transcript. The model-facing fields are described in the [prompt guide](prompts.md). Module construction failures are fatal. Recoverable proposal model failures record an unsuccessful operation and yield no candidates for that section; other sections and module instances continue. Fatal adapter or application failures cancel peers and retain partial observations. Consumer-visible outcomes are defined by the [report contract](../integrations/output-files.md). ## Changing Modules Frequently reevaluate the default module combination and sequence against what has been observed to work best for most workloads. Prior empirical results inform the current choice without fixing a permanent number or order of passes. Maintain the selected default in the [configuration contract](../config.md#pipeline-and-glossary-selections). 1. Add or update the narrowly scoped package under `internal/modules/`. 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/process_ordered_integration_test.go` (pipeline/report integration)