Skip to content

A personal assistant that lives on your desktop, remembers what matters, and can use your Mac for you.

TypeScript
35.5 KB
Raw Blame
//! The optional local voice model (S30.5): NVIDIA Parakeet TDT 0.6B v3, int8, as sherpa-onnx
//! publishes it. Nothing downloads unless the user asks. A download streams the official release
//! asset into a staging directory next to the install, hashing it on the way; the SHA-256 and the
//! size are pinned here. Only a verified archive is unpacked, and only the four model files at
//! `<archive root>/<file>` are taken from it (any other path, `..` included, is ignored). The
//! unpacked files then move into place with one rename, so a model directory is either complete
//! or absent; failures and cancels remove the staging directory.
//!
//! Progress and outcomes go out as `voice://model` events, throttled to a few a second.

use crate::computer::Clock;
use serde::Serialize;
use sha2::{Digest, Sha256};
use std::fmt;
use std::fs::{self, File};
use std::io::{self, BufReader, Read, Write};
use std::path::{Component, Path, PathBuf};
use std::sync::atomic::{AtomicBool, Ordering};
use std::sync::{Arc, Mutex, MutexGuard};
use std::time::Duration;

/// `{state, received?, total?, message?}`, to the panel.
pub const MODEL_EVENT: &str = "voice://model";
/// At most one progress event per this many milliseconds (plus the last one).
pub const PROGRESS_INTERVAL_MS: u64 = 250;
const CHUNK: usize = 64 * 1024;
const CANCELLED: &str = "The download was cancelled.";

/// What to download and what it must contain.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ModelSpec {
    pub url: String,
    /// Lowercase hex SHA-256 of the archive.
    pub sha256: String,
    /// The archive's size in bytes.
    pub size: u64,
    /// The archive's top-level directory.
    pub archive_root: String,
    /// The install directory under the models directory.
    pub dir: String,
    /// The files the recognizer needs, all of them required.
    pub files: Vec<String>,
}

impl ModelSpec {
    /// The official sherpa-onnx release asset (tag `asr-models`), published 2025-08-16. The
    /// SHA-256 was computed from the downloaded asset on 2026-10-09 and matches the digest
    /// GitHub lists for it.
    pub fn parakeet() -> Self {
        ModelSpec {
            url: "https://github.com/k2-fsa/sherpa-onnx/releases/download/asr-models/sherpa-onnx-nemo-parakeet-tdt-0.6b-v3-int8.tar.bz2".into(),
            sha256: "5793d0fd397c5778d2cf2126994d58e9d56b1be7c04d13c7a15bb1b4eafb16bf".into(),
            size: 487_170_055,
            archive_root: "sherpa-onnx-nemo-parakeet-tdt-0.6b-v3-int8".into(),
            dir: "parakeet-tdt-0.6b-v3-int8".into(),
            files: ["encoder.int8.onnx", "decoder.int8.onnx", "joiner.int8.onnx", "tokens.txt"].map(String::from).to_vec(),
        }
    }
}

#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]
#[serde(rename_all = "lowercase")]
pub enum ModelState {
    Downloading,
    /// Checking the checksum and unpacking the model files.
    Verifying,
    Installed,
    /// Failed or cancelled; `message` says which.
    Failed,
    Removed,
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
pub struct ModelEvent {
    pub state: ModelState,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub received: Option<u64>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub total: Option<u64>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub message: Option<String>,
}

impl ModelEvent {
    pub fn state(state: ModelState) -> Self {
        ModelEvent { state, received: None, total: None, message: None }
    }

    pub fn failed(message: impl Into<String>) -> Self {
        ModelEvent { message: Some(message.into()), ..ModelEvent::state(ModelState::Failed) }
    }

    fn progress(received: u64, total: u64) -> Self {
        ModelEvent { received: Some(received), total: Some(total), ..ModelEvent::state(ModelState::Downloading) }
    }
}

/// The speech-to-text engine `voice_start` uses.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]
#[serde(rename_all = "lowercase")]
pub enum EngineName {
    Parakeet,
    Apple,
    None,
}

/// The `voice_model_status` reply.
#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
pub struct ModelStatus {
    pub installed: bool,
    /// The installed files' total size.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub bytes: Option<u64>,
    pub downloading: bool,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub received: Option<u64>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub total: Option<u64>,
    pub engine: EngineName,
}

#[derive(Debug, Clone, PartialEq, Eq)]
pub enum ModelError {
    Installed,
    Downloading,
    Failed(String),
}

impl fmt::Display for ModelError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            ModelError::Installed => f.write_str("The local voice model is already installed."),
            ModelError::Downloading => f.write_str("The local voice model is downloading. Cancel the download first."),
            ModelError::Failed(message) => f.write_str(message),
        }
    }
}

