supreme_hook_config/

resolver.rs

//! Disk-aware resolution: given a loaded [`HookConfig`] plus a game
//! directory and a scratch/temp directory, decide what should happen to a
//! given `rel_key` for reads, writes, and deletes, including staging
//! patched replacement files and seeding write targets.
//!
//! This is deliberately an explicit, constructible type rather than a set
//! of free functions over hidden global state. Two very different
//! consumers need it:
//! - `supreme_hook_proxy` (the DLL): one `HookResolver`, loaded lazily the
//!   first time the game probes a magic trigger path, then reused for the
//!   rest of the process's life.
//! - anything else that wants to know "what would happen to this path"
//!   without injecting into the game at all, e.g. a launcher page that
//!   reads/writes a game file and wants mod redirection to apply exactly
//!   as it would in-game.
//!
//! Each consumer owns its own lifecycle/caching policy on top of this; the
//! type itself has no global state and no opinion on when it should be
//! constructed.

use crate::hook_config::{MATCH_OPTIONS, matched_suffix};
use crate::patch::{MemoryPatch, apply_all};
use crate::{
    DEFAULT_MODS_DIR_NAME, HookConfig, HookConfigError, RedirectionMode, RedirectionRule,
    ResolvedAction, RuleTarget,
};
use glob::Pattern;
use log::{debug, error, info, warn};
use std::collections::HashSet;
use std::path::{Path, PathBuf};

/// Cap on the number of *redirect* hops a single resolution chain may
/// follow (see [`HookResolver::resolve_chain`] /
/// [`HookResolver::resolve_chain_for_target`]) before it's forced to
/// stop. Identity hops (a matching rule with no real redirect) aren't
/// counted here, they can't loop, since scanning a stage always moves
/// strictly forward through a finite rule list. This bound exists for
/// the redirect-following part specifically, which *can* cycle
/// (`A -> B -> A`) if a mod config is misconfigured. `panic = "abort"`
/// on this workspace means a runaway chain would hang the game's file
/// I/O rather than unwind, so this has to be a hard, provable bound, not
/// a best-effort one.
const MAX_REDIRECT_CHAIN_DEPTH: usize = 8;

/// Owns a merged [`HookConfig`] plus the two directories every resolution
/// needs: the game's root directory (to reconstruct original paths) and a
/// scratch directory (to stage patched replacement files).
#[derive(Debug)]
pub struct HookResolver {
    config: HookConfig,
    game_dir: PathBuf,
    temp_dir: PathBuf,
}

/// The outcome of walking [`HookResolver::resolve_chain`].
struct ChainOutcome {
    /// `None` means the chain was blocked outright by a `hard_error`
    /// hop with no replacement available, nothing should be served,
    /// regardless of what patches or earlier redirects were found
    /// along the way.
    terminal_path: Option<PathBuf>,
    /// Patches from every stage visited, in visit order (and, within a
    /// stage, in rule-list order). Empty if the chain never produced
    /// anything to patch.
    patches: Vec<MemoryPatch>,
}

impl HookResolver {
    /// Builds a resolver directly from an already-loaded [`HookConfig`].
    /// Prefer [`HookResolver::load`] unless you've already got a
    /// `HookConfig` from somewhere else (e.g. a launcher page previewing a
    /// config that hasn't been written to `mods_dir` yet).
    #[must_use]
    pub fn new(config: HookConfig, game_dir: PathBuf, temp_dir: PathBuf) -> Self {
        Self {
            config,
            game_dir,
            temp_dir,
        }
    }

    /// Loads and merges every enabled mod's rules from `mods_dir` (see
    /// [`HookConfig::load_from_mods_dir`]), rewriting every rule's
    /// relative `target` to be absolute against `game_dir`, and wraps the
    /// result in a resolver ready to use.
    ///
    /// Skipped mods (present in the active preset's enabled list but
    /// whose `mod.json` couldn't be read/parsed) are returned alongside
    /// the resolver rather than logged here, this crate takes no logging
    /// dependency beyond the `log` facade, so it's the caller's call how
    /// (or whether) to surface them.
    ///
    /// A missing `mods.json` is treated as "no mods enabled" rather
    /// than a fatal error, the resolver falls back to an empty rule set
    /// and every resolution becomes a no-op `PassThrough`.
    #[must_use]
    pub fn load(
        mods_dir: &Path,
        game_dir: PathBuf,
        temp_dir: PathBuf,
    ) -> (Self, Vec<(String, HookConfigError)>) {
        info!("Loading mods from: {}", mods_dir.display());

        let (mut config, skipped) = HookConfig::load_from_mods_dir(mods_dir).unwrap_or_else(|e| {
            debug!(
                "Could not load {} ({e}); proceeding with no mods enabled",
                mods_dir.display()
            );
            (HookConfig::default(), Vec::new())
        });

        for rule in &mut config.rules {
            match &mut rule.target {
                Some(RuleTarget::Path(target)) if target.is_relative() => {
                    *target = game_dir.join(&*target);
                }
                Some(RuleTarget::Managed { local, .. }) if local.is_relative() => {
                    *local = game_dir.join(&*local);
                }
                _ => {}
            }
        }

        debug!("Loaded config: {config:#?}");

        (Self::new(config, game_dir, temp_dir), skipped)
    }

    /// Convenience wrapper around [`HookResolver::load`] using the
    /// conventional `<game_dir>/.supreme/mods` mods directory
    /// ([`DEFAULT_MODS_DIR_NAME`]).
    #[must_use]
    pub fn load_default(
        game_dir: PathBuf,
        temp_dir: PathBuf,
    ) -> (Self, Vec<(String, HookConfigError)>) {
        let mods_dir = game_dir.join(DEFAULT_MODS_DIR_NAME);
        Self::load(&mods_dir, game_dir, temp_dir)
    }

    /// The merged config this resolver was built from.
    #[must_use]
    pub fn config(&self) -> &HookConfig {
        &self.config
    }

    /// The game root directory this resolver reconstructs original paths
    /// against.
    #[must_use]
    pub fn game_dir(&self) -> &Path {
        &self.game_dir
    }

    fn original_path(&self, rel_key: &str) -> PathBuf {
        self.game_dir
            .join(rel_key.replace('/', std::path::MAIN_SEPARATOR_STR))
    }

    /// Returns the persistent temp path that mirrors the original relative
    /// structure. E.g. rel_key `data/levels/menu_strings.txt` maps to
    /// `<temp_dir>/data/levels/menu_strings.txt`.
    ///
    /// This ensures debuggable file names in the temp directory, idempotent
    /// staging (the same rel_key always maps to the same temp path), and
    /// consistency across repeated reads within a session.
    fn structured_temp_path(&self, rel_key: &str) -> PathBuf {
        self.temp_dir
            .join(rel_key.replace('/', std::path::MAIN_SEPARATOR_STR))
    }

    /// Finds the first rule in `self.config.rules[start_index..]` whose
    /// glob matches `rel_key`, returning its absolute index into
    /// `self.config.rules` (so a caller can resume scanning just past it,
    /// letting a subsequent rule for the same `rel_key` still apply,
    /// see [`Self::resolve_chain`]).
    fn next_matching_rule(
        &self,
        rel_key: &str,
        start_index: usize,
    ) -> Option<(usize, &RedirectionRule)> {
        let normalized = rel_key.replace('\\', "/");
        self.config
            .rules
            .get(start_index..)?
            .iter()
            .enumerate()
            .find_map(|(i, rule)| {
                Pattern::new(&rule.glob_pattern)
                    .is_ok_and(|pattern| pattern.matches_with(&normalized, MATCH_OPTIONS))
                    .then_some((start_index + i, rule))
            })
    }

    /// Re-expresses an absolute path as a `rel_key` (matchable against
    /// rule globs the same way any other `rel_key` is), if it falls
    /// under `game_dir` at all. Case-insensitive, matching
    /// [`crate::hook_config::matched_suffix`]'s handling of Windows
    /// paths, and deliberately doesn't distinguish a target that lands
    /// back inside `game_dir` from one that doesn't happen to right now
    /// a mod's own target folder living under `game_dir` chains
    /// exactly the same way a vanilla game asset path would.
    ///
    /// Returns `None` when `path` isn't expressible relative to
    /// `game_dir` at all (a different drive, or simply outside it
    /// entirely, the common case for a target pointing into
    /// `.supreme/mods/...`). That's not a special case to handle further
    /// up: no rule's glob is matched against anything but a `game_dir`-
    /// relative path, so a chain naturally ends the moment it steps
    /// outside it.
    fn rel_key_of(&self, path: &Path) -> Option<String> {
        let game_dir_lower = self
            .game_dir
            .to_string_lossy()
            .replace('\\', "/")
            .trim_end_matches('/')
            .to_lowercase();
        let path_lower = path.to_string_lossy().replace('\\', "/").to_lowercase();

        let rest = path_lower.strip_prefix(&game_dir_lower)?;
        let rest = rest.strip_prefix('/').unwrap_or(rest);
        (!rest.is_empty()).then(|| rest.to_string())
    }

    /// Walks the chain of rules matching `rel_key` for a READ, and then
    /// whatever `rel_key` each real redirect lands on in turn, the
    /// "first matching rule wins" replacement.
    ///
    /// A `rel_key` is resolved in **stages**. Within a stage, rules are
    /// scanned in list order, resuming wherever the previous match in
    /// that same stage left off:
    ///
    /// - A rule whose `target` is configured *and* whose computed target
    ///   file currently exists is a **redirect hop**: it ends the
    ///   current stage. Its own `patches` are recorded for this chain
    ///   (even though, if the chain continues, they won't be applied to
    ///   *this* stage's file, see the note below), and resolution moves
    ///   to the *next* stage: the redirect target, re-expressed as a
    ///   `rel_key` via [`Self::rel_key_of`] and scanned again from the
    ///   very top of the rule list (a fresh path can be matched by any
    ///   rule, not just ones after the redirecting rule's position).
    /// - A rule with no `target`, or whose target file doesn't currently
    ///   exist, is an **identity hop**: it does not end the stage. In
    ///   `graceful_fallback` mode, its `patches` are recorded and
    ///   scanning continues *at the same `rel_key`*, from the next rule
    ///   in the list, this is what lets a "patch the original file in
    ///   place" rule (`target: None` with `patches`) sit alongside, and
    ///   stack with, other rules for the same path instead of the first
    ///   one shadowing the rest. In `hard_error` mode it blocks
    ///   resolution immediately: nothing accumulated so far (from this
    ///   or any earlier stage) is served.
    /// - A stage with no further matching rule is **terminal**: its
    ///   physical file is `original_path(current_rel_key)`, which for
    ///   every stage after the first is exactly the previous stage's
    ///   redirect target (by construction of [`Self::rel_key_of`] /
    ///   [`Self::original_path`], they're inverses of each other for
    ///   any path that round-trips through both).
    ///
    /// **Patches accumulate across every stage visited, in visit order,
    /// and are applied once, at the very end, to the terminal file**,
    /// including a redirect hop's own `patches`, deferred rather than
    /// applied immediately to its own target, if the chain continues
    /// past it. A patch authored assuming it runs against one particular
    /// stage's byte layout could end up running against a *different*
    /// terminal file if a later rule redirects further; that's an
    /// authoring concern for chained mods, not something validated here.
    ///
    /// A visited-`rel_key` set (cycle guard) plus
    /// [`MAX_REDIRECT_CHAIN_DEPTH`] stop a misconfigured or cyclic chain
    /// deterministically.
    fn resolve_chain(&self, rel_key: &str) -> ChainOutcome {
        let mut current = rel_key.to_string();
        let mut visited: HashSet<String> = HashSet::from([current.clone()]);
        let mut patches: Vec<MemoryPatch> = Vec::new();
        let mut redirect_hops = 0usize;

        loop {
            let mut resume_index = 0;
            loop {
                let Some((idx, rule)) = self.next_matching_rule(&current, resume_index) else {
                    // Terminal: nothing further matches this stage.
                    return ChainOutcome {
                        terminal_path: Some(self.original_path(&current)),
                        patches,
                    };
                };

                let structured_target = compute_target_path(rule, &current);
                let is_redirect = structured_target.as_ref().is_some_and(|p| p.exists());

                if is_redirect {
                    patches.extend(rule.patches.iter().cloned());
                    let target = structured_target.expect("is_redirect implies Some");

                    redirect_hops += 1;
                    if redirect_hops > MAX_REDIRECT_CHAIN_DEPTH {
                        warn!(
                            "Redirect chain resolving {rel_key} exceeded depth cap of \
                             {MAX_REDIRECT_CHAIN_DEPTH}, stopping at {}",
                            target.display()
                        );
                        return ChainOutcome {
                            terminal_path: Some(target),
                            patches,
                        };
                    }

                    match self.rel_key_of(&target) {
                        Some(next) if visited.insert(next.clone()) => {
                            current = next;
                            break; // proceed to the next stage
                        }
                        Some(_) => {
                            warn!(
                                "Redirect cycle detected resolving {rel_key}, stopping at {}",
                                target.display()
                            );
                            return ChainOutcome {
                                terminal_path: Some(target),
                                patches,
                            };
                        }
                        None => {
                            // Not expressible relative to game_dir --
                            // nothing further can match it, so this is
                            // the terminal file.
                            return ChainOutcome {
                                terminal_path: Some(target),
                                patches,
                            };
                        }
                    }
                } else if rule.mode == RedirectionMode::HardError {
                    return ChainOutcome {
                        terminal_path: None,
                        patches: Vec::new(),
                    };
                } else {
                    patches.extend(rule.patches.iter().cloned());
                    resume_index = idx + 1;
                    // keep scanning the same stage
                }
            }
        }
    }

