rea-agents 4.0.1 → 5.0.0

package/dist/native/AppleDispatchMetadata.js

@@ -1,80 +1,33 @@
 import { createHash } from "node:crypto";
 import { open } from "node:fs/promises";
 import { constants } from "node:fs";
-import { objcSwiftMetadataSchema, nativeDispatchMetadataResultSchema, } from "../domain/objcSwiftMetadata.js";
-import { AnalysisCancelledError, EvidenceIntegrityError, } from "../domain/errors.js";
+import { objcSwiftMetadataSchema, nativeDispatchMetadataResultSchema, } from "../domain/native/objcSwiftMetadata.js";
+import { AnalysisCancelledError } from "../domain/analysisErrorCore.js";
+import { EvidenceIntegrityError } from "../domain/evidenceErrors.js";
+import { pushDispatchCoverage } from "./AppleDispatchCoverage.js";
+import { parsePointerFixups } from "./AppleMachoFixups.js";
+import { parseMachoLayout } from "./AppleMachoSelection.js";
+import { decodeObjcDispatchFacets } from "./AppleObjcDispatchFacets.js";
+import { createSwiftRelativeReader, decodeSwiftDispatchFacets, } from "./AppleSwiftDispatchFacets.js";
 import { decodeSwiftClassVtables } from "./AppleSwiftVtables.js";
