cleanup-bootstrap-root.sh

#!/usr/bin/env bash
#
# cleanup-bootstrap-root.sh
#
# Safely removes verified filesystem content from a retired
# Btrfs bootstrap root after transitioning to a snapshot root.
#
# Version: 1.1.0
# License: GPL-3.0-or-later
#
# Copyright (C) 2026 Scott McClain
# SPDX-License-Identifier: GPL-3.0-or-later
#
# Execution stages:
#   1. Environment verification
#   2. Mount bootstrap root
#   3. Discover subvolumes
#   4. Discover active snapshot
#   5. Build snapshot map
#   6. Build bootstrap map
#   7. Compare and build retained map
#   8. Policy classification
#   9. Verification report
#  10. Build execution plan
#  11. Execute cleanup
#  12. Policy verification

set -euo pipefail

###############################################################################
# Helper Functions
###############################################################################

pass() {
    printf "  [PASS] %s\n" "$1"
}

warn() {
    printf "  [WARN] %s\n" "$1"
}

fail() {
    printf "  [FAIL] %s\n" "$1"
    exit 1
}

derive_bootstrap_subvolume() {

    local current="$1"
    local bootstrap

    current="${current#/}"

    if [[ "$current" =~ ^(.+)/\.snapshots/([0-9]+)/snapshot$ ]]; then
        bootstrap="${BASH_REMATCH[1]}"
    else
        return 1
    fi

    [[ -n "$bootstrap" ]] || return 1
    [[ "$bootstrap" =~ ^[a-zA-Z0-9_@.+/-]+$ ]] || return 1

    case "/$bootstrap/" in
        *//*|*/./*|*/../*|*/.snapshots/*)
            return 1
            ;;
    esac

    printf '%s\n' "$bootstrap"
}

device_node_signature() {

    local object="$1"
    local allow_symlink="${2:-false}"
    local kind
    local device_number

    if [[ -L "$object" && "$allow_symlink" != true ]]; then
        return 1
    fi

    if [[ -c "$object" ]]; then
        kind="character"
    elif [[ -b "$object" ]]; then
        kind="block"
    else
        return 1
    fi

    device_number=$(stat -Lc '%t:%T' -- "$object") || return 1
    printf '%s:%s\n' "$kind" "$device_number"
}

