# Audita Modules

## Scope

This document covers module contracts and built-in module packages.

## 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 setup failures surface as `runner_setup` or module setup errors;
- module runtime failures surface as `runner_execution` with partial module results preserved;
- malformed structured proposal payloads are downgraded to warnings and section-level proposal rejection.

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