rea-agents 6.3.0 → 6.5.0

package/dist/artifacts/apple/InterfaceBuilderAnalysis.js

@@ -1,14 +1,18 @@
 import { createHash } from "node:crypto";
 import { parseBinary } from "plist";
+import { appleResourceKeyFields } from "../../domain/apple/appleAssetCatalog.js";
+import { interfaceBuilderConnectionFieldNames, isUIKitRuntimeConnectionClass, } from "../../domain/apple/interfaceBuilderKeyedArchive.js";
 import { DirectoryArtifactReader } from "../DirectoryArtifactReader.js";
 import { projectPlistValue } from "../../domain/apple/plistValue.js";
 import { omittedPrototypeKeysLimitation, parseXmlPropertyList, } from "../../domain/propertyListKeys.js";
 import { decodeNibArchive } from "./NibArchive.js";
-import { estimatePropertyListDecodeBytes, InterfaceBuilderDecodeBudget, InterfaceBuilderDecodeBudgetExceeded, } from "./InterfaceBuilderDecodeBudget.js";
+import { preflightPropertyListDecode, InterfaceBuilderDecodeBudget, InterfaceBuilderDecodeBudgetExceeded, } from "./InterfaceBuilderDecodeBudget.js";
 import { buildInterfaceBuilderAnalysis, interfaceBuilderLimitsSchema, } from "../../domain/apple/interfaceBuilderGraph.js";
 import { mergeNibHierarchies, projectNibViewHierarchy, } from "./NibViewHierarchy.js";
 import { jsonValueSchema } from "../../domain/jsonValue.js";
+import { compareUnicodeCodePoints } from "../../domain/unicodeCodePointOrder.js";
 import { decodeXmlPlistText } from "../../domain/propertyListXmlText.js";
+import { hasBinaryPlistSignature, hasNibArchiveSignature, } from "../../domain/apple/appleArchiveFormat.js";
 const MAX_AGGREGATE_INPUT_BYTES = 32 * 1024 * 1024;
 const MAX_AGGREGATE_DECODE_BYTES = 256 * 1024 * 1024;
 const MAX_REPORTED_OMITTED_ARCHIVES = 64;
