rea-agents 3.2.0 → 4.0.0

package/dist/application/ManagedMemberComparisonService.js

@@ -1,7 +1,8 @@
+import { createHash } from "node:crypto";
 import { readFile } from "node:fs/promises";
 import { z } from "zod";
 import { compareManagedMembers, managedMemberComparisonResultSchema, parseManagedMemberEvidence, } from "../domain/managedMemberComparison.js";
-import { AnalysisInputError, AnalysisProtocolError, } from "../domain/errors.js";
+import { AnalysisInputError, AnalysisProtocolError, EvidenceIntegrityError, } from "../domain/errors.js";
 import { createEvidence } from "../domain/evidence.js";
 import { jsonValueSchema } from "../domain/jsonValue.js";
 import { parseBinaryTarget } from "./BinaryTargetResolver.js";
@@ -21,22 +22,34 @@ export const compareManagedMembersEvidenceValidated = (input) => {
         return workflowFailure(operation, cause);
     }
 };
+const DEFAULT_PATH_DEPENDENCIES = {
+    resolveTarget: parseBinaryTarget,
+    readBytes: readFile,
+};
 /** Inspect two local PE artifacts and return one derived comparison Evidence. */
-export const compareManagedMemberPaths = async (input) => {
+export const compareManagedMemberPaths = async (input, dependencies = DEFAULT_PATH_DEPENDENCIES) => {
     const operation = "compare_managed_members";
     try {
         const [leftTarget, rightTarget] = await Promise.all([
-            parseBinaryTarget(input.leftPath),
-            parseBinaryTarget(input.rightPath),
+            dependencies.resolveTarget(input.leftPath),
+            dependencies.resolveTarget(input.rightPath),
         ]);
         if (!leftTarget.ok)
             return err(new AnalysisInputError(operation, { cause: leftTarget.error }));
         if (!rightTarget.ok)
             return err(new AnalysisInputError(operation, { cause: rightTarget.error }));
         const [leftBytes, rightBytes] = await Promise.all([
-            readFile(leftTarget.value.path),
-            readFile(rightTarget.value.path),
+            dependencies.readBytes(leftTarget.value.path),
+            dependencies.readBytes(rightTarget.value.path),
         ]);
+        for (const [target, bytes] of [
+            [leftTarget.value, leftBytes],
+            [rightTarget.value, rightBytes],
+        ]) {
+            const observedSha256 = createHash("sha256").update(bytes).digest("hex");
+            if (observedSha256 !== target.sha256)
+                return err(new EvidenceIntegrityError(`Managed artifact digest changed after open: expected ${target.sha256}, observed ${observedSha256} at ${target.path}`));
+        }
         const leftInspection = inspectManagedMembersBytes(leftBytes, leftTarget.value);
         const rightInspection = inspectManagedMembersBytes(rightBytes, rightTarget.value);
         const leftEvidence = createEvidence(leftTarget.value, MANAGED_STATIC_PROVIDER, {

package/dist/application/NativeApiInspection.js

@@ -58,6 +58,8 @@ export const projectNativeApiInspection = (dossier) => {
 const availableResidualUnknowns = (boundary) => {
     const unknowns = [];
     for (const table of boundary.jump_tables) {
+        if (table.default_targets.length === 0)
+            unknowns.push(`Which default or out-of-range path, if any, belongs to the dispatch at ${table.dispatch_address}?`);
         if (table.mappings.length === 0)
             unknowns.push(`Which case values and targets belong to the dispatch at ${table.dispatch_address}?`);
         if (table.data_sources.length === 0)

package/dist/application/NativeCallRoutes.js

@@ -0,0 +1,72 @@
+import { z } from "zod";
+import { parseRelatedAddresses, referenceKindSchema, } from "../domain/hopperValues.js";
+import { err, ok } from "../domain/result.js";
+import { AnalysisOutputError } from "../domain/errors.js";
+const referencesSchema = z.object({
+    reference_kinds_available: z.boolean().optional(),
+    references: z.array(z.object({
+        source_address: z.string(),
+        target_address: z.string(),
+        target_procedure: z.object({ address: z.string() }).nullable(),
+        kind: referenceKindSchema,
+    })),
+    unresolved_calls: z
+        .array(z.object({ address: z.string(), reason: z.string() }))
+        .default([]),
+});
+/** Prefer typed static call references, preserving computed targets and targetless sites. */
+export const readNativeCallRoutes = async (analysis, procedure, signal) => {
+    const options = signal === undefined ? {} : { signal };
+    const execution = await analysis.execute("procedure_references", { procedure, direction: "outgoing" }, options);
+    if (execution.ok) {
+        const parsed = referencesSchema.safeParse(execution.value.result);
+        if (!parsed.success)
+            return err(new AnalysisOutputError("procedure_references", "Invalid typed call references"));
+        const references = parsed.data.references;
+        if (parsed.data.reference_kinds_available === true ||
+            (references.length > 0 && references.every(({ kind }) => kind.available))) {
+            const calls = references.filter(({ kind }) => kind.available && kind.call);
+            const countBySite = new Map();
+            for (const call of calls) {
+                const targets = countBySite.get(call.source_address) ?? new Set();
+                targets.add(call.target_address);
+                countBySite.set(call.source_address, targets);
+            }
+            return ok({
+                provider: execution.value.provider,
+                routes: calls.map((call) => ({
+                    address: call.target_procedure?.address ?? call.target_address,
+                    site: call.source_address,
+                    relation: call.kind.available && (call.kind.computed || call.kind.indirect)
+                        ? "indirect_call"
+                        : "direct_call",
+                    resolution: (countBySite.get(call.source_address)?.size ?? 0) > 1
+                        ? "ambiguous"
+                        : call.kind.available &&
+                            (call.kind.computed || call.kind.indirect)
+                            ? "resolved"
+                            : "observed",
+                })),
+                unknowns: parsed.data.unresolved_calls,
+            });
+        }
+    }
+    else if (execution.error._tag !== "AnalysisCapabilityUnavailableError")
+        return err(execution.error);
+    const callees = await analysis.execute("procedure_callees", { procedure }, options);
+    if (!callees.ok)
+        return callees;
+    const parsed = parseRelatedAddresses(callees.value.result, "callees");
+    return parsed.ok
+        ? ok({
+            provider: callees.value.provider,
+            routes: parsed.value.map((address) => ({
+                address,
+                site: procedure,
+                relation: "provider_call",
+                resolution: "inferred",
+            })),
+            unknowns: [],
+        })
+        : parsed;
+};

package/dist/application/NativeDispatchMetadataInspection.js

@@ -0,0 +1,33 @@
+import { z } from "zod";
+import { nativeDispatchMetadataResultSchema, inspectNativeDispatchMetadata, } from "../domain/objcSwiftMetadata.js";
+import { AnalysisOutputError } from "../domain/errors.js";
+import { jsonValueSchema } from "../domain/jsonValue.js";
+import { err, ok } from "../domain/result.js";
+/** Prefer validated binary metadata, otherwise preserve the bound provider's symbol-only coverage. */
+export const inspectNativeDispatch = async (analysis, maxRecords, signal) => {
+    const binaryMetadata = await analysis.execute("inspect_native_dispatch_metadata", { max_records: maxRecords }, signal === undefined ? {} : { signal });
+    if (binaryMetadata.ok)
+        return ok(jsonValueSchema.parse(nativeDispatchMetadataResultSchema.parse(binaryMetadata.value.result)));
+    if (binaryMetadata.error._tag !== "AnalysisCapabilityUnavailableError")
+        return err(binaryMetadata.error);
+    const execution = await analysis.execute("list_names", {}, signal === undefined ? {} : { signal });
+    if (!execution.ok)
+        return err(execution.error);
+    const names = z
+        .array(z.union([
+        z.strictObject({ address: z.string(), value: z.string() }),
+        z.strictObject({ address: z.string(), name: z.string() }),
+    ]))
+        .safeParse(execution.value.result);
+    if (!names.success)
+        return err(new AnalysisOutputError("list_names", "provider returned an invalid inventory"));
+    return ok(jsonValueSchema.parse(nativeDispatchMetadataResultSchema.parse({
+        target_sha256: execution.value.subject?.sha256 ?? null,
+        provider: execution.value.provider,
+        analysis_profile_digest: execution.value.analysisProfile?.digest ?? null,
+        result: inspectNativeDispatchMetadata(names.data.map((entry) => ({
+            address: entry.address,
+            name: "value" in entry ? entry.value : entry.name,
+        })), maxRecords),
+    })));
+};

package/dist/application/NativeUiActionTrace.js

@@ -1,45 +1,31 @@
 import { z } from "zod";
 import { interfaceBuilderAnalysisSchema } from "../domain/interfaceBuilderGraph.js";
 import { nativeInvestigationGraphSchema, nativeInvestigationTraceSchema, traceNativeInvestigationGraph, joinInterfaceBuilderDispatch, } from "../domain/nativeInvestigationGraph.js";
-import { inspectNativeDispatchMetadata, nativeDispatchMetadataResultSchema, } from "../domain/objcSwiftMetadata.js";
+import { nativeDispatchMetadataResultSchema } from "../domain/objcSwiftMetadata.js";
+import { inspectNativeDispatch } from "./NativeDispatchMetadataInspection.js";
 import { jsonValueSchema } from "../domain/jsonValue.js";
-import { parseRelatedAddresses } from "../domain/hopperValues.js";
+import { readNativeCallRoutes } from "./NativeCallRoutes.js";
 import { err, ok } from "../domain/result.js";
-import { AnalysisCancelledError, AnalysisOutputError, projectAnalysisError, } from "../domain/errors.js";
-const nativeNameSchema = z.array(z.union([
-    z.strictObject({ address: z.string(), name: z.string() }),
-    z.strictObject({ address: z.string(), value: z.string() }),
-]));
+import { AnalysisOutputError, projectAnalysisError } from "../domain/errors.js";
 /** Build a UI-to-code trace from the active app and selected native provider. */
 export const traceNativeUiAction = async (analysis, input, signal) => {
-    const [uiExecution, namesExecution] = await Promise.all([
+    const [uiExecution, metadataExecution] = await Promise.all([
         analysis.execute("decode_interface_builder", {
             max_documents: 64,
             max_objects: input.max_nodes,
             max_connections: input.max_edges,
         }, signal === undefined ? {} : { signal }),
-        analysis.execute("list_names", {}, signal === undefined ? {} : { signal }),
+        inspectNativeDispatch(analysis, 20_000, signal),
     ]);
     if (!uiExecution.ok && uiExecution.error._tag === "AnalysisCancelledError")
-        return err(new AnalysisCancelledError("decode_interface_builder"));
-    if (!namesExecution.ok)
-        return err(namesExecution.error);
-    const parsedNames = nativeNameSchema.safeParse(namesExecution.value.result);
-    if (!parsedNames.success)
-        return err(new AnalysisOutputError("list_names", "provider returned an invalid name inventory"));
-    const targetSha256 = namesExecution.value.subject?.sha256;
-    if (targetSha256 === undefined)
-        return err(new AnalysisOutputError("list_names", "provider did not bind the name inventory to a target SHA-256"));
-    const metadata = nativeDispatchMetadataResultSchema.parse({
-        target_sha256: targetSha256,
-        provider: namesExecution.value.provider,
-        analysis_profile_digest: namesExecution.value.analysisProfile?.digest ?? null,
-        result: inspectNativeDispatchMetadata(parsedNames.data.map((entry) => ({
-            address: entry.address,
-            name: "name" in entry ? entry.name : entry.value,
-        })), parsedNames.data.length),
-    });
-    let graph = emptyGraph(targetSha256, namesExecution.value.provider);
+        return err(uiExecution.error);
+    if (!metadataExecution.ok)
+        return err(metadataExecution.error);
+    const metadata = nativeDispatchMetadataResultSchema.parse(metadataExecution.value);
+    const targetSha256 = metadata.target_sha256;
+    if (targetSha256 === null)
+        return err(new AnalysisOutputError("inspect_native_dispatch_metadata", "Dispatch metadata lacks target identity"));
+    let graph = emptyGraph(targetSha256, metadata.provider);
     const coverage = [];
     if (uiExecution.ok) {
         const decoded = interfaceBuilderAnalysisSchema.safeParse(uiExecution.value.result);
@@ -77,7 +63,35 @@ export const traceNativeUiAction = async (analysis, input, signal) => {
             omitted: 0,
         });
     }
-    const selected = resolveUiAction(graph, input.action);
+    let selected = resolveUiAction(graph, input.action);
+    if (selected.nodeId === null && selected.candidates.length === 0) {
+        const native = await analysis.execute("procedure_address", { procedure: input.action }, signal === undefined ? {} : { signal });
+        if (!native.ok && native.error._tag === "AnalysisCancelledError")
+            return err(native.error);
+        if (native.ok) {
+            const address = z.string().safeParse(native.value.result);
+            if (!address.success || native.value.subject?.sha256 !== targetSha256)
+                return err(new AnalysisOutputError("procedure_address", "Native seed lacks a validated address or matching target identity"));
+            const id = `native:function:${address.data}`;
+            graph.nodes.push({
+                id,
+                kind: "function",
+                name: input.action,
+                location: { address: address.data, file_offset: null },
+                attributes: { resolved_by: native.value.provider.id },
+                evidence: [
+                    {
+                        kind: "reference",
+                        description: `Provider resolved the explicit native seed ${input.action}`,
+                        location: { address: address.data, file_offset: null },
+                        artifact_path: null,
+                        artifact_sha256: targetSha256,
+                    },
+                ],
+            });
+            selected = { nodeId: id, candidates: [], reason: null };
+        }
+    }
     if (selected.nodeId === null) {
         coverage.push(...graph.coverage);
         const trace = {
@@ -93,7 +107,7 @@ export const traceNativeUiAction = async (analysis, input, signal) => {
             reason: selected.reason,
             coverage,
             limitations: [
-                "The query did not identify one unique authored UI action; no handler path was inferred.",
+                "The query did not identify one unique authored UI action or native function; no handler path was inferred.",
             ],
         };
         return ok(jsonValueSchema.parse(nativeInvestigationTraceSchema.parse(trace)));
@@ -118,9 +132,9 @@ export const traceNativeUiAction = async (analysis, input, signal) => {
     if (expanded.error !== undefined)
         return err(expanded.error);
     coverage.push({
-        facet: "direct_native_calls",
+        facet: "static_native_calls",
         status: "partial",
-        reason: "resolved_direct_calls_do_not_cover_all_indirect_dispatch",
+        reason: "typed_direct_and_indirect_references_do_not_cover_all_runtime_dispatch; untyped_provider_callees_remain_inferred",
         examined: expanded.examined,
         omitted: expanded.omitted,
     });
@@ -266,7 +280,7 @@ const addDirectCallees = async (input) => {
             omitted += queue.length - queueIndex + 1;
             break;
         }
-        const execution = await input.analysis.execute("procedure_callees", { procedure: current.address }, input.signal === undefined ? {} : { signal: input.signal });
+        const execution = await readNativeCallRoutes(input.analysis, current.address, input.signal);
         examined += 1;
         if (!execution.ok) {
             if (execution.error._tag === "AnalysisCancelledError")
@@ -286,35 +300,45 @@ const addDirectCallees = async (input) => {
             });
             continue;
         }
-        const related = parseRelatedAddresses(execution.value.result, "callees");
-        if (!related.ok) {
-            const id = `unknown-callees:${current.address}`;
+        for (const unknown of execution.value.unknowns) {
+            if (edges.size >= input.input.max_edges) {
+                truncated = true;
+                omitted++;
+                break;
+            }
+            const id = `unknown-dispatch:${current.address}:${unknown.address}`;
             edges.set(id, {
                 id,
                 from: current.node.id,
                 to: null,
-                relation: "direct_call",
+                relation: "indirect_call",
                 resolution: "unresolved",
-                reason: "provider_returned_unreadable_callee_relationships",
-                evidence: [],
-                limitations: [
-                    "The provider result could not be normalized into callee addresses.",
+                reason: unknown.reason,
+                evidence: [
+                    {
+                        kind: "reference",
+                        description: unknown.reason,
+                        location: { address: unknown.address, file_offset: null },
+                        artifact_path: null,
+                        artifact_sha256: input.targetSha256,
+                    },
                 ],
+                limitations: [],
             });
-            continue;
         }
-        for (const [index, address] of related.value.entries()) {
+        for (const [index, route] of execution.value.routes.entries()) {
+            const address = route.address;
             if (edges.size >= input.input.max_edges) {
                 truncated = true;
-                omitted += related.value.length - index;
+                omitted += execution.value.routes.length - index;
                 break;
             }
             const targetId = `native:function:${address}`;
             const evidence = [
                 {
                     kind: "reference",
-                    description: `${execution.value.provider.name} resolved a direct callee from ${current.address} to ${address}`,
-                    location: { address: current.address, file_offset: null },
+                    description: `${execution.value.provider.name} reported ${route.relation} from ${current.address} to ${address}`,
+                    location: { address: route.site, file_offset: null },
                     artifact_path: null,
                     artifact_sha256: input.targetSha256,
                 },
@@ -348,13 +372,13 @@ const addDirectCallees = async (input) => {
                 nodes.set(targetId, node);
                 queue.push({ node, address, depth: current.depth + 1 });
             }
-            const edgeId = `call:${current.address}:${address}`;
+            const edgeId = `call:${current.address}:${route.site}:${address}`;
             edges.set(edgeId, {
                 id: edgeId,
                 from: current.node.id,
                 to: targetId,
-                relation: "direct_call",
-                resolution: "observed",
+                relation: route.relation,
+                resolution: route.resolution,
                 evidence,
                 limitations: [
                     "A resolved static call edge does not establish runtime reachability.",