Skip to content

Run a virtual iPhone on an Apple Silicon Mac.

Swift
29.4 KB
Raw Blame
// DyldSharedCacheChunkSet.swift — Flat virtual-address access over a chunked dyld shared cache.
//
// The iOS 26/27 SystemOS cryptex ships the shared cache as many files:
//
//     dyld_shared_cache_arm64e
//     dyld_shared_cache_arm64e.01
//     dyld_shared_cache_arm64e.02
//     ...
//     dyld_shared_cache_arm64e.75.dylddata
//     dyld_shared_cache_arm64e.77.dyldlinkedit
//
// Every one of them carries its own `dyld_cache_header` and its own mapping
// table. The address ranges are disjoint across chunks, so together they are
// one contiguous virtual address space. This type is the translation from an
// address in that space to (file, offset), and back.
//
// It deliberately does not extract dylibs. Patchers want to read four bytes at
// a vmaddr, decide something, and write four bytes back; anything more is the
// symbol resolver's job.
//
// Port of `scripts/patchers/cfw_dsc_chunks.py`. The Python remains the
// independent reference for this layer — see `DyldSharedCacheFoundationTests`.
//
// Two places diverge from it on purpose, both pinned by tests:
//
//   * `bytes_at_vma` bounds-checks only its first byte and then reads `length`
//     raw bytes from the file, so a read near the end of a mapping comes back
//     padded with whatever follows — at 0x1800BBFFC on this cache, with the
//     chunk's own code signature. Here the whole span has to be addressable.
//   * `write_at_vma` compares only the chunk path, so it will write across a
//     mapping seam whether or not the file offsets continue across it. Here a
//     span may cross a seam only when the bytes behind it really are one run of
//     one file, which on this cache accepts every seam the Python accepts.

import Foundation
import VPhonePatchKit

/// A half-open span of virtual addresses that was written, or is about to be.
///
/// Re-attestation consumes these rather than bare addresses. An address alone
/// cannot say how many 16 KiB pages a write dirtied, and a caller that writes
/// eight bytes across a page boundary and then re-attests the one address it
/// started at leaves the second page's code slot stale — a
/// `KERN_PROTECTION_FAILURE` on the first demand-page-in, with nothing pointing
/// back at the patch. Carrying the length is what makes that unexpressible.
public struct DyldSharedCacheWriteSpan: Sendable, Hashable {
    /// First address the span covers.
    public let vma: UInt64
    /// Byte length. Always at least 1.
    public let length: Int

    public init(vma: UInt64, length: Int) {
        precondition(length > 0, "a write span covers at least one byte")
        self.vma = vma
        self.length = length
    }

    /// The single byte at `vma` — the only honest way to spell "just this
    /// address", and it has to be spelled out.
    public static func byte(at vma: UInt64) -> DyldSharedCacheWriteSpan {
        DyldSharedCacheWriteSpan(vma: vma, length: 1)
    }

    /// Last address the span covers.
    public var lastVMA: UInt64 {
        vma &+ UInt64(length - 1)
    }

    /// One past the last address the span covers.
    public var endVMA: UInt64 {
        vma &+ UInt64(length)
    }
}

/// Random-access byte view over a chunked dyld shared cache.
public final class DyldSharedCacheChunkSet {
    /// One `dyld_cache_mapping_info` entry, tagged with the chunk it came from.
    public struct Mapping: Sendable {
        /// First address the mapping covers.
        public let address: UInt64
        /// Byte length of the mapping.
        public let size: UInt64
        /// Offset of `address` within `chunkURL`.
        public let fileOffset: UInt64
        public let maxProt: UInt32
        /// VM_PROT mask: read 1, write 2, execute 4.
        public let initProt: UInt32
        public let chunkURL: URL

        /// One past the last address the mapping covers.
        public var endAddress: UInt64 {
            address &+ size
        }

        public var isExecutable: Bool {
            initProt & DyldSharedCacheChunkSet.vmProtExecute != 0
        }
    }

    public static let vmProtExecute: UInt32 = 4

