Skip to content

Run a virtual iPhone on an Apple Silicon Mac.

Swift
45.5 KB
Raw Blame
// DyldSharedCacheMaxSlidePatcherTests.swift — Parity cross-checks for `DyldSharedCacheMaxSlidePatcher`.
//
// There is no `codesign -v` for a dyld shared cache chunk and no second
// implementation of this patch anywhere. The only independent reference was
// `scripts/patchers/cfw_patch_dsc_maxslide.py`, driven through the Command the
// install scripts use: `cfw.py patch-dsc-maxslide <dir> [--dry-run] [--force]`.
// That Python has been removed, so what it produced is frozen in
// `FrozenReference` below — for the real cache, and for each of the five
// synthetic gate cases, the digest of the input it saw and the digest of the
// file it left behind. Every claim here is "the Swift, given the bytes the
// reference was given, produces the bytes the reference produced".
//
// The tests need the real cache. Point `VPHONE_DSC_PRISTINE` at a directory of
// `dyld_shared_cache_arm64e*` chunks, or leave the default
// `ipsws/ref_extract/dsc_pristine` in place.
//
// Without it they FAIL, following `DyldSharedCacheFoundationTests`: a `guard … else
// { return }` is reported by Swift Testing as a pass, so a green run on a
// machine with no fixture would be indistinguishable from a green run that
// proved something. A machine that genuinely cannot carry the 5.3 GB cache sets
// `VPHONE_DSC_FIXTURE_OPTIONAL=1`, which turns the failure into a visible skip.
//
// Nothing here writes to the pristine directory, and nothing here writes
// anywhere under `ipsws/ref_extract/` at all: clones land in
// `ipsws/scratch_dscmaxslide/`, on the same filesystem, so `cp -c` is a
// `clonefile` rather than 10 GB of copying.

import CryptoKit
@testable import FirmwarePatcher
import Foundation
import Testing
import VPhonePatchKit

// MARK: - The frozen reference

/// What the reference Python produced, recorded from live runs at commit
/// 78cbeea:
///
///     .venv/bin/python3 scripts/patchers/cfw.py \
///         patch-dsc-maxslide <input> [--dry-run] [--force]
///
/// The real-cache input was a clone of `ipsws/ref_extract/dsc_pristine`. The
/// synthetic inputs were rebuilt byte for byte from
/// `DyldSharedCacheMaxSlideGateTests.writeCache`, which is why each case carries the digest
/// of its input as well as of its output: a test that fed the Swift something
/// else would fail on the input digest rather than quietly compare nothing.
private enum FrozenReference {
    // MARK: The real 24A435 arm64e cache

    /// Python: `dyld_shared_cache_arm64e: start=0x180000000 size=0x17D504000
    /// maxSlide=0x20000000`.
    static let realStart: UInt64 = 0x1_8000_0000
    static let realSize: UInt64 = 0x1_7D50_4000
    static let realMaxSlide: UInt64 = 0x2000_0000

    /// Python: `overflow: span+maxSlide 0x19D504000 > region 0x180000000; set
    /// maxSlide 0x20000000 -> 0x0`, then `DSC maxSlide patch complete`.
    ///
    /// `cmp -s` against the pristine tree afterwards: exactly one file moved,
    /// the main chunk, to this digest (`shasum -a 256 <output>/…arm64e`). The
    /// other 79 files were untouched. The reference did not re-attest page 0;
    /// the Swift now does, so its output matches this digest once page 0's
    /// slot is put back to the pristine one — see `Digest.sha256(of:splicing:)`.
    static let realChangedChunks: [String: String] = [
        "dyld_shared_cache_arm64e":
            "3d7197cc0714e95c0e49434ab8bbb6311952a96d5b0425b10f87d2cc060c0110",
    ]

    // Re-running the Python over its own output printed `fits: span+maxSlide
    // 0x17D504000 <= region 0x180000000; no change` — the *fits* gate, not the
    // already-zero one — and left the digest above standing. A third run with
    // `--force` skipped that gate and printed `maxSlide already 0; no change`,
    // also writing nothing. A `--dry-run` on a fresh clone printed `would set
    // maxSlide 0x20000000 -> 0x0` and changed no byte.

    // MARK: The synthetic gate cases

    /// One synthetic case: the digest of the cache handed to the patcher, and
    /// the digest of what it held afterwards.
    struct GateCase {
        let inputSHA256: String
        let outputSHA256: String
        /// The branch word the Python printed: `overflow`, `fits`, `forced` or
        /// `maxSlide already 0`.
        let branch: String
    }

    /// `writeCache(regionSize: 0x17C830000, maxSlide: 0x20000000)`, no flags.
    /// Python: `overflow: span+maxSlide 0x19C830000 > region 0x180000000; set
    /// maxSlide 0x20000000 -> 0x0`.
    static let overflow = GateCase(
        inputSHA256: "0eeb86dc953aa43a29df533a0c151cb1d8ce7f322f8fa77232d5c97733984ab3",
        outputSHA256: "93e9ee632ab259a245f37e224e52e7f5671c8b323d04ba541483335c0d94bc6c",
        branch: "overflow",
    )

    /// `writeCache(regionSize: 0x140904000, maxSlide: 0x20000000)`, no flags.
    /// Python: `fits: span+maxSlide 0x160904000 <= region 0x180000000; no
    /// change` — input and output digests are the same file.
    static let fits = GateCase(
        inputSHA256: "88c50a6f8304c87bca21e6c01da193d8022673c12d03d4d0dfd52340b3fca718",
        outputSHA256: "88c50a6f8304c87bca21e6c01da193d8022673c12d03d4d0dfd52340b3fca718",
        branch: "fits",
    )

