forge_dictate/

diagnostics.rs

//! Per-take diagnostics written to disk, best-effort.
//!
//! One take becomes one directory holding the original capture, every
//! transcription stage, and the timings - so "which stage ate the
//! words" is answerable by opening files rather than by rerunning the
//! take under investigation. The layout is granular on purpose: the
//! pre-normalization text is kept per window, because the joined form
//! cannot show whether a window lost the words or the join did.
//!
//! Everything here is best-effort: a capture that cannot be written is
//! logged and dropped, never propagated, because diagnostics must
//! never break a take.
//!
//! Retention: the store keeps the last [`RETAINED_TAKES`] takes,
//! pruning the oldest by directory name after each write.

use std::path::{Path, PathBuf};
use std::time::{SystemTime, UNIX_EPOCH};

use serde_json::json;
use transcribe_cpp::CancelToken;

use crate::audio::SAMPLE_RATE;
use crate::config::ModelSpec;
use crate::engine::Stages;

/// One window's record: the slice of capture it covered and the raw
/// pre-normalization text it produced.
pub(crate) struct WindowRecord {
    pub(crate) start_ms: u64,
    pub(crate) end_ms: u64,
    pub(crate) raw: String,
}

/// The models a take ran under: the resolved specs the engine was built
/// with.
pub(crate) struct TakeModels {
    pub(crate) asr: ModelSpec,
    /// `None` when no normalizer is configured.
    pub(crate) normalizer: Option<ModelSpec>,
    /// The language hint, `None` when the run autodetects.
    pub(crate) language: Option<String>,
}

impl TakeModels {
    pub(crate) fn from_config(cfg: &crate::Config) -> Self {
        Self {
            asr: cfg.asr_model.clone(),
            normalizer: cfg.normalizer.clone(),
            language: cfg.language.clone(),
        }
    }
}

/// Everything one finished take contributes to the store.
pub(crate) struct TakeRecord<'a> {
    pub(crate) audio: &'a [f32],
    pub(crate) windows: &'a [WindowRecord],
    /// The exact normalizer input.
    pub(crate) joined: &'a str,
    pub(crate) text: &'a str,
    pub(crate) stages: &'a Stages,
    /// The models that made this take.
    pub(crate) models: &'a TakeModels,
    /// Engine accept to first window start: the queue, and for early
    /// takes the tail of the model load. The felt lag the stages do
    /// not carry; `start_lag_ms` + `processing_ms` spans accept to
    /// reply.
    pub(crate) start_lag_ms: u64,
    pub(crate) processing_ms: u64,
    pub(crate) truncated: bool,
    /// `transcript`, `empty` or `recognition_error`.
    pub(crate) outcome: &'a str,
    /// The window whose recognition failed and the error text, when
    /// the take ended in a recognition error.
    pub(crate) recognition_error: Option<(usize, String)>,
}

/// How many takes the store keeps, and the bench's corpus along with it.
///
/// Measured on the maintainer's live store (2026-10-06, ten takes,
/// read-only): 10.3 MB in total, median 226 KB, mean 1.03 MB, worst
/// 7.68 MB - a mean take is about half a minute of audio. The cap is
/// the bench's run time as much as its disk, since a run scores the
/// whole store: 100 takes is roughly an hour of speech, around a minute
/// of wall clock per run at the measured rate, and about 55 MB typical
/// (770 MB if every take were the worst case).
const RETAINED_TAKES: usize = 100;

/// The unix-millisecond stamp a take directory is named by, as
/// `take-<13 digits>`: sortable, and 13 digits holds until the year
/// 2286 so lexicographic order never lies about recency.
pub(crate) fn take_stamp() -> u128 {
    SystemTime::now().duration_since(UNIX_EPOCH).map_or(0, |d| d.as_millis())
}

