Skip to content

Run a virtual iPhone on an Apple Silicon Mac.

Swift
119 KB
Raw Blame
// CustomFirmwareVirtualAudio.swift — keep `No default VAD present` from
// terminating audiomxd.
//
// VirtualAudio walks the current port list applying speaker protection and the
// DSP chain whenever a property write arrives that touches the route (most
// visibly MediaExperience's VAD serialization listener, which pushes saved
// route and volume state on every launch and on every route change). The
// walker needs a `vdef` virtual audio device to apply anything to; when the
// speaker port is published by a device that is not one of VirtualAudio's own
// — the virtio sound device publishing as `PuffinOutput`, whose `pspk` speaker
// port is what makes playback routable in a vphone guest at all — the list it
// is handed can hold no `vdef`, and the walker answers that with
// `throw std::runtime_error("No default VAD present")`.
//
// The throw sits inside an AudioServerPlugIn property callback, which is a C
// boundary that cannot propagate C++ exceptions: the exception reaches
// `std::terminate` and audiomxd aborts. The saved serialization state then
// replays the same write into every later launch, so one abort becomes a
// crash loop until the guest is rebooted.
//
// The walker holds five exception sites — "No default VAD present", two
// "Could not construct" (each behind a routing-mutex assertion), "Unexpected
// HAL speaker protection ... *VP* speaker protection", and a generic
// "Precondition failure." — every one unreachable on real hardware, where the
// built-in speaker is a codec the routing layer grew up with. A guest whose
// speaker arrives any other way reaches them all.
//
// The patch rewrites the first instruction of each throw block — the `mov w0,
// #<size>` that sizes the exception allocation — into a branch to the
// function's own epilogue, so each condition degrades to "apply nothing and
// return". The diagnostic logs that precede the throws are left intact.
//
// Anchoring
// ---------
// Nothing is a literal address. The site is found from the C string
// `No default VAD present`, which the code references exactly twice: once as
// the os_log format's argument (x3) and once as the `runtime_error`
// constructor's message argument (x1), the second reference being the throw
// site. Both references must resolve, and the ctor reference must be the one
// whose `add` is followed by a call. The throw block is then read backwards
// from there: `bl` (the exception allocation) preceded by `movz w0, #imm`.
// The epilogue is found forwards from the `___cxa_throw` call as the stack-
// guard-checked pop sequence ending in `retab`, and its shape is verified
// instruction by instruction before the branch is encoded.
//
// An arm64e.x1 userland (iOS 27.1 on iPhone19,4) is built with FEAT_PAuth_LR:
// functions open with `pacibsppc` and return with `retabsppc <label>`, whose
// label names the `pacibsppc` that signed. The plugin is patched in that
// native form, so a prologue is either signing instruction and an epilogue
// ends in either return, and a `retabsppc` must name the prologue of the
// function the patch walked — the epilogue is the function's own.
//
// The mute-set throw
// ------------------
// Establishing the route also asks the HAL device itself to unmute:
// Device_HAL_Common's set wrapper pushes `kAudioDevicePropertyMute` through
// `AudioObjectSetPropertyData` and reads it back. iOS's HAL server rejects a
// device-level mute on a plugin device with 'what' without ever forwarding
// the selector to the driver — ASDAudioDevice's dispatch has no case for it
// — and the wrapper answers any failed set by throwing a CAException out of
// the callback. RoutingManager catches it and abandons the route, which
// leaves the vdef's aggregate on Null_Device and the guest silent. Every
// caller of the wrapper ignores its return value, so skipping the throw is
// safe: the FAIL and EXCEPTION diagnostics still log, and the route proceeds
// as if the mute had held.
//
// Anchored on the mute-set log ("Set mute value of %u on HAL device"), whose
// single `__text` reference sits in the wrapper's selector dispatch. Within
// the wrapper, the site is the CAException throw block — the exception
// allocation, the status stored into the object, the throw call — that has
// the "Unable to set property data." EXCEPTION log a few instructions above
// it; iOS 27's wrapper holds a second, unrelated CAException (the
// deactivated-device throw), and that log window is what tells them apart.
// The epilogue is the wrapper's single `retab` (`retabsppc` on X1), walked
// back to its entry.
//
// The speaker-protection gate
// ---------------------------
// With the walker and the mute-set throw quieted, a route change still
// declines at the last step: RoutingHandler_Playback_GenericConfig1 builds
// the whole route — virtual stream, DSP chain, format match — and then
// rejects it because the route's device list calls for HAL Speaker
// Protection, a capability only a physical codec reports. The capability
// query never leaves VirtualAudio, so no plugin can provide it. The decline
// is a log line and a branch to the handler's failure path, which leaves the
// vdef's output stream on Null_Device: every "playing" signature is genuine
// and nothing is audible, volume included.
//
// Anchored on the decline's log format, a message three routing handlers
// share — ours is the handler whose log block also names
// RoutingHandler_Playback_GenericConfig1.cpp. The gate's branch is left as
// it is; what changes is the log block it jumps to, whose opening
// instruction — the `mov w0, #<size>` sizing the os_log — becomes a branch
// back to the gate's own fall-through. A taken gate now lands on the
// success path the handler already built, which never reads the verdict
// the gate tested, on either supported build. The block is entered only by
// the gate's jump — the instruction above its head is an unconditional
// branch, checked before anything is written — so no fall-through is
// orphaned, and leaving the gate's branch intact is what lets the anchor
// find the site again on an already-patched binary.
//
// RoutingHandler_PlaybackAndRecord_GenericConfig1 holds the same gate in the
// same shape, and a route that plays and records ('cpar', what a recording
// app asks for) is declined by it once the guest has a microphone port to
// build that route with. It is the patch's second site, found by that
// handler's own file name. Its volume-mode test is a plain branch between
// two ways of building the route, not a precondition, and needs nothing.
//
// The volume-mode precondition
// ----------------------------
// The gate opened; the route survives its own construction and dies one
// step later on a precondition. The handler asks the volume-mode lookup for
// the route's default scope and requires a packed (present,
// kHardwareOnlyReadOnly) pair back; a device whose software volume runs any
// other mode — the virtio plugin's reports SoftwareHardwareMix — fails the
// test, and the handler answers a `std::logic_error` that unwinds into
// RoutingManager, which fails the route and tears the session down onto
// Null_Device. Same silence as the gate produced, one layer later: by then
// the route had already built its DSP chain, its virtual stream and an
// IOProc on the virtio aggregate.
//
// The precondition's own text survives only in the iOS 27 build
// ("softwareVolumeModeForPerDefaultScope.has_value() && … ==
// kHardwareOnlyReadOnly"); iPadOS 26 stripped it to a bare "Precondition
// failure.". What identifies the site on both builds is the test itself:
// the handler masks the lookup's return with the 33-bit packing mask
// (`and xN, xM, #0x1ffffffff` — a present flag in bit 32 above the mode's
// low 32 bits), compares it against the expected pair, and branches to the
// decline on inequality. Two sibling preconditions in the same handler
// branch off plain flag tests, so the mask is what tells the declines
// apart. The write is the one the speaker-protection gate performs: the
// comparison stays intact, and the decline's log block head becomes a
// branch back to the comparison's fall-through, which reloads everything
// it reads from memory and never re-reads the value the test examined, on
// either supported build.
//
// The device-state null gate
// --------------------------
// With the route quieted end to end, one ordering fault is left, and it
// belongs to the arm64e.x1 build alone. Publishing the route wakes
// VirtualAudio_Device's update, which asks DeviceStateManager for its
// singleton twice — each ask behind its own capability gate — and pushes
// the route's state into the manager. On a guest the singleton never
// exists: deferred initialization is dispatched at plugin init, but on a
// machine with no haptic hardware it leaves without constructing the
// manager (no "Ending Deferred Initialization" is ever logged, and no
// thread is parked inside it when the fault lands — it exits early),
// because the manager is a haptics-domain object whose construction the
// actuator the wait loop polls for belongs to. Asked for an instance
// nobody published, TheInstance() logs "TheInstance() called before
// SetInstance()" and returns null, and the update dereferences that null
// — the audiomxd crash on an iPhone Duo guest, whenever a push arrives
// after the gates answer true (observed from ~10 s to ~130 s in).
//
// The patch makes each update wait for the manager to exist: the
// gate-check call above each `cbz w0, <skip>` is redirected to
// TheInstance itself, so the branch the function already carries — the
// one that skips the update when its check answers false — now tests the
// singleton. Null manager: the update is skipped through the function's
// own path, exactly as on any build whose gates answer false. Manager
// present: the fall-through re-calls TheInstance and the whole update —
// the save, the dereference, the lock, the push — runs untouched, as
// designed. Nothing is removed: the update happens whenever there is a
// manager to receive it, which is the most this code can do on a machine
// whose manager cannot be constructed, and everything it does on one
// whose manager can.
//
// Anchoring: the singleton is found from its own diagnostic — the
// "TheInstance() called before SetInstance()" log format, referenced once
// in __text; the prologue above that reference is TheInstance's entry.
// Every direct `bl` to that entry is filtered to the gated shape both
// device-state updates share: a call at −8, the `cbz w0` at −4 skipping
// forward past the whole update, the singleton's return moved aside at +4
// (`mov xN, x0`), and that return dereferenced unchecked at +8 (`ldr xM,
// [x0]`) — the instruction that faults. Exactly two callers carry the
// shape; both gate-check calls are redirected. A build with a different
// count is refused, not half-patched. The plugin is touched only where
// iOS 27.1's arm64e.x1 build carries the fault: a header check (cputype
// arm64, cpusubtype 12 — 26.x and 27.0 are cpusubtype 2) reports
// "nothing to do" on every other build, so their bytes never move.

import Foundation
import VPhonePatchKit

/// Turns VirtualAudio's `No default VAD present` exception into a no-op
/// return, so a speaker route published by the virtio device cannot abort
/// audiomxd.
public enum CustomFirmwareVirtualAudio {
    // MARK: - Identity

    /// The exception message, and the anchor string.
    public static let message = "No default VAD present"

    /// The fault log that precedes the walker's direct `std::terminate` call.
    public static let terminateFault = "Speaker Protection is not active on speaker route"

    /// Component name for the patch records.
    public static let component = "virtualaudio"

    /// Record identity, tying the emitted record to its patch-set declaration.
    public static let patchID = "system-virtualaudio-cfw-speaker_route_throws"

    /// The mute-set log format, and the anchor for the set wrapper's patch.
    /// Its full text carries the selector and scope; the needle stops where
    /// the format stays stable across builds.
    public static let muteSetMessage = "Set mute value of %u on HAL device"

    /// The EXCEPTION diagnostic whose log must sit just above the mute-set
    /// throw, telling it apart from the wrapper's other CAException (the
    /// deactivated-device throw iOS 27 builds in).
    public static let muteSetException = "Unable to set property data."

    /// Record identity for the mute-set patch.
    public static let muteSetPatchID = "system-virtualaudio-cfw-mute_set_throw"

    /// The route-decline log format, and the anchor for the SP-gate patch.
    /// Its full text carries the route it declines; the needle stops where
    /// the format stays stable across builds.
    public static let spGateMessage = "HAL Speaker Protection is missing. Failing route"

    /// The routing handler the SP-gate patch targets, named by its own log:
    /// three handlers share the decline's format, and this file's string is
    /// the one the ringtone ('crnp') reconfiguration route runs through.
    public static let spGateFile = "RoutingHandler_Playback_GenericConfig1.cpp"

    /// The handlers whose SP gate the patch opens. A route that plays and
    /// records ('cpar', what a recording app asks for) runs through the
    /// second, which declines it for the same missing capability once a
    /// microphone port makes the route buildable at all.
    public enum SPGateHandler: String, Sendable, CaseIterable {
        case playback
        case playbackAndRecord

        /// The handler's source-file string, which its log blocks reference.
        public var file: String {
            switch self {
            case .playback: spGateFile
            case .playbackAndRecord: "RoutingHandler_PlaybackAndRecord_GenericConfig1.cpp"
            }
        }

        /// The record this handler's write emits: the declaration's own
        /// identifier, or a site of it.
        public var patchID: String {
            switch self {
            case .playback: spGatePatchID
            case .playbackAndRecord: spGatePatchID + ".playback_and_record"
            }
        }
    }

    /// Record identity for the SP-gate patch.
    public static let spGatePatchID = "system-virtualaudio-cfw-speaker_protection_gate"

    /// The precondition log format the volume-mode decline opens with, and
    /// one anchor of the volume-gate patch. Three declines in this handler
    /// share it; the packing-mask comparison picks ours out.
    public static let volumePreconditionFormat = "PRECONDITION FAILURE (std::logic_error)"

    /// The 33-bit packing mask the handler compares the volume-mode lookup
    /// under — a present flag in bit 32 above the mode's low 32 bits. The
    /// semantic constant the site is recognised by, beside the strings.
    public static let volumeModePackingMask = 0x1_FFFF_FFFF

    /// Record identity for the volume-gate patch.
    public static let volumeGatePatchID = "system-virtualaudio-cfw-volume_mode_precondition"

    /// The singleton's own diagnostic, and the anchor of the null-gate
    /// patch: the log DeviceStateManager's accessor prints when it is
    /// asked for an instance nobody published yet.
    public static let deviceStateInstanceMissing = "TheInstance() called before SetInstance()"

    /// Record identity for the null-gate patch.
    public static let deviceStateNullGatePatchID = "system-virtualaudio-cfw-device_state_null_gate"

    /// Where progress goes when the caller does not say.
    public static let stdoutLog: @Sendable (String) -> Void = { print($0) }

    // MARK: - Results

