notarius/docs/internal/diagnostics.md

Diagnostics Internals

Diagnostics internals live in internal/core/diagnostics. Operator-facing run behavior is documented in Operations.

Purpose

Diagnostics provide local inspection artifacts for a run without becoming the durable output contract. Durable user output is produced by output modules and written by the CLI.

Diagnostics must not expose secrets.

Run Directory

NewRunDirectory(workDir, retention) creates:

<workDir>/run-<unix-nanoseconds>/

If workDir is empty, it defaults to /tmp/notarius. Empty retention defaults to auto.

The CLI passes the effective diagnostics root from workspace configuration. When workspace.directory is set and diagnostics are enabled, that root is <workspace.directory>/diagnostics. The legacy diagnostics work directory and --diagnostics-dir still pass a diagnostics-only root to this constructor.

The writer makes the work directory if needed, then attempts to create a unique run directory. It retries run ID creation a bounded number of times if a collision occurs.

Artifact Writers

Implemented artifact names:

• invocation.json
• effective-config.json
• resolved-pipeline.json
• resolved-references.json
• checkpoint-events.json
• source-document.json
• run-manifest.json
• run-report.json
• warnings.json
• error.log

JSON artifacts are encoded with indentation and a trailing newline. Writes are atomic through a temporary file in the target directory followed by rename.

Artifact names must be single relative file names. Absolute paths, path separators, and names resolving outside the run directory are rejected.

Redacted Effective Config

Diagnostics writers accept payloads that implement RedactedDiagnosticsPayload. internal/core/config uses this to redact API keys in effective config diagnostics while preserving resolved pipeline context.

The redaction path clones config data before replacing secret values.

Retention

Retention is decided by ShouldRetainRunDirectory.

• Failed runs are always retained.
• always retains successful runs.
• never removes successful runs.
• auto retains successful runs only when warnings exist.
• Unknown retention values are treated as retain by the retention decision, but config validation rejects unsupported values before normal runs.

ApplyRetention removes only the specific run directory.

CLI Failure Behavior

When diagnostics are enabled, the CLI creates the diagnostics run directory after config loading and before pipeline resolution. Failures before that point do not have diagnostics.

When workspace diagnostics are explicitly disabled, the CLI does not create a diagnostics run directory and skips diagnostics artifact writes. Failures are still printed to stderr.

After diagnostics creation, run failures call WriteErrorLog and apply retention with RunSucceeded: false, so the run directory remains available.

When the pipeline returns a partial manifest on failure, the CLI writes that manifest before logging the failure.

Invariants

• Diagnostics paths must be narrow and run-directory scoped.
• Writes should be atomic where practical.
• Secrets must be redacted.
• Diagnostics write failures are command failures because they can hide the information needed for recovery.
• Durable output file contracts belong to output modules and integration docs, not to diagnostics.
• Checkpoint and debug workspace files are separate framework-owned artifacts, not diagnostics artifacts.