Skip to content

armgit / rea

Public Imported from GitHub
0

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

fix(analysis): preserve relationship coverage across evidence and replay

morluto9c8511409c07
diff --git a/docs/tool-design.md b/docs/tool-design.md
index 934722850..a4dd155f0 100644
--- a/docs/tool-design.md
+++ b/docs/tool-design.md
@@ -55,6 +55,11 @@ satisfy. A plan without execution does not establish runtime behavior.
- Keep observed, derived, and inferred relationships distinct. Preserve
unresolved edges and partial provider facts instead of requiring every
provider to supply the same metadata.
+- For caller/callee reads, `relationship_coverage` describes only the
+ provider-observed direct relationship set. `complete` means that set was
+ returned without a known read limit; it does not claim every possible runtime
+ edge. Provider and execution caveats stay in `limitations` and do not imply
+ incomplete relationship coverage. Missing coverage remains `unknown`.
- Declare process, filesystem, network, UI, and mutation effects truthfully;
enforce the requested target and lifecycle.
- Add limits only for real format, protocol, authority, or measured resource
diff --git a/src/application/AnalysisProvider.ts b/src/application/AnalysisProvider.ts
index d88da6df7..87a717795 100644
--- a/src/application/AnalysisProvider.ts
+++ b/src/application/AnalysisProvider.ts
@@ -15,6 +15,10 @@ import type { ProgressReporter } from "./ProgressReporter.js";
import type { ProviderRejectionCode } from "../contracts/providerSelection.js";
import type { ProcessLineageObservation } from "../process/ProcessOwnership.js";
import type { ProviderOperationHealth } from "../domain/providerOperationHealth.js";
+import {
+ relationshipCoverageSchema,
+ type RelationshipCoverage,
+} from "../domain/relationshipCoverage.js";
export interface ExecutionOptions {
readonly signal?: AbortSignal;
@@ -44,6 +48,8 @@ export interface AnalysisExecution {
readonly provider: ProviderIdentity;
readonly analysisProfile?: AnalysisProfileCommitment;
readonly limitations: readonly string[];
+ /** Provider-owned completeness assessment for caller/callee observations. */
+ readonly relationshipCoverage?: RelationshipCoverage;
readonly locations: readonly EvidenceLocation[];
readonly subject: EvidenceSubjectTarget | null;
}
@@ -62,6 +68,7 @@ export const createAnalysisExecution = (
readonly rawResult?: unknown;
readonly analysisProfile?: AnalysisProfileCommitment;
readonly limitations?: readonly string[];
+ readonly relationshipCoverage?: RelationshipCoverage;
readonly locations?: readonly EvidenceLocation[];
readonly subject?: EvidenceSubjectTarget;
} = {},
@@ -76,6 +83,13 @@ export const createAnalysisExecution = (
? {}
: { analysisProfile: structuredClone(options.analysisProfile) }),
limitations: [...(options.limitations ?? [])],
+ ...(options.relationshipCoverage === undefined
+ ? {}
+ : {
+ relationshipCoverage: relationshipCoverageSchema.parse(
+ options.relationshipCoverage,
+ ),
+ }),
locations: [...(options.locations ?? [])],
subject: options.subject ?? null,
});
diff --git a/src/application/CallPathTracing.ts b/src/application/CallPathTracing.ts
index 66d1aa50c..65628cf32 100644
--- a/src/application/CallPathTracing.ts
+++ b/src/application/CallPathTracing.ts
@@ -10,6 +10,7 @@ import type { JsonValue } from "../domain/jsonValue.js";
import { ok, type Result } from "../domain/result.js";
import type { EnhancedResult } from "./EnhancedToolTypes.js";
import { resolveProcedureAddress } from "./ProcedureAddressResolution.js";
+import type { RelationshipCoverage } from "../domain/relationshipCoverage.js";
type AnalysisCall = (
name: AnalysisOperation,
@@ -51,6 +52,7 @@ interface TraceState {
}>;
readonly residual: Set<string>;
readonly limitations: Set<string>;
+ readonly relationshipCoverage: Map<string, RelationshipCoverage>;
queueIndex: number;
traversalPath: string[];
}
@@ -117,6 +119,7 @@ const createTraceState = (input: CallPathTraceInput): TraceState => ({
failures: [],
residual: new Set(),
limitations: new Set(),
+ relationshipCoverage: new Map(),
queueIndex: 0,
traversalPath: input.goal === input.start ? [input.start] : [],
});
@@ -147,12 +150,22 @@ const expandAddress = async (
state.residual.add(`Call relationships were unreadable for ${address}.`);
return false;
}
- for (const limitation of result.value.limitations) {
+ for (const limitation of result.value.limitations)
state.limitations.add(limitation);
+ const coverage = result.value.relationshipCoverage ?? {
+ status: "unknown",
+ reason: "Provider did not report relationship coverage.",
+ };
+ state.relationshipCoverage.set(address, coverage);
+ if (coverage.status === "partial")
+ for (const limitation of coverage.limitations)
+ state.residual.add(
+ `Call relationships for ${address} are limited: ${limitation}`,
+ );
+ else if (coverage.status === "unknown")
state.residual.add(
- `Call relationships for ${address} are limited: ${limitation}`,
+ `Call relationship coverage is unknown for ${address}: ${coverage.reason}`,
);
- }
for (const relatedAddress of sortedUniqueAddresses(related.value)) {
recordEdge(input, state, {
address,
@@ -228,6 +241,11 @@ const projectTrace = (input: CallPathTraceInput, state: TraceState) => ({
traversal: {
nodes_visited: state.visited.size,
},
+ relationship_coverage: Object.fromEntries(
+ [...state.relationshipCoverage.entries()].sort(([left], [right]) =>
+ compareAddress(left, right),
+ ),
+ ),
truncated: state.residual.size > 0,
residual_unknowns: [...state.residual],
limitations: [
diff --git a/src/application/DirectAnalysis.ts b/src/application/DirectAnalysis.ts
index 2d5ac1762..cc0e358bb 100644
--- a/src/application/DirectAnalysis.ts
+++ b/src/application/DirectAnalysis.ts
@@ -177,6 +177,9 @@ const runManagedProviderAnalysis = async (
result: value.result,
rawResult: value.rawResult,
limitations: value.limitations,
+ ...(value.relationshipCoverage === undefined
+ ? {}
+ : { relationshipCoverage: value.relationshipCoverage }),
locations: value.locations,
});
};
@@ -436,6 +439,9 @@ const executeAnalysisTool = async (input: {
: { analysisProfile: result.value.analysisProfile }),
rawResult: result.value.rawResult,
limitations: result.value.limitations,
+ ...(result.value.relationshipCoverage === undefined
+ ? {}
+ : { relationshipCoverage: result.value.relationshipCoverage }),
locations: result.value.locations,
evidenceLinks:
tool === "inspect_artifact"
diff --git a/src/application/EnhancedTools.ts b/src/application/EnhancedTools.ts
index 7e0b1addf..89c65a41f 100644
--- a/src/application/EnhancedTools.ts
+++ b/src/application/EnhancedTools.ts
@@ -389,6 +389,10 @@ export class EnhancedTools {
address: current.address,
status: "ok",
calls: [...related.value],
+ relationship_coverage: result.value.relationshipCoverage ?? {
+ status: "unknown",
+ reason: "Provider did not report relationship coverage.",
+ },
...(result.value.limitations.length === 0
? {}
: { limitations: [...result.value.limitations] }),
diff --git a/src/application/binary/AnalysisSnapshotCache.test.ts b/src/application/binary/AnalysisSnapshotCache.test.ts
index 15f4e403c..4d57e8a3d 100644
--- a/src/application/binary/AnalysisSnapshotCache.test.ts
+++ b/src/application/binary/AnalysisSnapshotCache.test.ts
@@ -441,7 +441,7 @@ describe("analysis snapshot cache partitioning", () => {
ANALYSIS_SNAPSHOT_PROFILE,
createEvidenceBundle([evidence]),
);
- if (!exported.ok) throw new Error("snapshot export failed");
+ if (!exported.ok) throw exported.error;
const tampered = structuredClone(exported.value);
const tamperedEntry = tampered.entries[0];
if (tamperedEntry === undefined)
@@ -499,3 +499,105 @@ describe("analysis snapshot cache partitioning", () => {
).toBeUndefined();
});
});
+
+describe("relationship coverage snapshot replay", () => {
+ it("authenticates relationship coverage and replays legacy reads as unknown", () => {
+ const cache = new AnalysisSnapshotCache();
+ const operation = "procedure_callees" as const;
+ const parameters = { procedure: "0x1000", document: "fixture" };
+ const coverage = { status: "complete" as const };
+ const execution = createAnalysisExecution(
+ ["0x2000"],
+ ANALYSIS_SNAPSHOT_PROVIDER,
+ {
+ analysisProfile: ANALYSIS_SNAPSHOT_PROFILE,
+ rawResult: ["0x2000"],
+ relationshipCoverage: coverage,
+ subject: {
+ path: ANALYSIS_SNAPSHOT_TARGET.path,
+ sha256: ANALYSIS_SNAPSHOT_TARGET.sha256,
+ format: ANALYSIS_SNAPSHOT_TARGET.format,
+ ...(ANALYSIS_SNAPSHOT_TARGET.architecture === undefined
+ ? {}
+ : { architecture: ANALYSIS_SNAPSHOT_TARGET.architecture }),
+ },
+ },
+ );
+ cache.record({
+ target: ANALYSIS_SNAPSHOT_TARGET,
+ profile: ANALYSIS_SNAPSHOT_PROFILE,
+ operation,
+ parameters,
+ execution,
+ });
+ const evidence = createEvidence(
+ ANALYSIS_SNAPSHOT_TARGET,
+ ANALYSIS_SNAPSHOT_PROVIDER,
+ {
+ operation,
+ parameters,
+ result: ["0x2000"],
+ rawResult: ["0x2000"],
+ analysisProfile: ANALYSIS_SNAPSHOT_PROFILE,
+ relationshipCoverage: coverage,
+ },
+ );
+ const exported = cache.export(
+ ANALYSIS_SNAPSHOT_TARGET,
+ ANALYSIS_SNAPSHOT_PROFILE,
+ createEvidenceBundle([evidence]),
+ );
+ if (!exported.ok) throw exported.error;
+ expect(
+ cache.lookup(
+ ANALYSIS_SNAPSHOT_TARGET,
+ ANALYSIS_SNAPSHOT_PROFILE,
+ operation,
+ parameters,
+ )?.relationshipCoverage,
+ ).toEqual(coverage);
+
+ const tampered = structuredClone(exported.value);
+ const tamperedEntry = tampered.entries[0];
+ if (tamperedEntry === undefined) throw new Error("snapshot entry missing");
+ tamperedEntry.execution.relationship_coverage = {
+ status: "partial",
+ limitations: ["forged coverage"],
+ };
+ expect(
+ new AnalysisSnapshotCache().import(tampered, undefined, () => ok(0)).ok,
+ ).toBe(false);
+
+ const legacy = structuredClone(exported.value);
+ const legacyEntry = legacy.entries[0];
+ if (legacyEntry === undefined) throw new Error("snapshot entry missing");
+ Reflect.deleteProperty(legacyEntry.execution, "relationship_coverage");
+ const legacyEvidence = createEvidence(
+ ANALYSIS_SNAPSHOT_TARGET,
+ ANALYSIS_SNAPSHOT_PROVIDER,
+ {
+ operation,
+ parameters,
+ result: ["0x2000"],
+ rawResult: ["0x2000"],
+ analysisProfile: ANALYSIS_SNAPSHOT_PROFILE,
+ },
+ );
+ Reflect.deleteProperty(legacyEvidence, "relationship_coverage");
+ legacy.evidence_bundle = createEvidenceBundle([legacyEvidence]);
+ parseAnalysisSnapshot(legacy);
+ const replayCache = new AnalysisSnapshotCache();
+ expect(replayCache.import(legacy, undefined, () => ok(0)).ok).toBe(true);
+ expect(
+ replayCache.lookup(
+ ANALYSIS_SNAPSHOT_TARGET,
+ ANALYSIS_SNAPSHOT_PROFILE,
+ operation,
+ parameters,
+ )?.relationshipCoverage,
+ ).toEqual({
+ status: "unknown",
+ reason: "Snapshot entry does not report relationship coverage.",
+ });
+ });
+});
diff --git a/src/application/binary/AnalysisSnapshotCache.ts b/src/application/binary/AnalysisSnapshotCache.ts
index cf5083e1a..6440ccf6a 100644
--- a/src/application/binary/AnalysisSnapshotCache.ts
+++ b/src/application/binary/AnalysisSnapshotCache.ts
@@ -34,6 +34,11 @@ import type {
import { OFFICIAL_TOOL_CONTRACTS } from "../../contracts/officialToolContracts.js";
import { compareUnicodeCodePoints } from "../../domain/unicodeCodePointOrder.js";
+const RELATIONSHIP_OPERATIONS: ReadonlySet<AnalysisOperation> = new Set([
+ "procedure_callers",
+ "procedure_callees",
+]);
+
const STATEFUL_OPERATIONS: ReadonlySet<AnalysisOperation> = new Set([
"health",
"current_address",
@@ -241,6 +246,7 @@ export class AnalysisSnapshotCache {
readonly provider: AnalysisExecution["provider"];
readonly analysisProfile: AnalysisProfileCommitment;
readonly limitations: readonly string[];
+ readonly relationshipCoverage?: AnalysisExecution["relationshipCoverage"];
readonly locations: AnalysisExecution["locations"];
readonly subject: AnalysisExecution["subject"];
};
@@ -302,6 +308,19 @@ export class AnalysisSnapshotCache {
...cached.execution.limitations,
"Loaded from a local REA analysis snapshot; this call did not re-run the provider.",
],
+ ...(cached.execution.relationship_coverage === null &&
+ RELATIONSHIP_OPERATIONS.has(operation)
+ ? {
+ relationshipCoverage: {
+ status: "unknown",
+ reason: "Snapshot entry does not report relationship coverage.",
+ },
+ }
+ : cached.execution.relationship_coverage === null
+ ? {}
+ : {
+ relationshipCoverage: cached.execution.relationship_coverage,
+ }),
locations: cached.execution.locations,
subject,
});
diff --git a/src/application/binary/BinarySession.ts b/src/application/binary/BinarySession.ts
index e604256d9..30239874e 100644
--- a/src/application/binary/BinarySession.ts
+++ b/src/application/binary/BinarySession.ts
@@ -594,9 +594,22 @@ export class BinarySession
name,
active.target,
);
- this.#observeRuntimeAvailability(name, profiled);
- if (
+ const execution =
profiled.ok &&
+ (name === "procedure_callers" || name === "procedure_callees") &&
+ profiled.value.relationshipCoverage === undefined
+ ? ok({
+ ...profiled.value,
+ relationshipCoverage: {
+ status: "unknown" as const,
+ reason:
+ "Provider did not report relationship coverage for this observation.",
+ },
+ })
+ : profiled;
+ this.#observeRuntimeAvailability(name, execution);
+ if (
+ execution.ok &&
cacheable &&
profile !== undefined &&
name !== "decode_interface_builder" &&
@@ -605,16 +618,21 @@ export class BinarySession
name !== "trace_dylib_resolution"
) {
const evidence = createEvidence(
- profiled.value.subject ?? active.target,
- profiled.value.provider,
+ execution.value.subject ?? active.target,
+ execution.value.provider,
{
operation: name,
parameters: arguments_,
- result: profiled.value.result,
+ result: execution.value.result,
analysisProfile: profile,
- rawResult: profiled.value.rawResult,
- limitations: profiled.value.limitations,
- locations: profiled.value.locations,
+ rawResult: execution.value.rawResult,
+ limitations: execution.value.limitations,
+ ...(execution.value.relationshipCoverage === undefined
+ ? {}
+ : {
+ relationshipCoverage: execution.value.relationshipCoverage,
+ }),
+ locations: execution.value.locations,
},
);
const recorded = this.recordEvidence(evidence);
@@ -624,12 +642,12 @@ export class BinarySession
profile,
operation: name,
parameters: arguments_,
- execution: profiled.value,
+ execution: execution.value,
});
} else if (profiled.ok && capability.effects.mutatesArtifact) {
this.invalidateSnapshot();
}
- return profiled;
+ return execution;
}
#observeRuntimeAvailability(
diff --git a/src/contracts/toolOutputSchemaGroups.ts b/src/contracts/toolOutputSchemaGroups.ts
index c87c0f09c..3c97b3aca 100644
--- a/src/contracts/toolOutputSchemaGroups.ts
+++ b/src/contracts/toolOutputSchemaGroups.ts
@@ -59,6 +59,7 @@ import { callPathResultSchema } from "../domain/callPathSchemas.js";
import { staticRuntimeCorrelationResultSchema } from "../domain/staticRuntimeCorrelation.js";
import { reconstructionVerificationResultSchema } from "../domain/reconstructionVerificationSchemas.js";
import { analysisErrorProjectionSchema } from "./errorSchemas.js";
+import { relationshipCoverageSchema } from "../domain/relationshipCoverage.js";
import { nativeDispatchMetadataResultSchema } from "../domain/native/objcSwiftMetadata.js";
import { nativeInvestigationTraceSchema } from "../domain/native/nativeInvestigationGraph.js";
import {
@@ -240,6 +241,7 @@ const callPathTraceOutput = evidenceResultOf(
error: analysisErrorProjectionSchema,
}),
),
+ relationship_coverage: z.record(z.string(), relationshipCoverageSchema),
traversal: z.object({
nodes_visited: z.number().int().min(1),
}),
diff --git a/src/contracts/toolOutputSchemaPrimitives.ts b/src/contracts/toolOutputSchemaPrimitives.ts
index 1f1a8c700..b8d7815f3 100644
--- a/src/contracts/toolOutputSchemaPrimitives.ts
+++ b/src/contracts/toolOutputSchemaPrimitives.ts
@@ -23,6 +23,7 @@ import {
PROVIDER_RETRY_ACTIONS,
} from "../domain/providerOperationHealth.js";
import { analysisErrorProjectionSchema } from "./errorSchemas.js";
+import { relationshipCoverageSchema } from "../domain/relationshipCoverage.js";
/** Specialize the single normalized result inside a complete Evidence record. */
export const evidenceResultOf = <Schema extends z.ZodType>(schema: Schema) =>
@@ -505,6 +506,7 @@ export const graphNode = z.discriminatedUnion("status", [
address: z.string(),
status: z.literal("ok"),
calls: z.array(z.string()),
+ relationship_coverage: relationshipCoverageSchema,
limitations: z.array(z.string()).optional(),
}),
z.object({
diff --git a/src/domain/analysisSnapshot.test.ts b/src/domain/analysisSnapshot.test.ts
index e2c1483c9..bd37f79eb 100644
--- a/src/domain/analysisSnapshot.test.ts
+++ b/src/domain/analysisSnapshot.test.ts
@@ -40,6 +40,7 @@ const snapshotWithHistoricalEvidence = () => {
raw_result: null,
provider: binding.provider,
limitations: [],
+ relationship_coverage: null,
locations: [],
subject: {
path: ANALYSIS_SNAPSHOT_TARGET.path,
@@ -392,7 +393,10 @@ describe("analysis snapshot Evidence binding", () => {
workflow_entries: [],
evidence_bundle: createEvidenceBundle([evidence]),
};
- expect(parseAnalysisSnapshot(snapshot)).toEqual(snapshot);
+ const parsedLegacySnapshot = parseAnalysisSnapshot(snapshot);
+ expect(
+ parsedLegacySnapshot.entries[0]?.execution.relationship_coverage,
+ ).toBeNull();
expect(() =>
parseAnalysisSnapshot({
@@ -420,6 +424,13 @@ describe("analysis snapshot Evidence binding", () => {
if (subject !== null && subject !== undefined)
subject.path = "/different/path";
},
+ (altered: typeof snapshot) => {
+ const entry = altered.entries[0];
+ if (entry === undefined) throw new TypeError("missing fixture entry");
+ Reflect.set(entry.execution, "relationship_coverage", {
+ status: "complete",
+ });
+ },
];
for (const alter of alterations) {
const altered = structuredClone(snapshot);
diff --git a/src/domain/analysisSnapshot.ts b/src/domain/analysisSnapshot.ts
index e156144e9..2b99f9faf 100644
--- a/src/domain/analysisSnapshot.ts
+++ b/src/domain/analysisSnapshot.ts
@@ -42,6 +42,10 @@ import { prefixedDigestSchema } from "./../domain/digests.js";
import { canonicalJsonDigestSteps } from "./canonicalJsonDigestSteps.js";
import { freezeJsonSnapshot } from "./immutableJson.js";
import { rawBinaryEntryPointSchema } from "./rawBinary.js";
+import {
+ relationshipCoverageSchema,
+ type RelationshipCoverage,
+} from "./relationshipCoverage.js";
const architectureSchema = z.enum(BINARY_ARCHITECTURES);
const formatSchema = z.enum([
@@ -125,6 +129,7 @@ const entrySchema = z.object({
raw_result: jsonValueSchema.nullable(),
provider: committedProviderSchema,
limitations: z.array(z.string()),
+ relationship_coverage: relationshipCoverageSchema.nullable().default(null),
locations: z.array(evidenceLocationSchema),
subject: subjectSchema.nullable(),
}),
@@ -139,6 +144,7 @@ const workflowEntrySchema = z.object({
provider: committedProviderSchema,
analysis_profile: analysisProfileSchema,
limitations: z.array(z.string()),
+ relationship_coverage: relationshipCoverageSchema.nullable().default(null),
locations: z.array(evidenceLocationSchema),
subject: subjectSchema.nullable(),
}),
@@ -268,7 +274,7 @@ const snapshotContentDigest = (
rawResult: JsonValue | null,
execution: Pick<
AnalysisSnapshotEntry["execution"],
- "limitations" | "locations" | "subject"
+ "limitations" | "locations" | "subject" | "relationship_coverage"
>,
): string => {
const metadata = jsonObjectSchema.parse({
@@ -283,6 +289,9 @@ const snapshotContentDigest = (
format: execution.subject.format,
architecture: execution.subject.architecture,
},
+ ...(execution.relationship_coverage === null
+ ? {}
+ : { relationship_coverage: execution.relationship_coverage }),
});
return contentDigest({
...metadata,
@@ -309,6 +318,7 @@ interface SnapshotExecution {
};
readonly analysisProfile?: AnalysisProfileCommitment;
readonly limitations: readonly string[];
+ readonly relationshipCoverage?: RelationshipCoverage | null | undefined;
readonly locations: readonly EvidenceLocation[];
readonly subject: EvidenceSubjectTarget | null;
}
@@ -460,6 +470,7 @@ export const createAnalysisSnapshotWorkflowEntry = (input: {
provider: execution.analysisProfile.provider,
analysis_profile: execution.analysisProfile,
limitations: [...execution.limitations],
+ relationship_coverage: execution.relationshipCoverage ?? null,
locations: [...execution.locations],
subject:
execution.subject === null
@@ -522,6 +533,7 @@ export const createAnalysisSnapshotEntry = (input: {
raw_result: execution.rawResult,
provider: binding.provider,
limitations: [...execution.limitations],
+ relationship_coverage: execution.relationshipCoverage ?? null,
locations: [...execution.locations],
subject:
execution.subject === null
@@ -838,19 +850,24 @@ const evidenceMatchesWorkflowEntry = (
evidenceContentDigest(evidence),
]) === workflowEntryEvidenceKey(entry);
-const evidenceContentMetadata = (evidence: Evidence) => ({
- limitations: evidence.limitations,
- locations: evidence.locations,
- subject:
- evidence.subject === null
- ? null
- : {
- local_path: evidence.subject.local_path,
- sha256: evidence.subject.digest.sha256,
- format: evidence.subject.format,
- architecture: evidence.subject.architecture,
- },
-});
+const evidenceContentMetadata = (evidence: Evidence) => {
+ return {
+ limitations: evidence.limitations,
+ ...(evidence.relationship_coverage === null
+ ? {}
+ : { relationship_coverage: evidence.relationship_coverage }),
+ locations: evidence.locations,
+ subject:
+ evidence.subject === null
+ ? null
+ : {
+ local_path: evidence.subject.local_path,
+ sha256: evidence.subject.digest.sha256,
+ format: evidence.subject.format,
+ architecture: evidence.subject.architecture,
+ },
+ };
+};
/** Serialize a validated snapshot with byte-stable canonical entry ordering. */
export const serializeAnalysisSnapshot = (snapshot: AnalysisSnapshot): string =>
diff --git a/src/domain/evidence.ts b/src/domain/evidence.ts
index dcfee98fd..8e21686e5 100644
--- a/src/domain/evidence.ts
+++ b/src/domain/evidence.ts
@@ -27,6 +27,10 @@ import {
} from "./immutableJson.js";
import { digestSchema } from "./../domain/digests.js";
import { prefixedDigestSchema } from "./../domain/digests.js";
+import {
+ relationshipCoverageSchema,
+ type RelationshipCoverage,
+} from "./relationshipCoverage.js";
/** Provider identity schema shared by evidence-bearing persistence formats. */
export const providerSchema = z.object({
@@ -118,6 +122,7 @@ const evidenceBaseSchema = z
authority: evidenceAuthoritySchema,
environment: executionEnvironmentSchema.nullable(),
limitations: z.array(z.string()),
+ relationship_coverage: relationshipCoverageSchema.nullable().default(null),
locations: z.array(evidenceLocationSchema),
evidence_links: z.array(prefixedDigestSchema("ev")),
})
@@ -163,9 +168,11 @@ const authenticatedEvidenceSchema = evidenceSchema.superRefine(
);
/** Complete observation whose normalized payload retains its operation-specific type. */
-export type Evidence<Result extends JsonValue = JsonValue> = z.infer<
- typeof evidenceSchema
-> & { readonly normalized_result: Result };
+type EvidenceSchemaValue = z.infer<typeof evidenceSchema>;
+export type Evidence<Result extends JsonValue = JsonValue> =
+ EvidenceSchemaValue & {
+ readonly normalized_result: Result;
+ };
const immutableEvidenceSnapshots = new WeakMap<object, Evidence>();
const immutableResultSchema = z
.custom<JsonValue>(isImmutableJsonSnapshot)
@@ -215,13 +222,14 @@ export interface EvidenceObservation {
readonly authority?: EvidenceAuthority;
readonly environment?: ExecutionEnvironment | null;
readonly limitations?: readonly string[];
+ readonly relationshipCoverage?: RelationshipCoverage;
/** Reason the subject identity is unavailable, when no target identity is supplied. */
readonly subjectUnavailableReason?: string;
readonly locations?: readonly EvidenceLocation[];
readonly evidenceLinks?: readonly string[];
}
-type EvidenceWithoutId = Omit<Evidence, "evidence_id">;
+type EvidenceWithoutId = Omit<EvidenceSchemaValue, "evidence_id">;
const semanticProjection = (evidence: EvidenceWithoutId): JsonValue => ({
subject:
@@ -243,6 +251,9 @@ const semanticProjection = (evidence: EvidenceWithoutId): JsonValue => ({
authority: evidence.authority,
environment: evidence.environment,
limitations: evidence.limitations,
+ ...(evidence.relationship_coverage === null
+ ? {}
+ : { relationship_coverage: evidence.relationship_coverage }),
locations: evidence.locations,
evidence_links: evidence.evidence_links,
});
@@ -404,6 +415,9 @@ const normalizeEvidenceObservation = (
: []),
...(observation.limitations ?? []),
],
+ ...(observation.relationshipCoverage === undefined
+ ? { relationship_coverage: null }
+ : { relationship_coverage: observation.relationshipCoverage }),
locations: [...(observation.locations ?? [])],
evidence_links: [...(observation.evidenceLinks ?? [])],
} satisfies JsonValue;
diff --git a/src/domain/relationshipCoverage.ts b/src/domain/relationshipCoverage.ts
new file mode 100644
index 000000000..556853343
--- /dev/null
+++ b/src/domain/relationshipCoverage.ts
@@ -0,0 +1,16 @@
+import { z } from "zod";
+
+/** Explicit coverage state for a provider's observed caller/callee set. */
+export const relationshipCoverageSchema = z.discriminatedUnion("status", [
+ z.strictObject({ status: z.literal("complete") }),
+ z.strictObject({
+ status: z.literal("partial"),
+ limitations: z.array(z.string().min(1)).min(1),
+ }),
+ z.strictObject({
+ status: z.literal("unknown"),
+ reason: z.string().min(1),
+ }),
+]);
+
+export type RelationshipCoverage = z.infer<typeof relationshipCoverageSchema>;
diff --git a/src/ghidra/GhidraProvider.behavior.test.ts b/src/ghidra/GhidraProvider.behavior.test.ts
index 57fd8aa8a..72d8ecd38 100644
--- a/src/ghidra/GhidraProvider.behavior.test.ts
+++ b/src/ghidra/GhidraProvider.behavior.test.ts
@@ -64,6 +64,15 @@ const provider = (
);
};
+const createElfClient = async (ghidra: GhidraProvider) => {
+ const target = executableTarget("elf", "x86_64");
+ const resolved = await ghidra.resolveAnalysisProfile(target);
+ if (!resolved.ok) throw resolved.error;
+ if (resolved.value.profile === null)
+ throw new Error("Expected a bound Ghidra profile");
+ return ghidra.createClient(target, resolved.value.profile);
+};
+
describe("Ghidra provider", () => {
it("commits DOS loader and real-mode language while retaining the CPU family", async () => {
const ghidra = provider();
@@ -608,15 +617,6 @@ describe("Ghidra client projection", () => {
});
describe("Ghidra result projection", () => {
- const createElfClient = async (ghidra: GhidraProvider) => {
- const target = executableTarget("elf", "x86_64");
- const resolved = await ghidra.resolveAnalysisProfile(target);
- if (!resolved.ok) throw resolved.error;
- if (resolved.value.profile === null)
- throw new Error("Expected a bound Ghidra profile");
- return ghidra.createClient(target, resolved.value.profile);
- };
-
it("rejects malformed inventory output before Evidence creation", async () => {
const ghidra = provider(installationHost(), () => ({
start: () => Promise.resolve(ok(sessionInfo())),
@@ -763,6 +763,32 @@ describe("Ghidra result projection", () => {
});
});
+describe("Ghidra relationship coverage", () => {
+ it("marks the full direct call-reference response complete while keeping static caveats", async () => {
+ const ghidra = provider(installationHost(), () => ({
+ start: () => Promise.resolve(ok(sessionInfo())),
+ callTool: (operation) =>
+ Promise.resolve(
+ ok(operation === "procedure_callees" ? ["0x2000"] : []),
+ ),
+ close: () => Promise.resolve(ok(null)),
+ }));
+ const client = await createElfClient(ghidra);
+ const execution = await client.execute("procedure_callees", {
+ procedure: "0x1000",
+ document: "fixture",
+ });
+ if (!execution.ok) throw execution.error;
+ expect(execution.value.relationshipCoverage).toEqual({
+ status: "complete",
+ });
+ expect(execution.value.limitations).toContain(
+ "Only resolved Ghidra call references are returned; unresolved computed or indirect calls remain unknown, while function classifications distinguish thunks and externals.",
+ );
+ await client.close();
+ });
+});
+
describe("Ghidra measured load-image projection", () => {
it.each(["verified", "changed-snapshot", "cancelled"] as const)(
"streams raw snapshot identity and preserves %s outcomes",
diff --git a/src/ghidra/GhidraProviderClient.ts b/src/ghidra/GhidraProviderClient.ts
index 742ef79f7..5503c62cc 100644
--- a/src/ghidra/GhidraProviderClient.ts
+++ b/src/ghidra/GhidraProviderClient.ts
@@ -821,6 +821,10 @@ export const createGhidraProviderClient = (input: {
createAnalysisExecution(normalized, committedProfile.provider, {
rawResult: called.value,
analysisProfile: committedProfile,
+ ...(operation === "procedure_callers" ||
+ operation === "procedure_callees"
+ ? { relationshipCoverage: { status: "complete" as const } }
+ : {}),
limitations: [
...limitationsFor(operation),
...observationLimitations,
diff --git a/src/hopper/HopperProvider.ts b/src/hopper/HopperProvider.ts
index d8b2dafa6..0b7316a19 100644
--- a/src/hopper/HopperProvider.ts
+++ b/src/hopper/HopperProvider.ts
@@ -271,6 +271,10 @@ export class HopperProvider implements AnalysisProviderCandidate {
// Only the file-offset mapping differs from Hopper's reply.
rawResult: mapped === result ? null : result.value,
...(profile === undefined ? {} : { analysisProfile: profile }),
+ ...(operation === "procedure_callers" ||
+ operation === "procedure_callees"
+ ? { relationshipCoverage: { status: "complete" as const } }
+ : {}),
limitations: [
...(preparedImage === undefined
? []
diff --git a/src/ida/IdaCallGraph.ts b/src/ida/IdaCallGraph.ts
index 53152d138..930f14877 100644
--- a/src/ida/IdaCallGraph.ts
+++ b/src/ida/IdaCallGraph.ts
@@ -5,6 +5,7 @@ import {
} from "../domain/analysisErrorCore.js";
import type { BinaryTarget } from "../domain/binaryTargetTypes.js";
import type { JsonValue } from "../domain/jsonValue.js";
+import type { RelationshipCoverage } from "../domain/relationshipCoverage.js";
import { ZodError } from "zod";
import {
idaAddressSchema,
@@ -48,6 +49,7 @@ export interface CallGraphCallees {
readonly name: string;
}[];
readonly limitations: readonly string[];
+ readonly coverage: RelationshipCoverage;
}
/** No function edges can be observed when the server lacks the graph tool. */
@@ -57,6 +59,10 @@ export const unavailableCallGraph = (reason: string): CallGraphCallees => ({
UNRECOGNIZED_CALLEE_LIMITATION,
`Upstream callgraph was unavailable (${reason}); callee edges remain unknown.`,
],
+ coverage: {
+ status: "unknown",
+ reason: `Upstream callgraph was unavailable (${reason}); callee edges remain unknown.`,
+ },
});
/**
@@ -95,6 +101,7 @@ export const readCallGraphCallees = async (
BigInt(left) < BigInt(right) ? -1 : BigInt(left) > BigInt(right) ? 1 : 0,
);
const limitations = [UNRECOGNIZED_CALLEE_LIMITATION];
+ const coverageLimitations: string[] = [];
const truncated =
row.truncated === true ||
row.per_func_capped === true ||
@@ -104,8 +111,13 @@ export const readCallGraphCallees = async (
const saturated =
row.max_edges_per_func !== undefined &&
edges.length >= row.max_edges_per_func;
- if (truncated) limitations.push(TRUNCATED_LIMITATION);
- else if (saturated) limitations.push(POSSIBLY_TRUNCATED_LIMITATION);
+ if (truncated) {
+ limitations.push(TRUNCATED_LIMITATION);
+ coverageLimitations.push(TRUNCATED_LIMITATION);
+ } else if (saturated) {
+ limitations.push(POSSIBLY_TRUNCATED_LIMITATION);
+ coverageLimitations.push(POSSIBLY_TRUNCATED_LIMITATION);
+ }
const names = new Map<string, string>();
if (targets.length > 0) {
@@ -149,5 +161,9 @@ export const readCallGraphCallees = async (
};
}),
limitations,
+ coverage:
+ coverageLimitations.length === 0
+ ? { status: "complete" }
+ : { status: "partial", limitations: coverageLimitations },
};
};
diff --git a/src/ida/IdaOperationRunner.ts b/src/ida/IdaOperationRunner.ts
index 6099f379e..fea479c19 100644
--- a/src/ida/IdaOperationRunner.ts
+++ b/src/ida/IdaOperationRunner.ts
@@ -10,6 +10,7 @@ import {
functionInstructionWindowSchema,
} from "../domain/hopperValues.js";
import type { JsonValue } from "../domain/jsonValue.js";
+import type { RelationshipCoverage } from "../domain/relationshipCoverage.js";
import { readCallGraphCallees, unavailableCallGraph } from "./IdaCallGraph.js";
import type { IdaMcpConnection } from "./IdaMcpConnection.js";
import type { IdaOperation } from "./IdaProviderCapabilities.js";
@@ -65,6 +66,7 @@ export class IdaOperationRunner {
readonly raw: IdaRawObservation[] = [];
readonly locations: EvidenceLocation[] = [];
readonly limitations: string[] = [];
+ relationshipCoverage: RelationshipCoverage | undefined;
constructor(
private readonly connection: IdaMcpConnection,
private readonly protocol: "legacy" | "modern",
@@ -203,6 +205,7 @@ export class IdaOperationRunner {
(tool, args) => this.call(tool, args),
fn.address,
);
+ this.relationshipCoverage = graph.coverage;
this.limitations.push(...graph.limitations);
for (const callee of graph.callees)
if (!result.has(callee.address))
@@ -366,6 +369,11 @@ export class IdaOperationRunner {
this.limitations.push(
"Modern upstream xrefs classify references as code or data, without proving call edges. Direct callers are unavailable in this profile.",
);
+ this.relationshipCoverage = {
+ status: "unknown",
+ reason:
+ "Modern upstream xrefs do not establish direct caller relationships.",
+ };
return [];
} else {
const page = modernCalleesSchema.parse(
@@ -379,6 +387,15 @@ export class IdaOperationRunner {
this.limitations.push(
"Upstream callees capped results at 500; additional callees remain unknown.",
);
+ this.relationshipCoverage =
+ page.more === true
+ ? {
+ status: "partial",
+ limitations: [
+ "Upstream callees capped results at 500; additional callees remain unknown.",
+ ],
+ }
+ : { status: "complete" };
for (const item of page.callees) {
if ("type" in item && item.type === "external")
result.set(
@@ -392,6 +409,11 @@ export class IdaOperationRunner {
const resolved = identity(await this.resolve(query));
result.set(resolved.address, resolved);
}
+ if (this.relationshipCoverage === undefined)
+ this.relationshipCoverage = {
+ status: "unknown",
+ reason: "The legacy relationship response does not report coverage.",
+ };
return [...result.values()];
}
diff --git a/src/ida/IdaSessionClient.ts b/src/ida/IdaSessionClient.ts
index ff2257752..1d6aa599d 100644
--- a/src/ida/IdaSessionClient.ts
+++ b/src/ida/IdaSessionClient.ts
@@ -211,6 +211,9 @@ export class IdaSessionClient implements AnalysisClient {
observations: jsonValueSchema.parse(runner.raw),
},
limitations: [...IDA_LIMITATIONS, ...runner.limitations],
+ ...(runner.relationshipCoverage === undefined
+ ? {}
+ : { relationshipCoverage: runner.relationshipCoverage }),
locations: [
{ kind: "artifact-path", path: this.target.path },
...runner.locations,
diff --git a/src/server/registerOfficialTools.ts b/src/server/registerOfficialTools.ts
index dcb5b10ab..8cc603b8f 100644
--- a/src/server/registerOfficialTools.ts
+++ b/src/server/registerOfficialTools.ts
@@ -89,6 +89,11 @@ const registerOfficialTool = (
: { analysisProfile: result.value.analysisProfile }),
rawResult: result.value.rawResult,
limitations: result.value.limitations,
+ ...(result.value.relationshipCoverage === undefined
+ ? {}
+ : {
+ relationshipCoverage: result.value.relationshipCoverage,
+ }),
locations: result.value.locations,
},
);
diff --git a/tests/boundary/mcp/enhancedTools.01-lists-the-complete-target-open.test.ts b/tests/boundary/mcp/enhancedTools.01-lists-the-complete-target-open.test.ts
index 5d031b940..e1e37c26f 100644
--- a/tests/boundary/mcp/enhancedTools.01-lists-the-complete-target-open.test.ts
+++ b/tests/boundary/mcp/enhancedTools.01-lists-the-complete-target-open.test.ts
@@ -189,7 +189,7 @@ const fixturePort = (): AnalysisOperationPort => ({
case "analyze_function":
return Promise.resolve(targetObservation(functionDossier));
default:
- return Promise.resolve(ok(null));
+ throw new Error(`Unexpected analysis operation: ${name}`);
}
},
});
@@ -288,10 +288,36 @@ describe("enhanced MCP tools", () => {
failed: 0,
});
expect(results[3]).toEqual({
- "0": [{ address: "0x1", status: "ok", calls: ["0x2", "0x3"] }],
+ "0": [
+ {
+ address: "0x1",
+ status: "ok",
+ calls: ["0x2", "0x3"],
+ relationship_coverage: {
+ status: "unknown",
+ reason: "Provider did not report relationship coverage.",
+ },
+ },
+ ],
"1": [
- { address: "0x2", status: "ok", calls: ["0x1"] },
- { address: "0x3", status: "ok", calls: [] },
+ {
+ address: "0x2",
+ status: "ok",
+ calls: ["0x1"],
+ relationship_coverage: {
+ status: "unknown",
+ reason: "Provider did not report relationship coverage.",
+ },
+ },
+ {
+ address: "0x3",
+ status: "ok",
+ calls: [],
+ relationship_coverage: {
+ status: "unknown",
+ reason: "Provider did not report relationship coverage.",
+ },
+ },
],
});
expect(results[4]).toMatchObject({
@@ -354,7 +380,7 @@ describe("enhanced MCP tools", () => {
{ address: "0x1", depth: 0 },
{ address: "0x2", depth: 1 },
],
- truncated: false,
+ truncated: true,
});
expect(results[11]).toMatchObject({
start: "missing-selector",
diff --git a/tests/boundary/mcp/enhancedTools.callPathsAndBatches.test.ts b/tests/boundary/mcp/enhancedTools.callPathsAndBatches.test.ts
index 625bc27fd..54f61f8e0 100644
--- a/tests/boundary/mcp/enhancedTools.callPathsAndBatches.test.ts
+++ b/tests/boundary/mcp/enhancedTools.callPathsAndBatches.test.ts
@@ -7,6 +7,7 @@ import {
AnalysisCapabilityUnavailableError,
AnalysisOutputError,
} from "../../../src/domain/analysisErrorCore.js";
+import type { RelationshipCoverage } from "../../../src/domain/relationshipCoverage.js";
import { err, ok as resultOk } from "../../../src/domain/result.js";
import { closeEnhancedToolResources, connect } from "./enhancedToolsHarness.js";
@@ -17,12 +18,16 @@ afterEach(closeEnhancedToolResources);
const relationshipExecution = (
result: unknown,
limitations: readonly string[] = [],
+ relationshipCoverage?: RelationshipCoverage,
) =>
resultOk(
createAnalysisExecution(
result,
{ id: "fixture", name: "Fixture analysis provider", version: "1" },
- { limitations },
+ {
+ limitations,
+ ...(relationshipCoverage === undefined ? {} : { relationshipCoverage }),
+ },
),
);
@@ -38,6 +43,9 @@ describe("enhanced MCP tools", () => {
return relationshipExecution(
arguments_.procedure === "0x1" ? ["0x2"] : [],
arguments_.procedure === "0x1" ? [limitation] : [],
+ arguments_.procedure === "0x1"
+ ? { status: "partial", limitations: [limitation] }
+ : { status: "complete" },
);
},
});
@@ -54,6 +62,10 @@ describe("enhanced MCP tools", () => {
status: "ok",
calls: ["0x2"],
limitations: [limitation],
+ relationship_coverage: {
+ status: "partial",
+ limitations: [limitation],
+ },
},
],
},
@@ -77,6 +89,49 @@ describe("enhanced MCP tools", () => {
});
});
+ it("keeps generic provider caveats visible without truncating complete relationships", async () => {
+ const caveat = "Decompiler output may omit indirect calls.";
+ const client = await connect({
+ execute: async (name, arguments_) => {
+ if (name === "procedure_address")
+ return relationshipExecution(String(arguments_.procedure));
+ if (name !== "procedure_callees")
+ throw new Error(`Unexpected operation: ${name}`);
+ return relationshipExecution([], [caveat], { status: "complete" });
+ },
+ });
+
+ const graph = await client.callTool({
+ name: "get_call_graph",
+ arguments: { address: "0x1", direction: "forward" },
+ });
+ expect(graph.structuredContent).toMatchObject({
+ normalized_result: {
+ "0": [
+ {
+ limitations: [caveat],
+ relationship_coverage: { status: "complete" },
+ },
+ ],
+ },
+ });
+
+ const trace = await client.callTool({
+ name: "trace_call_path",
+ arguments: { start: "0x1", goal: "0x2" },
+ });
+ expect(trace.structuredContent).toMatchObject({
+ normalized_result: {
+ truncated: false,
+ residual_unknowns: [],
+ limitations: expect.arrayContaining([expect.stringContaining(caveat)]),
+ relationship_coverage: { "0x1": { status: "complete" } },
+ },
+ });
+ });
+});
+
+describe("enhanced MCP batches", () => {
it("returns every batch item in caller order with its own result", async () => {
const addresses = Array.from(
{ length: 37 },
diff --git a/tests/boundary/providers/ida/calleeRelationships.test.ts b/tests/boundary/providers/ida/calleeRelationships.test.ts
index ec46be03d..7ba797de4 100644
--- a/tests/boundary/providers/ida/calleeRelationships.test.ts
+++ b/tests/boundary/providers/ida/calleeRelationships.test.ts
@@ -122,13 +122,16 @@ it("traverses every ARM64 callee in a call path without a goal and records no fa
{ source_address: "0x1000", target_address: "0x3000" },
],
failures: [],
- truncated: true,
+ truncated: false,
limitations: expect.arrayContaining([
"This relationship read does not establish calls to targets IDA does not recognize as functions; imports and other non-function call targets remain unknown.",
]),
- residual_unknowns: expect.arrayContaining([
- expect.stringContaining("Call relationships for 0x1000 are limited:"),
- ]),
+ residual_unknowns: [],
+ relationship_coverage: {
+ "0x1000": { status: "complete" },
+ "0x2000": { status: "complete" },
+ "0x3000": { status: "complete" },
+ },
});
expect(
requestedRoots(producer),
@@ -203,7 +206,9 @@ it("preserves missing callgraph coverage through direct, graph, and trace workfl
expect.stringContaining("callgraph was unavailable"),
]),
residual_unknowns: expect.arrayContaining([
- expect.stringContaining("Call relationships for 0x1000 are limited:"),
+ expect.stringContaining(
+ "Call relationship coverage is unknown for 0x1000:",
+ ),
]),
});
expect(