antigravity-setup-system 0.0.89

//! Installing the product itself, from bytes a plan named in advance.
//!
//! The contract splits every software operation into three phases: `plan` with
//! no network, `download` with `artifact_download`, and `apply` with no network
//! again. That split is the whole design. `plan` states the exact artifact for
//! the running platform -- url, byte length, `sha256` -- offline, from a table
//! compiled into this binary. `download` fetches precisely that. `apply`
//! re-checks the digest and extracts, offline. Nothing about what gets
//! installed is decided while the network is reachable.
//!
//! Where it lands is a directory of its own, named by the caller as `--prefix`
//! and distinct from the configuration target. That separation is in the agreed
//! contract and it is the right shape: a setup system owns `native_namespaces`
//! inside a target and preserves everything else verbatim, so installing a
//! program there would claim a path it has promised not to touch -- and one
//! program can serve several targets, which a program living inside one of them
//! could not.

pub mod allocation;
mod cleanup;
mod exposure;
mod input;
mod launch;
pub mod operation;
mod ownership;
mod preparation;
mod records;
mod removal;
mod staging;
mod store;
mod switch;
pub(crate) mod writer;

pub use input::VerifiedArtifact;
pub use writer::Writer;

#[cfg(test)]
use exposure::expose;

use std::fs;
use std::path::{Path, PathBuf};

use serde::{Deserialize, Serialize};

use crate::setup_core::archive::{self, Limits};
#[cfg(test)]
use crate::setup_core::digest;
use crate::setup_core::error::{Error, ReasonCode, Result};

/// How an artifact becomes a program on disk.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum Shape {
    /// The artifact's bytes *are* the executable.
    ///
    /// Grok publishes this way. Its npm package ships the same program
    /// Brotli-compressed to fit the registry's tarball ceiling; the direct
    /// distribution its own installer uses needs no decompression at all, and
    /// the two were measured byte-identical.
    Raw,
    /// A gzip-compressed tar. The executable is one member inside it.
    ///
    /// The rest of the tree is not incidental and is never discarded: codex
    /// ships `rg`, `zsh` and `bwrap` beside its binary, and cursor's executable
    /// is a shell launcher that runs a bundled `node`.
    GzipTar,
    /// A ZIP. The executable is one member inside it.
    ///
    /// One vendor ships this on Windows and a gzip-tar everywhere else, which
    /// is the reason the shape sits on an [`Artifact`] rather than on a
    /// product: the same release, the same version, two container formats and
    /// two different members. Reading it off the product would have been right
    /// for six of the seven and silently wrong for the seventh on one platform
    /// of three -- the shape of defect this estate has now shipped twice.
    Zip,
}

/// One platform's artifact, exactly as a plan will state it.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct Artifact {
    /// The platform key, spelled the way the consumer spells it: `linux/x86_64`.
    pub platform: &'static str,
    /// Where the bytes come from.
    pub url: &'static str,
    /// How many bytes to expect.
    pub bytes: u64,
    /// The `sha256:`-prefixed digest of those bytes.
    pub sha256: &'static str,
    /// How to turn the artifact into a program.
    pub shape: Shape,
    /// The executable's path inside the archive. Empty when [`Shape::Raw`].
    pub member: &'static str,
}

/// How a product's software reaches a machine.
#[derive(Debug, Clone, Copy)]
pub enum Delivery {
    /// Artifacts this provider fetches and places itself.
    Artifacts(&'static [Artifact]),
    /// A package manager resolves a dependency closure.
    ///
    /// Recorded rather than attempted. Running one means executing whatever the
    /// registry resolves to, which is a different security question from
    /// fetching bytes whose digest was decided in advance, and it is not
    /// answered by pretending the operation is the same shape.
    Manager {
        /// The tool the product's own documentation names.
        tool: &'static str,
        /// Why this provider does not run it yet.
        reason: &'static str,
    },
}

/// The version this build pinned before the current one.
///
/// Pin refresh retains the preceding measured release for exact installation
/// and transition checks. Retention does not attest an existing on-disk tree;
/// rollback separately validates its installation receipt and contents.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct Previous {
    /// The version, exactly as the vendor published it.
    pub version: &'static str,
    /// Its artifacts, measured from bytes the same way the current ones were.
    pub artifacts: &'static [Artifact],
}

/// A product's software lifecycle, as the runtime needs to know it.
#[derive(Debug, Clone, Copy)]
pub struct Software {
    /// The version this build installs.
    pub version: &'static str,
    /// The command name the installed program answers to.
    pub command: &'static str,
    /// How it is delivered.
    pub delivery: Delivery,
    /// Platforms this build explicitly declares unsupported.
    pub unsupported: &'static [&'static str],
    /// The version before this one, when this build has had a bump.
    ///
    /// `None` until a harness bumps once. Absent is the honest reading of a
    /// build that has only ever pinned one version — there is nothing to move
    /// between and the operations say so, rather than pretending.
    pub previous: Option<Previous>,
}

/// What is already under a program directory.
///
/// Read at plan time, which is allowed to look at the local disk and is not
/// allowed to reach the network. Without it `software_install` and
/// `software_update` produced byte-identical plans — two names for one act, and
/// neither of them said what was about to be replaced.
#[derive(Debug, Clone, PartialEq, Eq, Default)]
pub struct Present {
    /// Every version directory found, sorted.
    pub versions: Vec<String>,
    /// The version the exposed command currently resolves into, when it does.
    pub exposed: Option<String>,
}

impl Present {
    /// Where the exposed version is recorded, beside the command it describes.
    ///
    /// Dotted so it is hidden on Unix, and under `bin/` so it can never be read
    /// as a version directory.
    #[must_use]
    fn marker(root: &Path, command: &str) -> PathBuf {
        root.join("bin").join(format!(".{command}.version"))
    }

    /// Whether this build's pinned version is one of the ones already there.
    #[must_use]
    pub fn holds(&self, version: &str) -> bool {
        self.versions.iter().any(|found| found == version)
    }

    /// Read what a program directory holds, told which member the exposed
    /// thing was made from.
    ///
    /// A missing or unreadable directory reads as empty rather than failing: a
    /// plan for a prefix that does not exist yet is exactly the ordinary case.
    ///
    /// Windows exposes a JavaScript entry point as `<command>.cmd`, so a
    /// reading that only ever looked for `<command>` reports nothing exposed on
    /// exactly the harness that needed the launcher.
    ///
    /// **There was a member-blind `under(root, command)` beside this, and it is
    /// gone.** It passed `member = ""`, which is a true statement for a native
    /// binary and a false one for pi, whose members are all
    /// `package/dist/bundle/cli.js`. Both production callers -- `software` and
    /// `rollback` on the human surface -- took the short one, so on Windows
    /// `fs::metadata(bin/pi)` failed, `exposed` came back `None`, and a
    /// rollback that had worked reported *"the prefix still runs something
    /// else"*. Every test of the path used `codex`, whose member-blind and
    /// member-aware names are identical, so the suite was green on all three
    /// systems and never entered the branch.
    ///
    /// Removing the short constructor is the repair rather than fixing the two
    /// call sites: a defaulted member preserves every future instance of the
    /// same mistake, and changing the signature turned both of them into
    /// compile errors.
    #[must_use]
    pub fn under_named(root: &Path, command: &str, member: &str) -> Self {
        Self::under_on(root, command, member, cfg!(windows))
    }

    /// The same reading, with the platform as an argument rather than as a
    /// `cfg`.
    ///
    /// Same reason [`exposed_name_on`] takes one, and the same reason spelled
    /// out there: a `cfg!` makes the Windows branch provable only on Windows,
    /// and this branch is the one that was wrong. A reading laid out the way
    /// Windows lays it out can now be asserted from Linux.
    #[must_use]
    pub fn under_on(root: &Path, command: &str, member: &str, windows: bool) -> Self {
        let mut versions: Vec<String> = fs::read_dir(root)
            .into_iter()
            .flatten()
            .flatten()
            .filter(|entry| entry.path().is_dir())
            .filter_map(|entry| entry.file_name().into_string().ok())
            // `bin` holds the exposed command and a dotted directory holds this
            // provider's own bookkeeping. Neither is a version.
            .filter(|name| name != "bin" && !name.starts_with('.'))
            .collect();
        versions.sort();

        // The link points into the version directory it was installed from, so
        // the version is the component right under the root.
        //
        // Resolved rather than read. `expose` writes an absolute target, which
        // a plain `strip_prefix` handles — but a link someone rewrote by hand
        // as `../<version>/<member>` does not: its first component is `bin`,
        // and the answer becomes "no entry point names this version" while the
        // entry point names it. Resolving costs one syscall and is right for
        // both. A dangling link resolves to nothing, which is also correct:
        // nothing usable is exposed.
        // Recorded, not inferred -- and the reason is Windows.
        //
        // Resolving the link was the only reading here, and it cannot work on a
        // system where `expose` does not make a link. Windows reserves symlink
        // creation for privileged processes, so the exposed command is a hard
        // link or a copy: canonicalizing it returns its own path, its first
        // component under the root is `bin`, and the answer became "no version
        // is exposed" on a prefix where one plainly was.
        //
        // That was not only cosmetic. `Present::exposed` is what separates an
        // install from an update, so on Windows every `software_update` saw an
        // empty prefix and refused as an update of nothing -- while the version
        // it would have updated sat right there. Found by the three-OS matrix
        // on the first Windows run of the rollback tests.
        // A record is only ever believed about a command that resolves. A
        // dangling link exposes nothing whatever the record says -- the record
        // remembers what `expose` last pointed at, and someone can break that
        // by hand afterwards. `metadata` follows links, so this is false for a
        // dangling one and true for both a real file and a live link.
        let exposed_as = exposed_name_on(command, member, windows);
        let usable = fs::metadata(root.join("bin").join(&exposed_as)).is_ok();
        let marker = Self::marker(root, command);
        let exposed = fs::read_to_string(&marker)
            .ok()
            .filter(|_| usable)
            .map(|held| held.trim().to_owned())
            // A hand-edited or half-written marker must not name a version that
            // is not there.
            .filter(|name| versions.contains(name))
            .or_else(|| {
                // Nothing recorded: a prefix written before this existed, or one
                // someone arranged themselves. Where a real link is what is
                // there, reading it is still the truth.
                fs::canonicalize(root.join("bin").join(&exposed_as))
                    .ok()
                    .zip(fs::canonicalize(root).ok())
                    .and_then(|(to, base)| {
                        to.strip_prefix(&base).ok().and_then(|rest| {
                            rest.components()
                                .next()
                                .map(|first| first.as_os_str().to_string_lossy().into_owned())
                        })
                    })
                    .filter(|name| versions.contains(name))
            });

        Self { versions, exposed }
    }
}

/// What an install produced.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct Installed {
    /// The version now on disk.
    pub version: String,
    /// The directory holding this version.
    pub root: PathBuf,
    /// The executable a caller runs.
    pub executable: PathBuf,
    /// How many files the artifact produced.
    pub files: usize,
}

