bootc_lib/bootc_composefs/

gc.rs

//! This module handles the case when deleting a deployment fails midway
//!
//! There could be the following cases (See ./delete.rs:delete_composefs_deployment):
//! - We delete the bootloader entry but fail to delete image
//! - We delete bootloader + image but fail to delete the state/unrefenced objects etc

use std::collections::HashSet;

use anyhow::{Context, Result};
use cap_std_ext::{cap_std::fs::Dir, dirext::CapStdExtDirExt};
use composefs::fsverity::FsVerityHashValue;
use composefs::repository::GcResult;
use composefs_boot::bootloader::EFI_EXT;
use composefs_ctl::composefs;
use composefs_ctl::composefs_boot;
use composefs_ctl::composefs_oci;
use ostree_ext::composefs::fsverity::Sha512HashValue;
use ostree_ext::composefs_oci::linked_erofs_images;
use rustix::fs::AtFlags;
use rustix::fs::FlockOperation;
use rustix::fs::flock;
use rustix::fs::{statat, unlinkat};

use crate::bootc_composefs::boot::GLOBAL_UKI_ADDONS_DIR;
use crate::bootc_composefs::boot::get_global_uki_addon_name;
use crate::bootc_composefs::uki_addon::UkiAddonType;
use crate::bootc_composefs::uki_addon::list_installed_uki_addons;
use crate::bootc_composefs::uki_addon::list_referenced_uki_addons;
use crate::{
    bootc_composefs::{
        boot::{BOOTC_UKI_DIR, BootType, get_type1_dir_name, get_uki_addon_dir_name, get_uki_name},
        delete::{delete_staged, delete_state_dir},
        repo::bootc_tag_for_manifest,
        state::read_origin,
        status::{BootloaderEntry, get_composefs_status, list_bootloader_entries},
    },
    composefs_consts::{
        BOOTC_TAG_PREFIX, ORIGIN_KEY_IMAGE, ORIGIN_KEY_MANIFEST_DIGEST, STATE_DIR_RELATIVE,
        TYPE1_BOOT_DIR_PREFIX, UKI_NAME_PREFIX,
    },
    store::{BootedComposefs, Storage},
};

#[fn_error_context::context("Listing state directories")]
fn list_state_dirs(sysroot: &Dir) -> Result<Vec<String>> {
    let state = sysroot
        .open_dir(STATE_DIR_RELATIVE)
        .context("Opening state dir")?;
    list_deployment_state_dirs(&state)
}

/// List the per-deployment directories in an opened composefs state directory.
pub(crate) fn list_deployment_state_dirs(state: &Dir) -> Result<Vec<String>> {
    let mut dirs = vec![];

    for dir in state.entries_utf8()? {
        let dir = dir?;

        if dir.file_type()?.is_file() {
            continue;
        }

        dirs.push(dir.file_name()?);
    }

    Ok(dirs)
}

type BootBinary = (BootType, String);

fn image_refs_match(
    image_ref_v1: Option<&composefs::fsverity::Sha512HashValue>,
    image_ref_v2: Option<&composefs::fsverity::Sha512HashValue>,
    verity: &str,
) -> bool {
    [image_ref_v1, image_ref_v2]
        .into_iter()
        .flatten()
        .any(|image_ref| image_ref.to_hex() == verity)
}

/// Collect all BLS Type1 boot binaries and UKI binaries by scanning filesystem
///
/// Returns a vector of binary type (UKI/Type1) + name of all boot binaries
#[fn_error_context::context("Collecting boot binaries")]
fn collect_boot_binaries(storage: &Storage) -> Result<Vec<BootBinary>> {
    let mut boot_binaries = Vec::new();
    let boot_dir = storage.bls_boot_binaries_dir()?;
    let boot_mount = storage.require_boot_mount()?;

    // Scan for UKI binaries in EFI/Linux/bootc
    collect_uki_binaries(&boot_mount.fd, &mut boot_binaries)?;

    // Scan for Type1 boot binaries (kernels + initrds) in `boot_dir`
    // depending upon whether systemd-boot is being used, or grub
    collect_type1_boot_binaries(&boot_dir, &mut boot_binaries)?;

    Ok(boot_binaries)
}

/// Scan for UKI binaries in EFI/Linux/bootc
#[fn_error_context::context("Collecting UKI binaries")]
fn collect_uki_binaries(boot_dir: &Dir, boot_binaries: &mut Vec<BootBinary>) -> Result<()> {
    let Ok(Some(efi_dir)) = boot_dir.open_dir_optional(BOOTC_UKI_DIR) else {
        return Ok(());
    };

    for entry in efi_dir.entries_utf8()? {
        let entry = entry?;
        let name = entry.file_name()?;

        let Some(efi_name_no_prefix) = name.strip_prefix(UKI_NAME_PREFIX) else {
            continue;
        };

        if let Some(verity) = efi_name_no_prefix.strip_suffix(EFI_EXT) {
            boot_binaries.push((BootType::Uki, verity.into()));
        }
    }

    Ok(())
}

/// Scan for Type1 boot binaries (kernels + initrds) by looking for directories with
/// that start with bootc_composefs-
///
/// Strips the prefix and returns the rest of the string
#[fn_error_context::context("Collecting Type1 boot binaries")]
fn collect_type1_boot_binaries(boot_dir: &Dir, boot_binaries: &mut Vec<BootBinary>) -> Result<()> {
    for entry in boot_dir.entries_utf8()? {
        let entry = entry?;
        let dir_name = entry.file_name()?;

        if !entry.file_type()?.is_dir() {
            continue;
        }

        let Some(verity) = dir_name.strip_prefix(TYPE1_BOOT_DIR_PREFIX) else {
            continue;
        };

        // The directory name starts with our custom prefix
        boot_binaries.push((BootType::Bls, verity.to_string()));
    }

    Ok(())
}

#[fn_error_context::context("Deleting kernel and initrd")]
fn delete_kernel_initrd(storage: &Storage, dir_to_delete: &str, dry_run: bool) -> Result<()> {
    tracing::debug!("Deleting Type1 entry {dir_to_delete}");

    if dry_run {
        return Ok(());
    }

    let boot_dir = storage.bls_boot_binaries_dir()?;

    boot_dir
        .remove_dir_all(dir_to_delete)
        .with_context(|| anyhow::anyhow!("Deleting {dir_to_delete}"))
}