impl From<ModelError> for String {
    fn from(error: ModelError) -> String {
        error.to_string()
    }
}

/// An open download: the body, and its length when the server says.
pub struct Download {
    pub body: Box<dyn Read + Send>,
    pub length: Option<u64>,
}

/// Opens a URL for reading. HTTPS in the app, an in-memory archive in tests.
pub trait Fetcher: Send + Sync {
    fn open(&self, url: &str) -> Result<Download, String>;
}

/// HTTPS through ureq (rustls with the bundled web PKI roots; `HTTPS_PROXY` is honored). GitHub
/// answers the release URL with a redirect to its asset host, which is followed.
pub struct HttpFetcher;

impl Fetcher for HttpFetcher {
    fn open(&self, url: &str) -> Result<Download, String> {
        let agent = ureq::AgentBuilder::new()
            .timeout_connect(Duration::from_secs(20))
            .timeout_read(Duration::from_secs(60))
            .try_proxy_from_env(true)
            .https_only(true)
            .build();
        let response = agent.get(url).call().map_err(|error| error.to_string())?;
        let length = response.header("Content-Length").and_then(|value| value.parse().ok());
        Ok(Download { body: Box::new(response.into_reader()), length })
    }
}

pub type ModelEvents = Arc<dyn Fn(ModelEvent) + Send + Sync>;

/// Downloads, verifies, installs, and removes one model under a models directory.
pub struct ModelManager {
    shared: Arc<Shared>,
}

struct Shared {
    spec: ModelSpec,
    root: PathBuf,
    fetcher: Arc<dyn Fetcher>,
    clock: Arc<dyn Clock>,
    events: ModelEvents,
    /// The engine used while the model is absent.
    fallback: EngineName,
    job: Mutex<Option<Job>>,
}

/// The download in flight.
struct Job {
    cancel: Arc<AtomicBool>,
    received: u64,
    total: u64,
}

enum Failure {
    Cancelled,
    Error(String),
}

impl From<io::Error> for Failure {
    fn from(error: io::Error) -> Self {
        Failure::Error(format!("The local voice model could not be installed: {error}"))
    }
}

fn lock<T>(mutex: &Mutex<T>) -> MutexGuard<'_, T> {
    mutex.lock().unwrap_or_else(|poisoned| poisoned.into_inner())
}

fn hex(bytes: &[u8]) -> String {
    bytes.iter().map(|byte| format!("{byte:02x}")).collect()
}

/// Removes a directory this manager owns, if present.
fn clear(path: &Path) -> io::Result<()> {
    match fs::remove_dir_all(path) {
        Err(error) if error.kind() != io::ErrorKind::NotFound => Err(error),
        _ => Ok(()),
    }
}

impl ModelManager {
    pub fn new(
        spec: ModelSpec,
        root: PathBuf,
        fetcher: Arc<dyn Fetcher>,
        clock: Arc<dyn Clock>,
        events: ModelEvents,
        fallback: EngineName,
    ) -> Self {
        let shared = Shared { spec, root, fetcher, clock, events, fallback, job: Mutex::new(None) };
        ModelManager { shared: Arc::new(shared) }
    }

    /// The model directory, when every model file is in it.
    pub fn installed(&self) -> Option<PathBuf> {
        self.shared.installed()
    }

    pub fn status(&self) -> ModelStatus {
        let (downloading, received, total) = match &*lock(&self.shared.job) {
            Some(job) => (true, Some(job.received), Some(job.total)),
            None => (false, None, None),
        };
        let dir = self.installed();
        let bytes = dir.as_ref().map(|dir| self.shared.spec.files.iter().filter_map(|f| fs::metadata(dir.join(f)).ok()).map(|m| m.len()).sum());
        let engine = if dir.is_some() { EngineName::Parakeet } else { self.shared.fallback };
        ModelStatus { installed: dir.is_some(), bytes, downloading, received, total, engine }
    }

    /// Starts the download in the background; progress and the outcome arrive as events.
    pub fn download(&self) -> Result<(), ModelError> {
        let mut job = lock(&self.shared.job);
        if job.is_some() {
            return Err(ModelError::Downloading);
        }
        if self.installed().is_some() {
            return Err(ModelError::Installed);
        }
        let cancel = Arc::new(AtomicBool::new(false));
        let shared = self.shared.clone();
        let flag = cancel.clone();
        std::thread::Builder::new()
            .name("voice-model-download".into())
            .spawn(move || shared.run(&flag))
            .map_err(|error| ModelError::Failed(format!("The download could not start: {error}")))?;
        *job = Some(Job { cancel, received: 0, total: self.shared.spec.size });
        Ok(())
    }

