rea-agents 6.3.0 → 6.5.0

package/dist/domain/apple/interfaceBuilderGraph.js

@@ -30,13 +30,16 @@ export const buildInterfaceBuilderAnalysis = (input) => {
     let omittedHierarchyReferences = 0;
     for (const document of input.documents.slice(0, input.limits.max_documents)) {
         const parsed = parseInterfaceBuilderRecords(document.raw);
-        const prefix = `ib:${document.relativePath}:`;
+        const prefix = `ib:${JSON.stringify(document.relativePath)}:`;
+        const graphId = (kind, parts = []) => `${prefix}${kind}:${JSON.stringify(parts)}`;
         const rootId = `${prefix}root`;
         const objectIds = new Set(parsed.objects.map(({ id }) => id));
         const evidenceFor = (description) => [
             {
                 kind: "interface_builder_resource",
-                description: `${document.relativePath}: ${description}`,
+                // artifact_path names the archive; repeating it here cost a path per
+                // node and edge.
+                description,
                 location: { address: null, file_offset: null },
                 artifact_path: document.relativePath,
                 artifact_sha256: document.archiveSha256,
@@ -66,7 +69,7 @@ export const buildInterfaceBuilderAnalysis = (input) => {
         addNode(rootNode);
         let documentObjectCount = 0;
         for (const object of parsed.objects.slice(0, input.limits.max_objects)) {
-            const id = `${prefix}object:${object.id}`;
+            const id = graphId("object", [object.id]);
             const kind = object.kind === "other" ? "unknown" : object.kind;
             if (!addNode({
                 id,
@@ -88,13 +91,15 @@ export const buildInterfaceBuilderAnalysis = (input) => {
         let hierarchyEdgeCount = 0;
         let documentOmittedConnections = 0;
         let documentOmittedHierarchyEdges = 0;
-        const objectNodeId = (objectId) => `${prefix}object:${objectId}`;
+        let hierarchyTruncated = false;
+        const objectNodeId = (objectId) => graphId("object", [objectId]);
         const addEdge = (edge, isHierarchy) => {
             if (isHierarchy
                 ? hierarchyEdgeCount >= input.limits.max_objects
                 : connectionEdgeCount >= input.limits.max_connections * 3) {
                 truncated = true;
                 if (isHierarchy) {
+                    hierarchyTruncated = true;
                     documentOmittedHierarchyEdges += 1;
                 }
                 else {
@@ -110,9 +115,11 @@ export const buildInterfaceBuilderAnalysis = (input) => {
                 connectionEdgeCount += 1;
         };
         const connect = (id, from, to, relation, description, reason) => {
+            const isHierarchy = relation === "contains" && id.includes(":hierarchy:");
             if (!nodes.has(from)) {
                 truncated = true;
-                if (relation === "contains" && id.includes(":hierarchy:")) {
+                if (isHierarchy) {
+                    hierarchyTruncated = true;
                     documentOmittedHierarchyEdges += 1;
                 }
                 else {
@@ -123,8 +130,11 @@ export const buildInterfaceBuilderAnalysis = (input) => {
             }
             const evidence = evidenceFor(description);
             const unresolvedEndpoint = to !== null && !nodes.has(to);
-            if (unresolvedEndpoint)
+            if (unresolvedEndpoint) {
                 truncated = true;
+                if (isHierarchy)
+                    hierarchyTruncated = true;
+            }
             const edgeTo = unresolvedEndpoint ? null : to;
             const edgeReason = unresolvedEndpoint
                 ? "endpoint_omitted_by_object_limit"
@@ -148,10 +158,9 @@ export const buildInterfaceBuilderAnalysis = (input) => {
                     resolution: "observed",
                     evidence,
                     limitations: [],
-                }, relation === "contains" && id.includes(":hierarchy:"));
+                }, isHierarchy);
         };
         let hierarchyCount = 0;
-        let hierarchyTruncated = false;
         const visitHierarchy = (initial, initialParentId) => {
             const pending = [{ value: initial, parentId: initialParentId }];
             while (pending.length > 0) {
@@ -181,7 +190,7 @@ export const buildInterfaceBuilderAnalysis = (input) => {
                     const known = objectIds.has(objectId);
                     const childId = known
                         ? objectNodeId(objectId)
-                        : `${prefix}unknown:${objectId}`;
+                        : graphId("unknown", [objectId]);
                     if (!known &&
                         !addNode({
                             id: childId,
@@ -192,7 +201,7 @@ export const buildInterfaceBuilderAnalysis = (input) => {
                             evidence: evidenceFor(`hierarchy item ${objectId}`),
                         }))
                         hierarchyTruncated = true;
-                    connect(`${prefix}hierarchy:${parentId}:${childId}`, parentId, childId, "contains", `hierarchy ${objectId}`);
+                    connect(graphId("hierarchy", [parentId, childId]), parentId, childId, "contains", `hierarchy ${objectId}`);
                     nextParent = childId;
                     hierarchyCount += 1;
                 }
@@ -216,10 +225,10 @@ export const buildInterfaceBuilderAnalysis = (input) => {
                 });
             const destinationId = item.destination_id === null ? null : objectNodeId(item.destination_id);
             if (item.kind === "action") {
-                const actionId = `${prefix}action:${item.id}`;
+                const actionId = graphId("action", [item.id]);
                 const selectorId = item.label === null
                     ? null
-                    : `${prefix}selector:${item.destination_id ?? "unknown"}:${item.label}`;
+                    : graphId("selector", [item.destination_id, item.label]);
                 addNode({
                     id: actionId,
                     kind: "action",
@@ -232,7 +241,7 @@ export const buildInterfaceBuilderAnalysis = (input) => {
                     },
                     evidence: evidenceFor(`action ${item.id}`),
                 });
-                connect(`${actionId}:source`, sourceId, actionId, "target_action", `action source ${item.source_id}`);
+                connect(graphId("action-edge", [item.id, "source"]), sourceId, actionId, "target_action", `action source ${item.source_id}`);
                 if (selectorId !== null) {
                     addNode({
                         id: selectorId,
@@ -242,15 +251,15 @@ export const buildInterfaceBuilderAnalysis = (input) => {
                         attributes: { destination_id: item.destination_id },
                         evidence: evidenceFor(`selector ${item.label}`),
                     });
-                    connect(`${actionId}:selector`, actionId, selectorId, "target_action", `selector ${item.label}`);
+                    connect(graphId("action-edge", [item.id, "selector"]), actionId, selectorId, "target_action", `selector ${item.label}`);
                 }
                 if (destinationId === null || !nodes.has(destinationId))
-                    connect(`${actionId}:destination`, actionId, null, "target_action", `action destination ${item.destination_id ?? "missing"}`, "destination_object_missing_or_external");
+                    connect(graphId("action-edge", [item.id, "destination"]), actionId, null, "target_action", `action destination ${item.destination_id ?? "missing"}`, "destination_object_missing_or_external");
                 else
-                    connect(`${actionId}:destination`, actionId, destinationId, "target_action", `action destination ${item.destination_id}`);
+                    connect(graphId("action-edge", [item.id, "destination"]), actionId, destinationId, "target_action", `action destination ${item.destination_id}`);
             }
             else if (item.kind === "outlet") {
-                const outletId = `${prefix}outlet:${item.id}`;
+                const outletId = graphId("outlet", [item.id]);
                 addNode({
                     id: outletId,
                     kind: "outlet",
@@ -259,43 +268,58 @@ export const buildInterfaceBuilderAnalysis = (input) => {
                     attributes: item.attributes,
                     evidence: evidenceFor(`outlet ${item.id}`),
                 });
-                connect(`${outletId}:source`, sourceId, outletId, "contains", `outlet source ${item.source_id}`);
+                connect(graphId("outlet-edge", [item.id, "source"]), sourceId, outletId, "contains", `outlet source ${item.source_id}`);
                 if (destinationId === null || !nodes.has(destinationId))
-                    connect(`${outletId}:destination`, outletId, null, "outlet_to", `outlet ${item.label ?? item.id}`, "destination_object_missing_or_external");
+                    connect(graphId("outlet-edge", [item.id, "destination"]), outletId, null, "outlet_to", `outlet ${item.label ?? item.id}`, "destination_object_missing_or_external");
                 else
-                    connect(`${outletId}:destination`, outletId, destinationId, "outlet_to", `outlet ${item.label ?? item.id}`);
+                    connect(graphId("outlet-edge", [item.id, "destination"]), outletId, destinationId, "outlet_to", `outlet ${item.label ?? item.id}`);
             }
             else if (item.kind === "segue") {
                 if (destinationId === null || !nodes.has(destinationId))
-                    connect(`${prefix}segue:${index}`, sourceId, null, "segue_to", `segue ${item.label ?? item.id}`, "destination_scene_missing");
+                    connect(graphId("segue", [index]), sourceId, null, "segue_to", `segue ${item.label ?? item.id}`, "destination_scene_missing");
                 else
-                    connect(`${prefix}segue:${index}`, sourceId, destinationId, "segue_to", `segue ${item.label ?? item.id}`);
+                    connect(graphId("segue", [index]), sourceId, destinationId, "segue_to", `segue ${item.label ?? item.id}`);
             }
             else {
-                connect(`${prefix}unknown-connection:${index}`, sourceId, null, "contains", `connection type ${item.kind}`, "unsupported_connection_type");
+                connect(graphId("unknown-connection", [index]), sourceId, null, "contains", `connection type ${item.kind}`, "unsupported_connection_type");
             }
         }
         const objectsTruncated = parsed.omittedObjects > 0 || parsed.objects.length > documentObjectCount;
         const parserOmittedHierarchyReferences = parsed.omittedHierarchyReferences;
-        omittedHierarchyReferences += parserOmittedHierarchyReferences;
+        const omittedSerializedHierarchyReferences = document.omittedSerializedHierarchyReferences ?? 0;
+        omittedHierarchyReferences +=
+            parserOmittedHierarchyReferences + omittedSerializedHierarchyReferences;
         const parserOmittedConnections = parsed.omittedConnections;
         const connectionsTruncated = parserOmittedConnections > 0 ||
             parsed.connections.length > input.limits.max_connections;
+        // A recognized connector the parser could not attach to an owner produces
+        // no connection record, so its coverage is partial with its own reason
+        // rather than absent or truncated.
+        const connectionsUnresolved = parsed.unresolvedConnections > 0;
         omittedObjects +=
             parsed.omittedObjects +
                 Math.max(0, parsed.objects.length - documentObjectCount);
         omittedConnections +=
             Math.max(0, parsed.connections.length - input.limits.max_connections) +
-                parserOmittedConnections;
+                parserOmittedConnections +
+                parsed.unresolvedConnections;
+        const hierarchyStatus = parserOmittedHierarchyReferences > 0 ||
+            omittedSerializedHierarchyReferences > 0
+            ? "partial"
+            : parsed.hierarchy.length === 0
+                ? "unsupported"
+                : hierarchyTruncated
+                    ? "partial"
+                    : "complete";
         summaries.push({
             relative_path: document.relativePath,
             archive_sha256: document.archiveSha256,
             document_kind: document.documentKind,
             object_count: parsed.objectCount,
-            connection_count: parsed.connections.length + parserOmittedConnections,
-            hierarchy_complete: parsed.hierarchy.length > 0 &&
-                !truncated &&
-                parserOmittedHierarchyReferences === 0,
+            connection_count: parsed.connections.length +
+                parserOmittedConnections +
+                parsed.unresolvedConnections,
+            hierarchy_complete: hierarchyStatus === "complete",
         });
         coverage.push({
             facet: `objects:${document.relativePath}`,
@@ -306,34 +330,37 @@ export const buildInterfaceBuilderAnalysis = (input) => {
                 Math.max(0, parsed.objects.length - documentObjectCount),
         }, {
             facet: `connections:${document.relativePath}`,
-            status: connectionsTruncated || documentOmittedConnections > 0
+            status: connectionsTruncated ||
+                documentOmittedConnections > 0 ||
+                connectionsUnresolved
                 ? "partial"
                 : "complete",
             reason: connectionsTruncated || documentOmittedConnections > 0
                 ? "connection_limit_reached"
-                : null,
+                : connectionsUnresolved
+                    ? "connection_unresolved"
+                    : null,
             examined: Math.min(parsed.connections.length, input.limits.max_connections),
             omitted: Math.max(0, parsed.connections.length - input.limits.max_connections) +
                 documentOmittedConnections +
-                parserOmittedConnections,
+                parserOmittedConnections +
+                parsed.unresolvedConnections,
         }, {
             facet: `hierarchy:${document.relativePath}`,
-            status: parserOmittedHierarchyReferences > 0
-                ? "partial"
-                : parsed.hierarchy.length === 0
-                    ? "unsupported"
-                    : hierarchyTruncated || documentOmittedHierarchyEdges > 0
-                        ? "partial"
-                        : "complete",
+            status: hierarchyStatus,
             reason: parserOmittedHierarchyReferences > 0
                 ? "archive_hierarchy_references_missing"
-                : parsed.hierarchy.length === 0
-                    ? "archive_hierarchy_not_decoded"
-                    : hierarchyTruncated || documentOmittedHierarchyEdges > 0
-                        ? "graph_limit_reached"
-                        : null,
+                : omittedSerializedHierarchyReferences > 0
+                    ? "serialized_view_hierarchy_incomplete"
+                    : parsed.hierarchy.length === 0
+                        ? "archive_hierarchy_not_decoded"
+                        : hierarchyTruncated
+                            ? "graph_limit_reached"
+                            : null,
             examined: hierarchyCount,
-            omitted: documentOmittedHierarchyEdges + parserOmittedHierarchyReferences,
+            omitted: documentOmittedHierarchyEdges +
+                parserOmittedHierarchyReferences +
+                omittedSerializedHierarchyReferences,
         }, {
             facet: `classes:${document.relativePath}`,
             status: Object.keys(parsed.classes).length > 0 ? "complete" : "unsupported",

package/dist/domain/apple/interfaceBuilderKeyedArchive.js

@@ -26,6 +26,12 @@ const connection = z.strictObject({
     label: z.string().nullable(),
     attributes: z.record(z.string(), jsonValueSchema),
 });
+/** UIKit runtime connection classes store their endpoints and labels under UI-prefixed keys. */
+export const isUIKitRuntimeConnectionClass = (className) => /^UIRuntime\w*Connection$/u.test(className);
+/** The connection class selects the source archive field namespace. */
+export const interfaceBuilderConnectionFieldNames = (className) => isUIKitRuntimeConnectionClass(className)
+    ? { source: "UISource", destination: "UIDestination", label: "UILabel" }
+    : { source: "NSSource", destination: "NSDestination", label: "NSLabel" };
 /** Parse ibtool dictionaries or compiled keyed archives into typed records. */
 export const parseInterfaceBuilderRecords = (value) => {
     const root = record(value);
@@ -44,12 +50,21 @@ export const parseInterfaceBuilderRecords = (value) => {
         const attributes = record(raw);
         const className = firstString(attributes["customClass"], attributes["class"], attributes["isa"]);
         const label = firstString(attributes["label"], attributes["title"], attributes["name"], className);
+        // class_name, name, and id already carry these values; repeating them in
+        // attributes doubled them on every graph node.
+        const carried = new Set();
+        if (attributes["customClass"] === className)
+            carried.add("customClass");
+        if (attributes["label"] === label)
+            carried.add("label");
+        if (attributes["objectID"] === id)
+            carried.add("objectID");
         objects.push(objectNode.parse({
             id,
             kind: classifyObject(className),
             class_name: className,
             name: label ?? id,
-            attributes: jsonSafeRecord(attributes),
+            attributes: jsonSafeRecord(Object.fromEntries(Object.entries(attributes).filter(([key]) => !carried.has(key)))),
         }));
     }
     for (const [sourceId, rawConnections] of Object.entries(connectionsRaw)) {
@@ -82,6 +97,7 @@ export const parseInterfaceBuilderRecords = (value) => {
         objectCount: objectEntries.length,
         omittedObjects: Math.max(0, objectEntries.length - 20_000),
         omittedConnections,
+        unresolvedConnections: 0,
         omittedHierarchyReferences: 0,
     };
 };
@@ -260,6 +276,7 @@ const parseKeyedArchive = (root) => {
     const connections = [];
     let objectCount = 0;
     let omittedConnections = 0;
+    let unresolvedConnections = 0;
     for (const [index, raw] of objectTable.entries()) {
         if (index === 0)
             continue;
@@ -285,20 +302,31 @@ const parseKeyedArchive = (root) => {
             }));
         if (/(?:Outlet|Connection|Segue|ActionConnection|ControlConnector)/iu.test(className)) {
             const controlAction = /ControlConnector/iu.test(className);
-            // AppKit connectors (NSNibOutletConnector, NSNibControlConnector)
-            // archive NSSource as the outlet owner or sending control and
-            // NSDestination as the outlet value or action target, so they are read
-            // in that order without the inversion the unprefixed fields use.
-            const source = firstObjectReference(controlAction ? fields.destination : fields.source, archivedObjectReference(fields.NSSource), controlAction ? fields.to : fields.from, controlAction ? fields.target : fields.owner);
-            if (source === null)
+            const uiKit = isUIKitRuntimeConnectionClass(className);
+            // AppKit and UIKit archive the same endpoint roles under their own
+            // class-specific field namespaces; the source is the outlet owner.
+            const connectionFields = interfaceBuilderConnectionFieldNames(className);
+            const source = uiKit
+                ? archivedObjectReference(fields[connectionFields.source])
+                : firstObjectReference(controlAction ? fields.destination : fields.source, archivedObjectReference(fields[connectionFields.source]), controlAction ? fields.to : fields.from, controlAction ? fields.target : fields.owner);
+            if (source === null) {
+                // A recognized connector that cannot name its owner is an unresolved
+                // connection, not an absent one, and cannot be represented as a
+                // connection because connection identity requires a source.
+                unresolvedConnections += 1;
                 continue;
+            }
             const kind = controlAction ? "action" : classifyConnection(className);
             const parsedConnection = connection.parse({
                 id: `archive:${objectId}`,
                 kind,
                 source_id: source,
-                destination_id: firstObjectReference(controlAction ? fields.source : fields.destination, archivedObjectReference(fields.NSDestination), controlAction ? fields.from : fields.to, controlAction ? fields.owner : fields.target),
-                label: firstString(fields.label, fields.NSLabel, fields.selector, fields.identifier, fields.action),
+                destination_id: uiKit
+                    ? archivedObjectReference(fields[connectionFields.destination])
+                    : firstObjectReference(controlAction ? fields.source : fields.destination, archivedObjectReference(fields[connectionFields.destination]), controlAction ? fields.from : fields.to, controlAction ? fields.owner : fields.target),
+                label: uiKit
+                    ? firstString(fields[connectionFields.label])
+                    : firstString(fields.label, fields[connectionFields.label], fields.selector, fields.identifier, fields.action),
                 attributes: jsonSafeRecord(fields),
             });
             if (connections.length < 40_000)
@@ -331,6 +359,7 @@ const parseKeyedArchive = (root) => {
         objectCount,
         omittedObjects: Math.max(0, objectCount - 20_000),
         omittedConnections,
+        unresolvedConnections,
         omittedHierarchyReferences: hierarchy.omittedReferences,
     };
 };

package/dist/domain/apple/machoContainer.js

@@ -1,3 +1,92 @@
+const FAT_MAGIC = 0xcafebabe;
+const FAT_MAGIC_64 = 0xcafebabf;
+const FAT_CIGAM = 0xbebafeca;
+const FAT_CIGAM_64 = 0xbfbafeca;
+const MAX_FAT_ARCHITECTURES = 128;
+const KNOWN_MACHO_CPU_TYPES = [
+    7, 0x01000007, 12, 0x0100000c, 0x0200000c, 18, 0x01000012,
+];
+const MACHO_HEADER_MAGICS = [
+    0xfeedface, 0xfeedfacf, 0xcefaedfe, 0xcffaedfe,
+];
+/** Parse a bounded FAT header and table without treating the magic alone as proof. */
+export const readFatContainerHeader = (bytes, fileSize) => {
+    if (bytes.byteLength < 4)
+        return { state: "not-fat" };
+    const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    const magic = view.getUint32(0, false);
+    if (![FAT_MAGIC, FAT_MAGIC_64, FAT_CIGAM, FAT_CIGAM_64].includes(magic))
+        return { state: "not-fat" };
+    if (!Number.isSafeInteger(fileSize) || fileSize < bytes.byteLength)
+        return {
+            state: "malformed",
+            reason: "FAT file size is invalid or contradicts retained bytes",
+        };
+    if (bytes.byteLength < 8) {
+        return fileSize < 8
+            ? { state: "malformed", reason: "FAT header is truncated" }
+            : { state: "needs-data", requiredBytes: 8 };
+    }
+    const littleEndian = magic === FAT_CIGAM || magic === FAT_CIGAM_64;
+    const wide = magic === FAT_MAGIC_64 || magic === FAT_CIGAM_64;
+    const count = view.getUint32(4, littleEndian);
+    if (count === 0)
+        return {
+            state: "malformed",
+            reason: "FAT header declares no architectures",
+        };
+    if (count > MAX_FAT_ARCHITECTURES)
+        return { state: "not-fat" };
+    const tableEnd = 8 + count * (wide ? 32 : 20);
+    if (tableEnd > fileSize)
+        return { state: "not-fat" };
+    if (tableEnd > bytes.byteLength)
+        return { state: "needs-data", requiredBytes: tableEnd };
+    const declarations = readFatSliceDeclarations(bytes.subarray(8, tableEnd), {
+        count,
+        wide,
+        littleEndian,
+    });
+    return declarations.status === "parsed"
+        ? {
+            state: "parsed",
+            magic,
+            count,
+            wide,
+            littleEndian,
+            tableEnd,
+            slices: declarations.slices,
+            rangeIssues: declarations.slices.map((slice) => inspectFatSliceRange(slice, fileSize, tableEnd)),
+        }
+        : { state: "malformed", reason: declarations.reason };
+};
+/** Confirm FAT identity from architecture records and observed slice headers. */
+export const classifyFatContainerIdentity = (header, sliceHeaderAt) => {
+    const hasKnownCpu = header.slices.some(({ cpuType }) => KNOWN_MACHO_CPU_TYPES.includes(cpuType));
+    const invalidRange = header.rangeIssues.find((issue) => issue !== null);
+    if (hasKnownCpu)
+        return invalidRange === undefined
+            ? { state: "mach-o" }
+            : { state: "malformed", ...invalidRange };
+    const validRanges = header.slices.filter((_slice, index) => header.rangeIssues[index] === null);
+    const missingHeaders = [];
+    let observedMachO = false;
+    for (const slice of validRanges) {
+        const magic = sliceHeaderAt(slice.offset);
+        if (magic === undefined)
+            missingHeaders.push(slice.offset);
+        else if (magic !== null && MACHO_HEADER_MAGICS.includes(magic))
+            observedMachO = true;
+    }
+    if (observedMachO) {
+        return invalidRange === undefined
+            ? { state: "mach-o" }
+            : { state: "malformed", ...invalidRange };
+    }
+    if (missingHeaders.length > 0)
+        return { state: "needs-slice-header", offsets: missingHeaders };
+    return { state: "not-mach-o" };
+};
 /** Decode FAT table entries once so artifact and native readers share identity facts. */
 export const readFatSliceDeclarations = (tableBytes, options) => {
     const { count, wide, littleEndian } = options;
@@ -32,23 +121,46 @@ export const readFatSliceDeclarations = (tableBytes, options) => {
 };
 /** Validate byte-range and table/header identity facts shared by Mach-O readers. */
 export const validateFatSlice = (declaration, containerSize, tableEnd, embedded) => {
-    const { index, offset, size, alignmentExponent, cpuType, cpuSubtype } = declaration;
+    const rangeIssue = inspectFatSliceRange(declaration, containerSize, tableEnd);
+    if (rangeIssue !== null)
+        return rangeIssue.reason;
+    return embedded === undefined
+        ? null
+        : validateFatSliceIdentity(declaration, embedded);
+};
+/** Validate table placement, container bounds, and alignment with a typed failure. */
+export const inspectFatSliceRange = (declaration, containerSize, tableEnd) => {
+    const { index, offset, size, alignmentExponent } = declaration;
     if (!Number.isSafeInteger(offset) ||
         !Number.isSafeInteger(size) ||
         size <= 0 ||
         offset < tableEnd)
-        return `FAT architecture ${index} has an invalid slice range`;
+        return {
+            category: "malformed",
+            reason: `FAT architecture ${index} has an invalid slice range`,
+        };
     if (offset > containerSize || size > containerSize - offset)
-        return `FAT architecture ${index} slice range extends beyond the file`;
+        return {
+            category: "malformed",
+            reason: `FAT architecture ${index} slice range extends beyond the file`,
+        };
     if (!Number.isInteger(alignmentExponent) ||
         alignmentExponent < 0 ||
         alignmentExponent > 52)
-        return `FAT architecture ${index} alignment exponent ${alignmentExponent} is unsupported`;
+        return {
+            category: "unsupported",
+            reason: `FAT architecture ${index} alignment exponent ${alignmentExponent} is unsupported`,
+        };
     if (offset % 2 ** alignmentExponent !== 0)
-        return `FAT architecture ${index} offset is not aligned to 2^${alignmentExponent}`;
-    if (embedded !== undefined &&
-        (embedded.cpuType !== cpuType || embedded.cpuSubtype !== cpuSubtype))
-        return `FAT architecture ${index} CPU type/subtype disagrees with its Mach-O header`;
+        return {
+            category: "malformed",
+            reason: `FAT architecture ${index} offset is not aligned to 2^${alignmentExponent}`,
+        };
     return null;
 };
+/** Validate only the identity claim after the owner has validated its range. */
+export const validateFatSliceIdentity = (declaration, embedded) => embedded.cpuType === declaration.cpuType &&
+    embedded.cpuSubtype === declaration.cpuSubtype
+    ? null
+    : `FAT architecture ${declaration.index} CPU type/subtype disagrees with its Mach-O header`;
 const safeNumber = (value) => value > BigInt(Number.MAX_SAFE_INTEGER) ? null : Number(value);

package/dist/domain/apple/machoCpuIdentity.js

@@ -0,0 +1,4 @@
+/** CPU subtype bits reserved for ABI/capability flags, not the base subtype. */
+const CPU_SUBTYPE_CAPABILITY_MASK = 0xff000000;
+/** Return the CPU subtype identity shared across capability-flag variations. */
+export const machoCpuSubtypeBase = (cpuSubtype) => cpuSubtype & ~CPU_SUBTYPE_CAPABILITY_MASK;

package/dist/domain/apple/plistValue.js

@@ -1,5 +1,10 @@
 import { z } from "zod";
-const MAX_PLIST_DEPTH = 128;
+/**
+ * Maximum plist value nesting the JSON projection supports. The XML decode
+ * preflight shares this limit so oversized documents are rejected before any
+ * recursive pass rather than during one.
+ */
+export const MAX_PLIST_DEPTH = 128;
 /**
  * Project a decoded plist into JSON. Data and dates become explicit
  * `$plist_type` objects; a non-finite real becomes an explicit unknown