    public enum Outcome: String, Sendable, Equatable {
        /// The throw block already branched to the epilogue. Nothing was written.
        case alreadyPatched
        /// `dryRun` was set, so the site was located and reported only.
        case wouldPatch
        /// The branch was written and its page re-attested.
        case patched
        /// The plugin is not an arm64e.x1 image: the device-state guard
        /// applies to nothing, and nothing was written.
        case notArm64EX1
    }

    /// The resolved pair the patch writes between.
    public struct Anchor: Sendable, Equatable {
        /// `movz w0, #imm` — the first instruction of the throw block.
        public let throwBlockFileOffset: Int
        public let throwBlockVMA: UInt64
        /// The `ldur` that begins the function's epilogue.
        public let epilogueFileOffset: Int
        public let epilogueVMA: UInt64
    }

    public struct Report: Sendable {
        public let outcome: Outcome
        public let anchor: Anchor
        public let records: [PatchRecord]
        public let slotRehashes: [CustomFirmwareSlotRehash]
    }

    /// The resolved pair the mute-set patch writes between.
    public struct MuteSetAnchor: Sendable, Equatable {
        /// `mov w0, #<size>` — the first instruction of the throw block.
        public let throwBlockFileOffset: Int
        public let throwBlockVMA: UInt64
        /// The guarded canary load (or first pop) that begins the wrapper's
        /// epilogue.
        public let epilogueFileOffset: Int
        public let epilogueVMA: UInt64
    }

    public struct MuteSetReport: Sendable {
        public let outcome: Outcome
        public let anchor: MuteSetAnchor
        public let records: [PatchRecord]
        public let slotRehashes: [CustomFirmwareSlotRehash]
    }

    /// The resolved pair the SP-gate patch writes between.
    public struct SPGateAnchor: Sendable, Equatable {
        /// The branch that jumps into the decline's log block — left as it is.
        public let branchFileOffset: Int
        public let branchVMA: UInt64
        /// The log block's entry — the instruction the patch rewrites into a
        /// branch back to the gate's own fall-through.
        public let blockHeadFileOffset: Int
        public let blockHeadVMA: UInt64
    }

    public struct SPGateReport: Sendable {
        public let outcome: Outcome
        public let anchor: SPGateAnchor
        public let records: [PatchRecord]
        public let slotRehashes: [CustomFirmwareSlotRehash]
    }

    /// The resolved pair the volume-gate patch writes between.
    public struct VolumeGateAnchor: Sendable, Equatable {
        /// The conditional branch that jumps into the decline's log block —
        /// left as it is.
        public let branchFileOffset: Int
        public let branchVMA: UInt64
        /// The log block's entry — the instruction the patch rewrites into a
        /// branch back to the comparison's own fall-through.
        public let blockHeadFileOffset: Int
        public let blockHeadVMA: UInt64
    }

    public struct VolumeGateReport: Sendable {
        public let outcome: Outcome
        public let anchor: VolumeGateAnchor
        public let records: [PatchRecord]
        public let slotRehashes: [CustomFirmwareSlotRehash]
    }

    /// One gated device-state update: the gate-check call the patch
    /// redirects, the branch that tests its answer, and the singleton call
    /// the update stands on.
    public struct DeviceStateNullGateAnchor: Sendable, Equatable {
        /// The `bl <gate check>` — the instruction the patch rewrites into
        /// a `bl` to TheInstance.
        public let gateCallFileOffset: Int
        public let gateCallVMA: UInt64
        /// The `cbz w0, <skip>` that now tests the singleton.
        public let branchVMA: UInt64
        /// Where the branch skips to when the singleton is null.
        public let skipTargetVMA: UInt64
    }

    public struct DeviceStateNullGateReport: Sendable {
        public let outcome: Outcome
        /// TheInstance's entry, resolved from its own diagnostic.
        public let theInstanceVMA: UInt64
        public let sites: [DeviceStateNullGateAnchor]
        public let records: [PatchRecord]
        public let slotRehashes: [CustomFirmwareSlotRehash]
    }

    private static func wordAt(_ data: Data, _ offset: Int) -> UInt32? {
        guard offset + 4 <= data.count else { return nil }
        return UInt32(data[offset])
            | UInt32(data[offset + 1]) << 8
            | UInt32(data[offset + 2]) << 16
            | UInt32(data[offset + 3]) << 24
    }

    /// Patch the VirtualAudio Mach-O at `url` in place.
    ///
    /// Idempotent: a second run recognises its own branch, reports
    /// ``Outcome/alreadyPatched`` and leaves the file byte-identical.
    ///
    /// - Parameters:
    ///   - url: the `VirtualAudio` plugin binary.
    ///   - reattest: recompute the code-directory slot hash of the touched
    ///     page. `false` when the caller re-signs the whole binary right
    ///     after, which is what both install paths do.
    ///   - dryRun: locate and report, write nothing.
    @discardableResult
    public static func patch(
        fileAt url: URL,
        reattest: Bool = true,
        dryRun: Bool = false,
        log: ((String) -> Void)? = stdoutLog,
    ) throws -> Report {
        guard FileManager.default.fileExists(atPath: url.path) else {
            throw PatcherError.fileNotFound(url.path)
        }
        var data = try Data(contentsOfFileToRewrite: url)
        let before = data
        let report = try patch(&data, reattest: reattest, dryRun: dryRun, log: log)
        if data != before {
            try data.write(to: url)
        }
        return report
    }

    /// In-memory form of ``patch(fileAt:reattest:dryRun:log:)``.
    @discardableResult
    public static func patch(
        _ data: inout Data,
        reattest: Bool = true,
        dryRun: Bool = false,
        log: ((String) -> Void)? = stdoutLog,
    ) throws -> Report {
        if data.startIndex != 0 {
            data = Data(data)
        }

        let located = try locate(in: data)
        log?("  [.] speaker-route walker 0x\(hex(located.walkerStartVMA)) … 0x\(hex(located.walkerEndVMA))"
            + "; epilogue 0x\(hex(located.epilogueVMA)); \(located.sites.count) throw site(s)")

        var records: [PatchRecord] = []
        var written: [Int] = []
        var alreadyPatched = 0
        for site in located.sites {
            let siteVMA = located.vma(site)
            let siteInstruction = located.disasm.disassembleOne(in: data, at: site, address: siteVMA)
            if let insn = siteInstruction, insn.isJump, !insn.isCall,
               let word = wordAt(data, site),
               let target = ARM64Encoder.decodeBranchTarget(insn: word, pc: siteVMA),
               target == located.epilogueVMA
            {
                alreadyPatched += 1
                continue
            }
            guard isExceptionSizeMove(siteInstruction) || siteInstruction?.isCall == true else {
                throw PatcherError.invalidFormat(
                    "\(component): site 0x\(hex(siteVMA)) is neither `mov w0, #<size>` nor a call",
                )
            }
            guard let branch = ARM64Encoder.encodeB(from: Int(siteVMA), to: Int(located.epilogueVMA)) else {
                throw PatcherError.patchSiteNotFound(
                    "\(component): the epilogue at 0x\(hex(located.epilogueVMA)) is out of "
                        + "branch range of the throw block at 0x\(hex(siteVMA))",
                )
            }
            let original = Data(data[site ..< site + 4])
            if dryRun {
                log?("      [.] dry-run — would branch 0x\(hex(siteVMA)) -> 0x\(hex(located.epilogueVMA))")
                continue
            }
            data.replaceSubrange(site ..< site + 4, with: branch)
            written.append(site)
            records.append(PatchRecord(
                patchID: patchID,
                component: component,
                fileOffset: site,
                virtualAddress: siteVMA,
                originalBytes: original,
                patchedBytes: branch,
                beforeDisasm: siteInstruction?.description ?? "",
                afterDisasm: branch.map { String(format: "%02x", $0) }.joined(separator: " "),
                description: "speaker-route walker throw -> epilogue",
            ))
            log?("      [+] 0x\(hex(siteVMA)): \(siteInstruction?.description ?? "") -> b 0x\(hex(located.epilogueVMA))")
        }

        if records.isEmpty, !dryRun {
            log?("      [=] all \(alreadyPatched) throw site(s) already branch to the epilogue")
        }

        var rehashes: [CustomFirmwareSlotRehash] = []
        if reattest, !written.isEmpty {
            rehashes = try CustomFirmwareMachOCodeSignature.reattest(&data, modifiedOffsets: written)
            if !rehashes.isEmpty {
                log?("      [+] re-attested \(rehashes.count) stale slot(s)")
            }
        }
        let outcome: Outcome = dryRun ? .wouldPatch : (records.isEmpty ? .alreadyPatched : .patched)
        return Report(
            outcome: outcome,
            anchor: Anchor(
                throwBlockFileOffset: located.sites.first ?? 0,
                throwBlockVMA: located.sites.isEmpty ? 0 : located.vma(located.sites[0]),
                epilogueFileOffset: located.epilogueOffset,
                epilogueVMA: located.epilogueVMA,
            ),
            records: records,
            slotRehashes: rehashes,
        )
    }

    // MARK: - Speaker Protection

    /// Patch the VirtualAudio Mach-O at `url` in place, turning the speaker-route
    /// walker's fault-logged terminating call into an unconditional branch to the
    /// wrapper's epilogue, so a speaker whose protection is inactive returns
    /// quietly instead of terminating.
    ///
    /// Idempotent: a second run finds the site already holding an unconditional
    /// branch to the epilogue, reports ``Outcome/alreadyPatched`` and leaves the
    /// file byte-identical.
    ///
    /// - Parameters:
    ///   - url: the `VirtualAudio` plugin binary.
    ///   - reattest: recompute the code-directory slot hash of the touched
    ///     page. `false` when the caller re-signs the whole binary right
    ///     after, which is what both install paths do.
    ///   - dryRun: locate and report, write nothing.
    @discardableResult
    public static func patchInactiveSpeakerProtection(
        fileAt url: URL,
        reattest: Bool = true,
        dryRun: Bool = false,
        log: ((String) -> Void)? = stdoutLog,
    ) throws -> Report {
        guard FileManager.default.fileExists(atPath: url.path) else {
            throw PatcherError.fileNotFound(url.path)
        }

        var data = try Data(contentsOfFileToRewrite: url)
        let before = data

        let report = try patchInactiveSpeakerProtection(
            &data, reattest: reattest, dryRun: dryRun, log: log,
        )

        if data != before {
            try data.write(to: url)
        }

        return report
    }

    /// In-memory form of ``patchInactiveSpeakerProtection(fileAt:reattest:dryRun:log:)``.
    @discardableResult
    public static func patchInactiveSpeakerProtection(
        _ data: inout Data,
        reattest: Bool = true,
        dryRun: Bool = false,
        log: ((String) -> Void)? = stdoutLog,
    ) throws -> Report {
        if data.startIndex != 0 {
            data = Data(data)
        }

        let located = try locate(in: data)
        guard let site = terminateSite(
            in: data, disasm: located.disasm,
            sections: MachOParser.parseSections(from: data),
            textStart: located.textStart, textEnd: located.walkerEndOffset,
            walkerStart: located.walkerStartOffset, walkerEnd: located.walkerEndOffset,
            epilogueVMA: located.epilogueVMA, includePatched: true, requireUniqueReference: true,
        ) else {
            throw PatcherError.patchSiteNotFound(
                "\(component): no fault-logged inactive speaker-protection termination in the walker",
            )
        }

        let siteVMA = located.vma(site)
        let anchor = Anchor(
            throwBlockFileOffset: site, throwBlockVMA: siteVMA,
            epilogueFileOffset: located.epilogueOffset, epilogueVMA: located.epilogueVMA,
        )

        let instruction = located.disasm.disassembleOne(in: data, at: site, address: siteVMA)
        if let instruction, instruction.isJump,
           !instruction.isCall,
           let word = wordAt(data, site),
           ARM64Encoder.decodeBranchTarget(insn: word, pc: siteVMA) == located.epilogueVMA
        {
            log?("      [=] inactive speaker-protection termination already bypassed")
            return Report(outcome: .alreadyPatched, anchor: anchor, records: [], slotRehashes: [])
        }

        guard instruction?.isCall == true,
              let branch = ARM64Encoder.encodeB(from: Int(siteVMA), to: Int(located.epilogueVMA)) else {
            throw PatcherError.patchSiteNotFound(
                "\(component): inactive speaker-protection termination is not a call with a reachable epilogue",
            )
        }

        log?("  [.] inactive speaker-protection termination 0x\(hex(siteVMA)) -> epilogue 0x\(hex(located.epilogueVMA))")
        if dryRun {
            return Report(outcome: .wouldPatch, anchor: anchor, records: [], slotRehashes: [])
        }

        let original = Data(data[site..<site + 4])
        data.replaceSubrange(site..<site + 4, with: branch)

        let rehashes = reattest
            ? try CustomFirmwareMachOCodeSignature.reattest(&data, modifiedOffsets: [site]) : []
        log?("      [+] bypassed only the inactive speaker-protection termination")

        return Report(
            outcome: .patched, anchor: anchor,
            records: [PatchRecord(
                patchID: patchID + ".inactive_protection", component: component,
                fileOffset: site, virtualAddress: siteVMA,
                originalBytes: original, patchedBytes: branch,
                beforeDisasm: instruction?.description ?? "",
                afterDisasm: branch.map { String(format: "%02x", $0) }.joined(separator: " "),
                description: "inactive speaker-protection termination -> epilogue",
            )], slotRehashes: rehashes,
        )
    }

    // MARK: - Mute-set patching

