zipatch_rs/index/

plan.rs

//! Pure-data plan describing every region a patch writes to every target file.
//!
//! A [`Plan`] is built once from a [`crate::ZiPatchReader`] by
//! [`crate::index::PlanBuilder`] and then handed to verifier / applier code that
//! actually touches disk. Nothing here resolves filesystem paths, opens files,
//! or fetches bytes from the patch source.

use crate::IndexResult as Result;
use crate::Platform;
use crate::index::apply::decompress_full;
use crate::index::source::PatchSource;
use crate::newtypes::{PatchIndex, SchemaVersion};
use std::collections::HashMap;
use tracing::{info, info_span, warn};

/// 4-byte ASCII patch-type tag carried by a `FHDR` chunk.
///
/// In retail FFXIV patches this is always `D000` (game-data) or `H000`
/// (boot/header). Future tags surface unchanged through the [`PatchType::Other`]
/// arm.
// Note: adding a variant here requires updating `feed_patch_type` at
// plan.rs:612 and bumping the v-tag at plan.rs:563.
#[derive(Debug, Clone, PartialEq, Eq)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
pub enum PatchType {
    /// `D000` — game-data patch.
    GameData,
    /// `H000` — boot/header patch.
    Boot,
    /// Any other 4-byte ASCII tag, preserved verbatim.
    Other([u8; 4]),
}

impl PatchType {
    /// Map the raw 4-byte tag from `FHDR` to a [`PatchType`].
    #[must_use]
    pub fn from_tag(tag: [u8; 4]) -> Self {
        match &tag {
            b"D000" => PatchType::GameData,
            b"H000" => PatchType::Boot,
            _ => PatchType::Other(tag),
        }
    }
}

/// Reference to a single source patch file from which a [`Plan`] is built.
///
/// A [`Plan`] always carries the full chain of patches that produced it in
/// [`Plan::patches`], in chain order. [`PartSource::Patch::patch_idx`] is an index
/// into that slice.
///
/// `#[non_exhaustive]`: patch-list parsing may eventually surface size,
/// hash, or version metadata that rides on this struct.
#[non_exhaustive]
#[derive(Debug, Clone, PartialEq, Eq)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
pub struct PatchRef {
    /// Human-readable patch name (typically the filename without extension).
    pub name: String,
    /// `FHDR` patch-type tag if the patch declared one.
    pub patch_type: Option<PatchType>,
}

impl PatchRef {
    /// Construct a [`PatchRef`] from its component parts.
    ///
    /// Pairs with [`Plan::new`] for callers outside this crate after the
    /// struct picked up `#[non_exhaustive]`.
    #[must_use]
    pub fn new(name: impl Into<String>, patch_type: Option<PatchType>) -> Self {
        Self {
            name: name.into(),
            patch_type,
        }
    }
}

/// Path identity of a single target file the plan writes to.
///
/// Resolution to a concrete [`std::path::PathBuf`] lives in the applier; the
/// plan only carries the symbolic identity so it can be compared, hashed, and
/// serialised without an `ApplyConfig`.
// Note: adding a variant here requires updating `feed_target_path` at
// plan.rs:626 and bumping the v-tag at plan.rs:563.
#[derive(Debug, Clone, PartialEq, Eq, Hash)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
pub enum TargetPath {
    /// `SqPack` `.dat` file at `(main_id, sub_id, file_id)`.
    SqpackDat {
        /// `SqPack` category identifier.
        main_id: u16,
        /// `SqPack` sub-category identifier; high byte selects the expansion folder.
        sub_id: u16,
        /// `.dat` file index, appended directly as `.datN`.
        file_id: u32,
    },
    /// `SqPack` `.index` file at `(main_id, sub_id, file_id)`.
    SqpackIndex {
        /// `SqPack` category identifier.
        main_id: u16,
        /// `SqPack` sub-category identifier; high byte selects the expansion folder.
        sub_id: u16,
        /// `.index` file index. `0` produces no numeric suffix; `> 0` appends directly.
        file_id: u32,
    },
    /// Generic relative path under the game install root (e.g. an `SqpkFile`
    /// `AddFile` target outside the `sqpack/` subtree).
    Generic(String),
}

/// One target file's complete write profile.
///
/// `#[non_exhaustive]`: per-target metadata (expected SHA1, pre-apply size,
/// repair hints) is a credible additive direction.
#[non_exhaustive]
#[derive(Debug, Clone, PartialEq, Eq)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
pub struct Target {
    /// Where the writes land.
    pub path: TargetPath,
    /// Highest `target_offset + length` produced by any region. May leave
    /// trailing or interior gaps that the indexed applier must not touch.
    pub final_size: u64,
    /// Region timeline for this target, sorted by `target_offset` and
    /// non-overlapping. Gaps between regions represent bytes the patch does
    /// not modify (the sequential apply leaves them sparse / unchanged).
    pub regions: Vec<Region>,
}

impl Target {
    /// Construct a [`Target`] from its component parts.
    ///
    /// Pairs with [`Plan::new`] for callers outside this crate after the
    /// struct picked up `#[non_exhaustive]`.
    #[must_use]
    pub fn new(path: TargetPath, final_size: u64, regions: Vec<Region>) -> Self {
        Self {
            path,
            final_size,
            regions,
        }
    }
}

/// One contiguous range of bytes the patch writes into a target file.
///
/// `#[non_exhaustive]`: per-region diagnostic fields (chunk index of origin,
/// source patch index for provenance) may be added.
#[non_exhaustive]
#[derive(Debug, Clone, PartialEq, Eq)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
pub struct Region {
    /// First byte offset within the target file that this region writes.
    pub target_offset: u64,
    /// Length of the region in bytes.
    pub length: u32,
    /// Where the bytes come from.
    pub source: PartSource,
    /// What the post-write content should be (size-only by default).
    pub expected: PartExpected,
}

impl Region {
    /// Construct a [`Region`] from its component parts.
    ///
    /// Pairs with [`Plan::new`] for callers outside this crate after the
    /// struct picked up `#[non_exhaustive]`.
    #[must_use]
    pub fn new(
        target_offset: u64,
        length: u32,
        source: PartSource,
        expected: PartExpected,
    ) -> Self {
        Self {
            target_offset,
            length,
            source,
            expected,
        }
    }
}

