122 lines
3.3 KiB
Markdown
122 lines
3.3 KiB
Markdown
# Audita Public Contract
|
|
|
|
## Scope
|
|
This document defines stability expectations for Audita's external runtime interfaces.
|
|
|
|
Covered interfaces:
|
|
- CLI commands and major flags;
|
|
- versioned config behavior and precedence;
|
|
- transcript/glossary input forms;
|
|
- output schema selection;
|
|
- report schema metadata;
|
|
- diagnostics artifact path metadata;
|
|
- stdout/stderr and exit-code behavior;
|
|
- redaction guarantees.
|
|
|
|
## CLI contract
|
|
Stable commands:
|
|
- `audita process`
|
|
- `audita config validate`
|
|
- `audita config print-effective`
|
|
|
|
Stable high-value `process` flags:
|
|
- `--config`
|
|
- `--glossary`
|
|
- `--output`
|
|
- `--report-json`
|
|
- `--modules`
|
|
- `--output-schema`
|
|
|
|
## Config contract
|
|
Supported config format:
|
|
- YAML;
|
|
- `version: 1`;
|
|
- strict unknown-field rejection.
|
|
|
|
Path resolution for `process` and `config print-effective`:
|
|
1. `--config`
|
|
2. `AUDITA_CONFIG`
|
|
3. `/usr/local/etc/audita/config.yml`
|
|
4. `/etc/audita/config.yml`
|
|
|
|
Missing explicit path is an error. Missing default paths is non-fatal.
|
|
|
|
Precedence for `process`:
|
|
1. defaults
|
|
2. file config
|
|
3. environment overrides
|
|
4. CLI overrides
|
|
|
|
`config validate` remains file-only validation (defaults + file config; no env overrides).
|
|
|
|
Module and output-schema keys are validated against built-in catalogs. Unknown keys fail validation.
|
|
|
|
## Input contract
|
|
Supported transcript JSON top-level forms:
|
|
- array of segments
|
|
- object with `segments` array
|
|
|
|
Supported glossary YAML form:
|
|
- top-level `glossary` list with required entry fields validated by schema parsing.
|
|
|
|
## Output schema contract
|
|
Supported transcript output schemas:
|
|
- `bare-segments` (default)
|
|
- `audita-v1`
|
|
|
|
Unknown schema keys fail before output write.
|
|
|
|
## Report metadata contract
|
|
Process reports include stable report metadata fields:
|
|
- `report_schema_name`
|
|
- `report_schema_version`
|
|
- `output_schema`
|
|
- `config_version` (when file config is loaded)
|
|
|
|
Current values:
|
|
- `report_schema_name = audita-process-report`
|
|
- `report_schema_version = v1`
|
|
|
|
`--report-json` output and run-directory `report.json` use the same report schema metadata.
|
|
|
|
Validator decision/rejection records use stable validator keys via `validator_name`.
|
|
|
|
## Diagnostics metadata contract
|
|
When run-directory initialization succeeds, diagnostics metadata paths reference stable artifacts, including:
|
|
- transcript and normalization artifacts;
|
|
- chunking summary;
|
|
- invocation metadata;
|
|
- redacted effective config;
|
|
- utilization diagnostics;
|
|
- correction ledger;
|
|
- `error.log` on failures.
|
|
|
|
LLM interaction diagnostics include stable prompt and structured-schema identifiers where applicable.
|
|
|
|
## Stdout/stderr and exit codes
|
|
Success:
|
|
- with `--output`, stdout is empty;
|
|
- without `--output`, stdout contains transcript JSON only;
|
|
- report JSON is not written to stdout.
|
|
|
|
Failures:
|
|
- nonzero exit;
|
|
- human-readable stderr summary;
|
|
- diagnostics directory path on stderr when available.
|
|
|
|
Exit codes:
|
|
- `0` success
|
|
- nonzero failure
|
|
|
|
## Redaction contract
|
|
Configured secrets are redacted from:
|
|
- effective config outputs;
|
|
- diagnostics artifacts;
|
|
- report artifacts;
|
|
- surfaced adapter/runtime errors.
|
|
|
|
## Compatibility policy
|
|
Stable command behavior, schema names, report metadata keys, diagnostics-path field semantics, and validator key identities are treated as public contract.
|
|
|
|
Additive fields are acceptable when existing fields and behavior remain compatible.
|