    /// Patch the VirtualAudio Mach-O at `url` in place, turning the mute-set
    /// CAException into a quiet return through the wrapper's epilogue.
    ///
    /// Idempotent: a second run recognises its own branch, reports
    /// ``Outcome/alreadyPatched`` and leaves the file byte-identical.
    ///
    /// - Parameters:
    ///   - url: the `VirtualAudio` plugin binary.
    ///   - reattest: recompute the code-directory slot hash of the touched
    ///     page. `false` when the caller re-signs the whole binary right
    ///     after, which is what both install paths do.
    ///   - dryRun: locate and report, write nothing.
    @discardableResult
    public static func patchMuteSet(
        fileAt url: URL,
        reattest: Bool = true,
        dryRun: Bool = false,
        log: ((String) -> Void)? = stdoutLog,
    ) throws -> MuteSetReport {
        guard FileManager.default.fileExists(atPath: url.path) else {
            throw PatcherError.fileNotFound(url.path)
        }
        var data = try Data(contentsOfFileToRewrite: url)
        let before = data
        let report = try patchMuteSet(&data, reattest: reattest, dryRun: dryRun, log: log)
        if data != before {
            try data.write(to: url)
        }
        return report
    }

    /// In-memory form of ``patchMuteSet(fileAt:reattest:dryRun:log:)``.
    @discardableResult
    public static func patchMuteSet(
        _ data: inout Data,
        reattest: Bool = true,
        dryRun: Bool = false,
        log: ((String) -> Void)? = stdoutLog,
    ) throws -> MuteSetReport {
        if data.startIndex != 0 {
            data = Data(data)
        }

        let located = try locateMuteSet(in: data)
        let site = located.site
        let siteVMA = located.vma(site)
        log?("  [.] mute-set wrapper 0x\(hex(located.functionStartVMA)) … 0x\(hex(located.functionEndVMA))"
            + "; epilogue 0x\(hex(located.epilogueVMA)); throw 0x\(hex(siteVMA))")

        let anchor = MuteSetAnchor(
            throwBlockFileOffset: site,
            throwBlockVMA: siteVMA,
            epilogueFileOffset: located.epilogueOffset,
            epilogueVMA: located.epilogueVMA,
        )
        let siteInstruction = located.disasm.disassembleOne(in: data, at: site, address: siteVMA)
        if let insn = siteInstruction, insn.isJump, !insn.isCall,
           let word = wordAt(data, site),
           let target = ARM64Encoder.decodeBranchTarget(insn: word, pc: siteVMA),
           target == located.epilogueVMA
        {
            log?("      [=] the mute-set throw already branches to the epilogue")
            return MuteSetReport(outcome: .alreadyPatched, anchor: anchor, records: [], slotRehashes: [])
        }
        guard isExceptionSizeMove(siteInstruction) else {
            throw PatcherError.invalidFormat(
                "\(component): the mute-set throw at 0x\(hex(siteVMA)) is not `mov w0, #<size>`",
            )
        }
        guard let branch = ARM64Encoder.encodeB(from: Int(siteVMA), to: Int(located.epilogueVMA)) else {
            throw PatcherError.patchSiteNotFound(
                "\(component): the epilogue at 0x\(hex(located.epilogueVMA)) is out of "
                    + "branch range of the mute-set throw at 0x\(hex(siteVMA))",
            )
        }
        let original = Data(data[site ..< site + 4])
        if dryRun {
            log?("      [.] dry-run — would branch 0x\(hex(siteVMA)) -> 0x\(hex(located.epilogueVMA))")
            return MuteSetReport(outcome: .wouldPatch, anchor: anchor, records: [], slotRehashes: [])
        }
        data.replaceSubrange(site ..< site + 4, with: branch)
        log?("      [+] 0x\(hex(siteVMA)): \(siteInstruction?.description ?? "") -> b 0x\(hex(located.epilogueVMA))")
        var rehashes: [CustomFirmwareSlotRehash] = []
        if reattest {
            rehashes = try CustomFirmwareMachOCodeSignature.reattest(&data, modifiedOffsets: [site])
            if !rehashes.isEmpty {
                log?("      [+] re-attested \(rehashes.count) stale slot(s)")
            }
        }
        return MuteSetReport(
            outcome: .patched,
            anchor: anchor,
            records: [PatchRecord(
                patchID: muteSetPatchID,
                component: component,
                fileOffset: site,
                virtualAddress: siteVMA,
                originalBytes: original,
                patchedBytes: branch,
                beforeDisasm: siteInstruction?.description ?? "",
                afterDisasm: branch.map { String(format: "%02x", $0) }.joined(separator: " "),
                description: "mute-set throw -> epilogue",
            )],
            slotRehashes: rehashes,
        )
    }

    // MARK: - SP-gate patching

    /// Patch the VirtualAudio Mach-O at `url` in place, opening the branch
    /// that declines a finished speaker route for lack of HAL Speaker
    /// Protection.
    ///
    /// The gate branch is left untouched; what changes is the decline's own
    /// log block: its entry — the `mov w0, #<size>` that opens the os_log —
    /// is rewritten into a branch back to the gate's fall-through, so a
    /// taken gate lands straight on the success path the handler already
    /// built. That path never reads the verdict the gate tested, on either
    /// supported build, and the block is reached only by the gate's jump —
    /// the instruction above it is an unconditional branch, checked before
    /// anything is written.
    ///
    /// Idempotent: a second run finds the log block's entry holding its own
    /// unconditional branch, reports ``Outcome/alreadyPatched`` and leaves
    /// the file byte-identical.
    ///
    /// - Parameters:
    ///   - url: the `VirtualAudio` plugin binary.
    ///   - reattest: recompute the code-directory slot hash of the touched
    ///     page. `false` when the caller re-signs the whole binary right
    ///     after, which is what both install paths do.
    ///   - dryRun: locate and report, write nothing.
    @discardableResult
    public static func patchSpeakerProtectionGate(
        fileAt url: URL,
        handler: SPGateHandler = .playback,
        reattest: Bool = true,
        dryRun: Bool = false,
        log: ((String) -> Void)? = stdoutLog,
    ) throws -> SPGateReport {
        guard FileManager.default.fileExists(atPath: url.path) else {
            throw PatcherError.fileNotFound(url.path)
        }
        var data = try Data(contentsOfFileToRewrite: url)
        let before = data
        let report = try patchSpeakerProtectionGate(
            &data, handler: handler, reattest: reattest, dryRun: dryRun, log: log,
        )
        if data != before {
            try data.write(to: url)
        }
        return report
    }

    /// In-memory form of ``patchSpeakerProtectionGate(fileAt:handler:reattest:dryRun:log:)``.
    @discardableResult
    public static func patchSpeakerProtectionGate(
        _ data: inout Data,
        handler: SPGateHandler = .playback,
        reattest: Bool = true,
        dryRun: Bool = false,
        log: ((String) -> Void)? = stdoutLog,
    ) throws -> SPGateReport {
        if data.startIndex != 0 {
            data = Data(data)
        }

        let located = try locateSPGate(in: data, handler: handler)
        let head = located.blockHead
        let headVMA = located.vma(head)
        let site = located.site
        let siteVMA = located.vma(site)
        log?("  [.] SP-gate \(handler.rawValue) handler 0x\(hex(located.functionStartVMA)) … 0x\(hex(located.functionEndVMA))"
            + "; log block 0x\(hex(headVMA)); gate 0x\(hex(siteVMA))")
        let anchor = SPGateAnchor(
            branchFileOffset: site,
            branchVMA: siteVMA,
            blockHeadFileOffset: head,
            blockHeadVMA: headVMA,
        )

        let headInstruction = located.disasm.disassembleOne(in: data, at: head, address: headVMA)
        if let insn = headInstruction, insn.isJump, !insn.isCall, insn.detail?.conditionCode == nil {
            // An unconditional branch at the head is either this patch's own
            // work or someone else's; the target tells them apart, and
            // someone else's is never overwritten.
            guard let word = wordAt(data, head),
                  let target = ARM64Encoder.decodeBranchTarget(insn: word, pc: headVMA),
                  target == siteVMA + 4
            else {
                throw PatcherError.invalidFormat(
                    "\(component): the log block at 0x\(hex(headVMA)) holds a branch this "
                        + "patch did not write",
                )
            }
            log?("      [=] the decline's log block already branches back to the gate's fall-through")
            return SPGateReport(outcome: .alreadyPatched, anchor: anchor, records: [], slotRehashes: [])
        }
        // A pristine block opens the os_log allocation: the size move, then
        // the call that allocates it.
        guard isExceptionSizeMove(headInstruction),
              let next = located.disasm.disassembleOne(in: data, at: head + 4), next.isCall
        else {
            throw PatcherError.invalidFormat(
                "\(component): the log block at 0x\(hex(headVMA)) does not open an os_log allocation",
            )
        }
        guard let branch = ARM64Encoder.encodeB(from: Int(headVMA), to: Int(siteVMA) + 4) else {
            throw PatcherError.patchSiteNotFound(
                "\(component): the fall-through at 0x\(hex(siteVMA + 4)) is out of "
                    + "branch range of the log block at 0x\(hex(headVMA))",
            )
        }
        let original = Data(data[head ..< head + 4])
        if dryRun {
            log?("      [.] dry-run — would branch 0x\(hex(headVMA)) -> 0x\(hex(siteVMA + 4))")
            return SPGateReport(outcome: .wouldPatch, anchor: anchor, records: [], slotRehashes: [])
        }
        data.replaceSubrange(head ..< head + 4, with: branch)
        log?("      [+] 0x\(hex(headVMA)): \(headInstruction?.description ?? "") -> b 0x\(hex(siteVMA + 4))")
        var rehashes: [CustomFirmwareSlotRehash] = []
        if reattest {
            rehashes = try CustomFirmwareMachOCodeSignature.reattest(&data, modifiedOffsets: [head])
            if !rehashes.isEmpty {
                log?("      [+] re-attested \(rehashes.count) stale slot(s)")
            }
        }
        return SPGateReport(
            outcome: .patched,
            anchor: anchor,
            records: [PatchRecord(
                patchID: handler.patchID,
                component: component,
                fileOffset: head,
                virtualAddress: headVMA,
                originalBytes: original,
                patchedBytes: branch,
                beforeDisasm: headInstruction?.description ?? "",
                afterDisasm: branch.map { String(format: "%02x", $0) }.joined(separator: " "),
                description: "speaker-protection decline -> gate fall-through",
            )],
            slotRehashes: rehashes,
        )
    }

    // MARK: - Volume-gate patching

    /// Patch the VirtualAudio Mach-O at `url` in place, opening the branch
    /// that declines a finished route when its software-volume mode is not
    /// the kHardwareOnlyReadOnly the routing database demands.
    ///
    /// The comparison is left untouched; what changes is the decline's own
    /// log block: its entry — the `mov w0, #<size>` that opens the os_log —
    /// is rewritten into a branch back to the comparison's fall-through, so
    /// a failed precondition lands on the success path the handler already
    /// built. The block is reachable only by the comparison's jump (its
    /// predecessor is an unconditional branch, verified before writing) and
    /// that success path never reads the value the comparison tested, on
    /// either supported build.
    ///
    /// Idempotent: a second run finds the log block's entry holding its own
    /// unconditional branch, reports ``Outcome/alreadyPatched`` and leaves
    /// the file byte-identical.
    ///
    /// - Parameters:
    ///   - url: the `VirtualAudio` plugin binary.
    ///   - reattest: recompute the code-directory slot hash of the touched
    ///     page. `false` when the caller re-signs the whole binary right
    ///     after, which is what both install paths do.
    ///   - dryRun: locate and report, write nothing.
    @discardableResult
    public static func patchVolumeModePrecondition(
        fileAt url: URL,
        reattest: Bool = true,
        dryRun: Bool = false,
        log: ((String) -> Void)? = stdoutLog,
    ) throws -> VolumeGateReport {
        guard FileManager.default.fileExists(atPath: url.path) else {
            throw PatcherError.fileNotFound(url.path)
        }
        var data = try Data(contentsOfFileToRewrite: url)
        let before = data
        let report = try patchVolumeModePrecondition(&data, reattest: reattest, dryRun: dryRun, log: log)
        if data != before {
            try data.write(to: url)
        }
        return report
    }