    /// Directory holding the chunk files.
    public let directory: URL
    /// Chunk files, in the order they are enumerated (base file, then `.NN`).
    public let chunkURLs: [URL]
    /// Every mapping across every chunk, sorted by start address.
    public let mappings: [Mapping]

    private let architecture: String

    /// Guards the mutable state below.
    private let stateLock = NSLock()
    private var writeLog: [DyldSharedCacheWriteSpan] = []
    private var loadedLocalSymbols: DyldSharedCacheLocalSymbolTable?

    /// When set, every `write(at:_:)` first reads the bytes it is about to
    /// replace and captures them here, so a later run can put them back for a
    /// patch that has since been turned off. Nil disables capture, which is the
    /// default and what every read-only or throwaway use of this type wants.
    private var undoCaptureLog: DyldSharedCacheUndoLog?

    /// Chunk files mapped once, for a read-only set opened with `mappedReads`.
    /// Nil keeps the default: every read opens, seeks and closes the file.
    private var mappedChunks: [URL: Data]?

    // MARK: - Construction

    /// Open the cache under `directory`.
    ///
    /// - Parameters:
    ///   - directory: the directory holding `dyld_shared_cache_<arch>*`.
    ///   - architecture: explicit suffix, or nil to discover the cache.
    ///   - captureUndo: start capturing the original bytes of every write into
    ///     an undo log, retrievable with ``takeUndoLog()``. Off by default.
    ///   - mappedReads: serve reads from chunk files mapped once, for a set that
    ///     only reads, such as a planner's; its reads do not see later writes
    ///     made through another set. Off by default.
    public init(directory: URL, architecture: String? = nil, captureUndo: Bool = false, mappedReads: Bool = false) throws {
        mappedChunks = mappedReads ? [:] : nil
        self.directory = directory
        let architecture = String(Self.mainCacheURL(in: directory, architecture: architecture).lastPathComponent
            .dropFirst("dyld_shared_cache_".count))
        self.architecture = architecture
        undoCaptureLog = captureUndo ? DyldSharedCacheUndoLog() : nil
        chunkURLs = try Self.enumerateChunks(in: directory, architecture: architecture)
        guard !chunkURLs.isEmpty else {
            throw DyldSharedCacheError.noChunksFound(directory: directory.path)
        }

        var collected: [Mapping] = []
        for url in chunkURLs {
            for mapping in Self.parseMappings(of: url) where mapping.size != 0 {
                collected.append(mapping)
            }
        }
        guard !collected.isEmpty else {
            throw DyldSharedCacheError.noMappingsParsed(directory: directory.path)
        }
        collected.sort { $0.address < $1.address }
        mappings = collected
    }

    /// The unsuffixed chunk, which carries the cache-wide header (image list,
    /// sub-cache table, local-symbols pointer).
    public var mainCacheURL: URL {
        directory.appendingPathComponent("dyld_shared_cache_\(architecture)")
    }

    /// The `.symbols` side file holding the stripped local symbol table.
    public var localSymbolsURL: URL {
        directory.appendingPathComponent("dyld_shared_cache_\(architecture).symbols")
    }

    /// Prefers arm64e when both cache variants exist.
    public static func mainCacheURL(in directory: URL, architecture: String? = nil) -> URL {
        if let architecture {
            return directory.appendingPathComponent("dyld_shared_cache_\(architecture)")
        }
        let standard = directory.appendingPathComponent("dyld_shared_cache_arm64e")
        let x1 = directory.appendingPathComponent("dyld_shared_cache_arm64e_x1")
        return !FileManager.default.fileExists(atPath: standard.path)
            && FileManager.default.fileExists(atPath: x1.path) ? x1 : standard
    }

    /// Lowest and highest address the cache covers.
    public var addressRange: Range<UInt64> {
        (mappings.first?.address ?? 0) ..< (mappings.map(\.endAddress).max() ?? 0)
    }

    // MARK: - Address translation

