2.4 KiB
Diagnostics and Reporting Internals
The output-file contract owns public schemas and the operations guide owns physical placement.
internal/framework/outcomes contains processing-owned operation references,
counts, failure reasons, filtering details, and work states. It imports no
reporting, CLI, or provider package. The runner records those facts per initial
section and module instance. internal/framework/processreport maps them once
into internal/core/reporting.Snapshot, including nullable counts, grouped
work-unit errors, separate run errors, and one recovery per successful logical
operation. Reports order stages, sections, validators, and batches by semantic
identity, never concurrent completion time. The core reporting package owns
Audita's versioned YAML DTOs, fixed Markdown rendering, and brief CLI
completion formatter. YAML redaction walks serialized string nodes so numeric
and boolean values retain their types. Ordinary reports omit raw causes,
transcript text, complete decisions, and token/timing payloads.
internal/core/diagnostics.OutputSession owns active destination checks,
transcript preflight, report initialization, and per-file final replacement.
CLI composes it after configuration/profile inspection and before reading
inputs or dispatching model work. It does not create ordinary report parents.
On a final write error it attempts other enabled reports and one failed-status
pass; a published transcript is never erased by a later report failure.
Debug is independent. Only diagnostics.debug creates a unique retained child
under diagnostics.work_dir. CLI passes empty diagnostics paths and nil writers
when debug is off. With debug on, source/normalized snapshots, invocation,
effective settings, origins, profiles, initial chunk summary, correction ledger,
indexed execution/utilization, and model interactions are written. Runner
candidate capture includes proposals later rejected or interrupted. Debug
write failures produce safe stderr messages and do not abort processing.
Every debug writer uses all configured backend secrets for redaction, including
unselected backend credentials and source snapshots. Debug can still contain
sensitive transcript and prompt content.
Key Tests
Useful tests: internal/core/reporting/*_test.go,
internal/core/diagnostics/*_test.go,
internal/framework/processreport/*_test.go, and
cmd/audita/main_integration_test.go.