    /// Asks the download in flight to stop; whether there was one. The outcome arrives as a
    /// `failed` event once the staging files are gone.
    pub fn cancel(&self) -> bool {
        lock(&self.shared.job).as_ref().map(|job| job.cancel.store(true, Ordering::SeqCst)).is_some()
    }

    /// Deletes the installed model (refused while downloading). Removing nothing is not an error.
    pub fn remove(&self) -> Result<(), ModelError> {
        let shared = &self.shared;
        {
            let job = lock(&shared.job);
            if job.is_some() {
                return Err(ModelError::Downloading);
            }
            let dir = shared.dir();
            if fs::symlink_metadata(&dir).is_err() {
                return Ok(());
            }
            // Out of sight in one step, then deleted.
            let trash = shared.root.join(format!(".{}.removing", shared.spec.dir));
            let removed = clear(&trash).and_then(|()| fs::rename(&dir, &trash)).and_then(|()| clear(&trash));
            removed.map_err(|error| ModelError::Failed(format!("The local voice model could not be removed: {error}")))?;
        }
        (shared.events)(ModelEvent::state(ModelState::Removed));
        Ok(())
    }
}

impl Shared {
    fn dir(&self) -> PathBuf {
        self.root.join(&self.spec.dir)
    }

    fn staging(&self) -> PathBuf {
        self.root.join(format!(".{}.download", self.spec.dir))
    }

    fn installed(&self) -> Option<PathBuf> {
        let dir = self.dir();
        self.spec.files.iter().all(|file| fs::metadata(dir.join(file)).is_ok_and(|m| m.is_file())).then_some(dir)
    }

    /// The download thread: run, clean up, clear the job, then report.
    fn run(&self, cancel: &AtomicBool) {
        let staging = self.staging();
        let outcome = self.install(&staging, cancel);
        if let Err(error) = clear(&staging) {
            eprintln!("gentle-dot: cannot remove {}: {error}", staging.display());
        }
        *lock(&self.job) = None;
        (self.events)(match outcome {
            Ok(()) => ModelEvent::state(ModelState::Installed),
            Err(Failure::Cancelled) => ModelEvent::failed(CANCELLED),
            Err(Failure::Error(message)) => ModelEvent::failed(message),
        });
    }

    fn install(&self, staging: &Path, cancel: &AtomicBool) -> Result<(), Failure> {
        // A staging directory left by a crash is ours to clear.
        clear(staging)?;
        fs::create_dir_all(staging)?;
        let archive = staging.join("archive.tar.bz2");
        let digest = self.fetch(&archive, cancel)?;
        (self.events)(ModelEvent::state(ModelState::Verifying));
        if digest != self.spec.sha256 {
            return Err(Failure::Error("The download did not match the published checksum.".into()));
        }
        let unpacked = staging.join("model");
        self.extract(&archive, &unpacked, cancel)?;
        fs::remove_file(&archive)?;
        let dir = self.dir();
        // An incomplete directory (not `installed`) is replaced.
        clear(&dir)?;
        fs::rename(&unpacked, &dir)?;
        Ok(())
    }

    /// Streams the archive to `path`, reporting progress; the archive's SHA-256.
    fn fetch(&self, path: &Path, cancel: &AtomicBool) -> Result<String, Failure> {
        let total = self.spec.size;
        let Download { mut body, length } = self
            .fetcher
            .open(&self.spec.url)
            .map_err(|error| Failure::Error(format!("The local voice model could not be downloaded: {error}")))?;
        let wrong_size = || Failure::Error("The download was not the expected size.".into());
        if length.is_some_and(|length| length != total) {
            return Err(wrong_size());
        }
        let mut file = File::create(path)?;
        let mut hasher = Sha256::new();
        let mut buffer = vec![0; CHUNK];
        let (mut received, mut reported) = (0u64, 0u64);
        let mut last_ms = self.clock.now_ms();
        (self.events)(ModelEvent::progress(0, total));
        loop {
            if cancel.load(Ordering::SeqCst) {
                return Err(Failure::Cancelled);
            }
            let read = match body.read(&mut buffer) {
                Ok(0) => break,
                Ok(read) => read,
                Err(error) if error.kind() == io::ErrorKind::Interrupted => continue,
                Err(error) => return Err(Failure::Error(format!("The download was interrupted: {error}"))),
            };
            received += read as u64;
            if received > total {
                return Err(wrong_size());
            }
            hasher.update(&buffer[..read]);
            file.write_all(&buffer[..read])?;
            if let Some(job) = lock(&self.job).as_mut() {
                job.received = received;
            }
            let now = self.clock.now_ms();
            if now.saturating_sub(last_ms) >= PROGRESS_INTERVAL_MS {
                last_ms = now;
                reported = received;
                (self.events)(ModelEvent::progress(received, total));
            }
        }
        if cancel.load(Ordering::SeqCst) {
            return Err(Failure::Cancelled);
        }
        if received != total {
            return Err(wrong_size());
        }
        if reported != received {
            (self.events)(ModelEvent::progress(received, total));
        }
        file.sync_all()?;
        Ok(hex(&hasher.finalize()))
    }

