fxcp_core/

sidecar.rs

// SPDX-License-Identifier: GPL-2.0-or-later
// Copyright (C) 2025 Joel Wirāmu Pauling <aenertia@aenertia.net>
//
//! Xattr/sidecar metadata  --  SyncSignature, MerkleSignature, dir_hash.
//!
//! Metadata/dirty-flag management via xattr (primary) with JSON sidecar fallback.
// Architecture: xattrs are the canonical store. Sidecar JSON files are ONLY
// used as a fallback for filesystems that lack xattr support (exfat, vfat, etc.).
#![allow(clippy::unwrap_used, clippy::expect_used)]
use std::path::{Path, PathBuf};
use std::fs::{self, File};
use std::collections::HashMap;
use serde_json;
use std::os::unix::io::AsRawFd;
use libc;
use std::io::{self};
use xattr;
use tracing::{error, debug, warn};
use tokio::sync::{mpsc, oneshot};
use std::thread;
use std::sync::atomic::{AtomicBool, Ordering};
use crate::hashing;
use std::os::unix::fs::MetadataExt;

const NS_USER_PREFIX: &str = "user.foxing.";
const NS_TRUSTED_PREFIX: &str = "trusted.foxing.";
static FALLBACK_WARNED: AtomicBool = AtomicBool::new(false);
/// Set once xattr is confirmed unsupported  --  all subsequent writes go to sidecar
static XATTR_UNSUPPORTED: AtomicBool = AtomicBool::new(false);

// --- foxing xattr key namespace ---

/// xattr key for similarity metadata (SimHash, entropy class).
pub const XATTR_SIMILARITY: &str = "user.foxing.sim";
/// xattr key for file-level similarity fingerprint.
pub const XATTR_FILE_SIMILARITY: &str = "user.foxing.fsim";
/// xattr key for embedding metadata (model, dimensions, chunk count).
pub const XATTR_EMBEDDING: &str = "user.foxing.emb";
/// xattr key for LLM enrichment data (Dublin Core, APP envelope).
pub const XATTR_ENRICHMENT: &str = "user.foxing.enriched";
/// xattr key for extracted media metadata (EXIF, ID3, PDF info).
pub const XATTR_MEDIA_META: &str = "user.foxing.media_meta";

#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
/// File sync signature stored in xattr/sidecar for change detection
pub struct SyncSignature {
    /// File size in bytes
    pub size: u64,
    /// Modification time (seconds since epoch)
    pub mtime_sec: i64,
    /// Modification time nanosecond component
    pub mtime_nsec: i64,
    /// Hex-encoded BLAKE3 lite hash (head+tail sampling)
    pub hash: Option<String>,
    /// Hex-encoded BLAKE3 full Merkle root
    pub merkle_root: Option<String>,
    /// Chunk size used for Merkle tree construction
    pub chunk_size: Option<u64>,
    /// Number of Merkle leaves (v4+)
    pub leaf_count: Option<u32>,
    /// Average Shannon entropy across all chunks (v5+, 0.0-8.0 bits/byte)
    #[serde(default)]
    pub avg_entropy: Option<f32>,
    /// Entropy classification label (v5+, e.g. "low", "medium", "high", "encrypted")
    #[serde(default)]
    pub entropy_class: Option<String>,
    /// SimHash-64 whole-file fingerprint stored as i64 for pgvector BIGINT compat (v5+)
    #[serde(default)]
    pub file_simhash: Option<i64>,
    /// Signature schema version
    pub version: u8,
}

/// V4 layout: identical to SyncSignature but without avg_entropy, entropy_class, file_simhash.
/// Used ONLY for deserializing legacy xattr blobs from pre-v5 deployments.
#[derive(serde::Serialize, serde::Deserialize)]
struct SyncSignatureV4 {
    size: u64,
    mtime_sec: i64,
    mtime_nsec: i64,
    hash: Option<String>,
    merkle_root: Option<String>,
    chunk_size: Option<u64>,
    leaf_count: Option<u32>,
    version: u8,
}

/// V3 layout: identical to SyncSignature but without leaf_count.
/// Used ONLY for deserializing legacy xattr blobs from pre-v4 deployments.
#[derive(serde::Serialize, serde::Deserialize)]
struct SyncSignatureV3 {
    size: u64,
    mtime_sec: i64,
    mtime_nsec: i64,
    hash: Option<String>,
    merkle_root: Option<String>,
    chunk_size: Option<u64>,
    version: u8,
}

/// Compute byte-weighted average entropy and entropy class label from Merkle leaves.
///
/// Entropy bands follow ADR S4 thresholds: Sparse (<0.5), Text (<5.5),
/// Binary (<7.0), Compressed (<7.5), Encrypted (>=7.5). Dominant band must
/// exceed 66% of total bytes, otherwise "mixed".
fn compute_entropy_fields(leaves: &[hashing::ChunkHash]) -> (Option<f32>, Option<String>) {
    let total_bytes: u64 = leaves.iter().map(|c| c.length as u64).sum();
    if total_bytes == 0 {
        return (None, None);
    }
    let weighted_sum: f64 = leaves.iter()
        .map(|c| c.entropy as f64 * c.length as f64)
        .sum();
    let avg = (weighted_sum / total_bytes as f64) as f32;

    let mut band_bytes = [0u64; 5];
    for chunk in leaves {
        let band = match () {
            _ if chunk.entropy < 0.5 => 0,
            _ if chunk.entropy < 5.5 => 1,
            _ if chunk.entropy < 7.0 => 2,
            _ if chunk.entropy < 7.5 => 3,
            _ => 4,
        };
        band_bytes[band] += chunk.length as u64;
    }
    let (dominant_band, &dominant_bytes) = band_bytes
        .iter()
        .enumerate()
        .max_by_key(|(_, b)| **b)
        .expect("band_bytes is non-empty");
    let class_label = if dominant_bytes * 100 > total_bytes * 66 {
        match dominant_band {
            0 => "sparse",
            1 => "text",
            2 => "binary",
            3 => "compressed",
            _ => "encrypted",
        }
    } else {
        "mixed"
    };
    (Some(avg), Some(class_label.to_string()))
}

impl SyncSignature {
    pub const CURRENT_VERSION: u8 = 5;