/// Where a [`Region`]'s bytes come from.
///
/// `#[non_exhaustive]`: already grew the `Unavailable` variant
/// post-1.0; future region-source shapes (e.g. external download, sparse
/// hole) are plausible.
// Note: adding a variant here (or to the nested `PatchSourceKind`) requires
// updating `feed_part_source` at plan.rs:658 and bumping the v-tag at
// plan.rs:563.
#[non_exhaustive]
#[derive(Debug, Clone, PartialEq, Eq)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
pub enum PartSource {
    /// Bytes live in the source patch file at [`Plan::patches`]`[patch_idx]`.
    /// `offset` is **absolute within that patch file**, not chunk-relative —
    /// the builder has already added the chunk's body position. `kind` selects
    /// raw vs DEFLATE-encoded.
    Patch {
        /// Index into [`Plan::patches`] selecting which patch file holds the bytes.
        patch_idx: PatchIndex,
        /// Absolute byte offset within the patch file where the source bytes begin.
        offset: u64,
        /// How the source bytes are encoded at that offset.
        kind: PatchSourceKind,
        /// For [`PatchSourceKind::Deflated`] sources only: bytes to skip in the
        /// decompressed output before writing this region. Always `0` for
        /// [`PatchSourceKind::Raw`]. Used when a single DEFLATE block is split
        /// across two regions by a cross-patch overlap — both halves share
        /// `(patch_idx, offset, kind)` but slice the decompressed output differently.
        decoded_skip: u16,
    },
    /// Region is a run of zero bytes (e.g. an `SqpkAddData` `block_delete_number`
    /// trailing zero-fill).
    Zeros,
    /// Region is the canonical `SqPack` empty-block payload covering `units`
    /// 128-byte blocks (`SqpkDeleteData` / `SqpkExpandData`).
    EmptyBlock {
        /// Number of 128-byte `SqPack` blocks (total length = `units * 128`).
        units: u32,
    },
    /// Region exists in the plan but its source bytes are not reachable from
    /// the [`PatchSource`] the applier will be given. The builder does not
    /// emit this variant from any in-tree chunk parser; it is provided for
    /// hand-constructed plans (or deserialized plans) that intentionally name
    /// a region without backing bytes. [`crate::index::IndexApplier::execute`]
    /// surfaces these as
    /// [`crate::IndexError::SourceUnavailable`], and
    /// [`crate::index::PlanVerifier`] always flags them as needing repair.
    Unavailable,
}

/// Encoding of a [`PartSource::Patch`]'s bytes at its absolute patch-file offset.
#[derive(Debug, Clone, PartialEq, Eq)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
pub enum PatchSourceKind {
    /// Bytes are stored verbatim at `offset` and have length `len`.
    Raw {
        /// Length of the raw payload in bytes.
        len: u32,
    },
    /// Bytes are a raw DEFLATE stream at `offset` of `compressed_len` bytes,
    /// producing `decompressed_len` bytes of output.
    Deflated {
        /// Length of the DEFLATE-encoded payload at `offset` (may include
        /// trailing 128-byte alignment padding past the end-of-stream marker —
        /// the decoder stops at `StreamEnd` and ignores the tail).
        compressed_len: u32,
        /// Number of output bytes produced after decompression.
        decompressed_len: u32,
    },
}

/// Post-write content invariant for a [`Region`].
///
/// By default only the sentinel-source regions (`Zeros`, `EmptyBlock`) carry a
/// meaningful expectation; `Patch`-sourced regions default to
/// [`PartExpected::SizeOnly`]. Call [`Plan::with_crc32`] to populate every
/// region (including `Patch`) with [`PartExpected::Crc32`].
///
/// `#[non_exhaustive]`: future verification policies (SHA1 per region,
/// hash chains, signed expectations) may be added.
// Note: adding a variant here requires updating `feed_part_expected` at
// plan.rs:696 and bumping the v-tag at plan.rs:563.
#[non_exhaustive]
#[derive(Debug, Clone, PartialEq, Eq)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
pub enum PartExpected {
    /// Only the byte count is checked.
    SizeOnly,
    /// CRC32 of the region's expected output bytes (populated by
    /// [`Plan::with_crc32`]; not emitted by [`PlanBuilder`](crate::index::PlanBuilder)
    /// out of the box).
    Crc32(u32),
    /// Region must be all-zero bytes.
    Zeros,
    /// Region must match the canonical `SqPack` empty-block payload for `units`
    /// 128-byte blocks.
    EmptyBlock {
        /// Number of 128-byte `SqPack` blocks.
        units: u32,
    },
}

/// Filesystem-level operation that runs before any region writes.
///
/// `#[non_exhaustive]`: new top-level filesystem operations (rename, set
/// permissions, hard-link) would land here as new variants.
// Note: adding a variant here requires updating `feed_fs_op` at plan.rs:713
// and bumping the v-tag at plan.rs:563.
#[non_exhaustive]
#[derive(Debug, Clone, PartialEq, Eq)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
pub enum FilesystemOp {
    /// Ensure the directory at this relative path (joined under the install
    /// root) exists. Idempotent.
    EnsureDir(String),
    /// Remove the empty directory at this relative path.
    DeleteDir(String),
    /// Remove the file at this relative path.
    DeleteFile(String),
    /// Create the directory tree at this relative path (equivalent to
    /// `fs::create_dir_all`).
    MakeDirTree(String),
    /// Bulk-remove all non-keep-listed files in an expansion folder. The
    /// applier owns the keep-list policy; the plan only names the expansion.
    RemoveAllInExpansion(u16),
}

