Refresh documentation and policies and simplify releases
This commit is contained in:
@@ -1,113 +1,110 @@
|
||||
# Audita Operations
|
||||
|
||||
## Scope
|
||||
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.
|
||||
|
||||
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.
|
||||
## Normal Workflow
|
||||
|
||||
For command syntax, see [`docs/cli.md`](cli.md).
|
||||
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.
|
||||
|
||||
## 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.
|
||||
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
|
||||
|
||||
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.
|
||||
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.
|
||||
|
||||
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.
|
||||
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
|
||||
|
||||
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>`.
|
||||
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.
|
||||
|
||||
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)
|
||||
| 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 |
|
||||
|
||||
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.
|
||||
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
|
||||
|
||||
Retention is controlled by `work_dir_retention` (`auto|always|never`).
|
||||
[Configuration](config.md#thresholds-context-and-diagnostics) owns accepted
|
||||
retention values and the default. Current lifecycle behavior is:
|
||||
|
||||
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).
|
||||
| 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` |
|
||||
|
||||
Even when a successful run directory is removed under `auto`, an explicit `--report-json` file is still preserved at its target path.
|
||||
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.
|
||||
|
||||
## Failure Inspection
|
||||
## Artifact Handling
|
||||
|
||||
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.
|
||||
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).
|
||||
|
||||
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`
|
||||
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.
|
||||
|
||||
## Recovery Guidance
|
||||
## Failure Inspection and Recovery
|
||||
|
||||
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.
|
||||
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.
|
||||
|
||||
Not implemented:
|
||||
- resume/checkpoint APIs
|
||||
- remote diagnostics/report storage
|
||||
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.
|
||||
|
||||
Reference in New Issue
Block a user