cera 0.1.0

//! Bundle fetching + caching.
//!
//! `BundleRepo` resolves a remote URL to a file in a caller-chosen
//! cache directory. This is Phase 1.6 PR A scope: it does *not* resolve
//! bundle IDs like `"LiquidAI/LFM2-1.2B-GGUF"` to a manifest URL (PR B);
//! it takes a direct URL (typically pulled from a manifest's `files`
//! entries) and returns a local path.
//!
//! ## Caching
//!
//! Files are stored under `<store_dir>/<host>/<url-path>`, mirroring the
//! URL structure so contents are trivially inspectable and swappable
//! with a CDN mirror that preserves paths.
//!
//! ## `store_dir`, not `cache_dir`
//!
//! The directory the caller supplies is named `store_dir` on purpose.
//! On Android the consumer is expected to pass `Context.getFilesDir()`
//! (persistent storage), **not** `Context.getCacheDir()` — the latter
//! is OS-purgeable under storage pressure and would cause silent,
//! expensive re-downloads. Desktop and server callers typically pass
//! something like `~/.cache/cera/` but the crate never hardcodes a
//! default location; it's always caller-supplied.
//!
//! ## Integrity
//!
//! Each download is SHA-256'd on the fly and compared against either a
//! caller-supplied hash (via the `expected_sha256` argument to
//! [`BundleRepo::resolve_url`]) or the server's `X-Linked-Etag`
//! header (HuggingFace sets this for LFS objects — content-addressed,
//! stable across revisions). The successful hash is persisted as
//! `<dest>.sha256` alongside the cached file; subsequent cache hits
//! read the sidecar and compare it against the etag in O(1) rather
//! than re-hashing multi-GB files on every resolve. A missing or
//! stale sidecar triggers a full rehash (which also repairs the
//! sidecar on success).
//!
//! A cached file is considered valid when:
//! 1. A caller-supplied hash matches the sidecar (or full rehash
//!    fallback), or
//! 2. HEAD provides `X-Linked-Etag` and it matches the sidecar (or
//!    full rehash fallback), or
//! 3. HEAD provides only `Content-Length` and the sizes match, or
//! 4. HEAD fails entirely — reuse whatever's cached so a transient
//!    upstream blip doesn't defeat a CI cache hit.
//!
//! See [`download::head_info`] for the HEAD probe.

pub(crate) mod download;

use std::collections::{BTreeMap, BTreeSet};
use std::fs;
use std::path::{Path, PathBuf};
use std::sync::Arc;

use reqwest::blocking::Client;

use crate::session::CeraError;

/// Callback receiver for download progress events. Implementations
/// must be `Send + Sync` because downloads run on whatever thread
/// the caller drove them from (often a `spawn_blocking` worker).
///
/// Throttling: `download::download_to` calls `on_progress` at most
/// once per ~256 KB written + once at end-of-stream. Implementers
/// don't need to dedupe or rate-limit on their side.
pub trait DownloadProgress: Send + Sync + std::fmt::Debug {
    /// Called periodically during a download. `bytes_downloaded` is
    /// monotonic across the same call's stream; `total_bytes` is the
    /// `Content-Length` reported by the server (may be `None` for
    /// chunked-transfer responses or when HEAD didn't surface a
    /// length). Same `url` value across all calls for one download.
    fn on_progress(&self, url: &str, bytes_downloaded: u64, total_bytes: Option<u64>);
}

/// Repository for remote bundle files cached to a caller-chosen
/// directory. Construction is cheap — create one per `CeraEngine` at
/// most, or pass the same instance to multiple engines.
///
/// Holds two pooled `reqwest::blocking::Client`s:
/// - `http_client`: default redirect policy. Used for the `GET`
///   streaming-download path so HF's 302 to the CDN is followed
///   automatically.
/// - `head_client`: redirects **disabled**. Used for `HEAD` probes so
///   the code reads headers from HF's origin-hop 302 (which carries
///   `X-Linked-Etag`, the content SHA-256). A redirect-following
///   client would surface the CDN's unrelated `ETag` instead.
#[derive(Clone, Debug)]
pub struct BundleRepo {
    store_dir: PathBuf,
    http_client: Client,
    head_client: Client,
    /// Optional progress callback fired during cache-miss downloads.
    /// `None` for `BundleRepo::new`; populated by `with_progress`.
    /// Cache-hit resolves don't fire any callbacks since there's no
    /// streaming work to report on.
    progress: Option<Arc<dyn DownloadProgress>>,
}

impl BundleRepo {
    /// Create a new repo rooted at `store_dir`. The directory does not
    /// need to exist yet — it will be created on the first download.
    ///
    /// Constructs two clients (see [`BundleRepo`] docs for the
    /// redirect-policy split). Both use reqwest's defaults otherwise;
    /// per-request timeouts override at the call site (30s for HEAD,
    /// 10min for GET). `Client::builder().build()` panics only on
    /// severe OS resource failure (can't create a Tokio runtime) —
    /// documented failure mode, acceptable for a process-startup path.
    pub fn new(store_dir: impl Into<PathBuf>) -> Self {
        let head_client = Client::builder()
            .redirect(reqwest::redirect::Policy::none())
            .build()
            .expect("build no-redirect reqwest client");
        Self {
            store_dir: store_dir.into(),
            http_client: Client::new(),
            head_client,
            progress: None,
        }
    }

