void_core/metadata/

manifest_tree.rs

//! Indexed tree manifest with O(log N) single-file lookup.
//!
//! `TreeManifest` is the single type for both building and reading manifests.
//! It stores file entries in an indexed CBOR format that supports binary search
//! without deserializing the entire file list.
//!
//! # Format
//!
//! ```text
//! CBOR map {
//!   "offsets":     [u32, ...]            // byte offsets into entries blob, sorted by path
//!   "entries":     <byte string>         // concatenated per-entry CBOR, sorted by path
//!   "shards":      [ShardReference, ...] // shard references (parsed eagerly)
//!   "paths_hash":  <32 bytes>            // SHA256(sorted paths joined by \0)
//!   "total_files": u64
//!   "total_bytes": u64
//! }
//! ```
//!
//! # Usage
//!
//! ```ignore
//! // Build (seal pipeline):
//! let manifest = TreeManifest::builder()
//!     .files(files)
//!     .shards(shards)
//!     .paths_hash(hash)
//!     .total_files(n)
//!     .total_bytes(b)
//!     .build()?;
//!
//! // Read (from decrypted bytes):
//! let manifest = TreeManifest::open(bytes)?;
//! let entry = manifest.lookup("src/main.rs")?;
//! ```

use super::types::{ManifestEntry, ShardReference};
// Note: types.rs still has the old TreeManifest struct. Once all consumers
// migrate to this module's TreeManifest, the old struct will be removed.
use crate::{Result, VoidError};

use serde::{Deserialize, Serialize};

/// A child entry in a directory listing derived from the manifest.
#[derive(Clone, Debug)]
pub struct DirChild {
    /// Entry name (just the filename/dirname, not full path).
    pub name: String,
    /// Whether this is a directory.
    pub is_dir: bool,
    /// File size in bytes (0 for directories).
    pub size: u64,
    /// Number of lines (0 for directories or unknown).
    pub lines: u32,
}

/// CBOR wire format for the indexed manifest.
#[derive(Serialize, Deserialize)]
struct Wire {
    offsets: Vec<u32>,
    /// Concatenated per-entry CBOR. Serialized as CBOR byte string for efficiency
    /// (avoids encoding each byte as a separate CBOR integer).
    #[serde(with = "cbor_bytes")]
    entries: Vec<u8>,
    shards: Vec<ShardReference>,
    paths_hash: [u8; 32],
    total_files: u64,
    total_bytes: u64,
}

/// Serde helper to serialize `Vec<u8>` as a CBOR byte string instead of an
/// array of integers. Equivalent to `serde_bytes` but without the dependency.
mod cbor_bytes {
    use serde::{Deserializer, Serializer};

    pub fn serialize<S: Serializer>(bytes: &Vec<u8>, s: S) -> Result<S::Ok, S::Error> {
        s.serialize_bytes(bytes)
    }

    pub fn deserialize<'de, D: Deserializer<'de>>(d: D) -> Result<Vec<u8>, D::Error> {
        struct ByteVisitor;
        impl<'de> serde::de::Visitor<'de> for ByteVisitor {
            type Value = Vec<u8>;
            fn expecting(&self, f: &mut std::fmt::Formatter) -> std::fmt::Result {
                f.write_str("byte string")
            }
            fn visit_bytes<E: serde::de::Error>(self, v: &[u8]) -> Result<Vec<u8>, E> {
                Ok(v.to_vec())
            }
            fn visit_byte_buf<E: serde::de::Error>(self, v: Vec<u8>) -> Result<Vec<u8>, E> {
                Ok(v)
            }
        }
        d.deserialize_byte_buf(ByteVisitor)
    }
}

