Skip to content

Run a virtual iPhone on an Apple Silicon Mac.

Swift
42.4 KB
Raw Blame
// FirmwarePatchSetCatalogTests.swift — The bundled catalogue, checked against itself.
//
// The manifests are hand-written and the patch identifiers in them have to match
// the record identifiers the patchers emit. Nothing in the type system enforces
// that, so these tests do: every shipped preset resolves, every declaration is
// reachable, and the standard preset still says what the golden corpus was recorded
// against.
//
// The one thing they cannot check without firmware is that each declaration
// actually covers a record. That is what the `[!] declared by no patch set` warning
// is for: it fires during a real `fw patch`, and the golden runs are checked for it.

import FirmwarePatcher
import Foundation
import Testing
import VPhonePatchKit

@Suite("Bundled patch set catalogue")
struct FirmwarePatchSetCatalogTests {
    @Test func `Legacy startup compatibility is opt in and scoped to iOS 16`() throws {
        for id in [FirmwareGuestSystemPatchSet.ios16KeybaglessUI, FirmwareGuestSystemPatchSet.ios16Touchscreen, FirmwareGuestSystemPatchSet.ios16EphemeralStorage, FirmwareGuestSystemPatchSet.ios16Framebuffer, FirmwareGuestSystemPatchSet.ios16Surface, FirmwareGuestSystemPatchSet.ios16MachPorts, FirmwareGuestSystemPatchSet.ios16PortsLookup, FirmwareGuestSystemPatchSet.ios16Desktop, FirmwareGuestSystemPatchSet.ios16Keybag, FirmwareGuestSystemPatchSet.ios16Migration] {
            for version in ["16.6.1", "17.7", "18.6.2", "26.1", "27.1"] {
                for selected in [false, true] {
                    var preset = FirmwarePatchSetCatalog.standardPreset
                    if selected { preset.selection = preset.selection.allowing([id]) }
                    let plan = try VPhonePatchPlan.resolve(
                        preset: preset, patchSets: FirmwarePatchSetCatalog.bundled,
                        iOSBase: VPhoneVersion(version), cloudOS: VPhoneVersion("26.1")
                    )
                    #expect(plan.isEnabled(id) == (selected && version == "16.6.1"))
                }
            }
        }
    }

    @Test func `iOS 17 desktop workaround is opt in and unavailable on other bases`() throws {
        let id = FirmwareGuestSystemPatchSet.ios17Desktop
        for version in ["16.6.1", "17.7", "18.6.2", "26.1", "27.1"] {
            for enabled in [false, true] {
                var preset = FirmwarePatchSetCatalog.standardPreset
                if enabled { preset.selection = preset.selection.allowing([id]) }
                let plan = try VPhonePatchPlan.resolve(
                    preset: preset, patchSets: FirmwarePatchSetCatalog.bundled,
                    iOSBase: VPhoneVersion(version), cloudOS: VPhoneVersion("26.1")
                )
                #expect(plan.isEnabled(id) == (enabled && version == "17.7"))
            }
        }
    }

    @Test func `Local iOS 16 experiment selects older userland boot compatibility without the iOS 17 hook`() throws {
        let plan = try VPhonePatchPlan.resolve(
            preset: FirmwarePatchSetCatalog.standardPreset,
            patchSets: FirmwarePatchSetCatalog.bundled,
            iOSBase: VPhoneVersion("16.6.1"), cloudOS: VPhoneVersion("26.1")
        )
        #expect(plan.isEnabled("dyld-boot-iomfb_swapend"))
        #expect(plan.isEnabled("kernel-boot-thread_guard_violation"))
        #expect(plan.isEnabled(FirmwarePatchSetCatalog.paravirtUserClientsPatch))
        #expect(!plan.isEnabled(FirmwareGuestSystemPatchSet.ios17Desktop))
    }

    @Test func `Experimental iOS 17 selects the older userland boot compatibility patches`() throws {
        let plan = try VPhonePatchPlan.resolve(
            preset: FirmwarePatchSetCatalog.standardPreset,
            patchSets: FirmwarePatchSetCatalog.bundled,
            iOSBase: VPhoneVersion("17.7"), cloudOS: VPhoneVersion("26.1"),
        )
        #expect(plan.isEnabled("dyld-boot-iomfb_swapend"))
        #expect(plan.isEnabled("kernel-boot-thread_guard_violation"))
        #expect(plan.isEnabled(FirmwarePatchSetCatalog.paravirtUserClientsPatch))
        #expect(!plan.isEnabled("dyld-boot-iomfb_force_kern"))
    }

    @Test func `CIBarcode lowering is scoped to the measured base and can be disabled`() throws {
        let identifier = FirmwareGuestSystemPatchSet.arm64eX1CIBarcode
        for base in ["26.4", "27.0.1", "27.1", "27.1.1", "27.2", "28.0"] {
            for blocked in [false, true] {
                var preset = FirmwarePatchSetCatalog.standardPreset
                if blocked {
                    preset.selection = preset.selection.blocking([identifier])
                }
                let plan = try VPhonePatchPlan.resolve(
                    preset: preset,
                    patchSets: FirmwarePatchSetCatalog.bundled,
                    iOSBase: VPhoneVersion(base),
                    cloudOS: VPhoneVersion("26.4"),
                )
                let supported = base == "27.1" || base.hasPrefix("27.1.")
                #expect(plan.isEnabled(identifier) == (supported && !blocked))
            }
        }
    }