/// Complete write plan for a chain of one or more source patches.
///
/// # Schema versioning
///
/// Under the `serde` feature, every [`Plan`] carries a `schema_version: u32`
/// that records the in-memory layout this build emits. The current value is
/// exposed as [`Plan::CURRENT_SCHEMA_VERSION`] and is currently `1`.
///
/// **Compatibility policy:** the schema version is bumped any time a new
/// **required** field is added to [`Plan`] or any of the types it transitively
/// contains. Additive *optional* fields (defaulted via `#[serde(default)]`)
/// do not bump the version. On deserialize, a [`Plan`] whose persisted
/// `schema_version` does not equal [`Plan::CURRENT_SCHEMA_VERSION`] is
/// rejected with [`crate::IndexError::SchemaVersionMismatch`] — older
/// readers refuse to silently drop fields they cannot represent, rather than
/// risk an apply against a partial plan. Callers persisting plans across
/// crate-version boundaries should be prepared to rebuild the plan from the
/// patch chain on mismatch.
///
/// `#[non_exhaustive]`: the top-level plan owns the schema-version
/// contract; new persisted fields land here under that contract.
#[non_exhaustive]
#[derive(Debug, Clone, PartialEq, Eq)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
pub struct Plan {
    /// Schema-format version of this persisted plan. See the
    /// [type-level docs](Plan) for the compatibility policy. New plans
    /// constructed via [`Plan::new`] / [`PlanBuilder`](crate::index::PlanBuilder)
    /// always carry [`Plan::CURRENT_SCHEMA_VERSION`].
    #[cfg_attr(feature = "serde", serde(default = "Plan::default_schema_version"))]
    pub schema_version: SchemaVersion,
    /// Target platform pinned by the chain's most recent `SqpkTargetInfo`
    /// chunk. Defaults to [`Platform::Win32`] when no `TargetInfo` is seen.
    pub platform: Platform,
    /// Source patches in chain order. [`PartSource::Patch::patch_idx`] indexes
    /// into this vector; the applier asks the caller's [`crate::index::PatchSource`]
    /// for bytes by `(patch_idx, offset)`.
    pub patches: Vec<PatchRef>,
    /// Per-target write timelines, reflecting the chain's end state — regions
    /// killed by a mid-chain `RemoveAll`, `DeleteFile`, or `AddFile@0` are
    /// dropped at build time, not at apply time.
    pub targets: Vec<Target>,
    /// Filesystem operations to run before any region writes, in chain order.
    /// Destructive ops (`DeleteFile`, `DeleteDir`, `RemoveAllInExpansion`) are
    /// preserved so that the applier still removes any pre-chain artefacts
    /// that the plan's region set does not re-create.
    pub fs_ops: Vec<FilesystemOp>,
}

impl Plan {
    /// Current on-disk schema version for [`Plan`] under the `serde` feature.
    /// See the [type-level docs](Plan) for the compatibility policy.
    pub const CURRENT_SCHEMA_VERSION: SchemaVersion = SchemaVersion::new(1);

    /// Default used by serde to populate `schema_version` on plans persisted
    /// before the field was introduced. Returns `Self::CURRENT_SCHEMA_VERSION`
    /// because the only pre-versioning shape that exists in the wild is the
    /// one this build still understands; deliberate version mismatches must
    /// be authored explicitly.
    #[cfg(feature = "serde")]
    #[must_use]
    fn default_schema_version() -> SchemaVersion {
        Self::CURRENT_SCHEMA_VERSION
    }

    /// Validate that `self.schema_version` matches
    /// [`Self::CURRENT_SCHEMA_VERSION`]. Intended to be called by consumers
    /// immediately after deserializing a [`Plan`] from persistent storage,
    /// before handing it to the applier or verifier.
    ///
    /// # Errors
    ///
    /// Returns [`crate::IndexError::SchemaVersionMismatch`] when the
    /// persisted version does not equal [`Self::CURRENT_SCHEMA_VERSION`].
    pub fn check_schema_version(&self) -> Result<()> {
        if !self
            .schema_version
            .compatible_with(Self::CURRENT_SCHEMA_VERSION)
        {
            return Err(crate::IndexError::SchemaVersionMismatch {
                kind: "plan",
                found: self.schema_version,
                expected: Self::CURRENT_SCHEMA_VERSION,
            });
        }
        Ok(())
    }

    /// Construct a [`Plan`] from its component parts.
    ///
    /// Exists so callers outside this crate can still build synthetic plans
    /// after the struct picked up `#[non_exhaustive]` for `SemVer` hygiene —
    /// in-crate code may continue to use the struct literal form directly.
    /// The constructed plan always carries
    /// [`Plan::CURRENT_SCHEMA_VERSION`].
    #[must_use]
    pub fn new(
        platform: Platform,
        patches: Vec<PatchRef>,
        targets: Vec<Target>,
        fs_ops: Vec<FilesystemOp>,
    ) -> Self {
        Self {
            schema_version: Self::CURRENT_SCHEMA_VERSION,
            platform,
            patches,
            targets,
            fs_ops,
        }
    }

