# 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
- default `/etc/audita/config.yml`: missing file 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`.
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

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.
- 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.