    /// Variant of [`BundleRepo::new`] that attaches a progress
    /// callback. The callback fires during cache-miss downloads only
    /// (cache hits return without streaming I/O). Same callback gets
    /// called for every URL the repo downloads — implementers can
    /// branch on the `url` argument to drive a per-file UI.
    pub fn with_progress(
        store_dir: impl Into<PathBuf>,
        progress: Arc<dyn DownloadProgress>,
    ) -> Self {
        let mut repo = Self::new(store_dir);
        repo.progress = Some(progress);
        repo
    }

    /// Root directory backing this repo.
    pub fn store_dir(&self) -> &Path {
        &self.store_dir
    }

    /// Total bytes currently held in the cache. Recursively sums file
    /// sizes under `store_dir`; returns `Ok(0)` if the dir doesn't
    /// exist yet (no downloads have run). Skips files that fail to
    /// `metadata()` (deleted mid-walk, permission glitches) — partial
    /// totals beat hard-erroring on a transient I/O blip.
    ///
    /// O(n) over the cache contents; for a large cache (multiple GB
    /// across many shards) this is a real walk, not a constant-time
    /// query — the OS doesn't track per-directory totals. Callers
    /// surfacing the value in a UI should run it off the main thread.
    pub fn cache_size(&self) -> Result<u64, CeraError> {
        // No `exists()` pre-check — `walk_dir_size` already maps a
        // missing root to `Ok(())` via `read_dir`'s `NotFound` arm,
        // which leaves `total` at zero. Skipping the extra syscall
        // also closes the same TOCTOU we close in `clear_cache`.
        let mut total = 0u64;
        Self::walk_dir_size(&self.store_dir, &mut total)?;
        Ok(total)
    }

    fn walk_dir_size(dir: &Path, total: &mut u64) -> Result<(), CeraError> {
        let entries = match fs::read_dir(dir) {
            Ok(e) => e,
            // Directory disappeared mid-walk (concurrent clear, etc.) —
            // treat as empty rather than propagate.
            Err(e) if e.kind() == std::io::ErrorKind::NotFound => return Ok(()),
            Err(e) => return Err(e.into()),
        };
        for entry in entries.flatten() {
            // `entry.file_type()` is a syscall on POSIX, so use it
            // instead of `metadata()` for the directory test — cheaper
            // when we don't need the size yet.
            let Ok(file_type) = entry.file_type() else {
                continue;
            };
            if file_type.is_dir() {
                Self::walk_dir_size(&entry.path(), total)?;
            } else if file_type.is_file()
                && let Ok(meta) = entry.metadata()
            {
                *total = total.saturating_add(meta.len());
            }
        }
        Ok(())
    }

    /// Wipe every file the repo has cached, leaving `store_dir` itself
    /// in place (so subsequent downloads land in the same path).
    /// Idempotent — calling on an empty repo or non-existent
    /// `store_dir` is a no-op success.
    ///
    /// Mobile apps trigger this from a "clear downloaded models" UI
    /// action. Removes the tree under `store_dir` (sidecar `.sha256`
    /// files included) and recreates `store_dir` empty. In-flight
    /// downloads to the same repo will see the partial files vanish
    /// and may fail; callers should serialize the clear against
    /// any active `from_bundle_id*` calls themselves (typically
    /// trivial since the action is user-driven).
    pub fn clear_cache(&self) -> Result<(), CeraError> {
        // `remove_dir_all` + `create_dir_all` is simpler than walking
        // and `unlink`-ing each file. The dir-recreate keeps the
        // store_dir invariant (parent for future downloads).
        //
        // `NotFound` from `remove_dir_all` is treated as success: the
        // dir is already absent (lazy-creation invariant — no download
        // has run, or a concurrent clear got there first). In that
        // case we also skip `create_dir_all` to preserve the lazy
        // contract: nothing eagerly materializes `store_dir`. No
        // `exists()` pre-check — it would be a TOCTOU race against
        // the remove.
        match fs::remove_dir_all(&self.store_dir) {
            Ok(()) => {}
            Err(e) if e.kind() == std::io::ErrorKind::NotFound => return Ok(()),
            Err(e) => return Err(e.into()),
        }
        fs::create_dir_all(&self.store_dir)?;
        Ok(())
    }