    /// Write/delete equivalent of [`Self::resolve_chain`]: walks the
    /// same stage-by-stage structure, a rule with no `target` is an
    /// identity hop that lets scanning continue past it within the same
    /// stage, and a rule with a `target` is a redirect hop that moves to
    /// the next stage, but existence-independent (a `target` alone is
    /// enough to redirect, matching today's write behavior: a write
    /// always seeds/creates its target rather than waiting for it to
    /// already exist) and collects no patches (a read-only concept,
    /// unchanged).
    ///
    /// A stage with no further matching rule is terminal, exactly as in
    /// [`Self::resolve_chain`], and exactly as there, if we arrived at
    /// this stage via at least one real redirect, that redirect's
    /// computed target *is* the resolved destination (kept byte-exact,
    /// casing included, see the `last_target` note in the body; the old
    /// `original_path(rel_key_of(target))` re-expression lowercased it).
    /// Only when no redirect ever happened, the rel_key
    /// either matched nothing, or matched only identity hops throughout
    /// does this report `None`, preserving the original single-hop
    /// behavior for a `target: None` rule (straight `PassThrough`, no
    /// seed-and-redirect machinery kicking in for a file that was never
    /// meant to be redirected at all).
    ///
    /// Returns the **last** rule reached (for its `mode`, which
    /// [`Self::resolve_path_for_delete`]'s missing-file fallback uses,
    /// "everything happens at the end of the redirection path," not just
    /// the first rule matched) together with the terminal stage's
    /// structured target path, or `None` if no rule ever matched at all.
    fn resolve_chain_for_target(
        &self,
        rel_key: &str,
    ) -> Option<(&RedirectionRule, Option<PathBuf>)> {
        let mut current = rel_key.to_string();
        let mut visited: HashSet<String> = HashSet::from([current.clone()]);
        let mut redirect_hops = 0usize;
        let mut last_rule: Option<&RedirectionRule> = None;
        // The last REAL redirect target, kept verbatim: re-expressing the
        // target through `rel_key_of` would fold case to match rule globs
        // and silently rewrite a declared target's casing whenever it
        // lived under game_dir (`.supreme/mods/...` always does). On NTFS
        // that is the same file, but the engine's byte-exact bookkeeping
        // (the managed-file close hook compares the write target with the
        // registered local) never saw them as the same path, a MixedCase
        // managed `local` then never captured its game writes. Carrying
        // the computed target forward keeps the declared path byte-exact;
        // same file either way, the declared spelling is simply preserved.
        let mut last_target: Option<PathBuf> = None;

        loop {
            let mut resume_index = 0;
            loop {
                let Some((idx, rule)) = self.next_matching_rule(&current, resume_index) else {
                    // Terminal: nothing further matches this stage. When at
                    // least one real redirect happened, its LAST computed
                    // target IS the resolved destination (byte-exact, casing
                    // included); `redirect_hops == 0` means only identity
                    // hops matched, so there is no target at all.
                    return last_rule.map(|r| (r, last_target));
                };
                last_rule = Some(rule);

                let Some(target) = compute_target_path(rule, &current) else {
                    // identity hop: no target at all, keep scanning this stage
                    resume_index = idx + 1;
                    continue;
                };

                redirect_hops += 1;
                last_target = Some(target.clone());
                if redirect_hops > MAX_REDIRECT_CHAIN_DEPTH {
                    warn!(
                        "Write/delete redirect chain resolving {rel_key} exceeded depth \
                         cap of {MAX_REDIRECT_CHAIN_DEPTH}, stopping at {}",
                        target.display()
                    );
                    return Some((rule, Some(target)));
                }

                match self.rel_key_of(&target) {
                    Some(next) if visited.insert(next.clone()) => {
                        current = next;
                        break; // proceed to the next stage
                    }
                    Some(_) => {
                        warn!(
                            "Write/delete redirect cycle resolving {rel_key}, stopping at {}",
                            target.display()
                        );
                        return Some((rule, Some(target)));
                    }
                    None => return Some((rule, Some(target))),
                }
            }
        }
    }

    /// Resolves a game-relative path for READ operations.
    ///
    /// Flow:
    /// 1. Walk the redirect/patch chain ([`Self::resolve_chain`]) to find
    ///    the terminal physical file and the full accumulated patch list.
    /// 2. If patches exist, stage to a structured, persistent temp path.
    ///    - If any accumulated patch is a [`MemoryPatch::Script`], always
    ///      re-read the base file and re-run every patch as script can
    ///      derive its output from the current time variable, so it must
    ///      run fresh on every read rather than being served from a stale
    ///      cached stage.
    ///    - Otherwise, if the temp file already exists and is newer than
    ///      the base file, reuse it; otherwise read base + apply patches +
    ///      write to the structured temp path.
    /// 3. If no patches, return the resolved file directly.
    ///
    /// Not cached beyond the temp-file reuse above: external writers may
    /// change the underlying files at any time, so every call re-evaluates
    /// filesystem state.
    #[must_use]
    pub fn resolve_path(&self, rel_key: &str) -> ResolvedAction {
        let chain = self.resolve_chain(rel_key);

        let Some(base_path) = chain.terminal_path else {
            debug!("RESOLVE {rel_key} => HardErrorMissingFile (blocked)");
            return ResolvedAction::HardErrorMissingFile;
        };

        let patches = chain.patches.as_slice();
        let is_original = base_path == self.original_path(rel_key);

        // What to serve if there's nothing to patch -- also the fallback
        // if patch staging itself fails below.
        let no_patch_action = || {
            if is_original {
                ResolvedAction::PassThrough
            } else {
                ResolvedAction::Redirect {
                    replacement_path: base_path.clone(),
                }
            }
        };

        let final_action = if patches.is_empty() {
            no_patch_action()
        } else {
            let temp_path = self.structured_temp_path(rel_key);

            // A `Script` patch can derive its output from `timestamp` so
            // it can behave differently on every read (randomization).
            // Plain find/replace patches (deterministic in their output)
            // keep the existing "only restage when the base file changed"
            // behavior.
            let has_script_patch = patches
                .iter()
                .any(|p| matches!(p, MemoryPatch::Script { .. }));

            let needs_restage = if has_script_patch {
                true
            } else if temp_path.exists() {
                match (std::fs::metadata(&base_path), std::fs::metadata(&temp_path)) {
                    (Ok(bm), Ok(tm)) => match (bm.modified(), tm.modified()) {
                        (Ok(bt), Ok(tt)) => bt > tt,
                        _ => true,
                    },
                    _ => true,
                }
            } else {
                true
            };

            if needs_restage {
                match (|| -> std::io::Result<()> {
                    if let Some(parent) = temp_path.parent() {
                        std::fs::create_dir_all(parent)?;
                    }
                    let data = std::fs::read(&base_path)?;

                    // Handle fallible patch application
                    let patched = match apply_all(patches, &data, rel_key) {
                        Ok(p) => p,
                        Err(e) => {
                            error!(
                                "Patch application failed for {}: {}",
                                base_path.display(),
                                e
                            );
                            return Err(std::io::Error::other(e.to_string()));
                        }
                    };

                    std::fs::write(&temp_path, &patched)?;
                    Ok(())
                })() {
                    Ok(()) => ResolvedAction::Redirect {
                        replacement_path: temp_path,
                    },
                    Err(e) => {
                        error!("IO error staging {}: {e}", base_path.display());
                        no_patch_action()
                    }
                }
            } else {
                ResolvedAction::Redirect {
                    replacement_path: temp_path,
                }
            }
        };

        debug!("RESOLVE {rel_key} => {final_action:?}");
        final_action
    }

    /// Whether a directory listing should hide the *original* game file for
    /// `rel_key`, so that listings agree with what a direct open of the same
    /// rel_key would do (`resolve_path`): a `hard_error` rule hides the
    /// original unconditionally, the moment it matches, exactly as it would
    /// on a read, it never falls back to showing stale original content
    /// just because nothing's been staged in its place yet. A
    /// `graceful_fallback` rule only hides the original once a real
    /// replacement exists on disk to show instead; until then the original
    /// stays visible, same as a read would fall back to serving it.
    ///
    /// Deliberately uses only the pure decision layer
    /// ([`Self::resolve_chain`], existence checks only, no I/O writes)
    /// rather than the full `resolve_path`, a directory listing walks
    /// every entry in the directory, and `resolve_path` stages patched
    /// files to disk on demand, which would mean every entry in a patched
    /// directory gets eagerly (re-)staged just to decide whether to show
    /// it. Patch staging stays lazy, deferred to the first time a file is
    /// actually opened.
    #[must_use]
    pub fn should_hide_original_entry(&self, rel_key: &str) -> bool {
        let chain = self.resolve_chain(rel_key);
        match chain.terminal_path {
            None => true, // blocked by a hard_error hop -- hidden either way
            Some(base_path) => {
                base_path != self.original_path(rel_key) || !chain.patches.is_empty()
            }
        }
    }

    /// Resolves the physical target path for a rel_key destined for a
    /// write-type operation, ensuring its parent directory exists. Returns
    /// `None` if no rule matches (at any stage of the chain), the
    /// directory couldn't be created, or the target is the original file.
    /// Call [`Self::has_write_redirect`] to distinguish an unredirected
    /// path from a configured target that could not be prepared.
    #[must_use]
    pub fn resolve_write_target(&self, rel_key: &str) -> Option<PathBuf> {
        let (_rule, target_path) = self.resolve_chain_for_target(rel_key)?;
        let target_path = target_path?;

        let normalized_key = rel_key.to_lowercase();
        if self.rel_key_of(&target_path).as_deref() == Some(normalized_key.as_str()) {
            error!("Write target for {rel_key} resolves back to the original file");
            return None;
        }

        if let Some(parent) = target_path.parent()
            && let Err(e) = std::fs::create_dir_all(parent)
        {
            error!(
                "Failed to create target directory {}: {e}",
                parent.display()
            );
            return None;
        }

        Some(target_path)
    }

    /// Whether a write rule has a target, even when its directory cannot be
    /// prepared. A rename must fail instead of falling through to the
    /// unmodified game path in that case.
    #[must_use]
    pub fn has_write_redirect(&self, rel_key: &str) -> bool {
        self.resolve_chain_for_target(rel_key)
            .is_some_and(|(_, target)| target.is_some())
    }

