aerovault 0.6.3

//! AEROVAULT3 sync vault operations engine.
//!
//! A faithful, byte-for-byte port of the AeroFTP application's AEROVAULT3 vault
//! operations (`src-tauri/src/aerovault_v3.rs`), minus the Tauri command layer,
//! async, telemetry (`VaultReport`), and Error Correction (rev. 4). The on-disk
//! content pipeline, manifest shape, header layout, packing, chunking, and
//! extract path-traversal safety are preserved exactly so a container produced
//! here cross-opens with one produced by the app (T5 contract).
//!
//! Error Correction (parity sidecars, scrub/repair, shard recompute on seal) is
//! intentionally out of scope; it is wired in T6. Every place the app branched
//! on EC is marked with a `// T6:` comment.

// SPDX-License-Identifier: GPL-3.0-only

use std::borrow::Cow;
use std::collections::{BTreeMap, HashSet};
use std::io::Read;
use std::path::{Path, PathBuf};

use zeroize::{Zeroize, Zeroizing};

use super::block::{build_file_bytes, write_container};
use super::chunking::{chunk_ranges_with, keyed_chunk_id, CdcBounds, StreamingChunker};
use super::constants::{
    CDC_MAX, CRYPT_ALGORITHM_ENCRYPTED, CRYPT_ALGORITHM_NONE, DATA_OFFSET, DEFAULT_ZSTD_LEVEL,
    FLAG_PLAINTEXT_CONTENT, HEADER_SIZE, HKDF_CHUNK_ID, INCOMPRESSIBLE_PROBE_LEVEL,
    INCOMPRESSIBLE_PROBE_MAX_SAMPLE, INCOMPRESSIBLE_PROBE_SAMPLE, INCOMPRESSIBLE_RATIO_PCT,
    MAC_SIZE, MAGIC, MAX_BLOCK_SIZE, MAX_EXTENSION_DIR_SIZE, MAX_MANIFEST_SIZE,
    MAX_PLAINTEXT_BLOCK_SIZE, MIN_PASSWORD_LEN, PACK_SMALL_FILE_THRESHOLD, PACK_TARGET,
    SUPPORTED_WRAPPER_HEADER_VERSION, VERSION,
};
use super::format::{aerovz_mac_key, derive_keks, VaultHeaderV3};
use super::manifest::{
    block_aad, decrypt_manifest, empty_manifest, empty_manifest_plaintext, manifest_cdc_bounds,
    manifest_is_plaintext, manifest_zstd_level, next_block_index, now_iso,
    parse_manifest_plaintext, AlgorithmSpec, ChunkRecordV3, ExtensionEntryV3, ManifestEntryV3,
    VaultManifestV3, WrapperManifest,
};
use crate::aerocrypt::{
    decrypt_with_aad, derive_base_kek, encrypt_with_aad, hkdf_expand, random_array, unwrap_key,
    wrap_key, KEY_SIZE, SALT_SIZE, WRAPPED_KEY_SIZE,
};

/// Which cryptographic lane a container uses.
///
/// The encrypted lane is the standard password-protected `.aerovault`. The
/// plaintext lane is the unencrypted `.aerovz` archive (#7): the same
/// pack/chunk/compress/Error-Correction pipeline minus the encrypt stage —
/// content blocks and the manifest are stored in the clear, there is no
/// password, and the header carries an integrity-only public MAC. It is
/// integrity + recovery, NOT confidentiality; the data is readable by anyone.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum VaultLane {
    /// Password-protected, AES-256-GCM-SIV content + encrypted manifest.
    Encrypted,
    /// Unencrypted `.aerovz`: compressed + EC, no encryption, no password.
    Plaintext,
}

/// Options for creating an AEROVAULT3 container. Without an Error-Correction
/// placement this produces a plain rev. 3 container; setting one (see
/// [`VaultV3::create_with_error_correction`]) opts into rev. 4.
pub struct CreateOptionsV3 {
    /// Destination path for the `.aerovault` / `.aerovz` container.
    pub path: PathBuf,
    /// Master password (>= [`MIN_PASSWORD_LEN`] characters). Ignored — and may be
    /// empty — when `lane` is [`VaultLane::Plaintext`].
    pub password: String,
    /// zstd compression level recorded on the `compression` wrapper.
    pub zstd_level: i32,
    /// Optional explicit CDC bounds. When absent, the historical level-driven
    /// defaults are used (`level >= 19` selects the archive profile).
    pub cdc_bounds: Option<CdcBounds>,
    /// Cryptographic lane. [`VaultLane::Encrypted`] by default.
    pub lane: VaultLane,
    /// rev. 4 Error-Correction placement. `None` keeps the container plain rev. 3.
    pub(super) error_correction: Option<super::ec::RecoveryPlacement>,
    /// QR-style EC overhead percentage; only meaningful when
    /// `error_correction` is `Some`. Defaults to the original K=10/P=2 grid.
    pub(super) error_correction_pct: u32,
}

impl CreateOptionsV3 {
    /// New encrypted-lane options with the default ([`DEFAULT_ZSTD_LEVEL`])
    /// compression level.
    pub fn new(path: impl Into<PathBuf>, password: impl Into<String>) -> Self {
        Self {
            path: path.into(),
            password: password.into(),
            zstd_level: DEFAULT_ZSTD_LEVEL,
            cdc_bounds: None,
            lane: VaultLane::Encrypted,
            error_correction: None,
            error_correction_pct: crate::error_correction::ERROR_CORRECTION_DEFAULT_PCT,
        }
    }

    /// New plaintext-lane (`.aerovz`) options: no password, content + manifest
    /// stored unencrypted. Compression and (optional) Error Correction still
    /// apply. See [`VaultLane::Plaintext`] for the security caveat.
    pub fn new_plaintext(path: impl Into<PathBuf>) -> Self {
        Self {
            path: path.into(),
            password: String::new(),
            zstd_level: DEFAULT_ZSTD_LEVEL,
            cdc_bounds: None,
            lane: VaultLane::Plaintext,
            error_correction: None,
            error_correction_pct: crate::error_correction::ERROR_CORRECTION_DEFAULT_PCT,
        }
    }

    /// Override the zstd compression level.
    pub fn with_zstd_level(mut self, level: i32) -> Self {
        self.zstd_level = level;
        self
    }

    /// Override content-defined chunking bounds independently from the zstd
    /// level, so high compression levels can keep fine-grained deduplication.
    pub fn with_cdc_bounds(mut self, bounds: CdcBounds) -> Self {
        self.cdc_bounds = Some(bounds);
        self
    }
}

/// An unlocked, fully in-memory AEROVAULT3 container.
///
/// Holds the decrypted master and MAC keys plus the whole data section in RAM.
/// Drop it when done: the [`Drop`] impl zeroizes the key material.
pub struct OpenVaultV3 {
    pub(super) path: PathBuf,
    pub(super) header: VaultHeaderV3,
    pub(super) opened_file_len: u64,
    pub(super) opened_header_mac: [u8; MAC_SIZE],
    pub(super) master_key: [u8; KEY_SIZE],
    pub(super) mac_key: [u8; KEY_SIZE],
    pub(super) manifest: VaultManifestV3,
    pub(super) extensions: Vec<ExtensionEntryV3>,
    pub(super) data: Vec<u8>,
    /// Set when `open_vault` had to rebuild a corrupted encrypted manifest from
    /// Error-Correction parity (rev. 4). `repair` persists the healed region.
    pub(super) manifest_repaired_on_open: bool,
    /// Set when `open_vault` had to rebuild a corrupted header from the detached
    /// sidecar's header parity (rev. 4). `repair` persists the healed region.
    pub(super) header_repaired_on_open: bool,
    /// Optional embedder telemetry sink (see [`super::telemetry`]). `None` by
    /// default, so the content pipeline emits nothing and produces identical
    /// bytes; attach one with [`OpenVaultV3::set_telemetry_sink`].
    pub(super) telemetry: Option<Box<dyn super::telemetry::VaultTelemetrySink + Send>>,
}

impl std::fmt::Debug for OpenVaultV3 {
    /// Manual `Debug` (the optional telemetry sink is not `Debug`); never prints
    /// key material.
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("OpenVaultV3")
            .field("path", &self.path)
            .field("opened_file_len", &self.opened_file_len)
            .field("entries", &self.manifest.entries.len())
            .field("chunks", &self.manifest.chunks.len())
            .field("data_len", &self.data.len())
            .field("manifest_repaired_on_open", &self.manifest_repaired_on_open)
            .field("header_repaired_on_open", &self.header_repaired_on_open)
            .field("telemetry", &self.telemetry.is_some())
            .finish_non_exhaustive()
    }
}

impl Drop for OpenVaultV3 {
    /// Wipe the long-lived key material when the open vault is dropped.
    /// Ephemeral KEKs and plaintext/pack buffers are zeroized at every use
    /// site; the master/MAC keys live for the whole operation, so without this
    /// they would linger in freed memory after every mutation.
    fn drop(&mut self) {
        self.master_key.zeroize();
        self.mac_key.zeroize();
    }
}

impl OpenVaultV3 {
    /// The container's filesystem path.
    pub fn path(&self) -> &Path {
        &self.path
    }

    /// Attach an embedder telemetry sink to receive content-pipeline events for
    /// the operations run on this open vault (see [`super::telemetry`]). Without
    /// one the pipeline emits nothing; attaching one never changes the bytes
    /// written.
    pub fn set_telemetry_sink(
        &mut self,
        sink: Box<dyn super::telemetry::VaultTelemetrySink + Send>,
    ) {
        self.telemetry = Some(sink);
    }

    /// Run `f` against the attached telemetry sink, if any. A no-op when no sink
    /// is attached.
    pub(super) fn emit(
        &mut self,
        f: impl FnOnce(&mut (dyn super::telemetry::VaultTelemetrySink + Send)),
    ) {
        if let Some(sink) = self.telemetry.as_deref_mut() {
            f(sink);
        }
    }
}

/// One entry as surfaced by [`list`].
#[derive(Debug, Clone)]
pub struct EntryInfo {
    /// Canonical vault-relative path (uses `/` separators).
    pub path: String,
    /// Logical file size in bytes (0 for directories).
    pub size: u64,
    /// Whether this entry is a directory.
    pub is_dir: bool,
    /// Last-modified timestamp in the app's `%Y-%m-%dT%H:%M:%SZ` form.
    pub modified: String,
    /// Number of logical content chunks this entry references (0 for
    /// directories). Logical, not deduplicated: two entries sharing a chunk
    /// each count it.
    pub chunk_count: usize,
}

/// Aggregate view of an open vault, sufficient for an embedder to build a
/// JSON/info summary without reaching into the (private) manifest. Mirrors the
/// totals the app historically derived from the manifest.
#[derive(Debug, Clone)]
pub struct VaultSummaryV3 {
    /// On-disk format version ([`VERSION`]).
    pub version: u8,
    /// Number of file (non-directory) entries.
    pub file_count: usize,
    /// Number of distinct physical content chunks stored.
    pub chunk_count: usize,
    /// Deduplicated chunks: logical chunk references minus physical chunks.
    pub dedup_chunks: usize,
    /// Effective zstd compression level recorded in the manifest.
    pub compression_level: i32,
    /// Ordered wrapper chain (`"packing:small-file-batching v1"`, ...) derived
    /// from the manifest, for the technical receipt.
    pub algorithms: Vec<String>,
    /// Every entry (files and directories) with its logical chunk count.
    pub entries: Vec<EntryInfo>,
}

/// Header-only info available without a password.
#[derive(Debug, Clone)]
pub struct PeekInfo {
    /// On-disk format version (always [`VERSION`] for a valid file).
    pub version: u8,
    /// Total on-disk file length.
    pub file_len: u64,
    /// Length of the data section, per the (unverified) header.
    pub data_len: u64,
    /// Length of the encrypted manifest, per the (unverified) header.
    pub manifest_len: u64,
}

/// Namespace handle for the AEROVAULT3 sync API.
///
/// Mirrors the legacy v2 `Vault::create/open/is_vault/peek` shape, but every
/// mutating op takes a `&mut OpenVaultV3` and persists with [`save_open_vault`]
/// internally, exactly like the app's command layer drove the sync core.
pub struct VaultV3;

impl VaultV3 {
    /// Create a new empty container at `opts.path`. A plain rev. 3 container
    /// unless `opts` carries an Error-Correction placement (rev. 4).
    pub fn create(opts: &CreateOptionsV3) -> Result<(), String> {
        create_empty_vault(
            &opts.path,
            &opts.password,
            opts.zstd_level,
            opts.cdc_bounds,
            opts.lane,
            opts.error_correction,
            opts.error_correction_pct,
        )
    }

    /// Create a new empty rev. 4 container with Reed-Solomon Error Correction.
    ///
    /// `placement` selects where parity lives: `Embedded` (non-critical
    /// in-container extension, recomputed on every seal), `Detached` (a sibling
    /// `.aerocorrect` sidecar, container stays byte-identical to a plain vault),
    /// or `Both`. The embedded extension is non-critical so rev. 3 readers can
    /// still open + extract (#276). `pct` is the QR-style overhead level
    /// (clamped to `[MIN_PCT, MAX_PCT]`); the default reproduces the original
    /// K=10/P=2 (~20%) grid.
    pub fn create_with_error_correction(
        opts: &CreateOptionsV3,
        placement: super::ec::RecoveryPlacement,
        pct: u32,
    ) -> Result<(), String> {
        create_empty_vault(
            &opts.path,
            &opts.password,
            opts.zstd_level,
            opts.cdc_bounds,
            opts.lane,
            Some(placement),
            pct,
        )
    }

    /// Write a detached `.aerocorrect` recovery file for an existing vault
    /// without rewriting the container ("add Error Correction later"). Defaults
    /// to `<vault>.aerocorrect`; pass `out` to override.
    pub fn export_parity(
        vault_path: &Path,
        password: &str,
        out: Option<&Path>,
    ) -> Result<super::ec::ExportParityResult, String> {
        super::ec::export_parity(vault_path, password, out)
    }

    /// Drop the embedded Error-Correction extension on the next seal. Refuses
    /// unless a detached sidecar already exists or `force` is set, so a vault is
    /// never silently left with zero recovery.
    pub fn strip_parity(
        vault_path: &Path,
        password: &str,
        force: bool,
    ) -> Result<super::ec::StripParityResult, String> {
        super::ec::strip_parity(vault_path, password, force)
    }

    /// Verify every stored content block against its manifest `cipher_hash`,
    /// returning the damaged chunks (read-only).
    pub fn scrub(vault: &OpenVaultV3) -> Vec<super::ec::DamagedChunk> {
        super::ec::scrub_vault(vault)
    }

    /// Repair damaged blocks from Error-Correction parity (explicit `parity`
    /// path, else detached sidecar, else embedded extension). All-or-nothing:
    /// every reconstructed block is re-verified against the manifest
    /// `cipher_hash` and persisted only if all pass; on `dry_run` nothing is
    /// written. Returns `(repaired_block_count, parity_source)`.
    pub fn repair(
        vault: &mut OpenVaultV3,
        dry_run: bool,
        parity: Option<&Path>,
    ) -> Result<(usize, super::ec::ParitySource), String> {
        super::ec::repair_vault(vault, dry_run, parity)
    }

    /// True if `path` carries the embedded Error-Correction extension (no
    /// password needed; reads only the header + plaintext extension directory).
    pub fn has_error_correction(path: &Path) -> Result<bool, String> {
        super::ec::has_error_correction(path)
    }

    /// Pre-flight: which Error-Correction parity source a [`repair`](Self::repair)
    /// would draw from (`explicit` path wins, else the detached sidecar, else the
    /// embedded extension). An explicit path that is unreadable/malformed is a
    /// hard error; an absent default source returns
    /// [`ParitySource::None`](super::ec::ParitySource). Read-only; discards the
    /// resolved parity bytes.
    pub fn resolve_parity_source(
        vault: &OpenVaultV3,
        explicit: Option<&Path>,
    ) -> Result<super::ec::ParitySource, String> {
        super::ec::resolve_parity_source(vault, explicit).map(|(_, source)| source)
    }

    /// Recovery surfaces available for a vault without the password.
    pub fn recovery_status(path: &Path) -> Result<super::ec::RecoveryStatus, String> {
        super::ec::recovery_status(path)
    }

