zipatch_rs/index/

builder.rs

//! Multi-patch plan builder.
//!
//! [`PlanBuilder`] consumes one or more [`ZiPatchReader`]s in chain order via
//! [`PlanBuilder::add_patch`] and produces a single [`Plan`] describing the
//! end state. Mid-chain destructive operations — `SqpkFile::RemoveAll`,
//! `SqpkFile::DeleteFile`, and `SqpkFile::AddFile` at `file_offset == 0` —
//! retroactively drop accumulated regions from earlier patches so that the
//! returned plan reflects only the writes that survive.

use std::collections::HashMap;
use std::io::Read;

use crate::apply::path::expansion_folder_id;
use crate::chunk::sqpk::add_data::SqpkAddData;
use crate::chunk::{
    Chunk, SqpackFileId, SqpkCommand, SqpkFile, SqpkFileOperation, SqpkHeader, SqpkHeaderTarget,
    TargetHeaderKind, ZiPatchReader,
};
use crate::newtypes::PatchIndex;
use crate::{IndexError, IndexResult as Result, Platform};
use tracing::{info, info_span, trace};

use super::plan::{
    FilesystemOp, PartExpected, PartSource, PatchRef, PatchSourceKind, PatchType, Plan, Region,
    Target, TargetPath,
};
use super::region_map;

// Offset of a SQPK sub-command body from the start of the SQPK chunk body
// (the body starts with `[inner_size: i32 BE][sub_cmd: u8]` = 5 bytes).
const SQPK_SUB_CMD_BODY_OFFSET: u64 = 5;

// Offset of `header_data` from the start of a SqpkHeader sub-command body.
// Layout: file_kind(1) + header_kind(1) + pad(1) + main_id(2) + sub_id(2) + file_id(4).
const SQPK_HEADER_DATA_OFFSET: u64 = 11;

/// Reject a relative path that escapes the install root.
///
/// The indexed builder is a natural choke point for path-traversal checks: it
/// owns every `Generic` path that enters a plan, plus every relative path
/// fed to a [`FilesystemOp`]. The sequential apply path does not currently
/// enforce this guard — a malicious patch supplying `../../etc/passwd` would
/// land bytes outside the install root — but the indexed plan refuses to
/// build at all, surfacing the bad path at construction time rather than
/// apply time. `SqPack`-encoded targets are structurally constrained by
/// their numeric `(main_id, sub_id, file_id)` triple and skip this check.
///
/// Rejects:
/// - empty path components and `..` components anywhere in the path,
/// - absolute Unix paths (leading `/`),
/// - Windows drive-letter prefixes (`C:\`, `c:/`, etc.).
fn reject_unsafe_relative_path(path: &str) -> Result<()> {
    if path.starts_with('/') || path.starts_with('\\') {
        return Err(IndexError::UnsafeTargetPath(path.to_owned()));
    }
    // Windows drive letter: `[A-Za-z]:` followed by `/` or `\`, or just `[A-Za-z]:`
    // at minimum (`C:` alone is still absolute on Windows).
    let bytes = path.as_bytes();
    if bytes.len() >= 2 && bytes[1] == b':' && bytes[0].is_ascii_alphabetic() {
        return Err(IndexError::UnsafeTargetPath(path.to_owned()));
    }
    for component in path.split(['/', '\\']) {
        if component == ".." {
            return Err(IndexError::UnsafeTargetPath(path.to_owned()));
        }
    }
    Ok(())
}

// Largest `units` value whose `units * 128` byte length still fits in
// `Region::length: u32`. Used by `push_empty_block_region` to split a single
// huge EmptyBlock into a capped (header-bearing) region plus trailing Zeros
// fillers; see the function body for the byte-equivalence asterisk this
// implies for `units >= 2^25`.
const MAX_UNITS_PER_REGION: u32 = u32::MAX / 128; // 0x01FF_FFFF

/// Accumulating builder for a multi-patch [`Plan`].
///
/// Construct via [`PlanBuilder::new`], feed each patch in chain order via
/// [`PlanBuilder::add_patch`], then consume with [`PlanBuilder::finish`].
/// For a one-shot single-patch build, the three-line dance
/// `PlanBuilder::new().add_patch(name, reader)?.finish()` (the `add_patch`
/// call returning `&mut Self` is not supported — use a `let mut`) is the
/// canonical form; there is no freestanding convenience wrapper.
#[derive(Debug)]
pub struct PlanBuilder {
    state: BuilderState,
}