    /// Compute a sync signature from a file's current metadata and content hashes
    pub fn compute(path: &Path) -> crate::error::Result<Self> {
        let meta = std::fs::metadata(path)?;
        let size = meta.len();
        let chunk_size = hashing::calculate_adaptive_chunk_size(size);

        #[cfg(feature = "similarity")]
        let compute_mode = hashing::ComputeMode::WithSimilarity;
        #[cfg(not(feature = "similarity"))]
        let compute_mode = hashing::ComputeMode::WithEntropy;

        let (hash, merkle_root, avg_entropy, entropy_class, file_simhash) =
            if hashing::is_hashing_enabled() {
                if size >= hashing::get_lite_threshold_bytes() {
                    let lite = hashing::hash_file_lite(path, size)?
                        .map(|h| h.to_hex().to_string());
                    let tree = hashing::MerkleTree::from_file(path, chunk_size, compute_mode).ok();
                    let merkle = tree.as_ref().map(|t| t.root.to_hex().to_string());

                    // Compute byte-weighted average entropy from Merkle leaves
                    let (avg_ent, ent_class) = tree.as_ref()
                        .map(|t| compute_entropy_fields(&t.leaves))
                        .unwrap_or((None, None));

                    // Compute file-level SimHash (similarity feature only)
                    #[cfg(feature = "similarity")]
                    let sim = tree.as_ref().map(|t| t.file_simhash() as i64);
                    #[cfg(not(feature = "similarity"))]
                    let sim: Option<i64> = None;

                    (lite, merkle, avg_ent, ent_class, sim)
                } else {
                    (None, None, None, None, None)
                }
            } else {
                (None, None, None, None, None)
            };

        Ok(Self {
            size,
            mtime_sec: meta.mtime(),
            mtime_nsec: meta.mtime_nsec(),
            hash,
            merkle_root,
            chunk_size: Some(chunk_size),
            leaf_count: None,
            avg_entropy,
            entropy_class,
            file_simhash,
            version: Self::CURRENT_VERSION,
        })
    }

    /// Compute a signature from an in-memory buffer. Used by the NFS compound
    /// bypass path where file data is already in memory.
    pub fn compute_from_buffer(data: &[u8], mtime_sec: i64, mtime_nsec: i64) -> Self {
        let size = data.len() as u64;
        let (hash, merkle_root) = if hashing::is_hashing_enabled() {
            if size >= hashing::get_lite_threshold_bytes() {
                let lite = hashing::hash_buffer_lite(data, size)
                    .map(|h| h.to_hex().to_string());
                let full = hashing::hash_buffer_full(data)
                    .map(|h| h.to_hex().to_string());
                (lite, full)
            } else {
                (None, None)
            }
        } else {
            (None, None)
        };
        Self {
            size, mtime_sec, mtime_nsec,
            hash, merkle_root,
            chunk_size: Some(hashing::calculate_adaptive_chunk_size(size)),
            leaf_count: None,
            avg_entropy: None,
            entropy_class: None,
            file_simhash: None,
            version: Self::CURRENT_VERSION,
        }
    }

    /// Serialize to bincode bytes for xattr storage
    pub fn serialize(&self) -> Vec<u8> {
        bincode::serialize(self).unwrap_or_default()
    }

    /// Deserialize from bincode bytes (returns None on invalid data)
    pub fn deserialize(data: &[u8]) -> Option<Self> {
        bincode::deserialize(data).ok()
    }

    /// Version-aware deserialization. Handles v5 (current), v4 (missing
    /// entropy/simhash fields), v3 (missing leaf_count), and unknown/corrupt
    /// blobs (returns None with warn! log).
    pub fn deserialize_versioned(data: &[u8]) -> Option<Self> {
        if data.is_empty() {
            return None;
        }

        // Try v5 first (current format)
        if let Ok(sig) = bincode::deserialize::<SyncSignature>(data)
            && sig.version == Self::CURRENT_VERSION {
                return Some(sig);
            }

        // Try v4 (without avg_entropy, entropy_class, file_simhash)
        if let Ok(v4) = bincode::deserialize::<SyncSignatureV4>(data)
            && v4.version == 4 {
                warn!(
                    "sidecar: migrated SyncSignature from v{} to v{} (entropy/simhash fields not present)",
                    v4.version, Self::CURRENT_VERSION
                );
                return Some(SyncSignature {
                    size: v4.size,
                    mtime_sec: v4.mtime_sec,
                    mtime_nsec: v4.mtime_nsec,
                    hash: v4.hash,
                    merkle_root: v4.merkle_root,
                    chunk_size: v4.chunk_size,
                    leaf_count: v4.leaf_count,
                    avg_entropy: None,
                    entropy_class: None,
                    file_simhash: None,
                    version: Self::CURRENT_VERSION,
                });
            }

        // Try v3 (without leaf_count)
        if let Ok(v3) = bincode::deserialize::<SyncSignatureV3>(data)
            && v3.version <= 3 {
                warn!(
                    "sidecar: migrated SyncSignature from v{} to v{} (leaf_count not present)",
                    v3.version, Self::CURRENT_VERSION
                );
                return Some(SyncSignature {
                    size: v3.size,
                    mtime_sec: v3.mtime_sec,
                    mtime_nsec: v3.mtime_nsec,
                    hash: v3.hash,
                    merkle_root: v3.merkle_root,
                    chunk_size: v3.chunk_size,
                    leaf_count: None,
                    avg_entropy: None,
                    entropy_class: None,
                    file_simhash: None,
                    version: Self::CURRENT_VERSION,
                });
            }

        // Unknown format
        warn!(
            "sidecar: failed to deserialize SyncSignature ({} bytes, first byte: 0x{:02x})",
            data.len(),
            data[0]
        );
        None
    }

    /// Check if two signatures represent the same file state (merkle_root takes priority over mtime)
    pub fn matches(&self, other: &Self) -> bool {
        if self.size != other.size { return false; }

        // BUGFIX BUG-007: Verify mtime before trusting merkle_root comparison.
        // A file modified in-place (same size, conv=notrunc dd) after its sig was
        // stored will have a newer mtime on the source but the same size.
        // Without this check, the merkle_root early-return silently skips it.
        if self.mtime_sec != other.mtime_sec || self.mtime_nsec != other.mtime_nsec {
            return false;
        }

        if let (Some(a), Some(b)) = (&self.merkle_root, &other.merkle_root) { return a == b }

        match (&self.hash, &other.hash) {
            (Some(a), Some(b)) => a == b,
            _ => true,
        }
    }

    /// Return the lite hash as a CID string (computed on demand from hex).
    pub fn hash_cid(&self) -> Option<String> {
        self.hash.as_ref().and_then(|h| crate::cid::blake3_hex_to_cid_string(h).ok())
    }

    /// Return the Merkle root as a CID string (computed on demand from hex).
    pub fn merkle_root_cid(&self) -> Option<String> {
        self.merkle_root.as_ref().and_then(|h| crate::cid::blake3_hex_to_cid_string(h).ok())
    }
}

fn resolve_key_variants(key: &str) -> (String, String) {
    if key.starts_with("user.foxing.") {
        let suffix = key.strip_prefix("user.foxing.").unwrap();
        (format!("{}{}", NS_TRUSTED_PREFIX, suffix), key.to_string())
    } else if key.starts_with("trusted.foxing.") {
        let suffix = key.strip_prefix("trusted.foxing.").unwrap();
        (key.to_string(), format!("{}{}", NS_USER_PREFIX, suffix))
    } else {
        (format!("{}{}", NS_TRUSTED_PREFIX, key), format!("{}{}", NS_USER_PREFIX, key))
    }
}

/// Returns true if the error indicates xattrs are not supported on this filesystem.
fn is_xattr_unsupported(e: &io::Error) -> bool {
    if let Some(code) = e.raw_os_error() {
        code == libc::EOPNOTSUPP || code == libc::ENOTSUP || code == libc::ENOSYS
            || code == libc::EACCES
    } else {
        false
    }
}