/// Deletes the UKI `uki_id` and any addons specific to it
#[fn_error_context::context("Deleting UKI and UKI addons {uki_id}")]
fn delete_uki(storage: &Storage, uki_id: &str, dry_run: bool) -> Result<()> {
    let boot_mount = storage.require_boot_mount()?;

    let uki_dir = boot_mount.fd.open_dir(BOOTC_UKI_DIR)?;

    for entry in uki_dir.entries_utf8()? {
        let entry = entry?;
        let entry_name = entry.file_name()?;

        // The actual UKI PE binary
        if entry_name == get_uki_name(uki_id) {
            tracing::debug!("Deleting UKI: {}", entry_name);

            if dry_run {
                continue;
            }

            entry.remove_file().context("Deleting UKI")?;
        } else if entry_name == get_uki_addon_dir_name(uki_id) {
            // Addons dir
            tracing::debug!("Deleting UKI addons directory: {}", entry_name);

            if dry_run {
                continue;
            }

            uki_dir
                .remove_dir_all(entry_name)
                .context("Deleting UKI addons dir")?;
        }
    }

    Ok(())
}

/// Find boot binaries on disk that are not referenced by any bootloader entry.
///
/// We compare against `boot_artifact_name` (the directory/file name on disk)
/// rather than `fsverity` (the composefs= cmdline digest), because a shared
/// entry's directory name may belong to a different deployment than the one
/// whose composefs digest is in the BLS options line.
fn unreferenced_boot_binaries<'a>(
    boot_binaries: &'a [BootBinary],
    bootloader_entries: &[BootloaderEntry],
) -> Vec<&'a BootBinary> {
    boot_binaries
        .iter()
        .filter(|bin| {
            !bootloader_entries
                .iter()
                .any(|entry| entry.boot_artifact_name == bin.1)
        })
        .collect()
}

#[fn_error_context::context("GC Global UKI Addons")]
fn gc_global_uki_addons(
    storage: &Storage,
    booted_cfs: &BootedComposefs,
    gc_opts: &GCOpts,
    bootloader_entries: &Vec<BootloaderEntry>,
) -> Result<()> {
    // GC always runs *after* finalizing deployments so there would be no staged deployment
    // by definition but still only consider live addons for GC
    let currently_installed_addons = list_installed_uki_addons(storage, &None)?
        .into_iter()
        .filter(|addon| !addon.staged)
        .collect::<Vec<_>>();

    if !currently_installed_addons
        .iter()
        .any(|addon| addon.addon_type == UkiAddonType::Global)
    {
        tracing::debug!("No bootc managed Global UKI Addon installed");
        return Ok(());
    }

    // Remove unreferenced global UKI Addons
    // GC always runs *after* finalizing deployments so there would be no staged deployment
    // by definition
    let currently_referenced_addons =
        list_referenced_uki_addons(booted_cfs, &bootloader_entries, &None)?;
    let mut unreferenced_global_addons = vec![];

    tracing::debug!("currently_referenced_addons: {currently_referenced_addons:#?}");
    tracing::debug!("currently_installed_addons: {currently_installed_addons:#?}");

    for installed_addon in &currently_installed_addons {
        // We handle scoped UKI Addons along with the UKI itself
        if installed_addon.addon_type != UkiAddonType::Global {
            continue;
        }

        let is_referenced = currently_referenced_addons.iter().any(|(_, refs)| {
            refs.iter().any(|r| {
                r.addon_type == installed_addon.addon_type && r.name == installed_addon.name
            })
        });

        if !is_referenced {
            unreferenced_global_addons.push(installed_addon.name.clone());
        }
    }

    tracing::debug!("Unreferenced Global Addons: {unreferenced_global_addons:?}");

    if !unreferenced_global_addons.is_empty() {
        let global_uki_dir = storage
            .require_boot_mount()?
            .fd
            .open_dir(GLOBAL_UKI_ADDONS_DIR)
            .context("Opening global UKI Addons dir")?;

        for addon in &unreferenced_global_addons {
            let global_addon_name = get_global_uki_addon_name(&addon);

            tracing::debug!("Deleting Global UKI Addon: {}", addon);

            if gc_opts.dry_run {
                continue;
            }

            global_uki_dir
                .remove_file(&global_addon_name)
                .with_context(|| format!("Removing global addon {global_addon_name}"))?;
        }
    }

    Ok(())
}

pub(crate) struct GCOpts {
    pub(crate) dry_run: bool,
    pub(crate) prune_repo: bool,
}

fn orphaned_state_dirs<'a>(
    state_dirs: &'a [String],
    live_deployments: &[&str],
    bootloader_entries: &[BootloaderEntry],
    is_aboot: bool,
) -> Vec<&'a String> {
    state_dirs
        .iter()
        .filter(|state| {
            if is_aboot {
                !live_deployments.contains(&state.as_str())
            } else {
                !bootloader_entries
                    .iter()
                    .any(|entry| &entry.fsverity == *state)
            }
        })
        .collect()
}

fn get_boot_dump(booted_cfs: &BootedComposefs, verity: &str) -> Result<Option<Vec<u8>>> {
    let verity_to_sha = Sha512HashValue::from_hex(verity);

    let Ok(verity_to_sha) = verity_to_sha else {
        // We do not want to block on GC if we find corrupted state
        tracing::warn!("Bad FSVerity '{verity}' when checkign additional roots, skipping");
        return Ok(None);
    };

    let linked_images = match linked_erofs_images(&booted_cfs.repo, &verity_to_sha) {
        Ok(images) => images,
        Err(err) => {
            tracing::warn!(
                "Unable to inspect linked EROFS images for orphan '{verity}', skipping boot-object cleanup: {err:#}"
            );
            return Ok(None);
        }
    };

    // Get any image that is non-bootable
    let Some(non_bootable_img) = linked_images.iter().find(|img| !img.bootable) else {
        tracing::debug!("No non-bootable image found for {verity}");
        return Ok(None);
    };

    let boot_dump = composefs_ctl::dump_files(
        &booted_cfs.repo,
        &non_bootable_img.id.to_hex(),
        &vec![std::path::Path::new("/").join(crate::install::BOOT)],
        false,
    )
    .context("Getting dump for /boot")?;

    if boot_dump.is_empty() {
        tracing::debug!("Nothing found in /boot in non-bootable image");
        return Ok(None);
    }

    Ok(Some(boot_dump))
}

