114 lines
3.5 KiB
Markdown
114 lines
3.5 KiB
Markdown
# Audita Operations
|
|
|
|
## Scope
|
|
|
|
This document covers operational behavior for `audita process` as currently implemented:
|
|
- run lifecycle;
|
|
- output and report files;
|
|
- diagnostics artifacts;
|
|
- run-directory retention behavior;
|
|
- failure inspection and recovery.
|
|
|
|
For command syntax, see [`docs/cli.md`](cli.md).
|
|
|
|
## Process Run Lifecycle
|
|
|
|
A `process` run performs these high-level steps:
|
|
1. load effective config (defaults + optional file + env + CLI);
|
|
2. create a per-run diagnostics directory;
|
|
3. load transcript JSON and glossary YAML;
|
|
4. parse/validate input schemas;
|
|
5. normalize transcript and compute chunking;
|
|
6. run configured modules/validators;
|
|
7. serialize output schema and write transcript output;
|
|
8. build and write process report;
|
|
9. apply run-directory retention.
|
|
|
|
If a failure happens after diagnostics initialization, the run writes failure details and returns nonzero.
|
|
|
|
## Output Files
|
|
|
|
Transcript output:
|
|
- when `--output <path>` is set, corrected transcript JSON is written to that file;
|
|
- when `--output` is omitted, corrected transcript JSON is written to stdout.
|
|
|
|
Report output:
|
|
- when `--report-json <path>` is set, Audita writes a process report JSON file;
|
|
- the run directory also writes its own `report.json` artifact.
|
|
|
|
On success with `--output`, stdout is expected to be empty.
|
|
|
|
## Diagnostics Directory
|
|
|
|
By default, runs use `work_dir` from effective config (default `/tmp/audita`).
|
|
Each run directory is created under the work dir using a generated ID like `run-<unix-nanos>`.
|
|
|
|
Top-level diagnostics artifacts:
|
|
- `source-transcript.json`
|
|
- `source-transcript-parsed.json`
|
|
- `normalized-transcript.json`
|
|
- `normalization-summary.json`
|
|
- `chunking-summary.json`
|
|
- `utilization-diagnostics.json`
|
|
- `correction-ledger.json`
|
|
- `invocation.json`
|
|
- `effective-config.json` (redacted)
|
|
- `report.json`
|
|
- `error.log` (failure runs)
|
|
|
|
Report diagnostics metadata includes resolved paths to these artifacts.
|
|
|
|
## Correction Ledger and Utilization Diagnostics
|
|
|
|
`correction-ledger.json` records correction dispositions:
|
|
- `applied`
|
|
- `skipped`
|
|
- `rejected`
|
|
- `failed`
|
|
|
|
`utilization-diagnostics.json` records effective concurrency and execution timing summaries for run/module/validator activity.
|
|
|
|
## Retention Behavior
|
|
|
|
Retention is controlled by `work_dir_retention` (`auto|always|never`).
|
|
|
|
Current behavior:
|
|
- failed runs are always retained;
|
|
- `always`: successful runs are retained;
|
|
- `auto`: successful runs are retained only when skipped/rejected corrections occurred; clean successful runs are removed;
|
|
- `never`: successful runs are currently retained (same net retention outcome as `always` in current implementation).
|
|
|
|
Even when a successful run directory is removed under `auto`, an explicit `--report-json` file is still preserved at its target path.
|
|
|
|
## Failure Inspection
|
|
|
|
For failed runs:
|
|
1. read stderr for the top-level failure and diagnostics path;
|
|
2. open `error.log` in the reported run directory;
|
|
3. inspect run `report.json` (`status`, `error_phase`, `error_message`);
|
|
4. inspect related artifacts referenced by report diagnostics metadata.
|
|
|
|
Typical `error_phase` values include:
|
|
- `transcript_read`
|
|
- `glossary_read`
|
|
- `transcript_schema`
|
|
- `glossary_schema`
|
|
- `chunking`
|
|
- `runner_setup`
|
|
- `runner_execution`
|
|
- `output_schema`
|
|
- `serialization`
|
|
- `output_write`
|
|
- `stdout_write`
|
|
|
|
## Recovery Guidance
|
|
|
|
Safe recovery pattern:
|
|
1. correct the immediate input/config/output-path problem;
|
|
2. rerun with `--work-dir-retention always` during debugging;
|
|
3. once stable, restore your normal retention mode.
|
|
|
|
Not implemented:
|
|
- resume/checkpoint APIs
|
|
- remote diagnostics/report storage
|