rea-agents 6.0.0 → 6.1.0

package/dist/domain/apple/appleApplication.js

@@ -6,6 +6,7 @@ import { parseArtifactInventoryEvidence } from "../artifactInventoryEvidence.js"
 import { evidenceSchema } from "../evidence.js";
 import { digestSchema } from "../digests.js";
 import { prefixedDigestSchema } from "../digests.js";
+import { bridgeCandidateCoverageSchema, projectCartesianCandidates, } from "../bridgeCandidateProjection.js";
 const evidenceIdSchema = prefixedDigestSchema("ev");
 const pathSchema = z.string().min(1);
 const APPLE_ROOT_FORMATS = ["ipa", "directory", "zip", "dmg"];
@@ -52,6 +53,7 @@ export const appleApplicationProjectionResultSchema = z.strictObject({
             "unity-convention",
         ]),
     })),
+    bridge_candidate_coverage: bridgeCandidateCoverageSchema,
     coverage: z.strictObject({
         status: z.enum(["complete-within-inventory", "partial"]),
         inventory_complete: z.boolean(),
@@ -110,6 +112,7 @@ export const projectAppleApplication = (input) => {
         sidecars: entries.some(({ path }) => isSidecar(path)),
         symlinks: entries.some(({ kind }) => kind === "symlink"),
         unattributed,
+        bridgeCandidateCoverage: bridgeProjection.coverage,
     });
     const withoutId = {
         root_sha256: inventory.manifest.root_sha256,
@@ -127,8 +130,9 @@ export const projectAppleApplication = (input) => {
             .sort(compare),
         runtime_families: runtimeFamilies,
         bridge_candidates: bridgeProjection.candidates,
+        bridge_candidate_coverage: bridgeProjection.coverage,
         coverage: {
-            status: complete
+            status: complete && bridgeProjection.coverage.status === "complete"
                 ? "complete-within-inventory"
                 : "partial",
             inventory_complete: inventory.complete,
@@ -137,9 +141,11 @@ export const projectAppleApplication = (input) => {
     };
     return appleApplicationProjectionResultSchema.parse({
         ...withoutId,
-        projection_id: `aap_${digest(withoutId)}`,
+        projection_id: appleProjectionId(withoutId),
     });
 };
+/** Identify the complete projection, including source Evidence provenance. */
+export const appleProjectionId = (projection) => `aap_${digest(projection)}`;
 /**
  * IPA projection keeps every archive component, as before. Directory, ZIP,
  * and DMG inventories can hold installers and other siblings, so only
@@ -204,21 +210,37 @@ const identifyRuntimeFamilies = (all) => {
         families.add("unity");
     return [...families].sort(compare);
 };
-/** Pair scripts and native code only within the same application root. */
+/** Pair scripts and native code within matching application-root groups. */
 const identifyBridgeCandidates = (scripts, native, roots) => {
     const owner = (path) => roots.find((root) => isWithin(path, root)) ?? null;
-    return {
-        candidates: scripts.flatMap((script) => {
-            const root = owner(script.path);
-            return native
-                .filter(({ path }) => owner(path) === root)
-                .map((item) => ({
-                source_path: script.path,
-                native_path: item.path,
-                basis: bridgeBasis(item.path),
-            }));
+    const scriptGroups = [];
+    for (const script of scripts) {
+        const root = owner(script.path);
+        const last = scriptGroups.at(-1);
+        if (last?.root === root)
+            last.left.push(script);
+        else
+            scriptGroups.push({ root, left: [script] });
+    }
+    const nativeByRoot = new Map();
+    for (const item of native) {
+        const root = owner(item.path);
+        const scoped = nativeByRoot.get(root) ?? [];
+        scoped.push(item);
+        nativeByRoot.set(root, scoped);
+    }
+    const groups = scriptGroups.map(({ root, left }) => ({
+        left,
+        right: nativeByRoot.get(root) ?? [],
+    }));
+    return projectCartesianCandidates({
+        groups,
+        createCandidate: (source_path, item) => ({
+            source_path,
+            native_path: item.path,
+            basis: bridgeBasis(item.path),
         }),
-    };
+    });
 };
 const bridgeBasis = (path) => {
     const lower = path.toLowerCase();
@@ -264,6 +286,11 @@ const projectionLimitations = (facts) => [
             "AppleDouble sidecar entries (._* files and __MACOSX/) describe neighbouring files and are excluded from bundle roles.",
         ]
         : []),
+    ...(facts.bridgeCandidateCoverage.status === "partial"
+        ? [
+            `Bridge candidate pairs exceeded the projection safety budget; ${facts.bridgeCandidateCoverage.omitted_candidates} hypotheses are omitted. Component arrays still include every component from the supplied inventory pages.`,
+        ]
+        : []),
     "Bundle roles follow path conventions. Read each info_plist_path with inspect_plist for CFBundleExecutable, identifiers, and declared services.",
     "Bundle identifiers and signing claims require dedicated plist and CMS parsing; this projection reports only exact paths and hashes.",
     "Bridge candidates are path-based hypotheses, not observed runtime calls.",

package/dist/domain/apple/dyldEnvironment.js

@@ -0,0 +1,73 @@
+/** Retain recognized image-selection settings separately from diagnostic observations. */
+export const embeddedDyldOverrides = (environment, platforms) => {
+    const overrides = [];
+    for (const setting of environment) {
+        const delimiter = setting.indexOf("=");
+        if (delimiter <= 0)
+            continue;
+        const variable = setting.slice(0, delimiter);
+        const value = setting.slice(delimiter + 1);
+        const effect = overrideEffect(variable, value);
+        if (effect === undefined)
+            continue;
+        // ROOT_PATH is accepted only for simulator processes. Missing or unknown
+        // platform metadata cannot establish that dyld ignores it.
+        if (variable === "DYLD_ROOT_PATH" &&
+            platforms.length > 0 &&
+            platforms.every((platform) => platform >= 1 && platform <= 12) &&
+            !platforms.some((platform) => [7, 8, 9, 12].includes(platform)))
+            continue;
+        overrides.push({ variable, value, ...effect });
+    }
+    return overrides;
+};
+const overrideEffect = (variable, value) => {
+    switch (variable) {
+        // Empty directory components still produce /leaf candidates in dyld.
+        // In particular, an empty fallback value is not a no-op.
+        case "DYLD_LIBRARY_PATH":
+            return { phase: "override", scope: "library" };
+        case "DYLD_FRAMEWORK_PATH":
+            return { phase: "override", scope: "framework" };
+        case "DYLD_FALLBACK_LIBRARY_PATH":
+            return { phase: "fallback", scope: "library" };
+        case "DYLD_FALLBACK_FRAMEWORK_PATH":
+            return { phase: "fallback", scope: "framework" };
+        // Versioned paths map discovered images to their reported install names,
+        // so the directory's kind does not establish the replaced image's kind.
+        case "DYLD_VERSIONED_LIBRARY_PATH":
+        case "DYLD_VERSIONED_FRAMEWORK_PATH":
+        case "DYLD_IMAGE_SUFFIX":
+            // Versioned paths scan directories; suffixes create path variants.
+            // Empty directories cannot be scanned and empty suffixes repeat a path.
+            return /[^:]/u.test(value)
+                ? { phase: "override", scope: "all" }
+                : undefined;
+        case "DYLD_INSERT_LIBRARIES":
+            return value === "" ? undefined : { phase: "override", scope: "all" };
+        case "DYLD_ROOT_PATH":
+        case "DYLD_OVERLAY_PATH":
+            return value === "" ? undefined : { phase: "override", scope: "prefix" };
+        default:
+            return undefined;
+    }
+};
+const isFrameworkInstallName = (name, overrides) => {
+    const separator = name.lastIndexOf(".framework/");
+    if (separator < 0)
+        return false;
+    const framework = name.slice(0, separator).split("/").at(-1);
+    const leaf = name.slice(name.lastIndexOf("/") + 1);
+    return (leaf === framework ||
+        overrides.some(({ variable, value }) => variable === "DYLD_IMAGE_SUFFIX" && leaf === `${framework}${value}`));
+};
+/** Select only settings that can affect this dependency at its reached search phase. */
+export const hasApplicableDyldOverrides = (overrides, installName, ordinarySearchFoundImage) => {
+    const kind = isFrameworkInstallName(installName, overrides)
+        ? "framework"
+        : "library";
+    return overrides.some(({ phase, scope }) => (phase === "override" || !ordinarySearchFoundImage) &&
+        (scope === "all" ||
+            scope === kind ||
+            (scope === "prefix" && !installName.startsWith("@"))));
+};

package/dist/domain/apple/dylibResolution.js

@@ -1,6 +1,7 @@
 import { z } from "zod";
 import { compatibleSlice, directoryOf, expandPrefix, joinPath, resolveTreePath, } from "./dyldPaths.js";
 import { digestSchema } from "../digests.js";
+import { hasApplicableDyldOverrides, embeddedDyldOverrides, } from "./dyldEnvironment.js";
 import { DYLIB_RESOLUTION_LIMITATIONS, deriveFindings, } from "./dylibResolutionFindings.js";
 /** Normalized path below the analyzed root: no `.`/`..` or empty segments. */
 const ROOT_RELATIVE_PATH = /^(?!\/)(?!(?:.*\/)?\.{1,2}(?:\/|$))(?!.*\/\/)(?!.*\/$)[^\\\0]+$/u;
@@ -31,7 +32,20 @@ const dependencySchema = z.strictObject({
 /** Observed dylib-loading facts of one Mach-O slice. */
 export const machoSliceSchema = z.strictObject({
     architecture: z.string().min(1),
+    /** Physical identity observed in the thin header and, for FAT, its table. */
+    slice_offset: z.number().int().nonnegative(),
+    slice_size: z.number().int().positive(),
+    cpu_type: z.number().int().nonnegative(),
+    cpu_subtype: z.number().int().nonnegative(),
+    fat_cpu_type: z.number().int().nonnegative().nullable(),
+    fat_cpu_subtype: z.number().int().nonnegative().nullable(),
+    fat_alignment_exponent: z.number().int().nonnegative().nullable(),
     file_type: z.enum(["execute", "dylib", "bundle", "other"]),
+    file_type_code: z.number().int().nonnegative(),
+    /** Raw LC_BUILD_VERSION platform number; null means no such command was observed. */
+    platform: z.number().int().nonnegative().nullable(),
+    /** Every distinct build platform declared by LC_BUILD_VERSION/version-min commands. */
+    platforms: z.array(z.number().int().nonnegative()),
     install_name: z.string().nullable(),
     dependencies: z.array(dependencySchema),
     rpaths: z.array(z.string()),
@@ -56,6 +70,8 @@ const candidateSchema = z.strictObject({
         "malformed",
         "unsupported",
         "architecture-missing",
+        "not-loadable",
+        "platform-mismatch",
         "outside-target",
         "escapes-target",
         "undetermined",
@@ -168,13 +184,65 @@ const evaluateCandidate = async (template, context) => {
     if (lookup.kind !== "file")
         return { ...base, outcome: "absent", resolved_path: null };
     const facts = await imageFacts(context, lookup.path);
-    const outcome = facts.status !== "parsed"
-        ? facts.status
-        : compatibleSlice(facts.slices, context.architecture) === undefined
-            ? "architecture-missing"
-            : "resolved";
+    let outcome;
+    if (facts.status !== "parsed")
+        outcome = facts.status;
+    else {
+        const slice = compatibleSlice(facts.slices, context.architecture);
+        if (slice === undefined)
+            outcome = "architecture-missing";
+        // Dependency commands require a dylib; generic dyld image loadability
+        // also admits main executables and bundles for different operations.
+        else if (slice.file_type_code !== 6)
+            outcome = "not-loadable";
+        else {
+            const platformResult = platformLoadability(context.platforms, slice.platforms, slice.file_type_code, context.architecture);
+            outcome =
+                platformResult === "compatible"
+                    ? "resolved"
+                    : platformResult === "incompatible"
+                        ? "platform-mismatch"
+                        : "undetermined";
+        }
+    }
     return { ...base, outcome, resolved_path: lookup.path };
 };
+/** Apply dyld's documented cross-platform load cases and retain uncertain host cases. */
+const platformLoadability = (processPlatforms, imagePlatforms, fileType, architecture) => {
+    if (processPlatforms.length === 0 || imagePlatforms.length === 0)
+        return "unknown";
+    const outcomes = processPlatforms.map((processPlatform) => imageLoadabilityForPlatform(processPlatform, imagePlatforms, fileType, architecture));
+    if (outcomes.every((outcome) => outcome === "compatible"))
+        return "compatible";
+    if (outcomes.every((outcome) => outcome === "incompatible"))
+        return "incompatible";
+    return "unknown";
+};
+const imageLoadabilityForPlatform = (processPlatform, imagePlatforms, fileType, architecture) => {
+    if (imagePlatforms.includes(processPlatform))
+        return "compatible";
+    // These are explicit dyld loadableIntoProcess cross-platform cases.
+    if (processPlatform === 6 && imagePlatforms.includes(1))
+        return "compatible"; // macOS dylibs in Mac Catalyst processes
+    if (processPlatform === 2 && imagePlatforms.includes(6))
+        return "compatible"; // Catalyst dylibs in iOS processes
+    if (processPlatform === 2 && imagePlatforms.includes(11))
+        return "compatible"; // visionOS dylibs in iOS processes
+    if (processPlatform === 7 && imagePlatforms.includes(12))
+        return "compatible"; // visionOS simulator dylibs in iOS simulator processes
+    if (processPlatform === 1 && fileType === 2 && imagePlatforms.includes(6))
+        return "compatible"; // Catalyst main executables run on macOS
+    // dyld's remaining exceptions depend on host architecture or a special path.
+    if ((processPlatform === 2 &&
+        imagePlatforms.includes(1) &&
+        architecture.startsWith("arm64")) ||
+        ([7, 8, 9].includes(processPlatform) && imagePlatforms.includes(1)))
+        return "unknown";
+    if (isKnownPlatform(processPlatform) && imagePlatforms.every(isKnownPlatform))
+        return "incompatible";
+    return "unknown";
+};
+const isKnownPlatform = (platform) => platform >= 1 && platform <= 12;
 const imageFacts = async (context, path) => {
     const known = context.images.get(path);
     if (known !== undefined)
@@ -222,7 +290,19 @@ const resolveDependency = async (dependency, loader, context) => {
             if (candidate.outcome === "resolved")
                 break;
         }
-    const searched = resolution(candidates);
+    const modeled = resolution(candidates);
+    const searchUnknown = loaded === undefined &&
+        hasApplicableDyldOverrides(context.searchOverrides, dependency.install_name, modeled.image !== null);
+    if (searchUnknown)
+        context.environmentRoots.add(context.root);
+    // Fallbacks cannot preempt a modeled hit, and framework paths do not
+    // override ordinary dylibs. Reuse inherits uncertainty from the first load.
+    const searched = searchUnknown
+        ? {
+            ...modeled,
+            status: modeled.image === null ? "undetermined" : "conditional",
+        }
+        : modeled;
     // Reusing an image that itself loads only conditionally is conditional too.
     const resolved = loaded !== undefined &&
         context.loaded.get(loaded)?.conditional === true &&
@@ -306,6 +386,7 @@ export const traceDylibLoading = async (view, request) => {
     const roots = [];
     const edges = [];
     const withoutArchitecture = [];
+    const environmentRoots = new Set();
     for (const root of request.roots) {
         const facts = await view.image(root);
         images.set(root, facts);
@@ -316,12 +397,23 @@ export const traceDylibLoading = async (view, request) => {
         if (slices.length === 0)
             withoutArchitecture.push(root);
         for (const slice of slices) {
+            const executable = slice.file_type === "execute" ? root : null;
+            // Only the main executable supplies the process's embedded environment.
+            const searchOverrides = executable === null
+                ? []
+                : embeddedDyldOverrides(slice.dyld_environment, slice.platforms);
+            // Inserted libraries introduce unexamined images even without dependencies.
+            if (searchOverrides.some(({ variable, value }) => variable === "DYLD_INSERT_LIBRARIES" && value !== ""))
+                environmentRoots.add(root);
             roots.push({ image: root, architecture: slice.architecture });
             edges.push(...(await traceProcess({
                 view,
                 root,
                 architecture: slice.architecture,
-                executable: slice.file_type === "execute" ? root : null,
+                searchOverrides,
+                environmentRoots,
+                platforms: slice.platforms,
+                executable,
                 loaded: new Map(),
                 byInstallName: new Map(),
                 images,
@@ -347,18 +439,37 @@ export const traceDylibLoading = async (view, request) => {
         edges,
         findings: deriveFindings(edges, roots, images),
         coverage: {
-            status: unparsed.length === 0 && withoutArchitecture.length === 0
+            status: unparsed.length === 0 &&
+                withoutArchitecture.length === 0 &&
+                environmentRoots.size === 0
                 ? "complete"
                 : "partial",
             unparsed_images: unparsed,
             roots_without_architecture: withoutArchitecture,
         },
-        limitations: DYLIB_RESOLUTION_LIMITATIONS,
+        limitations: [
+            ...DYLIB_RESOLUTION_LIMITATIONS,
+            ...(environmentRoots.size === 0
+                ? []
+                : [
+                    `Roots ${[...environmentRoots].join(", ")} request applicable image-selection inputs through LC_DYLD_ENVIRONMENT that are not modeled; affected dependencies or inserted images remain uncertain.`,
+                ]),
+        ],
     };
 };
 const withoutDependencies = (slice) => ({
     architecture: slice.architecture,
+    slice_offset: slice.slice_offset,
+    slice_size: slice.slice_size,
+    cpu_type: slice.cpu_type,
+    cpu_subtype: slice.cpu_subtype,
+    fat_cpu_type: slice.fat_cpu_type,
+    fat_cpu_subtype: slice.fat_cpu_subtype,
+    fat_alignment_exponent: slice.fat_alignment_exponent,
     file_type: slice.file_type,
+    file_type_code: slice.file_type_code,
+    platform: slice.platform,
+    platforms: slice.platforms,
     install_name: slice.install_name,
     rpaths: slice.rpaths,
     dyld_environment: slice.dyld_environment,

package/dist/domain/apple/dylibResolutionFindings.js

@@ -14,22 +14,24 @@ export const deriveFindings = (edges, roots, images) => {
                 edge_index: index,
                 image: edge.loader,
                 basis: "derived",
-                explanation: `dyld searches ${earlier.join(", ")} before ${edge.resolution.image ?? edge.install_name}. A Mach-O placed at an earlier path would load first unless code-signing library validation rejects it; library validation is not evaluated here (see inspect_signature).`,
+                explanation: `The modeled dyld search checks ${earlier.join(", ")} before ${edge.resolution.image ?? edge.install_name}. A compatible Mach-O placed at an earlier modeled path could take precedence over that fallback, subject to unmodeled search inputs and code-signing library validation; library validation is not evaluated here (see inspect_signature).${edge.loader_conditional ? " This loader loads only conditionally; if it never loads, this search never occurs." : ""}${edge.resolution.status === "conditional" ? " Unmodeled environment overrides or earlier unknown candidates may take precedence; placing an image at this rpath does not establish which image dyld will load." : ""}`,
             });
     });
     for (const { image, architecture } of roots) {
         const facts = images.get(image);
-        const environment = facts?.status === "parsed"
-            ? (facts.slices.find((slice) => slice.architecture === architecture)
-                ?.dyld_environment ?? [])
-            : [];
+        const slice = facts?.status === "parsed"
+            ? facts.slices.find((candidate) => candidate.architecture === architecture)
+            : undefined;
+        const environment = slice?.dyld_environment ?? [];
         if (environment.length > 0)
             findings.push({
                 kind: "dyld-environment-present",
                 edge_index: null,
                 image,
                 basis: "derived",
-                explanation: `${image} (${architecture}) sets dyld environment variables through LC_DYLD_ENVIRONMENT (${environment.join(", ")}); search paths they add are not modeled.`,
+                explanation: slice?.file_type === "execute"
+                    ? `${image} (${architecture}) sets dyld environment variables through LC_DYLD_ENVIRONMENT (${environment.join(", ")}); any image-selection overrides they request are not modeled. Diagnostic settings alone do not alter resolution.`
+                    : `${image} (${architecture}) contains LC_DYLD_ENVIRONMENT (${environment.join(", ")}). Dyld reads these commands only from the main executable; entries in this non-executable root are observations and do not alter resolution.`,
             });
     }
     return findings;
@@ -60,7 +62,7 @@ const unresolvedFinding = (edge, index) => {
         : {
             ...base,
             kind: "required-load-unresolved",
-            explanation: `${missing}${when}dyld would fail to launch ${edge.root} (${edge.architecture}) unless the image is supplied elsewhere.`,
+            explanation: `${missing}${when}dyld would fail to load this required dependency for ${edge.root} (${edge.architecture}) unless the image is supplied elsewhere.`,
         };
 };
 export const DYLIB_RESOLUTION_LIMITATIONS = [

package/dist/domain/apple/interfaceBuilderGraph.js

@@ -28,6 +28,7 @@ export const buildInterfaceBuilderAnalysis = (input) => {
     let omittedObjects = 0;
     let omittedConnections = 0;
     let omittedGraphNodes = 0;
+    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}:`;
@@ -276,6 +277,8 @@ export const buildInterfaceBuilderAnalysis = (input) => {
             }
         }
         const objectsTruncated = parsed.omittedObjects > 0 || parsed.objects.length > documentObjectCount;
+        const parserOmittedHierarchyReferences = parsed.omittedHierarchyReferences;
+        omittedHierarchyReferences += parserOmittedHierarchyReferences;
         const parserOmittedConnections = parsed.omittedConnections;
         const connectionsTruncated = parserOmittedConnections > 0 ||
             parsed.connections.length > input.limits.max_connections;
@@ -291,7 +294,9 @@ export const buildInterfaceBuilderAnalysis = (input) => {
             document_kind: document.documentKind,
             object_count: parsed.objectCount,
             connection_count: parsed.connections.length + parserOmittedConnections,
-            hierarchy_complete: parsed.hierarchy.length > 0 && !truncated,
+            hierarchy_complete: parsed.hierarchy.length > 0 &&
+                !truncated &&
+                parserOmittedHierarchyReferences === 0,
         });
         coverage.push({
             facet: `objects:${document.relativePath}`,
@@ -314,18 +319,22 @@ export const buildInterfaceBuilderAnalysis = (input) => {
                 parserOmittedConnections,
         }, {
             facet: `hierarchy:${document.relativePath}`,
-            status: parsed.hierarchy.length === 0
-                ? "unsupported"
-                : hierarchyTruncated || documentOmittedHierarchyEdges > 0
-                    ? "partial"
-                    : "complete",
-            reason: parsed.hierarchy.length === 0
-                ? "archive_hierarchy_not_decoded"
-                : hierarchyTruncated || documentOmittedHierarchyEdges > 0
-                    ? "graph_limit_reached"
-                    : null,
+            status: parserOmittedHierarchyReferences > 0
+                ? "partial"
+                : parsed.hierarchy.length === 0
+                    ? "unsupported"
+                    : hierarchyTruncated || documentOmittedHierarchyEdges > 0
+                        ? "partial"
+                        : "complete",
+            reason: parserOmittedHierarchyReferences > 0
+                ? "archive_hierarchy_references_missing"
+                : parsed.hierarchy.length === 0
+                    ? "archive_hierarchy_not_decoded"
+                    : hierarchyTruncated || documentOmittedHierarchyEdges > 0
+                        ? "graph_limit_reached"
+                        : null,
             examined: hierarchyCount,
-            omitted: documentOmittedHierarchyEdges,
+            omitted: documentOmittedHierarchyEdges + parserOmittedHierarchyReferences,
         }, {
             facet: `classes:${document.relativePath}`,
             status: Object.keys(parsed.classes).length > 0 ? "complete" : "unsupported",
@@ -367,7 +376,10 @@ export const buildInterfaceBuilderAnalysis = (input) => {
             nodes: [...nodes.values()],
             edges,
             coverage,
-            truncated: truncated || omittedObjects > 0 || omittedConnections > 0,
+            truncated: truncated ||
+                omittedObjects > 0 ||
+                omittedConnections > 0 ||
+                omittedHierarchyReferences > 0,
         },
         limitations: [
             "The graph reflects recognized Interface Builder archive fields and connections; omitted private or unrecognized archive fields remain unknown.",

package/dist/domain/apple/interfaceBuilderKeyedArchive.js

@@ -82,6 +82,7 @@ export const parseInterfaceBuilderRecords = (value) => {
         objectCount: objectEntries.length,
         omittedObjects: Math.max(0, objectEntries.length - 20_000),
         omittedConnections,
+        omittedHierarchyReferences: 0,
     };
 };
 /**
@@ -164,6 +165,7 @@ const keyedArchiveTable = (objectTable) => {
         return output;
     };
     const hierarchy = (start) => {
+        let omittedReferences = 0;
         const visited = new Set();
         const root = [];
         const pending = [
@@ -190,10 +192,17 @@ const keyedArchiveTable = (objectTable) => {
             const { value, output } = entry;
             const uid = archiveUid(value);
             if (uid !== undefined) {
+                // UID0 is archived nil, not a missing hierarchy object.
+                if (uid === 0)
+                    continue;
+                const target = objectTable[uid];
+                if (target === undefined) {
+                    omittedReferences += 1;
+                    continue;
+                }
                 if (visited.has(uid))
                     continue;
                 visited.add(uid);
-                const target = objectTable[uid];
                 if (Array.isArray(target)) {
                     for (let index = target.length - 1; index >= 0; index -= 1) {
                         const child = target[index];
@@ -229,7 +238,7 @@ const keyedArchiveTable = (objectTable) => {
                 appendNode(record(value), undefined, output);
             }
         }
-        return root;
+        return { items: root, omittedReferences };
     };
     const archivedArrayClass = (classReference) => {
         const uid = archiveUid(classReference);
@@ -317,11 +326,12 @@ const parseKeyedArchive = (root) => {
     return {
         objects,
         connections,
-        hierarchy,
+        hierarchy: hierarchy.items,
         classes,
         objectCount,
         omittedObjects: Math.max(0, objectCount - 20_000),
         omittedConnections,
+        omittedHierarchyReferences: hierarchy.omittedReferences,
     };
 };
 /** Coerce unknown values to a string-keyed record; non-objects become `{}`. */

package/dist/domain/apple/keyedArchive.js

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { AnalysisInputError } from "../analysisErrorCore.js";
 import { jsonValueSchema } from "../jsonValue.js";
 /** Select one archive within the active bundle and optionally one named root. */
 export const keyedArchiveInputSchema = z.strictObject({
@@ -72,7 +73,14 @@ export const projectKeyedArchive = (value, selection) => {
     if (top === undefined || Object.keys(top).length === 0)
         throw new TypeError("Keyed archive has no $top roots");
     if (selection.root !== undefined && !Object.hasOwn(top, selection.root))
-        throw new TypeError(`Archive root does not exist: ${selection.root}`);
+        throw new AnalysisInputError("inspect_keyed_archive", undefined, [
+            {
+                path: ["root"],
+                reason: "invalid_value",
+                message: `Archive root does not exist: ${selection.root}. Select one of the archive's $top roots or omit root.`,
+                expected: Object.keys(top),
+            },
+        ]);
     const roots = selection.root === undefined
         ? top
         : { [selection.root]: top[selection.root] ?? null };

package/dist/domain/apple/machoContainer.js

@@ -0,0 +1,54 @@
+/** Decode FAT table entries once so artifact and native readers share identity facts. */
+export const readFatSliceDeclarations = (tableBytes, options) => {
+    const { count, wide, littleEndian } = options;
+    const entrySize = wide ? 32 : 20;
+    if (tableBytes.byteLength < count * entrySize)
+        return { status: "malformed", reason: "FAT table is truncated" };
+    const view = new DataView(tableBytes.buffer, tableBytes.byteOffset, tableBytes.byteLength);
+    const slices = [];
+    for (let index = 0; index < count; index++) {
+        const base = index * entrySize;
+        const offset = wide
+            ? safeNumber(view.getBigUint64(base + 8, littleEndian))
+            : view.getUint32(base + 8, littleEndian);
+        const size = wide
+            ? safeNumber(view.getBigUint64(base + 16, littleEndian))
+            : view.getUint32(base + 12, littleEndian);
+        if (offset === null || size === null)
+            return {
+                status: "malformed",
+                reason: "FAT offset or size exceeds the safe range",
+            };
+        slices.push({
+            index,
+            offset,
+            size,
+            alignmentExponent: view.getUint32(base + (wide ? 24 : 16), littleEndian),
+            cpuType: view.getUint32(base, littleEndian),
+            cpuSubtype: view.getUint32(base + 4, littleEndian),
+        });
+    }
+    return { status: "parsed", slices };
+};
+/** 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;
+    if (!Number.isSafeInteger(offset) ||
+        !Number.isSafeInteger(size) ||
+        size <= 0 ||
+        offset < tableEnd)
+        return `FAT architecture ${index} has an invalid slice range`;
+    if (offset > containerSize || size > containerSize - offset)
+        return `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`;
+    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 null;
+};
+const safeNumber = (value) => value > BigInt(Number.MAX_SAFE_INTEGER) ? null : Number(value);