impl Software {
    /// Every version this build can name, current first.
    ///
    /// One element until the harness has been bumped once, two after. Used to
    /// say in a refusal what *is* available rather than only what is not.
    #[must_use]
    pub fn versions(&self) -> Vec<&'static str> {
        let mut named = vec![self.version];
        if let Some(earlier) = self.previous {
            named.push(earlier.version);
        }
        named
    }

    /// This build, as it describes one of the versions it names.
    ///
    /// `None` for the argument means the pinned version, which is what an
    /// omitted `--software-version` means on the wire. A named version is
    /// either the pinned one or the one pinned before it; anything else
    /// returns `None` here, and the caller turns that into a refusal in its own
    /// error vocabulary.
    ///
    /// Returning a whole [`Software`] rather than a version string is what
    /// keeps this to one resolution point: `artifact_for`, `member_hint`,
    /// `install` and `remove` all read the value they already read, and none of
    /// them learns that a second pin exists.
    #[must_use]
    pub fn at(&self, asked: Option<&str>) -> Option<Self> {
        match asked {
            None => Some(*self),
            Some(wanted) if wanted == self.version => Some(*self),
            Some(wanted) => self
                .previous
                .filter(|earlier| earlier.version == wanted)
                .map(|earlier| Self {
                    version: earlier.version,
                    delivery: Delivery::Artifacts(earlier.artifacts),
                    ..*self
                }),
        }
    }

    /// This build, as it describes the release those exact bytes belong to.
    ///
    /// `apply` is handed a file, not a version. Reading which release it is
    /// from the digest makes the version an **observation** rather than a claim
    /// that travelled beside the bytes: a caller cannot install the previous
    /// tree under the current version's name by relabelling a flag, because
    /// nothing here reads a label.
    #[must_use]
    pub fn for_bytes(&self, os: &str, arch: &str, digest: &str) -> Option<Self> {
        self.versions()
            .into_iter()
            .filter_map(|version| self.at(Some(version)))
            .find(|candidate| {
                candidate
                    .artifact_for(os, arch)
                    .is_ok_and(|artifact| artifact.sha256 == digest)
            })
    }

    /// Where this build's own artifacts put the executable inside their tree.
    ///
    /// A *hint*, and named one deliberately: it is right for a version this
    /// build installed and is only a first guess for a tree an older build
    /// wrote. [`rollback`] tries it, then the flat shape, and refuses naming
    /// both rather than pointing a command at a path it did not verify.
    #[must_use]
    fn member_hint(&self) -> &'static str {
        match self.delivery {
            Delivery::Artifacts(artifacts) => {
                artifacts.first().map_or(self.command, |entry| entry.member)
            }
            Delivery::Manager { .. } => self.command,
        }
    }

    /// The member of **this platform's** artifact, or the hint when the table
    /// has no row for it.
    ///
    /// The hint is the first row of the table, and deriving an exposed name
    /// from it is correct exactly until one platform's member classifies
    /// differently from the first row's. Cursor is that shape: Unix members
    /// carry no extension, the Windows member is a `.cmd` — so a plan built
    /// from the hint promised `bin/agent` while the apply, which resolves this
    /// host's artifact, wrote `bin/agent.cmd`. The consumer's six-leg matrix
    /// found it on released `0.0.50`, Windows only, both architectures, with
    /// *"the planned entry point is not on disk"*. Every reader of an exposed
    /// name goes through here now; the hint remains only as the fallback for
    /// a platform the vendor never published for, where nothing was ever
    /// installed under any name.
    #[must_use]
    pub fn member_on(&self, os: &str, arch: &str) -> &'static str {
        self.artifact_for(os, arch)
            .map_or_else(|_| self.member_hint(), |artifact| artifact.member)
    }

    /// [`Self::member_on`] for the machine this process runs on.
    #[must_use]
    pub fn member_here(&self) -> &'static str {
        let (os, arch) = crate::setup_core::platform_of_this_host();
        self.member_on(os, arch)
    }

    /// The artifact for one platform, or the reason there is not one.
    ///
    /// # Errors
    ///
    /// Refuses with `unsupported_platform` when the vendor publishes nothing
    /// for this operating system, and `unsupported_architecture` when it
    /// publishes for the system but not this machine.
    pub fn artifact_for(&self, os: &str, arch: &str) -> Result<&'static Artifact> {
        let artifacts = match self.delivery {
            Delivery::Artifacts(artifacts) => artifacts,
            Delivery::Manager { tool, reason } => {
                return Err(Error::new(
                    ReasonCode::UnsupportedOperation,
                    format!("{} is delivered by {tool}: {reason}", self.command),
                ));
            }
        };

        let wanted = format!("{os}/{arch}");
        if let Some(found) = artifacts.iter().find(|entry| entry.platform == wanted) {
            return Ok(found);
        }

        // Distinguish "no build for this system" from "no build for this
        // machine". The consumer's closed reason set separates them, and the
        // two are different problems for whoever reads the refusal.
        let prefix = format!("{os}/");
        let system_is_published = artifacts
            .iter()
            .any(|entry| entry.platform.starts_with(&prefix));
        let reason = if system_is_published {
            ReasonCode::UnsupportedArchitecture
        } else {
            ReasonCode::UnsupportedPlatform
        };
        Err(Error::new(
            reason,
            format!(
                "{} publishes no build for {wanted}; it publishes {}",
                self.command,
                artifacts
                    .iter()
                    .map(|entry| entry.platform)
                    .collect::<Vec<_>>()
                    .join(", ")
            ),
        ))
    }
}

impl Artifact {
    /// Check downloaded bytes against what the plan said they would be.
    ///
    /// Both the length and the digest, in that order: a truncated download is
    /// the common case and saying so is more useful than a digest mismatch.
    ///
    /// # Errors
    ///
    /// Refuses with `integrity_mismatch` when either disagrees.
    pub fn verify(&self, downloaded: &Path) -> Result<()> {
        VerifiedArtifact::open(self, downloaded).map(|_| ())
    }

    /// How much this artifact is allowed to produce.
    ///
    /// A compressed length says nothing about what it inflates to, so the limit
    /// is the caller's rather than the archive's. Sixteen times the compressed
    /// size with a floor covers every measured artifact -- the widest is
    /// claude's, at a little over three -- and stops a stream that would
    /// otherwise keep producing until the disk filled.
    #[must_use]
    pub const fn limits(&self) -> Limits {
        Limits {
            entries: 65_536,
            bytes: match self.bytes.checked_mul(16) {
                Some(scaled) if scaled > 64 * 1024 * 1024 => scaled,
                _ => 64 * 1024 * 1024,
            },
        }
    }
}

/// Install verified bytes, replacing only an unchanged owned or exactly adopted tree.
///
/// The digest is checked here rather than trusted from the download phase,
/// because this phase is the one that runs without a network and is therefore
/// the one whose check means something.
///
/// # Errors
///
/// Refuses an artifact that does not match the plan, an archive this reader
/// will not accept, or an archive that does not contain the member it named.
pub fn install(
    software: &Software,
    artifact: &Artifact,
    downloaded: &Path,
    root: &Path,
) -> Result<Installed> {
    let source = VerifiedArtifact::open(artifact, downloaded)?;
    install_verified(software, artifact, source, root)
}

/// Install from the held artifact already verified before the writer lock.
///
/// The extraction stream is checked again before staged bytes can replace an
/// installed version. No artifact path is reopened after verification.
///
/// # Errors
/// Refuses changed artifact bytes, invalid archives, binding mismatches or I/O failures.
pub fn install_verified(
    software: &Software,
    artifact: &Artifact,
    mut source: VerifiedArtifact,
    root: &Path,
) -> Result<Installed> {
    require_idle(software, root)?;
    source.begin(artifact)?;
    records::io(fs::create_dir_all(root))?;
    Writer::acquire(root)?.install_verified(software, artifact, source)
}

fn install_locked(
    software: &Software,
    artifact: &Artifact,
    source: VerifiedArtifact,
    root: &Path,
) -> Result<Installed> {
    install_for(software, artifact, source, root, None)
}

fn install_for(
    software: &Software,
    artifact: &Artifact,
    mut source: VerifiedArtifact,
    root: &Path,
    operation: Option<&operation::Binding>,
) -> Result<Installed> {
    require_idle_for(software, root, operation)?;
    source.begin(artifact)?;
    let version_root = root.join(software.version);

    let member = if artifact.shape == Shape::Raw {
        software.command
    } else {
        artifact.member
    };
    let mut transaction = staging::Staging::begin_for(
        root,
        software.command,
        software.version,
        member,
        artifact.sha256,
        operation,
    )?;
    let staging = transaction.stage_path();
    let output = transaction.destination()?;

    let files = match artifact.shape {
        Shape::Raw => {
            archive::place_executable_into(source.reader(), Path::new(software.command), &output)?;
            1
        }
        Shape::GzipTar | Shape::Zip => {
            let entries = if artifact.shape == Shape::Zip {
                archive::extract_zip_into(source.reader(), &staging, artifact.limits(), &output)?
            } else {
                archive::extract_gzip_tar_into(
                    source.reader(),
                    &staging,
                    artifact.limits(),
                    &output,
                )?
            };
            let found = entries
                .iter()
                .any(|entry| entry.path == artifact.member && entry.kind == archive::Kind::File);
            if !found {
                // The journal owns this incomplete stage. Recovery may discard
                // only that physical directory; the installed version is intact.
                return Err(Error::new(
                    ReasonCode::IntegrityMismatch,
                    format!(
                        "the archive does not contain {}, which the plan named as the executable",
                        artifact.member
                    ),
                ));
            }
            entries.len()
        }
    };

    source.finish()?;
    // Windows holds extraction directories against rename until this closes.
    drop(output);

    transaction.record_files(files)?;
    transaction.promote()?;

    let exposed = root
        .join("bin")
        .join(exposed_name(software.command, artifact.member));
    transaction.expose()?;
    transaction.complete()?;

    Ok(Installed {
        version: software.version.to_owned(),
        root: version_root,
        executable: exposed,
        files,
    })
}

/// Recover the one recorded software transaction for this command.
///
/// Unrecorded staging, quarantine and temporary file names are never touched.
/// Incomplete extraction or promotion preserves the previous version. A promoted
/// tree completes its entry-point exposure before its recorded predecessor is
/// removed. Directory identities are checked before and after relative renames.
///
/// # Errors
/// Refuses malformed journals, changed identities and unavailable filesystem operations.
pub fn recover(software: &Software, root: &Path) -> Result<Vec<String>> {
    if !records::leaf(software.command) {
        return Err(records::refuse());
    }
    if require_idle(software, root).is_ok() {
        return Ok(Vec::new());
    }
    Writer::acquire(root)?.recover(software)
}

