audita/docs/internal/validators.md

Audita Validators

Scope

This document describes validator composition, execution order, and decision handling.

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 by validation_max_prompt_tokens;
• 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 records:

• validator_decisions
• validator_rejected
• warning records (including malformed response warnings)

Correction ledger classifies deterministic vs LLM validator decisions using canonical metadata classes.

Key Tests

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