audita/docs/architecture/validators.md

Audita Validators

This document describes Audita's built-in validator registry and module validator chains.

For LLM-backed validator prompt asset details, see docs/prompts.md.

Package ownership

Built-in validator construction is package-owned under internal/validators/<validator_key>:

• internal/validators/confidence_threshold
• internal/validators/proposal_shape
• internal/validators/original_text_presence
• internal/validators/non_empty_corrected_text
• internal/validators/no_effect
• internal/validators/protected_terms
• internal/validators/spoken_form_plausibility
• internal/validators/meaning_reversal_review
• internal/validators/editorial_review

Registry and chain wiring stay in:

• internal/validators/registry.go
• internal/validators/chains.go

Shared validator runtime mechanics stay in internal/framework/validators:

• request/result/decision models
• decision cardinality helpers
• protected vocabulary helpers
• shared LLM validator runtime, batching, and diagnostics helpers

Execution classification metadata is defined in internal/validators/metadata:

• deterministic
• llm_backed

Runner ordering uses this metadata so deterministic validators run before LLM-backed validators without concrete framework type assertions.

Scope

Validator chains are built-in runtime behavior.

Current 1.0 boundary:

• built-in validator keys and built-in module chains are stable runtime identifiers;
• thresholds and batching knobs remain configurable where already supported;
• arbitrary user-defined validator chains are deferred.

Built-in validator keys

Deterministic validators

• proposal_shape
  • rejects malformed proposal fields before other validators run.
• confidence_threshold
  • checks proposal confidence against module-specific configured threshold.
• original_text_presence
  • ensures target segment exists and original_text exists in current working segment text.
• non_empty_corrected_text
  • rejects proposals whose previewed resulting segment text would be empty or whitespace-only.
• no_effect
  • rejects proposals where original_text == corrected_text.
• protected_terms
  • protects glossary-derived terms from unsafe mutations in non-glossary modules.
  • glossary stages use glossary-specific protection logic but still report this same stable key.

LLM-backed validators

• spoken_form_plausibility
  • checks whether proposed spoken-form change remains plausible in transcript context.
• meaning_reversal_review
  • checks for likely meaning reversal or semantic contradiction.
• editorial_review
  • performs conservative editorial safety review.

Built-in module chains

Current built-in chains resolved from internal/validators/chains.go:

• 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

Protected terms construction

protected_terms has explicit constructors:

• general constructor used by non-glossary modules through the built-in registry
• glossary-stage constructor used by glossary chain resolution

Both variants preserve existing behavior and report the stable key protected_terms.

Execution semantics

• modules execute serially;
• section proposal work can run concurrently within a module;
• deterministic validators run before LLM-backed validators;
• malformed module proposal payloads are downgraded to section-scoped module warnings with zero proposals for the affected section rather than module failure;
• malformed/missing/duplicate/unknown LLM validator decisions reject the affected validator batch with warnings instead of failing the module;
• oversized single-proposal validator inputs reject only the affected proposal under that validator;
• approved proposals are applied once per module after section work settles.

Validator rejections vs proposal-application skips

• validator rejection:
  • proposal is denied by validator-chain review and appears in validator rejection reporting with validator key and reason code.
• proposal-application skip:
  • proposal passed validators but could not be applied under replacement-policy semantics (for example no matching span at apply time).
• module warning:
  • malformed proposal-generation payloads and malformed validator batches are recorded in module warning records and diagnostics without writing success stderr.

These are separate outcomes and are reported separately.

Reporting and diagnostics identity

• report validator decision/rejection entries use stable validator keys in validator_name.
• report module results include warning records for malformed module-stage LLM payloads.
• validator LLM diagnostics include validator identity in interaction metadata and structured response schema metadata.
• correction ledger entries include deterministic and LLM validator decision snapshots keyed by the same stable validator keys, and keep validator rejection distinct from application-level skip.

Prompt assets are unchanged by the validator package-ownership refactor and remain built-in under internal/prompts.

Configurable knobs that remain supported

• per-module confidence thresholds (thresholds.* / equivalent env+CLI overrides)
• validation batching limits (validation_max_prompt_tokens / equivalent env+CLI overrides)
• validation LLM model/base URL/timeout/retries/concurrency settings

These tune validator behavior without exposing arbitrary user-defined chains.