audita/docs/internal/validators.md

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.

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;
• 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; implementation mapping is covered by report assembly.

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.
4. Review validator, registry, chain, batching, malformed-output, diagnostics, and decision-cardinality tests; update meaningful coverage under the testing policy.
5. Update implementation guidance here and any affected external contract in its canonical owner.

Key Tests

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