64 lines
4.0 KiB
Markdown
64 lines
4.0 KiB
Markdown
# Diagnostics and Reporting Internals
|
|
|
|
The [output-file contract](../integrations/output-files.md) owns public
|
|
schemas and the [operations guide](../operations.md) 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 successful reads
|
|
through PromptKit's profile filesystem and supplies those source paths to CLI;
|
|
no second filename-based discovery rule is used.
|
|
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. Ledger
|
|
mapping uses optional string pointers so an empty proposed replacement is
|
|
serialized for every candidate and an empty applied replacement appears only
|
|
when that candidate applied; see the [public artifact contract](../integrations/output-files.md#debug-only-files).
|
|
Debug write failures reach the CLI through an explicit concurrency-safe diagnostic
|
|
callback and produce redacted stderr messages without aborting processing.
|
|
Completed validator decisions returned with a fatal batch error remain available
|
|
to the debug ledger; they never authorize applying an incompletely validated edit.
|
|
Runner decision records carry the validator's explicit approved, rejected, or
|
|
unavailable disposition into the ledger. Unavailable candidates have a distinct
|
|
top-level ledger disposition, while fatal interruptions remain interrupted when
|
|
no rejection or unavailable decision was returned. Successful validation
|
|
interaction payloads contain the full decoded response, final content, and
|
|
reconciliation outcomes; ignored indices do not become ledger candidates.
|
|
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`.
|