Skip to content

Run a virtual iPhone on an Apple Silicon Mac.

Swift
38.9 KB
Raw Blame
// FirmwareGuestPatchResolutionTests.swift — The guest-half selection resolver.
//
// `FirmwareGuestPatchResolution` decides which patches the guest half of an
// install applies now: the boot chain as the plan recorded it, the guest half
// as the current selection resolves it. These tests pin that split and the
// membership of the guest-target set against the real bundled catalogue.

import FirmwarePatcher
import Foundation
import Testing
import VPhonePatchKit

@Suite("Guest patch resolution")
struct FirmwareGuestPatchResolutionTests {
    @Test func `compiler identity needs cache key validation only when reuse is selected`() throws {
        let identity = FirmwareGuestSystemPatchSet.paravirtGPUCompilerCache
        let reuse = FirmwareGuestSystemPatchSet.metalCacheReuse
        let key = FirmwareGuestSystemPatchSet.metalCacheReuseKey
        let enabled: Set<String> = [identity, reuse, key]
        #expect(FirmwareGuestPatchResolution.missingCompilerCacheDependencies(enabled: enabled).isEmpty)
        #expect(FirmwareGuestPatchResolution.missingCompilerCacheDependencies(enabled: [identity, reuse]) == [key])
        // Selection succeeds before installation, but a failed key patch must
        // still stop the plugin/driver update. A prior applied key is sufficient.
        #expect(FirmwareGuestPatchResolution.missingCompilerCacheDependencies(enabled: enabled, applied: []) == [key])
        #expect(FirmwareGuestPatchResolution.missingCompilerCacheDependencies(enabled: enabled, applied: [identity, reuse]) == [key])
        #expect(FirmwareGuestPatchResolution.missingCompilerCacheDependencies(enabled: enabled, applied: [key]).isEmpty)
        #expect(FirmwareGuestPatchResolution.missingCompilerCacheDependencies(enabled: [identity], applied: []).isEmpty)
        let choices: [Set<String>] = [[], [identity], [reuse], [key], [identity, key], [reuse, key]]
        for choice in choices {
            #expect(FirmwareGuestPatchResolution.missingCompilerCacheDependencies(enabled: choice).isEmpty)
        }
        let standard = try VPhonePatchPlan.resolve(
            preset: FirmwarePatchSetCatalog.standardPreset,
            patchSets: FirmwarePatchSetCatalog.bundled,
            iOSBase: VPhoneVersion("26.6.2"), cloudOS: VPhoneVersion("26.4"),
        )
        #expect(standard.enabled.isSuperset(of: enabled))
        #expect(FirmwareGuestPatchResolution.missingCompilerCacheDependencies(enabled: standard.enabled).isEmpty)
    }