    /// Resolves a game-relative path for WRITE/CREATE/OVERWRITE operations.
    ///
    /// Never opens the original game file in write mode: if the target
    /// doesn't exist yet, it's seeded by copying the original first (see
    /// [`seed_target_file`]). Patches are not applied for writes, they're
    /// a read-time transform.
    #[must_use]
    pub fn resolve_path_for_write(&self, rel_key: &str) -> ResolvedAction {
        let Some((_rule, Some(target_path))) = self.resolve_chain_for_target(rel_key) else {
            return ResolvedAction::PassThrough;
        };

        // A self-redirect (including one reached after several hops) cannot
        // protect the original file: opening that target would write through
        // to the game installation. Refuse the write instead.
        let normalized_key = rel_key.to_lowercase();
        if self.rel_key_of(&target_path).as_deref() == Some(normalized_key.as_str()) {
            error!("Write target for {rel_key} resolves back to the original file");
            return ResolvedAction::HardErrorMissingFile;
        }

        if let Some(parent) = target_path.parent()
            && let Err(e) = std::fs::create_dir_all(parent)
        {
            error!("Cannot prepare write target {}: {e}", target_path.display());
            return ResolvedAction::HardErrorMissingFile;
        }

        let original_path = self.original_path(rel_key);
        if original_path.exists() {
            match seed_target_file(&original_path, &target_path) {
                Ok(true) => debug!(
                    "WRITE SEED: copied original {} -> {}",
                    original_path.display(),
                    target_path.display()
                ),
                Ok(false) => debug!(
                    "WRITE SEED: {} already present, skipping",
                    target_path.display()
                ),
                Err(e) => {
                    error!("Failed to seed target file {}: {e}", target_path.display());
                    return ResolvedAction::HardErrorMissingFile;
                }
            }
        } else if !target_path.exists() {
            debug!(
                "WRITE CREATE: original missing, caller will create new file at {}",
                target_path.display()
            );
        }

        debug!("WRITE RESOLVE {rel_key} -> {}", target_path.display());

        ResolvedAction::Redirect {
            replacement_path: target_path,
        }
    }

    /// Resolves a game-relative path for DELETE operations.
    ///
    /// - If a hooked file exists at the end of the redirect chain (static
    ///   config replacement, or a file previously written/created into a
    ///   `target`), the delete is redirected there.
    /// - If no hooked file exists: the **last** rule reached while
    ///   walking the chain decides the fallback, `hard_error` mode
    ///   blocks the delete (consistent with hard_error's "hide missing
    ///   files" read contract); `graceful_fallback` mode falls back to
    ///   the original. This is deliberately the last rule reached, not
    ///   the first one matched, a delete on a path that was redirected
    ///   one or more times follows the chain to its end, same as a read
    ///   or a write would, and it's the rule governing that terminal
    ///   stage whose `mode` actually applies.
    ///
    /// Always re-checks the filesystem fresh, same as [`resolve_path`].
    /// Patches are irrelevant here.
    ///
    /// Deliberately does *not* consult [`HookConfig::resolve`] the way
    /// [`resolve_path`] does: a delete must land on exactly the file the
    /// create wrote, so both share one suffix implementation
    /// ([`compute_target_path`], via [`crate::matched_suffix`]) as the
    /// single source of truth for "where does this rel_key's file live".
    ///
    /// [`resolve_path`]: HookResolver::resolve_path
    #[must_use]
    pub fn resolve_path_for_delete(&self, rel_key: &str) -> ResolvedAction {
        let Some((rule, target_path)) = self.resolve_chain_for_target(rel_key) else {
            return ResolvedAction::PassThrough;
        };

        let final_action = match target_path {
            Some(path) if path.exists() => ResolvedAction::Redirect {
                replacement_path: path,
            },
            _ => match rule.mode {
                RedirectionMode::HardError => ResolvedAction::HardErrorMissingFile,
                RedirectionMode::GracefulFallback => ResolvedAction::PassThrough,
            },
        };

        debug!("DELETE RESOLVE {rel_key} => {final_action:?}");
        final_action
    }

    /// Collects mod filenames directly under a given relative directory, by
    /// scanning each matching wildcard rule's `target` directory on disk,
    /// plus injecting the single file named by any matching literal-glob
    /// rule (whose `target` is a file, not a directory to scan, see
    /// [`RedirectionRule::is_literal_glob`]).
    #[must_use]
    pub fn collect_mod_files_in_dir(&self, rel_dir: &str) -> Vec<String> {
        let mut files: Vec<String> = Vec::new();
        let rel_dir_lower = rel_dir.to_lowercase();

        for rule in &self.config.rules {
            let Some(target) = rule.target.as_ref() else {
                continue;
            };
            let glob_lower = rule.glob_pattern.to_lowercase();

            if rule.is_literal_glob() {
                let rule_dir = Path::new(&glob_lower)
                    .parent()
                    .map(|p| p.to_string_lossy().replace('\\', "/"))
                    .unwrap_or_default();
                // managed (remote-backed) targets are listed even
                // when the local file does not exist yet. The game's
                // discovery is listing-driven: without the name it never
                // probes the slot, never triggers the fetch-on-access, and
                // a remote-backed file would stay invisible forever (the
                // tournament provider had the same fix as manual
                // "view-sync" injection). A probe that arrives before the
                // first fetch resolves gracefully, that is exactly what
                // the rule's mode is for.
                let listed = target.path().exists() || target.managed().is_some();
                if rule_dir == rel_dir_lower
                    && listed
                    && let Some(name) = target.path().file_name().and_then(|n| n.to_str())
                {
                    files.push(name.to_string());
                }
                continue;
            }

            let prefix_matches = if let Some(star_pos) = glob_lower.find("**") {
                let prefix = &glob_lower[..star_pos];
                rel_dir_lower.starts_with(prefix.trim_end_matches('/').trim_end_matches('\\'))
            } else {
                let rule_dir = Path::new(&glob_lower)
                    .parent()
                    .map(|p| p.to_string_lossy().replace('\\', "/"))
                    .unwrap_or_default();
                rule_dir == rel_dir_lower
            };

            if !prefix_matches {
                continue;
            }

            let scan_dir = if let Some(star_pos) = glob_lower.find("**") {
                let prefix = &glob_lower[..star_pos];
                let suffix = rel_dir_lower
                    .strip_prefix(prefix.trim_end_matches('/').trim_end_matches('\\'))
                    .unwrap_or("")
                    .trim_start_matches('/')
                    .trim_start_matches('\\');
                if suffix.is_empty() {
                    target.path().to_path_buf()
                } else {
                    target.path().join(suffix)
                }
            } else {
                target.path().to_path_buf()
            };

            if let Ok(entries) = std::fs::read_dir(&scan_dir) {
                for entry in entries.flatten() {
                    if entry.file_type().map(|ft| ft.is_file()).unwrap_or(false)
                        && let Some(name) = entry.file_name().to_str()
                        // Repo bookkeeping artifacts (`.gitkeep` & friends)
                        // live in instance dirs too; they must never be
                        // advertised to the game's directory listings.
                        && !name.starts_with('.')
                    {
                        files.push(name.to_string());
                    }
                }
            }
        }

        files.sort_unstable();
        files.dedup();
        files
    }
}

/// Determines whether a file open operation intends to write or create.
///
/// Strictly follows Windows NT API definitions:
/// - Dispositions 0 (SUPERSEDE), 2 (CREATE), 4 (OVERWRITE), 5
///   (OVERWRITE_IF) unconditionally imply write intent.
/// - Dispositions 1 (OPEN) and 3 (OPEN_IF) are only writes if
///   `desired_access` includes GENERIC_WRITE, FILE_WRITE_DATA, or
///   FILE_APPEND_DATA.
///
/// The bitmasks here are plain NT ABI constants, not Windows-crate types,
/// so this has no platform dependency of its own, the proxy DLL calls it
/// with values decoded from a real `NtCreateFile` call; any other caller
/// (including tests) can call it with the same raw `u32`s.
#[must_use]
pub fn is_write_operation(desired_access: u32, create_disposition: u32) -> bool {
    const WRITE_ACCESS_MASK: u32 = 0x4000_0000 | 0x0000_0002 | 0x0000_0004;
    const DESTRUCTIVE_DISPOSITIONS: [u32; 4] = [0, 2, 4, 5];

    (desired_access & WRITE_ACCESS_MASK) != 0
        || DESTRUCTIVE_DISPOSITIONS.contains(&create_disposition)
}

/// Computes the full target path for a redirected file. Returns `None` if
/// the rule has no `target` configured, there's nothing to compute a path
/// against.
///
/// - **Literal glob**: `target` *is* the replacement/write file, used
///   as-is.
/// - **Wildcard glob**: preserves the relative sub-directory structure
///   below the rule's fixed prefix, via [`crate::matched_suffix`], the
///   same computation [`HookConfig::resolve`] uses. Exactly one
///   implementation, so a file written via
///   [`HookResolver::resolve_path_for_write`] and one probed via
///   [`HookResolver::resolve_path`] or
///   [`HookResolver::resolve_path_for_delete`] land at the same path
///   for the same rel_key.
#[must_use]
pub fn compute_target_path(rule: &RedirectionRule, rel_key: &str) -> Option<PathBuf> {
    let target = rule.target.as_ref()?;
    let path = target.path();

    if rule.is_literal_glob() {
        return Some(path.to_path_buf());
    }

    Some(path.join(matched_suffix(&rule.glob_pattern, rel_key)))
}

/// One remote-backed managed file declared by a [`RuleTarget::Managed`]
/// rule. A mod's `mod.json` names the file (literal glob),
/// its local path, the URL whose body is the file content, an optional
/// push URL for game writes, and the auto-refresh cadence, the
/// proxy DLL's generic managed-file engine consumes exactly this, with no
/// per-mod knowledge inside the DLL.
#[derive(Debug, Clone, PartialEq)]
pub struct ManagedFileSpec {
    /// The rule's rel_key (its literal glob, separators normalized to `/`);
    /// the hooks compare case-insensitively.
    pub rel_key: String,
    /// Absolute local path the redirect serves and the refresh engine
    /// writes (relative rule targets already resolved against `game_dir`).
    pub local: PathBuf,
    /// URL whose HTTP-GET body IS the file content, already interpolated.
    pub remote: String,
    /// Auto-refresh cadence in seconds once the file has been accessed;
    /// `None` = no polling (refresh on access only).
    pub poll_interval_secs: Option<u64>,
    /// Where every game write of the file is POSTed to, already
    /// interpolated; `None` = fetch-only (writes never uploaded).
    pub push_url: Option<String>,
}

/// Collects every [`RuleTarget::Managed`] rule from the loaded config, in
/// config order. Relative `local` paths are resolved against `game_dir`
/// exactly like [`HookResolver::load`] does, so this accepts either a
/// loaded resolver's config (absolute) or a raw authored one (relative).
/// Rules whose glob is not literal are skipped here, a wildcard glob
/// cannot name the single file a remote URL provides, and
/// [`crate::mod_config::ModConfig::validate`] already rejects them with a
/// proper error at load time; this scan just stays defensive.
#[must_use]
pub fn managed_file_specs(game_dir: &Path, config: &HookConfig) -> Vec<ManagedFileSpec> {
    let mut out = Vec::new();
    for rule in &config.rules {
        let Some(target) = &rule.target else {
            continue;
        };
        let Some((remote, poll_interval_secs, push_url)) = target.managed() else {
            continue;
        };
        if !rule.is_literal_glob() {
            continue;
        }
        let local = target.path();
        let local_abs = if local.is_absolute() {
            local.to_path_buf()
        } else {
            game_dir.join(local)
        };
        out.push(ManagedFileSpec {
            rel_key: rule.glob_pattern.replace('\\', "/"),
            local: local_abs,
            remote: remote.to_string(),
            poll_interval_secs,
            push_url: push_url.map(str::to_string),
        });
    }
    out
}

