stuffr-cli 0.6.1

use std::io::{Read, Write};
use std::path::{Path, PathBuf};
use std::process::{Command, Stdio};
use std::sync::atomic::{AtomicU64, Ordering};

use flate2::Compression;
use flate2::write::GzEncoder;
use tar::{Builder, Header};

const STUFFR: &str = env!("CARGO_BIN_EXE_stuffr");

/// A token unique to THIS test-binary run, mixed into every temp path below.
///
/// `{pid}-{something}` was NOT unique enough, and the failure it caused reads
/// exactly like a code defect. These directories are never removed on a
/// failing path, PIDs are reused within a day, and a later run landing on a
/// recycled PID then inherits its predecessor's directories *with their
/// contents in them* — so five unrelated tests failed with "already exists"
/// against 4436 leftovers, and deleting the leftovers turned the gate green
/// with no code change at all. A false red that costs a session.
///
/// `RandomState` is the dependency-free source of per-process randomness in
/// `std`: its hasher keys are seeded from the OS, so two concurrent or
/// consecutive runs cannot agree on this token however their PIDs land. It
/// makes the name collision-proof rather than merely unlikely, which is the
/// property that matters — a teardown would still leave the window open for
/// a run that crashes or is interrupted.
static RUN_TOKEN: std::sync::LazyLock<String> = std::sync::LazyLock::new(|| {
    use std::hash::{BuildHasher, Hasher};
    let n = std::collections::hash_map::RandomState::new()
        .build_hasher()
        .finish();
    format!("{}-{n:016x}", std::process::id())
});

fn tmp(name: &str) -> std::path::PathBuf {
    let mut p = std::env::temp_dir();
    p.push(format!("stuffr-cli-{}-{name}", *RUN_TOKEN));
    p
}

// A bare `pack src` with neither `-o` nor `--format` can only default when
// exactly one codec is registered (see `default_format_in`'s doc comment in
// `stuffr::ops`). Phase 1d's `pure` build now registers three, so tests that
// are not actually exercising format inference pin gzip explicitly with
// `--format gzip` rather than relying on a default that no longer exists.

#[test]
fn formats_now_reports_gzip() {
    let out = Command::new(STUFFR).arg("formats").output().unwrap();
    assert!(out.status.success());
    let text = String::from_utf8(out.stdout).unwrap();
    assert!(text.contains("gzip"), "gzip must appear: {text}");
    assert!(
        !text.contains("0 formats"),
        "the build is no longer empty: {text}"
    );
}

#[test]
fn info_names_the_format_and_the_rung() {
    let src = tmp("info.txt");
    let gz = tmp("info.txt.gz");
    let _ = std::fs::remove_file(&gz);
    std::fs::write(&src, b"payload").unwrap();
    assert!(
        Command::new(STUFFR)
            .args(["pack", src.to_str().unwrap(), "--format", "gzip"])
            .status()
            .unwrap()
            .success()
    );

    let out = Command::new(STUFFR)
        .args(["info", gz.to_str().unwrap()])
        .output()
        .unwrap();
    assert!(out.status.success());
    let text = String::from_utf8(out.stdout).unwrap();
    assert!(text.contains("gzip"), "{text}");
    assert!(text.contains("exact"), "a file is read exactly: {text}");

    let _ = std::fs::remove_file(&src);
    let _ = std::fs::remove_file(&gz);
}

#[test]
fn info_json_is_structured_and_names_how_the_format_was_detected() {
    let src = tmp("json2.txt");
    let gz = tmp("json2.txt.gz");
    let _ = std::fs::remove_file(&gz);
    std::fs::write(&src, b"payload").unwrap();
    assert!(
        Command::new(STUFFR)
            .args(["pack", src.to_str().unwrap(), "--format", "gzip"])
            .status()
            .unwrap()
            .success()
    );

    let out = Command::new(STUFFR)
        .args(["info", "--json", gz.to_str().unwrap()])
        .output()
        .unwrap();
    let text = String::from_utf8(out.stdout).unwrap();
    let v: serde_json::Value =
        serde_json::from_str(&text).unwrap_or_else(|e| panic!("not JSON: {e}\n{text}"));

    assert_eq!(v["format"], "gzip");
    assert_eq!(v["rung"], "exact");
    assert_eq!(
        v["detected_by"], "magic",
        "a real gzip file is identified by its magic, not its name"
    );
    assert!(v["warnings"].as_array().unwrap().is_empty());

    let _ = std::fs::remove_file(&src);
    let _ = std::fs::remove_file(&gz);
}

/// `info` has no `--threads` (multi-threaded decode is out of scope this
/// phase), so there is no worker count to resolve — only the memory limit a
/// subsequent pack/unpack would use, either the value `--memory-limit`
/// names or `default_memory_limit()`'s auto-detected reading. Pinning an
/// explicit value keeps this test independent of the host's actual RAM.
#[test]
fn info_reports_the_resolved_memory_limit() {
    let src = tmp("info-mem.txt");
    let gz = tmp("info-mem.txt.gz");
    let _ = std::fs::remove_file(&gz);
    std::fs::write(&src, b"payload").unwrap();
    assert!(
        Command::new(STUFFR)
            .args(["pack", src.to_str().unwrap(), "--format", "gzip"])
            .status()
            .unwrap()
            .success()
    );

    let out = Command::new(STUFFR)
        .args(["info", "--memory-limit", "512M", gz.to_str().unwrap()])
        .output()
        .unwrap();
    assert!(out.status.success());
    let text = String::from_utf8(out.stdout).unwrap();
    // Asserts the RENDERED form, because that is what a user reads. `info`
    // prints "512 MiB" rather than "536870912 bytes" — the raw count is
    // technically the same information and unusable for checking a limit at a
    // glance. If this is ever changed back, the assertion should change with
    // it rather than being loosened to match both.
    assert!(
        text.contains("512 MiB"),
        "an explicit --memory-limit must be reflected in the report: {text}"
    );

    let out = Command::new(STUFFR)
        .args([
            "info",
            "--json",
            "--memory-limit",
            "512M",
            gz.to_str().unwrap(),
        ])
        .output()
        .unwrap();
    let text = String::from_utf8(out.stdout).unwrap();
    let v: serde_json::Value =
        serde_json::from_str(&text).unwrap_or_else(|e| panic!("not JSON: {e}\n{text}"));
    assert_eq!(v["memory_limit"], 512 * 1024 * 1024);

    let _ = std::fs::remove_file(&src);
    let _ = std::fs::remove_file(&gz);
}

/// The whole `info` fidelity rule, all four cases in one place, because the
/// discrimination is TWO-dimensional: it turns on the rung AND on whether the
/// container has anything to lose on a forward read.
///
/// This test exists because the first version of the fix was one-dimensional
/// — it withheld the claim for every container — which merely inverted the
/// dishonesty: "not evaluated" on a `.tar` is a false NEGATIVE, since a
/// forward read of a tar approximates nothing at all. Nothing pinned tar's
/// `info` text, which is exactly how the widening slipped through, so all
/// four cases are pinned here now.
#[test]
fn info_withholds_the_fidelity_claim_only_where_a_forward_read_could_lose_something() {
    let dir = tmp("info-fidelity-matrix");
    let _ = std::fs::remove_dir_all(&dir);
    std::fs::create_dir_all(&dir).unwrap();
    let one = dir.join("one.txt");
    std::fs::write(&one, b"payload").unwrap();

    // Built through the CLI so these are the same archives a user gets.
    let mut archives = Vec::new();
    for (ext, has_trailing_index) in [("zip", true), ("tar", false), ("cpio", false), ("a", false)]
    {
        let path = dir.join(format!("bundle.{ext}"));
        assert!(
            Command::new(STUFFR)
                .args(["pack", one.to_str().unwrap(), "-o", path.to_str().unwrap()])
                .status()
                .unwrap()
                .success(),
            "packing a .{ext} must succeed"
        );
        archives.push((ext, path, has_trailing_index));
    }

    for (ext, path, has_trailing_index) in &archives {
        let bytes = std::fs::read(path).unwrap();

        // (a) SEEKABLE: the container reads its own structures whatever they
        //     are, so nothing is lost and the claim is true for every format
        //     here — zip included.
        let text = String::from_utf8(
            Command::new(STUFFR)
                .args(["info", path.to_str().unwrap()])
                .output()
                .unwrap()
                .stdout,
        )
        .unwrap();
        assert!(text.contains("exact"), ".{ext} from a file: {text}");
        assert!(
            text.contains("nothing approximated"),
            ".{ext} from a FILE was read exactly — the claim is true and must be made: {text}"
        );

        // (b) PIPED: now it depends on the format. Only a trailing index can
        //     be missed by a forward read.
        let text = info_over_stdin(&bytes);
        assert!(text.contains("forward-only"), ".{ext} on a pipe: {text}");
        if *has_trailing_index {
            assert!(
                text.contains("not evaluated"),
                ".{ext} keeps its index at the END of the stream, so a forward read may well \
                 have approximated something and info has not looked: {text}"
            );
            assert!(!text.contains("nothing approximated"), ".{ext}: {text}");
        } else {
            assert!(
                text.contains("nothing approximated"),
                ".{ext} carries every entry's metadata inline, so a forward read loses \
                 NOTHING — withholding the claim here is a false negative: {text}"
            );
            assert!(!text.contains("not evaluated"), ".{ext}: {text}");
        }

        // And the ground truth for the `else` branch above, from the command
        // that DOES open the archive: a piped tar/cpio/ar really does report
        // no warnings, so "nothing approximated" is not merely convenient.
        let mut child = Command::new(STUFFR)
            .args(["test", "-"])
            .stdin(Stdio::piped())
            .stdout(Stdio::piped())
            .stderr(Stdio::piped())
            .spawn()
            .unwrap();
        child.stdin.take().unwrap().write_all(&bytes).unwrap();
        let out = child.wait_with_output().unwrap();
        let stderr = String::from_utf8_lossy(&out.stderr);
        if *has_trailing_index {
            assert!(
                stderr.contains("fidelity warning"),
                ".{ext} on a pipe must really have warnings, or info would be right to \
                 claim none: {stderr}"
            );
        } else {
            assert!(
                out.status.success() && !stderr.contains("fidelity warning"),
                ".{ext} on a pipe must really have NO warnings, which is what makes info's \
                 claim true: {stderr}"
            );
        }
    }

    let _ = std::fs::remove_dir_all(&dir);
}

/// `info` must not report a fidelity conclusion it did not reach.
///
/// `inspect` identifies a stream WITHOUT decoding it — that is its documented
/// contract — so it never opens the container and cannot know what a real
/// read would have approximated. It printed "nothing approximated" anyway,
/// which was harmless for tar, ar and cpio (a forward read of those really
/// does approximate nothing) and a flat contradiction for zip, whose
/// authoritative index is at the END of the stream: `stuffr test -` on the
/// very same bytes reports two warnings.
///
/// The fix is to withhold the claim, not to make `info` open the archive.
/// This test asserts both halves of that: `info` no longer claims, and
/// `test` still does.
#[test]
fn info_on_a_piped_zip_does_not_claim_nothing_was_approximated() {
    let dir = tmp("info-zip-fidelity");
    let _ = std::fs::remove_dir_all(&dir);
    std::fs::create_dir_all(&dir).unwrap();
    let one = dir.join("one.txt");
    std::fs::write(&one, b"payload").unwrap();
    let zip = dir.join("bundle.zip");
    assert!(
        Command::new(STUFFR)
            .args(["pack", one.to_str().unwrap(), "-o", zip.to_str().unwrap()])
            .status()
            .unwrap()
            .success()
    );
    let bytes = std::fs::read(&zip).unwrap();

    let text = info_over_stdin(&bytes);
    assert!(
        text.contains("forward-only"),
        "the rung is still real and still reported: {text}"
    );
    assert!(
        !text.contains("nothing approximated"),
        "info has not opened the archive, so it must not claim this: {text}"
    );
    assert!(
        text.contains("not evaluated"),
        "the line must say the conclusion was withheld, not vanish: {text}"
    );

    // The other half: `test`, which DOES open the archive, still reports the
    // two warnings. Without this the assertion above could be satisfied by
    // having lost the warnings altogether.
    let mut child = Command::new(STUFFR)
        .args(["test", "-"])
        .stdin(Stdio::piped())
        .stdout(Stdio::piped())
        .stderr(Stdio::piped())
        .spawn()
        .unwrap();
    child.stdin.take().unwrap().write_all(&bytes).unwrap();
    let out = child.wait_with_output().unwrap();
    let stderr = String::from_utf8_lossy(&out.stderr);
    assert!(
        stderr.contains("central/trailing index was never read")
            && stderr.contains("entry count is unknown"),
        "`test` opens the archive and must still report both losses: {stderr}"
    );

    // A real FILE is the other side of the rule and was WRONG in round 2:
    // the rung is `exact`, so a zip read from a file consults its central
    // directory and loses nothing. The claim is true there and must be made.
    // `info_withholds_the_fidelity_claim_only_where_a_forward_read_could_lose_something`
    // covers the full matrix; this keeps the contrast next to the defect.
    let out = Command::new(STUFFR)
        .args(["info", zip.to_str().unwrap()])
        .output()
        .unwrap();
    let text = String::from_utf8(out.stdout).unwrap();
    assert!(text.contains("exact"), "a file is read exactly: {text}");
    assert!(
        text.contains("nothing approximated"),
        "a seekable zip reads its central directory, so nothing is approximated: {text}"
    );

    let _ = std::fs::remove_dir_all(&dir);
}

/// The other side of the same fix: a bare CODEC stream has no container to
/// open, so its empty warning list is a genuine finding and `info` must go on
/// reporting it. Without this, "withhold the claim" could have been
/// implemented by withholding it everywhere.
#[test]
fn info_on_a_bare_codec_stream_still_reports_nothing_approximated() {
    let src = tmp("info-codec-fidelity.txt");
    let gz = tmp("info-codec-fidelity.txt.gz");
    let _ = std::fs::remove_file(&gz);
    std::fs::write(&src, b"payload").unwrap();
    assert!(
        Command::new(STUFFR)
            .args(["pack", src.to_str().unwrap(), "--format", "gzip"])
            .status()
            .unwrap()
            .success()
    );
    let bytes = std::fs::read(&gz).unwrap();

    for (what, text) in [
        (
            "a file",
            String::from_utf8(
                Command::new(STUFFR)
                    .args(["info", gz.to_str().unwrap()])
                    .output()
                    .unwrap()
                    .stdout,
            )
            .unwrap(),
        ),
        ("a pipe", info_over_stdin(&bytes)),
    ] {
        assert!(
            text.contains("nothing approximated"),
            "{what}: a bare codec stream has no container to open, so this claim is real \
             and must survive: {text}"
        );
        assert!(!text.contains("not evaluated"), "{what}: {text}");
    }

    // The JSON shape carries the same distinction, since `warnings: []` is
    // ambiguous on its own.
    let out = Command::new(STUFFR)
        .args(["info", "--json", gz.to_str().unwrap()])
        .output()
        .unwrap();
    let v: serde_json::Value = serde_json::from_str(&String::from_utf8(out.stdout).unwrap())
        .expect("info --json must be JSON");
    assert_eq!(v["fidelity_evaluated"], true, "{v}");

    let _ = std::fs::remove_file(&src);
    let _ = std::fs::remove_file(&gz);
}

/// Runs `stuffr info -` over `bytes` and returns its stdout.
fn info_over_stdin(bytes: &[u8]) -> String {
    let mut child = Command::new(STUFFR)
        .args(["info", "-"])
        .stdin(Stdio::piped())
        .stdout(Stdio::piped())
        .spawn()
        .unwrap();
    child.stdin.take().unwrap().write_all(bytes).unwrap();
    let out = child.wait_with_output().unwrap();
    assert!(out.status.success(), "stuffr info - must succeed");
    String::from_utf8(out.stdout).unwrap()
}

/// Together with `info_names_the_format_and_the_rung` (a file, "exact"),
/// this proves the rung is COMPUTED from the source's seekability rather
/// than hardcoded — neither test alone would catch a rung that was pinned
/// to a constant.
#[test]
fn info_over_a_pipe_reports_forward_only_not_exact() {
    let src = tmp("pipe-info.txt");
    let gz = tmp("pipe-info.txt.gz");
    let _ = std::fs::remove_file(&gz);
    std::fs::write(&src, b"payload").unwrap();
    assert!(
        Command::new(STUFFR)
            .args(["pack", src.to_str().unwrap(), "--format", "gzip"])
            .status()
            .unwrap()
            .success()
    );

    let gz_bytes = std::fs::read(&gz).unwrap();

    let mut child = Command::new(STUFFR)
        .args(["info", "-"])
        .stdin(Stdio::piped())
        .stdout(Stdio::piped())
        .spawn()
        .unwrap();
    child.stdin.take().unwrap().write_all(&gz_bytes).unwrap();
    let out = child.wait_with_output().unwrap();

    assert!(out.status.success());
    let text = String::from_utf8(out.stdout).unwrap();
    assert!(text.contains("gzip"), "{text}");
    assert!(
        text.contains("forward-only"),
        "a pipe cannot seek, so the rung must not be exact: {text}"
    );

    let _ = std::fs::remove_file(&src);
    let _ = std::fs::remove_file(&gz);
}

/// `head -c N`, `grep -m1`, `less` — every consumer that decides it has seen
/// enough and closes the pipe early. Rust ignores SIGPIPE, so the writer
/// would otherwise see this as an EPIPE `io::Error` and report a spurious
/// failure; every conventional Unix filter (zcat, gzip -d, cat) treats an
/// early-exiting reader as normal termination instead.
#[test]
fn cat_exits_cleanly_when_the_reader_closes_early() {
    let src = tmp("broken-pipe.txt");
    let gz = tmp("broken-pipe.txt.gz");
    let _ = std::fs::remove_file(&gz);
    // Large enough (and compressible enough) that the decompressed write to
    // stdout badly outlasts the handful of bytes we read below — the point
    // is for the write to still be in flight when we close the read end.
    let payload = "the quick brown fox jumps over the lazy dog\n".repeat(500_000);
    std::fs::write(&src, payload.as_bytes()).unwrap();
    assert!(
        Command::new(STUFFR)
            .args(["pack", src.to_str().unwrap(), "--format", "gzip"])
            .status()
            .unwrap()
            .success()
    );

    let mut child = Command::new(STUFFR)
        .args(["cat", gz.to_str().unwrap()])
        .stdout(Stdio::piped())
        .stderr(Stdio::piped())
        .spawn()
        .unwrap();

    let mut stdout = child.stdout.take().unwrap();
    let mut prefix = [0u8; 16];
    stdout
        .read_exact(&mut prefix)
        .expect("at least a few bytes before we stop reading");
    drop(stdout); // close our read end, like `head` exiting early

    let mut stderr = child.stderr.take().unwrap();
    let mut err_text = String::new();
    stderr.read_to_string(&mut err_text).unwrap();

    let status = child.wait().unwrap();
    assert!(
        status.success(),
        "an early-closing reader must not look like a failure: {status:?}"
    );
    assert!(
        err_text.is_empty(),
        "a clean broken-pipe exit prints nothing: {err_text}"
    );

    let _ = std::fs::remove_file(&src);
    let _ = std::fs::remove_file(&gz);
}

#[test]
fn formats_exits_cleanly_on_a_closed_stdout() {
    // `println!`/`print!` panic on a write error instead of returning one,
    // which bypasses `run`'s BrokenPipe-to-success mapping entirely: `stuffr
    // formats` and `stuffr info` used to exit 101 with "failed printing to
    // stdout: Broken pipe" against a closed reader, even though
    // `destination_is_stdout` already lists both as stdout destinations.
    let mut child = Command::new(STUFFR)
        .arg("formats")
        .stdout(Stdio::piped())
        .stderr(Stdio::piped())
        .spawn()
        .unwrap();

    // Close our read end without reading anything, before the child has a
    // chance to write — same technique as
    // `cat_exits_cleanly_when_the_reader_closes_early`, just without needing
    // a large payload to keep the write in flight: `formats`' whole output
    // fits in one pipe buffer, so what actually needs to race is the drop
    // here against the child's startup, not against a long write.
    drop(child.stdout.take().unwrap());

    let mut stderr = child.stderr.take().unwrap();
    let mut err_text = String::new();
    stderr.read_to_string(&mut err_text).unwrap();

    let status = child.wait().unwrap();
    assert!(
        status.success(),
        "an early-closing reader must not look like a failure: {status:?}"
    );
    assert!(
        err_text.is_empty(),
        "a clean broken-pipe exit prints nothing: {err_text}"
    );
}

#[test]
fn pack_then_unpack_round_trips_through_the_binary() {
    let src = tmp("e2e.txt");
    let gz = tmp("e2e.txt.gz");
    let back = tmp("e2e-back.txt");
    let _ = std::fs::remove_file(&gz);
    let _ = std::fs::remove_file(&back);

    let plain = b"the quick brown fox ".repeat(2000);
    std::fs::write(&src, &plain).unwrap();

    // Bare invocation, no --format: exercises default_format_in's
    // gzip preference, not just gzip named explicitly.
    assert!(
        Command::new(STUFFR)
            .args(["pack", src.to_str().unwrap()])
            .status()
            .unwrap()
            .success()
    );
    assert!(
        gz.exists(),
        "pack must have written the .gz beside the input"
    );
    assert!(src.exists(), "pack must not destroy its input");

    assert!(
        Command::new(STUFFR)
            .args(["unpack", gz.to_str().unwrap(), "-o", back.to_str().unwrap()])
            .status()
            .unwrap()
            .success()
    );
    assert_eq!(
        std::fs::read(&back).unwrap(),
        plain,
        "round trip must be byte-identical"
    );

    for p in [&src, &gz, &back] {
        let _ = std::fs::remove_file(p);
    }
}

#[test]
fn no_sync_is_accepted_by_pack_and_unpack_and_still_round_trips() {
    // Nothing previously exercised --no-sync from the CLI at all. A subprocess
    // test cannot observe the fsync itself being skipped (see
    // stuffr/tests/sync_counter.rs, in the same process as the code under
    // test, for that) — a wrong-polarity `sync: no_sync` instead of
    // `sync: !no_sync` would round-trip identically and this test would not
    // catch it either. What this DOES close is the cheaper, still-real gap
    // that nothing previously confirmed the flag even parses and reaches
    // pack and unpack without breaking anything along the way.
    let src = tmp("nosync-e2e.txt");
    let gz = tmp("nosync-e2e.txt.gz");
    let back = tmp("nosync-e2e-back.txt");
    let _ = std::fs::remove_file(&gz);
    let _ = std::fs::remove_file(&back);

    let plain = b"the quick brown fox ".repeat(500);
    std::fs::write(&src, &plain).unwrap();

    assert!(
        Command::new(STUFFR)
            .args([
                "pack",
                src.to_str().unwrap(),
                "--no-sync",
                "--format",
                "gzip"
            ])
            .status()
            .unwrap()
            .success()
    );
    assert!(gz.exists(), "pack --no-sync must still write the output");

    assert!(
        Command::new(STUFFR)
            .args([
                "unpack",
                gz.to_str().unwrap(),
                "-o",
                back.to_str().unwrap(),
                "--no-sync",
            ])
            .status()
            .unwrap()
            .success()
    );
    assert_eq!(
        std::fs::read(&back).unwrap(),
        plain,
        "--no-sync must cost durability, never correctness"
    );

    for p in [&src, &gz, &back] {
        let _ = std::fs::remove_file(p);
    }
}

#[test]
fn cat_reads_a_stream_on_stdin() {
    // The project's motivating case: `curl … | stuffr cat - | grep pattern`.
    use std::io::Write;
    use std::process::Stdio;

    let src = tmp("pipe.txt");
    let gz = tmp("pipe.txt.gz");
    let _ = std::fs::remove_file(&gz);
    std::fs::write(&src, b"needle in a haystack").unwrap();
    assert!(
        Command::new(STUFFR)
            .args(["pack", src.to_str().unwrap(), "--format", "gzip"])
            .status()
            .unwrap()
            .success()
    );
    let packed = std::fs::read(&gz).unwrap();

    let mut child = Command::new(STUFFR)
        .args(["cat", "-"])
        .stdin(Stdio::piped())
        .stdout(Stdio::piped())
        .spawn()
        .unwrap();
    child.stdin.as_mut().unwrap().write_all(&packed).unwrap();
    let out = child.wait_with_output().unwrap();

    assert!(out.status.success());
    assert_eq!(out.stdout, b"needle in a haystack");

    let _ = std::fs::remove_file(&src);
    let _ = std::fs::remove_file(&gz);
}

/// The motivating case for the whole flush contract: `stuffr pack - -o out.gz`
/// reads a pipe with no path to fall back on, so the output name must be
/// given explicitly, and the write must still land intact.
#[test]
fn pack_reads_input_from_stdin() {
    let out = tmp("stdin-pack.gz");
    let _ = std::fs::remove_file(&out);
    let plain = b"stdin plaintext, packed then verified byte for byte".repeat(200);

    let mut child = Command::new(STUFFR)
        .args(["pack", "-", "-o", out.to_str().unwrap()])
        .stdin(Stdio::piped())
        .stdout(Stdio::piped())
        .stderr(Stdio::piped())
        .spawn()
        .unwrap();
    child.stdin.take().unwrap().write_all(&plain).unwrap();
    let result = child.wait_with_output().unwrap();
    assert!(
        result.status.success(),
        "stderr: {}",
        String::from_utf8_lossy(&result.stderr)
    );
    assert!(out.exists(), "pack must have written the output file");

    // Round-trip through the binary rather than just checking the file
    // exists — a truncated or otherwise corrupt stream must fail here.
    let cat_out = Command::new(STUFFR)
        .args(["cat", out.to_str().unwrap()])
        .output()
        .unwrap();
    assert!(cat_out.status.success());
    assert_eq!(cat_out.stdout, plain, "round trip must be byte-identical");

    let _ = std::fs::remove_file(&out);
}

/// The other motivating case: `stuffr pack x -o -` writes to a destination
/// (stdout) that may be fully buffered and never see a newline — exactly the
/// scenario `Sink::finish`'s flush contract exists for. A stream that was
/// never flushed would truncate here.
#[test]
fn pack_writes_output_to_stdout() {
    let src = tmp("stdout-pack.txt");
    let _ = std::fs::remove_file(&src);
    let plain = b"payload written straight through to stdout by pack".repeat(200);
    std::fs::write(&src, &plain).unwrap();

    let pack_out = Command::new(STUFFR)
        .args(["pack", src.to_str().unwrap(), "--format", "gzip", "-o", "-"])
        .output()
        .unwrap();
    assert!(
        pack_out.status.success(),
        "stderr: {}",
        String::from_utf8_lossy(&pack_out.stderr)
    );
    assert_eq!(
        &pack_out.stdout[..2],
        &[0x1f, 0x8b],
        "must be a real gzip stream"
    );

    // Pipe the captured bytes back through `stuffr cat -`: a truncated stream
    // (an unflushed `Sink::finish`, notably) fails the equality below rather
    // than merely "existing".
    let mut child = Command::new(STUFFR)
        .args(["cat", "-"])
        .stdin(Stdio::piped())
        .stdout(Stdio::piped())
        .spawn()
        .unwrap();
    child
        .stdin
        .take()
        .unwrap()
        .write_all(&pack_out.stdout)
        .unwrap();
    let cat_out = child.wait_with_output().unwrap();
    assert!(cat_out.status.success());
    assert_eq!(
        cat_out.stdout, plain,
        "round trip through a piped stdout destination must be byte-identical"
    );

    let _ = std::fs::remove_file(&src);
}

/// Mirrors `info_over_a_pipe_reports_forward_only_not_exact`: `compress` must
/// compute its own fidelity rung from the source's actual seekability rather
/// than assuming `Exact`, the same way `decompress` already does.
#[test]
fn pack_over_a_pipe_reports_forward_only_not_exact() {
    let out = tmp("pack-rung-pipe.gz");
    let _ = std::fs::remove_file(&out);
    let plain = b"payload".repeat(50);

    let mut child = Command::new(STUFFR)
        .args(["pack", "-", "-o", out.to_str().unwrap()])
        .stdin(Stdio::piped())
        .stdout(Stdio::piped())
        .stderr(Stdio::piped())
        .spawn()
        .unwrap();
    child.stdin.take().unwrap().write_all(&plain).unwrap();
    let result = child.wait_with_output().unwrap();
    assert!(result.status.success());
    let err_text = String::from_utf8_lossy(&result.stderr);
    assert!(
        err_text.contains("forward-only"),
        "a pipe cannot seek, so pack's reported rung must not be exact: {err_text}"
    );

    let _ = std::fs::remove_file(&out);
}

/// The other half of the pair above: together they prove the rung is
/// computed rather than a constant either way.
#[test]
fn pack_of_a_seekable_file_reports_exact() {
    let src = tmp("pack-rung-file.txt");
    let gz = tmp("pack-rung-file.txt.gz");
    let _ = std::fs::remove_file(&gz);
    std::fs::write(&src, b"payload").unwrap();

    // Bare invocation, no --format: exercises default_format_in's
    // gzip preference, not just gzip named explicitly.
    let out = Command::new(STUFFR)
        .args(["pack", src.to_str().unwrap()])
        .output()
        .unwrap();
    assert!(out.status.success());
    let err_text = String::from_utf8_lossy(&out.stderr);
    assert!(err_text.contains("exact"), "{err_text}");

    let _ = std::fs::remove_file(&src);
    let _ = std::fs::remove_file(&gz);
}

#[test]
fn an_existing_output_is_refused_with_exit_two() {
    let src = tmp("clash.txt");
    let gz = tmp("clash.txt.gz");
    std::fs::write(&src, b"payload").unwrap();
    std::fs::write(&gz, b"PRE-EXISTING").unwrap();

    let out = Command::new(STUFFR)
        .args(["pack", src.to_str().unwrap(), "--format", "gzip"])
        .output()
        .unwrap();
    assert_eq!(out.status.code(), Some(2), "usage errors exit 2");
    assert!(String::from_utf8_lossy(&out.stderr).contains("--force"));
    assert_eq!(
        std::fs::read(&gz).unwrap(),
        b"PRE-EXISTING",
        "the refused command changed nothing"
    );

    let _ = std::fs::remove_file(&src);
    let _ = std::fs::remove_file(&gz);
}

#[test]
fn a_bomb_exits_six_and_leaves_no_partial_output() {
    let src = tmp("boom.bin");
    let gz = tmp("boom.bin.gz");
    let out_path = tmp("boom-out.bin");
    let _ = std::fs::remove_file(&gz);
    let _ = std::fs::remove_file(&out_path);

    std::fs::write(&src, vec![0u8; 2 * 1024 * 1024]).unwrap();
    assert!(
        Command::new(STUFFR)
            .args(["pack", src.to_str().unwrap(), "--format", "gzip"])
            .status()
            .unwrap()
            .success()
    );

    let out = Command::new(STUFFR)
        .args([
            "unpack",
            gz.to_str().unwrap(),
            "-o",
            out_path.to_str().unwrap(),
            "--max-ratio",
            "100",
        ])
        .output()
        .unwrap();
    assert_eq!(out.status.code(), Some(6), "resource limits exit 6");
    assert!(
        !out_path.exists(),
        "a refused decode must leave no partial file"
    );

    let _ = std::fs::remove_file(&src);
    let _ = std::fs::remove_file(&gz);
}

#[test]
fn an_unknown_verb_exits_two() {
    let out = Command::new(STUFFR).arg("bogus").output().unwrap();
    assert_eq!(out.status.code(), Some(2));
}

/// Keeps `stuffr --examples` honest as the tool grows: every format this build
/// registers, and every long flag / subcommand clap knows about, must be
/// mentioned on the page. This is what makes the page a contract rather than
/// prose that quietly goes stale — Phase 1d adding a codec, or any future
/// flag, fails this test until the page is updated to match.
#[test]
fn examples_page_covers_every_format_and_flag() {
    use clap::CommandFactory;
    use stuffr_cli::cli::Cli;

    let out = Command::new(STUFFR).arg("--examples").output().unwrap();
    assert!(out.status.success(), "stuffr --examples must exit 0");
    let text = String::from_utf8(out.stdout).unwrap();

    for row in stuffr::registry().matrix() {
        let id = row.id.as_str();
        assert!(
            text.contains(id),
            "the examples page does not mention the `{id}` format"
        );
    }

    let root = Cli::command();
    for sub in root.get_subcommands() {
        let name = sub.get_name();
        if name == "help" {
            continue;
        }
        assert!(
            text.contains(name),
            "the examples page does not mention the `{name}` subcommand"
        );
        for arg in sub.get_arguments() {
            let Some(long) = arg.get_long() else {
                continue;
            };
            if long == "help" || long == "version" {
                continue;
            }
            let flag = format!("--{long}");
            assert!(
                text.contains(flag.as_str()),
                "the examples page does not mention {flag}"
            );
        }
    }
}

/// The Phase 2 final review's I4: `examples_page_covers_every_format_and_flag`
/// above passed a page that still described a THREE-container build with
/// "fourteen rows", "all fourteen formats", "All three containers — tar, ar
/// and cpio", "eleven codecs and three containers" and "Still to come:
/// **zip**" — because the substring "zip" appears elsewhere on the page and
/// a mention was all it checked. This is the one document a user reads, so
/// a mention is not enough.
///
/// Three classes of staleness, each derived from the registry rather than
/// hard-coded, so adding a format in a later phase fails this test until
/// the page is updated:
///
/// 1. A "still to come" claim about a format that is REGISTERED.
/// 2. A written-out count of formats or containers that does not match the
///    registry's own.
/// 3. A registered container missing from the containers sentence.
#[test]
fn the_examples_page_cannot_carry_a_stale_count_or_a_shipped_still_to_come() {
    let out = Command::new(STUFFR).arg("--examples").output().unwrap();
    assert!(out.status.success());
    let text = String::from_utf8(out.stdout).unwrap();

    let rows = stuffr::registry().matrix();
    let containers: Vec<&str> = rows
        .iter()
        .filter(|r| stuffr::registry().container(r.id).is_some())
        .map(|r| r.id.as_str())
        .collect();
    let codecs: Vec<&str> = rows
        .iter()
        .filter(|r| stuffr::registry().container(r.id).is_none())
        .map(|r| r.id.as_str())
        .collect();

    // `lha`/`arj` (Phase 3b) used to be the first containers gated behind a
    // feature `pure` did not carry, back when `default = ["pure"]` and
    // `legacy` lived only in `full`/`--all-features` — so this test binary
    // could genuinely see two different container counts depending on
    // which `make check` leg compiled it (4 under `test-pure`, 6 under
    // `--all-features`), and the code below used to carry a PROJECTED count
    // (`base_containers.len() + LEGACY_ONLY_CONTAINERS.len()`) for the legs
    // where it could not observe `lha`/`arj` directly.
    //
    // That projection is now dead code, not just an unused branch: `legacy`
    // joined `stuffr`'s `default` feature set, and — measured, not assumed —
    // there is no longer any `cargo build`/`cargo test` of the `stuffr-cli`
    // binary that lacks it, `--no-default-features` included.
    // `crates/stuffr-cli/Cargo.toml`'s `[dependencies]` entry,
    // `stuffr = { path = "../stuffr", ..., features = ["serde"] }`, does not
    // set `default-features = false`, so it always requests `stuffr`'s
    // `default` (now `pure` **and** `legacy`) regardless of what
    // `--no-default-features`/`--features` this binary itself was built
    // with — `stuffr-cli` declares no `[features] default` of its own for
    // `--no-default-features` to even disable. Verified directly: `cargo
    // build -p stuffr-cli --no-default-features` (no `--features` at all)
    // still ships `lha`, `arj` and `compress` in `stuffr formats`. So
    // `containers.len()` is trusted unconditionally below — there is no
    // real build left for a projection to stand in for.
    //
    // `base_containers` (the tier-invariant round-trip quartet: tar/ar/
    // cpio/zip) is kept, because the page still legitimately describes that
    // subset by itself in some sentences (e.g. "four round-trip
    // containers", distinct from "six total").
    const LEGACY_ONLY_CONTAINERS: &[&str] = &["lha", "arj", "arc", "zoo"];
    let base_containers: Vec<&str> = containers
        .iter()
        .copied()
        .filter(|id| !LEGACY_ONLY_CONTAINERS.contains(id))
        .collect();
    let full_container_count = containers.len();

    // (1) No "still to come" line may name a format this build registers.
    // Checked per SENTENCE, so "still to come: walking a directory tree"
    // sitting in the same paragraph as the word "zip" does not trip it.
    for sentence in text.split(['.', '\n']) {
        let lower = sentence.to_lowercase();
        if !(lower.contains("still to come") || lower.contains("not yet supported")) {
            continue;
        }
        for id in rows.iter().map(|r| r.id.as_str()) {
            assert!(
                !sentence.contains(id),
                "the page says `{id}` is still to come, but this build registers it: \
                 {sentence:?}"
            );
        }
    }

    // (2) Any written-out count applied to "formats", "rows" or
    //     "containers" must be the real one.
    const NUMBERS: &[(&str, usize)] = &[
        ("one", 1),
        ("two", 2),
        ("three", 3),
        ("four", 4),
        ("five", 5),
        ("six", 6),
        ("seven", 7),
        ("eight", 8),
        ("nine", 9),
        ("ten", 10),
        ("eleven", 11),
        ("twelve", 12),
        ("thirteen", 13),
        ("fourteen", 14),
        ("fifteen", 15),
        ("sixteen", 16),
        ("seventeen", 17),
        ("eighteen", 18),
        ("nineteen", 19),
        ("twenty", 20),
    ];
    // Whitespace-normalised: the page wraps, so a count and its noun
    // split across a line break must still read as one phrase.
    let flat = text.split_whitespace().collect::<Vec<_>>().join(" ");
    let words: Vec<&str> = flat.split(' ').collect();
    for pair in words.windows(2) {
        let (word, next) = (
            pair[0].trim_matches(|c: char| !c.is_alphanumeric()),
            pair[1],
        );
        let Some((_, value)) = NUMBERS.iter().find(|(w, _)| *w == word.to_lowercase()) else {
            continue;
        };
        let noun = next
            .trim_matches(|c: char| !c.is_alphanumeric())
            .to_lowercase();
        if noun == "containers" {
            // Either the tier-invariant base count (the round-trip
            // quartet) or the full (`pure` + `legacy`) count is a true
            // claim — see `full_container_count`'s own comment above for
            // why it is now trusted straight from the live registry with
            // no projection: every real build of this binary compiles
            // `legacy` in, so a `lha`/`arj` registration failure would
            // already show up as `containers.len()` shrinking, not as a
            // stale count surviving here.
            assert!(
                *value == base_containers.len() || *value == full_container_count,
                "the page says `{word} containers`, but this build has {} base containers \
                 ({} once every legacy container is counted) — the counts on this page are \
                 what a user trusts before running `stuffr formats`",
                base_containers.len(),
                full_container_count
            );
            continue;
        }
        let expected = match noun.as_str() {
            "formats" | "rows" => rows.len(),
            "codecs" => codecs.len(),
            _ => continue,
        };
        assert_eq!(
            *value, expected,
            "the page says `{word} {noun}`, but this build has {expected} — the counts \
             on this page are what a user trusts before running `stuffr formats`"
        );
    }

    // (3) At least one sentence must both COUNT the containers and NAME
    //     every one of them. Matched as whole words, not substrings —
    //     `ar` occurs inside dozens of ordinary words, which is exactly
    //     the weakness that let "Still to come: zip" survive on a page
    //     that had already shipped zip.
    let counting_sentences: Vec<&str> = flat
        .split(". ")
        .filter(|sentence| {
            let l = sentence.to_lowercase();
            NUMBERS
                .iter()
                .any(|(w, _)| l.contains(&format!("{w} containers")))
        })
        .collect();
    assert!(
        !counting_sentences.is_empty(),
        "the page must state how many containers this build has"
    );
    let names_them_all = counting_sentences.iter().any(|sentence| {
        containers.iter().all(|id| {
            sentence
                .split(|c: char| !c.is_alphanumeric())
                .any(|word| word == *id)
        })
    });
    assert!(
        names_them_all,
        "no sentence both counts the containers and names every one of them \
         ({containers:?}); the counting sentences are {counting_sentences:?}"
    );
}

/// Pins ONE documented claim end-to-end rather than all of them: the page's
/// very first example, run verbatim in its own directory. `--examples`'
/// header claims "Everything below runs against this build as shown" —
/// `examples_page_covers_every_format_and_flag` only checks that words are
/// *mentioned*, so a page whose first command was actually broken (as this
/// task's own investigation found `stuffr pack notes.txt` briefly was) would
/// still pass it. A full executable-docs test extracting and running every
/// line on the page is the right long-term fix; this is the narrow stopgap.
#[test]
fn examples_pages_first_worked_example_runs_as_documented() {
    let dir = tmp("examples-first-example-dir");
    let _ = std::fs::remove_dir_all(&dir);
    std::fs::create_dir_all(&dir).unwrap();
    let notes = dir.join("notes.txt");
    let packed = dir.join("notes.txt.gz");
    std::fs::write(&notes, b"the documented example's payload").unwrap();

    // Verbatim: `stuffr pack notes.txt`, run from the directory containing it.
    let out = Command::new(STUFFR)
        .arg("pack")
        .arg("notes.txt")
        .current_dir(&dir)
        .output()
        .unwrap();
    assert!(
        out.status.success(),
        "stderr: {}",
        String::from_utf8_lossy(&out.stderr)
    );

    assert!(
        packed.exists(),
        "the page says this writes notes.txt.gz beside it"
    );
    assert!(
        notes.exists(),
        "the page says the input, notes.txt, is left alone"
    );

    let _ = std::fs::remove_dir_all(&dir);
}

/// **A behavioural claim on the `--examples` page, pinned by RUNNING it.**
///
/// The page ships INSIDE the binary and is where this project points users
/// for exit-code contracts, and the count guards around it derive their
/// expectations from the live registry — which is exactly why the COUNT
/// claims were all correct and a BEHAVIOURAL one was not. Phase 3c's final
/// review found `examples.txt`'s ARJ entry promising "A symlink is refused
/// rather than stored (exit 3)" when the measured answer is exit 0 with a
/// fidelity warning, exit 4 under `--strict-fidelity`. Nothing in the tree
/// could have said so: the sentence was prose, and prose is not checked.
///
/// Two arms, and the first is what gives the second its authority:
///
/// 1. **Measured.** Every container the registry says can WRITE is packed
///    over a tree holding a symlink, plain and `--strict-fidelity`. The
///    answer is 0 or 4 — stored (tar, cpio, zip) or skipped with a named
///    fidelity loss (ar, lha, arj) — and never 3. That is a real contract
///    of its own, derived from the registry rather than a list here, so a
///    seventh writable container joins it automatically.
/// 2. **The page is held to it.** No sentence may say a symlink is refused
///    at exit 3, because no container does that.
///
/// What this does NOT reach, stated so the next reader does not overtrust
/// it: only the symlink class, and only the exit-3 verdict. A page claiming
/// the wrong exit code for some other refusal is still unchecked prose. The
/// class is cheap to extend one measured case at a time; it is not a general
/// executable-docs harness and does not pretend to be.
#[test]
fn a_symlink_in_a_walked_tree_is_never_refused_and_the_page_may_not_say_it_is() {
    let dir = tmp("examples-symlink-verdict");
    let _ = std::fs::remove_dir_all(&dir);
    let tree = dir.join("tree");
    std::fs::create_dir_all(&tree).unwrap();
    std::fs::write(tree.join("file.txt"), b"payload").unwrap();
    std::os::unix::fs::symlink("file.txt", tree.join("link.txt")).unwrap();

    let registry = stuffr::registry();
    let mut measured = 0usize;
    for row in registry.matrix() {
        if registry.container(row.id).is_none() || !row.write {
            continue;
        }
        let id = row.id.as_str();
        let out_path = dir.join(format!("out-{id}"));
        for strict in [false, true] {
            let _ = std::fs::remove_file(&out_path);
            let mut cmd = Command::new(STUFFR);
            cmd.arg("pack")
                .arg(&tree)
                .arg("-o")
                .arg(&out_path)
                .arg("--format")
                .arg(id);
            if strict {
                cmd.arg("--strict-fidelity");
            }
            let out = cmd.output().unwrap();
            let code = out.status.code();
            assert!(
                matches!(code, Some(0) | Some(4)),
                "`pack` over a tree containing a symlink answered exit {code:?} for `{id}` \
                 (strict-fidelity: {strict}). A kind a container cannot store is a fidelity \
                 LOSS, never a refusal — and exit 3 in particular is what `examples.txt` \
                 wrongly promised for `arj` until Phase 3c's final review measured it. \
                 stderr: {}",
                String::from_utf8_lossy(&out.stderr)
            );
        }
        measured += 1;
    }
    assert!(
        measured >= 6,
        "only {measured} writable containers were exercised; this build registers six, so the \
         registry walk has stopped finding them and the measurement proves nothing"
    );
    let _ = std::fs::remove_dir_all(&dir);

    let out = Command::new(STUFFR).arg("--examples").output().unwrap();
    assert!(out.status.success(), "stuffr --examples must exit 0");
    let text = String::from_utf8(out.stdout).unwrap();
    // Whitespace-normalised, because the page wraps and a claim split across
    // a line break must still read as one sentence.
    let flat = text.split_whitespace().collect::<Vec<_>>().join(" ");
    for sentence in flat.split(". ") {
        let lower = sentence.to_lowercase();
        if !lower.contains("symlink") {
            continue;
        }
        if !(lower.contains("refused") || lower.contains("refuses")) {
            continue;
        }
        assert!(
            !lower.contains("exit 3"),
            "the examples page says a symlink is refused at exit 3, which the measurement \
             above proves no writable container does: {sentence:?}"
        );
    }
}

/// `pack --format arc`/`zoo` must refuse CLEARLY — exit 3, naming
/// the format as readable but not writable by this build — never fail
/// obscurely (an internal panic, a bare i/o error, or an unrelated exit
/// code). All three take the SAME route: `Registry::require_container_writer`
/// refuses on the declared capability, raising `Error::CapabilityUnavailable`.
/// Each module's own `create()` still returns that same error as an
/// unreachable backstop. This pins it all the way through the CLI rather
/// than only at the trait level each module's unit tests already cover.
///
/// **`compress` left this list in Phase 3c Task 5, `lha` in Task 6 and
/// `arj` in Task 7** — none is read-only any more, so none belongs among
/// the formats this test proves REFUSE to write.
/// `pack_writes_a_compress_stream_the_system_tool_reads`,
/// `pack_writes_an_lha_archive_the_system_tool_reads` and
/// `pack_writes_an_arj_archive_stuffr_reads_back` below are their positive
/// counterparts, proving the opposite claim for the three formats that
/// changed. The third is named differently on purpose: no `arj`/`unarj`
/// binary is obtainable, so that one is a round trip through stuffr's own
/// reader and nothing outside this project judges it.
///
/// Runtime-checked, not `cfg`-gated. `stuffr-cli` does declare a `legacy`
/// feature (a passthrough to `stuffr/legacy`, so `cargo install stuffr-cli
/// --features legacy` still works — it is just no longer required), but
/// `cargo test --workspace --all-features` unifies features across the
/// workspace, so this binary's own `cfg!(feature = "legacy")` is not what
/// decides whether the four formats are compiled in — the live registry
/// is, the same way `examples_page_covers_every_format_and_flag` above
/// already asks it for container counts.
///
/// The `!registered` skip below is now believed unreachable rather than
/// removed: `legacy` joined `stuffr`'s `default` feature set, and
/// `stuffr-cli`'s own dependency on `stuffr` requests `stuffr`'s defaults
/// unconditionally (see the dead-projection comment in
/// `the_examples_page_cannot_carry_a_stale_count_or_a_shipped_still_to_come`
/// above for the measured proof), so there is no longer a `cargo test`
/// invocation of this binary where any of the four is absent. Kept as a
/// guard rather than an assertion of reachability: if a future Cargo.toml
/// edit ever makes a legacy-less `stuffr-cli` build possible again (e.g. by
/// adding `default-features = false` to that dependency edge), this test
/// should degrade gracefully rather than fail on a tier it was never
/// written to cover.
#[test]
fn pack_refuses_a_read_only_legacy_format_clearly() {
    let registry = stuffr::registry();
    let dir = tmp("legacy-format-refusal-dir");
    let _ = std::fs::remove_dir_all(&dir);
    std::fs::create_dir_all(&dir).unwrap();
    let src = dir.join("notes.txt");
    std::fs::write(&src, b"payload").unwrap();

    for (name, out_ext) in [("arc", "arc"), ("zoo", "zoo")] {
        let registered = registry.container(stuffr::FormatId::new(name)).is_some()
            || registry.codec(stuffr::FormatId::new(name)).is_some();
        if !registered {
            // `legacy` was not compiled into this build — believed
            // unreachable now that `legacy` is in `stuffr`'s `default`
            // feature set (see this test's own doc comment), but if it ever
            // fires again, the read-only refusal this test pins simply
            // does not exist on that build, and asserting "unknown format"
            // instead would duplicate a claim `formats_now_reports_gzip`-
            // style tests already make elsewhere.
            continue;
        }
        let dst = dir.join(format!("out.{out_ext}"));
        let res = Command::new(STUFFR)
            .args([
                "pack",
                src.to_str().unwrap(),
                "--format",
                name,
                "-o",
                dst.to_str().unwrap(),
            ])
            .output()
            .unwrap();
        let err = String::from_utf8_lossy(&res.stderr);
        assert_eq!(
            res.status.code(),
            Some(3),
            "`--format {name}` must refuse at exit 3 (this build cannot do that), got \
             {:?}; stderr: {err}",
            res.status.code()
        );
        // ONE sentence for both, which is the point of the shared
        // gate: the containers used to say "unsupported: ARJ is
        // read-only in this build" (their own hand-rolled
        // `Container::create` refusal) before `require_container_writer`
        // existed, and a comment here called that difference "phrasing" when
        // it was two different code paths. A per-format substring would let
        // them drift apart again without failing.
        let lower = err.to_lowercase();
        assert!(
            lower.contains(&format!(
                "`{name}` can be read but not written by this build"
            )),
            "`--format {name}`'s refusal must be the one shared capability sentence, \
             naming the format, rather than a per-format phrasing: {err}"
        );
        assert!(
            !dst.exists(),
            "a refused pack must not leave a partial `{}` behind",
            dst.display()
        );
    }

    let _ = std::fs::remove_dir_all(&dir);
}

/// The positive counterpart to `pack_refuses_a_read_only_legacy_format_
/// clearly` above, for the one format Phase 3c Task 5 moved out of that
/// list: `pack --format compress` must actually write a `.Z` file the real
/// system `uncompress` can read back, at the default level (16, not the
/// maxbits-9 special case `compress_z.rs`'s own unit tests cover directly).
#[test]
fn pack_writes_a_compress_stream_the_system_tool_reads() {
    let uncompress_bin = require_bin("uncompress");
    let dir = tmp("compress-write-dir");
    let _ = std::fs::remove_dir_all(&dir);
    std::fs::create_dir_all(&dir).unwrap();
    let src = dir.join("notes.txt");
    let plain = b"the quick brown fox jumps over the lazy dog\n".repeat(200);
    std::fs::write(&src, &plain).unwrap();
    // Uppercase `.Z`, deliberately: the system `uncompress` appends `.Z`
    // itself when the name it is given does not already end in it (both
    // implementations), so a lowercase `.z` — this format's own registered
    // extension, and the natural spelling `--format compress` writing to a
    // bare `-o` name would otherwise pick — would have it look for
    // `notes.txt.z.Z` and fail with "No such file or directory".
    let dst = dir.join("notes.txt.Z");

    let res = Command::new(STUFFR)
        .args([
            "pack",
            src.to_str().unwrap(),
            "--format",
            "compress",
            "-o",
            dst.to_str().unwrap(),
        ])
        .output()
        .unwrap();
    assert!(
        res.status.success(),
        "pack --format compress must now succeed: {}",
        String::from_utf8_lossy(&res.stderr)
    );
    assert!(dst.exists(), "pack must have written {}", dst.display());

    let out = Command::new(&uncompress_bin)
        .arg("-c")
        .arg(&dst)
        .output()
        .unwrap();
    assert!(
        out.status.success(),
        "the system uncompress must read this build's own .Z output: {}",
        String::from_utf8_lossy(&out.stderr)
    );
    assert_eq!(
        out.stdout, plain,
        "the system uncompress's output must match the original plaintext exactly"
    );

    // stuffr's own reader must agree too.
    let cat = Command::new(STUFFR)
        .args(["cat", dst.to_str().unwrap()])
        .output()
        .unwrap();
    assert!(cat.status.success());
    assert_eq!(cat.stdout, plain);

    let _ = std::fs::remove_dir_all(&dir);
}

/// The positive counterpart to `pack_refuses_a_read_only_legacy_format_
/// clearly` above, for the format Phase 3c Task 6 moved out of that list.
///
/// A CONTAINER, not a codec, so this proves more than its `compress`
/// sibling does: a whole directory tree is packed — files and the directory
/// entry above them — the real `lhasa` reads the result back, and stuffr's
/// own `list` agrees on the entry names. `lhasa` is decompress-only, which
/// is exactly what makes it the right witness here and why no such test
/// could exist while LHA was read-only.
#[test]
fn pack_writes_an_lha_archive_the_system_tool_reads() {
    let lha_bin = require_lhasa();
    let banner = lhasa_banner(&lha_bin);
    let dir = tmp("lha-write-dir");
    let _ = std::fs::remove_dir_all(&dir);
    std::fs::create_dir_all(dir.join("tree/sub")).unwrap();
    let alpha = b"the quick brown fox jumps over the lazy dog\n".repeat(120);
    std::fs::write(dir.join("tree/alpha.txt"), &alpha).unwrap();
    std::fs::write(dir.join("tree/sub/beta.bin"), b"beta\n").unwrap();
    let dst = dir.join("out.lzh");

    let res = Command::new(STUFFR)
        .args([
            "pack",
            dir.join("tree").to_str().unwrap(),
            "--format",
            "lha",
            "-o",
            dst.to_str().unwrap(),
        ])
        .output()
        .unwrap();
    assert!(
        res.status.success(),
        "pack --format lha must now succeed: {}",
        String::from_utf8_lossy(&res.stderr)
    );
    assert!(dst.exists(), "pack must have written {}", dst.display());

    // The external witness: lhasa verifies every entry's CRC-16 itself.
    let test = Command::new(&lha_bin).arg("t").arg(&dst).output().unwrap();
    assert!(
        test.status.success(),
        "{banner} must accept an archive stuffr wrote: {}\n{}",
        String::from_utf8_lossy(&test.stdout),
        String::from_utf8_lossy(&test.stderr)
    );

    // ...and the bytes it extracts must be the bytes that went in. A CRC
    // agreeing proves the check value matches, not that the plaintext is
    // right.
    let out = dir.join("out");
    std::fs::create_dir_all(&out).unwrap();
    let extract = Command::new(&lha_bin)
        .arg(format!("xfw={}", out.display()))
        .arg(&dst)
        .output()
        .unwrap();
    assert!(
        extract.status.success(),
        "{banner} must extract it: {}",
        String::from_utf8_lossy(&extract.stderr)
    );
    assert_eq!(std::fs::read(out.join("tree/alpha.txt")).unwrap(), alpha);
    assert_eq!(
        std::fs::read(out.join("tree/sub/beta.bin")).unwrap(),
        b"beta\n"
    );

    // stuffr's own reader must agree on what is in there.
    let list = Command::new(STUFFR)
        .args(["list", dst.to_str().unwrap()])
        .output()
        .unwrap();
    assert!(list.status.success());
    let listing = String::from_utf8_lossy(&list.stdout);
    for name in ["tree/alpha.txt", "tree/sub/beta.bin"] {
        assert!(
            listing.contains(name),
            "`stuffr list` lost {name}: {listing}"
        );
    }

    let _ = std::fs::remove_dir_all(&dir);
}

/// The positive counterpart to `pack_refuses_a_read_only_legacy_format_
/// clearly` above, for the format Phase 3c Task 7 moved out of that list —
/// **and the one with no external witness at all.**
///
/// Its two siblings are judged from outside this project: the real
/// `uncompress`(1) reads what `--format compress` writes, and `lhasa` reads
/// what `--format lha` writes. No `arj`/`unarj` binary is obtainable here,
/// so this is a round trip through stuffr's OWN reader and proves exactly
/// that much — the archive stuffr writes is one stuffr reads back with the
/// tree intact. Everything that could be done about that gap was done in
/// `legacy::arj`'s unit tests (`spec_constraints_the_reader_never_checks`
/// asserts, on emitted bytes, the spec constraints `unarj-rs` ignores) and
/// it is named here so this test is not mistaken for the same kind of
/// evidence its two siblings carry.
///
/// A CONTAINER, so a whole tree goes in — files and the directory entry
/// above them — and the entries come back with their names, their contents
/// and their kinds.
#[test]
fn pack_writes_an_arj_archive_stuffr_reads_back() {
    let dir = tmp("arj-write-dir");
    let _ = std::fs::remove_dir_all(&dir);
    std::fs::create_dir_all(dir.join("tree/sub")).unwrap();
    let alpha = b"the quick brown fox jumps over the lazy dog\n".repeat(120);
    std::fs::write(dir.join("tree/alpha.txt"), &alpha).unwrap();
    std::fs::write(dir.join("tree/sub/beta.bin"), b"beta\n").unwrap();
    let dst = dir.join("out.arj");

    let res = Command::new(STUFFR)
        .args([
            "pack",
            dir.join("tree").to_str().unwrap(),
            "--format",
            "arj",
            "-o",
            dst.to_str().unwrap(),
        ])
        .output()
        .unwrap();
    assert!(
        res.status.success(),
        "pack --format arj must now succeed: {}",
        String::from_utf8_lossy(&res.stderr)
    );
    assert!(dst.exists(), "pack must have written {}", dst.display());

    // The magic the registry detects it by, at offset 0 — so the file is
    // recognised as ARJ without `--format`, which the `list` below relies
    // on.
    let head = std::fs::read(&dst).unwrap();
    assert_eq!(
        &head[0..2],
        &[0x60, 0xEA],
        "an ARJ archive opens with its own header id"
    );

    // `test` verifies every entry's CRC-32, which is the strongest check
    // available without a second implementation.
    let verify = Command::new(STUFFR)
        .args(["test", dst.to_str().unwrap()])
        .output()
        .unwrap();
    assert!(
        verify.status.success(),
        "`stuffr test` must accept an archive stuffr wrote: {}",
        String::from_utf8_lossy(&verify.stderr)
    );

    let list = Command::new(STUFFR)
        .args(["list", dst.to_str().unwrap()])
        .output()
        .unwrap();
    assert!(list.status.success());
    let listing = String::from_utf8_lossy(&list.stdout);
    for name in ["tree/alpha.txt", "tree/sub/beta.bin"] {
        assert!(
            listing.contains(name),
            "`stuffr list` lost {name}: {listing}"
        );
    }

    // ...and the bytes have to come back, not merely the names.
    let out = dir.join("out");
    let unpack = Command::new(STUFFR)
        .args(["unpack", dst.to_str().unwrap(), "-C", out.to_str().unwrap()])
        .output()
        .unwrap();
    assert!(
        unpack.status.success(),
        "unpack must restore the tree: {}",
        String::from_utf8_lossy(&unpack.stderr)
    );
    assert_eq!(std::fs::read(out.join("tree/alpha.txt")).unwrap(), alpha);
    assert_eq!(
        std::fs::read(out.join("tree/sub/beta.bin")).unwrap(),
        b"beta\n"
    );
    assert!(
        out.join("tree/sub").is_dir(),
        "the directory entries must come back as directories, which is what \
         ContainerCaps::stores_dirs claims"
    );

    let _ = std::fs::remove_dir_all(&dir);
}

#[test]
fn a_corrupt_archive_exits_five_not_one() {
    let src = tmp("cli-corrupt.txt");
    let gz = tmp("cli-corrupt.txt.gz");
    let out = tmp("cli-corrupt-out.txt");
    let _ = std::fs::remove_file(&gz);
    let _ = std::fs::remove_file(&out);

    std::fs::write(&src, b"the quick brown fox ".repeat(200)).unwrap();
    assert!(
        Command::new(STUFFR)
            .args(["pack", src.to_str().unwrap(), "--format", "gzip"])
            .status()
            .unwrap()
            .success()
    );

    let mut bytes = std::fs::read(&gz).unwrap();
    let mid = bytes.len() / 2;
    bytes[mid] ^= 0xFF;
    std::fs::write(&gz, &bytes).unwrap();

    let res = Command::new(STUFFR)
        .args(["unpack", gz.to_str().unwrap(), "-o", out.to_str().unwrap()])
        .output()
        .unwrap();

    assert_eq!(
        res.status.code(),
        Some(5),
        "a corrupt archive must be distinguishable from a full disk"
    );

    let _ = std::fs::remove_file(&src);
    let _ = std::fs::remove_file(&gz);
}

#[test]
fn unpack_accepts_an_explicit_format() {
    // Detection would find gzip here anyway; the point is that the flag is
    // accepted and honoured, so the codecs that CANNOT be detected have a way in.
    let src = tmp("fmt-unpack.txt");
    let gz = tmp("fmt-unpack.txt.gz");
    let out = tmp("fmt-unpack-out.txt");
    let _ = std::fs::remove_file(&gz);
    let _ = std::fs::remove_file(&out);
    std::fs::write(&src, b"payload").unwrap();
    assert!(
        Command::new(STUFFR)
            .args(["pack", src.to_str().unwrap(), "--format", "gzip"])
            .status()
            .unwrap()
            .success()
    );

    let res = Command::new(STUFFR)
        .args([
            "unpack",
            gz.to_str().unwrap(),
            "--format",
            "gzip",
            "-o",
            out.to_str().unwrap(),
        ])
        .output()
        .unwrap();
    assert!(
        res.status.success(),
        "stderr: {}",
        String::from_utf8_lossy(&res.stderr)
    );
    assert_eq!(std::fs::read(&out).unwrap(), b"payload");

    for p in [&src, &gz, &out] {
        let _ = std::fs::remove_file(p);
    }
}

#[test]
fn cat_accepts_an_explicit_format() {
    let src = tmp("fmt-cat.txt");
    let gz = tmp("fmt-cat.txt.gz");
    let _ = std::fs::remove_file(&gz);
    std::fs::write(&src, b"payload").unwrap();
    assert!(
        Command::new(STUFFR)
            .args(["pack", src.to_str().unwrap(), "--format", "gzip"])
            .status()
            .unwrap()
            .success()
    );

    let res = Command::new(STUFFR)
        .args(["cat", gz.to_str().unwrap(), "--format", "gzip"])
        .output()
        .unwrap();
    assert!(
        res.status.success(),
        "stderr: {}",
        String::from_utf8_lossy(&res.stderr)
    );
    assert_eq!(res.stdout, b"payload");

    let _ = std::fs::remove_file(&src);
    let _ = std::fs::remove_file(&gz);
}

#[test]
fn pack_with_no_flags_defaults_to_gzip() {
    // Now that this build registers three codecs, a bare `pack src` with
    // neither -o nor --format goes through choose_format's fallback to
    // default_format_in with no extension to infer from at all. This is
    // the path 14 other tests used to exercise incidentally before they
    // were pinned to --format gzip explicitly; this test is the one that
    // exists specifically to cover it, and would fail with the ambiguity
    // usage error ("cannot infer the output format") if default_format_in
    // did not prefer gzip when it is registered alongside other codecs.
    let src = tmp("bare-default.txt");
    let gz = tmp("bare-default.txt.gz");
    let _ = std::fs::remove_file(&gz);
    std::fs::write(&src, b"payload").unwrap();

    let out = Command::new(STUFFR)
        .args(["pack", src.to_str().unwrap()])
        .output()
        .unwrap();
    assert!(
        out.status.success(),
        "stderr: {}",
        String::from_utf8_lossy(&out.stderr)
    );
    assert!(
        gz.exists(),
        "a bare pack with no --format must default to gzip and write {}.gz",
        src.display()
    );

    let _ = std::fs::remove_file(&src);
    let _ = std::fs::remove_file(&gz);
}

#[test]
fn unpack_format_flag_is_honoured_not_merely_accepted() {
    // Raw deflate is the format that can actually prove this: it has no
    // magic and no conventional extension (see deflate::meta), so it is
    // undetectable by construction. gzip cannot make this distinction —
    // it is detectable from its magic regardless of whether --format was
    // read — which is exactly how Task 1's review found all four of its
    // --format tests still green after the resolved format was dropped on
    // the floor in main.rs. This test packs with --format deflate into a
    // name carrying no hint of the format, then requires unpack to FAIL
    // without --format (detection has nothing to go on) and to SUCCEED
    // with it, recovering the original bytes exactly.
    let src = tmp("fmt-deflate.txt");
    let packed = tmp("fmt-deflate.dat");
    let out = tmp("fmt-deflate-out.txt");
    for p in [&packed, &out] {
        let _ = std::fs::remove_file(p);
    }
    let payload = b"the quick brown fox jumps over the lazy dog".repeat(50);
    std::fs::write(&src, &payload).unwrap();

    assert!(
        Command::new(STUFFR)
            .args([
                "pack",
                src.to_str().unwrap(),
                "--format",
                "deflate",
                "-o",
                packed.to_str().unwrap(),
            ])
            .status()
            .unwrap()
            .success()
    );

    let no_format = Command::new(STUFFR)
        .args([
            "unpack",
            packed.to_str().unwrap(),
            "-o",
            out.to_str().unwrap(),
            "--force",
        ])
        .output()
        .unwrap();
    assert!(
        !no_format.status.success(),
        "a raw deflate stream must NOT be detectable without --format"
    );

    let with_format = Command::new(STUFFR)
        .args([
            "unpack",
            packed.to_str().unwrap(),
            "--format",
            "deflate",
            "-o",
            out.to_str().unwrap(),
            "--force",
        ])
        .output()
        .unwrap();
    assert!(
        with_format.status.success(),
        "stderr: {}",
        String::from_utf8_lossy(&with_format.stderr)
    );
    assert_eq!(std::fs::read(&out).unwrap(), payload);

    for p in [&src, &packed, &out] {
        let _ = std::fs::remove_file(p);
    }
}

#[test]
fn cat_format_flag_is_honoured_not_merely_accepted() {
    // Character-for-character the gap Task 1's review found for `unpack` and
    // closed with `unpack_format_flag_is_honoured_not_merely_accepted` above
    // (raw deflate, undetectable by construction) — never mirrored for
    // `cat`. `cat_accepts_an_explicit_format` uses gzip, which detection
    // identifies anyway (its own comment admits this), so it proves
    // `format_by_name` ran, not that its result reaches `DecompressOpts`.
    // Replacing `format: fmt` with `format: None` in main.rs's `Command::Cat`
    // arm would leave that test green; this one requires it to fail without
    // --format and succeed with it, the same shape as the unpack test above.
    let src = tmp("fmt-cat-deflate.txt");
    let packed = tmp("fmt-cat-deflate.dat");
    let _ = std::fs::remove_file(&packed);
    let payload = b"the quick brown fox jumps over the lazy dog".repeat(50);
    std::fs::write(&src, &payload).unwrap();

    assert!(
        Command::new(STUFFR)
            .args([
                "pack",
                src.to_str().unwrap(),
                "--format",
                "deflate",
                "-o",
                packed.to_str().unwrap(),
            ])
            .status()
            .unwrap()
            .success()
    );

    let no_format = Command::new(STUFFR)
        .args(["cat", packed.to_str().unwrap()])
        .output()
        .unwrap();
    assert!(
        !no_format.status.success(),
        "a raw deflate stream must NOT be detectable without --format"
    );

    let with_format = Command::new(STUFFR)
        .args(["cat", packed.to_str().unwrap(), "--format", "deflate"])
        .output()
        .unwrap();
    assert!(
        with_format.status.success(),
        "stderr: {}",
        String::from_utf8_lossy(&with_format.stderr)
    );
    assert_eq!(with_format.stdout, payload);

    for p in [&src, &packed] {
        let _ = std::fs::remove_file(p);
    }
}

#[test]
fn an_unknown_format_name_is_a_usage_error_on_every_verb() {
    // pack already rejected these; unpack and cat must agree rather than
    // silently ignoring a flag the user believed they had set.
    for verb in ["unpack", "cat"] {
        let out = Command::new(STUFFR)
            .args([verb, "/dev/null", "--format", "bogus"])
            .output()
            .unwrap();
        assert_eq!(
            out.status.code(),
            Some(2),
            "{verb} --format bogus must be a usage error"
        );
        assert!(
            String::from_utf8_lossy(&out.stderr).contains("gzip"),
            "the error must name what this build does have"
        );
    }
}

#[test]
fn cat_honours_max_ratio() {
    // A bomb reaches stdout as easily as a file; cat had no way to bound it.
    let src = tmp("cat-bomb.bin");
    let gz = tmp("cat-bomb.bin.gz");
    let _ = std::fs::remove_file(&gz);
    std::fs::write(&src, vec![0u8; 2 * 1024 * 1024]).unwrap();
    assert!(
        Command::new(STUFFR)
            .args(["pack", src.to_str().unwrap(), "--format", "gzip"])
            .status()
            .unwrap()
            .success()
    );

    let out = Command::new(STUFFR)
        .args(["cat", gz.to_str().unwrap(), "--max-ratio", "100"])
        .output()
        .unwrap();
    assert_eq!(out.status.code(), Some(6), "resource limits exit 6");

    let _ = std::fs::remove_file(&src);
    let _ = std::fs::remove_file(&gz);
}

#[test]
fn formats_lists_every_registered_format() {
    let out = Command::new(STUFFR).arg("formats").output().unwrap();
    let text = String::from_utf8(out.stdout).unwrap();
    for row in stuffr::registry().matrix() {
        assert!(
            text.contains(row.id.as_str()),
            "`stuffr formats` omits {}: {text}",
            row.id
        );
    }
}

/// The WRITE/`weak` note belongs BELOW the table, after a blank line. It used
/// to sit between the column headings and the first row, which split the
/// headings from the data they label and made the table hard to scan.
///
/// Asserting only that the output `contains` the note — which is all the test
/// above does for the rows — would pass with the note back in its old place,
/// so this pins the position: every format row must come before it, and the
/// line before it must be blank.
#[test]
fn the_formats_note_sits_below_the_table_after_a_blank_line() {
    let out = Command::new(STUFFR).arg("formats").output().unwrap();
    let text = String::from_utf8(out.stdout).unwrap();
    let lines: Vec<&str> = text.lines().collect();

    let note = lines
        .iter()
        .position(|l| l.starts_with("(WRITE shows"))
        .unwrap_or_else(|| panic!("`stuffr formats` printed no WRITE note:\n{text}"));

    for row in stuffr::registry().matrix() {
        let at = lines
            .iter()
            .position(|l| l.starts_with(row.id.as_str()))
            .unwrap_or_else(|| panic!("`stuffr formats` omits {}:\n{text}", row.id));
        assert!(
            at < note,
            "{} is listed at line {at}, below the note at line {note}:\n{text}",
            row.id
        );
    }

    assert!(
        note > 0,
        "the note is the first line, so no table precedes it"
    );
    assert_eq!(
        lines[note - 1],
        "",
        "the note must be separated from the table by a blank line, got {:?}:\n{text}",
        lines[note - 1]
    );
}

#[test]
fn a_malformed_memory_limit_is_a_usage_error() {
    let src = tmp("mem-bad.txt");
    let out_path = tmp("mem-bad.gz");
    let _ = std::fs::remove_file(&out_path);
    std::fs::write(&src, b"payload").unwrap();

    let out = Command::new(STUFFR)
        .args(["pack", "--memory-limit", "512MB", "--format", "gzip", "-o"])
        .arg(&out_path)
        .arg(&src)
        .output()
        .unwrap();
    assert_eq!(out.status.code(), Some(2), "malformed size must be exit 2");
    let err = String::from_utf8_lossy(&out.stderr);
    // `err.contains("512M")` alone is not discriminating: the message echoes
    // the bad input back (`512MB`), which itself contains the substring
    // `512M`, so the assertion would pass even with the actual guidance
    // removed entirely. Same weak-assertion class `size.rs`'s
    // `malformed_input_is_an_error_naming_the_accepted_forms` was
    // strengthened against (R3) — require a form the input cannot supply.
    assert!(
        err.contains("512M") && err.contains("2G"),
        "must name the accepted forms concretely: {err}"
    );
    assert!(!out_path.exists(), "a refused pack must leave no output");

    let _ = std::fs::remove_file(&src);
    let _ = std::fs::remove_file(&out_path);
}

#[test]
fn threads_is_not_offered_on_decode_subcommands() {
    // Multi-threaded decode is out of scope, and this project refuses a flag
    // rather than accepting and ignoring it. If MT decode is ever added, this
    // test should fail and be deleted deliberately.
    for sub in ["unpack", "cat"] {
        let out = Command::new(STUFFR)
            .args([sub, "--threads", "4", "-"])
            .output()
            .unwrap();
        let err = String::from_utf8_lossy(&out.stderr);
        assert!(
            err.contains("unexpected argument") || err.contains("--threads"),
            "{sub} must reject --threads, got: {err}"
        );
    }
}

#[test]
fn the_binary_reports_its_version() {
    // `CARGO_PKG_VERSION` resolves to this crate's own version at compile
    // time, so this checks "the binary reports its own version" rather than
    // one number that goes stale at the next bump — a hardcoded literal
    // here was the fifth site a version bump had to touch, discovered only
    // when Phase 2's 0.2.0 bump made this test fail; this formulation needs
    // no manual edit at any future bump.
    let want = env!("CARGO_PKG_VERSION");
    let out = Command::new(STUFFR).arg("--version").output().unwrap();
    let s = String::from_utf8_lossy(&out.stdout);
    assert!(s.contains(want), "--version must report {want}, got: {s}");
}

// ---------------------------------------------------------------------
// `list` and `test` (Task 8): fixtures and helpers.
//
// Fixtures are built with the `tar` and `flate2` crates directly rather
// than through `stuffr pack`/a `stuffr-formats` writer — this build has no
// way to CREATE a tar archive yet (that's a later task), and using an
// independent generator means a read-side bug in `stuffr-formats::Tar`
// cannot also be hiding in the fixture that exercises it.
// ---------------------------------------------------------------------

static NEXT_DIR: AtomicU64 = AtomicU64::new(0);

/// A fresh, empty directory for one test. Real files on disk, not just
/// bytes in memory, so `list_names_every_entry_and_extracts_nothing` can
/// assert the filesystem is untouched afterwards.
///
/// Named from [`RUN_TOKEN`] rather than `{pid}-{counter}`, and the word
/// "fresh" in the sentence above is why — see that constant for the false red
/// the old name produced. `create_dir_all` is deliberately kept (rather than
/// `create_dir`, which would refuse an existing path): with a random token the
/// path cannot pre-exist, so a refusal would only ever fire on a genuine
/// filesystem fault and `create_dir_all` reports that just as loudly.
fn tmp_dir() -> PathBuf {
    let n = NEXT_DIR.fetch_add(1, Ordering::Relaxed);
    let mut p = std::env::temp_dir();
    p.push(format!("stuffr-cli-archive-{}-{n}", *RUN_TOKEN));
    std::fs::create_dir_all(&p).unwrap();
    p
}

/// Writes a GNU-format tar header for `name`/`data` into `builder`. Kept
/// separate from callers so every fixture builder below sets exactly the
/// same fields the same way.
fn append_tar_entry<W: Write>(builder: &mut Builder<W>, name: &str, data: &[u8]) {
    let mut header = Header::new_gnu();
    header.set_size(data.len() as u64);
    header.set_mode(0o644);
    // `append_data` sets the path and recomputes the checksum itself, in
    // that order — see `tar::Builder::append_data`'s own source.
    builder.append_data(&mut header, name, data).unwrap();
}

/// A real tar archive, written to `dir/fixture.tar`.
fn write_fixture_tar(dir: &Path, entries: &[(&str, &[u8])]) -> PathBuf {
    let path = dir.join("fixture.tar");
    let mut builder = Builder::new(std::fs::File::create(&path).unwrap());
    for (name, data) in entries {
        append_tar_entry(&mut builder, name, data);
    }
    builder.finish().unwrap();
    path
}

/// The same tar bytes, real-gzip-wrapped (via `flate2`) under `name` —
/// `"fixture.tar.gz"` or `"fixture.tgz"` — exercising the exact shapes
/// `resolve_chain_deep` must resolve as "tar over gzip".
fn write_fixture_tar_gz(dir: &Path, name: &str, entries: &[(&str, &[u8])]) -> PathBuf {
    let mut tar_bytes = Vec::new();
    {
        let mut builder = Builder::new(&mut tar_bytes);
        for (n, data) in entries {
            append_tar_entry(&mut builder, n, data);
        }
        builder.finish().unwrap();
    }
    let path = dir.join(name);
    let mut enc = GzEncoder::new(
        std::fs::File::create(&path).unwrap(),
        Compression::default(),
    );
    enc.write_all(&tar_bytes).unwrap();
    enc.finish().unwrap();
    path
}

/// Gzip-wraps arbitrary bytes once — used to build a nesting-depth bomb.
fn gzip_wrap(bytes: &[u8]) -> Vec<u8> {
    let mut enc = GzEncoder::new(Vec::new(), Compression::fast());
    enc.write_all(bytes).unwrap();
    enc.finish().unwrap()
}

/// Truncates `good` to half its length: a real, structural corruption (a
/// missing or partial end-of-archive marker), not a bit flip tar has no way
/// to detect at all — it carries no payload checksum.
fn corrupt_midway(good: &Path) -> PathBuf {
    let bytes = std::fs::read(good).unwrap();
    let cut = bytes.len() / 2;
    let corrupt = good.with_file_name("corrupt.tar");
    std::fs::write(&corrupt, &bytes[..cut]).unwrap();
    corrupt
}

fn run(args: &[&str]) -> std::process::ExitStatus {
    Command::new(STUFFR).args(args).status().unwrap()
}

fn run_output(args: &[&str]) -> std::process::Output {
    Command::new(STUFFR).args(args).output().unwrap()
}

fn run_with_stdin_output(args: &[&str], input: &[u8]) -> std::process::Output {
    let mut child = Command::new(STUFFR)
        .args(args)
        .stdin(Stdio::piped())
        .stdout(Stdio::piped())
        .stderr(Stdio::piped())
        .spawn()
        .unwrap();
    child.stdin.take().unwrap().write_all(input).unwrap();
    child.wait_with_output().unwrap()
}

/// The streaming premise applied to `list`/`test`: stdin, no seek.
fn run_with_stdin(args: &[&str], input: &[u8]) -> String {
    let out = run_with_stdin_output(args, input);
    String::from_utf8(out.stdout).unwrap()
}

#[test]
fn list_names_every_entry_and_extracts_nothing() {
    let dir = tmp_dir();
    let archive = write_fixture_tar(&dir, &[("a.txt", b"alpha"), ("b/c.bin", b"\x00\xff")]);
    let out = run_output(&["list", archive.to_str().unwrap()]);
    assert!(
        out.status.success(),
        "stderr: {}",
        String::from_utf8_lossy(&out.stderr)
    );
    let text = String::from_utf8(out.stdout).unwrap();
    assert!(text.contains("a.txt") && text.contains("b/c.bin"), "{text}");
    // Nothing was written to the filesystem.
    assert!(!dir.join("a.txt").exists(), "list must not extract");
    assert!(!dir.join("b").exists(), "list must not extract");

    let _ = std::fs::remove_dir_all(&dir);
}

#[test]
fn ls_is_an_alias_for_list() {
    let dir = tmp_dir();
    let archive = write_fixture_tar(&dir, &[("a.txt", b"alpha")]);
    let out = run_output(&["ls", archive.to_str().unwrap()]);
    assert!(
        out.status.success(),
        "stderr: {}",
        String::from_utf8_lossy(&out.stderr)
    );
    assert!(String::from_utf8(out.stdout).unwrap().contains("a.txt"));

    let _ = std::fs::remove_dir_all(&dir);
}

#[test]
fn list_json_reports_name_kind_and_size() {
    let dir = tmp_dir();
    let archive = write_fixture_tar(&dir, &[("a.txt", b"alpha")]);
    let out = run_output(&["list", "--json", archive.to_str().unwrap()]);
    assert!(
        out.status.success(),
        "stderr: {}",
        String::from_utf8_lossy(&out.stderr)
    );
    let text = String::from_utf8(out.stdout).unwrap();
    let v: serde_json::Value =
        serde_json::from_str(&text).unwrap_or_else(|e| panic!("not JSON: {e}\n{text}"));
    let rows = v.as_array().expect("a JSON array of entries");
    assert_eq!(rows.len(), 1);
    assert_eq!(rows[0]["name"], "a.txt");
    assert_eq!(rows[0]["kind"], "file");
    assert_eq!(rows[0]["size"], 5);

    let _ = std::fs::remove_dir_all(&dir);
}

#[test]
fn test_verb_exits_five_on_a_corrupt_archive_and_zero_on_a_good_one() {
    let dir = tmp_dir();
    let good = write_fixture_tar(&dir, &[("a.txt", b"alpha")]);
    assert_eq!(run(&["test", good.to_str().unwrap()]).code(), Some(0));
    let bad = corrupt_midway(&good);
    assert_eq!(run(&["test", bad.to_str().unwrap()]).code(), Some(5));

    let _ = std::fs::remove_dir_all(&dir);
}

#[test]
fn list_works_on_a_pipe() {
    // The streaming premise applied to the new verb.
    let dir = tmp_dir();
    let bytes = std::fs::read(write_fixture_tar(&dir, &[("a.txt", b"alpha")])).unwrap();
    let text = run_with_stdin(&["list", "-"], &bytes);
    assert!(text.contains("a.txt"), "{text}");

    let _ = std::fs::remove_dir_all(&dir);
}

/// The forward risk flagged for this task: `open_archive` must not decode a
/// `.tar.gz`/`.tgz` layer twice, and `probe`'s peeking must not consume
/// bytes it doesn't replay — either bug reports every real `.tar.gz` as
/// "not a whole number of 512-byte blocks; the archive is truncated", which
/// looks exactly like corruption and is not. Verified here with a REAL
/// gzip (`flate2`) wrapping a REAL tar (`tar`), independent of
/// `stuffr-formats`' own writers, on a file AND on a pipe, for both
/// `.tar.gz` and `.tgz`.
#[test]
fn list_and_test_succeed_on_a_real_tar_gz_from_a_file() {
    let dir = tmp_dir();
    let archive = write_fixture_tar_gz(
        &dir,
        "fixture.tar.gz",
        &[("a.txt", b"alpha"), ("b/c.bin", b"\x00\xff")],
    );

    let list_out = run_output(&["list", archive.to_str().unwrap()]);
    assert!(
        list_out.status.success(),
        "list stderr: {}",
        String::from_utf8_lossy(&list_out.stderr)
    );
    let text = String::from_utf8(list_out.stdout).unwrap();
    assert!(text.contains("a.txt") && text.contains("b/c.bin"), "{text}");

    let test_out = run_output(&["test", archive.to_str().unwrap()]);
    assert!(
        test_out.status.success(),
        "test stderr: {}",
        String::from_utf8_lossy(&test_out.stderr)
    );

    let _ = std::fs::remove_dir_all(&dir);
}

#[test]
fn list_and_test_succeed_on_a_real_tar_gz_over_a_pipe() {
    let dir = tmp_dir();
    let archive = write_fixture_tar_gz(&dir, "fixture.tar.gz", &[("a.txt", b"alpha")]);
    let bytes = std::fs::read(&archive).unwrap();

    let list_out = run_with_stdin_output(&["list", "-"], &bytes);
    assert!(
        list_out.status.success(),
        "list stderr: {}",
        String::from_utf8_lossy(&list_out.stderr)
    );
    assert!(
        String::from_utf8(list_out.stdout)
            .unwrap()
            .contains("a.txt")
    );

    let test_out = run_with_stdin_output(&["test", "-"], &bytes);
    assert!(
        test_out.status.success(),
        "test stderr: {}",
        String::from_utf8_lossy(&test_out.stderr)
    );

    let _ = std::fs::remove_dir_all(&dir);
}

#[test]
fn list_and_test_succeed_on_a_real_tgz_from_a_file() {
    let dir = tmp_dir();
    let archive = write_fixture_tar_gz(&dir, "fixture.tgz", &[("a.txt", b"alpha")]);

    let list_out = run_output(&["list", archive.to_str().unwrap()]);
    assert!(
        list_out.status.success(),
        "list stderr: {}",
        String::from_utf8_lossy(&list_out.stderr)
    );
    assert!(
        String::from_utf8(list_out.stdout)
            .unwrap()
            .contains("a.txt")
    );

    let test_out = run_output(&["test", archive.to_str().unwrap()]);
    assert!(
        test_out.status.success(),
        "test stderr: {}",
        String::from_utf8_lossy(&test_out.stderr)
    );

    let _ = std::fs::remove_dir_all(&dir);
}

#[test]
fn list_and_test_succeed_on_a_real_tgz_over_a_pipe() {
    let dir = tmp_dir();
    let archive = write_fixture_tar_gz(&dir, "fixture.tgz", &[("a.txt", b"alpha")]);
    let bytes = std::fs::read(&archive).unwrap();

    let list_out = run_with_stdin_output(&["list", "-"], &bytes);
    assert!(
        list_out.status.success(),
        "list stderr: {}",
        String::from_utf8_lossy(&list_out.stderr)
    );
    assert!(
        String::from_utf8(list_out.stdout)
            .unwrap()
            .contains("a.txt")
    );

    let test_out = run_with_stdin_output(&["test", "-"], &bytes);
    assert!(
        test_out.status.success(),
        "test stderr: {}",
        String::from_utf8_lossy(&test_out.stderr)
    );

    let _ = std::fs::remove_dir_all(&dir);
}

/// A truncation strictly INSIDE a single entry's declared payload, well
/// short of where any end-of-archive marker begins — the case `test`'s own
/// explicit payload read (`entries.rs::test`) is designed to catch, via
/// `Error::from_decode_io` reclassifying the raw `io::ErrorKind::InvalidData`
/// tar's `EntryPayload::read` raises when delivered bytes fall short of the
/// header's declared size (see that message below) — a bare `?` there would
/// have surfaced as exit 1, not exit 5.
///
/// `list` (which never reads a payload) turns out to ALSO exit 5 here, but
/// via a wholly different path and message: walking headers to completion
/// forces the underlying `tar` crate to skip past this entry's unread
/// payload before it can look for the next header, and that skip itself
/// reports "unexpected EOF during skip". So the two verbs converge on the
/// same outcome for tar's length-based corruption specifically — this test
/// pins BOTH messages so a future change that silently drops either
/// detection path is caught, without claiming `list` succeeds where it does
/// not.
#[test]
fn test_catches_a_payload_truncation() {
    let dir = tmp_dir();
    let payload = vec![b'x'; 8192];
    let full = write_fixture_tar(&dir, &[("big.bin", &payload)]);
    let bytes = std::fs::read(&full).unwrap();
    // One 512-byte header block, then a third of the way into the payload.
    let cut = 512 + payload.len() / 3;
    let truncated = dir.join("truncated.tar");
    std::fs::write(&truncated, &bytes[..cut]).unwrap();

    let test_out = run_output(&["test", truncated.to_str().unwrap()]);
    assert_eq!(
        test_out.status.code(),
        Some(5),
        "test reads the payload and must catch the truncation: {}",
        String::from_utf8_lossy(&test_out.stderr)
    );
    let test_err = String::from_utf8_lossy(&test_out.stderr);
    assert!(
        test_err.contains("big.bin") && test_err.contains("short of the size"),
        "must be tar's own per-entry short-read diagnosis, reclassified from a raw \
         io::ErrorKind::InvalidData via Error::from_decode_io: {test_err}"
    );

    let list_out = run_output(&["list", truncated.to_str().unwrap()]);
    assert_eq!(
        list_out.status.code(),
        Some(5),
        "list also exits 5 here, via the tar crate's own header-skip detection, not via a \
         payload read: {}",
        String::from_utf8_lossy(&list_out.stderr)
    );

    let _ = std::fs::remove_dir_all(&dir);
}

/// The `container` fuzz target's own reproducer, minimised by `cargo fuzz
/// tmin` from the 6,779-byte artefact to the 540 bytes below, asserted at
/// the CLI because that is where the defect was user-visible.
///
/// **What it was:** `stuffr list`, `stuffr test` and `stuffr unpack` all
/// exited **1** — `stuffr: i/o error: Invalid argument (os error 22)` —
/// which in this project means *stuffr itself failed*. The oracle's own
/// words were `next_entry error classification: "a decoder raised Io(Os {
/// code: 22, kind: InvalidInput, message: \"Invalid argument\" }), which
/// maps to exit code 1"`.
///
/// **Why:** a zip64 extended-information extra field (tag `0x0001`) in the
/// central directory supplies an 8-byte relative local-header offset, and
/// `zip-8.6.0` hands it straight to `Seek::seek(SeekFrom::Start(..))`. On
/// unix `std` casts that `u64` to `off_t`, an `i64`, so anything above
/// `i64::MAX` reaches `lseek(2)` NEGATIVE and the kernel answers `EINVAL` —
/// a genuine errno that `Error::from_decode_io` does not fold.
///
/// The refusal now comes from `stuffr_core::source::GuardedSeek`, one layer
/// below every container, so this is a class fix and not a zip patch. Exit 5
/// rather than 6 by `error.rs`'s `exit_code` rule: nothing was allocated
/// from the offset, and what is wrong is the file's agreement with itself.
///
/// The assertion is on the CLASSIFIED outcome, not merely on "not 1": a
/// guard that turned one wrong answer into another would pass that.
#[test]
fn a_zip_declaring_an_unreachable_local_header_offset_exits_5_not_1() {
    // Hex rather than a checked-in binary: 540 bytes of fuzzer output has no
    // provenance a `fixtures/MANIFEST.md` entry could usefully describe, and
    // inline bytes cannot drift away from the test that stands on them.
    const MINIMISED_REPRODUCER: &str = concat!(
        "4b4d4d00504b010214031400000000000a3b375d0000000000000000000001010101e900000000000000237718c33a17",
        "fbe047df010101010101010166722066757a7a7403034b50ffff1304504b05060000000001000008f500040000000000",
        "000000000000005da481a9000007054b5000000a3b375dbc6ab89d2a00000000000000000b00000000000000000000a4",
        "81250000bf5907054b5047bbd19819f9938fb5527f0414d3000000000a3b375d000000000010000000004f0102141403",
        "1400000008000a3b375d06ff880a7374756666722066757a7a7403034b50ffff1304504b05060000000001000008f500",
        "0000ed000000000000000000005da481a900000081a90000001400000008000a3b375d06ff880a737475666672206675",
        "7a7a7403034b50ffff1304504b05060000000001000008f5000000ed000000000000000000005da481a900000081a900",
        "0000000000ed000000000000000000005da481a900000081a9000000a481a900000081a900000008000a3b375d06ff88",
        "0a7374756666722066757a7a7403034b50ffff1304504b05060000000001000008005da481a900000081000000000000",
        "5da481a900000081a9000000000000ed000000000000000000005da481a900000081a9000000a481a900000081a90000",
        "00000000000000000000005da481a900000081a9000000000000ed000000000000000000005da481a900000081a90000",
        "00a481a900000081a9000000",
    );

    let bytes: Vec<u8> = (0..MINIMISED_REPRODUCER.len() / 2)
        .map(|i| u8::from_str_radix(&MINIMISED_REPRODUCER[i * 2..i * 2 + 2], 16).unwrap())
        .collect();
    assert_eq!(bytes.len(), 540, "the reproducer must be carried verbatim");

    let dir = tmp_dir();
    let archive = dir.join("unreachable-offset.zip");
    std::fs::write(&archive, &bytes).unwrap();

    for verb in ["list", "test"] {
        let out = run_output(&[verb, archive.to_str().unwrap()]);
        let err = String::from_utf8_lossy(&out.stderr);
        assert_eq!(
            out.status.code(),
            Some(5),
            "`{verb}` must report the ARCHIVE as corrupt, never exit 1: {err}"
        );
        assert!(
            err.contains("archive is corrupt")
                && err.contains("largest position any file can hold"),
            "the refusal must name what the archive declared, not an errno: {err}"
        );
        assert!(
            !err.contains("os error 22"),
            "a bare errno reaching the user is the defect itself: {err}"
        );
    }

    let out = run_output(&[
        "unpack",
        "-C",
        dir.join("out").to_str().unwrap(),
        archive.to_str().unwrap(),
    ]);
    assert_eq!(
        out.status.code(),
        Some(5),
        "`unpack` too: {}",
        String::from_utf8_lossy(&out.stderr)
    );

    let _ = std::fs::remove_dir_all(&dir);
}

#[test]
fn list_refuses_a_plain_codec_stream_as_not_an_archive() {
    let dir = tmp_dir();
    let src = dir.join("notes.txt");
    let gz = dir.join("notes.txt.gz");
    std::fs::write(&src, b"just plain text, not an archive").unwrap();
    assert!(
        Command::new(STUFFR)
            .args(["pack", src.to_str().unwrap(), "--format", "gzip"])
            .status()
            .unwrap()
            .success()
    );

    let out = run_output(&["list", gz.to_str().unwrap()]);
    assert_eq!(
        out.status.code(),
        Some(2),
        "stderr: {}",
        String::from_utf8_lossy(&out.stderr)
    );
    let err = String::from_utf8_lossy(&out.stderr);
    assert!(err.contains("not an archive"), "{err}");
    assert!(
        err.contains("gzip"),
        "must name what the input actually resolved to: {err}"
    );

    let _ = std::fs::remove_dir_all(&dir);
}

#[test]
fn list_refuses_nesting_past_the_depth_bound() {
    let mut bytes = b"payload too shallow to be an archive".to_vec();
    // MAX_CHAIN_DEPTH is 4; six gzip layers is comfortably past it.
    for _ in 0..6 {
        bytes = gzip_wrap(&bytes);
    }
    let out = run_with_stdin_output(&["list", "-"], &bytes);
    assert_eq!(
        out.status.code(),
        Some(6),
        "stderr: {}",
        String::from_utf8_lossy(&out.stderr)
    );
    let err = String::from_utf8_lossy(&out.stderr);
    assert!(err.contains("nesting"), "{err}");
}

/// Task 4b (Phase 3a's fuzzing harness found this within seconds of the
/// `chain` target running). A truncated zlib stream with no container atop
/// it: `resolve_chain_deep_with` cannot resolve a container from the path
/// (`.zz` names nothing) or from the decoded bytes (there aren't enough of
/// them), so it falls into the peek-the-decoded-stream loop in
/// `probe.rs::resolve_chain_deep_with`, which used to hand the raw
/// `io::ErrorKind::InvalidData` `probe(decoded)` raised straight through a
/// bare `?` — `Error::Io`, exit 1, "stuffr failed" — for bytes that are
/// simply corrupt. `cat` (via `ops::decompress`, which already routes its
/// decode read through `Error::from_decode_io`) always got this right; the
/// two verbs disagreeing on the exit code for the identical bytes is the
/// bug.
#[test]
fn list_reports_a_truncated_codec_stream_as_corrupt_not_as_an_io_failure() {
    let dir = tmp_dir();
    let trunc = dir.join("trunc.zz");
    // A valid zlib header (`78 da`) plus one more byte, then nothing —
    // enough to identify the format, not enough to decode a single byte of
    // payload.
    std::fs::write(&trunc, [0x78, 0xda, 0x0a]).unwrap();

    let cat_out = run_output(&["cat", trunc.to_str().unwrap()]);
    assert_eq!(
        cat_out.status.code(),
        Some(5),
        "cat (unaffected by this bug) must still exit 5: {}",
        String::from_utf8_lossy(&cat_out.stderr)
    );

    let list_out = run_output(&["list", trunc.to_str().unwrap()]);
    assert_eq!(
        list_out.status.code(),
        Some(5),
        "list must agree with cat on the SAME bytes — exit 1 here means stuffr claimed it \
         failed, when the truth is the input is corrupt: {}",
        String::from_utf8_lossy(&list_out.stderr)
    );
    let list_err = String::from_utf8_lossy(&list_out.stderr);
    assert!(
        list_err.contains("archive is corrupt"),
        "must be Error::Corrupt's own wording, not Error::Io's: {list_err}"
    );

    let _ = std::fs::remove_dir_all(&dir);
}

/// The second shape Task 4b's fuzzing found: an EMPTY file named `.lz`.
/// `lzip`'s decoder does not check the magic until its first `read`, so this
/// hits the identical `probe(decoded)` site as the truncated-zlib case
/// above, by a different route — an empty stream rather than a short one.
#[test]
fn list_reports_an_empty_lzip_stream_as_corrupt_not_as_an_io_failure() {
    let dir = tmp_dir();
    let empty = dir.join("empty.lz");
    std::fs::write(&empty, []).unwrap();

    let cat_out = run_output(&["cat", empty.to_str().unwrap()]);
    assert_eq!(
        cat_out.status.code(),
        Some(5),
        "cat (unaffected by this bug) must still exit 5: {}",
        String::from_utf8_lossy(&cat_out.stderr)
    );

    let list_out = run_output(&["list", empty.to_str().unwrap()]);
    assert_eq!(
        list_out.status.code(),
        Some(5),
        "list must agree with cat on the SAME bytes: {}",
        String::from_utf8_lossy(&list_out.stderr)
    );
    let list_err = String::from_utf8_lossy(&list_out.stderr);
    assert!(
        list_err.contains("archive is corrupt") && list_err.contains("LZIP"),
        "must be Error::Corrupt's own wording, naming what lzip's decoder actually \
         complained about: {list_err}"
    );

    let _ = std::fs::remove_dir_all(&dir);
}

/// The hazard side of Task 4b's fix: a genuine i/o failure reading the RAW
/// source (never reaching a decoder at all) must stay `Error::Io` — exit 1
/// — and must NOT be swept into `Error::Corrupt` by a fix that reclassifies
/// too broadly. Opening a directory as if it were a file is a real,
/// deterministic i/o failure that arises before any codec sees a single
/// byte: `resolve_chain_deep_with`'s OWN top-level `probe(src)` call reads
/// the raw source.
///
/// This does NOT prove that widening `Error::from_decode_io` to that
/// top-level `probe(src)` call (or into `probe`/`PeekSource::fill`
/// themselves, rather than scoping it to the decoded-stream `probe` call
/// inside the re-probe loop) would be safe — checked, and it is a narrower
/// guard than that. `from_decode_io` only reclassifies `InvalidData` and
/// `OutOfMemory`; a directory read raises `std::io::ErrorKind::IsADirectory`,
/// neither of those, so it comes back `Error::Io` — exit 1 — whether or not
/// that call is widened, and this test cannot tell the two cases apart. What
/// it DOES catch is a cruder fix: one that swept every raw-source
/// `io::Error` into `Error::Corrupt` regardless of kind. The widening claim
/// itself is proven in `probe.rs`'s own
/// `a_raw_source_io_error_of_the_identical_kind_stays_io_not_corrupt`, which
/// deliberately uses an `InvalidData`-kind raw-source error — the one kind
/// `from_decode_io` actually reclassifies — and would flip to `Corrupt` if
/// that call site were widened.
#[test]
fn list_reports_a_directory_as_an_io_failure_not_as_corrupt() {
    let dir = tmp_dir();
    let sub = dir.join("not_a_file");
    std::fs::create_dir_all(&sub).unwrap();

    let out = run_output(&["list", sub.to_str().unwrap()]);
    assert_eq!(
        out.status.code(),
        Some(1),
        "a genuine i/o failure on the raw source must stay exit 1, not become exit 5: {}",
        String::from_utf8_lossy(&out.stderr)
    );
    let err = String::from_utf8_lossy(&out.stderr);
    assert!(
        err.starts_with("stuffr: i/o error:"),
        "must be Error::Io's own wording, not Error::Corrupt's \"archive is corrupt\": {err}"
    );
    assert!(
        !err.contains("archive is corrupt"),
        "must not have been reclassified as corrupt: {err}"
    );

    let _ = std::fs::remove_dir_all(&dir);
}

/// The 21 bytes the `chain` fuzz target's honesty oracle caught after the
/// previous exit-1 defect in this series was fixed. A zstd frame whose
/// DECODED bytes open with ARJ's `60 EA` magic, then run on for about a
/// kilobyte before the frame's second block fails to parse.
///
/// Its route is the one Task 4b's fix does not cover, and cannot: the good
/// prefix satisfies `resolve_chain_deep_with`'s re-probe window completely,
/// so the `probe(decoded)` call Task 4b classified never sees a failure at
/// all. The chain resolves cleanly to `arj` over `zstd`, ARJ declares
/// `needs_seek`, a decoder's output is never seekable — so the ladder takes
/// rung 3 and `SpillSource::materialize` drains the decoded stream into a
/// spool. That drain read through a bare `?`.
///
/// Measured before the fix, on the `0.5.0` binary:
///
/// ```text
/// stuffr list -> exit 1 :: stuffr: i/o error: Failed to parse/decode block body: ...
/// stuffr test -> exit 1 :: same
/// stuffr cat  -> exit 5 :: stuffr: archive is corrupt: ...
/// ```
///
/// Exit 5 and not 6, per `Error::exit_code`'s own rule: stuffr read the bytes
/// and they contradict each other, and no allocation was ever in question.
///
/// The bytes are embedded rather than generated because generating them means
/// encoding zstd, which the default (pure) tier will not do without
/// `--allow-weak-encoder` — and because a reproducer that is recomputed is a
/// reproducer that can quietly stop reproducing.
#[test]
fn list_reports_a_zstd_stream_that_decodes_into_arj_magic_as_corrupt() {
    const ZSTD_OVER_ARJ_MAGIC: &[u8] = &[
        0x28, 0xb5, 0x2f, 0xfd, 0x24, 0x00, 0x30, 0x00, 0x00, 0x60, 0xea, 0x05, 0x06, 0x28, 0x0a,
        0x0a, 0x0a, 0x0a, 0x0a, 0x70, 0x00,
    ];

    let dir = tmp_dir();
    let repro = dir.join("repro.zst");
    std::fs::write(&repro, ZSTD_OVER_ARJ_MAGIC).unwrap();
    let path = repro.to_str().unwrap();

    let cat_out = run_output(&["cat", path]);
    assert_eq!(
        cat_out.status.code(),
        Some(5),
        "cat was already right on these bytes and must stay right: {}",
        String::from_utf8_lossy(&cat_out.stderr)
    );

    for verb in ["list", "test"] {
        let out = run_output(&[verb, path]);
        assert_eq!(
            out.status.code(),
            Some(5),
            "`{verb}` must agree with cat on the SAME bytes — exit 1 here means stuffr claimed \
             it failed, when the truth is the input is corrupt: {}",
            String::from_utf8_lossy(&out.stderr)
        );
        let err = String::from_utf8_lossy(&out.stderr);
        assert!(
            err.contains("archive is corrupt"),
            "must be Error::Corrupt's own wording, not Error::Io's: {err}"
        );
    }

    let _ = std::fs::remove_dir_all(&dir);
}

/// The second shape the same enumeration turned up, and one no fuzz target
/// found: a `--max-ratio` refusal below a container.
///
/// 60 bytes of zstd expanding to 1 MiB of zeros behind ARJ's `60 EA` magic.
/// `RatioGuardedSource` raises `io::ErrorKind::OutOfMemory` specifically so
/// the classification maps it to `Error::ResourceLimit`, exit 6 — and below a
/// container that conversion never ran, because the refusal met
/// `SpillSource::materialize`'s bare `?` instead. Measured before the fix:
///
/// ```text
/// stuffr list -> exit 1 :: stuffr: i/o error: expansion ratio 17476:1 exceeds the 10000:1 limit
/// stuffr cat  -> exit 6 :: stuffr: resource limit exceeded: <same figures>
/// ```
///
/// Exit 6 and not 5, the other side of `Error::exit_code`'s rule: a LIMIT
/// decided the outcome, nothing was read that contradicts anything, and
/// `--max-ratio` names the knob that changes the answer.
///
/// It fires under the DEFAULT ratio, so no flag is passed — the bomb is real,
/// not a tightened bound arranged to trip.
#[test]
fn a_ratio_refusal_below_a_container_is_a_resource_limit_not_an_io_failure() {
    const ZSTD_BOMB_OVER_ARJ_MAGIC: &[u8] = &[
        0x28, 0xb5, 0x2f, 0xfd, 0xa4, 0x02, 0x00, 0x10, 0x00, 0x5c, 0x00, 0x00, 0x18, 0x60, 0xea,
        0x00, 0x01, 0x00, 0xfa, 0xff, 0x39, 0x18, 0x02, 0x02, 0x00, 0x10, 0x00, 0x02, 0x00, 0x10,
        0x00, 0x02, 0x00, 0x10, 0x00, 0x02, 0x00, 0x10, 0x00, 0x02, 0x00, 0x10, 0x00, 0x02, 0x00,
        0x10, 0x00, 0x02, 0x00, 0x10, 0x00, 0x11, 0x00, 0x00, 0x00, 0x00, 0xbe, 0xb2, 0xa6, 0x83,
    ];

    let dir = tmp_dir();
    let bomb = dir.join("bomb.zst");
    std::fs::write(&bomb, ZSTD_BOMB_OVER_ARJ_MAGIC).unwrap();
    let path = bomb.to_str().unwrap();

    let cat_out = run_output(&["cat", path]);
    assert_eq!(
        cat_out.status.code(),
        Some(6),
        "cat was already right and must stay right: {}",
        String::from_utf8_lossy(&cat_out.stderr)
    );

    for verb in ["list", "test"] {
        let out = run_output(&[verb, path]);
        assert_eq!(
            out.status.code(),
            Some(6),
            "`{verb}` must agree with cat: a refused expansion bomb is a limit, never \
             \"stuffr failed\": {}",
            String::from_utf8_lossy(&out.stderr)
        );
        let err = String::from_utf8_lossy(&out.stderr);
        assert!(
            err.contains("resource limit exceeded") && err.contains("--max-ratio"),
            "must be Error::ResourceLimit's own wording, naming the knob: {err}"
        );
    }

    let _ = std::fs::remove_dir_all(&dir);
}

// ---------------------------------------------------------------------
// `--max-ratio` on `list`/`test`: the codec layer beneath a container is
// bounded the same way `unpack`/`cat` already bound a bare codec stream.
//
// A single gzip member cannot itself reach the 10_000:1 default — its own
// structural ceiling on all-zero input is roughly 1024:1 (measured below,
// and documented on `examples.txt`'s "GUARDING AGAINST DECOMPRESSION
// BOMBS" section for the plain-codec case). `a_bomb_exits_six_and_leaves_
// no_partial_output` above hits this identical ceiling on the codec path
// and works around it with an explicit, tighter `--max-ratio`; these tests
// follow the same convention rather than inventing a new one.
// ---------------------------------------------------------------------

/// A small `.tar.gz` whose single all-zero entry gzip crushes hard — real
/// enough to measure, not assumed. Same 2 MiB size `a_bomb_exits_six_and_
/// leaves_no_partial_output` uses for the bare-codec case.
fn write_bomb_tar_gz(dir: &Path) -> PathBuf {
    write_fixture_tar_gz(
        dir,
        "bomb.tar.gz",
        &[("bomb.bin", &vec![0u8; 2 * 1024 * 1024])],
    )
}

#[test]
fn list_and_test_refuse_a_bomb_tar_gz_at_a_tight_max_ratio() {
    let dir = tmp_dir();
    let bomb = write_bomb_tar_gz(&dir);
    // Real measured ratio is roughly 1000:1 (2 MiB in, ~2 KiB of gzip out);
    // 100 is comfortably below that, exactly as the existing codec-path
    // bomb test uses for the identical reason.
    let list_out = run_output(&["list", bomb.to_str().unwrap(), "--max-ratio", "100"]);
    assert_eq!(
        list_out.status.code(),
        Some(6),
        "list stderr: {}",
        String::from_utf8_lossy(&list_out.stderr)
    );
    let list_err = String::from_utf8_lossy(&list_out.stderr);
    assert!(
        list_err.contains("100") && list_err.contains("--max-ratio"),
        "must name the limit and the flag, matching how decompress reports it: {list_err}"
    );

    let test_out = run_output(&["test", bomb.to_str().unwrap(), "--max-ratio", "100"]);
    assert_eq!(
        test_out.status.code(),
        Some(6),
        "test stderr: {}",
        String::from_utf8_lossy(&test_out.stderr)
    );
    let test_err = String::from_utf8_lossy(&test_out.stderr);
    assert!(
        test_err.contains("100") && test_err.contains("--max-ratio"),
        "must name the limit and the flag: {test_err}"
    );

    let _ = std::fs::remove_dir_all(&dir);
}

#[test]
fn raising_max_ratio_lets_the_bomb_through() {
    // Proves the flag is wired, not merely accepted and ignored: the exact
    // same archive `list_and_test_refuse_a_bomb_tar_gz_at_a_tight_max_ratio`
    // refuses at 100 must succeed once the limit is raised past its real
    // (roughly 1000:1) ratio.
    let dir = tmp_dir();
    let bomb = write_bomb_tar_gz(&dir);

    let list_out = run_output(&["list", bomb.to_str().unwrap(), "--max-ratio", "100000"]);
    assert!(
        list_out.status.success(),
        "list stderr: {}",
        String::from_utf8_lossy(&list_out.stderr)
    );

    let test_out = run_output(&["test", bomb.to_str().unwrap(), "--max-ratio", "100000"]);
    assert!(
        test_out.status.success(),
        "test stderr: {}",
        String::from_utf8_lossy(&test_out.stderr)
    );

    let _ = std::fs::remove_dir_all(&dir);
}

/// The false-positive trap the guard must NOT fall into: a real, sizeable
/// (not trivially tiny) archive that gzip legitimately crushes hard must
/// pass at the UNCHANGED default ratio — no `--max-ratio` given at all.
#[test]
fn a_legitimately_compressible_tar_gz_is_not_refused_at_the_default_ratio() {
    let dir = tmp_dir();
    let text = "the quick brown fox jumps over the lazy dog\n".repeat(200_000);
    let archive = write_fixture_tar_gz(&dir, "legit.tar.gz", &[("log.txt", text.as_bytes())]);

    let list_out = run_output(&["list", archive.to_str().unwrap()]);
    assert!(
        list_out.status.success(),
        "a legitimately compressible archive must not be refused at the default ratio: {}",
        String::from_utf8_lossy(&list_out.stderr)
    );
    assert!(
        String::from_utf8(list_out.stdout)
            .unwrap()
            .contains("log.txt")
    );

    let test_out = run_output(&["test", archive.to_str().unwrap()]);
    assert!(
        test_out.status.success(),
        "a legitimately compressible archive must not be refused at the default ratio: {}",
        String::from_utf8_lossy(&test_out.stderr)
    );

    let _ = std::fs::remove_dir_all(&dir);
}

// ---------------------------------------------------------------------
// Entry-aware pack/unpack/cat.
//
// The hostile fixtures below are written with the RAW `tar` crate, bypassing
// `Header::set_path` (which refuses `..` and absolute names outright), so
// they carry names stuffr itself would never produce. That is the point:
// containment has to refuse an archive somebody else wrote.
// ---------------------------------------------------------------------

/// The mtime every raw fixture entry carries, so a test can assert that
/// extraction put it back rather than that it happens to be "recent".
const FIXTURE_MTIME: u64 = 1_600_000_000;

/// A tar entry whose name is written straight into the 100-byte header field,
/// bypassing every validation `Builder::append_data`/`Header::set_path` would
/// apply. `write_fixture_tar` cannot express these names at all.
fn raw_header(
    name: &str,
    kind: tar::EntryType,
    link_target: Option<&str>,
    size: u64,
    mode: u32,
) -> Header {
    let mut header = Header::new_gnu();
    header.set_size(size);
    header.set_mode(mode);
    header.set_mtime(FIXTURE_MTIME);
    header.set_entry_type(kind);
    {
        let gnu = header.as_gnu_mut().expect("new_gnu is a GNU header");
        let bytes = name.as_bytes();
        assert!(
            bytes.len() <= gnu.name.len(),
            "raw fixture names must fit tar's 100-byte name field"
        );
        gnu.name[..bytes.len()].copy_from_slice(bytes);
        if let Some(target) = link_target {
            let bytes = target.as_bytes();
            assert!(
                bytes.len() <= gnu.linkname.len(),
                "raw fixture link targets must fit tar's 100-byte linkname field"
            );
            gnu.linkname[..bytes.len()].copy_from_slice(bytes);
        }
    }
    header.set_cksum();
    header
}

/// One raw entry, described the way the fixtures below need it.
enum Raw<'a> {
    File(&'a str, &'a [u8]),
    /// A file carrying an explicit mode, for the metadata tests.
    ModedFile(&'a str, &'a [u8], u32),
    Dir(&'a str),
    Symlink(&'a str, &'a str),
    /// A named pipe: `EntryKind::Other`, which has no shape on disk here.
    Fifo(&'a str),
}

/// Writes an archive whose entry names have passed through no validation at
/// all — the shape stuffr must be able to refuse.
fn write_raw_tar(path: &Path, entries: &[Raw<'_>]) -> PathBuf {
    let mut builder = Builder::new(std::fs::File::create(path).unwrap());
    for entry in entries {
        match entry {
            Raw::File(name, data) => {
                let header = raw_header(
                    name,
                    tar::EntryType::Regular,
                    None,
                    data.len() as u64,
                    0o644,
                );
                builder.append(&header, *data).unwrap();
            }
            Raw::ModedFile(name, data, mode) => {
                let header = raw_header(
                    name,
                    tar::EntryType::Regular,
                    None,
                    data.len() as u64,
                    *mode,
                );
                builder.append(&header, *data).unwrap();
            }
            Raw::Dir(name) => {
                let header = raw_header(name, tar::EntryType::Directory, None, 0, 0o755);
                builder.append(&header, std::io::empty()).unwrap();
            }
            Raw::Symlink(name, target) => {
                let header = raw_header(name, tar::EntryType::Symlink, Some(target), 0, 0o777);
                builder.append(&header, std::io::empty()).unwrap();
            }
            Raw::Fifo(name) => {
                let header = raw_header(name, tar::EntryType::Fifo, None, 0, 0o644);
                builder.append(&header, std::io::empty()).unwrap();
            }
        }
    }
    builder.finish().unwrap();
    path.to_path_buf()
}

#[test]
fn a_traversing_entry_is_refused_and_writes_nothing_outside_the_destination() {
    let dir = tmp_dir();
    let evil = dir.join("evil.tar");
    // Written with the raw `tar` crate, NOT through stuffr — stuffr must be
    // able to refuse archives it would never itself produce.
    write_raw_tar(&evil, &[Raw::File("../escaped.txt", b"pwned")]);

    let out = run_output(&[
        "unpack",
        evil.to_str().unwrap(),
        "-C",
        dir.join("out").to_str().unwrap(),
    ]);
    assert_eq!(
        out.status.code(),
        Some(7),
        "a traversing entry must be refused as an unsafe path (exit 7), stderr: {}",
        String::from_utf8_lossy(&out.stderr)
    );
    assert!(
        !dir.join("escaped.txt").exists(),
        "the file escaped the destination"
    );
    assert!(
        String::from_utf8_lossy(&out.stderr).contains("../escaped.txt"),
        "the refusal must name the offending entry, got: {}",
        String::from_utf8_lossy(&out.stderr)
    );
}

/// A **file** entry named `.` must be refused, not `File::create`d over the
/// caller's own destination directory.
///
/// `safe_join` resolves `.` to `dest` itself, deliberately — that is the
/// first entry `tar cf x.tar .` emits, and a DIRECTORY entry naming it is
/// correct and common. It cannot decide the case alone because it never sees
/// the entry's kind, so `entries.rs` refuses a non-`Dir` entry that resolves
/// to `dest` after the join.
///
/// Before that refusal existed this was **exit 1** — `i/o error: Is a
/// directory (os error 21)` — from three bytes of hostile name. Exit 1 means
/// *stuffr* failed, the one code hostile input must never produce and the
/// invariant `check_error_is_classified` exists to hold.
///
/// Written with the raw `tar` crate, never through stuffr: this is a shape
/// stuffr would not itself produce, and the hole is pre-existing in
/// `entries.rs` rather than anything a container introduced.
#[test]
fn a_file_entry_naming_the_destination_itself_is_refused() {
    let dir = tmp_dir();
    let evil = dir.join("dot.tar");
    write_raw_tar(&evil, &[Raw::File(".", b"pwned")]);
    let out_dir = dir.join("out");

    let out = run_output(&[
        "unpack",
        evil.to_str().unwrap(),
        "-C",
        out_dir.to_str().unwrap(),
    ]);
    assert_eq!(
        out.status.code(),
        Some(7),
        "a file entry naming the destination must be an unsafe path (exit 7), never exit 1 \
         (`stuffr failed`), stderr: {}",
        String::from_utf8_lossy(&out.stderr)
    );
    assert!(
        out_dir.is_dir(),
        "the destination must still be a directory, not a file stuffr created over it"
    );

    // A DIRECTORY entry named `.` is the legitimate shape and must still
    // work — the refusal is pinned to the kind, not to the name.
    let ok = dir.join("dotdir.tar");
    write_raw_tar(&ok, &[Raw::Dir("."), Raw::File("a.txt", b"hi")]);
    let ok_dir = dir.join("ok");
    let out = run_output(&[
        "unpack",
        ok.to_str().unwrap(),
        "-C",
        ok_dir.to_str().unwrap(),
    ]);
    assert_eq!(
        out.status.code(),
        Some(0),
        "`tar cf x.tar .`'s own leading directory entry must still extract, stderr: {}",
        String::from_utf8_lossy(&out.stderr)
    );
    assert_eq!(std::fs::read(ok_dir.join("a.txt")).unwrap(), b"hi");
}

/// The same refusal reached through LHA, which is where it was found.
///
/// `delharc`'s own name accessor stripped `.` to the empty string, so this
/// entry used to be refused one step earlier by `safe_join`'s "empty entry
/// name". Reporting the name verbatim — which is what containment needs —
/// let the raw `.` through to the hole `entries.rs` now closes, so BOTH
/// containers are tested: closing it in one place is the point.
#[test]
fn an_lha_file_entry_naming_the_destination_itself_is_refused() {
    let dir = tmp_dir();
    let evil = dir.join("dot.lzh");
    std::fs::write(&evil, raw_lha_entry(b".", b"-lh0-", b"pwned")).unwrap();
    let out_dir = dir.join("out");

    let out = run_output(&[
        "unpack",
        evil.to_str().unwrap(),
        "-C",
        out_dir.to_str().unwrap(),
    ]);
    assert_eq!(
        out.status.code(),
        Some(7),
        "an LHA file entry naming the destination must be exit 7, never exit 1, stderr: {}",
        String::from_utf8_lossy(&out.stderr)
    );
    assert!(
        out_dir.is_dir(),
        "the destination must still be a directory"
    );
}

/// One LHA level-1 header plus a stored (`-lh0-`) payload and the
/// end-of-archive marker, built here rather than through stuffr for the same
/// reason `write_raw_tar` exists: these are archives stuffr must be able to
/// REFUSE, and it would never write one.
fn raw_lha_entry(name: &[u8], method: &[u8; 5], content: &[u8]) -> Vec<u8> {
    let mut crc: u16 = 0;
    for &b in content {
        crc ^= u16::from(b);
        for _ in 0..8 {
            crc = if crc & 1 != 0 {
                (crc >> 1) ^ 0xA001
            } else {
                crc >> 1
            };
        }
    }
    let size = content.len() as u32;
    let mut counted: Vec<u8> = Vec::new();
    counted.extend_from_slice(method);
    counted.extend_from_slice(&size.to_le_bytes()); // level-1 skip size
    counted.extend_from_slice(&size.to_le_bytes()); // original size
    counted.extend_from_slice(&0u32.to_le_bytes()); // timestamp
    counted.push(0x20); // MS-DOS ARCHIVE
    counted.push(1); // header level
    counted.push(name.len() as u8);
    counted.extend_from_slice(name);
    counted.extend_from_slice(&crc.to_le_bytes());
    counted.push(b'U'); // OS-TYPE: Unix
    counted.extend_from_slice(&0u16.to_le_bytes()); // no extra headers

    let mut out = vec![
        counted.len() as u8,
        counted.iter().fold(0u8, |a, &b| a.wrapping_add(b)),
    ];
    out.extend_from_slice(&counted);
    out.extend_from_slice(content);
    out.push(0); // end-of-archive marker
    out
}

#[test]
fn an_absolute_entry_path_is_refused() {
    let dir = tmp_dir();
    let evil = dir.join("abs.tar");
    // PID-qualified: a shared, fixed /tmp name left behind by one failing run
    // would make every later run fail for the wrong reason.
    let escape = std::env::temp_dir().join(format!("stuffr-abs-escape-{}.txt", std::process::id()));
    let _ = std::fs::remove_file(&escape);
    write_raw_tar(&evil, &[Raw::File(escape.to_str().unwrap(), b"pwned")]);

    let out = run_output(&[
        "unpack",
        evil.to_str().unwrap(),
        "-C",
        dir.to_str().unwrap(),
    ]);
    assert_eq!(
        out.status.code(),
        Some(7),
        "an absolute entry name must be refused as an unsafe path (exit 7), stderr: {}",
        String::from_utf8_lossy(&out.stderr)
    );
    assert!(
        !escape.exists(),
        "an absolute entry name wrote outside the destination: {}",
        escape.display()
    );
}

#[test]
fn cat_streams_one_named_entry_from_a_pipe() {
    let bytes = std::fs::read(write_fixture_tar(
        &tmp_dir(),
        &[("a.txt", b"alpha"), ("b.txt", b"beta")],
    ))
    .unwrap();
    assert_eq!(run_with_stdin(&["cat", "-", "b.txt"], &bytes), "beta");
}

#[test]
fn pack_collects_several_paths_into_one_archive() {
    let dir = tmp_dir();
    std::fs::write(dir.join("one.txt"), b"1").unwrap();
    std::fs::write(dir.join("two.txt"), b"2").unwrap();
    let out = dir.join("bundle.tar");
    let packed = run_output(&[
        "pack",
        dir.join("one.txt").to_str().unwrap(),
        dir.join("two.txt").to_str().unwrap(),
        "-o",
        out.to_str().unwrap(),
    ]);
    assert!(
        packed.status.success(),
        "stderr: {}",
        String::from_utf8_lossy(&packed.stderr)
    );
    let listed = String::from_utf8(run_output(&["list", out.to_str().unwrap()]).stdout).unwrap();
    assert!(
        listed.contains("one.txt") && listed.contains("two.txt"),
        "both entries must be listed, got: {listed}"
    );
    // Stored under their basenames, not the absolute paths they came from:
    // stuffr must not write an archive it would itself refuse at exit 7.
    assert!(
        !listed.contains(dir.to_str().unwrap()),
        "absolute paths must not be stored as entry names, got: {listed}"
    );
}

// --- Hostile cases beyond the brief ---------------------------------------

#[test]
fn a_symlink_whose_target_escapes_the_destination_is_refused_before_it_is_created() {
    let dir = tmp_dir();
    let dest = dir.join("out");
    let evil = write_raw_tar(
        &dir.join("link.tar"),
        &[Raw::Symlink("link", "../../etc/passwd")],
    );

    let out = run_output(&[
        "unpack",
        evil.to_str().unwrap(),
        "-C",
        dest.to_str().unwrap(),
    ]);
    assert_eq!(
        out.status.code(),
        Some(7),
        "an escaping symlink target must be refused (exit 7), stderr: {}",
        String::from_utf8_lossy(&out.stderr)
    );
    assert!(
        std::fs::symlink_metadata(dest.join("link")).is_err(),
        "the symlink must not have been created at all"
    );
    assert!(
        String::from_utf8_lossy(&out.stderr).contains("../../etc/passwd"),
        "the refusal must name the offending target, got: {}",
        String::from_utf8_lossy(&out.stderr)
    );
}

#[test]
fn an_entry_written_through_an_escaping_symlink_lands_nowhere() {
    // The two-entry attack: entry 1's own PATH is perfectly contained, so
    // only its TARGET can refuse it; entry 2 is then an ordinary contained
    // name that the OS would resolve THROUGH the link. The link points at
    // this test's own directory (outside the destination) so the escape has
    // a checkable artifact rather than needing to inspect /etc.
    let dir = tmp_dir();
    let dest = dir.join("out");
    let evil = write_raw_tar(
        &dir.join("through.tar"),
        &[
            Raw::Symlink("evil", dir.to_str().unwrap()),
            Raw::File("evil/pwned.txt", b"pwned"),
        ],
    );

    let out = run_output(&[
        "unpack",
        evil.to_str().unwrap(),
        "-C",
        dest.to_str().unwrap(),
    ]);
    assert_eq!(
        out.status.code(),
        Some(7),
        "an absolute symlink target must be refused (exit 7), stderr: {}",
        String::from_utf8_lossy(&out.stderr)
    );
    assert!(
        !dir.join("pwned.txt").exists(),
        "the second entry was written through the symlink, outside the destination"
    );
    assert!(
        std::fs::symlink_metadata(dest.join("evil")).is_err(),
        "the symlink must not have been created"
    );
}

#[test]
fn a_symlink_chain_cannot_walk_out_of_the_destination() {
    // Neither link's own path escapes, and neither target is absolute: the
    // escape only exists once the two are followed together. `b`'s target is
    // refused on its own terms, which is what keeps the chain from ever
    // being walkable.
    let dir = tmp_dir();
    let dest = dir.join("out");
    let evil = write_raw_tar(
        &dir.join("chain.tar"),
        &[
            Raw::Symlink("a", "b"),
            Raw::Symlink("b", "../.."),
            Raw::File("a/pwned.txt", b"pwned"),
        ],
    );

    let out = run_output(&[
        "unpack",
        evil.to_str().unwrap(),
        "-C",
        dest.to_str().unwrap(),
    ]);
    assert_eq!(
        out.status.code(),
        Some(7),
        "a chained symlink escape must be refused (exit 7), stderr: {}",
        String::from_utf8_lossy(&out.stderr)
    );
    assert!(
        !dir.join("pwned.txt").exists() && !dir.parent().unwrap().join("pwned.txt").exists(),
        "the chain wrote outside the destination"
    );
}

#[test]
fn a_traversal_buried_inside_a_deeper_path_is_refused() {
    // `a/b/../../../escaped.txt` nets one level above the destination, but
    // only after two real components have been pushed — the shape a
    // "does the name start with ..?" check would wave straight through.
    let dir = tmp_dir();
    let dest = dir.join("out");
    let evil = write_raw_tar(
        &dir.join("deep.tar"),
        &[Raw::File("a/b/../../../escaped.txt", b"pwned")],
    );

    let out = run_output(&[
        "unpack",
        evil.to_str().unwrap(),
        "-C",
        dest.to_str().unwrap(),
    ]);
    assert_eq!(
        out.status.code(),
        Some(7),
        "a buried traversal must be refused (exit 7), stderr: {}",
        String::from_utf8_lossy(&out.stderr)
    );
    assert!(
        !dir.join("escaped.txt").exists(),
        "the buried traversal escaped the destination"
    );
}

#[test]
fn a_directory_entry_that_escapes_the_destination_is_refused() {
    // A directory entry creates a path without writing a byte of payload, so
    // a containment check placed on the file-writing branch alone would miss
    // it entirely.
    let dir = tmp_dir();
    let dest = dir.join("out");
    let evil = write_raw_tar(&dir.join("dir.tar"), &[Raw::Dir("../escaped-dir/")]);

    let out = run_output(&[
        "unpack",
        evil.to_str().unwrap(),
        "-C",
        dest.to_str().unwrap(),
    ]);
    assert_eq!(
        out.status.code(),
        Some(7),
        "an escaping directory entry must be refused (exit 7), stderr: {}",
        String::from_utf8_lossy(&out.stderr)
    );
    assert!(
        !dir.join("escaped-dir").exists(),
        "the directory escaped the destination"
    );
}

// --- Legitimate archives must still extract ------------------------------

#[test]
fn an_entry_named_dot_extracts_alongside_the_real_entries() {
    // `.` names the destination itself and is accepted, not refused: this is
    // the first entry `tar cf x.tar .` emits, and refusing it would turn a
    // security refusal loose on the most common tarball there is.
    let dir = tmp_dir();
    let dest = dir.join("out");
    let archive = write_raw_tar(
        &dir.join("dot.tar"),
        &[Raw::Dir("./"), Raw::File("./a.txt", b"alpha")],
    );

    let out = run_output(&[
        "unpack",
        archive.to_str().unwrap(),
        "-C",
        dest.to_str().unwrap(),
    ]);
    assert!(
        out.status.success(),
        "a `./` entry must be accepted, stderr: {}",
        String::from_utf8_lossy(&out.stderr)
    );
    assert_eq!(std::fs::read(dest.join("a.txt")).unwrap(), b"alpha");
}

/// The `tar cf x.tar .` idiom, built by the SYSTEM tar rather than by the
/// `tar` crate, extracted with stuffr and compared byte for byte. Three
/// safety checks in this phase have each threatened to fire on benign input;
/// this is the one that proves the containment check does not.
#[test]
fn a_system_tar_of_dot_extracts_cleanly() {
    let Some(tar_bin) = which_tar() else {
        eprintln!("system tar not found; skipping");
        return;
    };
    let dir = tmp_dir();
    let src = dir.join("src");
    std::fs::create_dir_all(src.join("nested")).unwrap();
    std::fs::write(src.join("top.txt"), b"top level").unwrap();
    std::fs::write(src.join("nested/deep.txt"), b"nested payload").unwrap();

    let archive = dir.join("dot.tar");
    let status = Command::new(&tar_bin)
        .arg("cf")
        .arg(&archive)
        .arg(".")
        .current_dir(&src)
        .status()
        .unwrap();
    assert!(
        status.success(),
        "the system tar failed to build the fixture"
    );

    let dest = dir.join("out");
    let out = run_output(&[
        "unpack",
        archive.to_str().unwrap(),
        "-C",
        dest.to_str().unwrap(),
    ]);
    assert!(
        out.status.success(),
        "`tar cf x.tar .` must extract cleanly, stderr: {}",
        String::from_utf8_lossy(&out.stderr)
    );
    assert_eq!(std::fs::read(dest.join("top.txt")).unwrap(), b"top level");
    assert_eq!(
        std::fs::read(dest.join("nested/deep.txt")).unwrap(),
        b"nested payload"
    );
}

/// `tar.rs`'s own tests gate on the system tool the same way rather than
/// failing a machine that has none.
fn which_tar() -> Option<PathBuf> {
    let path = std::env::var_os("PATH")?;
    std::env::split_paths(&path)
        .map(|dir| dir.join("tar"))
        .find(|candidate| candidate.is_file())
}

// Symlink creation is unix-only, the way `ops_compress.rs` gates its own
// symlink tests.
#[cfg(unix)]
#[test]
fn extraction_writes_files_directories_and_contained_symlinks() {
    let dir = tmp_dir();
    let dest = dir.join("out");
    let archive = write_raw_tar(
        &dir.join("good.tar"),
        &[
            Raw::Dir("sub/"),
            Raw::File("sub/a.txt", b"alpha"),
            Raw::Symlink("sub/link", "a.txt"),
        ],
    );

    let out = run_output(&[
        "unpack",
        archive.to_str().unwrap(),
        "-C",
        dest.to_str().unwrap(),
    ]);
    assert!(
        out.status.success(),
        "stderr: {}",
        String::from_utf8_lossy(&out.stderr)
    );
    assert!(dest.join("sub").is_dir());
    assert_eq!(std::fs::read(dest.join("sub/a.txt")).unwrap(), b"alpha");
    let link = std::fs::symlink_metadata(dest.join("sub/link")).unwrap();
    assert!(
        link.file_type().is_symlink(),
        "a symlink entry must become a symlink"
    );
    assert_eq!(
        std::fs::read_link(dest.join("sub/link")).unwrap(),
        Path::new("a.txt")
    );
    // Following it stays inside the destination, which is why it was allowed.
    assert_eq!(std::fs::read(dest.join("sub/link")).unwrap(), b"alpha");
}

#[test]
fn extraction_selects_only_the_entries_a_pattern_names() {
    let dir = tmp_dir();
    let dest = dir.join("out");
    let archive = write_fixture_tar(
        &dir,
        &[
            ("a.txt", b"alpha"),
            ("b.txt", b"beta"),
            ("d/c.txt", b"gamma"),
        ],
    );

    let out = run_output(&[
        "unpack",
        archive.to_str().unwrap(),
        "-C",
        dest.to_str().unwrap(),
        "b.txt",
        "d",
    ]);
    assert!(
        out.status.success(),
        "stderr: {}",
        String::from_utf8_lossy(&out.stderr)
    );
    assert!(
        !dest.join("a.txt").exists(),
        "an unmatched entry was extracted"
    );
    assert_eq!(std::fs::read(dest.join("b.txt")).unwrap(), b"beta");
    // A pattern naming a directory selects everything beneath it.
    assert_eq!(std::fs::read(dest.join("d/c.txt")).unwrap(), b"gamma");
}

#[test]
fn a_pattern_matching_no_entry_is_a_usage_error_rather_than_a_silent_success() {
    let dir = tmp_dir();
    let archive = write_fixture_tar(&dir, &[("a.txt", b"alpha")]);
    let out = run_output(&[
        "unpack",
        archive.to_str().unwrap(),
        "-C",
        dir.join("out").to_str().unwrap(),
        "nosuch.txt",
    ]);
    assert_eq!(
        out.status.code(),
        Some(2),
        "extracting nothing at all must not report success, stderr: {}",
        String::from_utf8_lossy(&out.stderr)
    );
    let out = run_output(&["cat", archive.to_str().unwrap(), "nosuch.txt"]);
    assert_eq!(out.status.code(), Some(2), "cat must agree with unpack");
}

#[test]
fn extraction_refuses_an_existing_file_unless_force_is_given() {
    let dir = tmp_dir();
    let dest = dir.join("out");
    std::fs::create_dir_all(&dest).unwrap();
    std::fs::write(dest.join("a.txt"), b"mine").unwrap();
    let archive = write_fixture_tar(&dir, &[("a.txt", b"alpha")]);

    let out = run_output(&[
        "unpack",
        archive.to_str().unwrap(),
        "-C",
        dest.to_str().unwrap(),
    ]);
    assert_eq!(
        out.status.code(),
        Some(2),
        "an existing file must be refused like every other output, stderr: {}",
        String::from_utf8_lossy(&out.stderr)
    );
    assert_eq!(std::fs::read(dest.join("a.txt")).unwrap(), b"mine");

    let out = run_output(&[
        "unpack",
        archive.to_str().unwrap(),
        "-C",
        dest.to_str().unwrap(),
        "--force",
    ]);
    assert!(
        out.status.success(),
        "stderr: {}",
        String::from_utf8_lossy(&out.stderr)
    );
    assert_eq!(std::fs::read(dest.join("a.txt")).unwrap(), b"alpha");
}

// Symlink creation is unix-only, the way `ops_compress.rs` gates its own
// symlink tests.
#[cfg(unix)]
#[test]
fn a_pre_existing_symlink_at_a_target_path_is_replaced_not_written_through() {
    // `File::create` follows a symlink. Somebody who can plant
    // `dest/a.txt -> outside` before extraction would otherwise redirect the
    // entry's bytes there; --force removes what is in the way rather than
    // writing through it.
    let dir = tmp_dir();
    let dest = dir.join("out");
    std::fs::create_dir_all(&dest).unwrap();
    let outside = dir.join("outside.txt");
    std::fs::write(&outside, b"untouched").unwrap();
    std::os::unix::fs::symlink(&outside, dest.join("a.txt")).unwrap();
    let archive = write_fixture_tar(&dir, &[("a.txt", b"alpha")]);

    let out = run_output(&[
        "unpack",
        archive.to_str().unwrap(),
        "-C",
        dest.to_str().unwrap(),
        "--force",
    ]);
    assert!(
        out.status.success(),
        "stderr: {}",
        String::from_utf8_lossy(&out.stderr)
    );
    assert_eq!(
        std::fs::read(&outside).unwrap(),
        b"untouched",
        "the entry was written through the pre-existing symlink"
    );
    assert_eq!(std::fs::read(dest.join("a.txt")).unwrap(), b"alpha");
}

#[test]
fn extraction_of_a_corrupt_archive_exits_five_not_seven() {
    // Corrupt, hostile and oversized must stay three distinguishable
    // answers: a script branches on which one it got.
    let dir = tmp_dir();
    let good = write_fixture_tar(&dir, &[("a.txt", b"alpha"), ("b.txt", b"beta")]);
    let corrupt = corrupt_midway(&good);
    let out = run_output(&[
        "unpack",
        corrupt.to_str().unwrap(),
        "-C",
        dir.join("out").to_str().unwrap(),
    ]);
    assert_eq!(
        out.status.code(),
        Some(5),
        "a corrupt archive is exit 5, stderr: {}",
        String::from_utf8_lossy(&out.stderr)
    );
}

#[test]
fn extraction_of_a_bomb_exits_six_at_a_tight_max_ratio() {
    let dir = tmp_dir();
    let bomb = write_bomb_tar_gz(&dir);
    let out = run_output(&[
        "unpack",
        bomb.to_str().unwrap(),
        "-C",
        dir.join("out").to_str().unwrap(),
        "--max-ratio",
        "2",
    ]);
    assert_eq!(
        out.status.code(),
        Some(6),
        "a bomb is a resource limit (exit 6), stderr: {}",
        String::from_utf8_lossy(&out.stderr)
    );
}

#[test]
fn cat_streams_every_entry_a_pattern_names_and_bounds_the_ratio() {
    let dir = tmp_dir();
    let archive = write_fixture_tar(&dir, &[("a.txt", b"alpha"), ("b.txt", b"beta")]);
    let out = run_output(&["cat", archive.to_str().unwrap(), "a.txt"]);
    assert!(out.status.success());
    assert_eq!(String::from_utf8(out.stdout).unwrap(), "alpha");

    let bomb = write_bomb_tar_gz(&dir);
    let out = run_output(&[
        "cat",
        bomb.to_str().unwrap(),
        "bomb.bin",
        "--max-ratio",
        "2",
    ]);
    assert_eq!(
        out.status.code(),
        Some(6),
        "cat must bound an entry the same way extraction does, stderr: {}",
        String::from_utf8_lossy(&out.stderr)
    );
}

#[test]
fn an_archive_needs_a_destination_and_the_error_says_which_flag() {
    // `unpack backup.tar` with no -C used to reach the single-stream decoder
    // and report "containers arrive in Phase 2". It now names the flag that
    // does what the user meant.
    let dir = tmp_dir();
    let archive = write_fixture_tar(&dir, &[("a.txt", b"alpha")]);
    let out = run_output(&["unpack", archive.to_str().unwrap()]);
    assert_eq!(
        out.status.code(),
        Some(2),
        "stderr: {}",
        String::from_utf8_lossy(&out.stderr)
    );
    let stderr = String::from_utf8_lossy(&out.stderr);
    assert!(
        stderr.contains("-C") && stderr.contains("tar"),
        "the error must name both the container and the flag, got: {stderr}"
    );
    assert!(
        !dir.join("fixture").exists(),
        "nothing may be written for a refused command"
    );
}

#[test]
fn pack_refuses_several_paths_when_the_output_is_not_a_container() {
    let dir = tmp_dir();
    std::fs::write(dir.join("one.txt"), b"1").unwrap();
    std::fs::write(dir.join("two.txt"), b"2").unwrap();
    let out = run_output(&[
        "pack",
        dir.join("one.txt").to_str().unwrap(),
        dir.join("two.txt").to_str().unwrap(),
        "-o",
        dir.join("bundle.gz").to_str().unwrap(),
    ]);
    assert_eq!(
        out.status.code(),
        Some(2),
        "a codec cannot hold two inputs, stderr: {}",
        String::from_utf8_lossy(&out.stderr)
    );
    assert!(
        !dir.join("bundle.gz").exists(),
        "a refused command must write nothing"
    );
}

#[test]
fn pack_into_a_container_round_trips_through_extraction() {
    let dir = tmp_dir();
    std::fs::write(dir.join("one.txt"), b"first").unwrap();
    std::fs::write(dir.join("two.txt"), b"second").unwrap();
    let archive = dir.join("bundle.tar");
    let out = run_output(&[
        "pack",
        dir.join("one.txt").to_str().unwrap(),
        dir.join("two.txt").to_str().unwrap(),
        "-o",
        archive.to_str().unwrap(),
    ]);
    assert!(
        out.status.success(),
        "stderr: {}",
        String::from_utf8_lossy(&out.stderr)
    );

    let dest = dir.join("out");
    let out = run_output(&[
        "unpack",
        archive.to_str().unwrap(),
        "-C",
        dest.to_str().unwrap(),
    ]);
    assert!(
        out.status.success(),
        "stderr: {}",
        String::from_utf8_lossy(&out.stderr)
    );
    assert_eq!(std::fs::read(dest.join("one.txt")).unwrap(), b"first");
    assert_eq!(std::fs::read(dest.join("two.txt")).unwrap(), b"second");
}

#[test]
fn pack_refuses_two_inputs_that_would_share_one_entry_name() {
    let dir = tmp_dir();
    std::fs::create_dir_all(dir.join("a")).unwrap();
    std::fs::create_dir_all(dir.join("b")).unwrap();
    std::fs::write(dir.join("a/same.txt"), b"1").unwrap();
    std::fs::write(dir.join("b/same.txt"), b"2").unwrap();
    let archive = dir.join("dup.tar");
    let out = run_output(&[
        "pack",
        dir.join("a/same.txt").to_str().unwrap(),
        dir.join("b/same.txt").to_str().unwrap(),
        "-o",
        archive.to_str().unwrap(),
    ]);
    assert_eq!(
        out.status.code(),
        Some(2),
        "two entries with one name would make an archive that cannot be \
         extracted without --force, stderr: {}",
        String::from_utf8_lossy(&out.stderr)
    );
    assert!(!archive.exists(), "a refused command must write nothing");
}

/// Was `pack_of_a_directory_says_so_rather_than_writing_an_empty_archive`,
/// which asserted exit 2 on a directory. Phase 2c walks it instead, so the
/// property worth keeping is the one the old name was really about: a
/// directory must not silently produce an archive with nothing in it. An
/// EMPTY directory is still one real entry.
#[test]
fn pack_of_an_empty_directory_stores_the_directory_itself() {
    let dir = tmp_dir();
    std::fs::create_dir_all(dir.join("tree")).unwrap();
    let archive = dir.join("tree.tar");
    let out = run_output(&[
        "pack",
        dir.join("tree").to_str().unwrap(),
        "-o",
        archive.to_str().unwrap(),
    ]);
    assert_eq!(
        out.status.code(),
        Some(0),
        "stderr: {}",
        String::from_utf8_lossy(&out.stderr)
    );

    let listed = run_output(&["list", archive.to_str().unwrap()]);
    let text = String::from_utf8_lossy(&listed.stdout);
    assert!(
        text.contains("tree"),
        "the directory itself must be an entry, not an empty archive: {text}"
    );
}

#[test]
fn flags_that_the_container_path_cannot_honour_are_refused_not_ignored() {
    // The tree's rule (see `threads_is_not_offered_on_decode_subcommands`):
    // a flag that would be silently ignored is refused instead.
    //
    // `--memory-limit` used to be in this list and no longer is: the Phase 2
    // final review's C1 threaded it through container resolution, so it is
    // now honoured rather than refused — see
    // `memory_limit_is_honoured_rather_than_refused_on_the_container_path`.
    let dir = tmp_dir();
    let archive = write_fixture_tar(&dir, &[("a.txt", b"alpha")]);
    let dest = dir.join("out");
    for extra in [vec!["--format", "gzip"], vec!["-o", "somewhere"]] {
        let mut args = vec![
            "unpack",
            archive.to_str().unwrap(),
            "-C",
            dest.to_str().unwrap(),
        ];
        args.extend_from_slice(&extra);
        let out = run_output(&args);
        assert_eq!(
            out.status.code(),
            Some(2),
            "`{}` must be refused alongside -C, stderr: {}",
            extra.join(" "),
            String::from_utf8_lossy(&out.stderr)
        );
    }
}

/// The same rule, applied to the PACK side, which had it backwards.
///
/// `entries::create_archive` builds `CreateOpts { level, ..Default::default() }`
/// — it hands the container no governor, no worker count and no weak-encoder
/// consent, because none of the four registered containers compresses
/// anything itself. So `--threads`, `--turbo` and `--allow-weak-encoder`
/// were accepted and silently dropped: precisely what the extract side above
/// refuses. Consistency, not new capability.
#[test]
fn pack_flags_the_container_path_cannot_honour_are_refused_not_ignored() {
    let dir = tmp_dir();
    let src = dir.join("a.txt");
    std::fs::write(&src, b"alpha").unwrap();
    let archive = dir.join("bundle.tar");
    for extra in [
        vec!["--threads", "4"],
        vec!["--turbo"],
        vec!["--allow-weak-encoder"],
    ] {
        let mut args = vec![
            "pack",
            src.to_str().unwrap(),
            "-o",
            archive.to_str().unwrap(),
        ];
        args.extend_from_slice(&extra);
        let out = run_output(&args);
        assert_eq!(
            out.status.code(),
            Some(2),
            "`{}` must be refused on the container pack path, stderr: {}",
            extra.join(" "),
            String::from_utf8_lossy(&out.stderr)
        );
        assert!(
            !archive.exists(),
            "a refused command must write nothing: {}",
            extra.join(" ")
        );
    }

    // The same flags stay ACCEPTED on the single-stream codec path, which
    // genuinely honours them — the refusal above must not have leaked.
    let out = run_output(&[
        "pack",
        src.to_str().unwrap(),
        "--format",
        "gzip",
        "--threads",
        "2",
        "--force",
    ]);
    assert!(
        out.status.success(),
        "the codec path still honours --threads, stderr: {}",
        String::from_utf8_lossy(&out.stderr)
    );
}

/// The gap the two lexical checks cannot see on their own, demonstrated
/// outside stuffr first (a shell reproduction is in the task report): every
/// step below is contained COMPONENT-WISE from the destination, and the OS
/// still resolves the last one outside it.
///
/// * `a/b/up -> ..` is contained: it resolves to `<dest>/a`.
/// * `a/b/up/link -> ../..` resolves, component-wise from `<dest>`, to `a`
///   — inside. Resolved by the OS through `up`, whose real parent is
///   `<dest>/a`, it lands on `<dest>/..`: the directory holding `<dest>`.
/// * `a/b/up/link/pwned.txt` is then an ordinary contained name written
///   straight through it.
///
/// So an entry whose PATH COMPONENTS include an existing symlink is refused
/// outright — the same defence libarchive's SECURE_SYMLINKS provides, and it
/// closes the pre-existing-hostile-symlink case in the destination too.
#[cfg(unix)]
#[test]
fn an_entry_written_through_a_symlinked_path_component_is_refused() {
    let dir = tmp_dir();
    let dest = dir.join("out");
    let evil = write_raw_tar(
        &dir.join("component.tar"),
        &[
            Raw::Dir("a/b/"),
            Raw::Symlink("a/b/up", ".."),
            Raw::Symlink("a/b/up/link", "../.."),
            Raw::File("a/b/up/link/pwned.txt", b"pwned"),
        ],
    );

    let out = run_output(&[
        "unpack",
        evil.to_str().unwrap(),
        "-C",
        dest.to_str().unwrap(),
    ]);
    assert_eq!(
        out.status.code(),
        Some(7),
        "an entry resolving through a symlinked component must be refused (exit 7), \
         stderr: {}",
        String::from_utf8_lossy(&out.stderr)
    );
    assert!(
        !dir.join("pwned.txt").exists(),
        "the entry escaped the destination through a symlinked path component"
    );
}

// ---------------------------------------------------------------------
// Extraction fidelity.
//
// `--strict-fidelity` gates on `FidelityReport::has_warnings`, so a loss that
// raises no warning is a loss the flag reports as success. These tests are
// the difference between the warnings meaning something and being decoration.
// ---------------------------------------------------------------------

#[cfg(unix)]
fn mode_of(path: &Path) -> u32 {
    use std::os::unix::fs::PermissionsExt;
    std::fs::metadata(path).unwrap().permissions().mode() & 0o7777
}

fn mtime_secs(path: &Path) -> u64 {
    std::fs::metadata(path)
        .unwrap()
        .modified()
        .unwrap()
        .duration_since(std::time::UNIX_EPOCH)
        .unwrap()
        .as_secs()
}

#[cfg(unix)]
#[test]
fn extraction_restores_modes_and_mtimes_for_files_and_directories() {
    let dir = tmp_dir();
    let dest = dir.join("out");
    let archive = write_raw_tar(
        &dir.join("meta.tar"),
        &[
            Raw::Dir("sub/"),
            Raw::ModedFile("sub/script.sh", b"#!/bin/sh\n", 0o750),
            Raw::ModedFile("readonly.txt", b"ro", 0o400),
        ],
    );

    let out = run_output(&[
        "unpack",
        archive.to_str().unwrap(),
        "-C",
        dest.to_str().unwrap(),
    ]);
    assert!(
        out.status.success(),
        "stderr: {}",
        String::from_utf8_lossy(&out.stderr)
    );

    assert_eq!(mode_of(&dest.join("sub/script.sh")), 0o750);
    assert_eq!(mode_of(&dest.join("readonly.txt")), 0o400);
    assert_eq!(mode_of(&dest.join("sub")), 0o755);
    assert_eq!(mtime_secs(&dest.join("sub/script.sh")), FIXTURE_MTIME);
    assert_eq!(mtime_secs(&dest.join("readonly.txt")), FIXTURE_MTIME);
    // A directory's mtime is restored AFTER its children are written —
    // creating one of them would otherwise bump it back to now.
    assert_eq!(mtime_secs(&dest.join("sub")), FIXTURE_MTIME);

    // Nothing was lost, so the gate passes.
    let strict = run_output(&[
        "unpack",
        archive.to_str().unwrap(),
        "-C",
        dir.join("strict").to_str().unwrap(),
        "--strict-fidelity",
    ]);
    assert!(
        strict.status.success(),
        "an extraction that lost nothing must pass --strict-fidelity, stderr: {}",
        String::from_utf8_lossy(&strict.stderr)
    );
}

#[cfg(unix)]
#[test]
fn a_setuid_bit_is_not_restored_and_strict_fidelity_fails_on_the_loss() {
    // An archive is untrusted input; honouring its setuid bit hands over a
    // privilege-escalation primitive for free. Dropping it is a real
    // difference from what the archive declared, so it is REPORTED — which is
    // what makes `--strict-fidelity` able to see it.
    let dir = tmp_dir();
    let dest = dir.join("out");
    let archive = write_raw_tar(
        &dir.join("setuid.tar"),
        &[Raw::ModedFile("suid", b"payload", 0o4755)],
    );

    let out = run_output(&[
        "unpack",
        archive.to_str().unwrap(),
        "-C",
        dest.to_str().unwrap(),
    ]);
    assert!(
        out.status.success(),
        "the extraction itself succeeds, stderr: {}",
        String::from_utf8_lossy(&out.stderr)
    );
    assert_eq!(
        mode_of(&dest.join("suid")),
        0o755,
        "the setuid bit must not be restored"
    );
    let stderr = String::from_utf8_lossy(&out.stderr);
    assert!(
        stderr.contains("suid") && stderr.contains("mode"),
        "the loss must be reported, naming the entry and the field: {stderr}"
    );

    let strict = run_output(&[
        "unpack",
        archive.to_str().unwrap(),
        "-C",
        dir.join("strict").to_str().unwrap(),
        "--force",
        "--strict-fidelity",
    ]);
    assert_eq!(
        strict.status.code(),
        Some(4),
        "a dropped mode must fail --strict-fidelity, stderr: {}",
        String::from_utf8_lossy(&strict.stderr)
    );
}

#[cfg(unix)]
#[test]
fn an_entry_with_no_shape_on_disk_is_skipped_and_said_out_loud() {
    // A fifo is `EntryKind::Other`. Writing it out as a regular file carrying
    // its "contents" would materialise something the archive never held.
    let dir = tmp_dir();
    let dest = dir.join("out");
    let archive = write_raw_tar(
        &dir.join("fifo.tar"),
        &[Raw::File("a.txt", b"alpha"), Raw::Fifo("pipe")],
    );

    let out = run_output(&[
        "unpack",
        archive.to_str().unwrap(),
        "-C",
        dest.to_str().unwrap(),
    ]);
    assert!(
        out.status.success(),
        "stderr: {}",
        String::from_utf8_lossy(&out.stderr)
    );
    assert_eq!(std::fs::read(dest.join("a.txt")).unwrap(), b"alpha");
    assert!(
        std::fs::symlink_metadata(dest.join("pipe")).is_err(),
        "a fifo entry must not become a regular file"
    );
    let stderr = String::from_utf8_lossy(&out.stderr);
    assert!(
        stderr.contains("skipped entry") && stderr.contains("pipe"),
        "the skip must name the entry and why: {stderr}"
    );

    let strict = run_output(&[
        "unpack",
        archive.to_str().unwrap(),
        "-C",
        dir.join("strict").to_str().unwrap(),
        "--strict-fidelity",
    ]);
    assert_eq!(
        strict.status.code(),
        Some(4),
        "a skipped entry must fail --strict-fidelity, stderr: {}",
        String::from_utf8_lossy(&strict.stderr)
    );
}

#[cfg(unix)]
#[test]
fn a_symlinks_own_mode_and_mtime_are_reported_as_lost() {
    // `set_permissions` and `File::set_times` both follow a link, and there
    // is no `lchmod`/`lutimes` in std — so the link's own metadata cannot be
    // restored, and saying so is the whole job of the fidelity report.
    let dir = tmp_dir();
    let dest = dir.join("out");
    let archive = write_raw_tar(
        &dir.join("link.tar"),
        &[Raw::File("a.txt", b"alpha"), Raw::Symlink("link", "a.txt")],
    );

    let out = run_output(&[
        "unpack",
        archive.to_str().unwrap(),
        "-C",
        dest.to_str().unwrap(),
        "--strict-fidelity",
    ]);
    assert_eq!(
        out.status.code(),
        Some(4),
        "stderr: {}",
        String::from_utf8_lossy(&out.stderr)
    );
    let stderr = String::from_utf8_lossy(&out.stderr);
    assert!(
        stderr.contains("link") && stderr.contains("mtime"),
        "the loss must name the entry and the field: {stderr}"
    );
    // The link itself still extracted — this is a fidelity report, not a
    // refusal.
    assert_eq!(
        std::fs::read_link(dest.join("link")).unwrap(),
        Path::new("a.txt")
    );
}

#[test]
fn test_verb_passes_strict_fidelity_on_an_ordinary_tarball() {
    // The counterpart assertion to the four above: the flag is not simply
    // "fail whenever it is given". A tar read approximates nothing.
    let dir = tmp_dir();
    let archive = write_fixture_tar(&dir, &[("a.txt", b"alpha")]);
    let out = run_output(&["test", archive.to_str().unwrap(), "--strict-fidelity"]);
    assert!(
        out.status.success(),
        "stderr: {}",
        String::from_utf8_lossy(&out.stderr)
    );
}

/// An `st_mode`-shaped mode field must not read as "setuid was refused".
///
/// Apache Commons Compress writes `TarArchiveEntry.DEFAULT_FILE_MODE =
/// 0100644` — the file-type bit `S_IFREG` still in it — which puts this shape
/// in Java, Gradle and Maven tarballs. `0o100644 & !0o777` is `0o100000`,
/// non-zero, so an unmasked check would report a dropped mode for EVERY entry
/// of an entirely ordinary archive and fail `--strict-fidelity` on all of
/// them, while the file itself lands at `0o644` exactly as it should. The
/// permission apply was always right; only the warning was wrong.
#[cfg(unix)]
#[test]
fn an_st_mode_shaped_header_mode_raises_no_warning() {
    let dir = tmp_dir();
    let dest = dir.join("out");
    let archive = write_raw_tar(
        &dir.join("commons.tar"),
        &[Raw::ModedFile("a.txt", b"alpha", 0o100_644)],
    );

    let out = run_output(&[
        "unpack",
        archive.to_str().unwrap(),
        "-C",
        dest.to_str().unwrap(),
        "--strict-fidelity",
    ]);
    assert!(
        out.status.success(),
        "an st_mode-shaped mode field must not fail the gate, stderr: {}",
        String::from_utf8_lossy(&out.stderr)
    );
    let stderr = String::from_utf8_lossy(&out.stderr);
    assert!(
        !stderr.contains("missing metadata"),
        "nothing was lost, so nothing may be reported: {stderr}"
    );
    assert_eq!(
        mode_of(&dest.join("a.txt")),
        0o644,
        "the permission bits apply; the type bits are not permissions"
    );

    // The setuid case must still be caught — the mask must not have widened
    // into "ignore everything above 0o777".
    let suid = write_raw_tar(
        &dir.join("suid.tar"),
        &[Raw::ModedFile("b.txt", b"beta", 0o104_755)],
    );
    let out = run_output(&[
        "unpack",
        suid.to_str().unwrap(),
        "-C",
        dir.join("suid-out").to_str().unwrap(),
        "--strict-fidelity",
    ]);
    assert_eq!(
        out.status.code(),
        Some(4),
        "setuid inside an st_mode-shaped field is still a dropped mode, stderr: {}",
        String::from_utf8_lossy(&out.stderr)
    );
}

/// Builds a `.tar.lz` and returns `(legitimate, crafted)`.
///
/// `crafted` differs from `legitimate` in exactly ONE byte: lzip's header
/// byte 5, the coded dictionary size, forced to `0x1D` — 512 MiB. The
/// payload is untouched and still decodes, so anything the crafted file
/// costs comes purely from the DECLARATION, which is what makes it the
/// right probe for a pre-output allocation guard.
fn craft_a_tar_lz_declaring_a_huge_dictionary(tag: &str) -> (PathBuf, PathBuf) {
    let dir = tmp(tag);
    let _ = std::fs::remove_dir_all(&dir);
    std::fs::create_dir_all(&dir).unwrap();

    let tar_path = dir.join("bundle.tar");
    write_raw_tar(
        &tar_path,
        &[Raw::File("a.txt", b"hello from inside the tar")],
    );

    assert!(
        Command::new(STUFFR)
            .args([
                "pack",
                tar_path.to_str().unwrap(),
                "--format",
                "lzip",
                "--force"
            ])
            .status()
            .unwrap()
            .success(),
        "packing the fixture must succeed"
    );
    let legit = dir.join("bundle.tar.lz");

    let mut bytes = std::fs::read(&legit).unwrap();
    assert_eq!(&bytes[..4], b"LZIP", "fixture must really be lzip");
    // Byte 5 is lzip's coded dictionary size. 0x1D asks for 512 MiB.
    bytes[5] = 0x1D;
    let crafted = dir.join("crafted.tar.lz");
    std::fs::write(&crafted, &bytes).unwrap();

    (legit, crafted)
}

/// The Phase 2 final review's C1, pinned on every entry-aware verb.
///
/// `entries::open_archive` resolved the codec layer beneath a container
/// through `resolve_chain_deep`, which built each decoder from
/// `DecodeOpts::default()` — `memory_limit: None`, i.e. unbounded. So a
/// 336-byte `.tar.lz` whose header declares a 512 MiB dictionary drove
/// 182 MB peak RSS through `list` and 307 MB through `test`, both exiting 0,
/// while single-stream `unpack` of the identical bytes refused it at exit 6
/// in 1.7 MB. That is the denial of service Phase 1f closed, reopened behind
/// `list` — the verb advertised as reading nothing and extracting nothing.
///
/// `--max-ratio` cannot substitute: it counts decoded OUTPUT bytes and the
/// allocation precedes any output. Only `DecodeOpts::memory_limit` sees it.
///
/// Every invocation passes `--memory-limit` EXPLICITLY. Relying on the
/// default would make the test host-dependent and green only by accident:
/// `default_memory_limit()` is 25% of available RAM, which is the 256 MiB
/// floor on macOS (no `/proc/meminfo`) but roughly 3.5 GiB on a 16 GB Linux
/// CI runner — comfortably above the 512 MiB this fixture declares, so all
/// four verbs would exit 0 and the assertion would fail on every Linux job.
/// Measured directly: `stuffr list crafted.tar.lz --memory-limit 3500M`
/// exits 0. 0x1D is lzip's LARGEST coded dictionary, so the fixture cannot
/// be made hungrier to compensate. `cli.rs`'s
/// `info_reports_the_resolved_memory_limit` states the same convention.
#[test]
fn a_container_under_a_codec_declaring_a_huge_dictionary_is_refused_on_every_verb() {
    let (_legit, crafted) = craft_a_tar_lz_declaring_a_huge_dictionary("c1-refuse");
    let path = crafted.to_str().unwrap();
    // Below the fixture's 512 MiB declaration, above what the legitimate
    // sibling needs — see `a_legitimate_archive_of_the_same_size_still_works_on_every_verb`.
    const LIMIT: &str = "64M";

    for args in [
        vec!["list", path, "--memory-limit", LIMIT],
        vec!["test", path, "--memory-limit", LIMIT],
        vec!["cat", path, "a.txt", "--memory-limit", LIMIT],
    ] {
        let out = Command::new(STUFFR).args(&args).output().unwrap();
        let stderr = String::from_utf8_lossy(&out.stderr).to_string();
        assert_eq!(
            out.status.code(),
            Some(6),
            "`stuffr {}` must refuse a 512 MiB dictionary declaration at exit 6, \
             not allocate for it; stderr: {stderr}",
            args.join(" ")
        );
        assert!(
            stderr.contains("memory-limit"),
            "the refusal must name the flag that raises it; stderr: {stderr}"
        );
    }

    // The single-stream path already did this; it must keep doing it.
    let out = Command::new(STUFFR)
        .args([
            "unpack",
            path,
            "-o",
            "/dev/null",
            "--force",
            "--memory-limit",
            LIMIT,
        ])
        .output()
        .unwrap();
    assert_eq!(
        out.status.code(),
        Some(6),
        "the single-stream path's existing refusal must be unchanged; stderr: {}",
        String::from_utf8_lossy(&out.stderr)
    );

    // And over a pipe, where there is no path to resolve the chain from.
    let mut child = Command::new(STUFFR)
        .args(["list", "-", "--memory-limit", LIMIT])
        .stdin(Stdio::piped())
        .stdout(Stdio::piped())
        .stderr(Stdio::piped())
        .spawn()
        .unwrap();
    let bytes = std::fs::read(&crafted).unwrap();
    child.stdin.take().unwrap().write_all(&bytes).unwrap();
    let out = child.wait_with_output().unwrap();
    assert_eq!(
        out.status.code(),
        Some(6),
        "a piped crafted archive must be refused too; stderr: {}",
        String::from_utf8_lossy(&out.stderr)
    );
}

/// The other half of C1, and the one that catches an over-broad fix: a
/// LEGITIMATE archive of the same size, differing in that one header byte,
/// must still work on every verb. A guard that refused this would be a
/// worse defect than the one it closed.
#[test]
fn a_legitimate_archive_of_the_same_size_still_works_on_every_verb() {
    let (legit, crafted) = craft_a_tar_lz_declaring_a_huge_dictionary("c1-allow");
    let path = legit.to_str().unwrap();
    assert_eq!(
        std::fs::metadata(&legit).unwrap().len(),
        std::fs::metadata(&crafted).unwrap().len(),
        "the two fixtures must differ only in that one byte"
    );

    // The SAME explicit limit its crafted sibling is refused at, so the pair
    // proves the bound discriminates on the declaration rather than refusing
    // everything — and so neither half depends on the host's RAM.
    const LIMIT: &str = "64M";

    let out = Command::new(STUFFR)
        .args(["list", path, "--memory-limit", LIMIT])
        .output()
        .unwrap();
    assert!(
        out.status.success(),
        "stderr: {}",
        String::from_utf8_lossy(&out.stderr)
    );
    assert!(
        String::from_utf8_lossy(&out.stdout).contains("a.txt"),
        "list must still show the entry"
    );

    let out = Command::new(STUFFR)
        .args(["test", path, "--memory-limit", LIMIT])
        .output()
        .unwrap();
    assert!(
        out.status.success(),
        "stderr: {}",
        String::from_utf8_lossy(&out.stderr)
    );

    let out = Command::new(STUFFR)
        .args(["cat", path, "a.txt", "--memory-limit", LIMIT])
        .output()
        .unwrap();
    assert!(out.status.success());
    assert_eq!(out.stdout, b"hello from inside the tar");

    let dest = tmp("c1-allow-dest");
    let _ = std::fs::remove_dir_all(&dest);
    let out = Command::new(STUFFR)
        .args([
            "unpack",
            path,
            "-C",
            dest.to_str().unwrap(),
            "--memory-limit",
            LIMIT,
        ])
        .output()
        .unwrap();
    assert!(
        out.status.success(),
        "stderr: {}",
        String::from_utf8_lossy(&out.stderr)
    );
    assert!(dest.join("a.txt").exists());
    let _ = std::fs::remove_dir_all(&dest);
}

/// `--memory-limit` is now ACCEPTED and honoured on the entry-aware paths,
/// where it used to be refused at exit 2 with "not yet honoured for a
/// container". Raising it past the declaration lets the crafted archive
/// through, which is the proof the flag actually reaches the decoder rather
/// than being parsed and dropped.
#[test]
fn memory_limit_is_honoured_rather_than_refused_on_the_container_path() {
    let (_legit, crafted) = craft_a_tar_lz_declaring_a_huge_dictionary("c1-flag");
    let path = crafted.to_str().unwrap();

    for args in [
        vec!["list", path, "--memory-limit", "1G"],
        vec!["test", path, "--memory-limit", "1G"],
        vec!["cat", path, "a.txt", "--memory-limit", "1G"],
    ] {
        let out = Command::new(STUFFR).args(&args).output().unwrap();
        assert!(
            out.status.success(),
            "`stuffr {}` must succeed once the limit is raised past the declaration; \
             stderr: {}",
            args.join(" "),
            String::from_utf8_lossy(&out.stderr)
        );
    }

    let dest = tmp("c1-flag-dest");
    let _ = std::fs::remove_dir_all(&dest);
    let out = Command::new(STUFFR)
        .args([
            "unpack",
            path,
            "-C",
            dest.to_str().unwrap(),
            "--memory-limit",
            "1G",
        ])
        .output()
        .unwrap();
    assert!(
        out.status.success(),
        "unpack -C must accept --memory-limit rather than refusing it; stderr: {}",
        String::from_utf8_lossy(&out.stderr)
    );
    let _ = std::fs::remove_dir_all(&dest);
}

/// The Phase 2 final review's I1, end to end.
///
/// `sub/top -> ..` points at the extraction root. bsdtar and GNU tar both
/// extract it; stuffr aborted the whole extraction at exit 7 with "unsafe
/// entry path `sub/..` refused: path traversal nets back to the
/// destination" — naming a path that is not an entry in the archive, so the
/// user could not find it. `dest` is inside `dest`; there is no escape here.
#[test]
fn a_symlink_pointing_at_the_extraction_root_is_extracted_not_refused() {
    let dir = tmp_dir();
    let dest = dir.join("out");
    let archive = write_raw_tar(
        &dir.join("root-link.tar"),
        &[
            Raw::Dir("sub"),
            Raw::Symlink("sub/top", ".."),
            Raw::File("sub/a.txt", b"alpha"),
        ],
    );

    let out = run_output(&[
        "unpack",
        archive.to_str().unwrap(),
        "-C",
        dest.to_str().unwrap(),
    ]);
    assert!(
        out.status.success(),
        "a symlink netting to the destination is contained, not an escape; stderr: {}",
        String::from_utf8_lossy(&out.stderr)
    );
    let link = dest.join("sub/top");
    assert!(
        std::fs::symlink_metadata(&link).is_ok(),
        "the symlink must have been created"
    );
    assert_eq!(std::fs::read_link(&link).unwrap(), Path::new(".."));
    assert!(dest.join("sub/a.txt").exists(), "extraction must not abort");
}

/// The regression guard for the test above: one step further out is still
/// an escape, and must still exit 7 with the entry's OWN target named.
#[test]
fn a_symlink_one_step_past_the_extraction_root_is_still_refused() {
    for (tag, target) in [
        ("i1-two-up", "../.."),
        ("i1-deep", "../../../etc"),
        ("i1-mixed", "../sub/../.."),
    ] {
        let dir = tmp_dir();
        let dest = dir.join(tag);
        let archive = write_raw_tar(
            &dir.join(format!("{tag}.tar")),
            &[Raw::Dir("sub"), Raw::Symlink("sub/top", target)],
        );
        let out = run_output(&[
            "unpack",
            archive.to_str().unwrap(),
            "-C",
            dest.to_str().unwrap(),
        ]);
        assert_eq!(
            out.status.code(),
            Some(7),
            "`{target}` escapes and must still be refused, stderr: {}",
            String::from_utf8_lossy(&out.stderr)
        );
        let stderr = String::from_utf8_lossy(&out.stderr).to_string();
        assert!(
            stderr.contains(target),
            "the refusal must name the archive's own target `{target}`, got: {stderr}"
        );
        assert!(
            std::fs::symlink_metadata(dest.join("sub/top")).is_err(),
            "the symlink must not have been created"
        );
    }
}

/// The Phase 2 final review's I2, across the third dimension round 3
/// missed: container × WRAPPED-IN-A-CODEC × source shape.
///
/// `fidelity_is_knowable_without_opening` returned `true` as soon as the
/// rung was authoritative — but the rung is the RAW INPUT's seekability,
/// which says nothing about a container reached through a decoder.
/// `bundle.zip.gz` on disk is a seekable file, so `info` printed
/// `rung: exact / fidelity: nothing approximated`, while `stuffr test
/// bundle.zip.gz --strict-fidelity` on the same bytes reported
/// `TrailingIndexUnread` and `EntryCountUnknown` and exited 4.
///
/// Every cell is checked against ground truth from `test`, which actually
/// opens the archive — so the assertions cannot drift into merely agreeing
/// with the predicate.
#[test]
fn info_does_not_claim_nothing_was_approximated_for_a_container_under_a_codec() {
    let dir = tmp("info-codec-wrapped-matrix");
    let _ = std::fs::remove_dir_all(&dir);
    std::fs::create_dir_all(&dir).unwrap();
    let one = dir.join("one.txt");
    std::fs::write(&one, b"payload").unwrap();

    for (ext, has_trailing_index) in [("zip", true), ("tar", false), ("cpio", false), ("a", false)]
    {
        let bare = dir.join(format!("bundle.{ext}"));
        assert!(
            Command::new(STUFFR)
                .args(["pack", one.to_str().unwrap(), "-o", bare.to_str().unwrap()])
                .status()
                .unwrap()
                .success(),
            "packing a .{ext} must succeed"
        );
        // Two steps here on purpose, not because one is impossible: since
        // Phase 2c `-o bundle.tar.gz` composes both layers in a single
        // command. What this test needs is a codec wrapped around an
        // ALREADY-WRITTEN container file, so that `info` sees a codec whose
        // inner layer it must resolve — and packing the container first is
        // the clearest way to get exactly that byte sequence.
        assert!(
            Command::new(STUFFR)
                .args([
                    "pack",
                    bare.to_str().unwrap(),
                    "--format",
                    "gzip",
                    "--force"
                ])
                .status()
                .unwrap()
                .success(),
            "wrapping the .{ext} in gzip must succeed"
        );
        let wrapped = dir.join(format!("bundle.{ext}.gz"));
        let bytes = std::fs::read(&wrapped).unwrap();

        // Ground truth first, from the verb that opens the archive.
        let strict = Command::new(STUFFR)
            .args(["test", wrapped.to_str().unwrap(), "--strict-fidelity"])
            .output()
            .unwrap();
        let strict_err = String::from_utf8_lossy(&strict.stderr).to_string();
        let really_loses = !strict.status.success();
        assert_eq!(
            really_loses, has_trailing_index,
            ".{ext}.gz: only a trailing index can be missed by a forward read; \
             stderr: {strict_err}"
        );

        // (a) A SEEKABLE FILE, where the path's extensions name the whole
        //     chain (`bundle.zip.gz` -> zip over gzip). This is the cell
        //     I2 reported: `rung: exact`, because the FILE is seekable,
        //     over a container that is not read from that file at all.
        let text = String::from_utf8(
            Command::new(STUFFR)
                .args(["info", wrapped.to_str().unwrap()])
                .output()
                .unwrap()
                .stdout,
        )
        .unwrap();
        assert!(
            text.contains("exact"),
            ".{ext}.gz from a file: the rung is real and unchanged: {text}"
        );
        assert!(
            text.contains(ext),
            ".{ext}.gz from a file must resolve the whole chain: {text}"
        );
        if has_trailing_index {
            assert!(
                text.contains("not evaluated"),
                ".{ext}.gz from a file: the zip is read out of a gzip decoder, which is \
                 forward-only however seekable the FILE is — `test` on these very bytes \
                 exits 4. info has not looked and must not claim: {text}"
            );
            assert!(!text.contains("nothing approximated"), "{text}");
        } else {
            assert!(
                text.contains("nothing approximated"),
                ".{ext}.gz from a file carries every entry's metadata inline, so a forward \
                 read loses nothing — withholding here would be a false negative, the \
                 round-3 defect repeating: {text}"
            );
            assert!(!text.contains("not evaluated"), "{text}");
        }

        // (b) A PIPE with no path. `inspect` resolves the chain with the
        //     SHALLOW `resolve_chain` — it identifies a stream without
        //     decoding it, and seeing the zip inside would mean running the
        //     gzip decoder. With no path to read extensions from, there is
        //     nothing to name the inner layer, so the chain bottoms out at
        //     the codec and `info` reports on the codec alone. That is a
        //     documented limit of `info`, not the I2 defect: the claim it
        //     makes is about what it identified. Pinned so the two cells
        //     cannot be confused for one another later.
        let text = info_over_stdin(&bytes);
        assert!(text.contains("forward-only"), ".{ext}.gz on a pipe: {text}");
        assert!(
            text.contains("chain:    gzip"),
            ".{ext}.gz on a pipe resolves to the codec alone — info does not decode to \
             look inside: {text}"
        );

        // And the codec-wrapped verdict must not have leaked onto the BARE
        // container: a seekable bare zip still reads its central directory.
        let text = String::from_utf8(
            Command::new(STUFFR)
                .args(["info", bare.to_str().unwrap()])
                .output()
                .unwrap()
                .stdout,
        )
        .unwrap();
        assert!(
            text.contains("nothing approximated"),
            "a bare seekable .{ext} is unaffected by the codec-wrapped rule: {text}"
        );
    }

    let _ = std::fs::remove_dir_all(&dir);
}

/// The Phase 2 final review's I3: `entries::test` built no `ArchiveBudget`
/// at all, so a 204 KB zip holding one 200 MB entry verified clean at exit
/// 0 under `--max-ratio 10` while `cat` and `unpack` of the identical file
/// refused it at exit 6. `test` is the verb reached for to inspect an
/// UNTRUSTED archive; it must not be the only unbounded one.
#[test]
fn every_entry_aware_verb_applies_the_same_expansion_bound() {
    let dir = tmp_dir();
    // Highly compressible, and large enough that a ratio of 10 cannot cover
    // it while staying quick to build.
    let payload = vec![0u8; 8 * 1024 * 1024];
    let big = dir.join("big.bin");
    std::fs::write(&big, &payload).unwrap();
    let bomb = dir.join("bomb.zip");
    assert!(
        Command::new(STUFFR)
            .args(["pack", big.to_str().unwrap(), "-o", bomb.to_str().unwrap()])
            .status()
            .unwrap()
            .success()
    );
    let compressed = std::fs::metadata(&bomb).unwrap().len();
    assert!(
        compressed * 10 < payload.len() as u64,
        "the fixture must actually exceed a ratio of 10 ({compressed} compressed)"
    );

    let dest = dir.join("out");
    for args in [
        vec!["test", bomb.to_str().unwrap(), "--max-ratio", "10"],
        vec![
            "cat",
            bomb.to_str().unwrap(),
            "big.bin",
            "--max-ratio",
            "10",
        ],
        vec![
            "unpack",
            bomb.to_str().unwrap(),
            "-C",
            dest.to_str().unwrap(),
            "--max-ratio",
            "10",
        ],
    ] {
        let out = Command::new(STUFFR).args(&args).output().unwrap();
        assert_eq!(
            out.status.code(),
            Some(6),
            "`stuffr {}` must refuse the same bomb the other verbs refuse; stderr: {}",
            args[0],
            String::from_utf8_lossy(&out.stderr)
        );
    }

    // The other half: the default ratio still lets the same archive through
    // on all three, so the new bound is not simply refusing everything.
    let _ = std::fs::remove_dir_all(&dest);
    for args in [
        vec!["test", bomb.to_str().unwrap()],
        vec!["cat", bomb.to_str().unwrap(), "big.bin"],
        vec![
            "unpack",
            bomb.to_str().unwrap(),
            "-C",
            dest.to_str().unwrap(),
        ],
    ] {
        let out = Command::new(STUFFR).args(&args).output().unwrap();
        assert!(
            out.status.success(),
            "`stuffr {}` must still accept a legitimate archive under the default ratio; \
             stderr: {}",
            args[0],
            String::from_utf8_lossy(&out.stderr)
        );
    }
}

/// The Phase 2 re-review's second finding: the pipe path refused every real
/// archive.
///
/// `ArchiveBudget::ceiling` returned a flat `RATIO_FLOOR` (1 MiB) whenever
/// the compressed total was unknown, which is always true of a pipe — so
/// `cat photos.zip | stuffr test -` refused any archive over a megabyte, and
/// `--max-ratio`, the flag the refusal names, could not raise it. The
/// examples page documents that exact invocation. `test` acquired the defect
/// when it gained a budget; `cat` and `unpack -C` had carried it since the
/// budget was introduced.
///
/// The fix gives the ratio a denominator on a pipe: bytes actually pulled so
/// far, which `open_archive`'s `Counting` wrapper already tallies. All three
/// assertions below are needed — one that a real archive passes, one that a
/// bomb is still refused, and one that raising the flag now changes the
/// outcome, which is what proves the flag reaches this path at all.
#[test]
fn a_piped_archive_larger_than_the_ratio_floor_is_not_refused() {
    let dir = tmp_dir();
    // Incompressible, so no codec layer can mask the size, and comfortably
    // past the 1 MiB floor.
    let payload: Vec<u8> = (0..3u32 * 1024 * 1024).map(|i| (i % 251) as u8).collect();
    let src = dir.join("big.bin");
    std::fs::write(&src, &payload).unwrap();
    let archive = dir.join("big.tar");
    assert!(
        Command::new(STUFFR)
            .args([
                "pack",
                src.to_str().unwrap(),
                "-o",
                archive.to_str().unwrap()
            ])
            .status()
            .unwrap()
            .success()
    );
    let bytes = std::fs::read(&archive).unwrap();
    assert!(
        bytes.len() as u64 > stuffr::RATIO_FLOOR,
        "the fixture must exceed the floor or this test proves nothing"
    );

    // Feed stdin from a THREAD, never inline. `stuffr cat - big.bin` writes
    // the 3 MB entry straight back to stdout, and an inline `write_all` here
    // deadlocks the moment that fills the 64 KB pipe buffer: the child blocks
    // writing stdout while this process blocks writing stdin, and neither
    // moves. `wait_with_output` drains stdout and stderr concurrently, so the
    // writer only needs to be off this thread. (Learned the hard way — this
    // hung the gate for 26 minutes.)
    let piped = |args: &[&str], input: &[u8]| {
        let mut child = Command::new(STUFFR)
            .args(args)
            .stdin(Stdio::piped())
            .stdout(Stdio::piped())
            .stderr(Stdio::piped())
            .spawn()
            .unwrap();
        let mut sin = child.stdin.take().unwrap();
        let data = input.to_vec();
        // A refusal closes the pipe early, so a broken pipe is an expected
        // outcome here rather than a test failure.
        let writer = std::thread::spawn(move || {
            let _ = sin.write_all(&data);
        });
        let out = child.wait_with_output().unwrap();
        writer.join().unwrap();
        out
    };

    let dest = dir.join("out");
    for args in [
        vec!["test", "-"],
        vec!["cat", "-", "big.bin"],
        vec!["unpack", "-", "-C", dest.to_str().unwrap()],
    ] {
        let out = piped(&args, &bytes);
        assert!(
            out.status.success(),
            "`stuffr {}` over a pipe must not refuse a {}-byte archive; stderr: {}",
            args.join(" "),
            bytes.len(),
            String::from_utf8_lossy(&out.stderr)
        );
    }

    // The bound is still real over a pipe. Same fixture shape as
    // `every_entry_aware_verb_applies_the_same_expansion_bound`, piped.
    let zeros = vec![0u8; 8 * 1024 * 1024];
    let zsrc = dir.join("zeros.bin");
    std::fs::write(&zsrc, &zeros).unwrap();
    let bomb = dir.join("bomb.zip");
    assert!(
        Command::new(STUFFR)
            .args(["pack", zsrc.to_str().unwrap(), "-o", bomb.to_str().unwrap()])
            .status()
            .unwrap()
            .success()
    );
    let bomb_bytes = std::fs::read(&bomb).unwrap();

    let piped_test = |extra: &[&str]| {
        let mut argv = vec!["test", "-"];
        argv.extend_from_slice(extra);
        piped(&argv, &bomb_bytes)
    };

    assert_eq!(
        piped_test(&["--max-ratio", "10"]).status.code(),
        Some(6),
        "a bomb piped in must still be refused"
    );
    assert!(
        piped_test(&["--max-ratio", "100000"]).status.success(),
        "raising --max-ratio must change the outcome on a pipe — that is what \
         proves the flag reaches this path rather than being parsed and dropped"
    );
}

/// The Phase 2 final review's I6, at the exit-code boundary a user sees.
///
/// A valid `odc` cpio archive reported `archive is corrupt: Invalid magic
/// number` at exit 5 — telling the user their intact file was damaged.
#[test]
fn a_valid_odc_cpio_archive_reports_a_capability_limit_not_corruption() {
    let dir = tmp_dir();
    // A real `newc` archive with only its magic rewritten to odc's, so the
    // classification is provably decided on the magic. `cpio.rs`'s own
    // `a_real_odc_archive_from_system_cpio_is_unsupported_not_corrupt`
    // proves that magic is what the reference tool actually emits.
    let src = dir.join("f.txt");
    std::fs::write(&src, b"payload").unwrap();
    let newc = dir.join("archive.cpio");
    assert!(
        Command::new(STUFFR)
            .args(["pack", src.to_str().unwrap(), "-o", newc.to_str().unwrap()])
            .status()
            .unwrap()
            .success()
    );
    let mut bytes = std::fs::read(&newc).unwrap();
    assert_eq!(&bytes[..6], b"070701");
    bytes[..6].copy_from_slice(b"070707");
    let odc = dir.join("odc.cpio");
    std::fs::write(&odc, &bytes).unwrap();

    let out = Command::new(STUFFR)
        .args(["list", odc.to_str().unwrap()])
        .output()
        .unwrap();
    let stderr = String::from_utf8_lossy(&out.stderr).to_string();
    assert_eq!(
        out.status.code(),
        Some(3),
        "an intact archive in an unreadable variant is a capability limit, \
         not damage; stderr: {stderr}"
    );
    assert!(
        stderr.contains("odc"),
        "the message must name the variant: {stderr}"
    );
    assert!(
        !stderr.contains("corrupt"),
        "the message must not suggest damage: {stderr}"
    );

    // The neighbour it must not have swallowed: a genuinely damaged newc
    // archive is still exit 5.
    let mut broken = std::fs::read(&newc).unwrap();
    broken.truncate(30);
    let cut = dir.join("cut.cpio");
    std::fs::write(&cut, &broken).unwrap();
    let out = Command::new(STUFFR)
        .args(["list", cut.to_str().unwrap()])
        .output()
        .unwrap();
    assert_eq!(
        out.status.code(),
        Some(5),
        "a truncated archive really is damaged; stderr: {}",
        String::from_utf8_lossy(&out.stderr)
    );
}

/// "You pointed the verb at the wrong file" must be ONE exit code.
///
/// `stuffr list plain.txt.gz` (a codec stream, `NotAnArchive`) exited 2
/// while `stuffr list plain.txt` (no format at all, `UnknownFormat`) exited
/// 1 — an internal failure — for the same class of mistake.
#[test]
fn pointing_a_verb_at_the_wrong_file_always_exits_two() {
    let dir = tmp_dir();

    let plain = dir.join("plain.txt");
    std::fs::write(&plain, b"just some text, no format at all").unwrap();
    let gz = dir.join("plain.txt.gz");
    assert!(
        Command::new(STUFFR)
            .args([
                "pack",
                plain.to_str().unwrap(),
                "--format",
                "gzip",
                "-o",
                gz.to_str().unwrap()
            ])
            .status()
            .unwrap()
            .success()
    );

    for (label, path) in [
        ("a codec stream, which is not an archive", &gz),
        ("a file of no recognised format", &plain),
    ] {
        let out = Command::new(STUFFR)
            .args(["list", path.to_str().unwrap()])
            .output()
            .unwrap();
        assert_eq!(
            out.status.code(),
            Some(2),
            "{label}: both are the caller pointing `list` at the wrong file, \
             so both are exit 2; stderr: {}",
            String::from_utf8_lossy(&out.stderr)
        );
    }
}

/// The Phase 2 final review's I5: three multi-line string literals in
/// `main.rs` had been collapsed with their continuation indentation left
/// in, so users saw runs of 22-30 spaces mid-sentence:
///
/// ```text
/// stuffr: usage error: packing 2 paths needs an output naming a container
/// (`-o bundle.tar`,                      or --format tar); a codec …
/// ```
///
/// All three were on new container paths and nothing asserted on any of
/// them. Asserted structurally rather than by exact text, so rewording a
/// message does not break the test but re-introducing the defect does.
///
/// These three cases are RENDERED evidence — real stderr from a real process —
/// and they are deliberately kept, but they are no longer the guard: three
/// hardcoded invocations could not cover a message a later task adds, and in
/// Phase 2c exactly that happened. See
/// `no_message_literal_in_the_workspace_carries_a_run_of_collapsed_indentation`
/// for the enumeration nothing can escape.
#[test]
fn no_cli_message_contains_a_run_of_collapsed_indentation() {
    let dir = tmp_dir();
    let a = dir.join("a.txt");
    let b = dir.join("b.txt");
    std::fs::write(&a, b"alpha").unwrap();
    std::fs::write(&b, b"beta").unwrap();
    let archive = write_fixture_tar(&dir, &[("x.txt", b"x")]);

    let cases: Vec<Vec<String>> = vec![
        // "packing N paths needs an output naming a container…"
        vec![
            "pack".into(),
            a.to_str().unwrap().into(),
            b.to_str().unwrap().into(),
        ],
        // "collecting several paths into an archive needs an explicit -o…"
        vec![
            "pack".into(),
            a.to_str().unwrap().into(),
            b.to_str().unwrap().into(),
            "--format".into(),
            "tar".into(),
        ],
        // "`x.txt` names an archive entry; pass -C DIR…"
        vec![
            "unpack".into(),
            archive.to_str().unwrap().into(),
            "x.txt".into(),
        ],
    ];

    for args in cases {
        let out = Command::new(STUFFR).args(&args).output().unwrap();
        let stderr = String::from_utf8_lossy(&out.stderr).to_string();
        assert_eq!(
            out.status.code(),
            Some(2),
            "`stuffr {}` must be a usage error; stderr: {stderr}",
            args.join(" ")
        );
        assert!(
            !stderr.contains("   "),
            "a CLI message must not carry a run of collapsed continuation \
             indentation; `stuffr {}` printed: {stderr:?}",
            args.join(" ")
        );
        assert!(
            !stderr.trim().is_empty(),
            "and it must actually say something: {stderr:?}"
        );
    }

    // The exact shape of the worst one, pinned so a reworded message that
    // re-collapses is still caught by a human reading the failure.
    let out = Command::new(STUFFR)
        .args(["pack", a.to_str().unwrap(), b.to_str().unwrap()])
        .output()
        .unwrap();
    let stderr = String::from_utf8_lossy(&out.stderr).to_string();
    assert!(
        stderr.contains("`-o bundle.tar`, or --format tar"),
        "the phrase either side of the old collapse must read as one sentence: {stderr:?}"
    );
}

/// The Phase 2c headline: a container over a codec, written in one step.
///
/// The trailer is checked with the SYSTEM tool, not our own reader. The whole
/// bug this phase fixes is a codec trailer that never got written, and our own
/// decoder may be lenient about a missing one — so asserting with `stuffr
/// list` could pass against the very defect under repair.
#[test]
fn a_container_over_a_codec_is_written_in_one_step() {
    let dir = tmp_dir();
    let src = dir.join("notes.txt");
    std::fs::write(&src, b"hello from inside the tar\n").unwrap();
    let out = dir.join("bundle.tar.gz");

    let st = Command::new(STUFFR)
        .args(["pack", src.to_str().unwrap(), "-o", out.to_str().unwrap()])
        .output()
        .unwrap();
    assert!(
        st.status.success(),
        "stderr: {}",
        String::from_utf8_lossy(&st.stderr)
    );

    // 1. It really is gzip, and the trailer is intact: `gunzip -t` verifies
    //    the CRC32 and ISIZE that the old code never wrote.
    let t = Command::new("gunzip")
        .args(["-t", out.to_str().unwrap()])
        .output()
        .unwrap();
    assert!(
        t.status.success(),
        "gunzip -t rejected it: {}",
        String::from_utf8_lossy(&t.stderr)
    );

    // 2. It really is a tar inside, per the system tar.
    let l = Command::new("tar")
        .args(["tzf", out.to_str().unwrap()])
        .output()
        .unwrap();
    assert!(
        l.status.success(),
        "tar tzf failed: {}",
        String::from_utf8_lossy(&l.stderr)
    );
    assert!(String::from_utf8_lossy(&l.stdout).contains("notes.txt"));

    // 3. And stuffr reads back what it wrote.
    let r = Command::new(STUFFR)
        .args(["list", out.to_str().unwrap()])
        .output()
        .unwrap();
    assert!(r.status.success());
    assert!(String::from_utf8_lossy(&r.stdout).contains("notes.txt"));
}

/// v0.2.0 wrote the wrong format, silently, in three different ways. Each
/// line here failed against that binary.
#[test]
fn a_dot_tar_dot_gz_output_is_never_silently_the_wrong_format() {
    let dir = tmp_dir();
    let src = dir.join("notes.txt");
    std::fs::write(&src, b"payload\n").unwrap();

    // Every spelling that means "tar inside gzip".
    for (name, extra) in [
        ("a.tar.gz", vec![]),
        ("b.tgz", vec![]),
        ("c.tar.gz", vec!["--format", "tar"]),
    ] {
        let out = dir.join(name);
        let mut args = vec!["pack", src.to_str().unwrap(), "-o", out.to_str().unwrap()];
        args.extend(extra);
        let st = Command::new(STUFFR).args(&args).output().unwrap();
        assert!(
            st.status.success(),
            "{name}: {}",
            String::from_utf8_lossy(&st.stderr)
        );

        // Must be gzip with a valid trailer...
        let t = Command::new("gunzip")
            .args(["-t", out.to_str().unwrap()])
            .output()
            .unwrap();
        assert!(
            t.status.success(),
            "{name} is not valid gzip: {}",
            String::from_utf8_lossy(&t.stderr)
        );
        // ...and a tar inside. v0.2.0 produced one or the other, never both.
        let l = Command::new("tar")
            .args(["tzf", out.to_str().unwrap()])
            .output()
            .unwrap();
        assert!(
            l.status.success(),
            "{name} has no tar inside: {}",
            String::from_utf8_lossy(&l.stderr)
        );
        assert!(
            String::from_utf8_lossy(&l.stdout).contains("notes.txt"),
            "{name}"
        );
    }
}

/// The neighbours must not regress: a codec-only output still takes the
/// single-stream path, and a container-only output still takes the bare path.
#[test]
fn a_codec_only_or_container_only_output_is_unaffected() {
    let dir = tmp_dir();
    let src = dir.join("notes.txt");
    std::fs::write(&src, b"payload\n").unwrap();

    let gz = dir.join("plain.gz");
    assert!(
        Command::new(STUFFR)
            .args(["pack", src.to_str().unwrap(), "-o", gz.to_str().unwrap()])
            .status()
            .unwrap()
            .success()
    );
    // A bare codec output is NOT a tar — decompressing gives the file itself.
    let out = Command::new("gunzip")
        .args(["-c", gz.to_str().unwrap()])
        .output()
        .unwrap();
    assert_eq!(out.stdout, b"payload\n");

    let tar = dir.join("plain.tar");
    assert!(
        Command::new(STUFFR)
            .args(["pack", src.to_str().unwrap(), "-o", tar.to_str().unwrap()])
            .status()
            .unwrap()
            .success()
    );
    let l = Command::new("tar")
        .args(["tf", tar.to_str().unwrap()])
        .output()
        .unwrap();
    assert!(String::from_utf8_lossy(&l.stdout).contains("notes.txt"));
}

/// A zip inside a codec: the shape that would have shown the stray
/// `flush_destination` in `ZipWrite::finish`, which emitted a `Z_SYNC_FLUSH`
/// empty stored block into the gzip stream before the trailer. And a bare
/// zip must still round-trip after that call was removed.
#[test]
fn a_zip_round_trips_bare_and_inside_a_codec() {
    let dir = tmp_dir();
    let src = dir.join("notes.txt");
    std::fs::write(&src, b"zip payload\n").unwrap();

    for name in ["bare.zip", "wrapped.zip.gz"] {
        let out = dir.join(name);
        let st = Command::new(STUFFR)
            .args(["pack", src.to_str().unwrap(), "-o", out.to_str().unwrap()])
            .output()
            .unwrap();
        assert!(
            st.status.success(),
            "{name}: {}",
            String::from_utf8_lossy(&st.stderr)
        );
        if name.ends_with(".gz") {
            let t = Command::new("gunzip")
                .args(["-t", out.to_str().unwrap()])
                .output()
                .unwrap();
            assert!(
                t.status.success(),
                "{name} is not valid gzip: {}",
                String::from_utf8_lossy(&t.stderr)
            );
        }
        let r = Command::new(STUFFR)
            .args(["list", out.to_str().unwrap()])
            .output()
            .unwrap();
        assert!(
            r.status.success(),
            "{name}: {}",
            String::from_utf8_lossy(&r.stderr)
        );
        assert!(
            String::from_utf8_lossy(&r.stdout).contains("notes.txt"),
            "{name}"
        );
    }
}

/// `--format` and the output's own name are two sources of truth about the
/// container, and they can disagree. Writing the file anyway is worse than
/// refusing: the bytes are valid gzip, so `pack` exits 0 and `list` on the
/// very same path then exits 5 — stuffr calling its own output corrupt, at
/// the exit code that publicly means "these bytes are damaged".
///
/// Measured at the commit that introduced composition:
/// `pack notes.txt --format zip -o x.tar.gz` wrote a zip inside gzip under a
/// `.tar.gz` name, `stuffr info` reported "tar over gzip", and `stuffr list`
/// exited 5.
#[test]
fn a_format_flag_contradicting_the_output_name_is_refused_before_anything_is_written() {
    let dir = tmp_dir();
    let src = dir.join("notes.txt");
    std::fs::write(&src, b"payload\n").unwrap();

    for (fmt, name) in [
        ("zip", "x.tar.gz"),
        ("tar", "x.zip.gz"),
        ("tar", "x.cpio"),
        ("cpio", "x.tgz"),
    ] {
        let out = dir.join(name);
        let o = Command::new(STUFFR)
            .args([
                "pack",
                src.to_str().unwrap(),
                "--format",
                fmt,
                "-o",
                out.to_str().unwrap(),
            ])
            .output()
            .unwrap();
        assert_eq!(
            o.status.code(),
            Some(2),
            "--format {fmt} -o {name} must be a usage error, not a written file"
        );
        let stderr = String::from_utf8_lossy(&o.stderr).to_string();
        assert!(
            stderr.contains(fmt) && stderr.contains(name),
            "the message must name both sides of the contradiction: {stderr:?}"
        );
        // "before anything is written" is the whole point of exit 2 here.
        assert!(!out.exists(), "--format {fmt} -o {name} left a file behind");
    }

    // The agreeing spellings are untouched, including the one where the name
    // carries only a codec and --format supplies the container.
    for (fmt, name) in [("tar", "ok.tar.gz"), ("tar", "ok.gz"), ("zip", "ok.zip.gz")] {
        let out = dir.join(name);
        let o = Command::new(STUFFR)
            .args([
                "pack",
                src.to_str().unwrap(),
                "--format",
                fmt,
                "-o",
                out.to_str().unwrap(),
            ])
            .output()
            .unwrap();
        assert!(
            o.status.success(),
            "--format {fmt} -o {name} must still work: {}",
            String::from_utf8_lossy(&o.stderr)
        );
        let l = Command::new(STUFFR)
            .args(["list", out.to_str().unwrap()])
            .output()
            .unwrap();
        assert!(
            l.status.success(),
            "stuffr must be able to read back what it wrote to {name}: {}",
            String::from_utf8_lossy(&l.stderr)
        );
        assert!(
            String::from_utf8_lossy(&l.stdout).contains("notes.txt"),
            "{name}"
        );
    }
}

/// Phase 2c used to hardcode the composed path's governor to `None`
/// specifically so `STUFFR_THREADS` could not succeed at what `--threads`
/// was refused for (no container compressed anything itself, so there was
/// genuinely nothing to hand a worker count to). Now that
/// `refuse_unhonoured_pack_flags` only refuses these where the resolved
/// chain has NO codec layer, `-o out.tar.xz` names a real codec underneath
/// the container, and `entries::create_archive` builds its governor from
/// `ops::resolved_budget(o)` exactly as the single-stream path does —
/// which means `STUFFR_THREADS` is consulted here now, precisely because
/// `--threads` is honoured here now. The two must not drift apart again.
///
/// This is the reproducibility promise working the other way: a
/// multi-threaded xz encode splits the input per worker, so the same input
/// and the same flags now produce DIFFERENT bytes under a different
/// `STUFFR_THREADS` — where before the fix they were, wrongly, identical.
#[test]
fn the_composed_path_honours_stuffr_threads_now_that_a_codec_is_present() {
    let dir = tmp_dir();
    let src = dir.join("big.txt");
    // Compressible but not trivially so, and large enough that xz would
    // really split it across workers.
    let mut data = Vec::with_capacity(4 << 20);
    let mut x: u32 = 0x1234_5678;
    while data.len() < (4 << 20) {
        x = x.wrapping_mul(1_664_525).wrapping_add(1_013_904_223);
        data.extend_from_slice(format!("line {} of the corpus\n", x >> 16).as_bytes());
    }
    std::fs::write(&src, &data).unwrap();

    let plain = dir.join("plain.tar.xz");
    let env = dir.join("env.tar.xz");
    for (out, threads) in [(&plain, None), (&env, Some("4"))] {
        let mut cmd = Command::new(STUFFR);
        cmd.args([
            "pack",
            src.to_str().unwrap(),
            "-o",
            out.to_str().unwrap(),
            "--level",
            "1",
        ]);
        match threads {
            Some(n) => cmd.env("STUFFR_THREADS", n),
            None => cmd.env_remove("STUFFR_THREADS"),
        };
        let o = cmd.output().unwrap();
        assert!(
            o.status.success(),
            "pack failed: {}",
            String::from_utf8_lossy(&o.stderr)
        );
    }
    assert_ne!(
        std::fs::read(&plain).unwrap(),
        std::fs::read(&env).unwrap(),
        "STUFFR_THREADS=4 must now change the bytes on a composed write with a codec \
         layer, the same way it already does on a single-stream one; identical bytes \
         here means the governor silently went back to None"
    );

    // And the flag it mirrors is honoured directly too, not just the
    // variable behind it — the two stay consistent by construction, but
    // both are worth asserting since either could regress independently.
    let flagged = Command::new(STUFFR)
        .args([
            "pack",
            src.to_str().unwrap(),
            "-o",
            dir.join("flag.tar.xz").to_str().unwrap(),
            "--threads",
            "4",
        ])
        .output()
        .unwrap();
    assert!(
        flagged.status.success(),
        "--threads must be honoured where a codec is present: {}",
        String::from_utf8_lossy(&flagged.stderr)
    );
}

/// Phase 2's minor 4 refused --threads whenever the output named a container,
/// reasoning that no container compresses anything itself. Composition makes
/// that false: `-o out.tar.xz` HAS a codec layer, and xz encodes in parallel.
#[test]
fn encoder_flags_are_refused_only_where_there_is_no_codec_to_honour_them() {
    let dir = tmp_dir();
    let src = dir.join("notes.txt");
    std::fs::write(&src, b"payload\n").unwrap();

    // Bare container: still refused, still exit 2.
    let st = Command::new(STUFFR)
        .args([
            "pack",
            src.to_str().unwrap(),
            "-o",
            dir.join("a.tar").to_str().unwrap(),
            "--threads",
            "2",
        ])
        .output()
        .unwrap();
    assert_eq!(
        st.status.code(),
        Some(2),
        "a bare container has no codec to hand threads to"
    );

    // Container over codec: accepted.
    let out = dir.join("b.tar.gz");
    let st = Command::new(STUFFR)
        .args([
            "pack",
            src.to_str().unwrap(),
            "-o",
            out.to_str().unwrap(),
            "--threads",
            "2",
        ])
        .output()
        .unwrap();
    assert!(
        st.status.success(),
        "a composed write HAS a codec: {}",
        String::from_utf8_lossy(&st.stderr)
    );
    assert!(
        Command::new("gunzip")
            .args(["-t", out.to_str().unwrap()])
            .status()
            .unwrap()
            .success()
    );

    // --level likewise reaches the codec layer — and this is asserted on the
    // BYTES, not on exit 0 plus `gunzip -t`, which is what it used to be.
    // Deleting `level: o.level` from the `EncodeOpts` that
    // `entries::create_archive` builds left the old form entirely green: both
    // levels still exited 0 and both still gunzipped. The only evidence that
    // the flag reached the encoder is that the two levels produce DIFFERENT
    // output, so that is what is checked.
    //
    // A payload with real structure, not `notes.txt`'s eight bytes: gzip
    // levels are indistinguishable on input too small or too uniform for the
    // match finder's effort to matter.
    let big = dir.join("big.txt");
    let mut payload = String::new();
    for i in 0..4000 {
        payload.push_str(&format!(
            "line {i} of a log with some repeated shape {}\n",
            i % 97
        ));
    }
    std::fs::write(&big, payload.as_bytes()).unwrap();

    let mut sizes = Vec::new();
    for level in ["1", "9"] {
        let out = dir.join(format!("c{level}.tar.gz"));
        assert!(
            Command::new(STUFFR)
                .args([
                    "pack",
                    big.to_str().unwrap(),
                    "-o",
                    out.to_str().unwrap(),
                    "--level",
                    level,
                ])
                .status()
                .unwrap()
                .success(),
            "--level {level} must be accepted on a composed write"
        );
        assert!(
            Command::new("gunzip")
                .args(["-t", out.to_str().unwrap()])
                .status()
                .unwrap()
                .success(),
            "--level {level} must still produce valid gzip"
        );
        sizes.push(std::fs::metadata(&out).unwrap().len());
    }
    assert!(
        sizes[0] > sizes[1],
        "--level must reach the codec beneath the container: level 1 produced \
         {} bytes and level 9 produced {} — equal sizes mean the flag was \
         accepted and dropped",
        sizes[0],
        sizes[1]
    );

    // And the single-stream codec path is untouched.
    assert!(
        Command::new(STUFFR)
            .args([
                "pack",
                src.to_str().unwrap(),
                "-o",
                dir.join("d.gz").to_str().unwrap(),
                "--threads",
                "2",
            ])
            .status()
            .unwrap()
            .success()
    );
}

// ---------------------------------------------------------------------
// Phase 2c: `pack` walks a directory tree, and says what walking it lost.
// ---------------------------------------------------------------------

#[test]
fn pack_walks_a_directory_and_round_trips_it() {
    let dir = tmp_dir();
    let root = dir.join("proj");
    std::fs::create_dir_all(root.join("src")).unwrap();
    std::fs::create_dir(root.join("empty")).unwrap();
    std::fs::write(root.join("README.md"), b"readme").unwrap();
    std::fs::write(root.join("src/main.rs"), b"fn main() {}").unwrap();

    let out = dir.join("p.tar");
    let st = Command::new(STUFFR)
        .args(["pack", root.to_str().unwrap(), "-o", out.to_str().unwrap()])
        .output()
        .unwrap();
    assert!(
        st.status.success(),
        "stderr: {}",
        String::from_utf8_lossy(&st.stderr)
    );

    let back = dir.join("back");
    assert!(
        Command::new(STUFFR)
            .args([
                "unpack",
                out.to_str().unwrap(),
                "-C",
                back.to_str().unwrap()
            ])
            .status()
            .unwrap()
            .success()
    );

    assert_eq!(
        std::fs::read(back.join("proj/README.md")).unwrap(),
        b"readme"
    );
    assert_eq!(
        std::fs::read(back.join("proj/src/main.rs")).unwrap(),
        b"fn main() {}"
    );
    assert!(
        back.join("proj/empty").is_dir(),
        "an empty directory must survive the round trip"
    );
}

/// A directory INSIDE a codec, in one command — the milestone's own headline
/// (`stuffr pack proj -o backup.tar.gz`), which needs the walk and the
/// composed write together.
#[test]
fn pack_walks_a_directory_into_a_container_inside_a_codec() {
    let dir = tmp_dir();
    let root = dir.join("proj");
    std::fs::create_dir_all(root.join("src")).unwrap();
    std::fs::write(root.join("src/main.rs"), b"fn main() {}").unwrap();

    let out = dir.join("backup.tar.gz");
    let st = Command::new(STUFFR)
        .args(["pack", root.to_str().unwrap(), "-o", out.to_str().unwrap()])
        .output()
        .unwrap();
    assert!(
        st.status.success(),
        "stderr: {}",
        String::from_utf8_lossy(&st.stderr)
    );

    let back = dir.join("back");
    assert!(
        Command::new(STUFFR)
            .args([
                "unpack",
                out.to_str().unwrap(),
                "-C",
                back.to_str().unwrap()
            ])
            .status()
            .unwrap()
            .success()
    );
    assert_eq!(
        std::fs::read(back.join("proj/src/main.rs")).unwrap(),
        b"fn main() {}"
    );
}

#[cfg(unix)]
#[test]
fn pack_stores_a_symlink_inside_a_directory_rather_than_following_it() {
    let dir = tmp_dir();
    let root = dir.join("proj");
    std::fs::create_dir(&root).unwrap();
    std::fs::write(root.join("real.txt"), b"real").unwrap();
    std::os::unix::fs::symlink("real.txt", root.join("link.txt")).unwrap();

    let out = dir.join("p.tar");
    assert!(
        Command::new(STUFFR)
            .args(["pack", root.to_str().unwrap(), "-o", out.to_str().unwrap()])
            .status()
            .unwrap()
            .success()
    );

    // The system tar must agree it is a link, not a second copy. Its absence
    // panics rather than skipping: the repo's reference-tool convention (see
    // `lzip.rs`'s `require_lzip`) is that failing loudly beats proving
    // nothing, and CI installs tar unconditionally.
    let l = Command::new("tar")
        .args(["tvf", out.to_str().unwrap()])
        .output()
        .expect("the system `tar` is this test's reference authority");
    let text = String::from_utf8_lossy(&l.stdout);
    assert!(
        text.contains("link.txt -> real.txt"),
        "tar tvf said: {text}"
    );
}

/// The opposite rule, and the reason the two must not be unified: a symlink
/// NAMED on the command line is followed, because storing the link itself
/// would let `pack` write an archive `unpack` then refuses at exit 7.
#[cfg(unix)]
#[test]
fn pack_follows_a_symlink_named_on_the_command_line() {
    let dir = tmp_dir();
    std::fs::write(dir.join("real.txt"), b"real").unwrap();
    std::os::unix::fs::symlink("real.txt", dir.join("link.txt")).unwrap();

    let out = dir.join("named.tar");
    assert!(
        Command::new(STUFFR)
            .args([
                "pack",
                dir.join("link.txt").to_str().unwrap(),
                "-o",
                out.to_str().unwrap()
            ])
            .status()
            .unwrap()
            .success()
    );

    let back = dir.join("back");
    assert!(
        Command::new(STUFFR)
            .args([
                "unpack",
                out.to_str().unwrap(),
                "-C",
                back.to_str().unwrap()
            ])
            .status()
            .unwrap()
            .success()
    );
    assert_eq!(
        std::fs::read(back.join("link.txt")).unwrap(),
        b"real",
        "a named symlink is followed, so the entry holds the target's bytes"
    );
}

#[test]
fn packing_a_directory_into_a_container_that_cannot_hold_it_warns_rather_than_refusing() {
    // `ar` has no directory concept at all. Refusing would be the tenth
    // instance of this project's signature defect; warning is honest.
    let dir = tmp_dir();
    let root = dir.join("proj");
    std::fs::create_dir_all(root.join("sub")).unwrap();
    std::fs::write(root.join("sub/a.txt"), b"a").unwrap();

    let out = dir.join("p.a");
    let st = Command::new(STUFFR)
        .args(["pack", root.to_str().unwrap(), "-o", out.to_str().unwrap()])
        .output()
        .unwrap();
    assert!(
        st.status.success(),
        "must not refuse: {}",
        String::from_utf8_lossy(&st.stderr)
    );
    let err = String::from_utf8_lossy(&st.stderr);
    // The DROPPED ENTRY'S NAME, not the word "fidelity". The pack summary
    // line carries a loss count on every successful pack, warnings or none,
    // so an assertion on that word passes against an implementation with the
    // whole warnings vector deleted — which is exactly what it was before
    // this was caught. Naming `proj/sub` is the property this test claims to
    // test.
    assert!(
        err.contains("proj/sub"),
        "it must SAY WHAT it dropped, by name; stderr: {err}"
    );

    // And --strict-fidelity turns that into a refusal, as it does on read.
    let out2 = dir.join("p2.a");
    let st2 = Command::new(STUFFR)
        .args([
            "pack",
            root.to_str().unwrap(),
            "-o",
            out2.to_str().unwrap(),
            "--strict-fidelity",
        ])
        .output()
        .unwrap();
    assert_eq!(
        st2.status.code(),
        Some(4),
        "strict fidelity must exit 4 on the write side too"
    );
}

/// The flag must not fire on a clean pack. A gate that always trips is a gate
/// nobody leaves on.
///
/// The tree carries a SYMLINK, and that is the case worth pinning rather than
/// an afterthought: `README.md:35` records that `--strict-fidelity` "fails on
/// essentially any tarball containing a symlink" on the READ side, because a
/// symlink's mtime cannot be restored without following the link (`std` has no
/// `lutimes`). The write side has no such limit — tar stores the link, target
/// and all, and loses nothing — so the two sides disagree about the same tree
/// on purpose, and this is the half most likely to be "fixed" into a refusal
/// by someone reading only the README.
#[test]
fn strict_fidelity_passes_on_a_pack_that_lost_nothing() {
    let dir = tmp_dir();
    let root = dir.join("proj");
    std::fs::create_dir_all(root.join("src")).unwrap();
    std::fs::write(root.join("src/main.rs"), b"fn main() {}").unwrap();
    #[cfg(unix)]
    std::os::unix::fs::symlink("main.rs", root.join("src/alias.rs")).unwrap();

    let archive = dir.join("clean.tar");
    let st = Command::new(STUFFR)
        .args([
            "pack",
            root.to_str().unwrap(),
            "-o",
            archive.to_str().unwrap(),
            "--strict-fidelity",
        ])
        .output()
        .unwrap();
    assert!(
        st.status.success(),
        "an ordinary tree into tar loses nothing, symlink included: {}",
        String::from_utf8_lossy(&st.stderr)
    );

    // And the symlink really is IN there, as a link. Without this the test
    // above would pass just as happily against a walk that dropped it —
    // strict fidelity cannot complain about an entry nobody tried to store.
    #[cfg(unix)]
    {
        let listed = Command::new("tar")
            .args(["tvf", archive.to_str().unwrap()])
            .output()
            .expect("the system `tar` is this test's reference authority");
        let text = String::from_utf8_lossy(&listed.stdout);
        assert!(
            text.contains("alias.rs -> main.rs"),
            "the symlink must be stored as a link, not dropped or copied: {text}"
        );
    }
}

/// The walk names entries beneath the root's own final component, so two
/// directories with the same name collide before anything is written — the
/// same rule two identically-named files have always had.
#[test]
fn two_directories_with_the_same_final_component_are_refused_before_writing() {
    let dir = tmp_dir();
    std::fs::create_dir_all(dir.join("a/proj")).unwrap();
    std::fs::create_dir_all(dir.join("b/proj")).unwrap();
    std::fs::write(dir.join("a/proj/x.txt"), b"x").unwrap();
    std::fs::write(dir.join("b/proj/y.txt"), b"y").unwrap();

    let out = dir.join("dup.tar");
    let st = Command::new(STUFFR)
        .args([
            "pack",
            dir.join("a/proj").to_str().unwrap(),
            dir.join("b/proj").to_str().unwrap(),
            "-o",
            out.to_str().unwrap(),
        ])
        .output()
        .unwrap();
    assert_eq!(
        st.status.code(),
        Some(2),
        "a name collision is a usage error"
    );
    assert!(
        !out.exists(),
        "nothing may be written: the refusal happens before the destination is opened"
    );
}
/// `stuffr pack . -o x.tar` — the single most common archiving idiom there
/// is, and what `tar cf x.tar .` teaches. `Path::file_name` returns `None`
/// for `.`, which used to make this exit 2 at the naming step, before the
/// walk this phase added ever ran.
#[test]
fn pack_of_dot_names_entries_after_the_directory_it_resolves_to() {
    let dir = tmp_dir();
    let root = dir.join("proj");
    std::fs::create_dir_all(root.join("src")).unwrap();
    std::fs::write(root.join("src/main.rs"), b"fn main() {}").unwrap();

    let out = dir.join("dot.tar");
    let st = Command::new(STUFFR)
        .current_dir(&root)
        .args(["pack", ".", "-o", out.to_str().unwrap()])
        .output()
        .unwrap();
    assert!(
        st.status.success(),
        "`pack .` must work: {}",
        String::from_utf8_lossy(&st.stderr)
    );

    let listed = run_output(&["list", out.to_str().unwrap()]);
    let text = String::from_utf8_lossy(&listed.stdout);
    assert!(
        text.contains("proj/src/main.rs"),
        "`.` resolves to its canonical final component, so entries sit under \
         `proj/` exactly as `pack ../proj` would name them: {text}"
    );
}

/// The same rule one level up. `..` from `proj/src` is `proj`, so the entries
/// are named the same way `pack proj` names them — the final-component rule
/// applied consistently rather than a special case bolted onto `.`.
#[test]
fn pack_of_dotdot_names_entries_after_the_parent_it_resolves_to() {
    let dir = tmp_dir();
    let root = dir.join("proj");
    std::fs::create_dir_all(root.join("src")).unwrap();
    std::fs::write(root.join("src/main.rs"), b"fn main() {}").unwrap();

    let out = dir.join("dotdot.tar");
    let st = Command::new(STUFFR)
        .current_dir(root.join("src"))
        .args(["pack", "..", "-o", out.to_str().unwrap()])
        .output()
        .unwrap();
    assert!(
        st.status.success(),
        "`pack ..` must work: {}",
        String::from_utf8_lossy(&st.stderr)
    );

    let listed = run_output(&["list", out.to_str().unwrap()]);
    let text = String::from_utf8_lossy(&listed.stdout);
    assert!(
        text.contains("proj/src/main.rs"),
        "`..` must name entries after the directory it resolves to: {text}"
    );
}

/// A trailing slash is noise, and `Path::file_name` already reads `proj/` as
/// `proj`. Pinned anyway: a hand-rolled "split on `/`, take the last" — the
/// obvious way to rewrite this function — yields an EMPTY name here, and an
/// archive of entries named `/src/main.rs` is one stuffr itself refuses to
/// extract at exit 7.
#[test]
fn a_trailing_slash_on_a_packed_directory_is_noise() {
    let dir = tmp_dir();
    let root = dir.join("proj");
    std::fs::create_dir_all(root.join("src")).unwrap();
    std::fs::write(root.join("src/main.rs"), b"fn main() {}").unwrap();

    let out = dir.join("slash.tar");
    let with_slash = format!("{}/", root.to_str().unwrap());
    let st = Command::new(STUFFR)
        .args(["pack", &with_slash, "-o", out.to_str().unwrap()])
        .output()
        .unwrap();
    assert!(
        st.status.success(),
        "a trailing slash must not change anything: {}",
        String::from_utf8_lossy(&st.stderr)
    );

    let listed = run_output(&["list", out.to_str().unwrap()]);
    let text = String::from_utf8_lossy(&listed.stdout);
    assert!(
        text.contains("proj/src/main.rs"),
        "entries must sit under `proj/`, not under an empty name: {text}"
    );
}

/// `stuffr pack . -o backup.tar` — `examples.txt`'s own headline idiom for
/// the directory walk — writes `backup.tar` INSIDE the directory it is
/// walking. The first run has nothing to exclude (`backup.tar` does not
/// exist until this command creates it), but a `--force` re-run walks a
/// directory that now contains the PREVIOUS run's archive; left unhandled
/// that nests the old archive inside the new one and the file grows on
/// every run. GNU tar's answer to the identical shape is `file is the
/// archive; not dumped`.
#[test]
fn pack_excludes_its_own_output_from_the_walk() {
    let dir = tmp_dir();
    let root = dir.join("proj");
    std::fs::create_dir_all(&root).unwrap();
    std::fs::write(root.join("a.txt"), b"a").unwrap();

    // First run: `backup.tar` does not exist yet, so there is nothing for
    // the walk to exclude, and the archive holds exactly `a.txt`.
    let st = Command::new(STUFFR)
        .current_dir(&root)
        .args(["pack", ".", "-o", "backup.tar"])
        .output()
        .unwrap();
    assert!(
        st.status.success(),
        "stderr: {}",
        String::from_utf8_lossy(&st.stderr)
    );
    let out = root.join("backup.tar");
    let first_len = std::fs::metadata(&out).unwrap().len();

    // Second run, `--force`: `backup.tar` now exists INSIDE the directory
    // being walked. If it were not excluded, this would nest the first
    // run's archive inside the second and the file would grow; if it were
    // silently dropped with no warning, `stderr` would say nothing about it.
    let st = Command::new(STUFFR)
        .current_dir(&root)
        .args(["pack", ".", "-o", "backup.tar", "--force"])
        .output()
        .unwrap();
    assert!(
        st.status.success(),
        "stderr: {}",
        String::from_utf8_lossy(&st.stderr)
    );
    // The EXCLUDED ENTRY'S NAME, not the word "fidelity" — the pack summary
    // line prints a count on every successful pack regardless, so asserting
    // on the word alone would pass even with the whole reporting deleted.
    let err = String::from_utf8_lossy(&st.stderr);
    assert!(
        err.contains("proj/backup.tar"),
        "it must SAY WHAT it excluded, by name; stderr: {err}"
    );
    let second_len = std::fs::metadata(&out).unwrap().len();
    assert_eq!(
        first_len, second_len,
        "a --force re-run must not nest the previous archive inside the new one"
    );

    let listed = run_output(&["list", out.to_str().unwrap()]);
    let text = String::from_utf8_lossy(&listed.stdout);
    assert!(
        !text.contains("backup.tar"),
        "the archive must not contain an entry naming itself: {text}"
    );
    assert!(
        text.contains("proj/a.txt"),
        "everything else in the directory is still stored: {text}"
    );

    // And a THIRD run, `--force --strict-fidelity`, stays GREEN. This
    // assertion was `Some(4)` until the Phase 2c final review: a fidelity
    // warning means "you lost something you asked for", and stuffr declining
    // to put a file inside itself is not that — it is stuffr being correct.
    // Gating on it made the nightly-backup shape `examples.txt` advertises
    // exit 4 on every run after the first, forever, which is a gate nobody
    // keeps. See `excluding_the_output_from_its_own_walk_is_a_note_not_a_
    // fidelity_loss`, which owns the property; this run only pins that the
    // verdict did not drift back.
    let st3 = Command::new(STUFFR)
        .current_dir(&root)
        .args([
            "pack",
            ".",
            "-o",
            "backup.tar",
            "--force",
            "--strict-fidelity",
        ])
        .output()
        .unwrap();
    assert_eq!(
        st3.status.code(),
        Some(0),
        "excluding the archive from its own walk costs no fidelity, so the strict \
         gate must not fire on it: {}",
        String::from_utf8_lossy(&st3.stderr)
    );
}

/// The hole the two rulings above left between them, measured through the
/// binary rather than the library.
///
/// Excluding the output from its own walk is right; recasting that exclusion
/// from a fidelity warning to a note is right. Together they meant that when
/// the output was the ONLY thing named, `pack` walked nothing, wrote an empty
/// 1024-byte tar over a healthy one, and `--strict-fidelity` — the strongest
/// gate this tool has — reported it clean at exit 0.
///
/// It is now `Error::Usage`, exit 2, raised while the plan is still being
/// built and before `dst.create` opens anything. That ordering is the whole
/// benefit and is what the byte-identity assertion below pins: a warning
/// would have let the empty archive replace the good one first, which is the
/// actual harm. Exit code alone would not have caught it.
#[test]
fn pack_refuses_when_the_only_input_is_the_output_and_leaves_it_untouched() {
    let dir = tmp_dir();
    let root = dir.join("backups");
    std::fs::create_dir_all(&root).unwrap();
    std::fs::write(root.join("data.txt"), b"last night's data").unwrap();

    // A healthy archive, written the ordinary way.
    let st = Command::new(STUFFR)
        .current_dir(&root)
        .args(["pack", "data.txt", "-o", "backup.tar"])
        .output()
        .unwrap();
    assert!(
        st.status.success(),
        "stderr: {}",
        String::from_utf8_lossy(&st.stderr)
    );
    let archive = root.join("backup.tar");
    let before = std::fs::read(&archive).unwrap();
    assert!(
        before.len() > 1024,
        "the fixture must be a real archive, not an empty one: {} bytes",
        before.len()
    );

    // The reproduction, verbatim.
    let st = Command::new(STUFFR)
        .current_dir(&root)
        .args([
            "pack",
            "backup.tar",
            "-o",
            "backup.tar",
            "--force",
            "--strict-fidelity",
        ])
        .output()
        .unwrap();
    let err = String::from_utf8_lossy(&st.stderr);
    assert_eq!(
        st.status.code(),
        Some(2),
        "an empty plan is a usage refusal, not a successful empty archive: {err}"
    );
    assert!(
        err.contains("nothing to pack") && err.contains("backup.tar"),
        "the refusal must name the cause and the destination: {err}"
    );

    assert_eq!(
        std::fs::read(&archive).unwrap(),
        before,
        "refusing before the destination is opened means no temp file and no \
         rename, so the existing archive must be byte-identical"
    );
}

/// The same hole one step further in, measured through the binary: the shape
/// the refusal above was written FOR and did not reach.
///
/// A nightly job pointed at the directory its archive lives in. Last night's
/// archive is the directory's only member, the walk correctly leaves it out,
/// and `/backups`'s own directory entry keeps the plan non-empty — so the
/// guard did not fire, and a good archive was replaced by a 1536-byte shell
/// holding one directory entry, at exit 0, with `--strict-fidelity` calling
/// it clean. Measured on `70ca649`:
///
/// ```text
/// $ stuffr pack nb -o nb/nightly.tar --force --strict-fidelity
/// 1 path(s) -> tar (0 -> 1536 bytes, no fidelity loss)
/// stuffr: note: `nb/nightly.tar` is the archive being written …
/// exit=0   contains: nb
/// ```
///
/// The byte-identity assertion is the one that matters: an exit code alone
/// would not distinguish refusing from writing the shell and then complaining.
#[test]
fn pack_refuses_a_nightly_over_a_directory_holding_only_its_own_archive() {
    let dir = tmp_dir();
    let root = dir.join("backups");
    std::fs::create_dir_all(&root).unwrap();
    std::fs::write(dir.join("data.txt"), b"last night's data").unwrap();

    // A healthy archive of something else, sitting in `backups`.
    let st = Command::new(STUFFR)
        .current_dir(&dir)
        .args(["pack", "data.txt", "-o", "backups/nightly.tar"])
        .output()
        .unwrap();
    assert!(
        st.status.success(),
        "stderr: {}",
        String::from_utf8_lossy(&st.stderr)
    );
    let archive = root.join("nightly.tar");
    let before = std::fs::read(&archive).unwrap();

    // Tonight: the job is pointed at the directory instead.
    let st = Command::new(STUFFR)
        .current_dir(&dir)
        .args([
            "pack",
            "backups",
            "-o",
            "backups/nightly.tar",
            "--force",
            "--strict-fidelity",
        ])
        .output()
        .unwrap();
    let err = String::from_utf8_lossy(&st.stderr);
    assert_eq!(
        st.status.code(),
        Some(2),
        "a plan reduced to the directory the output was removed from is a usage \
         refusal, not an archive of one empty directory: {err}"
    );
    assert!(
        err.contains("No archive was written") && err.contains("is unchanged"),
        "the refusal must say plainly that the destination survives: {err}"
    );
    assert_eq!(
        std::fs::read(&archive).unwrap(),
        before,
        "last night's archive must be byte-identical, not replaced by a shell"
    );
}

/// The read-side half of the same session: `stuffr test` on a zip whose index
/// declares more records than the reader can reach.
///
/// `ZipArchive` collapses central-directory records that share a name, so a
/// real 8-record archive that `unzip -t` reads whole enumerated 6 entries and
/// reported "exact fidelity" at exit 0 — under `--strict-fidelity`, the
/// strongest gate this tool has. The fixture is built here rather than
/// depending on that file, and `zip` itself will not write this shape, so the
/// central directory is forged: a verbatim copy of the first record appended
/// to the index, with the declared count bumped to match.
#[test]
fn test_reports_a_zip_whose_index_declares_more_records_than_are_reachable() {
    let dir = tmp_dir();
    let src = dir.join("a.txt");
    std::fs::write(&src, b"alpha").unwrap();
    let zip_path = dir.join("dup.zip");
    let st = Command::new(STUFFR)
        .current_dir(&dir)
        .args(["pack", "a.txt", "-o", "dup.zip"])
        .output()
        .unwrap();
    assert!(
        st.status.success(),
        "stderr: {}",
        String::from_utf8_lossy(&st.stderr)
    );

    // A clean archive must gain nothing, or the assertions below prove only
    // that `test` prints warnings.
    let st = Command::new(STUFFR)
        .args(["test", zip_path.to_str().unwrap(), "--strict-fidelity"])
        .output()
        .unwrap();
    let err = String::from_utf8_lossy(&st.stderr);
    assert_eq!(st.status.code(), Some(0), "a clean zip is clean: {err}");
    assert!(err.contains("exact fidelity"), "and still says so: {err}");

    // Forge a second central-directory record naming the same entry.
    let mut bytes = std::fs::read(&zip_path).unwrap();
    let eocd = bytes.len() - 22;
    assert_eq!(&bytes[eocd..eocd + 4], b"PK\x05\x06", "no EOCD");
    let le16 = |b: &[u8]| u16::from_le_bytes([b[0], b[1]]);
    let cd_size = u32::from_le_bytes(bytes[eocd + 12..eocd + 16].try_into().unwrap()) as usize;
    let cd_at = u32::from_le_bytes(bytes[eocd + 16..eocd + 20].try_into().unwrap()) as usize;
    let cd = bytes[cd_at..cd_at + cd_size].to_vec();
    let first = 46 + le16(&cd[28..]) as usize + le16(&cd[30..]) as usize + le16(&cd[32..]) as usize;
    let entries = le16(&bytes[eocd + 10..]);

    let mut out = bytes[..cd_at + cd_size].to_vec();
    out.extend_from_slice(&cd[..first]);
    let tail = &mut bytes[eocd..];
    tail[8..10].copy_from_slice(&(entries + 1).to_le_bytes());
    tail[10..12].copy_from_slice(&(entries + 1).to_le_bytes());
    tail[12..16].copy_from_slice(&((cd_size + first) as u32).to_le_bytes());
    out.extend_from_slice(tail);
    let forged = dir.join("shadowed.zip");
    std::fs::write(&forged, &out).unwrap();

    let st = Command::new(STUFFR)
        .args(["test", forged.to_str().unwrap()])
        .output()
        .unwrap();
    let err = String::from_utf8_lossy(&st.stderr);
    assert_eq!(
        st.status.code(),
        Some(0),
        "a shadowed record is a fidelity loss, not corruption: {err}"
    );
    assert!(
        err.contains("declares 2") && err.contains("only 1"),
        "the warning must name both counts: {err}"
    );
    assert!(
        !err.contains("exact fidelity"),
        "a read that reached one of two records must not announce exact \
         fidelity: {err}"
    );

    let st = Command::new(STUFFR)
        .args(["test", forged.to_str().unwrap(), "--strict-fidelity"])
        .output()
        .unwrap();
    assert_eq!(
        st.status.code(),
        Some(4),
        "--strict-fidelity must refuse it: {}",
        String::from_utf8_lossy(&st.stderr)
    );
}

// ---------------------------------------------------------------------------
// Phase 2c, Task 6: the properties that would otherwise pass while being
// structurally unable to fail.
// ---------------------------------------------------------------------------

/// Locates `bin` on `PATH`.
///
/// A local copy rather than a shared helper, matching this tree's existing
/// convention: `ar.rs`, `cpio.rs`, `zip.rs` and `zip_on_a_pipe.rs` each carry
/// their own. That four-copy situation was examined in Phase 2 and accepted
/// deliberately; extracting a shared test helper is a tree-wide refactor, not
/// something to smuggle into a testing task.
fn which(bin: &str) -> Option<PathBuf> {
    let path = std::env::var_os("PATH")?;
    std::env::split_paths(&path).find_map(|dir| {
        let candidate = dir.join(bin);
        candidate.is_file().then_some(candidate)
    })
}

/// Locates `bin` on `PATH`, panicking rather than silently skipping if it is
/// absent. CI installs every tool named here (`tar` and `ar` ship with the
/// image; `.github/workflows/ci.yml` installs `cpio`, `zip` and `unzip` on all
/// three test jobs), so an absence means only a contributor's own machine
/// lacks it — and a silent `return` would report a cross-implementation test
/// as PASSING having verified nothing at all.
fn require_bin(bin: &str) -> PathBuf {
    which(bin).unwrap_or_else(|| {
        panic!(
            "no reference `{bin}` tool found on PATH — this test proved nothing, which is \
             worth knowing rather than passing silently"
        )
    })
}

/// lhasa, under EITHER of the two names its packagers give it: Homebrew
/// installs the binary as `lha`, Debian and Ubuntu install exactly one
/// binary and call it `lhasa`. Same program, different spelling, so a
/// `require_bin("lha")` here would pass on a developer's Mac and turn all
/// three CI test jobs red. `legacy/lha.rs`'s own `require_lhasa` carries the
/// evidence (package file lists, both distributions) and is the same
/// resolution; the duplication is the same one `require_bin` itself already
/// has between this file and four format modules.
fn require_lhasa() -> PathBuf {
    which("lha").or_else(|| which("lhasa")).unwrap_or_else(|| {
        panic!(
            "no reference lhasa tool found on PATH under either of its two names, `lha` \
             (Homebrew) or `lhasa` (Debian/Ubuntu) — this test proved nothing, which is worth \
             knowing rather than passing silently"
        )
    })
}

/// lhasa's banner, which carries its VERSION, so an assertion that fires on
/// a runner says which build produced it. Ubuntu noble ships lhasa 0.4.0
/// while this project's `-lhd-` guard was measured against 0.6.0 — see
/// `legacy/lha.rs`'s `lhasa_banner` for why that difference is worth one
/// line of output.
fn lhasa_banner(bin: &std::path::Path) -> String {
    let out = Command::new(bin)
        .output()
        .expect("run lhasa with no arguments for its banner");
    let text = if out.stdout.is_empty() {
        String::from_utf8_lossy(&out.stderr).into_owned()
    } else {
        String::from_utf8_lossy(&out.stdout).into_owned()
    };
    text.lines().next().unwrap_or("<no banner>").to_string()
}

/// The permission bits only. The file-type bits are not what any container
/// carries in its mode field, and comparing them would fail on the kind rather
/// than on the permissions.
#[cfg(unix)]
fn perm_bits(md: &std::fs::Metadata) -> u32 {
    use std::os::unix::fs::PermissionsExt;
    md.permissions().mode() & 0o7777
}

/// A tree fixture whose every distinguishable fact is one a container is
/// expected to carry: a nested directory, an EMPTY directory (which only a
/// directory entry can preserve), a symlink, and two files with DIFFERENT
/// modes.
///
/// Every mode is `0o600`/`0o700` deliberately: extraction tools mask restored
/// permissions with the process umask, so a fixture using `0o644`/`0o755`
/// compares equal under umask 022 and unequal under umask 077. These two have
/// no bits any umask can clear, which makes the comparison umask-independent
/// rather than passing on this machine's umask alone.
#[cfg(unix)]
fn build_reference_tree(root: &Path) {
    use std::os::unix::fs::PermissionsExt;
    std::fs::create_dir_all(root.join("sub")).unwrap();
    std::fs::create_dir(root.join("empty")).unwrap();
    std::fs::write(root.join("a.txt"), b"alpha").unwrap();
    std::fs::write(root.join("sub/b.bin"), b"\x00\xff\x00beta").unwrap();
    std::os::unix::fs::symlink("a.txt", root.join("link")).unwrap();
    for (p, mode) in [
        (root.to_path_buf(), 0o700),
        (root.join("sub"), 0o700),
        (root.join("empty"), 0o700),
        (root.join("a.txt"), 0o600),
        (root.join("sub/b.bin"), 0o600),
    ] {
        std::fs::set_permissions(&p, std::fs::Permissions::from_mode(mode)).unwrap();
    }
}

/// Everything under `root`, relative, sorted: name, kind, mode, and the file's
/// own bytes or the link's own target.
///
/// NOT just names — the whole point of the cross-implementation property is
/// that two tools agree about the CONTENTS of a tree, and a comparison of
/// names alone passes against an extractor that produced empty files with the
/// wrong modes.
///
/// A symlink's mode is deliberately omitted: `std` cannot restore one (no
/// `lchmod`), which is the same limitation `README.md` records for mtime, and
/// every tool here leaves it at the platform default.
#[cfg(unix)]
fn tree_snapshot(root: &Path) -> Vec<String> {
    let mut out = Vec::new();
    let mut stack = vec![root.to_path_buf()];
    while let Some(dir) = stack.pop() {
        for entry in std::fs::read_dir(&dir).unwrap() {
            let path = entry.unwrap().path();
            let rel = path.strip_prefix(root).unwrap().display().to_string();
            let md = std::fs::symlink_metadata(&path).unwrap();
            if md.is_symlink() {
                out.push(format!(
                    "{rel}: symlink -> {}",
                    std::fs::read_link(&path).unwrap().display()
                ));
            } else if md.is_dir() {
                out.push(format!("{rel}: dir mode {:o}", perm_bits(&md)));
                stack.push(path);
            } else {
                out.push(format!(
                    "{rel}: file mode {:o} bytes {:?}",
                    perm_bits(&md),
                    std::fs::read(&path).unwrap()
                ));
            }
        }
    }
    out.sort();
    out
}

/// Runs a reference tool, with `COPYFILE_DISABLE=1` set unconditionally.
///
/// That variable is macOS's: bsdtar stores every file's extended attributes as
/// a companion `._name` AppleDouble entry, and macOS puts a
/// `com.apple.provenance` xattr on ordinary files, so a tree written by the
/// system tar comes back with a `._` sibling for every entry and the
/// comparison below fails for a reason that has nothing to do with stuffr.
/// Linux's tar ignores the variable, so setting it always costs nothing and
/// keeps the two platforms running the same command.
fn run_tool(bin: &Path, args: &[&std::ffi::OsStr], cwd: &Path, stdin: &[u8]) -> Vec<u8> {
    let mut child = Command::new(bin)
        .args(args)
        .current_dir(cwd)
        .env("COPYFILE_DISABLE", "1")
        .stdin(Stdio::piped())
        .stdout(Stdio::piped())
        .stderr(Stdio::piped())
        .spawn()
        .unwrap();
    child.stdin.take().unwrap().write_all(stdin).unwrap();
    let out = child.wait_with_output().unwrap();
    assert!(
        out.status.success(),
        "reference tool {} {:?} failed: {}",
        bin.display(),
        args,
        String::from_utf8_lossy(&out.stderr)
    );
    out.stdout
}

/// `OsStr` borrow, so `run_tool`'s argument list can mix `&str` and `&Path`.
fn os(s: &impl AsRef<std::ffi::OsStr>) -> &std::ffi::OsStr {
    s.as_ref()
}

fn pack_ok(args: &[&std::ffi::OsStr]) -> String {
    let out = Command::new(STUFFR)
        .arg("pack")
        .args(args)
        .output()
        .unwrap();
    assert!(
        out.status.success(),
        "stuffr pack {:?} failed: {}",
        args,
        String::from_utf8_lossy(&out.stderr)
    );
    String::from_utf8_lossy(&out.stderr).to_string()
}

fn unpack_ok(archive: &Path, dest: &Path) {
    let out = Command::new(STUFFR)
        .args([
            std::ffi::OsStr::new("unpack"),
            archive.as_ref(),
            std::ffi::OsStr::new("-C"),
            dest.as_ref(),
        ])
        .output()
        .unwrap();
    assert!(
        out.status.success(),
        "stuffr unpack {} failed: {}",
        archive.display(),
        String::from_utf8_lossy(&out.stderr)
    );
}

/// Property 1 — cross-implementation, BOTH directions, per container.
///
/// "The system tool reads what we write" and "we read what it writes" are
/// different claims; Phase 2's tar work proved it. Reference tools are
/// required, never skipped: a silent skip proves nothing.
///
/// Compared as whole TREES — names, contents, modes and symlink targets — and
/// through the CLI, which is what makes this new coverage rather than a second
/// copy of `tar.rs`'s and `ar.rs`'s own byte-level cross-implementation tests:
/// those build archives in memory and never walk a directory.
///
/// `ar` gets its documented DEGRADATION asserted instead of a faithful round
/// trip, because it has no directory and no symlink entries. `cpio` (newc) is
/// in the faithful group on measurement, not on assumption: it carries
/// directories, symlinks and modes, and both directions are checked below.
#[cfg(unix)]
#[test]
fn every_container_round_trips_a_tree_against_its_reference_tool() {
    let tar_bin = require_bin("tar");
    let zip_bin = require_bin("zip");
    let unzip_bin = require_bin("unzip");
    let cpio_bin = require_bin("cpio");
    let ar_bin = require_bin("ar");

    let dir = tmp_dir();
    let tree = dir.join("tree");
    let root = tree.join("proj");
    build_reference_tree(&root);
    let want = tree_snapshot(&root);

    // The fixture itself, asserted rather than assumed: every comparison below
    // is only as strong as what the tree actually contains, and a fixture that
    // silently lost its symlink would make four of the eight comparisons
    // prove nothing.
    assert_eq!(
        want,
        vec![
            "a.txt: file mode 600 bytes [97, 108, 112, 104, 97]".to_string(),
            "empty: dir mode 700".to_string(),
            "link: symlink -> a.txt".to_string(),
            "sub/b.bin: file mode 600 bytes [0, 255, 0, 98, 101, 116, 97]".to_string(),
            "sub: dir mode 700".to_string(),
        ],
        "the fixture must carry a nested dir, an EMPTY dir, a symlink and two \
         differently-named files, or the comparisons below prove less than they claim"
    );

    // ---- tar: stuffr writes, the system tar reads ----
    let out_tar = dir.join("out.tar");
    pack_ok(&[os(&root), os(&"-o"), os(&out_tar)]);
    let back = dir.join("back-tar");
    std::fs::create_dir(&back).unwrap();
    run_tool(
        &tar_bin,
        &[os(&"-xf"), os(&out_tar), os(&"-C"), os(&back)],
        &dir,
        b"",
    );
    assert_eq!(
        tree_snapshot(&back.join("proj")),
        want,
        "the system tar read our tar back as a different tree"
    );

    // ---- tar: the system tar writes, stuffr reads ----
    let ref_tar = dir.join("ref.tar");
    run_tool(
        &tar_bin,
        &[os(&"-cf"), os(&ref_tar), os(&"proj")],
        &tree,
        b"",
    );
    let back = dir.join("back-ref-tar");
    unpack_ok(&ref_tar, &back);
    assert_eq!(
        tree_snapshot(&back.join("proj")),
        want,
        "we read a tar the system tar wrote as a different tree"
    );

    // ---- zip: stuffr writes, unzip reads ----
    let out_zip = dir.join("out.zip");
    pack_ok(&[os(&root), os(&"-o"), os(&out_zip)]);
    let back = dir.join("back-zip");
    run_tool(
        &unzip_bin,
        &[os(&"-q"), os(&out_zip), os(&"-d"), os(&back)],
        &dir,
        b"",
    );
    assert_eq!(
        tree_snapshot(&back.join("proj")),
        want,
        "unzip read our zip back as a different tree"
    );

    // ---- zip: the system zip writes, stuffr reads ----
    // `-y` stores symlinks as symlinks rather than following them; without it
    // the reverse direction would compare a copy of `a.txt` against a link and
    // fail for the fixture's reason rather than ours.
    let ref_zip = dir.join("ref.zip");
    run_tool(
        &zip_bin,
        &[os(&"-qry"), os(&ref_zip), os(&"proj")],
        &tree,
        b"",
    );
    let back = dir.join("back-ref-zip");
    unpack_ok(&ref_zip, &back);
    assert_eq!(
        tree_snapshot(&back.join("proj")),
        want,
        "we read a zip the system zip wrote as a different tree"
    );

    // ---- cpio: stuffr writes, the system cpio reads ----
    //
    // This direction is PLATFORM-DEPENDENT in what it can prove, and that is
    // not fixable from here. `newc` records an entry's kind only in its mode
    // field's `S_IFMT` bits; GNU cpio 2.15 refuses an entry carrying none
    // with `unknown file type`, skips it and exits 0 anyway, while bsdcpio
    // (libarchive — what macOS ships as `cpio`) infers a regular file and
    // extracts the archive whole. So when `require_bin("cpio")` resolves to
    // GNU cpio this comparison catches a missing `S_IFREG`, and when it
    // resolves to bsdcpio it cannot: the tree comes back identical either
    // way. That is exactly how the 0.2.0 defect survived a phase of
    // macOS-only review, red on CI's Linux runners at the first push.
    //
    // Preferring a GNU cpio is not a portable fix either — Homebrew's is
    // keg-only and not on PATH under any name. The portable proof lives
    // where the format knowledge is, as a byte-level assertion on the header
    // this test cannot see: `cpio.rs`'s
    // `a_permission_only_file_mode_gains_the_regular_file_type_bits`. What
    // remains valuable HERE is the other direction and the whole-tree
    // comparison against whichever real tool is installed.
    let out_cpio = dir.join("out.cpio");
    pack_ok(&[os(&root), os(&"-o"), os(&out_cpio)]);
    let back = dir.join("back-cpio");
    std::fs::create_dir(&back).unwrap();
    run_tool(
        &cpio_bin,
        &[os(&"-i"), os(&"-d"), os(&"--quiet")],
        &back,
        &std::fs::read(&out_cpio).unwrap(),
    );
    assert_eq!(
        tree_snapshot(&back.join("proj")),
        want,
        "the system cpio read our cpio back as a different tree"
    );

    // ---- cpio: the system cpio writes, stuffr reads ----
    // The name list comes from this test rather than from `find`, so no shell
    // and no second traversal implementation is involved.
    let names = b"proj\nproj/a.txt\nproj/empty\nproj/link\nproj/sub\nproj/sub/b.bin\n";
    let ref_cpio_bytes = run_tool(
        &cpio_bin,
        &[os(&"-o"), os(&"--format=newc"), os(&"--quiet")],
        &tree,
        names,
    );
    let ref_cpio = dir.join("ref.cpio");
    std::fs::write(&ref_cpio, &ref_cpio_bytes).unwrap();
    let back = dir.join("back-ref-cpio");
    unpack_ok(&ref_cpio, &back);
    assert_eq!(
        tree_snapshot(&back.join("proj")),
        want,
        "we read a cpio the system cpio wrote as a different tree"
    );

    // ---- ar: the documented degradation, both directions ----
    //
    // `ar` has no directory and no symlink entries at all, so a faithful tree
    // round trip is not the property — what it must do is store the regular
    // files, drop the rest, and SAY SO. Asserted against the system `ar`'s own
    // listing, not against our reader.
    //
    // The member NAMES below are platform-dependent in the same way the cpio
    // comparison above is, and for a sibling reason. In the GNU variant a
    // short name is stored with `/` as its terminator, so GNU `ar` truncates
    // an inline `proj/a.txt` to `proj` — and `proj/sub/b.bin` to `proj` as
    // well, two members with one name. macOS's `ar` reads the 16-byte field
    // whole and cannot see it. `ar.rs`'s `write_safe_identifier` forces any
    // `/`-bearing name into the BSD extended form, which BOTH tools read back
    // verbatim (measured against GNU ar 2.47 and BSD ar), so the expectation
    // below is true of either. The portable proof that it stays that way is
    // `ar.rs`'s `a_name_containing_a_slash_is_never_stored_inline`.
    let out_ar = dir.join("out.a");
    let stderr = pack_ok(&[os(&root), os(&"-o"), os(&out_ar)]);
    for dropped in ["proj/empty", "proj/link", "proj/sub"] {
        assert!(
            stderr.contains(dropped),
            "`ar` dropping `{dropped}` must be named in the fidelity report; stderr: {stderr}"
        );
    }
    let listed = run_tool(&ar_bin, &[os(&"t"), os(&out_ar)], &dir, b"");
    let mut members: Vec<String> = String::from_utf8_lossy(&listed)
        .lines()
        .map(str::to_string)
        .collect();
    members.sort();
    assert_eq!(
        members,
        vec!["proj/a.txt".to_string(), "proj/sub/b.bin".to_string()],
        "the system ar must list exactly the regular files, and nothing standing in for \
         the directories or the symlink"
    );

    // And the other direction. `rcS` rather than `rc`: macOS's `ar` runs a
    // ranlib-style index over plain files by default and then silently emits
    // an archive holding ONLY an empty `__.SYMDEF SORTED` — measured, and
    // already documented in `ar.rs`'s own `we_accept_what_system_ar_writes`.
    let ref_ar = dir.join("ref.a");
    run_tool(
        &ar_bin,
        &[os(&"rcS"), os(&ref_ar), os(&"a.txt")],
        &root,
        b"",
    );
    let back = dir.join("back-ref-ar");
    unpack_ok(&ref_ar, &back);
    assert_eq!(
        std::fs::read(back.join("a.txt")).unwrap(),
        b"alpha",
        "we read an ar the system ar wrote as different bytes"
    );
}

/// Property 2 — the same tree packed twice is byte-identical, AND the entries
/// are in sorted order.
///
/// The two halves are not the same claim, and the second is the one that
/// needed adding. Byte-identity alone asserts DETERMINISM, not ordering:
/// `read_dir` is stable within a filesystem, so deleting the sort in
/// `walk.rs` entirely leaves two consecutive packs byte-identical and this
/// property green — measured, by deleting it (see `walk.rs`'s own
/// `each_directory_level_is_sorted_regardless_of_readdir_order`, which exists
/// for exactly this reason). So the archive's own entry ORDER is asserted
/// here too, against a fixture created in reverse-alphabetical order so that
/// readdir order and sorted order provably differ.
///
/// Byte-identity is still worth its half: it is what pins the composed
/// container-inside-codec path, where a codec could introduce a timestamp of
/// its own.
#[test]
fn packing_the_same_tree_twice_produces_identical_bytes() {
    let dir = tmp_dir();
    let root = dir.join("proj");
    std::fs::create_dir_all(root.join("b")).unwrap();
    // Created in reverse-alphabetical order, so a filesystem that hands back
    // creation order (tmpfs, ext4 for a small directory) is provably not
    // handing back sorted order. The premise is asserted below rather than
    // assumed, because a filesystem that DID sort would make the ordering
    // half of this test unable to fail.
    for n in ["z.txt", "m.txt", "a.txt"] {
        std::fs::write(root.join(n), n.as_bytes()).unwrap();
    }
    std::fs::write(root.join("b/inner.txt"), b"inner").unwrap();

    let readdir_order: Vec<String> = std::fs::read_dir(&root)
        .unwrap()
        .map(|e| e.unwrap().file_name().to_string_lossy().to_string())
        .collect();
    let mut sorted = readdir_order.clone();
    sorted.sort();
    assert_ne!(
        readdir_order, sorted,
        "this filesystem hands back directory entries already sorted, so the ordering \
         assertion below could not fail; the fixture needs a name order this filesystem \
         does not reproduce"
    );

    let listing = dir.join("order.tar");
    let st = Command::new(STUFFR)
        .args([
            "pack",
            root.to_str().unwrap(),
            "-o",
            listing.to_str().unwrap(),
        ])
        .output()
        .unwrap();
    assert!(
        st.status.success(),
        "stderr: {}",
        String::from_utf8_lossy(&st.stderr)
    );
    let listed = run_output(&["list", listing.to_str().unwrap()]);
    let names: Vec<String> = String::from_utf8_lossy(&listed.stdout)
        .lines()
        .map(|l| l.split_whitespace().last().unwrap_or_default().to_string())
        .collect();
    assert_eq!(
        names,
        vec![
            "proj",
            "proj/a.txt",
            "proj/b",
            "proj/b/inner.txt",
            "proj/m.txt",
            "proj/z.txt",
        ],
        "entries must be written in sorted, depth-first order — `readdir` order was {readdir_order:?}"
    );

    for ext in ["tar", "tar.gz", "zip"] {
        let one = dir.join(format!("one.{ext}"));
        let two = dir.join(format!("two.{ext}"));
        for out in [&one, &two] {
            let st = Command::new(STUFFR)
                .args(["pack", root.to_str().unwrap(), "-o", out.to_str().unwrap()])
                .output()
                .unwrap();
            assert!(
                st.status.success(),
                "stderr: {}",
                String::from_utf8_lossy(&st.stderr)
            );
        }
        assert_eq!(
            std::fs::read(&one).unwrap(),
            std::fs::read(&two).unwrap(),
            "the same tree must pack to the same `.{ext}` bytes; readdir order is not stable"
        );
    }
}

/// Property 3 — a failed write must leave the destination unpublished, and
/// must not take an existing archive at that path down with it.
///
/// The point of the outcome temp-then-rename, and of finishing the whole chain
/// BEFORE `publish`. Two failures, at the two points a pack can fail:
///
/// 1. AFTER the destination is opened, from inside the write loop, with
///    earlier entries already in the temp file — the only state `discard`
///    exists to clean up.
/// 2. BEFORE it is opened at all — a destination directory that cannot be
///    written, which fails in `Output::create`.
///
/// Only (1) exercises the `discard` arm, and the distinction is not
/// theoretical: the read-only-directory mechanism used for (1) in the first
/// round looked obviously correct and failed inside `Output::create`, before
/// `finish` existed at all, so `discard` was structurally unreachable and the
/// property tested nothing. That is why (1) is now driven by a container
/// REFUSING an entry the destination has already begun to hold, and why the
/// report records the `discard(finish)` -> `publish(finish)` mutation that
/// proves this one does reach it.
///
/// The refusal is cpio's 4 GiB `u32` size field, reached with a SPARSE file:
/// `check_u32_size` runs "before a single byte is read or allocated" (its own
/// comment), so this costs no disk and no time. Every other candidate needs a
/// race — a file truncated between the walk's `stat` and the write would do
/// it, but nothing outside the process can schedule that window, and a test
/// that only fails when it loses a race is worse than no test.
///
/// **This test is therefore coupled to that ordering**, which is the sort of
/// coupling a later refactor breaks without noticing: if `CpioWrite::add`
/// ever stops checking the DECLARED size and checks only the buffered one,
/// this test starts reading 4 GiB off a sparse file before it fails — slow
/// enough to look like a hang, and on a filesystem without sparse support it
/// would not run at all. `cpio.rs` carries the matching note at the check.
/// Anything that moves it needs a new mechanism for reaching a mid-write
/// failure cheaply, not a faster machine.
#[cfg(unix)]
#[test]
fn a_failed_write_never_replaces_an_existing_archive() {
    use std::os::unix::fs::{MetadataExt, PermissionsExt};

    let dir = tmp_dir();
    let root = dir.join("proj");
    std::fs::create_dir(&root).unwrap();
    // Sorted first, so it is written into the temp file BEFORE the entry that
    // fails — without an entry already written, `discard` would have nothing
    // to clean up and this property would be about `create` again.
    std::fs::write(root.join("a.txt"), b"alpha").unwrap();

    let big = root.join("zbig.bin");
    let f = std::fs::File::create(&big).unwrap();
    f.set_len(u64::from(u32::MAX) + 1).unwrap();
    drop(f);
    let md = std::fs::metadata(&big).unwrap();
    assert!(
        md.len() > u64::from(u32::MAX),
        "the premise: the entry must exceed cpio's u32 size field"
    );
    assert!(
        md.blocks() * 512 < md.len(),
        "this filesystem did not make the fixture sparse ({} blocks for {} bytes); a \
         non-sparse one would write 4 GiB to disk here",
        md.blocks(),
        md.len()
    );

    let out = dir.join("existing.cpio");
    std::fs::write(&out, b"PRECIOUS EXISTING CONTENT").unwrap();

    let st = Command::new(STUFFR)
        .args([
            "pack",
            root.to_str().unwrap(),
            "-o",
            out.to_str().unwrap(),
            "--force",
        ])
        .output()
        .unwrap();
    assert_eq!(
        st.status.code(),
        Some(3),
        "an entry this container cannot express is a capability limit, exit 3; stderr: {}",
        String::from_utf8_lossy(&st.stderr)
    );
    assert_eq!(
        std::fs::read(&out).unwrap(),
        b"PRECIOUS EXISTING CONTENT",
        "a pack that failed mid-write must not have replaced the archive already there"
    );
    // Nothing half-written left behind either: the destination directory holds
    // exactly what it held before, plus nothing.
    let mut siblings: Vec<String> = std::fs::read_dir(&dir)
        .unwrap()
        .map(|e| e.unwrap().file_name().to_string_lossy().to_string())
        .collect();
    siblings.sort();
    assert_eq!(
        siblings,
        vec!["existing.cpio".to_string(), "proj".to_string()],
        "a failed pack must leave no temp file behind"
    );

    // The second failure point: the destination cannot be created at all.
    let ro = dir.join("readonly");
    std::fs::create_dir(&ro).unwrap();
    std::fs::set_permissions(&ro, std::fs::Permissions::from_mode(0o500)).unwrap();
    assert!(
        std::fs::File::create(ro.join("probe")).is_err(),
        "this test needs a non-root user; the read-only directory is still writable"
    );
    let target = ro.join("out.tar");
    let st = Command::new(STUFFR)
        .args([
            "pack",
            root.join("a.txt").to_str().unwrap(),
            "-o",
            target.to_str().unwrap(),
        ])
        .output()
        .unwrap();
    assert_eq!(
        st.status.code(),
        Some(1),
        "a destination that cannot be created is an i/o failure, exit 1; stderr: {}",
        String::from_utf8_lossy(&st.stderr)
    );
    assert!(!target.exists(), "a failed pack must publish nothing");

    // Restored before the harness's own cleanup walks the tree.
    std::fs::set_permissions(&ro, std::fs::Permissions::from_mode(0o700)).unwrap();
}

/// An unreadable FILE is a warning, not a failure — the ruling that makes the
/// walk consistent with itself.
///
/// `walk.rs`'s `descend` already skips a directory it cannot list, on the
/// stated grounds that "backing up a home directory with one root-owned
/// subdirectory in it is the ordinary case", and R9 chose skip-plus-warning
/// for the analogous case. An unreadable file was never ruled on and, until
/// this, propagated with a bare `?`: one unreadable file in a home directory
/// aborted `stuffr pack ~ -o backup.tar` and produced nothing at all.
///
/// Skipping is not silent. The entry is named, and `--strict-fidelity` turns
/// it into exit 4, the same as every other loss.
#[cfg(unix)]
#[test]
fn an_unreadable_file_is_skipped_with_a_warning_rather_than_failing_the_pack() {
    use std::os::unix::fs::PermissionsExt;

    let dir = tmp_dir();
    let root = dir.join("proj");
    std::fs::create_dir(&root).unwrap();
    std::fs::write(root.join("a.txt"), b"alpha").unwrap();
    let unreadable = root.join("secret.txt");
    std::fs::write(&unreadable, b"beta").unwrap();
    std::fs::set_permissions(&unreadable, std::fs::Permissions::from_mode(0o000)).unwrap();
    // Loud rather than skipped: running as root makes the file readable, and
    // this test would then pass having proved nothing at all.
    assert!(
        std::fs::File::open(&unreadable).is_err(),
        "this test needs a non-root user; the unreadable file is still readable"
    );

    let out = dir.join("backup.tar");
    let st = Command::new(STUFFR)
        .args(["pack", root.to_str().unwrap(), "-o", out.to_str().unwrap()])
        .output()
        .unwrap();
    assert!(
        st.status.success(),
        "one unreadable file must not lose the whole backup: {}",
        String::from_utf8_lossy(&st.stderr)
    );
    let stderr = String::from_utf8_lossy(&st.stderr);
    // The entry's NAME, not the word "fidelity": the pack summary carries a
    // loss count on every successful pack, warnings or none, so asserting on
    // that word would pass with the whole warnings vector gone.
    assert!(
        stderr.contains("proj/secret.txt"),
        "it must SAY WHAT it skipped, by name; stderr: {stderr}"
    );

    // And the rest of the tree really is in there.
    let listed = run_output(&["list", out.to_str().unwrap()]);
    let text = String::from_utf8_lossy(&listed.stdout);
    assert!(text.contains("proj/a.txt"), "{text}");
    assert!(
        !text.contains("secret.txt"),
        "an entry that could not be read must not be written as an empty one: {text}"
    );

    // Strict fidelity is what turns the loss into a refusal.
    let strict = dir.join("strict.tar");
    let st = Command::new(STUFFR)
        .args([
            "pack",
            root.to_str().unwrap(),
            "-o",
            strict.to_str().unwrap(),
            "--strict-fidelity",
        ])
        .output()
        .unwrap();
    assert_eq!(
        st.status.code(),
        Some(4),
        "strict fidelity must refuse a pack that skipped a file; stderr: {}",
        String::from_utf8_lossy(&st.stderr)
    );

    std::fs::set_permissions(&unreadable, std::fs::Permissions::from_mode(0o600)).unwrap();
}

// ---------------------------------------------------------------------------
// The collapsed-indentation guard, enumerated structurally.
// ---------------------------------------------------------------------------

/// Every `.rs` file under the workspace's `crates/*/src/`.
///
/// Discovered by walking, not listed: a message added by a future task in a
/// file that does not exist yet is exactly the case the hardcoded version of
/// this guard could not cover.
///
/// `CARGO_MANIFEST_DIR` bakes an absolute path at compile time, the same
/// hazard `CARGO_BIN_EXE_stuffr` already carries at the top of this file — if
/// the repository is moved, `cargo clean -p stuffr-cli` is the fix for both
/// (see `CLAUDE.md`).
fn workspace_source_files() -> Vec<PathBuf> {
    let crates = Path::new(env!("CARGO_MANIFEST_DIR")).parent().unwrap();
    let mut out = Vec::new();
    let mut stack: Vec<PathBuf> = std::fs::read_dir(crates)
        .unwrap()
        .map(|e| e.unwrap().path().join("src"))
        .filter(|p| p.is_dir())
        .collect();
    while let Some(dir) = stack.pop() {
        for entry in std::fs::read_dir(&dir).unwrap() {
            let path = entry.unwrap().path();
            if path.is_dir() {
                stack.push(path);
            } else if path.extension().is_some_and(|e| e == "rs") {
                out.push(path);
            }
        }
    }
    out.sort();
    out
}

/// Every Rust string literal in `src`, as the compiler will see it: `\` at
/// end of line strips the newline AND the next line's leading whitespace, so a
/// literal written with that continuation contains no indentation at all,
/// while one that lost its `\` carries the indentation into the message.
///
/// Comments, char literals and lifetimes are skipped so that a `"` inside one
/// cannot desynchronise the scan. Raw strings are included: they cannot use
/// `\`-continuation, so a multi-line one carries its indentation too.
fn rust_string_literals(src: &str) -> Vec<(usize, String)> {
    let c: Vec<char> = src.chars().collect();
    let mut out = Vec::new();
    let mut i = 0usize;
    let mut line = 1usize;
    while i < c.len() {
        if c[i] == '\n' {
            line += 1;
            i += 1;
            continue;
        }
        if c[i] == '/' && c.get(i + 1) == Some(&'/') {
            while i < c.len() && c[i] != '\n' {
                i += 1;
            }
            continue;
        }
        if c[i] == '/' && c.get(i + 1) == Some(&'*') {
            let mut depth = 1usize;
            i += 2;
            while i < c.len() && depth > 0 {
                if c[i] == '/' && c.get(i + 1) == Some(&'*') {
                    depth += 1;
                    i += 2;
                } else if c[i] == '*' && c.get(i + 1) == Some(&'/') {
                    depth -= 1;
                    i += 2;
                } else {
                    if c[i] == '\n' {
                        line += 1;
                    }
                    i += 1;
                }
            }
            continue;
        }
        // A char literal (`'a'`, `'\''`, `'"'`) or a lifetime (`'a`). Telling
        // them apart matters: treating `'"'` as a lifetime would leave the
        // scan inside a string it never entered.
        if c[i] == '\'' {
            if c.get(i + 1) == Some(&'\\') {
                let mut j = i + 2;
                while j < c.len() && c[j] != '\'' {
                    j += 1;
                }
                i = j + 1;
                continue;
            }
            if c.get(i + 2) == Some(&'\'') {
                i += 3;
                continue;
            }
            i += 1;
            continue;
        }
        // A raw string, optionally byte: `r"…"`, `r#"…"#`, `br##"…"##`.
        let ident_before = i > 0 && (c[i - 1].is_alphanumeric() || c[i - 1] == '_');
        if (c[i] == 'r' || c[i] == 'b') && !ident_before {
            let mut j = i;
            if c[j] == 'b' {
                j += 1;
            }
            if c.get(j) == Some(&'r') {
                j += 1;
                let mut hashes = 0usize;
                while c.get(j) == Some(&'#') {
                    hashes += 1;
                    j += 1;
                }
                if c.get(j) == Some(&'"') {
                    let start_line = line;
                    j += 1;
                    let mut text = String::new();
                    loop {
                        if j >= c.len() {
                            break;
                        }
                        if c[j] == '"' && c[j + 1..].iter().take(hashes).all(|h| *h == '#') {
                            j += 1 + hashes;
                            break;
                        }
                        if c[j] == '\n' {
                            line += 1;
                        }
                        text.push(c[j]);
                        j += 1;
                    }
                    out.push((start_line, text));
                    i = j;
                    continue;
                }
            }
        }
        if c[i] == '"' {
            let start_line = line;
            let mut text = String::new();
            let mut j = i + 1;
            while j < c.len() && c[j] != '"' {
                if c[j] == '\\' && c.get(j + 1) == Some(&'\n') {
                    // The continuation rustc applies, and the whole reason a
                    // correctly-written message carries no indentation.
                    line += 1;
                    j += 2;
                    while matches!(c.get(j), Some(' ' | '\t' | '\r' | '\n')) {
                        if c[j] == '\n' {
                            line += 1;
                        }
                        j += 1;
                    }
                    continue;
                }
                if c[j] == '\\' {
                    text.push(c[j]);
                    if let Some(&e) = c.get(j + 1) {
                        text.push(e);
                    }
                    j += 2;
                    continue;
                }
                if c[j] == '\n' {
                    line += 1;
                }
                text.push(c[j]);
                j += 1;
            }
            out.push((start_line, text));
            i = j + 1;
            continue;
        }
        i += 1;
    }
    out
}

/// The byte offset of the first run of three or more spaces in `text`, if any.
fn first_space_run(text: &str) -> Option<usize> {
    text.as_bytes().windows(3).position(|w| w == b"   ")
}

/// Whether a run of spaces is a deliberate COLUMN, not a collapsed
/// continuation: everything before it on its own line is a ONE-WORD label
/// ending in a colon, which is `stuffr info`'s output shape (`format:   gzip`)
/// and the `/proc/meminfo` fixture's (`MemAvailable:    1048576 kB`).
///
/// Anything else — the historical defect's `` (`-o bundle.tar`, `` — is prose,
/// and prose never needs three spaces in a row.
///
/// The single-word rule is load-bearing, not tidiness. An earlier version
/// allowed any label of alphanumerics and SPACES, which exempted a whole prose
/// clause that happened to end in a colon —
/// `"stuffr cannot do this:                    try force"` passed it — and
/// messages in this tree routinely end a clause with a colon before a list.
/// One word still admits all seven exemptions the workspace actually has
/// (`format:`, `chain:`, `rung:`, `size:` twice, `memory:`, `MemTotal:`).
fn is_column_label(prefix: &str) -> bool {
    let tail = prefix
        .rsplit('\n')
        .next()
        .unwrap_or(prefix)
        .rsplit("\\n")
        .next()
        .unwrap_or(prefix);
    match tail.strip_suffix(':') {
        Some(label) => {
            !label.is_empty()
                && !label.contains(' ')
                && label
                    .chars()
                    .all(|ch| ch.is_ascii_alphanumeric() || ch == '_' || ch == '-')
        }
        None => false,
    }
}

/// Phase 2's final review found three multi-line literals in `main.rs`
/// collapsed with their continuation indentation left in, so users saw runs of
/// 22-30 spaces mid-sentence:
///
/// ```text
/// stuffr: usage error: packing 2 paths needs an output naming a container
/// (`-o bundle.tar`,                      or --format tar); a codec …
/// ```
///
/// The guard written then enumerated three hardcoded invocations, and in Phase
/// 2c it failed to catch the identical defect recurring, because the new
/// message was not one of its three. This is the same guard enumerated from
/// something a future task cannot escape: every string literal in every
/// source file of every crate, discovered by walking the tree, whether or not
/// any test ever reaches the code that prints it.
///
/// The mechanism is the one that produced the defect twice: a heredoc (or any
/// other editor) eating the `\` that ends a continued line leaves the next
/// line's indentation INSIDE the literal, and `cargo fmt` then folds the whole
/// thing onto one line. Neither the compiler nor the gate sees anything wrong;
/// only running the binary does.
#[test]
fn no_message_literal_in_the_workspace_carries_a_run_of_collapsed_indentation() {
    // The scanner is tested before it is trusted. Without this, a scanner that
    // silently found no literals at all would report the whole workspace
    // clean — the exact shape of defect this test exists to catch.
    let defective = "fn f() { err(\"packing paths needs a container (`-o bundle.tar`,                      or --format tar)\"); }";
    let found = rust_string_literals(defective);
    assert_eq!(
        found.len(),
        1,
        "the scanner must find the literal: {found:?}"
    );
    assert!(
        first_space_run(&found[0].1).is_some_and(|at| !is_column_label(&found[0].1[..at])),
        "the scanner must flag the historical defect: {:?}",
        found[0].1
    );

    let continued = "fn f() { err(\"packing paths needs a container \\\n                     (`-o bundle.tar`, or --format tar)\"); }";
    let found = rust_string_literals(continued);
    assert_eq!(found.len(), 1);
    assert_eq!(
        found[0].1, "packing paths needs a container (`-o bundle.tar`, or --format tar)",
        "a `\\`-continued literal carries no indentation, and the scanner must apply that \
         rule rather than report the source text"
    );
    assert!(first_space_run(&found[0].1).is_none());

    let aligned = "fn f() { println!(\"format:   {}\", x); }";
    let found = rust_string_literals(aligned);
    let at = first_space_run(&found[0].1).expect("the column really is three spaces");
    assert!(
        is_column_label(&found[0].1[..at]),
        "a deliberate column label must not be reported as a collapse"
    );

    // The exemption must not widen back into prose. A whole clause ending in a
    // colon is the historical defect verbatim — messages here routinely end a
    // clause with a colon before a list — and an exemption that allowed spaces
    // in the label let exactly this through.
    let colon_prose = "fn f() { err(\"stuffr cannot do this:                    try force\"); }";
    let found = rust_string_literals(colon_prose);
    assert_eq!(found.len(), 1);
    let at = first_space_run(&found[0].1).expect("the run is there");
    assert!(
        !is_column_label(&found[0].1[..at]),
        "a prose clause ending in a colon is not a column label: {:?}",
        found[0].1
    );

    // The two shapes either side of the one-word rule, so its boundary is
    // pinned rather than incidental.
    assert!(is_column_label("MemAvailable:"));
    assert!(!is_column_label("two words:"));

    let quoted_char = "fn f() { let q = '\"'; err(\"a   collapse\"); }";
    let found = rust_string_literals(quoted_char);
    assert_eq!(
        found.iter().map(|(_, t)| t.as_str()).collect::<Vec<_>>(),
        vec!["a   collapse"],
        "a `\"` inside a char literal must not desynchronise the scan"
    );

    // And now the workspace itself.
    let files = workspace_source_files();
    assert!(
        files.len() > 20,
        "the walk found only {} source files, which is not this workspace: {files:?}",
        files.len()
    );
    assert!(
        files.iter().any(|p| p.ends_with("stuffr-cli/src/main.rs")),
        "the walk must reach the crate every user-facing message is printed from"
    );

    let mut scanned = 0usize;
    let mut offenders = Vec::new();
    for file in &files {
        let src = std::fs::read_to_string(file).unwrap();
        for (line, text) in rust_string_literals(&src) {
            scanned += 1;
            let Some(at) = first_space_run(&text) else {
                continue;
            };
            if is_column_label(&text[..at]) {
                continue;
            }
            offenders.push(format!("{}:{line}: {text:?}", file.display()));
        }
    }
    assert!(
        scanned > 1000,
        "only {scanned} literals scanned, which is not this workspace"
    );
    assert!(
        offenders.is_empty(),
        "a string literal carries a run of three or more spaces, which reaches the user as \
         collapsed continuation indentation mid-sentence. Re-join the sentence and end each \
         continued line with `\\` (which strips the newline AND the next line's indentation); \
         a deliberate column is written `label:   value`. Offenders:\n{}",
        offenders.join("\n")
    );
}

// ---------------------------------------------------------------------------
// Three branches of `entries.rs` that were verified by reading, not by test.
// ---------------------------------------------------------------------------

/// `/` has no final component to name an entry after, and the refusal is a
/// usage error — not an `Io` error, and not an archive named `/`, which
/// `unpack` would then refuse at exit 7.
#[test]
fn packing_the_filesystem_root_is_a_usage_error_that_says_why() {
    let dir = tmp_dir();
    let out = dir.join("root.tar");
    let st = Command::new(STUFFR)
        .args(["pack", "/", "-o", out.to_str().unwrap()])
        .output()
        .unwrap();
    assert_eq!(
        st.status.code(),
        Some(2),
        "packing `/` is the caller's mistake, not an i/o failure; stderr: {}",
        String::from_utf8_lossy(&st.stderr)
    );
    let stderr = String::from_utf8_lossy(&st.stderr);
    assert!(
        stderr.contains("no final path component"),
        "the message must say what is wrong with `/`: {stderr}"
    );
    assert!(
        !out.exists(),
        "the refusal happens before the destination is opened"
    );
}

/// A path ending in `..` that does not exist fails as the `Io` error it is
/// (exit 1), not as a naming complaint.
///
/// `entry_name_for` reaches `canonicalize` for any path whose final component
/// is `.` or `..`, and that call is what reports a missing path here — a
/// deliberate exit-code decision (`Usage` before Phase 2c) with nothing
/// pinning it.
#[test]
fn a_nonexistent_dotdot_path_is_reported_as_an_io_error() {
    let dir = tmp_dir();
    let out = dir.join("dd.tar");
    let missing = dir.join("nosuch/..");
    let st = Command::new(STUFFR)
        .args([
            "pack",
            missing.to_str().unwrap(),
            "-o",
            out.to_str().unwrap(),
        ])
        .output()
        .unwrap();
    assert_eq!(
        st.status.code(),
        Some(1),
        "a path that does not exist is an i/o error, whatever its final component; \
         stderr: {}",
        String::from_utf8_lossy(&st.stderr)
    );
    assert!(!out.exists());
}

/// `pack .` from a SYMLINKED working directory names entries after the
/// directory the link resolves to, not after the link.
///
/// Surprising the first time it happens (`cd proj && stuffr pack .` writes
/// `real/…`), and correct: `Path::file_name` gives `None` for `.`, so the name
/// comes from `canonicalize`, which resolves every symlink in the path. Pinned
/// because the obvious "fix" — using the shell's `$PWD` or the un-resolved cwd
/// — would silently change every such archive's entry names.
#[cfg(unix)]
#[test]
fn pack_of_dot_from_a_symlinked_directory_names_entries_after_the_real_one() {
    let dir = tmp_dir();
    std::fs::create_dir_all(dir.join("real/src")).unwrap();
    std::fs::write(dir.join("real/src/main.rs"), b"fn main() {}").unwrap();
    std::os::unix::fs::symlink("real", dir.join("proj")).unwrap();

    let out = dir.join("sym.tar");
    let st = Command::new(STUFFR)
        .current_dir(dir.join("proj"))
        .args(["pack", ".", "-o", out.to_str().unwrap()])
        .output()
        .unwrap();
    assert!(
        st.status.success(),
        "stderr: {}",
        String::from_utf8_lossy(&st.stderr)
    );

    let listed = run_output(&["list", out.to_str().unwrap()]);
    let text = String::from_utf8_lossy(&listed.stdout);
    assert!(
        text.contains("real/src/main.rs"),
        "`.` resolves through the symlink, so entries sit under the real directory's \
         name: {text}"
    );
    assert!(
        !text.contains("proj/"),
        "nothing may be named after the link itself: {text}"
    );
}

// ---------------------------------------------------------------------
// Phase 2c final review: the four findings whose reproduction is a CLI
// invocation, and the summary line that reports them.
// ---------------------------------------------------------------------

/// Finding 3. `pack . -o backup.tar` excludes the archive from its own walk,
/// which is stuffr being correct — and Phase 2c recorded it as a fidelity
/// warning, so `--strict-fidelity` exited 0 on the first run and **4 on every
/// run after**, forever, on an archive that had lost nothing the user wanted.
/// That is the flagship nightly-backup shape `examples.txt` advertises.
#[test]
fn excluding_the_output_from_its_own_walk_is_a_note_not_a_fidelity_loss() {
    let dir = tmp_dir();
    let root = dir.join("proj");
    std::fs::create_dir_all(&root).unwrap();
    std::fs::write(root.join("a.txt"), b"payload\n").unwrap();
    let out = root.join("backup.tar");

    // Three runs, because the defect only appears from the SECOND: on the
    // first there is no `backup.tar` on disk for the walk to find.
    for run in 1..=3 {
        let st = Command::new(STUFFR)
            .args([
                "pack",
                root.to_str().unwrap(),
                "-o",
                out.to_str().unwrap(),
                "--force",
                "--strict-fidelity",
            ])
            .output()
            .unwrap();
        let stderr = String::from_utf8_lossy(&st.stderr).to_string();
        assert_eq!(
            st.status.code(),
            Some(0),
            "run {run}: declining to store the archive inside itself is not a \
             fidelity loss, so the strict gate must stay green; stderr: {stderr}"
        );
        // Still SAID, every run — routing it off the gate must not silence
        // it. Without this half the test passes against an implementation
        // that simply drops the file without a word.
        if run > 1 {
            assert!(
                stderr.contains("proj/backup.tar"),
                "run {run}: the user must still be told, by name: {stderr}"
            );
        }
        // And the summary line must not claim a loss it is not reporting.
        assert!(
            stderr.contains("no fidelity loss"),
            "run {run}: the count in the summary must agree with the (empty) \
             warning list: {stderr}"
        );
    }

    // The archive is real and does not nest a copy of itself.
    let listed = run_output(&["list", out.to_str().unwrap()]);
    let text = String::from_utf8_lossy(&listed.stdout);
    assert!(text.contains("proj/a.txt"), "{text}");
    assert!(
        !text.contains("backup.tar"),
        "the archive must not be inside itself: {text}"
    );
}

/// Finding 4. `compound_alias` stripped the `t` and looked up `bz`, which
/// bzip2 does not register (it registers `bz2`), so the whole name resolved
/// to `Chain::Raw` — which on the write side is not a refusal but a silent
/// fall back to `default_format()`. `-o f.tbz` wrote a **gzip stream with no
/// tar inside it, at exit 0**: a name promising one thing, bytes that are
/// another, reported as success.
#[test]
fn a_tbz_output_writes_tar_inside_bzip2_and_not_a_bare_gzip() {
    let dir = tmp_dir();
    let src = dir.join("notes.txt");
    std::fs::write(&src, b"payload\n").unwrap();

    let out = dir.join("f.tbz");
    let st = Command::new(STUFFR)
        .args(["pack", src.to_str().unwrap(), "-o", out.to_str().unwrap()])
        .output()
        .unwrap();
    assert!(
        st.status.success(),
        "stderr: {}",
        String::from_utf8_lossy(&st.stderr)
    );

    // The BYTES, not the exit code: exit 0 is exactly what the defect gave.
    let bytes = std::fs::read(&out).unwrap();
    assert_eq!(
        &bytes[..3],
        b"BZh",
        "a .tbz must be bzip2 — it was gzip (1f 8b) before this: {:02x?}",
        &bytes[..4.min(bytes.len())]
    );
    // And a tar really is inside it, which the gzip it used to write had no
    // room for at all.
    let listed = run_output(&["list", out.to_str().unwrap()]);
    assert!(
        listed.status.success(),
        "a .tbz must open as an archive: {}",
        String::from_utf8_lossy(&listed.stderr)
    );
    assert!(
        String::from_utf8_lossy(&listed.stdout).contains("notes.txt"),
        "the tar layer must be there: {}",
        String::from_utf8_lossy(&listed.stdout)
    );

    // `.tbz2` was never broken and must stay unbroken: stripping its `t`
    // already yields bzip2's own registered `bz2`.
    let out2 = dir.join("f.tbz2");
    assert!(
        Command::new(STUFFR)
            .args(["pack", src.to_str().unwrap(), "-o", out2.to_str().unwrap()])
            .status()
            .unwrap()
            .success()
    );
    assert_eq!(&std::fs::read(&out2).unwrap()[..3], b"BZh");

    // The fix is in the compound alias, NOT the registry: `.bz` is bzip1, a
    // different and obsolete format, and must not have become writable as
    // bzip2 on the way past.
    let out3 = dir.join("f.bz");
    assert!(
        Command::new(STUFFR)
            .args(["pack", src.to_str().unwrap(), "-o", out3.to_str().unwrap()])
            .status()
            .unwrap()
            .success()
    );
    assert_ne!(
        &std::fs::read(&out3).unwrap()[..3],
        b"BZh",
        "`bz` must not resolve to bzip2 outside the `t`-prefixed compound form"
    );
}

/// Finding 5. Phase 2c made a directory a legitimate input on the container
/// path and left it landing on `Error::exit_code`'s `_ => 1` wildcard on the
/// other: `File::open` on a directory succeeds on unix and fails at the first
/// `read`, so `pack proj -o proj.gz` reported `i/o error: Is a directory
/// (os error 21)` at exit 1 — as if stuffr had failed.
#[test]
fn a_directory_on_the_single_stream_path_is_a_usage_error_naming_the_fix() {
    let dir = tmp_dir();
    let root = dir.join("proj");
    std::fs::create_dir_all(&root).unwrap();
    std::fs::write(root.join("a.txt"), b"payload\n").unwrap();

    let out = dir.join("proj.gz");
    let st = Command::new(STUFFR)
        .args(["pack", root.to_str().unwrap(), "-o", out.to_str().unwrap()])
        .output()
        .unwrap();
    let stderr = String::from_utf8_lossy(&st.stderr).to_string();
    assert_eq!(
        st.status.code(),
        Some(2),
        "asking a codec for a tree is the caller's mistake, not an i/o \
         failure; stderr: {stderr}"
    );
    assert!(
        !stderr.contains("os error 21"),
        "the raw EISDIR must not reach the user: {stderr}"
    );
    // Naming the fix is the point of the finding — an exit code alone leaves
    // the reader no better off than the wildcard did.
    assert!(
        stderr.contains("proj.tar.gz"),
        "the message must name the output that works: {stderr}"
    );
    assert!(
        !out.exists(),
        "the refusal happens before the destination is touched"
    );

    // And the output it names really does work.
    let good = dir.join("proj.tar.gz");
    assert!(
        Command::new(STUFFR)
            .args(["pack", root.to_str().unwrap(), "-o", good.to_str().unwrap()])
            .status()
            .unwrap()
            .success()
    );
}

/// Minor 1. The pack summary printed `out.fidelity.rung`, which
/// `create_archive` hardcodes to `Rung::Exact` — so `pack proj -o out.ar`
/// announced "exact fidelity" and then named four losses on the next four
/// lines. The number printed must be one the following lines agree with.
#[test]
fn the_pack_summary_counts_losses_rather_than_claiming_exact_fidelity() {
    let dir = tmp_dir();
    let root = dir.join("proj");
    std::fs::create_dir_all(root.join("sub")).unwrap();
    std::fs::write(root.join("sub").join("a.txt"), b"payload\n").unwrap();

    // `ar` stores neither directories nor symlinks, so a walked tree loses
    // its directory entries there and nowhere else.
    let out = dir.join("p.a");
    let st = Command::new(STUFFR)
        .args(["pack", root.to_str().unwrap(), "-o", out.to_str().unwrap()])
        .output()
        .unwrap();
    assert!(
        st.status.success(),
        "stderr: {}",
        String::from_utf8_lossy(&st.stderr)
    );
    let stderr = String::from_utf8_lossy(&st.stderr).to_string();

    assert!(
        !stderr.contains("exact fidelity"),
        "a pack that lost entries must not announce exact fidelity: {stderr}"
    );
    // The two numbers must be the SAME number, read out of the two lines
    // that print it. An assertion on either alone passes against a summary
    // that prints a constant.
    let reported: usize = stderr
        .lines()
        .find_map(|l| l.split_once(" fidelity loss(es)"))
        .and_then(|(head, _)| head.rsplit(", ").next())
        .and_then(|n| n.trim().parse().ok())
        .unwrap_or_else(|| panic!("the summary must carry a loss count: {stderr}"));
    let listed: usize = stderr
        .lines()
        .find_map(|l| l.strip_prefix("stuffr: "))
        .and_then(|l| l.split_once(" fidelity warning(s):"))
        .and_then(|(n, _)| n.parse().ok())
        .unwrap_or_else(|| panic!("the warning header must carry a count: {stderr}"));
    assert_eq!(
        reported, listed,
        "the summary's count and the warning list's count are the same fact: {stderr}"
    );
    assert!(
        reported > 0,
        "packing a tree into `ar` really does lose the \
                          directory entries: {stderr}"
    );

    // And a pack that loses nothing says so, rather than saying "0".
    let clean = dir.join("p.tar");
    let st = Command::new(STUFFR)
        .args([
            "pack",
            root.to_str().unwrap(),
            "-o",
            clean.to_str().unwrap(),
        ])
        .output()
        .unwrap();
    let stderr = String::from_utf8_lossy(&st.stderr).to_string();
    assert!(
        stderr.contains("no fidelity loss"),
        "a lossless pack must say so: {stderr}"
    );
}

// ---------------------------------------------------------------------
// Selecting entries by index.
//
// `ArchiveRead::by_index` existed and was implemented on all four
// containers from Phase 2 onward with no call site above the container
// layer at all — built and dormant, the same shape `UnsafePath` and
// `ContainerCaps` were in earlier phases. These tests are the contract for
// the surface that finally reaches it.
//
// Index is 0-based and counts in ARCHIVE ORDER: the order `next_entry`
// yields, which is the order `list` prints. `list`'s first column and
// `--index` therefore read one enumeration, and the first test here is the
// one that keeps them from drifting apart.
// ---------------------------------------------------------------------

/// Builds a zip through `stuffr pack` itself. There is no `zip` dev-dependency
/// here (unlike `tar`/`flate2`), and for these tests that is fine: the point
/// is not to validate stuffr's zip WRITER but to have an archive whose
/// container carries a real central directory, which is what puts `--index`
/// on its random-access route.
fn write_zip_via_pack(dir: &Path, entries: &[(&str, &[u8])]) -> PathBuf {
    let src = dir.join("src");
    std::fs::create_dir_all(&src).unwrap();
    let mut paths = Vec::new();
    for (name, data) in entries {
        let p = src.join(name);
        std::fs::write(&p, data).unwrap();
        paths.push(p);
    }
    let zip = dir.join("bundle.zip");
    let mut args: Vec<String> = vec!["pack".into()];
    args.extend(paths.iter().map(|p| p.to_string_lossy().into_owned()));
    args.push("-o".into());
    args.push(zip.to_string_lossy().into_owned());
    let out = Command::new(STUFFR).args(&args).output().unwrap();
    assert!(
        out.status.success(),
        "building the zip fixture failed: {}",
        String::from_utf8_lossy(&out.stderr)
    );
    zip
}

/// The index column and `--index` must name the same entry, because a user
/// reads the first and types the second. Checked for EVERY row rather than
/// one, so an off-by-one that happens to be invisible at position 0 still
/// fails.
#[test]
fn the_index_list_prints_is_the_index_cat_selects_by() {
    let dir = tmp_dir();
    let archive = write_fixture_tar(
        &dir,
        &[
            ("a.txt", b"alpha"),
            ("b.txt", b"bravo"),
            ("c.txt", b"charlie"),
        ],
    );
    let listing =
        String::from_utf8(run_output(&["list", archive.to_str().unwrap()]).stdout).unwrap();
    let rows: Vec<&str> = listing.lines().collect();
    assert_eq!(rows.len(), 3, "{listing}");

    for (want_index, (_, payload)) in [
        ("a.txt", &b"alpha"[..]),
        ("b.txt", &b"bravo"[..]),
        ("c.txt", &b"charlie"[..]),
    ]
    .iter()
    .enumerate()
    {
        // The first column of the listing is the number `--index` takes.
        let printed = rows[want_index].split_whitespace().next().unwrap();
        assert_eq!(
            printed,
            want_index.to_string(),
            "list's first column must be the 0-based archive position: {listing}"
        );
        let out = run_output(&[
            "cat",
            archive.to_str().unwrap(),
            "--index",
            &want_index.to_string(),
        ]);
        assert!(
            out.status.success(),
            "stderr: {}",
            String::from_utf8_lossy(&out.stderr)
        );
        assert_eq!(
            out.stdout, *payload,
            "row {want_index} of the listing and `--index {want_index}` must be \
             the same entry"
        );
    }

    let _ = std::fs::remove_dir_all(&dir);
}

/// The property the two-route implementation rests on, at the level a user
/// meets it: a zip on a real file is reached through its central directory,
/// the same zip on a pipe is reached by counting the forward walk, and the
/// two must hand back the same bytes.
///
/// Compared against the ORIGINAL content as well as against each other —
/// two routes wrong in the same direction would agree with each other
/// perfectly and both be wrong.
#[test]
fn index_selection_agrees_between_a_seekable_zip_and_the_same_zip_on_a_pipe() {
    let dir = tmp_dir();
    let payloads: [&[u8]; 4] = [b"first", b"second!!", b"third:::", b"fourth"];
    let zip = write_zip_via_pack(
        &dir,
        &[
            ("one.txt", payloads[0]),
            ("two.txt", payloads[1]),
            ("three.txt", payloads[2]),
            ("four.txt", payloads[3]),
        ],
    );
    let bytes = std::fs::read(&zip).unwrap();

    for (i, payload) in payloads.iter().enumerate() {
        let n = i.to_string();
        let seekable = run_output(&["cat", zip.to_str().unwrap(), "--index", &n]);
        assert!(
            seekable.status.success(),
            "index {n} on a file: {}",
            String::from_utf8_lossy(&seekable.stderr)
        );
        let piped = run_with_stdin_output(&["cat", "-", "--index", &n], &bytes);
        assert!(
            piped.status.success(),
            "index {n} on a pipe: {}",
            String::from_utf8_lossy(&piped.stderr)
        );

        assert_eq!(
            seekable.stdout, piped.stdout,
            "the random-access and counted routes disagreed at index {n}"
        );
        assert_eq!(
            seekable.stdout,
            payload.to_vec(),
            "index {n} did not reach the entry the archive was built with"
        );
    }

    let _ = std::fs::remove_dir_all(&dir);
}

/// Repeatable, delivered in archive order however the flags were ordered,
/// and a repeat selects its entry once. That contract is what lets the two
/// routes above agree at all: the counted route can only ever produce
/// archive order.
#[test]
fn repeated_index_flags_are_deduplicated_and_delivered_in_archive_order() {
    let dir = tmp_dir();
    let archive = write_fixture_tar(
        &dir,
        &[
            ("a.txt", b"alpha"),
            ("b.txt", b"bravo"),
            ("c.txt", b"charlie"),
        ],
    );
    let out = run_output(&[
        "cat",
        archive.to_str().unwrap(),
        "--index",
        "2",
        "--index",
        "0",
        "--index",
        "2",
    ]);
    assert!(
        out.status.success(),
        "stderr: {}",
        String::from_utf8_lossy(&out.stderr)
    );
    assert_eq!(
        out.stdout, b"alphacharlie",
        "archive order, once each — not typed order, and not twice"
    );

    let _ = std::fs::remove_dir_all(&dir);
}

/// An index past the end is the caller's mistake, so exit 2 and say how many
/// entries there actually are. Pinned on both routes, since each discovers
/// the overrun at a different moment.
#[test]
fn an_index_past_the_end_is_a_usage_error_naming_the_real_entry_count() {
    let dir = tmp_dir();
    let archive = write_fixture_tar(&dir, &[("a.txt", b"alpha"), ("b.txt", b"bravo")]);
    let zip = write_zip_via_pack(&dir, &[("one.txt", b"first"), ("two.txt", b"second")]);

    for path in [&archive, &zip] {
        let out = run_output(&["cat", path.to_str().unwrap(), "--index", "9"]);
        assert_eq!(
            out.status.code(),
            Some(2),
            "{}: stderr {}",
            path.display(),
            String::from_utf8_lossy(&out.stderr)
        );
        let stderr = String::from_utf8_lossy(&out.stderr);
        assert!(
            stderr.contains("#9") && stderr.contains("0-1"),
            "the refusal must name the index asked for and the VALID range, \
             whichever route found it: {stderr}"
        );
        assert!(
            out.stdout.is_empty(),
            "an out-of-range index must not stream anything first"
        );
    }

    let _ = std::fs::remove_dir_all(&dir);
}

/// `--index` and PATTERNS are alternative ways of saying "which entries",
/// never a combination — exit 2 rather than a guess at union or
/// intersection.
#[test]
fn index_and_patterns_together_are_a_usage_error() {
    let dir = tmp_dir();
    let archive = write_fixture_tar(&dir, &[("a.txt", b"alpha"), ("b.txt", b"bravo")]);
    let dest = dir.join("out");

    let out = run_output(&["cat", archive.to_str().unwrap(), "a.txt", "--index", "1"]);
    assert_eq!(out.status.code(), Some(2));
    let stderr = String::from_utf8_lossy(&out.stderr);
    assert!(stderr.contains("--index"), "{stderr}");

    let out = run_output(&[
        "unpack",
        archive.to_str().unwrap(),
        "a.txt",
        "-C",
        dest.to_str().unwrap(),
        "--index",
        "1",
    ]);
    assert_eq!(out.status.code(), Some(2));
    assert!(
        !dest.exists(),
        "the refusal must come before anything is created"
    );

    let _ = std::fs::remove_dir_all(&dir);
}

/// `--index` selects entries, so on `unpack` it needs -C for exactly the
/// reason a pattern does — and the refusal names the flag the user typed.
#[test]
fn unpack_by_index_without_a_directory_names_the_index_in_its_refusal() {
    let dir = tmp_dir();
    let archive = write_fixture_tar(&dir, &[("a.txt", b"alpha"), ("b.txt", b"bravo")]);

    let out = run_output(&["unpack", archive.to_str().unwrap(), "--index", "1"]);
    assert_eq!(out.status.code(), Some(2));
    let stderr = String::from_utf8_lossy(&out.stderr);
    assert!(
        stderr.contains("--index 1") && stderr.contains("-C"),
        "the refusal must name what was typed and what to do instead: {stderr}"
    );

    let _ = std::fs::remove_dir_all(&dir);
}

/// The containered half of the feature: `unpack --index N -C out` writes
/// exactly that entry and nothing else.
#[test]
fn unpack_by_index_extracts_only_the_selected_entry() {
    let dir = tmp_dir();
    let archive = write_fixture_tar(
        &dir,
        &[
            ("a.txt", b"alpha"),
            ("b.txt", b"bravo"),
            ("c.txt", b"charlie"),
        ],
    );
    let dest = dir.join("out");
    let out = run_output(&[
        "unpack",
        archive.to_str().unwrap(),
        "-C",
        dest.to_str().unwrap(),
        "--index",
        "1",
    ]);
    assert!(
        out.status.success(),
        "stderr: {}",
        String::from_utf8_lossy(&out.stderr)
    );
    assert_eq!(std::fs::read(dest.join("b.txt")).unwrap(), b"bravo");
    assert!(!dest.join("a.txt").exists(), "only the selected entry");
    assert!(!dest.join("c.txt").exists(), "only the selected entry");

    let _ = std::fs::remove_dir_all(&dir);
}

/// `--json` carries the index too, since a script selecting by position has
/// to read it from somewhere.
#[test]
fn list_json_carries_the_archive_index_of_every_entry() {
    let dir = tmp_dir();
    let archive = write_fixture_tar(&dir, &[("a.txt", b"alpha"), ("b.txt", b"bravo")]);
    let out = run_output(&["list", "--json", archive.to_str().unwrap()]);
    let text = String::from_utf8(out.stdout).unwrap();
    let v: serde_json::Value = serde_json::from_str(&text).unwrap();
    let rows = v.as_array().unwrap();
    assert_eq!(rows[0]["index"], 0);
    assert_eq!(rows[0]["name"], "a.txt");
    assert_eq!(rows[1]["index"], 1);
    assert_eq!(rows[1]["name"], "b.txt");

    let _ = std::fs::remove_dir_all(&dir);
}

// ---------------------------------------------------------------------
// `list` reports its fidelity, through the same printer `test` uses.
// ---------------------------------------------------------------------

/// `list` used to drop the container's fidelity report entirely. On a piped
/// zip — the one shape whose forward read provably loses metadata — `test`
/// warned and `list` printed its rows in silence.
///
/// Fixed by handing `report_fidelity` the report, the same call `test` and
/// `unpack -C` make. Asserted against `test`'s own stderr on the identical
/// bytes so the two verbs cannot drift: whatever `test` says was lost,
/// `list` says too.
#[test]
fn list_reports_the_same_fidelity_warnings_test_does() {
    let dir = tmp_dir();
    let zip = write_zip_via_pack(&dir, &[("one.txt", b"first"), ("two.txt", b"second")]);
    let bytes = std::fs::read(&zip).unwrap();

    let listed = run_with_stdin_output(&["list", "-"], &bytes);
    assert!(
        listed.status.success(),
        "a warning is not a failure without --strict-fidelity"
    );
    let list_err = String::from_utf8_lossy(&listed.stderr).to_string();
    let tested = run_with_stdin_output(&["test", "-"], &bytes);
    let test_err = String::from_utf8_lossy(&tested.stderr).to_string();

    assert!(
        test_err.contains("fidelity warning(s)"),
        "the fixture must be a shape that really does lose something: {test_err}"
    );
    assert!(
        list_err.contains("fidelity warning(s)"),
        "`list` must report what it lost, not print rows in silence: {list_err}"
    );
    // Same warnings, verbatim, because it is the same printer over the same
    // report — not a second one that could word things differently.
    let warnings_of = |s: &str| -> Vec<String> {
        s.lines()
            .filter(|l| l.trim_start().starts_with("- "))
            .map(|l| l.trim().to_string())
            .collect()
    };
    assert_eq!(
        warnings_of(&list_err),
        warnings_of(&test_err),
        "list:\n{list_err}\ntest:\n{test_err}"
    );

    let _ = std::fs::remove_dir_all(&dir);
}

/// And the gate: `list --strict-fidelity` exits 4 on the same archive it
/// exits 0 on without the flag, the same contract `test` and `unpack -C`
/// have.
#[test]
fn list_strict_fidelity_turns_a_warning_into_exit_four() {
    let dir = tmp_dir();
    let zip = write_zip_via_pack(&dir, &[("one.txt", b"first")]);
    let bytes = std::fs::read(&zip).unwrap();

    let lenient = run_with_stdin_output(&["list", "-"], &bytes);
    assert_eq!(lenient.status.code(), Some(0));
    assert!(
        String::from_utf8_lossy(&lenient.stdout).contains("one.txt"),
        "the listing itself is still printed"
    );

    let strict = run_with_stdin_output(&["list", "-", "--strict-fidelity"], &bytes);
    assert_eq!(
        strict.status.code(),
        Some(4),
        "stderr: {}",
        String::from_utf8_lossy(&strict.stderr)
    );
    assert!(
        String::from_utf8_lossy(&strict.stdout).contains("one.txt"),
        "the gate is a verdict on a listing that was still produced"
    );

    // A read that loses nothing is still exit 0 under the flag — the gate is
    // on what was LOST, never on the rung.
    let clean = run_output(&["list", zip.to_str().unwrap(), "--strict-fidelity"]);
    assert_eq!(
        clean.status.code(),
        Some(0),
        "a seekable zip loses nothing: {}",
        String::from_utf8_lossy(&clean.stderr)
    );

    let _ = std::fs::remove_dir_all(&dir);
}

// ---------------------------------------------------------------------
// The test suite's own temp directories.
// ---------------------------------------------------------------------

/// `tmp_dir()` named its directories `stuffr-cli-archive-{pid}-{counter}`,
/// never removed them on a failing path, and so accumulated thousands of
/// them. PIDs are reused, so a later run landing on a recycled PID inherited
/// its predecessor's directories WITH CONTENTS, and five unrelated tests
/// failed with "already exists" — a red gate that went green again when the
/// leftovers were deleted, with no code change at all.
///
/// The fix is a random component no other run can reproduce. What this test
/// pins is precisely that: the part of the name that is not derivable from
/// the pid and the counter must exist. Under the old scheme the whole name
/// was derivable, and the tail below was the counter's digits alone.
#[test]
fn a_temp_directory_name_is_not_reproducible_from_the_pid_and_a_counter() {
    let dir = tmp_dir();
    assert_eq!(
        std::fs::read_dir(&dir).unwrap().count(),
        0,
        "a fresh temp directory must be empty — inheriting one with contents \
         in it is the whole failure this guards against"
    );

    let name = dir.file_name().unwrap().to_string_lossy().into_owned();
    let derivable = format!("stuffr-cli-archive-{}-", std::process::id());
    let tail = name
        .strip_prefix(&derivable)
        .unwrap_or_else(|| panic!("unexpected temp directory name: {name}"));
    assert!(
        tail.contains('-') && !tail.chars().all(|c| c.is_ascii_digit()),
        "everything after the pid was the counter alone, so a second run on a \
         recycled pid reproduced this name exactly: {name}"
    );

    // `tmp()` shares the same token, and had the same weakness: its old name
    // was `stuffr-cli-{pid}-{name}` exactly, every character of it derivable
    // by any other run that landed on the same pid.
    let other = tmp("token-check");
    let other_name = other.file_name().unwrap().to_string_lossy().into_owned();
    assert_ne!(
        other_name,
        format!("stuffr-cli-{}-token-check", std::process::id()),
        "tmp() must carry the run token too"
    );
    assert!(
        other_name.ends_with("-token-check"),
        "…and must still end in the caller's own name: {other_name}"
    );

    let _ = std::fs::remove_dir_all(&dir);
}

/// Every `cargo install stuffr-cli --features <x>` a shipped document prints
/// must name a feature `stuffr-cli` actually declares.
///
/// This exists because the opposite shipped. `crates/stuffr-cli/Cargo.toml`
/// carried no `[features]` section at all, while `README.md` printed
/// `cargo install stuffr-cli --features c-backed` as a copyable line — and
/// Cargo resolves a `--features` name against the package being installed,
/// not against its dependencies, so the command answered "the package
/// 'stuffr-cli' does not contain this feature" and the only working spelling
/// (`--features stuffr/c-backed`) appeared in no document. Phase 3b made it
/// acute by adding `legacy`, whose whole point is that a user turns it on.
///
/// Parsed out of the documents rather than listed here: a command added to a
/// README by a future phase is exactly the case a hardcoded list cannot
/// cover. The `[features]` table is read as text for the same reason the
/// version grep in `CLAUDE.md` is — no TOML parser is a dependency of this
/// crate, and a feature line is `name = [...]` at the start of a line, which
/// is unambiguous inside the one section this looks at.
#[test]
fn documented_install_commands_name_features_this_crate_declares() {
    let manifest_dir = Path::new(env!("CARGO_MANIFEST_DIR"));
    let manifest = std::fs::read_to_string(manifest_dir.join("Cargo.toml")).unwrap();

    let features: Vec<String> = manifest
        .split("\n[")
        .find(|section| section.starts_with("features]"))
        .expect(
            "stuffr-cli must declare a [features] section: without one, every \
                 documented `cargo install stuffr-cli --features …` fails",
        )
        .lines()
        .filter_map(|line| line.split_once('='))
        .filter(|(_, rhs)| rhs.trim_start().starts_with('['))
        .map(|(name, _)| name.trim().to_string())
        .collect();
    assert!(
        features.contains(&"legacy".to_string()),
        "the parse found {features:?}; if `legacy` is missing the scan itself is broken, \
         not the manifest"
    );

    // The same list the count guards scan — widened past this crate's own
    // three documents for the same reason they were: a stale `--features`
    // spelling in `CONTRIBUTING.md` or on another crate's published page
    // fails exactly as loudly for the reader who copies it.
    let docs = user_facing_documents();
    let mut commands_checked = 0usize;
    for doc in docs {
        let text = std::fs::read_to_string(&doc).unwrap();
        for line in text.lines() {
            let Some(rest) = line.split("cargo install stuffr-cli").nth(1) else {
                continue;
            };
            let Some(after) = rest.split("--features").nth(1) else {
                continue;
            };
            let name = after.split_whitespace().next().unwrap_or("");
            commands_checked += 1;
            assert!(
                features.contains(&name.to_string()),
                "{} prints `cargo install stuffr-cli --features {name}`, but stuffr-cli \
                 declares only {features:?} — that command fails with \"the package \
                 'stuffr-cli' does not contain this feature\"",
                doc.display()
            );
        }
    }
    assert!(
        commands_checked >= 2,
        "expected the READMEs to print at least the c-backed and legacy install \
         commands; found {commands_checked} — the scan has stopped finding them"
    );
}

/// **The documents this crate's count guards scan, in one place.**
///
/// It was three — this crate's README, the workspace README and
/// `examples.txt` — and that list is precisely what let Phase 3c's final
/// review find two stale published claims by hand: `crates/stuffr/README.md`
/// is a live crates.io landing page that did not know the legacy formats
/// existed, and `CONTRIBUTING.md` still said "eleven codecs". Neither was in
/// the list, so neither could have been caught. Every follow-up that review
/// raised lived in a file no task owned, which is the argument for widening
/// the scan rather than adding a checklist.
///
/// All four crate READMEs are here because all four are published pages, and
/// `CONTRIBUTING.md` because it is the document a contributor works from.
fn user_facing_documents() -> Vec<PathBuf> {
    let manifest_dir = Path::new(env!("CARGO_MANIFEST_DIR"));
    let root = manifest_dir.parent().unwrap().parent().unwrap();
    vec![
        manifest_dir.join("README.md"),
        manifest_dir.join("src").join("examples.txt"),
        root.join("README.md"),
        root.join("CONTRIBUTING.md"),
        root.join("crates").join("stuffr").join("README.md"),
        root.join("crates").join("stuffr-core").join("README.md"),
        root.join("crates").join("stuffr-formats").join("README.md"),
    ]
}

/// **An UNQUALIFIED "<number> codecs/containers" claim, checked too.**
///
/// The sibling below only checks a count carrying one of three qualifiers,
/// which is why `crates/stuffr-cli/README.md` could name all five legacy
/// formats and then, twenty lines lower in the same published page, say
/// "Eleven codecs (…) and four containers (…)" with nothing failing. A bare
/// codec count is the same class that test already owns; only the phrasing
/// escaped it.
///
/// The rule has to allow a legitimately NARROWED claim — a feature table's
/// `pure` row really does describe eleven codecs and four containers — so it
/// is: an unqualified count must be the FULL registry figure, unless the
/// clause it sits in carries a narrowing cue (`pure`, `writable`,
/// `round-trip`, `read-only`, `legacy`, `no-default-features`), in which
/// case one of the narrowed figures will do. A claim that is neither is what
/// "Eleven codecs and four containers" was.
///
/// Clauses, not sentences: the flattened text is split on `. ` AND on `|`,
/// so a markdown table cell is its own clause and a cue in the neighbouring
/// row cannot vouch for it.
///
/// **What it does not reach**, so nobody overtrusts it: spelled-out numbers
/// only (a digit evades, as it does in the sibling — no document uses one
/// today); the nouns `codecs` and `containers` only, never `formats`, which
/// is deliberately left to narrate; and a cue anywhere in the clause is
/// taken at face value rather than parsed, so a long clause can excuse a
/// narrowed count it did not really mean.
#[test]
fn no_document_carries_a_stale_unqualified_codec_or_container_count() {
    const LEGACY_ONLY_CODECS: &[&str] = &["compress"];
    const LEGACY_ONLY_CONTAINERS: &[&str] = &["lha", "arj", "arc", "zoo"];
    const CUES: &[&str] = &[
        "pure",
        "pure-tier",
        "writable",
        "round-trip",
        "read-only",
        "legacy",
        "no-default-features",
    ];
    const QUALIFIERS: &[&str] = &["round-trip", "read-only", "pure-tier"];
    /// How many words before the count a narrowing cue may sit.
    const CUE_WINDOW: usize = 8;

    let registry = stuffr::registry();
    let rows = registry.matrix();
    let is_container = |id| registry.container(id).is_some();
    let count = |container: bool, pred: &dyn Fn(&stuffr::FormatRow) -> bool| {
        rows.iter()
            .filter(|r| is_container(r.id) == container && pred(r))
            .count()
    };
    let legacy = |container: bool, id: &str| {
        if container {
            LEGACY_ONLY_CONTAINERS.contains(&id)
        } else {
            LEGACY_ONLY_CODECS.contains(&id)
        }
    };
    // The full count is the only one an unqualified, uncued claim may use.
    let full = |container: bool| count(container, &|_| true);
    // With a cue, any of these is a true statement about some build.
    let narrowed = |container: bool| {
        [
            count(container, &|r| r.write),
            count(container, &|r| !r.write),
            count(container, &|r| !legacy(container, r.id.as_str())),
        ]
    };

    const NUMBERS: &[(&str, usize)] = &[
        ("one", 1),
        ("two", 2),
        ("three", 3),
        ("four", 4),
        ("five", 5),
        ("six", 6),
        ("seven", 7),
        ("eight", 8),
        ("nine", 9),
        ("ten", 10),
        ("eleven", 11),
        ("twelve", 12),
        ("thirteen", 13),
        ("fourteen", 14),
        ("fifteen", 15),
        ("sixteen", 16),
        ("seventeen", 17),
        ("eighteen", 18),
        ("nineteen", 19),
        ("twenty", 20),
    ];

    let mut claims_checked = 0usize;
    for doc in user_facing_documents() {
        let text = std::fs::read_to_string(&doc).unwrap();
        let flat = text.split_whitespace().collect::<Vec<_>>().join(" ");
        for clause in flat.split(". ").flat_map(|s| s.split('|')) {
            let words: Vec<String> = clause
                .split(' ')
                .map(|w| {
                    w.trim_matches(|c: char| !c.is_alphanumeric() && c != '-')
                        .to_lowercase()
                })
                .collect();
            for i in 0..words.len() {
                let Some((_, value)) = NUMBERS.iter().find(|(w, _)| *w == words[i]) else {
                    continue;
                };
                let Some(noun) = words.get(i + 1) else {
                    continue;
                };
                // A qualified claim belongs to the sibling test, which can
                // say exactly which figure it must be.
                if QUALIFIERS.contains(&noun.as_str()) {
                    continue;
                }
                let container = match noun.as_str() {
                    "containers" => true,
                    "codecs" => false,
                    _ => continue,
                };
                claims_checked += 1;
                // The cue must be NEAR the count, not merely somewhere in
                // the clause. Measured why: `default = ["pure", "legacy"]`
                // appears in the same sentence as a general headline count
                // on `crates/stuffr/README.md`, and a clause-wide cue let a
                // deliberately-stalened "eleven codecs and four containers"
                // pass on the strength of a `pure` inside a code span twelve
                // words away. Eight words back through the noun is enough
                // for every real narrowed claim in the tree and not enough
                // for that.
                let from = i.saturating_sub(CUE_WINDOW);
                let cued = words[from..=i + 1]
                    .iter()
                    .any(|w| CUES.contains(&w.as_str()));
                let want_full = full(container);
                let ok = if cued {
                    *value == want_full || narrowed(container).contains(value)
                } else {
                    *value == want_full
                };
                assert!(
                    ok,
                    "{} says `{} {noun}`, but this build registers {want_full} {noun} \
                     (narrowed counts, allowed only in a clause naming a narrowing — \
                     {CUES:?}, within {CUE_WINDOW} words — are {:?}). The clause is \
                     {clause:?}",
                    doc.display(),
                    words[i],
                    narrowed(container),
                );
            }
        }
    }

    assert!(
        claims_checked >= 5,
        "the scan found only {claims_checked} unqualified counts — it is matching nothing \
         and proving nothing"
    );
}

/// **Every "<number> round-trip/read-only/pure-tier <noun>" claim in the
/// documents a user reads, checked against the live registry.**
///
/// This closes a class rather than an instance. Three stale
/// write-capability claims were found BY HAND across Phase 3c Tasks 5, 6 and
/// 7 — `README.md`'s own headline said "four round-trip containers, plus
/// four read-only legacy containers" when the binary had six and two — and
/// the reason no test caught any of them is structural:
/// `the_examples_page_cannot_carry_a_stale_count_or_a_shipped_still_to_come`
/// derives ROW counts from the registry and has no notion of the WRITE
/// column, and it reads only the `--examples` page, not the two READMEs
/// where two of the three lived.
///
/// Three qualifiers, each with a count the registry can answer:
///
/// - `round-trip` — the format can be written as well as read
///   (`FormatRow::write`, which is `ContainerCaps::write` for a container
///   and `CodecCaps::encode` for a codec; zstd's `weak` still counts as
///   writable, which is what `stuffr formats` shows).
/// - `read-only` — it cannot.
/// - `pure-tier` — what remains once the legacy formats are excluded, which
///   is what `--no-default-features --features pure` builds. Included rather
///   than exempted on purpose: a tier-narrowed sentence is a real thing to
///   want to write, and leaving it unchecked would be a loophole any stale
///   claim could take.
///
/// The noun is `codecs` or `containers` and never `formats`, deliberately:
/// `README.md` carries a historical "Phase 3b adds three READ-ONLY legacy
/// formats" sentence that was true when written and is narrating, not
/// claiming. Narrowing the noun is how that stays sayable without carving a
/// per-sentence exception a future stale claim could hide in. An optional
/// `legacy` may sit between the qualifier and the noun ("two read-only
/// legacy containers").
#[test]
fn no_document_carries_a_stale_round_trip_or_read_only_count() {
    // `compress` is to codecs what `LEGACY_ONLY_CONTAINERS` is to
    // containers: registered only when the `legacy` feature is compiled in,
    // which every real build of this binary does (see
    // `the_examples_page_cannot_carry_a_stale_count_or_a_shipped_still_to_come`'s
    // own comment for the measured proof), so it is what a `pure-tier`
    // count excludes.
    const LEGACY_ONLY_CODECS: &[&str] = &["compress"];
    const LEGACY_ONLY_CONTAINERS: &[&str] = &["lha", "arj", "arc", "zoo"];

    let registry = stuffr::registry();
    let rows = registry.matrix();
    let is_container = |id| registry.container(id).is_some();

    let count = |container: bool, pred: &dyn Fn(&stuffr::FormatRow) -> bool| {
        rows.iter()
            .filter(|r| is_container(r.id) == container && pred(r))
            .count()
    };
    let legacy = |container: bool, id: &str| {
        if container {
            LEGACY_ONLY_CONTAINERS.contains(&id)
        } else {
            LEGACY_ONLY_CODECS.contains(&id)
        }
    };

    // (qualifier, is_container) -> the count the registry says
    let expected = |qualifier: &str, container: bool| -> usize {
        match qualifier {
            "round-trip" => count(container, &|r| r.write),
            "read-only" => count(container, &|r| !r.write),
            "pure-tier" => count(container, &|r| !legacy(container, r.id.as_str())),
            other => unreachable!("unhandled qualifier {other}"),
        }
    };

    const NUMBERS: &[(&str, usize)] = &[
        ("one", 1),
        ("two", 2),
        ("three", 3),
        ("four", 4),
        ("five", 5),
        ("six", 6),
        ("seven", 7),
        ("eight", 8),
        ("nine", 9),
        ("ten", 10),
        ("eleven", 11),
        ("twelve", 12),
        ("thirteen", 13),
        ("fourteen", 14),
        ("fifteen", 15),
        ("sixteen", 16),
        ("seventeen", 17),
        ("eighteen", 18),
        ("nineteen", 19),
        ("twenty", 20),
    ];

    let docs = user_facing_documents();

    let mut claims_checked = 0usize;
    for doc in &docs {
        let text = std::fs::read_to_string(doc).unwrap();
        // Whitespace-normalised: every one of these documents wraps, and a
        // count split across a line break must still read as one phrase.
        let flat = text.split_whitespace().collect::<Vec<_>>().join(" ");
        let words: Vec<String> = flat
            .split(' ')
            .map(|w| {
                w.trim_matches(|c: char| !c.is_alphanumeric() && c != '-')
                    .to_lowercase()
            })
            .collect();
        for i in 0..words.len() {
            let Some((_, value)) = NUMBERS.iter().find(|(w, _)| *w == words[i]) else {
                continue;
            };
            let Some(qualifier) = words.get(i + 1) else {
                continue;
            };
            if !["round-trip", "read-only", "pure-tier"].contains(&qualifier.as_str()) {
                continue;
            }
            // An optional `legacy` between the qualifier and the noun.
            let noun = match words.get(i + 2).map(String::as_str) {
                Some("legacy") => words.get(i + 3),
                other => other.and_then(|_| words.get(i + 2)),
            };
            let container = match noun.map(String::as_str) {
                Some("containers") => true,
                Some("codecs") => false,
                // `formats` deliberately excluded — see this test's doc.
                _ => continue,
            };
            claims_checked += 1;
            let want = expected(qualifier, container);
            assert_eq!(
                *value,
                want,
                "{} says `{} {qualifier}{} {}`, but this build has {want}. This is the \
                 check that closes the class three stale write-capability claims were found \
                 by hand in: the row-count guard cannot see the WRITE column, so nothing \
                 else would say so",
                doc.display(),
                words[i],
                if words.get(i + 2).map(String::as_str) == Some("legacy") {
                    " legacy"
                } else {
                    ""
                },
                if container { "containers" } else { "codecs" },
            );
        }
    }

    // A scan that matched nothing would pass forever. These documents carry
    // such claims today and the point of the test is that they stay true.
    assert!(
        claims_checked >= 8,
        "the scan found only {claims_checked} qualified counts across the {} documents — \
         it is matching nothing and proving nothing",
        docs.len()
    );
}

// ---------------------------------------------------------------------
// `salvage`.
//
// The fixture below is a hand-assembled zip, not one built through
// `stuffr pack` (which never writes a duplicate record) or through the
// `zip` crate (no dev-dependency on it here, deliberately — see
// `write_zip_via_pack`'s own doc for why these tests avoid depending on a
// second zip-writing stack). It reproduces the exact shape
// `stuffr-formats/src/zip.rs`'s own `build_shadowing_zip` fixture does
// (that one is `pub(crate)` to `stuffr-formats` and unreachable from here):
// six distinct names, Stored (so a local header's declared compressed size
// is the whole payload, no deflate framing to reason about), with
// `shadowed-a.bin` and `shadowed-b.bin` each written a SECOND time — a
// byte-identical local header and payload, appended after the six
// originals — and a central directory carrying all EIGHT records (the six
// originals, then a duplicate central record for each shadowed name,
// pointing at the SECOND physical copy). A last-record-wins reader (`zip`,
// and so `stuffr list`) collapses that to 6 names; `stuffr salvage`'s raw
// scan walks local headers in FILE ORDER and finds all 8, so scan
// positions 6 and 7 are the two shadows of scan positions 2 and 3.
// ---------------------------------------------------------------------

/// CRC-32 (IEEE 802.3 — the same polynomial zip's own local/central headers
/// use), bit-by-bit. No crate needed for six known-plaintext payloads, and
/// pulling in a dependency for this one computation would be a heavier fix
/// than the six lines below.
fn salvage_fixture_crc32(data: &[u8]) -> u32 {
    let mut crc: u32 = 0xFFFF_FFFF;
    for &byte in data {
        crc ^= u32::from(byte);
        for _ in 0..8 {
            let mask = (crc & 1).wrapping_neg();
            crc = (crc >> 1) ^ (0xEDB8_8320 & mask);
        }
    }
    !crc
}

/// One Stored local file header plus its payload, and the offset it was
/// written at (needed to build the central-directory record alongside it).
struct SalvageFixtureLocalRecord {
    offset: u32,
    name: &'static str,
    crc: u32,
    len: u32,
    bytes: Vec<u8>,
}

fn salvage_fixture_local_record(
    offset: u32,
    name: &'static str,
    payload: &'static [u8],
) -> SalvageFixtureLocalRecord {
    let crc = salvage_fixture_crc32(payload);
    let len = u32::try_from(payload.len()).unwrap();
    let mut bytes = Vec::new();
    bytes.extend_from_slice(&[0x50, 0x4b, 0x03, 0x04]); // local file header signature
    bytes.extend_from_slice(&20u16.to_le_bytes()); // version needed to extract
    bytes.extend_from_slice(&0u16.to_le_bytes()); // general purpose flags
    bytes.extend_from_slice(&0u16.to_le_bytes()); // compression method: Stored
    bytes.extend_from_slice(&0u16.to_le_bytes()); // mod time
    bytes.extend_from_slice(&0x21u16.to_le_bytes()); // mod date
    bytes.extend_from_slice(&crc.to_le_bytes());
    bytes.extend_from_slice(&len.to_le_bytes()); // compressed size
    bytes.extend_from_slice(&len.to_le_bytes()); // uncompressed size
    bytes.extend_from_slice(&u16::try_from(name.len()).unwrap().to_le_bytes());
    bytes.extend_from_slice(&0u16.to_le_bytes()); // extra field length
    bytes.extend_from_slice(name.as_bytes());
    bytes.extend_from_slice(payload);
    SalvageFixtureLocalRecord {
        offset,
        name,
        crc,
        len,
        bytes,
    }
}

fn salvage_fixture_central_record(rec: &SalvageFixtureLocalRecord) -> Vec<u8> {
    let mut bytes = Vec::new();
    bytes.extend_from_slice(&[0x50, 0x4b, 0x01, 0x02]); // central header signature
    bytes.extend_from_slice(&20u16.to_le_bytes()); // version made by
    bytes.extend_from_slice(&20u16.to_le_bytes()); // version needed to extract
    bytes.extend_from_slice(&0u16.to_le_bytes()); // general purpose flags
    bytes.extend_from_slice(&0u16.to_le_bytes()); // compression method: Stored
    bytes.extend_from_slice(&0u16.to_le_bytes()); // mod time
    bytes.extend_from_slice(&0x21u16.to_le_bytes()); // mod date
    bytes.extend_from_slice(&rec.crc.to_le_bytes());
    bytes.extend_from_slice(&rec.len.to_le_bytes()); // compressed size
    bytes.extend_from_slice(&rec.len.to_le_bytes()); // uncompressed size
    bytes.extend_from_slice(&u16::try_from(rec.name.len()).unwrap().to_le_bytes());
    bytes.extend_from_slice(&0u16.to_le_bytes()); // extra field length
    bytes.extend_from_slice(&0u16.to_le_bytes()); // comment length
    bytes.extend_from_slice(&0u16.to_le_bytes()); // disk number start
    bytes.extend_from_slice(&0u16.to_le_bytes()); // internal file attrs
    bytes.extend_from_slice(&0u32.to_le_bytes()); // external file attrs
    bytes.extend_from_slice(&rec.offset.to_le_bytes()); // local header offset
    bytes.extend_from_slice(rec.name.as_bytes());
    bytes
}

/// What the two duplicate records at scan positions 6 and 7 carry.
///
/// [`build_shadowing_zip_fixture`]'s duplicates are byte-for-byte copies —
/// the shape the motivating real-world archive had, and the only shape this
/// file's fixtures modelled until the final whole-branch review. Under it,
/// annotating a duplicate costs nothing to get right and overwriting one on
/// disk costs nothing at all, because the bytes agree; three separate
/// findings hid behind exactly that. [`build_duplicate_name_zip_fixture`]
/// is the other half, and both are kept, because both are real.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
enum SalvageFixtureDuplicates {
    /// A byte-for-byte copy of the record whose name it repeats.
    Identical,
    /// The same name and the same length, DIFFERENT bytes — so both
    /// records still verify as `Intact`, and recovering one and then
    /// overwriting it with the other genuinely loses data.
    Distinct,
}

/// Builds the shadowing fixture this section's own doc comment describes:
/// 6 names, 8 physical local records, a central directory declaring all 8.
fn build_shadowing_zip_fixture() -> Vec<u8> {
    build_duplicating_zip_fixture(SalvageFixtureDuplicates::Identical)
}

/// The realistic counterpart: the same eight records under the same six
/// names, with each duplicate carrying a DIFFERENT, same-length payload and
/// its own recomputed CRC-32.
///
/// Same length on purpose — every size field in both headers stays valid, so
/// the payload bytes and the checksum over them are the ONLY difference
/// between this fixture and [`build_shadowing_zip_fixture`]. Anything that
/// behaves differently between the two does so because the duplicate's
/// content differs, and for no other reason.
fn build_duplicate_name_zip_fixture() -> Vec<u8> {
    build_duplicating_zip_fixture(SalvageFixtureDuplicates::Distinct)
}

fn build_duplicating_zip_fixture(duplicates: SalvageFixtureDuplicates) -> Vec<u8> {
    let originals_src: [(&str, &[u8]); 6] = [
        ("one.txt", b"payload for entry one"),
        ("two.txt", b"payload for entry two"),
        (
            "shadowed-a.bin",
            b"payload for the first record that will be shadowed",
        ),
        (
            "shadowed-b.bin",
            b"payload for the second record that will be shadowed",
        ),
        ("five.txt", b"payload for entry five"),
        ("six.txt", b"payload for entry six"),
    ];

    let mut out = Vec::new();
    let mut originals = Vec::new();
    for (name, payload) in originals_src {
        let rec = salvage_fixture_local_record(u32::try_from(out.len()).unwrap(), name, payload);
        out.extend_from_slice(&rec.bytes);
        originals.push(rec);
    }

    // The two physical duplicates, appended AFTER every original local
    // record — this is what puts their scan positions at 6 and 7. Under
    // `Distinct` their payloads are replaced by same-length, different
    // strings; `salvage_fixture_local_record` recomputes the CRC-32 from
    // whatever payload it is handed, so both the local header's copy and
    // (via `salvage_fixture_central_record`) the central directory's copy
    // follow automatically.
    const DIFFERENT_A: &[u8] = b"DIFFERENT bytes under the first duplicated name!!!";
    const DIFFERENT_B: &[u8] = b"DIFFERENT bytes under the second duplicated name!!!";
    let (payload_a, payload_b) = match duplicates {
        SalvageFixtureDuplicates::Identical => (originals_src[2].1, originals_src[3].1),
        SalvageFixtureDuplicates::Distinct => {
            // Length-preserving is asserted, not eyeballed: a mismatch would
            // make the fixture itself the damage rather than the repeated
            // name it exists to model.
            assert_eq!(originals_src[2].1.len(), DIFFERENT_A.len());
            assert_eq!(originals_src[3].1.len(), DIFFERENT_B.len());
            (DIFFERENT_A, DIFFERENT_B)
        }
    };
    let dup_a = salvage_fixture_local_record(
        u32::try_from(out.len()).unwrap(),
        "shadowed-a.bin",
        payload_a,
    );
    out.extend_from_slice(&dup_a.bytes);
    let dup_b = salvage_fixture_local_record(
        u32::try_from(out.len()).unwrap(),
        "shadowed-b.bin",
        payload_b,
    );
    out.extend_from_slice(&dup_b.bytes);

    let cd_start = u32::try_from(out.len()).unwrap();
    for rec in &originals {
        out.extend_from_slice(&salvage_fixture_central_record(rec));
    }
    out.extend_from_slice(&salvage_fixture_central_record(&dup_a));
    out.extend_from_slice(&salvage_fixture_central_record(&dup_b));
    let cd_size = u32::try_from(out.len()).unwrap() - cd_start;

    out.extend_from_slice(&[0x50, 0x4b, 0x05, 0x06]); // end of central directory signature
    out.extend_from_slice(&0u16.to_le_bytes()); // disk number
    out.extend_from_slice(&0u16.to_le_bytes()); // disk with the start of the cd
    out.extend_from_slice(&8u16.to_le_bytes()); // cd records on this disk
    out.extend_from_slice(&8u16.to_le_bytes()); // cd records total
    out.extend_from_slice(&cd_size.to_le_bytes());
    out.extend_from_slice(&cd_start.to_le_bytes());
    out.extend_from_slice(&0u16.to_le_bytes()); // comment length

    out
}

/// The final whole-branch review's F3, end to end: an ordinary one-entry
/// zip whose entry name holds interior NUL bytes — `zt\0ee\0a.txt`, the
/// exact shape a zeroed run inside `ztree/a.txt` produces, and what the
/// reviewer's sweep actually hit on a mutated `stuffr pack` output.
///
/// Before the fix:
///
/// ```text
/// $ stuffr list   nul.zip     # exit 0
/// $ stuffr test   nul.zip     # exit 0, "exact fidelity"
/// $ stuffr unpack nul.zip -C out
/// stuffr: i/o error: file name contained an unexpected NUL byte
/// exit=1                      # "stuffr itself failed", on input the
///                             # archive chose
/// ```
///
/// It was the ONLY exit 1 in a 31,460-invocation corruption sweep over
/// 2,860 mutated archives in all five salvageable formats. `list` and
/// `test` still exit 0 here and that is correct — neither turns a name into
/// a path, so neither can see the problem; the same asymmetry zip's
/// declared-size lie already has.
#[test]
fn unpack_refuses_a_nul_bearing_entry_name_rather_than_failing() {
    let dir = tmp_dir();
    let rec = salvage_fixture_local_record(0, "zt\0ee\0a.txt", b"hello world\n");
    let mut out = rec.bytes.clone();
    let cd_start = u32::try_from(out.len()).unwrap();
    out.extend_from_slice(&salvage_fixture_central_record(&rec));
    let cd_size = u32::try_from(out.len()).unwrap() - cd_start;
    out.extend_from_slice(&[0x50, 0x4b, 0x05, 0x06]);
    out.extend_from_slice(&0u16.to_le_bytes());
    out.extend_from_slice(&0u16.to_le_bytes());
    out.extend_from_slice(&1u16.to_le_bytes());
    out.extend_from_slice(&1u16.to_le_bytes());
    out.extend_from_slice(&cd_size.to_le_bytes());
    out.extend_from_slice(&cd_start.to_le_bytes());
    out.extend_from_slice(&0u16.to_le_bytes());
    let archive = dir.join("nul.zip");
    std::fs::write(&archive, &out).unwrap();

    let listed = run_output(&["list", archive.to_str().unwrap()]);
    assert_eq!(listed.status.code(), Some(0), "list reads the archive fine");

    let unpacked = run_output(&[
        "unpack",
        archive.to_str().unwrap(),
        "-C",
        dir.join("out").to_str().unwrap(),
    ]);
    let stderr = String::from_utf8(unpacked.stderr).unwrap();
    assert_eq!(
        unpacked.status.code(),
        Some(7),
        "hostile input must never be exit 1: {stderr}"
    );
    assert!(
        stderr.contains("NUL"),
        "and the refusal must name what it refused: {stderr}"
    );
}

fn write_shadowing_zip_fixture(dir: &Path) -> PathBuf {
    let path = dir.join("shadowing.zip");
    std::fs::write(&path, build_shadowing_zip_fixture()).unwrap();
    path
}

fn write_duplicate_name_zip_fixture(dir: &Path) -> PathBuf {
    let path = dir.join("duplicate-names.zip");
    std::fs::write(&path, build_duplicate_name_zip_fixture()).unwrap();
    path
}

/// The two fixtures must actually differ, and differ only where they are
/// meant to. Without this, a builder bug that ignored
/// [`SalvageFixtureDuplicates::Distinct`] would leave every test standing on
/// the new fixture silently re-testing the old one — the precise failure
/// mode (a fixture that does not model what its name says) that hid three
/// findings behind the identical-duplicate fixture in the first place.
#[test]
fn the_two_salvage_duplicate_fixtures_share_a_shape_and_differ_in_content() {
    let identical = build_shadowing_zip_fixture();
    let distinct = build_duplicate_name_zip_fixture();
    assert_eq!(
        identical.len(),
        distinct.len(),
        "length-preserving by construction"
    );
    assert_ne!(identical, distinct, "but not the same bytes");
    // Everything before the first duplicate's local record is byte-identical
    // — the six originals are untouched, which is what makes the two
    // fixtures a controlled pair rather than two different archives.
    let first_dup_at = identical
        .windows(4)
        .enumerate()
        .filter(|(_, w)| *w == b"PK\x03\x04")
        .map(|(i, _)| i)
        .nth(6)
        .expect("the fixture has eight local headers");
    assert_eq!(identical[..first_dup_at], distinct[..first_dup_at]);
}

/// The distinct-content fixture is structurally the same archive to both
/// readers: `list` still collapses it to six rows and still warns that two
/// records are unreachable, and `salvage --list` still reaches all eight.
/// That equivalence is what makes it a controlled comparison — whatever
/// differs between the two fixtures downstream differs because the
/// duplicates' CONTENT differs, not because the archives are shaped
/// differently.
#[test]
fn the_duplicate_name_fixture_reads_the_same_as_the_identical_one() {
    let dir = tmp_dir();
    let archive = write_duplicate_name_zip_fixture(&dir);

    let list_out = run_output(&["list", archive.to_str().unwrap()]);
    let listing = String::from_utf8(list_out.stdout).unwrap();
    assert_eq!(
        listing.lines().count(),
        6,
        "`list` collapses a repeated name whatever the bytes under it: {listing}"
    );
    let warnings = String::from_utf8(list_out.stderr).unwrap();
    assert!(
        warnings.contains("8") && warnings.contains("6"),
        "`list` must still warn that the index declares more records than it reaches: {warnings}"
    );

    let salvage_out = run_output(&["salvage", archive.to_str().unwrap(), "--list"]);
    let stdout = String::from_utf8(salvage_out.stdout).unwrap();
    assert_eq!(
        stdout.lines().count(),
        8,
        "`salvage --list` must reach every scanned record here too: {stdout}"
    );
    assert_eq!(
        stdout.matches("Intact").count(),
        8,
        "every record verifies: the duplicates carry their own correct CRC-32, which is what \
         makes losing one of them a real loss: {stdout}"
    );
}

/// The finding this closes, reproduced as a FILE COUNT and a BYTE
/// COMPARISON, which is how it was found and the only way it shows up at
/// all: before the fix, `salvage -C` on an archive whose duplicates differ
/// printed `8 scanned: 8 written` at exit 0 and left SIX files, with
/// `shadowed-a.bin` holding record 6's payload and record 2's gone —
/// while `salvage --index 2 -o f` returned record 2 correctly the whole
/// time. No error code was involved anywhere; a test asserting on one
/// would have passed through the defect untouched.
#[test]
fn salvage_recovers_both_records_under_a_repeated_name() {
    let dir = tmp_dir();
    let archive = write_duplicate_name_zip_fixture(&dir);
    let out_dir = dir.join("recovered");

    let out = run_output(&[
        "salvage",
        archive.to_str().unwrap(),
        "-C",
        out_dir.to_str().unwrap(),
    ]);
    assert_eq!(
        out.status.code(),
        Some(4),
        "a run that had to change a name must not exit 0: {}",
        String::from_utf8_lossy(&out.stderr)
    );

    let mut names: Vec<String> = std::fs::read_dir(&out_dir)
        .unwrap()
        .map(|e| e.unwrap().file_name().to_string_lossy().into_owned())
        .collect();
    names.sort();
    assert_eq!(
        names,
        [
            "five.txt",
            "one.txt",
            "shadowed-a.bin",
            "shadowed-a.bin.salvaged-6",
            "shadowed-b.bin",
            "shadowed-b.bin.salvaged-7",
            "six.txt",
            "two.txt",
        ],
        "eight records written must be eight files, with the later record of each pair \
         under a name derived from its own scan position"
    );

    // The bytes, not just the count: the record that owns the name keeps
    // it, and the later one is beside it rather than on top of it.
    let first = std::fs::read(out_dir.join("shadowed-a.bin")).unwrap();
    let second = std::fs::read(out_dir.join("shadowed-a.bin.salvaged-6")).unwrap();
    assert_eq!(
        first, b"payload for the first record that will be shadowed",
        "record 2 must keep its own name and its own bytes"
    );
    assert_eq!(
        second, b"DIFFERENT bytes under the first duplicated name!!!",
        "record 6's bytes must be on disk too, not lost to an overwrite"
    );
    assert_ne!(first, second, "the fixture's whole premise");

    let summary = String::from_utf8(out.stderr).unwrap();
    assert!(
        summary.contains("8 written"),
        "every written record is counted, and now there are eight files to match: {summary}"
    );
    assert!(
        summary.contains("2 renamed to avoid a name collision"),
        "the summary must say a name had to be changed: {summary}"
    );
}

/// The complement, and the reason the identical-duplicate fixture is kept:
/// when a duplicate IS a proven copy, nothing is renamed and nothing is
/// written twice — recovering the same bytes under a second name would be
/// noise, not a service. Without this, a fix that renamed every repeated
/// name would pass the test above and quietly double every shadowing
/// archive's output.
#[test]
fn a_proven_duplicate_is_still_skipped_rather_than_renamed() {
    let dir = tmp_dir();
    let archive = write_shadowing_zip_fixture(&dir);
    let out_dir = dir.join("recovered");

    let out = run_output(&[
        "salvage",
        archive.to_str().unwrap(),
        "-C",
        out_dir.to_str().unwrap(),
    ]);
    assert_eq!(out.status.code(), Some(4));
    assert_eq!(
        std::fs::read_dir(&out_dir).unwrap().count(),
        6,
        "six distinct names, and the two byte-identical duplicates add nothing"
    );
    let summary = String::from_utf8(out.stderr).unwrap();
    assert!(
        summary.contains("2 skipped"),
        "a proven copy is skipped, as it always was: {summary}"
    );
    assert!(
        summary.contains("0 renamed to avoid a name collision"),
        "and nothing needed renaming: {summary}"
    );
}

/// The two annotations, measured against each other on the two fixtures.
///
/// On the identical-duplicate archive the duplicates are PROVEN copies and
/// are marked `[shadowed: dup of #N]`. On the distinct-content one nothing
/// is provably a copy, so the same two rows are marked `[name collision: #N
/// uses this name too]` instead — the fact `stuffr list` warns about. Before
/// this, salvage marked the second archive in no way at all, so `list` and
/// `salvage` told a user two contradictory things about the same eight
/// records.
#[test]
fn a_name_collision_and_a_shadow_are_two_different_annotations() {
    let dir = tmp_dir();
    let identical = write_shadowing_zip_fixture(&dir);
    let distinct = write_duplicate_name_zip_fixture(&dir);

    let id_rows =
        String::from_utf8(run_output(&["salvage", identical.to_str().unwrap(), "--list"]).stdout)
            .unwrap();
    assert_eq!(
        id_rows.matches("[shadowed: dup of #").count(),
        2,
        "byte-identical duplicates are shadows: {id_rows}"
    );
    assert_eq!(
        id_rows.matches("[name collision:").count(),
        0,
        "a proven copy reports the stronger fact and only that one: {id_rows}"
    );

    let di_rows =
        String::from_utf8(run_output(&["salvage", distinct.to_str().unwrap(), "--list"]).stdout)
            .unwrap();
    assert_eq!(
        di_rows.matches("[shadowed: dup of #").count(),
        0,
        "no checksum agrees here, so nothing is a proven copy: {di_rows}"
    );
    assert!(
        di_rows.contains("[name collision: #2 uses this name too]"),
        "record 6 repeats record 2's name: {di_rows}"
    );
    assert!(
        di_rows.contains("[name collision: #3 uses this name too]"),
        "record 7 repeats record 3's name: {di_rows}"
    );
    assert_eq!(
        di_rows.matches("[name collision:").count(),
        2,
        "exactly the two repeated names, never the six originals: {di_rows}"
    );
}

/// `--list` prints every record the scan found — 8, on the fixture above —
/// where plain `list` prints only the 6 names its central-directory reader
/// collapses onto. The two shadows are annotated `[shadowed: dup of #N]`,
/// naming the EARLIER scan position they duplicate.
#[test]
fn salvage_list_reaches_every_record() {
    let dir = tmp_dir();
    let archive = write_shadowing_zip_fixture(&dir);

    let listing =
        String::from_utf8(run_output(&["list", archive.to_str().unwrap()]).stdout).unwrap();
    assert_eq!(
        listing.lines().count(),
        6,
        "sanity check on the fixture itself: `list` must collapse to 6 rows: {listing}"
    );

    let out_dir = dir.join("recovered");
    let salvage_out = run_output(&[
        "salvage",
        archive.to_str().unwrap(),
        "-C",
        out_dir.to_str().unwrap(),
        "--list",
    ]);
    let stdout = String::from_utf8(salvage_out.stdout).unwrap();
    assert_eq!(
        stdout.lines().count(),
        8,
        "`salvage --list` must reach every scanned record, shadowed ones included: {stdout}"
    );
    let shadow_lines: Vec<&str> = stdout
        .lines()
        .filter(|l| l.contains("[shadowed: dup of #"))
        .collect();
    assert_eq!(
        shadow_lines.len(),
        2,
        "exactly the two duplicate records must be annotated as shadows: {stdout}"
    );
    assert!(
        shadow_lines[0].contains("[shadowed: dup of #2]"),
        "the first shadow must name scan position 2 (shadowed-a.bin) as its original: {stdout}"
    );
    assert!(
        shadow_lines[1].contains("[shadowed: dup of #3]"),
        "the second shadow must name scan position 3 (shadowed-b.bin) as its original: {stdout}"
    );
}

/// `--index` on `salvage` selects by SCAN position, a different numbering
/// from `list`'s own index — `list --index 6` cannot even reach a row (the
/// listing this fixture prints has only 6 rows, 0-5), while `salvage --index
/// 6` reaches the shadow of scan position 2. Any message naming this
/// numbering must say "scan position", never "index".
#[test]
fn salvage_index_names_a_scan_position_not_a_list_index() {
    let dir = tmp_dir();
    let archive = write_shadowing_zip_fixture(&dir);

    let list_out = run_output(&["list", archive.to_str().unwrap(), "--index", "6"]);
    assert!(
        !list_out.status.success(),
        "list's own numbering has only 6 rows (0-5); --index 6 must not succeed"
    );

    let out_dir = dir.join("recovered");
    let out = run_output(&[
        "salvage",
        archive.to_str().unwrap(),
        "-C",
        out_dir.to_str().unwrap(),
        "--index",
        "6",
        "--list",
    ]);
    // Scan position 6 IS the shadow, so selecting only it selects a record
    // this run skips — exit 4 (Ruling R-N: any entry skipped, for any
    // reason, is a degraded run), not 0.
    assert_eq!(
        out.status.code(),
        Some(4),
        "stderr: {}",
        String::from_utf8_lossy(&out.stderr)
    );
    // Fix round 1, REQUIRED 2: `--list` always reports the FULL scan, even
    // under `--index` — `--index` narrows what is WRITTEN, never what
    // `--list` shows. All 8 rows must still be present, with every position
    // `--index` excluded tagged `[not selected]` and the selected one (6)
    // still showing its own, more permanent `[shadowed: ...]` annotation.
    let stdout = String::from_utf8(out.stdout).unwrap();
    let rows: Vec<&str> = stdout.lines().collect();
    assert_eq!(
        rows.len(),
        8,
        "--list must keep showing the full scan under --index too: {stdout}"
    );
    for (pos, row) in rows.iter().enumerate() {
        assert!(
            row.starts_with(&format!("{pos} ")),
            "row {pos} must lead with its own scan position: {stdout}"
        );
        match pos {
            // Selected, and shadows #2 — shadow detection runs BEFORE
            // `select` (a shadow is a permanent fact about the entry, unlike
            // selection), so this shows its shadow annotation, not
            // "not selected", even though it happens to be the one entry
            // `--index 6` did ask for.
            6 => assert!(
                row.contains("[shadowed: dup of #2]") && !row.contains("[not selected]"),
                "the selected row must show its shadow annotation, not a not-selected one: \
                 {row}"
            ),
            // Not selected, but ALSO a shadow (of #3) — same reasoning as
            // above, from the other direction: the shadow annotation wins
            // over "not selected" regardless of which one selection alone
            // would have produced.
            7 => assert!(
                row.contains("[shadowed: dup of #3]") && !row.contains("[not selected]"),
                "an unselected shadow must still show its shadow annotation: {row}"
            ),
            _ => assert!(
                row.contains("[not selected]"),
                "every non-shadow position other than the selected one must be tagged \
                 not selected: {row}"
            ),
        }
    }

    // The measurement that exposed REQUIRED 1: `--index` must select what
    // is WRITTEN, not just what is reported. Scan position 0 (`one.txt`) is
    // NOT a shadow, so this is the clean case that proves the fix rather
    // than one where nothing would be written either way.
    let out_dir2 = dir.join("recovered2");
    let out2 = run_output(&[
        "salvage",
        archive.to_str().unwrap(),
        "-C",
        out_dir2.to_str().unwrap(),
        "--index",
        "0",
    ]);
    assert!(
        out2.status.success(),
        "stderr: {}",
        String::from_utf8_lossy(&out2.stderr)
    );
    let names: Vec<String> = std::fs::read_dir(&out_dir2)
        .unwrap()
        .map(|e| e.unwrap().file_name().to_string_lossy().into_owned())
        .collect();
    assert_eq!(
        names,
        vec!["one.txt".to_string()],
        "-C DIR --index 0 must leave ONLY the selected record in DIR; found {names:?}"
    );

    // Naming rule: an out-of-range request must say "scan position", never
    // "index" — this project's own conformance harness ended up with
    // colliding property numbers by letting two numbering schemes share a
    // word, and this feature exists specifically not to repeat that.
    let bad = run_output(&[
        "salvage",
        archive.to_str().unwrap(),
        "-C",
        out_dir.to_str().unwrap(),
        "--index",
        "99",
    ]);
    assert!(!bad.status.success());
    let stderr = String::from_utf8_lossy(&bad.stderr);
    assert!(
        stderr.contains("scan position"),
        "an out-of-range --index must name it a scan position: {stderr}"
    );
    assert!(
        !stderr.to_lowercase().contains("index "),
        "the message must never say \"index\", to avoid being read as list's numbering: {stderr}"
    );
}

/// `salvage` without `-C` is refused: it has no single-stream mode, so
/// there is always somewhere recovered content must land.
#[test]
fn salvage_without_directory_is_refused() {
    let dir = tmp_dir();
    let archive = write_shadowing_zip_fixture(&dir);
    let out = run_output(&["salvage", archive.to_str().unwrap()]);
    assert!(!out.status.success());
    assert_eq!(out.status.code(), Some(2), "missing -C is a usage error");
}

/// A default (non-`--list`) run recovers every non-shadowed entry, prints
/// its summary to stderr, and exits 4 — not 0 — because two of the eight
/// scanned records are shadows this run skips (Ruling R-N: any entry
/// skipped, for any reason, is a degraded run).
#[test]
fn salvage_default_run_recovers_and_reports_the_shadow_skips() {
    let dir = tmp_dir();
    let archive = write_shadowing_zip_fixture(&dir);
    let out_dir = dir.join("recovered");
    let out = run_output(&[
        "salvage",
        archive.to_str().unwrap(),
        "-C",
        out_dir.to_str().unwrap(),
    ]);
    assert_eq!(
        out.status.code(),
        Some(4),
        "stderr: {}",
        String::from_utf8_lossy(&out.stderr)
    );
    assert!(
        out.stdout.is_empty(),
        "the default report goes to stderr, not stdout: {:?}",
        String::from_utf8_lossy(&out.stdout)
    );
    let stderr = String::from_utf8(out.stderr).unwrap();
    assert!(
        stderr.contains("8 scanned")
            && stderr.contains("6 written")
            && stderr.contains("2 skipped"),
        "the summary must count the two shadow skips: {stderr}"
    );
    assert_eq!(
        std::fs::read(out_dir.join("one.txt")).unwrap(),
        b"payload for entry one"
    );
    assert_eq!(
        std::fs::read(out_dir.join("shadowed-a.bin")).unwrap(),
        b"payload for the first record that will be shadowed"
    );
    // The two shadows recover nothing under their own name a second time —
    // `place_salvaged_entry` checks `shadows` before ever computing a
    // target, so there is no second write, partial or otherwise, to find.
    assert_eq!(std::fs::read_dir(&out_dir).unwrap().count(), 6);
}

/// The final whole-branch review's F1 reproducer, driven through the real
/// binary: a **228-byte** zip of three Stored local headers whose MIDDLE
/// name is EMPTY — one corrupted length byte, the shape the reviewer hit
/// from ordinary random corruption of a real `stuffr pack` output.
///
/// Before the final fix wave this printed one line — `stuffr: unsafe entry
/// path `` refused: empty entry name` — exited 7 with only `first.txt` on
/// disk, **never attempted `third.txt`, and printed no summary at all**,
/// while `--index 0 --index 2` recovered both. The unit test beside
/// `entries::salvage`'s own code pins the dispositions; this one exists
/// because three of the four things that were wrong are only observable at
/// the CLI: the summary line, the per-entry stderr line, and the exit code
/// a script reads.
#[test]
fn salvage_recovers_past_an_entry_whose_name_containment_refuses() {
    let dir = tmp_dir();
    let mut bytes = Vec::new();
    for (name, payload) in [
        ("first.txt", &b"AAAAAAAAAA"[..]),
        ("", &b"BBBBBBBBBB"[..]),
        ("third.txt", &b"CCCCCCCCCC"[..]),
    ] {
        let rec = salvage_fixture_local_record(u32::try_from(bytes.len()).unwrap(), name, payload);
        bytes.extend_from_slice(&rec.bytes);
    }
    let archive = dir.join("midbad.zip");
    std::fs::write(&archive, &bytes).unwrap();

    let out_dir = dir.join("recovered");
    let out = run_output(&[
        "salvage",
        archive.to_str().unwrap(),
        "-C",
        out_dir.to_str().unwrap(),
    ]);
    let stderr = String::from_utf8(out.stderr).unwrap();

    assert_eq!(
        out.status.code(),
        Some(7),
        "the hostile-path contract is unchanged — the RUN still answers 7: {stderr}"
    );
    assert_eq!(
        std::fs::read(out_dir.join("third.txt")).unwrap(),
        b"CCCCCCCCCC",
        "the record AFTER the refused one is exactly what the old behaviour lost"
    );
    assert_eq!(
        std::fs::read(out_dir.join("first.txt")).unwrap(),
        b"AAAAAAAAAA"
    );
    assert_eq!(
        std::fs::read_dir(&out_dir).unwrap().count(),
        2,
        "and nothing at all is written for the refused entry"
    );
    assert!(
        stderr.contains("3 scanned")
            && stderr.contains("2 written")
            && stderr.contains("1 skipped"),
        "the summary must print — a run that returns Err never prints one, so a user was \
         never told what WAS recovered: {stderr}"
    );
    assert!(
        stderr.contains("empty entry name"),
        "and the refusal must still be named, on stderr, every run: {stderr}"
    );
}

/// A single Stored local record, with the method and CRC-32 field callers
/// choose explicitly rather than derived from the payload — so a fixture
/// can build a record whose declared checksum does not match what it holds
/// (`Partial`/checksum mismatch), or one using a recognised-but-undecodable
/// method (`Unverified`/undecodable method), the two `--list` cause labels
/// [`salvage_list_names_partial_and_unverified_causes`] checks for.
fn salvage_fixture_local_record_with(
    offset: u32,
    name: &'static str,
    payload: &'static [u8],
    method: u16,
    crc: u32,
) -> SalvageFixtureLocalRecord {
    let len = u32::try_from(payload.len()).unwrap();
    let mut bytes = Vec::new();
    bytes.extend_from_slice(&[0x50, 0x4b, 0x03, 0x04]);
    bytes.extend_from_slice(&20u16.to_le_bytes());
    bytes.extend_from_slice(&0u16.to_le_bytes());
    bytes.extend_from_slice(&method.to_le_bytes());
    bytes.extend_from_slice(&0u16.to_le_bytes());
    bytes.extend_from_slice(&0x21u16.to_le_bytes());
    bytes.extend_from_slice(&crc.to_le_bytes());
    bytes.extend_from_slice(&len.to_le_bytes());
    bytes.extend_from_slice(&len.to_le_bytes());
    bytes.extend_from_slice(&u16::try_from(name.len()).unwrap().to_le_bytes());
    bytes.extend_from_slice(&0u16.to_le_bytes());
    bytes.extend_from_slice(name.as_bytes());
    bytes.extend_from_slice(payload);
    SalvageFixtureLocalRecord {
        offset,
        name,
        crc,
        len,
        bytes,
    }
}

/// Builds a two-entry zip: scan position 0 is Stored with a CRC-32 field
/// that disagrees with its payload (`Partial`, checksum-mismatch cause);
/// scan position 1 declares method 99 (AES — recognised by
/// `is_known_method`, not decoded by this build's salvage verifier), with a
/// correct CRC over ITS OWN bytes so only the method is what makes it
/// unverifiable (`Unverified`, undecodable-method cause).
fn build_partial_and_unverified_zip_fixture() -> Vec<u8> {
    let mismatched_payload: &[u8] = b"this payload's crc field below is wrong on purpose";
    let undecodable_payload: &[u8] = b"this method is recognised but this build cannot decode it";

    let mut out = Vec::new();
    let rec0 = salvage_fixture_local_record_with(
        u32::try_from(out.len()).unwrap(),
        "mismatched.bin",
        mismatched_payload,
        0, // Stored
        0xDEAD_BEEF,
    );
    out.extend_from_slice(&rec0.bytes);
    let rec1 = salvage_fixture_local_record_with(
        u32::try_from(out.len()).unwrap(),
        "undecodable.bin",
        undecodable_payload,
        99, // AES — recognised, not decoded
        salvage_fixture_crc32(undecodable_payload),
    );
    out.extend_from_slice(&rec1.bytes);

    let cd_start = u32::try_from(out.len()).unwrap();
    out.extend_from_slice(&salvage_fixture_central_record(&rec0));
    out.extend_from_slice(&salvage_fixture_central_record(&rec1));
    let cd_size = u32::try_from(out.len()).unwrap() - cd_start;

    out.extend_from_slice(&[0x50, 0x4b, 0x05, 0x06]);
    out.extend_from_slice(&0u16.to_le_bytes());
    out.extend_from_slice(&0u16.to_le_bytes());
    out.extend_from_slice(&2u16.to_le_bytes());
    out.extend_from_slice(&2u16.to_le_bytes());
    out.extend_from_slice(&cd_size.to_le_bytes());
    out.extend_from_slice(&cd_start.to_le_bytes());
    out.extend_from_slice(&0u16.to_le_bytes());
    out
}

/// The status column must name a `Partial`/`Unverified` entry's CAUSE, not
/// just its tier — "ran out" and "checksum disagreed" are different
/// diagnoses, and so are "this build cannot decode the method" and "no
/// length was available to bound the payload".
#[test]
fn salvage_list_names_partial_and_unverified_causes() {
    let dir = tmp_dir();
    let path = dir.join("mixed.zip");
    std::fs::write(&path, build_partial_and_unverified_zip_fixture()).unwrap();
    let out_dir = dir.join("recovered");

    let out = run_output(&[
        "salvage",
        path.to_str().unwrap(),
        "-C",
        out_dir.to_str().unwrap(),
        "--list",
    ]);
    // Exit 3 (any Unverified entry) outranks exit 4 (Ruling R-N) even though
    // this run also has a Partial entry.
    assert_eq!(
        out.status.code(),
        Some(3),
        "stderr: {}",
        String::from_utf8_lossy(&out.stderr)
    );
    let stdout = String::from_utf8(out.stdout).unwrap();
    let rows: Vec<&str> = stdout.lines().collect();
    assert_eq!(rows.len(), 2, "{stdout}");
    assert!(
        rows[0].contains("Partial (checksum mismatch)"),
        "a full decode that disagrees with the declared CRC-32 must name that cause: {stdout}"
    );
    assert!(
        rows[1].contains("Unverified (undecodable method)"),
        "a recognised-but-undecodable method must name that cause: {stdout}"
    );
    // `--partial=keep` is the default, so the mismatched entry is still
    // written — under `name.partial`, never its real name.
    assert_eq!(
        std::fs::read(out_dir.join("mismatched.bin.partial")).unwrap(),
        b"this payload's crc field below is wrong on purpose"
    );
    assert!(!out_dir.join("mismatched.bin").exists());
    assert!(!out_dir.join("undecodable.bin").exists());
}

/// Fix round 1, REQUIRED 3: a `--partial=skip` entry must still name its
/// cause in `--list`, not fall through to bare "Partial" — the gap the fix
/// brief singled out because it hits exactly the entries the flag caused to
/// be dropped, in a verb whose whole selling point is per-entry honesty.
#[test]
fn salvage_skipped_partial_names_its_cause() {
    let dir = tmp_dir();
    let path = dir.join("mixed.zip");
    std::fs::write(&path, build_partial_and_unverified_zip_fixture()).unwrap();
    let out_dir = dir.join("recovered");

    let out = run_output(&[
        "salvage",
        path.to_str().unwrap(),
        "-C",
        out_dir.to_str().unwrap(),
        "--partial=skip",
        "--list",
    ]);
    assert_eq!(
        out.status.code(),
        Some(3),
        "stderr: {}",
        String::from_utf8_lossy(&out.stderr)
    );
    let stdout = String::from_utf8(out.stdout).unwrap();
    let rows: Vec<&str> = stdout.lines().collect();
    assert_eq!(rows.len(), 2, "{stdout}");
    assert!(
        rows[0].contains("Partial (checksum mismatch)"),
        "--partial=skip must still name the cause, not fall back to bare \"Partial\": {stdout}"
    );
    // `--partial=skip` means the entry is never written at all, cause known
    // or not.
    assert!(!out_dir.join("mismatched.bin").exists());
    assert!(!out_dir.join("mismatched.bin.partial").exists());
}

/// Fix round 1, REQUIRED 2 (first surface form): `--list` must work with NO
/// destination at all — listing is not recovering, and this is the
/// diagnostic half of the feature that answers "what does this archive
/// hold" without extracting anything.
#[test]
fn salvage_list_works_with_no_destination() {
    let dir = tmp_dir();
    let archive = write_shadowing_zip_fixture(&dir);

    let out = run_output(&["salvage", archive.to_str().unwrap(), "--list"]);
    assert_eq!(
        out.status.code(),
        Some(4),
        "stderr: {}",
        String::from_utf8_lossy(&out.stderr)
    );
    let stdout = String::from_utf8(out.stdout).unwrap();
    assert_eq!(
        stdout.lines().count(),
        8,
        "a report-only run must still list the full scan: {stdout}"
    );
    // Nothing was created anywhere: no `-C` directory, and no directory
    // named after the archive either.
    assert_eq!(
        std::fs::read_dir(&dir).unwrap().count(),
        1,
        "report-only `--list` must touch nothing on disk but the archive itself"
    );
}

/// Fix round 1, REQUIRED 2 (second surface form): `-o FILE --index N`
/// recovers exactly one entry's bytes to a named file, with no `-C`
/// directory involved at all.
#[test]
fn salvage_output_recovers_one_entry_to_a_named_file() {
    let dir = tmp_dir();
    let archive = write_shadowing_zip_fixture(&dir);
    let out_file = dir.join("recovered-one.txt");

    let out = run_output(&[
        "salvage",
        archive.to_str().unwrap(),
        "-o",
        out_file.to_str().unwrap(),
        "--index",
        "0",
    ]);
    assert!(
        out.status.success(),
        "stderr: {}",
        String::from_utf8_lossy(&out.stderr)
    );
    assert_eq!(std::fs::read(&out_file).unwrap(), b"payload for entry one");

    // Refused: more than one selected record.
    let too_many = run_output(&[
        "salvage",
        archive.to_str().unwrap(),
        "-o",
        out_file.to_str().unwrap(),
        "--index",
        "0",
        "--index",
        "1",
    ]);
    assert_eq!(too_many.status.code(), Some(2));

    // Refused: -o together with -C.
    let both = run_output(&[
        "salvage",
        archive.to_str().unwrap(),
        "-o",
        out_file.to_str().unwrap(),
        "-C",
        dir.join("out").to_str().unwrap(),
        "--index",
        "0",
    ]);
    assert_eq!(both.status.code(), Some(2));
}

/// `-o` against a Partial entry lands under `FILE.partial`, never `FILE` —
/// the same rule `-C` follows, applied to a caller-named path.
#[test]
fn salvage_output_suffixes_a_partial_entry() {
    let dir = tmp_dir();
    let path = dir.join("mixed.zip");
    std::fs::write(&path, build_partial_and_unverified_zip_fixture()).unwrap();
    let out_file = dir.join("wanted.bin");

    let out = run_output(&[
        "salvage",
        path.to_str().unwrap(),
        "-o",
        out_file.to_str().unwrap(),
        "--index",
        "0",
    ]);
    assert_eq!(
        out.status.code(),
        Some(4),
        "stderr: {}",
        String::from_utf8_lossy(&out.stderr)
    );
    assert!(
        !out_file.exists(),
        "a Partial entry must never land under the literal -o path"
    );
    let partial_path = dir.join("wanted.bin.partial");
    assert_eq!(
        std::fs::read(&partial_path).unwrap(),
        b"this payload's crc field below is wrong on purpose"
    );
}

// ---------------------------------------------------------------------
// Task 7: the evidence.
//
// A damage catalogue built over ONE archive the REAL `zip` binary wrote
// (never this project's own writer), an external witness (`zip -FF`)
// cross-checked against the identical bytes, and — from the other
// direction — the healthy-archive-agrees-with-list property, proven inside
// `stuffr-formats` itself: see `zip_salvage.rs`'s
// `salvage_of_a_healthy_archive_agrees_with_list`, which this crate has no
// way to duplicate (it does not depend on `stuffr-formats`'s internals, on
// purpose, matching this section's own choice below to hand-parse a real
// zip rather than pull in a second zip-writing/reading stack).
//
// The reference archive: three Stored (`-0`, no compression to reason
// about), no-extra-field (`-X`) entries, so a payload byte or a CRC-32
// field can be mutated in place without moving any offset or length
// anywhere else in the file. What went in is known because THIS TEST chose
// the three files' names and bytes, not recovered from the archive after
// the fact — "the expectation is the pre-damage state, written by zip, not
// by us."
// ---------------------------------------------------------------------

/// One real local file header, parsed directly out of bytes the SYSTEM
/// `zip` wrote — a minimal, test-local mirror of the fixed 30-byte layout
/// `crates/stuffr-formats/src/zip_salvage.rs`'s own scanner reads (see that
/// module for the full field-by-field account). Hand-rolled here, rather
/// than depending on `stuffr-formats` at all, for the same reason this
/// file's `salvage_fixture_local_record` above hand-ASSEMBLES a local
/// header instead of reaching for a zip-writing crate: this test binary
/// has never depended on a second zip stack.
struct RealZipLocalEntry {
    /// Byte offset of this record's `PK\x03\x04` signature.
    offset: usize,
    name: String,
    /// Byte offset of the 4-byte `crc32` field within this record.
    crc_offset: usize,
    /// Byte range of this entry's (Stored, so uncompressed) payload.
    payload: std::ops::Range<usize>,
    /// Byte length of the WHOLE physical record (header + name + extra +
    /// payload) — what a byte-identical duplicate of this record must copy.
    record_len: usize,
}

/// Walks every local file header in `bytes` in file order — the same shape
/// `zip_salvage.rs`'s own raw scan performs, hand-rolled here so this test
/// binary never has to depend on that crate to damage the fixture below.
fn parse_real_zip_local_entries(bytes: &[u8]) -> Vec<RealZipLocalEntry> {
    let mut out = Vec::new();
    let mut i = 0usize;
    while i + 30 <= bytes.len() && bytes[i..i + 4] == [0x50, 0x4b, 0x03, 0x04] {
        let compressed_size =
            u32::from_le_bytes(bytes[i + 18..i + 22].try_into().unwrap()) as usize;
        let name_len = u16::from_le_bytes([bytes[i + 26], bytes[i + 27]]) as usize;
        let extra_len = u16::from_le_bytes([bytes[i + 28], bytes[i + 29]]) as usize;
        let name_start = i + 30;
        let name = String::from_utf8(bytes[name_start..name_start + name_len].to_vec())
            .expect("this section's own fixture names are plain ASCII");
        let payload_start = name_start + name_len + extra_len;
        let payload = payload_start..payload_start + compressed_size;
        let record_len = payload.end - i;
        out.push(RealZipLocalEntry {
            offset: i,
            name,
            crc_offset: i + 14,
            payload,
            record_len,
        });
        i += record_len;
    }
    out
}

/// Byte offset of the end-of-central-directory record. This section's own
/// fixture never carries an archive comment, so it is simply the last
/// four-byte match.
fn find_real_zip_eocd(bytes: &[u8]) -> usize {
    bytes
        .windows(4)
        .rposition(|w| w == b"PK\x05\x06")
        .expect("every archive this section builds must carry an EOCD record")
}

/// Builds the catalogue's one healthy archive — see this section's own
/// header comment for why it is Stored and carries no extra field. Written
/// by the SYSTEM `zip` binary, never by this project's own writer, so every
/// mutation below is damage applied to a tool-verified-good archive, not to
/// one only this project has ever agreed with itself is well-formed.
fn build_real_healthy_zip(dir: &Path) -> (PathBuf, [(&'static str, &'static [u8]); 3]) {
    let entries: [(&str, &[u8]); 3] = [
        ("alpha.txt", b"alpha entry payload, first in the archive"),
        ("beta.txt", b"beta entry payload, sits in the middle"),
        (
            "gamma.bin",
            b"gamma entry payload, the last one in the archive",
        ),
    ];
    let src = dir.join("src");
    std::fs::create_dir(&src).unwrap();
    for (name, data) in &entries {
        std::fs::write(src.join(name), data).unwrap();
    }
    let zip_bin = require_bin("zip");
    let archive = dir.join("healthy.zip");
    run_tool(
        &zip_bin,
        &[
            os(&"-q"),
            os(&"-0"),
            os(&"-X"),
            os(&archive),
            os(&"alpha.txt"),
            os(&"beta.txt"),
            os(&"gamma.bin"),
        ],
        &src,
        b"",
    );
    (archive, entries)
}

/// Runs `stuffr salvage ARCHIVE --list` (report-only: no `-C`, nothing is
/// ever written to disk) and returns its stdout, one string per row — the
/// same rows `describe_salvage_row` builds, in scan order, so `rows[N]`
/// below is scan position `N` whenever every damage catalogue mutation
/// leaves the earlier records discoverable (true of every mutation but the
/// truncated-tail one, which is checked by row COUNT instead).
fn salvage_list_rows(archive: &Path) -> Vec<String> {
    let out = run_output(&["salvage", archive.to_str().unwrap(), "--list"]);
    String::from_utf8(out.stdout)
        .unwrap()
        .lines()
        .map(str::to_string)
        .collect()
}

/// Zeroes every byte from the central directory onward (the CD itself and
/// the EOCD both) — the index destroyed entirely, the shape
/// `zip_salvage.rs`'s "Central-directory reconciliation" section calls the
/// scan's own reason to exist. Shared between the damage catalogue's own
/// row for this mutation and the external-witness test, since both need
/// the identical damaged bytes.
fn mutate_zeroed_central_directory(healthy: &[u8]) -> Vec<u8> {
    let mut bytes = healthy.to_vec();
    let eocd = find_real_zip_eocd(&bytes);
    let cd_offset = u32::from_le_bytes(bytes[eocd + 16..eocd + 20].try_into().unwrap()) as usize;
    for b in &mut bytes[cd_offset..] {
        *b = 0;
    }
    bytes
}

/// Flips 10 bytes in the MIDDLE (`beta.txt`) entry's payload — its declared
/// length and its own CRC-32 field are untouched, and the central directory
/// is untouched too, so this is a shape a reference tool can check with a
/// plain `unzip -t`, no `-FF` recovery step needed at all. Shared between
/// the damage catalogue's own row for this mutation and the external-
/// witness test (fix round 1, REQUIRED 1), since both need the identical
/// damaged bytes.
fn mutate_hole_punched_mid_payload(healthy: &[u8]) -> Vec<u8> {
    let mut bytes = healthy.to_vec();
    let real_entries = parse_real_zip_local_entries(&bytes);
    let beta = &real_entries[1];
    assert!(
        beta.payload.len() >= 15,
        "sanity: room to punch a hole without running past this entry's own payload"
    );
    for b in &mut bytes[beta.payload.start + 5..beta.payload.start + 15] {
        *b ^= 0xFF;
    }
    bytes
}

/// Flips a byte of the FIRST (`alpha.txt`) entry's LOCAL-header `crc32`
/// field only — its payload and the central directory's own copy of the
/// checksum are untouched, so (like the hole-punch mutation above) this is
/// checkable with a plain `unzip -t`. Shared between the damage catalogue's
/// own row for this mutation and the external-witness test (fix round 1,
/// REQUIRED 1).
fn mutate_one_crc_corrupted(healthy: &[u8]) -> Vec<u8> {
    let mut bytes = healthy.to_vec();
    let real_entries = parse_real_zip_local_entries(&bytes);
    let alpha_crc_offset = real_entries[0].crc_offset;
    bytes[alpha_crc_offset] ^= 0xFF;
    bytes
}

/// Appends a byte-identical physical copy of the FIRST entry's local
/// record, and splices a matching duplicate central-directory record
/// (pointing at the copy) into the index — 4 physical records over 3
/// names, the small sibling of `stuffr-formats/src/zip.rs`'s own
/// `build_shadowing_zip` fixture (8 records, 6 names) and this file's own
/// `build_shadowing_zip_fixture` above, built here over an archive the
/// SYSTEM `zip` wrote instead of one this project hand-assembled from
/// nothing.
fn duplicate_first_central_directory_record(healthy: &[u8]) -> Vec<u8> {
    let bytes = healthy.to_vec();
    let eocd = find_real_zip_eocd(&bytes);
    let disk_no = u16::from_le_bytes(bytes[eocd + 4..eocd + 6].try_into().unwrap());
    let disk_cd = u16::from_le_bytes(bytes[eocd + 6..eocd + 8].try_into().unwrap());
    let cd_total = u16::from_le_bytes(bytes[eocd + 10..eocd + 12].try_into().unwrap());
    let cd_size = u32::from_le_bytes(bytes[eocd + 12..eocd + 16].try_into().unwrap()) as usize;
    let cd_offset = u32::from_le_bytes(bytes[eocd + 16..eocd + 20].try_into().unwrap()) as usize;
    let comment_len = u16::from_le_bytes(bytes[eocd + 20..eocd + 22].try_into().unwrap());

    let real_entries = parse_real_zip_local_entries(&bytes);
    let first = &real_entries[0];
    let duplicate_record = bytes[first.offset..first.offset + first.record_len].to_vec();

    let old_cd = bytes[cd_offset..cd_offset + cd_size].to_vec();
    assert_eq!(
        &old_cd[0..4],
        &[0x50, 0x4b, 0x01, 0x02],
        "sanity: the central directory's first record"
    );
    let name_len = u16::from_le_bytes(old_cd[28..30].try_into().unwrap()) as usize;
    let extra_len = u16::from_le_bytes(old_cd[30..32].try_into().unwrap()) as usize;
    let comment_len_rec = u16::from_le_bytes(old_cd[32..34].try_into().unwrap()) as usize;
    let first_cd_len = 46 + name_len + extra_len + comment_len_rec;
    let mut duplicate_cd_record = old_cd[0..first_cd_len].to_vec();

    // The duplicate physical record lands exactly where the OLD central
    // directory used to start — that is where this function inserts it.
    let new_local_offset = cd_offset as u32;
    duplicate_cd_record[42..46].copy_from_slice(&new_local_offset.to_le_bytes());

    let new_cd_start = cd_offset + duplicate_record.len();
    let mut new_cd = old_cd.clone();
    new_cd.extend_from_slice(&duplicate_cd_record);
    let new_total = cd_total + 1;

    let mut out = bytes[..cd_offset].to_vec();
    out.extend_from_slice(&duplicate_record);
    out.extend_from_slice(&new_cd);
    out.extend_from_slice(&[0x50, 0x4b, 0x05, 0x06]);
    out.extend_from_slice(&disk_no.to_le_bytes());
    out.extend_from_slice(&disk_cd.to_le_bytes());
    out.extend_from_slice(&new_total.to_le_bytes());
    out.extend_from_slice(&new_total.to_le_bytes());
    out.extend_from_slice(&(new_cd.len() as u32).to_le_bytes());
    out.extend_from_slice(&(new_cd_start as u32).to_le_bytes());
    out.extend_from_slice(&comment_len.to_le_bytes());
    out
}

/// Damage catalogue row 1/5: a truncated tail — the canonical damaged zip,
/// an interrupted download. Cutting the archive partway through its LAST
/// entry's payload (dropping the central directory along with the missing
/// bytes) must recover the two earlier entries `Intact`, must NOT invent
/// the missing bytes of the third, and must SAY SO.
///
/// **This test asserted the opposite until the final whole-branch review**:
/// that the truncated entry was absent from the scan entirely. That was the
/// behaviour, and it was a correct refusal (`zip -FF` fabricates the
/// missing bytes and reports success — see `zip_salvage.rs`'s module doc)
/// implemented as silence. A three-header archive reported "2 scanned: 2
/// written" at exit 0, at every one of six truncation points swept across
/// the last entry, for a file the user reached for `salvage` precisely
/// because it was truncated. The refusal to invent is unchanged; what the
/// run says about it is not.
#[test]
fn damage_catalogue_truncated_tail() {
    let dir = tmp_dir();
    let (archive, _entries) = build_real_healthy_zip(&dir);
    let healthy = std::fs::read(&archive).unwrap();

    let real_entries = parse_real_zip_local_entries(&healthy);
    assert_eq!(
        real_entries
            .iter()
            .map(|e| e.name.as_str())
            .collect::<Vec<_>>(),
        vec!["alpha.txt", "beta.txt", "gamma.bin"],
        "sanity: the reference archive's own three entries, in file order"
    );
    let gamma = &real_entries[2];
    let cut = gamma.payload.start + gamma.payload.len() / 2;
    let path = dir.join("truncated.zip");
    std::fs::write(&path, &healthy[..cut]).unwrap();

    let rows = salvage_list_rows(&path);
    assert_eq!(
        rows.len(),
        3,
        "all three local headers are there, and the third one being uncompletable is a \
         fact worth a row: {rows:?}"
    );
    assert!(
        rows[0].contains("alpha.txt") && rows[0].contains("Intact"),
        "{rows:?}"
    );
    assert!(
        rows[1].contains("beta.txt") && rows[1].contains("Intact"),
        "{rows:?}"
    );
    assert!(
        rows[2].contains("gamma.bin") && rows[2].contains("Partial (truncated)"),
        "the truncated entry must be named, and named as truncated rather than as a bad \
         checksum — the payload ran out, nothing disagreed: {rows:?}"
    );

    // And the run must not exit 0. Recovering into a directory writes the
    // genuine prefix under `.partial`, never under the entry's real name.
    let out_dir = dir.join("recovered");
    let out = run_output(&[
        "salvage",
        path.to_str().unwrap(),
        "-C",
        out_dir.to_str().unwrap(),
    ]);
    assert_eq!(
        out.status.code(),
        Some(4),
        "a run that dropped something must not exit 0: {}",
        String::from_utf8_lossy(&out.stderr)
    );
    let mut names: Vec<String> = std::fs::read_dir(&out_dir)
        .unwrap()
        .map(|e| e.unwrap().file_name().to_string_lossy().into_owned())
        .collect();
    names.sort();
    assert_eq!(
        names,
        ["alpha.txt", "beta.txt", "gamma.bin.partial"],
        "the surviving prefix lands under `.partial`, never under `gamma.bin`"
    );

    // Not one invented byte: what is on disk is exactly the prefix that
    // survived the cut, and strictly shorter than the entry declared.
    let recovered = std::fs::read(out_dir.join("gamma.bin.partial")).unwrap();
    let declared = gamma.payload.len();
    assert!(
        !recovered.is_empty() && recovered.len() < declared,
        "{} recovered bytes against a declared {declared}",
        recovered.len()
    );
    assert_eq!(
        recovered[..],
        healthy[gamma.payload.start..cut],
        "every recovered byte must come from the truncated file itself — `zip -FF` fills \
         the gap from its own buffer and calls the result fixed"
    );
}

/// The sweep the whole-branch review ran, as a test: every truncation point
/// inside the last entry's payload must produce a row and a non-zero exit.
///
/// One point would not be enough. The defect this closes was uniform — 100,
/// 500, 2000, 3000, 4030 and 4043 bytes of the last payload present all
/// reported "2 scanned" at exit 0 — and a single sample could pass on a
/// boundary while the interior stayed silent.
#[test]
fn every_truncation_point_inside_the_last_entry_is_reported() {
    let dir = tmp_dir();
    let (archive, _entries) = build_real_healthy_zip(&dir);
    let healthy = std::fs::read(&archive).unwrap();
    let real_entries = parse_real_zip_local_entries(&healthy);
    let gamma = &real_entries[2];
    let declared = gamma.payload.len();

    // Both ends included: 0 surviving payload bytes (the header alone) and
    // one byte short of complete.
    for keep in [0, 1, declared / 4, declared / 2, declared - 1] {
        let path = dir.join(format!("truncated-{keep}.zip"));
        std::fs::write(&path, &healthy[..gamma.payload.start + keep]).unwrap();

        let rows = salvage_list_rows(&path);
        assert_eq!(
            rows.len(),
            3,
            "keep={keep}: the third header is there and must be counted: {rows:?}"
        );
        assert!(
            rows[2].contains("Partial (truncated)"),
            "keep={keep}: {rows:?}"
        );

        let out_dir = dir.join(format!("out-{keep}"));
        let out = run_output(&[
            "salvage",
            path.to_str().unwrap(),
            "-C",
            out_dir.to_str().unwrap(),
        ]);
        assert_eq!(
            out.status.code(),
            Some(4),
            "keep={keep}: must not exit 0: {}",
            String::from_utf8_lossy(&out.stderr)
        );
    }

    // The complement, so none of the above can pass by reporting everything
    // as truncated: the UNCUT archive still exits 0 with three clean rows.
    let whole = dir.join("whole.zip");
    std::fs::write(&whole, &healthy).unwrap();
    let out = run_output(&["salvage", whole.to_str().unwrap(), "--list"]);
    assert_eq!(out.status.code(), Some(0));
    let rows = String::from_utf8(out.stdout).unwrap();
    assert_eq!(rows.matches("Partial").count(), 0, "{rows}");
}

/// Damage catalogue row 2/5: a zeroed central directory. With the index
/// destroyed entirely, `salvage_zip` falls back to the raw local-header
/// scan alone and must still find and verify all three entries.
#[test]
fn damage_catalogue_zeroed_central_directory() {
    let dir = tmp_dir();
    let (archive, _entries) = build_real_healthy_zip(&dir);
    let healthy = std::fs::read(&archive).unwrap();
    let path = dir.join("zeroed_cd.zip");
    std::fs::write(&path, mutate_zeroed_central_directory(&healthy)).unwrap();

    let rows = salvage_list_rows(&path);
    assert_eq!(rows.len(), 3, "{rows:?}");
    for (row, name) in rows.iter().zip(["alpha.txt", "beta.txt", "gamma.bin"]) {
        assert!(
            row.contains(name) && row.contains("Intact"),
            "every entry must still be found by the raw scan and verify Intact: {row}"
        );
    }
}

/// Damage catalogue row 3/5: a hole punched mid-payload. Only the MIDDLE
/// entry's content is damaged (its declared length and its own CRC-32
/// field are untouched), so its neighbours must be unaffected and it alone
/// must come back `Partial`.
#[test]
fn damage_catalogue_hole_punched_mid_payload() {
    let dir = tmp_dir();
    let (archive, _entries) = build_real_healthy_zip(&dir);
    let healthy = std::fs::read(&archive).unwrap();
    let path = dir.join("hole_punched.zip");
    std::fs::write(&path, mutate_hole_punched_mid_payload(&healthy)).unwrap();

    let rows = salvage_list_rows(&path);
    assert_eq!(rows.len(), 3, "{rows:?}");
    assert!(
        rows[0].contains("alpha.txt") && rows[0].contains("Intact"),
        "{rows:?}"
    );
    assert!(
        rows[1].contains("beta.txt") && rows[1].contains("Partial"),
        "the punched entry's content no longer matches its own declared CRC-32: {rows:?}"
    );
    assert!(
        rows[2].contains("gamma.bin") && rows[2].contains("Intact"),
        "{rows:?}"
    );
}

/// Damage catalogue row 4/5: one CRC corrupted. Only the FIRST entry's
/// LOCAL-HEADER `crc32` field is flipped — its payload and the central
/// directory's own copy of the checksum are untouched — so the raw scan
/// (which builds its verifier from the LOCAL header, not the central
/// directory) reports a checksum that no longer matches the real content.
#[test]
fn damage_catalogue_one_crc_corrupted() {
    let dir = tmp_dir();
    let (archive, _entries) = build_real_healthy_zip(&dir);
    let healthy = std::fs::read(&archive).unwrap();
    let path = dir.join("crc_corrupted.zip");
    std::fs::write(&path, mutate_one_crc_corrupted(&healthy)).unwrap();

    let rows = salvage_list_rows(&path);
    assert_eq!(rows.len(), 3, "{rows:?}");
    assert!(
        rows[0].contains("alpha.txt") && rows[0].contains("Partial"),
        "the corrupted entry's declared checksum no longer matches its (untouched) payload: \
         {rows:?}"
    );
    assert!(
        rows[1].contains("beta.txt") && rows[1].contains("Intact"),
        "{rows:?}"
    );
    assert!(
        rows[2].contains("gamma.bin") && rows[2].contains("Intact"),
        "{rows:?}"
    );
}

/// Damage catalogue row 5/5: a duplicated record. 8 records over 6 names is
/// `build_shadowing_zip_fixture`'s own shape; this is its 4-records-over-3-
/// names sibling, built over an archive the SYSTEM `zip` wrote.
#[test]
fn damage_catalogue_duplicated_record() {
    let dir = tmp_dir();
    let (archive, _entries) = build_real_healthy_zip(&dir);
    let healthy = std::fs::read(&archive).unwrap();
    let path = dir.join("duplicated.zip");
    std::fs::write(&path, duplicate_first_central_directory_record(&healthy)).unwrap();

    let rows = salvage_list_rows(&path);
    assert_eq!(rows.len(), 4, "3 names, 4 physical records: {rows:?}");
    assert!(
        rows[0].contains("alpha.txt") && rows[0].contains("Intact"),
        "{rows:?}"
    );
    assert!(
        rows[1].contains("beta.txt") && rows[1].contains("Intact"),
        "{rows:?}"
    );
    assert!(
        rows[2].contains("gamma.bin") && rows[2].contains("Intact"),
        "{rows:?}"
    );
    assert!(
        rows[3].contains("alpha.txt")
            && rows[3].contains("Intact")
            && rows[3].contains("[shadowed: dup of #0]"),
        "the extra physical copy must be reported Intact (nothing in it is damaged) AND \
         flagged as shadowing scan position 0: {rows:?}"
    );
}

/// Runs Info-Zip's `zip -FF` against `archive`, answering its `y/n` prompt
/// ("Is this a single-disk archive?" — the only one any fixture in this
/// section provokes) with `y`. Guards against a real failure mode measured
/// while designing this test: given a fully closed stdin instead, `zip -FF`
/// treats the immediate EOF as a blank line at its OWN "try again" prompt
/// and loops forever re-printing its default-answer menu rather than
/// exiting — a hang, not a slow pass, in the REFERENCE tool's own handling
/// of EOF, so a watchdog thread kills the child if it is still running past
/// a generous bound rather than letting a run hang indefinitely.
#[cfg(unix)]
fn run_zip_ff(zip_bin: &Path, archive: &Path, out: &Path) -> std::process::Output {
    let mut child = Command::new(zip_bin)
        .args([os(&"-FF"), os(&archive), os(&"--out"), os(&out)])
        .stdin(Stdio::piped())
        .stdout(Stdio::piped())
        .stderr(Stdio::piped())
        .spawn()
        .unwrap();
    child
        .stdin
        .take()
        .unwrap()
        .write_all(b"y\ny\ny\ny\ny\n")
        .unwrap();

    let pid = child.id();
    let finished = std::sync::Arc::new(std::sync::atomic::AtomicBool::new(false));
    let finished_for_watchdog = finished.clone();
    let watchdog = std::thread::spawn(move || {
        for _ in 0..200 {
            if finished_for_watchdog.load(Ordering::Relaxed) {
                return;
            }
            std::thread::sleep(std::time::Duration::from_millis(100));
        }
        let _ = Command::new("kill").args(["-9", &pid.to_string()]).status();
    });

    let output = child.wait_with_output().unwrap();
    finished.store(true, Ordering::Relaxed);
    watchdog.join().unwrap();
    output
}

/// Runs `unzip -t ARCHIVE` directly — no `-FF` recovery step and no
/// interactive prompt, because the two mutations this is used for
/// (fix round 1, REQUIRED 1) leave the central directory untouched, so
/// `unzip` reads the index exactly as it would for a healthy archive and
/// only its PER-ENTRY decode/CRC-32 check can fail. Returns stdout, one
/// line per entry (plus header/footer lines). Exit status is deliberately
/// not asserted here: a damaged entry makes `unzip -t` exit non-zero by
/// design, and the callers below check per-entry lines, not the process
/// exit code.
fn unzip_test_lines(unzip_bin: &Path, archive: &Path) -> Vec<String> {
    let out = Command::new(unzip_bin)
        .args(["-t", archive.to_str().unwrap()])
        .output()
        .unwrap();
    String::from_utf8_lossy(&out.stdout)
        .lines()
        .map(str::to_string)
        .collect()
}

/// The line naming `name` within `unzip -t`'s output — panics (never
/// silently returns nothing) if `name` is missing entirely, since that
/// would mean the reference tool lost the entry outright rather than
/// merely disagreeing about its checksum.
fn unzip_test_line_for<'a>(lines: &'a [String], name: &str) -> &'a str {
    lines
        .iter()
        .map(String::as_str)
        .find(|l| l.contains(name))
        .unwrap_or_else(|| panic!("`unzip -t` must still report on `{name}`: {lines:?}"))
}

/// Step 3: the external witness, row 1/3. Info-Zip's `zip -FF` is a
/// genuine second implementation of zip recovery, cross-checked here on
/// the zeroed-central-directory shape — the one damage catalogue row that
/// forces BOTH tools onto a raw local-header scan with nothing to
/// reconcile against, so it needs `zip -FF`'s own recovery step (unlike
/// the two sibling tests below it, which check a reference tool directly
/// with no recovery step at all). `zip_salvage.rs`'s own module doc
/// records the ONE shape found where the two tools do NOT agree (a
/// truncated last entry, where `zip -FF` was measured fabricating bytes
/// for content that no longer exists) and why that is Info-Zip's tool
/// being the one that is wrong, rather than tuned away here.
#[cfg(unix)]
#[test]
fn info_zip_recovers_the_same_entries_we_do() {
    let zip_bin = require_bin("zip");
    let unzip_bin = require_bin("unzip");

    let dir = tmp_dir();
    let (archive, _entries) = build_real_healthy_zip(&dir);
    let healthy = std::fs::read(&archive).unwrap();
    let damaged = dir.join("zeroed_cd_for_witness.zip");
    std::fs::write(&damaged, mutate_zeroed_central_directory(&healthy)).unwrap();

    // Our own recovery.
    let rows = salvage_list_rows(&damaged);
    assert_eq!(rows.len(), 3, "{rows:?}");
    for (row, name) in rows.iter().zip(["alpha.txt", "beta.txt", "gamma.bin"]) {
        assert!(
            row.contains(name) && row.contains("Intact"),
            "our own recovery must find every entry, Intact: {row}"
        );
    }

    // Info-Zip's own recovery.
    let fixed = dir.join("witness_fixed.zip");
    let out = run_zip_ff(&zip_bin, &damaged, &fixed);
    assert!(
        out.status.success(),
        "zip -FF failed: {}",
        String::from_utf8_lossy(&out.stderr)
    );
    let test_out = Command::new(&unzip_bin)
        .args(["-t", fixed.to_str().unwrap()])
        .output()
        .unwrap();
    assert!(
        test_out.status.success(),
        "unzip -t reported a problem with zip -FF's own recovered archive: {}",
        String::from_utf8_lossy(&test_out.stdout)
    );
    let test_text = String::from_utf8_lossy(&test_out.stdout);
    for name in ["alpha.txt", "beta.txt", "gamma.bin"] {
        let line = test_text
            .lines()
            .find(|l| l.contains(name))
            .unwrap_or_else(|| {
                panic!("zip -FF's own recovery must still contain `{name}`: {test_text}")
            });
        assert!(
            line.contains("OK"),
            "we call `{name}` Intact; Info-Zip's own independent recovery must agree it \
             decodes cleanly: {line}"
        );
    }
}

/// Step 3: the external witness, row 2/3 (fix round 1, REQUIRED 1). A hole
/// punched mid-payload leaves the central directory untouched, so — unlike
/// the zeroed-CD test above — this needs no `zip -FF` recovery step and no
/// interactive prompt at all: plain `unzip -t` reads the same intact index
/// stuffr's own central-directory reconciliation would, and only its
/// per-entry CRC-32 check can disagree.
#[cfg(unix)]
#[test]
fn info_zip_agrees_on_a_hole_punched_payload() {
    let unzip_bin = require_bin("unzip");

    let dir = tmp_dir();
    let (archive, _entries) = build_real_healthy_zip(&dir);
    let healthy = std::fs::read(&archive).unwrap();
    let path = dir.join("hole_punched_for_witness.zip");
    std::fs::write(&path, mutate_hole_punched_mid_payload(&healthy)).unwrap();

    let rows = salvage_list_rows(&path);
    assert_eq!(rows.len(), 3, "{rows:?}");
    let lines = unzip_test_lines(&unzip_bin, &path);
    for (name, intact) in [
        ("alpha.txt", true),
        ("beta.txt", false),
        ("gamma.bin", true),
    ] {
        let our_row = rows
            .iter()
            .find(|r| r.contains(name))
            .unwrap_or_else(|| panic!("our own recovery must still report `{name}`: {rows:?}"));
        assert_eq!(
            our_row.contains("Intact"),
            intact,
            "our own verdict for `{name}`: {our_row}"
        );
        let their_line = unzip_test_line_for(&lines, name);
        assert_eq!(
            their_line.contains("OK"),
            intact,
            "Info-Zip's own independent verdict for `{name}` must agree with ours: {their_line}"
        );
    }
}

/// Step 3: the external witness, row 3/3 (fix round 1, REQUIRED 1). One
/// CRC corrupted leaves the central directory untouched too — same
/// reasoning as the hole-punch test above, no `zip -FF` step needed.
#[cfg(unix)]
#[test]
fn info_zip_agrees_on_a_corrupted_crc() {
    let unzip_bin = require_bin("unzip");

    let dir = tmp_dir();
    let (archive, _entries) = build_real_healthy_zip(&dir);
    let healthy = std::fs::read(&archive).unwrap();
    let path = dir.join("crc_corrupted_for_witness.zip");
    std::fs::write(&path, mutate_one_crc_corrupted(&healthy)).unwrap();

    let rows = salvage_list_rows(&path);
    assert_eq!(rows.len(), 3, "{rows:?}");
    let lines = unzip_test_lines(&unzip_bin, &path);
    for (name, intact) in [
        ("alpha.txt", false),
        ("beta.txt", true),
        ("gamma.bin", true),
    ] {
        let our_row = rows
            .iter()
            .find(|r| r.contains(name))
            .unwrap_or_else(|| panic!("our own recovery must still report `{name}`: {rows:?}"));
        assert_eq!(
            our_row.contains("Intact"),
            intact,
            "our own verdict for `{name}`: {our_row}"
        );
        let their_line = unzip_test_line_for(&lines, name);
        assert_eq!(
            their_line.contains("OK"),
            intact,
            "Info-Zip's own independent verdict for `{name}` must agree with ours: {their_line}"
        );
    }
}

/// Fix round 5, NEW-G. **A salvage entry that could not be written must be
/// named on stderr by the invocation a user actually types** — plain `-C`,
/// with no `--list`.
///
/// Task 3c's fix round 4 turned a filesystem failure from an aborted run
/// (exit 1, on a name the ARCHIVE chose) into a per-entry skip, and rested
/// that ruling on "the reason is on its own row, so nothing is silent". The
/// row only existed under `--list`. Measured on the shipped binary against a
/// read-only destination and a genuine ENOSPC volume, plain `salvage -C DIR`
/// printed `3 scanned: 0 written … 3 skipped` at exit 4 and **nothing on
/// stderr at all** — so a user could not tell a full disk from one entry the
/// archive made unwritable, which is the exact question that ruling's trade
/// turns on.
///
/// The fixture is the one from `entries.rs`'s own regression test: three
/// healthy Stored entries with a 404-character name in the middle, longer
/// than `NAME_MAX` on every filesystem this project builds for (255 on APFS,
/// ext4 and XFS), so `File::create` refuses it deterministically and without
/// needing a special volume, a permission trick or a `root` check.
///
/// Asserts the whole shape, because each half was separately wrong at some
/// point in this task's history: the run COMPLETES (exit 4, not 1), the
/// entries on either side are on disk with their real bytes, and the failure
/// is NAMED on stderr without `--list`.
#[test]
fn a_salvage_entry_that_cannot_be_written_is_named_on_stderr_without_list() {
    fn stored_local_record(name: &str, payload: &[u8]) -> Vec<u8> {
        let crc = salvage_fixture_crc32(payload);
        let len = u32::try_from(payload.len()).unwrap();
        let mut bytes = Vec::new();
        bytes.extend_from_slice(&[0x50, 0x4b, 0x03, 0x04]);
        bytes.extend_from_slice(&20u16.to_le_bytes()); // version needed
        bytes.extend_from_slice(&0u16.to_le_bytes()); // flags
        bytes.extend_from_slice(&0u16.to_le_bytes()); // Stored
        bytes.extend_from_slice(&0u16.to_le_bytes()); // mod time
        bytes.extend_from_slice(&0x21u16.to_le_bytes()); // mod date
        bytes.extend_from_slice(&crc.to_le_bytes());
        bytes.extend_from_slice(&len.to_le_bytes());
        bytes.extend_from_slice(&len.to_le_bytes());
        bytes.extend_from_slice(&u16::try_from(name.len()).unwrap().to_le_bytes());
        bytes.extend_from_slice(&0u16.to_le_bytes()); // extra len
        bytes.extend_from_slice(name.as_bytes());
        bytes.extend_from_slice(payload);
        bytes
    }

    let dir = tmp_dir();
    let long_name = format!("{}.txt", "L".repeat(400));
    let mut zip = stored_local_record("a.txt", b"AAAA");
    zip.extend_from_slice(&stored_local_record(&long_name, b"BBBB"));
    zip.extend_from_slice(&stored_local_record("z.txt", b"ZZZZ"));
    let archive = dir.join("unwritable-name.zip");
    std::fs::write(&archive, &zip).unwrap();

    let out_dir = dir.join("recovered");
    // No `--list`: this is the invocation the finding is about.
    let out = run_output(&[
        "salvage",
        archive.to_str().unwrap(),
        "--format",
        "zip",
        "-C",
        out_dir.to_str().unwrap(),
    ]);
    let stderr = String::from_utf8_lossy(&out.stderr).to_string();

    assert_eq!(
        out.status.code(),
        Some(4),
        "one unwritable name is a degraded run, never a failed one (and never exit 1, the \
         code reserved for stuffr itself failing, on input the archive chose): {stderr}"
    );
    assert!(
        stderr.contains("could not be written"),
        "the run must SAY an entry was not written, on stderr, without --list — the whole \
         fold rests on this not being silent: {stderr}"
    );
    assert!(
        stderr.contains("#1"),
        "and it must name WHICH entry by scan position, or a user cannot act on it: {stderr}"
    );

    // The survivors on either side, byte-for-byte — `z.txt` is the one the
    // pre-round-4 abort lost entirely.
    assert_eq!(std::fs::read(out_dir.join("a.txt")).unwrap(), b"AAAA");
    assert_eq!(std::fs::read(out_dir.join("z.txt")).unwrap(), b"ZZZZ");
}

/// **Fix round 1's LOW: the prose about which formats salvage actually
/// scans had no guard, and had just gone stale once.**
///
/// `salvage_format_by_name`'s *table* is already pinned against the live
/// registry (`main.rs`'s
/// `salvage_format_by_name_recognises_every_registered_container`), but that
/// table says only which names are *recognised* — every registered container
/// is, compiled scanner or not. Which of them this build can actually SCAN
/// was hand-maintained prose in two places, and both said "only zip" from
/// Salvage Stage 1 until Stage 2 Task 4 noticed: `arc` had been wired for a
/// whole task with neither document mentioning it.
///
/// So this derives the truth from the BINARY rather than from any list.
/// Every name `--format` accepts is run against a junk file: a wired format
/// reaches its own scanner and finds nothing (`the scan found nothing
/// recoverable`, exit 5), an unwired one is refused by `salvage_scan`'s own
/// fallback (`salvage has no scanner for`, exit 3). Those two messages are
/// the discriminator, and they are `entries.rs`'s own words, not this
/// test's guess at them.
///
/// Both documents carry one machine-readable sentence — `Scanners exist
/// for: …` — and both must name exactly that set. A scanner landing without
/// its documentation, or documentation naming a scanner that does not exist,
/// fails here.
#[test]
fn the_documented_salvage_scanner_list_matches_what_the_binary_actually_scans() {
    /// Pulls the comma-separated list out of the one marker sentence both
    /// documents carry.
    fn documented(text: &str, label: &str) -> Vec<String> {
        let at = text
            .find("Scanners exist for:")
            .unwrap_or_else(|| panic!("{label} must carry a `Scanners exist for:` sentence"));
        let rest = &text[at + "Scanners exist for:".len()..];
        let end = rest.find('.').unwrap_or_else(|| {
            panic!("{label}'s `Scanners exist for:` sentence must end in a `.`")
        });
        let mut names: Vec<String> = rest[..end]
            .split(',')
            .map(|n| n.trim().to_string())
            .filter(|n| !n.is_empty())
            .collect();
        names.sort();
        names
    }

    let tmp = tmp_dir();
    let junk = tmp.join("salvage-doc-guard-not-an-archive.bin");
    std::fs::write(&junk, b"these bytes are no format's magic at all\n").unwrap();

    // Every name `salvage_format_by_name` accepts — taken from its own
    // `Usage` message rather than restated here, so a ninth name cannot be
    // added to that table without this test seeing it.
    let usage = run_output(&[
        "salvage",
        "--format",
        "definitely-not-a-format",
        junk.to_str().unwrap(),
        "--list",
    ]);
    let usage_text = String::from_utf8_lossy(&usage.stderr).to_string();
    let recognised: Vec<String> = usage_text
        .split_once("salvage recognizes:")
        .unwrap_or_else(|| panic!("expected the `salvage recognizes:` usage message: {usage_text}"))
        .1
        .split(',')
        .map(|n| n.trim().trim_end_matches('\n').to_string())
        .filter(|n| !n.is_empty())
        .collect();
    assert!(
        recognised.len() >= 8,
        "the parse found {recognised:?}; if that is short the scan is broken, not the table"
    );

    let mut wired: Vec<String> = Vec::new();
    for name in &recognised {
        let out = run_output(&[
            "salvage",
            "--format",
            name,
            junk.to_str().unwrap(),
            "--list",
        ]);
        let stderr = String::from_utf8_lossy(&out.stderr);
        let unwired = stderr.contains("salvage has no scanner for");
        if !unwired {
            assert!(
                stderr.contains("found nothing recoverable"),
                "`--format {name}` over junk answered neither refusal nor an empty scan, so \
                 this test can no longer tell wired from unwired: {stderr}"
            );
            wired.push(name.clone());
        }
    }
    wired.sort();
    assert!(
        !wired.is_empty(),
        "no format scanned at all — the discriminator is broken, not the docs"
    );

    let manifest_dir = Path::new(env!("CARGO_MANIFEST_DIR"));
    let examples = std::fs::read_to_string(manifest_dir.join("src").join("examples.txt")).unwrap();
    let help = String::from_utf8_lossy(&run_output(&["salvage", "--help"]).stdout).to_string();

    assert_eq!(
        documented(&examples, "examples.txt"),
        wired,
        "`examples.txt` names a different set of salvage scanners than this binary has"
    );
    assert_eq!(
        documented(&help, "`salvage --format`'s help"),
        wired,
        "`--format`'s help names a different set of salvage scanners than this binary has"
    );
}

// ---------------------------------------------------------------------
// Salvage Stage 2 Task 7: the legacy damage catalogue, end to end.
//
// The fast half of this catalogue lives beside each scanner — see
// `crates/stuffr-formats/src/legacy/{arc,zoo,lha,arj}_salvage.rs`'s own
// `mod damage_catalogue`, which owns the agreement property (salvage of an
// UNDAMAGED archive must agree exactly with what the ordinary reader
// enumerates) and the full mutation table (truncated tail, a byte flipped
// mid-payload, a header field corrupted, each run with every entry taking
// its turn as the damaged one). Those tests reach parsers and geometry this
// binary deliberately cannot see, exactly as `zip_salvage.rs`'s own
// `salvage_of_a_healthy_archive_agrees_with_list` does for zip.
//
// What this file adds is the part only a process can state: the ROWS a user
// reads, the EXIT CODE a script branches on, and — the claim that separates
// this tool from `zip -FF` — that the bytes on disk after a recovery are a
// genuine prefix of what went in, with nothing invented to fill the gap.
//
// **The evidence behind each format is NOT equal, and these tests say so
// rather than presenting four identical-looking rows:**
//
// * **ARC and ZOO** — the archives are the borrowed `unarc-rs` 0.6.3
//   corpus, written by DOS-era archivers decades before this project
//   existed, each entry carrying the CRC-16 its ORIGINAL writer computed.
//   That checksum is the witness, and no `arc`/`zoo` binary is obtainable
//   on any platform in reach to add a second one.
// * **LHA** — `lhasa` exists, reads `.lzh`, and shares no code with
//   `delharc`. `lhasa_agrees_with_the_lha_damage_catalogue` below uses it
//   as a live witness: it pronounces the archive good BEFORE any damage and
//   names the damaged entry AFTER, so the damage is real by an outside
//   account and not only by ours.
// * **ARJ** — **no `arj`/`unarj` binary is obtainable anywhere in reach.**
//   `no_dedicated_arj_tool_is_obtainable_to_witness_this_catalogue` is the
//   tripwire that keeps that from being quietly forgotten.
// ---------------------------------------------------------------------

/// A checked-in legacy fixture, by path relative to
/// `crates/stuffr-formats/fixtures/legacy/`. `CARGO_MANIFEST_DIR` bakes an
/// absolute path at compile time — see `workspace_source_files` above for
/// the same hazard and the same fix.
fn legacy_fixture(rel: &str) -> PathBuf {
    Path::new(env!("CARGO_MANIFEST_DIR"))
        .parent()
        .unwrap()
        .join("stuffr-formats")
        .join("fixtures")
        .join("legacy")
        .join(rel)
}

/// Runs the truncated-tail catalogue row end to end over one archive.
///
/// `drop_bytes` is cut from the END of the file, which lands inside the
/// LAST entry's payload for every fixture named below (each format's
/// trailer — ARC's two-byte marker, ZOO's 56-byte terminator record, LHA's
/// one-byte marker, ARJ's four-byte marker — is smaller than the amount
/// cut).
///
/// **The expectation is the pre-damage state throughout.** `expected_names`
/// is what the archive held before anything was cut, asserted against the
/// HEALTHY file first; the recovered prefix is compared against the healthy
/// archive's own content for that entry, read back with `cat --index`
/// before the cut is made.
fn legacy_truncated_tail_row(
    label: &str,
    fixture: &str,
    drop_bytes: usize,
    expected_names: &[&str],
) {
    let dir = tmp_dir();
    let healthy_path = legacy_fixture(fixture);
    let healthy = std::fs::read(&healthy_path).unwrap();

    // 1. The pre-damage state, established before anything is damaged.
    let rows = salvage_list_rows(&healthy_path);
    assert_eq!(
        rows.len(),
        expected_names.len(),
        "{label}: sanity, the UNDAMAGED archive's own row count: {rows:?}"
    );
    for (row, name) in rows.iter().zip(expected_names) {
        assert!(
            row.contains(name) && row.contains("Intact"),
            "{label}: every entry of the undamaged archive must verify Intact: {row}"
        );
    }
    let last_index = expected_names.len() - 1;
    let out = run_output(&[
        "cat",
        "--index",
        &last_index.to_string(),
        healthy_path.to_str().unwrap(),
    ]);
    assert_eq!(
        out.status.code(),
        Some(0),
        "{label}: the undamaged archive's last entry must read back cleanly: {}",
        String::from_utf8_lossy(&out.stderr)
    );
    let went_in = out.stdout;
    assert!(
        !went_in.is_empty(),
        "{label}: the last entry must carry a payload for this row to mean anything"
    );

    // 2. The damage.
    let cut = healthy.len() - drop_bytes;
    let damaged = dir.join(format!("truncated-{}", fixture.replace('/', "-")));
    std::fs::write(&damaged, &healthy[..cut]).unwrap();

    // 3. Every earlier entry still Intact, the cut one named and named as
    //    TRUNCATED rather than as a bad checksum — the payload ran out,
    //    nothing disagreed.
    let rows = salvage_list_rows(&damaged);
    assert_eq!(
        rows.len(),
        expected_names.len(),
        "{label}: the cut entry's header is still there and its being uncompletable is a \
         fact worth a row, never silence: {rows:?}"
    );
    for (i, (row, name)) in rows.iter().zip(expected_names).enumerate() {
        assert!(row.contains(name), "{label}: {row}");
        if i == last_index {
            assert!(
                row.contains("Partial (truncated)"),
                "{label}: the cut entry must be named as truncated: {row}"
            );
        } else {
            assert!(
                row.contains("Intact"),
                "{label}: an entry before the cut is untouched: {row}"
            );
        }
    }

    // 4. The run must not exit 0, and the surviving prefix lands under
    //    `.partial` — never under the entry's real name.
    let out_dir = dir.join(format!("recovered-{}", fixture.replace('/', "-")));
    let out = run_output(&[
        "salvage",
        damaged.to_str().unwrap(),
        "-C",
        out_dir.to_str().unwrap(),
    ]);
    assert_eq!(
        out.status.code(),
        Some(4),
        "{label}: a run that could not complete something must not exit 0: {}",
        String::from_utf8_lossy(&out.stderr)
    );
    let partial = out_dir.join(format!("{}.partial", expected_names[last_index]));
    assert!(
        partial.is_file(),
        "{label}: expected {} on disk",
        partial.display()
    );
    assert!(
        !out_dir.join(expected_names[last_index]).exists(),
        "{label}: an incomplete entry must never land under its real name"
    );
    for name in &expected_names[..last_index] {
        let recovered = std::fs::read(out_dir.join(name)).unwrap_or_else(|e| {
            panic!("{label}: an entry before the cut must be recovered whole: {e}")
        });
        assert!(!recovered.is_empty(), "{label}: `{name}` came back empty");
    }

    // 5. **Not one invented byte.** What is on disk is exactly a prefix of
    //    what went in, and strictly shorter than it. `zip -FF` fills the
    //    gap from its own buffer and calls the result fixed; this is the
    //    assertion that says stuffr does not.
    let recovered = std::fs::read(&partial).unwrap();
    assert!(
        !recovered.is_empty() && recovered.len() < went_in.len(),
        "{label}: {} recovered bytes against {} that went in",
        recovered.len(),
        went_in.len()
    );
    assert_eq!(
        recovered[..],
        went_in[..recovered.len()],
        "{label}: every recovered byte must be one the archive itself still held"
    );

    let _ = std::fs::remove_dir_all(&dir);
}

/// ARC. Two borrowed entries (`cpm.arc`, `DDTZ.COM` then `READ.COM`) so the
/// "earlier entries untouched" half of the row is a real claim, and the
/// witness is the CRC-16 each entry's own header records.
#[test]
fn damage_catalogue_arc_truncated_tail() {
    legacy_truncated_tail_row("arc", "arc/cpm.arc", 40, &["DDTZ.COM", "READ.COM"]);
}

/// ARC again, over the one borrowed fixture whose payload IS its content
/// (`store.arc`, method 2, Unpacked): with no decoder between the archive
/// and the file on disk, "the recovered bytes are a prefix of what went in"
/// is a statement about the archive's own bytes.
#[test]
fn damage_catalogue_arc_truncated_tail_over_a_stored_entry() {
    legacy_truncated_tail_row("arc/stored", "arc/store.arc", 5_000, &["LICENSE"]);
}

/// ZOO. `store.zoo`'s single method-0 entry, same reasoning as
/// `store.arc` above — and the same witness, a CRC-16 zoo 2.10 computed.
#[test]
fn damage_catalogue_zoo_truncated_tail() {
    legacy_truncated_tail_row("zoo", "zoo/store.zoo", 5_000, &["license"]);
}

/// LHA. `sample.lzh` — the one legacy fixture an implementation outside
/// this project has agreed with (`lhasa`; see
/// `crates/stuffr-formats/fixtures/legacy/MANIFEST.md`). Two `-lh0-`
/// entries, so both halves of the row are real claims.
#[test]
fn damage_catalogue_lha_truncated_tail() {
    legacy_truncated_tail_row(
        "lha",
        "sample.lzh",
        4,
        &["sample/hello.txt", "sample/sub/b.bin"],
    );
}

/// ARJ. `sample.arj`, and **nothing outside this project has ever agreed
/// with these bytes** — see `the_arj_damage_catalogue_still_has_no_
/// external_witness` below, and this section's own header comment.
#[test]
fn damage_catalogue_arj_truncated_tail() {
    legacy_truncated_tail_row(
        "arj",
        "sample.arj",
        7,
        &["sample/hello.txt", "sample/sub/b.bin"],
    );
}

/// **The external witness for LHA, and the only live one in this
/// catalogue.**
///
/// `lhasa` shares no code with `delharc` (the parser stuffr reads `.lzh`
/// through) and none at all with `lha_salvage.rs`'s own second header
/// parser. Here it does two jobs no assertion of ours can do:
///
/// 1. It pronounces the archive GOOD before any damage — so "the
///    expectation is the pre-damage state" rests on an outside opinion,
///    not only on stuffr having written the file itself.
/// 2. It names the damaged entry AFTER — so the damage is real, and
///    localised to the entry this test aimed at, by an outside account.
///
/// Only then is `stuffr salvage`'s own verdict compared against it: the
/// entry `lhasa` calls bad is the entry salvage calls `Partial`, and every
/// entry `lhasa` calls good is one salvage calls `Intact`.
#[test]
fn lhasa_agrees_with_the_lha_damage_catalogue() {
    let lha_bin = require_lhasa();
    let banner = lhasa_banner(&lha_bin);
    let dir = tmp_dir();
    std::fs::create_dir_all(dir.join("tree/sub")).unwrap();
    let alpha = b"alpha payload, the first entry, repeated often.\n".repeat(120);
    let beta = b"beta payload, the middle entry, repeated often.\n".repeat(90);
    let gamma = b"gamma payload, the last entry, repeated often.\n".repeat(70);
    std::fs::write(dir.join("tree/alpha.txt"), &alpha).unwrap();
    std::fs::write(dir.join("tree/beta.txt"), &beta).unwrap();
    std::fs::write(dir.join("tree/sub/gamma.bin"), &gamma).unwrap();
    let archive = dir.join("healthy.lzh");

    let packed = run_output(&[
        "pack",
        dir.join("tree").to_str().unwrap(),
        "--format",
        "lha",
        "-o",
        archive.to_str().unwrap(),
    ]);
    assert_eq!(packed.status.code(), Some(0));

    /// Every entry `lha t` reported on, and whether it passed. lhasa writes
    /// one `NAME\t- Tested` or `NAME\t- CRC error` phrase per entry; the
    /// `\r`-driven progress it interleaves means a phrase can share a line
    /// with earlier progress text, so this scans phrases rather than lines.
    fn lhasa_verdicts(output: &[u8]) -> Vec<(String, bool)> {
        let text = String::from_utf8_lossy(output).replace('\r', "\n");
        let mut out: Vec<(String, bool)> = Vec::new();
        for chunk in text.split('\n') {
            for (marker, ok) in [("\t- Tested", true), ("\t- CRC error", false)] {
                if let Some(at) = chunk.find(marker) {
                    let name = chunk[..at].rsplit(':').next().unwrap().trim().to_string();
                    if !name.is_empty() && !out.iter().any(|(n, _)| *n == name) {
                        out.push((name, ok));
                    }
                }
            }
        }
        out
    }

    // 1. The outside opinion on the PRE-DAMAGE archive.
    let healthy_test = Command::new(&lha_bin)
        .arg("t")
        .arg(&archive)
        .output()
        .unwrap();
    assert!(
        healthy_test.status.success(),
        "{banner} must accept the undamaged archive: {}{}",
        String::from_utf8_lossy(&healthy_test.stdout),
        String::from_utf8_lossy(&healthy_test.stderr)
    );
    let mut combined = healthy_test.stdout.clone();
    combined.extend_from_slice(&healthy_test.stderr);
    let before = lhasa_verdicts(&combined);
    assert_eq!(
        before
            .iter()
            .map(|(n, _)| n.as_str())
            .collect::<Vec<_>>()
            .join(","),
        "tree/alpha.txt,tree/beta.txt,tree/sub/gamma.bin",
        "sanity: {banner} must report on all three entries — otherwise the comparison below \
         is against a partial account"
    );
    assert!(
        before.iter().all(|(_, ok)| *ok),
        "{banner} must call every entry of the undamaged archive good: {before:?}"
    );

    // 2. The damage: one byte inside the MIDDLE entry's compressed payload.
    //    Located by searching for the entry's own `-lh5-` header, so this
    //    test never asks stuffr where anything is.
    let healthy = std::fs::read(&archive).unwrap();
    let beta_header = healthy
        .windows(5)
        .enumerate()
        .filter(|(_, w)| *w == b"-lh5-")
        .map(|(i, _)| i)
        .nth(1)
        .expect("the middle entry's own method identifier");
    let mut bytes = healthy.clone();
    // Past the header (`header_len` byte, plus its two framing bytes, plus
    // the name and the rest), a few bytes into the payload itself.
    let beta_start = beta_header - 2;
    let payload_at = beta_start + bytes[beta_start] as usize + 2 + 4;
    bytes[payload_at] ^= 0xFF;
    let damaged = dir.join("damaged.lzh");
    std::fs::write(&damaged, &bytes).unwrap();

    // 3. The outside opinion on the DAMAGED archive: one entry bad, and
    //    which one.
    let damaged_test = Command::new(&lha_bin)
        .arg("t")
        .arg(&damaged)
        .output()
        .unwrap();
    assert!(
        !damaged_test.status.success(),
        "{banner} must refuse the damaged archive, or this test proved nothing"
    );
    let mut combined = damaged_test.stdout.clone();
    combined.extend_from_slice(&damaged_test.stderr);
    let after = lhasa_verdicts(&combined);
    let condemned: Vec<&str> = after
        .iter()
        .filter(|(_, ok)| !*ok)
        .map(|(n, _)| n.as_str())
        .collect();
    assert_eq!(
        condemned,
        ["tree/beta.txt"],
        "{banner} must condemn exactly the entry this test damaged: {after:?}"
    );

    // 4. And stuffr must agree with it, entry by entry.
    let rows = salvage_list_rows(&damaged);
    assert_eq!(
        rows.len(),
        5,
        "three files and two directory entries: {rows:?}"
    );
    for (name, ok) in &after {
        let row = rows
            .iter()
            .find(|r| r.contains(name.as_str()))
            .unwrap_or_else(|| {
                panic!("salvage lost `{name}` that {banner} still reports: {rows:?}")
            });
        if *ok {
            assert!(
                row.contains("Intact"),
                "{banner} calls `{name}` good and salvage does not: {row}"
            );
        } else {
            assert!(
                row.contains("Partial"),
                "{banner} calls `{name}` bad and salvage calls it whole: {row}"
            );
        }
    }

    let _ = std::fs::remove_dir_all(&dir);
}

/// **The tripwire, not a skip — and named for what it measures.**
///
/// Fix round 1, F7: this was `the_arj_damage_catalogue_still_has_no_external
/// _witness`, which claims more than the body checks. p7zip reading ARJ is a
/// documented fact, so "no external witness exists" is already false as a
/// statement about the world; what is true, and what decides whether this
/// catalogue can be strengthened, is that **no dedicated ARJ tool is
/// obtainable here**. The name now says that, and the exclusion of `7z` is
/// argued below rather than hidden behind a stronger claim.
///
/// ARJ's whole damage catalogue — here and in
/// `crates/stuffr-formats/src/legacy/arj_salvage.rs` — rests on
/// `unarj-rs` plus this project's own reading of the ARJ specification.
/// `fixtures/legacy/sample.arj` was hand-built from that same reading, so a
/// test can only prove the parser agrees with our own transcription; if
/// both sides share a misreading, every test in this repository stays
/// green. Phase 3c recorded the gap on the read and the write sides, and
/// the brief for this task asked that it be RESTATED rather than quietly
/// forgotten once a catalogue exists.
///
/// This is that restatement, made falsifiable: the day an `arj` or `unarj`
/// binary becomes obtainable, this test goes red and names what to do about
/// it. It is deliberately NOT a `require_bin`-shaped skip — there is
/// nothing to require — and deliberately not a comment, because a comment
/// cannot notice the world changing.
///
/// **`7z` is deliberately NOT in the list below**, though p7zip is
/// documented as reading ARJ. Two reasons, both about what this tripwire is
/// for: it is present on some CI images and absent on others, so naming it
/// would turn "the world changed" into "this runner differs from that one";
/// and nothing in this project has ever measured p7zip against an ARJ
/// stuffr wrote, so promoting it would be adopting a witness on its
/// reputation. If someone does that measurement, `7z` becomes a better
/// answer than this test and this test should go.
#[test]
fn no_dedicated_arj_tool_is_obtainable_to_witness_this_catalogue() {
    for candidate in ["arj", "unarj", "arj32"] {
        assert!(
            which(candidate).is_none(),
            "`{candidate}` is on PATH now. ARJ's catalogue has been checked against nothing \
             but this project's own reading of the spec since Phase 3b — promote \
             `damage_catalogue_arj_truncated_tail` and \
             `legacy::arj_salvage`'s own `mod damage_catalogue` to use this tool as a real \
             external witness (the shape `lhasa_agrees_with_the_lha_damage_catalogue` \
             above already has), and delete this test."
        );
    }

    // And the fixture the catalogue stands on is still the hand-built one,
    // unchanged — so the gap this test names is the gap that actually
    // exists, not a stale description of a fixture somebody has since
    // replaced with tool-written bytes.
    let sample = std::fs::read(legacy_fixture("sample.arj")).unwrap();
    assert_eq!(
        sample.len(),
        173,
        "`sample.arj` is no longer the 173-byte fixture MANIFEST.md describes; re-read its \
         provenance before trusting anything this catalogue asserts"
    );
}

/// **Ruling S-AA, falsified at the surface a user actually reads.**
///
/// Three damaged copies of the SAME borrowed ZOO corpus, differing only in
/// what was done to them, must print three different causes:
///
/// | damage | cause | what a user should do about it |
/// |---|---|---|
/// | the file cut mid-payload | `truncated` | find a longer copy; the bytes are gone |
/// | a byte flipped in an `lzd` payload | `decode failed` | the bytes present are damaged |
/// | a byte flipped in a `Stored` payload | `checksum mismatch` | you have every byte and they are wrong |
///
/// **Two of those three rows read `Partial (truncated)` before this fix
/// round**, over archives from which nothing had been cut — the `lzd` one
/// because its decoder aborts where the damage is, which the old two-cause
/// split could not distinguish from a short file. `stuffr::entries::
/// PartialCause`'s own doc carries the ruling; this is the test that makes
/// it falsifiable: forcing `declared_payload_is_all_present` either way
/// collapses two of these rows onto one string.
///
/// The first and third rows are the CONTROL for the second. All three run
/// over `unarc-rs`'s borrowed corpus — bytes zoo 2.10 wrote — and the
/// difference between `store.zoo` and `default.zoo` is the packing method
/// alone (0 vs 1), so nothing but the codec and the damage varies.
#[test]
fn damage_catalogue_the_three_partial_causes_are_distinguishable() {
    let dir = tmp_dir();
    let stored = std::fs::read(legacy_fixture("zoo/store.zoo")).unwrap();
    let lzd = std::fs::read(legacy_fixture("zoo/default.zoo")).unwrap();

    // Both fixtures' single record puts its payload at the offset its own
    // directory entry declares (`zoo.h`'s `SIZ_DIR`-relative field at +10),
    // read here rather than hardcoded so a fixture change cannot make this
    // test aim at the wrong bytes.
    let payload_at = |bytes: &[u8]| -> usize {
        u32::from_le_bytes(bytes[42 + 10..42 + 14].try_into().unwrap()) as usize
    };
    let declared_len = |bytes: &[u8]| -> usize {
        u32::from_le_bytes(bytes[42 + 24..42 + 28].try_into().unwrap()) as usize
    };

    // 1. The FILE is short: 100 of the declared bytes present.
    let cut = dir.join("cut.zoo");
    std::fs::write(&cut, &stored[..payload_at(&stored) + 100]).unwrap();

    // 2. Every declared byte present, one flipped inside an `lzd` stream —
    //    the decoder stops where the damage is.
    let mut bytes = lzd.clone();
    let at = payload_at(&lzd) + declared_len(&lzd) / 2;
    bytes[at] ^= 0xFF;
    let damaged_lzd = dir.join("lzd.zoo");
    std::fs::write(&damaged_lzd, &bytes).unwrap();

    // 3. Every declared byte present, one flipped inside a Stored payload —
    //    it all decodes and disagrees with the recorded CRC-16.
    let mut bytes = stored.clone();
    let at = payload_at(&stored) + declared_len(&stored) / 2;
    bytes[at] ^= 0xFF;
    let damaged_stored = dir.join("stored.zoo");
    std::fs::write(&damaged_stored, &bytes).unwrap();

    for (path, cause, why) in [
        (
            &cut,
            "Partial (truncated)",
            "bytes this entry declares are genuinely missing from the file",
        ),
        (
            &damaged_lzd,
            "Partial (decode failed)",
            "every declared byte is present and the decoder could not turn them into the \
             declared content — saying `truncated` here sent a user looking for a longer \
             copy of a file that is not short",
        ),
        (
            &damaged_stored,
            "Partial (checksum mismatch)",
            "every declared byte is present, it all decoded, and it is not what was written",
        ),
    ] {
        let rows = salvage_list_rows(path);
        assert_eq!(rows.len(), 1, "{}: {rows:?}", path.display());
        assert!(
            rows[0].contains(cause),
            "{}: expected `{cause}` — {why}: {}",
            path.display(),
            rows[0]
        );
        // And no row may carry a DIFFERENT cause as well, which is what
        // would happen if two of the three strings were prefixes of each
        // other or if the match above were satisfied by a substring.
        for other in [
            "Partial (truncated)",
            "Partial (decode failed)",
            "Partial (checksum mismatch)",
        ] {
            if other != cause {
                assert!(
                    !rows[0].contains(other),
                    "{}: row claims `{other}` as well as `{cause}`: {}",
                    path.display(),
                    rows[0]
                );
            }
        }
    }

    // The complement: none of the three fixtures is damaged in a way this
    // test merely assumed. Undamaged, all three verify.
    for (label, bytes) in [("store.zoo", &stored), ("default.zoo", &lzd)] {
        let whole = dir.join(format!("whole-{label}"));
        std::fs::write(&whole, bytes).unwrap();
        let rows = salvage_list_rows(&whole);
        assert_eq!(rows.len(), 1);
        assert!(
            rows[0].contains("Intact"),
            "{label} must be healthy before anything is done to it: {}",
            rows[0]
        );
    }

    let _ = std::fs::remove_dir_all(&dir);
}