#[fn_error_context::context("GC UKI Artifacts")]
fn gc_uki_artifacts(
    booted_cfs: &BootedComposefs,
    gc_opts: &GCOpts,
    additional_roots: &Vec<&str>,
    all_orphans: &Vec<&String>,
) -> Result<GcResult> {
    let mut live_objects: HashSet<String> = HashSet::new();
    let mut result = GcResult {
        objects_removed: 0,
        objects_bytes: 0,
        ..Default::default()
    };

    for verity in additional_roots {
        let Some(boot_dump) = get_boot_dump(booted_cfs, verity)? else {
            continue;
        };

        let boot_dump = std::str::from_utf8(&boot_dump).context("dumpfile is not UTF-8")?;

        use composefs::dumpfile_parse::{Entry, Item};

        for line in boot_dump.lines() {
            let entry =
                Entry::parse(line).with_context(|| format!("Parsing dumpfile line '{line}'"))?;

            let Item::Regular { path, .. } = entry.item else {
                continue;
            };

            live_objects.insert(
                path.to_str()
                    .ok_or_else(|| anyhow::anyhow!("Object path is not valid UTF-8"))?
                    .to_string(),
            );
        }
    }

    flock(&booted_cfs.repo.repo_fd(), FlockOperation::LockExclusive)
        .context("Acquiring exclusive lock for GC")?;

    // Now GC the UKI/UKI Addons from `.boot` EROFS if we have them.
    // Aboot artifacts may share repository objects and are left to repository GC.
    // These won't be GC'd by the above `repo.gc` as the EROFS have `/boot` masked.
    for verity in all_orphans {
        let Some(boot_dump) = get_boot_dump(booted_cfs, verity)? else {
            continue;
        };

        let boot_dump = std::str::from_utf8(&boot_dump).context("dumpfile is not UTF-8")?;

        let objects_dir = booted_cfs
            .repo
            .objects_dir()
            .context("Opening objects dir")?;

        use composefs::dumpfile_parse::{Entry, Item};

        for line in boot_dump.lines() {
            let entry =
                Entry::parse(line).with_context(|| format!("Parsing dumpfile line '{line}'"))?;

            let Item::Regular { path, .. } = entry.item else {
                continue;
            };

            let path_string = path
                .to_str()
                .ok_or_else(|| anyhow::anyhow!("Object path is not valid UTF-8"))?
                .to_string();

            if live_objects.contains(&path_string) {
                tracing::debug!("{path:?} is still referenced. Skipping...");
                continue;
            }

            tracing::debug!(
                "{}: objects/{path:?}",
                if gc_opts.dry_run {
                    "would remove"
                } else {
                    "removing"
                },
            );

            if gc_opts.dry_run {
                continue;
            }

            // Get file size before removing
            match statat(&objects_dir, path.as_ref(), AtFlags::empty()) {
                Ok(stat) => {
                    result.objects_bytes += stat.st_size as u64;
                }
                Err(e) if e.kind() == std::io::ErrorKind::NotFound => {
                    tracing::debug!("Object {} not found... skipping", path.display());
                    continue;
                }
                Err(e) => Err(e).with_context(|| format!("statat {} failed", path.display()))?,
            }

            result.objects_removed += 1;

            unlinkat(&objects_dir, path.as_ref(), AtFlags::empty())
                .with_context(|| format!("Unlinking (from bootc) object {path:?}"))?;
        }
    }

    flock(booted_cfs.repo.repo_fd(), FlockOperation::Unlock).context("repository unlock failed")?;

    Ok(result)
}

