rea-agents 4.1.0 → 5.0.0

package/dist/native/AppleObjcDispatchFacets.js

@@ -0,0 +1,257 @@
+import { boundClassName, decodeObjcCategories } from "./AppleObjcCategories.js";
+import { readObjcPropertiesOf } from "./AppleObjcProperties.js";
+import { createObjcProtocolReader } from "./AppleObjcProtocols.js";
+const hex = (value) => `0x${value.toString(16)}`;
+const decoded = { status: "decoded", reason: null };
+/** Name of a class defined in this image, from its class_ro_t. */
+const localClassName = (read, address) => read.string(read.pointer((read.pointer(address + 32n) & ~7n) + 24n));
+/**
+ * Resolve a class's superclass: a bind to `_OBJC_CLASS_$_Name` names a class
+ * in another image; otherwise the pointer is a class_t in this image.
+ */
+const resolveSuperclass = (read, address, className, failures) => {
+    const external = boundClassName(read, address + 8n);
+    if (external !== undefined)
+        return { name: external, address: null };
+    const superclass = read.pointer(address + 8n);
+    if (superclass === 0n)
+        return { name: null, address: null };
+    try {
+        return { name: localClassName(read, superclass), address: hex(superclass) };
+    }
+    catch (cause) {
+        // Superclass resolution failure is recorded; the cause adds no identity.
+        void cause;
+        failures.push(`Superclass pointer ${hex(superclass)} of ${className} requires unsupported binding/fixup resolution`);
+        return { name: null, address: hex(superclass) };
+    }
+};
+/** Decode Objective-C protocol lists, classlists, methods, and ivars into `result`. */
+export const decodeObjcDispatchFacets = (input) => {
+    const { bytes, sections, segments, readers: read, budget, result } = input;
+    const failures = [];
+    let examined = 0;
+    const methods = (list, className, methodType, category) => {
+        const selectors = [];
+        if (list === 0n)
+            return selectors;
+        const flags = read.u32(list), count = read.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 (!budget.admit())
+                break;
+            const entry = list + 8n + BigInt(index * stride);
+            const rel = (field) => {
+                const displacement = bytes.readInt32LE(read.offset(field, 4));
+                const target = field + BigInt(displacement);
+                let fileOffset = null;
+                try {
+                    fileOffset = read.offset(target);
+                }
+                catch (cause) {
+                    // best-effort cleanup: serialized target remains unresolved.
+                    void cause;
+                }
+                if (budget.admit())
+                    result.relative_pointers.push({
+                        field: read.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: read.evidence(field, "Signed-relative Objective-C method-list pointer"),
+                    });
+                return target;
+            };
+            let selectorAddress = relative ? rel(entry) : read.pointer(entry);
+            if (relative && (flags & 0x40000000) === 0)
+                selectorAddress = read.pointer(selectorAddress);
+            const implementation = relative
+                ? rel(entry + 8n)
+                : read.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 = read.location(implementation);
+            }
+            catch (cause) {
+                // best-effort cleanup: external/chained pointers remain unresolved.
+                void cause;
+            }
+            const selector = read.string(selectorAddress);
+            selectors.push(selector);
+            result.objc_dispatch_implementations.push({
+                class_name: className,
+                selector,
+                method_type: methodType,
+                ...(category === undefined ? {} : { category }),
+                implementation_address: implementationLocation?.address ?? null,
+                location: read.location(entry),
+                decode: implementationLocation === null
+                    ? {
+                        status: "partial",
+                        reason: "implementation_pointer_unmapped_or_encoded",
+                    }
+                    : decoded,
+                evidence: read.evidence(entry, relative
+                    ? "Encoded relative Objective-C method entry"
+                    : "Encoded absolute Objective-C method entry"),
+            });
+        }
+        return selectors;
+    };
+    const protocolReader = createObjcProtocolReader({
+        readers: {
+            u32: read.u32,
+            pointer: read.pointer,
+            string: read.string,
+            location: read.location,
+            evidence: read.evidence,
+            admit: () => budget.admit(),
+            i32: read.i32,
+            u64: read.u64,
+        },
+        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++) {
+            if (budget.isFull()) {
+                budget.markTruncated();
+                break;
+            }
+            protocolReader.record(read.pointer(section.address + BigInt(index * 8)));
+        }
+    }
+    const visited = new Set();
+    const readClass = (address, meta = false) => {
+        if (address === 0n || visited.has(hex(address)) || !budget.admit())
+            return;
+        visited.add(hex(address));
+        const ro = read.pointer(address + 32n) & ~7n;
+        const name = read.string(read.pointer(ro + 24n));
+        const root = (read.u32(ro) & 2) !== 0;
+        const superclass = resolveSuperclass(read, address, name, failures);
+        if (superclass.name === null && superclass.address === null && !root)
+            failures.push(`Superclass of ${name} requires external binding resolution`);
+        const ivarList = read.pointer(ro + 48n);
+        let ivarCount = 0;
+        if (ivarList !== 0n && !meta) {
+            const stride = read.u32(ivarList), count = read.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 (!budget.admit())
+                    break;
+                const entry = ivarList + 8n + BigInt(index * stride);
+                const encodedOffset = read.pointer(entry);
+                let value = null;
+                try {
+                    value = read.u32(encodedOffset);
+                }
+                catch (cause) {
+                    // Unresolved offsets are recorded; the cause adds no identity.
+                    void cause;
+                    failures.push(`Unresolved ivar offset pointer ${hex(encodedOffset)}`);
+                }
+                result.objc_ivars.push({
+                    class_name: name,
+                    name: read.string(read.pointer(entry + 8n)),
+                    type_encoding: read.string(read.pointer(entry + 16n)),
+                    offset: value,
+                    size: read.u32(entry + 28n),
+                    alignment: read.u32(entry + 24n) < 31 ? 2 ** read.u32(entry + 24n) : null,
+                    location: read.location(entry),
+                    decode: value === null
+                        ? { status: "partial", reason: "ivar_offset_pointer_unresolved" }
+                        : decoded,
+                    evidence: read.evidence(entry, "Objective-C ivar entry and encoded offset storage"),
+                });
+            }
+        }
+        methods(read.pointer(ro + 32n), name, meta ? "class" : "instance");
+        result.objc_classes.push({
+            name,
+            super_class: superclass.name,
+            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: readObjcPropertiesOf(read, read.pointer(ro + 64n), {
+                owner: name,
+                admit: () => budget.admit(),
+                failures,
+            }),
+            protocols: protocolReader.list(read.pointer(ro + 40n)),
+            ivar_count: ivarCount,
+            instance_size: read.u32(ro + 8n),
+            location: read.location(address),
+            superclass_address: superclass.address,
+            metaclass_address: meta ? null : hex(read.pointer(address)),
+            decode: superclass.name === null && !root
+                ? { status: "partial", reason: "superclass_binding_unresolved" }
+                : decoded,
+            evidence: read.evidence(address, "Objective-C class and class_ro_t records"),
+        });
+        if (!meta) {
+            try {
+                readClass(read.pointer(address), true);
+            }
+            catch (cause) {
+                failures.push(`Metaclass of ${name}: ${cause instanceof Error ? cause.message : String(cause)}`);
+            }
+        }
+    };
+    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 (budget.isFull()) {
+                budget.markTruncated();
+                break;
+            }
+            examined++;
+            const field = section.address + BigInt(index * 8);
+            try {
+                readClass(read.pointer(field));
+            }
+            catch (cause) {
+                failures.push(`${hex(field)}: ${cause instanceof Error ? cause.message : String(cause)}`);
+            }
+        }
+    }
+    const categoriesExamined = decodeObjcCategories({
+        sections,
+        read,
+        result,
+        failures,
+        admit: () => budget.admit(),
+        methods,
+        protocols: (list) => protocolReader.list(list),
+        localClassName: (address) => localClassName(read, address),
+    });
+    return { failures, examined, categoriesExamined };
+};

