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 validation.max_prompt_tokens and the existing domain token estimator;
• select an embedded prompt ID and pass payload/description variables to the role-bound structured client with the validator-decision schema.

Oversized single proposals are rejected with validator_input_too_large. Exhausted structural repair becomes a warning and rejected batch decisions. Provider, malformed HTTP envelope, deadline, and admission failures propagate as runtime errors. Schema-valid decisions still undergo exact index/cardinality checks and domain acceptance without a semantic retry.

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