    /// In-memory form of ``patchVolumeModePrecondition(fileAt:reattest:dryRun:log:)``.
    @discardableResult
    public static func patchVolumeModePrecondition(
        _ data: inout Data,
        reattest: Bool = true,
        dryRun: Bool = false,
        log: ((String) -> Void)? = stdoutLog,
    ) throws -> VolumeGateReport {
        if data.startIndex != 0 {
            data = Data(data)
        }

        let located = try locateVolumeGate(in: data)
        let head = located.blockHead
        let headVMA = located.vma(head)
        let site = located.site
        let siteVMA = located.vma(site)
        log?("  [.] volume-gate handler 0x\(hex(located.functionStartVMA)) … 0x\(hex(located.functionEndVMA))"
            + "; log block 0x\(hex(headVMA)); comparison 0x\(hex(siteVMA))")
        let anchor = VolumeGateAnchor(
            branchFileOffset: site,
            branchVMA: siteVMA,
            blockHeadFileOffset: head,
            blockHeadVMA: headVMA,
        )

        let headInstruction = located.disasm.disassembleOne(in: data, at: head, address: headVMA)
        if let insn = headInstruction, insn.isJump, !insn.isCall, insn.detail?.conditionCode == nil {
            // An unconditional branch at the head is either this patch's own
            // work or someone else's; the target tells them apart, and
            // someone else's is never overwritten.
            guard let word = wordAt(data, head),
                  let target = ARM64Encoder.decodeBranchTarget(insn: word, pc: headVMA),
                  target == siteVMA + 4
            else {
                throw PatcherError.invalidFormat(
                    "\(component): the log block at 0x\(hex(headVMA)) holds a branch this "
                        + "patch did not write",
                )
            }
            log?("      [=] the decline's log block already branches back to the comparison's fall-through")
            return VolumeGateReport(outcome: .alreadyPatched, anchor: anchor, records: [], slotRehashes: [])
        }
        // A pristine block opens the os_log allocation: the size move, then
        // the call that allocates it.
        guard isExceptionSizeMove(headInstruction),
              let next = located.disasm.disassembleOne(in: data, at: head + 4), next.isCall
        else {
            throw PatcherError.invalidFormat(
                "\(component): the log block at 0x\(hex(headVMA)) does not open an os_log allocation",
            )
        }
        guard let branch = ARM64Encoder.encodeB(from: Int(headVMA), to: Int(siteVMA) + 4) else {
            throw PatcherError.patchSiteNotFound(
                "\(component): the fall-through at 0x\(hex(siteVMA + 4)) is out of "
                    + "branch range of the log block at 0x\(hex(headVMA))",
            )
        }
        let original = Data(data[head ..< head + 4])
        if dryRun {
            log?("      [.] dry-run — would branch 0x\(hex(headVMA)) -> 0x\(hex(siteVMA + 4))")
            return VolumeGateReport(outcome: .wouldPatch, anchor: anchor, records: [], slotRehashes: [])
        }
        data.replaceSubrange(head ..< head + 4, with: branch)
        log?("      [+] 0x\(hex(headVMA)): \(headInstruction?.description ?? "") -> b 0x\(hex(siteVMA + 4))")
        var rehashes: [CustomFirmwareSlotRehash] = []
        if reattest {
            rehashes = try CustomFirmwareMachOCodeSignature.reattest(&data, modifiedOffsets: [head])
            if !rehashes.isEmpty {
                log?("      [+] re-attested \(rehashes.count) stale slot(s)")
            }
        }
        return VolumeGateReport(
            outcome: .patched,
            anchor: anchor,
            records: [PatchRecord(
                patchID: volumeGatePatchID,
                component: component,
                fileOffset: head,
                virtualAddress: headVMA,
                originalBytes: original,
                patchedBytes: branch,
                beforeDisasm: headInstruction?.description ?? "",
                afterDisasm: branch.map { String(format: "%02x", $0) }.joined(separator: " "),
                description: "volume-mode precondition -> comparison fall-through",
            )],
            slotRehashes: rehashes,
        )
    }

    // MARK: - Device-state null-gate patching

    /// Patch the VirtualAudio Mach-O at `url` in place, making the two
    /// device-state updates wait for the DeviceStateManager singleton
    /// instead of dereferencing it when it does not exist.
    ///
    /// Each gate-check call — the `bl` whose answer the following
    /// `cbz w0, <skip>` tests — is redirected to TheInstance, so that
    /// branch now tests the singleton itself: null manager, the update is
    /// skipped through the function's own path; manager present, the
    /// fall-through re-calls TheInstance and the update runs untouched,
    /// as designed. Applies only to an arm64e.x1 (cpusubtype 12) plugin:
    /// every other build reports ``Outcome/notArm64EX1`` and keeps its
    /// bytes.
    ///
    /// Idempotent: a second run finds the gate slot already calling
    /// TheInstance, reports ``Outcome/alreadyPatched`` and leaves the file
    /// byte-identical.
    ///
    /// - Parameters:
    ///   - url: the `VirtualAudio` plugin binary.
    ///   - reattest: recompute the code-directory slot hash of the touched
    ///     page. `false` when the caller re-signs the whole binary right
    ///     after, which is what both install paths do.
    ///   - dryRun: locate and report, write nothing.
    @discardableResult
    public static func patchDeviceStateNullGate(
        fileAt url: URL,
        reattest: Bool = true,
        dryRun: Bool = false,
        log: ((String) -> Void)? = stdoutLog,
    ) throws -> DeviceStateNullGateReport {
        guard FileManager.default.fileExists(atPath: url.path) else {
            throw PatcherError.fileNotFound(url.path)
        }
        var data = try Data(contentsOfFileToRewrite: url)
        let before = data
        let report = try patchDeviceStateNullGate(&data, reattest: reattest, dryRun: dryRun, log: log)
        if data != before {
            try data.write(to: url)
        }
        return report
    }

    /// In-memory form of ``patchDeviceStateNullGate(fileAt:reattest:dryRun:log:)``.
    @discardableResult
    public static func patchDeviceStateNullGate(
        _ data: inout Data,
        reattest: Bool = true,
        dryRun: Bool = false,
        log: ((String) -> Void)? = stdoutLog,
    ) throws -> DeviceStateNullGateReport {
        if data.startIndex != 0 {
            data = Data(data)
        }

        switch arm64Subtype(of: data) {
        case .x1:
            break
        case .other:
            log?("  [·] VirtualAudio: not an arm64e.x1 plugin — the device-state null gate has nothing to do")
            return DeviceStateNullGateReport(
                outcome: .notArm64EX1,
                theInstanceVMA: 0,
                sites: [],
                records: [],
                slotRehashes: [],
            )
        case .notArm64:
            break // not a thin arm64 image; the anchor below refuses it
        }

        let located = try locateDeviceStateNullGate(in: data)
        log?("  [.] TheInstance 0x\(hex(located.theInstanceVMA)); \(located.sites.count) gated device-state update(s)")
        let anchors = located.sites.map { site in
            DeviceStateNullGateAnchor(
                gateCallFileOffset: site.gateCall,
                gateCallVMA: located.vma(site.gateCall),
                branchVMA: located.vma(site.branch),
                skipTargetVMA: site.target,
            )
        }

        var records: [PatchRecord] = []
        var written: [Int] = []
        var alreadyPatched = 0
        for site in located.sites {
            let call = site.gateCall
            let callVMA = located.vma(call)
            let callInstruction = located.disasm.disassembleOne(in: data, at: call, address: callVMA)
            if site.alreadyGated {
                alreadyPatched += 1
                log?("      [=] 0x\(hex(callVMA)): the gate already asks TheInstance")
                continue
            }
            guard let redirect = ARM64Encoder.encodeBL(from: Int(callVMA), to: Int(located.theInstanceVMA)) else {
                throw PatcherError.patchSiteNotFound(
                    "\(component): TheInstance at 0x\(hex(located.theInstanceVMA)) is out of "
                        + "branch range of the gate call at 0x\(hex(callVMA))",
                )
            }
            let original = Data(data[call ..< call + 4])
            if dryRun {
                log?("      [.] dry-run — would call TheInstance from 0x\(hex(callVMA))")
                continue
            }
            data.replaceSubrange(call ..< call + 4, with: redirect)
            written.append(call)
            records.append(PatchRecord(
                patchID: deviceStateNullGatePatchID,
                component: component,
                fileOffset: call,
                virtualAddress: callVMA,
                originalBytes: original,
                patchedBytes: redirect,
                beforeDisasm: callInstruction?.description ?? "",
                afterDisasm: redirect.map { String(format: "%02x", $0) }.joined(separator: " "),
                description: "device-state gate check -> TheInstance",
            ))
            log?("      [+] 0x\(hex(callVMA)): \(callInstruction?.description ?? "") -> bl 0x\(hex(located.theInstanceVMA))")
        }

        if records.isEmpty, !dryRun {
            log?("      [=] all \(alreadyPatched) gate(s) already ask TheInstance")
        }

        var rehashes: [CustomFirmwareSlotRehash] = []
        if reattest, !written.isEmpty {
            rehashes = try CustomFirmwareMachOCodeSignature.reattest(&data, modifiedOffsets: written)
            if !rehashes.isEmpty {
                log?("      [+] re-attested \(rehashes.count) stale slot(s)")
            }
        }
        let outcome: Outcome = dryRun ? .wouldPatch : (records.isEmpty ? .alreadyPatched : .patched)
        return DeviceStateNullGateReport(
            outcome: outcome,
            theInstanceVMA: located.theInstanceVMA,
            sites: anchors,
            records: records,
            slotRehashes: rehashes,
        )
    }


    // MARK: - Anchoring

    /// Resolve the throw block and the epilogue, or say why not.
    /// Everything the patch needs: the walker's bounds, its epilogue, and
    /// every throw site inside it.
    struct Plan: Sendable {
        let disasm: ARM64Disassembler
        let textStart: Int
        let textAddress: UInt64
        let walkerStartOffset: Int
        let walkerEndOffset: Int
        let epilogueOffset: Int
        let epilogueVMA: UInt64
        let sites: [Int]

        var walkerStartVMA: UInt64 {
            vma(walkerStartOffset)
        }

        var walkerEndVMA: UInt64 {
            vma(walkerEndOffset)
        }

        func vma(_ offset: Int) -> UInt64 {
            textAddress + UInt64(offset - textStart)
        }
    }

    static func locate(in data: Data) throws -> Plan {
        let sections = MachOParser.parseSections(from: data)
        guard let text = sections["__TEXT,__text"] else {
            throw PatcherError.invalidFormat("\(component): no __TEXT,__text section")
        }
        let textStart = Int(text.fileOffset)
        let textEnd = textStart + Int(text.size)
        let disasm = ARM64Disassembler()

        let stringVMA = try locateMessage(in: data, sections: sections)
        let references = adrpAddReferences(to: 0, formingAnyOf: [stringVMA], in: data, textStart: textStart, textEnd: textEnd)
        guard references.count == 1 else {
            throw PatcherError.patchSiteNotFound(
                "\(component): expected exactly 1 reference to \"\(message)\" (the exception "
                    + "constructor's), found \(references.count)",
            )
        }
        let ctor = references[0]
        guard disasm.disassembleOne(in: data, at: ctor.add + 4)?.isCall == true else {
            throw PatcherError.patchSiteNotFound(
                "\(component): the reference to \"\(message)\" is not the exception constructor's",
            )
        }
        guard nearbyLogReference(in: data, sections: sections, textStart: textStart, textEnd: textEnd, before: ctor.adrp) != nil else {
            throw PatcherError.patchSiteNotFound(
                "\(component): no diagnostic-log reference above the throw to corroborate it",
            )
        }

        // The walker: the function whose prologue stands above the anchor and
        // whose next prologue closes it.
        let walkerStart = nearestPrologue(in: data, disasm: disasm, below: ctor.adrp, floor: textStart)
            ?? textStart
        let walkerEnd = nearestPrologue(in: data, disasm: disasm, atOrAfter: walkerStart + 4, ceiling: textEnd)
            ?? textEnd

        // The epilogue: the guarded pop run after the anchor's throw.
        guard let terminator = firstUnconditionalBranch(in: data, disasm: disasm, after: ctor.add + 4, textEnd: walkerEnd) else {
            throw PatcherError.patchSiteNotFound(
                "\(component): no terminator branch after the exception constructor",
            )
        }
        let epilogueOffset = try locateEpilogue(
            in: data, disasm: disasm, after: terminator, prologue: walkerStart, textEnd: walkerEnd,
        )

        // Every throw block in the walker: a `mov w0, #<size>` whose next
        // instruction calls the exception allocator, followed within a short
        // window by a message load into x1 and a constructor call, and closed
        // by the terminator branch.
        var sites: [Int] = []
        var offset = walkerStart
        while offset + 4 <= walkerEnd {
            defer { offset += 4 }
            guard let insn = disasm.disassembleOne(in: data, at: offset),
                  isExceptionSizeMove(insn) || (insn.isJump && !insn.isCall),
                  let next = disasm.disassembleOne(in: data, at: offset + 4), next.isCall
            else { continue }
            // An already-patched site still carries its allocation call and
            // the whole machinery below, so the shape check holds for it too
            // and `patch` recognises its own branch when it writes.
            if isThrowBlock(in: data, disasm: disasm, from: offset + 4, to: walkerEnd) {
                sites.append(offset)
            }
        }
        var allSites = sites
        if let terminate = terminateSite(
            in: data,
            disasm: disasm,
            sections: sections,
            textStart: textStart,
            textEnd: textEnd,
            walkerStart: walkerStart,
            walkerEnd: walkerEnd,
            epilogueVMA: text.address + UInt64(epilogueOffset - textStart),
        ) {
            allSites.append(terminate)
        }

        guard !allSites.isEmpty else {
            throw PatcherError.patchSiteNotFound(
                "\(component): no exception throw blocks in the walker at 0x\(hex(UInt64(textStart)))",
            )
        }

        return Plan(
            disasm: disasm,
            textStart: textStart,
            textAddress: text.address,
            walkerStartOffset: walkerStart,
            walkerEndOffset: walkerEnd,
            epilogueOffset: epilogueOffset,
            epilogueVMA: text.address + UInt64(epilogueOffset - textStart),
            sites: allSites.sorted(),
        )
    }

    // MARK: - Mute-set anchoring

    /// Everything the mute-set patch needs: the set wrapper's bounds, its
    /// epilogue, and its throw site.
    struct MuteSetPlan: Sendable {
        let disasm: ARM64Disassembler
        let textStart: Int
        let textAddress: UInt64
        let functionStartOffset: Int
        let functionEndOffset: Int
        let epilogueOffset: Int
        let epilogueVMA: UInt64
        let site: Int

        var functionStartVMA: UInt64 {
            vma(functionStartOffset)
        }

        var functionEndVMA: UInt64 {
            vma(functionEndOffset)
        }

        func vma(_ offset: Int) -> UInt64 {
            textAddress + UInt64(offset - textStart)
        }
    }