    /// Locate `vma`'s byte in its chunk file.
    ///
    /// Returns `nil` when no mapping covers the address. Only the first byte is
    /// checked — use `fileRange(of:)` when a whole span has to be addressable.
    public func findChunk(forVMA vma: UInt64) -> (chunkURL: URL, fileOffset: Int)? {
        guard let mapping = mapping(forVMA: vma) else { return nil }
        return (mapping.chunkURL, Int(mapping.fileOffset &+ (vma &- mapping.address)))
    }

    /// The mapping covering `vma`, if any.
    public func mapping(forVMA vma: UInt64) -> Mapping? {
        mappingIndex(forVMA: vma).map { mappings[$0] }
    }

    private func mappingIndex(forVMA vma: UInt64) -> Int? {
        // Mappings are disjoint and sorted, so the candidate is the last one
        // that starts at or below `vma`.
        var low = 0
        var high = mappings.count
        while low < high {
            let mid = (low + high) / 2
            if mappings[mid].address <= vma {
                low = mid + 1
            } else {
                high = mid
            }
        }
        guard low > 0 else { return nil }
        return vma < mappings[low - 1].endAddress ? low - 1 : nil
    }

    /// The unbroken run of chunk-file bytes that starts at `vma`.
    ///
    /// A span is addressable when the bytes behind it are one contiguous run of
    /// one file. Usually that means one mapping, but neighbouring mappings of
    /// the same chunk are often contiguous in address *and* in file offset — on
    /// the 24A435 arm64e cache 19 of the 62 adjacent mapping pairs are, all of
    /// them inside a single chunk — and a read or write that crosses such a
    /// seam is still reading or writing exactly the right bytes. A seam where
    /// either the file offsets or the chunk files break is a different story,
    /// and stops the run.
    ///
    /// - Returns: the chunk file, the offset of `vma` in it, and how many bytes
    ///   follow before the run ends. `nil` when `vma` is not mapped at all.
    func contiguousRun(from vma: UInt64) -> (chunkURL: URL, fileOffset: UInt64, available: UInt64)? {
        guard var index = mappingIndex(forVMA: vma) else { return nil }
        let first = mappings[index]
        var available = first.endAddress &- vma
        while index + 1 < mappings.count {
            let current = mappings[index]
            let next = mappings[index + 1]
            guard next.chunkURL == current.chunkURL,
                  next.address == current.endAddress,
                  next.fileOffset == current.fileOffset &+ current.size
            else { break }
            available &+= next.size
            index += 1
        }
        return (first.chunkURL, first.fileOffset &+ (vma &- first.address), available)
    }

    /// Where `span` lives in its chunk file.
    ///
    /// Throws when the first byte is unmapped, and when the span runs off the
    /// end of its contiguous run — the case where the following bytes in the
    /// file belong to some other virtual address, or to none at all.
    public func fileRange(of span: DyldSharedCacheWriteSpan) throws -> (chunkURL: URL, range: Range<Int>) {
        guard let run = contiguousRun(from: span.vma) else {
            throw DyldSharedCacheError.addressNotMapped(span.vma)
        }
        guard UInt64(span.length) <= run.available else {
            throw DyldSharedCacheError.addressSpanCrossesChunk(vma: span.vma, length: span.length)
        }
        let start = Int(run.fileOffset)
        return (run.chunkURL, start ..< (start + span.length))
    }

    // MARK: - Reading

    /// Read `length` bytes at `vma`. The whole span must be addressable.
    ///
    /// This is stricter than `cfw_dsc_chunks.bytes_at_vma`, deliberately. The
    /// Python bounds-checks only the first byte and then reads `length` raw
    /// bytes from the file, so a read that starts near the end of a mapping
    /// comes back padded with whatever happens to follow — on this cache,
    /// asking for 64 bytes at 0x1800BBFFC returns 60 bytes of the chunk's own
    /// `CS_SuperBlob` dressed up as code. That is silent wrong data on a read
    /// API, so here it throws.
    public func bytesAtVMA(_ vma: UInt64, length: Int) throws -> Data {
        guard length > 0 else { return Data() }
        let (chunkURL, range) = try fileRange(of: DyldSharedCacheWriteSpan(vma: vma, length: length))
        let data = try readBytes(url: chunkURL, offset: UInt64(range.lowerBound), length: length)
        guard data.count == length else {
            throw DyldSharedCacheError.shortRead(vma: vma, wanted: length, got: data.count)
        }
        return data
    }