    /// True if `path` begins with the AEROVAULT3 magic + version.
    pub fn is_vault_v3(path: impl AsRef<Path>) -> bool {
        let Ok(mut file) = std::fs::File::open(path.as_ref()) else {
            return false;
        };
        let mut buf = [0u8; 11];
        if file.read_exact(&mut buf).is_err() {
            return false;
        }
        &buf[..10] == MAGIC && buf[10] == VERSION
    }

    /// Open and unlock a container with `password`. A plaintext (`.aerovz`)
    /// container is opened regardless of `password` (it has none); pass `""`.
    pub fn open(path: impl Into<PathBuf>, password: &str) -> Result<OpenVaultV3, String> {
        open_vault(path, password)
    }

    /// Open a plaintext (`.aerovz`) container — convenience for `open(path, "")`.
    /// Errors if the container is an encrypted `.aerovault`.
    pub fn open_plaintext(path: impl Into<PathBuf>) -> Result<OpenVaultV3, String> {
        let vault = open_vault(path, "")?;
        if vault.header.flags & FLAG_PLAINTEXT_CONTENT == 0 {
            return Err("Not a plaintext .aerovz archive (it is encrypted)".to_string());
        }
        Ok(vault)
    }

    /// Read header-only info without a password.
    pub fn peek(path: impl AsRef<Path>) -> Result<PeekInfo, String> {
        let mut file =
            std::fs::File::open(path.as_ref()).map_err(|e| format!("Open vault: {e}"))?;
        let file_len = file
            .metadata()
            .map_err(|e| format!("Vault metadata: {e}"))?
            .len();
        let mut header_bytes = [0u8; HEADER_SIZE];
        file.read_exact(&mut header_bytes)
            .map_err(|e| format!("Read header: {e}"))?;
        let header = VaultHeaderV3::from_bytes(&header_bytes)?;
        Ok(PeekInfo {
            version: VERSION,
            file_len,
            data_len: header.data_len,
            manifest_len: header.manifest_len,
        })
    }

    /// List every entry (files and directories) in the manifest.
    pub fn list(vault: &OpenVaultV3) -> Vec<EntryInfo> {
        vault
            .manifest
            .entries
            .iter()
            .map(|entry| EntryInfo {
                path: entry.path.clone(),
                size: entry.size,
                is_dir: entry.is_dir,
                modified: entry.modified.clone(),
                chunk_count: entry.chunks.len(),
            })
            .collect()
    }

    /// Aggregate stats + entry list for an open vault, mirroring the totals the
    /// app historically derived from the manifest (file count, physical/dedup
    /// chunk counts, compression level). Lets an embedder build an info/JSON
    /// view without manifest access.
    pub fn summary(vault: &OpenVaultV3) -> VaultSummaryV3 {
        let entries = Self::list(vault);
        let file_count = entries.iter().filter(|e| !e.is_dir).count();
        let logical_chunks: usize = entries.iter().map(|e| e.chunk_count).sum();
        let chunk_count = vault.manifest.chunks.len();
        VaultSummaryV3 {
            version: VERSION,
            file_count,
            chunk_count,
            dedup_chunks: logical_chunks.saturating_sub(chunk_count),
            compression_level: super::manifest::manifest_zstd_level(&vault.manifest),
            algorithms: algorithm_chain(&vault.manifest),
            entries,
        }
    }

    /// Add files into the vault at the given vault-relative paths, then persist.
    pub fn add_files(vault: &mut OpenVaultV3, sources: &[(PathBuf, String)]) -> Result<(), String> {
        append_sources_batched(vault, sources)?;
        save_open_vault(vault)
    }

    /// Add `sources` into directory `target_dir`, joining each source's file
    /// name under it, then persist. `target_dir` empty means the vault root.
    pub fn add_files_to_dir(
        vault: &mut OpenVaultV3,
        sources: &[PathBuf],
        target_dir: &str,
    ) -> Result<(), String> {
        let target = target_dir.trim().trim_matches('/');
        let mut mapped: Vec<(PathBuf, String)> = Vec::with_capacity(sources.len());
        for source in sources {
            let name = safe_entry_name(source)?;
            let entry_path = if target.is_empty() {
                name
            } else {
                let target = normalize_vault_relative_path(target)?;
                join_vault_path(&target, &name)
            };
            mapped.push((source.clone(), entry_path));
        }
        if !target.is_empty() {
            create_directory_in_manifest(&mut vault.manifest, target)?;
        }
        append_sources_batched(vault, &mapped)?;
        save_open_vault(vault)
    }

    /// Create a directory (and any missing parents) inside the vault, persist.
    /// Returns `true` when the leaf directory was newly created, `false` when it
    /// already existed.
    pub fn create_directory(vault: &mut OpenVaultV3, dir_path: &str) -> Result<bool, String> {
        let created = create_directory_in_manifest(&mut vault.manifest, dir_path)?;
        save_open_vault(vault)?;
        Ok(created)
    }

    /// Recursively add `source_dir` (depth <= 100, <= 500000 entries) under
    /// `target_prefix` (or the root when `None`), then persist.
    pub fn add_directory(
        vault: &mut OpenVaultV3,
        source_dir: &Path,
        target_prefix: Option<&str>,
    ) -> Result<(usize, usize), String> {
        add_directory_into(vault, source_dir, target_prefix)
    }

    /// Delete a single entry (file or empty directory), then persist.
    pub fn delete_entry(vault: &mut OpenVaultV3, entry_name: &str) -> Result<usize, String> {
        let removed = delete_entries_from_manifest(
            vault,
            std::slice::from_ref(&entry_name.to_string()),
            false,
        )?;
        save_open_vault(vault)?;
        Ok(removed)
    }

    /// Delete entries; with `recursive` a directory drops its whole subtree.
    pub fn delete_entries(
        vault: &mut OpenVaultV3,
        entry_names: &[String],
        recursive: bool,
    ) -> Result<usize, String> {
        let removed = delete_entries_from_manifest(vault, entry_names, recursive)?;
        save_open_vault(vault)?;
        Ok(removed)
    }

    /// Move (or rename across directories) an entry/subtree, then persist.
    pub fn move_entry(vault: &mut OpenVaultV3, from: &str, to: &str) -> Result<(), String> {
        move_entry_in_manifest(vault, from, to)?;
        save_open_vault(vault)
    }

    /// Rename an entry within its parent directory, then persist.
    pub fn rename_entry(
        vault: &mut OpenVaultV3,
        current_name: &str,
        new_name: &str,
    ) -> Result<(), String> {
        let current = normalize_vault_relative_path(current_name)?;
        let leaf = normalize_leaf_name(new_name)?;
        let target = match path_parent(&current) {
            Some(parent) => join_vault_path(parent, &leaf),
            None => leaf,
        };
        move_entry_in_manifest(vault, &current, &target)?;
        save_open_vault(vault)
    }

    /// Copy an entry/subtree (reusing the same content chunks), then persist.
    pub fn copy_entry(vault: &mut OpenVaultV3, from: &str, to: &str) -> Result<(), String> {
        copy_entry_in_manifest(vault, from, to)?;
        save_open_vault(vault)
    }

    /// Re-wrap the keys under a new password (new salt + KEKs), then persist.
    pub fn change_password(vault: &mut OpenVaultV3, new_password: &str) -> Result<(), String> {
        change_password_in_place(vault, new_password)?;
        save_open_vault(vault)
    }

    /// Extract one entry (file or directory subtree) to `dest`.
    pub fn extract_entry(
        vault: &OpenVaultV3,
        entry_name: &str,
        dest: &Path,
    ) -> Result<PathBuf, String> {
        extract_entry(vault, entry_name, dest)
    }

    /// Extract the entire vault tree under `dest`, returning files written.
    pub fn extract_all(vault: &OpenVaultV3, dest: &Path) -> Result<u64, String> {
        extract_all_entries(vault, dest)
    }

    /// `extract_all` with a `(bytes_done, bytes_total)` progress callback invoked
    /// after each file is written (#5: progress for extract, GUI + CLI). The
    /// embedder turns this into a live bar; `extract_all` is the no-op-callback
    /// shorthand.
    pub fn extract_all_with_progress(
        vault: &OpenVaultV3,
        dest: &Path,
        progress: &mut dyn FnMut(u64, u64),
    ) -> Result<u64, String> {
        extract_all_entries_with_progress(vault, dest, progress)
    }
}

// --- Internal port of the app sync core ---------------------------------------

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
enum EntryKindV3 {
    File,
    Directory,
}

/// Ordered wrapper chain for the technical receipt, derived from the manifest
/// wrappers (`"packing:small-file-batching v1"`, `"chunking:gear-cdc v1"`, ...).
fn algorithm_chain(manifest: &VaultManifestV3) -> Vec<String> {
    let w = &manifest.wrappers;
    let line = |name: &str, s: &AlgorithmSpec| {
        format!("{name}:{} v{}", s.algorithm_id, s.algorithm_version)
    };
    vec![
        line("packing", &w.packing),
        line("chunking", &w.chunking),
        line("chunk_id", &w.chunk_id),
        line("compression", &w.compression),
        line("crypt", &w.crypt),
        line("cipher_hash", &w.cipher_hash),
    ]
}

fn validate_vault_path(path: &str) -> Result<(), String> {
    if path.is_empty()
        || path.starts_with('/')
        || path.starts_with('\\')
        || path.contains('\0')
        || path.contains('\\')
        || path.split('/').any(|part| part == "..")
        || path.as_bytes().get(1) == Some(&b':')
    {
        return Err(format!("Invalid AeroVault path: {path}"));
    }
    Ok(())
}

fn safe_entry_name(path: &Path) -> Result<String, String> {
    let name = path
        .file_name()
        .ok_or_else(|| format!("Invalid file name: {}", path.display()))?
        .to_string_lossy()
        .to_string();
    validate_vault_path(&name)?;
    Ok(name)
}

fn normalize_vault_relative_path(path: &str) -> Result<String, String> {
    let trimmed = path.trim().trim_matches('/');
    if trimmed.is_empty() {
        return Err("Invalid AeroVault path: empty".to_string());
    }
    validate_vault_path(trimmed)?;
    if trimmed
        .split('/')
        .any(|part| part.is_empty() || part == ".")
    {
        return Err(format!("Invalid AeroVault path: {trimmed}"));
    }
    Ok(trimmed.to_string())
}

fn normalize_leaf_name(name: &str) -> Result<String, String> {
    let trimmed = name.trim();
    if trimmed.is_empty()
        || trimmed.contains('/')
        || trimmed.contains('\\')
        || trimmed.contains("..")
        || trimmed.contains('\0')
    {
        return Err("Invalid AeroVault name".to_string());
    }
    Ok(trimmed.to_string())
}

fn validate_manifest_paths(manifest: &VaultManifestV3) -> Result<(), String> {
    let mut seen = HashSet::new();
    for entry in &manifest.entries {
        let normalized = normalize_vault_relative_path(&entry.path)?;
        if normalized != entry.path {
            return Err(format!(
                "Invalid non-canonical AeroVault path: {}",
                entry.path
            ));
        }
        if !seen.insert(entry.path.as_str()) {
            return Err(format!(
                "Duplicate AeroVault path in manifest: {}",
                entry.path
            ));
        }
    }
    Ok(())
}

/// Audit M4 hardening: validate the extension directory at open time. The header
/// MAC authenticates the directory's offset/length but NOT its JSON bytes, so a
/// file-level attacker could forge the entry list within the MAC-fixed window. Bound
/// the blast radius to a clean refusal (it is otherwise DoS-only, since every recovery
/// re-verifies reconstructed bytes against authenticated material): reject duplicate
/// extension ids and any entry whose payload slice escapes the authenticated
/// extension-payload region. Full authentication of the directory bytes is a version-2
/// header change (breaks v1 cross-compat) and is tracked as a follow-up.
fn validate_extension_dir(
    extensions: &[ExtensionEntryV3],
    extension_payload_len: u64,
) -> Result<(), String> {
    let mut seen = HashSet::new();
    for ext in extensions {
        // A rev. 3 reader rejects any critical extension; the rev. 4 EC layers are
        // deliberately non-critical so this stays a forward-compat skip.
        if ext.critical {
            return Err(format!(
                "Unsupported critical AeroVault v3 extension: {}",
                ext.extension_id
            ));
        }
        if !seen.insert(ext.extension_id.as_str()) {
            return Err(format!(
                "Duplicate AeroVault v3 extension id: {}",
                ext.extension_id
            ));
        }
        let end = ext
            .offset
            .checked_add(ext.length)
            .ok_or_else(|| format!("Extension {} payload range overflow", ext.extension_id))?;
        if end > extension_payload_len {
            return Err(format!(
                "Extension {} payload slice [{}..{}] escapes the {extension_payload_len}-byte extension payload",
                ext.extension_id, ext.offset, end
            ));
        }
    }
    Ok(())
}

fn join_vault_path(parent: &str, name: &str) -> String {
    if parent.is_empty() {
        name.to_string()
    } else {
        format!("{parent}/{name}")
    }
}

fn path_parent(path: &str) -> Option<&str> {
    path.rsplit_once('/').map(|(parent, _)| parent)
}

fn path_basename(path: &str) -> &str {
    path.rsplit('/').next().unwrap_or(path)
}

fn is_descendant_of(path: &str, parent: &str) -> bool {
    path.len() > parent.len()
        && path.starts_with(parent)
        && path.as_bytes().get(parent.len()) == Some(&b'/')
}

fn entry_kind(manifest: &VaultManifestV3, path: &str) -> Option<EntryKindV3> {
    if let Some(entry) = manifest.entries.iter().find(|entry| entry.path == path) {
        return Some(if entry.is_dir {
            EntryKindV3::Directory
        } else {
            EntryKindV3::File
        });
    }
    if manifest
        .entries
        .iter()
        .any(|entry| is_descendant_of(&entry.path, path))
    {
        return Some(EntryKindV3::Directory);
    }
    None
}

fn ensure_no_file_ancestor(manifest: &VaultManifestV3, path: &str) -> Result<(), String> {
    let mut current = path;
    while let Some(parent) = path_parent(current) {
        if manifest
            .entries
            .iter()
            .any(|entry| entry.path == parent && !entry.is_dir)
        {
            return Err(format!("Parent path is a file: {parent}"));
        }
        current = parent;
    }
    Ok(())
}

fn sort_entries(manifest: &mut VaultManifestV3) {
    manifest.entries.sort_by(|a, b| a.path.cmp(&b.path));
}

fn create_directory_in_manifest(
    manifest: &mut VaultManifestV3,
    dir_path: &str,
) -> Result<bool, String> {
    let dir_path = normalize_vault_relative_path(dir_path)?;
    ensure_no_file_ancestor(manifest, &dir_path)?;

    if let Some(existing) = manifest.entries.iter().find(|entry| entry.path == dir_path) {
        return if existing.is_dir {
            Ok(false)
        } else {
            Err(format!("A file already exists at: {dir_path}"))
        };
    }

    if let Some(parent) = path_parent(&dir_path) {
        create_directory_in_manifest(manifest, parent)?;
    }

    manifest.entries.push(ManifestEntryV3 {
        path: dir_path,
        size: 0,
        modified: now_iso(),
        is_dir: true,
        chunks: Vec::new(),
        pack_offset: None,
    });
    sort_entries(manifest);
    manifest.modified = now_iso();
    Ok(true)
}

fn ensure_parent_directories(manifest: &mut VaultManifestV3, path: &str) -> Result<(), String> {
    if let Some(parent) = path_parent(path) {
        create_directory_in_manifest(manifest, parent)?;
    }
    Ok(())
}

/// Cheap incompressibility probe (#10-B): trial-compress representative chunk
/// samples at a fast level and report whether they failed to shrink past the threshold.
/// `true` => store the chunk raw and skip the full, possibly expensive, pass.
/// A probe error is non-fatal: fall back to the normal compression path.
fn probe_incompressible(chunk: &[u8]) -> bool {
    if chunk.is_empty() {
        return false;
    }
    let sample = representative_probe_sample(chunk);
    match zstd::stream::encode_all(sample.as_ref(), INCOMPRESSIBLE_PROBE_LEVEL) {
        // Incompressible when the probe output is >= RATIO% of the sample.
        Ok(probed) => probed.len() as u64 * 100 >= sample.len() as u64 * INCOMPRESSIBLE_RATIO_PCT,
        Err(_) => false,
    }
}