    /// Resolve a remote URL to a local path, downloading if not cached.
    ///
    /// `expected_sha256`: if provided, the cached entry's hash (or the
    /// freshly-downloaded bytes' hash) must match this exactly. If
    /// `None`, integrity verification falls back to the server's
    /// `X-Linked-Etag` (when present) or a size check (when only
    /// `Content-Length` is available).
    ///
    /// ### Verification policy
    ///
    /// On cache hit:
    /// - If a sidecar `<dest>.sha256` exists, compare it against the
    ///   expected hash in O(1). This is the fast path for multi-GB
    ///   cached GGUFs.
    /// - Else fall back to `sha256_file` (full rehash) and repair the
    ///   sidecar on success.
    /// - If no hash is available anywhere, fall back to a
    ///   `Content-Length` size check.
    /// - If HEAD also fails, reuse the cached file (transient outage
    ///   shouldn't defeat a CI cache hit).
    ///
    /// On cache miss: download, hashing on the fly, verifying against
    /// `expected_sha256` or `X-Linked-Etag`. A mismatch deletes the
    /// partial and returns `CeraError::Backend`. The sidecar is
    /// persisted on success.
    pub fn resolve_url(
        &self,
        url: &str,
        expected_sha256: Option<&str>,
    ) -> Result<PathBuf, CeraError> {
        let dest = self.path_for_url(url)?;

        // Probe HEAD once up front (no-redirect client so HF's
        // `X-Linked-Etag` is captured from the first hop). Used both
        // to validate a cached file and — on cache miss — to hand the
        // server's advertised content hash to `download_to`, so the
        // first download is integrity-verified even when the caller
        // didn't pin a hash. Re-used across cache-hit and cache-miss
        // code paths so we issue at most one HEAD per resolve.
        let head = if expected_sha256.is_some() {
            // Caller pinned a hash — no need to consult the server.
            download::HeadInfo {
                content_length: None,
                linked_sha256: None,
            }
        } else {
            download::head_info(&self.head_client, url)
        };

        if dest.exists() && self.cache_hit_valid(&dest, url, expected_sha256, &head) {
            return Ok(dest);
        }

        // Cache miss: only now does the filesystem need to exist.
        // Deferred so cache-hit callers don't pay a `stat` on the
        // parent directory on every resolve.
        if let Some(parent) = dest.parent() {
            fs::create_dir_all(parent)?;
        }

        // Prefer caller's hash; else use the server's linked-etag
        // captured pre-redirect.
        let download_hash = expected_sha256
            .map(|s| s.to_ascii_lowercase())
            .or_else(|| head.linked_sha256.clone());

        tracing::info!(
            target: "cera::bundle",
            url,
            dest = %dest.display(),
            hash_source = match (expected_sha256.is_some(), head.linked_sha256.is_some()) {
                (true, _) => "caller",
                (false, true) => "x-linked-etag",
                (false, false) => "unverified",
            },
            "downloading bundle file"
        );
        download::download_to(
            &self.http_client,
            url,
            &dest,
            download_hash.as_deref(),
            // HEAD probe captures `x-linked-size` from HF's no-redirect
            // response. The GET path's CDN response usually echoes
            // `Content-Length` too, but defensively prefer the HEAD-
            // probed value so the progress callback gets a reliable
            // total even when the CDN omits the header.
            head.content_length,
            self.progress.as_deref(),
        )?;
        Ok(dest)
    }

    /// Decide whether an existing cached entry at `dest` is still
    /// valid. Verification prefers caller-supplied hash, then etag via
    /// sidecar, then etag via full rehash, then size, then reuse-on-
    /// HEAD-failure. Any mismatch returns `false` → caller re-downloads.
    fn cache_hit_valid(
        &self,
        dest: &Path,
        url: &str,
        expected_sha256: Option<&str>,
        head: &download::HeadInfo,
    ) -> bool {
        // Caller hash takes precedence over whatever the server
        // advertised — lets manifest-level hashes override an etag
        // that's been rotated.
        let expected_hash = expected_sha256
            .map(|s| s.to_ascii_lowercase())
            .or_else(|| head.linked_sha256.clone());

        if let Some(exp_hash) = expected_hash {
            return hash_matches(dest, url, &exp_hash);
        }

        if let Some(exp_len) = head.content_length {
            let actual = fs::metadata(dest).map(|m| m.len()).unwrap_or(0);
            if actual == exp_len {
                return true;
            }
            tracing::info!(
                target: "cera::bundle",
                url,
                expected = exp_len,
                actual,
                "cached file size mismatch; re-downloading"
            );
            return false;
        }

        // HEAD failed entirely — best-effort reuse so a transient
        // outage doesn't defeat a CI cache hit.
        true
    }

    /// Compute the on-disk cache location for `url`, rooted at
    /// `store_dir`. Mirrors `<host>/<path>` so the cache is inspectable
    /// and safely swappable with a host-preserving mirror.
    ///
    /// Rejects URLs whose host or path contain segments that could
    /// escape `store_dir` (e.g. `..`, null bytes, a bare `/` path
    /// component). This is a pre-`PathBuf::push` filter — `PathBuf`
    /// itself is not a validator; an attacker-controlled URL must not
    /// be able to write outside the cache root.
    ///
    /// The **host** is lowercased before it becomes a cache-dir name so
    /// URLs that differ only in host casing (per RFC 3986 §3.2.2,
    /// hosts are case-insensitive) share a cache entry on
    /// case-sensitive filesystems. Path segments stay as-is — they're
    /// content-addressable and different casings can legitimately
    /// resolve to different resources on the origin.
    fn path_for_url(&self, url: &str) -> Result<PathBuf, CeraError> {
        let (host, path) = split_url(url)?;
        let host_lower = host.to_ascii_lowercase();
        validate_path_segment("url host", &host_lower)?;

        // Strip the leading `/` and any trailing query/fragment before
        // segmenting. `?` / `#` are URL syntax that don't belong in the
        // on-disk path. If the request actually depends on them we'd
        // need a caller to pass them through separately; today every
        // bundle URL is a clean path.
        let path_no_qs = path
            .trim_start_matches('/')
            .split(['?', '#'])
            .next()
            .unwrap_or("");
        if path_no_qs.is_empty() {
            return Err(CeraError::Backend(format!(
                "url `{url}` has no path component"
            )));
        }

        let mut out = self.store_dir.clone();
        out.push(&host_lower);
        for segment in path_no_qs.split('/') {
            validate_path_segment("url path segment", segment)?;
            out.push(segment);
        }
        Ok(out)
    }
}