/// Indexed tree manifest.
///
/// Holds file entries as raw CBOR bytes with a sorted offset table for
/// O(log N) single-file lookup. Metadata (shards, totals) is parsed eagerly.
///
/// Constructed via [`TreeManifestBuilder`] or [`TreeManifest::open`].
pub struct TreeManifest {
    /// Byte offsets into `entries` for each file, sorted by path.
    offsets: Vec<u32>,
    /// Concatenated CBOR-serialized `ManifestEntry` values, sorted by path.
    entries: Vec<u8>,
    /// Shard references (parsed eagerly).
    shards: Vec<ShardReference>,
    /// SHA256 of sorted paths joined by \0.
    paths_hash: [u8; 32],
    /// Total file count.
    total_files: u64,
    /// Total bytes across all files.
    total_bytes: u64,
    /// Serialized CBOR bytes (cached from build or open).
    serialized: Vec<u8>,
}

impl TreeManifest {
    /// Create a builder for constructing a new manifest.
    pub fn builder() -> TreeManifestBuilder {
        TreeManifestBuilder::default()
    }

    /// Open a manifest from decrypted CBOR bytes.
    ///
    /// Parses the outer structure (offsets, shards, totals) but does NOT
    /// parse individual file entries — those stay as raw bytes until
    /// accessed via `lookup()` or `iter()`.
    pub(crate) fn open(data: Vec<u8>) -> Result<Self> {
        let wire: Wire = ciborium::from_reader(&data[..])
            .map_err(|e| VoidError::Serialization(format!("tree manifest: {e}")))?;

        Ok(Self {
            offsets: wire.offsets,
            entries: wire.entries,
            shards: wire.shards,
            paths_hash: wire.paths_hash,
            total_files: wire.total_files,
            total_bytes: wire.total_bytes,
            serialized: data,
        })
    }

    /// Load and decrypt the TreeManifest from a commit.
    ///
    /// Extracts the manifest CID from the commit, fetches the encrypted blob
    /// from the store, decrypts it with the reader's content key, and parses it.
    ///
    /// Returns `None` if the commit has no `manifest_cid`.
    pub fn from_commit(
        store: &impl crate::store::ObjectStoreExt,
        commit: &crate::metadata::Commit,
        reader: &crate::crypto::CommitReader,
    ) -> Result<Option<Self>> {
        let manifest_cid = match &commit.manifest_cid {
            Some(cid) => cid,
            None => return Ok(None),
        };
        let mcid = crate::cid::VoidCid::from_bytes(manifest_cid.as_bytes())?;
        let encrypted: void_crypto::EncryptedManifest = store.get_blob(&mcid)?;
        let decrypted = encrypted.decrypt(reader.content_key().as_bytes())?;
        Self::open(decrypted).map(Some)
    }

    /// Returns the serialized CBOR bytes for encryption and storage.
    pub fn as_bytes(&self) -> &[u8] {
        &self.serialized
    }

    /// Look up a single file by path. O(log N).
    ///
    /// Binary searches the offset table, parsing one entry per probe to
    /// compare paths.
    pub fn lookup(&self, path: &str) -> Result<ManifestEntry> {
        let n = self.offsets.len();
        if n == 0 {
            return Err(VoidError::NotFound(path.to_string()));
        }

        let mut lo = 0usize;
        let mut hi = n;

        while lo < hi {
            let mid = lo + (hi - lo) / 2;
            let entry = self.parse_entry_at(mid)?;

            match entry.path.as_str().cmp(path) {
                std::cmp::Ordering::Equal => return Ok(entry),
                std::cmp::Ordering::Less => lo = mid + 1,
                std::cmp::Ordering::Greater => hi = mid,
            }
        }

        Err(VoidError::NotFound(path.to_string()))
    }