fn representative_probe_sample(chunk: &[u8]) -> Cow<'_, [u8]> {
    if chunk.len() <= INCOMPRESSIBLE_PROBE_MAX_SAMPLE {
        return Cow::Borrowed(chunk);
    }

    let window_len = INCOMPRESSIBLE_PROBE_SAMPLE.min(chunk.len());
    let window_count = (INCOMPRESSIBLE_PROBE_MAX_SAMPLE / window_len).max(1);
    let mut sample = Vec::with_capacity(window_count * window_len);
    let max_start = chunk.len() - window_len;

    for idx in 0..window_count {
        let start = if window_count == 1 {
            0
        } else {
            idx * max_start / (window_count - 1)
        };
        sample.extend_from_slice(&chunk[start..start + window_len]);
    }

    Cow::Owned(sample)
}

/// Compress + encrypt + dedup one already-delimited plaintext chunk; returns the
/// chunk id. Shared by the per-file and pack paths. Incompressible chunks are
/// stored raw (still encrypted) so high zstd levels don't burn CPU re-packing
/// already-compressed data; the manifest's `stored_raw` flag drives decode.
/// (Telemetry dropped.)
fn ingest_chunk(
    vault: &mut OpenVaultV3,
    chunk: &[u8],
    chunk_key: &[u8; KEY_SIZE],
    level: i32,
) -> Result<String, String> {
    let chunk_id = keyed_chunk_id(chunk_key, chunk);
    if !vault.manifest.chunks.contains_key(&chunk_id) {
        // Decide the stored representation: skip the full compress when the
        // cheap probe says incompressible, and also fall back to raw if the
        // full pass somehow failed to shrink the chunk (never store a block
        // larger than the plaintext for zero gain).
        let mut stored_raw = probe_incompressible(chunk);
        let mut compressed = if stored_raw {
            Vec::new()
        } else {
            let out = zstd::stream::encode_all(chunk, level)
                .map_err(|e| format!("zstd compress failed: {e}"))?;
            if out.len() >= chunk.len() {
                stored_raw = true;
                Vec::new()
            } else {
                out
            }
        };
        let payload: &[u8] = if stored_raw { chunk } else { &compressed };
        let block_index = next_block_index(&vault.manifest);
        let aad = block_aad(block_index, &chunk_id);
        // Plaintext (`.aerovz`) lane: store the compressed-or-raw payload
        // directly, skipping AES-256-GCM-SIV. `cipher_hash` is taken over the
        // stored bytes either way (ciphertext on the encrypted lane, the payload
        // here), so the decode-side integrity check is unchanged.
        let encrypted = if manifest_is_plaintext(&vault.manifest) {
            payload.to_vec()
        } else {
            encrypt_with_aad(&vault.master_key, payload, &aad)?
        };
        let (pt, cz, enc) = (
            chunk.len() as u64,
            payload.len() as u64,
            encrypted.len() as u64,
        );
        compressed.zeroize();
        let cipher_hash = blake3::hash(&encrypted).to_hex().to_string();
        let data_offset = vault.data.len() as u64;
        vault
            .data
            .extend_from_slice(&(encrypted.len() as u64).to_le_bytes());
        vault.data.extend_from_slice(&encrypted);
        vault.manifest.chunks.insert(
            chunk_id.clone(),
            ChunkRecordV3 {
                id: chunk_id.clone(),
                block_index,
                data_offset,
                block_len: enc,
                plaintext_len: pt,
                compressed_len: cz,
                cipher_hash,
                stored_raw,
            },
        );
        vault.emit(|s| s.on_chunk(true, pt, cz, enc));
    } else {
        vault.emit(|s| s.on_chunk(false, chunk.len() as u64, 0, 0));
    }
    Ok(chunk_id)
}

fn append_file_at(vault: &mut OpenVaultV3, source: &Path, entry_path: &str) -> Result<(), String> {
    let entry_path = normalize_vault_relative_path(entry_path)?;
    if !source.is_file() {
        return Err(format!("Not a regular file: {}", source.display()));
    }
    ensure_parent_directories(&mut vault.manifest, &entry_path)?;

    if let Some(kind) = entry_kind(&vault.manifest, &entry_path) {
        match kind {
            EntryKindV3::Directory => {
                return Err(format!(
                    "Destination already exists as directory: {entry_path}"
                ));
            }
            EntryKindV3::File => {
                vault
                    .manifest
                    .entries
                    .retain(|entry| entry.path != entry_path);
            }
        }
    }

    let chunk_key = hkdf_expand::<KEY_SIZE>(&vault.master_key, HKDF_CHUNK_ID)?;
    let level = manifest_zstd_level(&vault.manifest);
    let bounds = manifest_cdc_bounds(&vault.manifest)?;
    let mut entry_chunks = Vec::new();

    // Stream the source through the bounded-buffer chunker so peak memory is one
    // CDC window (`bounds.max` + a refill), not the whole file. The streamed
    // boundaries are byte-identical to `chunk_ranges_with` over the same bytes
    // (pinned by `streaming_chunker_matches_whole_buffer`), so chunk ids and the
    // on-disk container are unchanged. `size` is accumulated from the streamed
    // chunks, so it equals the bytes actually ingested (as `plaintext.len()` did).
    let file =
        std::fs::File::open(source).map_err(|e| format!("Read {}: {e}", source.display()))?;
    let mut chunker = StreamingChunker::new(file, bounds);
    let mut size = 0u64;
    while let Some(mut chunk) = chunker
        .next_chunk()
        .map_err(|e| format!("Read {}: {e}", source.display()))?
    {
        size += chunk.len() as u64;
        let chunk_id = ingest_chunk(vault, &chunk, &chunk_key, level)?;
        chunk.zeroize();
        entry_chunks.push(chunk_id);
    }

    vault.manifest.entries.push(ManifestEntryV3 {
        path: entry_path,
        size,
        modified: now_iso(),
        is_dir: false,
        chunks: entry_chunks,
        pack_offset: None,
    });
    vault.emit(|s| s.on_file(false));
    sort_entries(&mut vault.manifest);
    vault.manifest.modified = now_iso();
    Ok(())
}

/// Chunk one assembled pack, ingest its chunks, then map every member file to
/// the chunks covering its byte span plus the first-byte offset inside the first
/// covering chunk. The manifest is the index; the pack carries no per-file
/// framing.
fn flush_pack(
    vault: &mut OpenVaultV3,
    pack: &[u8],
    members: &[(String, u64, u64)],
    chunk_key: &[u8; KEY_SIZE],
    level: i32,
    bounds: &CdcBounds,
) -> Result<(), String> {
    if members.is_empty() {
        return Ok(());
    }
    vault.emit(|s| s.on_pack());

    let ranges = chunk_ranges_with(pack, bounds);
    let mut chunks: Vec<(String, u64, u64)> = Vec::with_capacity(ranges.len());
    for (start, end) in &ranges {
        let id = ingest_chunk(vault, &pack[*start..*end], chunk_key, level)?;
        chunks.push((id, *start as u64, *end as u64));
    }
    let (member_count, pack_len, chunk_count) = (members.len(), pack.len(), chunks.len());
    vault.emit(|s| {
        s.step(&format!(
            "pack: {member_count} file(s), {pack_len} B -> chunk+compress+encrypt {chunk_count} chunk(s)"
        ))
    });

    for (entry_path, fstart, flen) in members {
        let fstart_v = *fstart;
        let flen_v = *flen;
        let fend = fstart_v + flen_v;

        ensure_parent_directories(&mut vault.manifest, entry_path)?;
        if let Some(kind) = entry_kind(&vault.manifest, entry_path) {
            match kind {
                EntryKindV3::Directory => {
                    return Err(format!(
                        "Destination already exists as directory: {entry_path}"
                    ));
                }
                EntryKindV3::File => {
                    vault.manifest.entries.retain(|e| &e.path != entry_path);
                }
            }
        }

        let (covering, pack_offset) = if flen_v == 0 {
            (Vec::new(), Some(0u64))
        } else {
            let mut cov = Vec::new();
            let mut first: Option<u64> = None;
            for (id, cstart, cend) in &chunks {
                if *cstart < fend && fstart_v < *cend {
                    if first.is_none() {
                        first = Some(*cstart);
                    }
                    cov.push(id.clone());
                }
            }
            let fc = first.ok_or_else(|| format!("Packing failed to cover file: {entry_path}"))?;
            (cov, Some(fstart_v - fc))
        };

        vault.manifest.entries.push(ManifestEntryV3 {
            path: entry_path.clone(),
            size: flen_v,
            modified: now_iso(),
            is_dir: false,
            chunks: covering,
            pack_offset,
        });
        vault.emit(|s| s.on_file(true));
    }
    Ok(())
}

/// Add a set of sources, batching sub-threshold files into shared packs before
/// chunking and routing large files through the per-file path. Deterministic
/// path ordering keeps packs (and therefore dedup) stable across identical adds.
fn append_sources_batched(
    vault: &mut OpenVaultV3,
    sources: &[(PathBuf, String)],
) -> Result<(), String> {
    let chunk_key = hkdf_expand::<KEY_SIZE>(&vault.master_key, HKDF_CHUNK_ID)?;
    let level = manifest_zstd_level(&vault.manifest);
    let bounds = manifest_cdc_bounds(&vault.manifest)?;
    let (cdc_min, cdc_avg, cdc_max) = (bounds.min, bounds.avg, bounds.max);
    vault.emit(|s| s.set_cdc(cdc_min, cdc_avg, cdc_max));
    let source_count = sources.len();
    vault.emit(|s| s.step(&format!("scan: {source_count} source(s) to add")));

    let mut small_meta: Vec<(PathBuf, String)> = Vec::new();
    let mut large_count = 0usize;
    for (source, entry_path) in sources {
        let entry_path = normalize_vault_relative_path(entry_path)?;
        if !source.is_file() {
            return Err(format!("Not a regular file: {}", source.display()));
        }
        let len = std::fs::metadata(source)
            .map_err(|e| format!("Stat {}: {e}", source.display()))?
            .len();
        if (len as usize) < PACK_SMALL_FILE_THRESHOLD {
            small_meta.push((source.clone(), entry_path));
        } else {
            large_count += 1;
            append_file_at(vault, source, &entry_path)?;
        }
    }
    let small_count = small_meta.len();
    vault.emit(|s| {
        s.step(&format!(
            "partition: {small_count} small (< {PACK_SMALL_FILE_THRESHOLD} B, batched) / {large_count} large (per-file)"
        ))
    });

    if !small_meta.is_empty() {
        small_meta.sort_by(|a, b| a.1.cmp(&b.1));

        let mut pack: Vec<u8> = Vec::new();
        let mut members: Vec<(String, u64, u64)> = Vec::new();
        for (source, entry_path) in &small_meta {
            let mut data =
                std::fs::read(source).map_err(|e| format!("Read {}: {e}", source.display()))?;
            let start = pack.len() as u64;
            pack.extend_from_slice(&data);
            let len = data.len() as u64;
            data.zeroize();
            members.push((entry_path.clone(), start, len));
            if pack.len() >= PACK_TARGET {
                flush_pack(vault, &pack, &members, &chunk_key, level, &bounds)?;
                pack.zeroize();
                pack.clear();
                members.clear();
            }
        }
        if !members.is_empty() {
            flush_pack(vault, &pack, &members, &chunk_key, level, &bounds)?;
            pack.zeroize();
        }
    }

    sort_entries(&mut vault.manifest);
    vault.manifest.modified = now_iso();
    Ok(())
}

/// Garbage-collect orphaned chunks: keep only chunk records still referenced by
/// a live entry, rewrite the data section in block-index order, and remap each
/// surviving record's `data_offset`.
fn compact_live_chunks(vault: &mut OpenVaultV3) -> Result<(), String> {
    let live_chunk_ids: HashSet<String> = vault
        .manifest
        .entries
        .iter()
        .flat_map(|entry| entry.chunks.iter().cloned())
        .collect();

    if live_chunk_ids.is_empty() {
        vault.manifest.chunks.clear();
        vault.data.clear();
        return Ok(());
    }

    let mut ordered_ids: Vec<(u64, String)> = vault
        .manifest
        .chunks
        .iter()
        .filter(|(id, _)| live_chunk_ids.contains(*id))
        .map(|(id, record)| (record.block_index, id.clone()))
        .collect();
    ordered_ids.sort_by_key(|(index, _)| *index);

    let mut new_data = Vec::new();
    let mut new_chunks = BTreeMap::new();

    for (_, chunk_id) in ordered_ids {
        let mut record = vault
            .manifest
            .chunks
            .get(&chunk_id)
            .cloned()
            .ok_or_else(|| format!("Missing chunk record: {chunk_id}"))?;
        let len_start = record.data_offset as usize;
        let len_end = len_start
            .checked_add(8)
            .ok_or_else(|| "Chunk length offset overflow".to_string())?;
        if len_end > vault.data.len() {
            return Err("Chunk length is outside data section".to_string());
        }
        let block_len = u64::from_le_bytes(
            vault.data[len_start..len_end]
                .try_into()
                .expect("slice length"),
        );
        if block_len != record.block_len || block_len > MAX_BLOCK_SIZE {
            return Err("Chunk length metadata mismatch".to_string());
        }
        let block_start = len_end;
        let block_end = block_start
            .checked_add(block_len as usize)
            .ok_or_else(|| "Chunk block offset overflow".to_string())?;
        if block_end > vault.data.len() {
            return Err("Chunk block is outside data section".to_string());
        }

        record.data_offset = new_data.len() as u64;
        new_data.extend_from_slice(&block_len.to_le_bytes());
        new_data.extend_from_slice(&vault.data[block_start..block_end]);
        new_chunks.insert(chunk_id, record);
    }

    vault.data = new_data;
    vault.manifest.chunks = new_chunks;
    Ok(())
}

fn delete_entries_from_manifest(
    vault: &mut OpenVaultV3,
    entry_names: &[String],
    recursive: bool,
) -> Result<usize, String> {
    let mut removed = 0usize;

    for entry_name in entry_names {
        let entry_name = normalize_vault_relative_path(entry_name)?;
        let kind = entry_kind(&vault.manifest, &entry_name)
            .ok_or_else(|| format!("Entry not found: {entry_name}"))?;

        match kind {
            EntryKindV3::File => {
                let before = vault.manifest.entries.len();
                vault
                    .manifest
                    .entries
                    .retain(|entry| entry.path != entry_name);
                removed += before.saturating_sub(vault.manifest.entries.len());
            }
            EntryKindV3::Directory => {
                let has_children = vault
                    .manifest
                    .entries
                    .iter()
                    .any(|entry| is_descendant_of(&entry.path, &entry_name));
                if has_children && !recursive {
                    return Err(format!("Directory is not empty: {entry_name}"));
                }
                let before = vault.manifest.entries.len();
                vault.manifest.entries.retain(|entry| {
                    entry.path != entry_name && !is_descendant_of(&entry.path, &entry_name)
                });
                removed += before.saturating_sub(vault.manifest.entries.len());
            }
        }
    }

    if removed > 0 {
        compact_live_chunks(vault)?;
        sort_entries(&mut vault.manifest);
        vault.manifest.modified = now_iso();
    }

    Ok(removed)
}

fn remap_entry_path(path: &str, from: &str, to: &str) -> String {
    if path == from {
        to.to_string()
    } else {
        format!("{}/{}", to, &path[from.len() + 1..])
    }
}

fn prepare_relocation(
    manifest: &VaultManifestV3,
    from: &str,
    to: &str,
) -> Result<EntryKindV3, String> {
    let from = normalize_vault_relative_path(from)?;
    let to = normalize_vault_relative_path(to)?;
    let kind = entry_kind(manifest, &from).ok_or_else(|| format!("Entry not found: {from}"))?;

    if from == to {
        return Ok(kind);
    }
    if kind == EntryKindV3::Directory && is_descendant_of(&to, &from) {
        return Err("Cannot move a directory inside itself".to_string());
    }
    if entry_kind(manifest, &to).is_some() {
        return Err(format!("Destination already exists: {to}"));
    }
    ensure_no_file_ancestor(manifest, &to)?;
    Ok(kind)
}

fn move_entry_in_manifest(vault: &mut OpenVaultV3, from: &str, to: &str) -> Result<(), String> {
    let from = normalize_vault_relative_path(from)?;
    let to = normalize_vault_relative_path(to)?;
    let _ = prepare_relocation(&vault.manifest, &from, &to)?;
    if from == to {
        return Ok(());
    }
    ensure_parent_directories(&mut vault.manifest, &to)?;
    for entry in &mut vault.manifest.entries {
        if entry.path == from || is_descendant_of(&entry.path, &from) {
            entry.path = remap_entry_path(&entry.path, &from, &to);
            entry.modified = now_iso();
        }
    }
    sort_entries(&mut vault.manifest);
    vault.manifest.modified = now_iso();
    Ok(())
}

