92 lines
3.2 KiB
Markdown
92 lines
3.2 KiB
Markdown
# 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](../config.md#settings).
|
|
|
|
## 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](../integrations/output-files.md); implementation mapping
|
|
is covered by [report assembly](diagnostics-reporting.md).
|
|
|
|
## 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](../policy/architecture.md#correction-and-concurrency-invariants).
|
|
4. Review validator, registry, chain, batching, malformed-output, diagnostics,
|
|
and decision-cardinality tests; update meaningful coverage under the
|
|
[testing policy](../policy/testing.md).
|
|
5. Update implementation guidance here and any affected external contract in its
|
|
[canonical owner](../policy/documentation.md#canonical-ownership).
|
|
|
|
## Key Tests
|
|
|
|
- `internal/validators/*_test.go`
|
|
- `internal/framework/validators/*_test.go`
|
|
- `internal/framework/processreport/correction_ledger_test.go`
|
|
- `internal/cli/run_test.go`
|