-import { createObjcProtocolReader } from "./AppleObjcProtocols.js";
-const hex = (value) => `0x${value.toString(16)}`;
-const decoded = { status: "decoded", reason: null };
 /** Decode validated little-endian 64-bit Apple Objective-C metadata without loading target code. */
 export const decodeAppleDispatchMetadata = (bytes, maxRecords, provenance, architecture = "arm64") => {
-    if (bytes.length < 4)
-        throw new RangeError("Truncated Mach-O header");
-    const { slice, sliceEnd } = selectMachoSlice(bytes, architecture);
-    if (slice === 0 && sliceEnd === bytes.length && bytes.length < 32)
-        throw new RangeError("Truncated Mach-O header");
-    if (slice + 32 > sliceEnd || bytes.readUInt32LE(slice) !== 0xfeedfacf)
-        throw new TypeError("Only little-endian 64-bit Mach-O metadata is supported");
-    const commands = bytes.readUInt32LE(slice + 16);
-    const commandEnd = slice + 32 + bytes.readUInt32LE(slice + 20);
-    if (commands > 4096 || commandEnd > sliceEnd)
-        throw new RangeError("Malformed Mach-O command bounds");
-    const segments = [];
-    const sections = [];
-    let cursor = slice + 32;
-    for (let index = 0; index < commands; index++) {
-        if (cursor + 8 > commandEnd)
-            throw new RangeError("Truncated load command");
-        const kind = bytes.readUInt32LE(cursor), size = bytes.readUInt32LE(cursor + 4);
-        if (size < 8 || cursor + size > commandEnd)
-            throw new RangeError("Invalid load command size");
-        if (kind === 0x19) {
-            if (size < 72)
-                throw new RangeError("Truncated segment command");
-            const address = bytes.readBigUInt64LE(cursor + 24), fileSize = bytes.readBigUInt64LE(cursor + 48), fileOffset = bytes.readBigUInt64LE(cursor + 40);
-            if (fileOffset + fileSize > BigInt(sliceEnd - slice))
-                throw new RangeError("Segment file range exceeds target bytes");
-            segments.push({
-                address,
-                size: fileSize,
-                offset: slice + Number(fileOffset),
-                executable: (bytes.readUInt32LE(cursor + 60) & 4) !== 0,
-            });
-            const count = bytes.readUInt32LE(cursor + 64);
-            if (72 + count * 80 > size)
-                throw new RangeError("Truncated section table");
-            for (let section = 0; section < count; section++) {
-                const position = cursor + 72 + section * 80;
-                const sectionSize = bytes.readBigUInt64LE(position + 40);
-                if (sectionSize > BigInt(Number.MAX_SAFE_INTEGER))
-                    throw new RangeError("Section size exceeds exact numeric range");
-                sections.push({
-                    name: bytes
-                        .subarray(position, position + 16)
-                        .toString("ascii")
-                        .replace(/\0.*$/u, ""),
-                    address: bytes.readBigUInt64LE(position + 32),
-                    size: Number(sectionSize),
-                });
-            }
-        }
-        cursor += size;
-    }
-    const offset = (address, size = 1) => {
-        const matches = segments.filter((segment) => address >= segment.address &&
-            address + BigInt(size) <= segment.address + segment.size);
-        if (matches.length !== 1)
-            throw new RangeError(`Unmapped or ambiguous metadata pointer ${hex(address)}`);
-        const segment = matches[0];
-        if (segment === undefined)
-            throw new RangeError("Missing metadata segment");
-        return segment.offset + Number(address - segment.address);
-    };
+    const layout = parseMachoLayout(bytes, architecture);
+    const { segments, sections, offset } = layout;
+    const fixups = parsePointerFixups(bytes, layout.fixups, segments, layout.baseAddress);
     const u32 = (address) => bytes.readUInt32LE(offset(address, 4));
-    const pointer = (address) => bytes.readBigUInt64LE(offset(address, 8));
+    const decodePointer = (address) => fixups.decode(address, bytes.readBigUInt64LE(offset(address, 8)));
+    /** Rebased target of a pointer; a bind to another image reads as 0. */
+    const pointer = (address) => {
+        const decodedPointer = decodePointer(address);
+        return decodedPointer.kind === "rebase" ? decodedPointer.target : 0n;
+    };
+    const bound = (address) => {
+        const decodedPointer = decodePointer(address);
+        return decodedPointer.kind === "bind" ? decodedPointer : undefined;
+    };
     const location = (address) => ({
-        address: hex(address),
+        address: `0x${address.toString(16)}`,
         file_offset: offset(address),
     });
     const evidence = (address, description) => [
@@ -97,355 +50,54 @@ export const decodeAppleDispatchMetadata = (bytes, maxRecords, provenance, archi
         return new TextDecoder("utf-8", { fatal: true }).decode(bytes.subarray(start, end));
     };
     const result = objcSwiftMetadataSchema.parse({ db_save_result: null });
-    const failures = [];
-    let records = 0, examined = 0, truncated = false;
-    const admit = () => {
-        if (records >= maxRecords) {
-            truncated = true;
-            return false;
-        }
-        records++;
-        return true;
-    };
-    const methods = (list, className, methodType) => {
-        if (list === 0n)
-            return;
-        const flags = u32(list), count = u32(list + 4n), relative = (flags & 0x80000000) !== 0;
-        const stride = flags & 0xfffc;
-        if (stride !== (relative ? 12 : 24))
-            throw new TypeError(`Unsupported method stride/flags at ${hex(list)}`);
-        for (let index = 0; index < count; index++) {
-            if (!admit())
-                break;
-            const entry = list + 8n + BigInt(index * stride);
-            const rel = (field) => {
-                const displacement = bytes.readInt32LE(offset(field, 4));
-                const target = field + BigInt(displacement);
-                let fileOffset = null;
-                try {
-                    fileOffset = offset(target);
-                }
-                catch {
-                    /* serialized target remains unresolved */
-                }
-                if (admit())
-                    result.relative_pointers.push({
-                        field: location(field),
-                        target: { address: hex(target), file_offset: fileOffset },
-                        displacement,
-                        indirectable: false,
-                        indirect: false,
-                        decode: fileOffset === null
-                            ? { status: "partial", reason: "relative_target_unmapped" }
-                            : decoded,
-                        evidence: evidence(field, "Signed-relative Objective-C method-list pointer"),
-                    });
-                return target;
-            };
-            let selectorAddress = relative ? rel(entry) : pointer(entry);
-            if (relative && (flags & 0x40000000) === 0)
-                selectorAddress = pointer(selectorAddress);
-            const implementation = relative ? rel(entry + 8n) : pointer(entry + 16n);
-            let implementationLocation = null;
-            try {
-                if (!segments.some((segment) => segment.executable &&
-                    implementation >= segment.address &&
-                    implementation < segment.address + segment.size))
-                    throw new RangeError("Method implementation is not in an executable segment");
-                implementationLocation = location(implementation);
-            }
-            catch {
-                /* external/chained pointers remain unresolved */
-            }
-            result.objc_dispatch_implementations.push({
-                class_name: className,
-                selector: string(selectorAddress),
-                method_type: methodType,
-                implementation_address: implementationLocation?.address ?? null,
-                location: location(entry),
-                decode: implementationLocation === null
-                    ? {
-                        status: "partial",
-                        reason: "implementation_pointer_unmapped_or_encoded",
-                    }
-                    : decoded,
-                evidence: evidence(entry, relative
-                    ? "Encoded relative Objective-C method entry"
-                    : "Encoded absolute Objective-C method entry"),
-            });
-        }
-    };
-    const protocolReader = createObjcProtocolReader({
-        readers: {
-            u32,
-            pointer,
-            string,
-            location,
-            evidence,
-            admit,
-            i32: (address) => bytes.readInt32LE(offset(address, 4)),
+    let records = 0;
+    const budget = {
+        truncated: false,
+        isFull: () => records >= maxRecords,
+        markTruncated: () => {
+            budget.truncated = true;
         },
-        result,
-        failures,
-    });
-    for (const section of sections.filter(({ name }) => name === "__objc_protolist")) {
-        if (section.size % 8 !== 0)
-            throw new RangeError("Misaligned Objective-C protocol list");
-        for (let index = 0; index < section.size / 8; index++) {
+        admit: () => {
             if (records >= maxRecords) {
-                truncated = true;
-                break;
-            }
-            protocolReader.record(pointer(section.address + BigInt(index * 8)));
-        }
-    }
-    const visited = new Set();
-    const readClass = (address, meta = false) => {
-        if (address === 0n || visited.has(hex(address)) || !admit())
-            return;
-        visited.add(hex(address));
-        const ro = pointer(address + 32n) & ~7n;
-        const name = string(pointer(ro + 24n));
-        const superclass = pointer(address + 8n);
-        const root = (u32(ro) & 2) !== 0;
-        let superclassName = null;
-        if (superclass !== 0n) {
-            try {
-                superclassName = string(pointer((pointer(superclass + 32n) & ~7n) + 24n));
-            }
-            catch {
-                failures.push(`Superclass pointer ${hex(superclass)} of ${name} requires unsupported binding/fixup resolution`);
-            }
-        }
-        if (superclass === 0n && !root)
-            failures.push(`Superclass of ${name} requires external binding resolution`);
-        const ivarList = pointer(ro + 48n);
-        let ivarCount = 0;
-        if (ivarList !== 0n && !meta) {
-            const stride = u32(ivarList), count = u32(ivarList + 4n);
-            if (stride !== 32)
-                throw new TypeError("Unsupported Objective-C ivar entry size");
-            ivarCount = count;
-            for (let index = 0; index < count; index++) {
-                if (!admit())
-                    break;
-                const entry = ivarList + 8n + BigInt(index * stride);
-                const encodedOffset = pointer(entry);
-                let value = null;
-                try {
-                    value = u32(encodedOffset);
-                }
-                catch {
-                    failures.push(`Unresolved ivar offset pointer ${hex(encodedOffset)}`);
-                }
-                result.objc_ivars.push({
-                    class_name: name,
-                    name: string(pointer(entry + 8n)),
-                    type_encoding: string(pointer(entry + 16n)),
-                    offset: value,
-                    size: u32(entry + 28n),
-                    alignment: u32(entry + 24n) < 31 ? 2 ** u32(entry + 24n) : null,
-                    location: location(entry),
-                    decode: value === null
-                        ? { status: "partial", reason: "ivar_offset_pointer_unresolved" }
-                        : decoded,
-                    evidence: evidence(entry, "Objective-C ivar entry and encoded offset storage"),
-                });
-            }
-        }
-        methods(pointer(ro + 32n), name, meta ? "class" : "instance");
-        result.objc_classes.push({
-            name,
-            super_class: superclassName,
-            is_meta_class: meta,
-            is_root_class: root,
-            methods: result.objc_dispatch_implementations
-                .filter((item) => item.class_name === name &&
-                item.method_type === (meta ? "class" : "instance"))
-                .map((item) => ({
-                selector: item.selector,
-                method_type: item.method_type,
-                address: item.implementation_address !== null &&
-                    BigInt(item.implementation_address) <=
-                        BigInt(Number.MAX_SAFE_INTEGER)
-                    ? Number(BigInt(item.implementation_address))
-                    : null,
-                is_required: false,
-                is_optional: false,
-            })),
-            properties: [],
-            protocols: protocolReader.list(pointer(ro + 40n)),
-            ivar_count: ivarCount,
-            instance_size: u32(ro + 8n),
-            location: location(address),
-            superclass_address: superclass === 0n ? null : hex(superclass),
-            metaclass_address: meta ? null : hex(pointer(address)),
-            decode: superclassName === null && !root
-                ? { status: "partial", reason: "superclass_binding_unresolved" }
-                : decoded,
-            evidence: evidence(address, "Objective-C class and class_ro_t records"),
-        });
-        if (!meta) {
-            try {
-                readClass(pointer(address), true);
-            }
-            catch (cause) {
-                failures.push(`Metaclass of ${name}: ${cause instanceof Error ? cause.message : String(cause)}`);
+                budget.truncated = true;
+                return false;
             }
-        }
+            records++;
+            return true;
+        },
     };
-    for (const section of sections.filter(({ name }) => name === "__objc_classlist")) {
-        if (section.size % 8 !== 0)
-            throw new RangeError("Misaligned Objective-C class-list size");
-        for (let index = 0; index < section.size / 8; index++) {
-            if (records >= maxRecords) {
-                truncated = true;
-                break;
-            }
-            examined++;
-            const field = section.address + BigInt(index * 8);
-            try {
-                readClass(pointer(field));
-            }
-            catch (cause) {
-                failures.push(`${hex(field)}: ${cause instanceof Error ? cause.message : String(cause)}`);
-            }
-        }
-    }
-    const swiftRelative = (field, indirectable = false) => {
-        const displacement = bytes.readInt32LE(offset(field, 4));
-        const indirect = indirectable && (displacement & 1) !== 0;
-        let target = displacement === 0
-            ? 0n
-            : field + BigInt(indirectable ? displacement & ~1 : displacement);
-        let fileOffset = null;
-        let reason = null;
-        try {
-            if (indirect && target !== 0n)
-                target = pointer(target);
-            if (target !== 0n)
-                fileOffset = offset(target);
-        }
-        catch (cause) {
-            reason = cause instanceof Error ? cause.message : String(cause);
-        }
-        if (admit())
-            result.relative_pointers.push({
-                field: location(field),
-                target: {
-                    address: target === 0n ? null : hex(target),
-                    file_offset: fileOffset,
-                },
-                displacement,
-                indirectable,
-                indirect,
-                decode: reason === null ? decoded : { status: "partial", reason },
-                evidence: evidence(field, "Swift ABI signed-relative metadata pointer"),
-            });
-        if (reason !== null)
-            throw new RangeError(reason);
-        return target;
+    const readers = {
+        u32,
+        i32: (address) => bytes.readInt32LE(offset(address, 4)),
+        u64: (address) => bytes.readBigUInt64LE(offset(address, 8)),
+        pointer,
+        bound,
+        string,
+        location,
+        evidence,
+        offset,
     };
-    const swiftFailures = [];
-    let swiftExamined = 0;
-    for (const section of sections.filter(({ name }) => name === "__swift5_proto")) {
-        if (section.size % 4 !== 0)
-            throw new RangeError("Misaligned Swift conformance section");
-        for (let index = 0; index < section.size / 4; index++) {
-            if (!admit())
-                break;
-            swiftExamined++;
-            const field = section.address + BigInt(index * 4);
-            try {
-                const descriptor = swiftRelative(field);
-                const flags = u32(descriptor + 12n);
-                const protocol = swiftRelative(descriptor, true);
-                if ((u32(protocol) & 31) !== 3)
-                    throw new TypeError("Unsupported Swift protocol descriptor kind");
-                const protocolName = string(swiftRelative(protocol + 8n));
-                const typeKind = (flags >>> 3) & 7;
-                if (typeKind !== 0 && typeKind !== 1)
-                    throw new TypeError("Unsupported Swift conformance type-reference kind");
-                let type = swiftRelative(descriptor + 4n);
-                if (typeKind === 1)
-                    type = pointer(type);
-                if (![16, 17, 18].includes(u32(type) & 31))
-                    throw new TypeError("Unsupported Swift type descriptor kind");
-                const typeName = string(swiftRelative(type + 8n));
-                const witness = swiftRelative(descriptor + 8n);
-                const staticWitness = witness !== 0n && (flags & ~0x38) === 0 && (u32(type) & 0x80) === 0;
-                let witnessReason = staticWitness
-                    ? null
-                    : "Conditional, generic, resilient or missing static witness table is not decoded";
-                if (staticWitness && pointer(witness) !== descriptor)
-                    witnessReason =
-                        "Witness-table conformance header is unresolved or encoded";
-                result.swift_conformances.push({
-                    type_name: typeName,
-                    protocol_name: protocolName,
-                    module: null,
-                    witness_table: witness === 0n
-                        ? { address: null, file_offset: null }
-                        : location(witness),
-                    location: location(descriptor),
-                    decode: witnessReason === null
-                        ? decoded
-                        : {
-                            status: "partial",
-                            reason: witnessReason,
-                        },
-                    evidence: evidence(descriptor, "Swift protocol conformance descriptor and directly encoded type/protocol names"),
-                });
-                if (witnessReason !== null) {
-                    swiftFailures.push(`${typeName}: ${witnessReason}`);
-                    continue;
-                }
-                const count = u32(protocol + 16n);
-                const signatureCount = u32(protocol + 12n);
-                if (count > 20_000 || signatureCount > 20_000)
-                    throw new RangeError("Swift witness requirement count exceeds 20000");
-                for (let slot = 0; slot < count; slot++) {
-                    if (!admit())
-                        break;
-                    const entry = witness + BigInt((slot + 1) * 8);
-                    const implementation = pointer(entry);
-                    const requirementFlags = u32(protocol + 24n + BigInt(signatureCount * 12 + slot * 8));
-                    const kind = requirementFlags & 15;
-                    const synchronousFunction = kind >= 1 && kind <= 4 && (requirementFlags & 0x20) === 0;
-                    const executable = synchronousFunction &&
-                        segments.some((segment) => segment.executable &&
-                            implementation >= segment.address &&
-                            implementation < segment.address + segment.size);
-                    result.swift_dispatch_slots.push({
-                        owner: `${typeName}: ${protocolName}`,
-                        table_kind: "witness_table",
-                        slot_index: slot + 1,
-                        requirement: null,
-                        implementation: null,
-                        implementation_address: executable ? hex(implementation) : null,
-                        thunk_address: null,
-                        location: location(entry),
-                        decode: executable
-                            ? decoded
-                            : {
-                                status: "partial",
-                                reason: "Witness slot is non-function, async, nil, external, authenticated or encoded; implementation target is unresolved",
-                            },
-                        evidence: evidence(entry, "Static Swift witness slot, indexed after the conformance-descriptor header"),
-                    });
-                }
-            }
-            catch (cause) {
-                swiftFailures.push(`${hex(field)}: ${cause instanceof Error ? cause.message : String(cause)}`);
-            }
-        }
-    }
-    result.coverage.push({
-        facet: "swift_conformances_static_witness_slots",
-        status: swiftFailures.length > 0 || truncated ? "partial" : "complete",
-        reason: [...swiftFailures, ...(truncated ? ["max_records_reached"] : [])].join("; ") || null,
-        examined: swiftExamined,
-        decoded: result.swift_conformances.length,
+    const { failures, examined, categoriesExamined } = decodeObjcDispatchFacets({
+        bytes,
+        sections,
+        segments,
+        readers,
+        budget,
+        result,
+    });
+    const swiftRelative = createSwiftRelativeReader({
+        bytes,
+        readers,
+        budget,
+        result,
+    });
+    decodeSwiftDispatchFacets({
+        sections,
+        segments,
+        readers,
+        relative: swiftRelative,
+        budget,
+        result,
     });
     const typeEntries = [];
     for (const section of sections.filter(({ name }) => name === "__swift5_types")) {
@@ -454,7 +106,7 @@ export const decodeAppleDispatchMetadata = (bytes, maxRecords, provenance, archi
         for (let index = 0; index < section.size / 4 && index < maxRecords; index++)
             typeEntries.push(section.address + BigInt(index * 4));
         if (section.size / 4 > maxRecords)
-            truncated = true;
+            budget.truncated = true;
     }
     decodeSwiftClassVtables({
         entries: typeEntries,
@@ -465,45 +117,20 @@ export const decodeAppleDispatchMetadata = (bytes, maxRecords, provenance, archi
             string,
             location,
             evidence,
-            admit,
+            admit: () => budget.admit(),
             executable: (address) => segments.some((segment) => segment.executable &&
                 address >= segment.address &&
                 address < segment.address + segment.size),
         },
     });
-    result.coverage.push({
-        facet: "objc_class_method_ivar_metadata",
-        status: failures.length > 0 || truncated ? "partial" : "complete",
-        reason: [...failures, ...(truncated ? ["max_records_reached"] : [])].join("; ") ||
-            null,
+    pushDispatchCoverage({
+        result,
+        failures,
         examined,
-        decoded: result.objc_classes.length,
-    });
-    result.coverage.push({
-        facet: "binary_relative_pointers",
-        status: truncated ||
-            result.relative_pointers.some((item) => item.decode.status !== "decoded")
-            ? "partial"
-            : "complete",
-        reason: truncated
-            ? "max_records_reached"
-            : result.relative_pointers.some((item) => item.decode.status !== "decoded")
-                ? "relative_pointer_targets_unresolved"
-                : null,
-        examined: result.relative_pointers.length,
-        decoded: result.relative_pointers.filter((item) => item.decode.status === "decoded").length,
+        categoriesExamined,
+        truncated: budget.truncated,
+        fixups,
     });
-    for (const facet of [
-        "objc_properties_categories",
-        "swift_generic_resilient_witnesses_overrides_async_coroutines",
-    ])
-        result.coverage.push({
-            facet,
-            status: "unsupported",
-            reason: "This reader admits validated 64-bit Objective-C class/ivar/method lists and simple Swift conformance/static witness records; chained fixups, generic/resilient tables and other metadata families are not decoded",
-            examined: 0,
-            decoded: 0,
-        });
     return objcSwiftMetadataSchema.parse(result);
 };
 /** Read digest-verified target bytes under a 64 MiB static metadata budget. */
@@ -536,47 +163,3 @@ export const inspectAppleDispatchMetadata = async (target, maxRecords, signal) =
         await handle.close();
     }
 };
-const selectMachoSlice = (bytes, architecture) => {
-    const magic = bytes.readUInt32BE(0);
-    const littleEndian = magic === 0xbebafeca || magic === 0xbfbafeca;
-    if (magic !== 0xcafebabe && magic !== 0xcafebabf && !littleEndian)
-        return { slice: 0, sliceEnd: bytes.length };
-    const fat64 = magic === 0xcafebabf || magic === 0xbfbafeca;
-    const stride = fat64 ? 32 : 20;
-    const readUInt32 = littleEndian
-        ? (offset) => bytes.readUInt32LE(offset)
-        : (offset) => bytes.readUInt32BE(offset);
-    const readUInt64 = littleEndian
-        ? (offset) => bytes.readBigUInt64LE(offset)
-        : (offset) => bytes.readBigUInt64BE(offset);
-    const byteOrder = littleEndian ? "little-endian" : "big-endian";
-    const malformed = (reason) => new RangeError(`${reason} (FAT header byte order: ${byteOrder})`);
-    const invalid = (reason) => new TypeError(`${reason} (FAT header byte order: ${byteOrder})`);
-    if (bytes.length < 8)
-        throw malformed("Malformed FAT architecture table");
-    const count = readUInt32(4);
-    const headerEnd = 8 + count * stride;
-    if (count > 128 || headerEnd > bytes.length)
-        throw malformed("Malformed FAT architecture table");
-    const cpu = architecture === "arm64" ? 0x0100000c : 0x01000007;
-    let selected;
-    for (let index = 0; index < count; index++) {
-        const offset = 8 + index * stride;
-        if (readUInt32(offset) !== cpu)
-            continue;
-        if (selected !== undefined)
-            throw invalid("Ambiguous FAT architecture slice");
-        const start = fat64
-            ? readUInt64(offset + 8)
-            : BigInt(readUInt32(offset + 8));
-        const size = fat64
-            ? readUInt64(offset + 16)
-            : BigInt(readUInt32(offset + 12));
-        if (start < BigInt(headerEnd) || start + size > BigInt(bytes.length))
-            throw malformed("FAT slice exceeds file");
-        selected = { slice: Number(start), sliceEnd: Number(start + size) };
-    }
-    if (selected === undefined)
-        throw invalid("Requested FAT architecture is absent");
-    return selected;
-};