    /// Iterate all file entries in path-sorted order. O(N).
    pub fn iter(&self) -> ManifestIter<'_> {
        ManifestIter {
            manifest: self,
            index: 0,
        }
    }

    /// Returns the shard references.
    pub fn shards(&self) -> &[ShardReference] {
        &self.shards
    }

    /// Total number of files.
    pub fn total_files(&self) -> u64 {
        self.total_files
    }

    /// Total bytes across all files.
    pub fn total_bytes(&self) -> u64 {
        self.total_bytes
    }

    /// SHA256 hash of sorted paths.
    pub fn paths_hash(&self) -> &[u8; 32] {
        &self.paths_hash
    }

    /// Number of file entries.
    pub fn entry_count(&self) -> usize {
        self.offsets.len()
    }

    /// List the immediate children of a directory.
    ///
    /// Returns files and subdirectories directly under `path`.
    /// Use `""` for the root directory.
    ///
    /// Entries are sorted by path, so we can efficiently find the range of
    /// entries under a prefix and derive the directory listing.
    pub fn list_dir(&self, path: &str) -> Result<Vec<DirChild>> {
        let prefix = if path.is_empty() {
            String::new()
        } else {
            format!("{}/", path.trim_end_matches('/'))
        };
        let mut children: std::collections::BTreeMap<String, DirChild> = std::collections::BTreeMap::new();

        for entry_result in self.iter() {
            let entry = entry_result?;

            // Check if entry is under this directory
            let relative = if prefix.is_empty() {
                entry.path.as_str()
            } else if let Some(rest) = entry.path.strip_prefix(&prefix) {
                rest
            } else {
                continue;
            };

            // Get the immediate child name
            if let Some(slash_pos) = relative.find('/') {
                // Subdirectory — register as a dir child
                let dir_name = &relative[..slash_pos];
                children
                    .entry(dir_name.to_string())
                    .or_insert_with(|| DirChild {
                        name: dir_name.to_string(),
                        is_dir: true,
                        size: 0,
                        lines: 0,
                    });
            } else {
                // Direct file child
                children.insert(
                    relative.to_string(),
                    DirChild {
                        name: relative.to_string(),
                        is_dir: false,
                        size: entry.size,
                        lines: entry.lines,
                    },
                );
            }
        }

        if children.is_empty() && !path.is_empty() {
            // Check if this directory even exists by looking for any entry with the prefix
            let has_entries = self.iter().any(|r| {
                r.ok()
                    .map(|e| e.path.starts_with(&prefix))
                    .unwrap_or(false)
            });
            if !has_entries {
                return Err(VoidError::NotFound(format!("directory: {}", path)));
            }
        }

        Ok(children.into_values().collect())
    }

    /// Group file entries by shard index.
    ///
    /// Returns a vec indexed by shard position, where each element contains the
    /// `ManifestEntry` items stored in that shard. Callers can iterate shard-by-shard
    /// to decrypt each shard once and extract all files from it.
    pub fn entries_by_shard(&self) -> Result<Vec<Vec<ManifestEntry>>> {
        let mut groups: Vec<Vec<ManifestEntry>> = vec![Vec::new(); self.shards.len()];
        for entry_result in self.iter() {
            let entry = entry_result?;
            let idx = entry.shard_index as usize;
            if idx < groups.len() {
                groups[idx].push(entry);
            }
        }
        Ok(groups)
    }

    /// Parse the entry at the given index in the offset table.
    fn parse_entry_at(&self, index: usize) -> Result<ManifestEntry> {
        let start = self.offsets[index] as usize;
        let end = if index + 1 < self.offsets.len() {
            self.offsets[index + 1] as usize
        } else {
            self.entries.len()
        };

        if start > self.entries.len() || end > self.entries.len() || start > end {
            return Err(VoidError::Serialization(format!(
                "manifest entry {index}: offset {start}..{end} out of range (entries len {})",
                self.entries.len()
            )));
        }

        ciborium::from_reader(&self.entries[start..end])
            .map_err(|e| VoidError::Serialization(format!("manifest entry {index}: {e}")))
    }
}

/// Builder for constructing a [`TreeManifest`].
///
/// Sorts entries by path and serializes into the indexed CBOR format.
#[derive(Default)]
pub struct TreeManifestBuilder {
    files: Vec<ManifestEntry>,
    shards: Vec<ShardReference>,
    paths_hash: [u8; 32],
    total_files: u64,
    total_bytes: u64,
}

