audita/docs/operations.md

Audita Operations

Scope

This document covers operational behavior for audita process as currently implemented:

• run lifecycle;
• output and report files;
• diagnostics artifacts;
• run-directory retention behavior;
• failure inspection and recovery.

For command syntax, see docs/cli.md.

Process Run Lifecycle

A process run performs these high-level steps:

1. load effective config (defaults + optional file + env + CLI);
2. create a per-run diagnostics directory;
3. load transcript JSON and glossary YAML;
4. parse/validate input schemas;
5. normalize transcript and compute chunking;
6. run configured modules/validators;
7. serialize output schema and write transcript output;
8. build and write process report;
9. apply run-directory retention.

If a failure happens after diagnostics initialization, the run writes failure details and returns nonzero.

Output Files

Transcript output:

• when --output <path> is set, corrected transcript JSON is written to that file;
• when --output is omitted, corrected transcript JSON is written to stdout.

Report output:

• when --report-json <path> is set, Audita writes a process report JSON file;
• the run directory also writes its own report.json artifact.

On success with --output, stdout is expected to be empty.

Diagnostics Directory

By default, runs use work_dir from effective config (default /tmp/audita). Each run directory is created under the work dir using a generated ID like run-<unix-nanos>.

Top-level diagnostics artifacts:

• source-transcript.json
• source-transcript-parsed.json
• normalized-transcript.json
• normalization-summary.json
• chunking-summary.json
• utilization-diagnostics.json
• correction-ledger.json
• invocation.json
• effective-config.json (redacted)
• report.json
• error.log (failure runs)

Report diagnostics metadata includes resolved paths to these artifacts.

Correction Ledger and Utilization Diagnostics

correction-ledger.json records correction dispositions:

• applied
• skipped
• rejected
• failed

utilization-diagnostics.json records effective concurrency and execution timing summaries for run/module/validator activity.

Retention Behavior

Retention is controlled by work_dir_retention (auto|always|never).

Current behavior:

• failed runs are always retained;
• always: successful runs are retained;
• auto: successful runs are retained only when skipped/rejected corrections occurred; clean successful runs are removed;
• never: successful runs are currently retained (same net retention outcome as always in current implementation).

Even when a successful run directory is removed under auto, an explicit --report-json file is still preserved at its target path.

Failure Inspection

For failed runs:

1. read stderr for the top-level failure and diagnostics path;
2. open error.log in the reported run directory;
3. inspect run report.json (status, error_phase, error_message);
4. inspect related artifacts referenced by report diagnostics metadata.

Typical error_phase values include:

• transcript_read
• glossary_read
• transcript_schema
• glossary_schema
• chunking
• runner_setup
• runner_execution
• output_schema
• serialization
• output_write
• stdout_write

Recovery Guidance

Safe recovery pattern:

1. correct the immediate input/config/output-path problem;
2. rerun with --work-dir-retention always during debugging;
3. once stable, restore your normal retention mode.

Not implemented:

• resume/checkpoint APIs
• remote diagnostics/report storage