/// Check whether `dest` hashes to `expected_hash` (case-insensitive
/// hex), preferring the sidecar fast path. Logs a tracing event when
/// a full rehash is performed or a mismatch is detected.
fn hash_matches(dest: &Path, url: &str, expected_hash: &str) -> bool {
    let expected = expected_hash.to_ascii_lowercase();

    // Fast path: trust the sidecar. We wrote it ourselves after the
    // last successful verification, so it's at least as trustworthy
    // as the cached file itself. `read_sidecar` returns lowercase.
    if let Some(cached) = download::read_sidecar(dest) {
        if cached == expected {
            return true;
        }
        tracing::info!(
            target: "cera::bundle",
            url,
            expected = %expected,
            actual = %cached,
            "cached file sidecar hash mismatch; re-downloading"
        );
        return false;
    }

    // Slow path: full rehash. Only hits when the sidecar is absent
    // (e.g. cached before the sidecar feature shipped) or unreadable.
    // `sha256_file` returns lowercase hex. On a match, persist the
    // sidecar so the next cache hit skips straight to the fast path.
    match download::sha256_file(dest) {
        Ok(actual) if actual == expected => {
            download::write_sidecar(dest, &actual);
            true
        }
        Ok(actual) => {
            tracing::info!(
                target: "cera::bundle",
                url,
                expected = %expected,
                actual = %actual,
                "cached file hash mismatch; re-downloading"
            );
            false
        }
        Err(e) => {
            tracing::warn!(
                target: "cera::bundle",
                url,
                error = %e,
                "failed to hash cached file; re-downloading"
            );
            false
        }
    }
}

/// HuggingFace model-info endpoint for the LeapBundles repo. The
/// response carries a `siblings` array listing every file in the
/// repo (one round-trip), which `list_leap_bundles` walks to build
/// the bundle/quant catalog.
const LEAP_BUNDLES_API_URL: &str = "https://huggingface.co/api/models/LiquidAI/LeapBundles";

/// HTTP timeout for `list_leap_bundles`. The HF model-info endpoint
/// returns a few KB of JSON — anything past 30 s is a stalled
/// connection (captive portal, network glitch) rather than a slow
/// response. Matches `HEAD_TIMEOUT` in `download.rs`.
const LIST_BUNDLES_TIMEOUT: std::time::Duration = std::time::Duration::from_secs(30);

/// One bundle entry in the LeapBundles catalog: a directory at
/// `LiquidAI/LeapBundles/<name>/` plus the per-quant manifests
/// (`<quant>.json`) Liquid publishes inside it.
///
/// Returned by [`list_leap_bundles`]; both `name` and `quants` are
/// sorted ascending so output is stable across runs even if the
/// HF API reorders its `siblings` array.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct LeapBundleEntry {
    pub name: String,
    pub quants: Vec<String>,
}

/// List bundles published on `LiquidAI/LeapBundles`.
///
/// Single GET to the HuggingFace model-info endpoint; groups the
/// returned `siblings` array by directory to surface
/// `<bundle>/<quant>` pairs. Top-level files (`README.md`,
/// `.gitattributes`, the `*.bundle` blobs Liquid publishes for
/// their own packaging tool) are ignored — only entries shaped
/// as `<bundle>/<quant>.json` count, which is the schema the
/// rest of `cera` consumes via [`leap_bundles_manifest_url`].
///
/// Network: blocking GET with a 30 s timeout (see
/// [`LIST_BUNDLES_TIMEOUT`]) so a captive portal or stalled
/// connection surfaces as an error instead of hanging the CLI.
/// No retry. Caller errors surface as [`CeraError::Backend`] with
/// the underlying reqwest message.
pub fn list_leap_bundles() -> Result<Vec<LeapBundleEntry>, CeraError> {
    // Build a one-shot client per call. `list_leap_bundles` runs at
    // most once per CLI invocation, so the cost is well below the
    // network round-trip; sharing a `Client` with `BundleRepo`
    // would force callers (FFI consumers, tests) to thread it
    // through, and the API stays simpler this way.
    let client = Client::builder()
        .timeout(LIST_BUNDLES_TIMEOUT)
        .build()
        .map_err(|e| CeraError::Backend(format!("list-bundles client build failed: {e}")))?;
    let body = client
        .get(LEAP_BUNDLES_API_URL)
        .send()
        .and_then(|r| r.error_for_status())
        .and_then(|r| r.text())
        .map_err(|e| CeraError::Backend(format!("list-bundles HTTP failed: {e}")))?;
    parse_leap_bundles(&body)
}