impl TreeManifestBuilder {
    /// Set the file entries. Will be sorted by path during `build()`.
    pub fn files(mut self, files: Vec<ManifestEntry>) -> Self {
        self.files = files;
        self
    }

    /// Set the shard references.
    pub fn shards(mut self, shards: Vec<ShardReference>) -> Self {
        self.shards = shards;
        self
    }

    /// Set the paths hash (SHA256 of sorted paths joined by \0).
    pub fn paths_hash(mut self, hash: [u8; 32]) -> Self {
        self.paths_hash = hash;
        self
    }

    /// Set the total file count.
    pub fn total_files(mut self, n: u64) -> Self {
        self.total_files = n;
        self
    }

    /// Set the total bytes across all files.
    pub fn total_bytes(mut self, n: u64) -> Self {
        self.total_bytes = n;
        self
    }

    /// Build the manifest, sorting entries and serializing to indexed CBOR.
    pub fn build(mut self) -> Result<TreeManifest> {
        // Sort entries by path for binary search
        self.files.sort_by(|a, b| a.path.cmp(&b.path));

        // Serialize each entry individually into a contiguous byte blob
        let mut entries_blob = Vec::new();
        let mut offsets = Vec::with_capacity(self.files.len());

        for entry in &self.files {
            offsets.push(entries_blob.len() as u32);
            ciborium::into_writer(entry, &mut entries_blob)
                .map_err(|e| VoidError::Serialization(format!("manifest entry: {e}")))?;
        }

        let wire = Wire {
            offsets: offsets.clone(),
            entries: entries_blob.clone(),
            shards: self.shards.clone(),
            paths_hash: self.paths_hash,
            total_files: self.total_files,
            total_bytes: self.total_bytes,
        };

        let mut serialized = Vec::new();
        ciborium::into_writer(&wire, &mut serialized)
            .map_err(|e| VoidError::Serialization(format!("tree manifest: {e}")))?;

        Ok(TreeManifest {
            offsets,
            entries: entries_blob,
            shards: self.shards,
            paths_hash: self.paths_hash,
            total_files: self.total_files,
            total_bytes: self.total_bytes,
            serialized,
        })
    }
}

/// Iterator over manifest entries in path-sorted order.
pub struct ManifestIter<'a> {
    manifest: &'a TreeManifest,
    index: usize,
}

impl<'a> Iterator for ManifestIter<'a> {
    type Item = Result<ManifestEntry>;

    fn next(&mut self) -> Option<Self::Item> {
        if self.index >= self.manifest.offsets.len() {
            return None;
        }
        let result = self.manifest.parse_entry_at(self.index);
        self.index += 1;
        Some(result)
    }

    fn size_hint(&self) -> (usize, Option<usize>) {
        let remaining = self.manifest.offsets.len() - self.index;
        (remaining, Some(remaining))
    }
}