package/dist/native/AppleObjcProperties.js

@@ -0,0 +1,68 @@
+/**
+ * Parse an `@property` attribute string such as `T@"NSString",C,N,V_name`.
+ * Each comma-separated token is one attribute; `T` is the type encoding.
+ */
+export const parsePropertyAttributes = (name, attributes) => {
+    const tokens = attributes.length === 0 ? [] : splitAttributes(attributes);
+    const value = (code) => tokens.find((token) => token.startsWith(code))?.slice(1) ?? null;
+    return {
+        name,
+        type_encoding: value("T"),
+        attributes: tokens.map((token) => ({
+            name: token.slice(0, 1),
+            value: token.slice(1),
+            is_weak: token === "W",
+            is_atomic: false,
+            is_copy: token === "C",
+            is_strong: token === "&",
+        })),
+        is_readonly: tokens.includes("R"),
+        getter: value("G"),
+        setter: value("S"),
+    };
+};
+/** Split on commas that are outside a quoted class name in the type encoding. */
+const splitAttributes = (attributes) => {
+    const tokens = [];
+    let current = "";
+    let quoted = false;
+    for (const character of attributes) {
+        if (character === '"')
+            quoted = !quoted;
+        if (character === "," && !quoted) {
+            tokens.push(current);
+            current = "";
+        }
+        else
+            current += character;
+    }
+    tokens.push(current);
+    return tokens.filter((token) => token.length > 0);
+};
+/** Decode `property_list_t { entsize_and_flags, count, property_t[] }`. */
+export const readObjcPropertyList = (read, list, admit) => {
+    if (list === 0n)
+        return [];
+    const entrySize = read.u32(list) & ~3;
+    const count = read.u32(list + 4n);
+    if (entrySize !== 16)
+        throw new TypeError(`Unsupported Objective-C property entry size ${entrySize}`);
+    const properties = [];
+    for (let index = 0; index < count; index++) {
+        if (!admit())
+            break;
+        const entry = list + 8n + BigInt(index * entrySize);
+        properties.push(parsePropertyAttributes(read.string(read.pointer(entry)), read.string(read.pointer(entry + 8n))));
+    }
+    return properties;
+};
+/** Decode a property list, recording a failure for `owner` instead of throwing. */
+export const readObjcPropertiesOf = (read, list, context) => {
+    try {
+        return readObjcPropertyList(read, list, context.admit);
+    }
+    catch (cause) {
+        context.failures.push(`Properties of ${context.owner}: ${cause instanceof Error ? cause.message : String(cause)}`);
+        return [];
+    }
+};