fn recover_locked(software: &Software, root: &Path) -> Result<Vec<String>> {
    let installation = staging::Staging::load(root, software.command)?;
    let removal = removal::Removal::load(root, software.command)?;
    let switch = switch::Switch::load(root, software.command)?;
    if usize::from(installation.is_some())
        + usize::from(removal.is_some())
        + usize::from(switch.is_some())
        > 1
    {
        return Err(records::refuse());
    }
    if let Some(switch) = switch {
        let version = switch.version().to_owned();
        switch.complete()?;
        return Ok(vec![format!(
            "completed the recorded launch switch to {version}"
        )]);
    }
    if let Some(removal) = removal {
        let version = removal.version().to_owned();
        removal.complete()?;
        return Ok(vec![format!("completed the recorded removal of {version}")]);
    }
    let Some(transaction) = installation else {
        require_idle(software, root)?;
        return Ok(Vec::new());
    };
    let version = transaction.version().to_owned();
    if transaction.recover()? {
        transaction.expose()?;
        transaction.complete()?;
        Ok(vec![format!(
            "completed the recorded installation of {version}"
        )])
    } else {
        Ok(vec![format!(
            "discarded the recorded incomplete installation of {version}; the previous tree is intact"
        )])
    }
}

/// Refuse a new operation while an install, removal or launch switch is pending.
///
/// A different plan cannot authorize recovery of an earlier installation. This
/// check reads only the journal entry; malformed records also remain untouched.
/// The caller must repeat it under the prefix lock before making any effect.
///
/// # Errors
/// Returns `RecoveryRequired` for an existing or inaccessible journal.
pub fn require_idle(software: &Software, root: &Path) -> Result<()> {
    require_idle_for(software, root, None)
}

fn require_idle_for(
    software: &Software,
    root: &Path,
    operation: Option<&operation::Binding>,
) -> Result<()> {
    if !records::leaf(software.command) {
        return Err(records::refuse());
    }
    if let Some(root) = records::optional_root(root)?
        && if operation.is_none() {
            store::pending(&root)?
        } else {
            store::pending_for(&root, operation)?
        }
    {
        return Err(Error::new(
            ReasonCode::RecoveryRequired,
            "a software operation is pending; a new plan cannot recover or replace its recorded operation",
        ));
    }
    Ok(())
}

/// Remove one installed version, and the exposed command if it pointed at it.
///
/// # Errors
///
/// Refuses an unrecorded or modified tree, or a filesystem failure during removal.
pub fn remove(software: &Software, root: &Path) -> Result<bool> {
    require_idle(software, root)?;
    if fs::symlink_metadata(root).is_err_and(|error| error.kind() == std::io::ErrorKind::NotFound) {
        return Ok(false);
    }
    Writer::acquire(root)?.remove(software)
}

fn remove_locked(software: &Software, root: &Path) -> Result<bool> {
    require_idle(software, root)?;
    let Some(removal) = removal::Removal::begin(root, software)? else {
        return Ok(false);
    };
    removal.complete()?;
    Ok(true)
}

/// Point the exposed command back at a version that is already on disk.
///
/// Installing 1.0.6 leaves 1.0.5 in its own directory and moves only the
/// exposed command, so the bytes to go back to are already there. Until this
/// existed nothing pointed at them: the owner named rollback in the same
/// sentence as install, reinstall and select, and three of those four were
/// reachable.
///
/// This is the one part of the software lifecycle that needs no network at all,
/// which is why it can be a command someone types rather than the three-phase
/// exchange install and update have to be.
///
/// **The version is named, never inferred.** There is no record of what was
/// previous -- only what is on disk -- and these version strings do not order
/// reliably: `2026.08.11-e8db854` sorts by string, not by release. Picking "the
/// one before" would mean inventing an ordering the vendor never promised, and
/// pointing a command at the wrong build is exactly the class of mistake this
/// program refuses everywhere else. A caller who omits it is told what is here.
///
/// # Errors
///
/// Refuses a missing or changed installation receipt/tree, conflicting launch
/// ownership, a pending operation or an unavailable prefix writer.
pub fn rollback(software: &Software, root: &Path, to: &str) -> Result<Installed> {
    require_idle(software, root)?;
    Writer::acquire(root)?.rollback(software, to)
}

fn rollback_locked(software: &Software, root: &Path, to: &str) -> Result<Installed> {
    let present = Present::under_named(root, software.command, software.member_here());
    if !present.versions.iter().any(|found| found == to) {
        return Err(Error::new(
            ReasonCode::InvalidTarget,
            if present.versions.is_empty() {
                format!(
                    "{} holds no installed version of {}",
                    root.display(),
                    software.command
                )
            } else {
                format!(
                    "{to} is not installed under {}; it holds {}",
                    root.display(),
                    present.versions.join(", ")
                )
            },
        ));
    }

    let switch = switch::Switch::begin(root, software.command, to)?;
    let exposed = switch.executable();
    switch.complete()?;
    Ok(Installed {
        version: to.to_owned(),
        root: root.join(to),
        executable: exposed,
        files: 0,
    })
}

/// The name the exposed command answers to, which is not always the command.
///
/// Six of the seven products ship a native executable, and a link named after
/// the command is the whole story. Pi ships JavaScript — `dist/bundle/cli.js`,
/// with a `#!/usr/bin/env node` line and mode 755 — and the two systems part
/// company there.
///
/// On Unix the shebang does the work and a symlink named `pi` runs. Windows has
/// no shebang: it decides how to run a file from its extension, and a copy
/// named `pi` with JavaScript inside it is not a program. So there the exposed
/// thing is `pi.cmd`, a launcher that names the interpreter.
///
/// Said in one place because three callers need the same answer: the plan that
/// states `entry_point`, the apply that writes it, and `launch` that starts it.
/// They disagreed once already about where a program lives, and once was
/// enough.
#[must_use]
pub fn exposed_name(command: &str, member: &str) -> String {
    exposed_name_on(command, member, cfg!(windows))
}

/// The same rule, with the platform as an argument rather than as a `cfg`.
///
/// Written this way so it can be *asserted* from either system rather than
/// demonstrated on one. A `cfg!` here would make the Windows branch provable
/// only on Windows, and a mutation that deleted it would leave every Linux run
/// green — which is exactly what happened to the first version of this, and is
/// the reason it is a parameter now.
#[must_use]
pub fn exposed_name_on(command: &str, member: &str, windows: bool) -> String {
    match member_kind(member, windows) {
        // A launcher naming the runtime, or a batch file kept as one. Both need
        // an extension because Windows decides how to run a file from its name.
        MemberKind::JavaScript | MemberKind::CommandScript => format!("{command}.cmd"),
        MemberKind::Native => command.to_owned(),
    }
}

/// What the vendor's entry point *is*, which is what decides how to expose it.
///
/// This used to be one question -- *is the member JavaScript* -- and everything
/// else fell through to the bare command. Cursor's Windows package ships
/// `dist-package/cursor-agent.cmd`, a batch launcher, so the stable command
/// became an extensionless file holding batch text: not a program on the only
/// platform that branch exists for, and hard-linked or copied as though it were
/// native.
///
/// **A native `.exe` deliberately stays extensionless**, which looks
/// inconsistent and is the measured distinction. `CreateProcess` on an explicit
/// path reads the PE header rather than the name, so codex's `codex.exe` runs
/// exposed as `codex`. A batch file has no header and cannot be executed without
/// an interpreter at all. One of the two was broken; renaming the other would
/// move the entry point in every plan, marker and readback for no benefit.
///
/// The platform is a parameter rather than a `cfg!` for the reason spelled out
/// on [`exposed_name_on`]: the branch that was wrong is the one only Windows
/// runs, and a `cfg!` makes it provable only there.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum MemberKind {
    /// A program the operating system runs directly.
    Native,
    /// JavaScript, which needs the runtime named.
    JavaScript,
    /// A Windows batch launcher, which needs `cmd` and its own directory.
    CommandScript,
}

/// Classify one artifact member for one platform.
#[must_use]
pub fn member_kind(member: &str, windows: bool) -> MemberKind {
    if !windows {
        // On Unix the shebang does the work and nothing here is a batch file.
        return MemberKind::Native;
    }
    // Through the extension rather than the spelling: Windows treats `.JS` and
    // `.js` as one extension, and a rule that missed the first would expose an
    // unrunnable file on the only platform this branch exists for.
    match Path::new(member)
        .extension()
        .map(|kind| kind.to_string_lossy().to_ascii_lowercase())
        .as_deref()
    {
        Some("js") => MemberKind::JavaScript,
        Some("cmd" | "bat") => MemberKind::CommandScript,
        _ => MemberKind::Native,
    }
}

/// What this prefix runs, recorded so a launch can check it rather than trust it.
///
/// The version marker beside this answers *which* version is exposed. It cannot
/// answer whether the bytes under that version are the ones this provider put
/// there, and `launch` was checking only that a file existed and carried an
/// executable bit. So a product that replaced itself, or anything else that
/// wrote over the tree, was started and reported as the pinned release.
///
/// The digest is of the executable named here rather than of the exposed
/// command: on Windows the exposure can be a `.cmd` launcher holding a path
/// rather than a copy of the program, and hashing that would check the launcher.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct Manifest {
    /// The shape of this record, so a reader can refuse one it does not know.
    pub schema_version: u32,
    /// Which product version the exposed command runs.
    pub version: String,
    /// The executable, relative to the prefix.
    pub executable: String,
    /// Its digest when this provider exposed it.
    pub executable_sha256: String,
}

impl Manifest {
    /// Where the record for one command lives.
    #[must_use]
    pub fn path(root: &Path, command: &str) -> PathBuf {
        root.join("bin").join(format!(".{command}.manifest.json"))
    }

    /// Distinguish absence from an unreadable, malformed or unsupported record.
    #[must_use]
    pub fn inspect(path: &Path, command: &str) -> ManifestState {
        let read = || -> Result<Option<Vec<u8>>> {
            if !records::leaf(command) {
                return Err(records::refuse());
            }
            let root = match records::open_root(path) {
                Ok(root) => root,
                Err(error) => match fs::symlink_metadata(path) {
                    Err(missing) if missing.kind() == std::io::ErrorKind::NotFound => {
                        return Ok(None);
                    }
                    _ => return Err(error),
                },
            };
            let Some(bin) = records::present(&root, "bin")? else {
                return Ok(None);
            };
            records::read_bytes(&bin, &format!(".{command}.manifest.json"), 16 * 1024)
        };
        match read() {
            Ok(None) => ManifestState::Missing,
            Err(_) => ManifestState::Unreadable,
            Ok(Some(raw)) => match serde_json::from_slice::<Self>(&raw) {
                Err(_) => ManifestState::Malformed,
                Ok(found) if found.schema_version != 1 => ManifestState::Unsupported {
                    schema_version: found.schema_version,
                },
                Ok(found) => ManifestState::Present(found),
            },
        }
    }
}

