# Audita Validators

## Scope

This document describes internal validator composition, execution order, and
decision handling. These registry keys identify implementation components; they
are not independently selectable through [configuration](../config.md#pipeline-and-output).

## Ownership

Built-in validator keys and chains:
- `internal/validators`

Shared validator runtime mechanics:
- `internal/framework/validators`

Execution-class metadata:
- `internal/validators/metadata`

## Built-In Validator Keys

Deterministic:
- `proposal_shape`
- `confidence_threshold`
- `original_text_presence`
- `non_empty_corrected_text`
- `no_effect`
- `protected_terms`

LLM-backed:
- `spoken_form_plausibility`
- `meaning_reversal_review`
- `editorial_review`

## Built-In Chains

Module chains are defined in `internal/validators/chains.go`.
Glossary, homophones, spoken_word, and grammar each resolve a fixed ordered chain.

## Runtime Execution

For each module section:
1. run deterministic validators;
2. run LLM-backed validators;
3. record decisions and warnings;
4. carry only approved proposals forward.

Decision cardinality is enforced: each candidate proposal must receive exactly one decision per validator.

## LLM Validator Batching

LLM validators:
- build canonical validation request payloads;
- batch using the [configured prompt budget](../config.md#concurrency);
- call structured LLM client using response schema registry.

Oversized single proposals are rejected with `validator_input_too_large`.
Malformed LLM validator responses are downgraded to warnings and rejected batch decisions.

## Decision and Rejection Reporting

Runner collects decisions, rejected candidates, and warning records. Ledger
assembly groups decisions by deterministic versus LLM-backed execution metadata.
The serialized names and fields belong to the
[report and ledger contract](../integrations/output-files.md); implementation mapping
is covered by [report assembly](diagnostics-reporting.md).

## Changing Validators

1. Implement validator behavior under `internal/validators/<validator_key>`;
   update registry and chain wiring in `internal/validators`.
2. Put shared runtime mechanics in `internal/framework/validators` only when
   needed. Keep deterministic versus LLM-backed execution metadata explicit.
3. Preserve exposed identities and decision semantics under the
   [architecture policy](../policy/architecture.md#correction-and-concurrency-invariants).
4. Review validator, registry, chain, batching, malformed-output, diagnostics,
   and decision-cardinality tests; update meaningful coverage under the
   [testing policy](../policy/testing.md).
5. Update implementation guidance here and any affected external contract in its
   [canonical owner](../policy/documentation.md#canonical-ownership).

## Key Tests

- `internal/validators/*_test.go`
- `internal/framework/validators/*_test.go`
- `internal/framework/processreport/correction_ledger_test.go`
- `internal/cli/run_test.go`