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(analysis): preserve relationship coverage across evidence and replay
morluto9c8511409c07
diff --git a/docs/tool-design.md b/docs/tool-design.mdindex 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. Preserveunresolved edges and partial provider facts instead of requiring everyprovider 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 resourcediff --git a/src/application/AnalysisProvider.ts b/src/application/AnalysisProvider.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex e604256d9..30239874e 100644--- a/src/application/binary/BinarySession.ts+++ b/src/application/binary/BinarySession.ts@@ -594,9 +594,22 @@ export class BinarySessionname,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 BinarySessionname !== "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 BinarySessionprofile,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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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 = zauthority: 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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 workflexpect.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(