feat(evidence)!: require firmware budgets and managed row resolution that producers always write (#11334)

The last fields kept optional "because historical Evidence may omit them"
after Phase 5 (#10510), checked against their producers:

- firmware `analysis_timeout_ms` (inspect_firmware_regions,
  extract_firmware): FirmwareProvider and FirmwarePublication always write
  it, and FirmwareAnalysisService already refused fresh results without it.
  Now required.
- managed call-edge and field-access `target_row_resolved`:
  ManagedMemberRows always writes a boolean. Now required; the comparison
  owner's `undefined` branch and the "historical omission" test are gone.
- Evidence `caller_input_path`: written only when a request selects a
  direct path, so it stays optional; the wording now says that.
- Ghidra `containing_instruction`: optional because other instruction
  statuses have no container; wording corrected.

BREAKING CHANGE: inspect_firmware_regions and extract_firmware results
require `analysis_timeout_ms`, and inspect_managed_members call edges and
field accesses require `target_row_resolved`. Evidence or analysis-view
input without them is refused. Every producer in this release writes them;
recreate observations made by a build that omitted them.
This commit is contained in:
morluto authored and GitHub committed 2026-11-16 03:42:04 +08:00
1 parent 4002bc2c23
commit 6bc74fbc40
9 files changed
+35 -35

No files matched your search

+3 -3
View File
@@ -496,9 +496,9 @@ TypeSpec owners and unresolved MethodSpec instantiations retain unknown target
equivalence. The exception is a target the left and right sides reach under the
same caller and target tokens of the same authenticated artifact, with both
producers reporting `target_row_resolved: true`: those parsed facts establish
the same metadata row without a nominal identity. Missing historical row
resolution, malformed or wrong-kind references, undecoded signatures and
unresolved TypeSpec operands stay unknown. This fact describes metadata
the same metadata row without a nominal identity. Malformed or wrong-kind
references, undecoded signatures and unresolved TypeSpec operands stay
unknown. This fact describes metadata
resolution, not runtime binding. Valid
MethodSpecs combine the base member identity with the resolved instantiation
signature, preserving generic argument distinctions.
@@ -30,7 +30,7 @@ const fixture = (
source_revision: null,
worker_count: 1,
};
const normalized = firmwareResultSchemas[operation].parse(
const facts =
operation === "inspect_firmware_regions"
? { engine, input_size: 1, regions: [], coverage: "signature_scan" }
: {
@@ -47,12 +47,14 @@ const fixture = (
extraction_gaps: [],
extraction_continuations: [],
published_bytes: 0,
},
);
};
const execution = createAnalysisExecution(
budget === null
? normalized
: { ...normalized, analysis_timeout_ms: budget },
? facts
: firmwareResultSchemas[operation].parse({
...facts,
analysis_timeout_ms: budget,
}),
{ id: "fixture", name: "Fixture firmware", version: "1" },
{
subject: {
@@ -224,10 +226,10 @@ for (const operation of [
},
);
it(`keeps historical ${operation} budget omissions unknown`, () => {
it(`refuses a ${operation} result without its analysis budget`, () => {
const { execution } = fixture(operation, null);
expect(
firmwareResultSchemas[operation].parse(execution.result),
).not.toHaveProperty("analysis_timeout_ms");
firmwareResultSchemas[operation].safeParse(execution.result).success,
).toBe(false);
});
}
@@ -278,6 +278,7 @@ it("filters relationship endpoints from recorded facts rather than caller displa
caller_token: "0x06000001",
il_offset: 0,
target_identity_sha256: null,
target_row_resolved: false,
caller: "Unrelated.Caller",
opcode: "call",
target_token: "0x0a000001",
@@ -289,6 +290,7 @@ it("filters relationship endpoints from recorded facts rather than caller displa
caller_token: "0x06000002",
il_offset: 0,
target_identity_sha256: null,
target_row_resolved: false,
caller: "Exact.Type.Target",
opcode: "call",
target_token: "0x0a000002",
@@ -302,6 +304,7 @@ it("filters relationship endpoints from recorded facts rather than caller displa
method_token: "0x06000001",
il_offset: 0,
target_identity_sha256: null,
target_row_resolved: false,
method: "Unrelated.Caller",
opcode: "ldfld",
field_token: "0x04000001",
@@ -312,6 +315,7 @@ it("filters relationship endpoints from recorded facts rather than caller displa
method_token: "0x06000002",
il_offset: 0,
target_identity_sha256: null,
target_row_resolved: false,
method: "Exact.Type.Target",
opcode: "ldfld",
field_token: "0x04000002",
+1 -1
View File
@@ -105,7 +105,7 @@ const evidenceBaseSchema = z
predicate_type: z.string().min(1),
operation: z.string().min(1),
parameters: jsonObjectSchema,
/** Verbatim selected path for a direct request; absent on older records. */
/** Verbatim selected path; present only when the request selected one directly. */
caller_input_path: nulFreeStringSchema
.exactOptional()
.describe("Verbatim direct-request path; not part of semantic identity."),
+4 -6
View File
@@ -96,13 +96,11 @@ const engine = z.strictObject({
source_revision: z.null(),
worker_count: z.literal(1),
});
/** Small execution metadata contract; historical omissions remain unknown. */
/** Execution metadata every firmware result carries. */
export const firmwareExecutionBudgetSchema = z.object({
analysis_timeout_ms: timerDurationMsSchema
.exactOptional()
.describe(
"Actual analysis phase budget in milliseconds; absent in historical Evidence means unknown",
),
analysis_timeout_ms: timerDurationMsSchema.describe(
"Actual analysis phase budget in milliseconds",
),
});
const selection = z.strictObject({ ...range.shape, sha256: digestSchema });
const chunk = z.strictObject({
+1 -2
View File
@@ -384,9 +384,8 @@ const managedNativeImplementationSchema = z.object({
const targetRowResolvedSchema = z
.boolean()
.exactOptional()
.describe(
"True when the producer resolved the operand to a matching member row with a decoded signature and owner; false means unresolved. Omitted by historical observations. Does not establish runtime binding.",
"True when the producer resolved the operand to a matching member row with a decoded signature and owner; false means unresolved. Does not establish runtime binding.",
);
const managedCallEdgeSchema = z.object({
@@ -280,7 +280,7 @@ const sameAssemblyIdentity = (
left.public_key.token === right.public_key.token;
interface ReferenceTarget {
readonly rowResolved: boolean | undefined;
readonly rowResolved: boolean;
readonly offset: number | null;
readonly opcode: string;
readonly token: string;
+9 -12
View File
@@ -821,19 +821,16 @@ describe("comparison of edges to a TypeSpec-owned member", () => {
},
);
it("keeps historical target-row resolution unknown", () => {
it("refuses an edge that omits its target-row resolution", () => {
const inspection = typeSpecMember(0x0a00_0001);
const historical = {
...inspection,
call_edges: inspection.call_edges.map(
({ target_row_resolved: _omitted, ...edge }) => edge,
),
};
const comparison = compareManagedMembers(
{ evidenceId: `ev_${"a".repeat(64)}`, result: historical },
{ evidenceId: `ev_${"b".repeat(64)}`, result: historical },
);
expect(comparison.methods[0]?.status).toBe("unknown");
expect(
managedMemberInspectionSchema.safeParse({
...inspection,
call_edges: inspection.call_edges.map(
({ target_row_resolved: _omitted, ...edge }) => edge,
),
}).success,
).toBe(false);
});
it("compares a proven TypeSpec field row through the same owner", () => {
+2 -2
View File
@@ -281,8 +281,8 @@ const ghidraFunctionInstructionWindow = functionInstructionWindowSchema
.extend({ procedure: procedureIdentity })
.strict();
// Current Ghidra profiles commit to emitting containment exactly for an interior
// listing address. The shared Evidence schema remains optional for older records.
// Ghidra emits containment exactly for an interior listing address. The shared
// schema keeps it optional: other statuses have no container.
const ghidraInstruction = nativeInstructionSchema.superRefine(
(value, context) => {
if (