    @Test func `GLES primitive expansion rejects missing transport prerequisites but permits opt out`() throws {
        let patch = FirmwareGuestSystemPatchSet.glesPrimitiveRestart
        let dependencies = FirmwareGuestPatchResolution.glesPrimitiveRestartDependencies
        #expect(dependencies == [FirmwareGuestSystemPatchSet.paravirtGPUPrimitiveRestart,
                                 FirmwareGuestSystemPatchSet.metalVertexIDFormat])
        let plan = try VPhonePatchPlan.resolve(
            preset: FirmwarePatchSetCatalog.standardPreset,
            patchSets: FirmwarePatchSetCatalog.bundled,
            iOSBase: VPhoneVersion("26.6.2"), cloudOS: VPhoneVersion("26.4"),
        )
        #expect(plan.isEnabled(patch))
        #expect(FirmwareGuestPatchResolution.missingGLESPrimitiveRestartDependencies(enabled: plan.enabled).isEmpty)
        for dependency in dependencies {
            let blocked = try VPhonePatchPlan.resolve(
                preset: FirmwarePatchSetCatalog.standardPreset,
                patchSets: FirmwarePatchSetCatalog.bundled,
                iOSBase: VPhoneVersion("26.6.2"), cloudOS: VPhoneVersion("26.4"),
                blocked: [dependency],
            )
            #expect(FirmwareGuestPatchResolution.missingGLESPrimitiveRestartDependencies(enabled: blocked.enabled) == [dependency])
            #expect(FirmwareGuestPatchResolution.missingGLESPrimitiveRestartDependencies(enabled: blocked.enabled.subtracting([patch])).isEmpty)
        }
        #expect(FirmwareGuestPatchResolution.missingGLESPrimitiveRestartDependencies(enabled: [patch]) == dependencies.sorted())
        #expect(FirmwareGuestPatchResolution.missingGLESPrimitiveRestartDependencies(enabled: []).isEmpty)
    }

    @Test func `HomeView environment simulation is explicit and limited to its reviewed base`() throws {
        let id = FirmwareGuestSystemPatchSet.homeViewEnvironmentService
        for preset in FirmwarePatchSetCatalog.builtInPresets {
            let plan = try VPhonePatchPlan.resolve(
                preset: preset, patchSets: FirmwarePatchSetCatalog.bundled,
                iOSBase: VPhoneVersion("27.2"), cloudOS: VPhoneVersion("26.4")
            )
            #expect(!plan.isEnabled(id))
        }
        #expect(FirmwareGuestPatchResolution.unvalidatedHomeViewGuestPatches(enabled: [id]).isEmpty)
        #expect(FirmwareGuestPatchResolution.unvalidatedTVGuestPatches(enabled: [id], arm64eUserland: true) == [id])
        #expect(FirmwareGuestPatchResolution.unvalidatedHomePodGuestPatches(enabled: [id]) == [id])
        let declaration = try #require(FirmwarePatchSetCatalog.allDeclarations.first { $0.identifier == id })
        #expect(declaration.applicability.matches(iOSBase: VPhoneVersion("27.2"), cloudOS: VPhoneVersion("26.4")))
        for version in ["26.4", "27.0", "27.1", "27.3"] {
            #expect(!declaration.applicability.matches(iOSBase: VPhoneVersion(version), cloudOS: VPhoneVersion("26.4")))
        }
    }

    @Test func `HomeView keeps native setup and its bypass is an explicit reversible selection`() throws {
        let plan = try VPhonePatchPlan.resolve(
            preset: FirmwarePatchSetCatalog.homeViewPreset, patchSets: FirmwarePatchSetCatalog.bundled,
            iOSBase: VPhoneVersion("27.2"), cloudOS: VPhoneVersion("26.4")
        )
        #expect(plan.isEnabled(FirmwareGuestSystemPatchSet.homeViewProfileLookup))
        #expect(plan.isEnabled(FirmwareGuestSystemPatchSet.homeViewDisplayLookups))
        #expect(plan.isEnabled(FirmwareGuestSystemPatchSet.tvOTAUserland))
        #expect(plan.isEnabled("system-extensions-boot-gpu_bundle"))
        #expect(!plan.isEnabled(FirmwareGuestSystemPatchSet.homeViewSetupBypass))
        #expect(FirmwareGuestPatchResolution.unvalidatedHomeViewGuestPatches(enabled: plan.enabled).isEmpty)
        #expect(FirmwareGuestPatchResolution.unvalidatedHomeViewGuestPatches(enabled: [FirmwareGuestSystemPatchSet.homeViewSetupBypass]).isEmpty)
        #expect(FirmwareGuestPatchResolution.unvalidatedTVGuestPatches(enabled: [FirmwareGuestSystemPatchSet.homeViewSetupBypass], arm64eUserland: true) == [FirmwareGuestSystemPatchSet.homeViewSetupBypass])
        #expect(FirmwareGuestPatchResolution.unvalidatedHomePodGuestPatches(enabled: [FirmwareGuestSystemPatchSet.homeViewSetupBypass]) == [FirmwareGuestSystemPatchSet.homeViewSetupBypass])
        #expect(!plan.isEnabled(FirmwareGuestSystemPatchSet.tvSetupFocus))
        #expect(!plan.isEnabled(FirmwareGuestSystemPatchSet.tvLocalActivation))
    }

    @Test func `native TV setup adapters are limited to the 27 point 2 4K preset`() throws {
        for identifier in [FirmwareGuestSystemPatchSet.tvSetupDisplayLookup, FirmwareGuestSystemPatchSet.tvSetupFocus, FirmwareGuestSystemPatchSet.tvLocalActivation] {
            for version in ["26.6", "27.0", "27.1", "27.2", "27.3"] {
                for preset in FirmwarePatchSetCatalog.builtInPresets {
                    let plan = try VPhonePatchPlan.resolve(
                        preset: preset, patchSets: FirmwarePatchSetCatalog.bundled,
                        iOSBase: VPhoneVersion(version), cloudOS: VPhoneVersion("26.4"),
                    )
                    #expect(plan.isEnabled(identifier) == (version == "27.2" && preset.identifier == VPhonePatchPreset.tvOS4KIdentifier))
                }
            }
            #expect(FirmwareGuestPatchResolution.unvalidatedTVGuestPatches(enabled: [identifier], arm64eUserland: true).isEmpty)
            #expect(FirmwareGuestPatchResolution.unvalidatedHomePodGuestPatches(enabled: [identifier]) == [identifier])
            #expect(FirmwareGuestPatchResolution.guestPatchesOff(selectionEnabled: []).contains(identifier))
            #expect(FirmwareGuestPatchResolution.unvalidatedTVGuestPatches(enabled: [identifier]) == [identifier])
        }
    }

    @Test func `legacy TV setup is not selected by any preset`() throws {
        let identifier = FirmwareGuestSystemPatchSet.tvLegacySetup
        for preset in FirmwarePatchSetCatalog.builtInPresets {
            let plan = try VPhonePatchPlan.resolve(
                preset: preset, patchSets: FirmwarePatchSetCatalog.bundled,
                iOSBase: VPhoneVersion("27.2"), cloudOS: VPhoneVersion("26.4"),
            )
            #expect(!plan.isEnabled(identifier))
        }
        #expect(FirmwareGuestPatchResolution.unvalidatedTVGuestPatches(enabled: [identifier], arm64eUserland: true).isEmpty)
        #expect(FirmwareGuestPatchResolution.unvalidatedHomePodGuestPatches(enabled: [identifier]) == [identifier])
    }

    @Test func `HomePod persona lookup uses isolated tvOS deployment and follows selection`() throws {
        let identifier = FirmwareGuestSystemPatchSet.installCoordinationPersona
        for base in ["26.4", "27.0", "27.2", "28.0"] {
            let plan = try VPhonePatchPlan.resolve(
                preset: FirmwarePatchSetCatalog.homePodMiniPreset, patchSets: FirmwarePatchSetCatalog.bundled,
                iOSBase: VPhoneVersion(base), cloudOS: VPhoneVersion("26.4"),
            )
            #expect(plan.isEnabled(identifier) == base.hasPrefix("27."))
            #expect(!plan.isEnabled("system-launchdaemons-boot-environment"))
            #expect(!plan.isEnabled(FirmwareGuestSystemPatchSet.arm64eX1LaunchdBootstrap))
            #expect(!plan.isEnabled("system-launchd-boot-jetsam_panic_guard_bypass"))
        }
        let disabled = try VPhonePatchPlan.resolve(
            preset: FirmwarePatchSetCatalog.homePodMiniPreset, patchSets: FirmwarePatchSetCatalog.bundled,
            iOSBase: VPhoneVersion("27.2"), cloudOS: VPhoneVersion("26.4"), blocked: [identifier],
        )
        #expect(!disabled.isEnabled(identifier))
        #expect(FirmwareGuestPatchResolution.guestPatchesOff(selectionEnabled: disabled.enabled).contains(identifier))
        #expect(FirmwareGuestPatchResolution.unvalidatedHomePodGuestPatches(enabled: [identifier]).isEmpty)
        #expect(FirmwareGuestPatchResolution.unvalidatedTVGuestPatches(enabled: [identifier], arm64eUserland: true) == [identifier])
    }

    @Test(arguments: [FirmwareGuestSystemPatchSet.homePodCryptexStaging, FirmwareGuestSystemPatchSet.homePodCryptexClass, FirmwareGuestSystemPatchSet.homePodAdHocInstall])
    func `HomePod developer compatibility is independent of the iPhone environment and reversible in selection`(identifier: String) throws {
        for base in ["26.4", "27.0", "27.2", "28.0"] {
            for preset in FirmwarePatchSetCatalog.builtInPresets {
                let plan = try VPhonePatchPlan.resolve(
                    preset: preset, patchSets: FirmwarePatchSetCatalog.bundled,
                    iOSBase: VPhoneVersion(base), cloudOS: VPhoneVersion("26.4"),
                )
                #expect(plan.isEnabled(identifier) == (base.hasPrefix("27.")
                    && preset.identifier == VPhonePatchPreset.homePodMiniIdentifier))
                if plan.isEnabled(identifier) {
                    #expect(!plan.isEnabled("system-launchdaemons-boot-environment"))
                    let disabled = try VPhonePatchPlan.resolve(
                        preset: preset, patchSets: FirmwarePatchSetCatalog.bundled,
                        iOSBase: VPhoneVersion(base), cloudOS: VPhoneVersion("26.4"),
                        blocked: [identifier],
                    )
                    #expect(!disabled.isEnabled(identifier))
                    #expect(FirmwareGuestPatchResolution.guestPatchesOff(selectionEnabled: disabled.enabled).contains(identifier))
                }
            }
        }
        #expect(FirmwareGuestPatchResolution.unvalidatedHomePodGuestPatches(enabled: [identifier]).isEmpty)
        #expect(FirmwareGuestPatchResolution.unvalidatedTVGuestPatches(enabled: [identifier], arm64eUserland: true) == [identifier])
        let declaration = try #require(FirmwarePatchSetCatalog.allDeclarations.first { $0.identifier == identifier })
        let expectedTarget: VPhonePatchTarget = switch identifier {
        case FirmwareGuestSystemPatchSet.homePodCryptexStaging: .guestExecutable(path: "/usr/libexec/cryptexd")
        case FirmwareGuestSystemPatchSet.homePodAdHocInstall: .guestExecutable(path: "/usr/libexec/installd")
        default: .prebootDeviceTree
        }
        #expect(declaration.target == expectedTarget)
        #expect(!declaration.bootEssential)
    }

    @Test(arguments: [FirmwareGuestSystemPatchSet.homePodOTAUserland, FirmwareGuestSystemPatchSet.homePodSoundGlow])
    func `HomePod OTA and Sound Glow require 27 point 2 and stay out of other presets`(identifier: String) throws {
        for version in ["26.6", "27.0", "27.1", "27.2", "27.3"] {
            for preset in FirmwarePatchSetCatalog.builtInPresets {
                let plan = try VPhonePatchPlan.resolve(
                    preset: preset, patchSets: FirmwarePatchSetCatalog.bundled,
                    iOSBase: VPhoneVersion(version), cloudOS: VPhoneVersion("26.4"),
                )
                #expect(plan.isEnabled(identifier) == (VPhoneVersion(version)! >= VPhoneVersion(major: 27, minor: 2)
                    && preset.identifier == VPhonePatchPreset.homePodMiniIdentifier))
            }
        }
        #expect(FirmwareGuestPatchResolution.unvalidatedHomePodGuestPatches(enabled: [identifier]).isEmpty)
        #expect(FirmwareGuestPatchResolution.unvalidatedTVGuestPatches(enabled: [identifier], arm64eUserland: true) == [identifier])
        #expect(FirmwareGuestPatchResolution.guestPatchesOff(selectionEnabled: []).contains(identifier))
    }

    @Test func `Sound Glow requires native cap delivery but not speech or welcome`() throws {
        let glow = FirmwareGuestSystemPatchSet.homePodSoundGlow
        let dependencies = FirmwareGuestPatchResolution.homePodSoundGlowDependencies
        #expect(dependencies == ["system-vphoned-boot-install", FirmwareGuestSystemPatchSet.homePodTopCap])
        let enabled = dependencies.union([glow])
        #expect(FirmwareGuestPatchResolution.missingHomePodSoundGlowDependencies(enabled: enabled).isEmpty)
        for dependency in dependencies {
            #expect(FirmwareGuestPatchResolution.missingHomePodSoundGlowDependencies(enabled: enabled.subtracting([dependency])) == [dependency])
        }
        #expect(FirmwareGuestPatchResolution.missingHomePodSoundGlowDependencies(enabled: []).isEmpty)
        let declaration = try #require(FirmwarePatchSetCatalog.allDeclarations.first { $0.identifier == glow })
        #expect(declaration.target == .guestFile(path: FirmwareGuestSystemPatchSet.homePodSoundGlowPath))
        #expect(!declaration.bootEssential)
    }

    @Test func `only the HomePod preset selects the top cap and TV rejects explicit selection`() throws {
        let identifier = FirmwareGuestSystemPatchSet.homePodTopCap
        for preset in FirmwarePatchSetCatalog.builtInPresets {
            let plan = try VPhonePatchPlan.resolve(
                preset: preset, patchSets: FirmwarePatchSetCatalog.bundled,
                iOSBase: VPhoneVersion("27.0"), cloudOS: VPhoneVersion("26.4"),
            )
            #expect(plan.isEnabled(identifier) == (preset.identifier == VPhonePatchPreset.homePodMiniIdentifier))
        }
        #expect(FirmwareGuestPatchResolution.unvalidatedHomePodGuestPatches(enabled: [identifier]).isEmpty)
        #expect(FirmwareGuestPatchResolution.unvalidatedTVGuestPatches(enabled: [identifier]) == [identifier])
        #expect(FirmwareGuestPatchResolution.unvalidatedTVGuestPatches(enabled: [identifier], arm64eUserland: true) == [identifier])
    }

    @Test(arguments: [FirmwareGuestSystemPatchSet.homePodSetupBypass, FirmwareGuestSystemPatchSet.homePodAirPlayVM, FirmwareGuestSystemPatchSet.homePodAudioProduct,
                      FirmwareGuestSystemPatchSet.homePodWelcome, FirmwareGuestSystemPatchSet.homePodSiriSpeech])
    func `HomePod optional guest repairs are version gated and never selected for other devices`(identifier: String) throws {
        for base in ["26.4", "26.5", "27.0", "27.1"] {
            // The setup completion also applies to 26.5, the AirPlay override
            // only there; the others need 27.
            let applies = identifier == FirmwareGuestSystemPatchSet.homePodAirPlayVM ? base == "26.5"
                : base.hasPrefix("27.") || (base == "26.5" && identifier == FirmwareGuestSystemPatchSet.homePodSetupBypass)
            for preset in FirmwarePatchSetCatalog.builtInPresets {
                let plan = try VPhonePatchPlan.resolve(
                    preset: preset, patchSets: FirmwarePatchSetCatalog.bundled,
                    iOSBase: VPhoneVersion(base), cloudOS: VPhoneVersion("26.4"),
                )
                #expect(plan.isEnabled(identifier) == (applies
                    && identifier != FirmwareGuestSystemPatchSet.homePodAudioProduct
                    && preset.identifier == VPhonePatchPreset.homePodMiniIdentifier))
            }
        }
        #expect(FirmwareGuestPatchResolution.unvalidatedHomePodGuestPatches(enabled: [identifier]).isEmpty)
        #expect(FirmwareGuestPatchResolution.unvalidatedTVGuestPatches(enabled: [identifier]) == [identifier])
        #expect(FirmwareGuestPatchResolution.unvalidatedTVGuestPatches(enabled: [identifier], arm64eUserland: true) == [identifier])
        #expect(FirmwareGuestPatchResolution.guestPatchesOff(selectionEnabled: []).contains(identifier))
    }

    @Test func `HomePod AirPlay override is a guest marker for the setup helper`() throws {
        let airPlay = FirmwareGuestSystemPatchSet.homePodAirPlayVM
        let declaration = try #require(FirmwarePatchSetCatalog.allDeclarations.first { $0.identifier == airPlay })
        #expect(declaration.target == .guestFile(path: "/usr/share/vphone/HomePodAirPlay.plist"))
        #expect(!declaration.bootEssential)
        #expect(FirmwarePatchSetCatalog.manualOnlyPatches.contains(airPlay))
    }

    @Test func `HomePod welcome requires every selected runtime prerequisite but opt out is independent`() throws {
        let welcome = FirmwareGuestSystemPatchSet.homePodWelcome
        let dependencies = FirmwareGuestPatchResolution.homePodWelcomeDependencies
        #expect(dependencies == ["system-vphoned-boot-install", FirmwareGuestSystemPatchSet.homePodTopCap,
                                 FirmwareGuestSystemPatchSet.homePodSetupBypass, FirmwareGuestSystemPatchSet.virtioSoundDriver,
                                 FirmwareGuestSystemPatchSet.homePodSiriSpeech])
        let complete = dependencies.union([welcome])
        #expect(FirmwareGuestPatchResolution.missingHomePodWelcomeDependencies(enabled: complete).isEmpty)
        for dependency in dependencies {
            #expect(FirmwareGuestPatchResolution.missingHomePodWelcomeDependencies(enabled: complete.subtracting([dependency])) == [dependency])
        }
        #expect(FirmwareGuestPatchResolution.missingHomePodWelcomeDependencies(enabled: [welcome]) == dependencies.sorted())
        #expect(FirmwareGuestPatchResolution.missingHomePodWelcomeDependencies(enabled: []).isEmpty)
        #expect(FirmwareGuestPatchResolution.missingHomePodWelcomeDependencies(enabled: dependencies).isEmpty)
        let plan = try VPhonePatchPlan.resolve(
            preset: FirmwarePatchSetCatalog.homePodMiniPreset, patchSets: FirmwarePatchSetCatalog.bundled,
            iOSBase: VPhoneVersion("27.0"), cloudOS: VPhoneVersion("26.4"),
        )
        #expect(plan.isEnabled(welcome))
        #expect(FirmwareGuestPatchResolution.missingHomePodWelcomeDependencies(enabled: plan.enabled).isEmpty)
        let declaration = try #require(FirmwarePatchSetCatalog.allDeclarations.first { $0.identifier == welcome })
        #expect(declaration.target == .guestFile(path: "/usr/share/vphone/HomePodWelcome.plist"))
        #expect(!declaration.bootEssential)
    }

    @Test func `HomePod Siri speech requires its native output dependencies and can be disabled independently`() throws {
        let speech = FirmwareGuestSystemPatchSet.homePodSiriSpeech
        let dependencies = FirmwareGuestPatchResolution.homePodSiriSpeechDependencies
        #expect(dependencies == ["system-vphoned-boot-install", FirmwareGuestSystemPatchSet.homePodTopCap,
                                 FirmwareGuestSystemPatchSet.virtioSoundDriver])
        let complete = dependencies.union([speech])
        #expect(FirmwareGuestPatchResolution.missingHomePodSiriSpeechDependencies(enabled: complete).isEmpty)
        for dependency in dependencies {
            #expect(FirmwareGuestPatchResolution.missingHomePodSiriSpeechDependencies(enabled: complete.subtracting([dependency])) == [dependency])
        }
        #expect(FirmwareGuestPatchResolution.missingHomePodSiriSpeechDependencies(enabled: [speech]) == dependencies.sorted())
        #expect(FirmwareGuestPatchResolution.missingHomePodSiriSpeechDependencies(enabled: []).isEmpty)
        #expect(FirmwareGuestPatchResolution.missingHomePodSiriSpeechDependencies(enabled: dependencies).isEmpty)
        #expect(!dependencies.contains(FirmwareGuestSystemPatchSet.homePodSetupBypass))
        #expect(!dependencies.contains(FirmwareGuestSystemPatchSet.homePodWelcome))
        let plan = try VPhonePatchPlan.resolve(
            preset: FirmwarePatchSetCatalog.homePodMiniPreset, patchSets: FirmwarePatchSetCatalog.bundled,
            iOSBase: VPhoneVersion("27.0"), cloudOS: VPhoneVersion("26.4"),
        )
        #expect(plan.isEnabled(speech))
        #expect(FirmwareGuestPatchResolution.missingHomePodSiriSpeechDependencies(enabled: plan.enabled).isEmpty)
        let declaration = try #require(FirmwarePatchSetCatalog.allDeclarations.first { $0.identifier == speech })
        #expect(declaration.target == .guestFile(path: "/usr/share/vphone/HomePodSiriSpeech.plist"))
        #expect(!declaration.bootEssential)
        // Welcome cannot remain enabled after opting out of its speech repair.
        #expect(FirmwareGuestPatchResolution.missingHomePodWelcomeDependencies(enabled: plan.enabled.subtracting([speech])) == [speech])
    }

    @Test
    func `TV selection keeps vphoned and excludes iOS payloads and cache patches`() throws {
        let standard = try VPhonePatchPlan.resolve(
            preset: FirmwarePatchSetCatalog.standardPreset,
            patchSets: FirmwarePatchSetCatalog.bundled,
            iOSBase: VPhoneVersion("26.4"),
            cloudOS: VPhoneVersion("26.4"),
        )
        let unvalidated = FirmwareGuestPatchResolution.unvalidatedTVGuestPatches(enabled: standard.enabled)
        #expect(!unvalidated.contains("system-vphoned-boot-install"))
        #expect(!unvalidated.contains("system-launchd_cache_loader-boot-unsecure_cache_gate"))
        #expect(unvalidated.contains("system-launchdaemons-boot-environment"))
        #expect(unvalidated.contains("system-extensions-boot-gpu_bundle"))
        #expect(unvalidated.contains(FirmwareGuestSystemPatchSet.paravirtGPUIndexOffset))
        #expect(unvalidated.contains(FirmwareGuestSystemPatchSet.paravirtGPUPrimitiveRestart))
        #expect(unvalidated.contains("dyld-cfw-camera"))
        #expect(!unvalidated.contains("system-seputil-boot-gigalocker_uuid"))
        #expect(!unvalidated.contains("system-gigalocker-boot-rename"))
        let serial = standard.enabled.subtracting(unvalidated)
        #expect(FirmwareGuestPatchResolution.unvalidatedTVGuestPatches(enabled: serial).isEmpty)
        #expect(serial.intersection(FirmwareGuestPatchResolution.guestTargetIdentifiers)
            == FirmwareGuestPatchResolution.tvSupportedGuestPatches.subtracting([FirmwareGuestSystemPatchSet.tvTPRO]))
        #expect(serial.subtracting(FirmwareGuestPatchResolution.guestTargetIdentifiers)
            == standard.enabled.subtracting(FirmwareGuestPatchResolution.guestTargetIdentifiers))
    }

    @Test
    func `TV TPRO is opt in and retains the TV guest guard`() throws {
        let identifier = FirmwareGuestSystemPatchSet.tvTPRO
        let standard = try VPhonePatchPlan.resolve(
            preset: FirmwarePatchSetCatalog.standardPreset,
            patchSets: FirmwarePatchSetCatalog.bundled,
            iOSBase: VPhoneVersion("26.4"), cloudOS: VPhoneVersion("26.4"),
        )
        #expect(!standard.enabled.contains(identifier))
        let serial = standard.enabled.subtracting(
            FirmwareGuestPatchResolution.unvalidatedTVGuestPatches(enabled: standard.enabled),
        ).union([identifier])
        #expect(FirmwareGuestPatchResolution.unvalidatedTVGuestPatches(enabled: serial).isEmpty)
        #expect(serial.contains("system-vphoned-boot-install"))
        #expect(!serial.contains("system-extensions-boot-gpu_bundle"))
    }

    @Test
    func `only an arm64e TV admits the GPU driver and the OTA userland`() {
        let gpu = "system-extensions-boot-gpu_bundle"
        let ota = FirmwareGuestSystemPatchSet.tvOTAUserland
        let selection: Set<String> = [gpu, ota, "system-vphoned-boot-install"]
        #expect(FirmwareGuestPatchResolution.unvalidatedTVGuestPatches(enabled: selection) == [gpu, ota].sorted())
        #expect(FirmwareGuestPatchResolution.unvalidatedTVGuestPatches(enabled: selection, arm64eUserland: true).isEmpty)
        // The iOS payloads stay out for both.
        #expect(FirmwareGuestPatchResolution.unvalidatedTVGuestPatches(enabled: ["dyld-cfw-camera"], arm64eUserland: true) == ["dyld-cfw-camera"])
    }

    @Test
    func `only an arm64e TV admits the environment hooks and the launchd patch that loads them`() {
        let hooks: Set = ["system-launchdaemons-boot-environment", "system-launchd-boot-jetsam_panic_guard_bypass"]
        #expect(FirmwareGuestPatchResolution.unvalidatedTVGuestPatches(enabled: hooks, arm64eUserland: true).isEmpty)
        // Both libraries are arm64e: a plain-arm64 launchd cannot load them.
        #expect(FirmwareGuestPatchResolution.unvalidatedTVGuestPatches(enabled: hooks) == hooks.sorted())
        // The X1 launchd bootstrap shares the load command but stays out.
        let x1 = FirmwareGuestSystemPatchSet.arm64eX1LaunchdBootstrap
        #expect(FirmwareGuestPatchResolution.unvalidatedTVGuestPatches(enabled: [x1], arm64eUserland: true) == [x1])
        // HomePod keeps its own launchd library and no environment. Its
        // launchd takes the jetsam guard (userspace debugging) into the same
        // copy as the persona adapter, so that patch alone is admitted.
        #expect(FirmwareGuestPatchResolution.unvalidatedHomePodGuestPatches(enabled: hooks) == ["system-launchdaemons-boot-environment"])
    }

    @Test(arguments: ["27.0", "27.2"])
    func `the Apple TV 4K preset swaps in the OTA userland with the GPU driver and no TPRO patches`(version: String) throws {
        let gpu = "system-extensions-boot-gpu_bundle"
        let ota = FirmwareGuestSystemPatchSet.tvOTAUserland
        let tpro: Set = [FirmwareGuestSystemPatchSet.tvTPRO, FirmwareKernelCustomFirmwarePatchSet.tvTPROPagers]
        func plan(_ preset: VPhonePatchPreset) throws -> VPhonePatchPlan {
            try VPhonePatchPlan.resolve(
                preset: preset,
                patchSets: FirmwarePatchSetCatalog.bundled,
                iOSBase: VPhoneVersion("26.6"),
                cloudOS: VPhoneVersion("26.4"),
            )
        }
        let tv4K = try plan(FirmwarePatchSetCatalog.tvOS4KPreset)
        #expect(tv4K.isEnabled(gpu) && tv4K.isEnabled(ota))
        #expect(tv4K.enabled.isDisjoint(with: tpro))
        #expect(tv4K.isEnabled("system-vphoned-boot-install"))
        // The upstream GPU heap index patch stays out, as for every TV guest.
        #expect(!tv4K.isEnabled(FirmwareGuestSystemPatchSet.paravirtGPUIndexOffset))
        #expect(!tv4K.isEnabled(FirmwareGuestSystemPatchSet.paravirtGPUPrimitiveRestart))
        #expect(FirmwareGuestPatchResolution.unvalidatedTVGuestPatches(enabled: tv4K.enabled, arm64eUserland: true).isEmpty)
        #expect(FirmwareGuestPatchResolution.unvalidatedTVGuestPatches(enabled: tv4K.enabled) == [gpu, ota].sorted())
        // The 27 shared-cache patches are on but meet only a 27 userland.
        #expect(tv4K.enabled.isDisjoint(with: FirmwarePatchSetCatalog.tvOS27UserlandPatches))
        let tv4K27 = try VPhonePatchPlan.resolve(
            preset: FirmwarePatchSetCatalog.tvOS4KPreset,
            patchSets: FirmwarePatchSetCatalog.bundled,
            iOSBase: VPhoneVersion(version),
            cloudOS: VPhoneVersion("26.4"),
        )
        // The userland swap and the GPU driver carry on to the 27 OTA.
        #expect(tv4K27.isEnabled(gpu) && tv4K27.isEnabled(ota))
        #expect(tv4K27.enabled.isSuperset(of: FirmwarePatchSetCatalog.tvOS27UserlandPatches))
        #expect(tv4K27.isEnabled("kernel-boot-iomfb_swapend"))
        #expect(FirmwareGuestPatchResolution.unvalidatedTVGuestPatches(enabled: tv4K27.enabled, arm64eUserland: true).isEmpty)
        let x1Patches: Set<String> = [
            FirmwareGuestSystemPatchSet.arm64eX1CacheBootstrap,
            FirmwareGuestSystemPatchSet.arm64eX1CacheRemaining,
            FirmwareGuestSystemPatchSet.arm64eX1DyldBootstrap,
            FirmwareGuestSystemPatchSet.arm64eX1FsckBootstrap,
            FirmwareGuestSystemPatchSet.arm64eX1LaunchdBootstrap,
            FirmwareGuestSystemPatchSet.arm64eX1MountBootstrap,
            "kernel-boot-arm64e_x1",
            "restoreramdisk-boot-apfs_sha3_hash",
        ]
        #expect(tv4K27.enabled.isDisjoint(with: x1Patches))

        // The HD's preset is the mirror image.
        let tvHD = try plan(FirmwarePatchSetCatalog.tvOSPreset)
        #expect(!tvHD.isEnabled(gpu) && !tvHD.isEnabled(ota))
        #expect(tvHD.enabled.isSuperset(of: tpro))
        // Otherwise the two agree.
        #expect(tv4K.enabled.symmetricDifference(tvHD.enabled) == tpro.union([gpu, ota]))
    }

    @Test
    func `HomePod audio uses its shared driver without global identity or iPhone routing patches`() throws {
        let driver = FirmwareGuestSystemPatchSet.virtioSoundDriver
        let product = FirmwareGuestSystemPatchSet.homePodAudioProduct
        let plan = try VPhonePatchPlan.resolve(
            preset: FirmwarePatchSetCatalog.homePodMiniPreset,
            patchSets: FirmwarePatchSetCatalog.bundled,
            iOSBase: VPhoneVersion("27.0"), cloudOS: VPhoneVersion("26.4"),
        )
        #expect(plan.isEnabled(driver))
        #expect(!plan.isEnabled(product))
        #expect(FirmwareGuestPatchResolution.unvalidatedHomePodGuestPatches(enabled: [driver, product]).isEmpty)
        #expect(FirmwareGuestPatchResolution.unvalidatedTVGuestPatches(enabled: [driver]) == [driver])
        #expect(FirmwareGuestPatchResolution.unvalidatedTVGuestPatches(enabled: [driver], arm64eUserland: true) == [driver])
        let iPhoneRouting: Set<String> = [
            FirmwareGuestSystemPatchSet.virtualAudioSpeakerRouteThrows,
            FirmwareGuestSystemPatchSet.virtualAudioMuteSetThrow,
            FirmwareGuestSystemPatchSet.virtualAudioSpeakerProtectionGate,
            FirmwareGuestSystemPatchSet.virtualAudioVolumeModePrecondition,
            FirmwareGuestSystemPatchSet.virtualAudioGraphConfigurations,
            FirmwareGuestSystemPatchSet.virtualAudioSpeakerRawChains,
            FirmwareGuestSystemPatchSet.virtualAudioMicrophoneChains,
        ]
        #expect(plan.enabled.isDisjoint(with: iPhoneRouting))
    }

    @Test
    func `HomePod rejects explicit TV payloads while admitting its daemon and 27 compatibility patches`() {
        let supported: Set<String> = [
            "system-vphoned-boot-install",
            "system-launchd_cache_loader-boot-unsecure_cache_gate",
            "system-seputil-boot-gigalocker_uuid",
            "system-gigalocker-boot-rename",
        ]
        let rejected: Set<String> = [
            "system-extensions-boot-gpu_bundle",
            FirmwareGuestSystemPatchSet.tvOTAUserland,
            FirmwareGuestSystemPatchSet.tvTPRO,
            "system-launchdaemons-boot-environment",
            "dyld-cfw-camera",
        ]
        let admitted = supported.union(FirmwarePatchSetCatalog.tvOS27UserlandPatches)
        #expect(FirmwareGuestPatchResolution.unvalidatedHomePodGuestPatches(enabled: admitted).isEmpty)
        #expect(FirmwareGuestPatchResolution.unvalidatedHomePodGuestPatches(enabled: admitted.union(rejected)) == rejected.sorted())
        // The TV arm64e guard admits GPU/OTA selection; HomePod's own guard
        // must keep rejecting those even though its userland is also arm64e.
        let tvPayloads: Set<String> = ["system-extensions-boot-gpu_bundle", FirmwareGuestSystemPatchSet.tvOTAUserland]
        #expect(FirmwareGuestPatchResolution.unvalidatedTVGuestPatches(enabled: tvPayloads, arm64eUserland: true).isEmpty)
        #expect(FirmwareGuestPatchResolution.unvalidatedHomePodGuestPatches(enabled: tvPayloads) == tvPayloads.sorted())
        #expect(FirmwareGuestPatchResolution.homePodSupportedGuestPatches.isDisjoint(with: rejected))
    }

    @Test
    func `HomePod mini uses its own arm64e image with 27 compatibility and no TV OTA or display payload`() throws {
        let excluded: Set<String> = [
            "system-extensions-boot-gpu_bundle",
            FirmwareGuestSystemPatchSet.tvOTAUserland,
            FirmwareGuestSystemPatchSet.tvTPRO,
            FirmwareKernelCustomFirmwarePatchSet.tvTPROPagers,
            FirmwareGuestSystemPatchSet.paravirtGPUIndexOffset,
            FirmwareGuestSystemPatchSet.paravirtGPUPrimitiveRestart,
            "system-launchdaemons-boot-environment",
            "dyld-cfw-camera",
        ]
        #expect(FirmwarePatchSetCatalog.homePodMiniPreset.identifier == VPhonePatchPreset.homePodMiniIdentifier)
        for base in ["26.4", "27.0"] {
            let plan = try VPhonePatchPlan.resolve(
                preset: FirmwarePatchSetCatalog.homePodMiniPreset,
                patchSets: FirmwarePatchSetCatalog.bundled,
                iOSBase: VPhoneVersion(base), cloudOS: VPhoneVersion("26.4"),
            )
            #expect(plan.enabled.isDisjoint(with: excluded))
            #expect(plan.isEnabled("system-vphoned-boot-install"))
            #expect(plan.isEnabled("system-launchd_cache_loader-boot-unsecure_cache_gate"))
            #expect(plan.isEnabled("devicetree-cfw-homepod_product"))
            #expect(FirmwareGuestPatchResolution.unvalidatedHomePodGuestPatches(enabled: plan.enabled).isEmpty)
            if base == "27.0" {
                #expect(plan.enabled.isSuperset(of: FirmwarePatchSetCatalog.tvOS27UserlandPatches))
            } else {
                #expect(plan.enabled.isDisjoint(with: FirmwarePatchSetCatalog.tvOS27UserlandPatches))
            }
        }
    }

    @Test
    func `TV TPRO patches apply to every tvOS 26 userland on the 26.4 kernel`() throws {
        let tv: Set = [FirmwareGuestSystemPatchSet.tvTPRO, FirmwareKernelCustomFirmwarePatchSet.tvTPROPagers]
        for build in ["26.4", "26.6"] {
            let plan = try VPhonePatchPlan.resolve(
                preset: FirmwarePatchSetCatalog.standardPreset,
                patchSets: FirmwarePatchSetCatalog.bundled,
                iOSBase: VPhoneVersion(build),
                cloudOS: VPhoneVersion("26.4"),
                allowed: tv,
            )
            #expect(plan.enabled.isSuperset(of: tv), "\(build)")
            #expect(plan.skippedByVersion.isDisjoint(with: tv), "\(build)")
        }
    }

    @Test
    func `Guest target identifiers include the guest patches and exclude the boot chain`() {
        let guest = FirmwareGuestPatchResolution.guestTargetIdentifiers

        // A dyld-cache patch, a guest Mach-O, a guest file, and a Preboot
        // device-tree patch are all guest-half.
        #expect(guest.contains("dyld-boot-lockdown_mode"))
        #expect(guest.contains("system-seputil-boot-gigalocker_uuid"))
        #expect(guest.contains("system-vphoned-boot-install"))
        #expect(guest.contains(FirmwareGuestSystemPatchSet.prebootHaptics))
        #expect(guest.contains(FirmwareGuestIdentityPatchSet.prebootDeviceTreeIdentity))

        // Every boot-chain patch is excluded: those are `fw patch`'s, not the
        // guest half's.
        for declaration in FirmwarePatchSetCatalog.allDeclarations where declaration.target.isBootChain {
            #expect(!guest.contains(declaration.identifier), "\(declaration.identifier) is boot-chain")
        }

        // And the set is exactly the non-boot-chain declarations.
        let expected = Set(
            FirmwarePatchSetCatalog.allDeclarations
                .filter { !$0.target.isBootChain }
                .map(\.identifier),
        )
        #expect(guest == expected)
    }

    @Test
    func `Effective enabled keeps boot chain from the plan and guest half from the selection`() {
        let guest = FirmwareGuestPatchResolution.guestTargetIdentifiers
        let bootChain = Set(
            FirmwarePatchSetCatalog.allDeclarations
                .filter(\.target.isBootChain)
                .map(\.identifier),
        )
        guard
            let boot = bootChain.first,
            let guestOn = guest.first,
            let guestOff = guest.dropFirst().first
        else {
            Issue.record("the bundled catalogue has too few patches to exercise the split")
            return
        }

        // The plan had a boot patch and one guest patch on; the selection now
        // has a *different* guest patch on and the old one off.
        let planEnabled: Set<String> = [boot, guestOn]
        let selectionEnabled: Set<String> = [guestOff]

        let effective = FirmwareGuestPatchResolution.effectiveEnabled(
            planEnabled: planEnabled,
            selectionEnabled: selectionEnabled,
        )

        #expect(effective.contains(boot), "the boot patch stays from the plan")
        #expect(effective.contains(guestOff), "a guest patch the selection turned on comes in")
        #expect(!effective.contains(guestOn), "a guest patch the selection turned off drops out")
    }

    @Test
    func `A boot-chain selection cannot add or drop guest patches`() {
        let guest = FirmwareGuestPatchResolution.guestTargetIdentifiers
        guard let guestID = guest.first else {
            Issue.record("no guest patches in the catalogue")
            return
        }
        // The selection resolves the guest patch off but names a boot patch the
        // plan never had: the boot side is the plan's alone, so nothing from the
        // selection's boot choices leaks in.
        let planEnabled: Set<String> = [guestID]
        let selectionEnabled: Set<String> = []
        let effective = FirmwareGuestPatchResolution.effectiveEnabled(
            planEnabled: planEnabled,
            selectionEnabled: selectionEnabled,
        )
        #expect(effective.isEmpty, "the guest patch drops and no boot patch is invented")
    }

    @Test
    func `Guest patches off is the guest set minus the selection`() {
        let guest = FirmwareGuestPatchResolution.guestTargetIdentifiers
        guard let on = guest.first else {
            Issue.record("no guest patches in the catalogue")
            return
        }
        let off = FirmwareGuestPatchResolution.guestPatchesOff(selectionEnabled: [on])
        #expect(!off.contains(on))
        #expect(off == guest.subtracting([on]))
    }
}