// --- Sidecar fallback (only for filesystems without xattr support) ---

/// Compute the `.foxing_meta` sidecar path for a given file
pub fn get_sidecar_path(target_path: &Path) -> Option<PathBuf> {
    let file_name = target_path.file_name()?.to_str()?;
    let sidecar_name = format!(".{}.foxing_meta", file_name);
    Some(target_path.with_file_name(sidecar_name))
}

fn lock_file(file: &File, exclusive: bool) -> std::io::Result<()> {
    let fd = file.as_raw_fd();
    let op = if exclusive { libc::LOCK_EX } else { libc::LOCK_SH };
    // SAFETY: fd is a valid open file descriptor from file.as_raw_fd().
    let ret = unsafe { libc::flock(fd, op) };
    if ret == 0 { Ok(()) } else { Err(std::io::Error::last_os_error()) }
}

fn unlock_file(file: &File) -> std::io::Result<()> {
    let fd = file.as_raw_fd();
    // SAFETY: fd is a valid open file descriptor from file.as_raw_fd().
    let ret = unsafe { libc::flock(fd, libc::LOCK_UN) };
    if ret == 0 { Ok(()) } else { Err(std::io::Error::last_os_error()) }
}

fn sidecar_set(path: &Path, key: &str, value: &[u8]) -> std::io::Result<()> {
    let sp = match get_sidecar_path(path) {
        Some(p) => p,
        None => return Err(io::Error::new(io::ErrorKind::InvalidInput, "Cannot determine sidecar path")),
    };
    let (_trusted_key, user_key) = resolve_key_variants(key);
    let file = fs::OpenOptions::new().read(true).write(true).create(true).open(&sp)?;
    lock_file(&file, true)?;
    let mut map: HashMap<String, String> = serde_json::from_reader(&file).unwrap_or_default();
    map.insert(user_key, hex::encode(value));
    // Atomic write: tmp -> fsync -> rename
    let tmp_path = {
        let mut t = sp.as_os_str().to_os_string();
        t.push(".tmp");
        std::path::PathBuf::from(t)
    };
    {
        let tmp_file = File::create(&tmp_path)?;
        serde_json::to_writer(&tmp_file, &map)?;
        tmp_file.sync_data()?;
    }
    std::fs::rename(&tmp_path, &sp)?;
    unlock_file(&file)?;
    crate::metrics::SIDECAR_FILES_CREATED.inc();
    Ok(())
}

fn sidecar_set_batch(path: &Path, entries: &[(&str, &[u8])]) -> std::io::Result<()> {
    let sp = match get_sidecar_path(path) {
        Some(p) => p,
        None => return Err(io::Error::new(io::ErrorKind::InvalidInput, "Cannot determine sidecar path")),
    };
    let file = fs::OpenOptions::new().read(true).write(true).create(true).open(&sp)?;
    lock_file(&file, true)?;
    let mut map: HashMap<String, String> = serde_json::from_reader(&file).unwrap_or_default();
    for &(key, value) in entries {
        let (_trusted_key, user_key) = resolve_key_variants(key);
        map.insert(user_key, hex::encode(value));
    }
    let tmp_path = {
        let mut t = sp.as_os_str().to_os_string();
        t.push(".tmp");
        std::path::PathBuf::from(t)
    };
    {
        let tmp_file = File::create(&tmp_path)?;
        serde_json::to_writer(&tmp_file, &map)?;
        tmp_file.sync_data()?;
    }
    std::fs::rename(&tmp_path, &sp)?;
    unlock_file(&file)?;
    crate::metrics::SIDECAR_FILES_CREATED.inc();
    Ok(())
}

fn sidecar_get(path: &Path, key: &str) -> Option<Vec<u8>> {
    let sp = get_sidecar_path(path)?;
    let file = File::open(&sp).ok()?;
    if lock_file(&file, false).is_err() { return None; }
    let map: HashMap<String, String> = serde_json::from_reader(&file).unwrap_or_default();
    let _ = unlock_file(&file);
    let (trusted_key, user_key) = resolve_key_variants(key);
    let val_str = map.get(&trusted_key).or_else(|| map.get(&user_key))?;
    hex::decode(val_str).ok()
}

fn sidecar_remove(path: &Path, key: &str) -> std::io::Result<()> {
    let sp = match get_sidecar_path(path) {
        Some(p) => p,
        None => return Ok(()),
    };
    if !sp.exists() { return Ok(()); }
    let file = fs::OpenOptions::new().read(true).write(true).open(&sp)?;
    if lock_file(&file, true).is_err() { return Ok(()); }
    let mut map: HashMap<String, String> = serde_json::from_reader(&file).unwrap_or_default();
    let (trusted_key, user_key) = resolve_key_variants(key);
    let rem1 = map.remove(&trusted_key).is_some();
    let rem2 = map.remove(&user_key).is_some();
    if rem1 || rem2 {
        if map.is_empty() {
            let _ = fs::remove_file(&sp);
        } else {
            let tmp_path = {
                let mut t = sp.as_os_str().to_os_string();
                t.push(".tmp");
                std::path::PathBuf::from(t)
            };
            {
                let tmp_file = File::create(&tmp_path)?;
                serde_json::to_writer(&tmp_file, &map)?;
                tmp_file.sync_data()?;
            }
            std::fs::rename(&tmp_path, &sp)?;
        }
    }
    let _ = unlock_file(&file);
    Ok(())
}

// --- Public API ---

/// Try xattr set (trusted then user namespace). Returns Ok if xattr worked,
/// Err if xattr unsupported and caller should use sidecar fallback.
fn try_xattr_set(path: &Path, key: &str, value: &[u8]) -> std::result::Result<(), io::Error> {
    let (trusted_key, user_key) = resolve_key_variants(key);
    match xattr::set(path, &trusted_key, value) {
        Ok(_) => Ok(()),
        Err(e) => {
            if is_xattr_unsupported(&e) {
                // trusted namespace not available (unprivileged)  --  try user namespace
                match xattr::set(path, &user_key, value) {
                    Ok(_) => {
                        if !FALLBACK_WARNED.swap(true, Ordering::Relaxed) {
                            warn!("Security: 'trusted' xattr namespace unavailable. Using 'user' namespace.");
                        }
                        Ok(())
                    }
                    Err(e2) if is_xattr_unsupported(&e2) => Err(e2),
                    Err(e2) => {
                        // EPERM on user namespace likely means filesystem doesn't support xattrs at all
                        if e2.raw_os_error() == Some(libc::EPERM) {
                            Err(e2)
                        } else {
                            warn!("xattr set failed for {:?}: {}, falling back to sidecar", path, e2);
                            Err(e2)
                        }
                    }
                }
            } else {
                // EPERM on trusted  --  expected for non-root, try user namespace
                if e.raw_os_error() == Some(libc::EPERM) {
                    match xattr::set(path, &user_key, value) {
                        Ok(_) => {
                            if !FALLBACK_WARNED.swap(true, Ordering::Relaxed) {
                                warn!("Security: 'trusted' xattr namespace unavailable. Using 'user' namespace.");
                            }
                            Ok(())
                        }
                        Err(e2) if is_xattr_unsupported(&e2) => Err(e2),
                        Err(e2) => {
                            warn!("xattr set failed for {:?}: {}, falling back to sidecar", path, e2);
                            Err(e2)
                        }
                    }
                } else {
                    warn!("xattr set failed for {:?}: {}, falling back to sidecar", path, e);
                    Err(e)
                }
            }
        }
    }
}

