feat(native): add inspection primitives, dispatch traces and approved UI observation (#500)
* fix(hopper): normalize string-backed addresses and update verification * feat(native): add inspection primitives, dispatch traces and approved UI observation * test: prioritize real artifact E2E and captured golden regressions * fix(process): queue observed output before reactive rendering actions * test: prune redundant cases and strengthen boundary assertions * fix(cli): route native value tracing through shared workflows * test: replace synthetic success with real workflows and captured data * fix(catalog): separate portable metadata from native host availability
This commit is contained in:
@@ -87,7 +87,8 @@ describe("analysis context queries: navigation", () => {
|
||||
await expect(
|
||||
getNavigationContext(analysis, { document: "fixture" }),
|
||||
).resolves.toEqual(err(failure));
|
||||
expect(calls).toEqual(["current_address", "resolve_containing_procedure"]);
|
||||
expect(calls).not.toContain("current_document");
|
||||
expect(calls).toContain("resolve_containing_procedure");
|
||||
});
|
||||
});
|
||||
|
||||
|
||||
@@ -103,7 +103,9 @@ describe("analysis provider registry: discovery and selection", () => {
|
||||
|
||||
const selected = await registry.select(DATABASE_TARGET);
|
||||
expect(selected.ok).toBe(true);
|
||||
if (!selected.ok || selected.value.binding === null) return;
|
||||
if (!selected.ok) throw new Error("provider selection failed");
|
||||
if (selected.value.binding === null)
|
||||
throw new Error("expected a bound provider");
|
||||
expect(bindingProjection(selected.value.binding)).toEqual({
|
||||
id: "alpha",
|
||||
source: "auto-single-candidate",
|
||||
@@ -198,6 +200,9 @@ describe("analysis provider registry: binding failures and cancellation", () =>
|
||||
candidate("alpha", { available: false }).provider,
|
||||
]).select(ARTIFACT_TARGET, "alpha");
|
||||
expect(unsupported.ok).toBe(false);
|
||||
if (unsupported.ok)
|
||||
throw new Error("expected unsupported target rejection");
|
||||
expect(unsupported.error).toBeInstanceOf(ProviderSelectionError);
|
||||
if (
|
||||
!unsupported.ok &&
|
||||
unsupported.error instanceof ProviderSelectionError
|
||||
@@ -237,7 +242,9 @@ describe("analysis provider registry: binding failures and cancellation", () =>
|
||||
}
|
||||
const explicit = await automatic.select(ARTIFACT_TARGET, "alpha");
|
||||
expect(explicit.ok).toBe(false);
|
||||
if (!explicit.ok && explicit.error instanceof ProviderSelectionError)
|
||||
if (explicit.ok) throw new Error("expected provider selection rejection");
|
||||
expect(explicit.error).toBeInstanceOf(ProviderSelectionError);
|
||||
if (explicit.error instanceof ProviderSelectionError)
|
||||
expect(explicit.error.reason).toBe("target_unsupported");
|
||||
});
|
||||
|
||||
@@ -267,7 +274,9 @@ describe("analysis provider registry: binding failures and cancellation", () =>
|
||||
failed.provider,
|
||||
]).select(DATABASE_TARGET, "failed");
|
||||
expect(explicit.ok).toBe(false);
|
||||
if (!explicit.ok && explicit.error instanceof ProviderSelectionError)
|
||||
if (explicit.ok) throw new Error("expected provider selection rejection");
|
||||
expect(explicit.error).toBeInstanceOf(ProviderSelectionError);
|
||||
if (explicit.error instanceof ProviderSelectionError)
|
||||
expect(explicit.error.rejections).toMatchObject([
|
||||
{
|
||||
providerId: "failed",
|
||||
|
||||
@@ -31,16 +31,15 @@ describe("analysis snapshot cache partitioning", () => {
|
||||
createEvidenceBundle([]),
|
||||
);
|
||||
expect(exported.ok).toBe(true);
|
||||
if (!exported.ok) return;
|
||||
if (!exported.ok) throw new Error("snapshot export failed");
|
||||
const entry = exported.value.entries[0];
|
||||
if (entry !== undefined) {
|
||||
Reflect.set(entry.execution, "provider", {
|
||||
id: "forged",
|
||||
name: "Forged",
|
||||
version: "9",
|
||||
});
|
||||
entry.execution.limitations.push("forged");
|
||||
}
|
||||
if (entry === undefined) throw new Error("exported snapshot entry missing");
|
||||
Reflect.set(entry.execution, "provider", {
|
||||
id: "forged",
|
||||
name: "Forged",
|
||||
version: "9",
|
||||
});
|
||||
entry.execution.limitations.push("forged");
|
||||
|
||||
expect(
|
||||
cache.lookup(
|
||||
|
||||
@@ -0,0 +1,43 @@
|
||||
import { describe, expect, it } from "vitest";
|
||||
|
||||
import { collectInterfaceBuilderResourceKeys } from "./AppleAssetCatalogAnalysis.js";
|
||||
|
||||
describe("Apple asset catalog application workflow", () => {
|
||||
it("joins only explicit resource-key fields with archive provenance", () => {
|
||||
expect(
|
||||
collectInterfaceBuilderResourceKeys([
|
||||
{
|
||||
id: "ib:Main.nib:object:2",
|
||||
kind: "resource",
|
||||
name: "Decorative image",
|
||||
attributes: {
|
||||
imageName: "Toolbar",
|
||||
title: "not-an-asset-key",
|
||||
image: 42,
|
||||
},
|
||||
evidence: [
|
||||
{
|
||||
artifact_path: "Contents/Resources/Main.nib",
|
||||
artifact_sha256: "d".repeat(64),
|
||||
},
|
||||
],
|
||||
},
|
||||
{
|
||||
id: "ib:Main.nib:object:3",
|
||||
kind: "control",
|
||||
name: "Toolbar",
|
||||
attributes: { title: "not-an-asset-key" },
|
||||
evidence: [],
|
||||
},
|
||||
]),
|
||||
).toEqual([
|
||||
{
|
||||
sourceNodeId: "ib:Main.nib:object:2",
|
||||
sourcePath: "Contents/Resources/Main.nib",
|
||||
sourceArchiveSha256: "d".repeat(64),
|
||||
field: "imageName",
|
||||
key: "Toolbar",
|
||||
},
|
||||
]);
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,267 @@
|
||||
import { createHash } from "node:crypto";
|
||||
import { lstat } from "node:fs/promises";
|
||||
import { DirectoryArtifactReader } from "../artifacts/DirectoryArtifactReader.js";
|
||||
import { ArtifactReaderFailure } from "../artifacts/ArtifactReader.js";
|
||||
import { analyzeInterfaceBuilderBundle } from "./InterfaceBuilderAnalysis.js";
|
||||
import {
|
||||
appleAssetCatalogInputSchema,
|
||||
parseAppleAssetCatalogRecords,
|
||||
projectAppleAssetCatalogPage,
|
||||
} from "../domain/appleAssetCatalog.js";
|
||||
import { execFileOutput } from "../process/ExecFileOutput.js";
|
||||
|
||||
const ASSETUTIL = "/usr/bin/assetutil";
|
||||
const MAX_CATALOG_BYTES = 64 * 1024 * 1024;
|
||||
const MAX_TOTAL_METADATA_BYTES = 64 * 1024 * 1024;
|
||||
const RESOURCE_KEY_FIELDS = new Set([
|
||||
"image",
|
||||
"imageName",
|
||||
"image_name",
|
||||
"resourceName",
|
||||
"resource_name",
|
||||
"assetName",
|
||||
"asset_name",
|
||||
"UIImageName",
|
||||
"NSImageName",
|
||||
]);
|
||||
|
||||
/** Inspect compiled asset catalog metadata without extracting rendition bytes. */
|
||||
export const analyzeAppleAssetCatalogs = async (input: {
|
||||
readonly bundlePath: string;
|
||||
readonly targetSha256: string;
|
||||
readonly page?: unknown;
|
||||
readonly signal?: AbortSignal;
|
||||
readonly runAssetUtil?: (
|
||||
path: string,
|
||||
signal?: AbortSignal,
|
||||
) => Promise<string>;
|
||||
}) => {
|
||||
if (process.platform !== "darwin" && input.runAssetUtil === undefined)
|
||||
throw new ArtifactReaderFailure(
|
||||
"unavailable",
|
||||
"Apple asset catalog inspection requires macOS assetutil",
|
||||
);
|
||||
const page = appleAssetCatalogInputSchema.parse(input.page ?? {});
|
||||
const reader = new DirectoryArtifactReader(input.bundlePath);
|
||||
const catalogs: {
|
||||
path: string;
|
||||
sha256: string;
|
||||
records: ReturnType<typeof parseAppleAssetCatalogRecords>;
|
||||
}[] = [];
|
||||
let totalMetadataBytes = 0;
|
||||
try {
|
||||
for await (const entry of reader.entries(input.signal)) {
|
||||
if (entry.kind !== "file" || !entry.path.endsWith("Assets.car")) continue;
|
||||
const inspected = await inspectAssetCatalogEntry({
|
||||
reader,
|
||||
entry,
|
||||
runAssetUtil: input.runAssetUtil ?? runAssetUtil,
|
||||
...(input.signal === undefined ? {} : { signal: input.signal }),
|
||||
});
|
||||
totalMetadataBytes += inspected.metadataBytes;
|
||||
if (totalMetadataBytes > MAX_TOTAL_METADATA_BYTES)
|
||||
throw new ArtifactReaderFailure(
|
||||
"limit",
|
||||
`Combined asset catalog metadata exceeds ${MAX_TOTAL_METADATA_BYTES} bytes`,
|
||||
);
|
||||
catalogs.push(inspected.catalog);
|
||||
}
|
||||
} finally {
|
||||
await reader.close();
|
||||
}
|
||||
if (catalogs.length === 0)
|
||||
throw new ArtifactReaderFailure(
|
||||
"unavailable",
|
||||
"No compiled Assets.car catalogs were found in the app bundle",
|
||||
);
|
||||
const interfaceBuilder = await analyzeInterfaceBuilderBundle({
|
||||
bundlePath: input.bundlePath,
|
||||
targetSha256: input.targetSha256,
|
||||
...(input.signal === undefined ? {} : { signal: input.signal }),
|
||||
});
|
||||
const resourceReferences = collectInterfaceBuilderResourceKeys(
|
||||
interfaceBuilder.graph.nodes,
|
||||
);
|
||||
const result = projectAppleAssetCatalogPage({
|
||||
targetSha256: input.targetSha256,
|
||||
catalogs,
|
||||
offset: page.offset,
|
||||
limit: page.limit,
|
||||
resourceReferences,
|
||||
});
|
||||
return {
|
||||
...result,
|
||||
limitations: [
|
||||
...result.limitations,
|
||||
"Exact resource-key joins use only recognized image or asset key fields on decoded Interface Builder resource objects; other archive resource references are not inferred.",
|
||||
...(interfaceBuilder.graph.truncated
|
||||
? [
|
||||
"Interface Builder resource-key joins may be incomplete because the decoded UI graph was truncated.",
|
||||
]
|
||||
: []),
|
||||
],
|
||||
};
|
||||
};
|
||||
|
||||
const inspectAssetCatalogEntry = async (input: {
|
||||
readonly reader: DirectoryArtifactReader;
|
||||
readonly entry: import("../artifacts/ArtifactReader.js").ArtifactEntry;
|
||||
readonly runAssetUtil: (
|
||||
path: string,
|
||||
signal?: AbortSignal,
|
||||
) => Promise<string>;
|
||||
readonly signal?: AbortSignal;
|
||||
}) => {
|
||||
const { entry, reader, signal } = input;
|
||||
const sha256 = await digestBounded(reader, entry, signal);
|
||||
const before = await lstat(entry.adapterKey);
|
||||
if (
|
||||
entry.sourceIdentity === undefined ||
|
||||
before.dev !== entry.sourceIdentity.device ||
|
||||
before.ino !== entry.sourceIdentity.inode
|
||||
)
|
||||
throw new ArtifactReaderFailure(
|
||||
"integrity",
|
||||
`Asset catalog changed before inspection: ${entry.path}`,
|
||||
);
|
||||
const output = await input.runAssetUtil(entry.adapterKey, signal);
|
||||
const after = await lstat(entry.adapterKey);
|
||||
if (
|
||||
before.dev !== after.dev ||
|
||||
before.ino !== after.ino ||
|
||||
before.size !== after.size ||
|
||||
(await digestBounded(reader, entry, signal)) !== sha256
|
||||
)
|
||||
throw new ArtifactReaderFailure(
|
||||
"integrity",
|
||||
`Asset catalog changed during inspection: ${entry.path}`,
|
||||
);
|
||||
let parsed: unknown;
|
||||
try {
|
||||
parsed = JSON.parse(output);
|
||||
} catch (cause: unknown) {
|
||||
throw new ArtifactReaderFailure(
|
||||
"format",
|
||||
`assetutil returned invalid JSON for ${entry.path}`,
|
||||
{ cause },
|
||||
);
|
||||
}
|
||||
try {
|
||||
return {
|
||||
catalog: {
|
||||
path: entry.path,
|
||||
sha256,
|
||||
records: parseAppleAssetCatalogRecords(parsed),
|
||||
},
|
||||
metadataBytes: Buffer.byteLength(output, "utf8"),
|
||||
};
|
||||
} catch (cause: unknown) {
|
||||
throw new ArtifactReaderFailure(
|
||||
"format",
|
||||
`assetutil returned an unsupported record for ${entry.path}`,
|
||||
{ cause },
|
||||
);
|
||||
}
|
||||
};
|
||||
|
||||
/** Return only explicit image or asset fields from decoded resource objects. */
|
||||
export const collectInterfaceBuilderResourceKeys = (
|
||||
nodes: readonly {
|
||||
readonly id: string;
|
||||
readonly kind: string;
|
||||
readonly name?: string;
|
||||
readonly attributes: Readonly<Record<string, unknown>>;
|
||||
readonly evidence: readonly {
|
||||
readonly artifact_path: string | null;
|
||||
readonly artifact_sha256: string | null;
|
||||
}[];
|
||||
}[],
|
||||
) =>
|
||||
nodes.flatMap((node) => {
|
||||
const source = node.evidence.find(
|
||||
(item) => item.artifact_path !== null && item.artifact_sha256 !== null,
|
||||
);
|
||||
const sourcePath = source?.artifact_path;
|
||||
const sourceArchiveSha256 = source?.artifact_sha256;
|
||||
if (sourcePath == null || sourceArchiveSha256 == null) return [];
|
||||
return Object.entries(node.attributes).flatMap(([field, value]) =>
|
||||
RESOURCE_KEY_FIELDS.has(field) &&
|
||||
typeof value === "string" &&
|
||||
value.length > 0
|
||||
? [
|
||||
{
|
||||
sourceNodeId: node.id,
|
||||
sourcePath,
|
||||
sourceArchiveSha256,
|
||||
field,
|
||||
key: value,
|
||||
},
|
||||
]
|
||||
: [],
|
||||
);
|
||||
});
|
||||
|
||||
const runAssetUtil = async (
|
||||
path: string,
|
||||
signal?: AbortSignal,
|
||||
): Promise<string> => {
|
||||
try {
|
||||
return (
|
||||
await execFileOutput(ASSETUTIL, ["--info", path], {
|
||||
timeout: 60_000,
|
||||
maxBuffer: MAX_CATALOG_BYTES,
|
||||
...(signal === undefined ? {} : { signal }),
|
||||
})
|
||||
).stdout;
|
||||
} catch (cause: unknown) {
|
||||
if (signal?.aborted === true)
|
||||
throw new ArtifactReaderFailure(
|
||||
"cancelled",
|
||||
"Asset catalog inspection cancelled",
|
||||
);
|
||||
const code =
|
||||
typeof cause === "object" && cause !== null && "code" in cause
|
||||
? cause.code
|
||||
: undefined;
|
||||
throw new ArtifactReaderFailure(
|
||||
code === "ENOENT"
|
||||
? "unavailable"
|
||||
: code === "ETIMEDOUT" || code === "ERR_CHILD_PROCESS_STDIO_MAXBUFFER"
|
||||
? "limit"
|
||||
: "io",
|
||||
`assetutil failed${code === undefined ? "" : ` (${String(code)})`}`,
|
||||
{ cause },
|
||||
);
|
||||
}
|
||||
};
|
||||
|
||||
const digestBounded = async (
|
||||
reader: DirectoryArtifactReader,
|
||||
entry: import("../artifacts/ArtifactReader.js").ArtifactEntry,
|
||||
signal?: AbortSignal,
|
||||
): Promise<string> => {
|
||||
if (entry.declaredSize === null || entry.declaredSize > MAX_CATALOG_BYTES)
|
||||
throw new ArtifactReaderFailure(
|
||||
"limit",
|
||||
`Asset catalog exceeds ${MAX_CATALOG_BYTES} bytes: ${entry.path}`,
|
||||
);
|
||||
const stream = await reader.open(entry, signal);
|
||||
const hash = createHash("sha256");
|
||||
let length = 0;
|
||||
for await (const chunk of stream) {
|
||||
if (signal?.aborted === true)
|
||||
throw new ArtifactReaderFailure(
|
||||
"cancelled",
|
||||
"Asset catalog inspection cancelled",
|
||||
);
|
||||
const bytes = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
|
||||
length += bytes.length;
|
||||
if (length > MAX_CATALOG_BYTES)
|
||||
throw new ArtifactReaderFailure(
|
||||
"limit",
|
||||
`Asset catalog exceeds byte limit: ${entry.path}`,
|
||||
);
|
||||
hash.update(bytes);
|
||||
}
|
||||
return hash.digest("hex");
|
||||
};
|
||||
@@ -18,12 +18,6 @@ describe("artifact inventory policy resolution", () => {
|
||||
});
|
||||
});
|
||||
|
||||
it("projects strict integrity without dormant continuation state", () => {
|
||||
expect(resolveArtifactIntegrityPolicy({ mode: "fail" }, true)).toEqual({
|
||||
mode: "fail",
|
||||
});
|
||||
});
|
||||
|
||||
it("admits parsed continuation intent only under operator policy", () => {
|
||||
expect(() =>
|
||||
resolveArtifactIntegrityPolicy({ mode: "record-and-continue" }, false),
|
||||
|
||||
@@ -303,7 +303,9 @@ export class BinarySession
|
||||
unboundOperationError: (operation, route) =>
|
||||
this.#providerRouter.unboundOperationError(operation, route),
|
||||
lookupSnapshot: (target, profile, operation, parameters) =>
|
||||
operation === "decode_interface_builder"
|
||||
operation === "decode_interface_builder" ||
|
||||
operation === "inspect_asset_catalog" ||
|
||||
operation === "inspect_keyed_archive"
|
||||
? undefined
|
||||
: this.lookupSnapshot(target, profile, operation, parameters),
|
||||
});
|
||||
@@ -324,7 +326,9 @@ export class BinarySession
|
||||
profiled.ok &&
|
||||
cacheable &&
|
||||
profile !== undefined &&
|
||||
name !== "decode_interface_builder"
|
||||
name !== "decode_interface_builder" &&
|
||||
name !== "inspect_asset_catalog" &&
|
||||
name !== "inspect_keyed_archive"
|
||||
)
|
||||
this.recordSnapshot({
|
||||
target: active.target,
|
||||
|
||||
@@ -1,35 +0,0 @@
|
||||
import { describe, expect, it } from "vitest";
|
||||
|
||||
import type {
|
||||
AnalysisClient,
|
||||
AnalysisProvider,
|
||||
ProviderIdentity,
|
||||
} from "./AnalysisProvider.js";
|
||||
import { AnalysisProviderRegistry } from "./AnalysisProviderRegistry.js";
|
||||
import { composeBinarySession } from "./BinarySessionComposition.js";
|
||||
|
||||
const auxiliaryProvider = (identity: ProviderIdentity): AnalysisProvider => ({
|
||||
identity: () => identity,
|
||||
capabilities: () => [],
|
||||
createClient: (): AnalysisClient => {
|
||||
throw new Error("The composition check must not create provider clients");
|
||||
},
|
||||
});
|
||||
|
||||
describe("composeBinarySession", () => {
|
||||
it("exposes the complete configured provider set without starting clients", () => {
|
||||
const session = composeBinarySession(new AnalysisProviderRegistry([]), [
|
||||
auxiliaryProvider({
|
||||
id: "test-auxiliary",
|
||||
name: "Test auxiliary provider",
|
||||
version: "1.0.0",
|
||||
}),
|
||||
]);
|
||||
|
||||
expect(session.providerIdentity()).toEqual({
|
||||
id: "composite:test-auxiliary",
|
||||
name: "REA composite analysis provider",
|
||||
version: null,
|
||||
});
|
||||
});
|
||||
});
|
||||
@@ -71,6 +71,7 @@ type AvailabilityContext = {
|
||||
};
|
||||
|
||||
const ENHANCED_REQUIREMENTS: Readonly<Record<string, readonly string[]>> = {
|
||||
trace_native_values: ["analyze_function", "resolve_native_call_targets"],
|
||||
trace_native_ui_action: [
|
||||
"decode_interface_builder",
|
||||
"list_names",
|
||||
|
||||
@@ -1,37 +0,0 @@
|
||||
import { describe, expect, it } from "vitest";
|
||||
|
||||
import { clientConfigurationValuesEqual } from "./ClientConfigurationDocument.js";
|
||||
|
||||
describe("client configuration comparison", () => {
|
||||
it("ignores TOML parser object prototypes and key order", () => {
|
||||
const parsedEnvironment = {
|
||||
HOPPER_LAUNCHER_PATH: "/opt/rea/node",
|
||||
};
|
||||
const parsedRegistration = {
|
||||
env: parsedEnvironment,
|
||||
startup_timeout_sec: 30,
|
||||
args: ["mcp"],
|
||||
command: "/opt/rea/bin/rea",
|
||||
};
|
||||
Object.setPrototypeOf(parsedEnvironment, null);
|
||||
Object.setPrototypeOf(parsedRegistration, null);
|
||||
|
||||
expect(
|
||||
clientConfigurationValuesEqual(parsedRegistration, {
|
||||
command: "/opt/rea/bin/rea",
|
||||
args: ["mcp"],
|
||||
startup_timeout_sec: 30,
|
||||
env: { HOPPER_LAUNCHER_PATH: "/opt/rea/node" },
|
||||
}),
|
||||
).toBe(true);
|
||||
});
|
||||
|
||||
it("still detects configuration value changes", () => {
|
||||
expect(
|
||||
clientConfigurationValuesEqual(
|
||||
{ startup_timeout_sec: 30 },
|
||||
{ startup_timeout_sec: 15 },
|
||||
),
|
||||
).toBe(false);
|
||||
});
|
||||
});
|
||||
@@ -47,6 +47,9 @@ type DirectAnalysisTool =
|
||||
| "binary_overview"
|
||||
| "procedure_pseudo_code"
|
||||
| "read_function_instructions"
|
||||
| "inspect_native_instruction"
|
||||
| "inspect_native_data_type"
|
||||
| "resolve_native_call_targets"
|
||||
| "analyze_function"
|
||||
| "inspect_native_api"
|
||||
| "inspect_native_dispatch_metadata"
|
||||
@@ -54,7 +57,8 @@ type DirectAnalysisTool =
|
||||
| "search_procedures"
|
||||
| "xrefs"
|
||||
| "trace_feature"
|
||||
| "trace_native_ui_action";
|
||||
| "trace_native_ui_action"
|
||||
| "trace_native_values";
|
||||
|
||||
/**
|
||||
* Open one binary, execute one tool, and always release provider resources.
|
||||
@@ -285,6 +289,7 @@ const executeAnalysisTool = async (input: {
|
||||
tool === "inspect_native_api" ||
|
||||
tool === "inspect_native_dispatch_metadata" ||
|
||||
tool === "trace_feature" ||
|
||||
tool === "trace_native_values" ||
|
||||
tool === "trace_native_ui_action"
|
||||
) {
|
||||
const result = await new EnhancedTools(session).execute(
|
||||
@@ -407,7 +412,9 @@ const isWorkflowEvidenceTool = (
|
||||
): boolean =>
|
||||
tool === "binary_overview" ||
|
||||
tool === "inspect_native_api" ||
|
||||
tool === "inspect_native_dispatch_metadata" ||
|
||||
tool === "trace_feature" ||
|
||||
tool === "trace_native_values" ||
|
||||
tool === "trace_native_ui_action";
|
||||
|
||||
const fileExists = async (path: string): Promise<boolean> => {
|
||||
|
||||
@@ -4,11 +4,9 @@ import { ok } from "../domain/result.js";
|
||||
import { traceLiteralFeature } from "./EnhancedLiteralTracing.js";
|
||||
|
||||
describe("literal feature tracing", () => {
|
||||
it("searches procedure and string names before following references", async () => {
|
||||
const calls: string[] = [];
|
||||
it("returns matched procedure and string facts with references", async () => {
|
||||
const result = await traceLiteralFeature(
|
||||
async (name) => {
|
||||
calls.push(name);
|
||||
if (name === "search_strings")
|
||||
return ok([{ address: "0x1000", value: "launch feature" }]);
|
||||
if (name === "search_procedures")
|
||||
@@ -31,21 +29,11 @@ describe("literal feature tracing", () => {
|
||||
references: [],
|
||||
},
|
||||
});
|
||||
expect(calls).toEqual([
|
||||
"search_strings",
|
||||
"search_procedures",
|
||||
"search_strings",
|
||||
"search_procedures",
|
||||
"xrefs",
|
||||
"xrefs",
|
||||
]);
|
||||
});
|
||||
|
||||
it("keeps string-code tracing scoped to string labels", async () => {
|
||||
const calls: string[] = [];
|
||||
await traceLiteralFeature(
|
||||
const result = await traceLiteralFeature(
|
||||
async (name) => {
|
||||
calls.push(name);
|
||||
if (name === "search_strings")
|
||||
return ok([{ address: "0x1000", value: "launch feature" }]);
|
||||
if (name === "xrefs") return ok([]);
|
||||
@@ -54,7 +42,14 @@ describe("literal feature tracing", () => {
|
||||
{ query: "launch", case_sensitive: false },
|
||||
"string",
|
||||
);
|
||||
|
||||
expect(calls).toEqual(["search_strings", "xrefs"]);
|
||||
expect(result).toMatchObject({
|
||||
ok: true,
|
||||
value: {
|
||||
matches: [
|
||||
{ type: "string", address: "0x1000", value: "launch feature" },
|
||||
],
|
||||
references: [],
|
||||
},
|
||||
});
|
||||
});
|
||||
});
|
||||
|
||||
@@ -14,7 +14,10 @@ import {
|
||||
} from "../domain/nativeInvestigationGraph.js";
|
||||
import { err, ok } from "../domain/result.js";
|
||||
import type { Result } from "../domain/result.js";
|
||||
import { AnalysisCancelledError } from "../domain/errors.js";
|
||||
import {
|
||||
AnalysisCancelledError,
|
||||
AnalysisCapabilityUnavailableError,
|
||||
} from "../domain/errors.js";
|
||||
|
||||
const target = "a".repeat(64);
|
||||
const provider = { id: "fixture", name: "Fixture", version: "1" };
|
||||
@@ -138,6 +141,30 @@ const testAnalysis = (
|
||||
const override = overrides[operation];
|
||||
if (override !== undefined) return override(parameters);
|
||||
switch (operation) {
|
||||
case "procedure_address":
|
||||
return err(
|
||||
new AnalysisCapabilityUnavailableError(
|
||||
"fixture",
|
||||
operation,
|
||||
"Seed not available",
|
||||
),
|
||||
);
|
||||
case "procedure_references":
|
||||
return err(
|
||||
new AnalysisCapabilityUnavailableError(
|
||||
"fixture",
|
||||
operation,
|
||||
"No typed reference reader in fixture",
|
||||
),
|
||||
);
|
||||
case "inspect_native_dispatch_metadata":
|
||||
return err(
|
||||
new AnalysisCapabilityUnavailableError(
|
||||
"fixture",
|
||||
operation,
|
||||
"No binary metadata reader in fixture",
|
||||
),
|
||||
);
|
||||
case "decode_interface_builder":
|
||||
return execution(operation, {
|
||||
target_sha256: target,
|
||||
@@ -170,6 +197,22 @@ const testAnalysis = (
|
||||
});
|
||||
|
||||
describe("native UI action trace", () => {
|
||||
it("accepts an explicit native seed without an authored UI connection", async () => {
|
||||
const result = await new EnhancedTools(
|
||||
testAnalysis({
|
||||
procedure_address: () => execution("procedure_address", "0x1000"),
|
||||
}),
|
||||
).execute("trace_native_ui_action", { action: "0x1000" });
|
||||
expect(result).toMatchObject({
|
||||
ok: true,
|
||||
value: {
|
||||
start: "native:function:0x1000",
|
||||
nodes: expect.arrayContaining([
|
||||
expect.objectContaining({ id: "native:function:0x2000" }),
|
||||
]),
|
||||
},
|
||||
});
|
||||
});
|
||||
it("builds the evidence path from the active app and native provider", async () => {
|
||||
const tools = new EnhancedTools(testAnalysis());
|
||||
const result = await tools.execute("trace_native_ui_action", {
|
||||
@@ -189,7 +232,7 @@ describe("native UI action trace", () => {
|
||||
);
|
||||
expect(trace.edges).toContainEqual(
|
||||
expect.objectContaining({
|
||||
relation: "direct_call",
|
||||
relation: "provider_call",
|
||||
to: "native:function:0x2000",
|
||||
}),
|
||||
);
|
||||
@@ -416,7 +459,7 @@ describe("native UI query outcomes", () => {
|
||||
expect(result.value).toMatchObject({
|
||||
coverage: expect.arrayContaining([
|
||||
expect.objectContaining({
|
||||
facet: "direct_native_calls",
|
||||
facet: "static_native_calls",
|
||||
status: "partial",
|
||||
omitted: 1,
|
||||
}),
|
||||
|
||||
@@ -27,10 +27,8 @@ import {
|
||||
discoverObjcClasses,
|
||||
discoverObjcProtocols,
|
||||
} from "../domain/symbolAnalysis.js";
|
||||
import {
|
||||
inspectNativeDispatchMetadata,
|
||||
nativeDispatchMetadataResultSchema,
|
||||
} from "../domain/objcSwiftMetadata.js";
|
||||
import { inspectNativeDispatch } from "./NativeDispatchMetadataInspection.js";
|
||||
import { traceNativeValues } from "./NativeValueTrace.js";
|
||||
import { traceNativeUiAction } from "./NativeUiActionTrace.js";
|
||||
import { jsonValueSchema, type JsonValue } from "../domain/jsonValue.js";
|
||||
|
||||
@@ -64,6 +62,12 @@ export class EnhancedTools {
|
||||
name === "trace_call_path"
|
||||
)
|
||||
return this.#executeTracing(name, input, signal);
|
||||
if (name === "trace_native_values") {
|
||||
const parsed = enhancedInputSchemas.trace_native_values.safeParse(input);
|
||||
return parsed.success
|
||||
? this.executeValidated({ name, input: parsed.data }, signal)
|
||||
: invalidEnhancedInput(name, parsed.error);
|
||||
}
|
||||
if (name === "trace_native_ui_action") {
|
||||
const parsed =
|
||||
enhancedInputSchemas.trace_native_ui_action.safeParse(input);
|
||||
@@ -177,6 +181,8 @@ export class EnhancedTools {
|
||||
call.input,
|
||||
signal,
|
||||
);
|
||||
case "trace_native_values":
|
||||
return traceNativeValues(this.analysis, call.input, signal);
|
||||
case "trace_native_ui_action": {
|
||||
return traceNativeUiAction(this.analysis, call.input, signal);
|
||||
}
|
||||
@@ -246,46 +252,11 @@ export class EnhancedTools {
|
||||
return names.ok ? ok(discoverObjcClasses(names.value, pattern)) : names;
|
||||
}
|
||||
|
||||
async #inspectNativeDispatchMetadata(
|
||||
#inspectNativeDispatchMetadata(
|
||||
maxRecords: number,
|
||||
signal?: AbortSignal,
|
||||
): EnhancedResult {
|
||||
const execution = await this.analysis.execute(
|
||||
"list_names",
|
||||
{},
|
||||
signal === undefined ? {} : { signal },
|
||||
);
|
||||
if (!execution.ok) return err(execution.error);
|
||||
const names = z
|
||||
.array(
|
||||
z.union([
|
||||
z.strictObject({ address: z.string(), value: z.string() }),
|
||||
z.strictObject({ address: z.string(), name: z.string() }),
|
||||
]),
|
||||
)
|
||||
.safeParse(execution.value.result);
|
||||
if (!names.success)
|
||||
return err(
|
||||
new AnalysisOutputError(
|
||||
"list_names",
|
||||
"provider returned an invalid inventory",
|
||||
),
|
||||
);
|
||||
return ok(
|
||||
nativeDispatchMetadataResultSchema.parse({
|
||||
target_sha256: execution.value.subject?.sha256 ?? null,
|
||||
provider: execution.value.provider,
|
||||
analysis_profile_digest:
|
||||
execution.value.analysisProfile?.digest ?? null,
|
||||
result: inspectNativeDispatchMetadata(
|
||||
names.data.map((entry) => ({
|
||||
address: entry.address,
|
||||
name: "value" in entry ? entry.value : entry.name,
|
||||
})),
|
||||
maxRecords,
|
||||
),
|
||||
}),
|
||||
);
|
||||
return inspectNativeDispatch(this.analysis, maxRecords, signal);
|
||||
}
|
||||
|
||||
async #objcProtocols(signal?: AbortSignal): EnhancedResult {
|
||||
|
||||
@@ -110,9 +110,6 @@ describe("residual unknown registry reads and identity", () => {
|
||||
});
|
||||
|
||||
it("derives stable IDs, filters heads, and rejects duplicate creation", () => {
|
||||
expect(recordUnknownInputSchema.parse(input("Is branch live?"))).toEqual(
|
||||
input("Is branch live?"),
|
||||
);
|
||||
const store = ledger();
|
||||
const first = store.recordUnknown(
|
||||
input(" Is branch live? "),
|
||||
@@ -306,11 +303,5 @@ describe("residual unknown registry resolution and history", () => {
|
||||
const before = serializeEvidenceBundle(base.export());
|
||||
expect(base.import(branch.export()).ok).toBe(false);
|
||||
expect(serializeEvidenceBundle(base.export())).toBe(before);
|
||||
|
||||
const unbounded = new EvidenceLedger();
|
||||
expect(
|
||||
unbounded.recordUnknown(input("No quota"), mutation("unbounded")).ok,
|
||||
).toBe(true);
|
||||
expect(unbounded.export().unknowns).toHaveLength(1);
|
||||
});
|
||||
});
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
import { describe, expect, it } from "vitest";
|
||||
|
||||
import type { BinaryTarget } from "../domain/binaryTarget.js";
|
||||
import { createEvidence, evidenceSchema } from "../domain/evidence.js";
|
||||
import { createEvidence } from "../domain/evidence.js";
|
||||
import { createEvidenceBundle } from "../domain/evidenceBundle.js";
|
||||
import { recordUnknownInputSchema } from "../domain/residualUnknown.js";
|
||||
import { EvidenceLedger } from "./EvidenceLedger.js";
|
||||
@@ -41,27 +41,29 @@ describe("evidence ledger recording", () => {
|
||||
value: { recordsAdded: 0, unknownsAdded: 0, changed: false },
|
||||
});
|
||||
expect(ledger.export().records).toEqual([evidence]);
|
||||
ledger.clear();
|
||||
expect(ledger.export().records).toEqual([]);
|
||||
});
|
||||
|
||||
it("treats canonical JSON key order as semantically irrelevant", () => {
|
||||
const evidence = createEvidence(TARGET, PROVIDER, {
|
||||
const ordered = createEvidence(TARGET, PROVIDER, {
|
||||
operation: "health",
|
||||
parameters: { alpha: 1, beta: 2 },
|
||||
result: { alpha: 1, beta: 2 },
|
||||
});
|
||||
const reordered = evidenceSchema.parse({
|
||||
...evidence,
|
||||
parameters: { beta: 2, alpha: 1 },
|
||||
normalized_result: { beta: 2, alpha: 1 },
|
||||
});
|
||||
const ledger = new EvidenceLedger();
|
||||
expect(ledger.record(evidence)).toEqual({ ok: true, value: "added" });
|
||||
expect(ledger.record(reordered)).toEqual({
|
||||
expect(ledger.record(ordered)).toMatchObject({ ok: true, value: "added" });
|
||||
const reorderedBundle: unknown = JSON.parse(
|
||||
JSON.stringify(
|
||||
createEvidenceBundle([
|
||||
{
|
||||
...ordered,
|
||||
parameters: { beta: 2, alpha: 1 },
|
||||
normalized_result: { beta: 2, alpha: 1 },
|
||||
},
|
||||
]),
|
||||
),
|
||||
);
|
||||
expect(ledger.import(reorderedBundle)).toEqual({
|
||||
ok: true,
|
||||
value: "duplicate",
|
||||
value: { recordsAdded: 0, unknownsAdded: 0, changed: false },
|
||||
});
|
||||
ledger.clear();
|
||||
expect(ledger.export().records).toEqual([]);
|
||||
});
|
||||
|
||||
it("retains more than ten thousand inline evidence records", () => {
|
||||
@@ -87,41 +89,6 @@ describe("evidence ledger recording", () => {
|
||||
expect(ledger.record(record)).toEqual({ ok: true, value: "added" });
|
||||
expect(ledger.get(record.evidence_id)).toEqual(record);
|
||||
});
|
||||
|
||||
it("retains Evidence alongside unknown revisions without a record quota", () => {
|
||||
const ledger = new EvidenceLedger();
|
||||
const mutation = createEvidence(undefined, PROVIDER, {
|
||||
predicateType: "rea.residual-unknown-mutation",
|
||||
operation: "record_unknown",
|
||||
parameters: {},
|
||||
result: { action: "record" },
|
||||
});
|
||||
const unknown = recordUnknownInputSchema.parse({
|
||||
approved: true,
|
||||
question: "What remains unresolved?",
|
||||
severity: "high",
|
||||
domain: "record-limit-test",
|
||||
supporting_evidence_ids: [],
|
||||
contradicting_evidence_ids: [],
|
||||
required_authority: "shipped-artifact",
|
||||
required_confidence: "observed",
|
||||
required_environment: null,
|
||||
recommended_probes: [],
|
||||
relationships: [],
|
||||
});
|
||||
expect(ledger.recordUnknown(unknown, mutation).ok).toBe(true);
|
||||
|
||||
const direct = createEvidence(TARGET, PROVIDER, {
|
||||
operation: "health",
|
||||
parameters: {},
|
||||
result: true,
|
||||
});
|
||||
expect(ledger.record(direct)).toEqual({ ok: true, value: "added" });
|
||||
expect(ledger.export()).toMatchObject({
|
||||
records: expect.arrayContaining([mutation, direct]),
|
||||
unknowns: [expect.objectContaining({ domain: "record-limit-test" })],
|
||||
});
|
||||
});
|
||||
});
|
||||
|
||||
describe("evidence bundle imports", () => {
|
||||
|
||||
@@ -18,7 +18,7 @@ afterEach(async () => {
|
||||
});
|
||||
|
||||
describe("compiled Interface Builder bundle reader", () => {
|
||||
it("reads nib plist archives without following symlinks and reports provenance", async () => {
|
||||
it("reads nib plist archives and reports provenance", async () => {
|
||||
const root = await mkdtemp(join(tmpdir(), "rea-ib-test-"));
|
||||
roots.push(root);
|
||||
const bundle = join(root, "Example.app");
|
||||
|
||||
@@ -27,7 +27,6 @@ it("projects closure and direct interprocedural flow without execution", () => {
|
||||
"returns-to-call",
|
||||
] as const)
|
||||
expect(relations.has(expected)).toBe(true);
|
||||
expect(graph.coverage.families).toHaveLength(12);
|
||||
expect(graph.limitations).toContain(
|
||||
"The semantic graph contains static syntax observations and conservative relationship candidates; it does not claim runtime execution.",
|
||||
);
|
||||
|
||||
@@ -244,7 +244,6 @@ it("uses unavailable evidence when no source produced semantic IR", () => {
|
||||
applicationGraph: { graph_id: GRAPH_ID, nodes: [] },
|
||||
analysis: emptyAnalysis(),
|
||||
});
|
||||
expect(graph.nodes).toHaveLength(1);
|
||||
expect(graph.nodes[0]?.evidence).toMatchObject({
|
||||
authority: "unknown",
|
||||
state: "unavailable",
|
||||
|
||||
@@ -6,7 +6,7 @@ import { nativeApiBoundarySchema } from "../domain/nativeApiBoundary.js";
|
||||
import { projectNativeApiInspection } from "./NativeApiInspection.js";
|
||||
|
||||
describe("native API inspection", () => {
|
||||
it("projects structured boundary evidence through inspectable substeps", () => {
|
||||
it("preserves structured type and jump-table boundary evidence", () => {
|
||||
const dossier = functionDossierSchema.parse(ghidraFunctionDossier());
|
||||
|
||||
expect(projectNativeApiInspection(dossier)).toMatchObject({
|
||||
@@ -26,11 +26,6 @@ describe("native API inspection", () => {
|
||||
},
|
||||
],
|
||||
},
|
||||
substeps: [
|
||||
{ operation: "analyze_function", status: "completed" },
|
||||
{ operation: "project_native_api_boundary", status: "completed" },
|
||||
{ operation: "preserve_residual_unknowns", status: "completed" },
|
||||
],
|
||||
unsupported_branches: [],
|
||||
residual_unknowns: [],
|
||||
});
|
||||
|
||||
@@ -0,0 +1,104 @@
|
||||
import { describe, expect, it } from "vitest";
|
||||
import { readNativeCallRoutes } from "./NativeCallRoutes.js";
|
||||
import { createAnalysisExecution } from "./AnalysisProvider.js";
|
||||
import { ghidraReferenceEdge } from "../domain/hopperValues.fixture.js";
|
||||
import { jsonValueSchema } from "../domain/jsonValue.js";
|
||||
import { err, ok } from "../domain/result.js";
|
||||
import { AnalysisCancelledError } from "../domain/errors.js";
|
||||
|
||||
const provider = { id: "fixture", name: "Fixture", version: "1" };
|
||||
describe("typed native call routes", () => {
|
||||
it("preserves computed targets, ambiguity and targetless call sites", async () => {
|
||||
const reference = jsonValueSchema.parse(ghidraReferenceEdge());
|
||||
if (
|
||||
reference === null ||
|
||||
typeof reference !== "object" ||
|
||||
Array.isArray(reference)
|
||||
)
|
||||
throw new TypeError("Invalid reference fixture");
|
||||
const result = await readNativeCallRoutes(
|
||||
{
|
||||
execute: async () =>
|
||||
ok(
|
||||
createAnalysisExecution(
|
||||
{
|
||||
reference_kinds_available: true,
|
||||
references: ["0x2000", "0x3000"].map((address) => ({
|
||||
...reference,
|
||||
source_address: "0x1004",
|
||||
target_address: address,
|
||||
target_procedure: { address },
|
||||
kind: {
|
||||
available: true,
|
||||
provenance: "fixture-reference",
|
||||
type: "COMPUTED_CALL",
|
||||
flow: true,
|
||||
call: true,
|
||||
jump: false,
|
||||
data: false,
|
||||
read: false,
|
||||
write: false,
|
||||
indirect: true,
|
||||
computed: true,
|
||||
external: false,
|
||||
conditional: false,
|
||||
terminal: false,
|
||||
primary: true,
|
||||
operand_index: 0,
|
||||
},
|
||||
})),
|
||||
unresolved_calls: [
|
||||
{ address: "0x1008", reason: "No static target" },
|
||||
],
|
||||
},
|
||||
provider,
|
||||
),
|
||||
),
|
||||
},
|
||||
"0x1000",
|
||||
);
|
||||
expect(result).toMatchObject({
|
||||
ok: true,
|
||||
value: {
|
||||
routes: [
|
||||
{
|
||||
address: "0x2000",
|
||||
relation: "indirect_call",
|
||||
resolution: "ambiguous",
|
||||
},
|
||||
{
|
||||
address: "0x3000",
|
||||
relation: "indirect_call",
|
||||
resolution: "ambiguous",
|
||||
},
|
||||
],
|
||||
unknowns: [{ address: "0x1008" }],
|
||||
},
|
||||
});
|
||||
});
|
||||
it("does not fall back on cancellation or invalid typed output", async () => {
|
||||
let calls = 0;
|
||||
const cancelled = await readNativeCallRoutes(
|
||||
{
|
||||
execute: async () => {
|
||||
calls++;
|
||||
return err(new AnalysisCancelledError("procedure_references"));
|
||||
},
|
||||
},
|
||||
"0x1000",
|
||||
);
|
||||
expect(cancelled).toMatchObject({
|
||||
ok: false,
|
||||
error: { _tag: "AnalysisCancelledError" },
|
||||
});
|
||||
expect(calls).toBe(1);
|
||||
const malformed = await readNativeCallRoutes(
|
||||
{ execute: async () => ok(createAnalysisExecution({}, provider)) },
|
||||
"0x1000",
|
||||
);
|
||||
expect(malformed).toMatchObject({
|
||||
ok: false,
|
||||
error: { _tag: "AnalysisOutputError" },
|
||||
});
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,101 @@
|
||||
import { z } from "zod";
|
||||
import type { AnalysisOperationPort } from "./AnalysisProvider.js";
|
||||
import {
|
||||
parseRelatedAddresses,
|
||||
referenceKindSchema,
|
||||
} from "../domain/hopperValues.js";
|
||||
import { err, ok } from "../domain/result.js";
|
||||
import { AnalysisOutputError } from "../domain/errors.js";
|
||||
|
||||
const referencesSchema = z.object({
|
||||
reference_kinds_available: z.boolean().optional(),
|
||||
references: z.array(
|
||||
z.object({
|
||||
source_address: z.string(),
|
||||
target_address: z.string(),
|
||||
target_procedure: z.object({ address: z.string() }).nullable(),
|
||||
kind: referenceKindSchema,
|
||||
}),
|
||||
),
|
||||
unresolved_calls: z
|
||||
.array(z.object({ address: z.string(), reason: z.string() }))
|
||||
.default([]),
|
||||
});
|
||||
/** Prefer typed static call references, preserving computed targets and targetless sites. */
|
||||
export const readNativeCallRoutes = async (
|
||||
analysis: AnalysisOperationPort,
|
||||
procedure: string,
|
||||
signal?: AbortSignal,
|
||||
) => {
|
||||
const options = signal === undefined ? {} : { signal };
|
||||
const execution = await analysis.execute(
|
||||
"procedure_references",
|
||||
{ procedure, direction: "outgoing" },
|
||||
options,
|
||||
);
|
||||
if (execution.ok) {
|
||||
const parsed = referencesSchema.safeParse(execution.value.result);
|
||||
if (!parsed.success)
|
||||
return err(
|
||||
new AnalysisOutputError(
|
||||
"procedure_references",
|
||||
"Invalid typed call references",
|
||||
),
|
||||
);
|
||||
const references = parsed.data.references;
|
||||
if (
|
||||
parsed.data.reference_kinds_available === true ||
|
||||
(references.length > 0 && references.every(({ kind }) => kind.available))
|
||||
) {
|
||||
const calls = references.filter(
|
||||
({ kind }) => kind.available && kind.call,
|
||||
);
|
||||
const countBySite = new Map<string, Set<string>>();
|
||||
for (const call of calls) {
|
||||
const targets =
|
||||
countBySite.get(call.source_address) ?? new Set<string>();
|
||||
targets.add(call.target_address);
|
||||
countBySite.set(call.source_address, targets);
|
||||
}
|
||||
return ok({
|
||||
provider: execution.value.provider,
|
||||
routes: calls.map((call) => ({
|
||||
address: call.target_procedure?.address ?? call.target_address,
|
||||
site: call.source_address,
|
||||
relation:
|
||||
call.kind.available && (call.kind.computed || call.kind.indirect)
|
||||
? ("indirect_call" as const)
|
||||
: ("direct_call" as const),
|
||||
resolution:
|
||||
(countBySite.get(call.source_address)?.size ?? 0) > 1
|
||||
? ("ambiguous" as const)
|
||||
: call.kind.available &&
|
||||
(call.kind.computed || call.kind.indirect)
|
||||
? ("resolved" as const)
|
||||
: ("observed" as const),
|
||||
})),
|
||||
unknowns: parsed.data.unresolved_calls,
|
||||
});
|
||||
}
|
||||
} else if (execution.error._tag !== "AnalysisCapabilityUnavailableError")
|
||||
return err(execution.error);
|
||||
const callees = await analysis.execute(
|
||||
"procedure_callees",
|
||||
{ procedure },
|
||||
options,
|
||||
);
|
||||
if (!callees.ok) return callees;
|
||||
const parsed = parseRelatedAddresses(callees.value.result, "callees");
|
||||
return parsed.ok
|
||||
? ok({
|
||||
provider: callees.value.provider,
|
||||
routes: parsed.value.map((address) => ({
|
||||
address,
|
||||
site: procedure,
|
||||
relation: "provider_call" as const,
|
||||
resolution: "inferred" as const,
|
||||
})),
|
||||
unknowns: [],
|
||||
})
|
||||
: parsed;
|
||||
};
|
||||
@@ -0,0 +1,68 @@
|
||||
import { z } from "zod";
|
||||
import {
|
||||
nativeDispatchMetadataResultSchema,
|
||||
inspectNativeDispatchMetadata,
|
||||
} from "../domain/objcSwiftMetadata.js";
|
||||
import { AnalysisOutputError } from "../domain/errors.js";
|
||||
import { jsonValueSchema } from "../domain/jsonValue.js";
|
||||
import { err, ok } from "../domain/result.js";
|
||||
import type { AnalysisOperationPort } from "./AnalysisProvider.js";
|
||||
import type { EnhancedResult } from "./EnhancedToolTypes.js";
|
||||
/** Prefer validated binary metadata, otherwise preserve the bound provider's symbol-only coverage. */
|
||||
export const inspectNativeDispatch = async (
|
||||
analysis: AnalysisOperationPort,
|
||||
maxRecords: number,
|
||||
signal?: AbortSignal,
|
||||
): EnhancedResult => {
|
||||
const binaryMetadata = await analysis.execute(
|
||||
"inspect_native_dispatch_metadata",
|
||||
{ max_records: maxRecords },
|
||||
signal === undefined ? {} : { signal },
|
||||
);
|
||||
if (binaryMetadata.ok)
|
||||
return ok(
|
||||
jsonValueSchema.parse(
|
||||
nativeDispatchMetadataResultSchema.parse(binaryMetadata.value.result),
|
||||
),
|
||||
);
|
||||
if (binaryMetadata.error._tag !== "AnalysisCapabilityUnavailableError")
|
||||
return err(binaryMetadata.error);
|
||||
const execution = await analysis.execute(
|
||||
"list_names",
|
||||
{},
|
||||
signal === undefined ? {} : { signal },
|
||||
);
|
||||
if (!execution.ok) return err(execution.error);
|
||||
const names = z
|
||||
.array(
|
||||
z.union([
|
||||
z.strictObject({ address: z.string(), value: z.string() }),
|
||||
z.strictObject({ address: z.string(), name: z.string() }),
|
||||
]),
|
||||
)
|
||||
.safeParse(execution.value.result);
|
||||
if (!names.success)
|
||||
return err(
|
||||
new AnalysisOutputError(
|
||||
"list_names",
|
||||
"provider returned an invalid inventory",
|
||||
),
|
||||
);
|
||||
return ok(
|
||||
jsonValueSchema.parse(
|
||||
nativeDispatchMetadataResultSchema.parse({
|
||||
target_sha256: execution.value.subject?.sha256 ?? null,
|
||||
provider: execution.value.provider,
|
||||
analysis_profile_digest:
|
||||
execution.value.analysisProfile?.digest ?? null,
|
||||
result: inspectNativeDispatchMetadata(
|
||||
names.data.map((entry) => ({
|
||||
address: entry.address,
|
||||
name: "value" in entry ? entry.value : entry.name,
|
||||
})),
|
||||
maxRecords,
|
||||
),
|
||||
}),
|
||||
),
|
||||
);
|
||||
};
|
||||
@@ -10,34 +10,21 @@ import {
|
||||
traceNativeInvestigationGraph,
|
||||
joinInterfaceBuilderDispatch,
|
||||
} from "../domain/nativeInvestigationGraph.js";
|
||||
import {
|
||||
inspectNativeDispatchMetadata,
|
||||
nativeDispatchMetadataResultSchema,
|
||||
} from "../domain/objcSwiftMetadata.js";
|
||||
import { nativeDispatchMetadataResultSchema } from "../domain/objcSwiftMetadata.js";
|
||||
import { inspectNativeDispatch } from "./NativeDispatchMetadataInspection.js";
|
||||
import { jsonValueSchema } from "../domain/jsonValue.js";
|
||||
import { parseRelatedAddresses } from "../domain/hopperValues.js";
|
||||
import { readNativeCallRoutes } from "./NativeCallRoutes.js";
|
||||
import { err, ok } from "../domain/result.js";
|
||||
import {
|
||||
AnalysisCancelledError,
|
||||
AnalysisOutputError,
|
||||
projectAnalysisError,
|
||||
} from "../domain/errors.js";
|
||||
import { AnalysisOutputError, projectAnalysisError } from "../domain/errors.js";
|
||||
|
||||
type Input = z.output<typeof enhancedInputSchemas.trace_native_ui_action>;
|
||||
const nativeNameSchema = z.array(
|
||||
z.union([
|
||||
z.strictObject({ address: z.string(), name: z.string() }),
|
||||
z.strictObject({ address: z.string(), value: z.string() }),
|
||||
]),
|
||||
);
|
||||
|
||||
/** Build a UI-to-code trace from the active app and selected native provider. */
|
||||
export const traceNativeUiAction = async (
|
||||
analysis: AnalysisOperationPort,
|
||||
input: Input,
|
||||
signal?: AbortSignal,
|
||||
): EnhancedResult => {
|
||||
const [uiExecution, namesExecution] = await Promise.all([
|
||||
const [uiExecution, metadataExecution] = await Promise.all([
|
||||
analysis.execute(
|
||||
"decode_interface_builder",
|
||||
{
|
||||
@@ -47,44 +34,24 @@ export const traceNativeUiAction = async (
|
||||
},
|
||||
signal === undefined ? {} : { signal },
|
||||
),
|
||||
analysis.execute("list_names", {}, signal === undefined ? {} : { signal }),
|
||||
inspectNativeDispatch(analysis, 20_000, signal),
|
||||
]);
|
||||
|
||||
if (!uiExecution.ok && uiExecution.error._tag === "AnalysisCancelledError")
|
||||
return err(new AnalysisCancelledError("decode_interface_builder"));
|
||||
if (!namesExecution.ok) return err(namesExecution.error);
|
||||
const parsedNames = nativeNameSchema.safeParse(namesExecution.value.result);
|
||||
if (!parsedNames.success)
|
||||
return err(uiExecution.error);
|
||||
if (!metadataExecution.ok) return err(metadataExecution.error);
|
||||
const metadata = nativeDispatchMetadataResultSchema.parse(
|
||||
metadataExecution.value,
|
||||
);
|
||||
const targetSha256 = metadata.target_sha256;
|
||||
if (targetSha256 === null)
|
||||
return err(
|
||||
new AnalysisOutputError(
|
||||
"list_names",
|
||||
"provider returned an invalid name inventory",
|
||||
),
|
||||
);
|
||||
const targetSha256 = namesExecution.value.subject?.sha256;
|
||||
if (targetSha256 === undefined)
|
||||
return err(
|
||||
new AnalysisOutputError(
|
||||
"list_names",
|
||||
"provider did not bind the name inventory to a target SHA-256",
|
||||
"inspect_native_dispatch_metadata",
|
||||
"Dispatch metadata lacks target identity",
|
||||
),
|
||||
);
|
||||
|
||||
const metadata = nativeDispatchMetadataResultSchema.parse({
|
||||
target_sha256: targetSha256,
|
||||
provider: namesExecution.value.provider,
|
||||
analysis_profile_digest:
|
||||
namesExecution.value.analysisProfile?.digest ?? null,
|
||||
result: inspectNativeDispatchMetadata(
|
||||
parsedNames.data.map((entry) => ({
|
||||
address: entry.address,
|
||||
name: "name" in entry ? entry.name : entry.value,
|
||||
})),
|
||||
parsedNames.data.length,
|
||||
),
|
||||
});
|
||||
|
||||
let graph = emptyGraph(targetSha256, namesExecution.value.provider);
|
||||
let graph = emptyGraph(targetSha256, metadata.provider);
|
||||
const coverage = [];
|
||||
if (uiExecution.ok) {
|
||||
const decoded = interfaceBuilderAnalysisSchema.safeParse(
|
||||
@@ -136,7 +103,44 @@ export const traceNativeUiAction = async (
|
||||
});
|
||||
}
|
||||
|
||||
const selected = resolveUiAction(graph, input.action);
|
||||
let selected = resolveUiAction(graph, input.action);
|
||||
if (selected.nodeId === null && selected.candidates.length === 0) {
|
||||
const native = await analysis.execute(
|
||||
"procedure_address",
|
||||
{ procedure: input.action },
|
||||
signal === undefined ? {} : { signal },
|
||||
);
|
||||
if (!native.ok && native.error._tag === "AnalysisCancelledError")
|
||||
return err(native.error);
|
||||
if (native.ok) {
|
||||
const address = z.string().safeParse(native.value.result);
|
||||
if (!address.success || native.value.subject?.sha256 !== targetSha256)
|
||||
return err(
|
||||
new AnalysisOutputError(
|
||||
"procedure_address",
|
||||
"Native seed lacks a validated address or matching target identity",
|
||||
),
|
||||
);
|
||||
const id = `native:function:${address.data}`;
|
||||
graph.nodes.push({
|
||||
id,
|
||||
kind: "function",
|
||||
name: input.action,
|
||||
location: { address: address.data, file_offset: null },
|
||||
attributes: { resolved_by: native.value.provider.id },
|
||||
evidence: [
|
||||
{
|
||||
kind: "reference",
|
||||
description: `Provider resolved the explicit native seed ${input.action}`,
|
||||
location: { address: address.data, file_offset: null },
|
||||
artifact_path: null,
|
||||
artifact_sha256: targetSha256,
|
||||
},
|
||||
],
|
||||
});
|
||||
selected = { nodeId: id, candidates: [], reason: null };
|
||||
}
|
||||
}
|
||||
if (selected.nodeId === null) {
|
||||
coverage.push(...graph.coverage);
|
||||
const trace = {
|
||||
@@ -152,7 +156,7 @@ export const traceNativeUiAction = async (
|
||||
reason: selected.reason,
|
||||
coverage,
|
||||
limitations: [
|
||||
"The query did not identify one unique authored UI action; no handler path was inferred.",
|
||||
"The query did not identify one unique authored UI action or native function; no handler path was inferred.",
|
||||
],
|
||||
};
|
||||
return ok(
|
||||
@@ -179,9 +183,10 @@ export const traceNativeUiAction = async (
|
||||
});
|
||||
if (expanded.error !== undefined) return err(expanded.error);
|
||||
coverage.push({
|
||||
facet: "direct_native_calls",
|
||||
facet: "static_native_calls",
|
||||
status: "partial",
|
||||
reason: "resolved_direct_calls_do_not_cover_all_indirect_dispatch",
|
||||
reason:
|
||||
"typed_direct_and_indirect_references_do_not_cover_all_runtime_dispatch; untyped_provider_callees_remain_inferred",
|
||||
examined: expanded.examined,
|
||||
omitted: expanded.omitted,
|
||||
});
|
||||
@@ -390,10 +395,10 @@ const addDirectCallees = async (input: {
|
||||
omitted += queue.length - queueIndex + 1;
|
||||
break;
|
||||
}
|
||||
const execution = await input.analysis.execute(
|
||||
"procedure_callees",
|
||||
{ procedure: current.address },
|
||||
input.signal === undefined ? {} : { signal: input.signal },
|
||||
const execution = await readNativeCallRoutes(
|
||||
input.analysis,
|
||||
current.address,
|
||||
input.signal,
|
||||
);
|
||||
examined += 1;
|
||||
if (!execution.ok) {
|
||||
@@ -414,35 +419,45 @@ const addDirectCallees = async (input: {
|
||||
});
|
||||
continue;
|
||||
}
|
||||
const related = parseRelatedAddresses(execution.value.result, "callees");
|
||||
if (!related.ok) {
|
||||
const id = `unknown-callees:${current.address}`;
|
||||
for (const unknown of execution.value.unknowns) {
|
||||
if (edges.size >= input.input.max_edges) {
|
||||
truncated = true;
|
||||
omitted++;
|
||||
break;
|
||||
}
|
||||
const id = `unknown-dispatch:${current.address}:${unknown.address}`;
|
||||
edges.set(id, {
|
||||
id,
|
||||
from: current.node.id,
|
||||
to: null,
|
||||
relation: "direct_call",
|
||||
relation: "indirect_call",
|
||||
resolution: "unresolved",
|
||||
reason: "provider_returned_unreadable_callee_relationships",
|
||||
evidence: [],
|
||||
limitations: [
|
||||
"The provider result could not be normalized into callee addresses.",
|
||||
reason: unknown.reason,
|
||||
evidence: [
|
||||
{
|
||||
kind: "reference",
|
||||
description: unknown.reason,
|
||||
location: { address: unknown.address, file_offset: null },
|
||||
artifact_path: null,
|
||||
artifact_sha256: input.targetSha256,
|
||||
},
|
||||
],
|
||||
limitations: [],
|
||||
});
|
||||
continue;
|
||||
}
|
||||
for (const [index, address] of related.value.entries()) {
|
||||
for (const [index, route] of execution.value.routes.entries()) {
|
||||
const address = route.address;
|
||||
if (edges.size >= input.input.max_edges) {
|
||||
truncated = true;
|
||||
omitted += related.value.length - index;
|
||||
omitted += execution.value.routes.length - index;
|
||||
break;
|
||||
}
|
||||
const targetId = `native:function:${address}`;
|
||||
const evidence = [
|
||||
{
|
||||
kind: "reference" as const,
|
||||
description: `${execution.value.provider.name} resolved a direct callee from ${current.address} to ${address}`,
|
||||
location: { address: current.address, file_offset: null },
|
||||
description: `${execution.value.provider.name} reported ${route.relation} from ${current.address} to ${address}`,
|
||||
location: { address: route.site, file_offset: null },
|
||||
artifact_path: null,
|
||||
artifact_sha256: input.targetSha256,
|
||||
},
|
||||
@@ -476,13 +491,13 @@ const addDirectCallees = async (input: {
|
||||
nodes.set(targetId, node);
|
||||
queue.push({ node, address, depth: current.depth + 1 });
|
||||
}
|
||||
const edgeId = `call:${current.address}:${address}`;
|
||||
const edgeId = `call:${current.address}:${route.site}:${address}`;
|
||||
edges.set(edgeId, {
|
||||
id: edgeId,
|
||||
from: current.node.id,
|
||||
to: targetId,
|
||||
relation: "direct_call",
|
||||
resolution: "observed",
|
||||
relation: route.relation,
|
||||
resolution: route.resolution,
|
||||
evidence,
|
||||
limitations: [
|
||||
"A resolved static call edge does not establish runtime reachability.",
|
||||
|
||||
@@ -0,0 +1,194 @@
|
||||
import { describe, expect, it } from "vitest";
|
||||
import { traceNativeValues } from "./NativeValueTrace.js";
|
||||
import {
|
||||
createAnalysisExecution,
|
||||
type AnalysisOperationPort,
|
||||
} from "./AnalysisProvider.js";
|
||||
import { ghidraFunctionDossier } from "../domain/hopperValues.fixture.js";
|
||||
import { functionDossierSchema } from "../domain/hopperValues.js";
|
||||
import { jsonValueSchema } from "../domain/jsonValue.js";
|
||||
import { AnalysisCancelledError } from "../domain/errors.js";
|
||||
import { ok, err } from "../domain/result.js";
|
||||
|
||||
const subject = {
|
||||
path: "/fixture",
|
||||
sha256: "a".repeat(64),
|
||||
format: "mach-o" as const,
|
||||
architecture: "arm64" as const,
|
||||
};
|
||||
const provider = { id: "fixture", name: "Fixture", version: "1" };
|
||||
const scalar = {
|
||||
kind: "constant",
|
||||
size_bytes: 4,
|
||||
location: null,
|
||||
constant_hex: "3",
|
||||
};
|
||||
const node = (id: string, address: string, opcode: string) => ({
|
||||
id,
|
||||
address,
|
||||
sequence: 0,
|
||||
opcode,
|
||||
is_dead: true,
|
||||
block_membership: "member",
|
||||
inputs: [scalar, scalar],
|
||||
output: scalar,
|
||||
});
|
||||
const analysis: AnalysisOperationPort = {
|
||||
execute: async (operation, parameters) => {
|
||||
if (operation === "resolve_native_call_targets")
|
||||
return ok(
|
||||
createAnalysisExecution(
|
||||
{
|
||||
call_site: "0x1000",
|
||||
procedure: "0x1000",
|
||||
status: "direct",
|
||||
mechanism: "direct",
|
||||
targets: [
|
||||
{
|
||||
address: "0x2000",
|
||||
procedure: "0x2000",
|
||||
status: "direct",
|
||||
basis: "provider-reference",
|
||||
references: [],
|
||||
},
|
||||
],
|
||||
limitations: [],
|
||||
},
|
||||
provider,
|
||||
{ subject },
|
||||
),
|
||||
);
|
||||
const callee = parameters.procedure === "0x2000";
|
||||
return ok(
|
||||
createAnalysisExecution(
|
||||
jsonValueSchema.parse({
|
||||
...functionDossierSchema.parse(ghidraFunctionDossier()),
|
||||
procedure: {
|
||||
address: callee ? "0x2000" : "0x1000",
|
||||
name: callee ? "callee" : "caller",
|
||||
classification: null,
|
||||
signature: null,
|
||||
locals: [],
|
||||
},
|
||||
native_value_flow: {
|
||||
available: true,
|
||||
provenance: "ghidra-high-pcode",
|
||||
operations: callee
|
||||
? [node("return", "0x2000", "RETURN")]
|
||||
: [node("call", "0x1000", "CALL")],
|
||||
def_use: [],
|
||||
effects: [],
|
||||
parameters: callee
|
||||
? [{ ordinal: 0, name: "value", data_type: "/int" }]
|
||||
: [],
|
||||
parameter_uses: callee
|
||||
? [{ ordinal: 0, use: "return", input_index: 1 }]
|
||||
: [],
|
||||
truncated: false,
|
||||
omitted_operations_lower_bound: 0,
|
||||
known_omitted_inputs: 0,
|
||||
known_omitted_edges: 0,
|
||||
limitations: [],
|
||||
},
|
||||
}),
|
||||
provider,
|
||||
{ subject },
|
||||
),
|
||||
);
|
||||
},
|
||||
};
|
||||
describe("bounded native value dependency composition", () => {
|
||||
it("reports work truncation and stable pagination without traversing ambiguous calls", async () => {
|
||||
const bounded = await traceNativeValues(analysis, {
|
||||
procedure: "0x1000",
|
||||
max_functions: 1,
|
||||
});
|
||||
expect(bounded.ok).toBe(true);
|
||||
if (bounded.ok)
|
||||
expect(bounded.value).toMatchObject({
|
||||
truncated: true,
|
||||
decompilations: 1,
|
||||
});
|
||||
const page = await traceNativeValues(analysis, {
|
||||
procedure: "0x1000",
|
||||
limit: 1,
|
||||
});
|
||||
expect(page.ok).toBe(true);
|
||||
if (page.ok)
|
||||
expect(page.value).toMatchObject({ total_nodes: 3, next_offset: 1 });
|
||||
const ambiguous = await traceNativeValues(
|
||||
{
|
||||
execute: async (operation, parameters, options) => {
|
||||
if (operation !== "resolve_native_call_targets")
|
||||
return analysis.execute(operation, parameters, options);
|
||||
return ok(
|
||||
createAnalysisExecution(
|
||||
{
|
||||
call_site: "0x1000",
|
||||
procedure: "0x1000",
|
||||
status: "ambiguous",
|
||||
mechanism: "computed",
|
||||
targets: [
|
||||
{
|
||||
address: "0x2000",
|
||||
procedure: "0x2000",
|
||||
status: "candidate",
|
||||
basis: "provider-reference",
|
||||
references: [],
|
||||
},
|
||||
],
|
||||
limitations: [],
|
||||
},
|
||||
provider,
|
||||
{ subject },
|
||||
),
|
||||
);
|
||||
},
|
||||
},
|
||||
{ procedure: "0x1000" },
|
||||
);
|
||||
expect(ambiguous.ok).toBe(true);
|
||||
if (ambiguous.ok)
|
||||
expect(ambiguous.value).toMatchObject({
|
||||
decompilations: 1,
|
||||
edges: [expect.objectContaining({ status: "candidate" })],
|
||||
});
|
||||
});
|
||||
it("propagates cancellation and rejects cross-target dependencies", async () => {
|
||||
const controller = new AbortController();
|
||||
controller.abort();
|
||||
expect(
|
||||
await traceNativeValues(
|
||||
analysis,
|
||||
{ procedure: "0x1000" },
|
||||
controller.signal,
|
||||
),
|
||||
).toMatchObject({ ok: false, error: { _tag: "AnalysisCancelledError" } });
|
||||
const cancelled = await traceNativeValues(
|
||||
{
|
||||
execute: async () =>
|
||||
err(new AnalysisCancelledError("analyze_function")),
|
||||
},
|
||||
{ procedure: "0x1000" },
|
||||
);
|
||||
expect(cancelled.ok).toBe(false);
|
||||
const mismatch = await traceNativeValues(
|
||||
{
|
||||
execute: async (operation, parameters, options) => {
|
||||
const value = await analysis.execute(operation, parameters, options);
|
||||
return value.ok && parameters.procedure === "0x2000"
|
||||
? ok({
|
||||
...value.value,
|
||||
subject: { ...subject, sha256: "b".repeat(64) },
|
||||
})
|
||||
: value;
|
||||
},
|
||||
},
|
||||
{ procedure: "0x1000" },
|
||||
);
|
||||
expect(mismatch).toMatchObject({
|
||||
ok: false,
|
||||
error: { _tag: "AnalysisOutputError" },
|
||||
});
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,389 @@
|
||||
import { functionDossierSchema } from "../domain/hopperValues.js";
|
||||
import { nativeCallTargetsSchema } from "../domain/nativeInstruction.js";
|
||||
import {
|
||||
nativeValueTraceInputSchema,
|
||||
nativeValueTraceSchema,
|
||||
} from "../domain/nativeValueTrace.js";
|
||||
import { createEvidence } from "../domain/evidence.js";
|
||||
import {
|
||||
AnalysisCancelledError,
|
||||
AnalysisOutputError,
|
||||
} from "../domain/errors.js";
|
||||
import { err, ok } from "../domain/result.js";
|
||||
import type { AnalysisOperationPort } from "./AnalysisProvider.js";
|
||||
import type { EnhancedResult } from "./EnhancedToolTypes.js";
|
||||
|
||||
/** Compose bounded high-p-code def-use graphs across exactly referenced call destinations. */
|
||||
export const traceNativeValues = async (
|
||||
analysis: AnalysisOperationPort,
|
||||
parameters: unknown,
|
||||
signal?: AbortSignal,
|
||||
): EnhancedResult => {
|
||||
const input = nativeValueTraceInputSchema.parse(parameters);
|
||||
const nodes: typeof nativeValueTraceSchema._output.nodes = [];
|
||||
const edges: typeof nativeValueTraceSchema._output.edges = [];
|
||||
const procedures: typeof nativeValueTraceSchema._output.procedures = [];
|
||||
const unknowns: typeof nativeValueTraceSchema._output.unknowns = [];
|
||||
const callBindings: {
|
||||
caller: string;
|
||||
callee: string;
|
||||
call: string;
|
||||
argument_count: number;
|
||||
output: boolean;
|
||||
evidence_id: string;
|
||||
}[] = [];
|
||||
const pending = [{ procedure: input.procedure, depth: 0 }];
|
||||
const visited = new Set<string>();
|
||||
let targetSha256: string | undefined;
|
||||
let truncated = false;
|
||||
let decompilations = 0;
|
||||
let callSites = 0;
|
||||
let bytes = 0;
|
||||
while (pending.length > 0) {
|
||||
if (signal?.aborted)
|
||||
return err(new AnalysisCancelledError("trace_native_values"));
|
||||
const next = pending.shift();
|
||||
if (next === undefined || visited.has(next.procedure)) continue;
|
||||
if (decompilations >= input.max_functions) {
|
||||
truncated = true;
|
||||
unknowns.push({
|
||||
procedure: next.procedure,
|
||||
address: null,
|
||||
reason: "decompilation budget reached",
|
||||
});
|
||||
break;
|
||||
}
|
||||
const execution = await analysis.execute(
|
||||
"analyze_function",
|
||||
{ procedure: next.procedure },
|
||||
signal === undefined ? {} : { signal },
|
||||
);
|
||||
decompilations++;
|
||||
if (!execution.ok) {
|
||||
if (execution.error._tag === "AnalysisCancelledError")
|
||||
return err(execution.error);
|
||||
unknowns.push({
|
||||
procedure: next.procedure,
|
||||
address: null,
|
||||
reason: execution.error.message,
|
||||
});
|
||||
continue;
|
||||
}
|
||||
const parsed = functionDossierSchema.safeParse(execution.value.result);
|
||||
if (!parsed.success || execution.value.subject === null)
|
||||
return err(
|
||||
new AnalysisOutputError(
|
||||
"trace_native_values",
|
||||
"Function dossier lacks validated facts or artifact identity",
|
||||
),
|
||||
);
|
||||
const dossier = parsed.data;
|
||||
const address = dossier.procedure.address;
|
||||
if (visited.has(address)) continue;
|
||||
visited.add(next.procedure);
|
||||
visited.add(address);
|
||||
targetSha256 ??= execution.value.subject.sha256;
|
||||
if (execution.value.subject.sha256 !== targetSha256)
|
||||
return err(
|
||||
new AnalysisOutputError(
|
||||
"trace_native_values",
|
||||
"Cross-function target digest mismatch",
|
||||
),
|
||||
);
|
||||
const evidence = createEvidence(
|
||||
execution.value.subject,
|
||||
execution.value.provider,
|
||||
{
|
||||
operation: "analyze_function",
|
||||
parameters: { procedure: next.procedure },
|
||||
result: execution.value.result,
|
||||
rawResult: execution.value.rawResult,
|
||||
limitations: execution.value.limitations,
|
||||
locations: execution.value.locations,
|
||||
...(execution.value.analysisProfile === undefined
|
||||
? {}
|
||||
: { analysisProfile: execution.value.analysisProfile }),
|
||||
},
|
||||
);
|
||||
const evidenceId = evidence.evidence_id;
|
||||
procedures.push({
|
||||
address,
|
||||
depth: next.depth,
|
||||
evidence_id: evidenceId,
|
||||
provider: execution.value.provider.id,
|
||||
analysis_profile_digest: execution.value.analysisProfile?.digest ?? null,
|
||||
});
|
||||
const flow = dossier.native_value_flow;
|
||||
if (flow === null || !flow.available) {
|
||||
unknowns.push({
|
||||
procedure: address,
|
||||
address: null,
|
||||
reason: flow?.reason ?? "Provider has no native def-use model",
|
||||
});
|
||||
continue;
|
||||
}
|
||||
if (flow.truncated) {
|
||||
truncated = true;
|
||||
unknowns.push({
|
||||
procedure: address,
|
||||
address: null,
|
||||
reason: "Provider p-code was truncated",
|
||||
});
|
||||
}
|
||||
const ids = new Set<string>();
|
||||
const qualified = (id: string) => `${address}/${id}`;
|
||||
for (const operation of flow.operations) {
|
||||
if (
|
||||
operation.block_membership === "detached" ||
|
||||
(operation.block_membership === "unavailable" && operation.is_dead)
|
||||
)
|
||||
continue;
|
||||
const node = {
|
||||
id: qualified(operation.id),
|
||||
procedure: address,
|
||||
evidence_id: evidenceId,
|
||||
operation,
|
||||
kind: "operation" as const,
|
||||
parameter: null,
|
||||
};
|
||||
const size = Buffer.byteLength(JSON.stringify(node));
|
||||
if (nodes.length >= input.max_nodes || bytes + size > 8 * 1024 * 1024) {
|
||||
truncated = true;
|
||||
break;
|
||||
}
|
||||
bytes += size;
|
||||
ids.add(operation.id);
|
||||
nodes.push(node);
|
||||
}
|
||||
for (const parameter of flow.parameters) {
|
||||
if (nodes.length >= input.max_nodes) {
|
||||
truncated = true;
|
||||
break;
|
||||
}
|
||||
nodes.push({
|
||||
id: `${address}/parameter:${parameter.ordinal}`,
|
||||
procedure: address,
|
||||
evidence_id: evidenceId,
|
||||
kind: "parameter",
|
||||
operation: null,
|
||||
parameter,
|
||||
});
|
||||
}
|
||||
for (const use of flow.parameter_uses) {
|
||||
if (
|
||||
!ids.has(use.use) ||
|
||||
!nodes.some((node) => node.id === `${address}/parameter:${use.ordinal}`)
|
||||
)
|
||||
continue;
|
||||
if (edges.length >= input.max_edges) {
|
||||
truncated = true;
|
||||
break;
|
||||
}
|
||||
edges.push({
|
||||
source: `${address}/parameter:${use.ordinal}`,
|
||||
target: qualified(use.use),
|
||||
input_index: use.input_index,
|
||||
kind: "parameter-use",
|
||||
status: "derived",
|
||||
evidence_id: evidenceId,
|
||||
});
|
||||
}
|
||||
for (const edge of flow.def_use) {
|
||||
if (!ids.has(edge.definition) || !ids.has(edge.use)) continue;
|
||||
if (edges.length >= input.max_edges) {
|
||||
truncated = true;
|
||||
break;
|
||||
}
|
||||
edges.push({
|
||||
source: qualified(edge.definition),
|
||||
target: qualified(edge.use),
|
||||
input_index: edge.input_index,
|
||||
kind: "def-use",
|
||||
status: "derived",
|
||||
evidence_id: evidenceId,
|
||||
});
|
||||
}
|
||||
for (const operation of flow.operations) {
|
||||
if (
|
||||
!ids.has(operation.id) ||
|
||||
!["CALL", "CALLIND"].includes(operation.opcode)
|
||||
)
|
||||
continue;
|
||||
if (callSites >= input.max_call_sites) {
|
||||
truncated = true;
|
||||
unknowns.push({
|
||||
procedure: address,
|
||||
address: operation.address,
|
||||
reason: "Call-site resolution budget reached",
|
||||
});
|
||||
break;
|
||||
}
|
||||
callSites++;
|
||||
const resolved = await analysis.execute(
|
||||
"resolve_native_call_targets",
|
||||
{ address: operation.address },
|
||||
signal === undefined ? {} : { signal },
|
||||
);
|
||||
if (!resolved.ok) {
|
||||
if (resolved.error._tag === "AnalysisCancelledError")
|
||||
return err(resolved.error);
|
||||
unknowns.push({
|
||||
procedure: address,
|
||||
address: operation.address,
|
||||
reason: resolved.error.message,
|
||||
});
|
||||
continue;
|
||||
}
|
||||
const targets = nativeCallTargetsSchema.safeParse(resolved.value.result);
|
||||
if (!targets.success)
|
||||
return err(
|
||||
new AnalysisOutputError(
|
||||
"resolve_native_call_targets",
|
||||
"Invalid static call resolution",
|
||||
),
|
||||
);
|
||||
if (targets.data.targets.length === 0)
|
||||
unknowns.push({
|
||||
procedure: address,
|
||||
address: operation.address,
|
||||
reason: `Call target ${targets.data.status}`,
|
||||
});
|
||||
for (const target of targets.data.targets) {
|
||||
if (edges.length >= input.max_edges) {
|
||||
truncated = true;
|
||||
break;
|
||||
}
|
||||
const destination = target.procedure ?? target.address;
|
||||
edges.push({
|
||||
source: qualified(operation.id),
|
||||
target: destination,
|
||||
input_index: null,
|
||||
kind: "call",
|
||||
status: target.status,
|
||||
evidence_id: evidenceId,
|
||||
});
|
||||
if (target.status !== "candidate")
|
||||
callBindings.push({
|
||||
caller: address,
|
||||
callee: destination,
|
||||
call: qualified(operation.id),
|
||||
argument_count: Math.max(0, operation.inputs.length - 1),
|
||||
output: operation.output !== null,
|
||||
evidence_id: evidenceId,
|
||||
});
|
||||
if (next.depth < input.max_depth && target.status !== "candidate")
|
||||
pending.push({ procedure: destination, depth: next.depth + 1 });
|
||||
else if (!visited.has(destination)) {
|
||||
truncated = true;
|
||||
unknowns.push({
|
||||
procedure: address,
|
||||
address: operation.address,
|
||||
reason:
|
||||
target.status === "candidate"
|
||||
? "Ambiguous call candidates were not traversed"
|
||||
: "Call depth budget reached",
|
||||
});
|
||||
}
|
||||
}
|
||||
}
|
||||
if (
|
||||
truncated &&
|
||||
(nodes.length >= input.max_nodes ||
|
||||
edges.length >= input.max_edges ||
|
||||
bytes >= 8 * 1024 * 1024)
|
||||
)
|
||||
break;
|
||||
}
|
||||
if (targetSha256 === undefined)
|
||||
return err(
|
||||
new AnalysisOutputError(
|
||||
"trace_native_values",
|
||||
"No seed function could be analyzed",
|
||||
),
|
||||
);
|
||||
for (const binding of callBindings) {
|
||||
const parameters = nodes.filter(
|
||||
(node) => node.procedure === binding.callee && node.kind === "parameter",
|
||||
);
|
||||
if (parameters.length === 0)
|
||||
unknowns.push({
|
||||
procedure: binding.caller,
|
||||
address: null,
|
||||
reason: `Parameter bindings for ${binding.callee} are unavailable or omitted`,
|
||||
});
|
||||
for (const node of parameters) {
|
||||
const ordinal = node.parameter?.ordinal;
|
||||
if (ordinal === undefined || ordinal >= binding.argument_count) {
|
||||
unknowns.push({
|
||||
procedure: binding.caller,
|
||||
address: null,
|
||||
reason: `Argument ${ordinal ?? "unknown"} for ${binding.callee} was not recovered`,
|
||||
});
|
||||
continue;
|
||||
}
|
||||
if (edges.length >= input.max_edges) {
|
||||
truncated = true;
|
||||
break;
|
||||
}
|
||||
edges.push({
|
||||
source: binding.call,
|
||||
target: node.id,
|
||||
input_index: ordinal + 1,
|
||||
kind: "argument-binding",
|
||||
status: "derived",
|
||||
evidence_id: binding.evidence_id,
|
||||
});
|
||||
}
|
||||
if (binding.output)
|
||||
for (const node of nodes.filter(
|
||||
(node) =>
|
||||
node.procedure === binding.callee &&
|
||||
node.operation?.opcode === "RETURN" &&
|
||||
node.operation.inputs.length > 1,
|
||||
)) {
|
||||
if (edges.length >= input.max_edges) {
|
||||
truncated = true;
|
||||
break;
|
||||
}
|
||||
edges.push({
|
||||
source: node.id,
|
||||
target: binding.call,
|
||||
input_index: 1,
|
||||
kind: "return-binding",
|
||||
status: "derived",
|
||||
evidence_id: node.evidence_id,
|
||||
});
|
||||
}
|
||||
}
|
||||
const page = nodes.slice(input.offset, input.offset + input.limit);
|
||||
const pageIds = new Set(page.map(({ id }) => id));
|
||||
const result = nativeValueTraceSchema.parse({
|
||||
seed: input.procedure,
|
||||
target_sha256: targetSha256,
|
||||
nodes: page,
|
||||
edges: edges.filter(({ source }) => pageIds.has(source)),
|
||||
procedures,
|
||||
unknowns,
|
||||
total_nodes: nodes.length,
|
||||
total_edges: edges.length,
|
||||
decompilations,
|
||||
next_offset:
|
||||
input.offset + page.length < nodes.length
|
||||
? input.offset + page.length
|
||||
: null,
|
||||
truncated: truncated || page.length !== nodes.length,
|
||||
limitations: [
|
||||
"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.",
|
||||
],
|
||||
});
|
||||
if (Buffer.byteLength(JSON.stringify(result)) > 32 * 1024 * 1024)
|
||||
return err(
|
||||
new AnalysisOutputError(
|
||||
"trace_native_values",
|
||||
"Graph output exceeds 32 MiB; lower max_nodes, max_edges or page limit",
|
||||
),
|
||||
);
|
||||
return ok(result);
|
||||
};
|
||||
@@ -394,8 +394,10 @@ export const captureTerminalFrames = (options: {
|
||||
at_ms: atMs,
|
||||
data: normalized,
|
||||
});
|
||||
options.recordEvent("frames", sequence);
|
||||
// Queue the observed output before publishing it: reactive subscribers may
|
||||
// synchronously resize the terminal in response to this journal entry.
|
||||
options.renderer.write(data, atMs);
|
||||
options.recordEvent("frames", sequence);
|
||||
options.checkpoints.observeTerminal(normalized);
|
||||
});
|
||||
return () => truncated;
|
||||
|
||||
@@ -43,8 +43,13 @@ it("returns detached terminal and filesystem checkpoint observations", async ()
|
||||
expect(frames).toHaveLength(22);
|
||||
expect(frames.slice(0, 2).map(({ at_ms }) => at_ms)).toEqual([20, 10]);
|
||||
expect(observed).toHaveLength(22);
|
||||
if (frames[0] !== undefined) Reflect.set(frames[0], "cursor_x", 999);
|
||||
expect((await renderer.frames())[0]?.cursor_x).not.toBe(999);
|
||||
const frame = frames[0];
|
||||
if (frame === undefined) throw new Error("expected observed frame");
|
||||
const originalCursor = frame.cursor_x;
|
||||
Reflect.set(frame, "cursor_x", 999);
|
||||
const reread = await renderer.frames();
|
||||
expect(reread).toHaveLength(frames.length);
|
||||
expect(reread[0]?.cursor_x).toBe(originalCursor);
|
||||
await renderer.dispose();
|
||||
|
||||
const scenario = parseProcessScenario(base);
|
||||
@@ -55,7 +60,9 @@ it("returns detached terminal and filesystem checkpoint observations", async ()
|
||||
{ signal: undefined },
|
||||
);
|
||||
const first = await checkpoints.finish({ files: [], truncated: false });
|
||||
if (first[0] !== undefined) Reflect.set(first[0], "name", "tampered");
|
||||
const checkpoint = first[0];
|
||||
if (checkpoint === undefined) throw new Error("expected checkpoint");
|
||||
Reflect.set(checkpoint, "name", "tampered");
|
||||
const second = await checkpoints.finish({ files: [], truncated: false });
|
||||
expect(second[0]?.name).toBe("before");
|
||||
await checkpoints.dispose();
|
||||
@@ -276,7 +283,7 @@ it("cancels filesystem snapshots before traversing declared roots", async () =>
|
||||
});
|
||||
|
||||
it("parses bounded scenarios and rejects unordered events", () => {
|
||||
expect(parseProcessScenario(base).timeout_ms).toBe(30_000);
|
||||
const timeoutMs = parseProcessScenario(base).timeout_ms;
|
||||
expect(() =>
|
||||
parseProcessScenario({
|
||||
...base,
|
||||
@@ -295,7 +302,7 @@ it("parses bounded scenarios and rejects unordered events", () => {
|
||||
expect(() =>
|
||||
parseProcessScenario({
|
||||
...base,
|
||||
events: [{ type: "input", at_ms: 31_000, data: "late" }],
|
||||
events: [{ type: "input", at_ms: timeoutMs + 1, data: "late" }],
|
||||
}),
|
||||
).toThrow(/after the scenario timeout/);
|
||||
});
|
||||
|
||||
@@ -1,16 +0,0 @@
|
||||
import { describe, expect, it } from "vitest";
|
||||
|
||||
import { completeReconstructionCoverageData } from "../domain/reconstructionCoverage.fixture.js";
|
||||
import { reconstructionCoverageEvaluationInputSchema } from "./ReconstructionCoverageService.js";
|
||||
|
||||
describe("reconstruction coverage service input", () => {
|
||||
it("accepts caller boundary identifiers longer than the former schema ceiling", () => {
|
||||
const boundaryId = "b".repeat(1_000);
|
||||
const parsed = reconstructionCoverageEvaluationInputSchema.parse({
|
||||
coverage: completeReconstructionCoverageData(),
|
||||
boundary_id: boundaryId,
|
||||
});
|
||||
|
||||
expect(parsed.boundary_id).toBe(boundaryId);
|
||||
});
|
||||
});
|
||||
@@ -12,7 +12,6 @@ import { jsonValueSchema } from "../domain/jsonValue.js";
|
||||
import { processCaptureSchema } from "../domain/processCapture.js";
|
||||
import {
|
||||
reconstructionObligationLedgerSchema,
|
||||
serializeReconstructionObligationLedger,
|
||||
type ReconstructionObligationLedgerInput,
|
||||
type ReconstructionObligationLedger,
|
||||
type ReviewedReconstructionObligation,
|
||||
@@ -153,13 +152,8 @@ describe("reconstruction obligation ledger", () => {
|
||||
);
|
||||
expect(first.obligations).toHaveLength(2);
|
||||
expect(first).toEqual(second);
|
||||
expect(second.ledger_id).toBe(first.ledger_id);
|
||||
expect(second.closure_digest).toBe(first.closure_digest);
|
||||
expect(first.obligations[0]?.source_state).toBe("reviewed");
|
||||
expect(first.status).toBe("open");
|
||||
expect(serializeReconstructionObligationLedger(first)).toBe(
|
||||
serializeReconstructionObligationLedger(second),
|
||||
);
|
||||
});
|
||||
|
||||
it("does not let green unit evidence close a packaged-process obligation", () => {
|
||||
|
||||
@@ -92,7 +92,6 @@ describe("setup workflow", () => {
|
||||
expect(result.status).toBe("needs_human");
|
||||
expect(host.hopperInstalls).toBe(0);
|
||||
expect(result.appliedActions).toEqual(["installed_skill"]);
|
||||
expect(result.remediation).toContain("--install-hopper");
|
||||
expect(result.remediation).toBe(
|
||||
"Hopper is optional for non-Hopper providers. Rerun with --yes --install-hopper for deep native analysis.",
|
||||
);
|
||||
|
||||
@@ -26,7 +26,6 @@ describe("setup installer failure projection", () => {
|
||||
] as const)("maps %s to %s", (reason, code) => {
|
||||
const result = setupInstallFailure(reason as HopperInstallFailureReason);
|
||||
expect(result).toMatchObject({ status: "failed", code });
|
||||
if (result.status === "failed")
|
||||
expect(result.remediation.length).toBeGreaterThan(20);
|
||||
expect(result).toMatchObject({ remediation: expect.stringMatching(/\S/u) });
|
||||
});
|
||||
});
|
||||
|
||||
@@ -6,6 +6,7 @@ import { silentLogger, type Logger } from "../logger.js";
|
||||
import { GENERATED_AUXILIARY_PROVIDERS } from "../generatedMcpToolCatalog.js";
|
||||
import { AnalysisProviderRegistry } from "./AnalysisProviderRegistry.js";
|
||||
import { composeBinarySession } from "./BinarySessionComposition.js";
|
||||
import { nativeHostCapabilities } from "../native/NativeHostCapabilities.js";
|
||||
import { LazyAnalysisProvider } from "./LazyAnalysisProvider.js";
|
||||
|
||||
/**
|
||||
@@ -32,7 +33,11 @@ export const createBinarySession = (
|
||||
const generated = auxiliary.get(id);
|
||||
if (generated === undefined)
|
||||
throw new TypeError(`Missing generated provider metadata for ${id}`);
|
||||
return new LazyAnalysisProvider({ ...generated, load });
|
||||
return new LazyAnalysisProvider({
|
||||
...generated,
|
||||
capabilities: nativeHostCapabilities(generated.capabilities),
|
||||
load,
|
||||
});
|
||||
};
|
||||
return composeBinarySession(
|
||||
new AnalysisProviderRegistry([hopper, ghidra], config.analysisProvider),
|
||||
|
||||
Reference in New Issue
Block a user