fix(contracts)!: require observed provider output metadata

Reject omitted segment bounds, procedure classification and body facts, unresolved-call observations, dossier facets, and Ghidra parameter flow metadata. Providers emit explicit nulls for unsupported facets. Verify those unknowns in the real Hopper workflow.

BREAKING CHANGE: Provider analysis outputs must explicitly supply metadata previously repaired with defaults; unsupported nullable facets must be reported as null.
This commit is contained in:
morluto
2026-10-10 03:52:13 +08:00
parent e3bbb9ac45
commit a4ba8aecd5
29 changed files with 465 additions and 112 deletions
@@ -100,11 +100,7 @@ describe("native API inspection", () => {
const value = ghidraFunctionDossier();
if (typeof value !== "object" || value === null || Array.isArray(value))
throw new TypeError("Ghidra dossier fixture is invalid");
const dossier = functionDossierSchema.parse(
Object.fromEntries(
Object.entries(value).filter(([key]) => key !== "native_api"),
),
);
const dossier = functionDossierSchema.parse({ ...value, native_api: null });
expect(projectNativeApiInspection(dossier)).toMatchObject({
boundary: { available: false },
@@ -101,4 +101,30 @@ describe("typed native call routes", () => {
error: { _tag: "AnalysisOutputError" },
});
});
it("rejects omitted unresolved-call observations instead of claiming none", async () => {
let calls = 0;
const result = await readNativeCallRoutes(
{
execute: async () => {
calls++;
return ok(
createAnalysisExecution(
{
reference_kinds_available: false,
references: [],
},
provider,
),
);
},
},
"0x1000",
);
expect(result).toMatchObject({
ok: false,
error: { _tag: "AnalysisOutputError" },
});
expect(calls).toBe(1);
});
});
+4 -4
View File
@@ -8,7 +8,7 @@ import { err, ok } from "../../domain/result.js";
import { AnalysisOutputError } from "../../domain/analysisErrorCore.js";
const referencesSchema = z.object({
reference_kinds_available: z.boolean().optional(),
reference_kinds_available: z.boolean(),
references: z.array(
z.object({
source_address: z.string(),
@@ -17,9 +17,9 @@ const referencesSchema = z.object({
kind: referenceKindSchema,
}),
),
unresolved_calls: z
.array(z.object({ address: z.string(), reason: z.string() }))
.default([]),
unresolved_calls: z.array(
z.object({ address: z.string(), reason: z.string() }),
),
});
/** Prefer typed static call references, preserving computed targets and targetless sites. */
export const readNativeCallRoutes = async (
@@ -67,6 +67,11 @@ const analysis: AnalysisOperationPort = {
address: callee ? "0x2000" : "0x1000",
name: callee ? "callee" : "caller",
classification: null,
body: {
available: false,
reason:
"The provider did not report complete function body ranges.",
},
signature: null,
locals: [],
},
@@ -7,6 +7,11 @@ const dossier = (text: string) =>
procedure: {
address: "0x1000",
name: "main",
classification: null,
body: {
available: false,
reason: "The fixture omits function-body extent observations.",
},
signature: "int main(void)",
locals: [],
},
@@ -20,6 +25,9 @@ const dossier = (text: string) =>
referenced_strings: [],
referenced_names: [],
basic_blocks: [{ start: "0x1000", end: "0x1001", successors: [] }],
native_api: null,
native_value_flow: null,
limitations: ["The fixture omits native API and value-flow observations."],
});
const observe = (digit: string, text: string) =>
+2 -2
View File
@@ -165,8 +165,8 @@ export const officialOutputSchemas: Readonly<Record<string, z.ZodObject>> = {
z.object({
procedure: procedureIdentitySchema,
direction: z.enum(["incoming", "outgoing"]),
reference_kinds_available: z.boolean().optional(),
unresolved_calls: z.array(unresolvedCallSchema).default([]),
reference_kinds_available: z.boolean(),
unresolved_calls: z.array(unresolvedCallSchema),
references: z.array(referenceEdgeSchema),
}),
),
+2 -5
View File
@@ -484,11 +484,8 @@ export const procedureInfoOutput = evidenceResultOf(
length: z.number().min(0),
signature: nullableText,
locals: z.array(localVariableSchema),
classification: procedureClassificationSchema.nullable().default(null),
body: functionBodySchema.default({
available: false,
reason: "The provider did not report complete function body ranges.",
}),
classification: procedureClassificationSchema.nullable(),
body: functionBodySchema,
}),
);
+15
View File
@@ -19,6 +19,12 @@ const observe = (
procedure: {
address,
name: `fn_${address.slice(2)}`,
classification: null,
body: {
available: false,
reason:
"Hopper's public Python API does not expose complete function body ranges",
},
signature: null,
locals: [],
},
@@ -29,12 +35,21 @@ const observe = (
callees: callees.map((callee) => ({
address: callee,
name: `fn_${callee.slice(2)}`,
classification: null,
body: {
available: false,
reason:
"Hopper's public Python API does not expose complete function body ranges",
},
})),
incoming_references: [],
outgoing_references: [],
referenced_strings: [],
referenced_names: [],
native_api: null,
native_value_flow: null,
basic_blocks: [],
limitations: [],
});
return createEvidence(
{ path: "/tmp/a", sha256: "a".repeat(64), format: "mach-o" },
+29 -22
View File
@@ -11,6 +11,16 @@ import { compareUnicodeCodePoints } from "./unicodeCodePointOrder.js";
import { jsonValueSchema } from "./jsonValue.js";
import { compareFunctions } from "./functionComparison.js";
const procedure = (address: string, name: string) => ({
address,
name,
classification: null,
body: {
available: false as const,
reason:
"Hopper's public Python API does not expose complete function body ranges",
},
});
const dossier = (
text: string,
base: "0x1000" | "0x2000",
@@ -18,8 +28,7 @@ const dossier = (
) =>
functionDossierSchema.parse({
procedure: {
address: base,
name: "main",
...procedure(base, "main"),
signature: "int main(void)",
locals: [],
},
@@ -32,6 +41,8 @@ const dossier = (
outgoing_references: [],
referenced_strings: [],
referenced_names: [],
native_api: null,
native_value_flow: null,
basic_blocks: [
{
start: base,
@@ -39,6 +50,7 @@ const dossier = (
successors,
},
],
limitations: [],
});
const dossierWithReference = (
@@ -52,8 +64,8 @@ const dossierWithReference = (
{
source_address: base,
target_address: target,
source_procedure: { address: base, name: "main" },
target_procedure: { address: target, name: "helper" },
source_procedure: procedure(base, "main"),
target_procedure: procedure(target, "helper"),
kind:
kind === "unavailable"
? { available: false, reason: "provider has no kind authority" }
@@ -111,7 +123,7 @@ describe("function comparison normalized identity", () => {
functionDossierSchema.parse({
...dossier("return 0;", base),
procedure: {
address: base,
...procedure(base, name),
name,
signature: "int helper(void)",
locals: [],
@@ -138,7 +150,7 @@ describe("function comparison normalized identity", () => {
functionDossierSchema.parse({
...dossier("return 0;", base),
procedure: {
address: base,
...procedure(base, name),
name,
signature: "int helper(void)",
locals: [],
@@ -161,7 +173,7 @@ describe("function comparison normalized identity", () => {
const calling = (base: "0x1000" | "0x2000") =>
functionDossierSchema.parse({
...dossier("return helper();", base),
callees: [{ address: base === "0x1000" ? "0x1010" : "0x2010", name }],
callees: [procedure(base === "0x1000" ? "0x1010" : "0x2010", name)],
});
const result = compareFunctions(
observe("6", calling("0x1000")),
@@ -174,11 +186,9 @@ describe("function comparison normalized identity", () => {
});
describe("function collection collation ties", () => {
const composed = { address: "0x2000", name: "caf\u00e9" };
const decomposed = { address: "0x3000", name: "cafe\u0301" };
const calling = (
callees: readonly { readonly address: string; readonly name: string }[],
) =>
const composed = procedure("0x2000", "caf\u00e9");
const decomposed = procedure("0x3000", "cafe\u0301");
const calling = (callees: readonly ReturnType<typeof procedure>[]) =>
functionDossierSchema.parse({
...dossier("return 0;", "0x1000"),
callees,
@@ -221,10 +231,7 @@ describe("function collection collation ties", () => {
it("uses canonical code-point ordering for collection digests", () => {
const callees = ["zeta", "Alpha", "alpha", "_helper", "beta"].map(
(name, index) => ({
address: `0x${(0x2000 + index).toString(16)}`,
name,
}),
(name, index) => procedure(`0x${(0x2000 + index).toString(16)}`, name),
);
const canonicalProjection = callees
.map(({ name }) => ({ direction: "out", name }))
@@ -247,8 +254,8 @@ describe("function collection collation ties", () => {
});
describe("function comparison ordering controls", () => {
const composed = { address: "0x2000", name: "caf\u00e9" };
const decomposed = { address: "0x3000", name: "cafe\u0301" };
const composed = procedure("0x2000", "caf\u00e9");
const decomposed = procedure("0x3000", "cafe\u0301");
it("preserves duplicate Unicode collections and nullable endpoints", () => {
const controlled = (base: "0x1000" | "0x2000", reverse: boolean) => {
@@ -258,7 +265,7 @@ describe("function comparison ordering controls", () => {
source_address: base,
target_address: endpoint,
source_procedure: null,
target_procedure: { address: endpoint, name: "caf\u00e9" },
target_procedure: procedure(endpoint, "caf\u00e9"),
kind: {
available: true,
provenance: "provider-reference-manager",
@@ -281,7 +288,7 @@ describe("function comparison ordering controls", () => {
{
source_address: base,
target_address: endpoint,
source_procedure: { address: base, name: "dispatch" },
source_procedure: procedure(base, "dispatch"),
target_procedure: null,
kind: {
available: true,
@@ -337,7 +344,7 @@ describe("function comparison ordering controls", () => {
);
const left = controlled("0x1000", false);
const right = controlled("0x2000", true);
const { native_api: _nativeApi, ...rightWithoutNativeApi } = right;
const rightWithoutNativeApi = { ...right, native_api: null };
const comparison = compareFunctions(
makeEvidence("d", left),
@@ -522,7 +529,7 @@ describe("function comparison", () => {
functionDossierSchema.parse({
...dossier("return 0;", base),
procedure: {
address: base,
...procedure(base, "sub_1000"),
name: "sub_1000",
signature: "int helper(void)",
locals: [],
+3
View File
@@ -184,6 +184,7 @@ export const ghidraFunctionDossier = (includeAssembly = true): JsonValue => {
sequence: 0,
opcode: "COPY",
is_dead: false,
block_membership: "member",
inputs: [
{
kind: "constant",
@@ -201,6 +202,8 @@ export const ghidraFunctionDossier = (includeAssembly = true): JsonValue => {
},
],
def_use: [],
parameters: [],
parameter_uses: [],
effects: [],
truncated: false,
omitted_operations_lower_bound: 0,
+24 -6
View File
@@ -96,13 +96,27 @@ describe("provider-neutral inclusive function body evidence", () => {
non_contiguous: true,
contains_entry: true,
});
it("represents missing Hopper extent explicitly as unknown", () => {
it("rejects missing provider body metadata", () => {
expect(
procedureIdentitySchema.parse({ address: "0x1000", name: "main" }).body,
).toEqual({
available: false,
reason: "The provider did not report complete function body ranges.",
});
procedureIdentitySchema.safeParse({ address: "0x1000", name: "main" })
.success,
).toBe(false);
});
it("rejects segments when required coordinates or unknown permissions are omitted", () => {
expect(
parseSegments([
{
name: "__TEXT",
start: "0x1",
end: "0x2",
readable: null,
writable: null,
},
]).ok,
).toBe(false);
expect(
parseSegments([{ name: "__TEXT", start: "0x1", end: "0x2" }]).ok,
).toBe(false);
});
it("counts inclusive one-byte ranges without assuming an enclosing continuous body", () => {
expect(
@@ -143,6 +157,7 @@ describe("provider-neutral inclusive function body evidence", () => {
procedureIdentitySchema.safeParse({
address: "0x1000",
name: "external",
classification: null,
body: {
...observed(),
ranges: [],
@@ -159,6 +174,7 @@ describe("provider-neutral inclusive function body evidence", () => {
procedureIdentitySchema.safeParse({
address: "0x1002",
name: "last",
classification: null,
body: observed(),
}).success,
).toBe(true);
@@ -166,6 +182,7 @@ describe("provider-neutral inclusive function body evidence", () => {
procedureIdentitySchema.safeParse({
address: "0x1003",
name: "gap",
classification: null,
body: observed(),
}).success,
).toBe(false);
@@ -173,6 +190,7 @@ describe("provider-neutral inclusive function body evidence", () => {
procedureIdentitySchema.safeParse({
address: "other:0x1000",
name: "other",
classification: null,
body: observed(),
}).success,
).toBe(false);
+11 -17
View File
@@ -52,12 +52,12 @@ const addressedNamesSchema = z.array(
);
const addressedNameMapSchema = z.record(z.string(), z.string());
const segmentSchema = z.object({
name: z.string().default(""),
start: z.string().default(""),
end: z.string().default(""),
readable: z.boolean().nullable().default(null),
writable: z.boolean().nullable().default(null),
executable: z.boolean().nullable().default(null),
name: z.string(),
start: z.string(),
end: z.string(),
readable: z.boolean().nullable(),
writable: z.boolean().nullable(),
executable: z.boolean().nullable(),
});
const unavailableAnalysisFactSchema = z
.object({ available: z.literal(false), reason: z.string() })
@@ -186,12 +186,6 @@ export const functionBodySchema = z.discriminatedUnion("available", [
}),
]);
const unknownFunctionBody = () =>
functionBodySchema.default({
available: false,
reason: "The provider did not report complete function body ranges.",
});
/** Check the declared entry membership against complete, inclusive body ranges. */
export const functionBodyEntryAgrees = (
body: z.infer<typeof functionBodySchema>,
@@ -226,8 +220,8 @@ export const procedureIdentitySchema = z
.object({
address: z.string(),
name: z.string(),
classification: procedureClassificationSchema.nullable().default(null),
body: unknownFunctionBody(),
classification: procedureClassificationSchema.nullable(),
body: functionBodySchema,
})
.strict()
.superRefine((identity, context) => {
@@ -352,9 +346,9 @@ export const functionDossierSchema = z
})
.strict(),
),
native_api: nativeApiBoundarySchema.nullable().default(null),
native_value_flow: nativeValueFlowSchema.nullable().default(null),
limitations: z.array(z.string()).default([]),
native_api: nativeApiBoundarySchema.nullable(),
native_value_flow: nativeValueFlowSchema.nullable(),
limitations: z.array(z.string()),
})
.strict();
+15 -21
View File
@@ -18,9 +18,7 @@ export const nativePcodeOperationSchema = z.strictObject({
sequence: z.number().int().nonnegative(),
opcode: z.string().min(1),
is_dead: z.boolean(),
block_membership: z
.enum(["member", "detached", "unavailable"])
.default("unavailable"),
block_membership: z.enum(["member", "detached", "unavailable"]),
inputs: z.array(nativeVarnodeSchema),
output: nativeVarnodeSchema.nullable(),
});
@@ -55,24 +53,20 @@ export const nativeValueFlowSchema = z.discriminatedUnion("available", [
operations: z.array(nativePcodeOperationSchema),
def_use: z.array(nativePcodeDefUseSchema),
effects: z.array(nativePcodeEffectSchema),
parameters: z
.array(
z.strictObject({
ordinal: z.number().int().nonnegative(),
name: z.string(),
data_type: z.string(),
}),
)
.default([]),
parameter_uses: z
.array(
z.strictObject({
ordinal: z.number().int().nonnegative(),
use: z.string(),
input_index: z.number().int().nonnegative(),
}),
)
.default([]),
parameters: z.array(
z.strictObject({
ordinal: z.number().int().nonnegative(),
name: z.string(),
data_type: z.string(),
}),
),
parameter_uses: z.array(
z.strictObject({
ordinal: z.number().int().nonnegative(),
use: z.string(),
input_index: z.number().int().nonnegative(),
}),
),
truncated: z.boolean(),
omitted_operations_lower_bound: z.number().int().nonnegative(),
known_omitted_inputs: z.number().int().nonnegative(),
@@ -24,6 +24,12 @@ const dossier = jsonValueSchema.parse(
procedure: {
address: "0x1000",
name: "main",
classification: null,
body: {
available: false,
reason:
"Hopper's public Python API does not expose complete function body ranges",
},
signature: "int main(void)",
locals: [],
},
@@ -36,7 +42,10 @@ const dossier = jsonValueSchema.parse(
outgoing_references: [],
referenced_strings: [],
referenced_names: [],
native_api: null,
native_value_flow: null,
basic_blocks: [{ start: "0x1000", end: "0x1001", successors: [] }],
limitations: [],
}),
);
+49
View File
@@ -1,6 +1,7 @@
import { describe, expect, it } from "vitest";
import type { JsonValue } from "../domain/jsonValue.js";
import { jsonValueSchema } from "../domain/jsonValue.js";
import { functionDossierSchema } from "../domain/hopperValues.js";
import {
parseGhidraFunctionResult,
@@ -37,6 +38,54 @@ describe("Ghidra function-analysis result values", () => {
},
);
it.each(["block_membership", "parameters", "parameter_uses"])(
"rejects a value-flow result missing %s",
(field) => {
const dossier = ghidraFunctionDossier();
if (
typeof dossier !== "object" ||
dossier === null ||
Array.isArray(dossier)
)
throw new TypeError("Ghidra dossier fixture is invalid");
const flow = dossier.native_value_flow;
if (typeof flow !== "object" || flow === null || Array.isArray(flow))
throw new TypeError("Ghidra p-code fixture is invalid");
if (!Array.isArray(flow.operations))
throw new TypeError("Ghidra operation fixture is invalid");
const incompleteFlow =
field === "block_membership"
? {
...flow,
operations: flow.operations.map((operation, index) =>
index !== 0 ||
typeof operation !== "object" ||
operation === null ||
Array.isArray(operation)
? operation
: Object.fromEntries(
Object.entries(operation).filter(
([key]) => key !== field,
),
),
),
}
: Object.fromEntries(
Object.entries(flow).filter(([key]) => key !== field),
);
expect(
parseGhidraFunctionResult(
"analyze_function",
jsonValueSchema.parse({
...dossier,
native_value_flow: incompleteFlow,
}),
),
).toMatchObject({ ok: false, error: { _tag: "AnalysisOutputError" } });
},
);
it("rejects p-code relationships that refer to omitted operation IDs", () => {
const dossier = ghidraFunctionDossier();
if (
+2
View File
@@ -426,6 +426,8 @@ export class IdaOperationRunner {
referenced_strings: [],
referenced_names: [],
basic_blocks: [],
native_api: null,
native_value_flow: null,
limitations: [
...IDA_LIMITATIONS,
...this.limitations,
+11
View File
@@ -95,6 +95,17 @@ describe("headless IDA producer pagination", () => {
const dossier = functionDossierSchema.parse(result.value.result);
expect(dossier.pseudocode).toBe("first line\nsecond line");
expect(dossier.assembly).toEqual(["0x1000: push rbp", "0x1001: ret"]);
expect(dossier).toMatchObject({
procedure: {
classification: null,
body: {
available: false,
reason: "IDA MCP does not report complete function body ranges.",
},
},
native_api: null,
native_value_flow: null,
});
await client.close();
});
});