matching_device_node() {

    local bootstrap_object="$1"
    local active_object="$2"
    local bootstrap_signature
    local active_signature
    local active_resolved

    bootstrap_signature=$(device_node_signature "$bootstrap_object") \
        || return 1

    [[ "$active_object" == /dev/* ]] || return 1

    if [[ -L "$active_object" ]]; then
        active_resolved=$(readlink -f -- "$active_object") || return 1
        [[ "$active_resolved" == /dev/* ]] || return 1
    fi

    active_signature=$(device_node_signature "$active_object" true) \
        || return 1

    [[ "$bootstrap_signature" == "$active_signature" ]]
}

###############################################################################
# Cleanup
###############################################################################

cleanup() {

    local original_status=$?
    local cleanup_failed=false

    trap - EXIT

    if [[ -n "${BOOTSTRAP_ROOT:-}" ]] &&
       mountpoint -q "$BOOTSTRAP_ROOT" 2>/dev/null; then

        if ! umount "$BOOTSTRAP_ROOT"; then
            warn "Unable to unmount temporary bootstrap root:"
            printf "         %s\n" "$BOOTSTRAP_ROOT"
            cleanup_failed=true
        fi
    fi

    if [[ -n "${BOOTSTRAP_ROOT:-}" ]] &&
       [[ -d "$BOOTSTRAP_ROOT" ]] &&
       ! mountpoint -q "$BOOTSTRAP_ROOT" 2>/dev/null; then

        if ! rmdir "$BOOTSTRAP_ROOT"; then
            warn "Unable to remove temporary mount directory:"
            printf "         %s\n" "$BOOTSTRAP_ROOT"
            cleanup_failed=true
        fi
    fi

    if (( original_status == 0 )) && [[ "$cleanup_failed" == true ]]; then
        exit 1
    fi

    exit "$original_status"
}

trap cleanup EXIT

###############################################################################
# Execution Helper Functions
###############################################################################

delete_object() {

    local OBJECT="$1"

    if [[ "$DRY_RUN" == true ]]; then
        return 0
    fi

    rm -- "$OBJECT"

}

###############################################################################
# Runtime Environment
###############################################################################

DEVICE=""
ROOT_FSTYPE=""

CURRENT_SOURCE=""
CURRENT_SUBVOL=""
CURRENT_SUBVOL_ID=""
DEFAULT_SUBVOL_ID=""

BOOTSTRAP_ROOT=""
BOOTSTRAP_SUBVOL=""
BOOTSTRAP_SUBVOL_ID=""
MOUNTED_BOOTSTRAP_SUBVOL=""
SNAPSHOT_STORE_SUBVOL=""

SUBVOLUME_LIST=()

declare -A SNAPSHOT_MAP
declare -A BOOTSTRAP_MAP
declare -A RETAINED_MAP

declare -A SUBVOLUME_PATH_MAP
declare -A SUBVOLUME_PARENT_MAP

MATCH_LIST=()
MISSING_LIST=()

KEEP_BOOT=()
KEEP_SNAPSHOTS=()
KEEP_SUBVOLUME=()

DELETE_CANDIDATE=()
RETAINED_OBJECTS=()

###############################################################################
# Execution Queues
###############################################################################
DELETE_LINKS=()
DELETE_FILES=()
DELETE_SOCKETS=()
DELETE_DEVICES=()
DELETE_DIRS=()
DELETE_OTHER=()

###############################################################################
# Execution Statistics
###############################################################################

REMOVED_LINKS=0
FAILED_LINKS=0

REMOVED_FILES=0
FAILED_FILES=0

REMOVED_SOCKETS=0
FAILED_SOCKETS=0

REMOVED_DEVICES=0
FAILED_DEVICES=0

REMOVED_DIRS=0

###############################################################################
# Execution Settings
###############################################################################

DRY_RUN=""

usage() {

    printf '\n'
    printf 'Usage:\n'
    printf '\n'
    printf '  %s --dryrun\n' "$0"
    printf '  %s --execute\n' "$0"
    printf '\n'

    exit 1
}

(( $# == 1 )) || usage

case "$1" in

    --dryrun)
        DRY_RUN=true
        ;;

    --execute)
        DRY_RUN=false
        ;;

    *)
        usage
        ;;

esac

###############################################################################
# Banner
###############################################################################

echo
echo "============================================================"
echo "cleanup-bootstrap-root.sh"
echo "Version 1.1.0"
echo "============================================================"
echo
echo "Module 1 - Environment Verification"
###############################################################################
# Root
###############################################################################

[[ $EUID -eq 0 ]] \
    && pass "Running as root." \
    || fail "This script must be run with sudo."

###############################################################################
# Filesystem
###############################################################################

ROOT_FSTYPE=$(findmnt -no FSTYPE /)

[[ "$ROOT_FSTYPE" == "btrfs" ]] \
    && pass "Root filesystem is BTRFS." \
    || fail "Root filesystem is not BTRFS."

###############################################################################
# Current Root
###############################################################################

CURRENT_SOURCE=$(findmnt -no SOURCE /)
CURRENT_SUBVOL=$(findmnt -no FSROOT /)
CURRENT_SUBVOL="${CURRENT_SUBVOL#/}"

[[ -n "$CURRENT_SUBVOL" ]] \
    || fail "Unable to determine the current root subvolume."

echo
echo "Current Root"
echo "------------"
echo "$CURRENT_SOURCE"
echo

echo "Current Subvolume"
echo "-----------------"
echo "$CURRENT_SUBVOL"
echo

#
# Derive the retired bootstrap root from the exact nested snapshot path.
# This supports @, @rootfs, @btrfs, and other root-subvolume names while
# refusing a snapshot nested beneath another snapshot.
#

BOOTSTRAP_SUBVOL=$(derive_bootstrap_subvolume "$CURRENT_SUBVOL") \
    || fail "System is NOT running from a supported nested snapshot."

SNAPSHOT_STORE_SUBVOL="${BOOTSTRAP_SUBVOL}/.snapshots"

pass "Running from a snapshot beneath '$BOOTSTRAP_SUBVOL'."

###############################################################################
# Default Subvolume
###############################################################################

echo
echo "Default Subvolume"
echo "-----------------"

DEFAULT_INFO=$(btrfs subvolume get-default /)

echo "$DEFAULT_INFO"

DEFAULT_SUBVOL_ID=$(awk '$1 == "ID" { print $2 }' <<< "$DEFAULT_INFO")
CURRENT_SUBVOL_ID=$(btrfs subvolume show / | \
    sed -n 's/^[[:space:]]*Subvolume ID:[[:space:]]*//p')

if [[ -n "$CURRENT_SUBVOL_ID" &&
      -n "$DEFAULT_SUBVOL_ID" &&
      "$CURRENT_SUBVOL_ID" == "$DEFAULT_SUBVOL_ID" ]]; then
    pass "Default subvolume matches running system."
else
    fail "Running snapshot does not match the default snapshot."
fi

###############################################################################
# Locate Device
###############################################################################

DEVICE=$(findmnt -no SOURCE / | sed 's/\[.*//')

echo
echo "Filesystem Device"
echo "-----------------"
echo "$DEVICE"

[[ -b "$DEVICE" ]] \
    && pass "Filesystem device located." \
    || fail "Unable to determine filesystem device."

###############################################################################
# Verify Derived Bootstrap Root Exists
###############################################################################

echo
echo "Checking for bootstrap root subvolume..."
echo

BOOTSTRAP_SUBVOL_ID=$(btrfs subvolume list / | awk -v expected="$BOOTSTRAP_SUBVOL" '
    $1 == "ID" && $2 ~ /^[0-9]+$/ && index($0, " path ") {
        path=$0
        sub(/^.* path /, "", path)
        if (path == expected) {
            print $2
            found++
        }
    }
    END { if (found != 1) exit 1 }
') || fail "Bootstrap root subvolume '$BOOTSTRAP_SUBVOL' not found or ambiguous."

if [[ "$BOOTSTRAP_SUBVOL_ID" =~ ^[0-9]+$ ]]; then
    pass "Bootstrap root '$BOOTSTRAP_SUBVOL' found (ID $BOOTSTRAP_SUBVOL_ID)."
else
    fail "Invalid subvolume ID for bootstrap root '$BOOTSTRAP_SUBVOL'."
fi

###############################################################################
# Verify .snapshots
###############################################################################

echo
echo "Checking for .snapshots subvolume..."
echo

if btrfs subvolume list / | awk -v expected="$SNAPSHOT_STORE_SUBVOL" '
    $1 == "ID" && index($0, " path ") {
        path=$0
        sub(/^.* path /, "", path)
        if (path == expected) found++
    }
    END { exit(found == 1 ? 0 : 1) }
'; then
    pass "$SNAPSHOT_STORE_SUBVOL found."
else
    fail "$SNAPSHOT_STORE_SUBVOL not found."
fi

###############################################################################
# Execution Mode
###############################################################################

echo
echo "Execution Mode"
echo "--------------"

if [[ "$DRY_RUN" == true ]]; then

    echo "Mode : Dry Run"
    pass "Filesystem modifications are disabled."
    echo "       Analysis, planning, and validation will be performed."

else

    echo "Mode : Execute"
    warn "Filesystem modifications are ENABLED."
    echo "       The retired bootstrap ($BOOTSTRAP_SUBVOL) subvolume will be modified."

fi

echo

###############################################################################
# Summary
###############################################################################

echo
echo "============================================================"
pass "Environment verification complete."
echo "Proceed to Module 2."
echo "============================================================"
echo

###############################################################################
# Module 2 - Mount Bootstrap Root
###############################################################################

echo
echo "============================================================"
echo "Module 2 - Mount Bootstrap Root"
echo "============================================================"

#
# Create a temporary mount point
#

BOOTSTRAP_ROOT=$(mktemp -d /run/bootstrap-root.XXXXXX)

pass "Created temporary mount point:"
echo "       $BOOTSTRAP_ROOT"

#
# Mount the retired bootstrap subvolume read-only
#

echo
echo "Mounting retired $BOOTSTRAP_SUBVOL subvolume..."

mount -t btrfs -o "ro,subvolid=$BOOTSTRAP_SUBVOL_ID" \
    "$DEVICE" "$BOOTSTRAP_ROOT"

#
# Verify mount
#

MOUNTED_BOOTSTRAP_SUBVOL=$(findmnt -no FSROOT "$BOOTSTRAP_ROOT")
MOUNTED_BOOTSTRAP_SUBVOL="${MOUNTED_BOOTSTRAP_SUBVOL#/}"

echo
echo "Mounted Filesystem"
echo "------------------"
echo "Mount Point : $BOOTSTRAP_ROOT"
echo "Device      : $DEVICE"
echo "Subvolume   : $MOUNTED_BOOTSTRAP_SUBVOL"
echo "Access      : Read-only"

if [[ "$MOUNTED_BOOTSTRAP_SUBVOL" != "$BOOTSTRAP_SUBVOL" ]]; then
    fail "Expected subvolume '$BOOTSTRAP_SUBVOL' but mounted '$MOUNTED_BOOTSTRAP_SUBVOL'."
fi

pass "Bootstrap root mounted successfully."

#
# Bootstrap Root Summary
#

echo
echo "Bootstrap Root Summary"
echo "----------------------"

echo "Mount Point : $BOOTSTRAP_ROOT"
echo "Device      : $DEVICE"
echo "Subvolume   : $BOOTSTRAP_SUBVOL"

echo
echo "Top-Level Objects"
echo "-----------------"

find "$BOOTSTRAP_ROOT" \
    -mindepth 1 \
    -maxdepth 1 \
    -printf "%f\n" | sort

echo

###############################################################################
# Mount Verification
###############################################################################

echo
pass "Bootstrap root mounted and ready for analysis."

echo
pass "Module 2 complete."

###############################################################################
# Module 3 - Discover Btrfs Subvolumes
###############################################################################

echo
echo "============================================================"
echo "Module 3 - Discover Btrfs Subvolumes"
echo "============================================================"

#
# Discover every Btrfs subvolume on the filesystem.
#

mapfile -t SUBVOLUME_LIST < <(
    btrfs subvolume list / | awk '
        $1 == "ID" && index($0, " path ") {
            sub(/^.* path /, "")
            print
        }
    ' | sort
)

#
# Verify discovery.
#

if [[ ${#SUBVOLUME_LIST[@]} -eq 0 ]]; then
    fail "No Btrfs subvolumes were discovered."
fi

###############################################################################
# Build subvolume and parent-directory lookup tables
###############################################################################

for subvol in "${SUBVOLUME_LIST[@]}"; do

    #
    # Only subvolumes nested beneath the derived bootstrap root exist inside
    # the retired bootstrap-root namespace.
    #
    # Sibling subvolumes outside that exact namespace require no mapping.
    #

    [[ "$subvol" == "$BOOTSTRAP_SUBVOL/"* ]] || continue

    #
    # Convert the Btrfs subvolume path into a path
    # relative to the mounted bootstrap root.
    #

    path="${subvol#"$BOOTSTRAP_SUBVOL/"}"

    [[ -n "$path" ]] || continue

    #
    # Record the actual subvolume path.
    #
    # This path and everything beneath it must remain.
    #

    SUBVOLUME_PATH_MAP["$path"]=1

    #
    # Record only the parent directory entries leading
    # to the subvolume.
    #
    # Their unrelated contents are not protected.
    #

    parent="$path"

    while [[ "$parent" == */* ]]; do

        parent="${parent%/*}"

        [[ -n "$parent" ]] || break

        SUBVOLUME_PARENT_MAP["$parent"]=1

    done

done

echo
echo "Protected Subvolume Paths : ${#SUBVOLUME_PATH_MAP[@]}"

echo
echo "Protected Parent Paths    : ${#SUBVOLUME_PARENT_MAP[@]}"

echo
echo "Indexed Subvolumes : ${#SUBVOLUME_LIST[@]}"

#
# Display summary.
#

echo
echo "Discovered Subvolumes"
echo "---------------------"

for subvol in "${SUBVOLUME_LIST[@]}"; do
    printf "  %s\n" "$subvol"
done

echo
echo "Total Subvolumes : ${#SUBVOLUME_LIST[@]}"

#
# Sanity checks.
#

bootstrap_found=false
snapshot_store_found=false

for subvol in "${SUBVOLUME_LIST[@]}"; do
    [[ "$subvol" == "$BOOTSTRAP_SUBVOL" ]] && bootstrap_found=true
    [[ "$subvol" == "$SNAPSHOT_STORE_SUBVOL" ]] && snapshot_store_found=true
done

if [[ "$bootstrap_found" == true ]]; then
    pass "$BOOTSTRAP_SUBVOL subvolume found."
else
    fail "$BOOTSTRAP_SUBVOL subvolume missing."
fi

if [[ "$snapshot_store_found" == true ]]; then
    pass "$SNAPSHOT_STORE_SUBVOL subvolume found."
else
    fail "$SNAPSHOT_STORE_SUBVOL subvolume missing."
fi

echo
pass "Module 3 complete."

###############################################################################
# Module 4 - Discover Active Snapshot Tree
###############################################################################

echo
echo "============================================================"
echo "Module 4 - Discover Active Snapshot Tree"
echo "============================================================"

#
# Discover every object in the currently running snapshot.
#

mapfile -t SNAPSHOT_LIST < <(
    cd / &&
    find . -xdev \
        | sed 's#^\./##' \
        | grep -v '^\.$' \
        | sort
)

#
# Verify discovery.
#

if [[ ${#SNAPSHOT_LIST[@]} -eq 0 ]]; then
    fail "Active snapshot appears to be empty."
fi

#
# Summary
#

echo
echo "Snapshot Statistics"
echo "-------------------"

echo "Objects Found : ${#SNAPSHOT_LIST[@]}"

echo
echo "Sample Objects"
echo "--------------"

for ((i=0; i<20 && i<${#SNAPSHOT_LIST[@]}; i++)); do
    printf "  %s\n" "${SNAPSHOT_LIST[$i]}"
done

echo
pass "Module 4 complete."

###############################################################################
# Module 5 - Build Snapshot Lookup Table
###############################################################################

echo
echo "============================================================"
echo "Module 5 - Build Snapshot Lookup Table"
echo "============================================================"

#
# Build an associative array for O(1) lookups.
#

for path in "${SNAPSHOT_LIST[@]}"; do
    SNAPSHOT_MAP["$path"]=1
done

#
# Verify.
#

if [[ ${#SNAPSHOT_MAP[@]} -eq 0 ]]; then
    fail "Snapshot lookup table is empty."
fi

echo
echo "Snapshot Lookup Table"
echo "---------------------"

echo "Indexed Objects : ${#SNAPSHOT_MAP[@]}"

echo
echo "Lookup Tests"
echo "------------"

for path in \
    etc \
    usr \
    var \
    boot \
    boot/grub \
    var/log \
    does/not/exist
do

    if [[ -n "${SNAPSHOT_MAP[$path]:-}" ]]; then
        printf "  %-20s YES\n" "$path"
    else
        printf "  %-20s NO\n" "$path"
    fi

done

echo
pass "Module 5 complete."

###############################################################################
# Module 6 - Build Bootstrap Lookup Table
###############################################################################

echo
echo "============================================================"
echo "Module 6 - Build Bootstrap Lookup Table"
echo "============================================================"

#
# Build a lookup table from the retired bootstrap-root subvolume.
#

while IFS= read -r path; do

    #
    # Remove the leading mount point.
    #

    relative="${path#${BOOTSTRAP_ROOT}/}"

    #
    # Skip the root itself.
    #

    [[ "$relative" == "$BOOTSTRAP_ROOT" ]] && continue
    [[ -z "$relative" ]] && continue

    BOOTSTRAP_MAP["$relative"]=1

done < <(
    find "$BOOTSTRAP_ROOT" -xdev
)

#
# Verify.
#

if [[ ${#BOOTSTRAP_MAP[@]} -eq 0 ]]; then
    fail "Bootstrap lookup table is empty."
fi

echo
echo "Bootstrap Lookup Table"
echo "----------------------"

echo "Indexed Objects : ${#BOOTSTRAP_MAP[@]}"

echo
echo "Lookup Tests"
echo "------------"

for path in \
    etc \
    usr \
    var \
    boot \
    boot/grub \
    var/log \
    does/not/exist
do

    if [[ -n "${BOOTSTRAP_MAP[$path]:-}" ]]; then
        printf "  %-20s YES\n" "$path"
    else
        printf "  %-20s NO\n" "$path"
    fi

done

echo
pass "Module 6 complete."

###############################################################################
# Module 7 - Compare Bootstrap to Active Snapshot
###############################################################################

echo
echo "============================================================"
echo "Module 7 - Compare Bootstrap to Active Snapshot"
echo "============================================================"

MATCH_LIST=()
MISSING_LIST=()

#
# Compare every bootstrap object against the active snapshot.
#

for path in "${!BOOTSTRAP_MAP[@]}"; do

    if [[ -n "${SNAPSHOT_MAP[$path]:-}" ]]; then
        MATCH_LIST+=("$path")
    else

        #
        # Object is missing from the active snapshot.
        # If its immediate parent directory still exists
        # in the active snapshot, treat it as obsolete.
        #

        PARENT="${path%/*}"

        #
        # Top-level objects have no parent directory.
        #

        if [[ "$PARENT" == "$path" ]]; then
            MISSING_LIST+=("$path")
            continue
        fi

        #
        # Parent directory still exists in the snapshot.
        #

        if [[ -n "${SNAPSHOT_MAP[$PARENT]:-}" ]]; then
            MATCH_LIST+=("$path")
        else
            MISSING_LIST+=("$path")
        fi

    fi

done

###############################################################################
# Build retained object lookup table
###############################################################################

RETAINED_MAP=()

for path in "${MISSING_LIST[@]}"; do
    RETAINED_MAP["$path"]=1
done

echo
echo "Comparison Results"
echo "------------------"

echo "Bootstrap Objects : ${#BOOTSTRAP_MAP[@]}"
echo "Snapshot Objects  : ${#SNAPSHOT_MAP[@]}"
echo "Matched Objects   : ${#MATCH_LIST[@]}"
echo "Retained Objects  : ${#MISSING_LIST[@]}"

echo

#
# Display the first few retained objects.
#

if (( ${#MISSING_LIST[@]} > 0 )); then

    echo "Retained Objects"
    echo "----------------"

    LIMIT=20
    (( ${#MISSING_LIST[@]} < LIMIT )) && LIMIT=${#MISSING_LIST[@]}

    for ((i=0; i<LIMIT; i++)); do

        path="${MISSING_LIST[$i]}"
        if [[ -L "${BOOTSTRAP_ROOT}/${path}" ]]; then
            TYPE="LINK"
        elif [[ -d "${BOOTSTRAP_ROOT}/${path}" ]]; then
            TYPE="DIR"
        elif [[ -f "${BOOTSTRAP_ROOT}/${path}" ]]; then
            TYPE="FILE"
        else
            TYPE="OTHER"
        fi

        printf "  %-5s %s\n" "$TYPE" "$path"

    done

else

    pass "No retained objects were discovered."

fi

echo
pass "Module 7 complete."

###############################################################################
# Module 8 - Policy Classification
###############################################################################

echo
echo "============================================================"
echo "Module 8 - Policy Classification"
echo "============================================================"

KEEP_BOOT=()
KEEP_SNAPSHOTS=()
KEEP_SUBVOLUME=()

DELETE_CANDIDATE=()
RETAINED_OBJECTS=()

#
# Classify every object in the retired bootstrap root.
#
TOTAL_OBJECTS=${#BOOTSTRAP_MAP[@]}
CLASSIFIED=0
for path in "${!BOOTSTRAP_MAP[@]}"; do
((++CLASSIFIED))

    if (( CLASSIFIED % 1000 == 0 || CLASSIFIED == TOTAL_OBJECTS )); then
        printf "\rClassifying Objects: %7d / %7d" \
            "$CLASSIFIED" \
            "$TOTAL_OBJECTS"
    fi

    #
    # Rule 1: Never touch /boot.
    #
    if [[ "$path" == boot || "$path" == boot/* ]]; then
        KEEP_BOOT+=("$path")
        continue
    fi

    #
    # Rule 2: Never touch /.snapshots.
    #
    if [[ "$path" == ".snapshots" || "$path" == .snapshots/* ]]; then
        KEEP_SNAPSHOTS+=("$path")
        continue
    fi

    ###############################################################################
    # Rule 3:
    # Protect actual Btrfs subvolumes, their contents,
    # and the parent directory entries leading to them.
    ###############################################################################

    #
    # Protect the actual subvolume path.
    #

    if [[ -n "${SUBVOLUME_PATH_MAP[$path]:-}" ]]; then
        KEEP_SUBVOLUME+=("$path")
        continue
    fi

    #
    # Protect only the parent directory entry.
    #
    # Unrelated objects beneath this directory continue
    # through the remaining policy rules.
    #

    if [[ -n "${SUBVOLUME_PARENT_MAP[$path]:-}" ]]; then
        KEEP_SUBVOLUME+=("$path")
        continue
    fi

    #
    # Protect everything inside an actual subvolume.
    #

    for protected in "${!SUBVOLUME_PATH_MAP[@]}"; do

        if [[ "$path" == "$protected/"* ]]; then
            KEEP_SUBVOLUME+=("$path")
            continue 2
        fi

    done

    #
    # Rule 4:
    # Retain only objects that Module 7 determined
    # belong to abandoned directory trees.
    #

    if [[ -n "${RETAINED_MAP[$path]:-}" ]]; then
        RETAINED_OBJECTS+=("$path")
        continue
    fi

    #
    # Rule 5: Safe delete candidate.
    #
    DELETE_CANDIDATE+=("$path")

done

echo
echo
echo "Policy Summary"
echo "--------------"

printf "  %-22s %8d\n" "Protected Boot"        "${#KEEP_BOOT[@]}"
printf "  %-22s %8d\n" "Protected Snapshots"   "${#KEEP_SNAPSHOTS[@]}"
printf "  %-22s %8d\n" "Protected Subvolume Objects"  "${#KEEP_SUBVOLUME[@]}"
printf "  %-22s %8d\n" "Retained Objects"      "${#RETAINED_OBJECTS[@]}"
printf "  %-22s %8d\n" "Delete Candidates"     "${#DELETE_CANDIDATE[@]}"

echo
pass "Module 8 complete."

###############################################################################
# Module 9 - Cleanup Verification Report
###############################################################################

echo
echo "============================================================"
echo "Module 9 - Cleanup Verification Report"
echo "============================================================"

show_sample() {

    local TITLE="$1"
    shift

    local -n LIST=$1

    echo
    echo "$TITLE"
    printf '%*s\n' "${#TITLE}" '' | tr ' ' '-'

    echo "Count : ${#LIST[@]}"

    if (( ${#LIST[@]} == 0 )); then
        echo "  (none)"
        return
    fi

    LIMIT=10
    (( ${#LIST[@]} < LIMIT )) && LIMIT=${#LIST[@]}

    echo "Sample:"

    for ((i=0; i<LIMIT; i++)); do
        printf "  %s\n" "${LIST[$i]}"
    done

    if (( ${#LIST[@]} > LIMIT )); then
        echo "  ..."
    fi
}

show_sample "Protected Boot Objects" KEEP_BOOT
show_sample "Protected Snapshot Objects" KEEP_SNAPSHOTS
show_sample "Protected Subvolume Objects" KEEP_SUBVOLUME
show_sample "Retained Objects" RETAINED_OBJECTS
show_sample "Delete Candidates" DELETE_CANDIDATE

echo
echo "============================================================"
echo "Summary"
echo "============================================================"

printf "%-24s %8d\n" "Protected Boot"        "${#KEEP_BOOT[@]}"
printf "%-24s %8d\n" "Protected Snapshots"   "${#KEEP_SNAPSHOTS[@]}"
printf "%-24s %8d\n" "Protected Subvolume Objects"  "${#KEEP_SUBVOLUME[@]}"
printf "%-24s %8d\n" "Retained Objects"      "${#RETAINED_OBJECTS[@]}"
printf "%-24s %8d\n" "Delete Candidates"     "${#DELETE_CANDIDATE[@]}"

echo

if (( ${#RETAINED_OBJECTS[@]} > 0 )); then

    echo
    echo "Retained Objects"
    echo "----------------"
    echo "The retired bootstrap root contains objects"
    echo "that could not be proven safe to remove."

    echo
    echo "These objects have been retained and will"
    echo "not be modified."

    echo
    echo "Cleanup may proceed safely."

else

    pass "All bootstrap objects were classified."

fi

echo
pass "Module 9 complete."

###############################################################################
# Module 10 - Build Execution Plan
###############################################################################

echo
echo "============================================================"
echo "Module 10 - Build Execution Plan"
echo "============================================================"

DELETE_LINKS=()
DELETE_FILES=()
DELETE_SOCKETS=()
DELETE_DEVICES=()
DELETE_DIRS=()
DELETE_OTHER=()

for path in "${DELETE_CANDIDATE[@]}"; do

    FULLPATH="${BOOTSTRAP_ROOT}/${path}"

    if [[ -L "$FULLPATH" ]]; then
        DELETE_LINKS+=("$path")

    elif [[ -f "$FULLPATH" ]]; then
        DELETE_FILES+=("$path")

    elif [[ -S "$FULLPATH" ]]; then
        DELETE_SOCKETS+=("$path")

    elif [[ -c "$FULLPATH" || -b "$FULLPATH" ]]; then
        ACTIVEPATH="/${path}"

        if [[ "$path" == dev/* ]] && \
           matching_device_node "$FULLPATH" "$ACTIVEPATH"; then
            DELETE_DEVICES+=("$path")
        else
            DELETE_OTHER+=("$path")
        fi

    elif [[ -d "$FULLPATH" ]]; then
        DELETE_DIRS+=("$path")

    else
        DELETE_OTHER+=("$path")
    fi

done

###############################################################################
# Sort directories deepest first
###############################################################################

if (( ${#DELETE_DIRS[@]} > 0 )); then
    mapfile -t DELETE_DIRS < <(
        printf '%s\n' "${DELETE_DIRS[@]}" |
        awk -F/ '{print NF "|" $0}' |
        sort -rn |
        cut -d'|' -f2-
    )
fi

echo
echo "Execution Queues"
echo "----------------"

printf "  %-18s %8d\n" "Symbolic Links" "${#DELETE_LINKS[@]}"
printf "  %-18s %8d\n" "Regular Files"  "${#DELETE_FILES[@]}"
printf "  %-18s %8d\n" "Sockets"        "${#DELETE_SOCKETS[@]}"
printf "  %-18s %8d\n" "Device Nodes"   "${#DELETE_DEVICES[@]}"
printf "  %-18s %8d\n" "Directories"    "${#DELETE_DIRS[@]}"
printf "  %-18s %8d\n" "Other"          "${#DELETE_OTHER[@]}"

###############################################################################
# Verify execution queues
###############################################################################

TOTAL_QUEUE_COUNT=$(( \
    ${#DELETE_LINKS[@]} + \
    ${#DELETE_FILES[@]} + \
    ${#DELETE_SOCKETS[@]} + \
    ${#DELETE_DEVICES[@]} + \
    ${#DELETE_DIRS[@]} + \
    ${#DELETE_OTHER[@]} ))

printf "  %-18s %8d\n" "Total Queued" "$TOTAL_QUEUE_COUNT"

echo

if (( TOTAL_QUEUE_COUNT != ${#DELETE_CANDIDATE[@]} )); then
    fail "Execution queue count mismatch."
fi

pass "Execution queues verified."

echo
echo "Execution Order"
echo "---------------"
echo "  1. Remove symbolic links"
echo "  2. Remove regular files"
echo "  3. Remove sockets"
echo "  4. Remove verified device nodes"
echo "  5. Remove empty directories"
echo "  6. Final verification"

echo

if (( ${#DELETE_OTHER[@]} > 0 )); then
    warn "Unexpected object types detected."
    echo
    echo "Unexpected Objects"
    echo "------------------"

    for item in "${DELETE_OTHER[@]}"; do
        printf "  %s\n" "$item"
    done

    fail "Execution queues are not safe."
fi

echo
pass "Execution plan complete."

###############################################################################
# Module 11 - Execute Cleanup
###############################################################################

echo
echo "============================================================"
echo "Module 11 - Execute Cleanup"
echo "============================================================"

echo
echo "Execution Environment"
echo "---------------------"
echo

if [[ "$DRY_RUN" == true ]]; then

    #
    # Dry-run mode does not require a writable mount.
    #

    if findmnt -no OPTIONS "$BOOTSTRAP_ROOT" | grep -qw ro; then
        pass "Bootstrap root remains mounted read-only."
    else
        fail "Bootstrap root is not read-only."
    fi

    echo
    pass "Execution Mode: Dry Run"
    echo "Execution queues will be processed."
    echo "No filesystem changes will be made."

else

    #
    # Execution mode requires a writable mount.
    #

    echo "Unmounting read-only bootstrap root..."

    if ! umount "$BOOTSTRAP_ROOT"; then
        fail "Unable to unmount bootstrap root."
    fi

    echo "Mounting bootstrap root read-write..."

    if ! mount \
        -t btrfs \
        -o "rw,subvolid=$BOOTSTRAP_SUBVOL_ID" \
        "$DEVICE" \
        "$BOOTSTRAP_ROOT"
    then
        fail "Unable to mount bootstrap root read-write."
    fi

    echo
    echo "Execution Mount"
    echo "---------------"
    echo "Mount Point : $BOOTSTRAP_ROOT"
    echo "Device      : $DEVICE"
    echo "Subvolume   : $BOOTSTRAP_SUBVOL"
    echo "Access      : Read-write"

    MOUNTED_BOOTSTRAP_SUBVOL=$(findmnt -no FSROOT "$BOOTSTRAP_ROOT")
    MOUNTED_BOOTSTRAP_SUBVOL="${MOUNTED_BOOTSTRAP_SUBVOL#/}"

    [[ "$MOUNTED_BOOTSTRAP_SUBVOL" == "$BOOTSTRAP_SUBVOL" ]] \
        || fail "Read-write mount resolved to '$MOUNTED_BOOTSTRAP_SUBVOL' instead of '$BOOTSTRAP_SUBVOL'."

    if findmnt -no OPTIONS "$BOOTSTRAP_ROOT" | grep -qw rw; then
        pass "Bootstrap root mounted read-write."
    else
        fail "Bootstrap root is not writable."
    fi

    echo
    pass "Execution Mode: Execute"
    echo "Delete candidates will now be removed"
    echo "from the retired bootstrap ($BOOTSTRAP_SUBVOL) subvolume."

fi

#
# Recheck every device node immediately before cleanup begins. A changed or
# missing active counterpart must stop execution before any object is removed.
#

for path in "${DELETE_DEVICES[@]}"; do
    FULLPATH="${BOOTSTRAP_ROOT}/${path}"
    ACTIVEPATH="/${path}"

    matching_device_node "$FULLPATH" "$ACTIVEPATH" \
        || fail "Device node no longer matches the active system: $path"
done

echo "Phase 1 - Remove Symbolic Links"
echo "-------------------------------"

COUNT=0

for path in "${DELETE_LINKS[@]}"; do

    ((++COUNT))

    printf "\rRemoving links: %6d / %6d" \
        "$COUNT" "${#DELETE_LINKS[@]}"

    FULLPATH="${BOOTSTRAP_ROOT}/${path}"

    if delete_object "$FULLPATH"; then
        ((++REMOVED_LINKS))
    else
        ((++FAILED_LINKS))
        warn "Unable to remove symbolic link: $path"
    fi

done

echo
echo
echo "Phase 1 Summary"
echo "---------------"

printf "  %-20s %8d\n" "Links Removed" "$REMOVED_LINKS"
printf "  %-20s %8d\n" "Links Failed"  "$FAILED_LINKS"

if (( FAILED_LINKS > 0 )); then
    fail "One or more symbolic links could not be removed."
fi

echo
pass "Phase 1 complete."

###############################################################################
# Phase 2 - Remove Regular Files
###############################################################################

echo
echo "Phase 2 - Remove Regular Files"
echo "------------------------------"

COUNT=0

for path in "${DELETE_FILES[@]}"; do

    ((++COUNT))

    printf "\rRemoving files: %6d / %6d" \
        "$COUNT" "${#DELETE_FILES[@]}"

    FULLPATH="${BOOTSTRAP_ROOT}/${path}"

    if delete_object "$FULLPATH"; then
        ((++REMOVED_FILES))
    else
        ((++FAILED_FILES))
        warn "Unable to remove file: $path"
    fi

done

echo
echo

echo "Phase 2 Summary"
echo "---------------"

printf "  %-20s %8d\n" "Files Removed" "$REMOVED_FILES"
printf "  %-20s %8d\n" "Files Failed"  "$FAILED_FILES"

if (( FAILED_FILES > 0 )); then
    fail "One or more regular files could not be removed."
fi

echo
pass "Phase 2 complete."

###############################################################################
# Phase 3 - Remove Sockets
###############################################################################

echo
echo "Phase 3 - Remove Sockets"
echo "------------------------"

COUNT=0

for path in "${DELETE_SOCKETS[@]}"; do

    ((++COUNT))

    printf "\rRemoving sockets: %6d / %6d" \
        "$COUNT" "${#DELETE_SOCKETS[@]}"

    FULLPATH="${BOOTSTRAP_ROOT}/${path}"

    if delete_object "$FULLPATH"; then
        ((++REMOVED_SOCKETS))
    else
        ((++FAILED_SOCKETS))
        warn "Unable to remove socket: $path"
    fi

done

echo
echo
echo "Phase 3 Summary"
echo "---------------"

printf "  %-20s %8d\n" "Sockets Removed" "$REMOVED_SOCKETS"
printf "  %-20s %8d\n" "Sockets Failed"  "$FAILED_SOCKETS"

if (( FAILED_SOCKETS > 0 )); then
    fail "One or more sockets could not be removed."
fi

echo
pass "Phase 3 complete."

###############################################################################
# Phase 4 - Remove Verified Device Nodes
###############################################################################

echo
echo "Phase 4 - Remove Verified Device Nodes"
echo "--------------------------------------"

COUNT=0

for path in "${DELETE_DEVICES[@]}"; do

    ((++COUNT))

    printf "\rRemoving device nodes: %6d / %6d" \
        "$COUNT" "${#DELETE_DEVICES[@]}"

    FULLPATH="${BOOTSTRAP_ROOT}/${path}"

    if delete_object "$FULLPATH"; then
        ((++REMOVED_DEVICES))
    else
        ((++FAILED_DEVICES))
        warn "Unable to remove device node: $path"
    fi

done

echo
echo
echo "Phase 4 Summary"
echo "---------------"

printf "  %-20s %8d\n" "Device Nodes Removed" "$REMOVED_DEVICES"
printf "  %-20s %8d\n" "Device Nodes Failed"  "$FAILED_DEVICES"

if (( FAILED_DEVICES > 0 )); then
    fail "One or more device nodes could not be removed."
fi

echo
pass "Phase 4 complete."

###############################################################################
# Phase 5 - Remove Empty Directories
###############################################################################

echo
echo "Phase 5 - Remove Empty Directories"
echo "----------------------------------"

COUNT=0

for path in "${DELETE_DIRS[@]}"; do

    ((++COUNT))

    printf "\rRemoving directories: %6d / %6d" \
        "$COUNT" "${#DELETE_DIRS[@]}"

    FULLPATH="${BOOTSTRAP_ROOT}/${path}"

    if [[ "$DRY_RUN" == true ]]; then
        ((++REMOVED_DIRS))
    else
        if rmdir "$FULLPATH" 2>/dev/null; then
            ((++REMOVED_DIRS))
        fi
    fi

done

echo
echo

echo "Phase 5 Summary"
echo "---------------"

if [[ "$DRY_RUN" == true ]]; then
    printf "  %-20s %8d\n" "Directories Planned" "$REMOVED_DIRS"
else
    printf "  %-20s %8d\n" "Directories Removed" "$REMOVED_DIRS"
fi

pass "Phase 5 complete."

echo
echo

if [[ "$DRY_RUN" == true ]]; then
    pass "Dry run complete."
else
    pass "Cleanup execution complete."
fi

###############################################################################
# Module 12 - Policy Verification
###############################################################################

echo
echo "============================================================"
echo "Module 12 - Final Validation"
echo "============================================================"

###############################################################################
# Return bootstrap root to read-only
###############################################################################

echo
echo "Preparing Validation Environment"
echo "--------------------------------"

echo "Unmounting bootstrap root..."
umount "$BOOTSTRAP_ROOT" \
    || fail "Unable to unmount bootstrap root."

echo "Mounting bootstrap root read-only..."

mount \
    -t btrfs \
    -o "ro,subvolid=$BOOTSTRAP_SUBVOL_ID" \
    "$DEVICE" \
    "$BOOTSTRAP_ROOT"

echo
echo "Validation Mount"
echo "----------------"
echo "Mount Point : $BOOTSTRAP_ROOT"
echo "Device      : $DEVICE"
echo "Subvolume   : $BOOTSTRAP_SUBVOL"
echo "Access      : Read-only"

MOUNTED_BOOTSTRAP_SUBVOL=$(findmnt -no FSROOT "$BOOTSTRAP_ROOT")
MOUNTED_BOOTSTRAP_SUBVOL="${MOUNTED_BOOTSTRAP_SUBVOL#/}"

[[ "$MOUNTED_BOOTSTRAP_SUBVOL" == "$BOOTSTRAP_SUBVOL" ]] \
    || fail "Validation mount resolved to '$MOUNTED_BOOTSTRAP_SUBVOL' instead of '$BOOTSTRAP_SUBVOL'."

if findmnt -no OPTIONS "$BOOTSTRAP_ROOT" | grep -qw ro; then
    pass "Bootstrap root mounted read-only."
else
    fail "Bootstrap root is not read-only."
fi

###############################################################################
# Discover Remaining Objects
###############################################################################

declare -A FINAL_MAP

while IFS= read -r path; do

    relative="${path#${BOOTSTRAP_ROOT}/}"

    [[ -z "$relative" ]] && continue
    [[ "$relative" == "$BOOTSTRAP_ROOT" ]] && continue

    FINAL_MAP["$relative"]=1

done < <(
    find "$BOOTSTRAP_ROOT" -xdev
)

echo
echo "Remaining Objects"
echo "-----------------"

echo "Objects Remaining : ${#FINAL_MAP[@]}"

###############################################################################
# Verify Policy
###############################################################################

DELETE_REMAINING=0
PROTECTED_MISSING=0
RETAINED_MISSING=0

#
# Delete candidates should no longer exist.
#
# Directories are ignored here because they may
# legitimately remain as parents of retained objects.
#

for path in "${DELETE_CANDIDATE[@]}"; do

    FULLPATH="${BOOTSTRAP_ROOT}/${path}"

    #
    # Ignore directories.
    #

    if [[ -d "$FULLPATH" ]]; then
        continue
    fi

    #
    # Files and links must be gone.
    #

    if [[ -n "${FINAL_MAP[$path]:-}" ]]; then
        ((++DELETE_REMAINING))
        echo "Delete candidate still present:"
        echo "  $path"
    fi

done

#
# Protected objects must still exist.
#

for path in \
    "${KEEP_BOOT[@]}" \
    "${KEEP_SNAPSHOTS[@]}" \
    "${KEEP_SUBVOLUME[@]}"
do

    if [[ -z "${FINAL_MAP[$path]:-}" ]]; then
        ((++PROTECTED_MISSING))
        echo "Protected object missing:"
        echo "  $path"
    fi

done

#
# Retained objects must still exist.
#

for path in "${RETAINED_OBJECTS[@]}"; do

    if [[ -z "${FINAL_MAP[$path]:-}" ]]; then
        ((++RETAINED_MISSING))
        echo "Retained object missing:"
        echo "  $path"
    fi

done

###############################################################################
# Dry Run Validation
###############################################################################

if [[ "$DRY_RUN" == true ]]; then

    echo
    pass "Dry run verification complete."

    echo
    echo "Validation Summary"
    echo "------------------"
    printf "  %-30s %8d\n" "Delete Candidates Planned" "${#DELETE_CANDIDATE[@]}"
    printf "  %-30s %8d\n" "Protected Objects"          "$(( ${#KEEP_BOOT[@]} + ${#KEEP_SNAPSHOTS[@]} + ${#KEEP_SUBVOLUME[@]} ))"
    printf "  %-30s %8d\n" "Retained Objects"          "${#RETAINED_OBJECTS[@]}"

    echo
    echo "No filesystem changes were made."
    pass "Dry run completed successfully."

    exit 0

fi

echo
echo "Validation Summary"
echo "------------------"

printf "  %-30s %8d\n" "Delete Candidates Remaining" "$DELETE_REMAINING"
printf "  %-30s %8d\n" "Protected Objects Missing"   "$PROTECTED_MISSING"
printf "  %-30s %8d\n" "Retained Objects Missing"   "$RETAINED_MISSING"

echo

if (( DELETE_REMAINING == 0 \
   && PROTECTED_MISSING == 0 \
   && RETAINED_MISSING == 0 )); then

    pass "Policy verification successful."

    echo
    echo "Cleanup policy verified."
    echo "The retired bootstrap root now contains only"
    echo "protected and intentionally retained objects."

    echo
    pass "cleanup-bootstrap completed successfully."

else

    fail "Policy verification failed."

fi