/// Seeds a sibling temporary file first, then atomically creates a hard link
/// at `target_path`. Other writers only see a complete copy, and linking does
/// not overwrite a target another writer created. The temporary file is
/// removed after the link is created (or after any error). Both paths are in
/// the same directory, so they are on the same volume. A filesystem that
/// cannot create a hard link fails the seed rather than exposing a partial
/// target or modifying the original.
///
/// Returns `Ok(true)` if this call performed the seed, `Ok(false)` if
/// another call already had (or was concurrently doing so), or `Err` for
/// any other I/O failure.
///
/// # Errors
///
/// Returns an error if `original_path` cannot be read or the copy fails
/// for a reason other than `target_path` already existing.
pub fn seed_target_file(original_path: &Path, target_path: &Path) -> std::io::Result<bool> {
    if target_path.exists() {
        return Ok(false);
    }
    let parent = target_path.parent().ok_or_else(|| {
        std::io::Error::new(
            std::io::ErrorKind::InvalidInput,
            "write target has no parent",
        )
    })?;
    let mut staged = tempfile::NamedTempFile::new_in(parent)?;
    std::io::copy(
        &mut std::fs::File::open(original_path)?,
        staged.as_file_mut(),
    )?;
    staged.as_file_mut().sync_all()?;
    match std::fs::hard_link(staged.path(), target_path) {
        Ok(()) => Ok(true),
        Err(e) if e.kind() == std::io::ErrorKind::AlreadyExists => Ok(false),
        Err(e) => Err(e),
    }
}

#[cfg(test)]
mod chain_resolution_tests {
    //! Read-side chain resolution: `resolve_path`'s replacement for
    //! "first matching rule wins" -- see `HookResolver::resolve_chain`.
    //!
    //! `identity_hop_with_patches_and_no_target_still_patches_original`
    //! is the regression guard for the exact bug this crate shipped
    //! once already: a `target: None` rule with `patches` is not an
    //! inert placeholder, it's "patch the original file in place," and
    //! must keep working exactly as before no matter how the rest of
    //! rule matching changes around it.

    use super::HookResolver;
    use crate::{
        HookConfig, MemoryPatch, RedirectionMode, RedirectionRule, RuleTarget, StringReplacement,
    };
    use std::fs;
    use std::path::PathBuf;

    struct ScratchDir(PathBuf);

    impl ScratchDir {
        fn new(name: &str) -> Self {
            let dir = std::env::temp_dir().join(format!(
                "hook_resolver_chain_test_{name}_{}",
                std::process::id()
            ));
            let _ = fs::remove_dir_all(&dir);
            fs::create_dir_all(dir.join("game")).unwrap();
            Self(dir)
        }

        fn path(&self, name: &str) -> PathBuf {
            self.0.join(name)
        }

        fn write_file(&self, name: &str, contents: &[u8]) {
            let path = self.path(name);
            fs::create_dir_all(path.parent().unwrap()).unwrap();
            fs::write(path, contents).unwrap();
        }
    }

    impl Drop for ScratchDir {
        fn drop(&mut self) {
            let _ = fs::remove_dir_all(&self.0);
        }
    }

    fn resolver_for(dir: &ScratchDir, rules: Vec<RedirectionRule>) -> HookResolver {
        HookResolver::new(HookConfig { rules }, dir.path("game"), dir.path("temp"))
    }

    fn replace_patch(find: &str, replace: &str) -> MemoryPatch {
        MemoryPatch::ReplaceString {
            replacements: vec![StringReplacement {
                find: find.to_string(),
                replace: replace.to_string(),
                enable_if: None,
            }],
        }
    }

    fn identity_rule(
        glob_pattern: &str,
        mode: RedirectionMode,
        patches: Vec<MemoryPatch>,
    ) -> RedirectionRule {
        RedirectionRule {
            glob_pattern: glob_pattern.into(),
            target: None,
            mode,
            patches,
            enable_if: None,
        }
    }

    fn redirect_rule(
        glob_pattern: &str,
        target: PathBuf,
        mode: RedirectionMode,
        patches: Vec<MemoryPatch>,
    ) -> RedirectionRule {
        RedirectionRule {
            glob_pattern: glob_pattern.into(),
            target: Some(RuleTarget::Path(target)),
            mode,
            patches,
            enable_if: None,
        }
    }

    #[test]
    fn identity_hop_with_patches_and_no_target_still_patches_original() {
        // Exactly the shape of the reported regression: a single rule,
        // target: None, mode: graceful_fallback, one ReplaceString patch.
        let dir = ScratchDir::new("regression_detail_config");
        dir.write_file("game/Data/Detail_Config.txt", b"amount_of_snowflakes\t= 1;");

        let resolver = resolver_for(
            &dir,
            vec![identity_rule(
                "Data/Detail_Config.txt",
                RedirectionMode::GracefulFallback,
                vec![replace_patch(
                    "amount_of_snowflakes\t= 1;",
                    "amount_of_snowflakes = 10.0;",
                )],
            )],
        );

        let action = resolver.resolve_path("Data/Detail_Config.txt");
        let crate::ResolvedAction::Redirect { replacement_path } = action else {
            panic!("expected a staged patch redirect, got {action:?}");
        };
        assert_eq!(
            fs::read(&replacement_path).unwrap(),
            b"amount_of_snowflakes = 10.0;"
        );
    }

    #[test]
    fn two_identity_hops_stack_patches_in_rule_order() {
        let dir = ScratchDir::new("two_identity_hops");
        dir.write_file("game/data/levels/Object_Data.txt", b"base");

        let resolver = resolver_for(
            &dir,
            vec![
                identity_rule(
                    "**/Object_Data.txt",
                    RedirectionMode::GracefulFallback,
                    vec![replace_patch("base", "base+ring")],
                ),
                identity_rule(
                    "**/Object_Data.txt",
                    RedirectionMode::GracefulFallback,
                    vec![replace_patch("ring", "ring+lighting")],
                ),
            ],
        );

        let action = resolver.resolve_path("data/levels/Object_Data.txt");
        let crate::ResolvedAction::Redirect { replacement_path } = action else {
            panic!("expected a staged patch redirect, got {action:?}");
        };
        assert_eq!(fs::read(&replacement_path).unwrap(), b"base+ring+lighting");
    }

    #[test]
    fn redirect_hop_then_identity_hops_stack_on_top() {
        // The full worked example: rule 1 redirects a campaign level to
        // the training level (both under game_dir), rules 2 and 3 then
        // patch Object_Data.txt at the *redirected* location.
        let dir = ScratchDir::new("redirect_then_identity");
        dir.write_file("game/campaign/level1.dat", b"unused");
        dir.write_file("game/campaign/training.dat", b"training level");
        dir.write_file("game/campaign/Object_Data.txt", b"base");

        let resolver = resolver_for(
            &dir,
            vec![
                redirect_rule(
                    "campaign/level1.dat",
                    dir.path("game/campaign/training.dat"),
                    RedirectionMode::GracefulFallback,
                    vec![],
                ),
                identity_rule(
                    "**/Object_Data.txt",
                    RedirectionMode::GracefulFallback,
                    vec![replace_patch("base", "base+ring")],
                ),
                identity_rule(
                    "**/Object_Data.txt",
                    RedirectionMode::GracefulFallback,
                    vec![replace_patch("ring", "ring+lighting")],
                ),
            ],
        );

        // Rule 1 doesn't touch Object_Data.txt directly -- this test is
        // really about rules 2/3 firing on campaign/Object_Data.txt
        // regardless of whether level1.dat itself was redirected; the
        // key assertion is the same as the two-identity-hops test, kept
        // separate to document the worked example explicitly.
        let action = resolver.resolve_path("campaign/Object_Data.txt");
        let crate::ResolvedAction::Redirect { replacement_path } = action else {
            panic!("expected a staged patch redirect, got {action:?}");
        };
        assert_eq!(fs::read(&replacement_path).unwrap(), b"base+ring+lighting");

        // And the level swap itself still works as a plain redirect.
        assert_eq!(
            resolver.resolve_path("campaign/level1.dat"),
            crate::ResolvedAction::Redirect {
                replacement_path: dir.path("game/campaign/training.dat")
            }
        );
    }

    #[test]
    fn redirecting_rules_own_patches_apply_at_the_end_not_immediately() {
        // A -> B via a rule that ALSO patches, then B -> C via a second
        // redirect. A's patch must land on C's content, not B's -- B is
        // never actually served, it's superseded by C.
        let dir = ScratchDir::new("deferred_patch");
        fs::create_dir_all(dir.path("game/mid")).unwrap();
        fs::create_dir_all(dir.path("game/final")).unwrap();
        fs::write(dir.path("game/mid/file.txt"), b"unused").unwrap();
        fs::write(dir.path("game/final/file.txt"), b"final content").unwrap();

        let resolver = resolver_for(
            &dir,
            vec![
                redirect_rule(
                    "start/file.txt",
                    dir.path("game/mid/file.txt"),
                    RedirectionMode::GracefulFallback,
                    vec![replace_patch("final", "FINAL")],
                ),
                redirect_rule(
                    "mid/file.txt",
                    dir.path("game/final/file.txt"),
                    RedirectionMode::GracefulFallback,
                    vec![],
                ),
            ],
        );

        let action = resolver.resolve_path("start/file.txt");
        let crate::ResolvedAction::Redirect { replacement_path } = action else {
            panic!("expected a staged patch redirect, got {action:?}");
        };
        assert_eq!(fs::read(&replacement_path).unwrap(), b"FINAL content");
    }

    #[test]
    fn hard_error_identity_hop_blocks_regardless_of_prior_patches() {
        let dir = ScratchDir::new("hard_error_blocks");
        dir.write_file("game/data/thing.txt", b"base");

        let resolver = resolver_for(
            &dir,
            vec![
                identity_rule(
                    "data/thing.txt",
                    RedirectionMode::GracefulFallback,
                    vec![replace_patch("base", "patched")],
                ),
                identity_rule("data/thing.txt", RedirectionMode::HardError, vec![]),
            ],
        );

        assert_eq!(
            resolver.resolve_path("data/thing.txt"),
            crate::ResolvedAction::HardErrorMissingFile
        );
    }

    #[test]
    fn chain_cycle_is_broken() {
        let dir = ScratchDir::new("cycle");
        fs::write(dir.path("game/a.txt"), b"a").unwrap();
        fs::write(dir.path("game/b.txt"), b"b").unwrap();

        let resolver = resolver_for(
            &dir,
            vec![
                redirect_rule(
                    "a.txt",
                    dir.path("game/b.txt"),
                    RedirectionMode::GracefulFallback,
                    vec![],
                ),
                redirect_rule(
                    "b.txt",
                    dir.path("game/a.txt"),
                    RedirectionMode::GracefulFallback,
                    vec![],
                ),
            ],
        );

        // The cycle returns to the requested original, so the correct
        // outcome is pass-through. It must terminate without looping.
        let action = resolver.resolve_path("a.txt");
        assert_eq!(action, crate::ResolvedAction::PassThrough);
    }

    #[test]
    fn chain_depth_cap_is_enforced() {
        // A -> B -> C -> ... a straight-line, non-cyclic chain longer
        // than MAX_REDIRECT_CHAIN_DEPTH. Must terminate rather than
        // following it forever.
        let dir = ScratchDir::new("depth_cap");
        let chain_len = 20;
        let mut rules = Vec::new();
        for i in 0..chain_len {
            let from = format!("f{i}.txt");
            let to_path = dir.path(&format!("game/f{}.txt", i + 1));
            fs::write(&to_path, format!("content {}", i + 1)).unwrap();
            rules.push(redirect_rule(
                &from,
                to_path,
                RedirectionMode::GracefulFallback,
                vec![],
            ));
        }
        fs::write(dir.path("game/f0.txt"), b"content 0").unwrap();

        let resolver = resolver_for(&dir, rules);

        // Should not hang; should stop well before the end of the chain.
        let action = resolver.resolve_path("f0.txt");
        let crate::ResolvedAction::Redirect { replacement_path } = action else {
            panic!("expected a redirect, got {action:?}");
        };
        assert_ne!(
            replacement_path,
            dir.path(&format!("game/f{chain_len}.txt")),
            "depth cap should have stopped the chain before reaching the end"
        );
    }