    /// The model file an archive path names: exactly `<archive root>/<one of the files>`.
    fn model_file(&self, path: &Path) -> Option<&str> {
        let mut parts = path.components().filter(|part| *part != Component::CurDir);
        match (parts.next(), parts.next(), parts.next()) {
            (Some(Component::Normal(root)), Some(Component::Normal(name)), None) if root == self.spec.archive_root.as_str() => {
                self.spec.files.iter().find(|file| name == file.as_str()).map(String::as_str)
            }
            _ => None,
        }
    }

    /// Unpacks the model files of a verified archive into `into`, which must not exist.
    fn extract(&self, archive: &Path, into: &Path, cancel: &AtomicBool) -> Result<(), Failure> {
        fs::create_dir(into)?;
        let mut archive = tar::Archive::new(bzip2::read::BzDecoder::new(BufReader::new(File::open(archive)?)));
        for entry in archive.entries()? {
            let mut entry = entry?;
            if cancel.load(Ordering::SeqCst) {
                return Err(Failure::Cancelled);
            }
            if !entry.header().entry_type().is_file() {
                continue;
            }
            let path = entry.path()?.into_owned();
            let Some(name) = self.model_file(&path) else { continue };
            let mut out = File::create_new(into.join(name))?;
            let mut buffer = vec![0; CHUNK];
            loop {
                if cancel.load(Ordering::SeqCst) {
                    return Err(Failure::Cancelled);
                }
                let read = entry.read(&mut buffer)?;
                if read == 0 {
                    break;
                }
                out.write_all(&buffer[..read])?;
            }
            out.sync_all()?;
        }
        let missing: Vec<&str> = self.spec.files.iter().filter(|file| !into.join(file).is_file()).map(String::as_str).collect();
        if !missing.is_empty() {
            return Err(Failure::Error(format!("The downloaded model is missing {}.", missing.join(", "))));
        }
        Ok(())
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::voice::fake::FakeClock;
    use bzip2::write::BzEncoder;
    use sha2::{Digest, Sha256};
    use std::io::{Cursor, Read};
    use std::sync::atomic::AtomicU64;
    use std::sync::mpsc;
    use std::sync::{Arc, Condvar, Mutex};
    use std::time::Duration;

    const FILES: [&str; 4] = ["encoder.int8.onnx", "decoder.int8.onnx", "joiner.int8.onnx", "tokens.txt"];

    /// A tar.bz2 shaped like the sherpa-onnx release: `<root>/<file>` plus files to skip.
    fn archive(root: &str, files: &[(&str, &[u8])]) -> Vec<u8> {
        let paths: Vec<(String, &[u8])> = files.iter().map(|(name, data)| (format!("{root}/{name}"), *data)).collect();
        raw_archive(&paths.iter().map(|(path, data)| (path.as_str(), *data)).collect::<Vec<_>>())
    }

    /// Entries written with the exact path bytes, `..` included (the builder refuses those).
    fn raw_archive(entries: &[(&str, &[u8])]) -> Vec<u8> {
        let mut builder = tar::Builder::new(BzEncoder::new(Vec::new(), bzip2::Compression::fast()));
        for (path, data) in entries {
            let mut header = tar::Header::new_old();
            header.as_old_mut().name[..path.len()].copy_from_slice(path.as_bytes());
            header.set_size(data.len() as u64);
            header.set_mode(0o644);
            header.set_entry_type(tar::EntryType::Regular);
            header.set_cksum();
            builder.append(&header, *data).unwrap();
        }
        builder.into_inner().unwrap().finish().unwrap()
    }

    /// Bytes bzip2 cannot shrink, so the archive spans many reads.
    fn noise(len: usize) -> Vec<u8> {
        let mut state = 0x2545_f491u32;
        (0..len)
            .map(|_| {
                state ^= state << 13;
                state ^= state >> 17;
                state ^= state << 5;
                state as u8
            })
            .collect()
    }

    fn full_archive() -> Vec<u8> {
        archive(
            "release-root",
            &[
                ("tokens.txt", b"<blk> 0\n"),
                ("encoder.int8.onnx", &noise(20_000)),
                ("decoder.int8.onnx", &[2u8; 200]),
                ("joiner.int8.onnx", &[3u8; 100]),
                ("test_wavs/en.wav", b"RIFF"),
            ],
        )
    }

    fn sha(bytes: &[u8]) -> String {
        Sha256::digest(bytes).iter().map(|b| format!("{b:02x}")).collect()
    }

    fn spec_for(bytes: &[u8]) -> ModelSpec {
        ModelSpec {
            url: "https://example.invalid/model.tar.bz2".into(),
            sha256: sha(bytes),
            size: bytes.len() as u64,
            archive_root: "release-root".into(),
            dir: "parakeet-test".into(),
            files: FILES.map(String::from).to_vec(),
        }
    }

    /// Holds the body after its first chunk, so a test can look at a download in flight.
    #[derive(Default)]
    struct Pause {
        /// (reached, released)
        state: Mutex<(bool, bool)>,
        changed: Condvar,
    }

    impl Pause {
        fn wait_reached(&self) {
            let mut state = self.state.lock().unwrap();
            while !state.0 {
                state = self.changed.wait_timeout(state, Duration::from_secs(5)).unwrap().0;
            }
        }

        fn release(&self) {
            self.state.lock().unwrap().1 = true;
            self.changed.notify_all();
        }

        fn hold(&self) {
            let mut state = self.state.lock().unwrap();
            state.0 = true;
            self.changed.notify_all();
            while !state.1 {
                state = self.changed.wait(state).unwrap();
            }
        }
    }

    struct Body {
        data: Cursor<Vec<u8>>,
        chunk: usize,
        pause: Option<Arc<Pause>>,
        clock: Arc<FakeClock>,
        served: usize,
    }

    impl Read for Body {
        fn read(&mut self, buf: &mut [u8]) -> std::io::Result<usize> {
            if let (Some(pause), true) = (&self.pause, self.served > 0) {
                pause.hold();
            }
            let n = buf.len().min(self.chunk);
            let read = self.data.read(&mut buf[..n])?;
            self.served += read;
            self.clock.advance(100);
            Ok(read)
        }
    }

    struct FakeFetcher {
        body: Vec<u8>,
        length: Option<u64>,
        chunk: usize,
        pause: Option<Arc<Pause>>,
        clock: Arc<FakeClock>,
        urls: Mutex<Vec<String>>,
    }

    impl Fetcher for FakeFetcher {
        fn open(&self, url: &str) -> Result<Download, String> {
            self.urls.lock().unwrap().push(url.to_string());
            let body = Body {
                data: Cursor::new(self.body.clone()),
                chunk: self.chunk,
                pause: self.pause.clone(),
                clock: self.clock.clone(),
                served: 0,
            };
            Ok(Download { body: Box::new(body), length: self.length })
        }
    }

    struct Rig {
        manager: ModelManager,
        fetcher: Arc<FakeFetcher>,
        events: mpsc::Receiver<ModelEvent>,
        root: PathBuf,
    }

    fn temp_root(name: &str) -> PathBuf {
        let root = std::env::temp_dir().join(format!("gentle-dot-model-{name}-{}", std::process::id()));
        let _ = std::fs::remove_dir_all(&root);
        root
    }

    fn rig(name: &str, body: Vec<u8>, spec: ModelSpec, pause: Option<Arc<Pause>>) -> Rig {
        let clock = Arc::new(FakeClock(AtomicU64::new(0)));
        let length = Some(body.len() as u64);
        let fetcher = Arc::new(FakeFetcher { body, length, chunk: 512, pause, clock: clock.clone(), urls: Mutex::default() });
        let (tx, events) = mpsc::channel();
        let tx = Mutex::new(tx);
        let root = temp_root(name);
        let manager = ModelManager::new(
            spec,
            root.clone(),
            fetcher.clone(),
            clock,
            Arc::new(move |event| {
                let _ = tx.lock().unwrap().send(event);
            }),
            EngineName::Apple,
        );
        Rig { manager, fetcher, events, root }
    }

    impl Rig {
        /// Every event up to and including the next terminal one.
        fn until_done(&self) -> Vec<ModelEvent> {
            let mut seen = Vec::new();
            loop {
                let event = self.events.recv_timeout(Duration::from_secs(10)).expect("a model event");
                let done = matches!(event.state, ModelState::Installed | ModelState::Failed | ModelState::Removed);
                seen.push(event);
                if done {
                    return seen;
                }
            }
        }

        fn leftovers(&self) -> Vec<String> {
            let Ok(entries) = std::fs::read_dir(&self.root) else { return Vec::new() };
            let mut names: Vec<String> = entries.map(|e| e.unwrap().file_name().to_string_lossy().into_owned()).collect();
            names.sort();
            names
        }
    }

    #[test]
    fn the_pinned_parakeet_asset_is_the_official_int8_release() {
        let spec = ModelSpec::parakeet();
        assert_eq!(
            spec.url,
            "https://github.com/k2-fsa/sherpa-onnx/releases/download/asr-models/sherpa-onnx-nemo-parakeet-tdt-0.6b-v3-int8.tar.bz2"
        );
        assert_eq!(spec.sha256, "5793d0fd397c5778d2cf2126994d58e9d56b1be7c04d13c7a15bb1b4eafb16bf");
        assert_eq!(spec.size, 487_170_055);
        assert_eq!(spec.archive_root, "sherpa-onnx-nemo-parakeet-tdt-0.6b-v3-int8");
        assert_eq!(spec.dir, "parakeet-tdt-0.6b-v3-int8");
        assert_eq!(spec.files, FILES.map(String::from).to_vec());
    }

    #[test]
    fn status_before_any_download_reports_the_fallback_engine() {
        let rig = rig("status", full_archive(), spec_for(&full_archive()), None);
        let status = rig.manager.status();
        assert_eq!(
            serde_json::to_value(&status).unwrap(),
            serde_json::json!({"installed": false, "downloading": false, "engine": "apple"})
        );
        assert_eq!(rig.manager.installed(), None);
    }

    #[test]
    fn a_download_reports_progress_verifies_and_installs_only_the_model_files() {
        let body = full_archive();
        let rig = rig("install", body.clone(), spec_for(&body), None);
        rig.manager.download().unwrap();
        let events = rig.until_done();
        assert_eq!(rig.fetcher.urls.lock().unwrap().as_slice(), ["https://example.invalid/model.tar.bz2"]);

        let first = &events[0];
        assert_eq!((first.state, first.received, first.total), (ModelState::Downloading, Some(0), Some(body.len() as u64)));
        let progress: Vec<u64> = events.iter().filter(|e| e.state == ModelState::Downloading).filter_map(|e| e.received).collect();
        assert!(progress.windows(2).all(|w| w[0] < w[1]), "progress grows: {progress:?}");
        assert_eq!(progress.last(), Some(&(body.len() as u64)), "the last progress is the whole body");
        assert!(
            progress.len() < body.len().div_ceil(512),
            "progress is throttled, not one event per chunk ({} events)",
            progress.len()
        );
        assert!(events.iter().any(|e| e.state == ModelState::Verifying));
        assert_eq!(events.last().unwrap().state, ModelState::Installed);

        let dir = rig.root.join("parakeet-test");
        assert_eq!(rig.manager.installed(), Some(dir.clone()));
        let mut names: Vec<String> =
            std::fs::read_dir(&dir).unwrap().map(|e| e.unwrap().file_name().to_string_lossy().into_owned()).collect();
        names.sort();
        assert_eq!(names, ["decoder.int8.onnx", "encoder.int8.onnx", "joiner.int8.onnx", "tokens.txt"]);
        assert_eq!(std::fs::read(dir.join("encoder.int8.onnx")).unwrap(), noise(20_000));
        assert_eq!(rig.leftovers(), ["parakeet-test"], "no staging files remain");

        let status = rig.manager.status();
        assert_eq!(
            serde_json::to_value(&status).unwrap(),
            serde_json::json!({"installed": true, "bytes": 20_000 + 200 + 100 + 8, "downloading": false, "engine": "parakeet"})
        );
        assert_eq!(rig.manager.download(), Err(ModelError::Installed));
        let _ = std::fs::remove_dir_all(&rig.root);
    }

    #[test]
    fn a_checksum_mismatch_fails_and_leaves_nothing_behind() {
        let body = full_archive();
        let mut spec = spec_for(&body);
        spec.sha256 = "0".repeat(64);
        let rig = rig("mismatch", body, spec, None);
        rig.manager.download().unwrap();
        let last = rig.until_done().pop().unwrap();
        assert_eq!(last.state, ModelState::Failed);
        assert!(last.message.unwrap().contains("did not match"), "the reason is the checksum");
        assert_eq!(rig.manager.installed(), None);
        assert!(rig.leftovers().is_empty(), "staging removed: {:?}", rig.leftovers());
        assert!(!rig.manager.status().downloading);
        let _ = std::fs::remove_dir_all(&rig.root);
    }

    #[test]
    fn a_body_of_the_wrong_size_fails() {
        let body = full_archive();
        let mut spec = spec_for(&body);
        spec.size += 1;
        let rig = rig("size", body, spec, None);
        rig.manager.download().unwrap();
        let last = rig.until_done().pop().unwrap();
        assert_eq!(last.state, ModelState::Failed);
        assert!(rig.leftovers().is_empty());
        let _ = std::fs::remove_dir_all(&rig.root);
    }

    #[test]
    fn an_archive_missing_a_model_file_is_not_installed() {
        let body = archive("release-root", &[("tokens.txt", b"x"), ("encoder.int8.onnx", b"e"), ("decoder.int8.onnx", b"d")]);
        let rig = rig("missing", body.clone(), spec_for(&body), None);
        rig.manager.download().unwrap();
        let last = rig.until_done().pop().unwrap();
        assert_eq!(last.state, ModelState::Failed);
        assert!(last.message.unwrap().contains("joiner.int8.onnx"));
        assert_eq!(rig.manager.installed(), None);
        assert!(rig.leftovers().is_empty());
        let _ = std::fs::remove_dir_all(&rig.root);
    }

    #[test]
    fn entries_outside_the_release_root_are_ignored() {
        let body = raw_archive(&[
            ("other-root/tokens.txt", b"t"),
            ("release-root/../tokens.txt", b"t"),
            ("../encoder.int8.onnx", b"e"),
            ("/release-root/encoder.int8.onnx", b"e"),
            ("release-root/nested/decoder.int8.onnx", b"d"),
            ("release-root/joiner.int8.onnx", b"j"),
        ]);
        let rig = rig("outside", body.clone(), spec_for(&body), None);
        rig.manager.download().unwrap();
        let last = rig.until_done().pop().unwrap();
        assert_eq!(last.state, ModelState::Failed);
        let message = last.message.unwrap();
        assert_eq!(
            message, "The downloaded model is missing encoder.int8.onnx, decoder.int8.onnx, tokens.txt.",
            "only release-root/<file> counts"
        );
        assert!(rig.leftovers().is_empty());
        assert!(!rig.root.parent().unwrap().join("encoder.int8.onnx").exists());
        let _ = std::fs::remove_dir_all(&rig.root);
    }

    #[test]
    fn a_download_in_flight_is_reported_not_installed_and_can_be_cancelled() {
        let body = full_archive();
        let pause = Arc::new(Pause::default());
        let rig = rig("cancel", body.clone(), spec_for(&body), Some(pause.clone()));
        rig.manager.download().unwrap();
        pause.wait_reached();

        let status = rig.manager.status();
        assert!(status.downloading && !status.installed);
        assert_eq!((status.received, status.total), (Some(512), Some(body.len() as u64)));
        assert_eq!(rig.manager.download(), Err(ModelError::Downloading));
        assert_eq!(rig.manager.remove(), Err(ModelError::Downloading));
        assert!(!rig.root.join("parakeet-test").exists(), "nothing is installed until the end");

        assert!(rig.manager.cancel());
        pause.release();
        let last = rig.until_done().pop().unwrap();
        assert_eq!(last.state, ModelState::Failed);
        assert_eq!(last.message.as_deref(), Some("The download was cancelled."));
        assert!(rig.leftovers().is_empty(), "staging removed: {:?}", rig.leftovers());
        assert!(!rig.manager.status().downloading);
        assert!(!rig.manager.cancel(), "nothing left to cancel");
        let _ = std::fs::remove_dir_all(&rig.root);
    }

    #[test]
    fn remove_deletes_the_model_and_reports_it() {
        let body = full_archive();
        let rig = rig("remove", body.clone(), spec_for(&body), None);
        rig.manager.download().unwrap();
        assert_eq!(rig.until_done().pop().unwrap().state, ModelState::Installed);

        rig.manager.remove().unwrap();
        assert_eq!(rig.until_done(), vec![ModelEvent::state(ModelState::Removed)]);
        assert_eq!(rig.manager.installed(), None);
        assert!(rig.leftovers().is_empty());
        assert_eq!(rig.manager.status().engine, EngineName::Apple);
        rig.manager.remove().unwrap();
        assert!(rig.events.try_recv().is_err(), "removing nothing reports nothing");
        let _ = std::fs::remove_dir_all(&rig.root);
    }

    #[test]
    fn a_staging_directory_left_by_a_crash_is_cleared_by_the_next_download() {
        let body = full_archive();
        let rig = rig("stale", body.clone(), spec_for(&body), None);
        let stale = rig.root.join(".parakeet-test.download");
        std::fs::create_dir_all(stale.join("model")).unwrap();
        std::fs::write(stale.join("archive.tar.bz2"), b"partial").unwrap();
        rig.manager.download().unwrap();
        assert_eq!(rig.until_done().pop().unwrap().state, ModelState::Installed);
        assert_eq!(rig.leftovers(), ["parakeet-test"]);
        let _ = std::fs::remove_dir_all(&rig.root);
    }

    #[test]
    fn an_incomplete_install_does_not_count() {
        let rig = rig("partial", Vec::new(), spec_for(&[]), None);
        let dir = rig.root.join("parakeet-test");
        std::fs::create_dir_all(&dir).unwrap();
        std::fs::write(dir.join("tokens.txt"), b"t").unwrap();
        assert_eq!(rig.manager.installed(), None);
        let _ = std::fs::remove_dir_all(&rig.root);
    }

    /// Reads a local copy of the release asset.
    struct FileFetcher(PathBuf);

    impl Fetcher for FileFetcher {
        fn open(&self, _url: &str) -> Result<Download, String> {
            let file = std::fs::File::open(&self.0).map_err(|e| e.to_string())?;
            let length = file.metadata().map_err(|e| e.to_string())?.len();
            Ok(Download { body: Box::new(file), length: Some(length) })
        }
    }

    /// Installs from a downloaded copy of the real asset, checking the pinned SHA-256 and the
    /// release's layout. Run with
    /// `GENTLE_DOT_PARAKEET_ARCHIVE=<the .tar.bz2> cargo test -- --ignored real_parakeet_archive`.
    #[test]
    #[ignore = "needs the real Parakeet archive (487 MB)"]
    fn real_parakeet_archive_installs() {
        let Some(archive) = std::env::var_os("GENTLE_DOT_PARAKEET_ARCHIVE").map(PathBuf::from) else {
            eprintln!("GENTLE_DOT_PARAKEET_ARCHIVE is not set; skipping");
            return;
        };
        let (tx, events) = mpsc::channel();
        let tx = Mutex::new(tx);
        let root = temp_root("real");
        let manager = ModelManager::new(
            ModelSpec::parakeet(),
            root.clone(),
            Arc::new(FileFetcher(archive)),
            Arc::new(crate::computer::SystemClock),
            Arc::new(move |event| {
                let _ = tx.lock().unwrap().send(event);
            }),
            EngineName::Apple,
        );
        let started = std::time::Instant::now();
        manager.download().unwrap();
        let last = loop {
            let event: ModelEvent = events.recv_timeout(Duration::from_secs(600)).unwrap();
            if matches!(event.state, ModelState::Installed | ModelState::Failed) {
                break event;
            }
        };
        eprintln!("installed in {:?}: {:?}", started.elapsed(), manager.status());
        assert_eq!(last.state, ModelState::Installed, "{:?}", last.message);
        assert_eq!(manager.status().bytes, Some(670_478_772));
        let _ = std::fs::remove_dir_all(&root);
    }

    #[test]
    fn events_carry_the_contract_shape() {
        assert_eq!(MODEL_EVENT, "voice://model");
        let progress = ModelEvent { state: ModelState::Downloading, received: Some(5), total: Some(10), message: None };
        assert_eq!(
            serde_json::to_value(progress).unwrap(),
            serde_json::json!({"state": "downloading", "received": 5, "total": 10})
        );
        let failed = ModelEvent::failed("no");
        assert_eq!(serde_json::to_value(failed).unwrap(), serde_json::json!({"state": "failed", "message": "no"}));
        for (state, name) in [
            (ModelState::Verifying, "verifying"),
            (ModelState::Installed, "installed"),
            (ModelState::Removed, "removed"),
        ] {
            assert_eq!(serde_json::to_value(ModelEvent::state(state)).unwrap(), serde_json::json!({"state": name}));
        }
        for (engine, name) in [(EngineName::Parakeet, "parakeet"), (EngineName::Apple, "apple"), (EngineName::None, "none")] {
            assert_eq!(serde_json::to_value(engine).unwrap(), serde_json::json!(name));
        }
    }
}