impl Default for PlanBuilder {
    fn default() -> Self {
        Self::new()
    }
}

impl PlanBuilder {
    /// Start a new, empty builder.
    #[must_use]
    pub fn new() -> Self {
        Self {
            state: BuilderState::new(),
        }
    }

    /// Read `reader` to completion, appending the patch to the chain.
    ///
    /// Mid-chain destructive ops (`RemoveAll`, `DeleteFile`,
    /// `AddFile@file_offset=0`) retroactively prune accumulated regions from
    /// earlier patches at this point.
    ///
    /// # Errors
    ///
    /// - [`IndexError::DuplicatePatch`] if `name` matches a patch already
    ///   added to this builder. The chain protocol is order-sensitive; adding
    ///   the same patch twice is almost always a caller bug.
    /// - Any parser error surfaced by `reader.next_chunk()`.
    ///
    /// # Panics
    ///
    /// Panics if the chain grows past `u32::MAX` patches.
    pub fn add_patch<R: Read>(
        &mut self,
        name: impl Into<String>,
        mut reader: ZiPatchReader<R>,
    ) -> Result<()> {
        let name = name.into();
        let span = info_span!(crate::tracing_schema::span_names::BUILD_PLAN_PATCH, patch = %name);
        let _enter = span.enter();
        self.state.begin_patch(name)?;
        let mut chunks: usize = 0;
        while let Some(rec) = reader.next_chunk()? {
            self.state.consume_chunk(rec.chunk, rec.body_offset)?;
            chunks += 1;
        }
        info!(
            chunks,
            targets = self.state.target_order.len(),
            fs_ops = self.state.fs_ops.len(),
            "plan: patch consumed"
        );
        Ok(())
    }

    /// Consume the builder and return the accumulated [`Plan`].
    ///
    /// Emits a single `info!` summary event carrying the final patch / target /
    /// region / `fs_op` counts so a subscriber sees one completion record per
    /// fully-built plan regardless of how many `add_patch` calls fed it.
    #[must_use]
    pub fn finish(self) -> Plan {
        let plan = self.state.finalize();
        let region_count: usize = plan.targets.iter().map(|t| t.regions.len()).sum();
        info!(
            patches = plan.patches.len(),
            targets = plan.targets.len(),
            regions = region_count,
            fs_ops = plan.fs_ops.len(),
            "plan: built"
        );
        plan
    }
}

#[derive(Debug)]
struct BuilderState {
    platform: Platform,
    patches: Vec<PatchRef>,
    // Index of the patch currently being consumed; set by begin_patch and read
    // when constructing PartSource::Patch values.
    current_patch: PatchIndex,
    fs_ops: Vec<FilesystemOp>,
    targets: HashMap<TargetPath, Vec<Region>>,
    target_order: Vec<TargetPath>,
}

impl BuilderState {
    fn new() -> Self {
        Self {
            platform: Platform::Win32,
            patches: Vec::new(),
            current_patch: PatchIndex::new(0),
            fs_ops: Vec::new(),
            targets: HashMap::new(),
            target_order: Vec::new(),
        }
    }

    fn begin_patch(&mut self, name: String) -> Result<()> {
        if self.patches.iter().any(|p| p.name == name) {
            return Err(IndexError::DuplicatePatch { name });
        }
        let idx = u32::try_from(self.patches.len()).expect("more than u32::MAX patches");
        self.current_patch = PatchIndex::new(idx);
        self.patches.push(PatchRef {
            name,
            patch_type: None,
        });
        Ok(())
    }

    fn current_patch_ref_mut(&mut self) -> &mut PatchRef {
        let idx = self.current_patch.get() as usize;
        &mut self.patches[idx]
    }

    fn consume_chunk(&mut self, chunk: Chunk, body_offset: u64) -> Result<()> {
        match chunk {
            Chunk::FileHeader(fh) => {
                let pt = PatchType::from_tag(*fh.patch_type());
                self.current_patch_ref_mut().patch_type = Some(pt);
                trace!(version = fh.version(), "plan: file header");
            }
            Chunk::ApplyOption(opt) => {
                trace!(kind = ?opt.kind, value = opt.value, "plan: apply option (ignored in v1)");
            }
            Chunk::ApplyFreeSpace(_) => {
                trace!("plan: apply free space (ignored in v1)");
            }
            Chunk::AddDirectory(ad) => {
                reject_unsafe_relative_path(&ad.name)?;
                self.fs_ops.push(FilesystemOp::EnsureDir(ad.name));
            }
            Chunk::DeleteDirectory(dd) => {
                reject_unsafe_relative_path(&dd.name)?;
                self.fs_ops.push(FilesystemOp::DeleteDir(dd.name));
            }
            Chunk::Sqpk(cmd) => self.consume_sqpk(cmd, body_offset)?,
            // ZiPatchReader consumes `EOF_` internally and never yields it,
            // but the match still has to cover the variant.
            Chunk::EndOfFile => {}
        }
        Ok(())
    }

