rea-agents 4.0.1 → 5.0.0

package/dist/domain/apple/interfaceBuilderKeyedArchive.js

@@ -0,0 +1,411 @@
+import { z } from "zod";
+import { jsonValueSchema } from "../jsonValue.js";
+const recordSchema = z.record(z.string(), z.unknown());
+const objectNode = z.strictObject({
+    id: z.string().min(1),
+    kind: z.enum([
+        "view_controller",
+        "view",
+        "control",
+        "constraint",
+        "layout_guide",
+        "resource",
+        "placeholder",
+        "external_object",
+        "other",
+    ]),
+    class_name: z.string().nullable(),
+    name: z.string().min(1),
+    attributes: z.record(z.string(), jsonValueSchema),
+});
+const connection = z.strictObject({
+    id: z.string().min(1),
+    kind: z.enum(["outlet", "action", "segue", "other"]),
+    source_id: z.string().min(1),
+    destination_id: z.string().nullable(),
+    label: z.string().nullable(),
+    attributes: z.record(z.string(), jsonValueSchema),
+});
+/** Parse ibtool dictionaries or compiled keyed archives into typed records. */
+export const parseInterfaceBuilderRecords = (value) => {
+    const root = record(value);
+    const keyed = parseKeyedArchive(root);
+    if (keyed !== null)
+        return keyed;
+    const objectsRaw = record(root["com.apple.ibtool.document.objects"]);
+    const connectionsRaw = record(root["com.apple.ibtool.document.connections"]);
+    const hierarchyRaw = root["com.apple.ibtool.document.hierarchy"];
+    const classesRaw = record(root["com.apple.ibtool.document.classes"]);
+    const objects = [];
+    const connections = [];
+    let omittedConnections = 0;
+    const objectEntries = Object.entries(objectsRaw);
+    for (const [id, raw] of objectEntries.slice(0, 20_000)) {
+        const attributes = record(raw);
+        const className = firstString(attributes["customClass"], attributes["class"], attributes["isa"]);
+        const label = firstString(attributes["label"], attributes["title"], attributes["name"], className);
+        objects.push(objectNode.parse({
+            id,
+            kind: classifyObject(className),
+            class_name: className,
+            name: label ?? id,
+            attributes: jsonSafeRecord(attributes),
+        }));
+    }
+    for (const [sourceId, rawConnections] of Object.entries(connectionsRaw)) {
+        if (!Array.isArray(rawConnections))
+            continue;
+        for (const [index, raw] of rawConnections.entries()) {
+            if (connections.length >= 40_000) {
+                omittedConnections += rawConnections.length - index;
+                break;
+            }
+            const item = record(raw);
+            const type = firstString(item.type, item.connectionType) ?? "unknown";
+            const destination = firstString(item["destination-id"], item.destinationId);
+            const label = firstString(item.label, item.selector, item.identifier);
+            connections.push(connection.parse({
+                id: `${sourceId}:connection:${index}`,
+                kind: classifyConnection(type),
+                source_id: sourceId,
+                destination_id: destination,
+                label,
+                attributes: jsonSafeRecord(item),
+            }));
+        }
+    }
+    return {
+        objects,
+        connections,
+        hierarchy: Array.isArray(hierarchyRaw) ? hierarchyRaw.slice(0, 20_000) : [],
+        classes: classesRaw,
+        objectCount: objectEntries.length,
+        omittedObjects: Math.max(0, objectEntries.length - 20_000),
+        omittedConnections,
+    };
+};
+/**
+ * A UID decodes as a one-key `UID` (binary) or `CF$UID` (XML) dictionary with
+ * an integer value. Any other dictionary is ordinary archive data.
+ */
+const archiveUid = (value) => {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return undefined;
+    if (Object.keys(value).length !== 1)
+        return undefined;
+    const item = record(value);
+    const marker = Object.hasOwn(item, "UID") ? item.UID : item["CF$UID"];
+    return typeof marker === "number" && Number.isInteger(marker)
+        ? marker
+        : undefined;
+};
+const HIERARCHY_KEY = /(?:subviews|contentview|childviewcontrollers|children|views)$/iu;
+/**
+ * Read an NSKeyedArchiver object table without expanding it into a tree.
+ * Archived objects reference each other freely, including cycles such as a
+ * view and its superview, so inlining every reference grows exponentially.
+ * A reference instead resolves to the referenced string, or to a stub that
+ * names the referenced object; the hierarchy walk visits each object once.
+ */
+const keyedArchiveTable = (objectTable) => {
+    const classNameOf = (value) => {
+        const classReference = record(value).$class;
+        const uid = archiveUid(classReference);
+        return firstString(record(uid === undefined ? classReference : objectTable[uid]).$classname);
+    };
+    /** The string an archived string object holds, if it is one. */
+    const archivedString = (target) => {
+        if (typeof target === "string")
+            return target;
+        const text = record(target)["NS.string"];
+        return typeof text === "string" &&
+            /^NS(?:Mutable)?String$/u.test(classNameOf(target) ?? "")
+            ? text
+            : undefined;
+    };
+    const text = (value) => {
+        const uid = archiveUid(value);
+        return firstString(uid === undefined ? value : archivedString(objectTable[uid]));
+    };
+    const authoredId = (item) => firstString(text(item.objectID), text(item["object-id"]));
+    const reference = (uid) => {
+        // UID 0 is the archived nil.
+        const target = uid === 0 ? null : objectTable[uid];
+        if (target === undefined || target === null)
+            return null;
+        if (typeof target !== "object")
+            return target;
+        const string = archivedString(target);
+        if (string !== undefined)
+            return string;
+        const objectId = authoredId(record(target));
+        return {
+            archiveUID: uid,
+            ...(objectId === null ? {} : { objectID: objectId }),
+            className: classNameOf(target),
+        };
+    };
+    /** Resolve one object's own fields, leaving references to other objects as stubs. */
+    const resolve = (value) => {
+        const uid = archiveUid(value);
+        if (uid !== undefined)
+            return reference(uid);
+        if (Array.isArray(value))
+            return value.map(resolve);
+        if (typeof value !== "object" || value === null)
+            return value;
+        const output = {};
+        for (const [key, child] of Object.entries(value)) {
+            if (key === "$class")
+                output.className = classNameOf(value);
+            else
+                output[key] = resolve(child);
+        }
+        return output;
+    };
+    const hierarchy = (start) => {
+        const visited = new Set();
+        const root = [];
+        const pending = [
+            { value: start, output: root },
+        ];
+        const appendNode = (item, uid, output) => {
+            const objectId = firstString(authoredId(item), text(item.id), uid === undefined ? null : String(uid));
+            if (objectId === null) {
+                for (const [key, child] of Object.entries(item).reverse())
+                    if (HIERARCHY_KEY.test(key))
+                        pending.push({ value: child, output });
+                return;
+            }
+            const children = [];
+            output.push({ objectID: objectId, children });
+            for (const [key, child] of Object.entries(item).reverse())
+                if (HIERARCHY_KEY.test(key))
+                    pending.push({ value: child, output: children });
+        };
+        while (pending.length > 0) {
+            const entry = pending.pop();
+            if (entry === undefined)
+                break;
+            const { value, output } = entry;
+            const uid = archiveUid(value);
+            if (uid !== undefined) {
+                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];
+                        if (child !== undefined)
+                            pending.push({ value: child, output });
+                    }
+                    continue;
+                }
+                if (typeof target !== "object" || target === null)
+                    continue;
+                const item = record(target);
+                if (archivedArrayClass(item.$class)) {
+                    const members = item["NS.objects"];
+                    if (Array.isArray(members))
+                        for (let index = members.length - 1; index >= 0; index -= 1) {
+                            const child = members[index];
+                            if (child !== undefined)
+                                pending.push({ value: child, output });
+                        }
+                    continue;
+                }
+                appendNode(item, uid, output);
+                continue;
+            }
+            if (Array.isArray(value)) {
+                for (let index = value.length - 1; index >= 0; index -= 1) {
+                    const child = value[index];
+                    if (child !== undefined)
+                        pending.push({ value: child, output });
+                }
+            }
+            else if (typeof value === "object" && value !== null) {
+                appendNode(record(value), undefined, output);
+            }
+        }
+        return root;
+    };
+    const archivedArrayClass = (classReference) => {
+        const uid = archiveUid(classReference);
+        const descriptor = record(uid === undefined ? classReference : objectTable[uid]);
+        const classNames = Array.isArray(descriptor.$classes)
+            ? descriptor.$classes.filter((name) => typeof name === "string")
+            : [];
+        return (classNames.includes("NSArray") || classNames.includes("NSMutableArray"));
+    };
+    return { resolve, hierarchy };
+};
+/** Project class and connection objects from an NSKeyedArchiver object table. */
+const parseKeyedArchive = (root) => {
+    if (root.$archiver !== "NSKeyedArchiver" || !Array.isArray(root.$objects))
+        return null;
+    const objectTable = root.$objects;
+    const { resolve, hierarchy: toHierarchy } = keyedArchiveTable(objectTable);
+    const objects = [];
+    const connections = [];
+    let objectCount = 0;
+    let omittedConnections = 0;
+    for (const [index, raw] of objectTable.entries()) {
+        if (index === 0)
+            continue;
+        const resolved = record(resolve(raw));
+        const className = firstString(resolved.className);
+        if (className === null)
+            continue;
+        objectCount += 1;
+        const fields = Object.fromEntries(Object.entries(resolved).filter(([key]) => key !== "className"));
+        const authoredId = firstString(fields.objectID, fields["object-id"]);
+        const objectId = authoredId ??
+            (typeof fields.archiveUID === "number"
+                ? String(fields.archiveUID)
+                : String(index));
+        const kind = classifyObject(className);
+        if (objects.length < 20_000)
+            objects.push(objectNode.parse({
+                id: objectId,
+                kind,
+                class_name: className,
+                name: firstString(fields.label, fields.title, fields.identifier, fields.accessibilityLabel, className) ?? `object ${String(index)}`,
+                attributes: jsonSafeRecord(fields),
+            }));
+        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)
+                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),
+                attributes: jsonSafeRecord(fields),
+            });
+            if (connections.length < 40_000)
+                connections.push(parsedConnection);
+            else
+                omittedConnections += 1;
+        }
+    }
+    const top = record(root.$top);
+    const hierarchy = toHierarchy(top.root ?? top.UITopLevelObjectsKey);
+    const classes = Object.fromEntries(objectTable.flatMap((raw) => {
+        const item = record(raw);
+        const name = firstString(item.$classname);
+        return name === null
+            ? []
+            : [
+                [
+                    name,
+                    {
+                        superclasses: Array.isArray(item.$classes) ? item.$classes : [],
+                    },
+                ],
+            ];
+    }));
+    return {
+        objects,
+        connections,
+        hierarchy,
+        classes,
+        objectCount,
+        omittedObjects: Math.max(0, objectCount - 20_000),
+        omittedConnections,
+    };
+};
+/** Coerce unknown values to a string-keyed record; non-objects become `{}`. */
+export const record = (value) => recordSchema.safeParse(value).data ?? {};
+/** First non-empty string among the candidates, otherwise null. */
+export const firstString = (...values) => {
+    for (const value of values)
+        if (typeof value === "string" && value.length > 0)
+            return value;
+    return null;
+};
+/**
+ * The node identity of a resolved archive reference: its authored object ID,
+ * otherwise its archive UID, which is how the referenced object's node is keyed.
+ */
+const archivedObjectReference = (value) => {
+    const item = record(value);
+    if (typeof item.archiveUID !== "number")
+        return null;
+    return (firstString(item.objectID, item["object-id"]) ?? String(item.archiveUID));
+};
+const firstObjectReference = (...values) => {
+    for (const value of values) {
+        const direct = firstString(value);
+        if (direct !== null)
+            return direct;
+        const item = record(value);
+        const objectId = firstString(item.objectID, item["object-id"], item.id, item.identifier, typeof item.archiveUID === "number" ? String(item.archiveUID) : null);
+        if (objectId !== null)
+            return objectId;
+    }
+    return null;
+};
+const classifyObject = (className) => {
+    const value = className?.toLowerCase() ?? "";
+    if (value.includes("constraint"))
+        return "constraint";
+    if (value.includes("layoutguide"))
+        return "layout_guide";
+    if (value.includes("placeholder") ||
+        value.includes("firstresponder") ||
+        value === "uiproxyobject")
+        return "placeholder";
+    if (value.includes("image") ||
+        value.includes("color") ||
+        value.includes("font"))
+        return "resource";
+    if (value.includes("external"))
+        return "external_object";
+    if (value.includes("viewcontroller") || value.includes("windowcontroller"))
+        return "view_controller";
+    if (value.includes("button") ||
+        value.includes("control") ||
+        value.includes("textfield") ||
+        value.includes("slider") ||
+        value.includes("menuitem"))
+        return "control";
+    if (value.includes("view") ||
+        value.includes("window") ||
+        value.includes("cell"))
+        return "view";
+    return "other";
+};
+const classifyConnection = (type) => {
+    const value = type.toLowerCase();
+    if (value.includes("outlet"))
+        return "outlet";
+    if (value.includes("action"))
+        return "action";
+    if (value.includes("segue"))
+        return "segue";
+    return "other";
+};
+const jsonSafeRecord = (value) => Object.fromEntries(Object.entries(value).flatMap(([key, item]) => {
+    try {
+        const serialized = JSON.stringify(item);
+        if (serialized === undefined)
+            return [];
+        const parsed = jsonValueSchema.safeParse(JSON.parse(serialized));
+        return parsed.success ? [[key, parsed.data]] : [];
+    }
+    catch (cause) {
+        // Unserializable entries are omitted from the record.
+        void cause;
+        return [];
+    }
+}));

