rea-agents 6.3.0 → 6.5.0

package/dist/flutter/DartElf.js

@@ -0,0 +1,418 @@
+import { Buffer } from "node:buffer";
+import { setImmediate as yieldToEventLoop } from "node:timers/promises";
+import { createElfLoadMap } from "./ElfLoadMap.js";
+import { SNAPSHOT_HASH_LENGTH, SNAPSHOT_HASH_OFFSET, SNAPSHOT_HASH_PATTERN, } from "./FlutterPayloadScan.js";
+import { readElfFixedHeader } from "../domain/elfFixedHeader.js";
+/** Bounds-checked little-endian reader over one loaded buffer. */
+class BoundedReader {
+    bytes;
+    constructor(bytes) {
+        this.bytes = bytes;
+    }
+    u8(offset) {
+        return offset < this.bytes.length ? this.bytes.readUInt8(offset) : null;
+    }
+    u16(offset) {
+        return offset + 2 <= this.bytes.length
+            ? this.bytes.readUInt16LE(offset)
+            : null;
+    }
+    u32(offset) {
+        return offset + 4 <= this.bytes.length
+            ? this.bytes.readUInt32LE(offset)
+            : null;
+    }
+    u64(offset) {
+        const low = this.u32(offset);
+        const high = this.u32(offset + 4);
+        if (low === null || high === null || high > 0x001fffff)
+            return null;
+        return high * 0x1_0000_0000 + low;
+    }
+    cString(offset, tableEnd) {
+        if (offset < 0 || offset >= tableEnd || tableEnd > this.bytes.length)
+            return null;
+        const end = this.bytes
+            .subarray(offset, Math.min(tableEnd, offset + 257))
+            .indexOf(0);
+        return end < 0
+            ? null
+            : this.bytes.subarray(offset, offset + end).toString("latin1");
+    }
+}
+const SHT_DYNSYM = 11;
+const PT_LOAD = 1;
+const PT_DYNAMIC = 2;
+/** Position-independent executable images carry PT_DYNAMIC. */
+const ET_DYN = 3;
+const DT_NULL = 0;
+const DT_STRTAB = 5;
+const DT_SYMTAB = 6;
+const DT_STRSZ = 10;
+const DT_SYMENT = 11;
+/** ELF32 needs 52 bytes, ELF64 needs 64; retain at most this prefix. */
+export const ELF_HEADER_MAX_BYTES = 64;
+/**
+ * Decode the supported ELF header and validate its table extents against
+ * the complete image size. The buffer may contain only the header prefix;
+ * this does not validate table contents or symbol availability.
+ */
+export const readElfHeader = (bytes, totalBytes = bytes.length) => {
+    const reader = new BoundedReader(bytes);
+    const fixedHeader = readElfFixedHeader(bytes, totalBytes);
+    if (!fixedHeader.ok)
+        return { failure: { reason: fixedHeader.error } };
+    const is64 = fixedHeader.value.elfClass === 64;
+    const headerBytes = is64 ? ELF_HEADER_MAX_BYTES : 52;
+    if (fixedHeader.value.byteOrder !== "little")
+        return { failure: { reason: "unsupported ELF byte order" } };
+    if (fixedHeader.value.headerSize !== headerBytes)
+        return { failure: { reason: "unsupported ELF header size" } };
+    const e_type = reader.u16(0x10);
+    if (e_type !== 1 && e_type !== 2 && e_type !== ET_DYN)
+        return { failure: { reason: "unsupported ELF type" } };
+    const e_shoff = is64 ? reader.u64(0x28) : reader.u32(0x20);
+    const e_shentsize = reader.u16(is64 ? 0x3a : 0x2e);
+    const e_shnum = reader.u16(is64 ? 0x3c : 0x30);
+    const e_phoff = is64 ? reader.u64(0x20) : reader.u32(0x1c);
+    const e_phentsize = reader.u16(is64 ? 0x36 : 0x2a);
+    const e_phnum = reader.u16(is64 ? 0x38 : 0x2c);
+    const tableFits = (offset, width, count, minimumWidth) => offset !== null &&
+        width !== null &&
+        count !== null &&
+        offset >= headerBytes &&
+        offset <= totalBytes &&
+        width >= minimumWidth &&
+        count > 0 &&
+        count <= Math.floor((totalBytes - offset) / width);
+    const MIN_SHENT = is64 ? 64 : 40;
+    // Section-stripped ET_DYN images keep their exported symbols reachable
+    // through PT_DYNAMIC instead of section headers; every other shape still
+    // needs a usable section header table.
+    // A nonzero shoff with shnum=0 uses extended numbering, which this
+    // parser does not support; it must not masquerade as a stripped image.
+    const dynamicFallback = e_type === ET_DYN && e_shoff === 0 && e_shnum === 0;
+    if (e_shoff === null ||
+        e_shentsize === null ||
+        e_shnum === null ||
+        (!dynamicFallback && !tableFits(e_shoff, e_shentsize, e_shnum, MIN_SHENT)))
+        return {
+            failure: {
+                reason: "ELF section header table is missing or out of bounds",
+            },
+        };
+    const MIN_PHENT = is64 ? 56 : 32;
+    if (e_phoff === null ||
+        e_phentsize === null ||
+        e_phnum === null ||
+        e_phnum === 0xffff ||
+        !tableFits(e_phoff, e_phentsize, e_phnum, MIN_PHENT))
+        return {
+            failure: {
+                reason: "ELF program header table is missing or out of bounds",
+            },
+        };
+    return {
+        header: {
+            is64,
+            dynamicFallback,
+            e_shoff,
+            e_shentsize,
+            e_shnum,
+            e_phoff,
+            e_phentsize,
+            e_phnum,
+        },
+    };
+};
+/** Decode the ELF tables once and resolve only the requested definitions. */
+export const readElfSymbols = async (bytes, symbolNames, signal) => {
+    signal?.throwIfAborted();
+    const failure = (reason) => ({
+        symbols: [],
+        failures: [{ reason }],
+    });
+    const parsed = readElfHeader(bytes);
+    if (parsed.failure !== undefined)
+        return failure(parsed.failure.reason);
+    const { is64, dynamicFallback, e_shoff, e_shentsize, e_shnum, e_phoff, e_phentsize, e_phnum, } = parsed.header;
+    const reader = new BoundedReader(bytes);
+    const entrySize = is64 ? 24 : 16;
+    const segments = [];
+    let dynamicSegment = null;
+    for (let index = 0; index < e_phnum; index += 1) {
+        if (index % 4096 === 0) {
+            await yieldToEventLoop();
+            signal?.throwIfAborted();
+        }
+        const base = e_phoff + index * e_phentsize;
+        const type = reader.u32(base);
+        if (type !== PT_LOAD && type !== PT_DYNAMIC)
+            continue;
+        const vaddr = is64 ? reader.u64(base + 0x10) : reader.u32(base + 8);
+        const offset = is64 ? reader.u64(base + 8) : reader.u32(base + 4);
+        const filesz = is64 ? reader.u64(base + 0x20) : reader.u32(base + 0x10);
+        if (vaddr === null ||
+            offset === null ||
+            filesz === null ||
+            !Number.isSafeInteger(vaddr + filesz) ||
+            offset > bytes.length ||
+            filesz > bytes.length - offset)
+            return failure(`ELF segment ${String(index)} is not file-backed`);
+        if (type === PT_LOAD)
+            segments.push({ vaddr, offset, filesz });
+        else if (dynamicSegment !== null)
+            return failure("Multiple PT_DYNAMIC segments are ambiguous");
+        else
+            dynamicSegment = { offset, filesz };
+    }
+    const toOffset = await createElfLoadMap(segments, signal);
+    if (segments.length === 0)
+        return failure("ELF image has no PT_LOAD segments");
+    const tables = [];
+    if (!dynamicFallback) {
+        for (let index = 0; index < e_shnum; index += 1) {
+            if (index % 4096 === 0) {
+                await yieldToEventLoop();
+                signal?.throwIfAborted();
+            }
+            const header = e_shoff + index * e_shentsize;
+            if (reader.u32(header + 4) !== SHT_DYNSYM)
+                continue;
+            const offset = is64
+                ? reader.u64(header + 0x18)
+                : reader.u32(header + 0x10);
+            const size = is64 ? reader.u64(header + 0x20) : reader.u32(header + 0x14);
+            const width = is64
+                ? reader.u64(header + 0x38)
+                : reader.u32(header + 0x24);
+            const link = reader.u32(header + (is64 ? 0x28 : 0x18));
+            if (offset === null ||
+                size === null ||
+                width !== entrySize ||
+                offset > bytes.length ||
+                size > bytes.length - offset ||
+                size % entrySize !== 0)
+                return failure("Dynamic symbol table is malformed");
+            if (link === null || link >= e_shnum)
+                return failure("Dynamic symbol string section link is invalid");
+            const stringHeader = e_shoff + link * e_shentsize;
+            const stringOffset = is64
+                ? reader.u64(stringHeader + 0x18)
+                : reader.u32(stringHeader + 0x10);
+            const stringSize = is64
+                ? reader.u64(stringHeader + 0x20)
+                : reader.u32(stringHeader + 0x14);
+            if (reader.u32(stringHeader + 4) !== 3 ||
+                stringOffset === null ||
+                stringSize === null ||
+                stringOffset > bytes.length ||
+                stringSize > bytes.length - stringOffset)
+                return failure("Dynamic symbol strings are out of bounds or not a string table");
+            tables.push({
+                offset,
+                count: size / entrySize,
+                stringOffset,
+                stringSize,
+            });
+        }
+    }
+    else if (dynamicSegment !== null) {
+        const tags = new Map();
+        const dynamicEntrySize = is64 ? 16 : 8;
+        let terminated = false;
+        for (let base = dynamicSegment.offset; base + dynamicEntrySize <= dynamicSegment.offset + dynamicSegment.filesz; base += dynamicEntrySize) {
+            if ((base - dynamicSegment.offset) % (4096 * dynamicEntrySize) === 0) {
+                await yieldToEventLoop();
+                signal?.throwIfAborted();
+            }
+            const tag = is64 ? reader.u64(base) : reader.u32(base);
+            const value = is64 ? reader.u64(base + 8) : reader.u32(base + 4);
+            if (tag === null || value === null)
+                return failure("Dynamic entry is not representable");
+            if (tag === DT_NULL) {
+                terminated = true;
+                break;
+            }
+            if (![DT_SYMTAB, DT_STRTAB, DT_STRSZ, DT_SYMENT, 4, 0x6ffffef5].includes(tag))
+                continue;
+            if (tags.has(tag) && tags.get(tag) !== value)
+                return failure("Conflicting dynamic table tags");
+            tags.set(tag, value);
+        }
+        const sym = tags.get(DT_SYMTAB);
+        const str = tags.get(DT_STRTAB);
+        const stringSize = tags.get(DT_STRSZ);
+        if (!terminated ||
+            sym === undefined ||
+            str === undefined ||
+            stringSize === undefined ||
+            tags.get(DT_SYMENT) !== entrySize)
+            return failure("Stripped ELF lacks a complete dynamic symbol-table description");
+        // DT_HASH's nchain is the dynsym count. GNU hash instead records the
+        // first hashed index and bounded buckets/chains. No payload-to-EOF walk.
+        let count;
+        const sysv = tags.get(4);
+        const gnu = tags.get(0x6ffffef5);
+        if (sysv !== undefined) {
+            const at = toOffset(sysv, 8);
+            if (!at.ok)
+                return failure(`DT_HASH header ${at.error.reason}`);
+            const buckets = reader.u32(at.value);
+            count = reader.u32(at.value + 4);
+            const table = toOffset(sysv, 8 + 4 * (buckets + count));
+            if (!table.ok)
+                return failure(`DT_HASH table ${table.error.reason}`);
+        }
+        else if (gnu !== undefined) {
+            const at = toOffset(gnu, 16);
+            if (!at.ok)
+                return failure(`DT_GNU_HASH header ${at.error.reason}`);
+            const buckets = reader.u32(at.value);
+            const firstSymbol = reader.u32(at.value + 4);
+            const bloomWords = reader.u32(at.value + 8);
+            const prefixBytes = 16 + bloomWords * (is64 ? 8 : 4) + buckets * 4;
+            if (buckets === 0 || bloomWords === 0)
+                return failure("DT_GNU_HASH buckets are malformed");
+            const prefix = toOffset(gnu, prefixBytes);
+            if (!prefix.ok)
+                return failure(`DT_GNU_HASH buckets ${prefix.error.reason}`);
+            let last = 0;
+            const bucketsAt = at.value + 16 + bloomWords * (is64 ? 8 : 4);
+            for (let index = 0; index < buckets; index += 1) {
+                if (index % 4096 === 0) {
+                    await yieldToEventLoop();
+                    signal?.throwIfAborted();
+                }
+                const value = reader.u32(bucketsAt + index * 4);
+                if (value !== 0 && value < firstSymbol)
+                    return failure("DT_GNU_HASH bucket precedes its first symbol");
+                last = Math.max(last, value);
+            }
+            count = firstSymbol;
+            if (last !== 0) {
+                let index = last;
+                while (true) {
+                    if ((index - last) % 4096 === 0) {
+                        await yieldToEventLoop();
+                        signal?.throwIfAborted();
+                    }
+                    const span = prefixBytes + (index - firstSymbol + 1) * 4;
+                    const range = toOffset(gnu, span);
+                    if (!range.ok)
+                        return failure(`DT_GNU_HASH chain ${range.error.reason}`);
+                    const chain = reader.u32(at.value + span - 4);
+                    index += 1;
+                    if ((chain & 1) !== 0) {
+                        count = index;
+                        break;
+                    }
+                }
+            }
+        }
+        else
+            return failure("Stripped ELF has no DT_HASH or DT_GNU_HASH symbol count");
+        const offset = toOffset(sym, count * entrySize);
+        const stringOffset = toOffset(str, stringSize);
+        if (!offset.ok)
+            return failure(`Dynamic symbol table ${offset.error.reason}`);
+        if (!stringOffset.ok)
+            return failure(`Dynamic string table ${stringOffset.error.reason}`);
+        tables.push({
+            offset: offset.value,
+            count,
+            stringOffset: stringOffset.value,
+            stringSize,
+        });
+    }
+    const wanted = new Set(symbolNames);
+    const symbols = new Map();
+    const ambiguous = new Set();
+    const unresolved = new Set();
+    const failures = new Set();
+    for (const table of tables) {
+        for (let index = 0; index < table.count; index += 1) {
+            if (index % 4096 === 0) {
+                await yieldToEventLoop();
+                signal?.throwIfAborted();
+            }
+            const base = table.offset + index * entrySize;
+            const nameOffset = reader.u32(base);
+            const sectionIndex = reader.u16(base + (is64 ? 6 : 14));
+            const defined = sectionIndex === 0xfff1 ||
+                (sectionIndex > 0 &&
+                    sectionIndex < 0xff00 &&
+                    (dynamicFallback || sectionIndex < e_shnum));
+            if (!defined || nameOffset >= table.stringSize)
+                continue;
+            const name = reader.cString(table.stringOffset + nameOffset, table.stringOffset + table.stringSize);
+            if (name === null || !wanted.has(name))
+                continue;
+            const value = is64 ? reader.u64(base + 8) : reader.u32(base + 4);
+            const size = is64 ? reader.u64(base + 16) : reader.u32(base + 8);
+            if (value === null || size === null) {
+                failures.add(`Symbol ${name} has unrepresentable bounds`);
+                unresolved.add(name);
+                continue;
+            }
+            const offset = toOffset(value, size);
+            if (!offset.ok) {
+                failures.add(`Symbol ${name} ${offset.error.reason}`);
+                unresolved.add(name);
+                continue;
+            }
+            const previous = symbols.get(name);
+            if (previous !== undefined &&
+                (previous.offset !== offset.value || previous.size !== size))
+                ambiguous.add(name);
+            else
+                symbols.set(name, { name, offset: offset.value, size });
+        }
+    }
+    for (const name of ambiguous) {
+        symbols.delete(name);
+        failures.add(`Symbol ${name} has conflicting definitions`);
+    }
+    for (const name of unresolved)
+        symbols.delete(name);
+    for (const name of wanted)
+        if (!symbols.has(name) && !ambiguous.has(name) && !unresolved.has(name))
+            failures.add(`symbol ${name} is not in the dynamic symbol table`);
+    return {
+        symbols: [...symbols.values()],
+        failures: [...failures].map((reason) => ({ reason })),
+    };
+};
+/** Read one Dart snapshot section header from its file offset. */
+export const readSnapshotHeader = (bytes, offset) => {
+    const reader = new BoundedReader(bytes);
+    // The Dart magic bytes f5 f5 dc dc read little-endian. Kind and length
+    // fields are only meaningful in data-section headers; sections without
+    // the magic (instructions carry a different layout) report nulls.
+    const magic = reader.u32(offset);
+    if (magic !== 0xdcdcf5f5)
+        return {
+            magicValid: false,
+            kind: null,
+            headerLength: null,
+            hash: null,
+            complete: false,
+        };
+    const headerLength = reader.u64(offset + 4);
+    const kind = reader.u64(offset + 12);
+    const candidate = bytes
+        .subarray(offset + SNAPSHOT_HASH_OFFSET, offset + SNAPSHOT_HASH_OFFSET + SNAPSHOT_HASH_LENGTH)
+        .toString("latin1");
+    const hash = SNAPSHOT_HASH_PATTERN.test(candidate) ? candidate : null;
+    // Dart's stored length excludes the four magic bytes and includes the
+    // 20-byte fixed header and the version hash. Aligned data may follow it
+    // inside the exported symbol, but the serialized snapshot must fit.
+    // Kind 3 is FullAOT in the supported Dart 2.14 layout; enum values change
+    // across SDK versions, so other kinds remain uninterpreted observations.
+    const complete = headerLength !== null &&
+        headerLength >= SNAPSHOT_HASH_OFFSET + SNAPSHOT_HASH_LENGTH - 4 &&
+        headerLength <= bytes.length - offset - 4 &&
+        kind === 3 &&
+        hash !== null;
+    return { magicValid: true, kind, headerLength, hash, complete };
+};

