5.8 KiB
Audita Operations
This document owns runtime workflow, physical artifact placement, retention, and recovery. Use the CLI reference for invocation and stream/exit semantics, configuration for settings, and output-file contracts for logical formats.
Normal Workflow
- Choose a configuration and validate it using the configuration commands.
- Prepare input files conforming to the input contract.
- Run the processing command, choosing explicit output and report destinations when those files must survive run-directory cleanup.
- Inspect the corrected transcript and process report. Review rejected or skipped corrections when the report indicates them; successful execution does not mean every proposed correction was applied.
Processing creates a run directory, loads and normalizes the inputs, chunks the transcript, executes the correction pipeline, writes results, and applies retention. Early configuration failures happen before run-directory creation. Failures after initialization attempt to preserve diagnostic evidence; individual artifact writes can fail, so a run directory need not contain every listed file.
Output Files
The caller chooses transcript and optional external report destinations using the CLI. These are separate from the per-run diagnostic directory unless the caller deliberately places them inside it. Choose existing, writable parent directories. Output/report files can be overwritten by subsequent runs using the same destinations.
A later report or cleanup failure can occur after transcript output was written. Inspect the process result and available report before treating the files as a completed run. Retention of the diagnostic directory does not archive caller-selected output files elsewhere.
Diagnostics Directory
The diagnostics configuration
selects the parent work directory. Runs create children named like
run-<unix-nanoseconds>. The runtime creates the work directory if needed.
Report paths may be relative when the supplied work directory is relative;
resolve them using the invocation's working directory.
| Artifact in the run directory | Purpose |
|---|---|
source-transcript.json |
Original transcript input |
source-transcript-parsed.json |
Parsed source representation |
normalized-transcript.json |
Transcript after normalization |
normalization-summary.json |
Normalization counters |
chunking-summary.json |
Section/token summary |
invocation.json |
Invocation metadata |
effective-config.json |
Redacted configuration snapshot |
report.json |
Run's process report |
correction-ledger.json |
Correction dispositions |
utilization-diagnostics.json |
Concurrency and timing observations |
error.log |
Failure details when written |
LLM request, response, and error diagnostics are also written within the run directory. Their nested naming and payloads are debugging details. Prefer paths provided by the report and its decision/warning records over reconstructing those paths. The report describes intended artifact locations, not proof that every write succeeded or that the files still exist after retention.
Retention Behavior
Configuration owns accepted retention values and the default. Current lifecycle behavior is:
| Run outcome / selection | Directory outcome |
|---|---|
| Failed run | Retained regardless of selection |
Successful run, always |
Retained |
Successful run, auto |
Retained if corrections were skipped or rejected; otherwise removed |
Successful run, never |
Currently retained, the same outcome as always |
The name never does not currently mean deletion. Warnings alone do not trigger
retention under auto unless they also produce skipped or rejected corrections.
An external report outside the run directory survives automatic cleanup, but its
artifact paths can then point to removed files.
Artifact Handling
Run artifacts can contain full transcripts, glossary-related context, and LLM prompts/responses. Configured-key redaction does not anonymize those contents. Choose a work directory whose ownership and permissions fit the transcript data, and retain or share artifacts intentionally. Credential-supply mechanisms are owned by configuration.
For a debugging run, select retained diagnostics using the retention flag. Copy needed artifacts before removing completed run directories manually. Avoid deleting a directory while its run is active. Audita does not provide a separate archival/backup or remote artifact storage facility.
Failure Inspection and Recovery
- Read stderr and the exit classification defined by the CLI.
- Locate the external report, or the run directory identified by the error when available. If a late error omits the path, inspect the selected work directory.
- Read the available report and error log. Use report status and error fields to identify the failed phase, then inspect referenced artifacts.
- Correct the concrete input, configuration, endpoint, or filesystem issue and rerun the command with diagnostics retained if further investigation is needed.
Each invocation starts a new run. There is no implemented resume/checkpoint API; recovery is a rerun, not continuation from an artifact. Failures during early configuration or directory creation may leave no report or diagnostic files.