    #[test]
    fn chain_does_not_special_case_mod_space_targets() {
        // First hop's target lives under a mod folder (outside
        // game_dir); a second rule matches it there anyway, once
        // re-expressed relative to game_dir is impossible -- so in THIS
        // case the chain correctly stops (nothing can match outside
        // game_dir), but the point is it doesn't error or behave
        // differently just because the target isn't a vanilla game path.
        let dir = ScratchDir::new("mod_space");
        fs::create_dir_all(dir.path("mods/some_mod")).unwrap();
        fs::write(dir.path("mods/some_mod/file.txt"), b"mod content").unwrap();

        let resolver = resolver_for(
            &dir,
            vec![redirect_rule(
                "data/file.txt",
                dir.path("mods/some_mod/file.txt"),
                RedirectionMode::GracefulFallback,
                vec![],
            )],
        );

        assert_eq!(
            resolver.resolve_path("data/file.txt"),
            crate::ResolvedAction::Redirect {
                replacement_path: dir.path("mods/some_mod/file.txt")
            }
        );
    }

    #[test]
    fn chain_does_chain_when_mod_space_target_lands_back_under_game_dir() {
        // The positive case for the same principle: a mod's target
        // happens to be *inside* game_dir (unusual but not special-
        // cased), and a second rule matches it there -- chaining fires
        // exactly as it would for two purely-vanilla paths.
        let dir = ScratchDir::new("mod_space_chains_too");
        fs::create_dir_all(dir.path("game/.supreme/mods/some_mod")).unwrap();
        fs::write(
            dir.path("game/.supreme/mods/some_mod/file.txt"),
            b"mod content",
        )
        .unwrap();
        fs::write(dir.path("game/final.txt"), b"final content").unwrap();

        let resolver = resolver_for(
            &dir,
            vec![
                redirect_rule(
                    "data/file.txt",
                    dir.path("game/.supreme/mods/some_mod/file.txt"),
                    RedirectionMode::GracefulFallback,
                    vec![],
                ),
                redirect_rule(
                    ".supreme/mods/some_mod/file.txt",
                    dir.path("game/final.txt"),
                    RedirectionMode::GracefulFallback,
                    vec![],
                ),
            ],
        );

        assert_eq!(
            resolver.resolve_path("data/file.txt"),
            crate::ResolvedAction::Redirect {
                replacement_path: dir.path("game/final.txt")
            }
        );
    }

    #[test]
    fn non_script_patches_reuse_the_cached_stage_when_base_is_unchanged() {
        // Baseline for the script-patch test below: a plain find/replace
        // patch's output only depends on the base file's bytes, so once
        // staged it should be reused (not rewritten) as long as the base
        // file's mtime hasn't moved forward.
        let dir = ScratchDir::new("non_script_cache_reuse");
        dir.write_file("game/data/levels/Object_Data.txt", b"base");

        let resolver = resolver_for(
            &dir,
            vec![identity_rule(
                "**/Object_Data.txt",
                RedirectionMode::GracefulFallback,
                vec![replace_patch("base", "patched")],
            )],
        );

        let action = resolver.resolve_path("data/levels/Object_Data.txt");
        let crate::ResolvedAction::Redirect { replacement_path } = action else {
            panic!("expected a staged patch redirect, got {action:?}");
        };
        assert_eq!(fs::read(&replacement_path).unwrap(), b"patched");
        let mtime_after_first_call = fs::metadata(&replacement_path).unwrap().modified().unwrap();

        std::thread::sleep(std::time::Duration::from_millis(5));
        let action2 = resolver.resolve_path("data/levels/Object_Data.txt");
        assert_eq!(
            action2,
            crate::ResolvedAction::Redirect {
                replacement_path: replacement_path.clone()
            }
        );
        let mtime_after_second_call = fs::metadata(&replacement_path).unwrap().modified().unwrap();
        assert_eq!(
            mtime_after_first_call, mtime_after_second_call,
            "a non-script patch's stage should not be rewritten when the base file hasn't changed"
        );
    }

    #[test]
    fn script_patches_are_rerun_on_every_read_even_when_the_base_file_is_unchanged() {
        // Regression guard for the actual feature: a level's Object_Data.txt
        // can be patched by a script that derives randomness from
        // `timestamp` (e.g. randomizing camera placements on every load).
        // If script patches reused the mtime-based cache the same way
        // plain find/replace patches do (see the test above), the script
        // would only ever run once per base-file version, and every
        // subsequent load of the same level would see the exact same
        // "random" result.
        let dir = ScratchDir::new("script_rerun_every_read");
        dir.write_file("game/data/levels/Object_Data.txt", b"base");

        let script_patch = MemoryPatch::Script {
            source: crate::ScriptSource::Inline {
                inline: "`${input}${timestamp}`".to_string(),
            },
            parameters: vec![],
            configuration: std::collections::HashMap::new(),
        };

        let resolver = resolver_for(
            &dir,
            vec![identity_rule(
                "**/Object_Data.txt",
                RedirectionMode::GracefulFallback,
                vec![script_patch],
            )],
        );

        let action1 = resolver.resolve_path("data/levels/Object_Data.txt");
        let crate::ResolvedAction::Redirect {
            replacement_path: path1,
        } = action1
        else {
            panic!("expected a staged patch redirect, got {action1:?}");
        };
        let first = fs::read_to_string(&path1).unwrap();
        assert!(first.starts_with("base"));

        std::thread::sleep(std::time::Duration::from_millis(5));

        let action2 = resolver.resolve_path("data/levels/Object_Data.txt");
        let crate::ResolvedAction::Redirect {
            replacement_path: path2,
        } = action2
        else {
            panic!("expected a staged patch redirect, got {action2:?}");
        };
        let second = fs::read_to_string(&path2).unwrap();

        assert_eq!(
            path1, path2,
            "the same rel_key should always stage to the same temp path"
        );
        assert_ne!(
            first, second,
            "a script patch must re-run (fresh timestamp) on every read, not reuse a cached stage"
        );
    }

    #[test]
    fn script_patches_receive_the_rel_key_as_file_path() {
        let dir = ScratchDir::new("script_file_path_var");
        dir.write_file("game/data/levels/Object_Data.txt", b"ignored");

        let script_patch = MemoryPatch::Script {
            source: crate::ScriptSource::Inline {
                inline: "file_path".to_string(),
            },
            parameters: vec![],
            configuration: std::collections::HashMap::new(),
        };

        let resolver = resolver_for(
            &dir,
            vec![identity_rule(
                "**/Object_Data.txt",
                RedirectionMode::GracefulFallback,
                vec![script_patch],
            )],
        );

        let action = resolver.resolve_path("data/levels/Object_Data.txt");
        let crate::ResolvedAction::Redirect { replacement_path } = action else {
            panic!("expected a staged patch redirect, got {action:?}");
        };
        assert_eq!(
            fs::read_to_string(&replacement_path).unwrap(),
            "data/levels/Object_Data.txt"
        );
    }
}

#[cfg(test)]
mod is_write_operation_tests {
    use super::is_write_operation;

    const GENERIC_READ: u32 = 0x8000_0000;
    const GENERIC_WRITE: u32 = 0x4000_0000;
    const FILE_WRITE_DATA: u32 = 0x0000_0002;
    const FILE_APPEND_DATA: u32 = 0x0000_0004;
    const FILE_READ_DATA: u32 = 0x0000_0001;

    const SUPERSEDE: u32 = 0;
    const OPEN: u32 = 1;
    const CREATE: u32 = 2;
    const OPEN_IF: u32 = 3;
    const OVERWRITE: u32 = 4;
    const OVERWRITE_IF: u32 = 5;

    #[test]
    fn destructive_dispositions_are_always_writes_even_with_read_only_access() {
        for disposition in [SUPERSEDE, CREATE, OVERWRITE, OVERWRITE_IF] {
            assert!(
                is_write_operation(GENERIC_READ, disposition),
                "disposition {disposition} should be a write regardless of access mask"
            );
        }
    }

    #[test]
    fn open_with_read_only_access_is_not_a_write() {
        assert!(!is_write_operation(GENERIC_READ, OPEN));
        assert!(!is_write_operation(FILE_READ_DATA, OPEN));
    }

    #[test]
    fn open_if_with_read_only_access_is_not_a_write() {
        assert!(!is_write_operation(GENERIC_READ, OPEN_IF));
    }

    #[test]
    fn open_with_generic_write_access_is_a_write() {
        assert!(is_write_operation(GENERIC_WRITE, OPEN));
    }

    #[test]
    fn open_with_file_write_data_access_is_a_write() {
        assert!(is_write_operation(FILE_WRITE_DATA, OPEN));
    }

    #[test]
    fn open_if_with_file_append_data_access_is_a_write() {
        assert!(is_write_operation(FILE_APPEND_DATA, OPEN_IF));
    }

    #[test]
    fn open_with_combined_read_and_write_access_is_a_write() {
        assert!(is_write_operation(GENERIC_READ | GENERIC_WRITE, OPEN));
    }

    #[test]
    fn no_access_bits_and_non_destructive_disposition_is_not_a_write() {
        assert!(!is_write_operation(0, OPEN));
    }
}

#[cfg(test)]
mod seed_target_file_tests {
    use super::seed_target_file;
    use std::fs;

    struct ScratchDir(std::path::PathBuf);

    impl ScratchDir {
        fn new(name: &str) -> Self {
            let dir = std::env::temp_dir()
                .join(format!("hook_resolver_test_{name}_{}", std::process::id()));
            let _ = fs::remove_dir_all(&dir);
            fs::create_dir_all(&dir).unwrap();
            Self(dir)
        }

        fn path(&self, name: &str) -> std::path::PathBuf {
            self.0.join(name)
        }
    }

    impl Drop for ScratchDir {
        fn drop(&mut self) {
            let _ = fs::remove_dir_all(&self.0);
        }
    }

    #[test]
    fn seeds_target_with_original_contents_when_target_is_absent() {
        let dir = ScratchDir::new("seeds_when_absent");
        let original = dir.path("original.dat");
        let target = dir.path("target.dat");
        fs::write(&original, b"original bytes").unwrap();

        let seeded = seed_target_file(&original, &target).unwrap();

        assert!(seeded, "first caller should perform the seed");
        assert_eq!(fs::read(&target).unwrap(), b"original bytes");
    }

    #[test]
    fn does_not_touch_target_when_it_already_exists() {
        let dir = ScratchDir::new("skips_when_present");
        let original = dir.path("original.dat");
        let target = dir.path("target.dat");
        fs::write(&original, b"original bytes").unwrap();
        fs::write(&target, b"already-written save data").unwrap();

        let seeded = seed_target_file(&original, &target).unwrap();

        assert!(!seeded);
        assert_eq!(fs::read(&target).unwrap(), b"already-written save data");
    }

    #[test]
    fn second_call_after_a_successful_seed_is_a_no_op() {
        let dir = ScratchDir::new("second_call_is_noop");
        let original = dir.path("original.dat");
        let target = dir.path("target.dat");
        fs::write(&original, b"original bytes").unwrap();

        assert!(seed_target_file(&original, &target).unwrap());
        fs::write(&target, b"game already wrote new save data here").unwrap();

        let seeded_again = seed_target_file(&original, &target).unwrap();

        assert!(!seeded_again);
        assert_eq!(
            fs::read(&target).unwrap(),
            b"game already wrote new save data here"
        );
    }

    #[test]
    fn propagates_an_error_when_the_original_cannot_be_read() {
        let dir = ScratchDir::new("missing_original_errors");
        let original = dir.path("does_not_exist.dat");
        let target = dir.path("target.dat");

        let result = seed_target_file(&original, &target);

        assert!(result.is_err());
        assert!(!target.exists());
    }

    #[test]
    fn concurrent_seeds_publish_only_complete_original_bytes() {
        let dir = ScratchDir::new("concurrent_complete_seeds");
        let original = dir.path("original.dat");
        let target = dir.path("target.dat");
        let expected = vec![0x5au8; 2 * 1024 * 1024];
        fs::write(&original, &expected).unwrap();
        let barrier = std::sync::Arc::new(std::sync::Barrier::new(5));
        let results = std::thread::scope(|scope| {
            let threads: Vec<_> = (0..4)
                .map(|_| {
                    let barrier = barrier.clone();
                    let original = original.clone();
                    let target = target.clone();
                    scope.spawn(move || {
                        barrier.wait();
                        let seeded = seed_target_file(&original, &target).unwrap();
                        assert_eq!(fs::metadata(&target).unwrap().len(), 2 * 1024 * 1024);
                        seeded
                    })
                })
                .collect();
            barrier.wait();
            threads
                .into_iter()
                .map(|thread| thread.join().unwrap())
                .collect::<Vec<_>>()
        });
        assert_eq!(results.into_iter().filter(|seeded| *seeded).count(), 1);
        assert_eq!(fs::read(target).unwrap(), expected);
    }
}