/// Store a metadata key-value pair via xattr (primary) or JSON sidecar (fallback)
pub fn set_metadata(path: &Path, key: &str, value: &[u8]) -> std::io::Result<()> {
    if let Ok(meta) = fs::symlink_metadata(path) {
        if meta.is_symlink() { return Ok(()); }
    } else { return Ok(()); }

    // Fast path: if we already know xattr is unsupported, go straight to sidecar
    if XATTR_UNSUPPORTED.load(Ordering::Relaxed) {
        return sidecar_set(path, key, value);
    }

    match try_xattr_set(path, key, value) {
        Ok(()) => Ok(()),
        Err(_) => {
            // xattr not supported on this filesystem  --  mark and use sidecar
            XATTR_UNSUPPORTED.store(true, Ordering::Relaxed);
            warn!("xattr unsupported on filesystem for {:?}. Falling back to sidecar JSON.", path);
            sidecar_set(path, key, value)
        }
    }
}

/// Write multiple metadata keys. Uses xattr per-key (kernel can't batch),
/// but avoids sidecar entirely unless xattr is unsupported.
pub fn set_metadata_batch(path: &Path, entries: &[(&str, &[u8])]) -> std::io::Result<()> {
    if entries.is_empty() { return Ok(()); }
    if let Ok(meta) = fs::symlink_metadata(path) {
        if meta.is_symlink() { return Ok(()); }
    } else { return Ok(()); }

    if XATTR_UNSUPPORTED.load(Ordering::Relaxed) {
        return sidecar_set_batch(path, entries);
    }

    for &(key, value) in entries {
        if let Err(e) = try_xattr_set(path, key, value) {
            let is_permanent = e.raw_os_error().is_some_and(|errno| {
                errno == libc::EOPNOTSUPP || errno == libc::ENOTSUP
                    || errno == libc::EPERM || errno == libc::EACCES
            });
            if is_permanent {
                XATTR_UNSUPPORTED.store(true, Ordering::Relaxed);
                warn!("xattr unsupported on filesystem for {:?} ({}). Falling back to sidecar JSON.", path, e);
            } else {
                warn!("xattr write failed for {:?} key={} ({}), falling back to sidecar for this file", path, key, e);
            }
            return sidecar_set_batch(path, entries);
        }
    }
    Ok(())
}

/// Retrieve a metadata value by key from xattr or sidecar fallback
pub fn get_metadata(path: &Path, key: &str) -> Option<Vec<u8>> {
    if let Ok(meta) = fs::symlink_metadata(path) {
        if meta.is_symlink() { return None; }
    } else { return None; }

    // Fast path: if xattr is known-unsupported, go straight to sidecar
    if XATTR_UNSUPPORTED.load(Ordering::Relaxed) {
        return sidecar_get(path, key);
    }

    let (trusted_key, user_key) = resolve_key_variants(key);

    // Try trusted xattr first
    match xattr::get(path, &trusted_key) {
        Ok(Some(val)) => return Some(val),
        Ok(None) => {},
        Err(_) => {}
    }
    // Try user xattr
    match xattr::get(path, &user_key) {
        Ok(Some(val)) => return Some(val),
        Ok(None) => {},
        Err(_) => {}
    }

    // Fallback: check sidecar (for migration from old dual-write or xattr-less fs)
    sidecar_get(path, key)
}

/// Remove a metadata key from both xattr namespaces and sidecar
pub fn remove_metadata(path: &Path, key: &str) -> std::io::Result<()> {
    let (trusted_key, user_key) = resolve_key_variants(key);
    let trusted_res = xattr::remove(path, &trusted_key);
    let user_res = xattr::remove(path, &user_key);

    // Also clean up any legacy sidecar entry
    let _ = sidecar_remove(path, key);

    if trusted_res.is_err() && user_res.is_err() {
        let err = trusted_res.unwrap_err();
        if err.kind() == io::ErrorKind::NotFound {
            return Ok(());
        }
        if let Some(code) = err.raw_os_error()
            && (code == libc::EOPNOTSUPP || code == libc::ENOTSUP || code == libc::ENOSYS || code == libc::EPERM || code == libc::ENODATA || code == libc::EPROTONOSUPPORT) {
                return Ok(());
            }
        error!("Failed to remove xattr {}: {}", key, err);
        return Err(err);
    }
    Ok(())
}

/// Check if a file has the dirty flag set (indicates an in-progress copy)
pub fn is_dirty(path: &Path) -> bool {
    if let Some(val) = get_metadata(path, "dirty") {
        return val == vec![1];
    }
    false
}

/// Set or clear the dirty flag on a file
pub fn set_dirty_flag(path: &Path, active: bool, _reason: &str) -> std::io::Result<()> {
    if active {
        set_metadata(path, "dirty", &[1])
    } else {
        remove_metadata(path, "dirty")
    }
}

/// Store a sync signature in the file's xattr/sidecar metadata
pub fn set_sync_signature(path: &Path, sig: &SyncSignature) -> std::io::Result<()> {
    set_metadata(path, "sig", &sig.serialize())
}

/// Retrieve the stored sync signature for a file
pub fn get_sync_signature(path: &Path) -> Option<SyncSignature> {
    let raw = get_metadata(path, "sig")?;
    SyncSignature::deserialize_versioned(&raw)
}

/// Store a directory-level Merkle hash via xattr on the target directory.
pub fn set_dir_hash(path: &Path, hash: &[u8; 32]) -> std::io::Result<()> {
    set_metadata(path, "dir_hash", hash)
}

/// Retrieve a stored directory hash from xattr.
pub fn get_dir_hash(path: &Path) -> Option<[u8; 32]> {
    let bytes = get_metadata(path, "dir_hash")?;
    if bytes.len() == 32 {
        let mut arr = [0u8; 32];
        arr.copy_from_slice(&bytes);
        Some(arr)
    } else {
        None
    }
}

/// Clear a stored directory hash (invalidation).
pub fn clear_dir_hash(path: &Path) -> std::io::Result<()> {
    remove_metadata(path, "dir_hash")
}

/// Store a Merkle signature in xattr (small files) or per-target index (large files)
pub fn set_merkle_signature(path: &Path, sig: &hashing::MerkleSignature) -> std::io::Result<()> {
    let data = bincode::serialize(sig)
        .map_err(|e| std::io::Error::new(std::io::ErrorKind::InvalidData, e))?;
    if data.len() <= crate::constants::MERKLE_XATTR_MAX_BYTES {
        // Fits in xattr  --  fast path
        set_metadata(path, "merkle", &data)
    } else {
        // Too large for xattr  --  store in per-target Merkle index
        set_merkle_in_index(path, sig)
    }
}