    /// The same input as `fits`, with `--force`. Python: `forced: span+maxSlide
    /// 0x160904000 fits region 0x180000000 but --force set; set maxSlide
    /// 0x20000000 -> 0x0`.
    static let forced = GateCase(
        inputSHA256: "88c50a6f8304c87bca21e6c01da193d8022673c12d03d4d0dfd52340b3fca718",
        outputSHA256: "73e12cacf1350c07ad38991f4e845e51f64199815061e0ea1889d19f53f4beda",
        branch: "forced",
    )

    /// `writeCache(regionSize: 0x140904000, maxSlide: 0)` with `--force`.
    /// Python: `maxSlide already 0; no change`.
    static let forcedZero = GateCase(
        inputSHA256: "73e12cacf1350c07ad38991f4e845e51f64199815061e0ea1889d19f53f4beda",
        outputSHA256: "73e12cacf1350c07ad38991f4e845e51f64199815061e0ea1889d19f53f4beda",
        branch: "maxSlide already 0",
    )

    /// `writeCache(regionSize: 0x190000000, maxSlide: 0)`, no flags — a span
    /// that overruns the region with no slide left to give back. Python:
    /// `maxSlide already 0; no change`.
    static let overflowWithZeroSlide = GateCase(
        inputSHA256: "f2543eb53f0f69a25c72045311292c9c428798a53683aeebd5b051509126d4b9",
        outputSHA256: "f2543eb53f0f69a25c72045311292c9c428798a53683aeebd5b051509126d4b9",
        branch: "maxSlide already 0",
    )

    // The Python's own self-test fixture — a bare 0x100-byte header with no
    // mapping table — is the one input where the two implementations
    // deliberately disagree, so it has no `GateCase` above. The reference
    // patched it (`overflow: … set maxSlide 0x20000000 -> 0x0`, the field
    // reading back as 0 afterwards); the Swift refuses it, because every write
    // here goes through `DyldSharedCacheChunkSet`, which has nothing to address such a
    // file with. See `noMappingTableIsRefused`.
}

// MARK: - Fixture discovery

private enum MaxSlideFixture {
    static let repoRoot = URL(fileURLWithPath: #filePath)
        .deletingLastPathComponent()
        .deletingLastPathComponent()
        .deletingLastPathComponent()
        .deletingLastPathComponent()
        .deletingLastPathComponent()

    static let mainChunkName = "dyld_shared_cache_arm64e"

    /// The read-only reference cache.
    static var pristine: URL? {
        let url = ProcessInfo.processInfo.environment["VPHONE_DSC_PRISTINE"]
            .map { URL(fileURLWithPath: $0) }
            ?? repoRoot.appendingPathComponent("ipsws/ref_extract/dsc_pristine")
        let main = url.appendingPathComponent(mainChunkName)
        return FileManager.default.fileExists(atPath: main.path) ? url : nil
    }

    /// Opt-out for a machine that cannot carry the fixture.
    static var isOptional: Bool {
        ProcessInfo.processInfo.environment["VPHONE_DSC_FIXTURE_OPTIONAL"] == "1"
    }

    /// The suites run unless the cache is absent *and* the caller opted out.
    static var runs: Bool {
        pristine != nil || !isOptional
    }

    static let missing: Comment = """
    the real 24A435 arm64e shared cache is required — put it at \
    ipsws/ref_extract/dsc_pristine, point VPHONE_DSC_PRISTINE at it, or set \
    VPHONE_DSC_FIXTURE_OPTIONAL=1 to skip these tests instead of failing
    """

    static let skipReason: Comment =
        "VPHONE_DSC_FIXTURE_OPTIONAL=1 and no dyld_shared_cache_arm64e fixture present"

    /// Where clones are made. Same filesystem as the repo, and deliberately
    /// *not* under `ipsws/ref_extract/`, which is the pristine reference the
    /// whole suite compares against.
    static var scratchRoot: URL {
        repoRoot.appendingPathComponent("ipsws/scratch_dscmaxslide")
    }

    /// Clone the whole pristine cache into a fresh directory the caller may
    /// write to. `cp -c` is `clonefile(2)`: instant, and near-zero disk until
    /// something is written.
    static func cloneCache(named name: String) throws -> URL {
        guard let pristine else { throw CocoaError(.fileNoSuchFile) }
        let destination = scratchRoot.appendingPathComponent(name)
        try? FileManager.default.removeItem(at: destination)
        try FileManager.default.createDirectory(
            at: destination,
            withIntermediateDirectories: true,
        )
        let sources = try FileManager.default
            .contentsOfDirectory(atPath: pristine.path)
            .sorted()
            .map { pristine.appendingPathComponent($0).path }

        var result = try Subprocess.run(
            executable: URL(fileURLWithPath: "/bin/cp"),
            arguments: ["-c", "-R"] + sources + [destination.path],
        )
        if result.status != 0 {
            // A fixture pointed at another volume cannot be cloned. Copying is
            // slow but correct, and a refusal here would look like a patch bug.
            result = try Subprocess.run(
                executable: URL(fileURLWithPath: "/bin/cp"),
                arguments: ["-R"] + sources + [destination.path],
            )
        }
        guard result.status == 0 else { throw CocoaError(.fileWriteUnknown) }
        return destination
    }

    /// Clone only the chunk this patcher touches — enough for a
    /// `DyldSharedCacheChunkSet`, and cheap enough for the gate-logic tests to make many.
    static func cloneMainChunk(named name: String) throws -> URL {
        guard let pristine else { throw CocoaError(.fileNoSuchFile) }
        let destination = scratchRoot.appendingPathComponent(name)
        try? FileManager.default.removeItem(at: destination)
        try FileManager.default.createDirectory(
            at: destination,
            withIntermediateDirectories: true,
        )
        try FileManager.default.copyItem(
            at: pristine.appendingPathComponent(mainChunkName),
            to: destination.appendingPathComponent(mainChunkName),
        )
        return destination
    }

    /// Discard clones, and the scratch root with them once the last one is
    /// gone, so a test run leaves the working tree as it found it.
    static func discard(_ clones: URL...) {
        for clone in clones {
            try? FileManager.default.removeItem(at: clone)
        }
        let remaining = (try? FileManager.default
            .contentsOfDirectory(atPath: scratchRoot.path)) ?? []
        if remaining.isEmpty {
            try? FileManager.default.removeItem(at: scratchRoot)
        }
    }
}

// MARK: - Subprocess helper

private enum Subprocess {
    struct Result {
        let status: Int32
        let stdout: String
        let stderr: String
    }