/// 1. List all bootloader entries
/// 2. List all EROFS images
/// 3. List all state directories
/// 4. List staged depl if any
///
/// If bootloader entry B1 doesn't exist, but EROFS image B1 does exist, then delete the image and
/// perform GC
///
/// Similarly if EROFS image B1 doesn't exist, but state dir does, then delete the state dir and
/// perform GC
//
// Cases
// - BLS Entries
//      - On upgrade/switch, if only two are left, the staged and the current, then no GC
//          - If there are three - rollback, booted and staged, GC the rollback, so the current
//          becomes rollback
#[fn_error_context::context("Running composefs garbage collection")]
pub(crate) async fn composefs_gc(
    storage: &Storage,
    booted_cfs: &BootedComposefs,
    gc_opts: GCOpts,
) -> Result<GcResult> {
    const COMPOSEFS_GC_JOURNAL_ID: &str = "3b2a1f0e9d8c7b6a5f4e3d2c1b0a9f8e7";

    tracing::info!(
        message_id = COMPOSEFS_GC_JOURNAL_ID,
        bootc.operation = "gc",
        bootc.current_deployment = booted_cfs.cmdline.digest,
        "Starting composefs garbage collection"
    );

    // Upgrade any old-format OCI images (pre-EROFS-at-pull-time) before GC.
    //
    // Old bootc (pre composefs-rs 93634590c) used a seal-based flow that stored
    // the composefs EROFS hash in an OCI config label but did NOT commit the EROFS
    // image into the repository's images/ directory.  The GC's additional_roots
    // mechanism protects deployments by looking up each deployment's EROFS verity
    // in images/ and walking its object refs — but if no such image exists (old
    // format), all the layer blob objects for that deployment appear unreferenced
    // and are incorrectly collected.
    //
    // upgrade_repo() walks every tagged OCI image and generates EROFS for any
    // that lack it, rewriting their config splitstreams.  After this step the
    // additional_roots lookup succeeds and the rollback deployment's objects are
    // protected.  This is a no-op for already-upgraded images (idempotent).
    //
    // Safety net: upgrade_repo() is also called in pull_composefs_repo() so
    // that it runs at `bootc upgrade`/`bootc switch` time before any new
    // deployment is staged.  Running it here too covers the case where GC is
    // invoked directly (e.g. `bootc internals composefs-gc`) on a system that
    // skipped the pull path.  upgrade_repo() is idempotent (fast-paths images
    // that already have EROFS refs) and always runs even in dry-run mode since
    // it is a format migration, not a deletion.
    let upgrade_result = composefs_oci::upgrade_repo(&booted_cfs.repo)
        .context("Upgrading old-format OCI images before GC")?;
    if upgrade_result.upgraded > 0 {
        tracing::info!(
            "Upgraded {} old-format OCI image(s) to current format before GC",
            upgrade_result.upgraded
        );
    }

    let host = get_composefs_status(storage, booted_cfs).await?;
    let booted_cfs_status = host.require_composefs_booted()?;

    let sysroot = &storage.physical_root;

    let is_aboot = booted_cfs_status.boot_type == BootType::Aboot;
    let (bootloader_entries, boot_binaries) = if is_aboot {
        (Vec::new(), Vec::new())
    } else {
        (
            list_bootloader_entries(storage)?,
            collect_boot_binaries(storage)?,
        )
    };

    tracing::debug!("bootloader_entries: {bootloader_entries:?}");
    tracing::debug!("boot_binaries: {boot_binaries:?}");

    let unreferenced_boot_binaries =
        unreferenced_boot_binaries(&boot_binaries, &bootloader_entries);

    tracing::debug!("unreferenced_boot_binaries: {unreferenced_boot_binaries:?}");

    if unreferenced_boot_binaries
        .iter()
        .find(|be| be.1 == booted_cfs_status.verity)
        .is_some()
    {
        anyhow::bail!(
            "Inconsistent state. Booted binaries '{}' found for cleanup",
            booted_cfs_status.verity
        )
    }

    for (ty, verity) in &unreferenced_boot_binaries {
        match ty {
            BootType::Bls => {
                delete_kernel_initrd(storage, &get_type1_dir_name(verity), gc_opts.dry_run)?
            }
            BootType::Uki => delete_uki(storage, verity, gc_opts.dry_run)?,
            BootType::Aboot => {
                anyhow::bail!("Aboot artifact unexpectedly reached boot binary garbage collection")
            }
        }
    }

    if booted_cfs_status.boot_type == BootType::Uki {
        gc_global_uki_addons(storage, booted_cfs, &gc_opts, &bootloader_entries)?;
    }

    if !gc_opts.prune_repo {
        return Ok(GcResult::default());
    }

    // Identify orphaned deployments: state dirs or bootloader entries
    // that don't correspond to a live deployment. EROFS images in
    // composefs/images/ are NOT managed here — repo.gc() handles those
    // via the tag→manifest→config→image ref chain.
    let state_dirs = list_state_dirs(&sysroot)?;

    let staged = &host.status.staged;

    let live_deployments = host
        .list_deployments()
        .into_iter()
        .map(|deployment| {
            deployment
                .require_composefs()
                .map(|cfs| cfs.verity.as_str())
        })
        .collect::<Result<Vec<_>>>()?;

    // Aboot uses slot/pending references from status (because there are no BLS files).
    // BLS/UKI use raw boot entries, which can retain deployments omitted from status
    // after interrupted operations.
    let orphaned_state_dirs = orphaned_state_dirs(
        &state_dirs,
        &live_deployments,
        &bootloader_entries,
        is_aboot,
    );

    // Bootloader entries without a state dir are from interrupted cleanups.
    let orphaned_boot_entries: Vec<_> = if is_aboot {
        Vec::new()
    } else {
        bootloader_entries
            .iter()
            .map(|entry| &entry.fsverity)
            .filter(|verity| !state_dirs.contains(verity))
            .collect()
    };

    let all_orphans: Vec<_> = orphaned_state_dirs
        .iter()
        .chain(orphaned_boot_entries.iter())
        .copied()
        .collect();

    if all_orphans.contains(&&booted_cfs_status.verity) {
        anyhow::bail!(
            "Inconsistent state. Booted entry '{}' found for cleanup",
            booted_cfs_status.verity
        )
    }

    for verity in &orphaned_state_dirs {
        tracing::debug!("Cleaning up orphaned state dir: {verity}");
        delete_staged(staged, &all_orphans, gc_opts.dry_run)?;
        delete_state_dir(&sysroot, verity, gc_opts.dry_run)?;
    }

    for verity in &orphaned_boot_entries {
        tracing::debug!("Cleaning up orphaned bootloader entry: {verity}");
        delete_staged(staged, &all_orphans, gc_opts.dry_run)?;
    }

    // Collect the set of manifest digests referenced by live deployments,
    // and track EROFS image verities as fallback additional_roots for
    // deployments that predate the manifest -> image link.
    let mut live_manifest_digests: Vec<composefs_oci::OciDigest> = Vec::new();
    let mut additional_roots = Vec::new();
    // Container image names for containers-storage pruning.
    let mut live_container_images: std::collections::HashSet<String> = Default::default();

    // Read existing tags before the deployment loop so we can search
    // them for deployments that lack manifest_digest in their origin.
    let existing_tags = composefs_oci::list_refs(&*booted_cfs.repo)
        .context("Listing OCI tags in composefs repo")?;

    for deployment in host.list_deployments() {
        let verity = &deployment.require_composefs()?.verity;

        // Skip deployments that are already being GC'd.
        if all_orphans.contains(&verity) {
            continue;
        }

        // Keep the EROFS image as an additional root until all deployments
        // have manifest -> image refs. Once a deployment is pulled with the
        // new code, its EROFS image is reachable from the manifest and
        // this entry becomes redundant (but harmless).
        additional_roots.push(verity.clone());

        if let Some(ini) = read_origin(sysroot, verity)? {
            // Collect the container image name for containers-storage GC.
            if let Some(container_ref) =
                ini.get::<String>("origin", ostree_ext::container::deploy::ORIGIN_CONTAINER)
            {
                // Parse the ostree image reference to extract the bare image name
                // (e.g. "quay.io/foo:tag" from "ostree-unverified-image:docker://quay.io/foo:tag")
                let image_name = container_ref
                    .parse::<ostree_ext::container::OstreeImageReference>()
                    .map(|r| r.imgref.name)
                    .unwrap_or_else(|_| container_ref.clone());
                live_container_images.insert(image_name);
            }

            if let Some(manifest_digest_str) =
                ini.get::<String>(ORIGIN_KEY_IMAGE, ORIGIN_KEY_MANIFEST_DIGEST)
            {
                let digest: composefs_oci::OciDigest = manifest_digest_str
                    .parse()
                    .with_context(|| format!("Parsing manifest digest {manifest_digest_str}"))?;
                live_manifest_digests.push(digest);
            } else {
                // Pre-OCI-metadata deployment: search tagged manifests
                // for one whose config links to this EROFS image.
                let mut found_manifest = false;
                for (_, ref_digest) in &existing_tags {
                    if let Ok(img) = composefs_oci::oci_image::OciImage::open(
                        &*booted_cfs.repo,
                        ref_digest,
                        None,
                    ) {
                        // Check both V1 and V2 slots: the deployment verity
                        // may have been produced under either format.
                        if image_refs_match(img.image_ref_v1(), img.image_ref_v2(), verity) {
                            tracing::info!(
                                "Deployment {verity} has no manifest_digest in origin; \
                                 found matching manifest {ref_digest} via image_ref"
                            );
                            live_manifest_digests.push(ref_digest.clone());
                            found_manifest = true;
                            break;
                        }
                    }
                }
                if !found_manifest {
                    tracing::warn!(
                        "Deployment {verity} has no manifest_digest in origin \
                         and no tagged manifest references it; \
                         EROFS image is protected but OCI metadata may be collected"
                    );
                }
            }
        }
    }

    // Migration: ensure every live deployment has a bootc-owned tag.
    // Deployments from before the tag-based GC won't have tags yet;
    // create them now so their OCI metadata survives this GC cycle.

    for manifest_digest in &live_manifest_digests {
        let expected_tag = bootc_tag_for_manifest(&manifest_digest.to_string());
        let has_tag = existing_tags
            .iter()
            .any(|(tag_name, _)| tag_name == &expected_tag);
        if !has_tag {
            tracing::info!("Creating missing bootc tag for live deployment: {expected_tag}");
            if !gc_opts.dry_run {
                composefs_oci::tag_image(&*booted_cfs.repo, manifest_digest, &expected_tag)
                    .with_context(|| format!("Creating migration tag {expected_tag}"))?;
            }
        }
    }

    // Re-read tags after potential migration.
    let all_tags = composefs_oci::list_refs(&*booted_cfs.repo)
        .context("Listing OCI tags in composefs repo")?;

    for (tag_name, manifest_digest) in &all_tags {
        if !tag_name.starts_with(BOOTC_TAG_PREFIX) {
            // Not a bootc-owned tag; leave it alone (could be an app image).
            continue;
        }

        if !live_manifest_digests.iter().any(|d| d == manifest_digest) {
            tracing::debug!("Removing unreferenced bootc tag: {tag_name}");
            if !gc_opts.dry_run {
                composefs_oci::untag_image(&*booted_cfs.repo, tag_name)
                    .with_context(|| format!("Removing tag {tag_name}"))?;
            }
        }
    }

    let additional_roots = additional_roots
        .iter()
        .map(|x| x.as_str())
        .collect::<Vec<_>>();

    // Prune containers-storage: remove images not backing any live deployment.
    if !gc_opts.dry_run && !live_container_images.is_empty() {
        let subpath = crate::podstorage::CStorage::subpath();
        if sysroot.try_exists(&subpath).unwrap_or(false) {
            let run = Dir::open_ambient_dir("/run", cap_std_ext::cap_std::ambient_authority())?;
            let imgstore = crate::podstorage::CStorage::create(&sysroot, &run, None)?;
            let roots: std::collections::HashSet<&str> =
                live_container_images.iter().map(|s| s.as_str()).collect();
            let pruned = imgstore.prune_except_roots(&roots).await?;
            if !pruned.is_empty() {
                tracing::info!("Pruned {} images from containers-storage", pruned.len());
            }
        }
    }

    let uki_gc_result = if booted_cfs_status.boot_type == BootType::Uki {
        let res = gc_uki_artifacts(booted_cfs, &gc_opts, &additional_roots, &all_orphans)?;
        Some(res)
    } else {
        None
    };

    // Run garbage collection. Tags root the OCI metadata chain
    // (manifest → config → layers). The additional_roots protect EROFS
    // images for deployments that predate the manifest→image link;
    // once all deployments have been pulled with the new code, these
    // become redundant.
    // `Repository::gc()` takes an exclusive flock on the repository file as its
    // first action. Callers must ensure no other `Repository` handle on that
    // same underlying file is still alive when this runs, or it will deadlock
    // (see update.rs's do_upgrade() for an example of getting this wrong).
    let mut gc_result = if gc_opts.dry_run {
        booted_cfs.repo.gc_dry_run(&additional_roots)?
    } else {
        booted_cfs.repo.gc(&additional_roots)?
    };

    if let Some(uki_gc_result) = uki_gc_result {
        gc_result.objects_bytes += uki_gc_result.objects_bytes;
        gc_result.objects_removed += uki_gc_result.objects_removed;
    }

    Ok(gc_result)
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::bootc_composefs::status::list_type1_entries;
    use crate::bootc_composefs::{aboot, status::ComposefsCmdline};
    use crate::composefs_consts::STATE_DIR_RELATIVE;
    use crate::store::ComposefsRepository;
    use crate::testutils::{ChangeType, TestRoot};
    use cap_std_ext::{cap_std::ambient_authority, cap_tempfile::tempdir};
    use composefs_ctl::composefs::repository::RepositoryConfig;

    fn write_aboot_origin(root: &Dir, digest: &str) -> Result<()> {
        let path = format!("{STATE_DIR_RELATIVE}/{digest}");
        root.create_dir_all(&path)?;
        root.atomic_write(
            format!("{path}/{digest}.origin"),
            "[boot]\nboot_type=aboot\ndigest=boot-digest\n",
        )?;
        Ok(())
    }

    #[test]
    fn aboot_orphans_only_unreferenced_state() {
        let state = ["booted".into(), "rollback".into(), "invalid".into()];
        let live = ["booted", "rollback"];
        let orphans = orphaned_state_dirs(&state, &live, &[], true);
        assert_eq!(
            orphans.iter().map(|s| s.as_str()).collect::<Vec<_>>(),
            ["invalid"]
        );

        let live = ["booted"];
        let orphans = orphaned_state_dirs(&state, &live, &[], true);
        assert_eq!(
            orphans.iter().map(|s| s.as_str()).collect::<Vec<_>>(),
            ["rollback", "invalid"]
        );
    }

    #[tokio::test]
    async fn aboot_gc_uses_status_roots() -> Result<()> {
        let root = tempdir(ambient_authority())?;
        root.create_dir_all("composefs")?;
        root.create_dir("run")?;
        let repo_dir = root.open_dir("composefs")?;
        let config = RepositoryConfig::new(composefs_ctl::composefs::fsverity::Algorithm::SHA512)
            .set_insecure();
        let (repo, _) = ComposefsRepository::init_path(&repo_dir, ".", config)?;
        let repo = std::sync::Arc::new(repo);
        let storage = Storage::new_composefs_for_test(&root, &root.open_dir("run")?)?;
        let booted = "aa".repeat(64);
        let rollback = "bb".repeat(64);
        let orphan = "cc".repeat(64);
        for digest in [&booted, &rollback, &orphan] {
            write_aboot_origin(&root, digest)?;
        }
        let mut aboot_state = aboot::AbootState::open(&root)?;
        aboot_state.record_booted(
            &linux_kernel_cmdline::utf8::Cmdline::from("androidboot.slot_suffix=_a"),
            &booted,
        )?;
        aboot_state.record_booted(
            &linux_kernel_cmdline::utf8::Cmdline::from("androidboot.slot_suffix=_b"),
            &rollback,
        )?;
        let cmdline = Box::leak(Box::new(ComposefsCmdline::new(&booted)));
        let booted_cfs = BootedComposefs { repo, cmdline };

        composefs_gc(
            &storage,
            &booted_cfs,
            GCOpts {
                dry_run: false,
                prune_repo: true,
            },
        )
        .await?;

        assert!(root.try_exists(format!("{STATE_DIR_RELATIVE}/{booted}"))?);
        assert!(root.try_exists(format!("{STATE_DIR_RELATIVE}/{rollback}"))?);
        assert!(!root.try_exists(format!("{STATE_DIR_RELATIVE}/{orphan}"))?);
        Ok(())
    }

    #[test]
    fn test_image_refs_match_v2_when_v1_is_present() {
        let v1 = composefs::fsverity::Sha512HashValue::from_hex(&"11".repeat(64)).unwrap();
        let v2 = composefs::fsverity::Sha512HashValue::from_hex(&"22".repeat(64)).unwrap();

        assert!(image_refs_match(Some(&v1), Some(&v2), &v2.to_hex()));
    }

    /// Reproduce the shared-entry GC bug from issue #2102.
    ///
    /// Scenario with both shared and non-shared kernels:
    ///
    /// 1. Install deployment A (kernel K1, boot dir "A")
    /// 2. Upgrade to B, same kernel → shares A's boot dir
    /// 3. Upgrade to C, new kernel K2 → gets its own boot dir "C"
    /// 4. Upgrade to D, same kernel as C → shares C's boot dir
    ///
    /// After GC of A (the creator of boot dir used by B):
    /// - A's boot dir must still exist (B references it)
    /// - C's boot dir must still exist (D references it)
    ///
    /// The old code compared `fsverity` instead of `boot_artifact_name`,
    /// which would incorrectly mark A's boot dir as unreferenced once A's
    /// BLS entry is gone — even though B still points its linux/initrd
    /// paths at A's directory.
    #[test]
    fn test_gc_shared_boot_binaries_not_deleted() -> anyhow::Result<()> {
        let mut root = TestRoot::new()?;
        let digest_a = root.current().verity.clone();

        // B shares A's kernel (userspace-only change)
        root.upgrade(1, ChangeType::Userspace)?;

        // C gets a new kernel
        root.upgrade(2, ChangeType::Kernel)?;
        let digest_c = root.current().verity.clone();

        // D shares C's kernel (userspace-only change)
        root.upgrade(3, ChangeType::Userspace)?;
        let digest_d = root.current().verity.clone();

        // Now GC deployment A — the one that *created* the shared boot dir
        root.gc_deployment(&digest_a)?;

        // At this point only C (secondary) and D (primary) have BLS entries.
        // But A's boot binary directory is still on disk because B used to
        // share it and we haven't cleaned up boot binaries yet — that's
        // what the GC filter decides.
        let boot_dir = root.boot_dir()?;

        // Collect what's on disk: two boot dirs (A's and C's)
        let mut on_disk = Vec::new();
        collect_type1_boot_binaries(&boot_dir, &mut on_disk)?;
        assert_eq!(
            on_disk.len(),
            2,
            "should have A's and C's boot dirs on disk"
        );

        // Collect what the BLS entries reference
        let bls_entries = list_type1_entries(&boot_dir)?;
        assert_eq!(bls_entries.len(), 2, "D (primary) + C (secondary)");

        // The fix: unreferenced_boot_binaries uses boot_artifact_name.
        // D's boot_artifact_name points to C's dir, C's points to itself.
        // A's boot dir is NOT referenced by any current BLS entry's
        // boot_artifact_name (B was the one referencing it, and B is no
        // longer in the BLS entries either).
        let unreferenced = unreferenced_boot_binaries(&on_disk, &bls_entries);

        // A's boot dir IS unreferenced (only B used it, and B isn't in BLS anymore)
        assert_eq!(unreferenced.len(), 1);
        assert_eq!(unreferenced[0].1, digest_a);

        // C's boot dir is still referenced (by both C and D via boot_artifact_name)
        assert!(
            !unreferenced.iter().any(|b| b.1 == digest_c),
            "C's boot dir must not be unreferenced"
        );

        // Now the more dangerous scenario: GC C, the creator of the boot
        // dir that D shares. After this, remaining deployments are [B, D].
        // B still shares A's boot dir, D still shares C's boot dir.
        root.gc_deployment(&digest_c)?;

        let mut on_disk_2 = Vec::new();
        collect_type1_boot_binaries(&root.boot_dir()?, &mut on_disk_2)?;
        // A's dir + C's dir still on disk (boot binary cleanup hasn't run)
        assert_eq!(on_disk_2.len(), 2);

        let bls_entries_2 = list_type1_entries(&root.boot_dir()?)?;
        // D (primary) + B (secondary)
        assert_eq!(bls_entries_2.len(), 2);

        let entry_d = bls_entries_2
            .iter()
            .find(|e| e.fsverity == digest_d)
            .unwrap();
        assert_eq!(
            entry_d.boot_artifact_name, digest_c,
            "D shares C's boot dir"
        );

        let unreferenced_2 = unreferenced_boot_binaries(&on_disk_2, &bls_entries_2);

        // Both boot dirs are still referenced:
        // - A's dir via B's boot_artifact_name
        // - C's dir via D's boot_artifact_name
        assert!(
            unreferenced_2.is_empty(),
            "no boot dirs should be unreferenced when both are shared"
        );

        // Prove the old buggy logic would fail: if we compared fsverity
        // instead of boot_artifact_name, BOTH dirs would be wrongly
        // unreferenced. Neither A nor C has a BLS entry with matching
        // fsverity — only B (verity=B) and D (verity=D) exist, but their
        // boot dirs are named after A and C respectively.
        let buggy_unreferenced: Vec<_> = on_disk_2
            .iter()
            .filter(|bin| !bls_entries_2.iter().any(|e| e.fsverity == bin.1))
            .collect();
        assert_eq!(
            buggy_unreferenced.len(),
            2,
            "old fsverity-based logic would incorrectly GC both boot dirs"
        );

        Ok(())
    }

    /// Verify that list_type1_entries correctly parses legacy (unprefixed) BLS
    /// entries. This is the code path that composefs_gc actually uses to find
    /// bootloader entries, so it's critical that it handles both layouts.
    #[test]
    fn test_list_type1_entries_handles_legacy_bls() -> anyhow::Result<()> {
        let mut root = TestRoot::new_legacy()?;
        let digest_a = root.current().verity.clone();

        root.upgrade(1, ChangeType::Userspace)?;
        let digest_b = root.current().verity.clone();

        let boot_dir = root.boot_dir()?;
        let bls_entries = list_type1_entries(&boot_dir)?;

        assert_eq!(bls_entries.len(), 2, "Should find both BLS entries");

        // boot_artifact_name should return the raw digest (no prefix)
        // because the legacy entries don't have the prefix
        for entry in &bls_entries {
            assert_eq!(
                entry.boot_artifact_name, digest_a,
                "Both entries should reference A's boot dir (shared kernel)"
            );
        }

        // fsverity should differ between the two entries
        let verity_set: std::collections::HashSet<&str> =
            bls_entries.iter().map(|e| e.fsverity.as_str()).collect();
        assert!(verity_set.contains(digest_a.as_str()));
        assert!(verity_set.contains(digest_b.as_str()));

        Ok(())
    }

    /// Legacy (unprefixed) boot dirs are invisible to collect_type1_boot_binaries,
    /// which only looks for the `bootc_composefs-` prefix. This test verifies
    /// that the GC scanner does not see unprefixed directories.
    ///
    /// This is the problem that PR #2128 solves by migrating legacy entries
    /// to the prefixed format before any GC or status operations run.
    #[test]
    fn test_legacy_boot_dirs_invisible_to_gc_scanner() -> anyhow::Result<()> {
        let root = TestRoot::new_legacy()?;

        // The legacy layout creates a boot dir without the prefix
        let boot_dir = root.boot_dir()?;
        let mut on_disk = Vec::new();
        collect_type1_boot_binaries(&boot_dir, &mut on_disk)?;

        // collect_type1_boot_binaries requires the prefix — legacy dirs
        // are invisible to it
        assert!(
            on_disk.is_empty(),
            "Legacy (unprefixed) boot dirs should not be found by collect_type1_boot_binaries"
        );

        Ok(())
    }

    /// After migration from legacy to prefixed layout, GC should work
    /// correctly — the boot binary directories become visible and
    /// the BLS entries reference them properly.
    #[test]
    fn test_gc_works_after_legacy_migration() -> anyhow::Result<()> {
        let mut root = TestRoot::new_legacy()?;
        let digest_a = root.current().verity.clone();

        // B shares A's kernel (userspace-only change)
        root.upgrade(1, ChangeType::Userspace)?;

        // C gets a new kernel
        root.upgrade(2, ChangeType::Kernel)?;

        // Simulate the migration that PR #2128 performs
        root.migrate_to_prefixed()?;

        // Now GC should see both boot dirs
        let boot_dir = root.boot_dir()?;
        let mut on_disk = Vec::new();
        collect_type1_boot_binaries(&boot_dir, &mut on_disk)?;
        assert_eq!(on_disk.len(), 2, "Should see A's and C's boot dirs");

        // BLS entries should correctly reference boot artifact names
        let bls_entries = list_type1_entries(&boot_dir)?;
        assert_eq!(bls_entries.len(), 2);

        // No boot dirs should be unreferenced (all are in use)
        let unreferenced = unreferenced_boot_binaries(&on_disk, &bls_entries);
        assert!(
            unreferenced.is_empty(),
            "All boot dirs should be referenced after migration"
        );

        // GC deployment A (the one that created the shared boot dir)
        root.gc_deployment(&digest_a)?;

        let boot_dir = root.boot_dir()?;
        let bls_entries = list_type1_entries(&boot_dir)?;
        assert_eq!(bls_entries.len(), 2, "B (secondary) + C (primary)");

        let mut on_disk = Vec::new();
        collect_type1_boot_binaries(&boot_dir, &mut on_disk)?;
        assert_eq!(on_disk.len(), 2, "Both boot dirs still on disk");

        let unreferenced = unreferenced_boot_binaries(&on_disk, &bls_entries);
        // A's boot dir is still referenced by B
        assert!(
            unreferenced.is_empty(),
            "A's boot dir should still be referenced by B after migration"
        );

        Ok(())
    }

    /// Test the full upgrade cycle with shared kernels after migration:
    /// install (legacy) → migrate → upgrade → GC.
    ///
    /// This verifies that GC correctly handles a system that was originally
    /// installed with old bootc, migrated, and then upgraded with new bootc.
    #[test]
    fn test_gc_post_migration_upgrade_cycle() -> anyhow::Result<()> {
        let mut root = TestRoot::new_legacy()?;
        let digest_a = root.current().verity.clone();

        // B shares A's kernel (still legacy)
        root.upgrade(1, ChangeType::Userspace)?;

        // Simulate migration
        root.migrate_to_prefixed()?;

        // Now upgrade with new bootc (creates prefixed entries)
        root.upgrade(2, ChangeType::Kernel)?;
        let digest_c = root.current().verity.clone();

        // D shares C's kernel
        root.upgrade(3, ChangeType::Userspace)?;
        let digest_d = root.current().verity.clone();

        // GC all old deployments, keeping only C and D
        root.gc_deployment(&digest_a)?;

        let boot_dir = root.boot_dir()?;
        let mut on_disk = Vec::new();
        collect_type1_boot_binaries(&boot_dir, &mut on_disk)?;

        let bls_entries = list_type1_entries(&boot_dir)?;
        assert_eq!(bls_entries.len(), 2, "D (primary) + C (secondary)");

        let unreferenced = unreferenced_boot_binaries(&on_disk, &bls_entries);
        // A's boot dir is unreferenced (B is gone, only C and D remain)
        assert_eq!(
            unreferenced.len(),
            1,
            "A's boot dir should be unreferenced after GC of A and B is evicted"
        );
        assert_eq!(unreferenced[0].1, digest_a);

        // C's boot dir must still be referenced by D
        assert!(
            !unreferenced.iter().any(|b| b.1 == digest_c),
            "C's boot dir must still be referenced by D"
        );

        // Verify D shares C's boot dir
        let entry_d = bls_entries
            .iter()
            .find(|e| e.fsverity == digest_d)
            .expect("D should have a BLS entry");
        assert_eq!(
            entry_d.boot_artifact_name, digest_c,
            "D should share C's boot dir"
        );

        Ok(())
    }

    /// Test deep transitive sharing: A → B → C → D all share A's boot dir
    /// via successive userspace-only upgrades. When we GC A (the creator
    /// of the boot dir), the dir must be kept because the remaining
    /// deployments still reference it.
    ///
    /// This tests that boot_dir_verity propagates correctly through
    /// a chain of userspace-only upgrades and that the GC filter handles
    /// the case where no remaining deployment's fsverity matches the
    /// boot directory name.
    #[test]
    fn test_gc_deep_transitive_sharing_chain() -> anyhow::Result<()> {
        let mut root = TestRoot::new()?;
        let digest_a = root.current().verity.clone();

        // B, C, D all share A's kernel via userspace-only upgrades
        root.upgrade(1, ChangeType::Userspace)?;
        root.upgrade(2, ChangeType::Userspace)?;
        root.upgrade(3, ChangeType::Userspace)?;
        let digest_d = root.current().verity.clone();

        // Only one boot dir on disk (all share A's)
        let boot_dir = root.boot_dir()?;
        let mut on_disk = Vec::new();
        collect_type1_boot_binaries(&boot_dir, &mut on_disk)?;
        assert_eq!(on_disk.len(), 1, "All deployments share one boot dir");
        assert_eq!(on_disk[0].1, digest_a, "The boot dir belongs to A");

        // BLS entries: D (primary) + C (secondary), both referencing A's dir
        let bls_entries = list_type1_entries(&boot_dir)?;
        assert_eq!(bls_entries.len(), 2);
        for entry in &bls_entries {
            assert_eq!(
                entry.boot_artifact_name, digest_a,
                "All entries reference A's boot dir"
            );
        }

        // GC deployment A (the creator of the shared boot dir)
        root.gc_deployment(&digest_a)?;

        let boot_dir = root.boot_dir()?;
        let bls_entries = list_type1_entries(&boot_dir)?;
        // D (primary) + C (secondary) — A was already evicted from BLS
        assert_eq!(bls_entries.len(), 2);

        let mut on_disk = Vec::new();
        collect_type1_boot_binaries(&boot_dir, &mut on_disk)?;

        let unreferenced = unreferenced_boot_binaries(&on_disk, &bls_entries);
        assert!(
            unreferenced.is_empty(),
            "A's boot dir must stay — C and D still reference it"
        );

        // Now also GC B and C, leaving only D
        let digest_b = crate::testutils::fake_digest_version(1);
        let digest_c = crate::testutils::fake_digest_version(2);
        root.gc_deployment(&digest_b)?;
        root.gc_deployment(&digest_c)?;

        // D is the only deployment left
        let boot_dir = root.boot_dir()?;
        let bls_entries = list_type1_entries(&boot_dir)?;
        assert_eq!(bls_entries.len(), 1, "Only D remains");
        assert_eq!(bls_entries[0].fsverity, digest_d);
        assert_eq!(
            bls_entries[0].boot_artifact_name, digest_a,
            "D still references A's boot dir"
        );

        let mut on_disk = Vec::new();
        collect_type1_boot_binaries(&boot_dir, &mut on_disk)?;
        let unreferenced = unreferenced_boot_binaries(&on_disk, &bls_entries);
        assert!(
            unreferenced.is_empty(),
            "A's boot dir must survive — D is the last deployment and still uses it"
        );

        Ok(())
    }

    /// Verify that boot_artifact_info().1 (has_prefix) is the correct
    /// signal for identifying entries that need migration, and that the
    /// GC filter works correctly at each stage of the migration pipeline.
    ///
    /// This exercises the API that stage_bls_entry_changes() in PR #2128
    /// uses to decide which entries to migrate.
    #[test]
    fn test_boot_artifact_info_drives_migration_decisions() -> anyhow::Result<()> {
        use crate::bootc_composefs::status::get_sorted_type1_boot_entries;

        let mut root = TestRoot::new_legacy()?;
        let digest_a = root.current().verity.clone();

        root.upgrade(1, ChangeType::Userspace)?;
        root.upgrade(2, ChangeType::Kernel)?;

        // -- Pre-migration: all entries lack the prefix --
        let boot_dir = root.boot_dir()?;
        let raw_entries = get_sorted_type1_boot_entries(&boot_dir, true)?;
        assert_eq!(raw_entries.len(), 2);

        let needs_migration: Vec<_> = raw_entries
            .iter()
            .filter(|e| !e.boot_artifact_info().unwrap().1)
            .collect();
        assert_eq!(
            needs_migration.len(),
            2,
            "All legacy entries should need migration (has_prefix=false)"
        );

        // GC scanner can't see the boot dirs (no prefix on disk)
        let mut on_disk = Vec::new();
        collect_type1_boot_binaries(&boot_dir, &mut on_disk)?;
        assert!(on_disk.is_empty(), "Legacy dirs invisible before migration");

        // -- Migrate --
        root.migrate_to_prefixed()?;

        // -- Post-migration: all entries have the prefix --
        let boot_dir = root.boot_dir()?;
        let raw_entries = get_sorted_type1_boot_entries(&boot_dir, true)?;
        assert_eq!(raw_entries.len(), 2);

        let needs_migration: Vec<_> = raw_entries
            .iter()
            .filter(|e| !e.boot_artifact_info().unwrap().1)
            .collect();
        assert!(
            needs_migration.is_empty(),
            "No entries should need migration after migrate_to_prefixed()"
        );

        // GC scanner can now see the boot dirs
        let mut on_disk = Vec::new();
        collect_type1_boot_binaries(&boot_dir, &mut on_disk)?;
        assert_eq!(on_disk.len(), 2, "Both dirs visible after migration");

        // GC filter correctly identifies all dirs as referenced
        let bls_entries = list_type1_entries(&boot_dir)?;
        let unreferenced = unreferenced_boot_binaries(&on_disk, &bls_entries);
        assert!(
            unreferenced.is_empty(),
            "All dirs referenced after migration"
        );

        // -- Upgrade with new bootc (prefixed from creation) --
        root.upgrade(3, ChangeType::Kernel)?;

        let boot_dir = root.boot_dir()?;
        let raw_entries = get_sorted_type1_boot_entries(&boot_dir, true)?;
        // All entries (both migrated and new) should have the prefix
        for entry in &raw_entries {
            let (_, has_prefix) = entry.boot_artifact_info()?;
            assert!(
                has_prefix,
                "All entries should have prefix after migration + upgrade"
            );
        }

        // GC should now see 3 boot dirs: A's, C's (from upgrade 2), and
        // the new one from upgrade 3
        let mut on_disk = Vec::new();
        collect_type1_boot_binaries(&boot_dir, &mut on_disk)?;
        assert_eq!(on_disk.len(), 3, "Three boot dirs on disk");

        // Only 2 BLS entries (primary + secondary), so one dir is unreferenced
        let bls_entries = list_type1_entries(&boot_dir)?;
        assert_eq!(bls_entries.len(), 2);
        let unreferenced = unreferenced_boot_binaries(&on_disk, &bls_entries);
        assert_eq!(
            unreferenced.len(),
            1,
            "A's boot dir should be unreferenced (B evicted from BLS)"
        );
        assert_eq!(unreferenced[0].1, digest_a);

        Ok(())
    }
}