84 lines
4.9 KiB
Markdown
84 lines
4.9 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 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; 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` 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.
|