audita/docs/architecture/public-contract.md

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