# Diagnostics Internals

Diagnostics internals live in `internal/core/diagnostics`. Operator-facing run
behavior is documented in [Operations](../operations.md).

## 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:

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

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

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.