    fn consume_sqpk(&mut self, cmd: SqpkCommand, body_offset: u64) -> Result<()> {
        match cmd {
            SqpkCommand::TargetInfo(t) => {
                self.platform = match t.platform_id {
                    0 => Platform::Win32,
                    1 => Platform::Ps3,
                    2 => Platform::Ps4,
                    id => Platform::Unknown(id),
                };
                trace!(platform = ?self.platform, "plan: target info");
            }
            SqpkCommand::PatchInfo(_) | SqpkCommand::Index(_) => {
                trace!("plan: SQPK metadata-only chunk (ignored in v1)");
            }
            SqpkCommand::AddData(c) => self.consume_add_data(&c, body_offset),
            SqpkCommand::DeleteData(c) => {
                self.push_empty_block_region(&c.target_file, c.block_offset, c.block_count);
            }
            SqpkCommand::ExpandData(c) => {
                self.push_empty_block_region(&c.target_file, c.block_offset, c.block_count);
            }
            SqpkCommand::Header(c) => self.consume_header(&c, body_offset),
            SqpkCommand::File(c) => self.consume_file(*c, body_offset)?,
        }
        Ok(())
    }

    fn consume_add_data(&mut self, c: &SqpkAddData, body_offset: u64) {
        let data_abs_offset =
            body_offset + SQPK_SUB_CMD_BODY_OFFSET + SqpkAddData::DATA_SOURCE_OFFSET;
        let data_bytes = u32::try_from(c.data_bytes)
            .expect("SqpkAddData::data_bytes is bounded by the parser's 512 MiB chunk size limit");
        let path = dat_target(&c.target_file);
        self.push_region(
            &path,
            Region {
                target_offset: c.block_offset,
                length: data_bytes,
                source: PartSource::Patch {
                    patch_idx: self.current_patch,
                    offset: data_abs_offset,
                    kind: PatchSourceKind::Raw { len: data_bytes },
                    decoded_skip: 0,
                },
                expected: PartExpected::SizeOnly,
            },
        );
        if c.block_delete_number > 0 {
            // `block_delete_number` is wire-decoded as `(raw_u32 << 7)` and so
            // can legally reach ~549 GiB — well beyond `u32::MAX`. The on-disk
            // operation is just zero-fill (see `write_zeros` in
            // `apply/sqpk.rs`) and adjacent `Zeros` regions are
            // semantically equivalent to a single zero run, so split the run
            // into `u32::MAX`-sized chunks instead of widening `Region::length`.
            let mut remaining = c.block_delete_number;
            let mut cursor = c.block_offset + c.data_bytes;
            while remaining > 0 {
                let chunk = u32::try_from(remaining.min(u64::from(u32::MAX)))
                    .expect("clamped to u32::MAX above");
                self.push_region(
                    &path,
                    Region {
                        target_offset: cursor,
                        length: chunk,
                        source: PartSource::Zeros,
                        expected: PartExpected::Zeros,
                    },
                );
                cursor += u64::from(chunk);
                remaining -= u64::from(chunk);
            }
        }
    }