/// Why a launch receipt could not be used as a current verification.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum ManifestState {
    /// No file. An older provider release wrote this prefix.
    Missing,
    /// The path exists and could not be read.
    Unreadable,
    /// Bytes are present and are not a manifest.
    Malformed,
    /// A later schema this build does not verify.
    Unsupported {
        /// The schema the file named.
        schema_version: u32,
    },
    /// A current receipt.
    Present(Manifest),
}

#[cfg(test)]
mod tests {
    #![allow(clippy::unwrap_used, clippy::panic)]

    use super::*;
    use crate::setup_core::archive::build::{Dialect, Item, gzip_tar};

    /// Codex's real shape: the executable is deep inside a tree whose siblings
    /// it needs at runtime.
    const CODEX_MEMBER: &str = "package/vendor/x86_64-unknown-linux-musl/bin/codex";

    const ARTIFACTS: &[Artifact] = &[
        Artifact {
            platform: "linux/x86_64",
            url: "https://example.invalid/linux-x86_64.tgz",
            bytes: 0,
            sha256: "sha256:0",
            shape: Shape::GzipTar,
            member: CODEX_MEMBER,
        },
        Artifact {
            platform: "linux/arm64",
            url: "https://example.invalid/linux-arm64.tgz",
            bytes: 0,
            sha256: "sha256:0",
            shape: Shape::GzipTar,
            member: CODEX_MEMBER,
        },
    ];

    fn software() -> Software {
        Software {
            version: "1.2.3",
            command: "codex",
            delivery: Delivery::Artifacts(ARTIFACTS),
            unsupported: &["windows/x86_64"],
            previous: None,
        }
    }

    /// The release the fixture can move away from, with bytes of its own.
    ///
    /// A different digest from [`ARTIFACTS`] deliberately: resolution by bytes
    /// is only tested by a pair that can actually be told apart.
    const EARLIER_ARTIFACTS: &[Artifact] = &[
        Artifact {
            platform: "linux/x86_64",
            url: "https://example.invalid/linux-x86_64-1.2.2.tgz",
            bytes: 0,
            sha256: "sha256:earlier",
            shape: Shape::GzipTar,
            member: CODEX_MEMBER,
        },
        Artifact {
            platform: "linux/arm64",
            url: "https://example.invalid/linux-arm64-1.2.2.tgz",
            bytes: 0,
            sha256: "sha256:earlier",
            shape: Shape::GzipTar,
            member: CODEX_MEMBER,
        },
    ];

    fn bumped() -> Software {
        Software {
            previous: Some(Previous {
                version: "1.2.2",
                artifacts: EARLIER_ARTIFACTS,
            }),
            ..software()
        }
    }

    /// A cursor-shaped table: Unix members extensionless, the Windows member a
    /// batch launcher. The one shape in the estate where the first row's member
    /// and the Windows row's member classify differently.
    const MIXED_ARTIFACTS: &[Artifact] = &[
        Artifact {
            platform: "linux/arm64",
            url: "https://example.invalid/linux-arm64.tgz",
            bytes: 0,
            sha256: "sha256:0",
            shape: Shape::GzipTar,
            member: "dist-package/cursor-agent",
        },
        Artifact {
            platform: "windows/x86_64",
            url: "https://example.invalid/windows-x86_64.zip",
            bytes: 0,
            sha256: "sha256:0",
            shape: Shape::Zip,
            member: "dist-package/cursor-agent.cmd",
        },
    ];

    /// The name a plan states on Windows is the name Windows actually gets.
    ///
    /// Found by the consumer's six-leg matrix on released `0.0.50`, cursor,
    /// both Windows architectures: `software_install` answered success and
    /// their postcondition read *"the planned entry point is not on disk"*.
    /// The plan derived its entry point from `member_hint()` — the **first**
    /// artifact in the table, a Unix member with no extension, so
    /// `exposed_name_on(.., windows)` classified it `Native` and the plan
    /// promised `bin/agent`; the apply resolved this host's artifact, whose
    /// member is a `.cmd`, and wrote `bin/agent.cmd`. Four Unix legs agreed
    /// with themselves; the one platform where the two derivations differ is
    /// the one the plan lied on. Our own evidence stayed green because its
    /// readback derives the name the same way the apply does — self-consistent
    /// is not correct.
    #[test]
    fn the_windows_entry_point_names_the_member_windows_actually_gets() {
        let sw = Software {
            command: "agent",
            delivery: Delivery::Artifacts(MIXED_ARTIFACTS),
            ..software()
        };
        // The derivation the plan uses for this platform.
        let planned = exposed_name_on(sw.command, sw.member_on("windows", "x86_64"), true);
        // The derivation the apply uses: this platform's artifact, directly.
        let written = exposed_name_on(
            sw.command,
            sw.artifact_for("windows", "x86_64").unwrap().member,
            true,
        );
        assert_eq!(planned, written, "the plan and the apply name one file");
        assert_eq!(planned, "agent.cmd");
        // The control: the first-row derivation this replaced answers wrongly
        // on exactly this shape, which is what made the defect Windows-only
        // and cursor-only.
        assert_eq!(exposed_name_on(sw.command, sw.member_hint(), true), "agent");
    }

    /// A platform the table does not carry falls back to the hint.
    ///
    /// `software_remove` plans on hosts the vendor never published for, and a
    /// name that errors there would refuse a removal of nothing.
    #[test]
    fn a_platform_without_an_artifact_falls_back_to_the_hint() {
        let sw = software();
        assert_eq!(sw.member_on("windows", "x86_64"), sw.member_hint());
    }

    /// A build that has never been bumped names exactly one version.
    ///
    /// The absence is the point: `software_update` has nothing to move from
    /// and `rollback` nothing to return to, and both say so rather than
    /// pretending a transition exists.
    #[test]
    fn a_build_with_no_second_pin_names_one_version_and_refuses_the_rest() {
        let only = software();
        assert_eq!(only.versions(), vec!["1.2.3"]);
        assert!(only.at(None).is_some());
        assert!(only.at(Some("1.2.3")).is_some());
        assert!(only.at(Some("1.2.2")).is_none());
    }

    /// Asking for the earlier version gets the earlier version's *artifacts*.
    ///
    /// Not just its number. The whole failure this guards against is a build
    /// that answers "1.2.2" and then downloads 1.2.3's bytes, which would be a
    /// plan that names one thing and installs another.
    #[test]
    fn naming_the_earlier_version_selects_the_earlier_bytes() {
        let both = bumped();
        assert_eq!(both.versions(), vec!["1.2.3", "1.2.2"]);

        let earlier = both.at(Some("1.2.2")).unwrap();
        assert_eq!(earlier.version, "1.2.2");
        assert_eq!(
            earlier.artifact_for("linux", "x86_64").unwrap().url,
            "https://example.invalid/linux-x86_64-1.2.2.tgz"
        );

        // And the current one is unmoved by the second pin existing.
        let current = both.at(None).unwrap();
        assert_eq!(current.version, "1.2.3");
        assert_eq!(
            current.artifact_for("linux", "x86_64").unwrap().url,
            "https://example.invalid/linux-x86_64.tgz"
        );
    }

    /// Which release a file belongs to is read from the file.
    ///
    /// `apply` is handed bytes, not a version. Resolving by digest is what
    /// stops a caller installing the earlier tree under the current version's
    /// name by relabelling a flag -- nothing here reads a label.
    #[test]
    fn the_release_a_file_belongs_to_is_read_from_its_digest() {
        let both = bumped();
        assert_eq!(
            both.for_bytes("linux", "x86_64", "sha256:0")
                .map(|found| found.version),
            Some("1.2.3")
        );
        assert_eq!(
            both.for_bytes("linux", "x86_64", "sha256:earlier")
                .map(|found| found.version),
            Some("1.2.2")
        );
        // Bytes belonging to neither release resolve to neither, rather than to
        // whichever was checked first.
        assert!(
            both.for_bytes("linux", "x86_64", "sha256:someone-elses")
                .is_none()
        );
        // A platform this build publishes nothing for cannot resolve either,
        // however right the digest is.
        assert!(both.for_bytes("windows", "x86_64", "sha256:0").is_none());
    }

    /// The bytes to go back to are already on disk: installing a new version
    /// leaves the old tree in place and moves only the exposed command. Until
    /// `rollback` existed nothing pointed back at them, and the owner named
    /// rollback in the same sentence as install, reinstall and select.
    #[test]
    fn rollback_points_the_command_at_a_version_already_on_disk() {
        let (at, artifact) = staged("rollback", b"#!/bin/sh\necho new\n", CODEX_MEMBER);
        let root = at.join("prefix");
        let previous = Software {
            version: "1.2.2",
            ..software()
        };
        install(&previous, &artifact, &at.join("artifact.tgz"), &root).unwrap();
        let installed = install(&software(), &artifact, &at.join("artifact.tgz"), &root).unwrap();
        assert_eq!(installed.version, "1.2.3");

        let entry = root.join("bin/codex");
        let retained = at.join("retained-launcher");
        fs::rename(&entry, &retained).unwrap();
        fs::write(&entry, b"foreign launcher").unwrap();
        assert!(rollback(&software(), &root, "1.2.2").is_err());
        assert_eq!(fs::read(&entry).unwrap(), b"foreign launcher");
        fs::remove_file(&entry).unwrap();
        fs::rename(retained, entry).unwrap();
        let older = root.join("1.2.2").join(CODEX_MEMBER);
        fs::write(&older, b"changed retained version").unwrap();
        assert!(rollback(&software(), &root, "1.2.2").is_err());
        assert_eq!(fs::read(&older).unwrap(), b"changed retained version");
        fs::write(older, b"#!/bin/sh\necho new\n").unwrap();
        let rolled = rollback(&software(), &root, "1.2.2").unwrap();
        assert_eq!(rolled.version, "1.2.2");

        let present = Present::under_named(&root, "codex", CODEX_MEMBER);
        assert_eq!(present.exposed.as_deref(), Some("1.2.2"));
        assert_eq!(present.versions, vec!["1.2.2", "1.2.3"]);

        // And the version it came from is still there to go forward to.
        assert!(root.join("1.2.3").join(CODEX_MEMBER).is_file());
        assert_eq!(
            rollback(&software(), &root, "1.2.3").unwrap().version,
            "1.2.3"
        );
        assert_eq!(
            Present::under_named(&root, "codex", CODEX_MEMBER)
                .exposed
                .as_deref(),
            Some("1.2.3")
        );
        // A real durable switch record survives exit before its launch renames.
        drop(switch::Switch::begin(&root, "codex", "1.2.2").unwrap());
        assert!(rollback(&software(), &root, "1.2.3").is_err());
        assert!(remove(&software(), &root).is_err());
        assert!(install(&software(), &artifact, &at.join("artifact.tgz"), &root).is_err());
        let limit = crate::setup_core::software_prefix::INVENTORY_LIMIT;
        let directory = records::open_root(&root).unwrap();
        let receipt = store::Key::Receipt {
            command: "codex".into(),
            version: "1.2.2".into(),
        };
        let original: serde_json::Value =
            store::read(&directory, &receipt, limit).unwrap().unwrap();
        let mut changed = original.clone();
        changed["artifact_sha256"] = format!("sha256:{}", "0".repeat(64)).into();
        store::write(&directory, &receipt, &changed, limit).unwrap();
        assert!(recover(&software(), &root).is_err());
        store::write(&directory, &receipt, &original, limit).unwrap();
        let marker = root.join("bin/.codex.version");
        fs::write(&marker, b"foreign marker").unwrap();
        let before = crate::setup_core::software_prefix::observe(&root, ".codex-setup-system")
            .unwrap()
            .digest;
        assert!(recover(&software(), &root).is_err());
        assert_eq!(
            crate::setup_core::software_prefix::observe(&root, ".codex-setup-system")
                .unwrap()
                .digest,
            before
        );
        // Matching intended bytes alone do not establish a recorded rename.
        // A partial switch must retain its sealed preparation record.
        fs::write(&marker, b"1.2.2").unwrap();
        assert!(recover(&software(), &root).is_err());
        fs::write(marker, b"1.2.3").unwrap();
        assert_eq!(recover(&software(), &root).unwrap().len(), 1);
        assert!(recover(&software(), &root).unwrap().is_empty());
        assert_eq!(
            Present::under_named(&root, "codex", CODEX_MEMBER)
                .exposed
                .as_deref(),
            Some("1.2.2")
        );
        assert!(root.join("1.2.3").join(CODEX_MEMBER).is_file());
        assert!(
            !store::exists(
                &records::open_root(&root).unwrap(),
                &switch::journal("codex")
            )
            .unwrap()
        );
        drop(directory);
        fs::remove_dir_all(at).unwrap();
    }

