Reverse engineer anything with agents, from app behavior down to native binaries.
TypeScript agent-skillsai-agentsbinary-analysisclaude-codeclicodexcordisdecompilerdeveloper-toolsdshdsh-pluginghidrahopperllmmcpmodel-context-protocolreareverse-engineeringstatic-analysistouhou
fix(native): preserve partial call reference evidence
morlutoa80575c73652
diff --git a/docs/native-investigation.md b/docs/native-investigation.mdindex 8ff828225..b07fb53e1 100644--- a/docs/native-investigation.md+++ b/docs/native-investigation.md@@ -216,12 +216,24 @@ sites remain distinct. A static route does not establish runtime reachability.Swift/closure dispatch requires resolved static references; unavailable ABIforms remain unknown.-Incomplete reference kinds do not discard known typed calls. Callee fallback-adds inferred targets while each retained route keeps its original provider-and call site. If enumeration fails, known routes remain alongside an unresolved+Incomplete reference kinds do not discard known typed calls or partial+provider call references. A `provider_call` with `observed` resolution retains+the provider-reported call site and endpoint without claiming generic direct,+indirect or Objective-C dispatch semantics. Its `call_reference` evidence+preserves the original endpoints, classification, raw provider type and+provenance, even when the target node is a containing procedure. Hopper's+`none`, `unknown`, `direct` and `objective_c` labels stay provider-scoped;+unknown numeric types remain available in the raw type field. Target-only+callee fallback uses `provider_call` with `inferred` resolution.++Callee fallback adds inferred targets while each retained route keeps its+original provider and call site. If enumeration fails, known routes remain alongside an unresolvedfailure; cancellation still terminates the request. A node-limit omission keepsthe route's known relation while marking its target unresolved. Distinct callsites to the same omitted target retain separate evidence.+Reports sharing a call site and containing target procedure retain all their+original endpoint evidence on the shared graph edge. Different reported+relations retain separate edges, independent of enumeration order.Session discovery describes two automatic source routes for this trace:`authored_ui_dispatch` needs Interface Builder decoding and dispatch metadata;diff --git a/src/application/native/NativeCallRoutes.ts b/src/application/native/NativeCallRoutes.tsindex f4018b0a5..9c082c196 100644--- a/src/application/native/NativeCallRoutes.ts+++ b/src/application/native/NativeCallRoutes.ts@@ -12,8 +12,12 @@ import { AnalysisOutputError } from "../../domain/analysisErrorCore.js";import type { AnalysisError } from "../../domain/analysisErrorBase.js";import { err, ok, type Result } from "../../domain/result.js";import type { SourceLimitation } from "../SourceLimitations.js";+import {+ nativeCallClassificationSchema,+ type NativeCallReference,+} from "../../domain/native/nativeCallReference.js";-/** Preferred typed observations and the untyped fallback share one owner. */+/** Detailed or partial observations and the untyped fallback share one owner. */export const NATIVE_CALL_ROUTE_SOURCES = {references: "procedure_references",callees: "procedure_callees",@@ -34,6 +38,7 @@ const referencesSchema = z.object({target_address: z.string(),target_procedure: z.object({ address: z.string() }).nullable(),kind: referenceKindSchema,+ call: nativeCallClassificationSchema.exactOptional(),}),),unresolved_calls: z.array(@@ -47,6 +52,7 @@ interface NativeCallRoute {readonly relation: "direct_call" | "indirect_call" | "provider_call";readonly resolution: "observed" | "resolved" | "ambiguous" | "inferred";readonly provider: ProviderIdentity;+ readonly callReference?: NativeCallReference;}/** Enumeration failure does not invalidate facts already obtained. */@@ -61,11 +67,13 @@ interface NativeCallRouteRead {readonly outcome: Result<void, AnalysisError>;}-const typedCallRoutes = (+const observedCallRoutes = (references: z.infer<typeof referencesSchema>["references"],provider: ProviderIdentity,): NativeCallRoute[] => {- const calls = references.filter(({ kind }) => kind.available && kind.call);+ const calls = references.filter(({ kind, call }) =>+ kind.available ? kind.call : call !== undefined,+ );const countBySite = new Map<string, Set<string>>();for (const call of calls) {const targets = countBySite.get(call.source_address) ?? new Set<string>();@@ -76,20 +84,31 @@ const typedCallRoutes = (provider,address: call.target_procedure?.address ?? call.target_address,site: call.source_address,- relation:- call.kind.available && (call.kind.computed || call.kind.indirect)+ ...(call.call === undefined+ ? {}+ : {+ callReference: {+ ...call.call,+ source_address: call.source_address,+ target_address: call.target_address,+ },+ }),+ relation: !call.kind.available+ ? ("provider_call" as const)+ : call.kind.computed || call.kind.indirect? ("indirect_call" as const): ("direct_call" as const),- resolution:- (countBySite.get(call.source_address)?.size ?? 0) > 1+ resolution: !call.kind.available+ ? ("observed" as const)+ : (countBySite.get(call.source_address)?.size ?? 0) > 1? ("ambiguous" as const)- : call.kind.available && (call.kind.computed || call.kind.indirect)+ : call.kind.computed || call.kind.indirect? ("resolved" as const): ("observed" as const),}));};-/** Retain typed observations while supplementing incomplete kinds with inferred callees. */+/** Retain available observations while supplementing incomplete kinds with inferred callees. */export const readNativeCallRoutes = async (analysis: AnalysisOperationPort,procedure: string,@@ -148,7 +167,7 @@ export const readNativeCallRoutes = async (})),);const references = parsed.data.references;- routes.push(...typedCallRoutes(references, execution.value.provider));+ routes.push(...observedCallRoutes(references, execution.value.provider));if (references.every(({ kind }) => kind.available) &&(parsed.data.reference_kinds_available || references.length > 0)diff --git a/src/application/native/NativeUiActionTrace.ts b/src/application/native/NativeUiActionTrace.tsindex bc67af6c4..d8e5b0965 100644--- a/src/application/native/NativeUiActionTrace.ts+++ b/src/application/native/NativeUiActionTrace.ts@@ -471,39 +471,43 @@ const expandNativeCalls = async (input: {}for (const [index, route] of execution.routes.entries()) {const address = route.address;- if (edges.size >= input.input.max_edges) {+ const targetId = `native:function:${address}`;+ const targetOmitted =+ !nodes.has(targetId) && nodes.size >= input.input.max_nodes;+ const edgeId = `${targetOmitted ? "unknown-node-bound" : "call"}:${current.address}:${route.site}:${address}:${route.relation}`;+ if (!edges.has(edgeId) && edges.size >= input.input.max_edges) {truncated = true;omitted += execution.routes.length - index;break;}- const targetId = `native:function:${address}`;- const evidence = [- {- kind: "reference" as const,- provider: route.provider,- description: `${route.provider.name} reported ${route.relation} from ${current.address} to ${address}`,- location: { address: route.site, file_offset: null },- artifact_path: null,- artifact_sha256: input.targetSha256,- },- ];+ const evidence = edges.get(edgeId)?.evidence ?? [];+ evidence.push({+ kind: "reference",+ provider: route.provider,+ description: `${route.provider.name} reported ${route.relation} from ${current.address} to ${address}`,+ location: { address: route.site, file_offset: null },+ ...(route.callReference === undefined+ ? {}+ : { call_reference: route.callReference }),+ artifact_path: null,+ artifact_sha256: input.targetSha256,+ });+ if (targetOmitted) {+ truncated = true;+ omitted += 1;+ edges.set(edgeId, {+ id: edgeId,+ from: current.node.id,+ to: null,+ relation: route.relation,+ resolution: "unresolved",+ reason: "native_trace_node_bound_reached",+ evidence,+ limitations: [],+ });+ continue;+ }if (!nodes.has(targetId)) {- if (nodes.size >= input.input.max_nodes) {- truncated = true;- omitted += 1;- const id = `unknown-node-bound:${current.address}:${route.site}:${address}`;- edges.set(id, {- id,- from: current.node.id,- to: null,- relation: route.relation,- resolution: "unresolved",- reason: "native_trace_node_bound_reached",- evidence,- limitations: [],- });- continue;- }const name = addressNames.get(address) ?? address;const node = {id: targetId,@@ -516,7 +520,6 @@ const expandNativeCalls = async (input: {nodes.set(targetId, node);queue.push({ node, address, depth: current.depth + 1 });}- const edgeId = `call:${current.address}:${route.site}:${address}`;edges.set(edgeId, {id: edgeId,from: current.node.id,diff --git a/src/domain/hopperValues.ts b/src/domain/hopperValues.tsindex 4fbdb72db..e35338fd9 100644--- a/src/domain/hopperValues.ts+++ b/src/domain/hopperValues.ts@@ -7,6 +7,7 @@ import type { JsonValue } from "./jsonValue.js";import { err, ok, type Result } from "./result.js";import { nativeApiBoundarySchema } from "./native/nativeApiBoundary.js";import { nativeValueFlowSchema } from "./native/nativeValueFlow.js";+import { nativeCallClassificationSchema } from "./native/nativeCallReference.js";import { AnalysisOutputError } from "./analysisErrorCore.js";export interface AddressedName {@@ -350,13 +351,7 @@ export const referenceEdgeSchema = zsource_procedure: procedureIdentitySchema.nullable(),target_procedure: procedureIdentitySchema.nullable(),kind: referenceKindSchema,- call: z- .strictObject({- classification: z.enum(["none", "unknown", "direct", "objective_c"]),- provider_type: z.number().int(),- provenance: z.string().min(1),- })- .exactOptional(),+ call: nativeCallClassificationSchema.exactOptional(),}).strict();const facetAvailabilitySchema = z.discriminatedUnion("available", [diff --git a/src/domain/native/nativeCallReference.ts b/src/domain/native/nativeCallReference.tsnew file mode 100644index 000000000..aa8a6e3b2--- /dev/null+++ b/src/domain/native/nativeCallReference.ts@@ -0,0 +1,15 @@+import { z } from "zod";++/** Partial provider classification; it does not establish generic reference flags. */+export const nativeCallClassificationSchema = z.strictObject({+ classification: z.enum(["none", "unknown", "direct", "objective_c"]),+ provider_type: z.number().int(),+ provenance: z.string().min(1),+});++/** Original provider endpoints, before resolving a containing procedure. */+export const nativeCallReferenceSchema = nativeCallClassificationSchema.extend({+ source_address: z.string(),+ target_address: z.string(),+});+export type NativeCallReference = z.infer<typeof nativeCallReferenceSchema>;diff --git a/src/domain/native/objcSwiftMetadata.ts b/src/domain/native/objcSwiftMetadata.tsindex 89afb599e..85649ece2 100644--- a/src/domain/native/objcSwiftMetadata.ts+++ b/src/domain/native/objcSwiftMetadata.ts@@ -2,6 +2,7 @@ import { z } from "zod";import { isMachOFormat, type BinaryTarget } from "../binaryTargetTypes.js";import { providerSchema } from "../evidence.js";import { isSwiftMangledSymbolName } from "../swiftSymbolClassification.js";+import { nativeCallReferenceSchema } from "./nativeCallReference.js";import {compareUnicodeCodePoints,@@ -126,6 +127,7 @@ export const nativeMetadataEvidenceSchema = z.strictObject({location: nativeMetadataLocationSchema,/** Preserve a provider's source value when it does not establish a location. */reported_address: z.string().optional(),+ call_reference: nativeCallReferenceSchema.exactOptional(),artifact_path: z.string().min(1).nullable().default(null),artifact_sha256: z.string()diff --git a/tests/boundary/mcp/nativeUiPartialCallRoutesMcp.test.ts b/tests/boundary/mcp/nativeUiPartialCallRoutesMcp.test.tsindex 22440563a..baa844025 100644--- a/tests/boundary/mcp/nativeUiPartialCallRoutesMcp.test.ts+++ b/tests/boundary/mcp/nativeUiPartialCallRoutesMcp.test.ts@@ -52,14 +52,40 @@ function typedKind(indirect = false) {external: false,};}-function ref(site: string, target: string, indirect = false) {+type CallReference = {+ readonly classification: "none" | "unknown" | "direct" | "objective_c";+ readonly provider_type: number;+ readonly provenance: string;+};+function ref(+ site: string,+ target: string,+ indirect = false,+ callReference?: CallReference,+ targetProcedure = target,+) {return {source_address: site,target_address: target,- target_procedure: { address: target },- kind: typedKind(indirect),+ target_procedure: { address: targetProcedure },+ kind:+ callReference === undefined+ ? typedKind(indirect)+ : {+ available: false as const,+ reason: "Detailed reference-kind flags unavailable",+ },+ ...(callReference === undefined ? {} : { call: callReference }),};}+const partialCall = (+ classification: CallReference["classification"],+ provider_type: number,+): CallReference => ({+ classification,+ provider_type,+ provenance: "hopper-public-python-api:CallReference",+});const mixedReferences = (refs = [ref("0x1004", "0x2000")]) => ({reference_kinds_available: false,references: [@@ -85,12 +111,12 @@ const noClassifiedReferences = {};type Plan = {- readonly references?: ReturnType<typeof mixedReferences>;+ readonly references?: unknown;readonly callees?: readonly string[];readonly fallbackProvider?: typeof identity;readonly fallbackFailure?: "unavailable" | "output" | "cancelled";};-function publicTrace(plan: Plan, maxNodes = 12) {+function publicTrace(plan: Plan, maxNodes = 12, maxEdges = 500) {const analysis: AnalysisOperationPort = {execute: async (operation,@@ -173,7 +199,12 @@ function publicTrace(plan: Plan, maxNodes = 12) {await client.connect(clientTransport);const result = await client.callTool({name: "trace_native_ui_action",- arguments: { action: "0x1000", max_nodes: maxNodes, max_depth: 1 },+ arguments: {+ action: "0x1000",+ max_nodes: maxNodes,+ max_edges: maxEdges,+ max_depth: 1,+ },});return result;})();@@ -421,7 +452,267 @@ it("retains separate omitted callsites when routes share a target", async () =>});it("keeps cancellation terminal when fallback enumeration is cancelled", async () => {- const response = await publicTrace({ fallbackFailure: "cancelled" });+ const response = await publicTrace({+ references: completeReferences([+ ref("0x1004", "0x2000", false, partialCall("direct", 2)),+ ]),+ fallbackFailure: "cancelled",+ });expect(response.isError).toBe(true);expect(parseMcpToolError(response).error.code).toBe("cancelled");});++it.each([+ { classification: "direct", provider_type: 2 },+ { classification: "objective_c", provider_type: 3 },+ { classification: "none", provider_type: 0 },+ { classification: "unknown", provider_type: 1 },+ { classification: "unknown", provider_type: 99 },+] as const)(+ "retains raw $classification CallReference facts without inventing generic flags",+ async ({ classification, provider_type }) => {+ const call = partialCall(classification, provider_type);+ const response = await publicTrace({+ references: completeReferences([+ ref("0x1004", "0x2000", false, call, "0x2fff"),+ ]),+ callees: [],+ });+ expect(response.isError).not.toBe(true);+ const trace = traceFrom(response);+ expect(trace.edges).toContainEqual(+ expect.objectContaining({+ from: "native:function:0x1000",+ to: "native:function:0x2fff",+ relation: "provider_call",+ resolution: "observed",+ evidence: expect.arrayContaining([+ expect.objectContaining({+ provider: identity,+ location: expect.objectContaining({ address: "0x1004" }),+ call_reference: {+ ...call,+ source_address: "0x1004",+ target_address: "0x2000",+ },+ }),+ ]),+ }),+ );+ expect(trace.edges.some((edge) => edge.relation === "objc_dispatch")).toBe(+ false,+ );+ },+);++it("deduplicates fallback overlap while preserving CallReference site and provider", async () => {+ const call = partialCall("direct", 2);+ const response = await publicTrace({+ references: completeReferences([ref("0x1004", "0x2000", false, call)]),+ callees: ["0x2000", "0x3000"],+ });+ expect(response.isError).not.toBe(true);+ const trace = traceFrom(response);+ const targetEdges = trace.edges.filter(+ (edge) => edge.to === "native:function:0x2000",+ );+ expect(targetEdges).toHaveLength(1);+ expect(targetEdges[0]).toMatchObject({+ relation: "provider_call",+ resolution: "observed",+ evidence: [+ expect.objectContaining({+ provider: identity,+ location: expect.objectContaining({ address: "0x1004" }),+ call_reference: expect.objectContaining({+ classification: "direct",+ provider_type: 2,+ provenance: "hopper-public-python-api:CallReference",+ source_address: "0x1004",+ target_address: "0x2000",+ }),+ }),+ ],+ });+});++it.each(["unavailable", "output"] as const)(+ "preserves partial CallReference evidence when fallback has %s failure",+ async (fallbackFailure) => {+ const call = partialCall("direct", 2);+ const response = await publicTrace({+ references: completeReferences([+ ref("0x1004", "0x2000", false, call, "0x2fff"),+ ]),+ fallbackFailure,+ });+ expect(response.isError).not.toBe(true);+ const trace = traceFrom(response);+ expect(trace.edges).toContainEqual(+ expect.objectContaining({+ to: "native:function:0x2fff",+ relation: "provider_call",+ resolution: "observed",+ evidence: expect.arrayContaining([+ expect.objectContaining({+ provider: identity,+ location: expect.objectContaining({ address: "0x1004" }),+ call_reference: expect.objectContaining({+ ...call,+ source_address: "0x1004",+ target_address: "0x2000",+ }),+ }),+ ]),+ }),+ );+ expect(trace.unresolved).toContainEqual(+ expect.objectContaining({+ to: null,+ relation: "provider_call",+ resolution: "unresolved",+ limitations: expect.arrayContaining([+ "The provider could not complete callee enumeration.",+ ]),+ }),+ );+ },+);++it("keeps partial CallReference evidence on a node-bound unresolved edge", async () => {+ const response = await publicTrace(+ {+ references: completeReferences([+ ref("0x1004", "0x2000", false, partialCall("direct", 2)),+ ref("0x1008", "0x3000", false, partialCall("unknown", 99)),+ ]),+ callees: [],+ },+ 2,+ );+ expect(response.isError).not.toBe(true);+ const trace = traceFrom(response);+ expect(trace.unresolved).toContainEqual(+ expect.objectContaining({+ relation: "provider_call",+ resolution: "unresolved",+ evidence: expect.arrayContaining([+ expect.objectContaining({+ provider: identity,+ location: expect.objectContaining({ address: "0x1008" }),+ call_reference: expect.objectContaining({+ classification: "unknown",+ provider_type: 99,+ source_address: "0x1008",+ target_address: "0x3000",+ }),+ }),+ ]),+ }),+ );+});++it("reports malformed partial CallReference as unreadable route evidence", async () => {+ const response = await publicTrace({+ references: {+ reference_kinds_available: false,+ references: [+ {+ ...ref("0x1004", "0x2000"),+ kind: { available: false, reason: "Detailed flags unavailable" },+ call: {+ classification: "objectivec",+ provider_type: 3,+ provenance: "hopper-public-python-api:CallReference",+ },+ },+ ],+ unresolved_calls: [],+ },+ fallbackFailure: "unavailable",+ });+ expect(response.isError).not.toBe(true);+ const trace = traceFrom(response);+ expect(trace.edges).toEqual([]);+ expect(trace.unresolved).toContainEqual(+ expect.objectContaining({+ relation: "provider_call",+ resolution: "unresolved",+ reason: expect.stringContaining("unreadable result"),+ }),+ );+});++it.each([2, 12])(+ "retains original endpoints on a shared edge at the edge bound (maxNodes=%s)",+ async (maxNodes) => {+ const response = await publicTrace(+ {+ references: completeReferences(+ [+ ref("0x1004", "0x2004", false, partialCall("direct", 2), "0x2000"),+ ref(+ "0x1004",+ "0x2008",+ false,+ partialCall("unknown", 99),+ "0x2000",+ ),+ ref("0x1008", "0x3000", false, partialCall("direct", 2)),+ ].reverse(),+ ),+ callees: [],+ },+ maxNodes,+ 2,+ );+ expect(response.isError).not.toBe(true);+ const trace = traceFrom(response);+ const evidence = [...trace.edges, ...trace.unresolved].flatMap(+ (edge) => edge.evidence,+ );+ expect(evidence.map((item) => item.call_reference)).toEqual(+ expect.arrayContaining([+ expect.objectContaining({ target_address: "0x2004", provider_type: 2 }),+ expect.objectContaining({+ target_address: "0x2008",+ provider_type: 99,+ }),+ ]),+ );+ },+);++it.each([+ { maxNodes: 2, reverse: false },+ { maxNodes: 2, reverse: true },+ { maxNodes: 12, reverse: false },+ { maxNodes: 12, reverse: true },+])(+ "preserves typed and partial relations sharing a site and target ($maxNodes/$reverse)",+ async ({ maxNodes, reverse }) => {+ const references = [+ ref("0x1004", "0x2000"),+ ref("0x1004", "0x2008", false, partialCall("unknown", 99), "0x2000"),+ ];+ const response = await publicTrace(+ {+ references: completeReferences([+ ref("0x1008", "0x3000"),+ ...(reverse ? references.reverse() : references),+ ]),+ callees: [],+ },+ maxNodes,+ );+ expect(response.isError).not.toBe(true);+ const trace = traceFrom(response);+ const routes = [...trace.edges, ...trace.unresolved].filter((edge) =>+ edge.evidence.some((item) => item.location.address === "0x1004"),+ );+ expect(routes.map((edge) => edge.relation).sort()).toEqual([+ "direct_call",+ "provider_call",+ ]);+ },+);