    fn push_empty_block_region(&mut self, target_file: &SqpackFileId, offset: u64, units: u32) {
        let path = dat_target(target_file);
        // `units * 128` is the byte length of the region. For `units` up to
        // `u32::MAX / 128 == 0x01FF_FFFF` this fits in a `u32` and we emit a
        // single `EmptyBlock` region whose applier writes the canonical
        // SqPack empty-block header followed by `units*128 - 20` zero bytes.
        //
        // For `units >= 2^25` the byte count overflows `Region::length: u32`.
        // The wire format permits arbitrary `u32` `block_count` values, even
        // though no real ZiPatch ever uses one that large — guard against the
        // pathological case rather than silently saturating. We split into:
        //   1. One `EmptyBlock { units: cap }` region of `cap*128` bytes
        //      (where `cap = u32::MAX / 128`), so the canonical 20-byte
        //      empty-block header is written exactly as the sequential path
        //      would write it.
        //   2. Successive `u32::MAX`-sized `Zeros` regions covering the
        //      remaining `(units - cap) * 128` bytes.
        //
        // This means the header's `block_number - 1` field reflects only the
        // first capped chunk rather than the full original `units` count —
        // an unavoidable byte-equivalence asterisk for the unreachable
        // `units >= 2^25` case (mirroring the same family of `u32`-width
        // splits already used by `consume_add_data`'s zero-fill path).
        if units <= MAX_UNITS_PER_REGION {
            self.push_region(
                &path,
                Region {
                    target_offset: offset,
                    length: units * 128,
                    source: PartSource::EmptyBlock { units },
                    expected: PartExpected::EmptyBlock { units },
                },
            );
            return;
        }

        let cap = MAX_UNITS_PER_REGION;
        let cap_bytes = u64::from(cap) * 128;
        self.push_region(
            &path,
            Region {
                target_offset: offset,
                length: cap * 128,
                source: PartSource::EmptyBlock { units: cap },
                expected: PartExpected::EmptyBlock { units: cap },
            },
        );

        let total_bytes = u64::from(units) * 128;
        let mut cursor = offset + cap_bytes;
        let mut remaining = total_bytes - cap_bytes;
        while remaining > 0 {
            let chunk = u32::try_from(remaining.min(u64::from(u32::MAX)))
                .expect("clamped to u32::MAX above");
            self.push_region(
                &path,
                Region {
                    target_offset: cursor,
                    length: chunk,
                    source: PartSource::Zeros,
                    expected: PartExpected::Zeros,
                },
            );
            cursor += u64::from(chunk);
            remaining -= u64::from(chunk);
        }
    }

    fn consume_header(&mut self, c: &SqpkHeader, body_offset: u64) {
        let header_abs_offset = body_offset + SQPK_SUB_CMD_BODY_OFFSET + SQPK_HEADER_DATA_OFFSET;
        let target_offset: u64 = match c.header_kind {
            TargetHeaderKind::Version => 0,
            TargetHeaderKind::Index | TargetHeaderKind::Data => 1024,
        };
        let path = match &c.target {
            SqpkHeaderTarget::Dat(f) => dat_target(f),
            SqpkHeaderTarget::Index(f) => index_target(f),
        };
        self.push_region(
            &path,
            Region {
                target_offset,
                length: 1024,
                source: PartSource::Patch {
                    patch_idx: self.current_patch,
                    offset: header_abs_offset,
                    kind: PatchSourceKind::Raw { len: 1024 },
                    decoded_skip: 0,
                },
                expected: PartExpected::SizeOnly,
            },
        );
    }