package/dist/native/AppleObjcProtocols.js

@@ -6,7 +6,8 @@ export const createObjcProtocolReader = (input) => {
     const list = (address) => {
         if (address === 0n)
             return [];
-        const count = read.pointer(address);
+        // `count` is plain uintptr_t data, not a pointer fixup.
+        const count = read.u64(address);
         if (count > 20000n)
             throw new RangeError("Protocol list exceeds 20000 entries");
         const names = [];

package/dist/native/AppleSwiftDispatchFacets.js

@@ -0,0 +1,150 @@
+const hex = (value) => `0x${value.toString(16)}`;
+const decoded = { status: "decoded", reason: null };
+/** Create a Swift ABI signed-relative pointer decoder that records relative_pointers. */
+export const createSwiftRelativeReader = (input) => {
+    const { bytes, readers: read, budget, result } = input;
+    return (field, indirectable = false) => {
+        const displacement = bytes.readInt32LE(read.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 = read.pointer(target);
+            if (target !== 0n)
+                fileOffset = read.offset(target);
+        }
+        catch (cause) {
+            reason = cause instanceof Error ? cause.message : String(cause);
+        }
+        if (budget.admit())
+            result.relative_pointers.push({
+                field: read.location(field),
+                target: {
+                    address: target === 0n ? null : hex(target),
+                    file_offset: fileOffset,
+                },
+                displacement,
+                indirectable,
+                indirect,
+                decode: reason === null ? decoded : { status: "partial", reason },
+                evidence: read.evidence(field, "Swift ABI signed-relative metadata pointer"),
+            });
+        if (reason !== null)
+            throw new RangeError(reason);
+        return target;
+    };
+};
+/** Decode `__swift5_proto` conformances and static witness slots into `result`. */
+export const decodeSwiftDispatchFacets = (input) => {
+    const { sections, segments, readers: read, relative, budget, result } = input;
+    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 (!budget.admit())
+                break;
+            swiftExamined++;
+            const field = section.address + BigInt(index * 4);
+            try {
+                const descriptor = relative(field);
+                const flags = read.u32(descriptor + 12n);
+                const protocol = relative(descriptor, true);
+                if ((read.u32(protocol) & 31) !== 3)
+                    throw new TypeError("Unsupported Swift protocol descriptor kind");
+                const protocolName = read.string(relative(protocol + 8n));
+                const typeKind = (flags >>> 3) & 7;
+                if (typeKind !== 0 && typeKind !== 1)
+                    throw new TypeError("Unsupported Swift conformance type-reference kind");
+                let type = relative(descriptor + 4n);
+                if (typeKind === 1)
+                    type = read.pointer(type);
+                if (![16, 17, 18].includes(read.u32(type) & 31))
+                    throw new TypeError("Unsupported Swift type descriptor kind");
+                const typeName = read.string(relative(type + 8n));
+                const witness = relative(descriptor + 8n);
+                const staticWitness = witness !== 0n &&
+                    (flags & ~0x38) === 0 &&
+                    (read.u32(type) & 0x80) === 0;
+                let witnessReason = staticWitness
+                    ? null
+                    : "Conditional, generic, resilient or missing static witness table is not decoded";
+                if (staticWitness && read.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 }
+                        : read.location(witness),
+                    location: read.location(descriptor),
+                    decode: witnessReason === null
+                        ? decoded
+                        : {
+                            status: "partial",
+                            reason: witnessReason,
+                        },
+                    evidence: read.evidence(descriptor, "Swift protocol conformance descriptor and directly encoded type/protocol names"),
+                });
+                if (witnessReason !== null) {
+                    swiftFailures.push(`${typeName}: ${witnessReason}`);
+                    continue;
+                }
+                const count = read.u32(protocol + 16n);
+                const signatureCount = read.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 (!budget.admit())
+                        break;
+                    const entry = witness + BigInt((slot + 1) * 8);
+                    const implementation = read.pointer(entry);
+                    const requirementFlags = read.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: read.location(entry),
+                        decode: executable
+                            ? decoded
+                            : {
+                                status: "partial",
+                                reason: "Witness slot is non-function, async, nil, external, authenticated or encoded; implementation target is unresolved",
+                            },
+                        evidence: read.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 || budget.truncated ? "partial" : "complete",
+        reason: [
+            ...swiftFailures,
+            ...(budget.truncated ? ["max_records_reached"] : []),
+        ].join("; ") || null,
+        examined: swiftExamined,
+        decoded: result.swift_conformances.length,
+    });
+};