package/dist/flutter/ElfBuildId.js

@@ -0,0 +1,137 @@
+import { setImmediate as yieldToEventLoop } from "node:timers/promises";
+import { readElfHeader, ELF_HEADER_MAX_BYTES, } from "./DartElf.js";
+const MAX_METADATA_BYTES = 8 * 1024 * 1024;
+const MAX_BUILD_IDS = 64;
+// Range bookkeeping and separate positional reads need a budget independent
+// of payload bytes: tiny/overlapping declarations can otherwise fan out I/O.
+const MAX_NOTE_RANGES = 1024;
+/** Read only ELF-declared PT_NOTE/SHT_NOTE ranges from one owned engine image. */
+export const readElfBuildIds = async (file, totalBytes, signal) => {
+    const candidates = new Set();
+    const failures = [];
+    const failure = (reason) => ({
+        candidates: [...candidates],
+        failures: [...failures, { reason }],
+    });
+    let examined = 0;
+    const read = async (offset, size) => {
+        signal?.throwIfAborted();
+        if (!Number.isSafeInteger(offset) ||
+            !Number.isSafeInteger(size) ||
+            offset < 0 ||
+            size < 0 ||
+            size > totalBytes - offset ||
+            size > MAX_METADATA_BYTES - examined)
+            return null;
+        examined += size;
+        const bytes = Buffer.alloc(size);
+        let copied = 0;
+        while (copied < size) {
+            const result = await file.read(bytes, copied, size - copied, offset + copied);
+            signal?.throwIfAborted();
+            if (result.bytesRead === 0)
+                return null;
+            copied += result.bytesRead;
+        }
+        return bytes;
+    };
+    const prefix = await read(0, Math.min(totalBytes, ELF_HEADER_MAX_BYTES));
+    if (prefix === null)
+        return failure("ELF header could not be read");
+    const parsed = readElfHeader(prefix, totalBytes);
+    if (parsed.failure !== undefined)
+        return failure(parsed.failure.reason);
+    const h = parsed.header;
+    const ranges = new Map();
+    tables: for (const table of [
+        {
+            offset: h.e_phoff,
+            width: h.e_phentsize,
+            count: h.e_phnum,
+            program: true,
+        },
+        {
+            offset: h.e_shoff,
+            width: h.e_shentsize,
+            count: h.e_shnum,
+            program: false,
+        },
+    ]) {
+        const bytes = await read(table.offset, table.width * table.count);
+        if (bytes === null)
+            return failure("ELF note tables exceed the 8 MiB metadata budget or are truncated");
+        for (let index = 0; index < table.count; index += 1) {
+            if (index % 4096 === 0) {
+                await yieldToEventLoop();
+                signal?.throwIfAborted();
+            }
+            const base = index * table.width;
+            if (bytes.readUInt32LE(base + (table.program ? 0 : 4)) !==
+                (table.program ? 4 : 7))
+                continue;
+            const offsetAt = base + (table.program ? (h.is64 ? 8 : 4) : h.is64 ? 0x18 : 0x10);
+            const sizeAt = base + (table.program ? (h.is64 ? 0x20 : 0x10) : h.is64 ? 0x20 : 0x14);
+            const offset = h.is64
+                ? Number(bytes.readBigUInt64LE(offsetAt))
+                : bytes.readUInt32LE(offsetAt);
+            const size = h.is64
+                ? Number(bytes.readBigUInt64LE(sizeAt))
+                : bytes.readUInt32LE(sizeAt);
+            if (!Number.isSafeInteger(offset) ||
+                !Number.isSafeInteger(size) ||
+                size > totalBytes - offset)
+                return failure("ELF note range is not file-backed");
+            if (size === 0)
+                continue;
+            const key = `${offset}:${size}`;
+            if (ranges.has(key))
+                continue;
+            if (ranges.size === MAX_NOTE_RANGES) {
+                failures.push({
+                    reason: "ELF notes exceed the 1024-range note-range inventory/read budget",
+                });
+                break tables;
+            }
+            ranges.set(key, { offset, size });
+        }
+    }
+    const align4 = (value) => Math.ceil(value / 4) * 4;
+    for (const range of ranges.values()) {
+        const notes = await read(range.offset, range.size);
+        if (notes === null)
+            return failure("ELF notes exceed the 8 MiB metadata budget or are truncated");
+        let yieldedAt = 0;
+        for (let at = 0; at < notes.length;) {
+            if (at - yieldedAt >= 64 * 1024) {
+                await yieldToEventLoop();
+                signal?.throwIfAborted();
+                yieldedAt = at;
+            }
+            if (notes.length - at < 12) {
+                if (notes.subarray(at).some((byte) => byte !== 0))
+                    return failure("ELF note header is truncated");
+                break;
+            }
+            const namesz = notes.readUInt32LE(at);
+            const descsz = notes.readUInt32LE(at + 4);
+            const type = notes.readUInt32LE(at + 8);
+            const descriptor = at + 12 + align4(namesz);
+            const end = descriptor + descsz;
+            if (end > notes.length)
+                return failure("ELF note descriptor exceeds its declared note range");
+            if (namesz === 4 &&
+                type === 3 &&
+                notes.subarray(at + 12, at + 16).equals(Buffer.from("GNU\0"))) {
+                if (descsz < 4 || descsz > 64)
+                    return failure("GNU build-id descriptor exceeds the 4–64 byte projection");
+                const candidate = notes.subarray(descriptor, end).toString("hex");
+                if (!candidates.has(candidate) && candidates.size === MAX_BUILD_IDS)
+                    return failure("ELF build-id candidates exceed the 64-value evidence budget");
+                candidates.add(candidate);
+            }
+            at = align4(end);
+        }
+    }
+    signal?.throwIfAborted();
+    return { candidates: [...candidates], failures };
+};