    /// Read up to `length` bytes at `vma`.
    ///
    /// With `allowShort` set, a span that would run past the end of what is
    /// addressable comes back truncated instead of throwing — what a
    /// load-command walk wants when it asks for "the next 64 KiB, however much
    /// of it exists".
    public func readAtVMA(_ vma: UInt64, length: Int, allowShort: Bool = false) throws -> Data {
        guard length > 0 else { return Data() }
        guard let run = contiguousRun(from: vma) else {
            throw DyldSharedCacheError.addressNotMapped(vma)
        }
        let wanted: Int
        if run.available >= UInt64(length) {
            wanted = length
        } else if allowShort {
            wanted = Int(run.available)
        } else {
            throw DyldSharedCacheError.addressSpanCrossesChunk(vma: vma, length: length)
        }
        return try readBytes(url: run.chunkURL, offset: run.fileOffset, length: wanted)
    }

    // MARK: - Writing

    /// Write `data` at `vma`, straight through to the chunk that holds it, and
    /// record the span so it can be re-attested.
    ///
    /// The whole span has to be addressable as one run of one chunk file. A
    /// write that would straddle two chunks is refused rather than split: the
    /// second chunk's bytes are a different file with a different code
    /// directory, and silently writing half a patch is worse than not writing
    /// it.
    ///
    /// - Returns: the span written, which is what
    ///   `DyldSharedCacheCodeSignature.reattest(in:modifiedSpans:)` consumes. The same span
    ///   is appended to `recordedWrites`, so a patcher that just writes and
    ///   then calls `reattestRecordedWrites(in:)` cannot under-attest. Empty
    ///   `data` writes nothing and records nothing; the span it hands back is
    ///   the single byte at `vma`, and re-attesting it is a no-op.
    ///
    /// `capturingOriginal: false` leaves the bytes out of the undo log even
    /// while capture is on: a caller that records its own originals, word by
    /// word, would otherwise keep a second copy of every page run it writes.
    @discardableResult
    public func write(at vma: UInt64, _ data: Data, capturingOriginal: Bool = true) throws -> DyldSharedCacheWriteSpan {
        guard !data.isEmpty else { return DyldSharedCacheWriteSpan.byte(at: vma) }
        let span = DyldSharedCacheWriteSpan(vma: vma, length: data.count)
        let (chunkURL, range) = try fileRange(of: span)
        // Capture the bytes about to be overwritten before writing, so a later
        // run can put them back. Read once here rather than re-reading the
        // whole span later, and only when capture is on.
        let captured: Data? = capturingOriginal && stateLock.withLock { undoCaptureLog != nil }
            ? try Self.read(url: chunkURL, offset: UInt64(range.lowerBound), length: data.count)
            : nil
        let handle = try FileHandle(forUpdating: chunkURL)
        defer { try? handle.close() }
        try handle.seek(toOffset: UInt64(range.lowerBound))
        try handle.write(contentsOf: data)
        stateLock.withLock {
            writeLog.append(span)
            if let captured, captured != data {
                undoCaptureLog?.capture(
                    chunk: chunkURL.lastPathComponent,
                    fileOffset: range.lowerBound,
                    vma: vma,
                    original: captured,
                )
            }
        }
        return span
    }

    /// The undo log captured so far, if capture was enabled, and clear it so a
    /// second call does not hand back the same records. The caller stamps the
    /// records with the patch identifier this cache set applied.
    public func takeUndoLog() -> DyldSharedCacheUndoLog? {
        stateLock.withLock {
            guard let log = undoCaptureLog else { return nil }
            undoCaptureLog = DyldSharedCacheUndoLog()
            return log
        }
    }

    /// Every span `write(at:_:)` has put on disk through this chunk set, oldest
    /// first.
    public var recordedWrites: [DyldSharedCacheWriteSpan] {
        stateLock.withLock { writeLog }
    }