/// Claim `dir/take-<stamp>/`, advancing a millisecond per name already taken,
/// and answer the name and the directory it claimed.
///
/// **The claim is the `create_dir`, not a probe before it.** A name checked
/// with `exists()` and made with `create_dir_all` lets two writers stamped in
/// the same millisecond both pass the check and land in one directory, where
/// the later silently replaces the earlier's wav and meta. `create_dir` is the
/// one call that fails on a taken name, and its `AlreadyExists` is the loop's
/// next candidate.
///
/// Advancing the stamp rather than suffixing the name keeps the shape every
/// reader of a store directory goes by - `take-` followed by all digits (see
/// [`starts_take`]) - and the order the names sort in.
///
/// **The parent has to exist.** `create_dir` makes one directory, so a caller
/// whose store may not exist yet creates it first: `capture_take` and
/// `store_read_aloud_at` both do.
pub(crate) fn claim_take_dir(dir: &Path, stamp: u128) -> std::io::Result<(String, PathBuf)> {
    let mut stamp = stamp;
    loop {
        let name = format!("take-{stamp:013}");
        let take_dir = dir.join(&name);
        match std::fs::create_dir(&take_dir) {
            Ok(()) => return Ok((name, take_dir)),
            Err(error) if error.kind() == std::io::ErrorKind::AlreadyExists => stamp += 1,
            Err(source) => return Err(source),
        }
    }
}

/// Write one take into `dir/take-<take_id>/` and prune the store to
/// [`RETAINED_TAKES`]. Nothing here can fail the caller: every step
/// logs its own failure and stops that take's capture.
///
/// `cancel` is this take's token. Its answer is sent before the write
/// starts, so a cancel that lands while the write runs is seen here and
/// nowhere else: the directory this call claimed is removed rather than
/// left to persist and count toward retention. When the removal itself
/// fails, the directory is left in place and the failure is logged.
pub(crate) fn capture_take(dir: &Path, take_id: u128, take: &TakeRecord<'_>, cancel: &CancelToken) {
    // A take already abandoned before the write starts pays no write; the
    // check after it is for one cancelled while the files are landing.
    if cancel.is_cancelled() {
        return;
    }
    // The store is lazily made: a first take is what brings it into being.
    if let Err(error) = std::fs::create_dir_all(dir) {
        tracing::warn!(
            event_name = "diagnostics_store_uncreatable",
            %error,
            dir = %dir.display(),
            "diagnostics: store directory could not be made"
        );
        return;
    }
    let take_dir = match claim_take_dir(dir, take_id) {
        Ok((_, take_dir)) => take_dir,
        Err(error) => {
            tracing::warn!(
                event_name = "diagnostics_take_dir_unclaimed",
                %error,
                dir = %dir.display(),
                "diagnostics: store directory not claimed"
            );
            return;
        }
    };
    let wrote = write_take(&take_dir, take);
    if cancel.is_cancelled() {
        if let Err(error) = std::fs::remove_dir_all(&take_dir) {
            tracing::warn!(
                event_name = "diagnostics_cancelled_take_not_removed",
                %error,
                dir = %take_dir.display(),
                "diagnostics: cancelled take's directory could not be removed"
            );
        }
        return;
    }
    // Pruned only after a complete write, as before the write was split out:
    // a partial directory has not earned a retention pass.
    if wrote {
        prune(dir);
    }
}