fn copy_entry_in_manifest(vault: &mut OpenVaultV3, from: &str, to: &str) -> Result<(), String> {
    let from = normalize_vault_relative_path(from)?;
    let to = normalize_vault_relative_path(to)?;
    let _ = prepare_relocation(&vault.manifest, &from, &to)?;
    if from == to {
        return Ok(());
    }
    ensure_parent_directories(&mut vault.manifest, &to)?;
    let clones: Vec<ManifestEntryV3> = vault
        .manifest
        .entries
        .iter()
        .filter(|entry| entry.path == from || is_descendant_of(&entry.path, &from))
        .cloned()
        .map(|mut entry| {
            entry.path = remap_entry_path(&entry.path, &from, &to);
            entry.modified = now_iso();
            entry
        })
        .collect();
    if clones.is_empty() {
        return Err(format!("Entry not found: {from}"));
    }
    vault.manifest.entries.extend(clones);
    sort_entries(&mut vault.manifest);
    vault.manifest.modified = now_iso();
    Ok(())
}

fn change_password_in_place(vault: &mut OpenVaultV3, new_password: &str) -> Result<(), String> {
    if vault.header.flags & FLAG_PLAINTEXT_CONTENT != 0 {
        return Err("A plaintext .aerovz archive has no password to change".to_string());
    }
    if new_password.len() < MIN_PASSWORD_LEN {
        return Err("Password must be at least 8 characters".to_string());
    }
    let salt = random_array::<SALT_SIZE>();
    let mut base_kek = derive_base_kek(new_password, &salt)?;
    let (kek_master, kek_mac) = derive_keks(&base_kek)?;
    let kek_master = Zeroizing::new(kek_master);
    let kek_mac = Zeroizing::new(kek_mac);
    base_kek.zeroize();
    vault.header.salt = salt;
    vault.header.wrapped_master_key = wrap_key(&kek_master, &vault.master_key)?;
    vault.header.wrapped_mac_key = wrap_key(&kek_mac, &vault.mac_key)?;
    vault.manifest.modified = now_iso();
    Ok(())
}

/// True if `meta` (obtained via `symlink_metadata`, i.e. about the link itself, not
/// its target) describes a reparse point. On Windows this covers BOTH directory
/// junctions (`mklink /J`, no admin needed) and symlinks via the
/// `FILE_ATTRIBUTE_REPARSE_POINT` bit; on Unix it is any symlink.
#[cfg(windows)]
fn is_reparse_point(meta: &std::fs::Metadata) -> bool {
    use std::os::windows::fs::MetadataExt;
    const FILE_ATTRIBUTE_REPARSE_POINT: u32 = 0x400;
    meta.file_attributes() & FILE_ATTRIBUTE_REPARSE_POINT != 0
}

#[cfg(not(windows))]
fn is_reparse_point(meta: &std::fs::Metadata) -> bool {
    meta.file_type().is_symlink()
}

/// Create the directory chain `root/rel` one component at a time, refusing to
/// FOLLOW any pre-existing reparse point (Windows junction/symlink). This closes
/// the intermediate-directory extract escape (audit M2): a pre-planted
/// `dest/sub -> victim` junction would otherwise let `create_dir_all` + the temp
/// rename write decrypted plaintext into `victim`. The prior AV-001 fix only
/// covered a *leaf* reparse point (replaced by the rename); an intermediate
/// directory component was uncovered.
///
/// `rel` is a relative path whose components have already been validated
/// (`validate_manifest_paths` / `normalize_vault_relative_path`: no `..`, absolute,
/// or drive component). Any non-`Normal` component is still rejected defensively.
fn create_contained_dirs(root: &Path, rel: &Path) -> Result<(), String> {
    use std::path::Component;
    let mut current = root.to_path_buf();
    for comp in rel.components() {
        match comp {
            Component::Normal(part) => current.push(part),
            Component::CurDir => continue,
            _ => {
                return Err(format!(
                    "Refusing extraction: unexpected path component in {}",
                    rel.display()
                ))
            }
        }
        match std::fs::symlink_metadata(&current) {
            Ok(meta) => {
                if is_reparse_point(&meta) {
                    return Err(format!(
                        "Refusing extraction: {} is a reparse point; it would redirect writes outside {}",
                        current.display(),
                        root.display()
                    ));
                }
                if !meta.is_dir() {
                    return Err(format!(
                        "Refusing extraction: {} exists and is not a directory",
                        current.display()
                    ));
                }
            }
            Err(ref e) if e.kind() == std::io::ErrorKind::NotFound => {
                std::fs::create_dir(&current)
                    .map_err(|e| format!("Create output dir {}: {e}", current.display()))?;
            }
            Err(e) => {
                return Err(format!("Resolve output dir {}: {e}", current.display()));
            }
        }
    }
    Ok(())
}

/// Safely create `output`'s parent directory chain under `root` and confirm the
/// resolved parent is still contained in `root`. Fails closed on any reparse-point
/// escape (audit M2). `output` is always built as `root.join(rel)` by the extract
/// callers, so its parent is lexically under `root`; `root` may be a friendly
/// (non-canonical) path — the containment assertion canonicalizes both sides.
fn prepare_output_parent(root: &Path, output: &Path) -> Result<(), String> {
    let parent = match output.parent() {
        Some(p) if !p.as_os_str().is_empty() => p,
        _ => return Ok(()),
    };
    let rel = parent.strip_prefix(root).map_err(|_| {
        format!(
            "Refusing extraction: {} is outside destination root {}",
            parent.display(),
            root.display()
        )
    })?;
    create_contained_dirs(root, rel)?;
    // Defense in depth: the fully-resolved parent must still live inside the
    // fully-resolved root (both canonicalize to `\\?\`-verbatim paths on Windows).
    let canon_root = root
        .canonicalize()
        .map_err(|e| format!("Resolve destination {}: {e}", root.display()))?;
    let canon_parent = parent
        .canonicalize()
        .map_err(|e| format!("Resolve output dir {}: {e}", parent.display()))?;
    if !canon_parent.starts_with(&canon_root) {
        return Err(format!(
            "Refusing extraction: resolved {} escapes destination root {}",
            canon_parent.display(),
            canon_root.display()
        ));
    }
    Ok(())
}

fn extract_file_entry(
    vault: &OpenVaultV3,
    entry: &ManifestEntryV3,
    output_path: &Path,
    dest_root: &Path,
) -> Result<PathBuf, String> {
    // Create + contain the parent before decoding/writing any plaintext (audit M2).
    prepare_output_parent(dest_root, output_path)?;

    // We only ever slice `out[offset..offset+size]`, so decoding never needs to
    // grow `out` past that bound. Tracking it lets us stop early and refuse a
    // manifest that repeats the same chunk id to amplify memory use far beyond
    // the entry's real extent (CLAUDE-AV-005).
    let offset = entry.pack_offset.unwrap_or(0) as usize;
    let size = entry.size as usize;
    let end = offset
        .checked_add(size)
        .ok_or_else(|| "Entry slice range overflow".to_string())?;

    // The largest plaintext a single block may legitimately hold is this vault's
    // recorded chunking `max` (or the default), clamped to the format ceiling.
    let max_block_plaintext = vault
        .manifest
        .wrappers
        .chunking
        .bounds
        .map(|b| b.max as u64)
        .unwrap_or(CDC_MAX as u64)
        .min(MAX_PLAINTEXT_BLOCK_SIZE);

    // Plaintext (`.aerovz`) lane: blocks are stored unencrypted, so the decode
    // skips AES-256-GCM-SIV and treats the on-disk block bytes as the
    // compressed-or-raw payload directly. Computed once for the whole entry.
    let plaintext_lane = manifest_is_plaintext(&vault.manifest);

    // Stream the entry to disk one block at a time: decode each chunk, write the
    // portion that falls inside the requested slice [offset, end) straight to a
    // temp file, and keep only the current decoded block in RAM. Peak memory is
    // one block (bounded by `max_block_plaintext`), not the whole entry. The temp
    // is atomically promoted only after the full slice has been written, so a
    // failure mid-decode leaves no partial output and no plaintext temp artifact.
    let parent = output_parent_dir(output_path);
    std::fs::create_dir_all(parent).map_err(|e| format!("Create parent dir: {e}"))?;
    let mut tmp = tempfile::Builder::new()
        .prefix(".aerovault-v3-")
        .tempfile_in(parent)
        .map_err(|e| format!("Create temp file: {e}"))?;

    // Cumulative decoded plaintext length so far == the old `out.len()`; used to
    // place each block against the requested slice and to detect a short entry.
    let mut decoded_len = 0usize;
    {
        use std::io::Write;
        let mut writer = std::io::BufWriter::new(tmp.as_file_mut());
        for chunk_id in &entry.chunks {
            if decoded_len >= end {
                // Everything this entry slices is already written; ignore the
                // rest (a hostile pack may list extra/duplicate chunks).
                break;
            }
            let record = vault
                .manifest
                .chunks
                .get(chunk_id)
                .ok_or_else(|| format!("Missing chunk record: {chunk_id}"))?;
            let len_start = record.data_offset as usize;
            let len_end = len_start
                .checked_add(8)
                .ok_or_else(|| "Chunk length offset overflow".to_string())?;
            if len_end > vault.data.len() {
                return Err("Chunk length is outside data section".to_string());
            }
            let block_len = u64::from_le_bytes(
                vault.data[len_start..len_end]
                    .try_into()
                    .expect("slice length"),
            );
            if block_len != record.block_len || block_len > MAX_BLOCK_SIZE {
                return Err("Chunk length metadata mismatch".to_string());
            }
            // Reject an over-declared plaintext length before decompressing so a
            // single block cannot expand to gigabytes (CLAUDE-AV-005).
            if record.plaintext_len > max_block_plaintext {
                return Err(format!(
                    "Plaintext block too large for chunk {chunk_id}: {} bytes (max {max_block_plaintext})",
                    record.plaintext_len
                ));
            }
            let block_start = len_end;
            let block_end = block_start
                .checked_add(block_len as usize)
                .ok_or_else(|| "Chunk block offset overflow".to_string())?;
            if block_end > vault.data.len() {
                return Err("Chunk block is outside data section".to_string());
            }
            let encrypted = &vault.data[block_start..block_end];
            let actual_hash = blake3::hash(encrypted).to_hex().to_string();
            if actual_hash != record.cipher_hash {
                return Err(format!("Cipher block hash mismatch for chunk {chunk_id}"));
            }
            let aad = block_aad(record.block_index, chunk_id);
            // `Zeroizing` wipes the decrypted bytes on every exit path, including
            // the zstd-init / decode / write-error early returns below (the old
            // manual `.zeroize()` calls missed those error paths).
            let decrypted: Zeroizing<Vec<u8>> = Zeroizing::new(if plaintext_lane {
                encrypted.to_vec()
            } else {
                decrypt_with_aad(&vault.master_key, encrypted, &aad)?
            });
            // A raw-stored (incompressible, #10-B) block is the plaintext itself;
            // a normal block is zstd and is decoded with a `plaintext_len + 1`
            // ceiling so a zstd bomb cannot materialise more than one chunk before
            // the length mismatch below trips.
            let plaintext: Zeroizing<Vec<u8>> = if record.stored_raw {
                decrypted
            } else {
                let mut decoder = zstd::stream::read::Decoder::new(&decrypted[..])
                    .map_err(|e| format!("zstd decompress init failed: {e}"))?;
                let mut decoded: Zeroizing<Vec<u8>> =
                    Zeroizing::new(Vec::with_capacity(record.plaintext_len as usize));
                decoder
                    .by_ref()
                    .take(record.plaintext_len + 1)
                    .read_to_end(&mut decoded)
                    .map_err(|e| format!("zstd decompress failed: {e}"))?;
                decoded
            };
            if plaintext.len() as u64 != record.plaintext_len {
                return Err(format!("Plaintext length mismatch for chunk {chunk_id}"));
            }
            // Write only the slice of this block that intersects [offset, end);
            // the windowed equivalent of the old `out[offset..end]`.
            let block_pos = decoded_len;
            let next_pos = block_pos + plaintext.len();
            let w_start = offset.max(block_pos);
            let w_end = end.min(next_pos);
            if w_start < w_end {
                writer
                    .write_all(&plaintext[w_start - block_pos..w_end - block_pos])
                    .map_err(|e| format!("Write extracted file: {e}"))?;
            }
            decoded_len = next_pos;
        }
        writer
            .flush()
            .map_err(|e| format!("Flush extracted file: {e}"))?;
    }
    // The decoded stream must reach the end of the requested slice (matches the
    // old `end > out.len()` guard).
    if decoded_len < end {
        return Err(format!(
            "Entry slice [{offset}..{end}] exceeds decoded data ({decoded_len})"
        ));
    }
    tmp.as_file_mut()
        .sync_all()
        .map_err(|e| format!("Sync temp file: {e}"))?;
    tmp.persist(output_path)
        .map_err(|e| format!("Persist vault: {}", e.error))?;
    fsync_parent_dir(parent);
    Ok(output_path.to_path_buf())
}

/// Resolve the directory an output/temp file lives in, mapping a parent-less or
/// empty parent to the current directory. Shared by `atomic_write` and the
/// streaming `extract_file_entry` so both place their temp beside the target.
pub(super) fn output_parent_dir(target: &Path) -> &Path {
    target
        .parent()
        .filter(|p| !p.as_os_str().is_empty())
        .unwrap_or_else(|| Path::new("."))
}

/// Best-effort fsync of a directory so a freshly persisted rename is durable on
/// crash (Unix). A no-op on other platforms. Single definition so the durability
/// discipline cannot drift between the write paths that rely on it.
pub(super) fn fsync_parent_dir(parent: &Path) {
    #[cfg(unix)]
    {
        if let Ok(dir) = std::fs::File::open(parent) {
            let _ = dir.sync_all();
        }
    }
    #[cfg(not(unix))]
    {
        let _ = parent;
    }
}

pub(super) fn atomic_write(target: &Path, bytes: &[u8]) -> Result<(), String> {
    let parent = output_parent_dir(target);
    std::fs::create_dir_all(parent).map_err(|e| format!("Create parent dir: {e}"))?;
    let mut tmp = tempfile::Builder::new()
        .prefix(".aerovault-v3-")
        .tempfile_in(parent)
        .map_err(|e| format!("Create temp file: {e}"))?;
    use std::io::Write;
    tmp.write_all(bytes)
        .map_err(|e| format!("Write temp file: {e}"))?;
    tmp.as_file_mut()
        .sync_all()
        .map_err(|e| format!("Sync temp file: {e}"))?;
    tmp.persist(target)
        .map_err(|e| format!("Persist vault: {}", e.error))?;
    fsync_parent_dir(parent);
    Ok(())
}

pub(super) fn read_capped(
    file: &mut std::fs::File,
    offset: u64,
    len: u64,
    cap: u64,
    label: &str,
) -> Result<Vec<u8>, String> {
    use std::io::Seek;
    if len > cap {
        return Err(format!("{label} too large: {len} bytes"));
    }
    file.seek(std::io::SeekFrom::Start(offset))
        .map_err(|e| format!("Seek {label}: {e}"))?;
    let mut buf = vec![0u8; len as usize];
    file.read_exact(&mut buf)
        .map_err(|e| format!("Read {label}: {e}"))?;
    Ok(buf)
}

/// Reject a manifest whose wrapper algorithms differ from the ones this build
/// hardcodes. Fields are authenticated; asserting them turns a future
/// version-confusion bug into a clean fail-closed error.
fn check_wrapper(slot: &str, spec: &AlgorithmSpec, id: &str, ver: u32) -> Result<(), String> {
    if spec.algorithm_id != id || spec.algorithm_version != ver {
        return Err(format!(
            "Unsupported AeroVault v3 {slot} algorithm: {} v{} (expected {id} v{ver})",
            spec.algorithm_id, spec.algorithm_version
        ));
    }
    Ok(())
}