/// Store large Merkle signature in the per-target index.
/// Resolves the target root from the file path by walking up to find .foxing_meta
/// or the mount point.
fn set_merkle_in_index(path: &Path, sig: &hashing::MerkleSignature) -> std::io::Result<()> {
    if let Some((target_root, rel_path)) = resolve_target_root(path) {
        crate::merkle_index::set(&target_root, &rel_path, sig)
    } else {
        Err(std::io::Error::other(
            format!("merkle_index: Cannot resolve target root for {:?}", path),
        ))
    }
}

/// Retrieve a stored Merkle signature from xattr or per-target index
pub fn get_merkle_signature(path: &Path) -> Option<hashing::MerkleSignature> {
    // Try xattr first (fast, covers small files)
    if let Some(bytes) = get_metadata(path, "merkle") {
        let sig: hashing::MerkleSignature = bincode::deserialize(&bytes).ok()?;
        if sig.chunk_size == 0 { return None; }
        let expected_max = sig.file_size / sig.chunk_size + 2;
        if sig.leaf_hashes.len() as u64 > expected_max { return None; }
        return Some(sig);
    }
    // Fall back to per-target Merkle index (large files)
    if let Some((target_root, rel_path)) = resolve_target_root(path) {
        return crate::merkle_index::get(&target_root, &rel_path);
    }
    None
}

/// Walk up from a file path to find the target root directory.
/// Heuristic: look for `.foxing_versions`, `.foxing_meta`, or `.foxing_cas` marker.
/// Falls back to 2 levels up (target/subdir/file).
fn resolve_target_root(path: &Path) -> Option<(PathBuf, PathBuf)> {
    let path = path.canonicalize().ok().unwrap_or_else(|| path.to_path_buf());
    let mut current = path.parent()?;

    // Walk up looking for foxing metadata directories
    for _ in 0..10 {
        if current.join(".foxing_versions").exists()
            || current.join(".foxing_meta").exists()
            || current.join(".foxing_cas").exists()
        {
            let rel = path.strip_prefix(current).ok()?;
            return Some((current.to_path_buf(), rel.to_path_buf()));
        }
        current = current.parent()?;
    }

    // Fallback: assume parent of parent is target root
    let parent = path.parent()?;
    let grandparent = parent.parent()?;
    let rel = path.strip_prefix(grandparent).ok()?;
    Some((grandparent.to_path_buf(), rel.to_path_buf()))
}

enum SidecarOp {
    SetDirty {
        path: PathBuf,
        response: Option<oneshot::Sender<io::Result<()>>>,
    },
    ClearDirty {
        path: PathBuf,
    },
}

/// Background thread for non-blocking dirty flag I/O
#[derive(Clone)]
pub struct AsyncSidecar {
    tx: mpsc::UnboundedSender<SidecarOp>,
}

impl AsyncSidecar {
    /// Spawn the background sidecar I/O thread
    pub fn new() -> Self {
        let (tx, mut rx) = mpsc::unbounded_channel::<SidecarOp>();
        thread::Builder::new()
            .name("foxing-sidecar-io".into())
            .spawn(move || {
                debug!("AsyncSidecar: Background thread started.");
                while let Some(op) = rx.blocking_recv() {
                    match op {
                        SidecarOp::SetDirty { path, response } => {
                            let res = set_dirty_flag(&path, true, "ASYNC_WRITE");
                            if let Some(resp_tx) = response {
                                let _ = resp_tx.send(res);
                            }
                        },
                        SidecarOp::ClearDirty { path } => {
                            if let Err(e) = set_dirty_flag(&path, false, "ASYNC_CLEAR") {
                                debug!("AsyncSidecar: Failed to clear dirty flag for {:?}: {}", path, e);
                            }
                        }
                    }
                }
                debug!("AsyncSidecar: Background thread stopping.");
            })
            .expect("Failed to spawn sidecar thread");
        Self { tx }
    }
    /// Set the dirty flag asynchronously and wait for confirmation
    pub async fn set_dirty(&self, path: PathBuf) -> io::Result<()> {
        let (resp_tx, resp_rx) = oneshot::channel();
        if self.tx.send(SidecarOp::SetDirty { path, response: Some(resp_tx) }).is_err() {
            return Err(io::Error::new(io::ErrorKind::BrokenPipe, "Sidecar worker dead"));
        }
        match resp_rx.await {
            Ok(res) => res,
            Err(_) => Err(io::Error::new(io::ErrorKind::BrokenPipe, "Sidecar worker dropped response")),
        }
    }
    /// Set the dirty flag without waiting for completion (fire-and-forget)
    pub fn set_dirty_blind(&self, path: PathBuf) {
        let _ = self.tx.send(SidecarOp::SetDirty { path, response: None });
    }
    /// Clear the dirty flag asynchronously
    pub fn clear_dirty(&self, path: PathBuf) {
        let _ = self.tx.send(SidecarOp::ClearDirty { path });
    }

    /// Clear the dirty flag when a file is skipped (already in sync)
    pub fn clear_dirty_on_skip(&self, target_path: PathBuf) {
        let _ = self.tx.send(SidecarOp::ClearDirty { path: target_path });
    }
}

#[cfg(test)]
mod tests {
    #![allow(clippy::expect_used, clippy::panic, clippy::unwrap_in_result, clippy::unwrap_used)]
    use super::*;
    use tempfile::TempDir;
    use std::io::Write;

    /// Mutex to serialize tests that mutate the global `XATTR_UNSUPPORTED` flag.
    static TEST_XATTR_MUTEX: std::sync::Mutex<()> = std::sync::Mutex::new(());

    #[test]
    fn test_sidecar_sync_signature_v5_roundtrip() {
        let sig = SyncSignature {
            size: 123456,
            mtime_sec: 1700000000,
            mtime_nsec: 999999999,
            hash: Some("abcdef0123456789".to_string()),
            merkle_root: Some("fedcba9876543210".to_string()),
            chunk_size: Some(65536),
            leaf_count: Some(42),
            avg_entropy: None,
            entropy_class: None,
            file_simhash: None,
            version: SyncSignature::CURRENT_VERSION,
        };

        let bytes = sig.serialize();
        assert!(!bytes.is_empty(), "serialize should produce non-empty output");

        let deserialized = SyncSignature::deserialize(&bytes)
            .expect("deserialize should succeed on valid data");

        assert_eq!(deserialized.size, 123456);
        assert_eq!(deserialized.mtime_sec, 1700000000);
        assert_eq!(deserialized.mtime_nsec, 999999999);
        assert_eq!(deserialized.hash.as_deref(), Some("abcdef0123456789"));
        assert_eq!(deserialized.merkle_root.as_deref(), Some("fedcba9876543210"));
        assert_eq!(deserialized.chunk_size, Some(65536));
        assert_eq!(deserialized.leaf_count, Some(42));
        assert_eq!(deserialized.version, SyncSignature::CURRENT_VERSION);
    }