/// One claimed take's files, `meta.json` last, answering whether the take
/// was written whole.
///
/// A failure stops this take's write and leaves a partial directory, which
/// never reads as a complete take; [`capture_take`] then skips the prune.
/// An abandoned take is taken back by [`capture_take`] when its token is
/// set by the time this returns.
fn write_take(take_dir: &Path, take: &TakeRecord<'_>) -> bool {
    // meta.json is written LAST, which is what makes a take directory
    // without it incomplete: an early return above leaves a partial
    // directory that still counts for retention, but never reads as a
    // complete take.
    if let Err(error) = std::fs::create_dir_all(take_dir.join("raw")) {
        tracing::warn!(
            event_name = "diagnostics_store_dir_unwritable",
            %error,
            dir = %take_dir.display(),
            "diagnostics: store directory not writable"
        );
        return false;
    }

    if let Err(error) = write_wav(&take_dir.join("output.wav"), take.audio) {
        tracing::warn!(
            event_name = "diagnostics_capture_not_written",
            %error,
            dir = %take_dir.display(),
            "diagnostics: capture not written"
        );
        return false;
    }
    for (k, window) in take.windows.iter().enumerate() {
        if let Err(error) = std::fs::write(take_dir.join(format!("raw/{k}.txt")), &window.raw) {
            tracing::warn!(
                event_name = "diagnostics_window_transcript_not_written",
                %error,
                dir = %take_dir.display(),
                window = k,
                "diagnostics: window transcript not written"
            );
            return false;
        }
    }
    if let Err(error) = std::fs::write(take_dir.join("joined.txt"), take.joined) {
        tracing::warn!(
            event_name = "diagnostics_joined_transcript_not_written",
            %error,
            dir = %take_dir.display(),
            "diagnostics: joined transcript not written"
        );
        return false;
    }
    if let Err(error) = std::fs::write(take_dir.join("text.txt"), take.text) {
        tracing::warn!(
            event_name = "diagnostics_normalized_transcript_not_written",
            %error,
            dir = %take_dir.display(),
            "diagnostics: normalized transcript not written"
        );
        return false;
    }

    let ms = |d: std::time::Duration| u64::try_from(d.as_millis()).unwrap_or(u64::MAX);
    let mut meta = json!({
        "duration_ms": ms(take.stages.audio),
        // Accept to first window start, so the wall total reconciles:
        // start_lag_ms + processing_ms spans the engine's accept-to-reply.
        "start_lag_ms": take.start_lag_ms,
        "processing_ms": take.processing_ms,
        "truncated": take.truncated,
        "outcome": take.outcome,
        "asr": model_identity(&take.models.asr),
        "normalizer": take.models.normalizer.as_ref().map(model_identity),
        // Whether this take's text went through a completed cleanup pass:
        // false with none configured, on a failed pass, and on a take whose
        // recognition failed, so the pass never ran. A completed pass can
        // still have rewritten nothing.
        "normalizer_ran": take.stages.normalize.is_some(),
        // The language hint the engine was configured with; null
        // autodetects. Not the language a take turned out to be in.
        "language": take.models.language,
        // The release the take was made under: the workspace version, not
        // build identity.
        "forge_version": env!("CARGO_PKG_VERSION"),
        "stages_ms": {
            "mel": ms(take.stages.mel),
            "encode": ms(take.stages.encode),
            "decode": ms(take.stages.decode),
        },
        "windows": take.windows.iter().enumerate().map(|(k, window)| json!({
            "index": k,
            "file": format!("raw/{k}.txt"),
            "start_ms": window.start_ms,
            "end_ms": window.end_ms,
        })).collect::<Vec<_>>(),
    });
    if let Some((window, error)) = &take.recognition_error {
        meta["recognition_error"] = json!({ "window": window, "error": error });
    }
    match serde_json::to_vec_pretty(&meta) {
        Ok(bytes) => {
            if let Err(error) = std::fs::write(take_dir.join("meta.json"), bytes) {
                tracing::warn!(
                    event_name = "diagnostics_metadata_not_written",
                    %error,
                    dir = %take_dir.display(),
                    "diagnostics: metadata not written"
                );
                return false;
            }
        }
        Err(error) => {
            tracing::warn!(
                event_name = "diagnostics_metadata_not_serializable",
                %error,
                dir = %take_dir.display(),
                "diagnostics: metadata not serializable"
            );
            return false;
        }
    }
    true
}

/// One role's resolved spec as `meta.json` names it: the file, the digest
/// it declares where it declares one, and the size.
fn model_identity(spec: &ModelSpec) -> serde_json::Value {
    json!({ "file": spec.file, "sha256": spec.sha256, "size": spec.size })
}

