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; readonly limitations: Set; + readonly relationshipCoverage: Map; 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 = new Set([ + "procedure_callers", + "procedure_callees", +]); + const STATEFUL_OPERATIONS: ReadonlySet = 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: 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 = z.infer< - typeof evidenceSchema -> & { readonly normalized_result: Result }; +type EvidenceSchemaValue = z.infer; +export type Evidence = + EvidenceSchemaValue & { + readonly normalized_result: Result; + }; const immutableEvidenceSnapshots = new WeakMap(); const immutableResultSchema = z .custom(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; +type EvidenceWithoutId = Omit; 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; 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(); 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(