#[cfg(test)]
mod write_seed_failure_tests {
    use super::*;
    use crate::{HookConfig, RedirectionMode, RedirectionRule, ResolvedAction};

    #[test]
    fn partial_write_starts_with_original_and_leaves_original_untouched() {
        let dir = tempfile::tempdir().unwrap();
        let game = dir.path().join("game");
        std::fs::create_dir_all(game.join("data")).unwrap();
        std::fs::write(game.join("data/save.dat"), b"original bytes").unwrap();
        let target = game.join("mod/save.dat");
        let resolver = HookResolver::new(
            HookConfig {
                rules: vec![RedirectionRule {
                    glob_pattern: "data/save.dat".into(),
                    target: Some(RuleTarget::Path(target.clone())),
                    mode: RedirectionMode::GracefulFallback,
                    patches: vec![],
                    enable_if: None,
                }],
            },
            game.clone(),
            dir.path().join("temp"),
        );

        assert_eq!(
            resolver.resolve_path_for_write("data/save.dat"),
            ResolvedAction::Redirect {
                replacement_path: target.clone()
            }
        );
        let mut bytes = std::fs::read(&target).unwrap();
        bytes[0..7].copy_from_slice(b"updated");
        std::fs::write(&target, bytes).unwrap();
        assert_eq!(std::fs::read(&target).unwrap(), b"updatedl bytes");
        assert_eq!(
            std::fs::read(game.join("data/save.dat")).unwrap(),
            b"original bytes"
        );
    }

    #[test]
    fn target_preparation_failure_blocks_write_even_in_graceful_mode() {
        let dir = tempfile::tempdir().unwrap();
        let game = dir.path().join("game");
        std::fs::create_dir_all(game.join("data")).unwrap();
        std::fs::write(game.join("data/save.dat"), b"original bytes").unwrap();
        let blocker = game.join("blocker");
        std::fs::write(&blocker, b"a file, not a directory").unwrap();
        let resolver = HookResolver::new(
            HookConfig {
                rules: vec![RedirectionRule {
                    glob_pattern: "data/save.dat".into(),
                    target: Some(RuleTarget::Path(blocker.join("save.dat"))),
                    mode: RedirectionMode::GracefulFallback,
                    patches: vec![],
                    enable_if: None,
                }],
            },
            game.clone(),
            dir.path().join("temp"),
        );
        assert_eq!(
            resolver.resolve_path_for_write("data/save.dat"),
            ResolvedAction::HardErrorMissingFile
        );
        assert!(resolver.has_write_redirect("data/save.dat"));
        assert!(resolver.resolve_write_target("data/save.dat").is_none());
        assert_eq!(
            std::fs::read(game.join("data/save.dat")).unwrap(),
            b"original bytes"
        );
    }

    #[test]
    fn unreadable_original_blocks_redirect_instead_of_publishing_partial_target() {
        let dir = tempfile::tempdir().unwrap();
        let game = dir.path().join("game");
        std::fs::create_dir_all(game.join("data/save.dat")).unwrap();
        let target = game.join("mod/save.dat");
        let resolver = HookResolver::new(
            HookConfig {
                rules: vec![RedirectionRule {
                    glob_pattern: "data/save.dat".into(),
                    target: Some(RuleTarget::Path(target.clone())),
                    mode: RedirectionMode::GracefulFallback,
                    patches: vec![],
                    enable_if: None,
                }],
            },
            game,
            dir.path().join("temp"),
        );
        assert_eq!(
            resolver.resolve_path_for_write("data/save.dat"),
            ResolvedAction::HardErrorMissingFile
        );
        assert!(!target.exists());
    }

    #[test]
    fn self_redirect_cannot_write_into_original_file() {
        let dir = tempfile::tempdir().unwrap();
        let game = dir.path().join("game");
        std::fs::create_dir_all(game.join("data")).unwrap();
        let original = game.join("data/save.dat");
        std::fs::write(&original, b"original bytes").unwrap();
        let resolver = HookResolver::new(
            HookConfig {
                rules: vec![RedirectionRule {
                    glob_pattern: "data/save.dat".into(),
                    target: Some(RuleTarget::Path(original.clone())),
                    mode: RedirectionMode::GracefulFallback,
                    patches: vec![],
                    enable_if: None,
                }],
            },
            game,
            dir.path().join("temp"),
        );
        assert_eq!(
            resolver.resolve_path_for_write("data/save.dat"),
            ResolvedAction::HardErrorMissingFile
        );
        assert!(resolver.has_write_redirect("data/save.dat"));
        assert!(resolver.resolve_write_target("data/save.dat").is_none());
        assert_eq!(std::fs::read(original).unwrap(), b"original bytes");
    }
}

#[cfg(test)]
mod compute_target_path_tests {
    use super::compute_target_path;
    use crate::{RedirectionMode, RedirectionRule, RuleTarget};
    use std::path::PathBuf;

    fn rule(glob_pattern: &str, target: &str) -> RedirectionRule {
        RedirectionRule {
            glob_pattern: glob_pattern.into(),
            target: Some(RuleTarget::Path(PathBuf::from(target))),
            mode: RedirectionMode::GracefulFallback,
            patches: vec![],
            enable_if: None,
        }
    }

    #[test]
    fn double_star_preserves_subdirectory_structure() {
        let rule = rule("data/levels/**", "mods/levels");
        assert_eq!(
            compute_target_path(&rule, "data/levels/alpine/tracks/easy/replays/r2.dat"),
            Some(PathBuf::from(
                "mods/levels/alpine/tracks/easy/replays/r2.dat"
            ))
        );
    }

    /// Regression test: a wildcard segment that isn't the literal `**`
    /// substring (a single `*` matching a whole directory component, here
    /// the per-level name) must preserve the sub-directory structure, the
    /// same answer `HookConfig::resolve`'s `matched_suffix` gives;
    /// `compute_target_path` delegates to it directly, so there is
    /// exactly one answer to "where does this rel_key's file live".
    #[test]
    fn single_star_mid_path_preserves_subdirectory_structure() {
        let rule = rule("data/levels/*/ghost/*.dat", "mods/ghosts");
        assert_eq!(
            compute_target_path(&rule, "data/levels/alpine/ghost/run_42.dat"),
            Some(PathBuf::from("mods/ghosts/alpine/ghost/run_42.dat"))
        );
    }

    #[test]
    fn single_star_last_segment_reduces_to_basename() {
        // No subdirectory below the wildcard in this pattern shape, so
        // there's nothing to preserve, this should still just be the
        // basename, same as before.
        let rule = rule("data/levels/*.dat", "mods/levels");
        assert_eq!(
            compute_target_path(&rule, "data/levels/level1.dat"),
            Some(PathBuf::from("mods/levels/level1.dat"))
        );
    }

    #[test]
    fn literal_glob_uses_target_directly() {
        let rule = rule("Saved_Data/high_times.txt", "mods/high_times_custom.txt");
        assert_eq!(
            compute_target_path(&rule, "saved_data/high_times.txt"),
            Some(PathBuf::from("mods/high_times_custom.txt"))
        );
    }
}

#[cfg(test)]
mod write_then_delete_tests {
    //! End-to-end regression coverage for the exact bug reported against
    //! this resolver: a file created via `resolve_path_for_write` under a
    //! wildcard rule must be found (and only that file) by
    //! `resolve_path_for_delete` and `resolve_path` for the same rel_key,
    //! otherwise a "write a ghost recording, then delete it" cycle can
    //! delete the wrong file (or nothing at all), leaving the real one
    //! stranded. See `compute_target_path_tests` for the narrower unit-level
    //! version of the same regression.

    use super::HookResolver;
    use crate::{HookConfig, RedirectionMode, RedirectionRule, RuleTarget};
    use std::fs;
    use std::path::PathBuf;

    struct ScratchDir(PathBuf);

    impl ScratchDir {
        fn new(name: &str) -> Self {
            let dir = std::env::temp_dir().join(format!(
                "hook_resolver_write_delete_test_{name}_{}",
                std::process::id()
            ));
            let _ = fs::remove_dir_all(&dir);
            fs::create_dir_all(&dir).unwrap();
            Self(dir)
        }

        fn path(&self, name: &str) -> PathBuf {
            self.0.join(name)
        }
    }

    impl Drop for ScratchDir {
        fn drop(&mut self) {
            let _ = fs::remove_dir_all(&self.0);
        }
    }

    fn resolver_for(dir: &ScratchDir, glob_pattern: &str, mode: RedirectionMode) -> HookResolver {
        let config = HookConfig {
            rules: vec![RedirectionRule {
                glob_pattern: glob_pattern.into(),
                target: Some(RuleTarget::Path(dir.path("mods_ghosts"))),
                mode,
                patches: vec![],
                enable_if: None,
            }],
        };
        HookResolver::new(config, dir.path("game"), dir.path("temp"))
    }

    #[test]
    fn delete_finds_the_same_file_a_wildcard_write_created() {
        let dir = ScratchDir::new("delete_finds_write");
        let resolver = resolver_for(
            &dir,
            "data/levels/*/ghost/*.dat",
            RedirectionMode::GracefulFallback,
        );
        let rel_key = "data/levels/alpine/ghost/run_42.dat";

        let write_action = resolver.resolve_path_for_write(rel_key);
        let crate::ResolvedAction::Redirect {
            replacement_path: written_path,
        } = write_action
        else {
            panic!("expected a write redirect, got {write_action:?}");
        };
        fs::write(&written_path, b"ghost data").unwrap();

        let delete_action = resolver.resolve_path_for_delete(rel_key);
        assert_eq!(
            delete_action,
            crate::ResolvedAction::Redirect {
                replacement_path: written_path.clone()
            },
            "delete must resolve to the exact same physical file the write created"
        );

        // And nothing was ever written anywhere else under the target root.
        let mut all_files = Vec::new();
        for entry in walk(&dir.path("mods_ghosts")) {
            all_files.push(entry);
        }
        assert_eq!(all_files, vec![written_path]);
    }

    #[test]
    fn read_also_finds_the_same_file_a_wildcard_write_created() {
        // Covers the case where the game reopens the file with read-only /
        // delete-only access (no write bits) after closing the handle it
        // wrote with, `is_write_operation` routes that through
        // `resolve_path`, not `resolve_path_for_write`, so this must agree
        // too.
        let dir = ScratchDir::new("read_finds_write");
        let resolver = resolver_for(
            &dir,
            "data/levels/*/ghost/*.dat",
            RedirectionMode::GracefulFallback,
        );
        let rel_key = "data/levels/alpine/ghost/run_42.dat";

        let crate::ResolvedAction::Redirect {
            replacement_path: written_path,
        } = resolver.resolve_path_for_write(rel_key)
        else {
            panic!("expected a write redirect");
        };
        fs::write(&written_path, b"ghost data").unwrap();

        assert_eq!(
            resolver.resolve_path(rel_key),
            crate::ResolvedAction::Redirect {
                replacement_path: written_path
            }
        );
    }

    #[test]
    fn delete_hard_errors_when_nothing_was_ever_written() {
        let dir = ScratchDir::new("delete_hard_errors");
        let resolver = resolver_for(
            &dir,
            "data/levels/*/ghost/*.dat",
            RedirectionMode::HardError,
        );

        assert_eq!(
            resolver.resolve_path_for_delete("data/levels/practice/ghost/never_written.dat"),
            crate::ResolvedAction::HardErrorMissingFile
        );
    }

    #[test]
    fn delete_passes_through_when_nothing_was_ever_written_in_fallback_mode() {
        let dir = ScratchDir::new("delete_passes_through");
        let resolver = resolver_for(
            &dir,
            "data/levels/*/ghost/*.dat",
            RedirectionMode::GracefulFallback,
        );

        assert_eq!(
            resolver.resolve_path_for_delete("data/levels/practice/ghost/never_written.dat"),
            crate::ResolvedAction::PassThrough
        );
    }