    /// Resolve the mute-set throw and the wrapper's epilogue, or say why not.
    static func locateMuteSet(in data: Data) throws -> MuteSetPlan {
        let sections = MachOParser.parseSections(from: data)
        guard let text = sections["__TEXT,__text"] else {
            throw PatcherError.invalidFormat("\(component): no __TEXT,__text section")
        }
        let textStart = Int(text.fileOffset)
        let textEnd = textStart + Int(text.size)
        let disasm = ARM64Disassembler()

        // The anchor: the mute-set log format, referenced exactly once in
        // __text — by the wrapper's selector dispatch.
        guard let logVMA = cStringVMA(containing: muteSetMessage, in: data, sections: sections) else {
            throw PatcherError.patchSiteNotFound(
                "\(component): the string \"\(muteSetMessage)\" is nowhere in the binary's sections",
            )
        }
        let references = adrpAddReferences(
            to: 0,
            formingAnyOf: [logVMA],
            in: data,
            textStart: textStart,
            textEnd: textEnd,
        )
        guard references.count == 1 else {
            throw PatcherError.patchSiteNotFound(
                "\(component): expected exactly 1 reference to \"\(muteSetMessage)\", found \(references.count)",
            )
        }

        // The wrapper: the function whose prologue stands above the log
        // reference and whose next prologue closes it.
        let functionStart = nearestPrologue(in: data, disasm: disasm, below: references[0].adrp, floor: textStart)
            ?? textStart
        let functionEnd = nearestPrologue(in: data, disasm: disasm, atOrAfter: functionStart + 4, ceiling: textEnd)
            ?? textEnd

        // The throw: the wrapper's CAException block whose EXCEPTION log sits
        // just above it. iOS 27's wrapper holds a second CAException — the
        // deactivated-device throw — and the log window is what tells them
        // apart.
        let exceptionStrings = cStringVMAs(containing: muteSetException, in: data, sections: sections)
        guard !exceptionStrings.isEmpty else {
            throw PatcherError.patchSiteNotFound(
                "\(component): the string \"\(muteSetException)\" is nowhere in the binary's sections",
            )
        }
        var sites: [Int] = []
        var offset = functionStart
        while offset + 4 <= functionEnd {
            defer { offset += 4 }
            guard let insn = disasm.disassembleOne(in: data, at: offset),
                  isExceptionSizeMove(insn) || (insn.isJump && !insn.isCall),
                  let next = disasm.disassembleOne(in: data, at: offset + 4), next.isCall
            else { continue }
            // An already-patched site still carries the allocation call and
            // the stores below it, so the shape holds for it too and
            // `patchMuteSet` recognises its own branch when it writes.
            guard isCAExceptionThrowBlock(in: data, disasm: disasm, from: offset + 4, to: functionEnd),
                  hasExceptionLogWindow(
                      in: data,
                      textStart: textStart,
                      before: offset,
                      targets: exceptionStrings,
                  )
            else { continue }
            sites.append(offset)
        }
        guard sites.count == 1, let site = sites.first else {
            throw PatcherError.patchSiteNotFound(
                "\(component): expected exactly 1 mute-set throw in the wrapper at 0x\(hex(text.address + UInt64(functionStart - textStart))), found \(sites.count)",
            )
        }

        // The epilogue: the wrapper's only authenticated return (`retab`, or
        // `retabsppc` on an arm64e.x1 build), walked back to its entry. The
        // mute-set throw sits *below* the epilogue, so the forward search the
        // walker patch uses cannot apply — the return must be enumerated
        // within the function's own bounds, and a `retabsppc` must name the
        // wrapper's own prologue.
        var returns: [Int] = []
        offset = functionStart
        while offset + 4 <= functionEnd {
            if let insn = disasm.disassembleOne(in: data, at: offset), isAuthenticatedReturn(insn) {
                guard returnCloses(insn, at: offset, prologue: functionStart) else {
                    throw PatcherError.patchSiteNotFound(
                        "\(component): `\(insn.mnemonic)` at 0x\(hex(text.address + UInt64(offset - textStart))) "
                            + "in the mute-set wrapper does not close the wrapper's own prologue",
                    )
                }
                returns.append(offset)
            }
            offset += 4
        }
        guard returns.count == 1, let ret = returns.first else {
            throw PatcherError.patchSiteNotFound(
                "\(component): expected exactly 1 `retab`/`retabsppc` in the mute-set wrapper, found \(returns.count)",
            )
        }
        let epilogueOffset = try epilogueEntry(in: data, disasm: disasm, retab: ret)

        return MuteSetPlan(
            disasm: disasm,
            textStart: textStart,
            textAddress: text.address,
            functionStartOffset: functionStart,
            functionEndOffset: functionEnd,
            epilogueOffset: epilogueOffset,
            epilogueVMA: text.address + UInt64(epilogueOffset - textStart),
            site: site,
        )
    }

    // MARK: - SP-gate anchoring

    /// Everything the SP-gate patch needs: the routing handler's bounds, the
    /// decline's log block, and the branch that jumps into it. The branch is
    /// found the same way on a pristine and on an already-patched binary —
    /// the patch leaves it intact and rewrites the block's head instead.
    struct SPGatePlan: Sendable {
        let disasm: ARM64Disassembler
        let textStart: Int
        let textAddress: UInt64
        let functionStartOffset: Int
        let functionEndOffset: Int
        let blockHead: Int
        let site: Int

        var functionStartVMA: UInt64 {
            vma(functionStartOffset)
        }

        var functionEndVMA: UInt64 {
            vma(functionEndOffset)
        }

        func vma(_ offset: Int) -> UInt64 {
            textAddress + UInt64(offset - textStart)
        }
    }

    /// How far above a branch target the format-string reference may sit and
    /// still be inside the log block that target heads. Both supported
    /// builds hold the os_log's file-name and format references 0x34 apart,
    /// 0x84 above the block's entry; the budget covers the shape, not those
    /// exact figures.
    private static let spGateBlockWindow = 0x100

    /// The ringtone ('crnp') routing handler both gate patches live in,
    /// resolved once and shared: the SP-missing decline and the volume-mode
    /// precondition sit in the same function, qualified by the same pair of
    /// strings.
    struct PlaybackHandler: Sendable {
        let disasm: ARM64Disassembler
        let textStart: Int
        let textAddress: UInt64
        let functionStartOffset: Int
        let functionEndOffset: Int
        /// The SP-missing format reference that qualified the handler.
        let reference: (adrp: Int, add: Int)
        /// The handler's own source-file string addresses — the corroboration
        /// both gate scans read.
        let fileNameVMAs: Set<UInt64>

        var functionStartVMA: UInt64 {
            vma(functionStartOffset)
        }

        var functionEndVMA: UInt64 {
            vma(functionEndOffset)
        }

        func vma(_ offset: Int) -> UInt64 {
            textAddress + UInt64(offset - textStart)
        }
    }

    /// Resolve the routing handler, or say why not. The anchors are the
    /// SP-missing decline's log format and the handler's own source file:
    /// the format alone names three routing handlers, and of the functions
    /// holding a reference to it, exactly one — ours — also references the
    /// GenericConfig1 file name.
    static func locatePlaybackHandler(in data: Data, file: String = spGateFile) throws -> PlaybackHandler {
        let sections = MachOParser.parseSections(from: data)
        guard let text = sections["__TEXT,__text"] else {
            throw PatcherError.invalidFormat("\(component): no __TEXT,__text section")
        }
        let textStart = Int(text.fileOffset)
        let textEnd = textStart + Int(text.size)
        let disasm = ARM64Disassembler()

        let formats = cStringVMAs(containing: spGateMessage, in: data, sections: sections)
        guard !formats.isEmpty else {
            throw PatcherError.patchSiteNotFound(
                "\(component): the string \"\(spGateMessage)\" is nowhere in the binary's sections",
            )
        }
        let fileNames = cStringVMAs(containing: file, in: data, sections: sections)
        guard !fileNames.isEmpty else {
            throw PatcherError.patchSiteNotFound(
                "\(component): the string \"\(file)\" is nowhere in the binary's sections",
            )
        }

        let references = adrpAddReferences(
            to: 0,
            formingAnyOf: formats,
            in: data,
            textStart: textStart,
            textEnd: textEnd,
        )
        guard !references.isEmpty else {
            throw PatcherError.patchSiteNotFound(
                "\(component): no reference to \"\(spGateMessage)\" in __text",
            )
        }

        var qualified: [(reference: (adrp: Int, add: Int), start: Int, end: Int)] = []
        for reference in references {
            let start = nearestPrologue(in: data, disasm: disasm, below: reference.adrp, floor: textStart)
                ?? textStart
            let end = nearestPrologue(in: data, disasm: disasm, atOrAfter: start + 4, ceiling: textEnd)
                ?? textEnd
            let corroborated = adrpAddReferences(
                to: 0,
                formingAnyOf: fileNames,
                in: data,
                textStart: start,
                textEnd: end,
            )
            if !corroborated.isEmpty {
                qualified.append((reference, start, end))
            }
        }
        guard qualified.count == 1, let handler = qualified.first else {
            throw PatcherError.patchSiteNotFound(
                "\(component): expected exactly 1 \"\(file)\" handler referencing "
                    + "\"\(spGateMessage)\", found \(qualified.count)",
            )
        }
        return PlaybackHandler(
            disasm: disasm,
            textStart: textStart,
            textAddress: text.address,
            functionStartOffset: handler.start,
            functionEndOffset: handler.end,
            reference: handler.reference,
            fileNameVMAs: fileNames,
        )
    }

    /// Resolve the SP-gate branch, or say why not.
    static func locateSPGate(in data: Data, handler which: SPGateHandler = .playback) throws -> SPGatePlan {
        let handler = try locatePlaybackHandler(in: data, file: which.file)
        func vma(_ offset: Int) -> UInt64 {
            handler.vma(offset)
        }
        func offset(of address: UInt64) -> Int {
            handler.textStart + Int(address - handler.textAddress)
        }

        // The gate: the one branch in the handler whose target heads the log
        // block — a target at or above which, within the window, the format
        // reference sits and the handler's own file name is referenced too.
        // The os_log block carries both strings; a branch into any other
        // label in the window does not qualify.
        //
        // Each word is decoded rather than trusted to Capstone's jump group:
        // the gate is a `tbz`, which the group tagging misses, and the op
        // fields the decoded families live in hold nothing but branches.
        // The gate's branch is never rewritten, so the scan resolves the
        // same candidate on a pristine and on an already-patched binary
        // alike.
        var candidates: [(site: Int, head: Int)] = []
        var cursor = handler.functionStartOffset
        while cursor + 4 <= handler.functionEndOffset {
            defer { cursor += 4 }
            guard let insn = handler.disasm.disassembleOne(in: data, at: cursor),
                  !insn.isCall,
                  let word = wordAt(data, cursor),
                  let target = branchTargetValue(insn: word, pc: vma(cursor))
            else { continue }
            let head = offset(of: target)
            guard cursor < head, head >= handler.functionStartOffset,
                  head <= handler.reference.add, handler.reference.add - head <= spGateBlockWindow
            else { continue }
            let names = adrpAddReferences(
                to: 0,
                formingAnyOf: handler.fileNameVMAs,
                in: data,
                textStart: head,
                textEnd: handler.reference.add + 4,
            )
            guard !names.isEmpty else { continue }
            // The head must be the block's own opening — the os_log size
            // move and the allocation call, which is exactly what the patch
            // rewrites — or, once it has run, the branch back to the gate's
            // fall-through that replaced them. Any other label inside the
            // window is not the block's head, whichever branch lands on it.
            let headInsn = handler.disasm.disassembleOne(in: data, at: head)
            let opensLog = isExceptionSizeMove(headInsn)
                && handler.disasm.disassembleOne(in: data, at: head + 4)?.isCall == true
            let holdsOurBranch: Bool = {
                guard let insn = headInsn, insn.isJump, !insn.isCall,
                      insn.detail?.conditionCode == nil,
                      let word = wordAt(data, head)
                else { return false }
                return ARM64Encoder.decodeBranchTarget(insn: word, pc: vma(head)) == vma(cursor) + 4
            }()
            guard opensLog || holdsOurBranch else { continue }
            candidates.append((cursor, head))
        }
        guard candidates.count == 1, let gate = candidates.first else {
            throw PatcherError.patchSiteNotFound(
                "\(component): expected exactly 1 branch into the SP-missing log block in "
                    + "the handler at 0x\(hex(vma(handler.functionStartOffset))), found \(candidates.count)",
            )
        }

        // The block is entered only by the gate's jump: the instruction
        // above its head must not fall through. That is what makes rewriting
        // the head safe — nothing else arrives at the block expecting the
        // os_log the head used to open.
        guard let above = handler.disasm.disassembleOne(in: data, at: gate.head - 4),
              above.mnemonic == "brk" || returnMnemonics.contains(above.mnemonic)
              || (above.isJump && !above.isCall && above.detail?.conditionCode == nil)
        else {
            throw PatcherError.invalidFormat(
                "\(component): the log block at 0x\(hex(vma(gate.head))) is reached by "
                    + "fall-through, not only by the gate's jump",
            )
        }

        return SPGatePlan(
            disasm: handler.disasm,
            textStart: handler.textStart,
            textAddress: handler.textAddress,
            functionStartOffset: handler.functionStartOffset,
            functionEndOffset: handler.functionEndOffset,
            blockHead: gate.head,
            site: gate.site,
        )
    }

    // MARK: - Volume-gate anchoring

    /// Everything the volume-gate patch needs: the routing handler's bounds,
    /// the decline's log block, and the comparison that jumps into it. The
    /// comparison is found the same way on a pristine and on an
    /// already-patched binary — the patch leaves it intact and rewrites the
    /// block's head instead.
    struct VolumeGatePlan: Sendable {
        let disasm: ARM64Disassembler
        let textStart: Int
        let textAddress: UInt64
        let functionStartOffset: Int
        let functionEndOffset: Int
        let blockHead: Int
        let site: Int

