3.2 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.
Validation operations with unavailable decisions report only affected requested
indices, even when other candidates in the batch continue. Ignored extra
validator entries yield validation_decisions_filtered only for a successful
operation; they do not count as filtered correction proposals. Failed operations
retain their execution counts and never produce a recovery record.
internal/core/diagnostics.OutputSession owns active destination checks,
transcript preflight, report initialization, regular-file replacement, and direct
stream publication. Transcript input is protected from early report writes but
may be the final transcript destination. The LLM runtime records consumed PromptKit sources and effective host message
files and supplies those source paths to CLI;
no second filename-based discovery rule is used.
CLI composes it after configuration, transcript acquisition, and preflight
readiness and before 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. The shared --debug flag enables a unique retained child
under diagnostics.work_dir. CLI passes empty diagnostics paths and nil writers
when debug is off. With debug enabled, it captures source and normalized
snapshots, invocation, effective settings, correction ledger, LLM execution
observations, and model interactions. Candidate capture includes proposals later
rejected or interrupted. Ledger mapping preserves empty proposed and applied
replacements and distinguishes unavailable candidates from interrupted work.
A concurrency-safe diagnostic callback reports optional write failures without aborting processing. Diagnostic redaction uses credential source metadata; debug artifacts can still contain sensitive transcript and prompt content. Execution position and optional operator ID are carried separately from generated safe artifact path coordinates.
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.