    /// Consume this plan, walk every region, and return a new plan in which
    /// every applicable region's [`PartExpected`] has been replaced with
    /// [`PartExpected::Crc32`] of the region's effective output bytes.
    ///
    /// Consumes `self` and returns the populated plan so the mutation is
    /// honest at the type level — there's no in-place "compute" call that
    /// silently rewrites an outwardly-immutable-looking data type. Pairs with
    /// the [`PlanBuilder`](crate::index::PlanBuilder)`::finish() -> Plan`
    /// owned-builder style.
    ///
    /// - [`PartSource::Patch`] regions read the source bytes via `source` and,
    ///   for [`PatchSourceKind::Deflated`] sources, decompress them in full
    ///   before slicing the `[decoded_skip..decoded_skip + region.length]`
    ///   window and CRC32-ing the slice. A single shared
    ///   [`flate2::Decompress`] is reused across every Deflated region.
    /// - [`PartSource::Zeros`] regions use the canonical all-zero payload,
    ///   cached per-length so plans with many same-sized Zeros regions hit
    ///   `crc32fast::hash` once per unique length.
    /// - [`PartSource::EmptyBlock`] regions use the canonical empty-block
    ///   payload the apply layer's internal `write_empty_block` helper
    ///   produces (a 20-byte `SqPack` empty-block header followed by
    ///   `units * 128 - 20` zero bytes), cached per-`units`.
    /// - [`PartSource::Unavailable`] regions are left with their existing
    ///   [`PartExpected`] (typically [`PartExpected::SizeOnly`]). A single
    ///   `tracing::warn!` summary fires per call with the total count of
    ///   skipped regions — per-region tracing happens at `trace!`.
    ///
    /// Once populated, [`crate::index::PlanVerifier`] uses
    /// [`PartExpected::Crc32`] to detect single-byte damage inside `Patch`
    /// regions, which the v1 size-only policy missed.
    ///
    /// # Errors
    ///
    /// Surfaces any [`crate::IndexError`] produced by `source.read` or by
    /// DEFLATE decompression of a `Patch` region's bytes. On error the
    /// original plan is dropped; callers that need to retry must hold an
    /// independent copy.
    ///
    /// # Atomicity
    ///
    /// All-or-nothing: on `Ok`, every applicable region in the returned plan
    /// carries a fresh [`PartExpected::Crc32`]; on `Err`, no partially-mutated
    /// plan is observable — the input was consumed and the staging buffer is
    /// dropped without being flushed.
    pub fn with_crc32<S: PatchSource>(mut self, source: &mut S) -> Result<Self> {
        let span = info_span!(
            crate::tracing_schema::span_names::WITH_CRC32,
            targets = self.targets.len()
        );
        let _enter = span.enter();

        let mut compressed_scratch: Vec<u8> = Vec::new();
        let mut decompressed_scratch: Vec<u8> = Vec::new();
        let mut decompressor = flate2::Decompress::new(false);
        // Unique region lengths / `units` counts are tiny in practice; pre-size
        // both caches to skip the initial `HashMap` resize.
        let mut zeros_cache: HashMap<u32, u32> = HashMap::with_capacity(4);
        let mut empty_block_cache: HashMap<u32, u32> = HashMap::with_capacity(4);

        // Stage every successful CRC into a side buffer. The plan's
        // `expected` fields are only mutated after the whole pass completes,
        // so an `Err` surfaced midway leaves the plan untouched.
        let mut updates: Vec<(usize, usize, u32)> = Vec::new();
        let mut unavailable_skipped: usize = 0;

        for (t_idx, target) in self.targets.iter().enumerate() {
            for (r_idx, region) in target.regions.iter().enumerate() {
                match &region.source {
                    PartSource::Patch {
                        patch_idx,
                        offset,
                        kind,
                        decoded_skip,
                    } => {
                        let crc = patch_region_crc(
                            source,
                            *patch_idx,
                            *offset,
                            kind,
                            *decoded_skip,
                            region.length,
                            &mut compressed_scratch,
                            &mut decompressed_scratch,
                            &mut decompressor,
                        )?;
                        updates.push((t_idx, r_idx, crc));
                    }
                    PartSource::Zeros => {
                        let crc = *zeros_cache
                            .entry(region.length)
                            .or_insert_with(|| crc32_of_zeros(region.length));
                        updates.push((t_idx, r_idx, crc));
                    }
                    PartSource::EmptyBlock { units } => {
                        let crc = match empty_block_cache.entry(*units) {
                            std::collections::hash_map::Entry::Occupied(e) => *e.get(),
                            std::collections::hash_map::Entry::Vacant(e) => {
                                let crc = crc32_of_empty_block(*units)?;
                                *e.insert(crc)
                            }
                        };
                        updates.push((t_idx, r_idx, crc));
                    }
                    PartSource::Unavailable => {
                        unavailable_skipped += 1;
                        tracing::trace!(
                            target_idx = t_idx,
                            region_idx = r_idx,
                            target_offset = region.target_offset,
                            length = region.length,
                            "with_crc32: skipping Unavailable region"
                        );
                    }
                }
            }
        }

        // Commit phase — every read succeeded, so flush the staged values.
        let populated = updates.len();
        for (t_idx, r_idx, crc) in updates {
            self.targets[t_idx].regions[r_idx].expected = PartExpected::Crc32(crc);
        }
        if unavailable_skipped > 0 {
            warn!(
                skipped = unavailable_skipped,
                "with_crc32: left Unavailable regions with their existing expected"
            );
        }
        info!(
            populated,
            skipped = unavailable_skipped,
            "with_crc32: populated CRC32 for regions"
        );
        Ok(self)
    }

    /// Stable CRC32 identity over this plan's structural content.
    ///
    /// Used by [`IndexedCheckpoint::plan_crc32`](crate::apply::IndexedCheckpoint::plan_crc32) and
    /// [`crate::index::IndexApplier::resume_execute`] to detect a checkpoint
    /// that was persisted against a different plan revision than the one a
    /// resume call is given. The CRC is computed from a fixed,
    /// deterministically-ordered byte feed of every field that affects which
    /// bytes the applier writes — schema version, platform, patch chain,
    /// every target's path and region timeline (including `PartSource` /
    /// `PartExpected` discriminants and payload), and the `fs_ops` list. The
    /// encoding does **not** match any serde format on purpose: we hash
    /// directly so the result stays stable regardless of which serializer the
    /// consumer picks for on-disk persistence.
    ///
    /// Not cryptographic — collision space is 32 bits and the function is
    /// trivial to forge. Stale-detection only; never use this as an
    /// authentication or integrity check.
    ///
    /// `0` is a legitimate output value. CRC32 is uniform over `u32` and a
    /// real plan can hash to zero; consumers must represent the
    /// "no checkpoint yet" state via `Option<IndexedCheckpoint>` rather
    /// than a sentinel `plan_crc32: 0`. See
    /// [`IndexedCheckpoint::plan_crc32`](crate::apply::IndexedCheckpoint::plan_crc32) for the matching field doc.
    #[must_use]
    pub fn crc32(&self) -> u32 {
        let mut hasher = crc32fast::Hasher::new();
        plan_feed_crc(self, &mut hasher);
        hasher.finalize()
    }
}