        var functionStartVMA: UInt64 {
            vma(functionStartOffset)
        }

        var functionEndVMA: UInt64 {
            vma(functionEndOffset)
        }

        func vma(_ offset: Int) -> UInt64 {
            textAddress + UInt64(offset - textStart)
        }
    }

    /// How far above a branch target the precondition block's format and
    /// file-name references may sit. Both supported builds hold them 0x2c
    /// and 0x58 above the block's entry — the same layout every decline log
    /// in this handler carries; the budget covers the shape, not those
    /// exact figures.
    private static let volumeGateBlockWindow = 0x100

    /// Resolve the volume-mode comparison and its decline, or say why not.
    /// The decline is one of three in this handler that open with the same
    /// PRECONDITION FAILURE format; what picks ours out is the comparison
    /// that reaches it — the only one that masks a lookup's return with the
    /// 33-bit volume-mode packing mask and compares it against the expected
    /// packed pair. The sibling preconditions branch off plain flag tests.
    static func locateVolumeGate(in data: Data) throws -> VolumeGatePlan {
        let sections = MachOParser.parseSections(from: data)
        let handler = try locatePlaybackHandler(in: data)
        let formats = cStringVMAs(containing: volumePreconditionFormat, in: data, sections: sections)
        guard !formats.isEmpty else {
            throw PatcherError.patchSiteNotFound(
                "\(component): the string \"\(volumePreconditionFormat)\" is nowhere in the binary's sections",
            )
        }
        func vma(_ offset: Int) -> UInt64 {
            handler.vma(offset)
        }
        func offset(of address: UInt64) -> Int {
            handler.textStart + Int(address - handler.textAddress)
        }

        // The comparison: the one branch in the handler whose target heads a
        // precondition log block — both the format and the handler's own
        // file name referenced within the window, and the target opening the
        // os_log allocation — and whose own backward window holds the
        // packing-mask `and` over a call's return, closed by the branch.
        // Each word is decoded rather than trusted to Capstone's jump group:
        // the comparison's branch is a `b.ne`, and the op fields the decoded
        // families live in hold nothing but branches. The branch is never
        // rewritten, so the scan resolves the same candidate on a pristine
        // and on an already-patched binary alike.
        var candidates: [(site: Int, head: Int)] = []
        var cursor = handler.functionStartOffset
        while cursor + 4 <= handler.functionEndOffset {
            defer { cursor += 4 }
            guard let insn = handler.disasm.disassembleOne(in: data, at: cursor),
                  !insn.isCall,
                  let word = wordAt(data, cursor),
                  let target = branchTargetValue(insn: word, pc: vma(cursor))
            else { continue }
            let head = offset(of: target)
            guard cursor < head, head >= handler.functionStartOffset,
                  !adrpAddReferences(
                      to: 0,
                      formingAnyOf: formats,
                      in: data,
                      textStart: head,
                      textEnd: head + volumeGateBlockWindow,
                  ).isEmpty,
                  !adrpAddReferences(
                      to: 0,
                      formingAnyOf: handler.fileNameVMAs,
                      in: data,
                      textStart: head,
                      textEnd: head + volumeGateBlockWindow,
                  ).isEmpty
            else { continue }
            // The head must be the block's own opening — the os_log size
            // move and the allocation call, which is exactly what the patch
            // rewrites — or, once it has run, the branch back to the
            // comparison's fall-through that replaced them. The block's own
            // exception-allocation label and its log-enable skips hold size
            // moves too; the comparison window below the branch is what
            // rejects them.
            let headInsn = handler.disasm.disassembleOne(in: data, at: head)
            let opensLog = isExceptionSizeMove(headInsn)
                && handler.disasm.disassembleOne(in: data, at: head + 4)?.isCall == true
            let holdsOurBranch: Bool = {
                guard let insn = headInsn, insn.isJump, !insn.isCall,
                      insn.detail?.conditionCode == nil,
                      let word = wordAt(data, head)
                else { return false }
                return ARM64Encoder.decodeBranchTarget(insn: word, pc: vma(head)) == vma(cursor) + 4
            }()
            guard opensLog || holdsOurBranch,
                  isVolumeModeComparison(in: data, disasm: handler.disasm, below: cursor)
            else { continue }
            candidates.append((cursor, head))
        }
        guard candidates.count == 1, let gate = candidates.first else {
            throw PatcherError.patchSiteNotFound(
                "\(component): expected exactly 1 volume-mode comparison guarding a "
                    + "precondition decline in the handler at 0x\(hex(vma(handler.functionStartOffset))), "
                    + "found \(candidates.count)",
            )
        }

        // The block is entered only by the comparison's jump: the
        // instruction above its head must not fall through. That is what
        // makes rewriting the head safe — nothing else arrives at the block
        // expecting the os_log the head used to open.
        guard let above = handler.disasm.disassembleOne(in: data, at: gate.head - 4),
              above.mnemonic == "brk" || returnMnemonics.contains(above.mnemonic)
              || (above.isJump && !above.isCall && above.detail?.conditionCode == nil)
        else {
            throw PatcherError.invalidFormat(
                "\(component): the precondition block at 0x\(hex(vma(gate.head))) is reached by "
                    + "fall-through, not only by the comparison's jump",
            )
        }

        return VolumeGatePlan(
            disasm: handler.disasm,
            textStart: handler.textStart,
            textAddress: handler.textAddress,
            functionStartOffset: handler.functionStartOffset,
            functionEndOffset: handler.functionEndOffset,
            blockHead: gate.head,
            site: gate.site,
        )
    }

    /// Whether the branch at `branch` closes a volume-mode comparison: the
    /// packing-mask `and` over a lookup's return within a few instructions
    /// below it, a `cmp` between the two, and the call that produced the
    /// masked value directly below the `and`. The sibling preconditions in
    /// this handler branch off plain flag tests, so this is what tells the
    /// declines apart.
    private static func isVolumeModeComparison(
        in data: Data,
        disasm: ARM64Disassembler,
        below branch: Int,
    ) -> Bool {
        var sawCompare = false
        var cursor = branch - 4
        // Six instructions reach from the branch past the whole masked
        // compare on both supported builds (`cmp; add; and; bl`).
        while cursor >= branch - 24 {
            defer { cursor -= 4 }
            guard let insn = disasm.disassembleOne(in: data, at: cursor) else { return false }
            if insn.mnemonic == "cmp" {
                sawCompare = true
            }
            guard insn.mnemonic == "and",
                  let operands = insn.detail?.operands, operands.count >= 3,
                  operands[2].type == .immediate,
                  operands[2].imm == volumeModePackingMask
            else { continue }
            // The masked value is a lookup's return: the call that produced
            // it sits directly below the `and`.
            guard disasm.disassembleOne(in: data, at: cursor - 4)?.isCall == true else { return false }
            return sawCompare
        }
        return false
    }

    // MARK: - Device-state null-gate anchoring

    /// One gated device-state update, in file-offset terms.
    struct DeviceStateNullGateSite: Sendable {
        /// The gate-check `bl` — the instruction the patch redirects.
        let gateCall: Int
        /// The `cbz w0, <skip>` that tests the call's answer.
        let branch: Int
        /// Where the branch skips to — past the whole update.
        let target: UInt64
        /// The gate slot already calls TheInstance: this patch's own
        /// earlier write, recognised rather than repeated.
        let alreadyGated: Bool
    }

    /// Everything the null-gate patch needs: TheInstance's own entry and
    /// the gated callers whose gate-check calls it redirects.
    struct DeviceStateNullGatePlan: Sendable {
        let disasm: ARM64Disassembler
        let textStart: Int
        let textAddress: UInt64
        let theInstanceOffset: Int
        let sites: [DeviceStateNullGateSite]

        var theInstanceVMA: UInt64 {
            vma(theInstanceOffset)
        }

        func vma(_ offset: Int) -> UInt64 {
            textAddress + UInt64(offset - textStart)
        }
    }

    /// How many direct callers of TheInstance must carry the gated shape —
    /// one per device-state update VirtualAudio_Device pushes at the
    /// manager. A build with a different count is refused, not half-patched.
    private static let deviceStateNullGateSiteCount = 2

    /// Resolve TheInstance and its gated device-state callers, or say why
    /// not. The singleton is found from its own diagnostic — the log it
    /// prints when asked for an instance nobody published — and the
    /// callers from the shape every device-state update shares around its
    /// `bl`.
    static func locateDeviceStateNullGate(in data: Data) throws -> DeviceStateNullGatePlan {
        let sections = MachOParser.parseSections(from: data)
        guard let text = sections["__TEXT,__text"] else {
            throw PatcherError.invalidFormat("\(component): no __TEXT,__text section")
        }
        let textStart = Int(text.fileOffset)
        let textEnd = textStart + Int(text.size)
        let disasm = ARM64Disassembler()
        func vma(_ offset: Int) -> UInt64 {
            text.address + UInt64(offset - textStart)
        }

        // TheInstance, from its own diagnostic: the null-answer log is
        // referenced exactly once in __text, by the singleton's accessor.
        let anchors = cStringVMAs(containing: deviceStateInstanceMissing, in: data, sections: sections)
        guard !anchors.isEmpty else {
            throw PatcherError.patchSiteNotFound(
                "\(component): the string \"\(deviceStateInstanceMissing)\" is nowhere in the binary's sections",
            )
        }
        let references = adrpAddReferences(
            to: 0,
            formingAnyOf: anchors,
            in: data,
            textStart: textStart,
            textEnd: textEnd,
        )
        guard references.count == 1 else {
            throw PatcherError.patchSiteNotFound(
                "\(component): expected exactly 1 reference to \"\(deviceStateInstanceMissing)\", "
                    + "found \(references.count)",
            )
        }
        guard let theInstance = nearestPrologue(
            in: data, disasm: disasm, below: references[0].adrp, floor: textStart,
        ) else {
            throw PatcherError.patchSiteNotFound(
                "\(component): no function prologue above the \"\(deviceStateInstanceMissing)\" reference",
            )
        }

        // Every direct caller, kept where the gated device-state shape
        // holds around the call.
        var sites: [DeviceStateNullGateSite] = []
        var offset = textStart
        while offset + 4 <= textEnd {
            defer { offset += 4 }
            guard let insn = disasm.disassembleOne(in: data, at: offset), insn.isCall,
                  let word = wordAt(data, offset),
                  let target = ARM64Encoder.decodeBranchTarget(insn: word, pc: vma(offset)),
                  target == vma(theInstance)
            else { continue }
            if let site = gatedDeviceStateSite(
                in: data, disasm: disasm, call: offset, vma: vma, theInstance: vma(theInstance),
            ) {
                sites.append(site)
            }
        }
        guard sites.count == deviceStateNullGateSiteCount else {
            throw PatcherError.patchSiteNotFound(
                "\(component): expected exactly \(deviceStateNullGateSiteCount) gated device-state "
                    + "updates around TheInstance at 0x\(hex(vma(theInstance))), found \(sites.count)",
            )
        }

        return DeviceStateNullGatePlan(
            disasm: disasm,
            textStart: textStart,
            textAddress: text.address,
            theInstanceOffset: theInstance,
            sites: sites.sorted { $0.gateCall < $1.gateCall },
        )
    }

    /// Whether a direct `bl` to TheInstance sits in the gated device-state
    /// shape: a gate-check call at −8 (pristine, any callee — or
    /// TheInstance again once this patch has redirected it), the `cbz w0`
    /// at −4 skipping forward past the whole update, the singleton's
    /// return moved aside at +4 (`mov xN, x0`), and that return
    /// dereferenced unchecked at +8 (`ldr xM, [x0]`) — the read that
    /// faults when nobody published. The singleton's other callers either
    /// test its answer or live behind the haptic attenuation delegate's
    /// own capability flag, and match nothing here.
    static func gatedDeviceStateSite(
        in data: Data,
        disasm: ARM64Disassembler,
        call: Int,
        vma: (Int) -> UInt64,
        theInstance: UInt64,
    ) -> DeviceStateNullGateSite? {
        guard call >= 8 else { return nil }

        // The singleton's answer, moved aside and then read unchecked:
        // `mov xN, x0` directly above `ldr xM, [x0]`.
        guard let saved = disasm.disassembleOne(in: data, at: call + 4),
              saved.mnemonic == "mov",
              let savedOps = saved.detail?.operands, savedOps.count == 2,
              savedOps[0].type == .register, savedOps[1].type == .register,
              savedOps[1].reg.rawValue == ARM64Register.x(0).rawValue,
              let deref = disasm.disassembleOne(in: data, at: call + 8),
              deref.mnemonic == "ldr",
              let derefOps = deref.detail?.operands, derefOps.count == 2,
              derefOps[0].type == .register,
              derefOps[1].type == .memory, derefOps[1].mem.base == ARM64Register.x(0)
        else { return nil }

        // The gate: the call whose answer the branch below it tests.
        guard let gateCall = disasm.disassembleOne(in: data, at: call - 8), gateCall.isCall,
              let gateWord = wordAt(data, call - 8),
              let gateCallee = ARM64Encoder.decodeBranchTarget(insn: gateWord, pc: vma(call - 8))
        else { return nil }
        // Pristine, the gate slot calls anything but TheInstance; once
        // redirected, it calls TheInstance and the shape is our own work.
        let alreadyGated = gateCallee == theInstance

        guard let gateInsn = disasm.disassembleOne(in: data, at: call - 4),
              gateInsn.mnemonic == "cbz",
              let operands = gateInsn.detail?.operands, operands.count == 2,
              operands[0].type == .register, operands[0].reg.rawValue == ARM64Register.w(0).rawValue,
              let gateBranchWord = wordAt(data, call - 4),
              let target = decodeConditionalBranchTarget(insn: gateBranchWord, pc: vma(call - 4))
        else { return nil }
        // The skip must clear the dereference: the branch and its target
        // bracket the whole device-state update the patch gates.
        guard target > vma(call + 8) else { return nil }
        return DeviceStateNullGateSite(
            gateCall: call - 8, branch: call - 4, target: target, alreadyGated: alreadyGated,
        )
    }