    /// Removing a version nobody is running leaves the running one runnable.
    ///
    /// `remove` took the version tree, then took `bin/<command>` and the marker
    /// **whenever the tree existed**, without asking whether either named the
    /// version being removed. So the ordinary sequence after a bad release --
    /// install, update, roll back, then take the bad one off -- deleted the
    /// command that was pointing at the good one, and left a complete, working
    /// version tree that nothing could start.
    ///
    /// The evidence workflow could not have caught it: it switches *forward* to
    /// the newer version before removing it, so the version it removes is always
    /// the active one. The one case where the guard matters was the one case the
    /// happy path never enters.
    #[test]
    fn removing_an_inactive_version_leaves_the_active_one_exposed() {
        let (at, artifact) = staged("remove-inactive", b"#!/bin/sh\necho new\n", CODEX_MEMBER);
        let root = at.join("prefix");
        let previous = Software {
            version: "1.2.2",
            ..software()
        };
        install(&previous, &artifact, &at.join("artifact.tgz"), &root).unwrap();
        install(&software(), &artifact, &at.join("artifact.tgz"), &root).unwrap();

        rollback(&software(), &root, "1.2.2").unwrap();
        assert_eq!(
            Present::under_named(&root, "codex", CODEX_MEMBER)
                .exposed
                .as_deref(),
            Some("1.2.2"),
            "the rollback did not take"
        );

        // Take off the version nobody is running.
        assert!(remove(&software(), &root).unwrap());

        assert!(
            !root.join("1.2.3").exists(),
            "the removed version's tree is still here"
        );
        assert!(
            root.join("1.2.2").join(CODEX_MEMBER).is_file(),
            "removing one version took another version's files"
        );
        let after = Present::under_named(&root, "codex", CODEX_MEMBER);
        assert_eq!(
            after.exposed.as_deref(),
            Some("1.2.2"),
            "removing an inactive version took the command that was running the active one"
        );
        assert_eq!(after.versions, vec!["1.2.2"]);
    }

    /// An install that fails leaves the installation that was working.
    ///
    /// `install` cleared `<root>/<version>` and then extracted into that same
    /// path. Between those two steps there is no installation at all, and the
    /// exposed command points into a directory that has been deleted -- so a
    /// crash, a full disk, or an archive that turns out not to carry its
    /// declared executable takes the working program with it.
    ///
    /// Driven by the third of those, which is deterministic: an artifact whose
    /// digest is correct and whose archive does not contain the member the plan
    /// named. The digest check passes, the clearing happens, and the refusal
    /// arrives afterwards -- exactly where an interruption would.
    #[test]
    fn a_reinstall_that_fails_leaves_the_installation_that_was_working() {
        let (at, artifact) = staged("reinstall-fails", b"#!/bin/sh\necho good\n", CODEX_MEMBER);
        let root = at.join("prefix");
        install(&software(), &artifact, &at.join("artifact.tgz"), &root).unwrap();
        let good = fs::read(root.join("1.2.3").join(CODEX_MEMBER)).unwrap();

        // Same version, correct digest, and no executable inside.
        let raw = gzip_tar(
            &[
                Item::directory("package"),
                Item::file("package/README.md", b"no executable here", 0o644),
            ],
            Dialect::Gnu,
        );
        let broken_at = at.join("broken.tgz");
        fs::write(&broken_at, &raw).unwrap();
        let broken = Artifact {
            bytes: raw.len() as u64,
            sha256: Box::leak(digest::of_bytes(&raw).into_boxed_str()),
            ..artifact
        };

        let refused = install(&software(), &broken, &broken_at, &root).unwrap_err();
        assert_eq!(
            refused.reason(),
            ReasonCode::IntegrityMismatch,
            "the refusal is not the one this test drives: {refused:?}"
        );

        assert_eq!(
            fs::read(root.join("1.2.3").join(CODEX_MEMBER))
                .ok()
                .as_deref(),
            Some(good.as_slice()),
            "a failed reinstall destroyed the installation that was working"
        );
        assert_eq!(
            Present::under_named(&root, "codex", CODEX_MEMBER)
                .exposed
                .as_deref(),
            Some("1.2.3"),
            "the exposed command no longer names an installed version"
        );
    }

    /// A vendor command script keeps a runnable boundary on Windows.
    ///
    /// `exposed_name_on` asked one question -- *is the member JavaScript* -- and
    /// answered `agent` for everything else. Cursor's Windows package ships
    /// `dist-package/cursor-agent.cmd`, a batch launcher, so the stable command
    /// became an extensionless `bin/agent` holding batch text. Windows decides
    /// how to run a file from its extension, so that file is not a program, and
    /// the exposure branch beside it then hard-linked or copied it as though it
    /// were native.
    ///
    /// The question that decides is the member's *kind*, not whether it happens
    /// to be one particular kind. Four members, asserted for both platforms from
    /// whichever one is running, because the branch that was wrong is the one
    /// only Windows executes.
    #[test]
    fn a_command_script_member_keeps_an_extension_windows_can_run() {
        // Native: the command, on every system.
        assert_eq!(
            exposed_name_on("agent", "dist-package/cursor-agent", true),
            "agent"
        );
        assert_eq!(
            exposed_name_on("agent", "dist-package/cursor-agent", false),
            "agent"
        );

        // JavaScript: a launcher on Windows, the shebang does it on Unix.
        assert_eq!(
            exposed_name_on("pi", "package/dist/bundle/cli.js", true),
            "pi.cmd"
        );
        assert_eq!(
            exposed_name_on("pi", "package/dist/bundle/cli.js", false),
            "pi"
        );

        // A vendor batch launcher: still a batch file, so it keeps an extension
        // Windows will run. On Unix the member is never this shape.
        assert_eq!(
            exposed_name_on("agent", "dist-package/cursor-agent.cmd", true),
            "agent.cmd",
            "a .cmd member was exposed as a name Windows cannot run"
        );
        assert_eq!(
            exposed_name_on("agent", "dist-package/cursor-agent.cmd", false),
            "agent"
        );

        // **And a native `.exe` deliberately does not change.** Codex ships one
        // and is exposed extensionless today, which works: `CreateProcess` on an
        // explicit path reads the PE header rather than the name, so the file
        // runs whatever it is called. A batch file has no header and cannot be
        // executed at all without an interpreter, which is the whole difference
        // and the reason only one of these two was broken. Renaming the working
        // one would move the entry point in every plan and marker for no
        // measured benefit.
        assert_eq!(
            exposed_name_on("codex", "package/bin/codex.exe", true),
            "codex"
        );
        assert_eq!(
            exposed_name_on("codex", "package/bin/codex.exe", false),
            "codex"
        );
    }

    /// A marker truncated onto a sibling version is not believed.
    ///
    /// The consumer constructed the accident I told them I could not. The
    /// version filter rejects a truncated marker because the fragment is not an
    /// installed version -- unless the truncation stops somewhere that *is* one.
    /// `1.18.23` cut short is `1.18`, and where `1.18` is also installed the
    /// prefix relationship does it for free: no editing, no person, an
    /// interrupted write and a sibling whose string is a prefix of another.
    ///
    /// `versions.contains("1.18")` is true, because 1.18 really is installed.
    /// Nothing in a plain-text marker separates *"1.18 because that is what is
    /// exposed"* from *"1.18 because the write stopped there"*, and reading it
    /// twice does not help: the bytes are stable once written.
    ///
    /// So the fix is in the writing, not the reading. Both endings of an
    /// interrupted write are asserted -- the old value or the new one, never a
    /// third thing.
    #[test]
    fn a_marker_truncated_onto_a_sibling_version_is_not_believed() {
        let (at, artifact) = staged("truncated-marker", b"#!/bin/sh\necho new\n", CODEX_MEMBER);
        let root = at.join("prefix");
        install(&software(), &artifact, &at.join("artifact.tgz"), &root).unwrap();

        // A sibling whose string is a prefix of the exposed one. `1.2` beside
        // the installed `1.2.3` is the shape; the consumer measured `1.18`
        // beside `1.18.23`.
        let sibling = root.join("1.2");
        fs::create_dir_all(sibling.join("package/vendor/x86_64-unknown-linux-musl/bin")).unwrap();
        fs::write(sibling.join(CODEX_MEMBER), b"#!/bin/sh\necho sibling\n").unwrap();

        // What an interrupted write leaves: the exposed version, cut short at a
        // point that happens to be another installed version.
        fs::write(root.join("bin").join(".codex.version"), "1.2").unwrap();

        let read = Present::under_named(&root, "codex", CODEX_MEMBER);
        assert_eq!(
            read.exposed.as_deref(),
            Some("1.2"),
            "this test drives the state; if it stops reproducing, say why here"
        );

        // And the writer must make that state unreachable: a write that fails
        // leaves the marker it found, never a fragment of the one it was told
        // to put there.
        let marker = root.join("bin").join(".codex.version");
        fs::write(&marker, "1.2.3").unwrap();
        let staging = marker.with_extension("version.incoming");
        fs::write(&staging, b"unrelated temporary file").unwrap();
        let predecessor = launch::Snapshot::prepare(&root, "codex", CODEX_MEMBER).unwrap();
        let manifest = Manifest::path(&root, "codex");
        fs::remove_file(&manifest).unwrap();
        fs::create_dir(&manifest).unwrap(); // the destination is not a metadata file
        let refused = expose(
            &root.join("1.2").join(CODEX_MEMBER),
            &root.join("bin").join("codex"),
            "1.2",
            "codex",
            &predecessor,
        );
        assert!(
            refused.is_err(),
            "the marker write did not stage: {refused:?}"
        );
        assert_eq!(
            fs::read_to_string(&marker).unwrap(),
            "1.2.3",
            "a failed marker write replaced the marker that was there"
        );
        assert_eq!(fs::read(&staging).unwrap(), b"unrelated temporary file");
        assert_eq!(
            fs::read(root.join("bin/codex")).unwrap(),
            b"#!/bin/sh\necho new\n"
        );
    }

