Files
audita/docs/operations.md

72 lines
4.2 KiB
Markdown
Raw Normal View History

# Audita Operations
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.
## Processing
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.
Correction repair sends the complete original proposal exchange and branch
history to the selected repair provider. A provider rejection ends that branch
as unavailable; other approved edits can still be applied. See
[configuration](config.md#settings) for the attempt budget and profile selection.
## Outputs and lifecycle
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.
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, and a pipe can wait for its reader. If a transcript destination changes
between a regular file and a pipe or device during processing, Audita can report a
delivery failure while preserving the new destination. Parent directories for
required outputs must already exist. Publication uses the destinations resolved
during preparation. Give concurrent invocations separate destinations, and
choose separate report directories when retaining reports from multiple runs.
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.
After a required write failure or cancellation, Audita attempts to clean
unpublished temporary resources and publish failed-status reports. A cleanup
failure is reported with the earlier error. Cancellation observed after a
stream write still fails the invocation, even when some or all bytes reached
the reader. If failed reports cannot be rendered, available report evidence
remains. An uncatchable termination can leave `in_progress` evidence. Use the
exit status and report status to determine the outcome.
## Debug evidence
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 warnings without
changing correction decisions or the required output result. Debug material can
include transcript content, prompts, responses, and correction decisions.
Protect this material according to the sensitivity of the inputs and responses
and manage its retention. Repair interactions
and revalidation artifacts include proposal and attempt coordinates; the
correction ledger connects them to the original edit.
## Recovery
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.