notarius/docs/internal/diagnostics.md

Diagnostics Internals

internal/core/diagnostics provides the scoped writer and retention decision used by internal/cli. The physical layout, artifact inventory, retention semantics, failure inspection, and cleanup procedures are canonical in Operations. Configuration fields and defaults are canonical in Configuration.

Run Directory

NewRunDirectory normalizes empty constructor inputs, creates the effective diagnostics root when needed, and allocates a unique timestamp-based child directory. It retries a bounded number of collisions before failing. The resulting RunDirectory retains its creation time and retention mode for later metadata and cleanup decisions.

The package does not resolve workspace configuration. internal/cli derives effective workspace settings first and passes the diagnostics root into the constructor.

Scoped Writers

Typed methods on RunDirectory write invocation metadata, redacted effective configuration, resolved pipeline/reference data, checkpoint events, source data when explicitly requested, manifests, reports, warnings, redacted chunk-plan summaries, and error text. The current filenames and their operator-facing contents are listed in Operations.

The chunk-plan summary records the effective mode, source and candidate digests, requested module, lookup decision, materialization action, validation decision, and publication decision. Its closed decision values make failures and recoverable invalid records inspectable without serializing plan ranges, annotations, source content, reference content, prompts, model responses, or raw invalid-file bytes.

JSON methods indent their payload and append a newline. All artifact writes use a temporary file in the target directory, apply the requested permissions, and rename it into place. Artifact resolution accepts only a single relative base name; absolute paths, separators, and paths escaping the run directory fail before writing.

Redacted Configuration

WriteRedactedEffectiveConfig accepts a RedactedDiagnosticsPayload provider rather than a raw config value. internal/core/config implements that contract by cloning effective config data and removing secret-shaped values before JSON encoding. The diagnostics package therefore never needs configuration-specific field knowledge.

Retention Coordination

ShouldRetainRunDirectory is a pure decision over the effective retention mode, run success, and warning presence. ApplyRetention uses that result to remove only its own run directory. Unsupported modes retain data as a fail-safe, though normal CLI execution rejects them during config validation.

The meaning of each supported mode belongs in Operations; this package implements that contract without loading config or inspecting run artifacts.

CLI State Flow

When diagnostics are enabled, internal/cli creates the run directory after configuration loading and before pipeline resolution. It then writes artifacts as state becomes available: invocation data, effective resolution data, pipeline results, and the final report. This ordering permits later failures to retain the context already established.

Failures before construction have no RunDirectory. Later failures write an error log, preserve any available partial manifest and chunk-plan summary, and apply a failed-run retention decision. A diagnostics write failure is itself a command failure so the CLI does not report success after losing requested inspection data.

When diagnostics are disabled, the CLI carries a nil run directory and the shared writeDiagnostics helper turns writes into no-ops. User-facing errors still go to stderr; that invocation behavior is documented in Operations.

Package Guarantees

• A RunDirectory writes and removes only within its allocated directory.
• JSON and error artifacts use atomic replacement.
• Nil receivers and invalid typed payloads return errors rather than panicking.
• Retention never removes a failed run and never targets the diagnostics root.
• Diagnostics models contain inspection metadata, not the durable output contract.
• Checkpoint and debug serializers remain separate framework components.
• Secret-handling follows the invariant in Architecture.

Tests To Inspect

• internal/core/diagnostics/run_dir_test.go: allocation, artifact confinement, atomic writes, retention, and failure behavior.
• internal/core/diagnostics/artifacts_test.go: stable artifact identifiers.
• internal/core/config/redaction_test.go: clone-and-redact payload behavior.
• internal/core/workspace/settings_test.go: effective diagnostics-root and enablement handoff.
• internal/cli/run_test.go: creation timing, artifact sequencing, disabled diagnostics, overrides, failures, and retention integration.