package/dist/domain/{keyedArchive.js → apple/keyedArchive.js}

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { jsonValueSchema } from "./jsonValue.js";
+import { jsonValueSchema } from "../jsonValue.js";
 /** Select one archive within the active bundle and optionally one named root. */
 export const keyedArchiveInputSchema = z.strictObject({
     path: z.string().min(1).default("."),
@@ -47,11 +47,17 @@ export const keyedArchiveResultSchema = z.strictObject({
 const record = (value) => value !== null && typeof value === "object" && !Array.isArray(value)
     ? value
     : undefined;
+/**
+ * A UID decodes as a one-key `UID` (binary) or `CF$UID` (XML) dictionary with
+ * a numeric value. Any other value means an ordinary dictionary, such as a
+ * `$top` that holds a root encoded under the key `UID`.
+ */
 const uid = (value) => {
     const object = record(value);
     if (object === undefined || Object.keys(object).length !== 1)
         return undefined;
-    return Object.hasOwn(object, "UID") ? object.UID : object["CF$UID"];
+    const marker = Object.hasOwn(object, "UID") ? object.UID : object["CF$UID"];
+    return typeof marker === "number" ? marker : undefined;
 };
 /** Interpret serialized Foundation references without instantiating archive classes. */
 export const projectKeyedArchive = (value, selection) => {
@@ -84,10 +90,7 @@ export const projectKeyedArchive = (value, selection) => {
                 throw new RangeError("Archive exceeds 200000 values per object or 128 nesting levels");
             const target = uid(item.value);
             if (target !== undefined) {
-                const valid = typeof target === "number" &&
-                    Number.isSafeInteger(target) &&
-                    target >= 0;
-                const index = valid ? target : null;
+                const index = Number.isSafeInteger(target) && target >= 0 ? target : null;
                 references.push({
                     source,
                     path: item.path,
@@ -127,9 +130,7 @@ export const projectKeyedArchive = (value, selection) => {
         scan(id, value);
         const fields = record(value);
         const classUid = uid(fields?.$class);
-        const classId = typeof classUid === "number" &&
-            Number.isSafeInteger(classUid) &&
-            classUid >= 0
+        const classId = classUid !== undefined && Number.isSafeInteger(classUid) && classUid >= 0
             ? classUid
             : null;
         const descriptor = classId === null ? undefined : record(table[classId]);

package/dist/domain/apple/plistValue.js

@@ -0,0 +1,35 @@
+import { z } from "zod";
+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
+ * because the XML decoder reports NaN and ±infinity alike.
+ */
+export const projectPlistValue = (value) => {
+    let unknownRealCount = 0;
+    const project = (item, depth) => {
+        if (depth > MAX_PLIST_DEPTH)
+            throw new RangeError(`Plist exceeds ${String(MAX_PLIST_DEPTH)} nesting levels`);
+        if (item instanceof Uint8Array)
+            return {
+                $plist_type: "data",
+                base64: Buffer.from(item).toString("base64"),
+            };
+        if (item instanceof Date)
+            return { $plist_type: "date", iso8601: item.toISOString() };
+        if (typeof item === "number" && !Number.isFinite(item)) {
+            unknownRealCount += 1;
+            return { $plist_type: "real", value: null };
+        }
+        if (Array.isArray(item))
+            return item.map((entry) => project(entry, depth + 1));
+        if (item !== null && typeof item === "object")
+            return Object.fromEntries(Object.entries(item).map(([key, entry]) => [
+                key,
+                project(entry, depth + 1),
+            ]));
+        return z.union([z.string(), z.number(), z.boolean(), z.null()]).parse(item);
+    };
+    const projected = project(value, 0);
+    return { value: projected, unknownRealCount };
+};

package/dist/domain/artifactGraph.js

@@ -42,6 +42,7 @@ const artifactFormatSchema = z.enum([
     "elf",
     "pe",
     "dos-mz",
+    "dos-com",
     "hopper",
     "analysis-database",
     "ipa",

package/dist/domain/artifactInspection.js

@@ -1,7 +1,7 @@
-import { createHash } from "node:crypto";
-import canonicalize from "canonicalize";
 import { z } from "zod";
 import { artifactInventoryResultSchema, } from "./artifactGraph.js";
+import { canonicalDigest } from "./comparisonSemantics.js";
+import { uniqueSorted } from "./canonicalOrdering.js";
 import { evidenceSchema, parseEvidence } from "./evidence.js";
 import { jsonValueSchema } from "./jsonValue.js";
 import { prefixedDigestSchema } from "./../domain/digests.js";
@@ -137,10 +137,10 @@ export const createArtifactInspection = (inventoryInput) => {
         },
         substeps: [
             {
-                substep_id: `ais_${digestCanonical({
+                substep_id: `ais_${canonicalDigest({
                     operation: "inventory_artifact",
                     evidence_id: inventoryEvidence.evidence_id,
-                })}`,
+                }, "Artifact inspection")}`,
                 operation: "inventory_artifact",
                 status: "completed",
                 evidence_id: inventoryEvidence.evidence_id,
@@ -175,7 +175,7 @@ export const createArtifactInspection = (inventoryInput) => {
     };
     return artifactInspectionResultSchema.parse({
         ...semantic,
-        inspection_id: `ai_${digestCanonical(semantic)}`,
+        inspection_id: `ai_${canonicalDigest(semantic, "Artifact inspection")}`,
     });
 };
 const parseInventoryEvidence = (input) => {
@@ -197,7 +197,10 @@ const observation = (kind, subject, value, evidenceId) => {
         value: jsonValueSchema.parse(value),
         evidence_id: evidenceId,
     };
-    return { observation_id: `aio_${digestCanonical(semantic)}`, ...semantic };
+    return {
+        observation_id: `aio_${canonicalDigest(semantic, "Artifact inspection")}`,
+        ...semantic,
+    };
 };
 const allRelationships = (inventory, evidenceId) => inventory.edges.map((edge) => {
     const semantic = {
@@ -209,7 +212,7 @@ const allRelationships = (inventory, evidenceId) => inventory.edges.map((edge) =
         evidence_id: evidenceId,
     };
     return {
-        relationship_id: `air_${digestCanonical(semantic)}`,
+        relationship_id: `air_${canonicalDigest(semantic, "Artifact inspection")}`,
         ...semantic,
     };
 });
@@ -230,7 +233,10 @@ const allHypotheses = (inventory, evidenceId) => {
             basis_evidence_ids: [evidenceId],
             limitation: "Format classification proposes a bounded follow-up; it is not semantic proof.",
         };
-        return { hypothesis_id: `aih_${digestCanonical(semantic)}`, ...semantic };
+        return {
+            hypothesis_id: `aih_${canonicalDigest(semantic, "Artifact inspection")}`,
+            ...semantic,
+        };
     });
 };
 const contradictions = (inventory, evidenceId) => inventory.integrity_contradictions.map((value) => {
@@ -242,7 +248,7 @@ const contradictions = (inventory, evidenceId) => inventory.integrity_contradict
         evidence_id: evidenceId,
     };
     return {
-        contradiction_id: `aic_${digestCanonical(semantic)}`,
+        contradiction_id: `aic_${canonicalDigest(semantic, "Artifact inspection")}`,
         ...semantic,
     };
 });
@@ -301,17 +307,13 @@ const branch = (reason, detail, nextProbe, evidenceId) => {
         next_probe: nextProbe,
         evidence_id: evidenceId,
     };
-    return { branch_id: `aib_${digestCanonical(semantic)}`, ...semantic };
+    return {
+        branch_id: `aib_${canonicalDigest(semantic, "Artifact inspection")}`,
+        ...semantic,
+    };
 };
 const inspectionCoverage = (_inventory, omissions) => {
     if (Object.values(omissions).some((count) => count > 0))
         return "truncated";
     return "complete-within-substeps";
 };
-const digestCanonical = (value) => {
-    const encoded = canonicalize(value);
-    if (encoded === undefined)
-        throw new TypeError("Artifact inspection could not canonicalize");
-    return createHash("sha256").update(encoded).digest("hex");
-};
-const uniqueSorted = (values) => [...new Set(values)].sort((left, right) => left < right ? -1 : left > right ? 1 : 0);