fn validate_supported_wrappers(w: &WrapperManifest) -> Result<(), String> {
    check_wrapper("packing", &w.packing, "small-file-batching", 1)?;
    check_wrapper("chunking", &w.chunking, "gear-cdc", 1)?;
    check_wrapper("chunk_id", &w.chunk_id, "blake3-keyed-128", 1)?;
    check_wrapper("compression", &w.compression, "zstd", 1)?;
    // crypt: the encrypted lane records `aes-256-gcm-siv`, the plaintext
    // (`.aerovz`) lane records `none`. Both are version 1.
    match w.crypt.algorithm_id.as_str() {
        CRYPT_ALGORITHM_ENCRYPTED | CRYPT_ALGORITHM_NONE => {
            if w.crypt.algorithm_version != 1 {
                return Err(format!(
                    "Unsupported crypt wrapper version: {}",
                    w.crypt.algorithm_version
                ));
            }
        }
        other => return Err(format!("Unsupported crypt wrapper: {other}")),
    }
    check_wrapper("cipher_hash", &w.cipher_hash, "blake3-256", 1)?;
    Ok(())
}

pub(super) fn open_header_bytes(
    header_bytes: &[u8],
    password: &str,
) -> Result<(VaultHeaderV3, [u8; KEY_SIZE], [u8; KEY_SIZE]), String> {
    let header = VaultHeaderV3::from_bytes(header_bytes)?;
    let mut base_kek = derive_base_kek(password, &header.salt)?;
    // Wrap the transient KEKs so they are wiped on every exit path (including the
    // `?` early returns below), not just left in freed memory after use.
    let (kek_master, kek_mac) = derive_keks(&base_kek)?;
    let kek_master = Zeroizing::new(kek_master);
    let kek_mac = Zeroizing::new(kek_mac);
    base_kek.zeroize();
    let mac_key = unwrap_key(&kek_mac, &header.wrapped_mac_key)?;
    header.verify_mac(&mac_key)?;
    if header.wrapper_header_version != SUPPORTED_WRAPPER_HEADER_VERSION {
        return Err(format!(
            "Unsupported AeroVault v3 wrapper-header version: {} (expected {})",
            header.wrapper_header_version, SUPPORTED_WRAPPER_HEADER_VERSION
        ));
    }
    let master_key = unwrap_key(&kek_master, &header.wrapped_master_key)?;
    Ok((header, mac_key, master_key))
}

fn create_empty_vault(
    path: &Path,
    password: &str,
    level: i32,
    cdc_bounds: Option<CdcBounds>,
    lane: VaultLane,
    error_correction: Option<super::ec::RecoveryPlacement>,
    error_correction_pct: u32,
) -> Result<(), String> {
    // The plaintext (`.aerovz`) lane has no password: zero salt + zero wrapped
    // keys in the header, a public deterministic chunk-id key (all-zero master),
    // and the header HMAC keyed by the fixed PUBLIC integrity key. The encrypted
    // lane derives everything from the password exactly as before.
    let plaintext = lane == VaultLane::Plaintext;

    let (salt, wrapped_master_key, wrapped_mac_key, mut master_key, mut mac_key, flags) =
        if plaintext {
            (
                [0u8; SALT_SIZE],
                [0u8; WRAPPED_KEY_SIZE],
                [0u8; WRAPPED_KEY_SIZE],
                [0u8; KEY_SIZE],
                aerovz_mac_key()?,
                FLAG_PLAINTEXT_CONTENT,
            )
        } else {
            if password.len() < MIN_PASSWORD_LEN {
                return Err("Password must be at least 8 characters".to_string());
            }
            let salt = random_array::<SALT_SIZE>();
            let mut base_kek = derive_base_kek(password, &salt)?;
            let (kek_master, kek_mac) = derive_keks(&base_kek)?;
            let kek_master = Zeroizing::new(kek_master);
            let kek_mac = Zeroizing::new(kek_mac);
            base_kek.zeroize();
            let master_key = random_array::<KEY_SIZE>();
            let mac_key = random_array::<KEY_SIZE>();
            let wrapped_master_key = wrap_key(&kek_master, &master_key)?;
            let wrapped_mac_key = wrap_key(&kek_mac, &mac_key)?;
            (
                salt,
                wrapped_master_key,
                wrapped_mac_key,
                master_key,
                mac_key,
                0u8,
            )
        };

    let header = VaultHeaderV3 {
        flags,
        salt,
        wrapped_master_key,
        wrapped_mac_key,
        data_offset: DATA_OFFSET,
        data_len: 0,
        manifest_offset: DATA_OFFSET,
        manifest_len: 0,
        extension_dir_offset: DATA_OFFSET,
        extension_dir_len: 0,
        extension_payload_offset: DATA_OFFSET,
        extension_payload_len: 0,
        wrapper_header_version: 1,
        header_mac: [0u8; MAC_SIZE],
    };

    let mut manifest = if plaintext {
        empty_manifest_plaintext(level)
    } else {
        empty_manifest(level)
    };
    if let Some(bounds) = cdc_bounds {
        bounds.validate()?;
        manifest.wrappers.chunking.bounds = Some(bounds);
    }
    // Record the QR-style overhead level so every later seal / export uses the
    // same grid (#276). Only meaningful when Error Correction is enabled.
    if error_correction.is_some() {
        manifest.error_correction_pct = Some(error_correction_pct.clamp(
            crate::error_correction::ERROR_CORRECTION_MIN_PCT,
            crate::error_correction::ERROR_CORRECTION_MAX_PCT,
        ));
    }
    // Embed the extension only when the placement keeps an in-container copy.
    let embed = error_correction.is_some_and(|p| p.embeds());
    let mut extensions = if embed {
        vec![super::ec::error_correction_stub_extension()]
    } else {
        vec![]
    };
    let ext_payloads = if embed {
        let (p, _shards, _prot, _ov) =
            crate::error_correction::compute_error_correction_shards(&[]);
        if let Some(e) = extensions.first_mut() {
            e.offset = 0;
            e.length = p.len() as u64;
        }
        p
    } else {
        vec![]
    };
    let bytes = build_file_bytes(
        header,
        &mac_key,
        &master_key,
        &manifest,
        &extensions,
        &ext_payloads,
        &[],
    )?;
    master_key.zeroize();
    mac_key.zeroize();
    atomic_write(path, &bytes)?;

    // Detached/both placements seed the sidecar so the file exists from
    // creation. An empty vault has an empty parity payload; re-run
    // `export-parity` after adding files (par2 semantics).
    if error_correction.is_some_and(|p| p.writes_sidecar()) {
        super::ec::seed_empty_sidecar(path, &bytes)?;
    }
    Ok(())
}

pub(super) fn open_vault(path: impl Into<PathBuf>, password: &str) -> Result<OpenVaultV3, String> {
    let path = path.into();
    let mut file = std::fs::File::open(&path).map_err(|e| format!("Open vault: {e}"))?;
    let file_len = file
        .metadata()
        .map_err(|e| format!("Vault metadata: {e}"))?
        .len();
    let mut header_bytes = [0u8; HEADER_SIZE];
    file.read_exact(&mut header_bytes)
        .map_err(|e| format!("Read header: {e}"))?;

    // Plaintext (`.aerovz`) lane: when the header parses and carries
    // FLAG_PLAINTEXT_CONTENT, there is no password — verify the header MAC under
    // the fixed PUBLIC integrity key and use an all-zero (public) master key for
    // the deterministic chunk-id derivation. The manifest is read as plaintext
    // below. EC header recovery stays on the encrypted path (the plaintext
    // header is still EC-protected by region; recovery for it is a follow-up).
    let plaintext_header = VaultHeaderV3::from_bytes(&header_bytes)
        .ok()
        .is_some_and(|h| h.flags & FLAG_PLAINTEXT_CONTENT != 0);

    // HEADER parity (rev. 4): the on-disk header is the happy path. If it fails
    // to parse or its MAC does not verify (bit-rot / bad sector), fall back to
    // rebuilding it from the detached sidecar's header parity. A missing sidecar
    // / no header parity / a rebuild that still does not unlock keeps the
    // original error. The MAC verify inside `open_header_bytes` is the proof.
    let (header, mac_key, master_key, header_repaired_on_open) = if plaintext_header {
        let header = VaultHeaderV3::from_bytes(&header_bytes)?;
        let mac_key = aerovz_mac_key()?;
        header.verify_mac(&mac_key)?;
        if header.wrapper_header_version != SUPPORTED_WRAPPER_HEADER_VERSION {
            return Err(format!(
                "Unsupported AeroVault v3 wrapper-header version: {} (expected {})",
                header.wrapper_header_version, SUPPORTED_WRAPPER_HEADER_VERSION
            ));
        }
        (header, mac_key, [0u8; KEY_SIZE], false)
    } else {
        match open_header_bytes(&header_bytes, password) {
            Ok((h, mac, master)) => (h, mac, master, false),
            Err(orig) => {
                match super::ec::recover_header_from_sidecar(&path, &header_bytes, password)? {
                    Some((h, mac, master)) => (h, mac, master, true),
                    None => return Err(orig),
                }
            }
        }
    };

    validate_ranges(&header, file_len)?;

    let data = read_capped(
        &mut file,
        header.data_offset,
        header.data_len,
        // The data section is authenticated and validate_ranges has already
        // bounded it within the file; cap explicitly at file length.
        file_len,
        "data section",
    )?;
    let encrypted_manifest = read_capped(
        &mut file,
        header.manifest_offset,
        header.manifest_len,
        MAX_MANIFEST_SIZE,
        "manifest",
    )?;

    // Read, parse and VALIDATE the extension directory up front (audit M4) so a forged
    // directory is rejected at open BEFORE the manifest-recovery block below can consume
    // it (`reconstruct_encrypted_manifest` reads its own copy of the directory region to
    // locate the EC parity extension). `read_capped` seeks per call, so this read does
    // not perturb the later reads. Reject critical / duplicate / out-of-range entries.
    let extension_json = read_capped(
        &mut file,
        header.extension_dir_offset,
        header.extension_dir_len,
        MAX_EXTENSION_DIR_SIZE,
        "extension directory",
    )?;
    let extensions: Vec<ExtensionEntryV3> = serde_json::from_slice(&extension_json)
        .map_err(|e| format!("Extension directory parse: {e}"))?;
    validate_extension_dir(&extensions, header.extension_payload_len)?;

    // GAP-4 (rev. 4): the manifest region may be corrupted (bit-rot, bad
    // sector). Rebuild the encrypted manifest from parity and retry. Try the
    // embedded metadata extension first (auto-fresh on the embedded path), then
    // the detached sidecar's manifest parity (the only copy a pure-detached
    // vault keeps). A successful AEAD decrypt on the rebuilt bytes is the
    // correctness proof; otherwise keep the original error.
    // Decode the stored manifest blob: AEAD-decrypt on the encrypted lane, parse
    // plaintext JSON on the `.aerovz` lane. Either way, on a parse/decrypt
    // failure rebuild the blob from Error-Correction parity (embedded metadata
    // extension first, then the detached sidecar) and retry — the manifest is
    // EC-protected by region regardless of whether it is encrypted.
    let decode_manifest = |blob: &[u8]| -> Result<VaultManifestV3, String> {
        if plaintext_header {
            parse_manifest_plaintext(blob)
        } else {
            decrypt_manifest(&master_key, blob)
        }
    };
    let (manifest, manifest_repaired_on_open) = match decode_manifest(&encrypted_manifest) {
        Ok(m) => (m, false),
        Err(orig) => {
            let embedded = super::ec::reconstruct_encrypted_manifest(&mut file, &header, file_len)?;
            let rebuilt = match embedded {
                Some(r) if r != encrypted_manifest => Some(r),
                _ => super::ec::reconstruct_manifest_from_sidecar(&path, &encrypted_manifest)?,
            };
            match rebuilt {
                Some(r) if r != encrypted_manifest => (decode_manifest(&r)?, true),
                _ => return Err(orig),
            }
        }
    };
    if manifest.format != VERSION {
        return Err(format!(
            "Unsupported AeroVault manifest version: {}",
            manifest.format
        ));
    }
    validate_supported_wrappers(&manifest.wrappers)?;
    // The header flag and the manifest `crypt` wrapper are two views of the same
    // lane; reject a container whose header claims one lane and manifest the
    // other (a forged/corrupt mismatch would otherwise decode under the wrong
    // key path).
    if plaintext_header != manifest_is_plaintext(&manifest) {
        return Err("AeroVault v3 header/manifest encryption-lane mismatch".to_string());
    }
    validate_manifest_paths(&manifest)?;

    // Do not round-trip the EC metadata-parity extension; build_file_bytes is
    // its sole author and recomputes it on every seal from the freshly
    // encrypted manifest. (No-op when no EC extension is present.)
    let extensions: Vec<ExtensionEntryV3> = extensions
        .into_iter()
        .filter(|e| e.extension_id != super::constants::ERROR_CORRECTION_META_EXTENSION_ID)
        .collect();

    Ok(OpenVaultV3 {
        path,
        opened_file_len: file_len,
        opened_header_mac: header.header_mac,
        header,
        master_key,
        mac_key,
        manifest,
        extensions,
        data,
        manifest_repaired_on_open,
        header_repaired_on_open,
        telemetry: None,
    })
}

fn validate_ranges(header: &VaultHeaderV3, file_len: u64) -> Result<(), String> {
    if header.data_offset != DATA_OFFSET {
        return Err("Invalid AeroVault v3 data offset".to_string());
    }
    let ranges = [
        (header.data_offset, header.data_len, "data"),
        (header.manifest_offset, header.manifest_len, "manifest"),
        (
            header.extension_dir_offset,
            header.extension_dir_len,
            "extension directory",
        ),
        (
            header.extension_payload_offset,
            header.extension_payload_len,
            "extension payload",
        ),
    ];
    for (offset, len, label) in ranges {
        let end = offset
            .checked_add(len)
            .ok_or_else(|| format!("{label} range overflows"))?;
        if end > file_len {
            return Err(format!("{label} range exceeds file size"));
        }
    }
    Ok(())
}

/// Staleness guard: refuse to seal if the on-disk vault changed since open
/// (concurrent writer), keyed on file length + header MAC.
fn assert_vault_generation_current(vault: &OpenVaultV3) -> Result<(), String> {
    let mut file = std::fs::File::open(&vault.path).map_err(|e| format!("Open vault: {e}"))?;
    let file_len = file
        .metadata()
        .map_err(|e| format!("Vault metadata: {e}"))?
        .len();
    let mut header_bytes = [0u8; HEADER_SIZE];
    file.read_exact(&mut header_bytes)
        .map_err(|e| format!("Read header: {e}"))?;
    let header = VaultHeaderV3::from_bytes(&header_bytes)?;
    if file_len != vault.opened_file_len || header.header_mac != vault.opened_header_mac {
        return Err("Vault changed while this write was in progress; retry operation".to_string());
    }
    Ok(())
}