    #[test]
    fn write_target_skips_targetless_rule_to_reach_a_real_one() {
        // A target: None rule matches first in the list; a later rule
        // for the same glob has a real target. The write must not stop
        // at the first (targetless) match.
        let dir = ScratchDir::new("write_skips_targetless");
        let config = HookConfig {
            rules: vec![
                RedirectionRule {
                    glob_pattern: "saves/*.sav".into(),
                    target: None,
                    mode: RedirectionMode::GracefulFallback,
                    patches: vec![],
                    enable_if: None,
                },
                RedirectionRule {
                    glob_pattern: "saves/*.sav".into(),
                    target: Some(RuleTarget::Path(dir.path("mod_saves"))),
                    mode: RedirectionMode::GracefulFallback,
                    patches: vec![],
                    enable_if: None,
                },
            ],
        };
        let resolver = HookResolver::new(config, dir.path("game"), dir.path("temp"));

        let action = resolver.resolve_path_for_write("saves/slot1.sav");
        assert_eq!(
            action,
            crate::ResolvedAction::Redirect {
                replacement_path: dir.path("mod_saves/slot1.sav")
            }
        );
    }

    #[test]
    fn write_target_follows_redirect_to_its_end() {
        // rule 1 redirects data/x.txt -> mid/x.txt (still under
        // game_dir); rule 2 redirects mid/x.txt -> mods/final. Writing
        // to data/x.txt should land at the FINAL stage's target, not
        // the intermediate one.
        let dir = ScratchDir::new("write_follows_chain");
        fs::create_dir_all(dir.path("game")).unwrap();
        let config = HookConfig {
            rules: vec![
                RedirectionRule {
                    glob_pattern: "data/x.txt".into(),
                    target: Some(RuleTarget::Path(dir.path("game/mid/x.txt"))),
                    mode: RedirectionMode::GracefulFallback,
                    patches: vec![],
                    enable_if: None,
                },
                RedirectionRule {
                    glob_pattern: "mid/x.txt".into(),
                    target: Some(RuleTarget::Path(dir.path("mods/final_x.txt"))),
                    mode: RedirectionMode::GracefulFallback,
                    patches: vec![],
                    enable_if: None,
                },
            ],
        };
        let resolver = HookResolver::new(config, dir.path("game"), dir.path("temp"));

        let action = resolver.resolve_path_for_write("data/x.txt");
        assert_eq!(
            action,
            crate::ResolvedAction::Redirect {
                replacement_path: dir.path("mods/final_x.txt")
            }
        );
    }

    #[test]
    fn delete_uses_last_reached_rule_mode_for_missing_file_fallback() {
        // rule 1 (graceful_fallback) redirects to a stage that rule 2
        // (hard_error) also matches, but rule 2 has no target of its
        // own -- with nothing ever written, the LAST rule reached
        // (rule 2, hard_error) should govern the fallback, not rule 1.
        let dir = ScratchDir::new("delete_last_rule_mode");
        fs::create_dir_all(dir.path("game")).unwrap();
        let config = HookConfig {
            rules: vec![
                RedirectionRule {
                    glob_pattern: "data/y.txt".into(),
                    target: Some(RuleTarget::Path(dir.path("game/mid/y.txt"))),
                    mode: RedirectionMode::GracefulFallback,
                    patches: vec![],
                    enable_if: None,
                },
                RedirectionRule {
                    glob_pattern: "mid/y.txt".into(),
                    target: None,
                    mode: RedirectionMode::HardError,
                    patches: vec![],
                    enable_if: None,
                },
            ],
        };
        let resolver = HookResolver::new(config, dir.path("game"), dir.path("temp"));

        assert_eq!(
            resolver.resolve_path_for_delete("data/y.txt"),
            crate::ResolvedAction::HardErrorMissingFile,
            "the last rule reached (hard_error) should govern, not the first (graceful_fallback)"
        );
    }

    #[test]
    fn write_redirects_through_a_wildcard_rule_even_when_the_target_matches_nothing_further() {
        // Regression guard for the exact bug reported: a single
        // catch-all wildcard rule (`Data/.../Easy/**`) redirects into a
        // directory under game_dir, and *nothing* else matches that
        // redirected path -- the chain has exactly one hop, then ends.
        // A write (and, by the same code path, a rename) must still
        // land in the rule's target directory, not silently fall
        // through to writing/renaming over the original game file.
        let dir = ScratchDir::new("write_wildcard_terminal_redirect");
        fs::create_dir_all(dir.path("game/data/levels/easy")).unwrap();
        fs::create_dir_all(dir.path("game/data/levels/practice_easy")).unwrap();

        let config = HookConfig {
            rules: vec![RedirectionRule {
                glob_pattern: "data/levels/easy/**".into(),
                target: Some(RuleTarget::Path(
                    dir.path("game/data/levels/practice_easy/"),
                )),
                mode: RedirectionMode::HardError,
                patches: vec![],
                enable_if: None,
            }],
        };
        let resolver = HookResolver::new(config, dir.path("game"), dir.path("temp"));

        let action = resolver.resolve_path_for_write("data/levels/easy/replays/replay_0.dat");
        assert_eq!(
            action,
            crate::ResolvedAction::Redirect {
                replacement_path: dir.path("game/data/levels/practice_easy/replays/replay_0.dat")
            },
            "a write through a single-hop wildcard redirect must land in the \
             rule's target directory, not fall through to the original file"
        );
    }

    #[test]
    fn delete_redirects_through_a_wildcard_rule_even_when_the_target_matches_nothing_further() {
        // Same regression, delete side: once a replay has actually been
        // written into the target directory, deleting it (as part of
        // the game's shift-replays-down bookkeeping) must find it there
        // too, not report PassThrough/HardError against a file that was
        // never touched.
        let dir = ScratchDir::new("delete_wildcard_terminal_redirect");
        fs::create_dir_all(dir.path("game/data/levels/easy")).unwrap();
        fs::create_dir_all(dir.path("game/data/levels/practice_easy/replays")).unwrap();
        fs::write(
            dir.path("game/data/levels/practice_easy/replays/replay_4.dat"),
            b"a replay",
        )
        .unwrap();

        let config = HookConfig {
            rules: vec![RedirectionRule {
                glob_pattern: "data/levels/easy/**".into(),
                target: Some(RuleTarget::Path(
                    dir.path("game/data/levels/practice_easy/"),
                )),
                mode: RedirectionMode::HardError,
                patches: vec![],
                enable_if: None,
            }],
        };
        let resolver = HookResolver::new(config, dir.path("game"), dir.path("temp"));

        assert_eq!(
            resolver.resolve_path_for_delete("data/levels/easy/replays/replay_4.dat"),
            crate::ResolvedAction::Redirect {
                replacement_path: dir.path("game/data/levels/practice_easy/replays/replay_4.dat")
            }
        );

        // And for a replay slot that was never written, hard_error still
        // blocks the delete, exactly as it blocks the read -- this part
        // of the original bug report was already correct and must stay
        // that way.
        assert_eq!(
            resolver.resolve_path_for_delete("data/levels/easy/replays/replay_0.dat"),
            crate::ResolvedAction::HardErrorMissingFile
        );
    }

    #[test]
    fn literal_redirect_under_game_dir_keeps_the_declared_target_casing() {
        // field regression: a managed target's `local` under
        // game_dir (`.supreme/mods/...`, every mod target) used to be
        // resolved through `original_path(rel_key_of(target))`, whose
        // lowercase fold silently rewrote a MixedCase declared file name.
        // The write then landed on a differently-cased twin of the
        // registered local path, and the engine's byte-exact close-hook
        // comparison never captured the game's writes (the field 404
        // cascade). The terminal target must be the DECLARED path,
        // byte-exact.
        let dir = ScratchDir::new("literal_target_case_preserved");
        fs::create_dir_all(dir.path("game/saved_data")).unwrap();

        let config = HookConfig {
            rules: vec![RedirectionRule {
                glob_pattern: "Saved_Data/village_Tracks_medium_high_times.txt".into(),
                target: Some(RuleTarget::Path(dir.path(
                    "game/.supreme/mods/m/High_Times/Village_Tracks_Medium_high_times.txt",
                ))),
                mode: RedirectionMode::GracefulFallback,
                patches: vec![],
                enable_if: None,
            }],
        };
        let resolver = HookResolver::new(config, dir.path("game"), dir.path("temp"));

        let declared =
            dir.path("game/.supreme/mods/m/High_Times/Village_Tracks_Medium_high_times.txt");
        assert_eq!(
            resolver.resolve_path_for_write("saved_data/village_tracks_medium_high_times.txt"),
            crate::ResolvedAction::Redirect {
                replacement_path: declared.clone()
            },
            "the write target must carry the declared path byte-exactly, \
             not a lowercased re-expression of it"
        );
        // The delete side resolves through the same chain, same exactness.
        // (A delete only redirects to a target that exists on disk, in the
        // field the engine has materialized the managed local long before;
        // graceful_fallback would otherwise fall through by design.)
        std::fs::write(&declared, b"managed").unwrap();
        assert_eq!(
            resolver.resolve_path_for_delete("saved_data/village_tracks_medium_high_times.txt"),
            crate::ResolvedAction::Redirect {
                replacement_path: declared
            }
        );
    }

    fn walk(dir: &std::path::Path) -> Vec<PathBuf> {
        let mut out = Vec::new();
        let Ok(entries) = fs::read_dir(dir) else {
            return out;
        };
        for entry in entries.flatten() {
            let path = entry.path();
            if path.is_dir() {
                out.extend(walk(&path));
            } else {
                out.push(path);
            }
        }
        out
    }
}

#[cfg(test)]
mod listing_visibility_tests {
    //! `should_hide_original_entry` must agree with `resolve_path` about
    //! which files a rule actually governs, not just which ones currently
    //! have a replacement staged. Scenario used throughout: a directory
    //! `a/` redirected to `b/`, where `a/` has real files `2.txt` and
    //! `3.txt`, and only `b/1.txt` has been shipped so far (`1.txt` has no
    //! original counterpart in `a/` at all, it's a pure mod addition).
    //!
    //! `graceful_fallback`: only `1.txt` is hidden from `a/`'s listing (it
    //! has a real replacement); `2.txt` and `3.txt` stay visible, same as
    //! reading them directly would fall back to the originals.
    //!
    //! `hard_error`: every rel_key the rule matches is hidden the moment it
    //! matches, whether or not a replacement exists yet for it, same as
    //! reading `a/2.txt` directly reports "does not exist" under
    //! `hard_error`, even though the real file is still on disk.

    use super::HookResolver;
    use crate::{HookConfig, RedirectionMode, RedirectionRule, RuleTarget};
    use std::fs;
    use std::path::PathBuf;

    struct ScratchDir(PathBuf);

    impl ScratchDir {
        fn new(name: &str) -> Self {
            let dir = std::env::temp_dir().join(format!(
                "hook_resolver_listing_visibility_test_{name}_{}",
                std::process::id()
            ));
            let _ = fs::remove_dir_all(&dir);
            fs::create_dir_all(dir.join("a")).unwrap();
            fs::create_dir_all(dir.join("b")).unwrap();
            Self(dir)
        }

        fn path(&self, name: &str) -> PathBuf {
            self.0.join(name)
        }
    }

    impl Drop for ScratchDir {
        fn drop(&mut self) {
            let _ = fs::remove_dir_all(&self.0);
        }
    }

    fn resolver_for(dir: &ScratchDir, mode: RedirectionMode) -> HookResolver {
        let config = HookConfig {
            rules: vec![RedirectionRule {
                glob_pattern: "a/**".into(),
                target: Some(RuleTarget::Path(dir.path("b"))),
                mode,
                patches: vec![],
                enable_if: None,
            }],
        };
        HookResolver::new(config, dir.path("game"), dir.path("temp"))
    }

