audita/docs/internal/diagnostics-reporting.md

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