    fn consume_file(&mut self, c: SqpkFile, body_offset: u64) -> Result<()> {
        // Every SqpkFile op carries a relative path that lands in either a
        // TargetPath::Generic or a FilesystemOp (DeleteFile / MakeDirTree).
        // Reject path-traversal sequences here, before any plan state is mutated,
        // so a malicious `../../...` payload cannot construct a plan that would
        // write outside the install root at apply time.
        reject_unsafe_relative_path(&c.path)?;
        match c.operation {
            SqpkFileOperation::AddFile => {
                // Build the `TargetPath::Generic` once and keep its inner
                // `String` accessible by name so the offset-0 truncate-hint
                // branch can clone it without re-matching on the enum.
                // Pre-polish code matched `&path` with an `unreachable!()` else
                // arm; the unreachability was a *call-site* invariant (the
                // enum was constructed two lines above) rather than a type
                // invariant, so a future refactor that swapped out `Generic`
                // could silently turn the panic into a runtime hazard. Binding
                // `inner_path` to the raw string up front and reconstructing
                // the enum value next to it makes the invariant structural.
                let inner_path: String = c.path;
                let path = TargetPath::Generic(inner_path.clone());
                if c.file_offset == 0 {
                    // AddFile at offset 0 truncates the target. Drop any
                    // accumulated regions from earlier patches and emit a
                    // DeleteFile hint so a stale on-disk file (from outside
                    // the chain, e.g. a pre-existing install) is removed
                    // before the new regions land.
                    self.drop_target(&path);
                    self.fs_ops.push(FilesystemOp::DeleteFile(inner_path));
                }
                let mut cursor = c.file_offset;
                for (i, block) in c.blocks.iter().enumerate() {
                    let block_source_offset = c.block_source_offsets[i];
                    let abs_offset = body_offset + SQPK_SUB_CMD_BODY_OFFSET + block_source_offset;
                    let decompressed_len = u32::try_from(block.decompressed_size())
                        .expect("block decompressed_size bounded by chunk size limit");
                    let kind = if block.is_compressed() {
                        PatchSourceKind::Deflated {
                            compressed_len: u32::try_from(block.data_len())
                                .expect("block data_len bounded by chunk size limit"),
                            decompressed_len,
                        }
                    } else {
                        PatchSourceKind::Raw {
                            len: decompressed_len,
                        }
                    };
                    self.push_region(
                        &path,
                        Region {
                            target_offset: cursor,
                            length: decompressed_len,
                            source: PartSource::Patch {
                                patch_idx: self.current_patch,
                                offset: abs_offset,
                                kind,
                                decoded_skip: 0,
                            },
                            expected: PartExpected::SizeOnly,
                        },
                    );
                    cursor += u64::from(decompressed_len);
                }
            }
            SqpkFileOperation::RemoveAll => {
                self.fs_ops
                    .push(FilesystemOp::RemoveAllInExpansion(c.expansion_id));
                self.drop_targets_under_expansion(c.expansion_id);
            }
            SqpkFileOperation::DeleteFile => {
                let path = TargetPath::Generic(c.path.clone());
                self.drop_target(&path);
                self.fs_ops.push(FilesystemOp::DeleteFile(c.path));
            }
            SqpkFileOperation::MakeDirTree => {
                self.fs_ops.push(FilesystemOp::MakeDirTree(c.path));
            }
        }
        Ok(())
    }

    fn push_region(&mut self, path: &TargetPath, region: Region) {
        if region.length == 0 {
            return;
        }
        // Hot path: target already exists. A single `get_mut` lookup with an
        // early return halves the per-region HashMap work vs the original
        // `contains_key` + `get_mut` pair, and avoids cloning the `TargetPath`
        // entirely (the `Generic` variant wraps a `String`, so clones allocate).
        if let Some(regions) = self.targets.get_mut(path) {
            region_map::insert(regions, region);
            return;
        }
        let owned = path.clone();
        self.target_order.push(owned.clone());
        let regions = self.targets.entry(owned).or_default();
        region_map::insert(regions, region);
    }

    /// Drop every accumulated region (and the target's bookkeeping entry) for
    /// a single target. Used by `DeleteFile` and by `AddFile@0` for the
    /// truncate-then-rewrite case.
    fn drop_target(&mut self, path: &TargetPath) {
        self.targets.remove(path);
        self.target_order.retain(|tp| tp != path);
    }

    /// Drop every accumulated target that falls under the expansion folder
    /// `sqpack/<exp>/` or `movie/<exp>/`. Used by `RemoveAll`.
    fn drop_targets_under_expansion(&mut self, expansion_id: u16) {
        let folder = expansion_folder_id(expansion_id);
        let sqpack_prefix = format!("sqpack/{folder}/");
        let movie_prefix = format!("movie/{folder}/");

        // Take `target_order` out so the retain closure can mutate
        // `self.targets` without a split-borrow conflict. One pass instead of
        // building a `HashSet<TargetPath>` of cloned keys and then running two
        // separate retains over both maps.
        let mut order = std::mem::take(&mut self.target_order);
        order.retain(|tp| {
            if target_falls_under(tp, expansion_id, &sqpack_prefix, &movie_prefix) {
                self.targets.remove(tp);
                false
            } else {
                true
            }
        });
        self.target_order = order;
    }

    fn finalize(self) -> Plan {
        let BuilderState {
            platform,
            patches,
            current_patch: _,
            fs_ops,
            mut targets,
            target_order,
        } = self;

        let mut out_targets = Vec::with_capacity(target_order.len());
        for path in target_order {
            let regions = targets.remove(&path).unwrap_or_default();
            let final_size = regions
                .last()
                .map_or(0, |r| r.target_offset + u64::from(r.length));
            debug_assert!(
                regions
                    .windows(2)
                    .all(|w| w[0].target_offset + u64::from(w[0].length) <= w[1].target_offset),
                "regions must be sorted and non-overlapping after build"
            );
            out_targets.push(Target {
                path,
                final_size,
                regions,
            });
        }

        Plan {
            schema_version: Plan::CURRENT_SCHEMA_VERSION,
            platform,
            patches,
            targets: out_targets,
            fs_ops,
        }
    }
}