/// A file's sha256, lowercase hex; empty when it cannot be read.
pub(crate) fn sha256_file(path: &Path) -> String {
    use sha2::Digest as _;
    let Ok(bytes) = std::fs::read(path) else {
        return String::new();
    };
    hex::encode(sha2::Sha256::digest(&bytes))
}

/// Encode `audio` as a canonical 16-bit PCM wav at the one rate every
/// model here reads.
pub(crate) fn write_wav(path: &Path, audio: &[f32]) -> Result<(), String> {
    let spec = hound::WavSpec {
        channels: 1,
        sample_rate: SAMPLE_RATE,
        bits_per_sample: 16,
        sample_format: hound::SampleFormat::Int,
    };
    let mut writer = hound::WavWriter::create(path, spec).map_err(|error| error.to_string())?;
    for &sample in audio {
        // Safe after the clamp: the value is inside i16's range.
        #[allow(clippy::cast_possible_truncation, clippy::cast_possible_wrap)]
        let value = (sample * 32767.0).clamp(-32768.0, 32767.0).round() as i16;
        writer.write_sample(value).map_err(|error| error.to_string())?;
    }
    writer.finalize().map_err(|error| error.to_string())
}

/// Delete every take but the newest [`RETAINED_TAKES`]. Only store
/// directories count - `take-` followed by nothing but digits - so a
/// user directory that happens to share the prefix is never touched.
/// Removal is best-effort, and a directory that will not leave is
/// logged: it occupies a retention slot invisibly otherwise.
fn prune(dir: &Path) {
    let Ok(entries) = std::fs::read_dir(dir) else { return };
    let mut takes: Vec<PathBuf> = entries
        .flatten()
        .map(|entry| entry.path())
        .filter(|path| path.is_dir() && path.file_name().is_some_and(starts_take))
        .collect();
    takes.sort();
    for stale in takes.iter().rev().skip(RETAINED_TAKES) {
        if let Err(error) = std::fs::remove_dir_all(stale) {
            tracing::warn!(
                event_name = "diagnostics_stale_take_not_pruned",
                %error,
                dir = %stale.display(),
                "diagnostics: stale take not pruned"
            );
        }
    }
}

/// A store directory: `take-` followed by all-ASCII digits. Anything
/// else - `take-2026-photos`, a user's own folder - is not ours to
/// prune.
fn starts_take(name: &std::ffi::OsStr) -> bool {
    name.to_str().is_some_and(|s| {
        let id = s.strip_prefix("take-").unwrap_or_default();
        !id.is_empty() && id.len() >= 13 && id.bytes().all(|b| b.is_ascii_digit())
    })
}

#[cfg(test)]
mod tests {
    use super::*;
    use std::time::Duration;

    use crate::{ConfigBuilder, ModelFacts, ModelSpec};

    /// The cleanup role's stub spec, digest-free: the feed's doc-table
    /// models publish none, so the nullable sha256 is the shape to pin.
    fn stub_normalizer() -> ModelSpec {
        ModelSpec {
            file: "cleanup-stub.gguf".into(),
            url: String::new(),
            size: 7,
            sha256: None,
            facts: ModelFacts::default(),
        }
    }

    /// A stub configuration's resolved models, through the same
    /// `from_config` the engine uses.
    fn stub_models(normalizer: Option<ModelSpec>, language: Option<&str>) -> TakeModels {
        let mut builder = ConfigBuilder::new()
            .asr_model(ModelSpec {
                file: "asr-stub.gguf".into(),
                url: String::new(),
                size: 4242,
                sha256: Some("a1b2c3".into()),
                facts: ModelFacts::default(),
            })
            .normalizer(normalizer);
        if let Some(language) = language {
            builder = builder.language(language);
        }
        TakeModels::from_config(&builder.build())
    }