/// Parse a HuggingFace model-info JSON body into the bundle catalog.
/// Split out from [`list_leap_bundles`] so the grouping/filtering
/// logic is unit-testable without a live HTTP round-trip.
fn parse_leap_bundles(body: &str) -> Result<Vec<LeapBundleEntry>, CeraError> {
    #[derive(serde::Deserialize)]
    struct Sibling {
        rfilename: String,
    }
    #[derive(serde::Deserialize)]
    struct Resp {
        siblings: Vec<Sibling>,
    }
    let resp: Resp = serde_json::from_str(body)
        .map_err(|e| CeraError::Backend(format!("list-bundles JSON parse failed: {e}")))?;

    // BTreeMap/BTreeSet sort by key; the iter() walk that follows
    // produces a stable lexicographic ordering of bundles + quants.
    let mut by_bundle: BTreeMap<String, BTreeSet<String>> = BTreeMap::new();
    for sib in resp.siblings {
        // Only `<bundle>/<quant>.json` shapes count. Everything
        // else (top-level `*.bundle` blobs, `.gitattributes`,
        // `README.md`, nested-deeper paths) is silently dropped —
        // those aren't consumable by `from_bundle_id` and
        // surfacing them would confuse users.
        let Some((dir, file)) = sib.rfilename.split_once('/') else {
            continue;
        };
        let Some(quant) = file.strip_suffix(".json") else {
            continue;
        };
        if quant.contains('/') {
            // Nested deeper than `<bundle>/<quant>.json` — not
            // part of LeapBundles' schema today; skip rather than
            // mis-display.
            continue;
        }
        // Both segments must survive the same allowlist that
        // `leap_bundles_manifest_url` enforces — otherwise we'd
        // surface entries that `from_bundle_id` would reject at
        // resolve time. Today every entry passes this check, but
        // a future HF entry with non-ASCII or whitespace would
        // get filtered cleanly here instead of producing a
        // confusing post-list `--bundle-id` failure.
        if validate_path_segment("bundle_id", dir).is_err()
            || validate_path_segment("quant", quant).is_err()
        {
            continue;
        }
        by_bundle
            .entry(dir.to_string())
            .or_default()
            .insert(quant.to_string());
    }
    Ok(by_bundle
        .into_iter()
        .map(|(name, quants)| LeapBundleEntry {
            name,
            quants: quants.into_iter().collect(),
        })
        .collect())
}

/// Build the canonical manifest URL for a LeapBundles entry.
///
/// The LeapBundles repo on HuggingFace is a flat catalog at
/// `LiquidAI/LeapBundles`; each bundle occupies a top-level directory
/// named after the model (e.g. `LFM2-1.2B-GGUF/`), and per-quant
/// manifests live inside as `<QUANT>.json` (e.g. `Q4_0.json`,
/// `F16.json`). There is no top-level index — bundle IDs are passed in
/// as opaque strings.
///
/// `bundle_id` / `quant` are interpolated directly into a URL path and
/// must be safe filesystem components, so they go through the same
/// strict [`validate_path_segment`] allowlist used for cache-dir
/// segments. URL-reserved characters (`?`, `#`, `%`) are rejected so
/// they can't alter URL semantics when interpolated.
pub fn leap_bundles_manifest_url(bundle_id: &str, quant: &str) -> Result<String, CeraError> {
    validate_path_segment("bundle_id", bundle_id)?;
    validate_path_segment("quant", quant)?;
    Ok(format!(
        "https://huggingface.co/LiquidAI/LeapBundles/resolve/main/{bundle_id}/{quant}.json"
    ))
}

/// Strict allowlist for path segments: ASCII alphanumerics and
/// `-`, `_`, `.`. Everything else is rejected:
/// - `/`, `\` (path separators on any OS)
/// - `:` (Windows drive letters / NTFS alternate data streams)
/// - `*`, `"`, `<`, `>`, `|` (Windows-reserved)
/// - whitespace, null bytes, control chars (confusing / truncating)
/// - URL-reserved `?`, `#`, `%` (semantics-altering under URL parsing)
/// - non-ASCII (keeps paths portable across codepages; real bundle IDs
///   and URL segments in `LiquidAI/LeapBundles` are all ASCII today)
///
/// Used for both URL-derived cache-dir segments (in `path_for_url`,
/// where lax input could escape `store_dir` via `..`) and LeapBundles
/// bundle-id / quant components (in `leap_bundles_manifest_url`, where
/// lax input could 404 or manipulate the cache path). One allowlist
/// covers both because the same filename-safe subset works for every
/// real bundle identifier shipped in `LiquidAI/LeapBundles` today.
fn validate_path_segment(kind: &str, segment: &str) -> Result<(), CeraError> {
    if segment.is_empty() {
        return Err(CeraError::Backend(format!("{kind} must not be empty")));
    }
    if segment == "." || segment == ".." {
        return Err(CeraError::Backend(format!(
            "{kind} `{segment}` is not a valid path component"
        )));
    }
    for ch in segment.chars() {
        let ok = ch.is_ascii_alphanumeric() || matches!(ch, '-' | '_' | '.');
        if !ok {
            return Err(CeraError::Backend(format!(
                "{kind} `{segment}` contains forbidden character {ch:?}"
            )));
        }
    }
    Ok(())
}

