audita/docs/operations.md

Audita Operations

This guide owns physical output placement and failure handling. The CLI reference owns flags and streams, configuration owns settings, and the output contract owns schemas.

Normal Workflow

1. Validate a version-2 configuration and its selected profiles with audita config validate --config config.yml.
2. Prepare a transcript and glossary following the input contract.
3. Run audita process input.json --config config.yml --glossary glossary.yaml --output corrected.json.
4. Check the exit status, stderr summary, corrected transcript, and reports. A completed run can contain recoverable model errors and still apply corrections that passed every required validator.

Required Output Files

Reporting is enabled by default. For file transcript output, errors.yml, recoveries.yml, and report.md go in the transcript output's parent directory unless --report-dir is explicitly supplied. For stdout transcript output, they go in the effective reporting.stdout_dir (default .), including a --report-dir override. A config-file or overlay value for reporting.stdout_dir alone does not redirect file-output reports. An active selected report directory must be nonblank. --reporting=false suppresses all three reports and leaves their destination inactive, so it is not probed merely because --report-dir was supplied. It does not suppress the stderr summary or fatal errors. Stdout contains only transcript JSON; file output leaves it empty.

Existing report directories and parents for regular transcript files must be writable. Audita prevents report writes from overwriting transcript, glossary, loaded configuration, or loaded profile sources, and rejects conflicting output destinations. The final transcript may intentionally replace its own input after successful processing; other input/configuration/profile sources remain protected. Preparation never truncates an existing transcript. Device and pipe destinations (such as /dev/null and named pipes) receive ordinary writes at publication time; they are not opened during preflight or replaced with regular files. A pipe write can wait for its reader, and stream write errors are fatal. With reporting enabled, reports still use the output path's parent unless an explicit --report-dir selects another directory; disable reporting when that placement is unsuitable for a stream destination.

With reporting enabled, all three reports are initialized as in_progress before input processing. Output is encoded fully before publication. Each regular output file is replaced through a temporary file on its destination filesystem: transcript first, then errors.yml, recoveries.yml, and report.md. This is per-file replacement, not a multi-file transaction. New files honor the process umask; replacing an existing file preserves its permission bits. A late report error may leave the transcript published; the process exits nonzero and attempts failed-status reports. On fatal processing or cancellation, no completed transcript is published, but partial reports are finalized where possible. An uncatchable termination can leave in_progress.

Diagnostics Directory

--debug or diagnostics.debug enables detailed evidence independently of reporting. One directory named run-<id> is created under diagnostics.work_dir (default /tmp/audita), which --work-dir can override, and retained on success or failure. Selecting --work-dir alone does not enable capture. Without debug, no directory or payload files are created. The parent is created when needed only for debug. Failure to write optional debug evidence prints a redacted stderr diagnostic but does not change correction decisions or the exit status.

Debug evidence includes invocation and effective settings, configuration origins, selected profiles, redacted source and normalized snapshots, normalization and initial chunk summaries, all captured proposed candidates and validator decisions in correction-ledger.json, execution/utilization records, and model interaction files. Individual artifact writes can fail; a directory's existence does not prove every file was written. These files can contain transcript text and prompt/response payloads. Configured backend credentials are redacted, but the transcript itself is not anonymized. Protect and retain the directory according to the sensitivity of the input.

Failure Inspection and Recovery

Exit 0 means processing and every enabled required output completed. Exit 1 means cancellation, fatal processing, or required-output failure. Exit 2 identifies usage or configuration/destination selection errors. Recoverable model-operation failures appear in errors.yml as one record per affected work unit; they do not automatically make the run fail. recoveries.yml records successful operations that needed retry, repair, or proposal filtering. report.md shows every initial chunk and configured module instance, including interrupted and unattempted work. Ordinary reports omit transcript excerpts and full decision ledgers; enable debug when those are needed.

Read stderr and report status first. If a required output failed after a transcript was published, do not treat the file alone as proof of a completed run. Fix the input, service, or destination problem and rerun. Audita has no resume/checkpoint API.