111 lines
5.8 KiB
Markdown
111 lines
5.8 KiB
Markdown
# Audita Operations
|
|
|
|
This document owns runtime workflow, physical artifact placement, retention, and
|
|
recovery. Use the [CLI reference](cli.md) for invocation and stream/exit semantics,
|
|
[configuration](config.md) for settings, and [output-file contracts](integrations/output-files.md)
|
|
for logical formats.
|
|
|
|
## Normal Workflow
|
|
|
|
1. Choose a configuration and validate it using the
|
|
[configuration commands](cli.md#configuration-commands).
|
|
2. Prepare input files conforming to the [input contract](integrations/transcript-glossary-files.md).
|
|
3. Run the [processing command](cli.md#process-examples), choosing explicit output
|
|
and report destinations when those files must survive run-directory cleanup.
|
|
4. 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](cli.md#process-output-and-exit-behavior). 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](config.md#thresholds-context-and-diagnostics)
|
|
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](integrations/output-files.md#process-report) |
|
|
| `correction-ledger.json` | [Correction dispositions](integrations/output-files.md#correction-ledger) |
|
|
| `utilization-diagnostics.json` | [Concurrency and timing observations](integrations/output-files.md#utilization-diagnostics) |
|
|
| `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](config.md#thresholds-context-and-diagnostics) 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](config.md#secrets).
|
|
|
|
For a debugging run, select retained diagnostics using the
|
|
[retention flag](cli.md#process-flag-reference). 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
|
|
|
|
1. Read stderr and the exit classification defined by the [CLI](cli.md#process-output-and-exit-behavior).
|
|
2. 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.
|
|
3. Read the available report and error log. Use
|
|
[report status and error fields](integrations/output-files.md#process-report)
|
|
to identify the failed phase, then inspect referenced artifacts.
|
|
4. 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.
|