    /// Forget the recorded writes — for a caller that re-attests in batches and
    /// does not want the next batch to redo the previous one's pages.
    public func clearRecordedWrites() {
        stateLock.withLock { writeLog.removeAll() }
    }

    // MARK: - Local symbols

    /// The cache's `.symbols` local symbol table, parsed once and kept.
    ///
    /// Parsed directly rather than shelled out to `ipsw dyld symaddr`, which
    /// times out on a cache this size. The table is big — 1.2 GB resident on
    /// the 24A435 arm64e cache — so it is loaded at most once per chunk set and
    /// can be dropped again with `unloadLocalSymbolTable()`.
    ///
    /// Throws when the side file is missing or unparseable. That is the whole
    /// point of it throwing: "the symbol table is not there" and "that symbol
    /// is not in it" are different answers, and the previous `try?` spelled
    /// both of them `nil`.
    public func localSymbolTable() throws -> DyldSharedCacheLocalSymbolTable {
        try stateLock.withLock {
            if let loadedLocalSymbols {
                return loadedLocalSymbols
            }
            guard FileManager.default.fileExists(atPath: localSymbolsURL.path) else {
                throw DyldSharedCacheError.localSymbolsMissing(path: localSymbolsURL.path)
            }
            let table = try DyldSharedCacheLocalSymbolTable(url: localSymbolsURL)
            loadedLocalSymbols = table
            return table
        }
    }

    /// Drop the cached local symbol table and its ~1.2 GB of buffers.
    public func unloadLocalSymbolTable() {
        stateLock.withLock { loadedLocalSymbols = nil }
    }

    /// Resolve `name` to its address through the cache's own `.symbols` table.
    ///
    /// Returns the first match, matching the Python reference; local symbol
    /// names are not guaranteed unique across images, so callers that care
    /// which image a symbol came from should use `DyldSharedCacheSymbolResolver` instead.
    ///
    /// `nil` means "no symbol by that name". A missing or unreadable table
    /// throws instead, so a force-kern discovery run cannot report "zero pairs"
    /// when what actually happened is that the table was not there.
    public func resolveLocalSymbol(_ name: String) throws -> UInt64? {
        try localSymbolTable().firstAddress(of: name)
    }

    // MARK: - Search helpers

    /// Every address at which `needle` appears in an executable mapping,
    /// anchored at the mapping start or just after a NUL.
    ///
    /// Restricted to RX mappings, which is where `__TEXT,__cstring` lives. That
    /// skips LINKEDIT and the `__DATA` mappings, which between them are most of
    /// the cache's bytes and none of its C strings.
    public func findStringVMAs(_ needle: Data) throws -> [UInt64] {
        guard !needle.isEmpty else { return [] }
        var results: [UInt64] = []
        for mapping in mappings where mapping.isExecutable {
            let buffer = try Self.window(
                over: mapping,
                at: mapping.fileOffset,
                length: Int(mapping.size),
            )
            var searchFrom = buffer.startIndex
            while searchFrom < buffer.endIndex,
                  let found = buffer.range(of: needle, in: searchFrom ..< buffer.endIndex)
            {
                let position = found.lowerBound - buffer.startIndex
                if position == 0 || buffer[buffer.startIndex + position - 1] == 0 {
                    results.append(mapping.address &+ UInt64(position))
                }
                searchFrom = found.lowerBound + 1
            }
        }
        return results
    }

    private static let machOMagic64LE = Data([0xCF, 0xFA, 0xED, 0xFE])

