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