    #[test]
    fn graceful_fallback_hides_only_the_entry_with_a_real_replacement() {
        let dir = ScratchDir::new("graceful");
        fs::write(dir.path("a/2.txt"), b"original 2").unwrap();
        fs::write(dir.path("a/3.txt"), b"original 3").unwrap();
        fs::write(dir.path("b/1.txt"), b"replacement 1").unwrap();
        let resolver = resolver_for(&dir, RedirectionMode::GracefulFallback);

        assert!(
            resolver.should_hide_original_entry("a/1.txt"),
            "1.txt has a real replacement in b/, so it should be hidden \
             (the injected mod entry takes its place)"
        );
        assert!(
            !resolver.should_hide_original_entry("a/2.txt"),
            "2.txt has no replacement in b/ yet -- graceful_fallback must \
             keep showing the original"
        );
        assert!(
            !resolver.should_hide_original_entry("a/3.txt"),
            "same as 2.txt: no replacement yet, must stay visible"
        );
    }

    /// The regression this module exists for: under `hard_error`, a
    /// redirected directory's own leftover files must never leak into a
    /// listing just because nothing has replaced them yet, `2.txt` and
    /// `3.txt` are still physically present in `a/`, but the rule matches
    /// them, so they must be hidden exactly as a direct read of either would
    /// report `HardErrorMissingFile` instead of falling back to serving them.
    #[test]
    fn hard_error_hides_every_matched_entry_even_without_a_replacement() {
        let dir = ScratchDir::new("hard_error");
        fs::write(dir.path("a/2.txt"), b"original 2").unwrap();
        fs::write(dir.path("a/3.txt"), b"original 3").unwrap();
        fs::write(dir.path("b/1.txt"), b"replacement 1").unwrap();
        let resolver = resolver_for(&dir, RedirectionMode::HardError);

        assert!(
            resolver.should_hide_original_entry("a/1.txt"),
            "1.txt has a real replacement -- hidden either way"
        );
        assert!(
            resolver.should_hide_original_entry("a/2.txt"),
            "hard_error must hide 2.txt even though b/2.txt doesn't exist \
             yet -- the rule already claimed this rel_key"
        );
        assert!(
            resolver.should_hide_original_entry("a/3.txt"),
            "same as 2.txt"
        );
    }

    #[test]
    fn unmatched_path_is_never_hidden() {
        let dir = ScratchDir::new("unmatched");
        let resolver = resolver_for(&dir, RedirectionMode::HardError);

        assert!(
            !resolver.should_hide_original_entry("completely/unrelated/file.txt"),
            "no rule matches this rel_key at all, so there's nothing to hide"
        );
    }

    #[test]
    fn agrees_with_resolve_path_across_every_case_in_this_scenario() {
        // Cross-check: for every rel_key/mode pair above, hiding must be
        // exactly the cases where resolve_path would NOT serve the
        // original -- i.e. exactly Redirect and HardErrorMissingFile, never
        // FallbackToOriginal or PassThrough. This pins the two decisions
        // together so they can't drift apart again in the future.
        let dir = ScratchDir::new("agrees_with_resolve_path");
        fs::write(dir.path("a/2.txt"), b"original 2").unwrap();
        fs::write(dir.path("a/3.txt"), b"original 3").unwrap();
        fs::write(dir.path("b/1.txt"), b"replacement 1").unwrap();

        for mode in [
            RedirectionMode::GracefulFallback,
            RedirectionMode::HardError,
        ] {
            let resolver = resolver_for(&dir, mode);
            for rel_key in ["a/1.txt", "a/2.txt", "a/3.txt", "unrelated.txt"] {
                let hidden = resolver.should_hide_original_entry(rel_key);
                let would_serve_original = matches!(
                    resolver.resolve_path(rel_key),
                    crate::ResolvedAction::FallbackToOriginal | crate::ResolvedAction::PassThrough
                );
                assert_eq!(
                    hidden, !would_serve_original,
                    "mode={mode:?} rel_key={rel_key}: listing visibility must be the \
                     exact inverse of \"resolve_path would serve the original\""
                );
            }
        }
    }

    #[test]
    fn agrees_with_resolve_path_for_a_chained_and_patched_scenario() {
        // Same invariant as above, but exercising the actual chain
        // (redirect hop into game_dir, followed by an identity/patch
        // hop) rather than the single-rule scenario every other test in
        // this module uses.
        use crate::{MemoryPatch, StringReplacement};

        let dir = ScratchDir::new("agrees_with_resolve_path_chained");
        fs::write(dir.path("a/redirected.txt"), b"unused").unwrap();
        fs::write(dir.path("b/redirected.txt"), b"base content").unwrap();

        let config = HookConfig {
            rules: vec![
                RedirectionRule {
                    glob_pattern: "a/redirected.txt".into(),
                    target: Some(RuleTarget::Path(dir.path("b/redirected.txt"))),
                    mode: RedirectionMode::GracefulFallback,
                    patches: vec![],
                    enable_if: None,
                },
                RedirectionRule {
                    glob_pattern: "b/redirected.txt".into(),
                    target: None,
                    mode: RedirectionMode::GracefulFallback,
                    patches: vec![MemoryPatch::ReplaceString {
                        replacements: vec![StringReplacement {
                            find: "base".into(),
                            replace: "patched".into(),
                            enable_if: None,
                        }],
                    }],
                    enable_if: None,
                },
            ],
        };
        let resolver = HookResolver::new(config, dir.path("game_root_unused"), dir.path("temp"));
        // Note: this scenario's rel_keys are matched directly against
        // "a/..."/"b/..." glob patterns above rather than routed through
        // game_dir -- game_dir only matters for re-expressing a target
        // as a rel_key mid-chain (see chain_resolution_tests for that),
        // which this scenario's second hop doesn't need since it's an
        // identity hop, not a further redirect.

        let hidden = resolver.should_hide_original_entry("a/redirected.txt");
        let would_serve_original = matches!(
            resolver.resolve_path("a/redirected.txt"),
            crate::ResolvedAction::FallbackToOriginal | crate::ResolvedAction::PassThrough
        );
        assert_eq!(
            hidden, !would_serve_original,
            "a chained, patched rel_key must still agree between listing and read"
        );
        assert!(
            hidden,
            "this rel_key has a real, patched replacement -- must be hidden"
        );
    }
}

#[cfg(test)]
mod managed_file_specs_tests {
    //! the declarative managed-file scan. The tournament-specific
    //! high-times discovery is gone; `managed_file_specs` is the generic
    //! successor, every `RuleTarget::Managed` rule, in config order.

    use super::*;

    fn plain_rule(glob: &str, target: Option<&str>) -> RedirectionRule {
        RedirectionRule {
            glob_pattern: glob.to_owned(),
            target: target.map(|t| RuleTarget::Path(PathBuf::from(t))),
            mode: RedirectionMode::HardError,
            patches: vec![],
            enable_if: None,
        }
    }

    fn managed_rule(glob: &str, local: &str, remote: &str, poll: Option<u64>) -> RedirectionRule {
        managed_rule_with_push(glob, local, remote, poll, None)
    }

    fn managed_rule_with_push(
        glob: &str,
        local: &str,
        remote: &str,
        poll: Option<u64>,
        push: Option<&str>,
    ) -> RedirectionRule {
        RedirectionRule {
            glob_pattern: glob.to_owned(),
            target: Some(RuleTarget::Managed {
                local: PathBuf::from(local),
                remote: remote.to_owned(),
                poll_interval_secs: poll,
                push_url: push.map(str::to_owned),
            }),
            mode: RedirectionMode::GracefulFallback,
            patches: vec![],
            enable_if: None,
        }
    }

    fn config(rules: Vec<RedirectionRule>) -> HookConfig {
        HookConfig { rules }
    }

    const GAME: &str = "/games/supreme";

    #[test]
    fn collects_every_managed_rule_in_config_order() {
        let cfg = config(vec![
            plain_rule(
                "Data/Levels/village/Tracks/medium/replays/Replay_*.dat",
                Some(".supreme/mods/online-tournament/replays"),
            ),
            managed_rule_with_push(
                "Saved_Data/village_Tracks_medium_high_times.txt",
                ".supreme/mods/online-tournament/high_times/v.txt",
                "http://host/ssbz/index.php?action=room_high_times_file",
                Some(10),
                Some("http://host/ssbz/index.php?action=room_high_times_file"),
            ),
            managed_rule("Other/file.txt", "absolute-not", "https://host2/file", None),
        ]);
        let specs = managed_file_specs(Path::new(GAME), &cfg);
        assert_eq!(specs.len(), 2, "plain targets are not managed files");
        assert_eq!(
            specs[0].rel_key,
            "Saved_Data/village_Tracks_medium_high_times.txt"
        );
        assert_eq!(
            specs[0].local,
            PathBuf::from("/games/supreme/.supreme/mods/online-tournament/high_times/v.txt"),
            "relative local resolved against game_dir"
        );
        assert_eq!(specs[0].poll_interval_secs, Some(10));
        assert_eq!(
            specs[0].push_url.as_deref(),
            Some("http://host/ssbz/index.php?action=room_high_times_file"),
            "declared push URL carried into the spec"
        );
        assert_eq!(specs[1].poll_interval_secs, None, "absent = no polling");
        assert_eq!(specs[1].push_url, None, "absent = fetch-only");
    }

    #[test]
    fn wildcard_managed_rules_are_skipped() {
        // validate() rejects these; the scan stays defensive.
        let cfg = config(vec![managed_rule(
            "Data/Updates/**",
            ".supreme/mods/m/updates",
            "http://host/blob",
            Some(5),
        )]);
        assert!(managed_file_specs(Path::new(GAME), &cfg).is_empty());
    }

    #[test]
    fn plain_targets_only_is_empty() {
        let cfg = config(vec![
            plain_rule("Saved_Data/Defaults.txt", None),
            plain_rule("a.txt", Some("b.txt")),
        ]);
        assert!(managed_file_specs(Path::new(GAME), &cfg).is_empty());
    }

    #[test]
    fn round_trips_through_serde_both_forms() {
        // The untagged enum must keep accepting the classic string form
        // (every mod.json) and the new struct form.
        let classic: RedirectionRule = serde_json::from_value(serde_json::json!({
            "glob_pattern": "a.txt",
            "target": "b.txt",
            "mode": "graceful_fallback"
        }))
        .expect("classic string target");
        assert_eq!(
            classic.target,
            Some(RuleTarget::Path(PathBuf::from("b.txt")))
        );

        let managed: RedirectionRule = serde_json::from_value(serde_json::json!({
            "glob_pattern": "a.txt",
            "target": {
                "local": "b.txt",
                "remote": "http://host/f",
                "poll_interval_secs": 10
            },
            "mode": "graceful_fallback"
        }))
        .expect("managed struct target");
        match managed.target {
            Some(RuleTarget::Managed {
                local,
                remote,
                poll_interval_secs,
                push_url,
            }) => {
                assert_eq!(local, PathBuf::from("b.txt"));
                assert_eq!(remote, "http://host/f");
                assert_eq!(poll_interval_secs, Some(10));
                assert_eq!(push_url, None, "absent push_url deserializes as None");
            }
            other => panic!("expected managed target, got {other:?}"),
        }

        // No-poll serializes without the field (clean mod.json diffs).
        let no_poll = RuleTarget::Managed {
            local: PathBuf::from("b.txt"),
            remote: "http://host/f".to_owned(),
            poll_interval_secs: None,
            push_url: None,
        };
        let v = serde_json::to_value(&no_poll).unwrap();
        assert!(v.get("poll_interval_secs").is_none());
        assert!(v.get("push_url").is_none());

        // a full push-capable target round-trips with its URLs.
        let pushing: RedirectionRule = serde_json::from_value(serde_json::json!({
            "glob_pattern": "a.txt",
            "target": {
                "local": "b.txt",
                "remote": "http://host/f",
                "push_url": "http://host/push?f=${room}"
            },
            "mode": "graceful_fallback"
        }))
        .expect("managed struct target with push_url");
        match pushing.target {
            Some(RuleTarget::Managed {
                push_url: Some(push),
                poll_interval_secs,
                ..
            }) => {
                assert_eq!(push, "http://host/push?f=${room}");
                assert_eq!(poll_interval_secs, None);
            }
            other => panic!("expected managed target with push_url, got {other:?}"),
        }
    }
}