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.