/// Persist the in-memory vault back to disk with an atomic single-rename seal.
///
/// Concurrency contract (audit M6): this provides only a *same-open generation
/// check* via [`assert_vault_generation_current`] (it refuses to seal if the file
/// length or header MAC changed since open). It takes **no cross-process lock**, so
/// two writers that both opened the same generation can each pass the check and race
/// the final rename, last-writer-wins. Cross-process safety is the **embedder's
/// responsibility**: the AeroFTP app serializes all mutations behind an O_EXCL
/// `.{name}.lock`. Direct crate users that mutate a vault from more than one process
/// must apply their own external lock.
pub(super) fn save_open_vault(vault: &mut OpenVaultV3) -> Result<(), String> {
    assert_vault_generation_current(vault)?;

    let mut extensions = vault.extensions.clone();
    let mut ext_payloads = vec![];
    let mut ec_stats: Option<(u64, u64, f64)> = None;

    // rev. 4: if the Error-Correction extension is present, recompute the shards
    // over the current data section and update the entry + payload. Recompute on
    // every seal (cost is acceptable for the EC use case; most vaults won't have
    // it enabled).
    if let Some(error_correction_idx) = extensions
        .iter()
        .position(|e| e.extension_id == super::constants::ERROR_CORRECTION_EXTENSION_ID)
    {
        // On-disk blocks in data-section order (sorted by data_offset). Each
        // full block is [u64 len][ciphertext of that len]. Offset arithmetic is
        // checked so a manifest record near usize::MAX yields an empty slice
        // instead of panicking (matches collect_live_block_refs / scrub_vault).
        let mut chunk_records: Vec<_> = vault.manifest.chunks.values().cloned().collect();
        chunk_records.sort_by_key(|r| r.data_offset);

        let blocks: Vec<&[u8]> = chunk_records
            .iter()
            .map(|rec| {
                let start = rec.data_offset as usize;
                let end = (rec.block_len as usize)
                    .checked_add(8)
                    .and_then(|full| start.checked_add(full));
                match end {
                    Some(end) if end <= vault.data.len() => &vault.data[start..end],
                    _ => &[] as &[u8],
                }
            })
            .collect();

        let (k, p) = crate::error_correction::manifest_error_correction_grid(
            vault.manifest.error_correction_pct,
        );
        let (payload, shards, protected, overhead) =
            crate::error_correction::compute_error_correction_shards_grid(&blocks, k, p);

        let entry = &mut extensions[error_correction_idx];
        entry.offset = 0;
        entry.length = payload.len() as u64;

        ext_payloads = payload;
        if shards > 0 || protected > 0 {
            ec_stats = Some((shards, protected, overhead));
        }
    }
    // Surface Error Correction telemetry once the data borrow above is released.
    if let Some((shards, protected, overhead)) = ec_stats {
        vault.emit(|s| s.set_error_correction(shards, protected, overhead));
    }

    // Stream the container straight to the temp file: the data section (already
    // in RAM on `OpenVaultV3.data`) is written directly rather than copied into a
    // second whole-file buffer, so the seal no longer doubles peak memory
    // (T5 sub-task #2). Same atomic temp + sync + persist + dir-fsync discipline
    // as `atomic_write`, via the shared helpers.
    {
        use std::io::Write;
        let parent = output_parent_dir(&vault.path);
        std::fs::create_dir_all(parent).map_err(|e| format!("Create parent dir: {e}"))?;
        let mut tmp = tempfile::Builder::new()
            .prefix(".aerovault-v3-")
            .tempfile_in(parent)
            .map_err(|e| format!("Create temp file: {e}"))?;
        {
            let mut w = std::io::BufWriter::new(tmp.as_file_mut());
            write_container(
                &mut w,
                vault.header.clone(),
                &vault.mac_key,
                &vault.master_key,
                &vault.manifest,
                &extensions,
                &ext_payloads,
                &vault.data,
            )?;
            w.flush().map_err(|e| format!("Flush temp file: {e}"))?;
        }
        tmp.as_file_mut()
            .sync_all()
            .map_err(|e| format!("Sync temp file: {e}"))?;
        tmp.persist(&vault.path)
            .map_err(|e| format!("Persist vault: {}", e.error))?;
        fsync_parent_dir(parent);
    }

    // Refresh the staleness baseline so a second save in the same session does
    // not trip the generation guard against the bytes we just wrote.
    let mut file = std::fs::File::open(&vault.path).map_err(|e| format!("Open vault: {e}"))?;
    let file_len = file
        .metadata()
        .map_err(|e| format!("Vault metadata: {e}"))?
        .len();
    let mut header_bytes = [0u8; HEADER_SIZE];
    file.read_exact(&mut header_bytes)
        .map_err(|e| format!("Read header: {e}"))?;
    let header = VaultHeaderV3::from_bytes(&header_bytes)?;
    vault.opened_file_len = file_len;
    vault.opened_header_mac = header.header_mac;
    vault.header = header;
    Ok(())
}

fn extract_entry(
    vault: &OpenVaultV3,
    entry_name: &str,
    dest_path: &Path,
) -> Result<PathBuf, String> {
    let entry_name = normalize_vault_relative_path(entry_name)?;
    match entry_kind(&vault.manifest, &entry_name) {
        Some(EntryKindV3::File) => {
            let entry = vault
                .manifest
                .entries
                .iter()
                .find(|entry| entry.path == entry_name)
                .ok_or_else(|| format!("Entry not found: {entry_name}"))?;
            if dest_path.is_dir() {
                // Extracting into an existing directory: contain under it.
                let output_path = dest_path.join(&entry.path);
                extract_file_entry(vault, entry, &output_path, dest_path)
            } else {
                // Caller named an EXACT output file path (not manifest-derived); the
                // single leaf is replaced by atomic_write's rename. The destination is
                // the caller's own choice, so its parent is a trust boundary the caller
                // owns (no manifest-controlled component is appended here).
                let parent = dest_path
                    .parent()
                    .filter(|p| !p.as_os_str().is_empty())
                    .unwrap_or_else(|| Path::new("."));
                std::fs::create_dir_all(parent).map_err(|e| format!("Create output dir: {e}"))?;
                extract_file_entry(vault, entry, dest_path, parent)
            }
        }
        Some(EntryKindV3::Directory) => {
            // Containment root is the user's chosen destination. When it already exists
            // we extract the subtree under `dest/<basename>`, and the manifest-derived
            // `<basename>` component is created through create_contained_dirs so a
            // pre-planted junction there is refused (audit M2 residual) rather than
            // followed; the subtree is then contained under the REAL `dest` (`root`),
            // not under a possibly-redirected `output_root`. When dest does not exist
            // we create it fresh and it is its own root.
            let (root, output_root) = if dest_path.exists() {
                if !dest_path.is_dir() {
                    return Err(
                        "Destination for directory extraction must be a directory".to_string()
                    );
                }
                let basename = path_basename(&entry_name);
                create_contained_dirs(dest_path, Path::new(basename))?;
                (dest_path.to_path_buf(), dest_path.join(basename))
            } else {
                std::fs::create_dir_all(dest_path)
                    .map_err(|e| format!("Create output dir: {e}"))?;
                (dest_path.to_path_buf(), dest_path.to_path_buf())
            };

            let prefix = format!("{entry_name}/");
            let mut descendants: Vec<&ManifestEntryV3> = vault
                .manifest
                .entries
                .iter()
                .filter(|entry| entry.path == entry_name || entry.path.starts_with(&prefix))
                .collect();
            descendants.sort_by(|a, b| a.path.cmp(&b.path));

            for entry in descendants {
                normalize_vault_relative_path(&entry.path)?;
                let rel = if entry.path == entry_name {
                    String::new()
                } else {
                    entry.path[entry_name.len() + 1..].to_string()
                };
                if !rel.is_empty() {
                    normalize_vault_relative_path(&rel)?;
                }
                let child_output = if rel.is_empty() {
                    output_root.clone()
                } else {
                    output_root.join(&rel)
                };
                if entry.is_dir {
                    // Contain every created directory under the REAL root (dest), which
                    // includes the basename component, so a planted reparse point
                    // anywhere on the path is refused.
                    let rel_from_root = child_output.strip_prefix(&root).map_err(|_| {
                        format!(
                            "Refusing extraction: {} escapes destination root {}",
                            child_output.display(),
                            root.display()
                        )
                    })?;
                    if !rel_from_root.as_os_str().is_empty() {
                        create_contained_dirs(&root, rel_from_root)?;
                    }
                } else {
                    extract_file_entry(vault, entry, &child_output, &root)?;
                }
            }

            Ok(output_root)
        }
        None => Err(format!("Entry not found: {entry_name}")),
    }
}

/// Extract the whole vault tree into `dest_root`, recreating every entry's path
/// under it. Returns the number of files written. Every entry path is
/// normalized first, so a crafted manifest cannot escape `dest_root`.
fn extract_all_entries(vault: &OpenVaultV3, dest_root: &Path) -> Result<u64, String> {
    extract_all_entries_with_progress(vault, dest_root, &mut |_, _| {})
}

/// `extract_all_entries` with a `(bytes_done, bytes_total)` progress callback
/// invoked after each file is written (#5: progress for extract). `bytes_total`
/// is the sum of file-entry plaintext sizes; directory entries do not move it.
fn extract_all_entries_with_progress(
    vault: &OpenVaultV3,
    dest_root: &Path,
    progress: &mut dyn FnMut(u64, u64),
) -> Result<u64, String> {
    std::fs::create_dir_all(dest_root).map_err(|e| format!("Create output dir: {e}"))?;
    let mut entries: Vec<&ManifestEntryV3> = vault.manifest.entries.iter().collect();
    entries.sort_by(|a, b| a.path.cmp(&b.path));
    let total: u64 = entries.iter().filter(|e| !e.is_dir).map(|e| e.size).sum();
    let mut done = 0u64;
    let mut files_written = 0u64;
    for entry in entries {
        let rel = normalize_vault_relative_path(&entry.path)?;
        let output = dest_root.join(&rel);
        if entry.is_dir {
            // Create directory entries through the same reparse-point-refusing path
            // as file parents, so a planted intermediate junction cannot redirect them.
            create_contained_dirs(dest_root, Path::new(&rel))?;
        } else {
            extract_file_entry(vault, entry, &output, dest_root)?;
            files_written += 1;
            done = done.saturating_add(entry.size);
            progress(done, total);
        }
    }
    Ok(files_written)
}