    /// Walk back from `vma` to the start of the Mach-O image that contains it.
    ///
    /// Images in the cache start on a page boundary at the head of their
    /// `__TEXT`, and an arm64e dylib's header shares a mapping with its
    /// `__text`, so the search never has to leave the containing mapping.
    public func findMachOHeaderBefore(
        _ vma: UInt64,
        maxWalk: Int = 64 * 1024 * 1024,
    ) throws -> UInt64? {
        guard let mapping = mapping(forVMA: vma) else { return nil }
        let localOffset = Int(vma &- mapping.address)
        let scanLength = min(localOffset, maxWalk)
        let scanStart = localOffset - scanLength
        // +4 so a header sitting right at the scan's end is still matched.
        let buffer = try Self.window(
            over: mapping,
            at: mapping.fileOffset &+ UInt64(scanStart),
            length: scanLength + 4,
        )
        var searchEnd = buffer.endIndex
        while searchEnd > buffer.startIndex,
              let found = buffer.range(
                  of: Self.machOMagic64LE,
                  options: .backwards,
                  in: buffer.startIndex ..< searchEnd,
              )
        {
            let position = found.lowerBound - buffer.startIndex
            let candidate = mapping.address &+ UInt64(scanStart + position)
            if candidate & 0xFFF == 0 {
                return candidate
            }
            searchEnd = found.lowerBound
        }
        return nil
    }

    /// The `LC_ID_DYLIB` install name of the image whose header is at
    /// `headerVMA`, or `nil` when that address is not a dylib header.
    public func readInstallName(atHeaderVMA headerVMA: UInt64) -> String? {
        guard let head = try? readAtVMA(headerVMA, length: 64 * 1024, allowShort: true),
              head.count >= 32,
              head.loadLE(UInt32.self, at: 0) == 0xFEED_FACF
        else { return nil }

        let commandCount = head.loadLE(UInt32.self, at: 16)
        let commandsSize = head.loadLE(UInt32.self, at: 20)
        guard commandCount <= 4096, commandsSize <= 64 * 1024 else { return nil }

        var offset = 32
        for _ in 0 ..< commandCount {
            guard offset + 8 <= head.count else { return nil }
            let command = head.loadLE(UInt32.self, at: offset)
            let commandSize = Int(head.loadLE(UInt32.self, at: offset + 4))
            guard commandSize >= 8, commandSize <= 64 * 1024 else { return nil }
            if command == 0xD { // LC_ID_DYLIB
                let nameOffset = Int(head.loadLE(UInt32.self, at: offset + 8))
                let nameStart = offset + nameOffset
                guard nameStart < head.count, nameStart < offset + commandSize else { return nil }
                let limit = min(head.count, offset + commandSize)
                var end = nameStart
                while end < limit, head[head.startIndex + end] != 0 {
                    end += 1
                }
                let bytes = head[(head.startIndex + nameStart) ..< (head.startIndex + end)]
                return String(decoding: bytes, as: UTF8.self)
            }
            offset += commandSize
            if offset > Int(commandsSize) + 32 {
                return nil
            }
        }
        return nil
    }

    // MARK: - Chunk enumeration and header parsing

    static func enumerateChunks(in directory: URL, architecture: String) throws -> [URL] {
        let prefix = "dyld_shared_cache_\(architecture)"
        let names = try FileManager.default
            .contentsOfDirectory(atPath: directory.path)
            .filter { $0 == prefix || $0.hasPrefix(prefix + ".") }
            .filter { !$0.hasSuffix(".symbols") && !$0.hasSuffix(".map") }

        // Base file first, then numerically by sub-cache index. Files whose
        // suffix is not a bare number (`.75.dylddata`, `.atlas`) sort after,
        // by name — they still carry mappings and must not be dropped.
        func sortKey(_ name: String) -> (Int, Int, String) {
            if name == prefix {
                return (0, -1, name)
            }
            let suffix = name.dropFirst(prefix.count)
            guard suffix.hasPrefix(".") else { return (1, 0, name) }
            let rest = suffix.dropFirst()
            if let index = Int(rest), !rest.isEmpty {
                return (0, index, name)
            }
            return (1, 0, name)
        }
        return names
            .sorted { sortKey($0) < sortKey($1) }
            .map { directory.appendingPathComponent($0) }
    }