// Feed every structurally-relevant field of `plan` into `hasher` in a fixed
// order so [`Plan::crc32`] is stable across runs. Length-prefix every variable
// section (strings, vecs) so two fields with adjacent boundaries can never
// collide. Discriminants for `#[non_exhaustive]` enums are written as fixed
// `u8` tags chosen here, not via mem::discriminant, so a future variant added
// at the end of an enum does not shift existing CRCs.
fn plan_feed_crc(plan: &Plan, h: &mut crc32fast::Hasher) {
    h.update(b"zipatch-rs/plan/v1");
    h.update(&plan.schema_version.get().to_le_bytes());
    feed_platform(plan.platform, h);
    feed_len(plan.patches.len(), h);
    for p in &plan.patches {
        feed_str(&p.name, h);
        feed_patch_type(p.patch_type.as_ref(), h);
    }
    feed_len(plan.targets.len(), h);
    for t in &plan.targets {
        feed_target_path(&t.path, h);
        h.update(&t.final_size.to_le_bytes());
        feed_len(t.regions.len(), h);
        for r in &t.regions {
            h.update(&r.target_offset.to_le_bytes());
            h.update(&r.length.to_le_bytes());
            feed_part_source(&r.source, h);
            feed_part_expected(&r.expected, h);
        }
    }
    feed_len(plan.fs_ops.len(), h);
    for op in &plan.fs_ops {
        feed_fs_op(op, h);
    }
}

fn feed_len(n: usize, h: &mut crc32fast::Hasher) {
    h.update(&(n as u64).to_le_bytes());
}

fn feed_str(s: &str, h: &mut crc32fast::Hasher) {
    feed_len(s.len(), h);
    h.update(s.as_bytes());
}

fn feed_platform(p: crate::Platform, h: &mut crc32fast::Hasher) {
    match p {
        crate::Platform::Win32 => h.update(&[0u8]),
        crate::Platform::Ps3 => h.update(&[1u8]),
        crate::Platform::Ps4 => h.update(&[2u8]),
        crate::Platform::Unknown(raw) => {
            h.update(&[3u8]);
            h.update(&raw.to_le_bytes());
        }
    }
}

// Note: encodes `PatchType`; if a variant is added at plan.rs:25, update
// this function and bump the v-tag at plan.rs:563.
fn feed_patch_type(p: Option<&PatchType>, h: &mut crc32fast::Hasher) {
    match p {
        None => h.update(&[0u8]),
        Some(PatchType::GameData) => h.update(&[1u8]),
        Some(PatchType::Boot) => h.update(&[2u8]),
        Some(PatchType::Other(tag)) => {
            h.update(&[3u8]);
            h.update(tag);
        }
    }
}

// Note: encodes `TargetPath`; if a variant is added at plan.rs:85, update
// this function and bump the v-tag at plan.rs:563.
fn feed_target_path(tp: &TargetPath, h: &mut crc32fast::Hasher) {
    match *tp {
        TargetPath::SqpackDat {
            main_id,
            sub_id,
            file_id,
        } => {
            h.update(&[0u8]);
            h.update(&main_id.to_le_bytes());
            h.update(&sub_id.to_le_bytes());
            h.update(&file_id.to_le_bytes());
        }
        TargetPath::SqpackIndex {
            main_id,
            sub_id,
            file_id,
        } => {
            h.update(&[1u8]);
            h.update(&main_id.to_le_bytes());
            h.update(&sub_id.to_le_bytes());
            h.update(&file_id.to_le_bytes());
        }
        TargetPath::Generic(ref rel) => {
            h.update(&[2u8]);
            feed_str(rel, h);
        }
    }
}

// Note: encodes `PartSource` (and the nested `PatchSourceKind`); if a variant
// is added at plan.rs:183 or plan.rs:226, update this function and bump the
// v-tag at plan.rs:563.
fn feed_part_source(s: &PartSource, h: &mut crc32fast::Hasher) {
    match *s {
        PartSource::Patch {
            patch_idx,
            offset,
            ref kind,
            decoded_skip,
        } => {
            h.update(&[0u8]);
            h.update(&patch_idx.get().to_le_bytes());
            h.update(&offset.to_le_bytes());
            match *kind {
                PatchSourceKind::Raw { len } => {
                    h.update(&[0u8]);
                    h.update(&len.to_le_bytes());
                }
                PatchSourceKind::Deflated {
                    compressed_len,
                    decompressed_len,
                } => {
                    h.update(&[1u8]);
                    h.update(&compressed_len.to_le_bytes());
                    h.update(&decompressed_len.to_le_bytes());
                }
            }
            h.update(&decoded_skip.to_le_bytes());
        }
        PartSource::Zeros => h.update(&[1u8]),
        PartSource::EmptyBlock { units } => {
            h.update(&[2u8]);
            h.update(&units.to_le_bytes());
        }
        PartSource::Unavailable => h.update(&[3u8]),
    }
}

// Note: encodes `PartExpected`; if a variant is added at plan.rs:255, update
// this function and bump the v-tag at plan.rs:563.
fn feed_part_expected(e: &PartExpected, h: &mut crc32fast::Hasher) {
    match *e {
        PartExpected::SizeOnly => h.update(&[0u8]),
        PartExpected::Crc32(c) => {
            h.update(&[1u8]);
            h.update(&c.to_le_bytes());
        }
        PartExpected::Zeros => h.update(&[2u8]),
        PartExpected::EmptyBlock { units } => {
            h.update(&[3u8]);
            h.update(&units.to_le_bytes());
        }
    }
}

// Note: encodes `FilesystemOp`; if a variant is added at plan.rs:278, update
// this function and bump the v-tag at plan.rs:563.
fn feed_fs_op(op: &FilesystemOp, h: &mut crc32fast::Hasher) {
    match op {
        FilesystemOp::EnsureDir(s) => {
            h.update(&[0u8]);
            feed_str(s, h);
        }
        FilesystemOp::DeleteDir(s) => {
            h.update(&[1u8]);
            feed_str(s, h);
        }
        FilesystemOp::DeleteFile(s) => {
            h.update(&[2u8]);
            feed_str(s, h);
        }
        FilesystemOp::MakeDirTree(s) => {
            h.update(&[3u8]);
            feed_str(s, h);
        }
        FilesystemOp::RemoveAllInExpansion(id) => {
            h.update(&[4u8]);
            h.update(&id.to_le_bytes());
        }
    }
}