    @Test(arguments: [FirmwareGuestSystemPatchSet.gyroscope, FirmwareGuestSystemPatchSet.accelerometer, FirmwareGuestSystemPatchSet.attitude])
    func `Motion sensors follow selection and their deployment target`(identifier: String) throws {
        for base in ["18.6.2", "26.4", "27.0.1"] {
            let plan = try VPhonePatchPlan.resolve(
                preset: FirmwarePatchSetCatalog.standardPreset,
                patchSets: FirmwarePatchSetCatalog.bundled,
                iOSBase: VPhoneVersion(base), cloudOS: VPhoneVersion("26.4"),
            )
            #expect(plan.isEnabled(identifier))
            var blocked = FirmwarePatchSetCatalog.standardPreset
            blocked.selection = blocked.selection.blocking([identifier])
            let disabled = try VPhonePatchPlan.resolve(
                preset: blocked, patchSets: FirmwarePatchSetCatalog.bundled,
                iOSBase: VPhoneVersion(base), cloudOS: VPhoneVersion("26.4"),
            )
            #expect(!disabled.isEnabled(identifier))
        }
        let unsupportedBases: [VPhoneVersion?] = [nil, VPhoneVersion("17.0")]
        for base in unsupportedBases {
            let plan = try VPhonePatchPlan.resolve(
                preset: FirmwarePatchSetCatalog.standardPreset,
                patchSets: FirmwarePatchSetCatalog.bundled,
                iOSBase: base, cloudOS: VPhoneVersion("26.4"),
            )
            #expect(!plan.isEnabled(identifier))
        }
    }

    @Test func `CoreDevice persona lookup is selected only for iOS 27`() throws {
        for base in ["26.4", "27.0.1", "28.0"] {
            let plan = try VPhonePatchPlan.resolve(
                preset: FirmwarePatchSetCatalog.standardPreset,
                patchSets: FirmwarePatchSetCatalog.bundled,
                iOSBase: VPhoneVersion(base), cloudOS: VPhoneVersion("26.4"),
            )
            #expect(plan.isEnabled(FirmwareGuestSystemPatchSet.installCoordinationPersona) == base.hasPrefix("27."))
        }
    }

    @Test
    func `Every bundled set has a unique identifier and no duplicate patches`() {
        let setIdentifiers = FirmwarePatchSetCatalog.bundled.map(\.identifier)
        #expect(Set(setIdentifiers).count == setIdentifiers.count)

        let patchIdentifiers = FirmwarePatchSetCatalog.allDeclarations.map(\.identifier)
        #expect(Set(patchIdentifiers).count == patchIdentifiers.count)
    }

    @Test
    func `No patch identifier is a record-site prefix of another`() {
        // Two declarations where one is a site of the other would make record
        // attribution depend on the order they happen to be checked in. The
        // resolver picks the longest, but a catalogue that needs that rule to
        // disambiguate its own patches is a catalogue with a naming mistake. Only
        // a dot starts a site: an underscore continues a snake_case name.
        let identifiers = FirmwarePatchSetCatalog.allDeclarations.map(\.identifier)
        for outer in identifiers {
            for inner in identifiers where inner != outer {
                #expect(!inner.hasPrefix(outer + "."), "\(inner) reads as a site of \(outer)")
            }
        }
    }

    @Test
    func `Every patch identifier names its component, effect and patch`() throws {
        // `{component}-{effect}-{name}`. The effect is derived, not chosen:
        // `boot` for a boot-essential patch, `exp` for one standard leaves off,
        // `cfw` for the rest. A patch that changes either property has to be
        // renamed with it, so the identifier never lies about what it is.
        let shape = try Regex("^[a-z0-9_]+(-[a-z0-9_]+)*-(boot|cfw|exp)-[a-z0-9_]+$")
        let standard = FirmwarePatchSetCatalog.standardPreset
        let standardSets = Set(standard.patchSets.map(\.identifier))
        var seen: Set<String> = []
        for set in FirmwarePatchSetCatalog.bundled {
            // The same rule `fw patches --json` reports as `inPreset`.
            let setInStandard = standardSets.contains(set.identifier)
            for patch in set.patches {
                let identifier = patch.identifier
                #expect(seen.insert(identifier).inserted, "\(identifier) is declared twice")
                #expect(identifier.wholeMatch(of: shape) != nil, "\(identifier) does not match the naming scheme")

                let segments = identifier.split(separator: "-", omittingEmptySubsequences: false)
                guard segments.count >= 3 else { continue }
                let effect = segments[segments.count - 2]
                let inStandard = setInStandard && standard.selection.includes(identifier)
                let expected = patch.bootEssential ? "boot" : (inStandard ? "cfw" : "exp")
                #expect(effect == expected, "\(identifier) should use effect \(expected)")
            }
        }
    }

    @Test
    func `Every patch has a title, and a summary if it is boot-essential`() {
        for patch in FirmwarePatchSetCatalog.allDeclarations {
            #expect(!patch.title.isEmpty, "\(patch.identifier) has no title")
            // The editor shows these beside a checkbox someone may untick. A
            // boot-essential patch without an explanation is a trap.
            if patch.bootEssential {
                #expect(!patch.summary.isEmpty, "\(patch.identifier) is boot-essential with no summary")
            }
        }
    }

