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:
morluto
2026-10-04 16:02:36 +08:00
committed by GitHub
parent 0356f7677f
commit 4fbc501121
205 changed files with 8136 additions and 1816 deletions
@@ -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),
+6 -2
View File
@@ -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,
});
});
});
+1
View File
@@ -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);
});
});
+8 -1
View File
@@ -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> => {
+11 -16
View File
@@ -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,
}),
+12 -41
View File
@@ -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);
});
});
+18 -51
View File
@@ -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",
+1 -6
View File
@@ -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: [],
});
+104
View File
@@ -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" },
});
});
});
+101
View File
@@ -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,
),
}),
),
);
};
+88 -73
View File
@@ -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.",
+194
View File
@@ -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" },
});
});
});
+389
View File
@@ -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);
};
+3 -1
View File
@@ -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", () => {
-1
View File
@@ -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.",
);
+1 -2
View File
@@ -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 -1
View File
@@ -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),