eric/audita
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 6 Wiki Activity

Document the new configuration and processing workflow

Browse Source
This commit is contained in:
Eric Rakestraw
2026-11-10 17:52:14 +00:00
parent 926fa26a31
commit ba1d5d2367
61 changed files with 832 additions and 765 deletions
Download Patch File Download Diff File Expand all files Collapse all files

128
docs/operations.md
View File

@@ -1,94 +1,58 @@
# 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.
This guide owns output placement and failure handling. The [CLI reference](cli.md)
owns invocation, [configuration](config.md) owns settings, and the
[output contract](integrations/output-files.md) owns serialized formats.
## Normal Workflow
## Processing
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.
Inspect the application and PromptKit resources, prepare a transcript, then run
`audita process` with the desired destination. The [examples](../examples/README.md)
show complete projects. Processing preflight checks every configured glossary
correction and selected profile before output preparation and model work. Empty
protection and an empty pipeline are valid. A completed run can contain
recoverable model errors while still applying independently validated edits.
## Required Output Files
## Outputs and lifecycle
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.
Reporting is enabled by default. For transcript file output, `errors.yml`,
`recoveries.yml`, and `report.md` are placed beside that file unless `--report-dir`
is supplied. For stdout transcript output they use the effective report directory.
Disabling reporting leaves its destination inactive and unprobed. Quiet mode
requires a transcript file or `/dev/null`; it suppresses optional messages, not
failures. Stdout carries transcript JSON when selected.
Existing report directories and parents for regular transcript files must be
writable. Audita prevents report writes from overwriting transcript, glossary,
loaded application configuration, host YAML discovered under `profiles_dir`,
or host message files referenced by effective PromptKit `content_file` fields,
and rejects conflicting output destinations. Source paths come from the
runtime's captured configuration; unrelated files in the selected directory
remain eligible 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.
Before processing, Audita checks destination collisions against the transcript,
consumed application and PromptKit sources, and effective host message files. An
intentional in-place transcript replacement is allowed. A regular transcript
output is prepared in a sibling temporary file, leaving the final destination
untouched until successful publication. Pipes and devices are opened only for
delivery; a pipe can wait for its reader. Parent directories for required outputs
must already exist.
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`.
Enabled reports are initialized as `in_progress` before processing. The
transcript is published before final reports; the files do not form a single
transaction. A late report failure may therefore leave a published transcript.
Fatal errors and cancellation clean unpublished temporary resources and attempt
failed-status final reports. An uncatchable termination can leave `in_progress`
evidence. Read exit status and reports together rather than treating a file's
existence as proof of success.
## Diagnostics Directory
## Debug evidence
`--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.
The shared `--debug` flag enables retained artifacts in a run directory beneath
`diagnostics.work_dir`; selecting a work directory alone does not enable capture.
Optional debug preparation or writes can produce redacted warnings without
changing correction decisions or the required output result. Debug material can
include transcript content, prompts, responses, and correction decisions. It is
not anonymized; protect it according to the input's sensitivity. Configured
credential values are redacted at the diagnostic boundary.
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.
## Recovery
## 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.
Exit `0` indicates completion of processing and required outputs; nonzero status
indicates an input, processing, cancellation, or required-output failure.
Recoverable model-operation failures and successful repairs or retries are
recorded separately in the ordinary YAML reports. The Markdown matrices identify
pipeline position, module, and optional operator ID. Fix the input, service, or
destination and rerun when necessary; Audita has no resume or checkpoint API.