Reverse engineer anything with agents, from app behavior down to native binaries.
TypeScript agent-skillsai-agentsbinary-analysisclaude-codeclicodexcordisdecompilerdeveloper-toolsdshdsh-pluginghidrahopperllmmcpmodel-context-protocolreareverse-engineeringstatic-analysistouhou
fix(evidence): preserve source attribution across composed workflows
morlutoc4608a29620e
diff --git a/src/application/SourceLimitations.ts b/src/application/SourceLimitations.tsnew file mode 100644index 000000000..f30490af4--- /dev/null+++ b/src/application/SourceLimitations.ts@@ -0,0 +1,46 @@+import type {+ AnalysisOperation,+ ProviderIdentity,+} from "./AnalysisProvider.js";+import { compareUnicodeCodePoints } from "../domain/unicodeCodePointOrder.js";++/** One provider-owned caveat tied to the operation that reported it. */+export interface SourceLimitation {+ readonly provider: ProviderIdentity;+ readonly operation: AnalysisOperation;+ readonly limitation: string;+}++/** Stable exact-provenance key for deduplication before rendering. */+export const sourceLimitationKey = ({+ provider,+ operation,+ limitation,+}: SourceLimitation): string =>+ JSON.stringify([+ provider.id,+ provider.name,+ provider.version,+ operation,+ limitation,+ ]);++/** Render unique source caveats without losing their provider or operation. */+export const renderSourceLimitations = (+ limitations: readonly SourceLimitation[],+): string[] => {+ const rendered = new Map<string, string>();+ for (const { provider, operation, limitation } of limitations) {+ const provenance = sourceLimitationKey({+ provider,+ operation,+ limitation,+ });+ const version = provider.version === null ? "" : ` ${provider.version}`;+ rendered.set(+ provenance,+ `${provider.name} (${provider.id}${version}) ${operation}: ${limitation}`,+ );+ }+ return [...rendered.values()].sort(compareUnicodeCodePoints);+};diff --git a/src/application/WorkflowEvidence.test.ts b/src/application/WorkflowEvidence.test.tsindex b374efa01..7b1859915 100644--- a/src/application/WorkflowEvidence.test.ts+++ b/src/application/WorkflowEvidence.test.ts@@ -95,16 +95,18 @@ it("retains unique upstream limits in canonical order across concurrent observatlet calls = 0;const options = { signal: new AbortController().signal };const analysis: AnalysisOperationPort = {- execute: async (_, parameters, forwarded) => {+ execute: async (operation, parameters, forwarded) => {expect(parameters).toEqual({ marker: true });expect(forwarded).toBe(options);const call = calls++;if (call === 0) await gate;else release();+ const limitation =+ operation === "list_strings"+ ? ["first", "shared"]+ : ["second", "shared"];return ok(- createAnalysisExecution([], provider, {- limitations: call === 0 ? ["first", "shared"] : ["second", "shared"],- }),+ createAnalysisExecution([], provider, { limitations: limitation }),);},};@@ -117,7 +119,50 @@ it("retains unique upstream limits in canonical order across concurrent observat});expect(calls).toBe(2);expect(result).toEqual(- ok({ result: { count: 0 }, limitations: ["first", "second", "shared"] }),+ ok({+ result: { count: 0 },+ limitations: [+ "Fixture (fixture 1) list_procedures: second",+ "Fixture (fixture 1) list_procedures: shared",+ "Fixture (fixture 1) list_strings: first",+ "Fixture (fixture 1) list_strings: shared",+ ],+ }),+ );+});++it("deduplicates exact source caveats without merging providers or operations", async () => {+ const firstProvider = { id: "first", name: "First", version: "1" };+ const secondProvider = { id: "second", name: "Second", version: "1" };+ const result = await executeComposedWorkflow(+ {+ execute: async (operation, parameters) =>+ ok(+ createAnalysisExecution(+ null,+ parameters.provider === "second" ? secondProvider : firstProvider,+ { limitations: ["same source caveat"] },+ ),+ ),+ },+ async (observed) => {+ await observed.execute("list_strings", { provider: "first" });+ await observed.execute("list_strings", { provider: "first" });+ await observed.execute("list_strings", { provider: "second" });+ await observed.execute("list_procedures", { provider: "first" });+ return ok({ count: 0 });+ },+ );++ expect(result).toEqual(+ ok({+ result: { count: 0 },+ limitations: [+ "First (first 1) list_procedures: same source caveat",+ "First (first 1) list_strings: same source caveat",+ "Second (second 1) list_strings: same source caveat",+ ],+ }),);});diff --git a/src/application/WorkflowEvidence.ts b/src/application/WorkflowEvidence.tsindex 5bbd75455..599a5de29 100644--- a/src/application/WorkflowEvidence.ts+++ b/src/application/WorkflowEvidence.ts@@ -23,7 +23,11 @@ import {import type { JsonValue } from "../domain/jsonValue.js";import type { UnknownRegistryPort } from "./investigation/InvestigationRecordPort.js";import { UnknownRegistryError } from "../domain/unknownRegistryError.js";-import { compareUnicodeCodePoints } from "../domain/unicodeCodePointOrder.js";+import {+ renderSourceLimitations,+ sourceLimitationKey,+ type SourceLimitation,+} from "./SourceLimitations.js";/** Retain the limits of exactly the observations used by one composed call. */export const executeComposedWorkflow = async (@@ -37,21 +41,26 @@ export const executeComposedWorkflow = async (AnalysisError>> => {- const limitations = new Set<string>();+ const limitations = new Map<string, SourceLimitation>();const result = await execute({execute: async (operation, parameters, options) => {const execution = await analysis.execute(operation, parameters, options);if (execution.ok)- execution.value.limitations.forEach((limitation) =>- limitations.add(limitation),- );+ for (const limitation of execution.value.limitations) {+ const fact = {+ provider: execution.value.provider,+ operation,+ limitation,+ } satisfies SourceLimitation;+ limitations.set(sourceLimitationKey(fact), fact);+ }return execution;},});if (!result.ok) return result;return ok({result: result.value,- limitations: [...limitations].sort(compareUnicodeCodePoints),+ limitations: renderSourceLimitations([...limitations.values()]),});};diff --git a/src/application/native/NativeCallRoutes.ts b/src/application/native/NativeCallRoutes.tsindex affbfaf29..a4ba354e3 100644--- a/src/application/native/NativeCallRoutes.ts+++ b/src/application/native/NativeCallRoutes.ts@@ -9,18 +9,13 @@ import {referenceKindSchema,} from "../../domain/hopperValues.js";import { AnalysisOutputError } from "../../domain/analysisErrorCore.js";--export interface NativeCallRouteLimitation {- readonly provider: ProviderIdentity;- readonly operation: "procedure_references" | "procedure_callees";- readonly limitation: string;-}+import type { SourceLimitation } from "../SourceLimitations.js";const limitationsFrom = (- operation: NativeCallRouteLimitation["operation"],+ operation: SourceLimitation["operation"],provider: ProviderIdentity,limitations: readonly string[],-): NativeCallRouteLimitation[] =>+): SourceLimitation[] =>limitations.map((limitation) => ({ provider, operation, limitation }));const referencesSchema = z.object({@@ -85,7 +80,7 @@ export const readNativeCallRoutes = async (reason: string;provider: ProviderIdentity;}> = [];- let limitations: NativeCallRouteLimitation[] = [];+ let limitations: SourceLimitation[] = [];if (execution.ok) {limitations = limitationsFrom("procedure_references",diff --git a/src/application/native/NativeUiActionTrace.ts b/src/application/native/NativeUiActionTrace.tsindex 06d1fe4d3..c039f85cb 100644--- a/src/application/native/NativeUiActionTrace.ts+++ b/src/application/native/NativeUiActionTrace.ts@@ -13,10 +13,11 @@ import {import { nativeDispatchMetadataResultSchema } from "../../domain/native/objcSwiftMetadata.js";import { inspectNativeDispatch } from "./NativeDispatchMetadataInspection.js";import { jsonValueSchema } from "../../domain/jsonValue.js";+import { readNativeCallRoutes } from "./NativeCallRoutes.js";import {- readNativeCallRoutes,- type NativeCallRouteLimitation,-} from "./NativeCallRoutes.js";+ renderSourceLimitations,+ type SourceLimitation,+} from "../SourceLimitations.js";import { err, ok } from "../../domain/result.js";import { AnalysisOutputError } from "../../domain/analysisErrorCore.js";import { projectAnalysisError } from "../../domain/analysisErrorProjection.js";@@ -405,7 +406,7 @@ const addDirectCallees = async (input: {let examined = 0;let omitted = 0;let truncated = false;- const sourceLimitations: NativeCallRouteLimitation[] = [];+ const sourceLimitations: SourceLimitation[] = [];while (queueIndex < queue.length) {const current = queue[queueIndex++];if (current === undefined || visited.has(current.address)) continue;@@ -554,29 +555,6 @@ const addDirectCallees = async (input: {};};-const renderSourceLimitations = (- limitations: readonly NativeCallRouteLimitation[],-): string[] => {- const seen = new Set<string>();- const rendered: string[] = [];- for (const { provider, operation, limitation } of limitations) {- const provenance = JSON.stringify([- provider.id,- provider.name,- provider.version,- operation,- limitation,- ]);- if (seen.has(provenance)) continue;- seen.add(provenance);- const version = provider.version === null ? "" : ` ${provider.version}`;- rendered.push(- `${provider.name} (${provider.id}${version}) ${operation}: ${limitation}`,- );- }- return rendered;-};-const graphNodeDepths = (start: string,nodes: readonly z.infer<diff --git a/src/application/native/NativeValueTrace.test.ts b/src/application/native/NativeValueTrace.test.tsindex 56ed3761d..7688c9cc9 100644--- a/src/application/native/NativeValueTrace.test.ts+++ b/src/application/native/NativeValueTrace.test.ts@@ -291,31 +291,32 @@ const nativeFlowDossier = (});};-const callBindingAnalysis = (- callerAddress: string,- calleeAddress: string,- caller: ReturnType<typeof jsonValueSchema.parse>,- callee: ReturnType<typeof jsonValueSchema.parse>,-): AnalysisOperationPort => ({+const callBindingAnalysis = (input: {+ readonly callerAddress: string;+ readonly calleeAddress: string;+ readonly caller: ReturnType<typeof jsonValueSchema.parse>;+ readonly callee: ReturnType<typeof jsonValueSchema.parse>;+ readonly targetLimitations?: readonly string[];+}): AnalysisOperationPort => ({execute: async (operation, parameters) => {if (operation === "resolve_native_call_targets")return ok(createAnalysisExecution({call_site: String(parameters.address),- procedure: calleeAddress,+ procedure: input.calleeAddress,status: "direct",mechanism: "direct",targets: [{- address: calleeAddress,- procedure: calleeAddress,+ address: input.calleeAddress,+ procedure: input.calleeAddress,status: "direct",basis: "provider-reference",references: [],},],- limitations: [],+ limitations: [...(input.targetLimitations ?? [])],},provider,{ subject },@@ -324,13 +325,15 @@ const callBindingAnalysis = (if (operation !== "analyze_function")throw new Error(`Unexpected native trace operation: ${operation}`);if (- parameters.procedure !== callerAddress &&- parameters.procedure !== calleeAddress+ parameters.procedure !== input.callerAddress &&+ parameters.procedure !== input.calleeAddress)throw new Error(`Unexpected procedure: ${String(parameters.procedure)}`);return ok(createAnalysisExecution(- parameters.procedure === callerAddress ? caller : callee,+ parameters.procedure === input.callerAddress+ ? input.caller+ : input.callee,provider,{ subject },),@@ -430,6 +433,40 @@ describe("native value failed-callee traversal", () => {});describe("native value call-binding fan-out", () => {+ it("retains limitations embedded in resolved call-target results", async () => {+ const callerAddress = "0x1000";+ const calleeAddress = "0x2000";+ const base = functionDossierSchema.parse(ghidraFunctionDossier());+ const caller = nativeFlowDossier(base, {+ address: callerAddress,+ name: "caller",+ operations: [node("call", callerAddress, "CALL")],+ parameters: [],+ });+ const callee = nativeFlowDossier(base, {+ address: calleeAddress,+ name: "callee",+ operations: [],+ parameters: [],+ });+ const caveat = "Only statically resolved call sites are included.";+ const result = await traceNativeValues(+ callBindingAnalysis({+ callerAddress,+ calleeAddress,+ caller,+ callee,+ targetLimitations: [caveat],+ }),+ { procedure: callerAddress, max_functions: 2 },+ );++ if (!result.ok) throw result.error;+ expect(nativeValueTraceSchema.parse(result.value).limitations).toContain(+ `Fixture (fixture 1) resolve_native_call_targets: ${caveat}`,+ );+ });+it("preserves binding order and edge-budget behavior for repeated callees", async () => {const callCount = 128;const callerAddress = "0x1000";@@ -455,12 +492,12 @@ describe("native value call-binding fan-out", () => {operations: [node("return", calleeAddress, "RETURN")],parameters: [{ ordinal: 0, name: "value", data_type: "/int" }],});- const fanoutAnalysis = callBindingAnalysis(+ const fanoutAnalysis = callBindingAnalysis({callerAddress,calleeAddress,caller,callee,- );+ });const expectedEdges = [...Array.from({ length: callCount }, (_, index) => ({source: `${callerAddress}/call-${index}`,@@ -803,7 +840,12 @@ describe("native value byte-bound call bindings", () => {],});const result = await traceNativeValues(- callBindingAnalysis("0x1000", "0x2000", caller, callee),+ callBindingAnalysis({+ callerAddress: "0x1000",+ calleeAddress: "0x2000",+ caller,+ callee,+ }),{ procedure: "0x1000" },);if (!result.ok) throw result.error;diff --git a/src/application/native/NativeValueTrace.ts b/src/application/native/NativeValueTrace.tsindex fc304201d..f7ff79200 100644--- a/src/application/native/NativeValueTrace.ts+++ b/src/application/native/NativeValueTrace.ts@@ -13,6 +13,10 @@ import { err, ok } from "../../domain/result.js";import type { AnalysisOperationPort } from "../AnalysisProvider.js";import type { EnhancedResult } from "../EnhancedToolTypes.js";import { jsonParts } from "../../domain/jsonSerialization.js";+import {+ renderSourceLimitations,+ type SourceLimitation,+} from "../SourceLimitations.js";const NODE_PAYLOAD_BYTES = 8 * 1024 * 1024;@@ -27,6 +31,7 @@ export const traceNativeValues = async (const edges: typeof nativeValueTraceSchema._output.edges = [];const procedures: typeof nativeValueTraceSchema._output.procedures = [];const unknowns: typeof nativeValueTraceSchema._output.unknowns = [];+ const sourceLimitations: SourceLimitation[] = [];const callBindings: {caller: string;callee: string;@@ -280,6 +285,13 @@ export const traceNativeValues = async ("Invalid static call resolution",),);+ sourceLimitations.push(+ ...targets.data.limitations.map((limitation) => ({+ provider: resolved.value.provider,+ operation: "resolve_native_call_targets" as const,+ limitation,+ })),+ );if (targets.data.targets.length === 0)unknowns.push({procedure: address,@@ -424,6 +436,7 @@ export const traceNativeValues = async ("Static decompiler def-use graphs cover recovered block members; when membership is unavailable they exclude operations marked dead. Logical CALL argument positions bind to recovered HighParam ordinals and RETURN values bind to recovered CALL outputs; these are decompiler-derived dependencies, not original source or runtime observations. Missing parameters, variadic arguments and alias dependencies remain unknown.","LOAD and STORE are memory operations; object fields, persistent state and RNG semantics are not inferred from names or pseudocode.","Traversal caps depth, decompilations, call-site resolutions, nodes, edges and node payloads (8 MiB). Complete serialized output is bounded to 32 MiB. Pagination reruns analysis and returns edges whose source is on the node page; endpoints outside the page retain stable identities.",+ ...renderSourceLimitations(sourceLimitations),],});if (Buffer.byteLength(JSON.stringify(result)) > 32 * 1024 * 1024)diff --git a/tests/boundary/mcp/enhancedTools.callPathsAndBatches.test.ts b/tests/boundary/mcp/enhancedTools.callPathsAndBatches.test.tsindex 8dee037b9..24c285801 100644--- a/tests/boundary/mcp/enhancedTools.callPathsAndBatches.test.ts+++ b/tests/boundary/mcp/enhancedTools.callPathsAndBatches.test.ts@@ -124,8 +124,8 @@ describe("enhanced MCP graph caveats", () => {limitations: ["Artifact identity is unavailable for this observation.","Derived by an REA composed workflow.",- caveat,- leafCaveat,+ `Fixture analysis provider (fixture 1) procedure_callees: ${caveat}`,+ `Fixture analysis provider (fixture 1) procedure_callees: ${leafCaveat}`,],normalized_result: {graph: {@@ -153,9 +153,6 @@ describe("enhanced MCP graph caveats", () => {const normalized = JSON.stringify(evidence.normalized_result);for (const item of [caveat, leafCaveat]) {expect(normalized.split(item)).toHaveLength(2);- expect(- evidence.limitations.filter((limit) => limit === item),- ).toHaveLength(1);}const trace = await client.callTool({@@ -172,7 +169,11 @@ describe("enhanced MCP graph caveats", () => {});const traceEvidence = parseEvidence(trace.structuredContent);expect(- traceEvidence.limitations.filter((item) => item === caveat),+ traceEvidence.limitations.filter(+ (item) =>+ item ===+ `Fixture analysis provider (fixture 1) procedure_callees: ${caveat}`,+ ),).toHaveLength(1);expect(JSON.stringify(traceEvidence)).not.toContain(leafCaveat);});diff --git a/tests/boundary/mcp/enhancedTools.limitations.test.ts b/tests/boundary/mcp/enhancedTools.limitations.test.tsindex bf05bb20c..4188f78c6 100644--- a/tests/boundary/mcp/enhancedTools.limitations.test.ts+++ b/tests/boundary/mcp/enhancedTools.limitations.test.ts@@ -31,7 +31,10 @@ it("retains provider coverage caveats in a composed MCP overview without repeateexpect(evidence.limitations).toEqual(["Artifact identity is unavailable for this observation.","Derived by an REA composed workflow.",- limitation,+ `Fixture (fixture 1) current_document: ${limitation}`,+ `Fixture (fixture 1) list_procedures: ${limitation}`,+ `Fixture (fixture 1) list_segments: ${limitation}`,+ `Fixture (fixture 1) list_strings: ${limitation}`,]);expect(evidence.normalized_result).toMatchObject({document: "fixture",