# 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).

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 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](../integrations/output-files.md).

## 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/process_ordered_integration_test.go` (pipeline/report integration)