    @Test
    func `Every shipped preset resolves on each supported base`() throws {
        for preset in FirmwarePatchSetCatalog.builtInPresets {
            for base in ["18.6.2", "26.0", "26.4", "27.0"] {
                for cloud in ["26.1", "26.4"] {
                    let plan = try VPhonePatchPlan.resolve(
                        preset: preset,
                        patchSets: FirmwarePatchSetCatalog.bundled,
                        iOSBase: VPhoneVersion(base),
                        cloudOS: VPhoneVersion(cloud),
                    )
                    #expect(!plan.enabled.isEmpty)
                    // Nothing a shipped iOS preset does should drop a boot-essential
                    // patch: these are the combinations we claim boot. The tvOS
                    // presets drop exactly the iOS ones an Apple TV has no port of.
                    let tvPresets = [VPhonePatchPreset.homeViewIdentifier, VPhonePatchPreset.tvOSIdentifier, VPhonePatchPreset.tvOS4KIdentifier, VPhonePatchPreset.homePodMiniIdentifier]
                    // `minimal` and `watchos` drop every boot chain patch but
                    // iBEC's and LLB's, and every kernel patch of the two sets
                    // they name only so a machine can turn some on: their system
                    // is customised before the restore instead, onto a stock
                    // kernel.
                    let restoreImagePresets = [VPhonePatchPreset.minimalIdentifier, VPhonePatchPreset.watchOSIdentifier]
                    let droppable = Set(
                        [FirmwareBootChainPatchSet.manifest, FirmwareKernelBasePatchSet.manifest, FirmwareKernelCustomFirmwarePatchSet.manifest]
                            .flatMap { $0.patches.map(\.identifier) },
                    )
                    let expected = if tvPresets.contains(preset.identifier) {
                        Set(plan.droppedBootEssentials).isSubset(of: FirmwarePatchSetCatalog.tvOSBlockedPatches)
                    } else if restoreImagePresets.contains(preset.identifier) {
                        Set(plan.droppedBootEssentials).isSubset(of: droppable)
                            && Set(plan.droppedBootEssentials).isDisjoint(with: FirmwarePatchSetCatalog.minimalBootChainPatches)
                    } else {
                        plan.droppedBootEssentials.isEmpty
                    }
                    #expect(
                        expected,
                        "\(preset.identifier) on \(base)/\(cloud) drops \(plan.droppedBootEssentials)",
                    )
                }
            }
        }
    }

    @Test
    func `A preset resolves even when no version could be read`() throws {
        // `fw patch` can run against a tree whose manifests it could not parse.
        // Resolution must still succeed; the version-gated patches simply skip.
        let plan = try VPhonePatchPlan.resolve(
            preset: FirmwarePatchSetCatalog.standardPreset,
            patchSets: FirmwarePatchSetCatalog.bundled,
            iOSBase: nil,
            cloudOS: nil,
        )
        #expect(!plan.enabled.isEmpty)
        #expect(!plan.skippedByVersion.isEmpty)
    }

    @Test
    func `Only minimal and its watch form name the restore image, and patch only iBEC, LLB, the device tree and the research board besides`() throws {
        for preset in FirmwarePatchSetCatalog.builtInPresets {
            let namesRestoreImage = preset.patchSets.map(\.identifier).contains(FirmwareRestoreImagePatchSet.identifier)
            let restoreImagePresets = [VPhonePatchPreset.minimalIdentifier, VPhonePatchPreset.watchOSIdentifier]
            #expect(namesRestoreImage == restoreImagePresets.contains(preset.identifier), "\(preset.identifier)")
        }
        let plan = try VPhonePatchPlan.resolve(
            preset: FirmwarePatchSetCatalog.minimalPreset,
            patchSets: FirmwarePatchSetCatalog.bundled,
            iOSBase: VPhoneVersion("26.4"),
            cloudOS: VPhoneVersion("26.4"),
        )
        // The opt-in patches, like the debugserver re-sign, stay off.
        let restoreImage = FirmwareRestoreImagePatchSet.presetPatches
        #expect(!restoreImage.contains(FirmwareRestoreImagePatchSet.debugserver))
        let researchBoard = Set(FirmwareResearchBoardPatchSet.manifest.patches.map(\.identifier))
        // The unsecure-cache gate stays out: the launchd.plist minimal edits is
        // signed and in the trust cache, so the stock launchd_cache_loader takes it.
        #expect(!plan.isEnabled(FirmwareRestoreImagePatchSet.launchdCacheLoader))
        let bootChain = FirmwarePatchSetCatalog.minimalBootChainPatches
        let allBootChain = Set(FirmwareBootChainPatchSet.manifest.patches.map(\.identifier))
        #expect(bootChain.isSubset(of: allBootChain))
        #expect(plan.enabled == restoreImage.subtracting([FirmwareRestoreImagePatchSet.launchdCacheLoader])
            .union(FirmwarePatchSetCatalog.minimalDeviceTreePatches).union(bootChain).union(researchBoard))
        // A stock LLB does not reach the kernel on an OpenAVB machine: iBEC and
        // LLB stay patched, AVPBooter and iBSS stay stock.
        #expect(plan.enabled.intersection(allBootChain) == bootChain)
        #expect(plan.droppedBootEssentials.allSatisfy { !$0.hasPrefix("ibec-") && !$0.hasPrefix("llb-") })

        let watch = try VPhonePatchPlan.resolve(
            preset: FirmwarePatchSetCatalog.watchOSPreset,
            patchSets: FirmwarePatchSetCatalog.bundled,
            iOSBase: VPhoneVersion("26.4"),
            cloudOS: VPhoneVersion("26.4"),
        )
        #expect(!watch.isEnabled(FirmwareRestoreImagePatchSet.launchdCacheLoader))
        #expect(watch.enabled == restoreImage.subtracting([FirmwareRestoreImagePatchSet.launchdCacheLoader])
            .union(FirmwarePatchSetCatalog.watchOSDeviceTreePatches).union(bootChain).union(researchBoard))
        #expect(watch.enabled.intersection(allBootChain) == bootChain)
    }

    @Test
    func `The presets naming the restore image set include the audio payload`() throws {
        func enabled(_ preset: VPhonePatchPreset) throws -> Set<String> {
            try VPhonePatchPlan.resolve(
                preset: preset,
                patchSets: FirmwarePatchSetCatalog.bundled,
                iOSBase: VPhoneVersion("26.4"),
                cloudOS: VPhoneVersion("26.4"),
            ).enabled
        }

        let namesRestoreImage: Set<String> = [
            VPhonePatchPreset.minimalIdentifier,
            VPhonePatchPreset.watchOSIdentifier,
        ]
        
        for preset in FirmwarePatchSetCatalog.builtInPresets {
            let resolved = try enabled(preset)
            #expect(
                resolved.contains(FirmwareRestoreImagePatchSet.watchAudio)
                    == namesRestoreImage.contains(preset.identifier),
                "\(preset.identifier)",
            )
        }
    }

    @Test
    func `The watch audio payload stays selected across supported bases`() throws {
        for base in ["26.4", "26.5", "27.0"] {
            let plan = try VPhonePatchPlan.resolve(
                preset: FirmwarePatchSetCatalog.watchOSPreset,
                patchSets: FirmwarePatchSetCatalog.bundled,
                iOSBase: VPhoneVersion(base), cloudOS: VPhoneVersion("26.4"),
            )
            #expect(plan.enabled.contains(FirmwareRestoreImagePatchSet.watchAudio))
        }
    }

    @Test
    func `Userspace debugging resolves on every preset but Apple TV, taking the debugserver its sets deliver`() throws {
        let feature = FirmwarePatchSetCatalog.userspaceDebugging
        let declared = Set(FirmwarePatchSetCatalog.allDeclarations.map(\.identifier))
        #expect(feature.allPatches.isSubset(of: declared))
        let restoreImage = [VPhonePatchPreset.minimalIdentifier, VPhonePatchPreset.watchOSIdentifier]
        // cfw install refuses the debugserver and launchd patches on an Apple TV
        // and on HomeView.
        let appleTV = [VPhonePatchPreset.tvOSIdentifier, VPhonePatchPreset.tvOS4KIdentifier, VPhonePatchPreset.homeViewIdentifier]
        for preset in FirmwarePatchSetCatalog.builtInPresets {
            if appleTV.contains(preset.identifier) {
                #expect(feature.patches(in: preset) == nil, "\(preset.identifier)")
                continue
            }
            let patches = try #require(feature.patches(in: preset), "\(preset.identifier)")
            let debugserver = restoreImage.contains(preset.identifier)
                ? FirmwareRestoreImagePatchSet.debugserver : "system-debugserver-cfw-install"
            #expect(patches.contains(debugserver), "\(preset.identifier)")
            #expect(patches.count == feature.parts.count, "\(preset.identifier)")
            // Allowing them resolves.
            _ = try VPhonePatchPlan.resolve(
                preset: preset,
                patchSets: FirmwarePatchSetCatalog.bundled,
                iOSBase: VPhoneVersion("26.4"),
                cloudOS: VPhoneVersion("26.4"),
                allowed: patches,
            )
        }

        for preset in [FirmwarePatchSetCatalog.minimalPreset, FirmwarePatchSetCatalog.watchOSPreset] {
            let patches = try #require(feature.patches(in: preset))
            for base in ["18.6.2", "26.4"] {
                let plain = try VPhonePatchPlan.resolve(
                    preset: preset,
                    patchSets: FirmwarePatchSetCatalog.bundled,
                    iOSBase: VPhoneVersion(base),
                    cloudOS: VPhoneVersion("26.4"),
                )
                let debugging = try VPhonePatchPlan.resolve(
                    preset: preset,
                    patchSets: FirmwarePatchSetCatalog.bundled,
                    iOSBase: VPhoneVersion(base),
                    cloudOS: VPhoneVersion("26.4"),
                    allowed: patches,
                )
                // The plain preset keeps a stock kernel; the feature adds only its own.
                let kernelSets = [FirmwareKernelBasePatchSet.manifest, FirmwareKernelCustomFirmwarePatchSet.manifest]
                    .flatMap { $0.patches.map(\.identifier) }
                #expect(plain.enabled.isDisjoint(with: kernelSets), "\(preset.identifier) \(base)")
                #expect(debugging.enabled.subtracting(plain.enabled).isSubset(of: patches), "\(preset.identifier) \(base)")
                #expect(debugging.enabled.union(debugging.skippedByVersion).isSuperset(of: patches), "\(preset.identifier) \(base)")
            }
        }
    }

    @Test
    func `Standard turns userspace debugging on whole, so no box is offered there`() throws {
        let preset = FirmwarePatchSetCatalog.standardPreset
        let named = Set(preset.patchSets.map(\.identifier))
        let standard = Set(FirmwarePatchSetCatalog.bundled.filter { named.contains($0.identifier) }
            .flatMap(\.patches).map(\.identifier).filter { preset.selection.includes($0) })
        let patches = try #require(FirmwarePatchSetCatalog.userspaceDebugging.patches(in: preset))
        #expect(patches.isSubset(of: standard), "\(patches.subtracting(standard).sorted())")
    }

    @Test
    func `Standard leaves every manual-only patch off, on every base`() throws {
        for base in ["18.6.2", "26.4", "27.0"] {
            let plan = try VPhonePatchPlan.resolve(
                preset: FirmwarePatchSetCatalog.standardPreset,
                patchSets: FirmwarePatchSetCatalog.bundled,
                iOSBase: VPhoneVersion(base),
                cloudOS: VPhoneVersion("26.4"),
            )
            for identifier in FirmwarePatchSetCatalog.manualOnlyPatches {
                #expect(!plan.isEnabled(identifier), "standard enabled \(identifier) on \(base)")
            }
        }
    }

    @Test
    func `Extended adds the applicable manual patches except device-specific repairs`() throws {
        for base in ["18.6.2", "26.4", "27.0", "27.1", "27.2"] {
            let version = VPhoneVersion(base)
            let cloud = VPhoneVersion("26.4")
            let standard = try VPhonePatchPlan.resolve(
                preset: FirmwarePatchSetCatalog.standardPreset,
                patchSets: FirmwarePatchSetCatalog.bundled,
                iOSBase: version,
                cloudOS: cloud,
            )
            let experimental = try VPhonePatchPlan.resolve(
                preset: FirmwarePatchSetCatalog.experimentalPreset,
                patchSets: FirmwarePatchSetCatalog.bundled,
                iOSBase: version,
                cloudOS: cloud,
            )
            let applicableManual = Set(FirmwarePatchSetCatalog.allDeclarations.filter {
                FirmwarePatchSetCatalog.manualOnlyPatches.contains($0.identifier)
                    && $0.identifier != FirmwareGuestSystemPatchSet.homeViewProfileLookup
                    && $0.identifier != FirmwareGuestSystemPatchSet.homeViewDisplayLookups
                    && $0.identifier != FirmwareGuestSystemPatchSet.homeViewSetupBypass
                    && $0.identifier != FirmwareGuestSystemPatchSet.homeViewEnvironmentService
                    && $0.identifier != FirmwareGuestSystemPatchSet.homePodTopCap
                    && $0.identifier != FirmwareGuestSystemPatchSet.homePodSetupBypass
                    && $0.identifier != FirmwareGuestSystemPatchSet.homePodWelcome
                    && $0.identifier != FirmwareGuestSystemPatchSet.homePodSiriSpeech
                    && $0.identifier != FirmwareGuestSystemPatchSet.homePodAudioProduct
                    && $0.identifier != FirmwareGuestSystemPatchSet.homePodOTAUserland
                    && $0.identifier != FirmwareGuestSystemPatchSet.homePodSoundGlow
                    && $0.identifier != FirmwareGuestSystemPatchSet.tvSetupDisplayLookup
                    && $0.identifier != FirmwareGuestSystemPatchSet.tvSetupFocus
                    && $0.identifier != FirmwareGuestSystemPatchSet.tvLocalActivation
                    && $0.identifier != FirmwareGuestSystemPatchSet.tvLegacySetup
                    && $0.identifier != FirmwareGuestSystemPatchSet.homePodCryptexStaging
                    && $0.identifier != FirmwareGuestSystemPatchSet.homePodCryptexClass
                    && $0.identifier != FirmwareGuestSystemPatchSet.homePodAdHocInstall
                    && $0.applicability.matches(iOSBase: version, cloudOS: cloud)
            }.map(\.identifier))
            #expect(experimental.enabled.subtracting(standard.enabled) == applicableManual)
            #expect(standard.enabled.subtracting(experimental.enabled).isEmpty)
            #expect(experimental.isEnabled(FirmwareGuestSystemPatchSet.settingsRootRows) == (base == "27.0"))
            #expect(experimental.isEnabled(FirmwareGuestSystemPatchSet.settingsSoftwareUpdate) == (base == "27.0"))
        }
    }

    @Test
    func `The two patches pinned by release are off everywhere else`() throws {
        // These two were flags once (`--force-exc-guard`, `--force-dsc-maxslide`).
        // They are now pinned to the release that needs them, so a base that does
        // not need them never gets them from a preset.
        let pinned = ["kernel-boot-thread_guard_violation": 18, "dyld-boot-maxslide": 27]
        for (identifier, requiredMajor) in pinned {
            for base in [18, 26, 27] {
                let plan = try VPhonePatchPlan.resolve(
                    preset: FirmwarePatchSetCatalog.experimentalPreset,
                    patchSets: FirmwarePatchSetCatalog.bundled,
                    iOSBase: VPhoneVersion("\(base).0"),
                    cloudOS: VPhoneVersion("26.4"),
                )
                #expect(
                    plan.isEnabled(identifier) == (base == requiredMajor),
                    "\(identifier) on iOS \(base) should be \(base == requiredMajor)",
                )
            }
        }
    }

    @Test
    func `Standard opens the paravirtual user clients on every base`() throws {
        // A daemon has to reach the paravirtual GPU: cameracaptured prewarms its
        // shaders at boot and crash-loops without it. Before 27 that is the narrow
        // allowlist; on 27 the broad gate is boot-essential and opens everything, so
        // the narrow patch skips by version there rather than being blocked.
        let narrow = FirmwarePatchSetCatalog.paravirtUserClientsPatch
        let broad = "kernel-boot-iouc_sandbox_gate"
        #expect(!FirmwarePatchSetCatalog.manualOnlyPatches.contains(narrow))
        #expect(FirmwarePatchSetCatalog.standardPreset.selection.includes(narrow))
        for base in ["18.6.2", "26.0", "26.4", "26.6.2", "27.0"] {
            for cloud in ["26.1", "26.4"] {
                let plan = try VPhonePatchPlan.resolve(
                    preset: FirmwarePatchSetCatalog.standardPreset,
                    patchSets: FirmwarePatchSetCatalog.bundled,
                    iOSBase: VPhoneVersion(base),
                    cloudOS: VPhoneVersion(cloud),
                )
                let is27 = base.hasPrefix("27.")
                #expect(plan.isEnabled(narrow) == !is27, "\(narrow) on \(base)/\(cloud)")
                #expect(plan.skippedByVersion.contains(narrow) == is27, "\(narrow) on \(base)/\(cloud)")
                #expect(plan.isEnabled(broad) == is27, "\(broad) on \(base)/\(cloud)")
            }
        }
    }

    @Test
    func `Standard turns ProMotion on, on every base`() throws {
        let patch = FirmwarePatchSetCatalog.proMotionPatch
        #expect(!FirmwarePatchSetCatalog.manualOnlyPatches.contains(patch))
        #expect(FirmwarePatchSetCatalog.standardPreset.selection.includes(patch))
        for base in ["18.6.2", "26.0", "26.4", "26.6.2", "27.0"] {
            for cloud in ["26.1", "26.4"] {
                let plan = try VPhonePatchPlan.resolve(
                    preset: FirmwarePatchSetCatalog.standardPreset,
                    patchSets: FirmwarePatchSetCatalog.bundled,
                    iOSBase: VPhoneVersion(base),
                    cloudOS: VPhoneVersion(cloud),
                )
                #expect(plan.isEnabled(patch), "\(patch) on \(base)/\(cloud)")
            }
        }
        // A VM that blocks it keeps the host's 60 Hz.
        let blocked = try VPhonePatchPlan.resolve(
            preset: FirmwarePatchSetCatalog.standardPreset,
            patchSets: FirmwarePatchSetCatalog.bundled,
            iOSBase: VPhoneVersion("27.0"),
            cloudOS: VPhoneVersion("26.4"),
            blocked: [patch],
        )
        #expect(!blocked.isEnabled(patch))
    }

    @Test
    func `Standard enables persistent GPU caches while explicit blocks and tvOS stay off`() throws {
        let patch = FirmwarePatchSetCatalog.paravirtTask3Patch
        let guest = FirmwareGuestSystemPatchSet.metalCacheReuse
        let standard = try VPhonePatchPlan.resolve(
            preset: FirmwarePatchSetCatalog.standardPreset,
            patchSets: FirmwarePatchSetCatalog.bundled,
            iOSBase: VPhoneVersion("27.0.1"), cloudOS: VPhoneVersion("26.4"),
        )
        #expect(standard.isEnabled(patch))
        #expect(standard.isEnabled(guest))
        // Existing records use the experimental identifier. A saved opt-out
        // must still win when the preset now turns the renamed patch on.
        let blocked = try VPhonePatchPlan.resolve(
            preset: FirmwarePatchSetCatalog.standardPreset,
            patchSets: FirmwarePatchSetCatalog.bundled,
            iOSBase: VPhoneVersion("27.0.1"), cloudOS: VPhoneVersion("26.4"),
            blocked: Set(FirmwarePatchSetCatalog.currentIdentifiers(["kernel-exp-paravirt_gpu_task3"])),
        )
        #expect(!blocked.isEnabled(patch))
        // The kernel anchors exist only in cloudOS 26.4; earlier kernels must
        // not select a patch whose discovery would abort the kernel install.
        for (iOS, cloudOS) in [("18.6.2", "26.1"), ("26.2", "26.2"), ("26.3.1", "26.3")] {
            let plan = try VPhonePatchPlan.resolve(
                preset: FirmwarePatchSetCatalog.standardPreset,
                patchSets: FirmwarePatchSetCatalog.bundled,
                iOSBase: VPhoneVersion(iOS), cloudOS: VPhoneVersion(cloudOS),
            )
            #expect(!plan.isEnabled(patch))
        }
        for preset in [FirmwarePatchSetCatalog.tvOSPreset, FirmwarePatchSetCatalog.tvOS4KPreset, FirmwarePatchSetCatalog.homePodMiniPreset] {
            let plan = try VPhonePatchPlan.resolve(
                preset: preset, patchSets: FirmwarePatchSetCatalog.bundled,
                iOSBase: VPhoneVersion("27.0"), cloudOS: VPhoneVersion("26.4"),
            )
            #expect(!plan.isEnabled(patch))
            #expect(!plan.isEnabled(guest))
        }
    }

    @Test(arguments: [FirmwareGuestSystemPatchSet.glesUpperLeft, FirmwareGuestSystemPatchSet.metalVertexIDFormat,
                     FirmwareGuestSystemPatchSet.glesPrimitiveRestart, FirmwareGuestSystemPatchSet.glesPointDraw,
                     FirmwareGuestSystemPatchSet.paravirtGPUCompilerCache, FirmwareGuestSystemPatchSet.metalCacheReuseKey])
    func `Native GLES corrections follow the measured OS pair and can be reverted`(patch: String) throws {
        for base in ["26.4", "26.5", "26.6", "26.6.2", "26.7", "27.0.1", "unknown"] {
            for cloud in ["26.1", "26.4", "26.5", "unknown"] {
                let plan = try VPhonePatchPlan.resolve(
                    preset: FirmwarePatchSetCatalog.standardPreset,
                    patchSets: FirmwarePatchSetCatalog.bundled,
                    iOSBase: VPhoneVersion(base), cloudOS: VPhoneVersion(cloud),
                )
                let supported = (base == "26.6" || base == "26.6.2") && cloud == "26.4"
                #expect(plan.isEnabled(patch) == supported, "\(base)/\(cloud)")
                let updated = FirmwareGuestPatchResolution.effectiveEnabled(
                    planEnabled: [], selectionEnabled: plan.enabled,
                )
                #expect(updated.contains(patch) == supported, "A guest update must include new patches absent from the boot plan")
            }
        }
        let blocked = try VPhonePatchPlan.resolve(
            preset: FirmwarePatchSetCatalog.standardPreset,
            patchSets: FirmwarePatchSetCatalog.bundled,
            iOSBase: VPhoneVersion("26.6.2"), cloudOS: VPhoneVersion("26.4"),
            blocked: [patch],
        )
        #expect(!blocked.isEnabled(patch))
        #expect(FirmwareGuestPatchResolution.guestPatchesOff(selectionEnabled: blocked.enabled).contains(patch))
        #expect(!FirmwareGuestPatchResolution.effectiveEnabled(
            planEnabled: [patch], selectionEnabled: blocked.enabled,
        ).contains(patch))
        let unsupported = try VPhonePatchPlan.resolve(
            preset: FirmwarePatchSetCatalog.standardPreset,
            patchSets: FirmwarePatchSetCatalog.bundled,
            iOSBase: VPhoneVersion("27.0.1"), cloudOS: VPhoneVersion("26.4"),
            allowed: [patch],
        )
        #expect(!unsupported.isEnabled(patch), "An explicit selection must not widen the version gate")
        // Test the preset exclusions on the applicable pair so the version
        // gate cannot hide an accidentally missing block-list entry.
        for preset in [FirmwarePatchSetCatalog.tvOSPreset, FirmwarePatchSetCatalog.tvOS4KPreset,
                       FirmwarePatchSetCatalog.homePodMiniPreset, FirmwarePatchSetCatalog.homeViewPreset] {
            let plan = try VPhonePatchPlan.resolve(
                preset: preset, patchSets: FirmwarePatchSetCatalog.bundled,
                iOSBase: VPhoneVersion("26.6.2"), cloudOS: VPhoneVersion("26.4"),
            )
            #expect(!plan.isEnabled(patch), "\(preset.identifier)")
        }
    }

    @Test
    func `The iOS 18 GPU transport follows the measured OS pair`() throws {
        let patch = FirmwareGuestSystemPatchSet.ios18GPUTransport
        for base in ["18.1", "18.5", "18.6", "18.6.2", "18.7.2", "26.1", "unknown"] {
            for cloud in ["18.6", "26.1", "26.4", "unknown"] {
                let plan = try VPhonePatchPlan.resolve(
                    preset: FirmwarePatchSetCatalog.standardPreset,
                    patchSets: FirmwarePatchSetCatalog.bundled,
                    iOSBase: VPhoneVersion(base), cloudOS: VPhoneVersion(cloud),
                )
                let supported = (base == "18.6" || base == "18.6.2") && cloud == "26.1"
                #expect(plan.isEnabled(patch) == supported, "\(base)/\(cloud)")
            }
        }
        for preset in [FirmwarePatchSetCatalog.tvOSPreset, FirmwarePatchSetCatalog.tvOS4KPreset,
                       FirmwarePatchSetCatalog.homePodMiniPreset, FirmwarePatchSetCatalog.homeViewPreset] {
            let plan = try VPhonePatchPlan.resolve(
                preset: preset, patchSets: FirmwarePatchSetCatalog.bundled,
                iOSBase: VPhoneVersion("18.6.2"), cloudOS: VPhoneVersion("26.1"),
            )
            #expect(!plan.isEnabled(patch), "\(preset.identifier)")
        }
    }

    @Test
    func `Standard names the GLES renderer on every base while tvOS stays off`() throws {
        let patch = FirmwarePatchSetCatalog.paravirtGLESPatch
        #expect(!FirmwarePatchSetCatalog.manualOnlyPatches.contains(patch))
        for base in ["18.6.2", "26.4", "26.6.2", "27.0.1"] {
            for cloud in ["26.1", "26.4"] {
                let plan = try VPhonePatchPlan.resolve(
                    preset: FirmwarePatchSetCatalog.standardPreset,
                    patchSets: FirmwarePatchSetCatalog.bundled,
                    iOSBase: VPhoneVersion(base), cloudOS: VPhoneVersion(cloud),
                )
                #expect(plan.isEnabled(patch), "\(patch) on \(base)/\(cloud)")
            }
        }
        for preset in [FirmwarePatchSetCatalog.tvOSPreset, FirmwarePatchSetCatalog.tvOS4KPreset, FirmwarePatchSetCatalog.homePodMiniPreset] {
            let plan = try VPhonePatchPlan.resolve(
                preset: preset, patchSets: FirmwarePatchSetCatalog.bundled,
                iOSBase: VPhoneVersion("27.0"), cloudOS: VPhoneVersion("26.4"),
            )
            #expect(!plan.isEnabled(patch))
        }
    }

    @Test
    func `A renamed patch maps to one the catalogue declares`() {
        let declared = Set(FirmwarePatchSetCatalog.allDeclarations.map(\.identifier))
        for (old, new) in FirmwarePatchSetCatalog.renamedPatches {
            #expect(!declared.contains(old), "\(old) is still declared")
            #expect(declared.contains(new), "\(old) maps to \(new), which nothing declares")
        }
        // Records using an old identifier, possibly beside its replacement,
        // read as the new one, once, in place.
        #expect(
            FirmwarePatchSetCatalog.currentIdentifiers([
                "kernel-exp-hv_vmm",
                "kernel-exp-display_refresh_120hz",
                FirmwarePatchSetCatalog.proMotionPatch,
                "kernel-exp-paravirt_gpu_task3",
                FirmwarePatchSetCatalog.paravirtTask3Patch,
            ]) == ["kernel-exp-hv_vmm", FirmwarePatchSetCatalog.proMotionPatch, FirmwarePatchSetCatalog.paravirtTask3Patch],
        )
    }

    @Test
    func `Frida gates retain the measured cloudOS 26.1 syscall filter exception`() throws {
        for cloud in ["26.1", "26.4"] {
            let plan = try VPhonePatchPlan.resolve(
                preset: FirmwarePatchSetCatalog.experimentalPreset,
                patchSets: FirmwarePatchSetCatalog.bundled,
                iOSBase: VPhoneVersion("26.4"),
                cloudOS: VPhoneVersion(cloud),
            )
            let on = FirmwareKernelFridaPatchSet.manifest.patches.allSatisfy {
                plan.isEnabled($0.identifier)
            }
            #expect(on == (cloud == "26.4"))
            #expect(plan.isEnabled("kernel-exp-frida_syscall_filter_off"))
            let standard = try VPhonePatchPlan.resolve(
                preset: FirmwarePatchSetCatalog.standardPreset, patchSets: FirmwarePatchSetCatalog.bundled,
                iOSBase: VPhoneVersion("16.6.1"), cloudOS: VPhoneVersion(cloud)
            )
            #expect(!standard.isEnabled("kernel-exp-frida_syscall_filter_off"))
        }
    }

    @Test
    func `The hv_vmm_present patches move together, and only experimental has them`() throws {
        // Three patches, one behaviour: the kernel OID rename, the shared-cache
        // mangle and the watchdogd cache patch. A plan holding some without the
        // rest is broken — the rename alone breaks the graphics and ML paths and
        // panics watchdogd, the others alone do nothing — and all together brick a
        // freshly restored 26.4 guest, which is why standard has none. See
        // FirmwareKernelHypervisorPatchSet.
        let pair = FirmwarePatchSetCatalog.hypervisorConcealmentPatches
        #expect(pair.count == 3)
        for identifier in pair {
            let declaration = try #require(
                FirmwarePatchSetCatalog.allDeclarations.first { $0.identifier == identifier },
                "\(identifier) is not declared by any bundled set",
            )
            // Not boot-essential: standard drops both, and a shipped preset that
            // drops a boot-essential patch warns on every run.
            #expect(!declaration.bootEssential)
        }
        for base in ["18.6.2", "26.4", "27.0"] {
            for cloud in ["26.1", "26.4"] {
                for preset in FirmwarePatchSetCatalog.builtInPresets {
                    let plan = try VPhonePatchPlan.resolve(
                        preset: preset,
                        patchSets: FirmwarePatchSetCatalog.bundled,
                        iOSBase: VPhoneVersion(base),
                        cloudOS: VPhoneVersion(cloud),
                    )
                    let on = pair.filter { plan.isEnabled($0) }
                    #expect(
                        on.isEmpty || on == pair,
                        "\(preset.identifier) on \(base)/\(cloud) enabled only \(on)",
                    )
                    #expect(on.isEmpty == (preset.identifier != "experimental"))
                }
            }
        }
    }

    @Test
    func `Every set's manifest survives a plist round trip`() throws {
        for manifest in FirmwarePatchSetCatalog.bundled {
            let decoded = try VPhonePatchSetManifest.decode(manifest.encodedPlist())
            #expect(decoded == manifest, "\(manifest.identifier) did not round trip")
        }
    }

    @Test
    func `Every built-in preset survives a plist round trip`() throws {
        for preset in FirmwarePatchSetCatalog.builtInPresets {
            #expect(try VPhonePatchPreset.decode(preset.encodedPlist()) == preset)
        }
    }

    @Test
    func `The shipped preset plists match the built-in copies`() throws {
        // The bundle reads the plists; a dev build falls back to the Swift copies.
        // They have to agree, or a VM built from an Xcode build and a VM built from
        // a staged bundle would get different patches.
        let directory = URL(fileURLWithPath: #filePath)
            .deletingLastPathComponent() // PatchSets
            .deletingLastPathComponent() // FirmwarePatcherTests
            .deletingLastPathComponent() // VPhoneCommand
            .deletingLastPathComponent() // VPhoneExecutable/VPhoneCommand
            .appendingPathComponent("VPhoneVirtualization/Resources/patches_presets", isDirectory: true)
        let shipped = try VPhonePatchPreset.readAll(fromDirectory: directory)
        #expect(shipped.count == FirmwarePatchSetCatalog.builtInPresets.count)
        for builtIn in FirmwarePatchSetCatalog.builtInPresets {
            let match = shipped.first { $0.identifier == builtIn.identifier }
            if match != builtIn, let match,
               case let .block(shippedBlocked) = match.selection,
               case let .block(builtInBlocked) = builtIn.selection {
                let missing = builtInBlocked.subtracting(shippedBlocked).sorted()
                let extra = shippedBlocked.subtracting(builtInBlocked).sorted()
                #expect(match == builtIn, "\(builtIn.identifier).plist differs from the built-in copy — plist missing: \(missing), plist extra: \(extra)")
            } else {
                #expect(match == builtIn, "\(builtIn.identifier).plist differs from the built-in copy")
            }
        }
    }

    @Test
    func `Standard comes first in a picker`() {
        #expect(FirmwarePatchSetCatalog.builtInPresets.first?.isStandard == true)
    }

    @Test
    func `No bundled set is external, so root cfw install never loads a file`() {
        for preset in FirmwarePatchSetCatalog.builtInPresets {
            #expect(!preset.usesExternalPatchSets)
        }
    }
}