    @discardableResult
    static func run(executable: URL, arguments: [String]) throws -> Result {
        let process = Process()
        process.executableURL = executable
        process.arguments = arguments
        let out = Pipe()
        let err = Pipe()
        process.standardOutput = out
        process.standardError = err
        try process.run()
        // Drain before waiting, or a full pipe buffer deadlocks the child.
        let outData = out.fileHandleForReading.readDataToEndOfFile()
        let errData = err.fileHandleForReading.readDataToEndOfFile()
        process.waitUntilExit()
        return Result(
            status: process.terminationStatus,
            stdout: String(decoding: outData, as: UTF8.self),
            stderr: String(decoding: errData, as: UTF8.self),
        )
    }
}

// MARK: - Digests

/// SHA-256 of a file, streamed so a 131 MB chunk never lands in memory whole.
/// The hex spelling matches `shasum -a 256`, which produced the frozen digests.
private enum Digest {
    static func sha256(of url: URL) throws -> String {
        let handle = try FileHandle(forReadingFrom: url)
        defer { try? handle.close() }
        var hasher = SHA256()
        while let block = try handle.read(upToCount: 4 << 20), !block.isEmpty {
            hasher.update(data: block)
        }
        return hasher.finalize().map { String(format: "%02x", $0) }.joined()
    }

    /// The digest `url` would have with `bytes` written at `offset` — how a
    /// re-attested chunk is compared with the reference, which left the slot
    /// alone.
    static func sha256(of url: URL, splicing bytes: Data, at offset: Int) throws -> String {
        var data = try Data(contentsOf: url)
        data.replaceSubrange(offset ..< offset + bytes.count, with: bytes)
        return SHA256.hash(data: data).map { String(format: "%02x", $0) }.joined()
    }

    /// Page 0's stored slot in `chunk`, and where it lives.
    static func pageZeroSlot(of chunk: URL) throws -> (offset: Int, bytes: Data) {
        let directory = try #require(try DyldSharedCacheCodeSignature.readCodeDirectory(ofChunk: chunk))
        let offset = directory.slotOffset(forPage: 0)
        return (offset, try Bytes.read(chunk, offset: UInt64(offset), length: directory.hashSize))
    }

    /// The reference's digest, given Swift output whose only extra change is
    /// page 0's slot.
    static func referenceDigest(ofSwiftOutput chunk: URL, pristine pristineChunk: URL) throws -> String {
        let pristineSlot = try pageZeroSlot(of: pristineChunk)
        return try sha256(of: chunk, splicing: pristineSlot.bytes, at: pristineSlot.offset)
    }
}

// MARK: - Byte comparison

private enum Bytes {
    /// `cmp -s`, which is a C memcmp over two files and does not need either of
    /// them in this process's memory. Returns true when the two are identical.
    static func identical(_ lhs: URL, _ rhs: URL) throws -> Bool {
        try Subprocess.run(
            executable: URL(fileURLWithPath: "/usr/bin/cmp"),
            arguments: ["-s", lhs.path, rhs.path],
        ).status == 0
    }

    /// Every file in `lhs` compared with its namesake in `rhs`.
    ///
    /// - Returns: how many files matched, and the names that did not.
    static func compareTrees(_ lhs: URL, _ rhs: URL) throws -> (matched: Int, differing: [String]) {
        let leftNames = try FileManager.default.contentsOfDirectory(atPath: lhs.path).sorted()
        let rightNames = try FileManager.default.contentsOfDirectory(atPath: rhs.path).sorted()
        #expect(leftNames == rightNames, "the two clones do not even hold the same files")

        var matched = 0
        var differing: [String] = []
        for name in leftNames {
            if try identical(
                lhs.appendingPathComponent(name),
                rhs.appendingPathComponent(name),
            ) {
                matched += 1
            } else {
                differing.append(name)
            }
        }
        return (matched, differing)
    }

    static func read(_ url: URL, offset: UInt64, length: Int) throws -> Data {
        try DyldSharedCacheChunkSet.read(url: url, offset: offset, length: length)
    }

    /// The `maxSlide` field of a chunk on disk.
    static func maxSlide(of chunk: URL) throws -> UInt64 {
        try read(chunk, offset: UInt64(DyldSharedCacheMaxSlidePatcher.HeaderField.maxSlide), length: 8)
            .loadLE(UInt64.self, at: 0)
    }
}

// MARK: - The real cache

@Suite(.serialized, .enabled(if: MaxSlideFixture.runs, MaxSlideFixture.skipReason))
struct DyldSharedCacheMaxSlideRealCacheTests {
    /// The gate this cache trips, stated once: 24A435's arm64e cache records a
    /// 0x17D504000 span and a 0x20000000 slide, which together overrun the
    /// kernel's 0x180000000 region by 0x1D504000.
    @Test
    func `The pristine cache is one that overflows the kernel's shared region`() throws {
        let pristine = try #require(MaxSlideFixture.pristine, MaxSlideFixture.missing)

        let chunks = try DyldSharedCacheChunkSet(directory: pristine)
        let headerVMA = try DyldSharedCacheMaxSlidePatcher.headerVMA(of: chunks)
        let header = try DyldSharedCacheMaxSlidePatcher.readHeader(
            from: chunks,
            at: headerVMA,
            chunkName: MaxSlideFixture.mainChunkName,
        )

        #expect(header.sharedRegionStart == chunks.addressRange.lowerBound)
        #expect(header.maxSlide != 0, "the fixture is already patched; re-extract it")
        #expect(
            header.sharedRegionSize + header.maxSlide > DyldSharedCacheMaxSlidePatcher.kernelSharedRegionSize,
            "this fixture does not exercise the patch: it fits the region as it stands",
        )
        // The three numbers the reference read out of this same header.
        #expect(header.sharedRegionStart == FrozenReference.realStart)
        #expect(header.sharedRegionSize == FrozenReference.realSize)
        #expect(header.maxSlide == FrozenReference.realMaxSlide)
        print(
            "[pristine] start=0x\(String(header.sharedRegionStart, radix: 16, uppercase: true)) "
                + "size=0x\(String(header.sharedRegionSize, radix: 16, uppercase: true)) "
                + "maxSlide=0x\(String(header.maxSlide, radix: 16, uppercase: true))",
        )
    }