    #[test]
    fn test_sidecar_sync_signature_v5_roundtrip_none_fields() {
        let sig = SyncSignature {
            size: 0,
            mtime_sec: 0,
            mtime_nsec: 0,
            hash: None,
            merkle_root: None,
            chunk_size: None,
            leaf_count: None,
            avg_entropy: None,
            entropy_class: None,
            file_simhash: None,
            version: SyncSignature::CURRENT_VERSION,
        };

        let bytes = sig.serialize();
        let deserialized = SyncSignature::deserialize(&bytes).expect("roundtrip with None fields");
        assert_eq!(deserialized.size, 0);
        assert!(deserialized.hash.is_none());
        assert!(deserialized.merkle_root.is_none());
        assert!(deserialized.chunk_size.is_none());
        assert!(deserialized.leaf_count.is_none());
    }

    #[test]
    fn test_sidecar_sync_signature_compute_on_file() {
        let dir = TempDir::new().unwrap();
        let file_path = dir.path().join("testfile.bin");
        {
            let mut f = File::create(&file_path).unwrap();
            f.write_all(&[0xAA; 4096]).unwrap();
        }

        let sig = SyncSignature::compute(&file_path).expect("compute should succeed");
        assert_eq!(sig.size, 4096);
        assert_ne!(sig.mtime_sec, 0, "mtime_sec should be non-zero for a real file");
        assert_eq!(sig.version, SyncSignature::CURRENT_VERSION);
    }

    #[test]
    fn test_sidecar_sync_signature_matches_equal() {
        let sig1 = SyncSignature {
            size: 1000,
            mtime_sec: 1700000000,
            mtime_nsec: 500,
            hash: Some("abc123".to_string()),
            merkle_root: None,
            chunk_size: None,
            leaf_count: None,
            avg_entropy: None,
            entropy_class: None,
            file_simhash: None,
            version: 5,
        };
        let sig2 = sig1.clone();
        assert!(sig1.matches(&sig2), "identical signatures should match");
    }

    #[test]
    fn test_sidecar_sync_signature_matches_different_size() {
        let sig1 = SyncSignature {
            size: 1000,
            mtime_sec: 1700000000,
            mtime_nsec: 500,
            hash: None,
            merkle_root: None,
            chunk_size: None,
            leaf_count: None,
            avg_entropy: None,
            entropy_class: None,
            file_simhash: None,
            version: 5,
        };
        let sig2 = SyncSignature {
            size: 2000,
            ..sig1.clone()
        };
        assert!(!sig1.matches(&sig2), "different sizes should not match");
    }

    #[test]
    fn test_sidecar_sync_signature_matches_merkle_root_priority() {
        // BUG-007: mtime is checked BEFORE merkle_root. A file modified in-place
        // (same size, different mtime) must NOT match even if merkle_root is identical.
        let sig1 = SyncSignature {
            size: 1000,
            mtime_sec: 100,
            mtime_nsec: 0,
            hash: None,
            merkle_root: Some("same_root".to_string()),
            chunk_size: None,
            leaf_count: None,
            avg_entropy: None,
            entropy_class: None,
            file_simhash: None,
            version: 5,
        };
        let sig2 = SyncSignature {
            mtime_sec: 200, // different mtime
            ..sig1.clone()
        };
        // Different mtime -> no match, even with same merkle_root (BUG-007 fix)
        assert!(!sig1.matches(&sig2), "different mtime must not match even with same merkle_root");

        // Same mtime + same merkle_root -> match
        let sig2b = SyncSignature {
            mtime_sec: 100, // same mtime
            ..sig1.clone()
        };
        assert!(sig1.matches(&sig2b), "same mtime + same merkle_root should match");

        let sig3 = SyncSignature {
            merkle_root: Some("different_root".to_string()),
            ..sig1.clone()
        };
        assert!(!sig1.matches(&sig3), "different merkle_root should not match");
    }

    #[test]
    fn test_sidecar_sync_signature_deserialize_empty() {
        let result = SyncSignature::deserialize(&[]);
        assert!(result.is_none(), "deserialize of empty slice should return None");
    }

    #[test]
    fn test_sidecar_sync_signature_deserialize_garbage() {
        let result = SyncSignature::deserialize(&[0xFF, 0x00, 0x42, 0x99]);
        assert!(result.is_none(), "deserialize of garbage should return None");
    }

    #[test]
    fn test_sidecar_set_get_sync_signature_roundtrip() {
        let dir = TempDir::new().unwrap();
        let file_path = dir.path().join("sigtest.txt");
        {
            let mut f = File::create(&file_path).unwrap();
            f.write_all(b"signature roundtrip test").unwrap();
        }

        let sig = SyncSignature {
            size: 23,
            mtime_sec: 1700000000,
            mtime_nsec: 123456789,
            hash: Some("deadbeef".to_string()),
            merkle_root: None,
            chunk_size: Some(4096),
            leaf_count: None,
            avg_entropy: None,
            entropy_class: None,
            file_simhash: None,
            version: SyncSignature::CURRENT_VERSION,
        };

        // set_sync_signature may fail if xattr is unsupported (e.g. tmpfs in some CI)
        // In that case it falls back to sidecar JSON, which should also work
        match set_sync_signature(&file_path, &sig) {
            Ok(()) => {}
            Err(e) => {
                eprintln!("set_sync_signature failed (expected on some filesystems): {}", e);
                return; // skip rest of test
            }
        }

        let retrieved = get_sync_signature(&file_path);
        let retrieved = match retrieved {
            Some(s) => s,
            None => {
                eprintln!("get_sync_signature returned None  --  skipping on this filesystem");
                return;
            }
        };

        assert_eq!(retrieved.size, sig.size);
        assert_eq!(retrieved.mtime_sec, sig.mtime_sec);
        assert_eq!(retrieved.mtime_nsec, sig.mtime_nsec);
        assert_eq!(retrieved.hash, sig.hash);
        assert_eq!(retrieved.chunk_size, sig.chunk_size);
        assert_eq!(retrieved.version, sig.version);
    }

    #[test]
    fn test_sidecar_set_get_metadata_generic_api() {
        let dir = TempDir::new().unwrap();
        let file_path = dir.path().join("meta_api_test.txt");
        {
            let mut f = File::create(&file_path).unwrap();
            f.write_all(b"metadata api test").unwrap();
        }

        let key = "user.foxing.test_key";
        let value = b"test_value_bytes";

        match set_metadata(&file_path, key, value) {
            Ok(()) => {}
            Err(e) => {
                eprintln!("set_metadata failed (expected on some filesystems): {}", e);
                return;
            }
        }

        let retrieved = get_metadata(&file_path, key);
        match retrieved {
            Some(v) => assert_eq!(v, value, "get_metadata should return the value we set"),
            None => {
                eprintln!("get_metadata returned None  --  skipping on this filesystem");
            }
        }
    }