fn target_falls_under(
    tp: &TargetPath,
    expansion_id: u16,
    sqpack_prefix: &str,
    movie_prefix: &str,
) -> bool {
    match tp {
        TargetPath::SqpackDat { sub_id, .. } | TargetPath::SqpackIndex { sub_id, .. } => {
            (sub_id >> 8) == expansion_id
        }
        TargetPath::Generic(path) => {
            path.starts_with(sqpack_prefix) || path.starts_with(movie_prefix)
        }
    }
}

fn dat_target(f: &SqpackFileId) -> TargetPath {
    TargetPath::SqpackDat {
        main_id: f.main_id,
        sub_id: f.sub_id,
        file_id: f.file_id,
    }
}

fn index_target(f: &SqpackFileId) -> TargetPath {
    TargetPath::SqpackIndex {
        main_id: f.main_id,
        sub_id: f.sub_id,
        file_id: f.file_id,
    }
}

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

    fn synthetic_sqpack_file() -> SqpackFileId {
        SqpackFileId {
            main_id: 1,
            sub_id: 2,
            file_id: 0,
        }
    }

    /// `block_delete_number` is wire-decoded as `(raw_u32 << 7)` and can reach
    /// ~549 GiB. A naive `u32::try_from(...).expect(...)` would panic on any
    /// raw value `>= 2^25`. Use a value that is comfortably above `u32::MAX`
    /// to force at least two chunks of splitting.
    #[test]
    fn consume_add_data_splits_huge_block_delete_into_u32_chunks() {
        let mut state = BuilderState::new();
        state.begin_patch("synthetic".into()).unwrap();

        let huge: u64 = u64::from(u32::MAX) + 1024; // forces a second chunk
        let cmd = SqpkAddData {
            target_file: synthetic_sqpack_file(),
            block_offset: 0,
            data_bytes: 128,
            block_delete_number: huge,
            data: vec![0xAA; 128],
        };
        // body_offset value is irrelevant for the zero-fill split path.
        state.consume_add_data(&cmd, 0);

        let plan = state.finalize();
        assert_eq!(plan.targets.len(), 1);
        let regions = &plan.targets[0].regions;
        // 1 raw payload region + 2 Zeros regions (u32::MAX + remainder).
        assert_eq!(regions.len(), 3);

        assert_eq!(regions[0].target_offset, 0);
        assert_eq!(regions[0].length, 128);
        assert!(matches!(regions[0].source, PartSource::Patch { .. }));

        // First zero chunk is exactly u32::MAX, starting right after data.
        assert_eq!(regions[1].target_offset, 128);
        assert_eq!(regions[1].length, u32::MAX);
        assert!(matches!(regions[1].source, PartSource::Zeros));

        // Second zero chunk holds the remainder, starting where the first ends.
        assert_eq!(regions[2].target_offset, 128 + u64::from(u32::MAX));
        assert_eq!(regions[2].length, 1024);
        assert!(matches!(regions[2].source, PartSource::Zeros));

        assert_eq!(plan.targets[0].final_size, 128 + huge);
    }

    /// `EmptyBlock` regions whose byte length fits in `u32` must round-trip
    /// as a single `EmptyBlock` region — the split path only kicks in for
    /// pathological `units >= 2^25`.
    #[test]
    fn push_empty_block_region_emits_single_region_when_in_range() {
        let mut state = BuilderState::new();
        state.begin_patch("synthetic".into()).unwrap();

        state.push_empty_block_region(&synthetic_sqpack_file(), 0, 8);

        let plan = state.finalize();
        assert_eq!(plan.targets.len(), 1);
        let regions = &plan.targets[0].regions;
        assert_eq!(regions.len(), 1);
        assert_eq!(regions[0].length, 8 * 128);
        assert!(matches!(
            regions[0].source,
            PartSource::EmptyBlock { units: 8 }
        ));
        assert!(matches!(
            regions[0].expected,
            PartExpected::EmptyBlock { units: 8 }
        ));
    }

    /// `EmptyBlock` with `units * 128 > u32::MAX` must split into a capped
    /// `EmptyBlock` region (header-bearing) followed by `Zeros` fillers.
    /// Verifies both the total bytes covered and the region kind shapes —
    /// this prevents the v1.0 silent saturation of `Region::length`.
    #[test]
    fn push_empty_block_region_splits_when_bytes_exceed_u32_max() {
        let mut state = BuilderState::new();
        state.begin_patch("synthetic".into()).unwrap();

        // `units = 2^25` produces exactly `2^32` bytes — one byte past
        // `u32::MAX` — the smallest input that triggers the split.
        let units: u32 = 1 << 25; // 2^25
        state.push_empty_block_region(&synthetic_sqpack_file(), 0, units);

        let plan = state.finalize();
        assert_eq!(plan.targets.len(), 1);
        let regions = &plan.targets[0].regions;

        // First region: capped EmptyBlock with the header.
        let cap_units: u32 = u32::MAX / 128;
        let cap_bytes: u64 = u64::from(cap_units) * 128;
        assert_eq!(regions[0].target_offset, 0);
        assert_eq!(regions[0].length, cap_units * 128);
        match regions[0].source {
            PartSource::EmptyBlock { units: u } => assert_eq!(u, cap_units),
            ref other => panic!("expected EmptyBlock, got {other:?}"),
        }

        // Tail: one or more Zeros regions covering the remaining bytes.
        let total_bytes: u64 = u64::from(units) * 128;
        let mut covered: u64 = cap_bytes;
        for region in &regions[1..] {
            assert_eq!(region.target_offset, covered);
            assert!(matches!(region.source, PartSource::Zeros));
            assert!(matches!(region.expected, PartExpected::Zeros));
            covered += u64::from(region.length);
        }
        assert_eq!(covered, total_bytes);
        assert_eq!(plan.targets[0].final_size, total_bytes);

        for region in &regions[1..] {
            assert!(region.length <= u32::MAX);
        }
    }

    // ---- path traversal validation ----

    #[test]
    fn reject_unsafe_relative_path_accepts_safe_paths() {
        for safe in [
            "sqpack/ffxiv/000000.win32.dat0",
            "movie/ffxiv/opening.bk2",
            "boot/launcher.exe",
            "a/b/c.txt",
            "single",
        ] {
            assert!(
                reject_unsafe_relative_path(safe).is_ok(),
                "safe path rejected: {safe}"
            );
        }
    }

    #[test]
    fn reject_unsafe_relative_path_rejects_traversal_and_absolute() {
        for bad in [
            "../etc/passwd",
            "..\\etc\\passwd",
            "sqpack/../../etc/passwd",
            "a/b/../../../etc/passwd",
            "/etc/passwd",
            "\\\\server\\share\\file",
            "C:/Windows/system32",
            "c:\\Windows\\system32",
            "C:",
        ] {
            let err = reject_unsafe_relative_path(bad)
                .expect_err(&format!("unsafe path accepted: {bad}"));
            match err {
                IndexError::UnsafeTargetPath(s) => assert_eq!(s, bad),
                other => panic!("expected UnsafeTargetPath, got {other:?}"),
            }
        }
    }

    #[test]
    fn consume_file_rejects_path_traversal() {
        let mut state = BuilderState::new();
        state.begin_patch("synthetic".into()).unwrap();
        let cmd = SqpkFile {
            operation: SqpkFileOperation::AddFile,
            file_offset: 0,
            file_size: 0,
            expansion_id: 0,
            path: "../../etc/passwd".into(),
            block_source_offsets: Vec::new(),
            blocks: Vec::new(),
        };
        let err = state
            .consume_file(cmd, 0)
            .expect_err("must reject traversal");
        assert!(matches!(err, IndexError::UnsafeTargetPath(_)));
    }

    /// Re-adding a patch with the same name must surface
    /// `IndexError::DuplicatePatch` rather than silently appending a second
    /// `PatchRef`. Exercised at the `BuilderState` boundary; the public-API
    /// equivalent (via `PlanBuilder::add_patch`) is covered in
    /// `tests/index_chain.rs`.
    #[test]
    fn begin_patch_rejects_duplicate_name() {
        let mut state = BuilderState::new();
        state.begin_patch("p1".into()).unwrap();
        let err = state
            .begin_patch("p1".into())
            .expect_err("duplicate name must error");
        match err {
            IndexError::DuplicatePatch { name } => assert_eq!(name, "p1"),
            other => panic!("expected DuplicatePatch, got {other:?}"),
        }
    }
}