# 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`