74 lines
4.2 KiB
Markdown
74 lines
4.2 KiB
Markdown
# Audita Operations
|
|
|
|
This guide owns physical output placement and failure handling. The
|
|
[CLI reference](cli.md) owns flags and streams, [configuration](config.md) owns
|
|
settings, and the [output contract](integrations/output-files.md) 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](integrations/transcript-glossary-files.md).
|
|
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.
|
|
For stdout transcript output, they go in `reporting.stdout_dir` (default `.`),
|
|
overridden by `--report-dir`. `--reporting=false` suppresses all three reports
|
|
and removes their path requirements. It does not suppress the stderr summary or
|
|
fatal errors. Stdout contains only transcript JSON; file output leaves it empty.
|
|
|
|
Existing report directories and transcript-output parents must be writable.
|
|
Audita checks active destinations against input, configuration, and selected
|
|
profile files before model dispatch. It preflights file transcript output
|
|
without truncating an existing file. With reporting enabled, all three reports
|
|
are initialized as `in_progress` before input processing. Output is encoded
|
|
fully before publication. Each file is replaced through a temporary file in
|
|
its destination directory: transcript first, then `errors.yml`,
|
|
`recoveries.yml`, and `report.md`. This is per-file replacement, not a
|
|
multi-file transaction. 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` enables detailed evidence independently of reporting. One directory
|
|
named `run-<id>` is created under `diagnostics.work_dir` (default `/tmp/audita`)
|
|
and retained on success or failure. 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.
|