    /// The arm64 ABI a thin plugin is built for: arm64e.x1 (the X1
    /// extension, iOS 27.1's iPhone19,4 userland), any other arm64 subtype
    /// (plain arm64e covers 26.x and 27.0), or not an arm64 image at all —
    /// in which case the caller's own anchoring refuses the file. The
    /// subtype is masked the way the X1 bootstrap patcher masks fat slices:
    /// the LIB64 bit is not part of the ABI number.
    enum PluginArm64Subtype {
        case x1
        case other
        case notArm64
    }

    static func arm64Subtype(of data: Data) -> PluginArm64Subtype {
        guard let magic = wordAt(data, 0), magic == 0xFEED_FACF,
              let cpuType = wordAt(data, 4), cpuType == 0x0100_000C,
              let cpuSubtype = wordAt(data, 8)
        else { return .notArm64 }
        return cpuSubtype & 0x00FF_FFFF == 12 ? .x1 : .other
    }

    /// The target of a jump word, whichever immediate family encodes it:
    /// `ARM64Encoder.decodeBranchTarget` reads `b`/`bl`, this adds nothing
    /// for them and defers to ``decodeConditionalBranchTarget`` for the
    /// rest.
    private static func branchTargetValue(insn word: UInt32, pc: UInt64) -> UInt64? {
        ARM64Encoder.decodeBranchTarget(insn: word, pc: pc)
            ?? decodeConditionalBranchTarget(insn: word, pc: pc)
    }

    /// The target of the conditional-branch families, which
    /// ``ARM64Encoder.decodeBranchTarget(insn:pc:)`` (the `b`/`bl` pair)
    /// does not decode: `b.cond` and `cbz`/`cbnz` carry a 19-bit immediate
    /// at bits 23-5, `tbz`/`tbnz` a 14-bit one at bits 18-5. The SP-gate
    /// branch is a `tbz`. Analysis only: this reads where a branch goes, it
    /// assembles nothing.
    static func decodeConditionalBranchTarget(insn: UInt32, pc: UInt64) -> UInt64? {
        // b.cond: bits 31-24 = 01010100. The PAUTH BC.cond shares the top
        // seven bits but sets bit 24, and names a register, not an offset.
        if insn >> 24 == 0b0101_0100 {
            let imm19 = (insn >> 5) & 0x7FFFF
            let signed = Int32(bitPattern: imm19 << 13) >> 13
            return UInt64(Int64(pc) + Int64(signed) * 4)
        }
        // cbz/cbnz (bits 30-25 = 011010) and tbz/tbnz (011011): the leading
        // bit is sf/b5, which does not change how far the branch reaches.
        switch (insn >> 25) & 0x3F {
        case 0b011010:
            let imm19 = (insn >> 5) & 0x7FFFF
            let signed = Int32(bitPattern: imm19 << 13) >> 13
            return UInt64(Int64(pc) + Int64(signed) * 4)
        case 0b011011:
            let imm14 = (insn >> 5) & 0x3FFF
            let signed = Int32(bitPattern: imm14 << 18) >> 18
            return UInt64(Int64(pc) + Int64(signed) * 4)
        default:
            return nil
        }
    }

    /// Whether the window after an allocation call holds the CAException
    /// throw machinery: the vtable or status stored into the allocated object
    /// (`str xN, [x0, #imm]`), the throw call after it, and the block's
    /// terminator. A CAException carries no message string, so the
    /// `runtime_error` shape (`isThrowBlock`) does not fit it.
    private static func isCAExceptionThrowBlock(
        in data: Data,
        disasm: ARM64Disassembler,
        from offset: Int,
        to end: Int,
    ) -> Bool {
        var cursor = offset
        var sawObjectStore = false
        var sawThrowCall = false
        var scanned = 0
        // A CAException block runs longer than a runtime_error one — the
        // vtable and its PAC discriminators, the status store, the typeinfo
        // pointer — 17 instructions on both supported builds before the
        // terminator, so the budget reaches past it.
        while cursor + 4 <= end, scanned < 32 {
            defer {
                cursor += 4
                scanned += 1
            }
            guard let insn = disasm.disassembleOne(in: data, at: cursor) else { return false }
            if insn.mnemonic == "str",
               let operands = insn.detail?.operands, operands.count >= 2,
               operands[0].type == .register,
               operands[1].type == .memory, operands[1].mem.base == ARM64Register.x(0)
            {
                sawObjectStore = true
            }
            if insn.isCall, sawObjectStore {
                sawThrowCall = true
                continue
            }
            // The block ends at an unconditional branch (the iOS 27 twin jumps
            // to its `brk`) or at the `brk` the compiler plants after a call
            // it knows never returns.
            if insn.mnemonic == "brk"
                || (insn.isJump && !insn.isCall && insn.detail?.conditionCode == nil)
            {
                return sawObjectStore && sawThrowCall
            }
        }
        return false
    }

    /// Whether an adrp+add pair within `window` bytes above the site forms
    /// one of `targets` — the EXCEPTION log that always precedes this throw.
    private static func hasExceptionLogWindow(
        in data: Data,
        textStart: Int,
        before site: Int,
        targets: Set<UInt64>,
        window: Int = 0x40,
    ) -> Bool {
        !adrpAddReferences(
            to: 0,
            formingAnyOf: targets,
            in: data,
            textStart: max(textStart, site - window),
            textEnd: site,
        ).isEmpty
    }

    /// The address of the cstring containing `needle`, in a real string
    /// section. The os_log formats begin with a `%25s:%-5d` prefix, so the
    /// reference the code materialises points at the whole string's start,
    /// not at the needle itself.
    private static func cStringVMA(containing needle: String, in data: Data, sections: [String: MachOSectionInfo]) -> UInt64? {
        cStringVMAs(containing: needle, in: data, sections: sections).first
    }

    /// Every such address, one per section occurrence — a message can live in
    /// more than one string, and the callers only need the set for
    /// corroboration.
    private static func cStringVMAs(containing needle: String, in data: Data, sections: [String: MachOSectionInfo]) -> Set<UInt64> {
        let bytes = Array(needle.utf8)
        // cstring sections first, then any other section that still holds
        // file bytes; the signature and symbol tables are not sections.
        let searchable = sections.values
            .filter { $0.fileOffset > 0 && Int($0.fileOffset) + Int($0.size) <= data.count }
            .sorted { lhs, rhs in
                let l = lhs.sectionName == "__cstring"
                let r = rhs.sectionName == "__cstring"
                if l != r {
                    return l
                }
                return lhs.fileOffset < rhs.fileOffset
            }
        var addresses: Set<UInt64> = []
        for section in searchable {
            let start = Int(section.fileOffset)
            let end = start + Int(section.size)
            var searchFrom = start
            while searchFrom + bytes.count <= end,
                  let match = range(of: bytes, in: data, start: searchFrom, end: end)
            {
                let stringStart = cStringStart(in: data, containing: match, notBefore: start)
                addresses.insert(section.address + UInt64(stringStart - start))
                searchFrom = match + 1
            }
        }
        return addresses
    }

    /// The walker's direct `std::terminate` call. The compiler ends a
    /// fault-logged fatal path with a run of back-to-back `bl`s — the log, its
    /// releases — closed by the terminate call, whose successor is never a
    /// call. Anchored on the fault's own string, not on the stub address.
    private static func terminateSite(
        in data: Data,
        disasm: ARM64Disassembler,
        sections: [String: MachOSectionInfo],
        textStart _: Int,
        textEnd _: Int,
        walkerStart: Int,
        walkerEnd: Int,
        epilogueVMA: UInt64,
        includePatched: Bool = false,
        requireUniqueReference: Bool = false,
    ) -> Int? {
        let needle = Array((terminateFault + "\0").utf8)
        var faultVMA: UInt64?
        for section in sections.values
            where section.fileOffset > 0 && Int(section.fileOffset) + Int(section.size) <= data.count
        {
            let start = Int(section.fileOffset)
            let end = start + Int(section.size)
            if let match = range(of: needle, in: data, start: start, end: end) {
                faultVMA = section.address + UInt64(match - start)
                break
            }
        }
        guard let faultVMA else { return nil }
        let references = adrpAddReferences(
            to: 0,
            formingAnyOf: [faultVMA],
            in: data,
            textStart: walkerStart,
            textEnd: walkerEnd,
        )
        guard !requireUniqueReference || references.count == 1,
              let reference = references.first else { return nil }

        // The fault logger: the first call after the string reference,
        // following any unconditional branch its argument setup ends with.
        var cursor = reference.add + 4
        var steps = 0
        var faultLogger: Int?
        while cursor + 4 <= walkerEnd, steps < 32 {
            defer {
                cursor += 4
                steps += 1
            }
            guard let insn = disasm.disassembleOne(in: data, at: cursor) else { return nil }
            if insn.isCall {
                faultLogger = cursor
                break
            }
            if insn.isJump, !insn.isCall, insn.detail?.conditionCode == nil,
               let target = branchTarget(insn, at: cursor), target >= walkerStart, target < walkerEnd
            {
                cursor = Int(target) - 4 // the defer moves past it
                continue
            }
        }
        guard let logger = faultLogger else { return nil }

        // The back-to-back call run the logger opens; its last call, followed
        // by anything but a call, is the terminate.
        var call = logger
        var site: Int?
        while call + 8 <= walkerEnd {
            let nextOffset = call + 4
            guard let next = disasm.disassembleOne(in: data, at: nextOffset) else { break }
            if next.isCall {
                site = nextOffset
                call = nextOffset
                continue
            }
            break
        }
        // Already patched: the run now ends one call early, and what follows
        // its last call is our branch to the epilogue. Recognise it rather
        // than eating the release on every re-run.
        if let site,
           let after = disasm.disassembleOne(in: data, at: site + 4),
           after.isJump, !after.isCall,
           let word = wordAtCache(data: after.bytes, offset: 0),
           let target = ARM64Encoder.decodeBranchTarget(insn: word, pc: UInt64(site + 4)),
           target == epilogueVMA
        {
            return includePatched ? site + 4 : nil
        }
        return site
    }

    private static func branchTarget(_ insn: ARM64Instruction, at offset: Int) -> UInt64? {
        guard let word = wordAtCache(data: insn.bytes, offset: 0) else { return nil }
        return ARM64Encoder.decodeBranchTarget(insn: word, pc: UInt64(offset))
    }

    private static func wordAtCache(data bytes: [UInt8], offset _: Int) -> UInt32? {
        guard bytes.count >= 4 else { return nil }
        return UInt32(bytes[0]) | UInt32(bytes[1]) << 8 | UInt32(bytes[2]) << 16 | UInt32(bytes[3]) << 24
    }

    // MARK: - Frame signing

    /// The instructions that sign LR with the B key against SP as a function
    /// opens. arm64e builds use `pacibsp`; an arm64e.x1 userland (iOS 27.1's
    /// iPhone19,4) is built with FEAT_PAuth_LR and opens every function with
    /// `pacibsppc`, which adds the signing instruction's own address to the
    /// modifier. VirtualAudio is patched before any X1 lowering, so it is
    /// read in its native form.
    static let prologueMnemonics: Set<String> = ["pacibsp", "pacibsppc", "pacnbibsppc"]

    /// The returns that authenticate an LR signed by one of
    /// `prologueMnemonics`: `retab`, or its PAuth_LR forms — `retabsppc
    /// <label>`, whose label is the `pacibsppc` that signed, and the register
    /// form, which Capstone also names `retabsppc` (`retabsppcr` is LLVM's
    /// name, kept for a decoder that uses it). A plain `ret`, a `retaa*` or
    /// an `autib*` + `ret` pair closes something else, and is not an
    /// epilogue these patches branch to.
    static let authenticatedReturnMnemonics: Set<String> = ["retab", "retabsppc", "retabsppcr"]

    /// Every return, of either key and either PAuth form: an instruction
    /// that never falls through to the one after it.
    static let returnMnemonics: Set<String> = [
        "ret", "retaa", "retab", "retaasppc", "retabsppc", "retaasppcr", "retabsppcr",
    ]

    static func isPrologue(_ insn: ARM64Instruction?) -> Bool {
        guard let insn else { return false }
        return prologueMnemonics.contains(insn.mnemonic)
    }

    static func isAuthenticatedReturn(_ insn: ARM64Instruction?) -> Bool {
        guard let insn else { return false }
        return authenticatedReturnMnemonics.contains(insn.mnemonic)
    }

    /// Whether the return at `offset` closes the function whose prologue is
    /// at `prologue`. The label form of `retabsppc` names its signing
    /// instruction, and it must be that prologue — a return that
    /// authenticates against another frame is refused. `retab` and the
    /// register form (`retabsppc xN`) carry no label and are taken as they
    /// are, bounded by the function the caller already walked.
    static func returnCloses(_ insn: ARM64Instruction, at offset: Int, prologue: Int) -> Bool {
        guard insn.mnemonic == "retabsppc",
              insn.detail?.operands.first?.type != .register
        else { return true }
        return retabsppcLabel(insn, at: offset) == prologue
    }