/// Minimal URL parser: extract `(host, path)` from `https://host/path`.
/// Scheme comparison is case-insensitive (RFC 3986 §3.1) to match the
/// case-insensitive check in `engine::is_remote_url` — otherwise a
/// `HTTPS://…` URL would be accepted by the remote-URL gate but
/// rejected here. We avoid pulling in a full `url` crate dep — this
/// is the only URL handling `cera` needs and the shape we accept is
/// narrow.
fn split_url(url: &str) -> Result<(&str, &str), CeraError> {
    // Case-insensitive scheme match: find the `://` and check the
    // preceding label against our supported schemes.
    let scheme_end = url.find("://").ok_or_else(|| {
        CeraError::Backend(format!("url `{url}` must start with https:// or http://"))
    })?;
    let scheme = &url[..scheme_end];
    let lower = scheme.to_ascii_lowercase();
    if lower != "http" && lower != "https" {
        return Err(CeraError::Backend(format!(
            "url `{url}` must start with https:// or http://"
        )));
    }
    let after_scheme = &url[scheme_end + 3..]; // skip "://"
    let (host, path) = after_scheme
        .split_once('/')
        .ok_or_else(|| CeraError::Backend(format!("url `{url}` has no path component")))?;
    if host.is_empty() {
        return Err(CeraError::Backend(format!(
            "url `{url}` has empty host component"
        )));
    }
    // Return the path slice preserving its leading `/` so the caller
    // can detect an empty path after trimming.
    let path_start = url.len() - path.len() - 1;
    Ok((host, &url[path_start..]))
}

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

    /// Pick a temp path scoped to this process + test name so parallel
    /// test binaries and prior runs don't collide. tempfile is already
    /// a workspace dev-dep (used by other bundle tests below).
    fn unique_test_dir(name: &str) -> PathBuf {
        let dir =
            std::env::temp_dir().join(format!("cera-bundle-test-{}-{}", name, std::process::id()));
        let _ = fs::remove_dir_all(&dir);
        dir
    }

    /// `cache_size` returns 0 when the repo's `store_dir` doesn't
    /// exist yet (no downloads have run). Lazy-creation invariant:
    /// constructing a `BundleRepo` doesn't touch the disk; querying
    /// size before any download returns 0 cleanly.
    #[test]
    fn cache_size_is_zero_when_store_dir_missing() {
        let dir = unique_test_dir("size-empty");
        let repo = BundleRepo::new(&dir);
        assert!(
            !dir.exists(),
            "BundleRepo::new must not eagerly create store_dir"
        );
        assert_eq!(repo.cache_size().unwrap(), 0);
    }

    /// `cache_size` walks nested directories and sums file sizes.
    /// Builds a small synthetic cache (3 files of known sizes spread
    /// across two subdirectories), then asserts the total matches the
    /// sum.
    #[test]
    fn cache_size_sums_nested_files() {
        let dir = unique_test_dir("size-sum");
        fs::create_dir_all(dir.join("huggingface.co/LiquidAI/A")).unwrap();
        fs::create_dir_all(dir.join("huggingface.co/LiquidAI/B")).unwrap();
        fs::write(dir.join("huggingface.co/LiquidAI/A/file1"), vec![0u8; 1024]).unwrap();
        fs::write(
            dir.join("huggingface.co/LiquidAI/A/file1.sha256"),
            b"deadbeef",
        )
        .unwrap();
        fs::write(dir.join("huggingface.co/LiquidAI/B/file2"), vec![0u8; 4096]).unwrap();

        let repo = BundleRepo::new(&dir);
        assert_eq!(repo.cache_size().unwrap(), 1024 + 8 + 4096);

        let _ = fs::remove_dir_all(&dir);
    }

    /// `clear_cache` is idempotent: calling on a non-existent
    /// `store_dir` is a no-op success. Mobile apps invoking it from
    /// a "clear cache" UI before any download has run shouldn't crash.
    #[test]
    fn clear_cache_is_idempotent_on_missing_store_dir() {
        let dir = unique_test_dir("clear-empty");
        let repo = BundleRepo::new(&dir);
        assert!(!dir.exists());
        repo.clear_cache().unwrap();
        // Still no eager creation.
        assert!(!dir.exists());
    }

    /// `clear_cache` removes all files but leaves `store_dir` itself
    /// in place (so subsequent downloads land in the same path).
    /// Asserts the dir still exists + is empty after.
    #[test]
    fn clear_cache_wipes_files_but_keeps_store_dir() {
        let dir = unique_test_dir("clear-wipe");
        fs::create_dir_all(dir.join("huggingface.co/LiquidAI/A")).unwrap();
        fs::write(dir.join("huggingface.co/LiquidAI/A/file"), vec![0u8; 100]).unwrap();
        let repo = BundleRepo::new(&dir);
        assert_eq!(repo.cache_size().unwrap(), 100);

        repo.clear_cache().unwrap();
        assert!(dir.exists(), "store_dir must survive clear_cache");
        assert_eq!(repo.cache_size().unwrap(), 0);

        let _ = fs::remove_dir_all(&dir);
    }

    #[test]
    fn path_for_url_mirrors_host_and_path() {
        let repo = BundleRepo::new("/tmp/store");
        let p = repo
            .path_for_url("https://huggingface.co/LiquidAI/LFM2-1.2B-GGUF/resolve/main/x.gguf")
            .unwrap();
        assert_eq!(
            p,
            PathBuf::from("/tmp/store/huggingface.co/LiquidAI/LFM2-1.2B-GGUF/resolve/main/x.gguf")
        );
    }

    #[test]
    fn split_url_rejects_missing_scheme() {
        assert!(split_url("huggingface.co/x").is_err());
    }

    #[test]
    fn split_url_rejects_missing_path() {
        assert!(split_url("https://huggingface.co").is_err());
    }

    #[test]
    fn split_url_accepts_http_and_https() {
        assert!(split_url("http://example.com/x").is_ok());
        assert!(split_url("https://example.com/x").is_ok());
    }

    #[test]
    fn split_url_scheme_is_case_insensitive() {
        // Mixed-case schemes must be accepted (RFC 3986 §3.1) so we
        // don't drift from `engine::is_remote_url`, which already
        // does case-insensitive matching. Otherwise an `HTTPS://…`
        // URL would pass the remote-URL gate but fail here.
        assert!(split_url("HTTPS://example.com/x").is_ok());
        assert!(split_url("Http://example.com/x").is_ok());
        assert!(split_url("HTTP://example.com/x").is_ok());
    }

    #[test]
    fn path_for_url_lowercases_host_for_cache_consistency() {
        // Two URLs that differ only in host casing must share a cache
        // entry — hosts are case-insensitive per RFC 3986 §3.2.2, but
        // case-sensitive filesystems would otherwise double-cache.
        let repo = BundleRepo::new("/tmp/store");
        let a = repo
            .path_for_url("https://HuggingFace.co/LiquidAI/M/x.gguf")
            .unwrap();
        let b = repo
            .path_for_url("https://huggingface.co/LiquidAI/M/x.gguf")
            .unwrap();
        assert_eq!(a, b);
        assert_eq!(
            a,
            PathBuf::from("/tmp/store/huggingface.co/LiquidAI/M/x.gguf")
        );
    }

    #[test]
    fn path_for_url_rejects_parent_dir_segment() {
        let repo = BundleRepo::new("/tmp/store");
        // Attacker-controlled URL with `..` would otherwise escape
        // `store_dir` after PathBuf::push canonicalization.
        let e = repo
            .path_for_url("https://evil.example.com/a/../../etc/passwd")
            .expect_err("`..` segment must be rejected");
        assert!(format!("{e}").contains("not a valid path component"));
    }

    #[test]
    fn path_for_url_rejects_windows_reserved_chars() {
        // Chars that appear as segment content and are Windows-reserved:
        // `*`, `"`, `<`, `>`, `|`. (`?` and `#` are separately stripped
        // by `path_for_url` as URL syntax — see
        // `path_for_url_strips_query_and_fragment`.) Catching these up
        // front means a Windows consumer never sees a cryptic
        // filesystem error at `PathBuf::push` time.
        let repo = BundleRepo::new("/tmp/store");
        for bad in ["a*b", "a\"b", "a<b", "a>b", "a|b"] {
            let url = format!("https://example.com/{bad}");
            let e = repo
                .path_for_url(&url)
                .expect_err(&format!("{bad:?} must be rejected"));
            let msg = format!("{e}");
            assert!(
                msg.contains("forbidden"),
                "unexpected error for {bad:?}: {msg}"
            );
        }
    }

    #[test]
    fn path_for_url_rejects_empty_segment() {
        let repo = BundleRepo::new("/tmp/store");
        // Double slash produces an empty segment.
        let e = repo
            .path_for_url("https://example.com/a//b")
            .expect_err("empty path segment must be rejected");
        assert!(format!("{e}").contains("must not be empty"));
    }

    #[test]
    fn path_for_url_strips_query_and_fragment() {
        let repo = BundleRepo::new("/tmp/store");
        // Query / fragment are URL syntax; they must not appear in the
        // on-disk path or the filename becomes `model.gguf?x=1` etc.
        let p = repo
            .path_for_url("https://example.com/model.gguf?foo=bar#frag")
            .unwrap();
        assert_eq!(p, PathBuf::from("/tmp/store/example.com/model.gguf"));
    }

    #[test]
    fn path_for_url_rejects_null_byte_in_path() {
        let repo = BundleRepo::new("/tmp/store");
        let e = repo
            .path_for_url("https://example.com/a\0b")
            .expect_err("null byte in path must be rejected");
        assert!(format!("{e}").contains("forbidden"));
    }

    #[test]
    fn hash_matches_uses_sidecar_fast_path() {
        // Covers the first-class invariant behind the PR #37 review's
        // concern about rehashing large cached GGUFs: when a sidecar
        // exists and matches, `hash_matches` must return `true`
        // WITHOUT touching the file contents. We prove the latter by
        // never writing file contents at all — only a sidecar.
        let dir = tempfile::tempdir().unwrap();
        let dest = dir.path().join("x.gguf");
        std::fs::write(&dest, b"").unwrap();
        let hex = "0123456789abcdef".repeat(4);
        assert_eq!(hex.len(), 64);
        std::fs::write(download::sidecar_path(&dest), &hex).unwrap();

        assert!(hash_matches(&dest, "https://example.com/x", &hex));
        // Case-insensitive match.
        assert!(hash_matches(
            &dest,
            "https://example.com/x",
            &hex.to_uppercase()
        ));
        // Mismatch returns false without panicking.
        let wrong = "f".repeat(64);
        assert!(!hash_matches(&dest, "https://example.com/x", &wrong));
    }

    #[test]
    fn hash_matches_full_rehash_when_no_sidecar() {
        // When the sidecar is absent, `hash_matches` falls back to
        // hashing the file.
        let dir = tempfile::tempdir().unwrap();
        let dest = dir.path().join("x.bin");
        std::fs::write(&dest, b"hello").unwrap();
        let correct = "2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824";
        let wrong = "0".repeat(64);
        assert!(hash_matches(&dest, "https://example.com/x", correct));
        assert!(!hash_matches(&dest, "https://example.com/x", &wrong));
    }

    #[test]
    fn leap_manifest_url_happy_path() {
        let url = leap_bundles_manifest_url("LFM2-1.2B-GGUF", "Q4_0").unwrap();
        assert_eq!(
            url,
            "https://huggingface.co/LiquidAI/LeapBundles/resolve/main/LFM2-1.2B-GGUF/Q4_0.json"
        );
    }

    #[test]
    fn leap_manifest_url_rejects_empty() {
        assert!(leap_bundles_manifest_url("", "Q4_0").is_err());
        assert!(leap_bundles_manifest_url("LFM2-1.2B-GGUF", "").is_err());
    }

    #[test]
    fn leap_manifest_url_rejects_path_separators() {
        assert!(leap_bundles_manifest_url("LFM2/GGUF", "Q4_0").is_err());
        assert!(leap_bundles_manifest_url("LFM2-1.2B-GGUF", "sub/Q4_0").is_err());
        assert!(leap_bundles_manifest_url("LFM2\\GGUF", "Q4_0").is_err());
    }

    #[test]
    fn leap_manifest_url_rejects_parent_dir() {
        assert!(leap_bundles_manifest_url("..", "Q4_0").is_err());
        assert!(leap_bundles_manifest_url("LFM2-1.2B-GGUF", "..").is_err());
    }

    #[test]
    fn leap_manifest_url_rejects_whitespace_and_url_reserved() {
        assert!(leap_bundles_manifest_url("LFM2 GGUF", "Q4_0").is_err());
        assert!(leap_bundles_manifest_url("LFM2-1.2B-GGUF", "Q4 0").is_err());
        assert!(leap_bundles_manifest_url("LFM2-1.2B-GGUF", "Q4_0\n").is_err());
        // URL-reserved chars must be rejected so they can't alter URL
        // semantics when interpolated.
        assert!(leap_bundles_manifest_url("LFM2?x", "Q4_0").is_err());
        assert!(leap_bundles_manifest_url("LFM2#x", "Q4_0").is_err());
        assert!(leap_bundles_manifest_url("LFM2%2E", "Q4_0").is_err());
    }

    /// `parse_leap_bundles` groups `<bundle>/<quant>.json` siblings
    /// into bundle entries with sorted quants, drops top-level
    /// blobs / READMEs, and rejects deeper-nested paths so a future
    /// schema change is visible instead of silently misrendered.
    #[test]
    fn parse_leap_bundles_groups_siblings() {
        let body = r#"{
            "siblings": [
                {"rfilename": ".gitattributes"},
                {"rfilename": "README.md"},
                {"rfilename": "LFM2-1.2B-8da4w_output_8da8w-seq_4096.bundle"},
                {"rfilename": "LFM2-1.2B-GGUF/Q8_0.json"},
                {"rfilename": "LFM2-1.2B-GGUF/Q4_0.json"},
                {"rfilename": "LFM2-1.2B-GGUF/Q4_K_M.json"},
                {"rfilename": "LFM2-2.6B-GGUF/Q4_0.json"},
                {"rfilename": "LFM2-2.6B-GGUF/notes/extra.json"},
                {"rfilename": "LFM2-2.6B-GGUF/extras.txt"}
            ]
        }"#;
        let entries = parse_leap_bundles(body).unwrap();
        assert_eq!(entries.len(), 2, "expected 2 bundles, got {entries:?}");
        // BTreeMap → ascending bundle name order.
        assert_eq!(entries[0].name, "LFM2-1.2B-GGUF");
        assert_eq!(entries[0].quants, vec!["Q4_0", "Q4_K_M", "Q8_0"]);
        assert_eq!(entries[1].name, "LFM2-2.6B-GGUF");
        // `extras.txt` (wrong suffix) and `notes/extra.json`
        // (deeper-nested) both filtered out.
        assert_eq!(entries[1].quants, vec!["Q4_0"]);
    }

    #[test]
    fn parse_leap_bundles_rejects_malformed_json() {
        let err = parse_leap_bundles("not json at all").unwrap_err();
        let msg = format!("{err}");
        assert!(msg.contains("JSON parse failed"), "got: {msg}");
    }

    /// Empty `siblings` is a valid response shape (e.g. an empty
    /// repo) and should yield an empty catalog rather than an
    /// error.
    #[test]
    fn parse_leap_bundles_empty_siblings_is_ok() {
        let entries = parse_leap_bundles(r#"{"siblings": []}"#).unwrap();
        assert!(entries.is_empty());
    }

    /// Entries whose bundle / quant segment would fail
    /// `validate_path_segment` are dropped silently — surfacing
    /// them would mislead users since `from_bundle_id` rejects
    /// the same characters at resolve time. Today's catalog has
    /// none of these, but the filter is forward-compatible with
    /// any HF schema drift toward whitespace / non-ASCII names.
    #[test]
    fn parse_leap_bundles_drops_invalid_path_segments() {
        let body = r#"{
            "siblings": [
                {"rfilename": "Good-Bundle-GGUF/Q4_0.json"},
                {"rfilename": "Has Space-GGUF/Q4_0.json"},
                {"rfilename": "Good-Bundle-GGUF/Q 0.json"},
                {"rfilename": "Has?Reserved/Q4_0.json"},
                {"rfilename": "Café-GGUF/Q4_0.json"}
            ]
        }"#;
        let entries = parse_leap_bundles(body).unwrap();
        assert_eq!(entries.len(), 1, "expected only the valid entry");
        assert_eq!(entries[0].name, "Good-Bundle-GGUF");
        // The invalid quant `Q 0` got filtered, leaving the one
        // good `Q4_0` quant.
        assert_eq!(entries[0].quants, vec!["Q4_0"]);
    }
}