    /// The gate from the task: run the patcher on a clone of the real cache and
    /// require the result to be the bytes the reference left behind, over every
    /// one of the 79 chunks and the symbol side file — not just over the eight
    /// bytes the patch is about.
    @Test
    func `Swift patches the real cache into the reference's bytes`() throws {
        let pristine = try #require(MaxSlideFixture.pristine, MaxSlideFixture.missing)

        let swiftSide = try MaxSlideFixture.cloneCache(named: "parity_swift")
        defer { MaxSlideFixture.discard(swiftSide) }

        let mine = try DyldSharedCacheMaxSlidePatcher.patch(chunksDirectory: swiftSide)
        #expect(mine.siteCount == 1, "the Swift did not patch the real cache")
        #expect(mine.didWrite)
        #expect(mine.outcome == .overflow(
            combined: mine.sharedRegionSize + mine.maxSlide,
            region: DyldSharedCacheMaxSlidePatcher.kernelSharedRegionSize,
        ))
        #expect(mine.writtenSpan?.length == 8, "one site, one u64")

        // Exactly the file the reference moved, with exactly its bytes.
        let (unchanged, changed) = try Bytes.compareTrees(pristine, swiftSide)
        #expect(changed == FrozenReference.realChangedChunks.keys.sorted())
        #expect(unchanged >= 79, "only \(unchanged) files were left alone")
        for name in changed {
            let digest = try Digest.referenceDigest(
                ofSwiftOutput: swiftSide.appendingPathComponent(name),
                pristine: pristine.appendingPathComponent(name),
            )
            let frozen = FrozenReference.realChangedChunks[name] ?? "(not a file the Python moved)"
            #expect(digest == frozen, "\(name): Swift \(digest), reference \(frozen)")
        }

        // …and the change is the eight bytes of the field and nothing else.
        let pristineMain = pristine.appendingPathComponent(MaxSlideFixture.mainChunkName)
        let head = DyldSharedCacheMaxSlidePatcher.HeaderField.maxSlide
        let tailOffset = UInt64(head + 8)
        let tailLength = 0x100 - head - 8
        let main = swiftSide.appendingPathComponent(MaxSlideFixture.mainChunkName)
        #expect(try Bytes.maxSlide(of: main) == 0)
        #expect(try Bytes.read(main, offset: 0, length: head)
            == Bytes.read(pristineMain, offset: 0, length: head))
        #expect(try Bytes.read(main, offset: tailOffset, length: tailLength)
            == Bytes.read(pristineMain, offset: tailOffset, length: tailLength))
    }

    /// Page 0 carries the header, and `dsc_extractor` checks its slot like any
    /// other: left stale, `xcodebuild -prepareDeviceSupport` extracts nothing
    /// from the cache. The patch re-hashes that one slot and no other.
    @Test
    func `The patch re-attests the header page and no other slot`() throws {
        let pristine = try #require(MaxSlideFixture.pristine, MaxSlideFixture.missing)

        let clone = try MaxSlideFixture.cloneMainChunk(named: "reattest")
        defer { MaxSlideFixture.discard(clone) }
        let main = clone.appendingPathComponent(MaxSlideFixture.mainChunkName)
        let pristineMain = pristine.appendingPathComponent(MaxSlideFixture.mainChunkName)

        let directory = try #require(
            try DyldSharedCacheCodeSignature.readCodeDirectory(ofChunk: main),
            "the main chunk should carry a code directory",
        )
        let before = try DyldSharedCacheCodeSignature.pageHashes(
            chunkURL: main,
            pageIndex: 0,
            directory: directory,
        )
        #expect(before.computed == before.stored, "page 0 was not attested before the patch")

        let result = try DyldSharedCacheMaxSlidePatcher.patch(chunksDirectory: clone)
        #expect(result.siteCount == 1)
        #expect(result.reattestation?.updated.map(\.pageIndex) == [0])
        #expect(result.reattestation?.isFullyAttested == true)

        let after = try DyldSharedCacheCodeSignature.pageHashes(
            chunkURL: main,
            pageIndex: 0,
            directory: directory,
        )
        #expect(after.computed == after.stored, "page 0's slot does not match the patched header")
        #expect(after.stored != before.stored)

        // Outside slot 0 the code directory is byte-identical to pristine.
        let slot = directory.slotOffset(forPage: 0) - directory.blobOffset
        let mineBlob = try Bytes.read(
            main,
            offset: UInt64(directory.blobOffset),
            length: directory.blobLength,
        )
        var pristineBlob = try Bytes.read(
            pristineMain,
            offset: UInt64(directory.blobOffset),
            length: directory.blobLength,
        )
        pristineBlob.replaceSubrange(slot ..< slot + directory.hashSize, with: after.stored)
        #expect(mineBlob == pristineBlob, "the patch rewrote a code slot other than page 0's")
    }

    /// A guest clamped before the patch re-attested carries `maxSlide` 0 and
    /// page 0's pristine slot. A re-run must repair the slot without writing
    /// the field — the path `cfw update-environment` takes on such a guest.
    @Test
    func `A re-run repairs a header clamped without re-attestation`() throws {
        let pristine = try #require(MaxSlideFixture.pristine, MaxSlideFixture.missing)

        let clone = try MaxSlideFixture.cloneMainChunk(named: "repair")
        defer { MaxSlideFixture.discard(clone) }
        let main = clone.appendingPathComponent(MaxSlideFixture.mainChunkName)

        try DyldSharedCacheMaxSlidePatcher.patch(chunksDirectory: clone)
        let pristineSlot = try Digest.pageZeroSlot(
            of: pristine.appendingPathComponent(MaxSlideFixture.mainChunkName),
        )
        let handle = try FileHandle(forUpdating: main)
        try handle.seek(toOffset: UInt64(pristineSlot.offset))
        try handle.write(contentsOf: pristineSlot.bytes)
        try handle.close()

        let repaired = try DyldSharedCacheMaxSlidePatcher.patch(chunksDirectory: clone)
        #expect(repaired.siteCount == 0)
        #expect(!repaired.didWrite)
        #expect(repaired.reattestation?.updated.map(\.pageIndex) == [0])

        let directory = try #require(try DyldSharedCacheCodeSignature.readCodeDirectory(ofChunk: main))
        let hashes = try DyldSharedCacheCodeSignature.pageHashes(
            chunkURL: main,
            pageIndex: 0,
            directory: directory,
        )
        #expect(hashes.computed == hashes.stored)
    }

    /// The reference's `--dry-run` printed `would set maxSlide 0x20000000 ->
    /// 0x0` — one site reported, no byte written. So must this one.
    @Test
    func `A dry run reports the reference's site, and writes nothing`() throws {
        let pristine = try #require(MaxSlideFixture.pristine, MaxSlideFixture.missing)

        let swiftSide = try MaxSlideFixture.cloneMainChunk(named: "dryrun_swift")
        defer { MaxSlideFixture.discard(swiftSide) }

        let mine = try DyldSharedCacheMaxSlidePatcher.patch(chunksDirectory: swiftSide, dryRun: true)
        #expect(mine.siteCount == 1, "a dry run still reports the site, as the reference did")
        #expect(!mine.didWrite)
        #expect(mine.record?.patchID == DyldSharedCacheMaxSlidePatcher.patchID)
        #expect(mine.record?.patchedBytes == Data(count: 8))
        #expect(mine.record?.originalBytes.loadLE(UInt64.self, at: 0) == mine.maxSlide)
        #expect(mine.maxSlide == FrozenReference.realMaxSlide)

        let untouched = try Bytes.identical(
            swiftSide.appendingPathComponent(MaxSlideFixture.mainChunkName),
            pristine.appendingPathComponent(MaxSlideFixture.mainChunkName),
        )
        #expect(untouched, "a dry run wrote to the chunk")
    }

    /// `8eb6c8b`'s lesson again: a patcher has to recognise its own output. A
    /// second pass over a clamped cache is a no-op, not an error and not a
    /// second write.
    @Test
    func `A second pass over an already-clamped cache is a no-op`() throws {
        let pristine = try #require(MaxSlideFixture.pristine, MaxSlideFixture.missing)

        let swiftSide = try MaxSlideFixture.cloneMainChunk(named: "idem_swift")
        defer { MaxSlideFixture.discard(swiftSide) }

        let first = try DyldSharedCacheMaxSlidePatcher.patch(chunksDirectory: swiftSide)
        let afterFirst = try Digest.sha256(
            of: swiftSide.appendingPathComponent(MaxSlideFixture.mainChunkName),
        )

        let mineAgain = try DyldSharedCacheMaxSlidePatcher.patch(chunksDirectory: swiftSide)
        #expect(mineAgain.siteCount == 0)
        #expect(!mineAgain.didWrite)
        #expect(mineAgain.reattestation?.updated.isEmpty == true, "page 0 was attested by the first pass")
        // Which gate stops the second pass is worth being precise about. Once
        // the slide is gone this cache's span fits the region on its own
        // (0x17D504000 <= 0x180000000) — that is the whole point of the patch —
        // so the *fits* gate is what returns, and the already-zero gate behind
        // it is never reached. The reference said the same thing in words: its
        // second run printed "fits: … no change", not "maxSlide already 0".
        #expect(mineAgain.outcome == .fits(
            combined: first.sharedRegionSize,
            region: DyldSharedCacheMaxSlidePatcher.kernelSharedRegionSize,
        ))

        // `--force` skips the fits gate, so it is the one path that does reach
        // the already-zero check — and it still writes nothing. The reference's
        // third run printed "maxSlide already 0; no change" and left its file
        // alone, which is what the unchanged digest below has to show.
        let mineForced = try DyldSharedCacheMaxSlidePatcher.patch(chunksDirectory: swiftSide, force: true)
        #expect(mineForced.siteCount == 0)
        #expect(mineForced.outcome == .alreadyZero)

        let afterThird = try Digest.sha256(
            of: swiftSide.appendingPathComponent(MaxSlideFixture.mainChunkName),
        )
        #expect(afterThird == afterFirst, "a no-op pass rewrote the chunk")
        let referenceDigest = try Digest.referenceDigest(
            ofSwiftOutput: swiftSide.appendingPathComponent(MaxSlideFixture.mainChunkName),
            pristine: pristine.appendingPathComponent(MaxSlideFixture.mainChunkName),
        )
        #expect(referenceDigest == FrozenReference.realChangedChunks[MaxSlideFixture.mainChunkName])
    }
}

