function Remove-OutdatedNewHotfixPackages{
    <#
    .SYNOPSIS
        Removes hotfix packages supplied by the user if they are outdated given the existing or new orb version.

    .PARAMETER DependencyReleaseValue
        The value of the orb release being classified. Only populated for Orb installs.

    .PARAMETER PackageMetadata
        Packages object to populate.
    #>

    [CmdletBinding()]
    [OutputType([PSObject])]
    Param(
        [Parameter(Mandatory = $false)]
        [string]$DependencyReleaseValue = "",

        [Parameter(Mandatory = $true)]
        [PSObject] $PackageMetadata
    )
    $loglead = Get-LogleadName

    if ($PackageMetadata.ForceReinstallPackages) {
        if (Test-StringIsNullOrWhiteSpace -Value $DependencyReleaseValue) {
            Write-Host "##teamcity[message text='DependencyReleaseValue is NullOrWhiteSpace on an ORB deploy!' status='WARNING']"
        }

        # matches
        # release dot 4digits dot at-least-one-digit dot at-least-one-digit dot at-least-one-digit dot zip
        # parens around (\d{4}\.\d+\.\d+\.\d+) "captures" that string that looks like YYYY.N.N.N or 2022.3.0.9
        # which is our Release Version Number, or OrbVersion, matching what Get-OrbVersion would return
        $regexOrbReleaseFile = "release\.(\d{4}\.\d+\.\d+\.\d+)\.zip"
        if ($DependencyReleaseValue -match $regexOrbReleaseFile) {
            $releaseVersion = $Matches[1]
            Write-Host "$loglead : Valid release version found in dependency parameters"
            $PackageMetadata.InstalledOrbVersion = $releaseVersion
            $releaseVersionIsCanonical = $true
        } else {
            Write-Host "##teamcity[message text='DependencyReleaseValue does not match release name format. Fallback to Get-OrbVersion from remote host' status='WARNING']"
        }
    } else {
        Write-Host "$loglead : This is a package deploy, so we're using Get-OrbVersion from a remote host to determine what to do with hotfixes."
    }

    $firstWebORBServer = $PackageMetadata.WebServers | Select-Object -First 1
    $firstAppORBServer = $PackageMetadata.AppServers | Select-Object -First 1
    $firstMicORBServer = $PackageMetadata.MicServers | Select-Object -First 1

    $orbServersToCheck = @($firstWebORBServer, $firstAppORBServer, $firstMicORBServer)
    foreach ($server in $orbServersToCheck) {
        if ( -NOT (Test-StringIsNullOrWhiteSpace -Value $server)) {
            if (-NOT $releaseVersionIsCanonical) {
                $orbVersion = Get-OrbVersion -ComputerName $server
                $PackageMetadata.InstalledOrbVersion = $orbVersion
                Write-Host "$logLead : Found orb version $orbVersion."
                # Found an orb version, don't do this more than necessary.
                break;
            }
        }
    }

    $versionIsLessThanTarget = -1
    $versionIsSameAsTarget = 0
    $versionIsGreaterThanTarget = 1

    $webHotfixPackagesToRemove = @()
    $appHotfixPackagesToRemove = @()

    # Check incoming Web packages.
    foreach($package in $PackageMetadata.WebPackagesToInstall)
    {
        if($package.IsHotfix){
            $compareSemverResult = Compare-SemVer -Version1 $package.HotfixFixedInOrbVersion -Version2 $PackageMetadata.InstalledOrbVersion

            switch ($compareSemverResult) {
                $versionIsLessThanTarget { $webHotfixPackagesToRemove += $package.Name }
                $versionIsSameAsTarget { $webHotfixPackagesToRemove += $package.Name }
                $versionIsGreaterThanTarget { <# Do nothing, this will get reinstalled if it should be reinstalled at this point #> }
            }
        }
    }

    # This is a list of Package NAMES, not packages.
    foreach($package in $webHotfixPackagesToRemove){
        Write-Host "##teamcity[message text='Found a hotfix in the supplied WEB install list which is not valid with this version of Orb. It will not be installed: $package .' status='WARNING']"

        [array]$PackageMetadata.WebPackagesToInstall = ([array]$PackageMetadata.WebPackagesToInstall).Where( { $_.Name -ne $package })
    }

    # Check incoming App packages.
    foreach($package in $PackageMetadata.AppPackagesToInstall)
    {
        if($package.IsHotfix){
            $compareSemverResult = Compare-SemVer -Version1 $package.HotfixFixedInOrbVersion -Version2 $PackageMetadata.InstalledOrbVersion

            switch ($compareSemverResult) {
                $versionIsLessThanTarget { $appHotfixPackagesToRemove += $package.Name }
                $versionIsSameAsTarget { $appHotfixPackagesToRemove += $package.Name }
                $versionIsGreaterThanTarget { <# Do nothing, this will get reinstalled if it should be reinstalled at this point #> }
            }
        }
    }

    # This is a list of Package NAMES, not packages.
    foreach($package in $appHotfixPackagesToRemove){
        Write-Host "##teamcity[message text='Found a hotfix in the supplied APP install list which is not valid with this version of Orb. It will not be installed: $package .' status='WARNING']"

        [array]$PackageMetadata.AppPackagesToInstall = ([array]$PackageMetadata.AppPackagesToInstall).Where( { $_.Name -ne $package })
    }

    return $PackageMetadata
}