    #[test]
    fn test_sidecar_sync_signature_version_field_is_5() {
        let dir = TempDir::new().unwrap();
        let file_path = dir.path().join("version_check.bin");
        {
            let mut f = File::create(&file_path).unwrap();
            f.write_all(&[0x55; 128]).unwrap();
        }

        let sig = SyncSignature::compute(&file_path).expect("compute should succeed");
        assert_eq!(SyncSignature::CURRENT_VERSION, 5, "CURRENT_VERSION constant should be 5");
        assert_eq!(sig.version, SyncSignature::CURRENT_VERSION,
            "computed signature version should equal CURRENT_VERSION");
    }

    #[test]
    fn test_sidecar_get_sidecar_path() {
        let p = Path::new("/some/dir/myfile.txt");
        let sp = get_sidecar_path(p).expect("should produce sidecar path");
        assert_eq!(sp, PathBuf::from("/some/dir/.myfile.txt.foxing_meta"));
    }

    #[test]
    fn test_sidecar_resolve_key_variants() {
        // user.foxing.X -> (trusted.foxing.X, user.foxing.X)
        let (trusted, user) = resolve_key_variants("user.foxing.sig");
        assert_eq!(trusted, "trusted.foxing.sig");
        assert_eq!(user, "user.foxing.sig");

        // trusted.foxing.X -> (trusted.foxing.X, user.foxing.X)
        let (trusted, user) = resolve_key_variants("trusted.foxing.dirty");
        assert_eq!(trusted, "trusted.foxing.dirty");
        assert_eq!(user, "user.foxing.dirty");

        // bare key -> both prefixed
        let (trusted, user) = resolve_key_variants("sig");
        assert_eq!(trusted, "trusted.foxing.sig");
        assert_eq!(user, "user.foxing.sig");
    }

    #[test]
    fn test_sync_signature_v3_migration() {
        let v3 = SyncSignatureV3 {
            size: 999,
            mtime_sec: 12345,
            mtime_nsec: 678,
            hash: Some("aabbcc".to_string()),
            merkle_root: None,
            chunk_size: Some(65536),
            version: 3,
        };
        let v3_bytes = bincode::serialize(&v3).expect("v3 serialize");

        let migrated = SyncSignature::deserialize_versioned(&v3_bytes)
            .expect("v3 migration should succeed");

        assert_eq!(migrated.size, 999);
        assert_eq!(migrated.mtime_sec, 12345);
        assert_eq!(migrated.hash.as_deref(), Some("aabbcc"));
        assert_eq!(migrated.leaf_count, None);
        assert_eq!(migrated.avg_entropy, None);
        assert_eq!(migrated.entropy_class, None);
        assert_eq!(migrated.file_simhash, None);
        assert_eq!(migrated.version, SyncSignature::CURRENT_VERSION);
    }

    #[test]
    fn test_sync_signature_v4_backward_compat() {
        let v4 = SyncSignatureV4 {
            size: 4096,
            mtime_sec: 1700000000,
            mtime_nsec: 500,
            hash: Some("deadbeef".to_string()),
            merkle_root: Some("cafebabe".to_string()),
            chunk_size: Some(65536),
            leaf_count: Some(10),
            version: 4,
        };
        let v4_bytes = bincode::serialize(&v4).expect("v4 serialize");

        let migrated = SyncSignature::deserialize_versioned(&v4_bytes)
            .expect("v4 backward compat migration should succeed");

        assert_eq!(migrated.size, 4096);
        assert_eq!(migrated.mtime_sec, 1700000000);
        assert_eq!(migrated.mtime_nsec, 500);
        assert_eq!(migrated.hash.as_deref(), Some("deadbeef"));
        assert_eq!(migrated.merkle_root.as_deref(), Some("cafebabe"));
        assert_eq!(migrated.chunk_size, Some(65536));
        assert_eq!(migrated.leaf_count, Some(10));
        assert_eq!(migrated.avg_entropy, None);
        assert_eq!(migrated.entropy_class, None);
        assert_eq!(migrated.file_simhash, None);
        assert_eq!(migrated.version, SyncSignature::CURRENT_VERSION);
    }

    #[test]
    fn test_sync_signature_v5_roundtrip_with_entropy_simhash() {
        let sig = SyncSignature {
            size: 1048576,
            mtime_sec: 1700000000,
            mtime_nsec: 42,
            hash: Some("abc123".to_string()),
            merkle_root: Some("def456".to_string()),
            chunk_size: Some(131072),
            leaf_count: Some(8),
            avg_entropy: Some(7.85),
            entropy_class: Some("high".to_string()),
            file_simhash: Some(-1234567890_i64),
            version: SyncSignature::CURRENT_VERSION,
        };

        let bytes = sig.serialize();
        let deserialized = SyncSignature::deserialize_versioned(&bytes)
            .expect("v5 roundtrip should succeed");

        assert_eq!(deserialized.size, 1048576);
        assert_eq!(deserialized.mtime_sec, 1700000000);
        assert_eq!(deserialized.hash.as_deref(), Some("abc123"));
        assert_eq!(deserialized.merkle_root.as_deref(), Some("def456"));
        assert_eq!(deserialized.chunk_size, Some(131072));
        assert_eq!(deserialized.leaf_count, Some(8));
        assert_eq!(deserialized.avg_entropy, Some(7.85));
        assert_eq!(deserialized.entropy_class.as_deref(), Some("high"));
        assert_eq!(deserialized.file_simhash, Some(-1234567890_i64));
        assert_eq!(deserialized.version, SyncSignature::CURRENT_VERSION);
    }

    #[test]
    fn test_sidecar_set_atomic_write() {
        let _guard = TEST_XATTR_MUTEX.lock().unwrap();
        let dir = TempDir::new().unwrap();
        let file_path = dir.path().join("atomic_test.txt");
        File::create(&file_path).unwrap();
        XATTR_UNSUPPORTED.store(true, std::sync::atomic::Ordering::Relaxed);

        set_metadata(&file_path, "user.foxing.test", b"hello").unwrap();

        let sp = get_sidecar_path(&file_path).unwrap();
        assert!(sp.exists(), ".foxing_meta should exist");
        let content = std::fs::read_to_string(&sp).unwrap();
        let _: std::collections::HashMap<String, String> = serde_json::from_str(&content)
            .expect("sidecar must be valid JSON");

        let mut tmp = sp.as_os_str().to_os_string();
        tmp.push(".tmp");
        assert!(!std::path::PathBuf::from(&tmp).exists(), "tmp file should not remain");

        XATTR_UNSUPPORTED.store(false, std::sync::atomic::Ordering::Relaxed);
    }