// MARK: - The gate, on synthetic caches

/// The four branches `cfw_patch_dsc_maxslide._self_test` covered, replayed on
/// the same synthetic caches the reference was given — see `FrozenReference`
/// for the digests of each one, before and after.
///
/// Synthetic rather than real because the real cache can only exercise one of
/// the four: it overflows. A cache that *fits* — an 18.x or 26.x base, the case
/// the self-gate exists to protect — cannot be demonstrated with the fixture on
/// hand, so it is built.
@Suite(.serialized, .enabled(if: MaxSlideFixture.runs, MaxSlideFixture.skipReason))
struct DyldSharedCacheMaxSlideGateTests {
    /// A minimal but *real* cache: header plus a one-entry mapping table that
    /// covers it. The Python's own self-test fixture has no mapping table at
    /// all, which the Swift refuses — see `noMappingTableIsRefused`.
    ///
    /// - Parameters:
    ///   - regionSize: what the header records as `sharedRegionSize`.
    ///   - maxSlide: what the header records as `maxSlide`.
    static func writeCache(
        into directory: URL,
        regionSize: UInt64,
        maxSlide: UInt64,
        mappingOffset: Int = 0x238,
        magic: String = "dyld_v1  arm64e",
    ) throws {
        try FileManager.default.createDirectory(at: directory, withIntermediateDirectories: true)
        var bytes = [UInt8](repeating: 0, count: 0x4000)

        func put(_ value: UInt64, at offset: Int) {
            withUnsafeBytes(of: value.littleEndian) { source in
                for (index, byte) in source.enumerated() {
                    bytes[offset + index] = byte
                }
            }
        }
        func put32(_ value: UInt32, at offset: Int) {
            withUnsafeBytes(of: value.littleEndian) { source in
                for (index, byte) in source.enumerated() {
                    bytes[offset + index] = byte
                }
            }
        }

        for (index, byte) in Array(magic.utf8).prefix(16).enumerated() {
            bytes[index] = byte
        }
        put32(UInt32(mappingOffset), at: 0x10)
        put32(1, at: 0x14) // mappingCount

        // dyld_cache_mapping_info: address, size, fileOffset, maxProt, initProt.
        put(Self.mappingAddress, at: mappingOffset)
        put(0x4000, at: mappingOffset + 8)
        put(0, at: mappingOffset + 16)
        put32(5, at: mappingOffset + 24)
        put32(5, at: mappingOffset + 28)

        put(Self.mappingAddress, at: 0xE0) // sharedRegionStart
        put(regionSize, at: 0xE8) // sharedRegionSize
        put(maxSlide, at: 0xF0) // maxSlide

        try Data(bytes).write(
            to: directory.appendingPathComponent(MaxSlideFixture.mainChunkName),
        )
    }