@@ -21,10 +25,10 @@ export const analyzeInterfaceBuilderBundle = async (input) => {
     const omittedArchives = [];
     let unreportedOmittedArchives = 0;
     const incompleteHierarchies = new Map();
+    const unresolvedConnections = new Map();
     const prototypeKeyOmissions = new Map();
     let omitted = 0;
     let attempted = 0;
-    let candidates = 0;
     let aggregateInputBytes = 0;
     const decodeBudget = new InterfaceBuilderDecodeBudget(MAX_AGGREGATE_DECODE_BYTES);
     const recordOmittedArchive = (path, reason) => {
@@ -34,15 +38,12 @@ export const analyzeInterfaceBuilderBundle = async (input) => {
             unreportedOmittedArchives += 1;
     };
     try {
-        for await (const entry of reader.entries(input.signal)) {
-            if (entry.kind !== "file" || !isInterfaceBuilderArchive(entry.path))
-                continue;
-            candidates += 1;
-            if (candidates > limits.max_documents) {
-                omitted += 1;
-                recordOmittedArchive(entry.path, "max_documents");
-                continue;
-            }
+        const selection = await selectInterfaceBuilderCandidates(reader, input.signal, limits.max_documents);
+        omitted = selection.omitted;
+        for (const entry of selection.omittedSamples)
+            recordOmittedArchive(entry.path, "max_documents");
+        unreportedOmittedArchives += selection.unreportedOmitted;
+        for (const entry of selection.selected) {
             try {
                 const remainingInputBytes = MAX_AGGREGATE_INPUT_BYTES - aggregateInputBytes;
                 if (entry.declaredSize !== null &&
@@ -54,26 +55,31 @@ export const analyzeInterfaceBuilderBundle = async (input) => {
                 attempted += 1;
                 const bytes = await readEntry(reader, entry, input.signal, remainingInputBytes);
                 aggregateInputBytes += bytes.length;
-                const isNibArchive = bytes.subarray(0, 10).toString("ascii") === "NIBArchive";
+                const isNibArchive = hasNibArchiveSignature(bytes);
                 let nib = null;
                 let xmlText;
+                let binaryPrototypeKeyObserved = false;
                 if (isNibArchive) {
                     const documentBudget = new InterfaceBuilderDecodeBudget(decodeBudget.remainingBytes);
                     nib = projectNibArchive(decodeNibArchive(bytes, documentBudget), documentBudget, limits.max_objects);
                     decodeBudget.reserve(documentBudget.usedBytes, "NIBArchive representation exceeds the aggregate Interface Builder decode budget");
                 }
                 else {
-                    if (bytes.subarray(0, 8).toString("ascii") !== "bplist00")
+                    if (!hasBinaryPlistSignature(bytes))
                         xmlText = decodeXmlPlistText(bytes);
-                    const decodedReservation = estimatePropertyListDecodeBytes(bytes, decodeBudget.remainingBytes, xmlText);
-                    decodeBudget.reserve(decodedReservation, "plist representation exceeds the aggregate Interface Builder decode budget");
+                    const decodedReservation = preflightPropertyListDecode(bytes, decodeBudget.remainingBytes, xmlText);
+                    decodeBudget.reserve(decodedReservation.estimatedBytes, "plist representation exceeds the aggregate Interface Builder decode budget");
+                    binaryPrototypeKeyObserved =
+                        decodedReservation.binaryPrototypeKeyObserved;
                 }
                 const { value: raw, omittedPrototypeKeys } = nib === null
-                    ? decodePlist(bytes, xmlText)
+                    ? decodePlist(bytes, xmlText, binaryPrototypeKeyObserved)
                     : { value: nib.raw, omittedPrototypeKeys: 0 };
                 if (nib !== null && nib.omitted > 0)
                     incompleteHierarchies.set(entry.path, nib.omitted);
-                if (omittedPrototypeKeys > 0)
+                if (nib !== null && nib.unresolvedConnections > 0)
+                    unresolvedConnections.set(entry.path, nib.unresolvedConnections);
+                if (omittedPrototypeKeys !== 0)
                     prototypeKeyOmissions.set(entry.path, omittedPrototypeKeys);
                 const documentHash = createHash("sha256").update(bytes).digest("hex");
                 documents.push({
@@ -83,6 +89,9 @@ export const analyzeInterfaceBuilderBundle = async (input) => {
                         ? "storyboard_scene"
                         : "nib",
                     raw,
+                    ...(nib === null || nib.omitted === 0
+                        ? {}
+                        : { omittedSerializedHierarchyReferences: nib.omitted }),
                 });
             }
             catch (cause) {
@@ -108,6 +117,7 @@ export const analyzeInterfaceBuilderBundle = async (input) => {
     });
     return finalizeHierarchyCoverage(result, {
         incompleteHierarchies,
+        unresolvedConnections,
         prototypeKeyOmissions,
         invalid,
         omittedArchives,
@@ -116,8 +126,44 @@ export const analyzeInterfaceBuilderBundle = async (input) => {
         omitted,
     });
 };
+/** Select lexically earliest document paths independent of host traversal order. */
+const selectInterfaceBuilderCandidates = async (reader, signal, maximumDocuments) => {
+    const capacity = maximumDocuments + MAX_REPORTED_OMITTED_ARCHIVES;
+    const candidates = [];
+    let total = 0;
+    for await (const entry of reader.entries(signal)) {
+        if (entry.kind !== "file" || !isInterfaceBuilderArchive(entry.path))
+            continue;
+        total += 1;
+        retainCandidate(candidates, entry, capacity);
+    }
+    const omittedSamples = candidates.slice(maximumDocuments, capacity);
+    return {
+        selected: candidates.slice(0, maximumDocuments),
+        omittedSamples,
+        omitted: Math.max(0, total - maximumDocuments),
+        unreportedOmitted: Math.max(0, total - maximumDocuments - omittedSamples.length),
+    };
+};
+/** Keep the earliest bounded path set; directory iteration order is host-defined. */
+const retainCandidate = (candidates, entry, maximum) => {
+    let low = 0;
+    let high = candidates.length;
+    while (low < high) {
+        const middle = Math.floor((low + high) / 2);
+        const existing = candidates[middle];
+        if (existing !== undefined &&
+            compareUnicodeCodePoints(existing.path, entry.path) < 0)
+            low = middle + 1;
+        else
+            high = middle;
+    }
+    candidates.splice(low, 0, entry);
+    if (candidates.length > maximum)
+        candidates.pop();
+};
 const finalizeHierarchyCoverage = (result, counts) => {
-    const { incompleteHierarchies, prototypeKeyOmissions, invalid, omittedArchives, unreportedOmittedArchives, } = counts;
+    const { incompleteHierarchies, unresolvedConnections, prototypeKeyOmissions, invalid, omittedArchives, unreportedOmittedArchives, } = counts;
     const archiveDecodePartial = invalid.length > 0 ||
         prototypeKeyOmissions.size > 0 ||
         omittedArchives.length > 0;
@@ -125,20 +171,24 @@ const finalizeHierarchyCoverage = (result, counts) => {
         ...result,
         documents: result.documents.map((document) => ({
             ...document,
-            hierarchy_complete: document.hierarchy_complete &&
-                !incompleteHierarchies.has(document.relative_path),
+            connection_count: document.connection_count +
+                (unresolvedConnections.get(document.relative_path) ?? 0),
         })),
         graph: {
             ...result.graph,
             coverage: [
                 ...result.graph.coverage.map((facet) => {
-                    const omitted = incompleteHierarchies.get(facet.facet.replace(/^hierarchy:/u, ""));
-                    return facet.facet.startsWith("hierarchy:") && omitted !== undefined
+                    const omittedConnection = unresolvedConnections.get(facet.facet.replace(/^connections:/u, ""));
+                    return facet.facet.startsWith("connections:") &&
+                        omittedConnection !== undefined
                         ? {
                             ...facet,
                             status: "partial",
-                            reason: "serialized_view_hierarchy_incomplete",
-                            omitted: facet.omitted + omitted,
+                            // A connection dropped by the limit is recoverable by raising
+                            // it, so that cause keeps the reason the graph already named.
+                            // Only a facet with no other cause reports the omission.
+                            reason: facet.reason ?? "connection_unresolved",
+                            omitted: facet.omitted + omittedConnection,
                         }
                         : facet;
                 }),
@@ -165,7 +215,7 @@ const finalizeHierarchyCoverage = (result, counts) => {
             truncated: result.graph.truncated ||
                 counts.omitted > 0 ||
                 archiveDecodePartial ||
-                incompleteHierarchies.size > 0,
+                unresolvedConnections.size > 0,
         },
         limitations: [
             ...result.limitations,
@@ -175,6 +225,11 @@ const finalizeHierarchyCoverage = (result, counts) => {
                 : [
                     "Some serialized hierarchy links could not be projected within the bounded hierarchy; their parentage remains unknown.",
                 ]),
+            ...(unresolvedConnections.size === 0
+                ? []
+                : [
+                    "Some recognized NIBArchive connectors declare no resolvable owner; they carry no connection evidence and are reported as omissions.",
+                ]),
             ...(invalid.length === 0
                 ? []
                 : [
@@ -284,7 +339,7 @@ const projectNibArchive = (archive, budget, maxHierarchyNodes) => {
     const objects = Object.fromEntries(archive.objects
         .filter((object) => {
         const name = runtimeClass(object.id) ?? "";
-        return !/^(?:NSObject|NSIBObjectData|NSString|NSMutableString|NSNumber|NSArray|NSMutableArray|NSSet|NSMutableSet|NSDictionary|NSMutableDictionary|NSApplication|NSNib.*Connector|UIRuntime\w*Connection)$/u.test(name);
+        return (!/^(?:NSObject|NSIBObjectData|NSString|NSMutableString|NSNumber|NSArray|NSMutableArray|NSSet|NSMutableSet|NSDictionary|NSMutableDictionary|NSApplication|NSNib.*Connector)$/u.test(name) && !isUIKitRuntimeConnectionClass(name));
     })
         .map((object) => {
         const className = runtimeClass(object.id) ?? normalizeClassName(object.class_name);
@@ -300,21 +355,34 @@ const projectNibArchive = (archive, budget, maxHierarchyNodes) => {
             break;
         }
         budget.reserveJsonStringOccurrence(name);
+        const nibValues = Object.fromEntries(Object.entries(object.values).map(([key, value]) => {
+            budget.reserveJsonPropertyNameOccurrence(key);
+            return [key, dereference(value) ?? null];
+        }));
+        // Normalize only recognized scalar fields at the format owner. A keyed
+        // archive's authored nibValues dictionary must not gain this meaning.
+        const resourceFields = appleResourceKeyFields(nibValues);
+        for (const [field, value] of resourceFields) {
+            budget.reserveJsonPropertyNameOccurrence(field);
+            budget.reserveJsonStringOccurrence(value);
+        }
         return [
             String(object.id),
             {
                 customClass: className,
                 label: name,
                 objectID: String(object.id),
-                nibValues: Object.fromEntries(Object.entries(object.values).map(([key, value]) => {
-                    budget.reserveJsonPropertyNameOccurrence(key);
-                    return [key, dereference(value) ?? null];
-                })),
+                nibValues,
+                ...Object.fromEntries(resourceFields),
             },
         ];
     }));
     const connections = {};
     const hierarchy = [];
+    // A recognized connector whose owner reference cannot be resolved produces no
+    // connection entry, so the omission has to be counted here: the projected
+    // dictionary carries no trace of it for a downstream consumer to find.
+    let unresolvedConnections = 0;
     const reference = (value) => {
         if (typeof value !== "object" || value === null || Array.isArray(value))
             return null;
@@ -326,15 +394,18 @@ const projectNibArchive = (archive, budget, maxHierarchyNodes) => {
         const className = normalizeClassName(object.class_name);
         // AppKit connectors use NS-prefixed keys; UIKit's runtime outlet and
         // event connections use UI-prefixed keys with the same roles.
-        const uiKit = /^UIRuntime\w*Connection$/u.test(className);
+        const uiKit = isUIKitRuntimeConnectionClass(className);
         if (!uiKit && !className.includes("Connector"))
             continue;
         const values = object.values;
-        const source = reference(uiKit ? values.UISource : values.NSSource);
-        if (source === null)
+        const connectionFields = interfaceBuilderConnectionFieldNames(className);
+        const source = reference(values[connectionFields.source]);
+        if (source === null) {
+            unresolvedConnections += 1;
             continue;
-        const destination = reference(uiKit ? values.UIDestination : values.NSDestination);
-        const label = referencedString(uiKit ? values.UILabel : values.NSLabel);
+        }
+        const destination = reference(values[connectionFields.destination]);
+        const label = referencedString(values[connectionFields.label]);
         const type = className.includes("Outlet")
             ? "outlet"
             : className.includes("Control") || className.includes("Event")
@@ -416,6 +487,7 @@ const projectNibArchive = (archive, budget, maxHierarchyNodes) => {
     const merged = mergeNibHierarchies(hierarchy, viewHierarchy.hierarchy ?? [], () => budget.tryReserve(96), maxHierarchyNodes);
     return {
         omitted: viewHierarchy.omitted + hierarchyOmitted + merged.omitted,
+        unresolvedConnections,
         raw: jsonValueSchema.parse({
             "com.apple.ibtool.document.objects": objects,
             "com.apple.ibtool.document.connections": connections,
@@ -452,9 +524,13 @@ const readEntry = async (reader, entry, signal, maxInputBytes = MAX_AGGREGATE_IN
     return Buffer.concat(chunks, length);
 };
 /** Project decoded plist data and dates while retaining omitted-key coverage. */
-const decodePlist = (bytes, xmlText) => {
-    const { value, omittedPrototypeKeys } = bytes.subarray(0, 8).toString("ascii") === "bplist00"
-        ? { value: parseBinary(bytes), omittedPrototypeKeys: 0 }
+const decodePlist = (bytes, xmlText, binaryPrototypeKeyObserved) => {
+    const binary = hasBinaryPlistSignature(bytes);
+    const { value, omittedPrototypeKeys } = binary
+        ? {
+            value: parseBinary(bytes),
+            omittedPrototypeKeys: binaryPrototypeKeyObserved ? null : 0,
+        }
         : parseXmlPropertyList(xmlText ?? decodeXmlPlistText(bytes));
     return { value: projectPlistValue(value).value, omittedPrototypeKeys };
 };

package/dist/artifacts/apple/InterfaceBuilderDecodeBudget.js

@@ -1,4 +1,5 @@
 import { decodeXmlPlistText } from "../../domain/propertyListXmlText.js";
+import { hasBinaryPlistSignature } from "../../domain/apple/appleArchiveFormat.js";
 /** A named resource-limit failure that keeps budget exhaustion out of decode errors. */
 export class InterfaceBuilderDecodeBudgetExceeded extends Error {
     reason;
@@ -58,33 +59,34 @@ export class InterfaceBuilderDecodeBudget {
     }
 }
 /** Preflight the representation created by the pinned plist decoder. */
-export const estimatePropertyListDecodeBytes = (bytes, maxBytes, xmlText) => {
-    const estimate = bytes.subarray(0, 8).toString("ascii") === "bplist00"
+export const preflightPropertyListDecode = (bytes, maxBytes, xmlText) => {
+    const expansion = hasBinaryPlistSignature(bytes)
         ? estimateBinaryPlistExpansion(bytes, maxBytes)
-        : estimateXmlPlistExpansion(bytes, maxBytes, xmlText);
-    if (estimate > maxBytes)
+        : {
+            estimatedBytes: estimateXmlPlistExpansion(bytes, maxBytes, xmlText),
+            binaryPrototypeKeyObserved: false,
+        };
+    if (expansion.estimatedBytes > maxBytes)
         throw new InterfaceBuilderDecodeBudgetExceeded("aggregate_decode_budget_exhausted", "plist representation exceeds the aggregate Interface Builder decode budget");
-    return estimate;
+    return expansion;
 };
 const estimateXmlPlistExpansion = (bytes, maxBytes, xmlText) => {
     const xml = xmlText ?? decodeXmlPlistText(bytes);
-    if (/<!DOCTYPE\b[^>]*\[/iu.test(xml))
-        throw new InterfaceBuilderDecodeBudgetExceeded("aggregate_decode_budget_exhausted", "XML plist internal entity expansion exceeds the aggregate Interface Builder decode budget");
-    const elementPattern = /<!--[^]*?-->|<!\[CDATA\[[^]*?\]\]>|<!DOCTYPE[^>]*>|<\?[^]*?\?>|<\/?[A-Za-z][^>]*>/giu;
     const decodedSourceBytes = xml.length * 2;
     let elementCount = 0;
     let xmlDepth = 0;
-    for (const match of xml.matchAll(elementPattern)) {
-        const token = match[0] ?? "";
-        if (token.startsWith("<!--") ||
-            token.startsWith("<![CDATA[") ||
-            token.startsWith("<!DOCTYPE") ||
-            token.startsWith("<?"))
+    for (const token of xmlPreflightTokens(xml)) {
+        if (token.doctype) {
+            // Only a declaration outside opaque text can introduce an internal
+            // subset. Brackets in quoted external identifiers are literal text.
+            if (token.internalSubset)
+                throw new InterfaceBuilderDecodeBudgetExceeded("aggregate_decode_budget_exhausted", "XML plist internal entity expansion exceeds the aggregate Interface Builder decode budget");
             continue;
+        }
         elementCount += 1;
-        if (token.startsWith("</"))
+        if (token.closing)
             xmlDepth -= 1;
-        else if (!token.endsWith("/>")) {
+        else if (!token.selfClosing) {
             xmlDepth += 1;
             if (xmlDepth > 128)
                 throw new InterfaceBuilderDecodeBudgetExceeded("aggregate_decode_budget_exhausted", "XML plist nesting exceeds the aggregate Interface Builder decode budget");
@@ -94,8 +96,65 @@ const estimateXmlPlistExpansion = (bytes, maxBytes, xmlText) => {
     }
     return decodedSourceBytes * 2 + elementCount * 128;
 };
-/** Count every expanded binary-plist reference before calling plist.parseBinary. */
-const estimateBinaryPlistExpansion = (bytes, maxBytes) => {
+/** Consume each XML span once; malformed tokens cannot restart suffix scans. */
+function* xmlPreflightTokens(xml) {
+    let cursor = 0;
+    while (cursor < xml.length) {
+        const start = xml.indexOf("<", cursor);
+        if (start < 0)
+            return;
+        const opaqueEnd = xml.startsWith("<!--", start)
+            ? "-->"
+            : xml.startsWith("<![CDATA[", start)
+                ? "]]>"
+                : xml.startsWith("<?", start)
+                    ? "?>"
+                    : undefined;
+        if (opaqueEnd !== undefined) {
+            const end = xml.indexOf(opaqueEnd, start + 2);
+            if (end < 0)
+                return;
+            cursor = end + opaqueEnd.length;
+            continue;
+        }
+        const doctype = /^<!DOCTYPE\b/iu.test(xml.slice(start, start + 10));
+        const element = /^<\/?[A-Za-z]/u.test(xml.slice(start, start + 4));
+        let quote;
+        let internalSubset = false;
+        let end = start + 1;
+        for (; end < xml.length; end += 1) {
+            const character = xml[end];
+            if (quote !== undefined) {
+                if (character === quote)
+                    quote = undefined;
+            }
+            else if (character === '"' || character === "'")
+                quote = character;
+            else if (character === ">")
+                break;
+            else if (doctype && character === "[")
+                internalSubset = true;
+        }
+        if (end === xml.length)
+            return;
+        cursor = end + 1;
+        if (doctype || element)
+            yield {
+                doctype,
+                internalSubset,
+                closing: xml[start + 1] === "/",
+                selfClosing: xml[end - 1] === "/",
+            };
+    }
+}
+const interfaceBuilderBudgetFailure = (_kind, message) => new InterfaceBuilderDecodeBudgetExceeded("aggregate_decode_budget_exhausted", message);
+const PROTOTYPE_KEY = "__proto__";
+/**
+ * Count every expanded binary-plist reference before calling plist.parseBinary,
+ * which recurses on each reference and copies shared containers. Malformed
+ * structure throws TypeError; budget, depth, and cycle failures use `fail`.
+ */
+export const estimateBinaryPlistExpansion = (bytes, maxBytes, { budget = "the aggregate Interface Builder decode budget", fail = interfaceBuilderBudgetFailure, bounds = "strict", } = {}) => {
     if (bytes.length < 40)
         throw new TypeError("binary plist trailer is truncated");
     const trailer = bytes.length - 32;
@@ -115,19 +174,20 @@ const estimateBinaryPlistExpansion = (bytes, maxBytes) => {
     const objectCount = readInteger(trailer + 8, 8);
     const topObject = readInteger(trailer + 16, 8);
     const offsetTable = readInteger(trailer + 24, 8);
+    const tableEnd = bounds === "strict" ? trailer : bytes.length;
+    const objectsEnd = bounds === "strict" ? offsetTable : bytes.length;
     if (objectCount < 1 ||
         topObject < 0 ||
         topObject >= objectCount ||
         offsetTable < 8 ||
-        offsetTable + objectCount * offsetSize > trailer)
+        offsetTable + objectCount * offsetSize > tableEnd)
         throw new TypeError("binary plist trailer or object table is invalid");
     let estimate = bytes.length * 2 + objectCount * 16;
+    let binaryPrototypeKeyObserved = false;
     if (estimate > maxBytes)
-        throw new InterfaceBuilderDecodeBudgetExceeded("aggregate_decode_budget_exhausted", "binary plist object table exceeds the aggregate Interface Builder decode budget");
+        throw fail("expansion", `binary plist object table exceeds ${budget}`);
     const active = new Set();
-    const pending = [
-        { object: topObject, depth: 0, exit: false },
-    ];
+    const pending = [{ object: topObject, depth: 0, exit: false, dictionaryKey: false }];
     let pendingObjectCount = 1;
     while (pending.length > 0) {
         const entry = pending.pop();
@@ -139,17 +199,19 @@ const estimateBinaryPlistExpansion = (bytes, maxBytes) => {
         }
         pendingObjectCount -= 1;
         if (entry.depth > 128)
-            throw new InterfaceBuilderDecodeBudgetExceeded("aggregate_decode_budget_exhausted", "binary plist nesting exceeds the aggregate Interface Builder decode budget");
+            throw fail("depth", `binary plist nesting exceeds ${budget}`);
         if (active.has(entry.object))
-            throw new InterfaceBuilderDecodeBudgetExceeded("aggregate_decode_budget_exhausted", "binary plist reference cycle exceeds the aggregate Interface Builder decode budget");
+            throw fail("cycle", `binary plist reference cycle exceeds ${budget}`);
         estimate += 96;
         if (estimate > maxBytes)
-            throw new InterfaceBuilderDecodeBudgetExceeded("aggregate_decode_budget_exhausted", "binary plist reference expansion exceeds the aggregate Interface Builder decode budget");
+            throw fail("expansion", `binary plist reference expansion exceeds ${budget}`);
         const offset = readInteger(offsetTable + entry.object * offsetSize, offsetSize);
-        if (offset < 8 || offset >= offsetTable)
+        if (offset < 8 || offset >= objectsEnd)
             throw new TypeError("binary plist object offset is invalid");
         const marker = bytes[offset] ?? 0;
         const type = marker >> 4;
+        if (entry.dictionaryKey && type !== 5 && type !== 6)
+            throw new TypeError("binary plist dictionary key is not a string");
         let size = marker & 0x0f;
         let cursor = offset + 1;
         if (size === 0x0f && type !== 0 && type !== 8) {
@@ -160,36 +222,64 @@ const estimateBinaryPlistExpansion = (bytes, maxBytes) => {
             const integerSize = 1 << (extMarker & 0x0f);
             size = readInteger(cursor, integerSize);
             cursor += integerSize;
-            if (size < 0 || cursor > offsetTable)
+            if (size < 0 || cursor > objectsEnd)
                 throw new TypeError("binary plist extended object size is invalid");
         }
         if (type === 4 || type === 5 || type === 6) {
             const byteLength = type === 6 ? size * 2 : size;
-            if (cursor + byteLength > offsetTable)
+            if (cursor + byteLength > objectsEnd)
                 throw new TypeError("binary plist scalar object is truncated");
+            if (!binaryPrototypeKeyObserved &&
+                entry.dictionaryKey &&
+                (type === 5 || type === 6) &&
+                size === PROTOTYPE_KEY.length) {
+                let matches = true;
+                for (let index = 0; index < PROTOTYPE_KEY.length; index += 1) {
+                    const codeUnit = type === 5
+                        ? (bytes[cursor + index] ?? 0)
+                        : ((bytes[cursor + index * 2] ?? 0) << 8) |
+                            (bytes[cursor + index * 2 + 1] ?? 0);
+                    if (codeUnit !== PROTOTYPE_KEY.charCodeAt(index)) {
+                        matches = false;
+                        break;
+                    }
+                }
+                if (matches)
+                    binaryPrototypeKeyObserved = true;
+            }
             estimate += type === 4 ? size + 4 * Math.ceil(size / 3) : byteLength * 2;
             if (estimate > maxBytes)
-                throw new InterfaceBuilderDecodeBudgetExceeded("aggregate_decode_budget_exhausted", "binary plist scalar expansion exceeds the aggregate Interface Builder decode budget");
+                throw fail("expansion", `binary plist scalar expansion exceeds ${budget}`);
             continue;
         }
         if (type !== 10 && type !== 13)
             continue;
         const childCount = type === 13 ? size * 2 : size;
         const refsEnd = cursor + childCount * referenceSize;
-        if (!Number.isSafeInteger(refsEnd) || refsEnd > offsetTable)
+        if (!Number.isSafeInteger(refsEnd) || refsEnd > objectsEnd)
             throw new TypeError("binary plist reference table is truncated");
         const availableNodes = Math.floor((maxBytes - estimate) / 96);
         if (childCount > availableNodes - pendingObjectCount)
-            throw new InterfaceBuilderDecodeBudgetExceeded("aggregate_decode_budget_exhausted", "binary plist reference expansion exceeds the aggregate Interface Builder decode budget");
+            throw fail("expansion", `binary plist reference expansion exceeds ${budget}`);
         active.add(entry.object);
-        pending.push({ object: entry.object, depth: entry.depth, exit: true });
+        pending.push({
+            object: entry.object,
+            depth: entry.depth,
+            exit: true,
+            dictionaryKey: false,
+        });
         for (let index = childCount - 1; index >= 0; index -= 1) {
             const reference = readInteger(cursor + index * referenceSize, referenceSize);
             if (reference < 0 || reference >= objectCount)
                 throw new TypeError("binary plist reference is invalid");
-            pending.push({ object: reference, depth: entry.depth + 1, exit: false });
+            pending.push({
+                object: reference,
+                depth: entry.depth + 1,
+                exit: false,
+                dictionaryKey: type === 13 && index < size,
+            });
         }
         pendingObjectCount += childCount;
     }
-    return estimate;
+    return { estimatedBytes: estimate, binaryPrototypeKeyObserved };
 };

package/dist/artifacts/apple/KeyedArchiveReader.js

@@ -11,17 +11,38 @@ import { KeyedArchiveKindError, keyedArchiveInputSchema, keyedArchiveResultSchem
 import { DirectoryArtifactReader } from "../DirectoryArtifactReader.js";
 import { ArtifactReaderFailure } from "../ArtifactReader.js";
 import { decodeXmlPlistText } from "../../domain/propertyListXmlText.js";
+import { hasBinaryPlistSignature, hasNibArchiveSignature, } from "../../domain/apple/appleArchiveFormat.js";
+import { estimateBinaryPlistExpansion } from "./InterfaceBuilderDecodeBudget.js";
 const MAX_BYTES = 64 * 1024 * 1024;
+/** Decoded representation budget, the same 8:1 ratio Interface Builder uses. */
+const MAX_DECODE_BYTES = 8 * MAX_BYTES;
 /** Parse inert plist bytes, preserving data and dates with explicit typed values. */
 export const decodeKeyedArchiveBytes = (bytes, selection) => {
     if (bytes.length > MAX_BYTES)
         throw new RangeError("Keyed archive exceeds 64 MiB");
-    if (bytes.subarray(0, 10).toString("ascii") === "NIBArchive")
+    if (hasNibArchiveSignature(bytes))
         throw new KeyedArchiveKindError("Selected file is a compiled NIBArchive, not a Foundation plist archive; decode it with decode_interface_builder", "nib-archive");
-    const binary = bytes.subarray(0, 8).toString("ascii") === "bplist00";
+    const binary = hasBinaryPlistSignature(bytes);
     const xmlText = binary ? undefined : decodeXmlPlistText(bytes);
-    const parsed = binary
-        ? { value: parseBinary(bytes), omittedPrototypeKeys: 0 }
+    // plist.parseBinary recurses on every object reference and copies shared
+    // containers, so a few hundred bytes can exhaust memory or the stack.
+    // RangeError reports a resource limit; a reference cycle is malformed.
+    const binaryExpansion = binary
+        ? estimateBinaryPlistExpansion(bytes, MAX_DECODE_BYTES, {
+            budget: "the keyed archive decode budget",
+            fail: (kind, message) => kind === "cycle"
+                ? new TypeError("binary plist object references form a cycle, which a property list cannot represent")
+                : new RangeError(message),
+            bounds: "decoder",
+        })
+        : undefined;
+    const parsed = binaryExpansion !== undefined
+        ? {
+            value: parseBinary(bytes),
+            omittedPrototypeKeys: binaryExpansion.binaryPrototypeKeyObserved
+                ? null
+                : 0,
+        }
         : parseXmlPropertyList(xmlText ?? "");
     const { value: plistValue, unknownRealCount } = projectPlistValue(parsed.value);
     const graph = projectKeyedArchive(plistValue, selection);
@@ -82,21 +103,20 @@ export const inspectBundleKeyedArchive = async (input) => {
     try {
         // Match inventory spelling while retaining the raw path for I/O and evidence.
         const wanted = selected.path.normalize("NFC");
-        const matches = [];
-        for await (const entry of reader.entries(input.signal)) {
-            if (entry.path.normalize("NFC") !== wanted)
+        let entry;
+        for await (const candidate of reader.entries(input.signal, (directory) => wanted.startsWith(`${directory.normalize("NFC")}/`))) {
+            if (candidate.path.normalize("NFC") !== wanted)
                 continue;
-            matches.push(entry);
+            if (candidate.kind !== "file")
+                throw archivePathError("invalid_value", `Archive path selects a ${candidate.kind}, not a regular file: ${selected.path}`);
+            if ((candidate.declaredSize ?? 0) > MAX_BYTES)
+                throw new ArtifactReaderFailure("limit", "Keyed archive exceeds 64 MiB");
+            if (entry !== undefined)
+                throw archivePathError("invalid_value", `Archive path matches multiple Unicode-equivalent bundle entries; selection is ambiguous: ${selected.path}`);
+            entry = candidate;
         }
-        if (matches.length > 1)
-            throw archivePathError("invalid_value", `Archive path matches ${String(matches.length)} Unicode-equivalent bundle entries; selection is ambiguous: ${selected.path}`);
-        const entry = matches[0];
         if (entry === undefined)
             throw archivePathError("invalid_value", `No regular file exists at ${selected.path} in the active app bundle.`);
-        if (entry.kind !== "file")
-            throw archivePathError("invalid_value", `Archive path selects a ${entry.kind}, not a regular file: ${selected.path}`);
-        if ((entry.declaredSize ?? 0) > MAX_BYTES)
-            throw new ArtifactReaderFailure("limit", "Keyed archive exceeds 64 MiB");
         const stream = await reader.open(entry, input.signal);
         const chunks = [];
         let size = 0;