    #[test]
    fn test_sidecar_set_survives_concurrent_read() {
        let _guard = TEST_XATTR_MUTEX.lock().unwrap();
        let dir = TempDir::new().unwrap();
        let file_path = dir.path().join("concurrent.txt");
        File::create(&file_path).unwrap();
        XATTR_UNSUPPORTED.store(true, std::sync::atomic::Ordering::Relaxed);
        set_metadata(&file_path, "user.foxing.init", b"seed").unwrap();

        let sp = get_sidecar_path(&file_path).unwrap();
        let sp2 = sp.clone();
        let errors = std::sync::Arc::new(std::sync::atomic::AtomicUsize::new(0));
        let errors2 = errors.clone();

        let reader = std::thread::spawn(move || {
            for _ in 0..100 {
                if let Ok(content) = std::fs::read_to_string(&sp2)
                    && !content.is_empty()
                        && serde_json::from_str::<std::collections::HashMap<String, String>>(&content).is_err() {
                            errors2.fetch_add(1, std::sync::atomic::Ordering::Relaxed);
                        }
                std::thread::sleep(std::time::Duration::from_micros(100));
            }
        });

        let fp2 = file_path.clone();
        let writer = std::thread::spawn(move || {
            for i in 0..100 {
                let key = format!("user.foxing.key{}", i);
                let _ = set_metadata(&fp2, &key, b"value");
            }
        });

        writer.join().unwrap();
        reader.join().unwrap();
        assert_eq!(errors.load(std::sync::atomic::Ordering::Relaxed), 0,
            "reader should never see partial/invalid JSON");
        XATTR_UNSUPPORTED.store(false, std::sync::atomic::Ordering::Relaxed);
    }

    #[test]
    fn test_is_xattr_unsupported_classification() {
        let enotsup = io::Error::from_raw_os_error(libc::ENOTSUP);
        assert!(is_xattr_unsupported(&enotsup), "ENOTSUP should be xattr unsupported");

        let eopnotsupp = io::Error::from_raw_os_error(libc::EOPNOTSUPP);
        assert!(is_xattr_unsupported(&eopnotsupp), "EOPNOTSUPP should be xattr unsupported");

        let enosys = io::Error::from_raw_os_error(libc::ENOSYS);
        assert!(is_xattr_unsupported(&enosys), "ENOSYS should be xattr unsupported");

        let eperm = io::Error::from_raw_os_error(libc::EPERM);
        assert!(!is_xattr_unsupported(&eperm), "EPERM should NOT be xattr unsupported");

        let eio = io::Error::from_raw_os_error(libc::EIO);
        assert!(!is_xattr_unsupported(&eio), "EIO should NOT be xattr unsupported");

        let eacces = io::Error::from_raw_os_error(libc::EACCES);
        assert!(is_xattr_unsupported(&eacces), "EACCES should be xattr unsupported");

        let custom = io::Error::other("custom error");
        assert!(!is_xattr_unsupported(&custom), "custom error should NOT be xattr unsupported");
    }

    #[test]
    fn test_eperm_does_not_disable_xattr_globally() {
        let _guard = TEST_XATTR_MUTEX.lock().unwrap();
        XATTR_UNSUPPORTED.store(false, Ordering::Relaxed);
        FALLBACK_WARNED.store(false, Ordering::Relaxed);

        // After sidecar fallback fix: EPERM on /dev/null (device node where
        // both trusted.* and user.* xattr writes fail) now correctly propagates
        // as Err from try_xattr_set, triggering sidecar fallback via set_metadata.
        // This sets XATTR_UNSUPPORTED = true, which is the intended behavior —
        // any unrecoverable xattr error should trigger sidecar fallback.
        let dev_null = Path::new("/dev/null");
        let _result = set_metadata_batch(dev_null, &[("user.foxing.test", b"value" as &[u8])]);
        assert!(
            XATTR_UNSUPPORTED.load(Ordering::Relaxed),
            "EPERM on /dev/null should trigger sidecar fallback (XATTR_UNSUPPORTED=true)"
        );

        XATTR_UNSUPPORTED.store(false, Ordering::Relaxed);

        let _result2 = set_metadata(dev_null, "user.foxing.test", b"value");
        assert!(
            XATTR_UNSUPPORTED.load(Ordering::Relaxed),
            "EPERM on /dev/null in set_metadata should trigger sidecar fallback"
        );

        XATTR_UNSUPPORTED.store(false, Ordering::Relaxed);
    }

    #[test]
    fn test_sync_signature_merkle_root_matches_merkle_tree() {
        hashing::set_hashing_enabled(true);
        hashing::set_lite_threshold_kb(0);

        let dir = TempDir::new().unwrap();
        let file_path = dir.path().join("merkle_root_test.bin");
        let file_data = vec![0xABu8; 2 * 1024 * 1024];
        let mut f = std::fs::File::create(&file_path).unwrap();
        f.write_all(&file_data).unwrap();
        drop(f);

        let sig = SyncSignature::compute(&file_path)
            .expect("compute should succeed");
        let chunk_size = hashing::calculate_adaptive_chunk_size(2 * 1024 * 1024);
        let tree = hashing::MerkleTree::from_file(&file_path, chunk_size, hashing::ComputeMode::Blake3Only)
            .expect("MerkleTree::from_file should succeed");
        let expected_root = tree.root.to_hex().to_string();

        assert_eq!(
            sig.merkle_root.as_deref(),
            Some(expected_root.as_str()),
        );
    }

    #[test]
    fn test_hash_cid_returns_valid_cid() {
        let sig = SyncSignature {
            size: 100,
            mtime_sec: 1700000000,
            mtime_nsec: 0,
            hash: Some("af1349b9f5f9a1a6a0404dea36dcc9499bcb25c9adc112b7cc9a93cae41f3262".to_string()),
            merkle_root: None,
            chunk_size: None,
            leaf_count: None,
            avg_entropy: None,
            entropy_class: None,
            file_simhash: None,
            version: 5,
        };
        let cid = sig.hash_cid().expect("hash_cid should return Some for valid hex");
        assert!(cid.starts_with("b"), "CID should start with 'b' multibase prefix");
        let decoded_hex = crate::cid::cid_string_to_hex(&cid).unwrap();
        assert_eq!(decoded_hex, sig.hash.unwrap());
    }

    #[test]
    fn test_merkle_root_cid_returns_valid_cid() {
        let sig = SyncSignature {
            size: 100,
            mtime_sec: 1700000000,
            mtime_nsec: 0,
            hash: None,
            merkle_root: Some("1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef".to_string()),
            chunk_size: None,
            leaf_count: None,
            avg_entropy: None,
            entropy_class: None,
            file_simhash: None,
            version: 5,
        };
        let cid = sig.merkle_root_cid().expect("merkle_root_cid should return Some");
        assert!(cid.starts_with("b"));
    }

    #[test]
    fn test_hash_cid_returns_none_when_hash_is_none() {
        let sig = SyncSignature {
            size: 0,
            mtime_sec: 0,
            mtime_nsec: 0,
            hash: None,
            merkle_root: None,
            chunk_size: None,
            leaf_count: None,
            avg_entropy: None,
            entropy_class: None,
            file_simhash: None,
            version: 5,
        };
        assert!(sig.hash_cid().is_none());
    }

    #[test]
    fn test_hash_cid_returns_none_for_invalid_hex() {
        let sig = SyncSignature {
            size: 0,
            mtime_sec: 0,
            mtime_nsec: 0,
            hash: Some("not-valid-hex".to_string()),
            merkle_root: None,
            chunk_size: None,
            leaf_count: None,
            avg_entropy: None,
            entropy_class: None,
            file_simhash: None,
            version: 5,
        };
        assert!(sig.hash_cid().is_none());
    }
}