80 lines
2.2 KiB
Markdown
80 lines
2.2 KiB
Markdown
# Audita Diagnostics and Reporting
|
|
|
|
## Scope
|
|
|
|
This document describes diagnostics artifacts, process report mapping, and correction ledger generation.
|
|
|
|
## Run Directory Ownership
|
|
|
|
`internal/core/diagnostics` owns run-directory creation, artifact writes, and retention decisions.
|
|
|
|
Stable artifact names include:
|
|
- `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`
|
|
- `report.json`
|
|
- `error.log` (failure)
|
|
|
|
## Process Report Mapping
|
|
|
|
`internal/framework/processreport` maps runner/CLI execution facts into `reporting.ProcessReport`.
|
|
|
|
Report metadata fields include:
|
|
- `report_schema_name` (`audita-process-report`)
|
|
- `report_schema_version` (`v1`)
|
|
- `output_schema`
|
|
- `config_version` (when file config exists)
|
|
|
|
The report includes:
|
|
- top-level status/error phase/error message;
|
|
- normalization/chunking summaries;
|
|
- diagnostics metadata paths;
|
|
- per-module results and module summary.
|
|
|
|
## Correction Ledger
|
|
|
|
`internal/framework/processreport/BuildCorrectionLedger` flattens run results into `correction-ledger.json` entries.
|
|
|
|
Dispositions:
|
|
- `applied`
|
|
- `skipped`
|
|
- `rejected`
|
|
- `failed`
|
|
|
|
Validator decisions are split into deterministic and LLM-backed groups using validator metadata classification.
|
|
|
|
## Report Write Paths
|
|
|
|
- run directory always attempts to write `report.json` when possible;
|
|
- optional `--report-json` writes an external report file;
|
|
- on failure paths, report writing is best-effort and does not mask primary run errors.
|
|
|
|
## Retention Interaction
|
|
|
|
Current retention behavior:
|
|
- failed runs are retained;
|
|
- `always` keeps successful runs;
|
|
- `auto` removes only clean successful runs;
|
|
- `never` currently retains successful runs in current implementation.
|
|
|
|
## Redaction
|
|
|
|
Redacted data expectations:
|
|
- effective config artifact uses config redaction;
|
|
- diagnostics payloads and surfaced errors use LLM secret redaction;
|
|
- reports should not include raw API key values.
|
|
|
|
## Key Tests
|
|
|
|
- `internal/core/diagnostics/*_test.go`
|
|
- `internal/framework/processreport/*_test.go`
|
|
- `internal/core/reporting/report_test.go`
|
|
- `internal/cli/run_test.go`
|
|
- `cmd/audita/main_integration_test.go`
|