169 lines
5.5 KiB
Markdown
169 lines
5.5 KiB
Markdown
# Audita Public Contract
|
|
|
|
This document defines stability expectations for Audita's external process and data interfaces.
|
|
|
|
## Scope
|
|
|
|
This contract covers:
|
|
- CLI invocation and behavior
|
|
- versioned config file behavior
|
|
- transcript/glossary input forms
|
|
- transcript output schema selection
|
|
- process report schema metadata
|
|
- stable validator key identifiers in report/diagnostics records
|
|
- prompt metadata identifiers in diagnostics
|
|
- diagnostics directory behavior
|
|
- utilization diagnostics and correction-ledger artifact presence/pathing in diagnostics metadata
|
|
- stdout/stderr and exit-code behavior
|
|
- secret redaction guarantees
|
|
- compatibility and deprecation policy
|
|
|
|
## CLI stability expectations
|
|
|
|
Stable commands:
|
|
- `audita process`
|
|
- `audita config validate`
|
|
- `audita config print-effective`
|
|
|
|
For `audita process`, stable high-value flags include:
|
|
- `--config`
|
|
- `--glossary`
|
|
- `--output`
|
|
- `--report-json`
|
|
- `--modules`
|
|
- `--output-schema`
|
|
|
|
Compatibility flags and lower-level tuning flags remain available; they may be narrowed over time with explicit compatibility notes.
|
|
|
|
## Config file stability expectations
|
|
|
|
Supported file format:
|
|
- YAML
|
|
- strict unknown-field rejection
|
|
- explicit `version`
|
|
|
|
Supported version:
|
|
- `version: 1`
|
|
|
|
Precedence for `audita process`:
|
|
1. built-in defaults
|
|
2. file config
|
|
3. environment overrides
|
|
4. CLI overrides
|
|
|
|
Config source behavior:
|
|
- `--config <path>`: missing path is a clear failure
|
|
- `AUDITA_CONFIG`: missing path is a clear failure
|
|
- defaults `/usr/local/etc/audita/config.yml`, then `/etc/audita/config.yml`: both missing is non-fatal
|
|
|
|
## Supported transcript input forms
|
|
|
|
Audita accepts transcript JSON as either:
|
|
- a top-level array of segments
|
|
- an object with a `segments` array
|
|
|
|
Segments must satisfy the schema and validation rules enforced by `internal/core/schema`.
|
|
|
|
## Supported glossary input form
|
|
|
|
Audita accepts glossary YAML with a top-level `glossary` entry list and validates required fields per entry.
|
|
|
|
## Supported output schema names
|
|
|
|
Built-in output schema registry supports:
|
|
- `bare-segments` (default)
|
|
- `audita-v1`
|
|
|
|
`seriatim-intermediate` is planned but not implemented.
|
|
|
|
Unknown output schema names fail clearly.
|
|
|
|
## Report schema/versioning expectations
|
|
|
|
Process report payloads include `report_metadata` with:
|
|
- `report_schema_name`
|
|
- `report_schema_version`
|
|
- `output_schema`
|
|
- `config_version` when file config is used
|
|
|
|
Current values:
|
|
- `report_schema_name`: `audita-process-report`
|
|
- `report_schema_version`: `v1`
|
|
|
|
`--report-json` output and diagnostics run-dir `report.json` use the same report schema metadata.
|
|
|
|
Validator decision/rejection records in reports use stable validator keys in `validator_name`.
|
|
Module results may also include warning records for malformed module-stage LLM payloads.
|
|
Report diagnostics metadata includes artifact-path fields for utilization diagnostics and correction ledger when diagnostics initialization succeeds.
|
|
|
|
## Diagnostics directory behavior
|
|
|
|
When diagnostics directory creation succeeds, Audita writes run artifacts including:
|
|
- invocation metadata
|
|
- redacted effective config
|
|
- transcript/normalization/chunking artifacts
|
|
- utilization diagnostics (`utilization-diagnostics.json`)
|
|
- correction ledger (`correction-ledger.json`)
|
|
- report and failure error log (when applicable)
|
|
- module/LLM diagnostics artifacts as available
|
|
|
|
Retention behavior is controlled by configured retention mode; failed runs are retained.
|
|
|
|
Diagnostics metadata for LLM interactions may include semi-public prompt identifiers:
|
|
- `prompt_id`
|
|
- `prompt_version`
|
|
- `prompt_source`
|
|
- `embedded_path`
|
|
- `sha256`
|
|
|
|
These are diagnostic identifiers, not user-facing prompt override controls.
|
|
|
|
## Stdout/stderr behavior
|
|
|
|
Success behavior:
|
|
- with `--output`, stdout is empty
|
|
- without `--output`, stdout contains only transcript JSON in selected output schema
|
|
- report JSON is not written to stdout
|
|
- success stderr remains empty even when reports/diagnostics contain module warnings
|
|
|
|
Failure behavior:
|
|
- stderr contains human-readable error summary
|
|
- nonzero exit
|
|
- diagnostics path is printed when available
|
|
|
|
## Exit-code behavior
|
|
|
|
- `0`: success
|
|
- nonzero: failure
|
|
|
|
Treat any nonzero exit as a failed invocation.
|
|
|
|
## Secret redaction guarantees
|
|
|
|
Audita redacts API keys and authorization secrets from:
|
|
- effective config outputs (`audita config print-effective`, diagnostics effective-config artifact)
|
|
- report artifacts
|
|
- LLM diagnostics artifacts
|
|
- surfaced request/response error messages
|
|
|
|
Config files should reference secrets via environment variable names (`api_key_env`) rather than embedding secret values.
|
|
|
|
## Compatibility and deprecation policy
|
|
|
|
- Existing stable schema names, report metadata keys, and top-level command behavior are treated as public contract.
|
|
- Existing stable validator keys remain public contract values even when validator semantics are refined.
|
|
- Compatibility inputs (legacy flags/env aliases) may remain during transition windows.
|
|
- Any planned removal or behavior change should include clear compatibility notes and migration guidance.
|
|
|
|
## Breaking changes after 1.0
|
|
|
|
After 1.0, breaking changes include, for example:
|
|
- changing default success/failure exit-code semantics
|
|
- changing stdout/stderr routing semantics
|
|
- silently changing default output schema shape
|
|
- removing supported output schema names without compatibility strategy
|
|
- changing report schema fields or meanings incompatibly
|
|
- changing config version semantics incompatibly without version bump
|
|
|
|
Additive fields, additive diagnostics, and new optional schema names are generally non-breaking when existing behavior remains intact.
|