From d8b802b3a035a762d49793cec03dbd9d627509cf Mon Sep 17 00:00:00 2001 From: Mykola Dementiev Date: Mon, 12 Oct 2026 21:50:47 +0200 Subject: [PATCH 01/30] test(mcp): expect trace_feature to report references the provider truncated A provider that reports a capped xrefs read makes the trace truncated with a residual unknown for that target. An explicit complete report and a provider that reports nothing leave the trace as before. --- .../binary/AnalysisSnapshotCache.test.ts | 49 +++++ src/ida/IdaReferenceCoverage.test.ts | 59 ++++++ ...enhancedTools.traceFeatureCoverage.test.ts | 168 ++++++++++++++++++ 3 files changed, 276 insertions(+) create mode 100644 src/ida/IdaReferenceCoverage.test.ts create mode 100644 tests/boundary/mcp/enhancedTools.traceFeatureCoverage.test.ts diff --git a/src/application/binary/AnalysisSnapshotCache.test.ts b/src/application/binary/AnalysisSnapshotCache.test.ts index 48c2a54bd18..91b9f8807e3 100644 --- a/src/application/binary/AnalysisSnapshotCache.test.ts +++ b/src/application/binary/AnalysisSnapshotCache.test.ts @@ -661,3 +661,52 @@ it("does not replay pre-envelope call graphs under the revised workflow profile" }).success, ).toBe(false); }); + +describe("executions that report truncated references", () => { + const record = (referencesTruncated: boolean | undefined) => { + const cache = new AnalysisSnapshotCache(); + const parameters = { address: "0x1000", document: "fixture" }; + cache.record({ + target: ANALYSIS_SNAPSHOT_TARGET, + profile: ANALYSIS_SNAPSHOT_PROFILE, + operation: "xrefs", + parameters, + execution: createAnalysisExecution( + ["0x2000"], + ANALYSIS_SNAPSHOT_PROVIDER, + { + subject: ANALYSIS_SNAPSHOT_TARGET, + analysisProfile: ANALYSIS_SNAPSHOT_PROFILE, + ...(referencesTruncated === undefined ? {} : { referencesTruncated }), + }, + ), + }); + return cache.lookup( + ANALYSIS_SNAPSHOT_TARGET, + ANALYSIS_SNAPSHOT_PROFILE, + "xrefs", + parameters, + ); + }; + + it("are not replayed, because a replay would lose the truncation", () => { + expect(record(true)).toBeUndefined(); + }); + + it("do not stop an execution that is complete or silent from being replayed", () => { + expect(record(false)?.result).toEqual(["0x2000"]); + expect(record(undefined)?.result).toEqual(["0x2000"]); + }); +}); + +it("revises the trace_feature workflow profile so earlier results are not replayed", () => { + const profile = ANALYSIS_SNAPSHOT_PROFILE; + + expect(workflowAnalysisProfile(profile, "trace_feature")).not.toEqual( + workflowAnalysisProfile(profile), + ); + expect( + workflowAnalysisProfile(profile, "trace_call_path"), + "other workflows keep their profile", + ).toEqual(workflowAnalysisProfile(profile)); +}); diff --git a/src/ida/IdaReferenceCoverage.test.ts b/src/ida/IdaReferenceCoverage.test.ts new file mode 100644 index 00000000000..4617f572e9e --- /dev/null +++ b/src/ida/IdaReferenceCoverage.test.ts @@ -0,0 +1,59 @@ +import { afterEach, describe, expect, it } from "vitest"; +import { + callGraphSession as session, + removeCallGraphSessions, +} from "../../tests/fixtures/idaCallGraph.js"; + +afterEach(removeCallGraphSessions); + +const xrefs = async (more: boolean | undefined) => { + const { client, producer } = await session({ callees: [] }, "x86_64"); + const inner = producer.overrideCall; + producer.overrideCall = (name, args) => + name === "xrefs_to" + ? [{ xrefs: [], ...(more === undefined ? {} : { more }) }] + : inner?.(name, args); + try { + const result = await client.execute("xrefs", { address: "0x1000" }); + if (!result.ok) throw result.error; + return result.value; + } finally { + expect((await client.close()).ok).toBe(true); + } +}; + +describe("headless IDA reference coverage", () => { + it("reports a capped xrefs read as truncated", async () => { + const execution = await xrefs(true); + + expect(execution.referencesTruncated).toBe(true); + expect( + execution.limitations, + "the diagnostic limitation is still reported", + ).toContain( + "Upstream xrefs_to capped results at 1000 references; additional references remain unknown.", + ); + }); + + it("reports an explicitly uncapped xrefs read as not truncated", async () => { + expect((await xrefs(false)).referencesTruncated).toBe(false); + }); + + it("reports nothing when the producer does not say whether the read was capped", async () => { + expect((await xrefs(undefined)).referencesTruncated).toBeUndefined(); + }); + + it("does not report reference coverage for other operations", async () => { + const { client } = await session({ callees: [] }, "x86_64"); + try { + const result = await client.execute("procedure_callees", { + procedure: "main", + }); + + if (!result.ok) throw result.error; + expect(result.value.referencesTruncated).toBeUndefined(); + } finally { + expect((await client.close()).ok).toBe(true); + } + }); +}); diff --git a/tests/boundary/mcp/enhancedTools.traceFeatureCoverage.test.ts b/tests/boundary/mcp/enhancedTools.traceFeatureCoverage.test.ts new file mode 100644 index 00000000000..f44116de836 --- /dev/null +++ b/tests/boundary/mcp/enhancedTools.traceFeatureCoverage.test.ts @@ -0,0 +1,168 @@ +import { afterEach, describe, expect, it } from "vitest"; + +import type { AnalysisOperationPort } from "../../../src/application/AnalysisProvider.js"; +import { createAnalysisExecution } from "../../../src/application/AnalysisProvider.js"; +import { ok } from "../../../src/domain/result.js"; + +import { closeEnhancedToolResources, connect } from "./enhancedToolsHarness.js"; + +afterEach(closeEnhancedToolResources); + +const PROVIDER = { + id: "fixture", + name: "Fixture analysis provider", + version: "1", +} as const; + +type Coverage = boolean | undefined; + +/** + * A provider with two string matches. Each match has one reference; the + * `coverage` map says what the provider reports for that target's references: + * `true` for a capped read, `false` for an explicitly complete one, and + * undefined for a provider that reports nothing. + */ +const provider = ( + coverage: Readonly>, + limitations: readonly string[] = [], +): AnalysisOperationPort => ({ + execute: async (name, arguments_) => { + const address = String(arguments_.address); + switch (name) { + case "search_strings": + return ok( + createAnalysisExecution( + [ + { address: "0x10", value: "hello" }, + { address: "0x11", value: "hello again" }, + ], + PROVIDER, + ), + ); + case "search_procedures": + return ok(createAnalysisExecution([], PROVIDER)); + case "xrefs": { + const reported = coverage[address]; + return ok( + createAnalysisExecution( + [address === "0x10" ? "0x20" : "0x21"], + PROVIDER, + { + limitations, + ...(reported === undefined + ? {} + : { referencesTruncated: reported }), + }, + ), + ); + } + case "resolve_containing_procedure": + return ok( + createAnalysisExecution( + { + query_address: address, + found: false, + procedure: null, + reason: "not_in_procedure", + }, + PROVIDER, + ), + ); + default: + throw new Error(`Unexpected operation: ${name}`); + } + }, +}); + +const trace = async (analysis: AnalysisOperationPort) => { + const client = await connect(analysis); + const result = await client.callTool({ + name: "trace_feature", + arguments: { query: "hello" }, + }); + expect(result.isError).not.toBe(true); + return result.structuredContent as { + normalized_result: { + references: unknown[]; + truncated: boolean; + residual_unknowns: string[]; + }; + }; +}; + +describe("trace_feature reference coverage", () => { + it("marks the trace truncated for the target whose references the provider capped", async () => { + const output = await trace(provider({ "0x10": true, "0x11": false })); + + expect( + output.normalized_result, + "the returned references are kept and only the capped target is a residual unknown", + ).toMatchObject({ + references: [ + { target_address: "0x10", source_address: "0x20" }, + { target_address: "0x11", source_address: "0x21" }, + ], + truncated: true, + residual_unknowns: [ + "References to 0x10 were truncated by the provider; additional references may exist.", + ], + }); + }); + + it("keeps the trace complete when the provider explicitly reports no cap", async () => { + const output = await trace(provider({ "0x10": false, "0x11": false })); + + expect(output.normalized_result).toMatchObject({ + truncated: false, + residual_unknowns: [], + }); + }); + + it("does not change the trace of a provider that reports no coverage", async () => { + const output = await trace( + provider({}, ["Upstream xrefs_to capped results at 1000 references."]), + ); + + expect( + output.normalized_result, + "a limitation text alone never truncates, and an absent field keeps the previous result", + ).toEqual({ + query: "hello", + search_mode: "literal", + matches: [ + { type: "string", address: "0x10", value: "hello" }, + { type: "string", address: "0x11", value: "hello again" }, + ], + references: [ + { + target_address: "0x10", + source_address: "0x20", + containing_procedure: { + query_address: "0x20", + found: false, + procedure: null, + reason: "not_in_procedure", + }, + }, + { + target_address: "0x11", + source_address: "0x21", + containing_procedure: { + query_address: "0x21", + found: false, + procedure: null, + reason: "not_in_procedure", + }, + }, + ], + truncated: false, + residual_unknowns: [], + }); + }); + + it("never exposes the coverage field in the tool output", async () => { + const output = await trace(provider({ "0x10": true, "0x11": false })); + + expect(JSON.stringify(output)).not.toContain("referencesTruncated"); + }); +}); From 41708b0928055da57e4595532eb36ad273e914b3 Mon Sep 17 00:00:00 2001 From: Mykola Dementiev Date: Mon, 12 Oct 2026 21:52:00 +0200 Subject: [PATCH 02/30] fix(mcp): report references a provider truncated in trace_feature Executions gain an optional flag for a capped xrefs read, set by the IDA adapter from the upstream cap. trace_feature marks the trace truncated with a residual unknown for that target only when the provider reports a truncation; a provider that reports nothing keeps its previous result. The trace_feature workflow profile is revised so earlier results are not replayed. --- src/application/AnalysisProvider.ts | 11 +++++ src/application/EnhancedLiteralTracing.ts | 43 ++++++++++++++----- src/application/EnhancedTools.ts | 2 + src/application/InvestigationProviders.ts | 3 +- .../binary/AnalysisSnapshotCache.ts | 3 ++ src/ida/IdaOperationRunner.ts | 3 ++ src/ida/IdaSessionClient.ts | 3 ++ 7 files changed, 57 insertions(+), 11 deletions(-) diff --git a/src/application/AnalysisProvider.ts b/src/application/AnalysisProvider.ts index cc17cac825c..7f723c9afcc 100644 --- a/src/application/AnalysisProvider.ts +++ b/src/application/AnalysisProvider.ts @@ -50,6 +50,13 @@ export interface AnalysisExecution { readonly limitations: readonly string[]; /** Provider-owned completeness assessment for caller/callee observations. */ readonly relationshipCoverage?: RelationshipCoverage; + /** + * Whether the provider capped an `xrefs` read: true when it reported a + * truncation, false when it explicitly reported none. Absent when it reports + * nothing, which is not a completeness claim. Never part of Evidence or tool + * output. + */ + readonly referencesTruncated?: boolean; readonly locations: readonly EvidenceLocation[]; readonly subject: EvidenceSubjectTarget | null; } @@ -69,6 +76,7 @@ export const createAnalysisExecution = ( readonly analysisProfile?: AnalysisProfileCommitment; readonly limitations?: readonly string[]; readonly relationshipCoverage?: RelationshipCoverage; + readonly referencesTruncated?: boolean; readonly locations?: readonly EvidenceLocation[]; readonly subject?: EvidenceSubjectTarget; } = {}, @@ -90,6 +98,9 @@ export const createAnalysisExecution = ( options.relationshipCoverage, ), }), + ...(options.referencesTruncated === undefined + ? {} + : { referencesTruncated: options.referencesTruncated }), locations: [...(options.locations ?? [])], subject: options.subject ?? null, }); diff --git a/src/application/EnhancedLiteralTracing.ts b/src/application/EnhancedLiteralTracing.ts index 9c86781bce3..d382ac73ad7 100644 --- a/src/application/EnhancedLiteralTracing.ts +++ b/src/application/EnhancedLiteralTracing.ts @@ -1,5 +1,8 @@ import { z } from "zod"; -import type { AnalysisOperation } from "./AnalysisProvider.js"; +import type { + AnalysisExecution, + AnalysisOperation, +} from "./AnalysisProvider.js"; import { AnalysisOutputError } from "../domain/analysisErrorCore.js"; import type { AnalysisError } from "../domain/analysisErrorBase.js"; import type { JsonValue } from "../domain/jsonValue.js"; @@ -16,6 +19,12 @@ type AnalysisCall = ( signal?: AbortSignal, ) => Promise>; +type ObserveCall = ( + name: AnalysisOperation, + arguments_: Readonly>, + signal?: AbortSignal, +) => Promise>; + type LiteralSearchSource = readonly [ "search_strings" | "search_procedures", "string" | "procedure", @@ -39,6 +48,7 @@ export interface LiteralTraceInput { /** Trace matching strings and procedures through provider xrefs. */ export const traceLiteralFeature = async ( call: AnalysisCall, + observe: ObserveCall, input: LiteralTraceInput, signal?: AbortSignal, ): EnhancedResult => { @@ -49,7 +59,7 @@ export const traceLiteralFeature = async ( signal, ); if (!searched.ok) return searched; - const traced = await traceReferences(call, { + const traced = await traceReferences(call, observe, { matches: searched.value.matches, ...(signal === undefined ? {} : { signal }), }); @@ -59,8 +69,8 @@ export const traceLiteralFeature = async ( search_mode: "literal", matches: searched.value.matches, references: traced.value.references, - truncated: false, - residual_unknowns: [], + truncated: traced.value.residual.length > 0, + residual_unknowns: traced.value.residual, }); }; @@ -126,24 +136,37 @@ const addPageMatches = (input: { const traceReferences = async ( call: AnalysisCall, + observe: ObserveCall, request: ReferenceTraceRequest, -): Promise> => { +): Promise< + Result<{ references: TraceReference[]; residual: string[] }, AnalysisError> +> => { const references: TraceReference[] = []; + const residual: string[] = []; for (const match of request.matches) { - const xrefs = await call( + const observed = await observe( "xrefs", { address: match.address }, request.signal, ); - if (!xrefs.ok) return xrefs; - if (!Array.isArray(xrefs.value)) + if (!observed.ok) return observed; + // Only an explicit producer report of truncation is a coverage gap; a + // provider that reports nothing keeps its previous, unqualified result. + const unknown = `References to ${match.address} were truncated by the provider; additional references may exist.`; + if ( + observed.value.referencesTruncated === true && + !residual.includes(unknown) + ) + residual.push(unknown); + const sources = observed.value.result; + if (!Array.isArray(sources)) return err( new AnalysisOutputError( "xrefs", "provider returned a non-array result", ), ); - for (const source of xrefs.value) { + for (const source of sources) { if (typeof source !== "string") return err( new AnalysisOutputError( @@ -164,5 +187,5 @@ const traceReferences = async ( }); } } - return ok({ references }); + return ok({ references, residual }); }; diff --git a/src/application/EnhancedTools.ts b/src/application/EnhancedTools.ts index 5ea7ed70d77..99abec00ebd 100644 --- a/src/application/EnhancedTools.ts +++ b/src/application/EnhancedTools.ts @@ -161,6 +161,8 @@ export class EnhancedTools { return traceLiteralFeature( (name, arguments_, operationSignal) => this.#call(name, arguments_, operationSignal), + (name, arguments_, operationSignal) => + this.#observe(name, arguments_, operationSignal), call.input, signal, ); diff --git a/src/application/InvestigationProviders.ts b/src/application/InvestigationProviders.ts index 883d3878c21..2c3bd980623 100644 --- a/src/application/InvestigationProviders.ts +++ b/src/application/InvestigationProviders.ts @@ -20,7 +20,8 @@ export const workflowAnalysisProfile = ( upstream_analysis_profile: upstream, ...(operation === "binary_overview" || operation === "batch_decompile" || - operation === "get_call_graph" + operation === "get_call_graph" || + operation === "trace_feature" ? { workflow_revision: 2 } : {}), }); diff --git a/src/application/binary/AnalysisSnapshotCache.ts b/src/application/binary/AnalysisSnapshotCache.ts index bdaa9f68df0..7e307baa01b 100644 --- a/src/application/binary/AnalysisSnapshotCache.ts +++ b/src/application/binary/AnalysisSnapshotCache.ts @@ -337,6 +337,9 @@ export class AnalysisSnapshotCache { }): void { const { target, profile, operation, parameters, execution } = input; this.select(target, profile); + // The snapshot format does not carry reference truncation; a replay would + // present a capped read as complete, so it is not recorded. + if (execution.referencesTruncated === true) return; const queryId = analysisQueryId( snapshotTarget(target), snapshotBinding(profile), diff --git a/src/ida/IdaOperationRunner.ts b/src/ida/IdaOperationRunner.ts index 530376458ba..e87b879f870 100644 --- a/src/ida/IdaOperationRunner.ts +++ b/src/ida/IdaOperationRunner.ts @@ -112,6 +112,8 @@ export class IdaOperationRunner { readonly locations: EvidenceLocation[] = []; readonly limitations: string[] = []; relationshipCoverage: RelationshipCoverage | undefined; + /** The upstream cap flag of the last `xrefs_to` read, when the producer reported one. */ + referencesTruncated: boolean | undefined; constructor( private readonly connection: IdaMcpConnection, private readonly protocol: "legacy" | "modern" | "native", @@ -416,6 +418,7 @@ export class IdaOperationRunner { throw new AnalysisProtocolError( `IDA xrefs failed: ${page?.error ?? "missing references"}`, ); + if (page.more !== undefined) this.referencesTruncated = page.more; if (page.more === true) this.limitations.push( "Upstream xrefs_to capped results at 1000 references; additional references remain unknown.", diff --git a/src/ida/IdaSessionClient.ts b/src/ida/IdaSessionClient.ts index 7d3ec066c90..5b63b86a533 100644 --- a/src/ida/IdaSessionClient.ts +++ b/src/ida/IdaSessionClient.ts @@ -269,6 +269,9 @@ export class IdaSessionClient implements AnalysisClient { ...(runner.relationshipCoverage === undefined ? {} : { relationshipCoverage: runner.relationshipCoverage }), + ...(operation === "xrefs" && runner.referencesTruncated !== undefined + ? { referencesTruncated: runner.referencesTruncated } + : {}), locations: [ { kind: "artifact-path", path: this.target.path }, ...runner.locations, From 5c01da3dbf80212e557ef9335c3237c76a6716af Mon Sep 17 00:00:00 2001 From: Mykola Dementiev Date: Mon, 12 Oct 2026 21:56:15 +0200 Subject: [PATCH 03/30] refactor(ida): report reference truncation whenever the runner observed an xrefs cap --- src/ida/IdaSessionClient.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/ida/IdaSessionClient.ts b/src/ida/IdaSessionClient.ts index 5b63b86a533..e882929bc85 100644 --- a/src/ida/IdaSessionClient.ts +++ b/src/ida/IdaSessionClient.ts @@ -269,7 +269,7 @@ export class IdaSessionClient implements AnalysisClient { ...(runner.relationshipCoverage === undefined ? {} : { relationshipCoverage: runner.relationshipCoverage }), - ...(operation === "xrefs" && runner.referencesTruncated !== undefined + ...(runner.referencesTruncated !== undefined ? { referencesTruncated: runner.referencesTruncated } : {}), locations: [ From 6160b6eb8ee9f51a44ba534712cec0640a06e3c9 Mon Sep 17 00:00:00 2001 From: Mykola Dementiev Date: Mon, 12 Oct 2026 22:08:58 +0200 Subject: [PATCH 04/30] test(mcp): cover session forwarding, per-target state, native reports and failures of the trace coverage --- src/ida/IdaNativeProtocol.test.ts | 5 + src/ida/IdaReferenceCoverage.test.ts | 39 ++- ...enhancedTools.traceFeatureCoverage.test.ts | 223 +++++++++++------- .../analysis-sessions/binarySession.test.ts | 95 ++++++++ 4 files changed, 279 insertions(+), 83 deletions(-) diff --git a/src/ida/IdaNativeProtocol.test.ts b/src/ida/IdaNativeProtocol.test.ts index 0e17167b394..820a70708c7 100644 --- a/src/ida/IdaNativeProtocol.test.ts +++ b/src/ida/IdaNativeProtocol.test.ts @@ -263,6 +263,11 @@ describe("native IDA provider observations", () => { ); if (!result.ok) throw result.error; expect(result.value.provider.name).toBe("IDA MCP adapter"); + if (operation === "xrefs") + expect( + result.value.referencesTruncated, + "the native producer's explicit cap flag is forwarded", + ).toBe(false); if (operation === "procedure_assembly") expect(result.value.result).toBe("0x1000: ret"); if (operation === "procedure_pseudo_code") { diff --git a/src/ida/IdaReferenceCoverage.test.ts b/src/ida/IdaReferenceCoverage.test.ts index 4617f572e9e..930c3a88a7b 100644 --- a/src/ida/IdaReferenceCoverage.test.ts +++ b/src/ida/IdaReferenceCoverage.test.ts @@ -1,10 +1,22 @@ +import { rm } from "node:fs/promises"; import { afterEach, describe, expect, it } from "vitest"; +import { + createIdaTarget, + RecordingIdaMcp, +} from "../../tests/fixtures/idaMcp.js"; import { callGraphSession as session, removeCallGraphSessions, } from "../../tests/fixtures/idaCallGraph.js"; -afterEach(removeCallGraphSessions); +import { IdaSessionClient } from "./IdaSessionClient.js"; + +const attachedRoots: string[] = []; +afterEach(async () => { + await removeCallGraphSessions(); + for (const root of attachedRoots.splice(0)) + await rm(root, { recursive: true, force: true }); +}); const xrefs = async (more: boolean | undefined) => { const { client, producer } = await session({ callees: [] }, "x86_64"); @@ -56,4 +68,29 @@ describe("headless IDA reference coverage", () => { expect((await client.close()).ok).toBe(true); } }); + + it("reports nothing for the legacy profile, whose producer has no cap flag", async () => { + const { root, target } = await createIdaTarget("x86_64"); + attachedRoots.push(root); + const client = new IdaSessionClient( + { + command: "fixture", + args: [], + env: {}, + mode: "attached", + timeoutMs: 1000, + workspaceRoot: root, + }, + target, + new RecordingIdaMcp(target, "attached"), + ); + try { + const result = await client.execute("xrefs", { address: "0x1000" }); + + if (!result.ok) throw result.error; + expect(result.value.referencesTruncated).toBeUndefined(); + } finally { + expect((await client.close()).ok).toBe(true); + } + }); }); diff --git a/tests/boundary/mcp/enhancedTools.traceFeatureCoverage.test.ts b/tests/boundary/mcp/enhancedTools.traceFeatureCoverage.test.ts index f44116de836..41e3b7d405e 100644 --- a/tests/boundary/mcp/enhancedTools.traceFeatureCoverage.test.ts +++ b/tests/boundary/mcp/enhancedTools.traceFeatureCoverage.test.ts @@ -2,7 +2,9 @@ import { afterEach, describe, expect, it } from "vitest"; import type { AnalysisOperationPort } from "../../../src/application/AnalysisProvider.js"; import { createAnalysisExecution } from "../../../src/application/AnalysisProvider.js"; -import { ok } from "../../../src/domain/result.js"; +import { EnhancedTools } from "../../../src/application/EnhancedTools.js"; +import { AnalysisOutputError } from "../../../src/domain/analysisErrorCore.js"; +import { err, ok } from "../../../src/domain/result.js"; import { closeEnhancedToolResources, connect } from "./enhancedToolsHarness.js"; @@ -16,18 +18,32 @@ const PROVIDER = { type Coverage = boolean | undefined; +interface Behavior { + /** What the provider reports for the references of each match address. */ + readonly coverage?: Readonly>; + readonly limitations?: readonly string[]; + /** Also report the first string match as a procedure match. */ + readonly duplicateProcedure?: boolean; + /** Fail the references read of this address. */ + readonly failXrefsOf?: string; + readonly calls?: string[]; +} + +const containing = (address: string) => ({ + query_address: address, + found: false, + procedure: null, + reason: "not_in_procedure", +}); + /** - * A provider with two string matches. Each match has one reference; the - * `coverage` map says what the provider reports for that target's references: - * `true` for a capped read, `false` for an explicitly complete one, and - * undefined for a provider that reports nothing. + * A provider with two string matches (0x10 and 0x11), each referenced from + * one address (0x20 and 0x21). */ -const provider = ( - coverage: Readonly>, - limitations: readonly string[] = [], -): AnalysisOperationPort => ({ +const provider = (behavior: Behavior = {}): AnalysisOperationPort => ({ execute: async (name, arguments_) => { const address = String(arguments_.address); + behavior.calls?.push(`${name}:${address}`); switch (name) { case "search_strings": return ok( @@ -40,15 +56,24 @@ const provider = ( ), ); case "search_procedures": - return ok(createAnalysisExecution([], PROVIDER)); + return ok( + createAnalysisExecution( + behavior.duplicateProcedure === true + ? [{ address: "0x10", value: "hello" }] + : [], + PROVIDER, + ), + ); case "xrefs": { - const reported = coverage[address]; + if (address === behavior.failXrefsOf) + return err(new AnalysisOutputError("xrefs", "provider failed")); + const reported = behavior.coverage?.[address]; return ok( createAnalysisExecution( [address === "0x10" ? "0x20" : "0x21"], PROVIDER, { - limitations, + limitations: behavior.limitations ?? [], ...(reported === undefined ? {} : { referencesTruncated: reported }), @@ -57,23 +82,48 @@ const provider = ( ); } case "resolve_containing_procedure": - return ok( - createAnalysisExecution( - { - query_address: address, - found: false, - procedure: null, - reason: "not_in_procedure", - }, - PROVIDER, - ), - ); + return ok(createAnalysisExecution(containing(address), PROVIDER)); default: throw new Error(`Unexpected operation: ${name}`); } }, }); +const expectedTrace = ( + residual: readonly string[], + extraMatches: readonly object[] = [], +) => ({ + query: "hello", + search_mode: "literal", + matches: [ + { type: "string", address: "0x10", value: "hello" }, + { type: "string", address: "0x11", value: "hello again" }, + ...extraMatches, + ], + references: [ + { + target_address: "0x10", + source_address: "0x20", + containing_procedure: containing("0x20"), + }, + { + target_address: "0x11", + source_address: "0x21", + containing_procedure: containing("0x21"), + }, + ...extraMatches.map(() => ({ + target_address: "0x10", + source_address: "0x20", + containing_procedure: containing("0x20"), + })), + ], + truncated: residual.length > 0, + residual_unknowns: residual, +}); + +const unknownFor = (address: string) => + `References to ${address} were truncated by the provider; additional references may exist.`; + const trace = async (analysis: AnalysisOperationPort) => { const client = await connect(analysis); const result = await client.callTool({ @@ -81,88 +131,97 @@ const trace = async (analysis: AnalysisOperationPort) => { arguments: { query: "hello" }, }); expect(result.isError).not.toBe(true); - return result.structuredContent as { - normalized_result: { - references: unknown[]; - truncated: boolean; - residual_unknowns: string[]; - }; - }; + return result.structuredContent as { normalized_result: unknown }; }; describe("trace_feature reference coverage", () => { it("marks the trace truncated for the target whose references the provider capped", async () => { - const output = await trace(provider({ "0x10": true, "0x11": false })); + const output = await trace( + provider({ coverage: { "0x10": true, "0x11": false } }), + ); expect( output.normalized_result, - "the returned references are kept and only the capped target is a residual unknown", - ).toMatchObject({ - references: [ - { target_address: "0x10", source_address: "0x20" }, - { target_address: "0x11", source_address: "0x21" }, - ], - truncated: true, - residual_unknowns: [ - "References to 0x10 were truncated by the provider; additional references may exist.", - ], - }); + "the received references are kept and only the capped target is a residual unknown", + ).toEqual(expectedTrace([unknownFor("0x10")])); + }); + + it("does not carry a truncation over to the next target that reports nothing", async () => { + const output = await trace(provider({ coverage: { "0x10": true } })); + + expect(output.normalized_result).toEqual( + expectedTrace([unknownFor("0x10")]), + ); + }); + + it("reports a capped target once when it is matched twice", async () => { + const output = await trace( + provider({ coverage: { "0x10": true }, duplicateProcedure: true }), + ); + + expect(output.normalized_result).toEqual( + expectedTrace( + [unknownFor("0x10")], + [{ type: "procedure", address: "0x10", value: "hello" }], + ), + ); }); it("keeps the trace complete when the provider explicitly reports no cap", async () => { - const output = await trace(provider({ "0x10": false, "0x11": false })); + const output = await trace( + provider({ coverage: { "0x10": false, "0x11": false } }), + ); - expect(output.normalized_result).toMatchObject({ - truncated: false, - residual_unknowns: [], - }); + expect(output.normalized_result).toEqual(expectedTrace([])); }); it("does not change the trace of a provider that reports no coverage", async () => { const output = await trace( - provider({}, ["Upstream xrefs_to capped results at 1000 references."]), + provider({ + limitations: ["Upstream xrefs_to capped results at 1000 references."], + }), ); expect( output.normalized_result, "a limitation text alone never truncates, and an absent field keeps the previous result", - ).toEqual({ - query: "hello", - search_mode: "literal", - matches: [ - { type: "string", address: "0x10", value: "hello" }, - { type: "string", address: "0x11", value: "hello again" }, - ], - references: [ - { - target_address: "0x10", - source_address: "0x20", - containing_procedure: { - query_address: "0x20", - found: false, - procedure: null, - reason: "not_in_procedure", - }, - }, - { - target_address: "0x11", - source_address: "0x21", - containing_procedure: { - query_address: "0x21", - found: false, - procedure: null, - reason: "not_in_procedure", - }, - }, - ], - truncated: false, - residual_unknowns: [], - }); + ).toEqual(expectedTrace([])); }); it("never exposes the coverage field in the tool output", async () => { - const output = await trace(provider({ "0x10": true, "0x11": false })); + const output = await trace( + provider({ coverage: { "0x10": true, "0x11": false } }), + ); + + expect(JSON.stringify(output)).not.toMatch( + /referencesTruncated|references_truncated/, + ); + }); + + it("fails the trace when a references read fails and reads nothing further", async () => { + const calls: string[] = []; + const result = await new EnhancedTools( + provider({ failXrefsOf: "0x10", calls }), + ).execute("trace_feature", { query: "hello" }); + + expect(result.ok).toBe(false); + expect( + calls.filter((call) => call.startsWith("xrefs:")), + "the next target is not read after the failure", + ).toEqual(["xrefs:0x10"]); + }); + + it("stops without reading references when the trace is cancelled", async () => { + const calls: string[] = []; + const controller = new AbortController(); + controller.abort(); + const result = await new EnhancedTools(provider({ calls })).execute( + "trace_feature", + { query: "hello" }, + controller.signal, + ); - expect(JSON.stringify(output)).not.toContain("referencesTruncated"); + expect(result.ok).toBe(false); + expect(calls.filter((call) => call.startsWith("xrefs:"))).toEqual([]); }); }); diff --git a/tests/composition/analysis-sessions/binarySession.test.ts b/tests/composition/analysis-sessions/binarySession.test.ts index 813b90004bf..bdda65d9a85 100644 --- a/tests/composition/analysis-sessions/binarySession.test.ts +++ b/tests/composition/analysis-sessions/binarySession.test.ts @@ -1278,3 +1278,98 @@ describe("selector origin forwarding", () => { ).toEqual(["provider", "provider", undefined]); }); }); + +describe("reference truncation forwarding", () => { + const referenceProvider = ( + referencesTruncated: boolean | undefined, + calls: string[], + ): AnalysisProvider => { + const identity = { + id: "fixture", + name: "Fixture analysis provider", + version: "1", + } as const; + return { + identity: () => identity, + resolveAnalysisProfile: () => + Promise.resolve( + resultOk({ + profile: createAnalysisProfile(identity, { fixture: true }), + }), + ), + capabilities: () => [ + { + provider: identity, + operation: "xrefs", + available: true, + reason: null, + effects: { + mutatesArtifact: false, + launchesProcess: false, + mayShowUi: false, + mayAccessNetwork: false, + mayWriteFilesystem: false, + changesPermissions: false, + requiresRoot: false, + }, + limitations: [], + }, + ], + createClient: () => ({ + execute: (operation) => { + calls.push(operation); + return Promise.resolve( + resultOk( + createAnalysisExecution(["0x2000"], identity, (referencesTruncated === undefined + ? {} + : { referencesTruncated })), + ), + ); + }, + close: () => Promise.resolve(resultOk(null)), + }), + }; + }; + const parameters = { address: "0x1000", document: "fixture" }; + + it("forwards a truncation on both execution paths and never replays it from the snapshot", async () => { + const [first] = await createBinarySessionTargets(); + const calls: string[] = []; + const session = createTestBinarySession(referenceProvider(true, calls)); + expect((await session.open(first)).ok).toBe(true); + calls.length = 0; + + const direct = await session.execute("xrefs", parameters); + const admitted = await session.withAdmittedAnalysis( + "trace_feature", + undefined, + (analysis) => analysis.execute("xrefs", parameters), + ); + + expect(direct.ok && direct.value.referencesTruncated).toBe(true); + if (!admitted.ok) throw admitted.error; + expect(admitted.value.ok && admitted.value.value.referencesTruncated).toBe( + true, + ); + expect( + calls, + "a truncated read is not recorded, so every call reaches the provider", + ).toEqual(["xrefs", "xrefs"]); + }); + + it("keeps an explicit complete report out of the way of snapshot replay", async () => { + const [first] = await createBinarySessionTargets(); + const calls: string[] = []; + const session = createTestBinarySession(referenceProvider(false, calls)); + expect((await session.open(first)).ok).toBe(true); + calls.length = 0; + + const live = await session.execute("xrefs", parameters); + await session.execute("xrefs", parameters); + + expect(live.ok && live.value.referencesTruncated).toBe(false); + expect(calls, "the complete read is recorded and replayed").toEqual([ + "xrefs", + ]); + }); +}); From 142f8ad693b4a32e80a2f15e14892802973bff72 Mon Sep 17 00:00:00 2001 From: Mykola Dementiev Date: Mon, 12 Oct 2026 22:12:59 +0200 Subject: [PATCH 05/30] test(mcp): format the session forwarding test --- tests/composition/analysis-sessions/binarySession.test.ts | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/tests/composition/analysis-sessions/binarySession.test.ts b/tests/composition/analysis-sessions/binarySession.test.ts index bdda65d9a85..092f869e237 100644 --- a/tests/composition/analysis-sessions/binarySession.test.ts +++ b/tests/composition/analysis-sessions/binarySession.test.ts @@ -1320,9 +1320,13 @@ describe("reference truncation forwarding", () => { calls.push(operation); return Promise.resolve( resultOk( - createAnalysisExecution(["0x2000"], identity, (referencesTruncated === undefined + createAnalysisExecution( + ["0x2000"], + identity, + referencesTruncated === undefined ? {} - : { referencesTruncated })), + : { referencesTruncated }, + ), ), ); }, From bfcb5afdeaf2663ac9a1b9d8a0ada03d371f0584 Mon Sep 17 00:00:00 2001 From: Mykola Dementiev Date: Mon, 12 Oct 2026 22:22:05 +0200 Subject: [PATCH 06/30] test(ida): expect headless IDA to resolve containing procedures from lookups and segment facts Cover positive and negative containment, segment boundaries including addresses above 2^53, failures of the lookup and of the segment survey, cancellation, input validation and the admitted program as the only document. --- src/ida/IdaContainment.test.ts | 453 +++++++++++++++++++++++++++++++++ tests/fixtures/idaMcp.ts | 1 + 2 files changed, 454 insertions(+) create mode 100644 src/ida/IdaContainment.test.ts diff --git a/src/ida/IdaContainment.test.ts b/src/ida/IdaContainment.test.ts new file mode 100644 index 00000000000..dc754eff433 --- /dev/null +++ b/src/ida/IdaContainment.test.ts @@ -0,0 +1,453 @@ +import { rm } from "node:fs/promises"; +import { afterEach, describe, expect, it } from "vitest"; +import type { JsonValue } from "../domain/jsonValue.js"; +import { + createIdaTarget, + RecordingIdaMcp, +} from "../../tests/fixtures/idaMcp.js"; +import { decodeIdaToolResult } from "./IdaMcpConnection.js"; +import { idaCapabilities } from "./IdaProviderCapabilities.js"; +import { IdaSessionClient } from "./IdaSessionClient.js"; + +const roots: string[] = []; +afterEach(async () => { + for (const root of roots.splice(0)) + await rm(root, { recursive: true, force: true }); +}); + +const segment = (name: string, start: string, end: string) => ({ + name, + start, + end, + size: `0x${(BigInt(end) - BigInt(start)).toString(16)}`, + permissions: "r--", +}); + +/** Adjacent .text and .data, a gap, then a segment above 2^53. */ +const SEGMENTS = [ + segment(".text", "0x1000", "0x2000"), + segment(".data", "0x2000", "0x3000"), + segment(".far", "0x5000", "0x6000"), + segment(".huge", "0x20000000000000", "0x20000000000010"), +]; + +const survey = (segments: JsonValue = SEGMENTS) => ({ + metadata: { path: "/db/target.i64", module: "target", arch: "metapc" }, + statistics: { total_segments: 4 }, + segments, + entrypoints: [], +}); + +const function_ = { addr: "0x1000", name: "main", size: "0x20" }; + +const MODERN_WITHOUT_SURVEY = [ + "idb_open", + "idb_list", + "idb_close", + "server_health", + "list_funcs", + "lookup_funcs", + "find_regex", + "decompile", + "disasm", + "callees", + "xrefs_to", +]; + +interface Upstream { + /** Answer for the lookup of the queried address; default is "Not a function". */ + readonly lookup?: (query: string) => JsonValue; + readonly survey?: JsonValue; + readonly tools?: readonly string[]; + readonly surveyFailure?: "error" | "preview"; +} + +const session = async ( + upstream: Upstream = {}, + mode: "headless" | "attached" = "headless", +) => { + const { root, target } = await createIdaTarget("x86_64"); + roots.push(root); + const producer = new RecordingIdaMcp(target, mode); + if (upstream.tools !== undefined) producer.tools = upstream.tools; + producer.beforeCall = async (name) => { + if (name !== "survey_binary") return; + if (upstream.surveyFailure === "error") + decodeIdaToolResult({ + content: [{ type: "text", text: "survey failed" }], + isError: true, + }); + if (upstream.surveyFailure === "preview") + decodeIdaToolResult({ + content: [{ type: "text", text: "preview" }], + _meta: { ida_mcp: { output_truncated: true } }, + }); + }; + producer.overrideCall = (name, args) => { + if (name === "lookup_funcs") { + const queries = Array.isArray(args.queries) ? args.queries : []; + return queries.map((query) => + upstream.lookup === undefined + ? { query, fn: null, error: "Not a function" } + : upstream.lookup(String(query)), + ); + } + if (name === "survey_binary") return upstream.survey ?? survey(); + return undefined; + }; + const client = new IdaSessionClient( + { + command: "fixture", + args: [], + env: {}, + mode, + timeoutMs: 1000, + workspaceRoot: root, + }, + target, + producer, + ); + return { client, producer, target }; +}; + +const containing = async ( + client: IdaSessionClient, + address: string, + options?: Parameters[2], +) => client.execute("resolve_containing_procedure", { address }, options); + +const found = (query: string, fn: typeof function_) => ({ + query, + fn, + error: null, +}); + +describe("IDA containment capabilities", () => { + it("declares both operations for the headless profile only", () => { + const declared = (mode: "attached" | "headless", native = false) => + idaCapabilities(mode, false, native) + .filter(({ available }) => available) + .map(({ operation }) => operation) + .filter( + (operation) => + operation === "resolve_containing_procedure" || + operation === "list_documents", + ); + + expect(declared("headless")).toEqual([ + "resolve_containing_procedure", + "list_documents", + ]); + expect(declared("attached")).toEqual([]); + expect(declared("attached", true)).toEqual([]); + expect( + idaCapabilities("attached", false).map(({ operation }) => operation), + "attached profiles do not even declare them", + ).not.toContain("list_documents"); + }); + + it.each(["resolve_containing_procedure", "list_documents"] as const)( + "refuses %s on the legacy attached profile without calling upstream", + async (operation) => { + const { client, producer } = await session({}, "attached"); + try { + const result = await client.execute( + operation, + operation === "list_documents" ? {} : { address: "0x1000" }, + ); + + expect(result.ok).toBe(false); + if (!result.ok) + expect(result.error._tag).toBe("AnalysisCapabilityUnavailableError"); + expect(producer.calls.some(({ name }) => name === "lookup_funcs")).toBe( + false, + ); + } finally { + expect((await client.close()).ok).toBe(true); + } + }, + ); +}); + +describe("headless IDA containing procedure", () => { + it("returns the canonical entry for an interior address without reading segments", async () => { + const { client, producer } = await session({ + lookup: (query) => found(query, function_), + }); + try { + const result = await containing(client, "1ffe"); + + if (!result.ok) throw result.error; + expect(result.value.result).toEqual({ + query_address: "0x1ffe", + found: true, + procedure: { + address: "0x1000", + name: "main", + classification: null, + body: { + available: false, + reason: "IDA MCP does not report complete function body ranges.", + }, + }, + }); + expect( + producer.calls.filter(({ name }) => name === "lookup_funcs"), + "the normalized address is the only query", + ).toMatchObject([{ args: { queries: ["0x1ffe"] } }]); + expect( + producer.calls.some(({ name }) => name === "survey_binary"), + "a positive answer needs no segment facts", + ).toBe(false); + } finally { + expect((await client.close()).ok).toBe(true); + } + }); + + it.each([ + ["inside the first segment", "0x1000", "not_in_procedure"], + ["inside an adjacent segment", "0x2000", "not_in_procedure"], + [ + "at the exclusive end of the last adjacent segment", + "0x3000", + "outside_segments", + ], + ["in the gap between segments", "0x4000", "outside_segments"], + ["one below a segment start", "0xfff", "outside_segments"], + ["the last byte of a segment", "0x5fff", "not_in_procedure"], + ["above every segment", "0x6000", "outside_segments"], + ["inside a segment above 2^53", "0x20000000000001", "not_in_procedure"], + [ + "at the exclusive end of that segment", + "0x20000000000010", + "outside_segments", + ], + ] as const)( + "reports an address that is not a function %s as %s", + async (_description, address, reason) => { + const { client, producer } = await session(); + try { + const result = await containing(client, address); + + if (!result.ok) throw result.error; + expect(result.value.result).toEqual({ + query_address: address, + found: false, + procedure: null, + reason, + }); + expect( + producer.calls.find(({ name }) => name === "survey_binary")?.args, + "the minimal survey is the only segment source", + ).toMatchObject({ detail_level: "minimal" }); + expect( + producer.calls.filter(({ name }) => name === "survey_binary"), + ).toHaveLength(1); + } finally { + expect((await client.close()).ok).toBe(true); + } + }, + ); +}); + +describe("headless IDA containment failures", () => { + it.each([ + ["no segments field", { metadata: {}, statistics: {} }], + ["segments that are null", survey(null)], + [ + "a row with a malformed address", + survey([ + { + name: ".x", + start: "0xzz", + end: "0x2000", + size: "0x1000", + permissions: "r--", + }, + ]), + ], + ["a reversed segment", survey([segment(".x", "0x2000", "0x1000")])], + [ + "a size that disagrees with the bounds", + survey([{ ...segment(".x", "0x1000", "0x2000"), size: "0x10" }]), + ], + [ + "a total that disagrees with the rows", + { ...survey(), statistics: { total_segments: 9 } }, + ], + ["a malformed row after valid ones", survey([...SEGMENTS, { name: ".y" }])], + ] as const)( + "fails instead of guessing a reason when the survey has %s", + async (_description, reply) => { + const { client } = await session({ survey: reply as JsonValue }); + try { + const result = await containing(client, "0x4000"); + + expect(result.ok).toBe(false); + if (!result.ok) expect(result.error._tag).toBe("AnalysisProtocolError"); + } finally { + expect((await client.close()).ok).toBe(true); + } + }, + ); + + it.each(["error", "preview"] as const)( + "fails when the survey tool reports %s", + async (surveyFailure) => { + const { client } = await session({ surveyFailure }); + try { + const result = await containing(client, "0x4000"); + + expect(result.ok).toBe(false); + } finally { + expect((await client.close()).ok).toBe(true); + } + }, + ); + + it("fails without a segment source when the server does not advertise the survey", async () => { + const { client, producer } = await session({ + tools: MODERN_WITHOUT_SURVEY, + }); + try { + const negative = await containing(client, "0x4000"); + + expect(negative.ok).toBe(false); + expect( + producer.calls.some(({ name }) => name === "survey_binary"), + "an unadvertised tool is never requested", + ).toBe(false); + } finally { + expect((await client.close()).ok).toBe(true); + } + }); + + it("still answers a positive lookup when the server does not advertise the survey", async () => { + const { client } = await session({ + lookup: (query) => found(query, function_), + tools: MODERN_WITHOUT_SURVEY, + }); + try { + const result = await containing(client, "0x1010"); + + expect(result.ok).toBe(true); + } finally { + expect((await client.close()).ok).toBe(true); + } + }); +}); + +describe("headless IDA containment lookup failures", () => { + it.each([ + ["an answer for another query", () => found("0x9999", function_)], + [ + "a function together with an error", + (query: string) => ({ query, fn: function_, error: "Not found" }), + ], + [ + "neither a function nor an error", + (query: string) => ({ query, fn: null, error: null }), + ], + [ + "an unknown error text", + (query: string) => ({ query, fn: null, error: "boom" }), + ], + [ + "a padded missing answer", + (query: string) => ({ query, fn: null, error: " Not a function" }), + ], + ] as const)( + "treats %s as a producer failure and reads no segments", + async (_description, lookup) => { + const { client, producer } = await session({ lookup }); + try { + const result = await containing(client, "0x4000"); + + expect(result.ok).toBe(false); + if (!result.ok) expect(result.error._tag).toBe("AnalysisProtocolError"); + expect( + producer.calls.some(({ name }) => name === "survey_binary"), + ).toBe(false); + } finally { + expect((await client.close()).ok).toBe(true); + } + }, + ); + + it('treats "Not found" for an address like any expected missing answer', async () => { + const { client } = await session({ + lookup: (query) => ({ query, fn: null, error: "Not found" }), + }); + try { + const result = await containing(client, "0x4000"); + + if (!result.ok) throw result.error; + expect(result.value.result).toMatchObject({ + found: false, + reason: "outside_segments", + }); + } finally { + expect((await client.close()).ok).toBe(true); + } + }); + + it("stops before the survey when the request is cancelled after the lookup", async () => { + const controller = new AbortController(); + const { client, producer } = await session(); + const inner = producer.beforeCall; + producer.beforeCall = async (name, args) => { + await inner?.(name, args); + if (name === "lookup_funcs") controller.abort(); + }; + try { + const result = await containing(client, "0x4000", { + signal: controller.signal, + }); + + expect(result.ok).toBe(false); + if (!result.ok) expect(result.error._tag).toBe("AnalysisCancelledError"); + expect( + producer.calls.some(({ name }) => name === "survey_binary"), + "nothing is dispatched after cancellation", + ).toBe(false); + } finally { + expect((await client.close()).ok).toBe(true); + } + }); + + it("rejects an address that is not hexadecimal and a document that is not the admitted target", async () => { + const { client, producer } = await session(); + try { + const badAddress = await containing(client, "main"); + const badDocument = await client.execute("resolve_containing_procedure", { + address: "0x1000", + document: "/somewhere/else", + }); + + for (const result of [badAddress, badDocument]) { + expect(result.ok).toBe(false); + if (!result.ok) expect(result.error._tag).toBe("AnalysisInputError"); + } + expect( + producer.calls.some(({ name }) => name === "lookup_funcs"), + "invalid input never reaches upstream", + ).toBe(false); + } finally { + expect((await client.close()).ok).toBe(true); + } + }); +}); + +describe("headless IDA document identity", () => { + it("lists exactly the admitted program", async () => { + const { client, target } = await session(); + try { + const result = await client.execute("list_documents", {}); + + if (!result.ok) throw result.error; + expect(result.value.result).toEqual([target.path]); + } finally { + expect((await client.close()).ok).toBe(true); + } + }); +}); diff --git a/tests/fixtures/idaMcp.ts b/tests/fixtures/idaMcp.ts index 04bdb5f16d8..21e5e38f716 100644 --- a/tests/fixtures/idaMcp.ts +++ b/tests/fixtures/idaMcp.ts @@ -57,6 +57,7 @@ const modernNames = [ "callees", "xrefs_to", "callgraph", + "survey_binary", ]; /** Stateful producer fixture at the real connection seam; no module mocking. */ From 99ff05d09d2fcc77b52e4b728f3058be64581ade Mon Sep 17 00:00:00 2001 From: Mykola Dementiev Date: Mon, 12 Oct 2026 22:22:06 +0200 Subject: [PATCH 07/30] test(ida): expect feature tracing and address context to work on headless IDA Run trace_feature, including a capped reference read, and inspect_address_context with and without an explicit document through the IDA session client. --- .../providers/ida/containment.test.ts | 144 ++++++++++++++++++ .../conformance/ida/providerContracts.test.ts | 16 +- 2 files changed, 157 insertions(+), 3 deletions(-) create mode 100644 tests/boundary/providers/ida/containment.test.ts diff --git a/tests/boundary/providers/ida/containment.test.ts b/tests/boundary/providers/ida/containment.test.ts new file mode 100644 index 00000000000..75eb78f4244 --- /dev/null +++ b/tests/boundary/providers/ida/containment.test.ts @@ -0,0 +1,144 @@ +import { rm } from "node:fs/promises"; +import { afterEach, describe, expect, it } from "vitest"; +import { inspectAddressContext } from "../../../../src/application/AnalysisContextQueries.js"; +import { EnhancedTools } from "../../../../src/application/EnhancedTools.js"; +import { IdaSessionClient } from "../../../../src/ida/IdaSessionClient.js"; +import { createIdaTarget, RecordingIdaMcp } from "../../../fixtures/idaMcp.js"; + +const roots: string[] = []; +afterEach(async () => { + for (const root of roots.splice(0)) + await rm(root, { recursive: true, force: true }); +}); + +const session = async (cappedReferences = false) => { + const { root, target } = await createIdaTarget("arm64"); + roots.push(root); + const producer = new RecordingIdaMcp(target, "headless"); + if (cappedReferences) { + const inner = producer.overrideCall; + producer.overrideCall = (name, args) => + name === "xrefs_to" + ? [ + { + xrefs: [ + { + addr: "0x1004", + type: "code", + fn: { addr: "0x1000", name: "main", size: "0x20" }, + }, + ], + more: true, + }, + ] + : inner?.(name, args); + } + const client = new IdaSessionClient( + { + command: "fixture", + args: [], + env: {}, + mode: "headless", + timeoutMs: 1000, + workspaceRoot: root, + }, + target, + producer, + ); + return { client, target }; +}; + +const MAIN = { + found: true, + procedure: { address: "0x1000", name: "main" }, +}; + +describe("trace_feature on headless IDA", () => { + it("attributes a reference to its containing procedure", async () => { + const { client } = await session(); + try { + const result = await new EnhancedTools(client).execute("trace_feature", { + query: "a.b", + }); + + if (!result.ok) throw result.error; + expect(result.value).toMatchObject({ + matches: [{ type: "string", address: "0x3000" }], + references: [ + { + target_address: "0x3000", + source_address: "0x1004", + containing_procedure: MAIN, + }, + ], + truncated: false, + residual_unknowns: [], + }); + } finally { + expect((await client.close()).ok).toBe(true); + } + }); + + it("keeps an upstream reference cap visible once containment makes the trace run", async () => { + const { client } = await session(true); + try { + const result = await new EnhancedTools(client).execute("trace_feature", { + query: "a.b", + }); + + if (!result.ok) throw result.error; + expect(result.value).toMatchObject({ + references: [{ source_address: "0x1004", containing_procedure: MAIN }], + truncated: true, + residual_unknowns: [ + "References to 0x3000 were truncated by the provider; additional references may exist.", + ], + }); + } finally { + expect((await client.close()).ok).toBe(true); + } + }); +}); + +describe("inspect_address_context on headless IDA", () => { + it("resolves the admitted program as the document and reports the containing procedure", async () => { + const { client, target } = await session(); + try { + const result = await inspectAddressContext(client, { + address: "0x1004", + }); + + if (!result.ok) throw result.error; + expect(result.value).toMatchObject({ + address: "0x1004", + document: target.path, + procedure: { state: "available", value: MAIN }, + name: { state: "unavailable" }, + comment: { state: "unavailable" }, + inline_comment: { state: "unavailable" }, + bookmarks: { state: "unavailable" }, + }); + } finally { + expect((await client.close()).ok).toBe(true); + } + }); + + it("answers the same way for an explicit admitted document", async () => { + const { client, target } = await session(); + try { + const implicit = await inspectAddressContext(client, { + address: "0x1004", + }); + const explicit = await inspectAddressContext(client, { + address: "0x1004", + document: target.path, + }); + + if (!implicit.ok) throw implicit.error; + if (!explicit.ok) throw explicit.error; + expect(explicit.value).toEqual(implicit.value); + } finally { + expect((await client.close()).ok).toBe(true); + } + }); +}); diff --git a/tests/conformance/ida/providerContracts.test.ts b/tests/conformance/ida/providerContracts.test.ts index 39c524637df..4e4b04c3b01 100644 --- a/tests/conformance/ida/providerContracts.test.ts +++ b/tests/conformance/ida/providerContracts.test.ts @@ -29,15 +29,25 @@ const parametersFor = ( operation: string, ): Readonly> => { if (operation.startsWith("search_")) return { pattern: "a.b" }; - if (operation === "xrefs") return { address: "0x1000" }; + if (operation === "xrefs" || operation === "resolve_containing_procedure") + return { address: "0x1000" }; if (operation.startsWith("list_")) return {}; return { procedure: "main" }; }; +/** Operations only the headless profile declares. */ +const HEADLESS_ONLY: ReadonlySet = new Set([ + "resolve_containing_procedure", + "list_documents", +]); + describe.each(["attached", "headless"] as const)( "IDA %s caller-visible contracts", (mode) => { - it.each(IDA_OPERATIONS)( + const operations = IDA_OPERATIONS.filter( + (operation) => mode === "headless" || !HEADLESS_ONLY.has(operation), + ); + it.each(operations)( "declares %s UI effects matching the upstream tools it reaches", async (operation) => { const { root, target } = await createIdaTarget(); @@ -69,7 +79,7 @@ describe.each(["attached", "headless"] as const)( }, ); - it.each(IDA_OPERATIONS)( + it.each(operations)( "serializes %s against its named advertised output contract", async (operation) => { const { root, target } = await createIdaTarget(); From 64701e8f39fadedcd984e0829fe31e3fa2bd366d Mon Sep 17 00:00:00 2001 From: Mykola Dementiev Date: Mon, 12 Oct 2026 22:22:48 +0200 Subject: [PATCH 08/30] test(mcp): expect trace_feature availability to follow the search operations it calls --- src/application/CapabilityInventory.test.ts | 45 +++++++++++++++++++++ 1 file changed, 45 insertions(+) diff --git a/src/application/CapabilityInventory.test.ts b/src/application/CapabilityInventory.test.ts index 1b8ec641124..2edd8358173 100644 --- a/src/application/CapabilityInventory.test.ts +++ b/src/application/CapabilityInventory.test.ts @@ -497,3 +497,48 @@ it("reports host denial before target mismatch but keeps composed workflow prere ).reason, ).toBe("target_required"); }); + +describe("trace_feature requirements", () => { + const capabilities = (operations: readonly string[]) => + operations.map((operation) => ({ + operation, + available: true, + reason: null, + })); + + it("needs the search operations the workflow actually calls", () => { + expect( + entry( + "trace_feature", + status({ + open: true, + kind: "executable", + capabilities: capabilities([ + "search_strings", + "search_procedures", + "xrefs", + "resolve_containing_procedure", + ]), + }), + ), + ).toMatchObject({ available: true, reason: "available" }); + }); + + it("is unavailable when only the list operations exist", () => { + expect( + entry( + "trace_feature", + status({ + open: true, + kind: "executable", + capabilities: capabilities([ + "list_strings", + "list_procedures", + "xrefs", + "resolve_containing_procedure", + ]), + }), + ), + ).toMatchObject({ available: false, reason: "provider_missing" }); + }); +}); From a88a9ea22567984bfdea3e12c274fc346fbd4e64 Mon Sep 17 00:00:00 2001 From: Mykola Dementiev Date: Mon, 12 Oct 2026 22:25:25 +0200 Subject: [PATCH 09/30] fix(mcp): derive trace_feature availability from the search operations it calls --- src/application/CapabilityInventory.ts | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/application/CapabilityInventory.ts b/src/application/CapabilityInventory.ts index 73ffaecf976..2e282f68aa7 100644 --- a/src/application/CapabilityInventory.ts +++ b/src/application/CapabilityInventory.ts @@ -119,8 +119,8 @@ const ENHANCED_REQUIREMENTS: Readonly> = { analyze_function: ["analyze_function"], inspect_native_api: ["analyze_function"], trace_feature: [ - "list_strings", - "list_procedures", + "search_strings", + "search_procedures", "xrefs", "resolve_containing_procedure", ], From 6c46908341754e263aa3987e5df0fb9c600a2d0b Mon Sep 17 00:00:00 2001 From: Mykola Dementiev Date: Mon, 12 Oct 2026 22:25:26 +0200 Subject: [PATCH 10/30] feat(ida): resolve containing procedures and report the admitted program as the document The modern headless profile resolves an address through the function lookup and, when no function contains it, tells a mapped address from an unmapped one using the database-scoped minimal survey. A survey that is missing, truncated or inconsistent fails the read. list_documents reports the single admitted program. The attached profiles do not declare either operation. --- src/ida/IdaContainment.test.ts | 2 +- src/ida/IdaOperationRunner.ts | 103 +++++++++++++++++++++++------ src/ida/IdaProtocolValues.ts | 50 ++++++++++++++ src/ida/IdaProviderCapabilities.ts | 79 +++++++++++++--------- src/ida/IdaSessionClient.ts | 16 +++++ 5 files changed, 198 insertions(+), 52 deletions(-) diff --git a/src/ida/IdaContainment.test.ts b/src/ida/IdaContainment.test.ts index dc754eff433..8fcb5e4b7d8 100644 --- a/src/ida/IdaContainment.test.ts +++ b/src/ida/IdaContainment.test.ts @@ -284,7 +284,7 @@ describe("headless IDA containment failures", () => { const result = await containing(client, "0x4000"); expect(result.ok).toBe(false); - if (!result.ok) expect(result.error._tag).toBe("AnalysisProtocolError"); + if (!result.ok) expect(result.error._tag).toBe("AnalysisOutputError"); } finally { expect((await client.close()).ok).toBe(true); } diff --git a/src/ida/IdaOperationRunner.ts b/src/ida/IdaOperationRunner.ts index e87b879f870..efa1ecf9da4 100644 --- a/src/ida/IdaOperationRunner.ts +++ b/src/ida/IdaOperationRunner.ts @@ -44,6 +44,7 @@ import { modernStringsSchema, modernXrefsSchema, nextOffset, + surveySegmentsSchema, type IdaDisassembly, type IdaFunction, } from "./IdaProtocolValues.js"; @@ -125,6 +126,10 @@ export class IdaOperationRunner { readonly x86Only?: boolean; /** False when the upstream server does not advertise `callgraph`. */ readonly callGraphAvailable?: boolean; + /** False when the upstream server does not advertise `survey_binary`. */ + readonly surveyAvailable?: boolean; + /** The program identity REA admitted, reported by `list_documents`. */ + readonly admittedDocument?: string; } = {}, ) {} @@ -205,41 +210,89 @@ export class IdaOperationRunner { return entry; } - private lookupFunction( + /** Parse one lookup row: a function, an expected "missing" answer, or a producer failure. */ + private lookupOutcome( query: string, item: z.infer[number] | undefined, - requestedBy?: string, - ): IdaFunction { + ): { readonly fn: IdaFunction } | { readonly missing: string } { if (item?.query !== query) throw new AnalysisProtocolError( `IDA function lookup answered for a different query than ${JSON.stringify(query)}.`, ); if ( - requestedBy !== undefined && item.fn === null && item.error !== null && MISSING_PROCEDURE_ANSWERS.has(item.error) ) - throw new AnalysisInputError( - requestedBy, - { - cause: new AnalysisProtocolError( - `IDA function lookup failed for ${query}: ${item.error}`, - ), - }, - [ - { - path: [], - reason: "invalid_value", - message: `IDA could not resolve procedure ${JSON.stringify(query)}: ${item.error}.`, - }, - ], - ); + return { missing: item.error }; if (item.fn === null || item.error !== null) throw new AnalysisProtocolError( `IDA function lookup failed for ${query}: ${item.error ?? "missing function"}`, ); - return item.fn; + return { fn: item.fn }; + } + + private lookupFunction( + query: string, + item: z.infer[number] | undefined, + requestedBy?: string, + ): IdaFunction { + const outcome = this.lookupOutcome(query, item); + if ("fn" in outcome) return outcome.fn; + if (requestedBy === undefined) + throw new AnalysisProtocolError( + `IDA function lookup failed for ${query}: ${outcome.missing}`, + ); + throw new AnalysisInputError( + requestedBy, + { + cause: new AnalysisProtocolError( + `IDA function lookup failed for ${query}: ${outcome.missing}`, + ), + }, + [ + { + path: [], + reason: "invalid_value", + message: `IDA could not resolve procedure ${JSON.stringify(query)}: ${outcome.missing}.`, + }, + ], + ); + } + + /** The containing function of an address, or why none contains it. */ + private async containingProcedure(address: string): Promise { + const item = modernLookupSchema.parse( + await this.call("lookup_funcs", { queries: [address] }), + )[0]; + const outcome = this.lookupOutcome(address, item); + if ("fn" in outcome) + return { + query_address: address, + found: true, + procedure: identity(outcome.fn), + }; + return { + query_address: address, + found: false, + procedure: null, + reason: (await this.addressInSegment(address)) + ? "not_in_procedure" + : "outside_segments", + }; + } + + /** Segment membership from the database-scoped minimal survey; a missing fact is a failure. */ + private async addressInSegment(address: string): Promise { + if (this.options.surveyAvailable === false) + throw new AnalysisProtocolError( + "The upstream server does not advertise survey_binary, so segment membership cannot be established.", + ); + const { segments } = surveySegmentsSchema.parse( + await this.call("survey_binary", { detail_level: "minimal" }), + ); + const value = BigInt(address); + return segments.some(({ start, end }) => start <= value && value < end); } /** True only for modern callee reads on targets not proven x86-only; x86 reads never reach the graph code. */ @@ -565,6 +618,16 @@ export class IdaOperationRunner { address === idaAddressSchema.parse(parameters.address), ); } + if (operation === "list_documents") { + if (this.options.admittedDocument === undefined) + throw new AnalysisProtocolError("The admitted IDA program is unknown."); + return [this.options.admittedDocument]; + } + if (operation === "resolve_containing_procedure") { + const queried = idaAddressSchema.parse(parameters.address); + this.locations.push({ kind: "address", address: queried }); + return this.containingProcedure(queried); + } if (operation === "xrefs") { const inspectedAddress = idaAddressSchema.parse(parameters.address); this.locations.push({ kind: "address", address: inspectedAddress }); diff --git a/src/ida/IdaProtocolValues.ts b/src/ida/IdaProtocolValues.ts index 93ddbef8885..d4afb92db26 100644 --- a/src/ida/IdaProtocolValues.ts +++ b/src/ida/IdaProtocolValues.ts @@ -247,3 +247,53 @@ export const absentDatabaseCloseSchema = (sessionId: string) => z .object({ error: z.literal(`Session not found: ${sessionId}`) }) .passthrough(); + +// Piped, so a malformed coordinate is a schema issue and never reaches BigInt. +const hexCoordinate = z + .string() + .regex(/^0x[0-9a-f]+$/iu) + .pipe(z.transform((value) => BigInt(value))); + +/** + * The minimal `survey_binary` reply, reduced to validated segment intervals + * (exclusive ends). Any malformed, reversed or inconsistent fact rejects the + * whole reply, because a membership answer needs every segment. + */ +export const surveySegmentsSchema = z + .object({ + statistics: z + .object({ total_segments: z.number().int().nonnegative().optional() }) + .passthrough() + .optional(), + segments: z + .array( + z + .object({ + start: hexCoordinate, + end: hexCoordinate, + size: hexCoordinate.optional(), + }) + .passthrough(), + ) + .min(1), + }) + .passthrough() + .superRefine(({ statistics, segments }, context) => { + if ( + statistics?.total_segments !== undefined && + statistics.total_segments !== segments.length + ) + context.addIssue({ + code: "custom", + message: "survey segment count disagrees with its statistics", + }); + for (const { start, end, size } of segments) { + // A malformed row has already reported its own issue; refinements still run. + if (typeof start !== "bigint" || typeof end !== "bigint") continue; + if (start >= end || (size !== undefined && size !== end - start)) + context.addIssue({ + code: "custom", + message: "survey segment bounds are reversed or inconsistent", + }); + } + }); diff --git a/src/ida/IdaProviderCapabilities.ts b/src/ida/IdaProviderCapabilities.ts index d52c949e010..0ccc016d250 100644 --- a/src/ida/IdaProviderCapabilities.ts +++ b/src/ida/IdaProviderCapabilities.ts @@ -24,9 +24,23 @@ export const IDA_OPERATIONS = Object.freeze([ "read_function_instructions", "xrefs", "analyze_function", + "resolve_containing_procedure", + "list_documents", ] as const satisfies readonly Exclude[]); export type IdaOperation = (typeof IDA_OPERATIONS)[number]; +/** Operations only the modern headless profile implements. */ +const HEADLESS_ONLY_OPERATIONS: ReadonlySet = new Set([ + "resolve_containing_procedure", + "list_documents", +]); + +/** Whether the configured profile admits an operation. */ +export const idaProfileAdmits = ( + operation: IdaOperation, + mode: "attached" | "headless", +): boolean => mode === "headless" || !HEADLESS_ONLY_OPERATIONS.has(operation); + /** Shared limitations of observations from an externally mutable analysis database. */ export const IDA_LIMITATIONS = Object.freeze([ "Provider version identifies the REA IDA adapter. IDA engine and upstream distribution versions are unknown unless separately observed; MCP serverInfo is reported independently.", @@ -58,34 +72,37 @@ export const idaCapabilities = ( stdio: boolean, native = false, ): readonly CapabilityDescriptor[] => - IDA_OPERATIONS.map((operation) => ({ - provider: IDA_PROVIDER_IDENTITY, - operation, - ...((mode === "headless" || native) && operation === "procedure_callers" - ? ({ - available: false, - reason: native - ? "The native upstream profile reports code references without proving direct call edges." - : "The modern upstream profile reports code references without proving direct call edges.", - } as const) - : ({ available: true, reason: null } as const)), - cachePolicy: "live", - effects: { - mutatesArtifact: false, - launchesProcess: stdio || mode === "headless", - mayShowUi: - mode === "attached" && - (native - ? operation === "procedure_pseudo_code" || - operation === "analyze_function" - : ATTACHED_GUI_NAVIGATION_OPERATIONS.has(operation)), - mayAccessNetwork: true, - mayWriteFilesystem: stdio || mode === "headless", - changesPermissions: false, - requiresRoot: false, - }, - limitations: - native && (operation === "list_strings" || operation === "search_strings") - ? [...IDA_LIMITATIONS, IDA_NATIVE_STRING_LIMITATION] - : IDA_LIMITATIONS, - })); + IDA_OPERATIONS.filter((operation) => idaProfileAdmits(operation, mode)).map( + (operation) => ({ + provider: IDA_PROVIDER_IDENTITY, + operation, + ...((mode === "headless" || native) && operation === "procedure_callers" + ? ({ + available: false, + reason: native + ? "The native upstream profile reports code references without proving direct call edges." + : "The modern upstream profile reports code references without proving direct call edges.", + } as const) + : ({ available: true, reason: null } as const)), + cachePolicy: "live", + effects: { + mutatesArtifact: false, + launchesProcess: stdio || mode === "headless", + mayShowUi: + mode === "attached" && + (native + ? operation === "procedure_pseudo_code" || + operation === "analyze_function" + : ATTACHED_GUI_NAVIGATION_OPERATIONS.has(operation)), + mayAccessNetwork: true, + mayWriteFilesystem: stdio || mode === "headless", + changesPermissions: false, + requiresRoot: false, + }, + limitations: + native && + (operation === "list_strings" || operation === "search_strings") + ? [...IDA_LIMITATIONS, IDA_NATIVE_STRING_LIMITATION] + : IDA_LIMITATIONS, + }), + ); diff --git a/src/ida/IdaSessionClient.ts b/src/ida/IdaSessionClient.ts index e882929bc85..c940e4c6a08 100644 --- a/src/ida/IdaSessionClient.ts +++ b/src/ida/IdaSessionClient.ts @@ -33,6 +33,7 @@ import { IDA_LIMITATIONS, IDA_OPERATIONS, IDA_PROVIDER_IDENTITY, + idaProfileAdmits, type IdaOperation, } from "./IdaProviderCapabilities.js"; import { @@ -122,6 +123,7 @@ export class IdaSessionClient implements AnalysisClient { #openAttempted = false; #openCompleted = false; #callGraphAdvertised = false; + #surveyAdvertised = false; #initialIdentity: string | undefined; #metadata: JsonValue = null; #lifecycle: JsonValue[] = []; @@ -194,6 +196,17 @@ export class IdaSessionClient implements AnalysisClient { "This integration admits read-only analysis operations only.", ), ); + if ( + operation !== "health" && + !idaProfileAdmits(operation, this.config.mode) + ) + return err( + new AnalysisCapabilityUnavailableError( + "ida", + operation, + "This operation is available for the modern headless profile only.", + ), + ); if ( operation === "procedure_callers" && idaProtocol(this.config) !== "legacy" @@ -296,6 +309,8 @@ export class IdaSessionClient implements AnalysisClient { selectorOrigin: options?.selectorOrigin, x86Only: isX86OnlyTarget(this.target), callGraphAvailable: this.#callGraphAdvertised, + surveyAvailable: this.#surveyAdvertised, + admittedDocument: this.target.path, }, ); } @@ -426,6 +441,7 @@ export class IdaSessionClient implements AnalysisClient { async #initialize(): Promise { const tools = new Set(await this.connection.connect()); this.#callGraphAdvertised = tools.has("callgraph"); + this.#surveyAdvertised = tools.has("survey_binary"); const expected = this.config.protocol === "native" ? nativeTools From 4c5e944ce14784eaaf2f47ae0ac3faf457196ad8 Mon Sep 17 00:00:00 2001 From: Mykola Dementiev Date: Mon, 12 Oct 2026 22:25:27 +0200 Subject: [PATCH 11/30] docs(ida): describe containing procedures, the admitted document and truncated feature traces --- docs/ida-provider.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/ida-provider.md b/docs/ida-provider.md index ddcaaef4bad..44866bbc17c 100644 --- a/docs/ida-provider.md +++ b/docs/ida-provider.md @@ -126,6 +126,8 @@ For guided registration, set `REA_IDA_MCP_CONFIG` before `rea setup --client Date: Mon, 12 Oct 2026 22:26:33 +0200 Subject: [PATCH 12/30] test(ida): verify containing procedures, the admitted document and feature tracing on real IDA --- scripts/verify-real-ida.mjs | 49 +++++++++++++++++++++++++++++++++++++ 1 file changed, 49 insertions(+) diff --git a/scripts/verify-real-ida.mjs b/scripts/verify-real-ida.mjs index c2d4d55cc6b..97802f33c89 100644 --- a/scripts/verify-real-ida.mjs +++ b/scripts/verify-real-ida.mjs @@ -190,6 +190,55 @@ const mcp = async (cliDossier) => { const result = await call(name, args); observe(result); } + if (config.mode === "headless") { + const documents = observe(await call("list_documents", {})); + assert.equal(documents.length, 1); + const resolveAt = async (address) => + observe(await call("resolve_containing_procedure", { address })); + const interior = `0x${(BigInt(dossier.procedure.address) + 1n).toString(16)}`; + for (const queried of [dossier.procedure.address, interior]) { + const containing = await resolveAt(queried); + assert.equal(containing.found, true); + assert.equal(containing.procedure.address, dossier.procedure.address); + assert.equal(containing.procedure.name, dossier.procedure.name); + } + const unmapped = await resolveAt("0x1"); + assert.equal(unmapped.found, false); + assert.equal(unmapped.reason, "outside_segments"); + const strings = observe(await call("list_strings", {})); + if (strings.length > 0) { + const mapped = await resolveAt(strings[0].address); + assert.equal(mapped.found, false); + assert.equal(mapped.reason, "not_in_procedure"); + } + const context = await client.callTool({ + name: "inspect_address_context", + arguments: { address: dossier.procedure.address }, + }); + assert.notEqual(context.isError, true); + const contextResult = context.structuredContent.result; + assert.equal(contextResult.document, documents[0]); + assert.equal(contextResult.procedure.state, "available"); + assert.equal( + contextResult.procedure.value.procedure.address, + dossier.procedure.address, + ); + if (strings.length > 0) { + const traced = await client.callTool({ + name: "trace_feature", + arguments: { query: strings[0].value }, + }); + assert.notEqual(traced.isError, true); + const trace = traced.structuredContent.normalized_result; + assert.ok( + trace.matches.some(({ address }) => address === strings[0].address), + ); + assert.equal(typeof trace.truncated, "boolean"); + } + report.checks.push( + "headless containing procedures, the admitted program as the document, address context, and feature tracing", + ); + } if (values["second-procedure"] !== undefined) { const secondAddress = observe( await call("procedure_address", { From 5ebae475c703d58a5918921d7218211379b8a238 Mon Sep 17 00:00:00 2001 From: Mykola Dementiev Date: Mon, 12 Oct 2026 22:26:40 +0200 Subject: [PATCH 13/30] docs(testing): list the headless IDA workflows the real lane verifies --- docs/testing.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/testing.md b/docs/testing.md index 6f0b8013131..88d10ee46ad 100644 --- a/docs/testing.md +++ b/docs/testing.md @@ -637,7 +637,9 @@ use `--second-procedure rea_fixture_subtract --second-marker='- 13'`. The lane invokes the production CLI dispatcher and connects the pinned MCP client SDK to the production REA server. It verifies function Evidence and CLI/MCP parity, inventory/search, pseudocode, instructions, xrefs, malformed -input, original-input preservation, and lifecycle cleanup. For headless +input, original-input preservation, and lifecycle cleanup. The headless +profile also checks containing procedures, the admitted program as the +document, address context, and feature tracing. For headless analysis it confirms that the owned database IDs disappear from upstream discovery and private workspaces are removed. For attached analysis it confirms the existing GUI target remains reachable with the same input identity. From 29b72ebdda0ec3bde312a3be78841aad93b5891e Mon Sep 17 00:00:00 2001 From: Mykola Dementiev Date: Mon, 12 Oct 2026 22:31:27 +0200 Subject: [PATCH 14/30] test(ida): make each survey failure case isolate a single defect --- src/ida/IdaContainment.test.ts | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/src/ida/IdaContainment.test.ts b/src/ida/IdaContainment.test.ts index 8fcb5e4b7d8..7d38be1cdcb 100644 --- a/src/ida/IdaContainment.test.ts +++ b/src/ida/IdaContainment.test.ts @@ -33,7 +33,7 @@ const SEGMENTS = [ const survey = (segments: JsonValue = SEGMENTS) => ({ metadata: { path: "/db/target.i64", module: "target", arch: "metapc" }, - statistics: { total_segments: 4 }, + statistics: { total_segments: Array.isArray(segments) ? segments.length : 0 }, segments, entrypoints: [], }); @@ -266,7 +266,12 @@ describe("headless IDA containment failures", () => { }, ]), ], - ["a reversed segment", survey([segment(".x", "0x2000", "0x1000")])], + [ + "a reversed segment", + survey([ + { name: ".x", start: "0x2000", end: "0x1000", permissions: "r--" }, + ]), + ], [ "a size that disagrees with the bounds", survey([{ ...segment(".x", "0x1000", "0x2000"), size: "0x10" }]), From aea084dd8ef8ad55b409a8fa97525488f99f19cb Mon Sep 17 00:00:00 2001 From: Mykola Dementiev Date: Mon, 12 Oct 2026 22:43:48 +0200 Subject: [PATCH 15/30] test(ida): pin large addresses, segment order, document identity, attached refusals and each trace_feature prerequisite --- src/application/CapabilityInventory.test.ts | 23 ++++ src/ida/IdaContainment.test.ts | 145 +++++++++++++++++++- src/ida/IdaNativeProtocol.test.ts | 19 +++ 3 files changed, 182 insertions(+), 5 deletions(-) diff --git a/src/application/CapabilityInventory.test.ts b/src/application/CapabilityInventory.test.ts index 2edd8358173..4286ff1d040 100644 --- a/src/application/CapabilityInventory.test.ts +++ b/src/application/CapabilityInventory.test.ts @@ -524,6 +524,29 @@ describe("trace_feature requirements", () => { ).toMatchObject({ available: true, reason: "available" }); }); + it.each(["search_strings", "search_procedures"])( + "is unavailable without %s", + (missing) => { + const operations = [ + "search_strings", + "search_procedures", + "xrefs", + "resolve_containing_procedure", + ].filter((operation) => operation !== missing); + + expect( + entry( + "trace_feature", + status({ + open: true, + kind: "executable", + capabilities: capabilities(operations), + }), + ), + ).toMatchObject({ available: false, reason: "provider_missing" }); + }, + ); + it("is unavailable when only the list operations exist", () => { expect( entry( diff --git a/src/ida/IdaContainment.test.ts b/src/ida/IdaContainment.test.ts index 7d38be1cdcb..19842fb1c61 100644 --- a/src/ida/IdaContainment.test.ts +++ b/src/ida/IdaContainment.test.ts @@ -28,9 +28,12 @@ const SEGMENTS = [ segment(".text", "0x1000", "0x2000"), segment(".data", "0x2000", "0x3000"), segment(".far", "0x5000", "0x6000"), - segment(".huge", "0x20000000000000", "0x20000000000010"), + segment(".huge", "0x20000000000001", "0x20000000000002"), ]; +/** The same segments in an order a scan may not rely on. */ +const UNSORTED = [SEGMENTS[3], SEGMENTS[1], SEGMENTS[2], SEGMENTS[0]]; + const survey = (segments: JsonValue = SEGMENTS) => ({ metadata: { path: "/db/target.i64", module: "target", arch: "metapc" }, statistics: { total_segments: Array.isArray(segments) ? segments.length : 0 }, @@ -60,13 +63,22 @@ interface Upstream { readonly survey?: JsonValue; readonly tools?: readonly string[]; readonly surveyFailure?: "error" | "preview"; + /** A distinct source alias of the admitted target, as for an app bundle. */ + readonly sourcePath?: string; + /** Report a different input from the second health read on. */ + readonly identityChangesAfterOperation?: boolean; } const session = async ( upstream: Upstream = {}, mode: "headless" | "attached" = "headless", ) => { - const { root, target } = await createIdaTarget("x86_64"); + const created = await createIdaTarget("x86_64"); + const { root } = created; + const target = + upstream.sourcePath === undefined + ? created.target + : { ...created.target, sourcePath: upstream.sourcePath }; roots.push(root); const producer = new RecordingIdaMcp(target, mode); if (upstream.tools !== undefined) producer.tools = upstream.tools; @@ -83,7 +95,20 @@ const session = async ( _meta: { ida_mcp: { output_truncated: true } }, }); }; + let healthReads = 0; producer.overrideCall = (name, args) => { + if (name === "server_health" && upstream.identityChangesAfterOperation) { + healthReads += 1; + if (healthReads === 2) + return { + status: "ok", + input_path: "/different/target.elf", + idb_path: "/different/target.elf.i64", + module: "target.elf", + imagebase: "0x1000", + auto_analysis_ready: true, + }; + } if (name === "lookup_funcs") { const queries = Array.isArray(args.queries) ? args.queries : []; return queries.map((query) => @@ -126,7 +151,6 @@ describe("IDA containment capabilities", () => { it("declares both operations for the headless profile only", () => { const declared = (mode: "attached" | "headless", native = false) => idaCapabilities(mode, false, native) - .filter(({ available }) => available) .map(({ operation }) => operation) .filter( (operation) => @@ -134,6 +158,16 @@ describe("IDA containment capabilities", () => { operation === "list_documents", ); + expect( + idaCapabilities("headless", false) + .filter( + ({ operation }) => + operation === "resolve_containing_procedure" || + operation === "list_documents", + ) + .map(({ available }) => available), + "both are declared available, not merely listed", + ).toEqual([true, true]); expect(declared("headless")).toEqual([ "resolve_containing_procedure", "list_documents", @@ -216,10 +250,19 @@ describe("headless IDA containing procedure", () => { ["one below a segment start", "0xfff", "outside_segments"], ["the last byte of a segment", "0x5fff", "not_in_procedure"], ["above every segment", "0x6000", "outside_segments"], - ["inside a segment above 2^53", "0x20000000000001", "not_in_procedure"], + [ + "inside a one-byte segment above 2^53", + "0x20000000000001", + "not_in_procedure", + ], + [ + "one below that segment, which a rounded number cannot tell apart", + "0x20000000000000", + "outside_segments", + ], [ "at the exclusive end of that segment", - "0x20000000000010", + "0x20000000000002", "outside_segments", ], ] as const)( @@ -254,6 +297,7 @@ describe("headless IDA containment failures", () => { it.each([ ["no segments field", { metadata: {}, statistics: {} }], ["segments that are null", survey(null)], + ["an empty segment list", survey([])], [ "a row with a malformed address", survey([ @@ -420,6 +464,46 @@ describe("headless IDA containment lookup failures", () => { } }); + it("does not depend on the order of the surveyed segments", async () => { + const { client } = await session({ survey: survey(UNSORTED) }); + try { + const inside = await containing(client, "0x1000"); + const gap = await containing(client, "0x4000"); + + if (!inside.ok) throw inside.error; + if (!gap.ok) throw gap.error; + expect(inside.value.result).toMatchObject({ reason: "not_in_procedure" }); + expect(gap.value.result).toMatchObject({ reason: "outside_segments" }); + } finally { + expect((await client.close()).ok).toBe(true); + } + }); + + it("retains the completed replies when the survey is rejected", async () => { + const { client } = await session({ + survey: survey([ + { name: ".x", start: "0x2000", end: "0x1000", permissions: "r--" }, + ]), + }); + try { + const result = await containing(client, "0x4000"); + + expect(result.ok).toBe(false); + if (!result.ok) + expect(result.error.partialObservation).toMatchObject({ + normalized_result: { + status: "partial", + observations: [ + expect.objectContaining({ tool: "lookup_funcs" }), + expect.objectContaining({ tool: "survey_binary" }), + ], + }, + }); + } finally { + expect((await client.close()).ok).toBe(true); + } + }); + it("rejects an address that is not hexadecimal and a document that is not the admitted target", async () => { const { client, producer } = await session(); try { @@ -444,6 +528,57 @@ describe("headless IDA containment lookup failures", () => { }); describe("headless IDA document identity", () => { + it("lists the admitted path, not its source alias or the private copy", async () => { + const { client, target, producer } = await session({ + sourcePath: "/Applications/Fixture.app", + }); + try { + const result = await client.execute("list_documents", {}); + + if (!result.ok) throw result.error; + expect(result.value.result).toEqual([target.path]); + expect( + producer.calls.filter(({ name }) => name === "server_health"), + "the target identity is checked before and after the local answer", + ).toHaveLength(2); + } finally { + expect((await client.close()).ok).toBe(true); + } + }); + + it("fails when the target identity changes during the operation", async () => { + const { client } = await session({ identityChangesAfterOperation: true }); + try { + const result = await client.execute("list_documents", {}); + + expect(result.ok).toBe(false); + if (!result.ok) { + expect(result.error.message).toContain("identity changed"); + } + } finally { + expect((await client.close()).ok).toBe(true); + } + }); + + it("stops without dispatching when the request is already cancelled", async () => { + const controller = new AbortController(); + controller.abort(); + const { client, producer } = await session(); + try { + const result = await client.execute( + "list_documents", + {}, + { signal: controller.signal }, + ); + + expect(result.ok).toBe(false); + if (!result.ok) expect(result.error._tag).toBe("AnalysisCancelledError"); + expect(producer.calls).toEqual([]); + } finally { + expect((await client.close()).ok).toBe(true); + } + }); + it("lists exactly the admitted program", async () => { const { client, target } = await session(); try { diff --git a/src/ida/IdaNativeProtocol.test.ts b/src/ida/IdaNativeProtocol.test.ts index 820a70708c7..1ad190ae29f 100644 --- a/src/ida/IdaNativeProtocol.test.ts +++ b/src/ida/IdaNativeProtocol.test.ts @@ -317,6 +317,25 @@ describe("native IDA provider observations", () => { ).toBe(true); }); + it("does not admit the headless-only containment and document operations", async () => { + const { client, producer } = await fixture(); + for (const [operation, parameters] of [ + ["resolve_containing_procedure", { address: "0x1000" }], + ["list_documents", {}], + ] as const) { + const result = await client.execute(operation, parameters); + + expect(result.ok).toBe(false); + if (!result.ok) + expect(result.error._tag).toBe("AnalysisCapabilityUnavailableError"); + } + expect( + producer.calls.some(({ name }) => name === "lookup_funcs"), + "nothing is dispatched upstream", + ).toBe(false); + await client.close(); + }); + it("rejects unavailable or mismatched recorded input hashes and database switches", async () => { const { client, producer, target } = await fixture(); for (const hash of ["unavailable", "a".repeat(64)]) { From 48e012d20581ceac87330a9cf22d83298a008853 Mon Sep 17 00:00:00 2001 From: Mykola Dementiev Date: Mon, 12 Oct 2026 22:44:06 +0200 Subject: [PATCH 16/30] test(mcp): expect a repeated reference source to be resolved once in trace_feature --- ...enhancedTools.traceFeatureCoverage.test.ts | 22 +++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/tests/boundary/mcp/enhancedTools.traceFeatureCoverage.test.ts b/tests/boundary/mcp/enhancedTools.traceFeatureCoverage.test.ts index 41e3b7d405e..8c94d5de052 100644 --- a/tests/boundary/mcp/enhancedTools.traceFeatureCoverage.test.ts +++ b/tests/boundary/mcp/enhancedTools.traceFeatureCoverage.test.ts @@ -167,6 +167,28 @@ describe("trace_feature reference coverage", () => { ); }); + it("resolves the containing procedure of a repeated reference source once", async () => { + const calls: string[] = []; + const output = await trace(provider({ duplicateProcedure: true, calls })); + + expect( + calls.filter((call) => call.startsWith("resolve_containing_procedure:")), + "the source 0x20 is referenced by two matches of the same address and resolved once", + ).toEqual([ + "resolve_containing_procedure:0x20", + "resolve_containing_procedure:0x21", + ]); + expect( + output.normalized_result, + "every reference is still reported with its containing procedure", + ).toEqual( + expectedTrace( + [], + [{ type: "procedure", address: "0x10", value: "hello" }], + ), + ); + }); + it("keeps the trace complete when the provider explicitly reports no cap", async () => { const output = await trace( provider({ coverage: { "0x10": false, "0x11": false } }), From 72f12e195c61a7d923e8a91929905bac3b747604 Mon Sep 17 00:00:00 2001 From: Mykola Dementiev Date: Mon, 12 Oct 2026 22:44:39 +0200 Subject: [PATCH 17/30] fix(mcp): resolve the containing procedure of a repeated reference source once --- src/application/EnhancedLiteralTracing.ts | 21 ++++++++++++++------- src/ida/IdaContainment.test.ts | 4 ++-- 2 files changed, 16 insertions(+), 9 deletions(-) diff --git a/src/application/EnhancedLiteralTracing.ts b/src/application/EnhancedLiteralTracing.ts index d382ac73ad7..79684ce0fa5 100644 --- a/src/application/EnhancedLiteralTracing.ts +++ b/src/application/EnhancedLiteralTracing.ts @@ -143,6 +143,8 @@ const traceReferences = async ( > => { const references: TraceReference[] = []; const residual: string[] = []; + // A source address is resolved once however many matches reference it. + const containing = new Map(); for (const match of request.matches) { const observed = await observe( "xrefs", @@ -174,16 +176,21 @@ const traceReferences = async ( "provider returned a non-address value", ), ); - const resolved = await call( - "resolve_containing_procedure", - { address: source }, - request.signal, - ); - if (!resolved.ok) return resolved; + let containingProcedure = containing.get(source); + if (containingProcedure === undefined) { + const resolved = await call( + "resolve_containing_procedure", + { address: source }, + request.signal, + ); + if (!resolved.ok) return resolved; + containingProcedure = resolved.value; + containing.set(source, containingProcedure); + } references.push({ target_address: match.address, source_address: source, - containing_procedure: resolved.value, + containing_procedure: containingProcedure, }); } } diff --git a/src/ida/IdaContainment.test.ts b/src/ida/IdaContainment.test.ts index 19842fb1c61..e38acdcd4fd 100644 --- a/src/ida/IdaContainment.test.ts +++ b/src/ida/IdaContainment.test.ts @@ -31,8 +31,8 @@ const SEGMENTS = [ segment(".huge", "0x20000000000001", "0x20000000000002"), ]; -/** The same segments in an order a scan may not rely on. */ -const UNSORTED = [SEGMENTS[3], SEGMENTS[1], SEGMENTS[2], SEGMENTS[0]]; +/** The same segments in descending order, which a scan may not rely on. */ +const UNSORTED = [...SEGMENTS].reverse(); const survey = (segments: JsonValue = SEGMENTS) => ({ metadata: { path: "/db/target.i64", module: "target", arch: "metapc" }, From 0d68088c0537b59de903c676530e7d6490b1d58b Mon Sep 17 00:00:00 2001 From: Mykola Dementiev Date: Mon, 12 Oct 2026 22:45:14 +0200 Subject: [PATCH 18/30] test(ida): trace the fixture procedure and derive probe addresses from its facts in the real lane --- scripts/verify-real-ida.mjs | 48 ++++++++++++++++++++++++------------- 1 file changed, 32 insertions(+), 16 deletions(-) diff --git a/scripts/verify-real-ida.mjs b/scripts/verify-real-ida.mjs index 97802f33c89..246d69bd887 100644 --- a/scripts/verify-real-ida.mjs +++ b/scripts/verify-real-ida.mjs @@ -6,7 +6,7 @@ import { execFile } from "node:child_process"; import { createHash } from "node:crypto"; import { createReadStream } from "node:fs"; import { access, writeFile } from "node:fs/promises"; -import { dirname, join, resolve } from "node:path"; +import { basename, dirname, join, resolve } from "node:path"; import { fileURLToPath, pathToFileURL } from "node:url"; import { parseArgs, promisify } from "node:util"; import { Client } from "@modelcontextprotocol/client"; @@ -193,16 +193,27 @@ const mcp = async (cliDossier) => { if (config.mode === "headless") { const documents = observe(await call("list_documents", {})); assert.equal(documents.length, 1); + assert.equal(basename(documents[0]), basename(target)); + assert.ok( + !workspaces.has(dirname(documents[0])), + "list_documents reported the private workspace copy.", + ); const resolveAt = async (address) => observe(await call("resolve_containing_procedure", { address })); - const interior = `0x${(BigInt(dossier.procedure.address) + 1n).toString(16)}`; - for (const queried of [dossier.procedure.address, interior]) { + const instructionAddresses = dossier.assembly + .map((line) => /^(0x[0-9a-f]+)/iu.exec(line)?.[1]) + .filter((address) => address !== undefined); + const queries = [ + dossier.procedure.address, + ...instructionAddresses.slice(1, 2), + ]; + for (const queried of queries) { const containing = await resolveAt(queried); assert.equal(containing.found, true); assert.equal(containing.procedure.address, dossier.procedure.address); assert.equal(containing.procedure.name, dossier.procedure.name); } - const unmapped = await resolveAt("0x1"); + const unmapped = await resolveAt("0xffffffffffffff00"); assert.equal(unmapped.found, false); assert.equal(unmapped.reason, "outside_segments"); const strings = observe(await call("list_strings", {})); @@ -223,20 +234,25 @@ const mcp = async (cliDossier) => { contextResult.procedure.value.procedure.address, dossier.procedure.address, ); - if (strings.length > 0) { - const traced = await client.callTool({ - name: "trace_feature", - arguments: { query: strings[0].value }, - }); - assert.notEqual(traced.isError, true); - const trace = traced.structuredContent.normalized_result; - assert.ok( - trace.matches.some(({ address }) => address === strings[0].address), - ); - assert.equal(typeof trace.truncated, "boolean"); + const traced = await client.callTool({ + name: "trace_feature", + arguments: { query: dossier.procedure.name }, + }); + assert.notEqual(traced.isError, true); + const trace = traced.structuredContent.normalized_result; + assert.ok( + trace.matches.some( + ({ type, address }) => + type === "procedure" && address === dossier.procedure.address, + ), + ); + assert.equal(typeof trace.truncated, "boolean"); + for (const reference of trace.references) { + assert.equal(reference.target_address, dossier.procedure.address); + assert.equal(reference.containing_procedure.found, true); } report.checks.push( - "headless containing procedures, the admitted program as the document, address context, and feature tracing", + "headless containing procedures, the admitted program as the document, address context, and the procedure match and references of feature tracing", ); } if (values["second-procedure"] !== undefined) { From 86bec61b8908e399d46f7c04b099a95d08fcad54 Mon Sep 17 00:00:00 2001 From: Mykola Dementiev Date: Tue, 13 Oct 2026 09:26:24 +0200 Subject: [PATCH 19/30] test(process): format processCaptureLifecycle.test.ts after the merge --- tests/boundary/process/processCaptureLifecycle.test.ts | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/tests/boundary/process/processCaptureLifecycle.test.ts b/tests/boundary/process/processCaptureLifecycle.test.ts index 2a483845b64..01d8eba13cb 100644 --- a/tests/boundary/process/processCaptureLifecycle.test.ts +++ b/tests/boundary/process/processCaptureLifecycle.test.ts @@ -196,9 +196,9 @@ itWithCaptureCapability( result.value.frames.map(({ at_ms }) => at_ms), "capture-relative frame times stay ordered and nonnegative", ).toEqual( - result.value.frames.map(({ at_ms }) => at_ms).sort( - (left, right) => left - right, - ), + result.value.frames + .map(({ at_ms }) => at_ms) + .sort((left, right) => left - right), ); expect(result.value.frames.every(({ at_ms }) => at_ms >= 0)).toBe(true); expect(result.value.exit.reason).toBe("exited"); From b39c7683bacc6f8e00d33147171a3b7c7dc6b26b Mon Sep 17 00:00:00 2001 From: Mykola Dementiev Date: Tue, 13 Oct 2026 09:30:07 +0200 Subject: [PATCH 20/30] test(ida): declare the alignment each synthetic universal slice offset satisfies --- src/ida/IdaWorkspaceThinning.test.ts | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/src/ida/IdaWorkspaceThinning.test.ts b/src/ida/IdaWorkspaceThinning.test.ts index 7d83f089b28..2f0471d0b01 100644 --- a/src/ida/IdaWorkspaceThinning.test.ts +++ b/src/ida/IdaWorkspaceThinning.test.ts @@ -62,7 +62,8 @@ const largeUniversalTarget = async ( bytes.writeUInt32BE(cpu, entry); bytes.writeUInt32BE(offset, entry + 8); bytes.writeUInt32BE(size, entry + 12); - bytes.writeUInt32BE(14, entry + 16); + // The declared alignment is the power of two the offset is aligned to. + bytes.writeUInt32BE(Math.log2(offset & -offset), entry + 16); bytes.fill(0x11 * (index + 1), offset, offset + size); thinMach(0xfeedfacf, cpu).copy(bytes, offset); }); From d3507f570ab373b86f786f7c5422ebedd1015ff6 Mon Sep 17 00:00:00 2001 From: Mykola Dementiev Date: Tue, 13 Oct 2026 09:33:19 +0200 Subject: [PATCH 21/30] refactor(ida): move the real lane's feature trace assertions into a helper --- scripts/lib/ida-feature-trace.mjs | 19 +++++++++++++++++++ scripts/verify-real-ida.mjs | 13 ++----------- 2 files changed, 21 insertions(+), 11 deletions(-) create mode 100644 scripts/lib/ida-feature-trace.mjs diff --git a/scripts/lib/ida-feature-trace.mjs b/scripts/lib/ida-feature-trace.mjs new file mode 100644 index 00000000000..3e63f8205d3 --- /dev/null +++ b/scripts/lib/ida-feature-trace.mjs @@ -0,0 +1,19 @@ +import assert from "node:assert/strict"; + +/** + * Assert the `trace_feature` result of the real IDA lane for one selected + * procedure: its procedure match is present and its references are contained. + */ +export function assertFeatureTrace(trace, procedure) { + assert.ok( + trace.matches.some( + ({ type, address }) => + type === "procedure" && address === procedure.address, + ), + ); + assert.equal(typeof trace.truncated, "boolean"); + for (const reference of trace.references) { + assert.equal(reference.target_address, procedure.address); + assert.equal(reference.containing_procedure.found, true); + } +} diff --git a/scripts/verify-real-ida.mjs b/scripts/verify-real-ida.mjs index 164ec7c47eb..467b848ceeb 100644 --- a/scripts/verify-real-ida.mjs +++ b/scripts/verify-real-ida.mjs @@ -1,4 +1,5 @@ #!/usr/bin/env node +import { assertFeatureTrace } from "./lib/ida-feature-trace.mjs"; import { requireMcpToolError } from "./lib/mcp-verifier-results.mjs"; import assert from "node:assert/strict"; @@ -311,17 +312,7 @@ const mcp = async (cliDossier) => { }); assert.notEqual(traced.isError, true); const trace = traced.structuredContent.normalized_result; - assert.ok( - trace.matches.some( - ({ type, address }) => - type === "procedure" && address === dossier.procedure.address, - ), - ); - assert.equal(typeof trace.truncated, "boolean"); - for (const reference of trace.references) { - assert.equal(reference.target_address, dossier.procedure.address); - assert.equal(reference.containing_procedure.found, true); - } + assertFeatureTrace(trace, dossier.procedure); report.checks.push( "headless containing procedures, the admitted program as the document, address context, and the procedure match and references of feature tracing", ); From a7b1fe31bb27e50dd4e8cc3d5987599d8f517d75 Mon Sep 17 00:00:00 2001 From: Mykola Dementiev Date: Tue, 13 Oct 2026 09:34:01 +0200 Subject: [PATCH 22/30] test(ida): expect the real lane's feature trace check to accept references to every matched address --- .../ida/verifierFeatureTrace.test.ts | 136 ++++++++++++++++++ 1 file changed, 136 insertions(+) create mode 100644 tests/boundary/providers/ida/verifierFeatureTrace.test.ts diff --git a/tests/boundary/providers/ida/verifierFeatureTrace.test.ts b/tests/boundary/providers/ida/verifierFeatureTrace.test.ts new file mode 100644 index 00000000000..30e8aec6f52 --- /dev/null +++ b/tests/boundary/providers/ida/verifierFeatureTrace.test.ts @@ -0,0 +1,136 @@ +import { describe, expect, it } from "vitest"; +// @ts-expect-error The verifier library is plain JavaScript without declarations. +import { assertFeatureTrace } from "../../../../scripts/lib/ida-feature-trace.mjs"; + +const procedure = { address: "0x1000", name: "main" }; + +const containing = (found: boolean) => + found + ? { + query_address: "0x1004", + found: true, + procedure: { address: "0x1000", name: "main" }, + } + : { + query_address: "0x3010", + found: false, + procedure: null, + reason: "not_in_procedure", + }; + +const trace = ( + matches: readonly { type: string; address: string }[], + references: readonly { + target_address: string; + containing_procedure: unknown; + }[], +) => ({ + query: "main", + search_mode: "literal", + matches, + references, + truncated: false, + residual_unknowns: [], +}); + +const SELECTED = { type: "procedure", address: "0x1000" }; +const SUBSTRING = { type: "procedure", address: "0x2000" }; +const STRING = { type: "string", address: "0x3000" }; + +describe("the real IDA lane's feature trace assertions", () => { + it("accepts references to every matched address, whoever contains the source", () => { + expect(() => + assertFeatureTrace( + trace( + [SELECTED, SUBSTRING, STRING], + [ + { + target_address: "0x1000", + containing_procedure: containing(true), + }, + // A substring match such as main_helper, referenced from code. + { + target_address: "0x2000", + containing_procedure: containing(true), + }, + // A string containing the query, referenced from data outside functions. + { + target_address: "0x3000", + containing_procedure: containing(false), + }, + ], + ), + procedure, + ), + ).not.toThrow(); + }); + + it("accepts a reference to the selected procedure from data outside functions", () => { + expect(() => + assertFeatureTrace( + trace( + [SELECTED], + [ + { + target_address: "0x1000", + containing_procedure: containing(false), + }, + ], + ), + procedure, + ), + ).not.toThrow(); + }); + + it("rejects a reference whose target is not one of the matches", () => { + expect(() => + assertFeatureTrace( + trace( + [SELECTED], + [ + { + target_address: "0x9999", + containing_procedure: containing(true), + }, + ], + ), + procedure, + ), + ).toThrow(); + }); + + it("rejects a trace without the selected procedure's match", () => { + expect(() => assertFeatureTrace(trace([STRING], []), procedure)).toThrow(); + }); + + it("rejects a containment answer that is neither found nor a known reason", () => { + expect(() => + assertFeatureTrace( + trace( + [SELECTED], + [ + { + target_address: "0x1000", + containing_procedure: { + query_address: "0x1004", + found: false, + procedure: null, + reason: "unknown", + }, + }, + ], + ), + procedure, + ), + ).toThrow(); + }); + + it("rejects a trace that does not say whether it was truncated", () => { + expect(() => + assertFeatureTrace( + { ...trace([SELECTED], []), truncated: undefined }, + procedure, + ), + ).toThrow(); + }); +}); From b472d513167e3730b45fe74352ad58a181216d22 Mon Sep 17 00:00:00 2001 From: Mykola Dementiev Date: Tue, 13 Oct 2026 09:34:05 +0200 Subject: [PATCH 23/30] fix(ida): check each trace reference against its own matched address in the real lane --- scripts/lib/ida-feature-trace.mjs | 18 +++++++++++++++--- 1 file changed, 15 insertions(+), 3 deletions(-) diff --git a/scripts/lib/ida-feature-trace.mjs b/scripts/lib/ida-feature-trace.mjs index 3e63f8205d3..167a6bd918c 100644 --- a/scripts/lib/ida-feature-trace.mjs +++ b/scripts/lib/ida-feature-trace.mjs @@ -1,8 +1,12 @@ import assert from "node:assert/strict"; +const NEGATIVE_REASONS = new Set(["not_in_procedure", "outside_segments"]); + /** * Assert the `trace_feature` result of the real IDA lane for one selected - * procedure: its procedure match is present and its references are contained. + * procedure. The query is a substring search, so the trace may also match other + * procedures and strings; each reference is checked against its own matched + * target, and a source outside every function (a data reference) is valid. */ export function assertFeatureTrace(trace, procedure) { assert.ok( @@ -10,10 +14,18 @@ export function assertFeatureTrace(trace, procedure) { ({ type, address }) => type === "procedure" && address === procedure.address, ), + "The trace omitted the selected procedure's match.", ); assert.equal(typeof trace.truncated, "boolean"); + const matched = new Set(trace.matches.map(({ address }) => address)); for (const reference of trace.references) { - assert.equal(reference.target_address, procedure.address); - assert.equal(reference.containing_procedure.found, true); + assert.ok( + matched.has(reference.target_address), + `A reference targets ${reference.target_address}, which is not a match.`, + ); + const { containing_procedure: containing } = reference; + if (containing.found) + assert.equal(typeof containing.procedure.address, "string"); + else assert.ok(NEGATIVE_REASONS.has(containing.reason)); } } From e34afbfca06795b62009a9995123a1bac4ebd494 Mon Sep 17 00:00:00 2001 From: Mykola Dementiev Date: Tue, 13 Oct 2026 09:34:23 +0200 Subject: [PATCH 24/30] test(ida): pin that the new operations reject a document other than the admitted program --- src/ida/IdaContainment.test.ts | 30 ++++++++++++++++++++++++++++++ 1 file changed, 30 insertions(+) diff --git a/src/ida/IdaContainment.test.ts b/src/ida/IdaContainment.test.ts index e38acdcd4fd..069388df82c 100644 --- a/src/ida/IdaContainment.test.ts +++ b/src/ida/IdaContainment.test.ts @@ -528,6 +528,36 @@ describe("headless IDA containment lookup failures", () => { }); describe("headless IDA document identity", () => { + it("accepts an explicit admitted document and rejects an unknown one for the same operations", async () => { + const { client, target, producer } = await session(); + try { + const admitted = await client.execute("resolve_containing_procedure", { + address: "0x4000", + document: target.path, + }); + const unknownContainment = await client.execute( + "resolve_containing_procedure", + { address: "0x4000", document: "/somewhere/else" }, + ); + const unknownListing = await client.execute("list_documents", { + document: "/somewhere/else", + }); + + expect(admitted.ok, "the admitted program is accepted").toBe(true); + for (const rejected of [unknownContainment, unknownListing]) { + expect(rejected.ok).toBe(false); + if (!rejected.ok) + expect(rejected.error._tag).toBe("AnalysisInputError"); + } + expect( + producer.calls.filter(({ name }) => name === "lookup_funcs"), + "only the admitted request reached upstream", + ).toHaveLength(1); + } finally { + expect((await client.close()).ok).toBe(true); + } + }); + it("lists the admitted path, not its source alias or the private copy", async () => { const { client, target, producer } = await session({ sourcePath: "/Applications/Fixture.app", From b4fc393b498ecfdc74f9a26439e2507902e4d6cb Mon Sep 17 00:00:00 2001 From: Mykola Dementiev Date: Tue, 13 Oct 2026 10:29:34 +0200 Subject: [PATCH 25/30] refactor(ida): move the real lane's mapped non-function probe into a helper --- scripts/lib/ida-feature-trace.mjs | 12 ++++++++++++ scripts/verify-real-ida.mjs | 15 +++++++++------ 2 files changed, 21 insertions(+), 6 deletions(-) diff --git a/scripts/lib/ida-feature-trace.mjs b/scripts/lib/ida-feature-trace.mjs index 167a6bd918c..ea5948d880f 100644 --- a/scripts/lib/ida-feature-trace.mjs +++ b/scripts/lib/ida-feature-trace.mjs @@ -29,3 +29,15 @@ export function assertFeatureTrace(trace, procedure) { else assert.ok(NEGATIVE_REASONS.has(containing.reason)); } } + +/** + * Find a string that IDA maps outside every function. Returns its address, or + * undefined when the target has no strings. + */ +export async function findMappedNonFunction(strings, resolveAt) { + if (strings.length === 0) return undefined; + const mapped = await resolveAt(strings[0].address); + assert.equal(mapped.found, false); + assert.equal(mapped.reason, "not_in_procedure"); + return strings[0].address; +} diff --git a/scripts/verify-real-ida.mjs b/scripts/verify-real-ida.mjs index 467b848ceeb..7609adbe030 100644 --- a/scripts/verify-real-ida.mjs +++ b/scripts/verify-real-ida.mjs @@ -1,5 +1,8 @@ #!/usr/bin/env node -import { assertFeatureTrace } from "./lib/ida-feature-trace.mjs"; +import { + assertFeatureTrace, + findMappedNonFunction, +} from "./lib/ida-feature-trace.mjs"; import { requireMcpToolError } from "./lib/mcp-verifier-results.mjs"; import assert from "node:assert/strict"; @@ -289,11 +292,11 @@ const mcp = async (cliDossier) => { assert.equal(unmapped.found, false); assert.equal(unmapped.reason, "outside_segments"); const strings = observe(await call("list_strings", {})); - if (strings.length > 0) { - const mapped = await resolveAt(strings[0].address); - assert.equal(mapped.found, false); - assert.equal(mapped.reason, "not_in_procedure"); - } + const mappedString = await findMappedNonFunction(strings, resolveAt); + if (mappedString === undefined) + report.unverified.push( + "Mapped non-function containment: the target has no string outside every function.", + ); const context = await client.callTool({ name: "inspect_address_context", arguments: { address: dossier.procedure.address }, From 51c38326ef8e3ea16e94f24548e222e5323da2a4 Mon Sep 17 00:00:00 2001 From: Mykola Dementiev Date: Tue, 13 Oct 2026 10:30:07 +0200 Subject: [PATCH 26/30] test(ida): expect the real lane's mapped data probe to skip strings inside functions --- .../ida/verifierFeatureTrace.test.ts | 79 ++++++++++++++++++- 1 file changed, 78 insertions(+), 1 deletion(-) diff --git a/tests/boundary/providers/ida/verifierFeatureTrace.test.ts b/tests/boundary/providers/ida/verifierFeatureTrace.test.ts index 30e8aec6f52..c97d9e175b0 100644 --- a/tests/boundary/providers/ida/verifierFeatureTrace.test.ts +++ b/tests/boundary/providers/ida/verifierFeatureTrace.test.ts @@ -1,6 +1,9 @@ import { describe, expect, it } from "vitest"; // @ts-expect-error The verifier library is plain JavaScript without declarations. -import { assertFeatureTrace } from "../../../../scripts/lib/ida-feature-trace.mjs"; +import { + assertFeatureTrace, + findMappedNonFunction, +} from "../../../../scripts/lib/ida-feature-trace.mjs"; const procedure = { address: "0x1000", name: "main" }; @@ -134,3 +137,77 @@ describe("the real IDA lane's feature trace assertions", () => { ).toThrow(); }); }); + +describe("the real IDA lane's mapped non-function probe", () => { + const inFunction = { + query_address: "0x1100", + found: true, + procedure: { address: "0x1000", name: "main" }, + }; + const data = { + query_address: "0x3000", + found: false, + procedure: null, + reason: "not_in_procedure", + }; + const resolver = + (answers: Readonly>, asked: string[] = []) => + async (address: string) => { + asked.push(address); + return answers[address]; + }; + + it("skips a string inside a function chunk and uses the next one", async () => { + const asked: string[] = []; + + await expect( + findMappedNonFunction( + [{ address: "0x1100" }, { address: "0x3000" }], + resolver({ "0x1100": inFunction, "0x3000": data }, asked), + ), + ).resolves.toBe("0x3000"); + expect(asked, "strings are tried in order until one qualifies").toEqual([ + "0x1100", + "0x3000", + ]); + }); + + it("stops at the first string that qualifies", async () => { + const asked: string[] = []; + + await expect( + findMappedNonFunction( + [{ address: "0x3000" }, { address: "0x3100" }], + resolver({ "0x3000": data, "0x3100": data }, asked), + ), + ).resolves.toBe("0x3000"); + expect(asked).toEqual(["0x3000"]); + }); + + it("reports no qualifying string when every string is inside a function", async () => { + await expect( + findMappedNonFunction( + [{ address: "0x1100" }, { address: "0x1200" }], + resolver({ "0x1100": inFunction, "0x1200": inFunction }), + ), + ).resolves.toBeUndefined(); + }); + + it("reports no qualifying string when the target has no strings", async () => { + await expect( + findMappedNonFunction([], resolver({})), + ).resolves.toBeUndefined(); + }); + + it("skips a string that resolves as unmapped, since it proves no mapped data", async () => { + await expect( + findMappedNonFunction( + [{ address: "0x4000" }, { address: "0x3000" }], + resolver({ + "0x4000": { ...data, reason: "outside_segments" }, + "0x3000": data, + }), + ), + ).resolves.toBe("0x3000"); + }); +}); From f82873cdf8edb3274363f9fcf78772948311aa23 Mon Sep 17 00:00:00 2001 From: Mykola Dementiev Date: Tue, 13 Oct 2026 10:30:18 +0200 Subject: [PATCH 27/30] fix(ida): try the target's strings in order for the mapped non-function probe --- scripts/lib/ida-feature-trace.mjs | 16 +++++++++------- scripts/verify-real-ida.mjs | 2 +- 2 files changed, 10 insertions(+), 8 deletions(-) diff --git a/scripts/lib/ida-feature-trace.mjs b/scripts/lib/ida-feature-trace.mjs index ea5948d880f..ad4eebc3c97 100644 --- a/scripts/lib/ida-feature-trace.mjs +++ b/scripts/lib/ida-feature-trace.mjs @@ -31,13 +31,15 @@ export function assertFeatureTrace(trace, procedure) { } /** - * Find a string that IDA maps outside every function. Returns its address, or - * undefined when the target has no strings. + * Find a string that IDA maps outside every function. A string inside a + * function chunk (inline data in code) is valid and skipped, so the strings are + * tried in order. Returns its address, or undefined when no string qualifies. */ export async function findMappedNonFunction(strings, resolveAt) { - if (strings.length === 0) return undefined; - const mapped = await resolveAt(strings[0].address); - assert.equal(mapped.found, false); - assert.equal(mapped.reason, "not_in_procedure"); - return strings[0].address; + for (const { address } of strings) { + const resolved = await resolveAt(address); + if (!resolved.found && resolved.reason === "not_in_procedure") + return address; + } + return undefined; } diff --git a/scripts/verify-real-ida.mjs b/scripts/verify-real-ida.mjs index 7609adbe030..bed0519a9f7 100644 --- a/scripts/verify-real-ida.mjs +++ b/scripts/verify-real-ida.mjs @@ -295,7 +295,7 @@ const mcp = async (cliDossier) => { const mappedString = await findMappedNonFunction(strings, resolveAt); if (mappedString === undefined) report.unverified.push( - "Mapped non-function containment: the target has no string outside every function.", + "Mapped non-function containment: no string of the target is mapped outside every function.", ); const context = await client.callTool({ name: "inspect_address_context", From 5856c17818949c2f567c76fe561c4f35eba6659d Mon Sep 17 00:00:00 2001 From: Mykola Dementiev Date: Tue, 13 Oct 2026 10:33:24 +0200 Subject: [PATCH 28/30] test(ida): declare the real lane helper types for the verifier tests --- scripts/lib/ida-feature-trace.d.mts | 9 +++++++++ .../boundary/providers/ida/verifierFeatureTrace.test.ts | 1 - 2 files changed, 9 insertions(+), 1 deletion(-) create mode 100644 scripts/lib/ida-feature-trace.d.mts diff --git a/scripts/lib/ida-feature-trace.d.mts b/scripts/lib/ida-feature-trace.d.mts new file mode 100644 index 00000000000..13c84df275d --- /dev/null +++ b/scripts/lib/ida-feature-trace.d.mts @@ -0,0 +1,9 @@ +export function assertFeatureTrace( + trace: unknown, + procedure: { readonly address: string }, +): void; + +export function findMappedNonFunction( + strings: readonly { readonly address: string }[], + resolveAt: (address: string) => Promise, +): Promise; diff --git a/tests/boundary/providers/ida/verifierFeatureTrace.test.ts b/tests/boundary/providers/ida/verifierFeatureTrace.test.ts index c97d9e175b0..097d327bb15 100644 --- a/tests/boundary/providers/ida/verifierFeatureTrace.test.ts +++ b/tests/boundary/providers/ida/verifierFeatureTrace.test.ts @@ -1,5 +1,4 @@ import { describe, expect, it } from "vitest"; -// @ts-expect-error The verifier library is plain JavaScript without declarations. import { assertFeatureTrace, findMappedNonFunction, From 6d0ba6eaad21c5793787ce1b8f9ba1844b08410e Mon Sep 17 00:00:00 2001 From: Mykola Dementiev Date: Tue, 13 Oct 2026 10:40:54 +0200 Subject: [PATCH 29/30] test(ida): expect the real lane to reject a listed string that resolves as unmapped --- tests/boundary/providers/ida/verifierFeatureTrace.test.ts | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/tests/boundary/providers/ida/verifierFeatureTrace.test.ts b/tests/boundary/providers/ida/verifierFeatureTrace.test.ts index 097d327bb15..77f654ffc0f 100644 --- a/tests/boundary/providers/ida/verifierFeatureTrace.test.ts +++ b/tests/boundary/providers/ida/verifierFeatureTrace.test.ts @@ -198,7 +198,7 @@ describe("the real IDA lane's mapped non-function probe", () => { ).resolves.toBeUndefined(); }); - it("skips a string that resolves as unmapped, since it proves no mapped data", async () => { + it("rejects a listed string that resolves as unmapped, since IDA cannot list an unmapped address", async () => { await expect( findMappedNonFunction( [{ address: "0x4000" }, { address: "0x3000" }], @@ -207,6 +207,6 @@ describe("the real IDA lane's mapped non-function probe", () => { "0x3000": data, }), ), - ).resolves.toBe("0x3000"); + ).rejects.toThrow(); }); }); From 1bc928aad1d8f6e812357218bb024e69b103d0ea Mon Sep 17 00:00:00 2001 From: Mykola Dementiev Date: Tue, 13 Oct 2026 10:40:59 +0200 Subject: [PATCH 30/30] fix(ida): fail the real lane when a listed string resolves as unmapped --- scripts/lib/ida-feature-trace.mjs | 13 ++++++++++--- 1 file changed, 10 insertions(+), 3 deletions(-) diff --git a/scripts/lib/ida-feature-trace.mjs b/scripts/lib/ida-feature-trace.mjs index ad4eebc3c97..3c4778d25f5 100644 --- a/scripts/lib/ida-feature-trace.mjs +++ b/scripts/lib/ida-feature-trace.mjs @@ -33,13 +33,20 @@ export function assertFeatureTrace(trace, procedure) { /** * Find a string that IDA maps outside every function. A string inside a * function chunk (inline data in code) is valid and skipped, so the strings are - * tried in order. Returns its address, or undefined when no string qualifies. + * tried in order. Any other answer must be "not in a procedure": IDA lists only + * mapped strings, so an unmapped answer is a containment defect and fails the + * lane. Returns the address, or undefined when every string is inside a function. */ export async function findMappedNonFunction(strings, resolveAt) { for (const { address } of strings) { const resolved = await resolveAt(address); - if (!resolved.found && resolved.reason === "not_in_procedure") - return address; + if (resolved.found) continue; + assert.equal( + resolved.reason, + "not_in_procedure", + `The listed string at ${address} resolved as ${resolved.reason}.`, + ); + return address; } return undefined; }