#[allow(clippy::too_many_arguments)]
fn patch_region_crc<S: PatchSource>(
    source: &mut S,
    patch_idx: PatchIndex,
    offset: u64,
    kind: &PatchSourceKind,
    decoded_skip: u16,
    length: u32,
    compressed_scratch: &mut Vec<u8>,
    decompressed_scratch: &mut Vec<u8>,
    decompressor: &mut flate2::Decompress,
) -> Result<u32> {
    match *kind {
        PatchSourceKind::Raw { len } => {
            let len_us = len as usize;
            if compressed_scratch.len() < len_us {
                compressed_scratch.resize(len_us, 0);
            }
            source.read(patch_idx, offset, &mut compressed_scratch[..len_us])?;
            // Raw never carries decoded_skip; kind.len always equals region.length
            // after any truncation, so the whole filled slice is the region.
            Ok(crc32fast::hash(&compressed_scratch[..len_us]))
        }
        PatchSourceKind::Deflated {
            compressed_len,
            decompressed_len,
        } => {
            let comp_us = compressed_len as usize;
            if compressed_scratch.len() < comp_us {
                compressed_scratch.resize(comp_us, 0);
            }
            source.read(patch_idx, offset, &mut compressed_scratch[..comp_us])?;
            let produced = decompress_full(
                decompressor,
                &compressed_scratch[..comp_us],
                decompressed_len,
                decompressed_scratch,
            )?;
            let skip = decoded_skip as usize;
            let end = skip + length as usize;
            // `decompressed_scratch` is reused without zeroing — clamp to the
            // bytes the decoder actually produced so the hash never folds in
            // stale data from a prior region's decompression.
            let clamped_end = end.min(produced);
            let clamped_start = skip.min(clamped_end);
            Ok(crc32fast::hash(
                &decompressed_scratch[clamped_start..clamped_end],
            ))
        }
    }
}

fn crc32_of_zeros(length: u32) -> u32 {
    // Stream the all-zero payload through a shared 64 KiB buffer; same trick
    // as `write_zeros` in the apply layer. Avoids allocating a fresh
    // `vec![0; length]` for every unique zero-region length on huge plans.
    static ZERO_BUF: [u8; 64 * 1024] = [0; 64 * 1024];
    let mut hasher = crc32fast::Hasher::new();
    let mut remaining = length as u64;
    while remaining > 0 {
        let n = remaining.min(ZERO_BUF.len() as u64) as usize;
        hasher.update(&ZERO_BUF[..n]);
        remaining -= n as u64;
    }
    hasher.finalize()
}

