# Automated Device Diagnostics

This document defines the future automated diagnosis feature for a specific
sound device.

## Goal

Allow the user to select a specific device and run reproducible diagnostic
tests that produce logs, realtime stats, and a diagnostic bundle.

## Safety Rules

- Never run real-device automation without explicit user-selected device ID.
- Default to `Keep warm after stop` for known-problem USB DACs or ASIO drivers.
- Avoid rapid release/reopen loops.
- Use cooldowns before release, reacquire, sample-rate switching, and stress
  loops.
- Bound all retries and stop on repeated device invalidation.
- Do not change global Windows power, USB selective suspend, default device, or
  driver settings automatically.
- Do not open ASIO control panels automatically.

## Test Modes

### Dry Run

- Validate planned test matrix.
- Resolve backend/device/format selections.
- Emit `diagnostic_plan.json`.
- Open no audio device.

### NullBackend Run

- Exercise config, signal generation, buffers, logger, realtime stats, and
  bundle export without hardware.

### Single Device Run

- Initialize one selected backend/device/format.
- Play one signal profile.
- Keep warm or drain/release according to lifecycle settings.
- Export logs and summary.

### Format Matrix Test

- Try selected sample rate, bit depth, container, and backend combinations.
- Record probe result and start result separately.
- Use cooldowns between format changes.

### Buffer Ramp-Down Test

- Start with conservative buffer settings.
- Decrease buffer size step by step.
- Stop when underrun/jitter/failure thresholds are crossed.
- Report the smallest stable tested buffer, not a universal guarantee.

### Start/Stop Stress Test

- Disabled by default for known-problem devices.
- Requires explicit confirmation.
- Must use cooldowns and bounded iterations.
- Should prefer hold-open signal/silence transitions over full release/reopen.

### Reinitialize Loop

- Expert-only diagnostic.
- Disabled by default.
- Must never be the first automated test against a device.

## Outputs

Each automated diagnostic should produce:

- `diagnostic_plan.json`
- `config.json`
- `init.log`
- `playback.jsonl`
- `realtime.csv`
- `device_dump.json`
- `format_probe.json`
- `diagnostic_score.json`
- `summary.txt`
- zip diagnostic bundle.

Implemented bundle behavior:

- Writes both a directory bundle and dependency-free zip archive.
- Includes the requested config, playback JSONL, realtime CSV, summary CSV/text,
  PCM summary, device snapshot, format probe, build metadata, and optional
  `diagnostic_plan.json` / `diagnostic_score.json`.
- Refuses overwrite unless the user explicitly enables overwrite logging.

## Current Implementation Status

Implemented components:

- `src/core/diagnostic_planner.h`
- `src/app/diagnostic_ui_state.h`
- Dry-run plans always set `opens_audio_device` to false.
- Automatic single-device plans require an explicit selected device ID and an
  accepted playback format before any real backend path can run.
- Known-problem device plans reject full-release lifecycle modes.
- Format matrix and buffer ramp-down modes require explicit cooldowns.
- Start/stop stress requires expert permission and cooldown.
- Reinitialize loop requires expert permission, bounded reacquire attempts, and
  longer cooldown for known-problem devices.
- Single-run automation can execute the selected backend path, score the run,
  and export the diagnostic bundle.
- Matrix, buffer-ramp, stress, and reinitialize execution are planned and
  logged, but blocked from automatic execution in the current slice.
- Fixture: `tests/fixtures/diagnostic_plan.json`.