    /// A JavaScript entry point is exposed as something the platform can run.
    ///
    /// Six of the seven products ship a native executable and a link named
    /// after the command is the whole story. Pi ships `dist/bundle/cli.js`, and
    /// the two systems part company: Unix has the shebang, Windows decides how
    /// to run a file from its extension, so a copy named `pi` with JavaScript
    /// inside it is not a program there.
    ///
    /// The rule is asserted for both systems from either, because it is the
    /// answer three callers need to agree on -- the plan that states
    /// `entry_point`, the apply that writes it, and `launch` that starts it.
    #[test]
    fn a_javascript_entry_point_is_exposed_as_something_the_platform_can_run() {
        // A native member is the command, on every system.
        assert_eq!(exposed_name("codex", CODEX_MEMBER), "codex");
        assert_eq!(exposed_name("grok", ""), "grok");

        // A JavaScript member, asserted for both systems from whichever one is
        // running: Windows cannot run a file named `pi` holding JavaScript, and
        // on Unix the shebang does the work so a launcher would be noise.
        let js = "package/dist/bundle/cli.js";
        assert_eq!(exposed_name_on("pi", js, true), "pi.cmd");
        assert_eq!(exposed_name_on("pi", js, false), "pi");

        // A native member is unaffected by the platform, which is what makes
        // this a rule about the artifact rather than about Windows.
        assert_eq!(exposed_name_on("codex", CODEX_MEMBER, true), "codex");
        assert_eq!(exposed_name_on("codex", CODEX_MEMBER, false), "codex");

        // And the shipped entry point agrees with the rule for this system.
        assert_eq!(
            exposed_name("pi", js),
            exposed_name_on("pi", js, cfg!(windows))
        );
    }

    /// A prefix laid out the way Windows lays one out reads back correctly,
    /// and the member-blind reading of the same prefix finds nothing.
    ///
    /// This is the defect `pi`'s `evidence.yml` failed on, on `windows-latest`
    /// and only there: `rollback` answered, and the readback after it reported
    /// *"the prefix still runs something else"*. `rollback` was right; the
    /// reading was blind. Both production callers passed `member = ""`, so
    /// `exposed_name("pi", "")` gave `pi`, `bin/pi` does not exist beside a
    /// `.cmd` launcher, and `exposed` came back `None`.
    ///
    /// **Every existing test of this path uses `codex`**, a native binary whose
    /// member-blind and member-aware names are the same string. So the whole
    /// suite was green on all three systems while never once entering the
    /// branch that was wrong. That is why this test names `pi` and its real
    /// member, and why it takes the platform as an argument: on Linux
    /// `cfg!(windows)` is false and a `cfg`-gated version of this could not
    /// have run where it was written.
    ///
    /// The control is the second half. A positive that says "the reading found
    /// it" proves nothing unless the reading can also fail — so the same
    /// directory is read once with the member and once without, and the
    /// member-blind reading must come back empty. If someone reintroduces a
    /// blind constructor, that assertion is what stops it.
    #[test]
    fn a_windows_shaped_prefix_is_read_back_by_the_member_and_not_by_the_command() {
        let member = "package/dist/bundle/cli.js";
        let at = scratch("windows-readback");
        let root = at.join("prefix");
        fs::create_dir_all(root.join("0.84.4").join("package/dist/bundle")).unwrap();
        fs::write(root.join("0.84.4").join(member), b"// the bundle").unwrap();
        fs::create_dir_all(root.join("bin")).unwrap();

        // What `expose` leaves on Windows: a launcher named by the extension
        // rule, plus the marker that records which version it points into.
        let launcher = exposed_name_on("pi", member, true);
        assert_eq!(launcher, "pi.cmd");
        fs::write(root.join("bin").join(&launcher), b"@echo off\r\n").unwrap();
        fs::write(root.join("bin").join(".pi.version"), b"0.84.4\n").unwrap();

        assert_eq!(
            Present::under_on(&root, "pi", member, true)
                .exposed
                .as_deref(),
            Some("0.84.4"),
            "the reading told the member did not find the launcher beside it"
        );

        // The control: the same prefix, read the way the two callers read it
        // before this commit.
        assert_eq!(
            Present::under_on(&root, "pi", "", true).exposed,
            None,
            "a member-blind reading found something, so this test proves nothing"
        );

        // And both readings agree about what is installed, which is what makes
        // the difference above specifically about the exposed name.
        assert_eq!(
            Present::under_on(&root, "pi", "", true).versions,
            vec!["0.84.4".to_owned()]
        );
    }

    /// Pi installs from one tarball and the thing that lands runs.
    ///
    /// The declaration this replaces said pi could not be installed because
    /// "its dependency closure is resolved at install time, so there is no
    /// single artifact whose digest can be decided in advance". The published
    /// package ships `npm-shrinkwrap.json`, so the closure is fixed -- and it
    /// does not matter, because the bundle imports only Node built-ins and runs
    /// with no `node_modules` at all.
    #[test]
    #[cfg(unix)]
    fn a_javascript_program_installs_from_one_archive_and_runs() {
        let member = "package/dist/bundle/cli.js";
        let (at, artifact) = staged(
            "js-entry",
            b"#!/usr/bin/env sh\necho 'js-stand-in 9.9.9'\n",
            member,
        );
        let software = Software {
            version: "9.9.9",
            command: "jsprog",
            delivery: Delivery::Artifacts(&[]),
            unsupported: &[],
            previous: None,
        };
        let root = at.join("prefix");
        let installed = install(&software, &artifact, &at.join("artifact.tgz"), &root).unwrap();

        // Exposed under the name the rule gives, pointing into the archive's
        // own layout rather than a copy lifted out of it.
        assert_eq!(
            installed.executable,
            root.join("bin").join(exposed_name("jsprog", member))
        );
        assert_eq!(
            fs::canonicalize(&installed.executable).unwrap(),
            fs::canonicalize(root.join("9.9.9").join(member)).unwrap()
        );

        // And the reading of what is exposed agrees with what was written.
        assert_eq!(
            Present::under_named(&root, "jsprog", member)
                .exposed
                .as_deref(),
            Some("9.9.9")
        );
    }

    /// The exposed version is recorded, so it is readable where no link exists.
    ///
    /// This is the Windows defect written as a test that fails on Linux too.
    /// `expose` makes a symlink on Unix and a recorded copy on Windows,
    /// and the old reading resolved the link -- so on Windows the answer was
    /// always "nothing is exposed", on a prefix where something plainly was.
    ///
    /// It was not cosmetic: `Present::exposed` is what separates an install
    /// from an update, so every `software_update` on Windows saw an empty
    /// prefix and refused as an update of nothing.
    #[test]
    fn the_exposed_version_is_readable_without_a_link_to_resolve() {
        let (at, artifact) = staged("exposed-marker", b"#!/bin/sh\necho hi\n", CODEX_MEMBER);
        let root = at.join("prefix");
        install(&software(), &artifact, &at.join("artifact.tgz"), &root).unwrap();
        assert_eq!(
            Present::under_named(&root, "codex", CODEX_MEMBER)
                .exposed
                .as_deref(),
            Some("1.2.3")
        );

        // Exactly what Windows leaves behind: a real file where Unix has a
        // link. Nothing to resolve, and the answer must not change.
        let exposed = root.join("bin").join("codex");
        let bytes = fs::read(root.join("1.2.3").join(CODEX_MEMBER)).unwrap();
        fs::remove_file(&exposed).unwrap();
        fs::write(&exposed, &bytes).unwrap();
        assert!(!exposed.symlink_metadata().unwrap().is_symlink());
        assert_eq!(
            Present::under_named(&root, "codex", CODEX_MEMBER)
                .exposed
                .as_deref(),
            Some("1.2.3"),
            "the exposed version was unreadable without a link to resolve"
        );

        // A record naming a version that is not there is not believed.
        fs::write(root.join("bin").join(".codex.version"), "9.9.9").unwrap();
        assert_eq!(
            Present::under_named(&root, "codex", CODEX_MEMBER).exposed,
            None
        );

        // And removing takes the record with the command it described.
        fs::write(root.join("bin").join(".codex.version"), "1.2.3").unwrap();
        remove(&software(), &root).unwrap();
        assert!(!root.join("bin").join(".codex.version").exists());
    }

    /// A version that is not there is refused, and the refusal says what is --
    /// otherwise a caller's only way to find out is to guess again.
    #[test]
    fn rollback_to_a_version_that_is_not_installed_names_the_ones_that_are() {
        let (at, artifact) = staged("rollback-missing", b"x", CODEX_MEMBER);
        let root = at.join("prefix");
        install(&software(), &artifact, &at.join("artifact.tgz"), &root).unwrap();

        let error = rollback(&software(), &root, "9.9.9").unwrap_err();
        assert!(error.detail().contains("9.9.9"), "{}", error.detail());
        assert!(error.detail().contains("1.2.3"), "{}", error.detail());
        // Nothing moved.
        assert_eq!(
            Present::under_named(&root, "codex", CODEX_MEMBER)
                .exposed
                .as_deref(),
            Some("1.2.3")
        );
    }

    /// A directory name is not evidence that a provider installed the tree.
    #[test]
    fn rollback_refuses_an_unrecorded_version_without_changing_the_launcher() {
        let (at, artifact) = staged("rollback-empty", b"x", CODEX_MEMBER);
        let root = at.join("prefix");
        install(&software(), &artifact, &at.join("artifact.tgz"), &root).unwrap();
        fs::create_dir_all(root.join("1.2.2")).unwrap();

        let error = rollback(&software(), &root, "1.2.2").unwrap_err();
        assert_eq!(error.reason(), ReasonCode::RecoveryRequired);
        assert!(root.join("1.2.2").is_dir());
        assert_eq!(
            Present::under_named(&root, "codex", CODEX_MEMBER)
                .exposed
                .as_deref(),
            Some("1.2.3")
        );
    }

    fn scratch(name: &str) -> PathBuf {
        let path =
            std::env::temp_dir().join(format!("setup-core-software-{name}-{}", std::process::id()));
        let _ = fs::remove_dir_all(&path);
        path
    }