fn crc32_of_empty_block(units: u32) -> Result<u32> {
    // Stream the canonical payload through the hasher in 64 KiB chunks so the
    // work is bounded by hashing throughput, not by `units * 128` allocation.
    // A pathological plan with `units` near `MAX_UNITS_PER_REGION` would
    // otherwise request a ~4 GiB buffer here (see issue #32). The byte layout
    // (20-byte header + zeros) matches `apply::sqpk::write_empty_block` by
    // sharing the `empty_block_header` helper.
    static ZERO_BUF: [u8; 64 * 1024] = [0; 64 * 1024];
    if units == 0 {
        return Err(crate::IndexError::InvalidField {
            context: "EmptyBlock units must be non-zero",
        });
    }
    let mut hasher = crc32fast::Hasher::new();
    hasher.update(&crate::apply::sqpk::empty_block_header(units));
    let mut remaining = u64::from(units) * 128 - 20;
    while remaining > 0 {
        let n = remaining.min(ZERO_BUF.len() as u64) as usize;
        hasher.update(&ZERO_BUF[..n]);
        remaining -= n as u64;
    }
    Ok(hasher.finalize())
}

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

    #[test]
    fn patch_type_from_tag_known_values() {
        assert_eq!(PatchType::from_tag(*b"D000"), PatchType::GameData);
        assert_eq!(PatchType::from_tag(*b"H000"), PatchType::Boot);
        assert_eq!(
            PatchType::from_tag(*b"Z999"),
            PatchType::Other(*b"Z999"),
            "unknown tags must round-trip through Other"
        );
    }

    #[test]
    fn part_source_variants_are_clone_partial_eq() {
        let a = PartSource::Patch {
            patch_idx: PatchIndex::new(0),
            offset: 1024,
            kind: PatchSourceKind::Raw { len: 128 },
            decoded_skip: 0,
        };
        let b = a.clone();
        assert_eq!(a, b);

        let z1 = PartSource::Zeros;
        let z2 = PartSource::Zeros;
        assert_eq!(z1, z2);

        let e1 = PartSource::EmptyBlock { units: 4 };
        let e2 = PartSource::EmptyBlock { units: 4 };
        assert_eq!(e1, e2);
        assert_ne!(e1, PartSource::EmptyBlock { units: 5 });
    }

    #[test]
    fn patch_source_kind_distinguishes_raw_and_deflated() {
        let raw = PatchSourceKind::Raw { len: 16 };
        let def = PatchSourceKind::Deflated {
            compressed_len: 8,
            decompressed_len: 16,
        };
        assert_ne!(raw, def);
        // Same kind, different decompressed_len → not equal.
        assert_ne!(
            def,
            PatchSourceKind::Deflated {
                compressed_len: 8,
                decompressed_len: 32,
            }
        );
    }

    #[test]
    fn part_expected_variants_round_trip() {
        let cases = [
            PartExpected::SizeOnly,
            PartExpected::Crc32(0xDEAD_BEEF),
            PartExpected::Zeros,
            PartExpected::EmptyBlock { units: 2 },
        ];
        for c in &cases {
            assert_eq!(c, &c.clone());
        }
    }

    #[test]
    fn filesystem_op_variants_round_trip() {
        let ops = [
            FilesystemOp::EnsureDir("sqpack/ffxiv".to_owned()),
            FilesystemOp::DeleteDir("old".to_owned()),
            FilesystemOp::DeleteFile("dead.dat".to_owned()),
            FilesystemOp::MakeDirTree("sqpack/ex1".to_owned()),
            FilesystemOp::RemoveAllInExpansion(2),
        ];
        for op in &ops {
            assert_eq!(op, &op.clone());
        }
    }

    // ---- with_crc32 ----

    use crate::index::source::MemoryPatchSource;
    use flate2::Compression;
    use flate2::write::DeflateEncoder;
    use std::io::Write;

    fn plan_with_regions(regions: Vec<Region>) -> Plan {
        Plan {
            schema_version: Plan::CURRENT_SCHEMA_VERSION,
            platform: Platform::Win32,
            patches: vec![PatchRef {
                name: "synthetic".into(),
                patch_type: None,
            }],
            targets: vec![Target {
                path: TargetPath::Generic("file.bin".into()),
                final_size: regions
                    .last()
                    .map_or(0, |r| r.target_offset + u64::from(r.length)),
                regions,
            }],
            fs_ops: vec![],
        }
    }

    #[test]
    fn with_crc32_populates_every_patch_region() {
        let raw_payload: Vec<u8> = (0..64u8).collect();
        let deflate_src: Vec<u8> = (0..128u8).map(|i| i.wrapping_mul(3)).collect();
        let mut enc = DeflateEncoder::new(Vec::new(), Compression::default());
        enc.write_all(&deflate_src).unwrap();
        let compressed = enc.finish().unwrap();

        let mut source_buf = vec![0u8; 4096];
        source_buf[..raw_payload.len()].copy_from_slice(&raw_payload);
        source_buf[256..256 + compressed.len()].copy_from_slice(&compressed);

        let regions = vec![
            Region {
                target_offset: 0,
                length: raw_payload.len() as u32,
                source: PartSource::Patch {
                    patch_idx: PatchIndex::new(0),
                    offset: 0,
                    kind: PatchSourceKind::Raw {
                        len: raw_payload.len() as u32,
                    },
                    decoded_skip: 0,
                },
                expected: PartExpected::SizeOnly,
            },
            Region {
                target_offset: raw_payload.len() as u64,
                length: deflate_src.len() as u32,
                source: PartSource::Patch {
                    patch_idx: PatchIndex::new(0),
                    offset: 256,
                    kind: PatchSourceKind::Deflated {
                        compressed_len: compressed.len() as u32,
                        decompressed_len: deflate_src.len() as u32,
                    },
                    decoded_skip: 0,
                },
                expected: PartExpected::SizeOnly,
            },
        ];
        let plan = plan_with_regions(regions);

        let mut src = MemoryPatchSource::new(source_buf);
        let plan = plan.with_crc32(&mut src).expect("with_crc32");

        let raw_expected = crc32fast::hash(&raw_payload);
        let def_expected = crc32fast::hash(&deflate_src);
        assert_eq!(
            plan.targets[0].regions[0].expected,
            PartExpected::Crc32(raw_expected)
        );
        assert_eq!(
            plan.targets[0].regions[1].expected,
            PartExpected::Crc32(def_expected)
        );
    }

    #[test]
    fn with_crc32_deflated_honors_decoded_skip() {
        // Compress a 256-byte block; build a region that slices [128..256] of
        // the decompressed output. Pin the CRC against the canonical slice.
        let payload: Vec<u8> = (0..256u32).map(|i| (i * 11) as u8).collect();
        let mut enc = DeflateEncoder::new(Vec::new(), Compression::default());
        enc.write_all(&payload).unwrap();
        let compressed = enc.finish().unwrap();

        let mut source_buf = vec![0u8; 4096];
        source_buf[100..100 + compressed.len()].copy_from_slice(&compressed);

        let regions = vec![Region {
            target_offset: 0,
            length: 128,
            source: PartSource::Patch {
                patch_idx: PatchIndex::new(0),
                offset: 100,
                kind: PatchSourceKind::Deflated {
                    compressed_len: compressed.len() as u32,
                    decompressed_len: payload.len() as u32,
                },
                decoded_skip: 128,
            },
            expected: PartExpected::SizeOnly,
        }];
        let plan = plan_with_regions(regions);
        let mut src = MemoryPatchSource::new(source_buf);
        let plan = plan.with_crc32(&mut src).unwrap();

        let expected = crc32fast::hash(&payload[128..256]);
        assert_eq!(
            plan.targets[0].regions[0].expected,
            PartExpected::Crc32(expected)
        );
    }

    #[test]
    fn with_crc32_uses_canonical_zeros() {
        // Pin the CRC of 128 zero bytes. The crc32 of the all-zero payload of
        // length N is a fixed value — `crc32fast::hash(&[0u8; 128])`.
        let regions = vec![Region {
            target_offset: 0,
            length: 128,
            source: PartSource::Zeros,
            expected: PartExpected::Zeros,
        }];
        let plan = plan_with_regions(regions);
        let mut src = MemoryPatchSource::new(Vec::new());
        let plan = plan.with_crc32(&mut src).unwrap();

        let expected = crc32fast::hash(&[0u8; 128]);
        assert_eq!(
            plan.targets[0].regions[0].expected,
            PartExpected::Crc32(expected)
        );
    }

    #[test]
    fn with_crc32_uses_canonical_empty_block() {
        let regions = vec![Region {
            target_offset: 0,
            length: 128,
            source: PartSource::EmptyBlock { units: 1 },
            expected: PartExpected::EmptyBlock { units: 1 },
        }];
        let plan = plan_with_regions(regions);
        let mut src = MemoryPatchSource::new(Vec::new());
        let plan = plan.with_crc32(&mut src).unwrap();

        let mut buf = Vec::with_capacity(128);
        crate::apply::sqpk::write_empty_block(&mut std::io::Cursor::new(&mut buf), 0, 1).unwrap();
        let expected = crc32fast::hash(&buf);
        assert_eq!(
            plan.targets[0].regions[0].expected,
            PartExpected::Crc32(expected)
        );
    }

    #[test]
    fn with_crc32_short_stream_after_prior_region_does_not_fold_stale_bytes() {
        // Regression: `decompressed_scratch` in `patch_region_crc` is reused
        // across regions and never zeroed. If a Deflated region's stream
        // produces fewer bytes than its declared `decompressed_len`, the
        // pre-fix code hashed `decompressed_scratch[skip..end]` — including
        // stale bytes left over from a prior region's decompression. The CRC
        // must be derived only from bytes the decoder actually produced.
        let first_payload: Vec<u8> = (0..96u8).collect();
        let second_payload: &[u8] = b"abcd";

        let compress = |raw: &[u8]| {
            let mut enc = DeflateEncoder::new(Vec::new(), Compression::default());
            enc.write_all(raw).unwrap();
            enc.finish().unwrap()
        };
        let first_compressed = compress(&first_payload);
        let second_compressed = compress(second_payload);

        let mut src_buf = Vec::new();
        let first_offset = src_buf.len() as u64;
        src_buf.extend_from_slice(&first_compressed);
        let second_offset = src_buf.len() as u64;
        src_buf.extend_from_slice(&second_compressed);

        let declared_second_len: u32 = first_payload.len() as u32;
        let regions = vec![
            Region {
                target_offset: 0,
                length: first_payload.len() as u32,
                source: PartSource::Patch {
                    patch_idx: PatchIndex::new(0),
                    offset: first_offset,
                    kind: PatchSourceKind::Deflated {
                        compressed_len: first_compressed.len() as u32,
                        decompressed_len: first_payload.len() as u32,
                    },
                    decoded_skip: 0,
                },
                expected: PartExpected::SizeOnly,
            },
            Region {
                target_offset: u64::from(first_payload.len() as u32),
                length: declared_second_len,
                source: PartSource::Patch {
                    patch_idx: PatchIndex::new(0),
                    offset: second_offset,
                    kind: PatchSourceKind::Deflated {
                        compressed_len: second_compressed.len() as u32,
                        decompressed_len: declared_second_len,
                    },
                    decoded_skip: 0,
                },
                expected: PartExpected::SizeOnly,
            },
        ];
        let plan = plan_with_regions(regions);
        let mut src = MemoryPatchSource::new(src_buf);
        let plan = plan.with_crc32(&mut src).unwrap();

        let expected_second = crc32fast::hash(second_payload);
        let leaked_second = {
            let mut buf = Vec::with_capacity(declared_second_len as usize);
            buf.extend_from_slice(second_payload);
            buf.extend_from_slice(&first_payload[second_payload.len()..]);
            crc32fast::hash(&buf)
        };
        let got = match &plan.targets[0].regions[1].expected {
            PartExpected::Crc32(c) => *c,
            other => panic!("expected Crc32, got {other:?}"),
        };
        assert_eq!(
            got, expected_second,
            "CRC must be of decoded bytes only (got {got:#x}, expected {expected_second:#x})"
        );
        assert_ne!(
            got, leaked_second,
            "CRC must not fold in stale scratch bytes from a prior region"
        );
    }

    #[test]
    fn with_crc32_drops_input_on_midway_source_failure() {
        // Two targets. Target 0's regions can be read from the source. Target 1's
        // Patch region points past the source buffer, so its read fails. The
        // contract: on Err return, the input plan was consumed and no partially-
        // populated plan is returned — staged CRCs are discarded.
        let payload: Vec<u8> = (0..32u8).collect();
        let mut src_buf = vec![0u8; 64];
        src_buf[..payload.len()].copy_from_slice(&payload);

        let plan_targets = vec![
            Target {
                path: TargetPath::Generic("a.bin".into()),
                final_size: payload.len() as u64,
                regions: vec![Region {
                    target_offset: 0,
                    length: payload.len() as u32,
                    source: PartSource::Patch {
                        patch_idx: PatchIndex::new(0),
                        offset: 0,
                        kind: PatchSourceKind::Raw {
                            len: payload.len() as u32,
                        },
                        decoded_skip: 0,
                    },
                    expected: PartExpected::SizeOnly,
                }],
            },
            Target {
                path: TargetPath::Generic("b.bin".into()),
                final_size: 4096,
                regions: vec![Region {
                    target_offset: 0,
                    length: 32,
                    source: PartSource::Patch {
                        patch_idx: PatchIndex::new(0),
                        // Past the 64-byte source buffer: MemoryPatchSource
                        // returns PatchSourceTooShort, surfacing as Err.
                        offset: 4096,
                        kind: PatchSourceKind::Raw { len: 32 },
                        decoded_skip: 0,
                    },
                    expected: PartExpected::SizeOnly,
                }],
            },
        ];
        let plan = Plan {
            schema_version: Plan::CURRENT_SCHEMA_VERSION,
            platform: Platform::Win32,
            patches: vec![PatchRef {
                name: "synthetic".into(),
                patch_type: None,
            }],
            targets: plan_targets,
            fs_ops: vec![],
        };

        let mut src = MemoryPatchSource::new(src_buf);
        let err = plan
            .with_crc32(&mut src)
            .expect_err("second target's read must fail");
        assert!(
            matches!(err, crate::IndexError::PatchSourceTooShort { .. }),
            "expected PatchSourceTooShort, got {err:?}"
        );
    }

    #[test]
    fn crc32_of_empty_block_matches_explicit_buffer() {
        // Build the canonical payload by hand (20-byte header + zeros) and
        // confirm the streaming hash returns the same CRC across a range of
        // units values, including one large enough to exercise many loop
        // iterations (128 KiB / 64 KiB chunk = ≥2 iterations).
        for units in [1u32, 2, 4, 8, 16, 100, 1024, 8192] {
            let mut buf = vec![0u8; (units as usize) * 128];
            buf[0..4].copy_from_slice(&128u32.to_le_bytes());
            buf[12..16].copy_from_slice(&units.wrapping_sub(1).to_le_bytes());
            let expected = crc32fast::hash(&buf);
            let got = crc32_of_empty_block(units).unwrap();
            assert_eq!(got, expected, "units={units}");
        }
    }

    #[test]
    fn crc32_of_empty_block_rejects_zero_units() {
        let err = crc32_of_empty_block(0).unwrap_err();
        assert!(
            matches!(err, crate::IndexError::InvalidField { context } if context.contains("non-zero")),
            "got {err:?}"
        );
    }

    #[test]
    fn with_crc32_skips_unavailable_regions() {
        let regions = vec![Region {
            target_offset: 0,
            length: 32,
            source: PartSource::Unavailable,
            expected: PartExpected::SizeOnly,
        }];
        let plan = plan_with_regions(regions);
        let mut src = MemoryPatchSource::new(Vec::new());
        let plan = plan
            .with_crc32(&mut src)
            .expect("must not error on Unavailable");
        assert_eq!(plan.targets[0].regions[0].expected, PartExpected::SizeOnly);
    }
}