audita/docs/architecture/validators.md

Audita Validators

Scope

This document defines the built-in validator system used by production module runs.

Ownership boundaries

Built-in validator keys, constructors, and module chains are owned by internal/validators.

Shared runtime execution mechanics are owned by internal/framework/validators, including:

• validator request/result models;
• deterministic proposal checks;
• LLM validator batching and execution;
• decision-cardinality enforcement;
• diagnostics integration.

Execution class metadata is owned by internal/validators/metadata.

Stable 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 module chains

glossary:

• proposal_shape
• no_effect
• original_text_presence
• confidence_threshold
• protected_terms
• non_empty_corrected_text
• spoken_form_plausibility
• meaning_reversal_review

homophones:

• proposal_shape
• no_effect
• original_text_presence
• confidence_threshold
• protected_terms
• non_empty_corrected_text
• spoken_form_plausibility
• meaning_reversal_review

spoken_word:

• proposal_shape
• no_effect
• original_text_presence
• confidence_threshold
• protected_terms
• non_empty_corrected_text
• editorial_review
• meaning_reversal_review

grammar:

• proposal_shape
• no_effect
• original_text_presence
• confidence_threshold
• protected_terms
• non_empty_corrected_text
• editorial_review
• meaning_reversal_review

Ordering and execution semantics

Validator ordering is based on canonical metadata:

• deterministic validators run before LLM-backed validators.

Within each module stage:

• proposals are generated per section;
• validator chains execute on those proposals;
• approved proposals are applied once after section work settles.

Malformed payload behavior

Malformed structured-output from proposal generation and LLM validator calls is downgraded, not treated as a process-fatal transport error.

Current outcomes:

• malformed proposal-generation payloads produce section/module warnings and zero proposals for the affected section;
• malformed validator decision payloads reject the affected validator batch with warnings;
• deterministic validator behavior and runner order remain unchanged.

Reporting identity

Reports and diagnostics use stable validator keys as identifiers.

Correction-ledger deterministic-vs-LLM classification is derived from canonical validator metadata, not package-local hardcoded maps.

Prompt assets

LLM validator prompt assets and prompt metadata are documented in Prompts.