94 lines
4.4 KiB
Markdown
94 lines
4.4 KiB
Markdown
# 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](../operations.md#diagnostics-directory). Configuration fields and
|
|
defaults are canonical in [Configuration](../config.md#diagnostics).
|
|
|
|
## 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, and error text. The
|
|
current filenames and their operator-facing contents are listed in
|
|
[Operations](../operations.md#diagnostics-directory).
|
|
|
|
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](../operations.md#retention); 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 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](../operations.md#failures).
|
|
|
|
## 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](../policy/architecture.md#state-output-and-safety).
|
|
|
|
## 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.
|