/// Recursive directory add (the byte-affecting part of the app command, minus
/// the Tauri progress emit). Returns `(added_files, added_dirs)`.
fn add_directory_into(
    vault: &mut OpenVaultV3,
    source_dir: &Path,
    target_prefix: Option<&str>,
) -> Result<(usize, usize), String> {
    let source = source_dir
        .canonicalize()
        .map_err(|e| format!("Failed to resolve directory: {e}"))?;
    if !source.is_dir() {
        return Err(format!("Not a directory: {}", source_dir.display()));
    }

    struct DirEntry {
        rel_path: String,
        is_dir: bool,
        abs_path: PathBuf,
        depth: usize,
    }

    let normalized_prefix = target_prefix
        .map(|prefix| prefix.trim_matches('/'))
        .filter(|prefix| !prefix.is_empty())
        .map(normalize_vault_relative_path)
        .transpose()?;

    let mut all_entries: Vec<DirEntry> = Vec::new();
    for entry in walkdir::WalkDir::new(&source)
        .follow_links(false)
        .max_depth(100)
        .into_iter()
        .filter_map(|e| e.ok())
    {
        if entry.path() == source {
            continue;
        }
        if all_entries.len() >= 500_000 {
            return Err("Directory exceeds maximum entry limit (500000)".to_string());
        }

        let rel_path = entry
            .path()
            .strip_prefix(&source)
            .map_err(|_| "Failed to compute relative path".to_string())?
            .to_string_lossy()
            .replace('\\', "/");
        let full_rel = if let Some(prefix) = &normalized_prefix {
            join_vault_path(prefix, &rel_path)
        } else {
            rel_path
        };
        let full_rel = normalize_vault_relative_path(&full_rel)?;

        all_entries.push(DirEntry {
            rel_path: full_rel,
            is_dir: entry.file_type().is_dir(),
            abs_path: entry.path().to_path_buf(),
            depth: entry.depth(),
        });
    }

    let mut dirs: Vec<&DirEntry> = all_entries.iter().filter(|entry| entry.is_dir).collect();
    let files: Vec<&DirEntry> = all_entries.iter().filter(|entry| !entry.is_dir).collect();
    dirs.sort_by_key(|entry| entry.depth);

    let mut added_dirs = 0usize;
    for dir_entry in dirs {
        if create_directory_in_manifest(&mut vault.manifest, &dir_entry.rel_path)? {
            added_dirs += 1;
        }
    }

    let total_files = files.len();
    let sources: Vec<(PathBuf, String)> = files
        .iter()
        .map(|f| (f.abs_path.clone(), f.rel_path.clone()))
        .collect();
    append_sources_batched(vault, &sources)?;

    save_open_vault(vault)?;
    Ok((total_files, added_dirs))
}

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

    const PW: &str = "test-password-123";

    fn vault_path() -> PathBuf {
        let mut p = std::env::temp_dir();
        p.push(format!("av3-test-{}.aerovault", rand::random::<u64>()));
        p
    }

    fn scratch_dir() -> PathBuf {
        let mut p = std::env::temp_dir();
        p.push(format!("av3-scratch-{}", rand::random::<u64>()));
        std::fs::create_dir_all(&p).unwrap();
        p
    }

    #[test]
    fn create_open_wrong_password_and_full_round_trip() {
        // One create + a couple opens to keep Argon2id calls modest.
        let vp = vault_path();
        VaultV3::create(&CreateOptionsV3::new(&vp, PW)).unwrap();
        assert!(VaultV3::is_vault_v3(&vp));

        // Wrong password fails.
        assert!(VaultV3::open(&vp, "wrong-password").is_err());

        // Peek without password.
        let info = VaultV3::peek(&vp).unwrap();
        assert_eq!(info.version, VERSION);

        // Build a tree: several small files (packed), one large file (CDC path),
        // and a subdirectory.
        let src = scratch_dir();
        let small1 = src.join("a.txt");
        let small2 = src.join("b.txt");
        let small3 = src.join("c.txt");
        std::fs::write(&small1, b"alpha contents").unwrap();
        std::fs::write(&small2, b"beta contents which differ").unwrap();
        std::fs::write(&small3, vec![0x5au8; 4096]).unwrap();

        // Large file > PACK_SMALL_FILE_THRESHOLD to force the CDC per-file path.
        let large = src.join("big.bin");
        let mut payload = vec![0u8; PACK_SMALL_FILE_THRESHOLD + 600_000];
        let mut x = 0x9e3779b97f4a7c15u64;
        for b in payload.iter_mut() {
            x ^= x << 13;
            x ^= x >> 7;
            x ^= x << 17;
            *b = (x & 0xff) as u8;
        }
        std::fs::write(&large, &payload).unwrap();

        let mut vault = VaultV3::open(&vp, PW).unwrap();
        VaultV3::create_directory(&mut vault, "docs/sub").unwrap();
        VaultV3::add_files(
            &mut vault,
            &[
                (small1.clone(), "a.txt".to_string()),
                (small2.clone(), "b.txt".to_string()),
                (small3.clone(), "docs/sub/c.txt".to_string()),
                (large.clone(), "big.bin".to_string()),
            ],
        )
        .unwrap();

        let listed = VaultV3::list(&vault);
        assert!(listed.iter().any(|e| e.path == "a.txt" && !e.is_dir));
        assert!(listed.iter().any(|e| e.path == "docs/sub" && e.is_dir));
        assert!(listed
            .iter()
            .any(|e| e.path == "big.bin" && e.size == payload.len() as u64));

        // Extract all and verify byte-identity.
        let out = scratch_dir();
        let written = VaultV3::extract_all(&vault, &out).unwrap();
        assert_eq!(written, 4);
        assert_eq!(std::fs::read(out.join("a.txt")).unwrap(), b"alpha contents");
        assert_eq!(
            std::fs::read(out.join("b.txt")).unwrap(),
            b"beta contents which differ"
        );
        assert_eq!(
            std::fs::read(out.join("docs/sub/c.txt")).unwrap(),
            vec![0x5au8; 4096]
        );
        assert_eq!(std::fs::read(out.join("big.bin")).unwrap(), payload);

        std::fs::remove_file(&vp).ok();
        std::fs::remove_dir_all(&src).ok();
        std::fs::remove_dir_all(&out).ok();
    }

    #[test]
    fn streaming_multi_megabyte_round_trip_is_byte_identical() {
        // T5 headline: a multi-MB file is ingested through the bounded-buffer
        // StreamingChunker (many CDC windows + several reader refills) and
        // re-extracted block-by-block, and must come back byte-for-byte. This
        // exercises the streaming add + streaming extract paths end to end,
        // across both the incompressible (stored-raw) and the zstd lanes.
        let vp = vault_path();
        VaultV3::create(&CreateOptionsV3::new(&vp, PW)).unwrap();

        let src = scratch_dir();

        // 12 MiB pseudo-random => incompressible (stored_raw) and split into
        // several CDC chunks (min 256 KiB / max 4 MiB => at least 3 chunks).
        let mut random = vec![0u8; 12 * 1024 * 1024 + 7];
        let mut x = 0xd1b54a32d192ed03u64;
        for b in random.iter_mut() {
            x ^= x << 13;
            x ^= x >> 7;
            x ^= x << 17;
            *b = (x & 0xff) as u8;
        }
        let rnd_path = src.join("random.bin");
        std::fs::write(&rnd_path, &random).unwrap();

        // 12 MiB highly compressible => the zstd lane, decoded windowed on extract.
        let pattern = b"AeroVault v3 streaming round-trip payload block. ";
        let mut text = Vec::with_capacity(12 * 1024 * 1024);
        while text.len() < 12 * 1024 * 1024 {
            text.extend_from_slice(pattern);
        }
        let txt_path = src.join("text.bin");
        std::fs::write(&txt_path, &text).unwrap();

        let mut vault = VaultV3::open(&vp, PW).unwrap();
        VaultV3::add_files(
            &mut vault,
            &[
                (rnd_path.clone(), "random.bin".to_string()),
                (txt_path.clone(), "text.bin".to_string()),
            ],
        )
        .unwrap();

        // Both files must have been split into multiple CDC chunks, i.e. the
        // streaming chunker actually crossed window boundaries (not one big read).
        let rnd_entry = vault
            .manifest
            .entries
            .iter()
            .find(|e| e.path == "random.bin")
            .unwrap();
        assert!(
            rnd_entry.chunks.len() >= 3,
            "12 MiB random file should split into multiple CDC chunks, got {}",
            rnd_entry.chunks.len()
        );

        let out = scratch_dir();
        VaultV3::extract_all(&vault, &out).unwrap();
        assert_eq!(
            std::fs::read(out.join("random.bin")).unwrap(),
            random,
            "incompressible multi-chunk file must round-trip byte-identically"
        );
        assert_eq!(
            std::fs::read(out.join("text.bin")).unwrap(),
            text,
            "compressible multi-chunk file must round-trip byte-identically"
        );

        std::fs::remove_file(&vp).ok();
        std::fs::remove_dir_all(&src).ok();
        std::fs::remove_dir_all(&out).ok();
    }

    #[test]
    fn streaming_packed_small_files_cross_chunk_round_trip() {
        // Exercises the windowed streaming extract with offset > 0 AND a file
        // straddling a CDC chunk boundary: many sub-threshold files are batched
        // into one pack, the pack is chunked (>= 2 chunks), and each member's
        // [pack_offset, pack_offset+size) slice is reassembled block-by-block.
        // This is the most error-prone new arithmetic (w_start/w_end clamp) and
        // the old offset==0 round-trip tests do not cover it.
        let vp = vault_path();
        VaultV3::create(&CreateOptionsV3::new(&vp, PW)).unwrap();

        let src = scratch_dir();
        // 48 distinct ~100 KiB files => ~4.8 MiB packed, which the CDC (avg 1 MiB,
        // max 4 MiB) splits into several chunks, so members straddle boundaries.
        // Each file gets unique pseudo-random content (no dedup collapse, so the
        // per-file byte comparison is meaningful).
        let mut files: Vec<(PathBuf, String, Vec<u8>)> = Vec::new();
        for i in 0..48u64 {
            let len = 100 * 1024 + (i as usize); // vary length so boundaries shift
            let mut data = vec![0u8; len];
            let mut x = 0xa5a5_0000_0000_0001u64.wrapping_add(i.wrapping_mul(0x9e3779b97f4a7c15));
            for b in data.iter_mut() {
                x ^= x << 13;
                x ^= x >> 7;
                x ^= x << 17;
                *b = (x & 0xff) as u8;
            }
            let name = format!("packed/file_{i:03}.bin");
            let path = src.join(format!("file_{i:03}.bin"));
            std::fs::write(&path, &data).unwrap();
            files.push((path, name, data));
        }

        let mut vault = VaultV3::open(&vp, PW).unwrap();
        let sources: Vec<(PathBuf, String)> = files
            .iter()
            .map(|(p, n, _)| (p.clone(), n.clone()))
            .collect();
        VaultV3::add_files(&mut vault, &sources).unwrap();

        // The pack must have split into multiple chunks AND at least one member
        // must span >1 chunk (i.e. a real cross-boundary windowed extract).
        assert!(
            vault.manifest.chunks.len() >= 2,
            "packed set should chunk into >= 2 blocks, got {}",
            vault.manifest.chunks.len()
        );
        assert!(
            vault.manifest.entries.iter().any(|e| e.chunks.len() >= 2),
            "at least one packed file must straddle a chunk boundary"
        );

        let out = scratch_dir();
        VaultV3::extract_all(&vault, &out).unwrap();
        for (_, name, data) in &files {
            assert_eq!(
                &std::fs::read(out.join(name)).unwrap(),
                data,
                "packed cross-chunk file {name} must round-trip byte-identically"
            );
        }

        std::fs::remove_file(&vp).ok();
        std::fs::remove_dir_all(&src).ok();
        std::fs::remove_dir_all(&out).ok();
    }

    #[test]
    fn probe_classifies_compressible_and_random() {
        // Highly repetitive text shrinks well past the threshold.
        let text = b"the quick brown fox jumps over the lazy dog. ".repeat(4096);
        assert!(!probe_incompressible(&text));

        // High-entropy bytes do not shrink: stored raw.
        let mut noise = vec![0u8; 256 * 1024];
        let mut x = 0x243f6a8885a308d3u64;
        for b in noise.iter_mut() {
            x ^= x << 13;
            x ^= x >> 7;
            x ^= x << 17;
            *b = (x & 0xff) as u8;
        }
        assert!(probe_incompressible(&noise));

        // Empty input is never "incompressible".
        assert!(!probe_incompressible(&[]));
    }

    #[test]
    fn probe_does_not_let_noisy_prefix_hide_large_compressible_chunk() {
        let mut chunk = b"AeroVault representative probe body. ".repeat(80_000);
        let mut x = 0x9e3779b97f4a7c15u64;
        for b in chunk[..INCOMPRESSIBLE_PROBE_SAMPLE].iter_mut() {
            x ^= x << 13;
            x ^= x >> 7;
            x ^= x << 17;
            *b = (x & 0xff) as u8;
        }

        assert!(chunk.len() > INCOMPRESSIBLE_PROBE_MAX_SAMPLE);
        assert!(
            !probe_incompressible(&chunk),
            "a noisy prefix must not force a large compressible chunk to raw"
        );
    }

    #[test]
    fn probe_still_stores_large_high_entropy_chunks_raw() {
        let mut noise = vec![0u8; INCOMPRESSIBLE_PROBE_MAX_SAMPLE * 2];
        let mut x = 0x6a09e667f3bcc909u64;
        for b in noise.iter_mut() {
            x ^= x << 13;
            x ^= x >> 7;
            x ^= x << 17;
            *b = (x & 0xff) as u8;
        }

        assert!(probe_incompressible(&noise));
    }

    #[test]
    fn incompressible_chunks_store_raw_and_round_trip() {
        let vp = vault_path();
        VaultV3::create(&CreateOptionsV3::new(&vp, PW)).unwrap();
        let src = scratch_dir();

        // Compressible file (>CDC threshold so it takes the per-file path).
        let text = src.join("text.txt");
        let text_payload = b"AeroVault incompressible-skip round trip. ".repeat(12_000);
        std::fs::write(&text, &text_payload).unwrap();

        // Incompressible file: high-entropy, also above the threshold.
        let noise = src.join("noise.bin");
        let mut noise_payload = vec![0u8; PACK_SMALL_FILE_THRESHOLD + 500_000];
        let mut x = 0xdeadbeefcafef00du64;
        for b in noise_payload.iter_mut() {
            x ^= x << 13;
            x ^= x >> 7;
            x ^= x << 17;
            *b = (x & 0xff) as u8;
        }
        std::fs::write(&noise, &noise_payload).unwrap();

        let mut vault = VaultV3::open(&vp, PW).unwrap();
        VaultV3::add_files(
            &mut vault,
            &[
                (text.clone(), "text.txt".to_string()),
                (noise.clone(), "noise.bin".to_string()),
            ],
        )
        .unwrap();

        // Both representations must be present: the noise chunks are stored raw,
        // the text chunks are compressed.
        let any_raw = vault.manifest.chunks.values().any(|c| c.stored_raw);
        let any_compressed = vault.manifest.chunks.values().any(|c| !c.stored_raw);
        assert!(
            any_raw,
            "incompressible file should store at least one raw chunk"
        );
        assert!(
            any_compressed,
            "compressible file should store at least one zstd chunk"
        );
        // A raw chunk never stores more than its plaintext.
        for c in vault.manifest.chunks.values().filter(|c| c.stored_raw) {
            assert_eq!(c.compressed_len, c.plaintext_len);
        }

        // Decode honours the flag: both files come back byte-identical.
        let out = scratch_dir();
        VaultV3::extract_all(&vault, &out).unwrap();
        assert_eq!(std::fs::read(out.join("text.txt")).unwrap(), text_payload);
        assert_eq!(std::fs::read(out.join("noise.bin")).unwrap(), noise_payload);

        std::fs::remove_file(&vp).ok();
        std::fs::remove_dir_all(&src).ok();
        std::fs::remove_dir_all(&out).ok();
    }

    #[test]
    fn plaintext_lane_round_trip_and_unencrypted_storage() {
        // `.aerovz` (#7): no password, content + manifest stored unencrypted,
        // still compressed (+ EC available). create_empty_vault + add + extract.
        let vp = vault_path();
        VaultV3::create(&CreateOptionsV3::new_plaintext(&vp)).unwrap();
        assert!(VaultV3::is_vault_v3(&vp));

        let src = scratch_dir();
        // A small (packed) file and a large compressible file (per-file CDC path).
        let small = src.join("note.txt");
        std::fs::write(&small, b"plaintext archive note").unwrap();
        let big = src.join("big.txt");
        let big_payload = b"Aerovz plaintext compressible body. ".repeat(20_000);
        std::fs::write(&big, &big_payload).unwrap();

        // Opens without any password (auto-detected via the header flag).
        let mut vault = VaultV3::open_plaintext(&vp).unwrap();
        assert!(vault.header.flags & FLAG_PLAINTEXT_CONTENT != 0);
        assert!(manifest_is_plaintext(&vault.manifest));
        VaultV3::add_files(
            &mut vault,
            &[
                (small.clone(), "note.txt".to_string()),
                (big.clone(), "big.txt".to_string()),
            ],
        )
        .unwrap();
        drop(vault);

        // Reopen and extract byte-identical.
        let vault = VaultV3::open_plaintext(&vp).unwrap();
        let out = scratch_dir();
        VaultV3::extract_all(&vault, &out).unwrap();
        assert_eq!(
            std::fs::read(out.join("note.txt")).unwrap(),
            b"plaintext archive note"
        );
        assert_eq!(std::fs::read(out.join("big.txt")).unwrap(), big_payload);

        // The data section is genuinely unencrypted: the compressed body of the
        // large file zstd-decodes straight off disk WITHOUT any key. We find the
        // big file's first stored block and decompress it.
        let raw = std::fs::read(&vp).unwrap();
        let big_entry = vault
            .manifest
            .entries
            .iter()
            .find(|e| e.path == "big.txt")
            .unwrap();
        let first_id = big_entry.chunks.first().unwrap();
        let rec = vault.manifest.chunks.get(first_id).unwrap();
        // `data_offset` is relative to the data section, which starts at
        // DATA_OFFSET in the file; +8 skips the block length prefix.
        let start = DATA_OFFSET as usize + rec.data_offset as usize + 8;
        let block = &raw[start..start + rec.block_len as usize];
        let decoded = zstd::stream::decode_all(block).unwrap();
        assert!(
            big_payload.starts_with(&decoded),
            "plaintext-lane block must zstd-decode off disk with no key"
        );

        // A plaintext archive has no password to change.
        let mut vault = VaultV3::open_plaintext(&vp).unwrap();
        assert!(VaultV3::change_password(&mut vault, "irrelevant-pw-123").is_err());

        std::fs::remove_file(&vp).ok();
        std::fs::remove_dir_all(&src).ok();
        std::fs::remove_dir_all(&out).ok();
    }

    #[test]
    fn create_options_decouple_zstd_level_from_cdc_bounds() {
        let vp = vault_path();
        let opts = CreateOptionsV3::new_plaintext(&vp)
            .with_zstd_level(19)
            .with_cdc_bounds(CdcBounds::defaults());
        VaultV3::create(&opts).unwrap();

        let vault = VaultV3::open_plaintext(&vp).unwrap();
        let bounds = manifest_cdc_bounds(&vault.manifest).unwrap();
        let defaults = CdcBounds::defaults();
        assert_eq!(manifest_zstd_level(&vault.manifest), 19);
        assert_eq!(bounds.min, defaults.min);
        assert_eq!(bounds.avg, defaults.avg);
        assert_eq!(bounds.max, defaults.max);

        std::fs::remove_file(&vp).ok();
    }

    #[test]
    fn plaintext_lane_stored_raw_composition() {
        // stored_raw (#10-B) composes with the plaintext lane: an incompressible
        // chunk is stored BOTH raw AND unencrypted, and still round-trips.
        let vp = vault_path();
        VaultV3::create(&CreateOptionsV3::new_plaintext(&vp)).unwrap();
        let src = scratch_dir();
        let noise = src.join("noise.bin");
        let mut noise_payload = vec![0u8; PACK_SMALL_FILE_THRESHOLD + 400_000];
        let mut x = 0x1234_5678_9abc_def0u64;
        for b in noise_payload.iter_mut() {
            x ^= x << 13;
            x ^= x >> 7;
            x ^= x << 17;
            *b = (x & 0xff) as u8;
        }
        std::fs::write(&noise, &noise_payload).unwrap();

        let mut vault = VaultV3::open_plaintext(&vp).unwrap();
        VaultV3::add_files(&mut vault, &[(noise.clone(), "noise.bin".to_string())]).unwrap();
        assert!(
            vault.manifest.chunks.values().any(|c| c.stored_raw),
            "incompressible input should store raw chunks"
        );
        let out = scratch_dir();
        VaultV3::extract_all(&vault, &out).unwrap();
        assert_eq!(std::fs::read(out.join("noise.bin")).unwrap(), noise_payload);

        std::fs::remove_file(&vp).ok();
        std::fs::remove_dir_all(&src).ok();
        std::fs::remove_dir_all(&out).ok();
    }

    #[test]
    #[cfg(feature = "test-vectors")]
    fn plaintext_empty_archive_is_deterministic() {
        // The plaintext lane has zero randomness (no salt, no random keys, fixed
        // public MAC key) and, under `test-vectors`, a fixed timestamp — so an
        // empty `.aerovz` is byte-deterministic. Freeze its digest to catch any
        // accidental layout drift in the plaintext header/manifest path.
        let vp = vault_path();
        VaultV3::create(&CreateOptionsV3::new_plaintext(&vp)).unwrap();
        let bytes = std::fs::read(&vp).unwrap();
        let digest = blake3::hash(&bytes).to_hex().to_string();
        let vp2 = vault_path();
        VaultV3::create(&CreateOptionsV3::new_plaintext(&vp2)).unwrap();
        assert_eq!(
            digest,
            blake3::hash(&std::fs::read(&vp2).unwrap())
                .to_hex()
                .to_string(),
            "empty plaintext archive must be byte-deterministic"
        );
        std::fs::remove_file(&vp).ok();
        std::fs::remove_file(&vp2).ok();
    }

    #[derive(Default)]
    struct CountingSink {
        chunks_new: u64,
        chunks_dedup: u64,
        files_packed: u64,
        files_unpacked: u64,
        packs: u64,
        cdc_set: bool,
        steps: Vec<String>,
        plaintext: u64,
    }

    impl super::super::telemetry::VaultTelemetrySink
        for std::sync::Arc<std::sync::Mutex<CountingSink>>
    {
        fn on_chunk(&mut self, is_new: bool, plaintext: u64, _c: u64, _e: u64) {
            let mut g = self.lock().unwrap();
            if is_new {
                g.chunks_new += 1;
            } else {
                g.chunks_dedup += 1;
            }
            g.plaintext += plaintext;
        }
        fn on_file(&mut self, packed: bool) {
            let mut g = self.lock().unwrap();
            if packed {
                g.files_packed += 1;
            } else {
                g.files_unpacked += 1;
            }
        }
        fn on_pack(&mut self) {
            self.lock().unwrap().packs += 1;
        }
        fn set_cdc(&mut self, _min: usize, _avg: usize, _max: usize) {
            self.lock().unwrap().cdc_set = true;
        }
        fn step(&mut self, message: &str) {
            self.lock().unwrap().steps.push(message.to_string());
        }
    }

    #[test]
    fn telemetry_sink_receives_content_pipeline_events() {
        // An attached sink must observe the same events the app historically
        // inlined: per-chunk, per-file (packed vs per-file), per-pack, CDC bounds,
        // and step lines. With no sink the bytes are unchanged (T5 golden).
        let vp = vault_path();
        VaultV3::create(&CreateOptionsV3::new(&vp, PW)).unwrap();
        let src = scratch_dir();
        // Two small files (packed path) + one large file (per-file CDC path).
        std::fs::write(src.join("s1.txt"), b"small one").unwrap();
        std::fs::write(src.join("s2.txt"), b"small two differs").unwrap();
        let large = src.join("big.bin");
        let mut payload = vec![0u8; PACK_SMALL_FILE_THRESHOLD + 200_000];
        let mut x = 0xfeed_face_dead_beefu64;
        for b in payload.iter_mut() {
            x ^= x << 13;
            x ^= x >> 7;
            x ^= x << 17;
            *b = (x & 0xff) as u8;
        }
        std::fs::write(&large, &payload).unwrap();

        let sink = std::sync::Arc::new(std::sync::Mutex::new(CountingSink::default()));
        let mut vault = VaultV3::open(&vp, PW).unwrap();
        vault.set_telemetry_sink(Box::new(sink.clone()));
        VaultV3::add_files(
            &mut vault,
            &[
                (src.join("s1.txt"), "s1.txt".to_string()),
                (src.join("s2.txt"), "s2.txt".to_string()),
                (large.clone(), "big.bin".to_string()),
            ],
        )
        .unwrap();
        drop(vault);

        let g = sink.lock().unwrap();
        assert!(g.cdc_set, "CDC bounds reported");
        assert_eq!(g.packs, 1, "one pack for the two small files");
        assert_eq!(g.files_packed, 2, "two small files via the packed path");
        assert_eq!(g.files_unpacked, 1, "one large file via the per-file path");
        assert!(
            g.chunks_new >= 2,
            "at least the pack chunk + a large-file chunk"
        );
        assert!(
            g.steps.iter().any(|s| s.starts_with("scan:"))
                && g.steps.iter().any(|s| s.starts_with("partition:"))
                && g.steps.iter().any(|s| s.starts_with("pack:")),
            "scan / partition / pack step lines present: {:?}",
            g.steps
        );
        assert!(g.plaintext > 0);

        std::fs::remove_file(&vp).ok();
        std::fs::remove_dir_all(&src).ok();
    }

    #[test]
    fn dedup_same_content_stored_once() {
        let vp = vault_path();
        VaultV3::create(&CreateOptionsV3::new(&vp, PW)).unwrap();
        let src = scratch_dir();
        // Large identical content under two names -> CDC path -> deduped chunks.
        let mut payload = vec![0u8; PACK_SMALL_FILE_THRESHOLD + 300_000];
        let mut x = 0x1234_5678_9abc_def0u64;
        for b in payload.iter_mut() {
            x ^= x << 13;
            x ^= x >> 7;
            x ^= x << 17;
            *b = (x & 0xff) as u8;
        }
        let f1 = src.join("one.bin");
        let f2 = src.join("two.bin");
        std::fs::write(&f1, &payload).unwrap();
        std::fs::write(&f2, &payload).unwrap();

        let mut vault = VaultV3::open(&vp, PW).unwrap();
        VaultV3::add_files(
            &mut vault,
            &[
                (f1.clone(), "one.bin".to_string()),
                (f2.clone(), "two.bin".to_string()),
            ],
        )
        .unwrap();

        // Two entries, but the logical chunk references exceed the stored chunks.
        let entries = &vault.manifest.entries;
        let total_refs: usize = entries.iter().map(|e| e.chunks.len()).sum();
        let stored = vault.manifest.chunks.len();
        assert!(total_refs > stored, "dedup must collapse identical content");
        // Both files reference the exact same chunk id set.
        let c1: Vec<&String> = entries
            .iter()
            .find(|e| e.path == "one.bin")
            .unwrap()
            .chunks
            .iter()
            .collect();
        let c2: Vec<&String> = entries
            .iter()
            .find(|e| e.path == "two.bin")
            .unwrap()
            .chunks
            .iter()
            .collect();
        assert_eq!(c1, c2);

        std::fs::remove_file(&vp).ok();
        std::fs::remove_dir_all(&src).ok();
    }

    #[test]
    fn copy_reuses_chunks_move_rename_delete() {
        let vp = vault_path();
        VaultV3::create(&CreateOptionsV3::new(&vp, PW)).unwrap();
        let src = scratch_dir();
        std::fs::write(src.join("doc.txt"), b"hello world copy").unwrap();

        let mut vault = VaultV3::open(&vp, PW).unwrap();
        VaultV3::create_directory(&mut vault, "src").unwrap();
        VaultV3::add_files(
            &mut vault,
            &[(src.join("doc.txt"), "src/doc.txt".to_string())],
        )
        .unwrap();

        let chunks_before = vault.manifest.chunks.len();
        VaultV3::copy_entry(&mut vault, "src/doc.txt", "src/doc-copy.txt").unwrap();
        // Copy reuses chunk records: no new chunks stored.
        assert_eq!(vault.manifest.chunks.len(), chunks_before);
        assert!(VaultV3::list(&vault)
            .iter()
            .any(|e| e.path == "src/doc-copy.txt"));

        // Move directory updates descendants.
        VaultV3::move_entry(&mut vault, "src", "moved").unwrap();
        let paths: Vec<String> = VaultV3::list(&vault).into_iter().map(|e| e.path).collect();
        assert!(paths.contains(&"moved".to_string()));
        assert!(paths.contains(&"moved/doc.txt".to_string()));
        assert!(!paths.iter().any(|p| p.starts_with("src")));

        // Rename within parent.
        VaultV3::rename_entry(&mut vault, "moved/doc.txt", "renamed.txt").unwrap();
        assert!(VaultV3::list(&vault)
            .iter()
            .any(|e| e.path == "moved/renamed.txt"));

        // Delete then re-open round-trips.
        VaultV3::delete_entries(&mut vault, &["moved".to_string()], true).unwrap();
        assert!(VaultV3::list(&vault).is_empty());
        drop(vault);

        let reopened = VaultV3::open(&vp, PW).unwrap();
        assert!(VaultV3::list(&reopened).is_empty());

        std::fs::remove_file(&vp).ok();
        std::fs::remove_dir_all(&src).ok();
    }

    #[test]
    fn change_password_old_fails_new_opens() {
        let vp = vault_path();
        VaultV3::create(&CreateOptionsV3::new(&vp, "old-password-123")).unwrap();
        let src = scratch_dir();
        std::fs::write(src.join("x.txt"), b"keep me").unwrap();

        let mut vault = VaultV3::open(&vp, "old-password-123").unwrap();
        VaultV3::add_files(&mut vault, &[(src.join("x.txt"), "x.txt".to_string())]).unwrap();
        VaultV3::change_password(&mut vault, "new-password-456").unwrap();
        drop(vault);

        assert!(VaultV3::open(&vp, "old-password-123").is_err());
        let v2 = VaultV3::open(&vp, "new-password-456").unwrap();
        assert!(VaultV3::list(&v2).iter().any(|e| e.path == "x.txt"));

        std::fs::remove_file(&vp).ok();
        std::fs::remove_dir_all(&src).ok();
    }

    #[test]
    fn add_directory_recursive_round_trip() {
        let vp = vault_path();
        VaultV3::create(&CreateOptionsV3::new(&vp, PW)).unwrap();
        let tree = scratch_dir();
        std::fs::create_dir_all(tree.join("nested/deep")).unwrap();
        std::fs::write(tree.join("top.txt"), b"top file").unwrap();
        std::fs::write(tree.join("nested/mid.txt"), b"mid file").unwrap();
        std::fs::write(tree.join("nested/deep/bottom.txt"), b"bottom file").unwrap();

        let mut vault = VaultV3::open(&vp, PW).unwrap();
        let (files, _dirs) = VaultV3::add_directory(&mut vault, &tree, Some("imported")).unwrap();
        assert_eq!(files, 3);

        let out = scratch_dir();
        VaultV3::extract_all(&vault, &out).unwrap();
        assert_eq!(
            std::fs::read(out.join("imported/top.txt")).unwrap(),
            b"top file"
        );
        assert_eq!(
            std::fs::read(out.join("imported/nested/deep/bottom.txt")).unwrap(),
            b"bottom file"
        );

        std::fs::remove_file(&vp).ok();
        std::fs::remove_dir_all(&tree).ok();
        std::fs::remove_dir_all(&out).ok();
    }

    #[test]
    fn path_normalization_rejects_traversal() {
        assert!(normalize_vault_relative_path("..").is_err());
        assert!(normalize_vault_relative_path("../etc/passwd").is_err());
        assert!(normalize_vault_relative_path("a/../b").is_err());
        assert!(normalize_vault_relative_path("a/./b").is_err());
        assert!(normalize_vault_relative_path("a\\b").is_err());
        assert!(normalize_vault_relative_path("C:\\x").is_err());
        assert!(normalize_vault_relative_path("a/b/c").is_ok());
        // Faithful to the app: leading '/' is trimmed, not rejected, so an
        // absolute-looking path normalizes to a vault-relative one.
        assert_eq!(
            normalize_vault_relative_path("/etc/passwd").unwrap(),
            "etc/passwd"
        );
    }

    #[test]
    fn extract_rejects_crafted_traversal_entry() {
        // No crypto / no Argon2: craft an OpenVaultV3 by hand with a malicious
        // manifest path and prove extract refuses it via normalization.
        let mut manifest = empty_manifest(DEFAULT_ZSTD_LEVEL);
        manifest.entries.push(ManifestEntryV3 {
            path: "../escape.txt".to_string(),
            size: 0,
            modified: now_iso(),
            is_dir: false,
            chunks: Vec::new(),
            pack_offset: None,
        });
        let vault = OpenVaultV3 {
            path: PathBuf::from("/tmp/none.aerovault"),
            header: VaultHeaderV3 {
                flags: 0,
                salt: [0u8; SALT_SIZE],
                wrapped_master_key: [0u8; crate::aerocrypt::WRAPPED_KEY_SIZE],
                wrapped_mac_key: [0u8; crate::aerocrypt::WRAPPED_KEY_SIZE],
                data_offset: DATA_OFFSET,
                data_len: 0,
                manifest_offset: DATA_OFFSET,
                manifest_len: 0,
                extension_dir_offset: DATA_OFFSET,
                extension_dir_len: 0,
                extension_payload_offset: DATA_OFFSET,
                extension_payload_len: 0,
                wrapper_header_version: 1,
                header_mac: [0u8; MAC_SIZE],
            },
            opened_file_len: 0,
            opened_header_mac: [0u8; MAC_SIZE],
            master_key: [0u8; KEY_SIZE],
            mac_key: [0u8; KEY_SIZE],
            manifest,
            extensions: Vec::new(),
            data: Vec::new(),
            manifest_repaired_on_open: false,
            header_repaired_on_open: false,
            telemetry: None,
        };
        let out = scratch_dir();
        assert!(VaultV3::extract_entry(&vault, "../escape.txt", &out).is_err());
        std::fs::remove_dir_all(&out).ok();
    }

    /// Audit M2 regression: a pre-planted intermediate reparse point in the
    /// destination (a directory that is really a junction/symlink to a sibling
    /// "victim") must not let extraction write decrypted plaintext outside the
    /// chosen root. Build a real sealed vault with a nested entry `sub/secret.txt`,
    /// plant `dest/sub -> victim`, then assert `extract_all` fails closed and the
    /// victim directory stays empty. (Junctions need no admin on Windows.)
    #[test]
    fn extract_refuses_planted_reparse_point_parent() {
        let vp = vault_path();
        VaultV3::create(&CreateOptionsV3::new(&vp, PW)).unwrap();

        let src = scratch_dir();
        let secret = src.join("secret.txt");
        let secret_bytes = b"TOP SECRET PLAINTEXT THAT MUST STAY CONTAINED";
        std::fs::write(&secret, secret_bytes).unwrap();

        let mut vault = VaultV3::open(&vp, PW).unwrap();
        VaultV3::add_files(
            &mut vault,
            &[(secret.clone(), "sub/secret.txt".to_string())],
        )
        .unwrap();

        let dest = scratch_dir();
        let victim = scratch_dir();
        // Plant `dest/sub` as a reparse point pointing at `victim`.
        let link = dest.join("sub");
        let planted = plant_dir_reparse_point(&link, &victim);
        if !planted {
            // Environment cannot create a junction/symlink (e.g. Developer Mode off and
            // no junction support); skip rather than give a false pass.
            eprintln!("skipping extract_refuses_planted_reparse_point_parent: no reparse support");
            std::fs::remove_dir_all(&dest).ok();
            std::fs::remove_dir_all(&victim).ok();
            std::fs::remove_file(&vp).ok();
            return;
        }

        let result = VaultV3::extract_all(&vault, &dest);
        assert!(
            result.is_err(),
            "extract must fail closed on a planted reparse-point parent, got {result:?}"
        );
        // The decrypted plaintext must NOT have been written through the junction.
        assert!(
            !victim.join("secret.txt").exists(),
            "plaintext escaped the destination root into the victim directory"
        );

        std::fs::remove_dir_all(&dest).ok();
        std::fs::remove_dir_all(&victim).ok();
        std::fs::remove_dir_all(&src).ok();
        std::fs::remove_file(&vp).ok();
    }

    /// Audit M4: a forged extension directory (duplicate id, or a payload slice that
    /// escapes the authenticated extension payload, or a critical extension) must be
    /// rejected at validation time. The header MAC covers the directory offset/len but
    /// not its bytes, so this is the open-time fail-closed gate.
    #[test]
    fn validate_extension_dir_rejects_forged_entries() {
        let ok = ExtensionEntryV3 {
            extension_id: "error-correction.reed-solomon".to_string(),
            algorithm_id: "rs".to_string(),
            algorithm_version: 1,
            critical: false,
            offset: 0,
            length: 100,
        };
        assert!(validate_extension_dir(std::slice::from_ref(&ok), 100).is_ok());

        // Payload slice escapes the declared extension-payload length.
        let mut oob = ok.clone();
        oob.length = 101;
        assert!(validate_extension_dir(std::slice::from_ref(&oob), 100).is_err());

        // offset + length overflow.
        let mut overflow = ok.clone();
        overflow.offset = u64::MAX;
        overflow.length = 1;
        assert!(validate_extension_dir(std::slice::from_ref(&overflow), 100).is_err());

        // Duplicate extension ids.
        assert!(validate_extension_dir(&[ok.clone(), ok.clone()], 1000).is_err());

        // Critical (unknown) extension is rejected.
        let mut critical = ok.clone();
        critical.critical = true;
        assert!(validate_extension_dir(std::slice::from_ref(&critical), 100).is_err());
    }

    /// Audit M2 residual (controaudit): the single-entry `extract_entry` directory
    /// path builds its subtree root from a manifest-derived basename. A pre-planted
    /// junction at `dest/<basename>` must be refused, not followed into a victim.
    #[test]
    fn extract_entry_dir_refuses_planted_output_root_junction() {
        let vp = vault_path();
        VaultV3::create(&CreateOptionsV3::new(&vp, PW)).unwrap();

        let src = scratch_dir();
        let secret = src.join("secret.txt");
        std::fs::write(&secret, b"TOP SECRET PLAINTEXT THAT MUST STAY CONTAINED").unwrap();
        let mut vault = VaultV3::open(&vp, PW).unwrap();
        VaultV3::add_files(
            &mut vault,
            &[(secret.clone(), "sub/secret.txt".to_string())],
        )
        .unwrap();

        let dest = scratch_dir(); // exists & is a dir -> output_root = dest/sub
        let victim = scratch_dir();
        let link = dest.join("sub"); // the manifest-derived basename component
        if !plant_dir_reparse_point(&link, &victim) {
            eprintln!("skipping extract_entry_dir_refuses_planted_output_root_junction: no reparse support");
            std::fs::remove_dir_all(&dest).ok();
            std::fs::remove_dir_all(&victim).ok();
            std::fs::remove_file(&vp).ok();
            return;
        }

        let result = VaultV3::extract_entry(&vault, "sub", &dest);
        assert!(
            result.is_err(),
            "extract_entry must fail closed on a planted output_root junction, got {result:?}"
        );
        assert!(
            !victim.join("secret.txt").exists(),
            "plaintext escaped into the victim via extract_entry"
        );

        std::fs::remove_dir_all(&dest).ok();
        std::fs::remove_dir_all(&victim).ok();
        std::fs::remove_dir_all(&src).ok();
        std::fs::remove_file(&vp).ok();
    }

    /// Plant `link` as a directory reparse point targeting `target`. Returns false
    /// if the platform/environment cannot create one (caller then skips).
    #[cfg(windows)]
    fn plant_dir_reparse_point(link: &Path, target: &Path) -> bool {
        // `mklink /J` creates a directory junction and needs no admin / Developer Mode.
        let status = std::process::Command::new("cmd")
            .args(["/c", "mklink", "/J"])
            .arg(link)
            .arg(target)
            .stdout(std::process::Stdio::null())
            .stderr(std::process::Stdio::null())
            .status();
        matches!(status, Ok(s) if s.success()) && link.exists()
    }

    #[cfg(not(windows))]
    fn plant_dir_reparse_point(link: &Path, target: &Path) -> bool {
        std::os::unix::fs::symlink(target, link).is_ok() && link.exists()
    }
}