    /// Where the label form of `retabsppc` at `offset` points: the
    /// `pacibsppc` whose address entered the LR's signature. The label is
    /// `imm16` words *back* from the return (bits 20-5, unsigned), which
    /// Capstone decodes as `#0` whatever the field holds — its PAuth_LR
    /// support stops at the mnemonic — so the field is read off the word
    /// Capstone already identified. Analysis only: this assembles nothing.
    static func retabsppcLabel(_ insn: ARM64Instruction, at offset: Int) -> Int? {
        guard insn.mnemonic == "retabsppc", insn.bytes.count == 4 else { return nil }
        let word = UInt32(insn.bytes[0]) | UInt32(insn.bytes[1]) << 8
            | UInt32(insn.bytes[2]) << 16 | UInt32(insn.bytes[3]) << 24
        // RETABSPPC <label>: 0101_0101_0010_0000 | imm16 << 5 | 11111 — the
        // B-key form (bit 21) of the PC-relative return; anything else is
        // the register form or not this instruction.
        guard word & 0xFFE0_001F == 0x5520_001F else { return nil }
        return offset - Int((word >> 5) & 0xFFFF) * 4
    }

    /// The nearest function prologue at or before `below`.
    static func nearestPrologue(in data: Data, disasm: ARM64Disassembler, below: Int, floor: Int) -> Int? {
        var offset = min(below, floor + ((below - floor) & ~3))
        while offset >= floor {
            if isPrologue(disasm.disassembleOne(in: data, at: offset)) {
                return offset
            }
            offset -= 4
        }
        return nil
    }

    /// The nearest function prologue at or after `atOrAfter`.
    static func nearestPrologue(in data: Data, disasm: ARM64Disassembler, atOrAfter: Int, ceiling: Int) -> Int? {
        var offset = atOrAfter
        while offset + 4 <= ceiling {
            if isPrologue(disasm.disassembleOne(in: data, at: offset)) {
                return offset
            }
            offset += 4
        }
        return nil
    }

    /// Whether the window after an allocation call holds the whole throw
    /// machinery: a message load into x1, a constructor call, and the block's
    /// terminating branch.
    private static func isThrowBlock(
        in data: Data,
        disasm: ARM64Disassembler,
        from offset: Int,
        to end: Int,
    ) -> Bool {
        var cursor = offset
        var sawMessageLoad = false
        var sawConstructorCall = false
        var scanned = 0
        while cursor + 4 <= end, scanned < 16 {
            defer {
                cursor += 4
                scanned += 1
            }
            guard let insn = disasm.disassembleOne(in: data, at: cursor) else { return false }
            if insn.mnemonic == "adrp",
               let operands = insn.detail?.operands, operands.count >= 2,
               operands[0].reg == ARM64Register.x(1)
            {
                if let low = disasm.disassembleOne(in: data, at: cursor + 4), low.mnemonic == "add",
                   let lowOps = low.detail?.operands, lowOps.count >= 3,
                   lowOps[0].reg == ARM64Register.x(1), lowOps[1].reg == ARM64Register.x(1)
                {
                    sawMessageLoad = true
                }
            }
            if insn.isCall, sawMessageLoad {
                sawConstructorCall = true
                continue
            }
            // The block ends at an unconditional branch (to a resume path or
            // a tail-called throw) or at the `brk` the compiler plants after
            // a call it knows never returns.
            if insn.mnemonic == "brk"
                || (insn.isJump, !insn.isCall, insn.detail?.conditionCode == nil) == (true, true, true)
            {
                return sawMessageLoad && sawConstructorCall
            }
        }
        return false
    }

    /// A cstring that *contains* the message — the diagnostic log's format
    /// string — with an adrp+add reference within `window` bytes above the
    /// throw. The exception and its log always come as this pair, so a
    /// message string whose only reference is not corroborated by a log
    /// reference nearby is not this site.
    private static func nearbyLogReference(
        in data: Data,
        sections: [String: MachOSectionInfo],
        textStart: Int,
        textEnd _: Int,
        before offset: Int,
        window: Int = 0x100,
    ) -> (adrp: Int, add: Int)? {
        let messageBytes = Array(message.utf8)
        let formats: [UInt64] = sections.values
            .filter { $0.fileOffset > 0 && Int($0.fileOffset) + Int($0.size) <= data.count }
            .compactMap { section in
                let start = Int(section.fileOffset)
                let end = start + Int(section.size)
                guard let match = range(of: messageBytes, in: data, start: start, end: end) else { return nil }
                let stringStart = cStringStart(in: data, containing: match, notBefore: start)
                let stringEnd = cStringEnd(in: data, from: stringStart, notAfter: end)
                guard stringEnd - stringStart > messageBytes.count + 8 else { return nil }
                return section.address + UInt64(stringStart - start)
            }
        guard !formats.isEmpty else { return nil }
        return adrpAddReferences(
            to: 0,
            formingAnyOf: Set(formats),
            in: data,
            textStart: max(textStart, offset - window),
            textEnd: offset,
        ).first
    }

    /// The `No default VAD present` C string, in a real string section.
    private static func locateMessage(in data: Data, sections: [String: MachOSectionInfo]) throws -> UInt64 {
        let needle = Array((message + "\0").utf8)
        // cstring sections first, then any other section that still holds
        // file bytes; the signature and symbol tables are not sections.
        let searchable = sections.values
            .filter { $0.fileOffset > 0 && Int($0.fileOffset) + Int($0.size) <= data.count }
            .sorted { lhs, rhs in
                let l = lhs.sectionName == "__cstring"
                let r = rhs.sectionName == "__cstring"
                if l != r {
                    return l
                }
                return lhs.fileOffset < rhs.fileOffset
            }
        for section in searchable {
            let start = Int(section.fileOffset)
            let end = start + Int(section.size)
            guard end - start >= needle.count else { continue }
            guard let match = range(of: needle, in: data, start: start, end: end) else { continue }
            return section.address + UInt64(match - start)
        }
        throw PatcherError.patchSiteNotFound(
            "\(component): the string \"\(message)\" is nowhere in the binary's sections",
        )
    }

    /// Every `adrp Xn, page ; add Xn, Xn, #low` pair in `__text` whose sum is
    /// `target`, in file-offset terms.
    private static func adrpAddReferences(
        to target: UInt64,
        in data: Data,
        textStart: Int,
        textEnd: Int,
    ) -> [(adrp: Int, add: Int)] {
        adrpAddReferences(to: 0, formingAnyOf: [target], in: data, textStart: textStart, textEnd: textEnd)
    }

    /// The same pairs, matching any target in a set.
    private static func adrpAddReferences(
        to _: UInt64,
        formingAnyOf targets: Set<UInt64>,
        in data: Data,
        textStart: Int,
        textEnd: Int,
    ) -> [(adrp: Int, add: Int)] {
        let disasm = ARM64Disassembler()
        var references: [(Int, Int)] = []
        var offset = textStart
        while offset + 8 <= textEnd {
            defer { offset += 4 }
            guard let adrp = disasm.disassembleOne(in: data, at: offset), adrp.mnemonic == "adrp",
                  let add = disasm.disassembleOne(in: data, at: offset + 4), add.mnemonic == "add",
                  let page = adrp.detail?.operands, page.count >= 2,
                  let low = add.detail?.operands, low.count >= 3,
                  page[0].reg == low[1].reg,
                  page[1].type == .immediate, low[2].type == .immediate,
                  targets.contains(UInt64(page[1].imm + low[2].imm))
            else { continue }
            references.append((offset, offset + 4))
        }
        return references
    }

    /// The first unconditional, non-call branch after `offset` — the throw
    /// block's terminator, whether it jumps to a resume path or tail-calls
    /// the throw itself.
    private static func firstUnconditionalBranch(
        in data: Data,
        disasm: ARM64Disassembler,
        after offset: Int,
        textEnd: Int,
    ) -> Int? {
        var cursor = offset
        var scanned = 0
        while cursor + 4 <= textEnd, scanned < 16 {
            defer {
                cursor += 4
                scanned += 1
            }
            guard let insn = disasm.disassembleOne(in: data, at: cursor) else { return nil }
            if insn.isCall {
                continue
            }
            if insn.mnemonic == "brk" || (insn.isJump && insn.detail?.conditionCode == nil) {
                return cursor
            }
        }
        return nil
    }

    /// `mov w0, #<size>` — the instruction that sizes a std::exception.
    static func isExceptionSizeMove(_ insn: ARM64Instruction?) -> Bool {
        guard let insn else { return false }
        guard ["mov", "movz"].contains(insn.mnemonic),
              let operands = insn.detail?.operands, operands.count == 2
        else { return false }
        return operands[0].type == .register
            && operands[0].reg == ARM64Register.w(0)
            && operands[1].type == .immediate
            && (0 ... 0x100).contains(operands[1].imm)
    }

    /// The function epilogue's entry, found after the throw: the stack-guard
    /// load when the function is built with the protector (iOS 26), or the
    /// first frame restore when it is not (iOS 27).
    static func locateEpilogue(
        in data: Data,
        disasm: ARM64Disassembler,
        after offset: Int,
        prologue: Int,
        textEnd: Int,
    ) throws -> Int {
        // The first authenticated return after the throw ends the epilogue —
        // `retab`, or `retabsppc` on an arm64e.x1 build — and it must be the
        // function's own: a `retabsppc` names the prologue that signed.
        var returnOffset: Int?
        var cursor = offset + 4
        while cursor + 4 <= textEnd {
            defer { cursor += 4 }
            if let insn = disasm.disassembleOne(in: data, at: cursor), isAuthenticatedReturn(insn) {
                guard returnCloses(insn, at: cursor, prologue: prologue) else {
                    throw PatcherError.patchSiteNotFound(
                        "\(component): the first return after the throw at 0x\(hex(UInt64(offset))), "
                            + "`\(insn.mnemonic)` at 0x\(hex(UInt64(cursor))), does not close the function "
                            + "at 0x\(hex(UInt64(prologue)))",
                    )
                }
                returnOffset = cursor
                break
            }
        }
        guard let ret = returnOffset else {
            throw PatcherError.patchSiteNotFound(
                "\(component): no `retab` or `retabsppc` after the throw at 0x\(hex(UInt64(offset)))",
            )
        }
        return try epilogueEntry(in: data, disasm: disasm, retab: ret)
    }

    /// The entry of the epilogue a known authenticated return (`retab` or
    /// `retabsppc`) closes: the stack-guard load when the function is built
    /// with the protector, or the first frame restore when it is not. Shared
    /// by both VirtualAudio patches — the walker patch reaches the return
    /// forwards from its throw, the mute-set patch enumerates the wrapper's
    /// own return because its throw sits below the epilogue.
    static func epilogueEntry(
        in data: Data,
        disasm: ARM64Disassembler,
        retab: Int,
    ) throws -> Int {
        func instruction(_ at: Int) -> ARM64Instruction? {
            guard at >= 0 else { return nil }
            return disasm.disassembleOne(in: data, at: at)
        }

        // `add sp, sp, #imm` directly before the return, then the pops.
        guard let addSP = instruction(retab - 4), addSP.mnemonic == "add",
              let addOps = addSP.detail?.operands, addOps.count >= 2,
              addOps[0].type == .register, addOps[1].type == .register,
              addOps[0].reg == addOps[1].reg
        else {
            throw PatcherError.invalidFormat(
                "\(component): no `add sp` directly before the epilogue's return",
            )
        }

        // The pops, innermost first, until the frame pair. `index` lands one
        // instruction below the first pop.
        var index = retab - 8
        var sawFramePair = false
        while let insn = instruction(index), insn.mnemonic == "ldp",
              let operands = insn.detail?.operands, operands.count >= 2
        {
            if operands[0].reg == ARM64Register.x(29), operands[1].reg == ARM64Register.x(30) {
                sawFramePair = true
            }
            index -= 4
        }
        guard sawFramePair else {
            throw PatcherError.invalidFormat(
                "\(component): the epilogue's pops do not restore the frame pair",
            )
        }
        let firstPop = index + 4

        // A stack-guarded function loads the canary below the first pop:
        // `ldur` off the frame pointer, its page, two loads, a compare and
        // the fail branch. When that chain is there the entry is the load,
        // so the restored canary is still checked; when it is not (a build
        // without the protector) the entry is the first pop itself.
        if let branch = instruction(index), branch.mnemonic == "b.ne",
           let cmp = instruction(index - 4), cmp.mnemonic == "cmp",
           let load2 = instruction(index - 8), load2.mnemonic == "ldr",
           let load1 = instruction(index - 12), load1.mnemonic == "ldr",
           let page = instruction(index - 16), page.mnemonic == "adrp",
           let canary = instruction(index - 20), canary.mnemonic == "ldur",
           let canaryOps = canary.detail?.operands, canaryOps.count >= 2,
           canaryOps[1].type == .memory,
           canaryOps[1].mem.base == ARM64Register.x(29)
        {
            return index - 20
        }
        return firstPop
    }

    // MARK: - Bytes

    /// The first byte of the null-terminated string containing `offset`.
    private static func cStringStart(in data: Data, containing offset: Int, notBefore start: Int) -> Int {
        var begin = offset
        while begin > start, data[begin - 1] != 0 {
            begin -= 1
        }
        return begin
    }

    /// One past the NUL ending the string at `offset`.
    private static func cStringEnd(in data: Data, from offset: Int, notAfter end: Int) -> Int {
        var terminator = offset
        while terminator < end, data[terminator] != 0 {
            terminator += 1
        }
        return min(terminator + 1, end)
    }

    private static func range(of needle: [UInt8], in data: Data, start: Int, end: Int) -> Int? {
        guard end - start >= needle.count else { return nil }
        for offset in start ... (end - needle.count) {
            var matched = true
            for (index, byte) in needle.enumerated() where data[offset + index] != byte {
                matched = false
                break
            }
            if matched {
                return offset
            }
        }
        return nil
    }
}

private func hex(_ value: UInt64) -> String {
    String(format: "%llx", value)
}