impl<'a> ExactSizeIterator for ManifestIter<'a> {}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::ContentHash;
    use void_crypto::ShardCid;

    fn make_entry(path: &str, shard_index: u32, offset: u64, size: u64) -> ManifestEntry {
        ManifestEntry {
            path: path.to_string(),
            content_hash: ContentHash::ZERO,
            size,
            mode: 0o644,
            shard_index,
            offset,
            length: size,
            lines: 0,
            shard_count: 1,
        }
    }

    fn make_shard_ref(id: u8) -> ShardReference {
        ShardReference {
            cid: ShardCid::from_bytes(vec![id]),
            size_compressed: 100,
            size_decompressed: 200,
            wrapped_key: None,
        }
    }

    /// Helper: build a manifest via the builder.
    fn build_manifest(
        files: Vec<ManifestEntry>,
        shards: Vec<ShardReference>,
    ) -> TreeManifest {
        let total_files = files.len() as u64;
        let total_bytes = files.iter().map(|f| f.size).sum();
        TreeManifest::builder()
            .files(files)
            .shards(shards)
            .paths_hash([0u8; 32])
            .total_files(total_files)
            .total_bytes(total_bytes)
            .build()
            .unwrap()
    }

    // -- Round-trip: build → as_bytes → open → lookup --

    #[test]
    fn round_trip_single_file() {
        let manifest = build_manifest(
            vec![make_entry("hello.txt", 0, 0, 42)],
            vec![make_shard_ref(1)],
        );

        let reopened = TreeManifest::open(manifest.as_bytes().to_vec()).unwrap();

        assert_eq!(reopened.entry_count(), 1);
        assert_eq!(reopened.total_files(), 1);
        assert_eq!(reopened.total_bytes(), 42);
        assert_eq!(reopened.shards().len(), 1);

        let entry = reopened.lookup("hello.txt").unwrap();
        assert_eq!(entry.path, "hello.txt");
        assert_eq!(entry.size, 42);
        assert_eq!(entry.shard_index, 0);
    }

    #[test]
    fn round_trip_multiple_files() {
        let files = vec![
            make_entry("src/main.rs", 0, 0, 500),
            make_entry("Cargo.toml", 0, 500, 200),
            make_entry("README.md", 1, 0, 100),
            make_entry("src/lib.rs", 0, 700, 300),
            make_entry("tests/test.rs", 1, 100, 150),
        ];
        let manifest = build_manifest(files.clone(), vec![make_shard_ref(1), make_shard_ref(2)]);

        let reopened = TreeManifest::open(manifest.as_bytes().to_vec()).unwrap();
        assert_eq!(reopened.entry_count(), 5);

        for file in &files {
            let entry = reopened.lookup(&file.path).unwrap();
            assert_eq!(entry.path, file.path);
            assert_eq!(entry.size, file.size);
            assert_eq!(entry.shard_index, file.shard_index);
            assert_eq!(entry.offset, file.offset);
        }
    }

    #[test]
    fn round_trip_preserves_all_fields() {
        let original = ManifestEntry {
            path: "deep/nested/path/file.rs".to_string(),
            content_hash: ContentHash([0xAB; 32]),
            size: 9999,
            mode: 0o755,
            shard_index: 3,
            offset: 1234,
            length: 9999,
            lines: 42,
            shard_count: 1,
        };

        let manifest = build_manifest(vec![original.clone()], vec![make_shard_ref(1)]);
        let reopened = TreeManifest::open(manifest.as_bytes().to_vec()).unwrap();

        let got = reopened.lookup("deep/nested/path/file.rs").unwrap();
        assert_eq!(got.path, original.path);
        assert_eq!(got.content_hash, original.content_hash);
        assert_eq!(got.size, original.size);
        assert_eq!(got.mode, original.mode);
        assert_eq!(got.shard_index, original.shard_index);
        assert_eq!(got.offset, original.offset);
        assert_eq!(got.length, original.length);
        assert_eq!(got.lines, original.lines);
    }

    // -- Builder sorts unsorted input --

    #[test]
    fn builder_sorts_unsorted_input() {
        let manifest = build_manifest(
            vec![
                make_entry("c.txt", 0, 0, 10),
                make_entry("a.txt", 0, 10, 20),
                make_entry("b.txt", 0, 30, 30),
            ],
            vec![make_shard_ref(1)],
        );

        assert_eq!(manifest.lookup("a.txt").unwrap().size, 20);
        assert_eq!(manifest.lookup("b.txt").unwrap().size, 30);
        assert_eq!(manifest.lookup("c.txt").unwrap().size, 10);
    }

    // -- Iterator --

    #[test]
    fn iter_returns_sorted_order() {
        let manifest = build_manifest(
            vec![
                make_entry("z.txt", 0, 0, 10),
                make_entry("a.txt", 0, 10, 20),
                make_entry("m.txt", 0, 30, 30),
            ],
            vec![make_shard_ref(1)],
        );

        let paths: Vec<String> = manifest.iter().map(|r| r.unwrap().path).collect();
        assert_eq!(paths, vec!["a.txt", "m.txt", "z.txt"]);
    }

    #[test]
    fn iter_exact_size() {
        let manifest = build_manifest(
            vec![
                make_entry("a.txt", 0, 0, 10),
                make_entry("b.txt", 0, 10, 20),
                make_entry("c.txt", 0, 30, 30),
            ],
            vec![make_shard_ref(1)],
        );

        assert_eq!(manifest.iter().len(), 3);
    }

    // -- Lookup miss --

    #[test]
    fn lookup_nonexistent_returns_not_found() {
        let manifest = build_manifest(
            vec![make_entry("a.txt", 0, 0, 10)],
            vec![make_shard_ref(1)],
        );

        let err = manifest.lookup("nonexistent.txt").unwrap_err();
        assert!(matches!(err, VoidError::NotFound(_)));
    }

    // -- Empty manifest --

    #[test]
    fn empty_manifest() {
        let manifest = build_manifest(vec![], vec![]);

        assert_eq!(manifest.entry_count(), 0);
        assert_eq!(manifest.total_files(), 0);
        assert_eq!(manifest.total_bytes(), 0);
        assert_eq!(manifest.shards().len(), 0);
        assert_eq!(manifest.iter().count(), 0);

        let err = manifest.lookup("anything").unwrap_err();
        assert!(matches!(err, VoidError::NotFound(_)));
    }

    // -- Binary search boundary --

    #[test]
    fn lookup_first_entry() {
        let manifest = build_manifest(
            vec![
                make_entry("aaa", 0, 0, 10),
                make_entry("bbb", 0, 10, 20),
                make_entry("ccc", 0, 30, 30),
            ],
            vec![make_shard_ref(1)],
        );
        assert_eq!(manifest.lookup("aaa").unwrap().size, 10);
    }

    #[test]
    fn lookup_last_entry() {
        let manifest = build_manifest(
            vec![
                make_entry("aaa", 0, 0, 10),
                make_entry("bbb", 0, 10, 20),
                make_entry("ccc", 0, 30, 30),
            ],
            vec![make_shard_ref(1)],
        );
        assert_eq!(manifest.lookup("ccc").unwrap().size, 30);
    }

    #[test]
    fn lookup_middle_entry() {
        let manifest = build_manifest(
            vec![
                make_entry("aaa", 0, 0, 10),
                make_entry("bbb", 0, 10, 20),
                make_entry("ccc", 0, 30, 30),
            ],
            vec![make_shard_ref(1)],
        );
        assert_eq!(manifest.lookup("bbb").unwrap().size, 20);
    }

    // -- Scale --

    #[test]
    fn lookup_100_files() {
        let files: Vec<ManifestEntry> = (0..100)
            .map(|i| make_entry(&format!("file_{:04}.txt", i), i % 4, (i as u64) * 100, 100))
            .collect();

        let manifest = build_manifest(
            files.clone(),
            vec![
                make_shard_ref(1),
                make_shard_ref(2),
                make_shard_ref(3),
                make_shard_ref(4),
            ],
        );

        assert_eq!(manifest.entry_count(), 100);

        for file in &files {
            let entry = manifest.lookup(&file.path).unwrap();
            assert_eq!(entry.path, file.path);
            assert_eq!(entry.shard_index, file.shard_index);
        }

        assert!(manifest.lookup("file_9999.txt").is_err());
    }

    // -- Deep paths --

    #[test]
    fn lookup_deep_nested_paths() {
        let manifest = build_manifest(
            vec![
                make_entry("a/b/c/d/e/f/g.txt", 0, 0, 10),
                make_entry("a/b/c/d/e/f/h.txt", 0, 10, 20),
                make_entry("x/y/z.txt", 0, 30, 30),
            ],
            vec![make_shard_ref(1)],
        );

        assert_eq!(manifest.lookup("a/b/c/d/e/f/g.txt").unwrap().size, 10);
        assert_eq!(manifest.lookup("a/b/c/d/e/f/h.txt").unwrap().size, 20);
        assert_eq!(manifest.lookup("x/y/z.txt").unwrap().size, 30);
    }

    // -- Metadata preservation --

    #[test]
    fn preserves_shards_and_metadata() {
        let shards = vec![
            ShardReference {
                cid: ShardCid::from_bytes(vec![1, 2, 3]),
                size_compressed: 500,
                size_decompressed: 1000,
                wrapped_key: None,
            },
            ShardReference {
                cid: ShardCid::from_bytes(vec![4, 5, 6]),
                size_compressed: 300,
                size_decompressed: 600,
                wrapped_key: Some(void_crypto::WrappedKey::from_bytes(vec![7, 8, 9])),
            },
        ];

        let manifest = TreeManifest::builder()
            .files(vec![make_entry("test.txt", 0, 0, 100)])
            .shards(shards)
            .paths_hash([0xAB; 32])
            .total_files(1)
            .total_bytes(100)
            .build()
            .unwrap();

        assert_eq!(manifest.paths_hash(), &[0xAB; 32]);
        assert_eq!(manifest.total_files(), 1);
        assert_eq!(manifest.total_bytes(), 100);
        assert_eq!(manifest.shards().len(), 2);
        assert_eq!(manifest.shards()[0].size_compressed, 500);
        assert_eq!(manifest.shards()[1].size_compressed, 300);
        assert!(manifest.shards()[1].wrapped_key.is_some());
    }

    // -- entries_by_shard --

    #[test]
    fn entries_by_shard_groups_correctly() {
        let manifest = build_manifest(
            vec![
                make_entry("a.txt", 0, 0, 10),
                make_entry("b.txt", 1, 0, 20),
                make_entry("c.txt", 0, 10, 30),
                make_entry("d.txt", 2, 0, 40),
                make_entry("e.txt", 1, 20, 50),
            ],
            vec![make_shard_ref(1), make_shard_ref(2), make_shard_ref(3)],
        );

        let groups = manifest.entries_by_shard().unwrap();
        assert_eq!(groups.len(), 3);

        // Shard 0: a.txt, c.txt
        assert_eq!(groups[0].len(), 2);
        assert_eq!(groups[0][0].path, "a.txt");
        assert_eq!(groups[0][1].path, "c.txt");

        // Shard 1: b.txt, e.txt
        assert_eq!(groups[1].len(), 2);
        assert_eq!(groups[1][0].path, "b.txt");
        assert_eq!(groups[1][1].path, "e.txt");

        // Shard 2: d.txt
        assert_eq!(groups[2].len(), 1);
        assert_eq!(groups[2][0].path, "d.txt");
    }

    #[test]
    fn entries_by_shard_empty_manifest() {
        let manifest = build_manifest(vec![], vec![]);
        let groups = manifest.entries_by_shard().unwrap();
        assert_eq!(groups.len(), 0);
    }

    // -- Corrupt data --

    #[test]
    fn open_corrupt_data_returns_error() {
        let result = TreeManifest::open(vec![0xFF, 0xFF, 0xFF]);
        assert!(result.is_err());
    }

    #[test]
    fn open_empty_data_returns_error() {
        let result = TreeManifest::open(vec![]);
        assert!(result.is_err());
    }

    // -- as_bytes round-trip --

    #[test]
    fn as_bytes_produces_valid_manifest() {
        let manifest = build_manifest(
            vec![
                make_entry("foo.txt", 0, 0, 50),
                make_entry("bar.txt", 1, 0, 75),
            ],
            vec![make_shard_ref(1), make_shard_ref(2)],
        );

        // Simulate encrypt → store → load → decrypt cycle
        let bytes = manifest.as_bytes().to_vec();
        let reopened = TreeManifest::open(bytes).unwrap();

        assert_eq!(reopened.entry_count(), 2);
        assert_eq!(reopened.lookup("foo.txt").unwrap().size, 50);
        assert_eq!(reopened.lookup("bar.txt").unwrap().size, 75);
        assert_eq!(reopened.shards().len(), 2);
    }
}