Files
reverse-engineering-anything/src/domain/native/nativeValueTrace.ts
T
Abhishek Sharmaandgensokyo-dev 8578daf8b7 fix(native): report an unexamined thunk target in value traces
trace_native_values ended at a provider-classified thunk whose model
holds only a synthetic return (an external import) or borrows its
target's operations, without saying the target was never examined, so
a stub's small model read as the end of the call chain. Thunk targets
are now reconciled after traversal: one another path traced, attempted
or queued is left to that path, and the rest are reported in unknowns
with the target in a new optional related_procedure field.

Fixes #8476
Supersedes #8678

Based on #8678 and rebased onto main's separate call-binding module.
related_procedure is exactOptional and set only on the thunk unknown,
so other unknowns and retained traces keep their shape.

Co-Authored-By: gensokyo-dev <342580529+gensokyo-dev@users.noreply.github.com>
2026-11-14 15:32:34 +01:00

136 lines
4.7 KiB
TypeScript

import { z } from "zod";
import { nativePcodeOperationSchema } from "./nativeValueFlow.js";
/** Work and output budgets for a static procedure-seeded dependency graph. */
export const nativeValueTraceInputSchema = z.strictObject({
procedure: z.string().min(1),
max_depth: z.int().min(0).max(16).default(3),
max_functions: z.int().min(1).max(64).default(16),
max_call_sites: z.int().min(1).max(4096).default(256),
max_nodes: z.int().min(1).max(20_000).default(5_000),
max_edges: z.int().min(1).max(40_000).default(10_000),
offset: z.int().min(0).default(0),
limit: z.int().min(1).max(5_000).default(1_000),
});
/**
* Observed causes of a narrowed traversal. Budget codes name the input field a
* caller can raise; the remaining codes are fixed or provider-owned limits.
* `cleanup_incomplete` appears only in the partial trace a `cleanup_incomplete`
* failure retains, because unconfirmed provider cleanup stops the trace.
*/
export const nativeValueTraceTruncationReasonSchema = z.enum([
"max_depth",
"max_functions",
"max_call_sites",
"max_nodes",
"max_edges",
"node_payload_bytes",
"provider_pcode_truncated",
"ambiguous_call_candidates",
"cleanup_incomplete",
]);
export type NativeValueTraceTruncationReason = z.output<
typeof nativeValueTraceTruncationReasonSchema
>;
/** Traversal completeness under the requested budgets, independent of paging. */
const nativeValueTraceTraversalSchema = z
.discriminatedUnion("status", [
z.strictObject({ status: z.literal("complete") }),
z.strictObject({
status: z.literal("truncated"),
reasons: z.array(nativeValueTraceTruncationReasonSchema).min(1),
}),
])
.describe(
"complete: no trace budget, fixed node-payload allowance, provider p-code limit, ambiguous-candidate policy or unconfirmed provider cleanup stopped or narrowed the traversal; failed analyses and unresolved calls remain in unknowns. truncated: reasons lists each observed cause in schema order.",
);
/** Def-use observations and call relationships retain separate authority. */
export const nativeValueTraceSchema = z.strictObject({
seed: z.string(),
target_sha256: z.string(),
nodes: z.array(
z.strictObject({
id: z.string(),
procedure: z.string(),
evidence_id: z.string(),
kind: z.enum(["operation", "parameter"]),
operation: nativePcodeOperationSchema.nullable(),
parameter: z
.strictObject({
ordinal: z.int().nonnegative(),
name: z.string(),
data_type: z.string(),
})
.nullable(),
}),
),
edges: z.array(
z.strictObject({
source: z.string(),
target: z.string(),
input_index: z.int().nonnegative().nullable(),
kind: z.enum([
"def-use",
"call",
"parameter-use",
"argument-binding",
"return-binding",
]),
status: z.enum(["derived", "direct", "resolved-indirect", "candidate"]),
evidence_id: z.string(),
}),
),
procedures: z.array(
z.strictObject({
address: z.string(),
depth: z.int().nonnegative(),
evidence_id: z.string(),
provider: z.string(),
analysis_profile_digest: z.string().nullable(),
}),
),
unknowns: z.array(
z.strictObject({
procedure: z.string(),
address: z.string().nullable(),
reason: z.string(),
related_procedure: z
.string()
.exactOptional()
.describe(
"The procedure this unknown names, such as a thunk target the trace did not examine. Omitted for other unknowns and in historical traces.",
),
call_inputs: z
.strictObject({
call_node_id: z.string(),
destination: z.string(),
evidence_id: z.string(),
input_indices: z.array(z.int().positive()).min(1),
})
.exactOptional()
.describe(
"Recovered CALL input positions with no recovered parameter binding after complete callee parameter examination. Index 0 is the call destination and is excluded. This does not establish formal parameters or a variadic signature. Omitted in historical traces and other unknowns.",
),
}),
),
total_nodes: z.int().nonnegative(),
total_edges: z.int().nonnegative(),
decompilations: z.int().nonnegative(),
next_offset: z.int().nonnegative().nullable(),
page_truncated: z
.boolean()
.describe(
"This page omits retained nodes, and the edges they source, before offset or after next_offset.",
),
traversal: nativeValueTraceTraversalSchema,
truncated: z
.boolean()
.describe(
"page_truncated or a truncated traversal. Read those fields to distinguish page omission from traversal truncation.",
),
limitations: z.array(z.string()),
});