Skip to content

armgit / rea

Public Imported from GitHub
0

Reverse engineer anything with agents, from app behavior down to native binaries.

fix(native): retain partial call routes and omitted sites

morluto65884350ff33
diff --git a/docs/native-investigation.md b/docs/native-investigation.md
index e5abb3a45..8ff828225 100644
--- a/docs/native-investigation.md
+++ b/docs/native-investigation.md
@@ -216,6 +216,13 @@ sites remain distinct. A static route does not establish runtime reachability.
Swift/closure dispatch requires resolved static references; unavailable ABI
forms 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
+failure; cancellation still terminates the request. A node-limit omission keeps
+the route's known relation while marking its target unresolved. Distinct call
+sites to the same omitted target retain separate evidence.
+
Session discovery describes two automatic source routes for this trace:
`authored_ui_dispatch` needs Interface Builder decoding and dispatch metadata;
`native_seed_call_trace` needs native address resolution, dispatch metadata and
diff --git a/src/application/native/NativeCallRoutes.test.ts b/src/application/native/NativeCallRoutes.test.ts
index fa8f12a15..0d6f10b1d 100644
--- a/src/application/native/NativeCallRoutes.test.ts
+++ b/src/application/native/NativeCallRoutes.test.ts
@@ -4,9 +4,40 @@ import { createAnalysisExecution } from "../AnalysisProvider.js";
import { ghidraReferenceEdge } from "../../domain/ghidraValues.fixture.js";
import { jsonValueSchema } from "../../domain/jsonValue.js";
import { err, ok } from "../../domain/result.js";
-import { AnalysisCancelledError } from "../../domain/analysisErrorCore.js";
+import {
+ AnalysisCancelledError,
+ AnalysisCapabilityUnavailableError,
+} from "../../domain/analysisErrorCore.js";
const provider = { id: "fixture", name: "Fixture", version: "1" };
+const callReference = (source: string, target: string) => ({
+ source_address: source,
+ target_address: target,
+ target_procedure: { address: target },
+ kind: {
+ available: true as const,
+ provenance: "fixture-reference",
+ type: "UNCONDITIONAL_CALL",
+ flow: true,
+ call: true,
+ jump: false,
+ data: false,
+ read: false,
+ write: false,
+ indirect: false,
+ computed: false,
+ external: false,
+ conditional: false,
+ terminal: false,
+ primary: true,
+ operand_index: 0,
+ },
+});
+
+const unavailableCallKind = {
+ available: false as const,
+ reason: "Reference kind is unavailable.",
+};
describe("untyped native call route fallback", () => {
it.each([{ callees: [] }, { callees: ["0x2000"] }])(
"preserves targetless calls and their provider when fallback callees are $callees",
@@ -50,35 +81,343 @@ describe("untyped native call route fallback", () => {
);
expect(calls).toEqual(["procedure_references", "procedure_callees"]);
expect(result).toEqual({
- ok: true,
- value: {
+ routes: callees.map((address) => ({
provider: fallbackProvider,
- routes: callees.map((address) => ({
- address,
+ address,
+ site: "0x1000",
+ relation: "provider_call",
+ resolution: "inferred",
+ })),
+ unknowns: [{ ...unknown, provider: referenceProvider }],
+ limitations: [
+ {
+ provider: referenceProvider,
+ operation: "procedure_references",
+ limitation: "Reference-kind metadata is incomplete.",
+ },
+ {
+ provider: fallbackProvider,
+ operation: "procedure_callees",
+ limitation: "Callee enumeration is limited to named functions.",
+ },
+ ],
+ outcome: { ok: true, value: undefined },
+ });
+ },
+ );
+});
+
+describe("partially typed native call routes", () => {
+ it.each([false, true])(
+ "keeps known typed calls when an individual kind is unavailable (aggregate=$0)",
+ async (referenceKindsAvailable) => {
+ const typedProvider = { ...provider, id: "typed" };
+ const fallbackProvider = { ...provider, id: "fallback" };
+ const result = await readNativeCallRoutes(
+ {
+ execute: async (operation) =>
+ operation === "procedure_references"
+ ? ok(
+ createAnalysisExecution(
+ {
+ reference_kinds_available: referenceKindsAvailable,
+ references: [
+ callReference("0x1004", "0x2000"),
+ {
+ ...callReference("0x1008", "0x3000"),
+ kind: unavailableCallKind,
+ },
+ ],
+ unresolved_calls: [],
+ },
+ typedProvider,
+ { limitations: ["Some reference kinds are unavailable."] },
+ ),
+ )
+ : ok(
+ createAnalysisExecution(
+ ["0x2000", "0x3000", "0x4000"],
+ fallbackProvider,
+ { limitations: ["Callee enumeration is incomplete."] },
+ ),
+ ),
+ },
+ "0x1000",
+ );
+
+ expect(result).toEqual({
+ routes: [
+ {
+ provider: typedProvider,
+ address: "0x2000",
+ site: "0x1004",
+ relation: "direct_call",
+ resolution: "observed",
+ },
+ {
+ provider: fallbackProvider,
+ address: "0x3000",
site: "0x1000",
relation: "provider_call",
resolution: "inferred",
- })),
- unknowns: [{ ...unknown, provider: referenceProvider }],
- limitations: [
- {
- provider: referenceProvider,
- operation: "procedure_references",
- limitation: "Reference-kind metadata is incomplete.",
- },
- {
- provider: fallbackProvider,
- operation: "procedure_callees",
- limitation: "Callee enumeration is limited to named functions.",
- },
- ],
- },
+ },
+ {
+ provider: fallbackProvider,
+ address: "0x4000",
+ site: "0x1000",
+ relation: "provider_call",
+ resolution: "inferred",
+ },
+ ],
+ unknowns: [],
+ limitations: [
+ {
+ provider: typedProvider,
+ operation: "procedure_references",
+ limitation: "Some reference kinds are unavailable.",
+ },
+ {
+ provider: fallbackProvider,
+ operation: "procedure_callees",
+ limitation: "Callee enumeration is incomplete.",
+ },
+ ],
+ outcome: { ok: true, value: undefined },
});
},
);
+
+ it("preserves distinct typed sites when fallback overlaps their target", async () => {
+ const typedProvider = { ...provider, id: "typed" };
+ const fallbackProvider = { ...provider, id: "fallback" };
+ const result = await readNativeCallRoutes(
+ {
+ execute: async (operation) =>
+ operation === "procedure_references"
+ ? ok(
+ createAnalysisExecution(
+ {
+ reference_kinds_available: false,
+ references: [
+ callReference("0x1004", "0x2000"),
+ callReference("0x1008", "0x2000"),
+ {
+ ...callReference("0x100c", "0x4000"),
+ kind: unavailableCallKind,
+ },
+ ],
+ unresolved_calls: [],
+ },
+ typedProvider,
+ ),
+ )
+ : ok(
+ createAnalysisExecution(["0x2000", "0x3000"], fallbackProvider),
+ ),
+ },
+ "0x1000",
+ );
+
+ expect(result).toEqual({
+ routes: [
+ {
+ provider: typedProvider,
+ address: "0x2000",
+ site: "0x1004",
+ relation: "direct_call",
+ resolution: "observed",
+ },
+ {
+ provider: typedProvider,
+ address: "0x2000",
+ site: "0x1008",
+ relation: "direct_call",
+ resolution: "observed",
+ },
+ {
+ provider: fallbackProvider,
+ address: "0x3000",
+ site: "0x1000",
+ relation: "provider_call",
+ resolution: "inferred",
+ },
+ ],
+ unknowns: [],
+ limitations: [],
+ outcome: { ok: true, value: undefined },
+ });
+ });
});
-describe("typed native call routes", () => {
+describe("native call fallback output failures", () => {
+ it("retains source limitations when fallback output is invalid", async () => {
+ const typedProvider = { ...provider, id: "typed" };
+ const fallbackProvider = { ...provider, id: "fallback" };
+ const result = await readNativeCallRoutes(
+ {
+ execute: async (operation) =>
+ operation === "procedure_references"
+ ? err(
+ new AnalysisCapabilityUnavailableError(
+ typedProvider.id,
+ "procedure_references",
+ "Typed references are unavailable.",
+ ),
+ )
+ : ok(
+ createAnalysisExecution(
+ { callees: "not-an-address-list" },
+ fallbackProvider,
+ { limitations: ["Fallback output is truncated."] },
+ ),
+ ),
+ },
+ "0x1000",
+ );
+
+ expect(result).toMatchObject({
+ routes: [],
+ unknowns: [],
+ limitations: [
+ {
+ provider: fallbackProvider,
+ operation: "procedure_callees",
+ limitation: "Fallback output is truncated.",
+ },
+ ],
+ outcome: {
+ ok: false,
+ error: { _tag: "AnalysisOutputError" },
+ },
+ });
+ });
+
+ it("retains known typed routes when fallback output is invalid", async () => {
+ const typedProvider = { ...provider, id: "typed" };
+ const fallbackProvider = { ...provider, id: "fallback" };
+ const result = await readNativeCallRoutes(
+ {
+ execute: async (operation) =>
+ operation === "procedure_references"
+ ? ok(
+ createAnalysisExecution(
+ {
+ reference_kinds_available: false,
+ references: [
+ callReference("0x1004", "0x2000"),
+ {
+ ...callReference("0x1008", "0x3000"),
+ kind: unavailableCallKind,
+ },
+ ],
+ unresolved_calls: [],
+ },
+ typedProvider,
+ { limitations: ["One call kind remains unavailable."] },
+ ),
+ )
+ : ok(
+ createAnalysisExecution(
+ { callees: "not-an-address-list" },
+ fallbackProvider,
+ { limitations: ["Fallback output is truncated."] },
+ ),
+ ),
+ },
+ "0x1000",
+ );
+
+ expect(result).toMatchObject({
+ routes: [
+ {
+ provider: typedProvider,
+ address: "0x2000",
+ site: "0x1004",
+ relation: "direct_call",
+ resolution: "observed",
+ },
+ ],
+ unknowns: [],
+ limitations: [
+ {
+ provider: typedProvider,
+ operation: "procedure_references",
+ limitation: "One call kind remains unavailable.",
+ },
+ {
+ provider: fallbackProvider,
+ operation: "procedure_callees",
+ limitation: "Fallback output is truncated.",
+ },
+ ],
+ outcome: {
+ ok: false,
+ error: { _tag: "AnalysisOutputError" },
+ },
+ });
+ });
+});
+
+describe("native call fallback cancellation", () => {
+ it("keeps known typed routes when fallback is cancelled", async () => {
+ let calls = 0;
+ const referenceProvider = { ...provider, id: "references" };
+ const result = await readNativeCallRoutes(
+ {
+ execute: async (operation) => {
+ calls += 1;
+ return operation === "procedure_references"
+ ? ok(
+ createAnalysisExecution(
+ {
+ reference_kinds_available: false,
+ references: [
+ callReference("0x1004", "0x2000"),
+ {
+ ...callReference("0x1008", "0x3000"),
+ kind: unavailableCallKind,
+ },
+ ],
+ unresolved_calls: [],
+ },
+ referenceProvider,
+ { limitations: ["One call kind remains unavailable."] },
+ ),
+ )
+ : err(new AnalysisCancelledError("procedure_callees"));
+ },
+ },
+ "0x1000",
+ );
+
+ expect(result).toMatchObject({
+ routes: [
+ {
+ provider: referenceProvider,
+ address: "0x2000",
+ site: "0x1004",
+ relation: "direct_call",
+ resolution: "observed",
+ },
+ ],
+ unknowns: [],
+ limitations: [
+ {
+ provider: referenceProvider,
+ operation: "procedure_references",
+ limitation: "One call kind remains unavailable.",
+ },
+ ],
+ outcome: {
+ ok: false,
+ error: { _tag: "AnalysisCancelledError" },
+ },
+ });
+ expect(calls).toBe(2);
+ });
+});
+
+describe("complete typed native call routes", () => {
it("preserves computed targets, ambiguity and targetless call sites", async () => {
const reference = jsonValueSchema.parse(ghidraReferenceEdge());
if (
@@ -87,13 +426,15 @@ describe("typed native call routes", () => {
Array.isArray(reference)
)
throw new TypeError("Invalid reference fixture");
+ const calls: string[] = [];
const result = await readNativeCallRoutes(
{
- execute: async () =>
- ok(
+ execute: async (operation) => {
+ calls.push(operation);
+ return ok(
createAnalysisExecution(
{
- reference_kinds_available: true,
+ reference_kinds_available: false,
references: ["0x2000", "0x3000"].map((address) => ({
...reference,
source_address: "0x1004",
@@ -125,36 +466,41 @@ describe("typed native call routes", () => {
provider,
{ limitations: ["SEH handler targets may be outside the body."] },
),
- ),
+ );
+ },
},
"0x1000",
);
expect(result).toMatchObject({
- ok: true,
- value: {
- routes: [
- {
- address: "0x2000",
- relation: "indirect_call",
- resolution: "ambiguous",
- },
- {
- address: "0x3000",
- relation: "indirect_call",
- resolution: "ambiguous",
- },
- ],
- unknowns: [{ address: "0x1008" }],
- limitations: [
- {
- provider,
- operation: "procedure_references",
- limitation: "SEH handler targets may be outside the body.",
- },
- ],
- },
+ routes: [
+ {
+ provider,
+ address: "0x2000",
+ relation: "indirect_call",
+ resolution: "ambiguous",
+ },
+ {
+ provider,
+ address: "0x3000",
+ relation: "indirect_call",
+ resolution: "ambiguous",
+ },
+ ],
+ unknowns: [{ address: "0x1008", provider }],
+ limitations: [
+ {
+ provider,
+ operation: "procedure_references",
+ limitation: "SEH handler targets may be outside the body.",
+ },
+ ],
+ outcome: { ok: true, value: undefined },
});
+ expect(calls).toEqual(["procedure_references"]);
});
+});
+
+describe("malformed typed native call output", () => {
it("does not fall back on cancellation or invalid typed output", async () => {
let calls = 0;
const cancelled = await readNativeCallRoutes(
@@ -167,8 +513,10 @@ describe("typed native call routes", () => {
"0x1000",
);
expect(cancelled).toMatchObject({
- ok: false,
- error: { _tag: "AnalysisCancelledError" },
+ routes: [],
+ unknowns: [],
+ limitations: [],
+ outcome: { ok: false, error: { _tag: "AnalysisCancelledError" } },
});
expect(calls).toBe(1);
const malformed = await readNativeCallRoutes(
@@ -183,8 +531,8 @@ describe("typed native call routes", () => {
"0x1000",
);
expect(malformed).toMatchObject({
- ok: false,
- error: { _tag: "AnalysisOutputError" },
+ routes: [],
+ unknowns: [],
limitations: [
{
provider,
@@ -192,8 +540,12 @@ describe("typed native call routes", () => {
limitation: "Malformed output still has source caveats.",
},
],
+ outcome: { ok: false, error: { _tag: "AnalysisOutputError" } },
});
});
+});
+
+describe("missing unresolved-call observations", () => {
it("rejects omitted unresolved-call observations instead of claiming none", async () => {
let calls = 0;
const result = await readNativeCallRoutes(
@@ -215,8 +567,10 @@ describe("typed native call routes", () => {
);
expect(result).toMatchObject({
- ok: false,
- error: { _tag: "AnalysisOutputError" },
+ routes: [],
+ unknowns: [],
+ limitations: [],
+ outcome: { ok: false, error: { _tag: "AnalysisOutputError" } },
});
expect(calls).toBe(1);
});
diff --git a/src/application/native/NativeCallRoutes.ts b/src/application/native/NativeCallRoutes.ts
index 59b97cf17..f4018b0a5 100644
--- a/src/application/native/NativeCallRoutes.ts
+++ b/src/application/native/NativeCallRoutes.ts
@@ -9,6 +9,8 @@ import {
referenceKindSchema,
} from "../../domain/hopperValues.js";
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";
/** Preferred typed observations and the untyped fallback share one owner. */
@@ -39,9 +41,30 @@ const referencesSchema = z.object({
),
});
+interface NativeCallRoute {
+ readonly address: string;
+ readonly site: string;
+ readonly relation: "direct_call" | "indirect_call" | "provider_call";
+ readonly resolution: "observed" | "resolved" | "ambiguous" | "inferred";
+ readonly provider: ProviderIdentity;
+}
+
+/** Enumeration failure does not invalidate facts already obtained. */
+interface NativeCallRouteRead {
+ readonly routes: readonly NativeCallRoute[];
+ readonly unknowns: readonly {
+ address: string;
+ reason: string;
+ provider: ProviderIdentity;
+ }[];
+ readonly limitations: readonly SourceLimitation[];
+ readonly outcome: Result<void, AnalysisError>;
+}
+
const typedCallRoutes = (
references: z.infer<typeof referencesSchema>["references"],
-) => {
+ provider: ProviderIdentity,
+): NativeCallRoute[] => {
const calls = references.filter(({ kind }) => kind.available && kind.call);
const countBySite = new Map<string, Set<string>>();
for (const call of calls) {
@@ -50,6 +73,7 @@ const typedCallRoutes = (
countBySite.set(call.source_address, targets);
}
return calls.map((call) => ({
+ provider,
address: call.target_procedure?.address ?? call.target_address,
site: call.source_address,
relation:
@@ -65,13 +89,13 @@ const typedCallRoutes = (
}));
};
-/** Prefer typed static call references, preserving computed targets and targetless sites. */
+/** Retain typed observations while supplementing incomplete kinds with inferred callees. */
export const readNativeCallRoutes = async (
analysis: AnalysisOperationPort,
procedure: string,
signal?: AbortSignal,
selectorOrigin?: ExecutionOptions["selectorOrigin"],
-) => {
+): Promise<NativeCallRouteRead> => {
const options = {
...(signal === undefined ? {} : { signal }),
...(selectorOrigin === undefined ? {} : { selectorOrigin }),
@@ -81,88 +105,85 @@ export const readNativeCallRoutes = async (
{ procedure, direction: "outgoing" },
options,
);
- let unknowns: Array<{
+ const routes: NativeCallRoute[] = [];
+ const unknowns: Array<{
address: string;
reason: string;
provider: ProviderIdentity;
}> = [];
- let limitations: SourceLimitation[] = [];
+ const limitations: SourceLimitation[] = [];
+ const finish = (
+ outcome: Result<void, AnalysisError>,
+ ): NativeCallRouteRead => ({
+ routes,
+ unknowns,
+ limitations,
+ outcome,
+ });
if (execution.ok) {
- limitations = limitationsFrom(
- NATIVE_CALL_ROUTE_SOURCES.references,
- execution.value.provider,
- execution.value.limitations,
+ limitations.push(
+ ...limitationsFrom(
+ NATIVE_CALL_ROUTE_SOURCES.references,
+ execution.value.provider,
+ execution.value.limitations,
+ ),
);
const parsed = referencesSchema.safeParse(execution.value.result);
if (!parsed.success)
- return {
- ok: false as const,
- error: new AnalysisOutputError(
- NATIVE_CALL_ROUTE_SOURCES.references,
- "Invalid typed call references",
+ return finish(
+ err(
+ new AnalysisOutputError(
+ NATIVE_CALL_ROUTE_SOURCES.references,
+ "Invalid typed call references",
+ ),
),
- unknowns,
- limitations,
- };
+ );
// Missing detailed reference flags do not invalidate observed targetless
// calls. Keep their producing provider even if another provider supplies
// the fallback callee inventory.
- unknowns = parsed.data.unresolved_calls.map((call) => ({
- ...call,
- provider: execution.value.provider,
- }));
+ unknowns.push(
+ ...parsed.data.unresolved_calls.map((call) => ({
+ ...call,
+ provider: execution.value.provider,
+ })),
+ );
const references = parsed.data.references;
+ routes.push(...typedCallRoutes(references, execution.value.provider));
if (
- parsed.data.reference_kinds_available === true ||
- (references.length > 0 && references.every(({ kind }) => kind.available))
- ) {
- return {
- ok: true as const,
- value: {
- provider: execution.value.provider,
- routes: typedCallRoutes(references),
- unknowns,
- limitations,
- },
- };
- }
+ references.every(({ kind }) => kind.available) &&
+ (parsed.data.reference_kinds_available || references.length > 0)
+ )
+ return finish(ok(undefined));
} else if (execution.error._tag !== "AnalysisCapabilityUnavailableError")
- return {
- ok: false as const,
- error: execution.error,
- unknowns,
- limitations,
- };
+ return finish(err(execution.error));
const callees = await analysis.execute(
NATIVE_CALL_ROUTE_SOURCES.callees,
{ procedure },
options,
);
- if (!callees.ok)
- return { ok: false as const, error: callees.error, unknowns, limitations };
- limitations = [
- ...limitations,
+ if (!callees.ok) return finish(err(callees.error));
+ limitations.push(
...limitationsFrom(
NATIVE_CALL_ROUTE_SOURCES.callees,
callees.value.provider,
callees.value.limitations,
),
- ];
+ );
const parsed = parseRelatedAddresses(callees.value.result, "callees");
- return parsed.ok
- ? {
- ok: true as const,
- value: {
- provider: callees.value.provider,
- routes: parsed.value.map((address) => ({
- address,
- site: procedure,
- relation: "provider_call" as const,
- resolution: "inferred" as const,
- })),
- unknowns,
- limitations,
- },
- }
- : { ok: false as const, error: parsed.error, unknowns, limitations };
+ if (!parsed.ok) return finish(err(parsed.error));
+ // Keep every observed call site. A target-only fallback cannot replace one,
+ // and repeated fallback targets add no new observation.
+ const targets = new Set(routes.map(({ address }) => address));
+ for (const address of parsed.value) {
+ if (targets.has(address)) continue;
+ targets.add(address);
+ routes.push({
+ address,
+ site: procedure,
+ relation: "provider_call",
+ resolution: "inferred",
+ provider: callees.value.provider,
+ });
+ }
+ return finish(ok(undefined));
};
diff --git a/src/application/native/NativeUiActionTrace.ts b/src/application/native/NativeUiActionTrace.ts
index e413a07b3..bc67af6c4 100644
--- a/src/application/native/NativeUiActionTrace.ts
+++ b/src/application/native/NativeUiActionTrace.ts
@@ -202,7 +202,7 @@ export const traceNativeUiAction = async (
max_edges: input.max_edges,
},
});
- const expanded = await addDirectCallees({
+ const expanded = await expandNativeCalls({
analysis,
graph,
initial,
@@ -372,7 +372,7 @@ const resolveUiAction = (
};
};
-const addDirectCallees = async (input: {
+const expandNativeCalls = async (input: {
readonly analysis: AnalysisOperationPort;
readonly graph: z.infer<typeof nativeInvestigationGraphSchema>;
readonly initial: z.infer<typeof nativeInvestigationTraceSchema>;
@@ -435,14 +435,13 @@ const addDirectCallees = async (input: {
"provider",
);
examined += 1;
- sourceLimitations.push(
- ...(execution.ok ? execution.value.limitations : execution.limitations),
- );
- if (!execution.ok && execution.error._tag === "AnalysisCancelledError")
- return { error: execution.error };
- const unknowns = execution.ok
- ? execution.value.unknowns
- : execution.unknowns;
+ sourceLimitations.push(...execution.limitations);
+ if (
+ !execution.outcome.ok &&
+ execution.outcome.error._tag === "AnalysisCancelledError"
+ )
+ return { error: execution.outcome.error };
+ const unknowns = execution.unknowns;
for (const [index, unknown] of unknowns.entries()) {
if (edges.size >= input.input.max_edges) {
truncated = true;
@@ -470,40 +469,19 @@ const addDirectCallees = async (input: {
limitations: [],
});
}
- if (!execution.ok) {
- if (edges.size >= input.input.max_edges) {
- truncated = true;
- omitted += 1;
- continue;
- }
- const id = `unknown-callees:${current.address}`;
- edges.set(id, {
- id,
- from: current.node.id,
- to: null,
- relation: "direct_call",
- resolution: "unresolved",
- reason: projectAnalysisError(execution.error).message,
- evidence: [],
- limitations: [
- "The provider could not enumerate resolved direct callees.",
- ],
- });
- continue;
- }
- for (const [index, route] of execution.value.routes.entries()) {
+ for (const [index, route] of execution.routes.entries()) {
const address = route.address;
if (edges.size >= input.input.max_edges) {
truncated = true;
- omitted += execution.value.routes.length - index;
+ omitted += execution.routes.length - index;
break;
}
const targetId = `native:function:${address}`;
const evidence = [
{
kind: "reference" as const,
- provider: execution.value.provider,
- description: `${execution.value.provider.name} reported ${route.relation} from ${current.address} to ${address}`,
+ 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,
@@ -513,12 +491,12 @@ const addDirectCallees = async (input: {
if (nodes.size >= input.input.max_nodes) {
truncated = true;
omitted += 1;
- const id = `unknown-node-bound:${current.address}:${address}`;
+ const id = `unknown-node-bound:${current.address}:${route.site}:${address}`;
edges.set(id, {
id,
from: current.node.id,
to: null,
- relation: "direct_call",
+ relation: route.relation,
resolution: "unresolved",
reason: "native_trace_node_bound_reached",
evidence,
@@ -532,7 +510,7 @@ const addDirectCallees = async (input: {
kind: "function" as const,
name,
location: { address, file_offset: null },
- attributes: { resolved_by: execution.value.provider.id },
+ attributes: { resolved_by: route.provider.id },
evidence,
};
nodes.set(targetId, node);
@@ -551,6 +529,24 @@ const addDirectCallees = async (input: {
],
});
}
+ if (!execution.outcome.ok) {
+ if (edges.size >= input.input.max_edges) {
+ truncated = true;
+ omitted += 1;
+ continue;
+ }
+ const id = `unknown-callees:${current.address}`;
+ edges.set(id, {
+ id,
+ from: current.node.id,
+ to: null,
+ relation: "provider_call",
+ resolution: "unresolved",
+ reason: projectAnalysisError(execution.outcome.error).message,
+ evidence: [],
+ limitations: ["The provider could not complete callee enumeration."],
+ });
+ }
}
return {
nodes: [...nodes.values()],
diff --git a/tests/boundary/mcp/nativeUiPartialCallRoutesMcp.test.ts b/tests/boundary/mcp/nativeUiPartialCallRoutesMcp.test.ts
new file mode 100644
index 000000000..22440563a
--- /dev/null
+++ b/tests/boundary/mcp/nativeUiPartialCallRoutesMcp.test.ts
@@ -0,0 +1,427 @@
+import { afterEach, expect, it } from "vitest";
+import { Client, InMemoryTransport } from "@modelcontextprotocol/client";
+import { z } from "zod";
+import type {
+ AnalysisExecution,
+ AnalysisOperationPort,
+} from "../../../src/application/AnalysisProvider.js";
+import type { AnalysisError } from "../../../src/domain/analysisErrorBase.js";
+import { createAnalysisExecution } from "../../../src/application/AnalysisProvider.js";
+import {
+ AnalysisCancelledError,
+ AnalysisCapabilityUnavailableError,
+ AnalysisOutputError,
+} from "../../../src/domain/analysisErrorCore.js";
+import { inspectNativeDispatchMetadata } from "../../../src/domain/native/objcSwiftMetadata.js";
+import { nativeInvestigationTraceSchema } from "../../../src/domain/native/nativeInvestigationGraph.js";
+import { err, ok, type Result } from "../../../src/domain/result.js";
+import { createServer } from "../../../src/server/createServer.js";
+import { parseMcpToolError } from "../../fixtures/mcpToolError.js";
+
+const identity = { id: "typed", name: "Typed provider", version: "1" };
+const fallback = { id: "fallback", name: "Fallback provider", version: "1" };
+const sha256 = "a".repeat(64);
+const subject = {
+ sha256,
+ path: "/fixture",
+ format: "mach-o",
+ architecture: "arm64",
+} as const;
+const resources: Array<{ close(): Promise<unknown> }> = [];
+afterEach(async () =>
+ Promise.all(resources.splice(0).map((resource) => resource.close())),
+);
+
+function typedKind(indirect = false) {
+ return {
+ available: true,
+ provenance: "fixture reference classification",
+ type: "call",
+ flow: true,
+ call: true,
+ jump: false,
+ data: false,
+ read: false,
+ write: false,
+ indirect,
+ computed: indirect,
+ conditional: false,
+ terminal: false,
+ primary: true,
+ operand_index: 0,
+ external: false,
+ };
+}
+function ref(site: string, target: string, indirect = false) {
+ return {
+ source_address: site,
+ target_address: target,
+ target_procedure: { address: target },
+ kind: typedKind(indirect),
+ };
+}
+const mixedReferences = (refs = [ref("0x1004", "0x2000")]) => ({
+ reference_kinds_available: false,
+ references: [
+ ...refs,
+ {
+ source_address: "0x1008",
+ target_address: "0x9000",
+ target_procedure: { address: "0x9000" },
+ kind: { available: false, reason: "classification unavailable" },
+ },
+ ],
+ unresolved_calls: [],
+});
+const completeReferences = (refs: ReturnType<typeof ref>[]) => ({
+ reference_kinds_available: true,
+ references: refs,
+ unresolved_calls: [],
+});
+const noClassifiedReferences = {
+ reference_kinds_available: false,
+ references: [],
+ unresolved_calls: [],
+};
+
+type Plan = {
+ readonly references?: ReturnType<typeof mixedReferences>;
+ readonly callees?: readonly string[];
+ readonly fallbackProvider?: typeof identity;
+ readonly fallbackFailure?: "unavailable" | "output" | "cancelled";
+};
+function publicTrace(plan: Plan, maxNodes = 12) {
+ const analysis: AnalysisOperationPort = {
+ execute: async (
+ operation,
+ parameters,
+ ): Promise<Result<AnalysisExecution, AnalysisError>> => {
+ if (operation === "decode_interface_builder")
+ return err(
+ new AnalysisCapabilityUnavailableError(
+ identity.id,
+ operation,
+ "No authored UI fixture",
+ ),
+ );
+ if (operation === "inspect_native_dispatch_metadata")
+ return ok(
+ createAnalysisExecution(
+ {
+ target_sha256: sha256,
+ provider: identity,
+ analysis_profile_digest: null,
+ result: inspectNativeDispatchMetadata([]),
+ },
+ identity,
+ { subject },
+ ),
+ );
+ if (operation === "procedure_address")
+ return ok(createAnalysisExecution("0x1000", identity, { subject }));
+ if (operation === "procedure_references")
+ return ok(
+ createAnalysisExecution(
+ plan.references ?? mixedReferences(),
+ identity,
+ { subject },
+ ),
+ );
+ if (operation === "procedure_callees") {
+ if (plan.fallbackFailure === "unavailable")
+ return err(
+ new AnalysisCapabilityUnavailableError(
+ identity.id,
+ operation,
+ "enumeration unavailable in fixture",
+ ),
+ );
+ if (plan.fallbackFailure === "output")
+ return err(
+ new AnalysisOutputError(
+ operation,
+ "enumeration output failed in fixture",
+ ),
+ );
+ if (plan.fallbackFailure === "cancelled")
+ return err(new AnalysisCancelledError(operation));
+ return ok(
+ createAnalysisExecution(
+ plan.callees ?? ["0x3000"],
+ plan.fallbackProvider ?? fallback,
+ { subject },
+ ),
+ );
+ }
+ throw new Error(
+ `Unexpected operation ${operation} ${JSON.stringify(parameters)}`,
+ );
+ },
+ };
+ const server = createServer({ kind: "fixed", analysis });
+ const client = new Client({ name: "native-ui-partial-routes", version: "1" });
+ const [clientTransport, serverTransport] =
+ InMemoryTransport.createLinkedPair();
+ resources.push({
+ close: async () => {
+ await client.close();
+ await server.close();
+ },
+ });
+ return (async () => {
+ await server.connect(serverTransport);
+ await client.connect(clientTransport);
+ const result = await client.callTool({
+ name: "trace_native_ui_action",
+ arguments: { action: "0x1000", max_nodes: maxNodes, max_depth: 1 },
+ });
+ return result;
+ })();
+}
+
+const traceFrom = (result: { structuredContent?: unknown }) =>
+ z
+ .object({
+ normalized_result: nativeInvestigationTraceSchema,
+ })
+ .parse(result.structuredContent).normalized_result;
+
+it("keeps typed callsite evidence and distinct fallback-provider routes for mixed reference kinds", async () => {
+ const response = await publicTrace({});
+ expect(response.isError).not.toBe(true);
+ const trace = traceFrom(response);
+ expect(trace.target_sha256).toBe(sha256);
+ expect(trace.edges).toEqual(
+ expect.arrayContaining([
+ expect.objectContaining({
+ from: "native:function:0x1000",
+ to: "native:function:0x2000",
+ relation: "direct_call",
+ resolution: "observed",
+ evidence: expect.arrayContaining([
+ expect.objectContaining({
+ provider: identity,
+ location: expect.objectContaining({ address: "0x1004" }),
+ }),
+ ]),
+ }),
+ expect.objectContaining({
+ from: "native:function:0x1000",
+ to: "native:function:0x3000",
+ relation: "provider_call",
+ resolution: "inferred",
+ evidence: expect.arrayContaining([
+ expect.objectContaining({
+ provider: fallback,
+ location: expect.objectContaining({ address: "0x1000" }),
+ }),
+ ]),
+ }),
+ ]),
+ );
+});
+
+it.each(["unavailable", "output"] as const)(
+ "retains known observed routes when fallback enumeration has %s failure",
+ async (failure) => {
+ const response = await publicTrace({ fallbackFailure: failure });
+ expect(response.isError).not.toBe(true);
+ const trace = traceFrom(response);
+ expect(trace.edges).toContainEqual(
+ expect.objectContaining({
+ from: "native:function:0x1000",
+ to: "native:function:0x2000",
+ relation: "direct_call",
+ resolution: "observed",
+ evidence: expect.arrayContaining([
+ expect.objectContaining({
+ provider: identity,
+ location: expect.objectContaining({ address: "0x1004" }),
+ }),
+ ]),
+ }),
+ );
+ expect(trace.unresolved).toContainEqual(
+ expect.objectContaining({
+ from: "native:function:0x1000",
+ to: null,
+ relation: "provider_call",
+ resolution: "unresolved",
+ reason:
+ failure === "unavailable"
+ ? "This analysis is unavailable for the current target. Choose another analysis or target."
+ : expect.stringContaining("unreadable result"),
+ limitations: expect.arrayContaining([
+ "The provider could not complete callee enumeration.",
+ ]),
+ }),
+ );
+ },
+);
+
+it("deduplicates fallback overlap without erasing multiple typed callsites", async () => {
+ const response = await publicTrace({
+ references: mixedReferences([
+ ref("0x1004", "0x2000"),
+ ref("0x100c", "0x2000"),
+ ]),
+ callees: ["0x2000", "0x3000"],
+ });
+ expect(response.isError).not.toBe(true);
+ const trace = traceFrom(response);
+ const typedEdges = trace.edges.filter(
+ (edge) => edge.to === "native:function:0x2000",
+ );
+ expect(typedEdges).toHaveLength(2);
+ expect(
+ typedEdges
+ .map((edge) => edge.evidence.flatMap((item) => item.location?.address))
+ .flat(),
+ ).toEqual(expect.arrayContaining(["0x1004", "0x100c"]));
+ expect(
+ trace.edges.filter(
+ (edge) =>
+ edge.to === "native:function:0x2000" &&
+ edge.relation === "provider_call",
+ ),
+ ).toHaveLength(0);
+});
+
+it.each([
+ {
+ relation: "direct_call",
+ references: completeReferences([
+ ref("0x1004", "0x2000"),
+ ref("0x1008", "0x3000"),
+ ]),
+ callees: [],
+ firstRelation: "direct_call",
+ firstTarget: "native:function:0x2000",
+ firstResolution: "observed",
+ firstProvider: identity,
+ firstSite: "0x1004",
+ },
+ {
+ relation: "indirect_call",
+ references: completeReferences([
+ ref("0x1004", "0x2000"),
+ ref("0x1008", "0x3000", true),
+ ]),
+ callees: [],
+ firstRelation: "direct_call",
+ firstTarget: "native:function:0x2000",
+ firstResolution: "observed",
+ firstProvider: identity,
+ firstSite: "0x1004",
+ },
+ {
+ relation: "provider_call",
+ references: noClassifiedReferences,
+ callees: ["0x2000", "0x3000"],
+ firstRelation: "provider_call",
+ firstTarget: "native:function:0x2000",
+ firstResolution: "inferred",
+ firstProvider: fallback,
+ firstSite: "0x1000",
+ },
+] as const)(
+ "preserves $relation when node bounds omit a route",
+ async ({
+ relation,
+ callees,
+ references,
+ firstRelation,
+ firstTarget,
+ firstResolution,
+ firstProvider,
+ firstSite,
+ }) => {
+ const response = await publicTrace({ references, callees }, 2);
+ expect(response.isError).not.toBe(true);
+ const trace = traceFrom(response);
+ expect(trace.unresolved).toContainEqual(
+ expect.objectContaining({
+ from: "native:function:0x1000",
+ to: null,
+ relation,
+ resolution: "unresolved",
+ reason: "native_trace_node_bound_reached",
+ }),
+ );
+ expect(trace.edges).toContainEqual(
+ expect.objectContaining({
+ from: "native:function:0x1000",
+ to: firstTarget,
+ relation: firstRelation,
+ resolution: firstResolution,
+ evidence: expect.arrayContaining([
+ expect.objectContaining({
+ provider: firstProvider,
+ location: expect.objectContaining({ address: firstSite }),
+ }),
+ ]),
+ }),
+ );
+ expect(trace.truncated).toBe(true);
+ expect(trace.coverage).toContainEqual(
+ expect.objectContaining({
+ facet: "static_native_calls",
+ status: "partial",
+ }),
+ );
+ expect(trace.limitations).toContain(
+ "Static analysis does not prove that an authored UI action is reachable or executed at runtime.",
+ );
+ },
+);
+
+it("retains separate omitted callsites when routes share a target", async () => {
+ const response = await publicTrace(
+ {
+ references: completeReferences([
+ ref("0x1004", "0x2000"),
+ ref("0x1008", "0x3000", true),
+ ref("0x100c", "0x3000"),
+ ]),
+ callees: [],
+ },
+ 2,
+ );
+ expect(response.isError).not.toBe(true);
+ const trace = traceFrom(response);
+ expect(trace.unresolved).toEqual(
+ expect.arrayContaining([
+ expect.objectContaining({
+ from: "native:function:0x1000",
+ to: null,
+ relation: "indirect_call",
+ resolution: "unresolved",
+ evidence: expect.arrayContaining([
+ expect.objectContaining({
+ provider: identity,
+ location: expect.objectContaining({ address: "0x1008" }),
+ }),
+ ]),
+ }),
+ expect.objectContaining({
+ from: "native:function:0x1000",
+ to: null,
+ relation: "direct_call",
+ resolution: "unresolved",
+ evidence: expect.arrayContaining([
+ expect.objectContaining({
+ provider: identity,
+ location: expect.objectContaining({ address: "0x100c" }),
+ }),
+ ]),
+ }),
+ ]),
+ );
+ expect(trace.truncated).toBe(true);
+});
+
+it("keeps cancellation terminal when fallback enumeration is cancelled", async () => {
+ const response = await publicTrace({ fallbackFailure: "cancelled" });
+ expect(response.isError).toBe(true);
+ expect(parseMcpToolError(response).error.code).toBe("cancelled");
+});