#[cfg(any(not(coverage), test))]
/// Keeps `format_human_report` explicit because it sits on CLI orchestration, where operators need deterministic exits and artifact paths.
/// Inputs are the typed parameters; output is the return value or side effect.
fn format_human_report(
    capture_path: &std::path::Path,
    report: &SyncAnalysisReport,
    signature_coverage: Option<&SignatureCoverage>,
    calibration: &SyncCalibrationRecommendation,
    verdict: &SyncAnalysisVerdict,
) -> String {
    let first_paired_video = report
        .paired_events
        .first()
        .map(|event| event.video_time_s)
        .unwrap_or(0.0);
    let first_paired_audio = report
        .paired_events
        .first()
        .map(|event| event.audio_time_s)
        .unwrap_or(0.0);
    let unpaired_video = format_onset_list(&unpaired_video_onsets(report));
    let unpaired_audio = format_onset_list(&unpaired_audio_onsets(report));
    let raw_activity_handling = if report.raw_activity_start_is_verdict_relevant() {
        "used as verdict evidence"
    } else {
        "reported only; ignored for verdict/calibration because it disagrees with paired pulses"
    };
    let signature_coverage = format_signature_coverage(signature_coverage);
    format!(
        "\
A/V sync report for {capture}
- verdict: {status} ({passed})
- verdict reason: {reason}
- evidence mode: {evidence_mode}
- p95 abs skew: {p95:.1} ms
- video onsets: {video_events}
- audio onsets: {audio_events}
- paired pulses: {paired_events}
- activity start delta: {activity_start_delta:+.1} ms (audio after video is positive)
- raw first video activity: {raw_video:.3} s
- raw first audio activity: {raw_audio:.3} s
- raw-vs-paired disagreement: {raw_pair_disagreement:.1} ms
- raw activity handling: {raw_activity_handling}
- paired window first video/audio: {paired_video:.3} s / {paired_audio:.3} s
- unpaired video onsets: {unpaired_video}
- unpaired audio onsets: {unpaired_audio}
{signature_coverage}\
- first skew: {first_skew:+.1} ms (audio after video is positive)
- last skew: {last_skew:+.1} ms
- mean skew: {mean_skew:+.1} ms
- median skew: {median_skew:+.1} ms
- max abs skew: {max_abs:.1} ms
- drift: {drift:+.1} ms
- calibration ready: {cal_ready}
- recommended audio offset adjust: {audio_adjust:+} us
- alternative video offset adjust: {video_adjust:+} us
- calibration note: {cal_note}
",
        capture = capture_path.display(),
        status = verdict.status,
        passed = if verdict.passed { "pass" } else { "fail" },
        reason = verdict.reason,
        evidence_mode = if report.coded_events {
            "coded pulses"
        } else {
            "cadence/brightness pulses"
        },
        p95 = verdict.p95_abs_skew_ms,
        video_events = report.video_event_count,
        audio_events = report.audio_event_count,
        paired_events = report.paired_event_count,
        activity_start_delta = report.activity_start_delta_ms,
        raw_video = report.raw_first_video_activity_s,
        raw_audio = report.raw_first_audio_activity_s,
        raw_pair_disagreement = report.activity_start_pair_disagreement_ms().abs(),
        raw_activity_handling = raw_activity_handling,
        paired_video = first_paired_video,
        paired_audio = first_paired_audio,
        unpaired_video = unpaired_video,
        unpaired_audio = unpaired_audio,
        signature_coverage = signature_coverage,
        first_skew = report.first_skew_ms,
        last_skew = report.last_skew_ms,
        mean_skew = report.mean_skew_ms,
        median_skew = report.median_skew_ms,
        max_abs = report.max_abs_skew_ms,
        drift = report.drift_ms,
        cal_ready = calibration.ready,
        audio_adjust = calibration.recommended_audio_offset_adjust_us,
        video_adjust = calibration.recommended_video_offset_adjust_us,
        cal_note = calibration.note,
    )
}