    fn take_record<'a>(
        models: &'a TakeModels,
        audio: &'a [f32],
        windows: &'a [WindowRecord],
        joined: &'a str,
        text: &'a str,
        stages: &'a Stages,
    ) -> TakeRecord<'a> {
        TakeRecord {
            audio,
            windows,
            joined,
            text,
            stages,
            models,
            start_lag_ms: 3,
            processing_ms: 7,
            truncated: false,
            outcome: "transcript",
            recognition_error: None,
        }
    }

    /// A take cancelled before its write starts still leaves no directory
    /// behind: the token can be set between the branch's decision and the
    /// writer's first step, and the writer takes back what it claimed
    /// rather than leave it to count toward retention.
    #[test]
    fn a_take_cancelled_before_its_write_leaves_no_directory() {
        let dir = tempfile::tempdir().unwrap();
        let audio = vec![0.5; 16];
        let stages = Stages::default();
        let models = stub_models(None, None);
        let cancel = CancelToken::new();
        cancel.cancel();
        capture_take(
            dir.path(),
            41,
            &take_record(&models, &audio, &[], "early", "early", &stages),
            &cancel,
        );
        let entries: Vec<_> = std::fs::read_dir(dir.path()).unwrap().flatten().collect();
        assert!(
            entries.is_empty(),
            "a cancelled take persists nothing, found {} entries",
            entries.len()
        );
    }

    /// The store mirrors the granular layout: capture, per-window raw
    /// transcripts, the exact normalizer input, the final text, and the
    /// metadata that ties them together.
    #[test]
    fn a_take_writes_the_whole_store() {
        let dir = tempfile::tempdir().unwrap();
        let audio = vec![0.5; SAMPLE_RATE as usize];
        let stages = Stages { audio: Duration::from_millis(1000), ..Stages::default() };
        let windows = vec![
            WindowRecord { start_ms: 0, end_ms: 500, raw: "first take".into() },
            WindowRecord { start_ms: 500, end_ms: 1000, raw: "second take".into() },
        ];
        let models = stub_models(None, None);
        capture_take(
            dir.path(),
            42,
            &take_record(
                &models,
                &audio,
                &windows,
                "first take second take",
                "First take, second take.",
                &stages,
            ),
            &CancelToken::new(),
        );

        let take = dir.path().join("take-0000000000042");
        let mut reader = hound::WavReader::open(take.join("output.wav")).unwrap();
        assert_eq!(
            reader.spec().sample_rate,
            SAMPLE_RATE,
            "the capture is stored at the model rate"
        );
        assert_eq!(
            reader.samples::<i16>().count(),
            SAMPLE_RATE as usize,
            "the whole capture is stored"
        );
        assert_eq!(
            std::fs::read_to_string(take.join("raw/0.txt")).unwrap(),
            "first take",
            "window 0's pre-normalization text"
        );
        assert_eq!(
            std::fs::read_to_string(take.join("raw/1.txt")).unwrap(),
            "second take",
            "window 1's pre-normalization text"
        );
        assert_eq!(
            std::fs::read_to_string(take.join("joined.txt")).unwrap(),
            "first take second take",
            "joined.txt is the exact normalizer input"
        );
        assert_eq!(
            std::fs::read_to_string(take.join("text.txt")).unwrap(),
            "First take, second take.",
            "text.txt is the final normalized text"
        );
        let meta: serde_json::Value =
            serde_json::from_str(&std::fs::read_to_string(take.join("meta.json")).unwrap())
                .unwrap();
        assert_eq!(meta["duration_ms"], 1000);
        assert_eq!(meta["start_lag_ms"], 3, "the pre-transcribe lag reaches the metadata");
        assert_eq!(meta["processing_ms"], 7);
        assert_eq!(meta["truncated"], false);
        assert_eq!(meta["outcome"], "transcript");
        assert_eq!(meta["stages_ms"]["mel"], 0);
        assert_eq!(meta["windows"][0]["file"], "raw/0.txt");
        assert_eq!(meta["windows"][1]["end_ms"], 1000);
        assert!(
            meta.get("recognition_error").is_none(),
            "a successful take names no failed window"
        );
    }

    /// A recognition-error take names the window that failed and the
    /// error text, so meta.json answers "which stage ate the words"
    /// for the one outcome whose transcript stages cannot.
    #[test]
    fn a_recognition_error_take_records_the_failed_window() {
        let dir = tempfile::tempdir().unwrap();
        let audio = vec![0.5; 16];
        let stages = Stages::default();
        let windows = vec![WindowRecord { start_ms: 0, end_ms: 500, raw: "first".into() }];
        let models = stub_models(None, None);
        let mut record = take_record(&models, &audio, &windows, "first", "", &stages);
        record.outcome = "recognition_error";
        record.recognition_error = Some((1, "decode failed: bad input".into()));
        capture_take(dir.path(), 7, &record, &CancelToken::new());

        let meta: serde_json::Value = serde_json::from_str(
            &std::fs::read_to_string(dir.path().join("take-0000000000007/meta.json")).unwrap(),
        )
        .unwrap();
        assert_eq!(meta["outcome"], "recognition_error");
        assert_eq!(meta["recognition_error"]["window"], 1, "the failed window index");
        assert_eq!(
            meta["recognition_error"]["error"], "decode failed: bad input",
            "the recognition failure text"
        );
    }

    /// A take names the models that made it: both roles' resolved specs
    /// by the three fields a spec declares, plus whether the cleanup pass
    /// ran, the language, and the release. This is what makes the archive
    /// usable for comparing models.
    #[test]
    fn a_take_names_the_models_that_made_it() {
        let dir = tempfile::tempdir().unwrap();
        let audio = vec![0.5; 16];
        let stages = Stages {
            audio: Duration::from_millis(1000),
            normalize: Some(Duration::from_millis(11)),
            ..Stages::default()
        };
        let windows = vec![];
        let models = stub_models(Some(stub_normalizer()), Some("en"));
        let record = take_record(&models, &audio, &windows, "", "first take", &stages);
        capture_take(dir.path(), 9, &record, &CancelToken::new());

        let meta: serde_json::Value = serde_json::from_str(
            &std::fs::read_to_string(dir.path().join("take-0000000000009/meta.json")).unwrap(),
        )
        .unwrap();
        assert_eq!(meta["asr"]["file"], "asr-stub.gguf", "the transcribing spec's file");
        assert_eq!(meta["asr"]["sha256"], "a1b2c3", "the digest the transcribing spec declares");
        assert_eq!(meta["asr"]["size"], 4242, "the size the transcribing spec declares");
        assert_eq!(meta["normalizer"]["file"], "cleanup-stub.gguf", "the cleanup spec's file");
        assert!(
            meta["normalizer"]["sha256"].is_null(),
            "a spec whose upstream publishes no digest records none, got {}",
            meta["normalizer"]["sha256"]
        );
        assert_eq!(meta["normalizer"]["size"], 7, "the size the cleanup spec declares");
        assert_eq!(
            meta["normalizer_ran"], true,
            "a take whose stages carry a normalize pass ran the normalizer"
        );
        assert_eq!(meta["language"], "en", "the language the engine was configured with");
        assert_eq!(
            meta["forge_version"],
            env!("CARGO_PKG_VERSION"),
            "the release the take was made under"
        );
    }

    /// The nullable shape: with no normalizer configured, the spec is
    /// null and the take says no cleanup ran. An autodetecting run
    /// records no language either.
    #[test]
    fn a_take_with_the_normalizer_off_names_no_cleanup_model() {
        let dir = tempfile::tempdir().unwrap();
        let audio = vec![0.5; 16];
        let stages = Stages::default();
        let windows = vec![];
        let models = stub_models(None, None);
        let record = take_record(&models, &audio, &windows, "", "first take", &stages);
        capture_take(dir.path(), 8, &record, &CancelToken::new());

        let meta: serde_json::Value = serde_json::from_str(
            &std::fs::read_to_string(dir.path().join("take-0000000000008/meta.json")).unwrap(),
        )
        .unwrap();
        assert!(meta["normalizer"].is_null(), "no configured cleanup names no model");
        assert_eq!(meta["normalizer_ran"], false, "no normalize stage means it did not run");
        assert!(meta["language"].is_null(), "autodetect records no language");
        assert_eq!(
            meta["asr"]["file"], "asr-stub.gguf",
            "the transcribing spec is named whatever the cleanup role is"
        );
    }

    /// Prune only ever touches store directories: `take-` followed by
    /// nothing but digits. A user folder sharing the prefix is not ours
    /// to remove, whatever its age.
    #[test]
    fn prune_never_touches_a_foreign_directory() {
        let dir = tempfile::tempdir().unwrap();
        let foreign = dir.path().join("take-2026-photos");
        std::fs::create_dir_all(&foreign).unwrap();
        std::fs::write(foreign.join("holiday.jpg"), "not ours").unwrap();
        let stages = Stages::default();
        let audio = vec![0.5; 16];
        let windows = vec![];
        let models = stub_models(None, None);
        for id in 1..=RETAINED_TAKES as u128 + 1 {
            capture_take(
                dir.path(),
                id,
                &take_record(&models, &audio, &windows, "", "", &stages),
                &CancelToken::new(),
            );
        }
        assert!(foreign.is_dir(), "a user directory sharing the take- prefix must survive pruning");
        let takes: Vec<_> = std::fs::read_dir(dir.path())
            .unwrap()
            .flatten()
            .map(|e| e.file_name().to_string_lossy().into_owned())
            .filter(|n| n.starts_with("take-0"))
            .collect();
        assert_eq!(
            takes.len(),
            RETAINED_TAKES,
            "the store kept a different number than its own cap, got {takes:?}"
        );
    }

    /// The store cannot grow without bound: past the retained count the
    /// oldest takes leave, by directory name. **The cap is the knob, so
    /// this is a test of the pruning, not of the number** - it writes
    /// one past whatever `RETAINED_TAKES` is and asserts the survivors.
    #[test]
    fn the_store_keeps_the_last_of_its_retention() {
        let dir = tempfile::tempdir().unwrap();
        let audio = vec![0.5; 16];
        let stages = Stages::default();
        let windows = vec![];
        let models = stub_models(None, None);
        let newest = RETAINED_TAKES as u128 + 2;
        for id in 1..=newest {
            capture_take(
                dir.path(),
                id,
                &take_record(&models, &audio, &windows, "", "", &stages),
                &CancelToken::new(),
            );
        }
        let takes: Vec<_> = std::fs::read_dir(dir.path())
            .unwrap()
            .flatten()
            .map(|e| e.file_name().to_string_lossy().into_owned())
            .collect();
        assert_eq!(
            takes.len(),
            RETAINED_TAKES,
            "{newest} takes leave the cap's number, got {takes:?}"
        );
        assert!(
            !takes.contains(&"take-0000000000001".to_owned()),
            "the oldest take is pruned, got {takes:?}"
        );
        assert!(
            takes.contains(&format!("take-{newest:013}")),
            "the newest take survives, got {takes:?}"
        );
    }

    /// Diagnostics must never break a take: a directory that cannot be
    /// created is logged and dropped, not propagated.
    #[test]
    fn a_diagnostics_failure_is_swallowed() {
        let dir = tempfile::tempdir().unwrap();
        let blocker = dir.path().join("blocker");
        std::fs::write(&blocker, "a regular file, so subdirectories cannot exist").unwrap();
        let audio = vec![0.5; 16];
        let stages = Stages::default();
        let windows = vec![];
        let models = stub_models(None, None);
        capture_take(
            &blocker.join("under"),
            1,
            &take_record(&models, &audio, &windows, "", "", &stages),
            &CancelToken::new(),
        );
        assert!(!blocker.is_dir(), "the unwritable location must not have been turned into one");
    }
}