    /// Write an archive to disk and return it with an artifact describing it.
    fn staged(name: &str, body: &[u8], member: &'static str) -> (PathBuf, Artifact) {
        let raw = gzip_tar(
            &[
                Item::directory("package"),
                Item::file(member, body, 0o755),
                Item::file("package/README.md", b"read me", 0o644),
            ],
            Dialect::Gnu,
        );
        let at = scratch(name);
        fs::create_dir_all(&at).unwrap();
        let file = at.join("artifact.tgz");
        fs::write(&file, &raw).unwrap();
        let artifact = Artifact {
            platform: "linux/x86_64",
            url: "https://example.invalid/artifact.tgz",
            bytes: raw.len() as u64,
            sha256: Box::leak(digest::of_bytes(&raw).into_boxed_str()),
            shape: Shape::GzipTar,
            member,
        };
        (at, artifact)
    }

    #[test]
    fn the_artifact_for_this_platform_is_the_one_named_for_it() {
        let found = software().artifact_for("linux", "x86_64").unwrap();
        assert_eq!(found.url, "https://example.invalid/linux-x86_64.tgz");
    }

    #[test]
    fn a_system_the_vendor_does_not_build_for_is_an_unsupported_platform() {
        let error = software().artifact_for("windows", "x86_64").unwrap_err();
        assert_eq!(error.reason(), ReasonCode::UnsupportedPlatform);
        assert!(
            error.detail().contains("linux/x86_64"),
            "{}",
            error.detail()
        );
    }

    #[test]
    fn a_machine_the_vendor_does_not_build_for_is_an_unsupported_architecture() {
        // The system is published, this machine is not. The consumer's closed
        // set separates these and so must the refusal.
        let error = software().artifact_for("linux", "riscv64").unwrap_err();
        assert_eq!(error.reason(), ReasonCode::UnsupportedArchitecture);
    }

    #[test]
    fn a_product_delivered_by_a_package_manager_says_so_rather_than_pretending() {
        let pi = Software {
            version: "0.84.3",
            command: "pi",
            delivery: Delivery::Manager {
                tool: "npm",
                reason: "its dependency closure is resolved at install time",
            },
            unsupported: &[],
            previous: None,
        };
        let error = pi.artifact_for("linux", "x86_64").unwrap_err();
        assert_eq!(error.reason(), ReasonCode::UnsupportedOperation);
        assert!(error.detail().contains("npm"), "{}", error.detail());
    }

    #[test]
    fn an_archive_installs_and_exposes_one_stable_command() {
        let (at, artifact) = staged("install", b"#!/bin/sh\necho hi\n", CODEX_MEMBER);
        let root = at.join("software");
        let path = at.join("artifact.tgz");
        let source = VerifiedArtifact::open(&artifact, &path).unwrap();
        fs::rename(&path, at.join("retained.tgz")).unwrap();
        fs::write(&path, b"a different file at the original name").unwrap();
        let installed = install_verified(&software(), &artifact, source, &root).unwrap();

        assert_eq!(installed.version, "1.2.3");
        assert_eq!(installed.files, 3);
        assert_eq!(installed.executable, root.join("bin/codex"));
        // The executable stays inside its tree; only a link leaves it. Codex
        // needs `rg` and `bwrap` beside it, so moving the binary would break it.
        assert!(root.join("1.2.3").join(CODEX_MEMBER).is_file());
        assert!(root.join("1.2.3/package/README.md").is_file());
        assert_eq!(
            fs::read(&installed.executable).unwrap(),
            b"#!/bin/sh\necho hi\n"
        );
        fs::remove_dir_all(&at).unwrap();
    }

    fn admission_preserves_foreign_paths(root: &Path, writer: &Writer, intent: &operation::Intent) {
        fs::write(root.join("foreign"), b"preserve unrelated bytes").unwrap();
        assert!(writer.resume_operation(intent).is_err());
        assert_eq!(
            fs::read(root.join("foreign")).unwrap(),
            b"preserve unrelated bytes"
        );
        fs::remove_file(root.join("foreign")).unwrap();

        // Model interruption after bin creation, before the first kernel record.
        fs::create_dir(root.join("bin")).unwrap();
        assert_eq!(writer.resume_operation(intent).unwrap(), None);
        fs::write(root.join("bin/foreign"), b"not a planned launch entry").unwrap();
        assert!(writer.resume_operation(intent).is_err());
        assert!(root.join("bin/foreign").exists());
        fs::remove_file(root.join("bin/foreign")).unwrap();
    }

    #[test]
    fn caller_intent_survives_preparation_and_returns_history_without_replaying_effects() {
        use operation::{Intent, Kind, Outcome, State};

        let (at, artifact) = staged("caller-intent", b"generated program", CODEX_MEMBER);
        let root = at.join("software");
        fs::create_dir(&root).unwrap();
        let declared = software();
        let control = ".codex-setup-system";
        let expected = crate::setup_core::software_prefix::observe(&root, control)
            .unwrap()
            .digest;
        let writer = Writer::acquire(&root).unwrap();
        let intent = Intent::new(
            "original-request",
            &digest::of_bytes(b"complete original plan"),
            &declared,
            Kind::Install,
        )
        .unwrap();
        assert_eq!(writer.operation_state(&intent).unwrap(), None);
        writer
            .admit_operation(&intent, &declared, control, &expected)
            .unwrap();
        assert!(!root.join("bin").exists());
        assert_eq!(
            writer.operation_state(&intent).unwrap(),
            Some(State::Pending)
        );
        let conflict = Intent::new(
            "original-request",
            &digest::of_bytes(b"different intent"),
            &declared,
            Kind::Install,
        )
        .unwrap();
        assert!(writer.operation_state(&conflict).is_err());
        assert!(writer.remove(&declared).is_err());
        assert!(writer.recover(&declared).is_err());
        admission_preserves_foreign_paths(&root, &writer, &intent);

        // An interrupted extraction is discarded only for this admitted intent.
        let stage = staging::Staging::begin_for(
            &root,
            declared.command,
            declared.version,
            CODEX_MEMBER,
            artifact.sha256,
            Some(&intent.binding),
        )
        .unwrap();
        let incoming = stage.stage_path();
        fs::write(incoming.join("partial"), b"incomplete generated bytes").unwrap();
        drop(stage);
        assert_eq!(writer.resume_operation(&intent).unwrap(), None);
        assert!(!incoming.exists());
        let input = VerifiedArtifact::open(&artifact, &at.join("artifact.tgz")).unwrap();
        let original = writer
            .install_operation(&intent, &declared, &artifact, input)
            .unwrap();
        assert_eq!(original, Outcome::Installed { files: 3 });
        drop(writer);

        let writer = Writer::acquire(&root).unwrap();
        assert_eq!(
            writer.operation_state(&intent).unwrap(),
            Some(State::Completed(original.clone()))
        );
        fs::remove_file(at.join("artifact.tgz")).unwrap();
        let removal = Intent::new(
            "remove-request",
            &digest::of_bytes(b"later removal plan"),
            &declared,
            Kind::Remove,
        )
        .unwrap();
        let expected = crate::setup_core::software_prefix::observe(&root, control)
            .unwrap()
            .digest;
        writer
            .admit_operation(&removal, &declared, control, &expected)
            .unwrap();
        assert_eq!(
            writer.remove_operation(&removal, &declared).unwrap(),
            Outcome::Removed { removed: true }
        );
        let after = crate::setup_core::software_prefix::observe(&root, control)
            .unwrap()
            .digest;
        assert_eq!(writer.resume_operation(&intent).unwrap(), Some(original));
        assert_eq!(
            writer.resume_operation(&removal).unwrap(),
            Some(Outcome::Removed { removed: true })
        );
        assert_eq!(
            crate::setup_core::software_prefix::observe(&root, control)
                .unwrap()
                .digest,
            after
        );
        assert!(!root.join(declared.version).exists());
        assert!(writer.operation_state(&conflict).is_err());
        drop(writer);
        fs::remove_dir_all(at).unwrap();
    }

    #[test]
    fn held_input_checks_seeked_blocks_before_partial_bytes_can_be_promoted() {
        use std::io::{Read, Seek, SeekFrom};

        let (at, artifact) = staged("held-input", b"initial", CODEX_MEMBER);
        let path = at.join("artifact.tgz");
        let root = at.join("software");
        let bytes: Vec<u8> = (0_u8..251).cycle().take(150_001).collect();
        fs::write(&path, &bytes).unwrap();
        let artifact = Artifact {
            bytes: bytes.len() as u64,
            sha256: Box::leak(digest::of_bytes(&bytes).into_boxed_str()),
            shape: Shape::Raw,
            member: "",
            ..artifact
        };
        let mut source = VerifiedArtifact::open(&artifact, &path).unwrap();
        source.reader().seek(SeekFrom::Start(65_532)).unwrap();
        let mut crossing = [0; 16];
        source.reader().read_exact(&mut crossing).unwrap();
        assert_eq!(&crossing, &bytes[65_532..65_548]);
        source.reader().seek(SeekFrom::End(-16)).unwrap();
        source.reader().read_exact(&mut crossing).unwrap();
        assert_eq!(&crossing, &bytes[bytes.len() - 16..]);
        assert!(source.reader().seek(SeekFrom::Current(-200_000)).is_err());
        // Installation resets the private reader after any internal inspection.
        let installed = install_verified(&software(), &artifact, source, &root).unwrap();
        assert_eq!(fs::read(&installed.executable).unwrap(), bytes);

        let source = VerifiedArtifact::open(&artifact, &path).unwrap();
        let modified = fs::metadata(&path).unwrap().modified().unwrap();
        let mut changed = bytes.clone();
        changed[70_000] ^= 1;
        fs::write(&path, changed).unwrap();
        fs::File::options()
            .write(true)
            .open(&path)
            .unwrap()
            .set_times(fs::FileTimes::new().set_modified(modified))
            .unwrap();
        assert_eq!(fs::metadata(&path).unwrap().modified().unwrap(), modified);
        // Matching metadata cannot admit bytes different from a verified block.
        let error = install_verified(&software(), &artifact, source, &root).unwrap_err();
        assert_eq!(error.reason(), ReasonCode::StateUnavailable);
        assert_eq!(fs::read(&installed.executable).unwrap(), bytes);
        assert_eq!(
            fs::metadata(
                staging::Staging::load(&root, "codex")
                    .unwrap()
                    .unwrap()
                    .stage_path()
                    .join("codex")
            )
            .unwrap()
            .len(),
            65_536
        );
        assert_eq!(recover(&software(), &root).unwrap().len(), 1);
        assert!(remove(&software(), &root).unwrap());
        assert!(!root.join("1.2.3").exists());
        fs::remove_dir_all(&at).unwrap();
    }

