audita/docs/internal/modules.md

Audita Modules

Scope

This document covers internal module contracts and packages. User-selectable keys and the default sequence belong to configuration.

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. Model-facing segment IDs are one-based positions within the proposal request. Generation maps returned 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

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.

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.
3. Wire module registration and catalog resolution through framework module registration and the core module catalog. Update selectable keys in the configuration contract when they change.
4. Verify replacement policy and validator-chain selection against the architecture requirements.
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.
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)