audita/docs/architecture/public-contract.md

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