package/dist/flutter/ElfLoadMap.js

@@ -0,0 +1,91 @@
+import { setImmediate as yieldToEventLoop } from "node:timers/promises";
+import { err, ok } from "../domain/result.js";
+/** Normalize overlapping file-backed interpretations once, before any lookups. */
+export const createElfLoadMap = async (segments, signal) => {
+    const events = segments
+        .filter((segment) => segment.filesz > 0)
+        .flatMap((segment) => [
+        { at: segment.vaddr, delta: segment.offset - segment.vaddr, change: 1 },
+        {
+            at: segment.vaddr + segment.filesz,
+            delta: segment.offset - segment.vaddr,
+            change: -1,
+        },
+    ])
+        .sort((left, right) => left.at - right.at);
+    const active = new Map();
+    const spans = [];
+    let previous = 0;
+    for (let index = 0; index < events.length; index += 1) {
+        if (index % 4096 === 0) {
+            await yieldToEventLoop();
+            signal?.throwIfAborted();
+        }
+        const event = events[index];
+        if (event.at > previous && active.size > 0) {
+            const delta = active.size === 1 ? active.keys().next().value : null;
+            const last = spans.at(-1);
+            if (last?.end === previous && last.delta === delta)
+                last.end = event.at;
+            else
+                spans.push({ start: previous, end: event.at, delta });
+        }
+        const count = (active.get(event.delta) ?? 0) + event.change;
+        if (count === 0)
+            active.delete(event.delta);
+        else
+            active.set(event.delta, count);
+        previous = event.at;
+    }
+    // Prefix counts keep growing GNU-hash range checks logarithmic even with
+    // many load segments. Null denotes conflicting interpretations, not a hole.
+    const conflicts = [0];
+    for (const span of spans)
+        conflicts.push(conflicts.at(-1) + Number(span.delta === null));
+    const locate = (address) => {
+        let low = 0, high = spans.length;
+        while (low < high) {
+            const middle = Math.floor((low + high) / 2);
+            if (spans[middle].start <= address)
+                low = middle + 1;
+            else
+                high = middle;
+        }
+        return low - 1;
+    };
+    signal?.throwIfAborted();
+    return (address, size) => {
+        const missing = () => err({ reason: "has no contiguous file-backed PT_LOAD range" });
+        const ambiguous = () => err({ reason: "has conflicting PT_LOAD mappings" });
+        if (!Number.isSafeInteger(address) ||
+            !Number.isSafeInteger(size) ||
+            address < 0 ||
+            size < 0 ||
+            !Number.isSafeInteger(address + size))
+            return missing();
+        const first = locate(address);
+        const span = spans[first];
+        if (span === undefined || (size > 0 && address >= span.end))
+            return missing();
+        if (size === 0) {
+            // A zero-width symbol at a shared endpoint still needs one file offset.
+            if (address > span.end)
+                return missing();
+            const left = spans[first - 1];
+            if (span.delta === null ||
+                (span.start === address &&
+                    left?.end === address &&
+                    left.delta !== span.delta))
+                return ambiguous();
+            return ok(address + span.delta);
+        }
+        const last = locate(address + size - 1);
+        if (conflicts[last + 1] !== conflicts[first])
+            return ambiguous();
+        return span.delta !== null &&
+            address < span.end &&
+            size <= span.end - address
+            ? ok(address + span.delta)
+            : missing();
+    };
+};