    /// SHARED_REGION_BASE_ARM64, which is also where the real cache starts.
    static let mappingAddress: UInt64 = 0x1_8000_0000

    /// Build the synthetic cache the reference was given, hand it to the Swift,
    /// and require the file to come out with the reference's digest.
    ///
    /// The input digest is checked first. Without it a change to `writeCache`
    /// would silently move the comparison onto some other cache, and the output
    /// digest would then be measuring the wrong thing.
    private func compare(
        named name: String,
        regionSize: UInt64,
        maxSlide: UInt64,
        force: Bool = false,
        reference: FrozenReference.GateCase,
        expectedSites: Int,
        expectedOutcome: DyldSharedCacheMaxSlidePatcher.Outcome,
        expectedMaxSlideAfter: UInt64,
    ) throws {
        let swiftSide = MaxSlideFixture.scratchRoot.appendingPathComponent("\(name)_swift")
        defer { MaxSlideFixture.discard(swiftSide) }
        try Self.writeCache(into: swiftSide, regionSize: regionSize, maxSlide: maxSlide)

        let swiftMain = swiftSide.appendingPathComponent(MaxSlideFixture.mainChunkName)
        let inputDigest = try Digest.sha256(of: swiftMain)
        #expect(
            inputDigest == reference.inputSHA256,
            "\(name): this is not the cache the reference saw — \(inputDigest)",
        )

        let mine = try DyldSharedCacheMaxSlidePatcher.patch(chunksDirectory: swiftSide, force: force)
        #expect(mine.siteCount == expectedSites)
        #expect(mine.outcome == expectedOutcome)