    /// Parse one chunk's `dyld_cache_mapping_info` table.
    ///
    /// Slide-info mappings (`mappingWithSlideOffset`) are left alone: which
    /// address comes from which file offset is fully covered by the standard
    /// mappings, and that is all this layer claims to know.
    static func parseMappings(of url: URL) -> [Mapping] {
        guard let head = try? read(url: url, offset: 0, length: 0x100), head.count >= 24 else {
            return []
        }
        guard head.prefix(4) == Data("dyld".utf8) else { return [] }

        let mappingOffset = head.loadLE(UInt32.self, at: 16)
        let mappingCount = head.loadLE(UInt32.self, at: 20)
        // Sanity bounds — a mis-parsed header must not turn into a huge read.
        guard mappingCount <= 64, mappingOffset <= 0x10000 else { return [] }

        guard let raw = try? read(
            url: url,
            offset: UInt64(mappingOffset),
            length: Int(mappingCount) * 32,
        ), raw.count == Int(mappingCount) * 32 else { return [] }

        return (0 ..< Int(mappingCount)).map { index in
            let base = index * 32
            return Mapping(
                address: raw.loadLE(UInt64.self, at: base),
                size: raw.loadLE(UInt64.self, at: base + 8),
                fileOffset: raw.loadLE(UInt64.self, at: base + 16),
                maxProt: raw.loadLE(UInt32.self, at: base + 24),
                initProt: raw.loadLE(UInt32.self, at: base + 28),
                chunkURL: url,
            )
        }
    }

    /// `read(url:offset:length:)`, or a copy out of the chunk mapped once when
    /// this set was opened with `mappedReads`.
    private func readBytes(url: URL, offset: UInt64, length: Int) throws -> Data {
        guard length > 0 else { return Data() }
        let mapped: Data? = try stateLock.withLock {
            guard mappedChunks != nil else { return nil }
            if let file = mappedChunks?[url] { return file }
            let file = try Data(contentsOf: url, options: .alwaysMapped)
            mappedChunks?[url] = file
            return file
        }
        guard let file = mapped else { return try Self.read(url: url, offset: offset, length: length) }
        let lower = file.startIndex + Int(clamping: offset)
        guard lower < file.endIndex else { return Data() }
        return Data(file[lower ..< min(file.endIndex, lower + length)])
    }

    /// A bounded read: a seek and a copy of `length` bytes.
    ///
    /// Right for the small reads — a load command, a page, a run of a few
    /// kilobytes. Wrong for a whole mapping; use `window(over:)` for those.
    ///
    /// The pool returns the buffer FileHandle autoreleases to the caller's
    /// ownership. A command-line run never drains one otherwise, and the X1
    /// lowering's 212,573 page runs kept 3.3 GB of buffers alive that way.
    static func read(url: URL, offset: UInt64, length: Int) throws -> Data {
        guard length > 0 else { return Data() }
        return try autoreleasepool {
            let handle = try FileHandle(forReadingFrom: url)
            defer { try? handle.close() }
            try handle.seek(toOffset: offset)
            return try handle.read(upToCount: length) ?? Data()
        }
    }

    /// A whole mapping, as a slice of the MAPPED chunk file.
    ///
    /// The scans — `findStringVMAs` over every executable mapping,
    /// `findMachOHeaderBefore` walking back up to 64 MB — used `read` for this,
    /// which copied the mapping into the heap: an executable mapping is around
    /// 130 MB and there are two dozen of them, so one string search cost 3.3 GB
    /// of resident memory and a test run that did a few in a row took the
    /// machine down.
    ///
    /// A slice of a mapping is not a copy. The bytes fault in as the scan walks
    /// them and the kernel evicts them again behind it, so the same search
    /// costs a working set rather than the whole cache.
    ///
    /// The returned slice keeps the mapping alive for as long as it is held,
    /// and its `startIndex` is NOT zero — every caller here already works in
    /// terms of `buffer.startIndex`, which is what makes that safe.
    static func window(over mapping: Mapping, at offset: UInt64, length: Int) throws -> Data {
        guard length > 0 else { return Data() }
        let file = try Data(contentsOf: mapping.chunkURL, options: .mappedIfSafe)
        let lower = file.startIndex + Int(offset)
        guard lower <= file.endIndex else { return Data() }
        let upper = min(file.endIndex, lower + length)
        return file[lower ..< upper]
    }
}