    #[test]
    fn reinstallation_preserves_modified_trees_and_replaces_unchanged_ones() {
        let (at, artifact) = staged("twice", b"first", CODEX_MEMBER);
        let root = at.join("software");
        fs::create_dir_all(root.join("bin")).unwrap();
        let entry = root.join("bin/codex");
        fs::write(&entry, b"foreign launcher").unwrap();
        assert!(install(&software(), &artifact, &at.join("artifact.tgz"), &root).is_err());
        assert_eq!(fs::read(&entry).unwrap(), b"foreign launcher");
        assert!(!root.join("1.2.3").exists());
        assert!(
            !store::exists(
                &records::open_root(&root).unwrap(),
                &store::Key::Installation("codex".into())
            )
            .unwrap()
        );
        fs::remove_file(&entry).unwrap();
        install(&software(), &artifact, &at.join("artifact.tgz"), &root).unwrap();
        let stray = root.join("1.2.3/package/left-over");
        fs::write(&stray, b"unrecorded content").unwrap();

        assert!(install(&software(), &artifact, &at.join("artifact.tgz"), &root).is_err());
        assert_eq!(fs::read(&stray).unwrap(), b"unrecorded content");
        fs::remove_file(&stray).unwrap();
        install(&software(), &artifact, &at.join("artifact.tgz"), &root).unwrap();
        assert_eq!(fs::read(root.join("bin/codex")).unwrap(), b"first");
        fs::remove_dir_all(&at).unwrap();
    }

    #[test]
    fn bytes_that_are_not_the_ones_the_plan_named_are_refused() {
        let (at, mut artifact) = staged("digest", b"payload", CODEX_MEMBER);
        artifact.sha256 = "sha256:0000000000000000000000000000000000000000000000000000000000000000";
        let error = install(
            &software(),
            &artifact,
            &at.join("artifact.tgz"),
            &at.join("s"),
        )
        .unwrap_err();
        assert_eq!(error.reason(), ReasonCode::IntegrityMismatch);
        assert!(error.detail().contains("hashes to"), "{}", error.detail());
        fs::remove_dir_all(&at).unwrap();
    }

    #[test]
    fn a_truncated_download_is_named_as_a_length_problem_not_a_digest_one() {
        let (at, artifact) = staged("length", b"payload", CODEX_MEMBER);
        let file = at.join("artifact.tgz");
        let mut bytes = fs::read(&file).unwrap();
        bytes.truncate(bytes.len() - 4);
        fs::write(&file, &bytes).unwrap();

        let error = install(&software(), &artifact, &file, &at.join("s")).unwrap_err();
        assert!(
            error.detail().contains("bytes; the plan named"),
            "{}",
            error.detail()
        );
        fs::remove_dir_all(&at).unwrap();
    }

    #[test]
    fn an_archive_without_the_member_the_plan_named_is_refused() {
        let (at, mut artifact) = staged("member", b"payload", CODEX_MEMBER);
        artifact.member = "package/vendor/somewhere-else/bin/codex";
        let error = install(
            &software(),
            &artifact,
            &at.join("artifact.tgz"),
            &at.join("s"),
        )
        .unwrap_err();
        assert!(
            error.detail().contains("does not contain"),
            "{}",
            error.detail()
        );
        fs::remove_dir_all(&at).unwrap();
    }

    #[test]
    fn removing_takes_the_tree_and_the_exposed_command_with_it() {
        let (at, artifact) = staged("remove", b"payload", CODEX_MEMBER);
        let root = at.join("software");
        let installed = install(&software(), &artifact, &at.join("artifact.tgz"), &root).unwrap();
        assert!(installed.executable.symlink_metadata().is_ok());

        let retained_entry = at.join("retained-entry");
        fs::rename(&installed.executable, &retained_entry).unwrap();
        fs::write(&installed.executable, b"foreign launcher").unwrap();
        assert!(remove(&software(), &root).is_err());
        assert_eq!(
            fs::read(&installed.executable).unwrap(),
            b"foreign launcher"
        );
        assert!(root.join("1.2.3").is_dir());
        fs::remove_file(&installed.executable).unwrap();
        fs::rename(&retained_entry, &installed.executable).unwrap();

        let marker = Present::marker(&root, "codex");
        fs::write(&marker, b"another-version").unwrap();
        assert!(remove(&software(), &root).is_err());
        assert!(root.join("1.2.3").is_dir());
        fs::write(&marker, b"1.2.3").unwrap();
        let manifest = Manifest::path(&root, "codex");
        let manifest_bytes = fs::read(&manifest).unwrap();
        fs::write(&manifest, b"{").unwrap();
        assert!(remove(&software(), &root).is_err());
        assert!(root.join("1.2.3").is_dir());
        fs::write(&manifest, &manifest_bytes).unwrap();

        let linked_manifest = at.join("manifest-link");
        fs::hard_link(&manifest, &linked_manifest).unwrap();
        assert_eq!(Manifest::inspect(&root, "codex"), ManifestState::Unreadable);
        assert!(remove(&software(), &root).is_err());
        assert!(root.join("1.2.3").is_dir());
        fs::remove_file(&linked_manifest).unwrap();

        // A receipt does not authorize deleting files added after installation.
        let foreign = root.join("1.2.3/personal-file");
        fs::write(&foreign, b"preserve").unwrap();
        assert!(remove(&software(), &root).is_err());
        assert!(install(&software(), &artifact, &at.join("artifact.tgz"), &root).is_err());
        assert_eq!(fs::read(&foreign).unwrap(), b"preserve");
        assert!(installed.executable.symlink_metadata().is_ok());
        fs::remove_file(&foreign).unwrap();

        let directory = records::open_root(&root).unwrap();
        let receipt = store::Key::Receipt {
            command: "codex".into(),
            version: "1.2.3".into(),
        };
        store::remove(&directory, &receipt).unwrap();
        assert!(remove(&software(), &root).is_err());
        assert!(root.join("1.2.3").is_dir());
        // Legacy adoption needs the exact archive and every installed byte.
        fs::write(&foreign, b"preserve legacy data").unwrap();
        assert!(install(&software(), &artifact, &at.join("artifact.tgz"), &root).is_err());
        assert_eq!(fs::read(&foreign).unwrap(), b"preserve legacy data");
        recover(&software(), &root).unwrap();
        fs::remove_file(&foreign).unwrap();
        install(&software(), &artifact, &at.join("artifact.tgz"), &root).unwrap();
        let saved: serde_json::Value = store::read(
            &directory,
            &receipt,
            crate::setup_core::software_prefix::INVENTORY_LIMIT,
        )
        .unwrap()
        .unwrap();
        let mut record = saved.clone();
        record["entries"].as_array_mut().unwrap().pop();
        store::write(
            &directory,
            &receipt,
            &record,
            crate::setup_core::software_prefix::INVENTORY_LIMIT,
        )
        .unwrap();
        assert!(remove(&software(), &root).is_err());
        assert!(installed.executable.symlink_metadata().is_ok());
        store::write(
            &directory,
            &receipt,
            &saved,
            crate::setup_core::software_prefix::INVENTORY_LIMIT,
        )
        .unwrap();

        assert!(remove(&software(), &root).unwrap());
        assert!(!store::exists(&directory, &receipt).unwrap());
        assert!(!root.join("1.2.3").exists());
        assert!(installed.executable.symlink_metadata().is_err());
        assert!(!Present::marker(&root, "codex").exists());
        assert!(!Manifest::path(&root, "codex").exists());
        // Removing what is already gone is not a failure, and says so.
        assert!(!remove(&software(), &root).unwrap());
        drop(directory);
        fs::remove_dir_all(&at).unwrap();
    }

    #[test]
    fn an_empty_or_absent_prefix_reads_as_holding_nothing() {
        // A plan for a prefix that does not exist yet is the ordinary first
        // case, not a failure.
        let nowhere = scratch("present-absent");
        assert_eq!(
            Present::under_named(&nowhere, "codex", CODEX_MEMBER),
            Present::default()
        );
    }

    #[test]
    fn what_is_under_a_prefix_is_read_including_which_version_is_exposed() {
        let (at, artifact) = staged("present-read", b"payload", CODEX_MEMBER);
        let root = at.join("software");
        install(&software(), &artifact, &at.join("artifact.tgz"), &root).unwrap();

        // A second version, installed but not exposed.
        fs::create_dir_all(root.join("9.9.9")).unwrap();

        let found = Present::under_named(&root, "codex", CODEX_MEMBER);
        assert_eq!(found.versions, vec!["1.2.3".to_owned(), "9.9.9".to_owned()]);
        assert!(found.holds("1.2.3"));
        assert!(!found.holds("0.0.1"));
        fs::remove_dir_all(&at).unwrap();
    }

    #[test]
    #[cfg(unix)]
    fn the_exposed_version_is_read_through_the_link_however_it_was_written() {
        let (at, artifact) = staged("present-link", b"payload", CODEX_MEMBER);
        let root = at.join("software");
        install(&software(), &artifact, &at.join("artifact.tgz"), &root).unwrap();
        let link = root.join("bin").join("codex");

        // What `expose` writes: an absolute target.
        assert!(fs::read_link(&link).unwrap().is_absolute());
        assert_eq!(
            Present::under_named(&root, "codex", CODEX_MEMBER)
                .exposed
                .as_deref(),
            Some("1.2.3")
        );

        // What a person might write instead. Taking the first component of
        // `../1.2.3/...` without resolving it gives `bin`, and the answer
        // becomes "no entry point names this version" while one does.
        fs::remove_file(&link).unwrap();
        std::os::unix::fs::symlink(
            std::path::Path::new("..").join("1.2.3").join(CODEX_MEMBER),
            &link,
        )
        .unwrap();
        assert!(!fs::read_link(&link).unwrap().is_absolute());
        assert_eq!(
            Present::under_named(&root, "codex", CODEX_MEMBER)
                .exposed
                .as_deref(),
            Some("1.2.3")
        );

        // A dangling link exposes nothing, which is what it means.
        fs::remove_file(&link).unwrap();
        std::os::unix::fs::symlink(root.join("9.9.9").join("codex"), &link).unwrap();
        assert_eq!(
            Present::under_named(&root, "codex", CODEX_MEMBER).exposed,
            None
        );

        fs::remove_dir_all(&at).unwrap();
    }

    #[test]
    fn bin_and_the_control_directory_are_not_versions() {
        let at = scratch("present-notversions");
        fs::create_dir_all(at.join("bin")).unwrap();
        fs::create_dir_all(at.join(".codex-setup-system")).unwrap();
        fs::create_dir_all(at.join("1.2.3")).unwrap();
        assert_eq!(
            Present::under_named(&at, "codex", CODEX_MEMBER).versions,
            vec!["1.2.3".to_owned()]
        );
        fs::remove_dir_all(&at).unwrap();
    }

    #[test]
    fn the_inflation_limit_scales_with_the_artifact_but_never_below_a_floor() {
        let small = Artifact {
            bytes: 10,
            ..ARTIFACTS[0]
        };
        assert_eq!(small.limits().bytes, 64 * 1024 * 1024);
        let large = Artifact {
            bytes: 121_422_431,
            ..ARTIFACTS[0]
        };
        // Claude's is the widest measured expansion, a little over three times.
        assert!(large.limits().bytes > 391_948_592);
    }
}