        let outputDigest = try Digest.sha256(of: swiftMain)
        #expect(
            outputDigest == reference.outputSHA256,
            "\(name): Swift \(outputDigest), reference \(reference.outputSHA256)",
        )
        #expect(try Bytes.maxSlide(of: swiftMain) == expectedMaxSlideAfter)
        print("[gate \(name)] \(expectedSites) site(s) on the reference's \(reference.branch) "
            + "branch; maxSlide now 0x\(String(expectedMaxSlideAfter, radix: 16, uppercase: true))")
    }

    @Test
    func `An overflowing cache is clamped, as the reference clamped it`() throws {
        // iOS 27.0-like: 0x17C830000 + 0x20000000 > 0x180000000.
        try compare(
            named: "overflow",
            regionSize: 0x1_7C83_0000,
            maxSlide: 0x2000_0000,
            reference: FrozenReference.overflow,
            expectedSites: 1,
            expectedOutcome: .overflow(
                combined: 0x1_9C83_0000,
                region: DyldSharedCacheMaxSlidePatcher.kernelSharedRegionSize,
            ),
            expectedMaxSlideAfter: 0,
        )
    }

    @Test
    func `A cache that fits is left alone, as the reference left it`() throws {
        // 26.4-like: 0x140904000 + 0x20000000 <= 0x180000000.
        try compare(
            named: "fits",
            regionSize: 0x1_4090_4000,
            maxSlide: 0x2000_0000,
            reference: FrozenReference.fits,
            expectedSites: 0,
            expectedOutcome: .fits(
                combined: 0x1_6090_4000,
                region: DyldSharedCacheMaxSlidePatcher.kernelSharedRegionSize,
            ),
            expectedMaxSlideAfter: 0x2000_0000,
        )
    }

    @Test
    func `--force clamps a cache that fits, to the reference's bytes`() throws {
        try compare(
            named: "forced",
            regionSize: 0x1_4090_4000,
            maxSlide: 0x2000_0000,
            force: true,
            reference: FrozenReference.forced,
            expectedSites: 1,
            expectedOutcome: .forced(
                combined: 0x1_6090_4000,
                region: DyldSharedCacheMaxSlidePatcher.kernelSharedRegionSize,
            ),
            expectedMaxSlideAfter: 0,
        )
    }

    @Test
    func `--force over an already-zero cache is a no-op, as it was for the reference`() throws {
        try compare(
            named: "forced_zero",
            regionSize: 0x1_4090_4000,
            maxSlide: 0,
            force: true,
            reference: FrozenReference.forcedZero,
            expectedSites: 0,
            expectedOutcome: .alreadyZero,
            expectedMaxSlideAfter: 0,
        )
    }

    /// The fourth branch, and the only one that needs no `--force` to reach the
    /// already-zero check: a span that overruns the region on its own, with no
    /// slide left to give back. Both implementations report the cache as
    /// unpatchable rather than writing a zero over a zero.
    ///
    /// The span has to exceed the region by itself — a 0x17C830000 span with a
    /// zero slide *fits*, and takes the fits branch instead, which is what both
    /// implementations do and what an earlier version of this test got wrong.
    @Test
    func `A cache that overruns the region with no slide left is left alone`() throws {
        try compare(
            named: "overflow_zero",
            regionSize: 0x1_9000_0000,
            maxSlide: 0,
            reference: FrozenReference.overflowWithZeroSlide,
            expectedSites: 0,
            expectedOutcome: .alreadyZero,
            expectedMaxSlideAfter: 0,
        )
    }

    // MARK: - Refusals

    @Test
    func `A missing main chunk is a named failure, not a crash`() throws {
        let empty = MaxSlideFixture.scratchRoot.appendingPathComponent("empty")
        try FileManager.default.createDirectory(at: empty, withIntermediateDirectories: true)
        defer { MaxSlideFixture.discard(empty) }

        #expect(throws: PatcherError.self) {
            _ = try DyldSharedCacheMaxSlidePatcher.patch(chunksDirectory: empty, verbose: false)
        }
    }

    /// The Python checks `hdr[:7] != b"dyld_v1"`; so does this. A `dyld_v2`
    /// header still parses as a cache far enough to reach the check, which is
    /// what makes the check worth having.
    @Test
    func `A file that is not a dyld_v1 cache is refused`() throws {
        let directory = MaxSlideFixture.scratchRoot.appendingPathComponent("badmagic")
        defer { MaxSlideFixture.discard(directory) }
        try Self.writeCache(
            into: directory,
            regionSize: 0x1_7C83_0000,
            maxSlide: 0x2000_0000,
            magic: "dyld_v2  arm64e",
        )

        #expect(throws: PatcherError.self) {
            _ = try DyldSharedCacheMaxSlidePatcher.patch(chunksDirectory: directory, verbose: false)
        }
    }

    /// dyld's own field-presence rule: the header struct ends where the mapping
    /// table begins, so a `mappingOffset` that does not reach past `maxSlide`
    /// means this cache version has no such field. The reference had no
    /// equivalent gate and would write eight zero bytes into whatever is at
    /// 0xF0 — here that is a `dyld_cache_mapping_info.fileOffset`.
    @Test
    func `A header too short to hold maxSlide is refused, where the reference would write`() throws {
        let directory = MaxSlideFixture.scratchRoot.appendingPathComponent("shortheader")
        defer { MaxSlideFixture.discard(directory) }
        // Mapping table at 0xC0: the header struct then ends at 0xC0, well
        // before the 0xF0 these offsets want to write at. The mapping itself is
        // still valid, so the run gets as far as the version gate.
        try Self.writeCache(
            into: directory,
            regionSize: 0x1_7C83_0000,
            maxSlide: 0x2000_0000,
            mappingOffset: 0xC0,
        )

        #expect(throws: PatcherError.self) {
            _ = try DyldSharedCacheMaxSlidePatcher.patch(chunksDirectory: directory, verbose: false)
        }
    }

    /// The corroboration check: a header whose `sharedRegionStart` is not the
    /// cache's lowest mapped address is not laid out the way these offsets
    /// assume, so the write is refused rather than aimed at an unknown field.
    @Test
    func `A header that disagrees with the mapping table is refused`() throws {
        let directory = MaxSlideFixture.scratchRoot.appendingPathComponent("mismatch")
        defer { MaxSlideFixture.discard(directory) }
        try Self.writeCache(
            into: directory,
            regionSize: 0x1_7C83_0000,
            maxSlide: 0x2000_0000,
        )
        // Move sharedRegionStart away from the mapping's address.
        let main = directory.appendingPathComponent(MaxSlideFixture.mainChunkName)
        let handle = try FileHandle(forUpdating: main)
        try handle.seek(toOffset: 0xE0)
        try handle.write(contentsOf: withUnsafeBytes(of: UInt64(0x1_9000_0000).littleEndian) {
            Data($0)
        })
        try handle.close()

        #expect(throws: PatcherError.self) {
            _ = try DyldSharedCacheMaxSlidePatcher.patch(chunksDirectory: directory, verbose: false)
        }
    }

    /// The Python's own self-test fixture: a bare 0x100-byte header with no
    /// mapping table. The reference patched it — it printed `overflow: … set
    /// maxSlide 0x20000000 -> 0x0` and the field read back as 0. This refuses
    /// it, because every write here goes through `DyldSharedCacheChunkSet`, which has
    /// nothing to address such a file with. A documented divergence, and a
    /// strictly safer one — the input is not a shared cache.
    @Test
    func `A header with no mapping table is refused, where the reference patched it`() throws {
        let swiftSide = MaxSlideFixture.scratchRoot.appendingPathComponent("headeronly_swift")
        defer { MaxSlideFixture.discard(swiftSide) }

        try FileManager.default.createDirectory(at: swiftSide, withIntermediateDirectories: true)
        var bytes = [UInt8](repeating: 0, count: 0x100)
        for (index, byte) in Array("dyld_v1  arm64e".utf8).enumerated() {
            bytes[index] = byte
        }
        func put(_ value: UInt64, at offset: Int) {
            withUnsafeBytes(of: value.littleEndian) { source in
                for (index, byte) in source.enumerated() {
                    bytes[offset + index] = byte
                }
            }
        }
        put(Self.mappingAddress, at: 0xE0)
        put(0x1_7C83_0000, at: 0xE8)
        put(0x2000_0000, at: 0xF0)
        try Data(bytes).write(
            to: swiftSide.appendingPathComponent(MaxSlideFixture.mainChunkName),
        )

        #expect(throws: DyldSharedCacheError.self) {
            _ = try DyldSharedCacheMaxSlidePatcher.patch(chunksDirectory: swiftSide, verbose: false)
        }
        let untouchedSlide = try Bytes.maxSlide(
            of: swiftSide.appendingPathComponent(MaxSlideFixture.mainChunkName),
        )
        #expect(untouchedSlide == 0x2000_0000, "the refusal still wrote")
    }
}

// MARK: - The region check, on synthetic caches

/// `requireFitsAtSlideZero`, which `cfw install` runs before any dyld patch.
/// Synthetic caches only, so this runs without the real-cache fixture: the
/// sizes are the iOS 27.0.1 (24A446) headers from issue #596.
struct DyldSharedCacheRegionCheckTests {
    private func withCache(
        regionSize: UInt64,
        maxSlide: UInt64 = 0x2000_0000,
        magic: String = "dyld_v1  arm64e",
        _ body: (URL) throws -> Void,
    ) throws {
        let directory = FileManager.default.temporaryDirectory
            .appendingPathComponent("vphone-dsc-region-\(UUID().uuidString)")
        defer { try? FileManager.default.removeItem(at: directory) }
        try DyldSharedCacheMaxSlideGateTests.writeCache(
            into: directory, regionSize: regionSize, maxSlide: maxSlide, magic: magic,
        )
        try body(directory)
    }

    @Test
    func `An x1 cache uses its own header symbols and subcaches`() throws {
        try withCache(regionSize: 0x1_7D50_8000, magic: "dyld_v1arm64ex1") { directory in
            let main = directory.appendingPathComponent(MaxSlideFixture.mainChunkName)
            let x1 = directory.appendingPathComponent("dyld_shared_cache_arm64e_x1")
            try FileManager.default.moveItem(at: main, to: x1)
            try Data().write(to: x1.appendingPathExtension("symbols"))
            try Data().write(to: x1.appendingPathExtension("01"))
            let chunks = try DyldSharedCacheChunkSet(directory: directory)
            #expect(chunks.mainCacheURL == x1)
            #expect(chunks.localSymbolsURL == x1.appendingPathExtension("symbols"))
            #expect(chunks.chunkURLs.map(\.lastPathComponent) == [x1.lastPathComponent, x1.lastPathComponent + ".01"])
            #expect(try DyldSharedCacheMaxSlidePatcher.requireFitsAtSlideZero(chunksDirectory: directory) == 0x1_7D50_8000)
            let result = try DyldSharedCacheMaxSlidePatcher.patch(chunksDirectory: directory, dryRun: true, verbose: false)
            #expect(result.sharedRegionSize == 0x1_7D50_8000)
            #expect(DyldSharedCacheChunkSet.mainCacheURL(in: directory, architecture: "arm64e") == main)
        }
    }

    @Test
    func `A regular cache never includes x1 chunks from the same directory`() throws {
        try withCache(regionSize: 0x1_7D50_8000) { directory in
            let x1 = directory.appendingPathComponent("dyld_shared_cache_arm64e_x1")
            try Data().write(to: x1)
            try Data().write(to: x1.appendingPathExtension("01"))
            let chunks = try DyldSharedCacheChunkSet(directory: directory)
            #expect(chunks.chunkURLs.map(\.lastPathComponent) == [MaxSlideFixture.mainChunkName])
            #expect(chunks.mainCacheURL.lastPathComponent == MaxSlideFixture.mainChunkName)
        }
    }

    @Test
    func `An iPhone18,2 27.0.1 cache overruns the region even at slide 0`() throws {
        try withCache(regionSize: 0x1_8580_4000) { directory in
            let main = directory.appendingPathComponent(MaxSlideFixture.mainChunkName)
            let before = try Data(contentsOf: main)
            #expect(throws: DyldSharedCacheMaxSlidePatcher.RegionOverflow(
                sharedRegionSize: 0x1_8580_4000,
                region: DyldSharedCacheMaxSlidePatcher.kernelSharedRegionSize,
            )) {
                try DyldSharedCacheMaxSlidePatcher.requireFitsAtSlideZero(chunksDirectory: directory)
            }
            #expect(try Data(contentsOf: main) == before, "the check wrote")
        }
    }

    @Test
    func `An iPhone17,3 27.0.1 cache fits once its slide is dropped`() throws {
        try withCache(regionSize: 0x1_7D50_8000) { directory in
            let size = try DyldSharedCacheMaxSlidePatcher.requireFitsAtSlideZero(chunksDirectory: directory)
            #expect(size == 0x1_7D50_8000)
        }
    }

    @Test
    func `A cache exactly the size of the region fits`() throws {
        let region = DyldSharedCacheMaxSlidePatcher.kernelSharedRegionSize
        try withCache(regionSize: region, maxSlide: 0) { directory in
            let size = try DyldSharedCacheMaxSlidePatcher.requireFitsAtSlideZero(chunksDirectory: directory)
            #expect(size == region)
        }
    }

    @Test
    func `The refusal names both sizes and a way out`() {
        let message = DyldSharedCacheMaxSlidePatcher.RegionOverflow(
            sharedRegionSize: 0x1_8580_4000,
            region: 0x1_8000_0000,
        ).description
        #expect(message.contains("0x185804000"))
        #expect(message.contains("0x180000000"))
        #expect(message.contains("iPhone17,3"))
    }
}