rea-agents 3.1.0 → 3.2.0

package/dist/domain/nativeInvestigationGraph.js

@@ -0,0 +1,351 @@
+import { z } from "zod";
+import { nativeMetadataEvidenceSchema, nativeMetadataLocationSchema, } from "./objcSwiftMetadata.js";
+import { jsonValueSchema } from "./jsonValue.js";
+/** Entity kinds shared by decoded Interface Builder archives and native code. */
+export const nativeInvestigationNodeKindSchema = z.enum([
+    "storyboard",
+    "scene",
+    "view_controller",
+    "view",
+    "control",
+    "constraint",
+    "layout_guide",
+    "resource",
+    "placeholder",
+    "external_object",
+    "outlet",
+    "action",
+    "segue",
+    "objc_class",
+    "objc_selector",
+    "swift_declaration",
+    "swift_requirement",
+    "dispatch_table",
+    "dispatch_slot",
+    "thunk",
+    "function",
+    "state_value",
+    "global_value",
+    "field",
+    "branch_condition",
+    "sink",
+    "unknown",
+]);
+/** One UI, dispatch, or value entity with optional decoded source location. */
+export const nativeInvestigationNodeSchema = z.strictObject({
+    id: z.string().min(1),
+    kind: nativeInvestigationNodeKindSchema,
+    name: z.string().min(1),
+    location: nativeMetadataLocationSchema.nullable(),
+    attributes: z.record(z.string(), jsonValueSchema),
+    evidence: z.array(nativeMetadataEvidenceSchema),
+});
+/** Relationship types preserve UI wiring, native dispatch, and value flow. */
+export const nativeInvestigationRelationSchema = z.enum([
+    "contains",
+    "outlet_to",
+    "target_action",
+    "segue_to",
+    "objc_dispatch",
+    "swift_witness_dispatch",
+    "swift_vtable_dispatch",
+    "thunk_to",
+    "direct_call",
+    "reads",
+    "writes",
+    "flows_to",
+    "controls",
+]);
+/** An observed, inferred, or unresolved relationship between entities. */
+export const nativeInvestigationEdgeSchema = z.discriminatedUnion("resolution", [
+    z.strictObject({
+        id: z.string().min(1),
+        from: z.string().min(1),
+        to: z.string().min(1),
+        relation: nativeInvestigationRelationSchema,
+        resolution: z.enum(["observed", "inferred"]),
+        evidence: z.array(nativeMetadataEvidenceSchema).min(1),
+        limitations: z.array(z.string()),
+    }),
+    z.strictObject({
+        id: z.string().min(1),
+        from: z.string().min(1),
+        to: z.null(),
+        relation: nativeInvestigationRelationSchema,
+        resolution: z.literal("unresolved"),
+        reason: z.string().min(1),
+        evidence: z.array(nativeMetadataEvidenceSchema),
+        limitations: z.array(z.string()),
+    }),
+]);
+/** Explicit inventory coverage so missing graph parts are not read as absent. */
+export const nativeInvestigationCoverageSchema = z.strictObject({
+    facet: z.string().min(1),
+    status: z.enum(["complete", "partial", "unsupported", "not_requested"]),
+    reason: z.string().nullable(),
+    examined: z.number().int().nonnegative(),
+    omitted: z.number().int().nonnegative(),
+});
+/** Complete provider-neutral graph bound to one immutable target identity. */
+export const nativeInvestigationGraphSchema = z.strictObject({
+    target_sha256: z.string().regex(/^[a-f0-9]{64}$/u),
+    provider: z.strictObject({
+        id: z.string().min(1),
+        version: z.string().nullable(),
+        tool_version: z.string().min(1),
+    }),
+    nodes: z.array(nativeInvestigationNodeSchema),
+    edges: z.array(nativeInvestigationEdgeSchema),
+    coverage: z.array(nativeInvestigationCoverageSchema),
+    truncated: z.boolean(),
+});
+/** Caller-controlled hard limits for a bounded relationship trace. */
+export const nativeInvestigationTraceLimitsSchema = z.strictObject({
+    max_depth: z.number().int().min(0).max(32).default(8),
+    max_nodes: z.number().int().min(1).max(2000).default(250),
+    max_edges: z.number().int().min(1).max(5000).default(500),
+});
+/** Exact graph route and any unresolved edges encountered along the route. */
+export const nativeInvestigationTraceSchema = z.strictObject({
+    target_sha256: z.string().regex(/^[a-f0-9]{64}$/u),
+    provider: nativeInvestigationGraphSchema.shape.provider,
+    start: z.string().min(1),
+    direction: z.enum(["forward", "backward"]),
+    nodes: z.array(nativeInvestigationNodeSchema),
+    edges: z.array(nativeInvestigationEdgeSchema),
+    unresolved: z.array(nativeInvestigationEdgeSchema),
+    reached_depth: z.number().int().nonnegative(),
+    truncated: z.boolean(),
+    reason: z.string().nullable(),
+    coverage: z.array(nativeInvestigationCoverageSchema),
+    limitations: z.array(z.string().min(1)),
+});
+/** Trace known relationships while retaining unknown indirect dispatch edges. */
+export const traceNativeInvestigationGraph = (graph, input) => {
+    const start = graph.nodes.find(({ id }) => id === input.start);
+    if (start === undefined)
+        return {
+            target_sha256: graph.target_sha256,
+            provider: graph.provider,
+            start: input.start,
+            direction: input.direction ?? "forward",
+            nodes: [],
+            edges: [],
+            unresolved: [],
+            reached_depth: 0,
+            truncated: false,
+            reason: "start_node_missing",
+            coverage: graph.coverage,
+            limitations: [
+                "The requested start node is absent from the supplied graph.",
+            ],
+        };
+    const limits = nativeInvestigationTraceLimitsSchema.parse(input.limits ?? {});
+    const direction = input.direction ?? "forward";
+    const nodeById = new Map(graph.nodes.map((node) => [node.id, node]));
+    const visited = new Set([start.id]);
+    const selectedEdges = new Map();
+    const unresolved = new Map();
+    const queue = [
+        { id: start.id, depth: 0 },
+    ];
+    let reachedDepth = 0;
+    let truncated = false;
+    let reason = null;
+    while (queue.length > 0) {
+        const current = queue.shift();
+        if (current === undefined)
+            break;
+        reachedDepth = Math.max(reachedDepth, current.depth);
+        const adjacent = graph.edges.filter((edge) => direction === "forward"
+            ? edge.from === current.id
+            : edge.to === current.id);
+        for (const edge of adjacent) {
+            if (selectedEdges.size + unresolved.size >= limits.max_edges) {
+                truncated = true;
+                reason = "max_edges_reached";
+                break;
+            }
+            if (edge.resolution === "unresolved") {
+                unresolved.set(edge.id, edge);
+                continue;
+            }
+            const nextId = direction === "forward" ? edge.to : edge.from;
+            const alreadyVisited = visited.has(nextId);
+            if (!alreadyVisited && current.depth >= limits.max_depth) {
+                truncated = true;
+                reason ??= "max_depth_reached";
+                continue;
+            }
+            selectedEdges.set(edge.id, edge);
+            if (alreadyVisited)
+                continue;
+            if (visited.size >= limits.max_nodes) {
+                truncated = true;
+                reason = "max_nodes_reached";
+                break;
+            }
+            if (!nodeById.has(nextId)) {
+                truncated = true;
+                reason ??= "edge_target_missing_from_graph";
+                continue;
+            }
+            visited.add(nextId);
+            queue.push({ id: nextId, depth: current.depth + 1 });
+        }
+        if (reason === "max_edges_reached" || reason === "max_nodes_reached")
+            break;
+    }
+    return {
+        target_sha256: graph.target_sha256,
+        provider: graph.provider,
+        start: start.id,
+        direction,
+        nodes: [...visited].flatMap((id) => {
+            const node = nodeById.get(id);
+            return node === undefined ? [] : [node];
+        }),
+        edges: [...selectedEdges.values()],
+        unresolved: [...unresolved.values()],
+        reached_depth: reachedDepth,
+        truncated,
+        reason,
+        coverage: graph.coverage,
+        limitations: [
+            "Static analysis does not prove that an authored UI action is reachable or executed at runtime.",
+            "Provider call graphs may omit unresolved indirect dispatch.",
+        ],
+    };
+};
+/** Join authored UI actions to exact Objective-C method symbols when known. */
+export const joinInterfaceBuilderDispatch = (graph, metadata) => {
+    const nodes = new Map(graph.nodes.map((node) => [node.id, node]));
+    const edges = [...graph.edges];
+    const existingEdgeIds = new Set(edges.map(({ id }) => id));
+    const selectorNodesByAction = new Map();
+    for (const edge of edges) {
+        if (edge.resolution === "observed" &&
+            edge.relation === "target_action" &&
+            nodes.get(edge.to)?.kind === "objc_selector")
+            selectorNodesByAction.set(edge.from, edge.to);
+    }
+    let examined = 0;
+    let resolved = 0;
+    let inferredWithoutOwnerClass = 0;
+    for (const action of nodes.values()) {
+        if (action.kind !== "action")
+            continue;
+        const selector = action.attributes.selector;
+        if (typeof selector !== "string" || selector.length === 0)
+            continue;
+        const selectorNodeId = selectorNodesByAction.get(action.id);
+        if (selectorNodeId === undefined)
+            continue;
+        const destinationEdge = edges.find((edge) => edge.resolution === "observed" &&
+            edge.relation === "target_action" &&
+            edge.from === action.id &&
+            ["view_controller", "placeholder", "external_object"].includes(nodes.get(edge.to)?.kind ?? ""));
+        if (destinationEdge === undefined ||
+            destinationEdge.resolution !== "observed")
+            continue;
+        const owner = nodes.get(destinationEdge.to);
+        examined += 1;
+        const declaredClass = owner?.attributes.class_name;
+        const className = typeof declaredClass === "string" &&
+            declaredClass.length > 0 &&
+            owner?.kind === "view_controller"
+            ? declaredClass
+            : null;
+        const candidates = metadata.objc_dispatch_implementations.filter((candidate) => candidate.method_type === "instance" &&
+            candidate.selector === selector &&
+            (className === null ||
+                candidate.class_name.replace(/\([^)]*\)$/u, "") === className));
+        const implementation = candidates.length === 1 ? candidates[0] : undefined;
+        const edgeId = `dispatch:${selectorNodeId}:${className ?? owner?.id ?? "unknown"}:${selector}`;
+        if (existingEdgeIds.has(edgeId))
+            continue;
+        existingEdgeIds.add(edgeId);
+        if (implementation === undefined ||
+            implementation.implementation_address === null) {
+            edges.push({
+                id: edgeId,
+                from: selectorNodeId,
+                to: null,
+                relation: "objc_dispatch",
+                resolution: "unresolved",
+                reason: candidates.length > 1
+                    ? "selector_has_multiple_candidate_implementations"
+                    : "implementation_not_resolved_from_provider_symbols",
+                evidence: [
+                    ...action.evidence,
+                    ...candidates.flatMap(({ evidence }) => evidence),
+                ],
+                limitations: [
+                    "A missing or ambiguous symbol match does not prove that the runtime implementation is absent.",
+                ],
+            });
+            continue;
+        }
+        const functionId = `native:function:${implementation.implementation_address}`;
+        if (!nodes.has(functionId))
+            nodes.set(functionId, {
+                id: functionId,
+                kind: "function",
+                name: `${implementation.class_name} ${selector}`,
+                location: {
+                    address: implementation.implementation_address,
+                    file_offset: implementation.location.file_offset,
+                },
+                attributes: {
+                    class_name: implementation.class_name,
+                    selector,
+                    method_type: implementation.method_type,
+                },
+                evidence: implementation.evidence,
+            });
+        edges.push({
+            id: edgeId,
+            from: selectorNodeId,
+            to: functionId,
+            relation: "objc_dispatch",
+            resolution: "inferred",
+            evidence: [...action.evidence, ...implementation.evidence],
+            limitations: className === null
+                ? [
+                    "The selector uniquely matches a symbolized method, but the Interface Builder receiver is an unresolved placeholder; runtime dispatch was not observed.",
+                ]
+                : [
+                    "The Interface Builder target and symbolized method agree on class and selector; runtime dispatch and dynamically supplied targets were not observed.",
+                ],
+        });
+        resolved += 1;
+        if (className === null)
+            inferredWithoutOwnerClass += 1;
+    }
+    return nativeInvestigationGraphSchema.parse({
+        ...graph,
+        provider: {
+            id: "rea-native-investigation",
+            version: null,
+            tool_version: "rea-native-investigation/1",
+        },
+        nodes: [...nodes.values()],
+        edges,
+        coverage: [
+            ...graph.coverage,
+            {
+                facet: "ui_to_objc_dispatch",
+                status: examined === resolved && inferredWithoutOwnerClass === 0
+                    ? "complete"
+                    : "partial",
+                reason: examined === resolved && inferredWithoutOwnerClass === 0
+                    ? null
+                    : inferredWithoutOwnerClass > 0
+                        ? "some_action_receivers_remain_placeholders"
+                        : "some_action_implementations_not_resolved",
+                examined,
+                omitted: examined - resolved + inferredWithoutOwnerClass,
+            },
+        ],
+    });
+};

package/dist/domain/nativeValueFlow.js

@@ -0,0 +1,61 @@
+import { z } from "zod";
+/** A decompiler p-code varnode location or literal value. */
+export const nativeVarnodeSchema = z.strictObject({
+    kind: z.enum(["constant", "address", "register", "unique", "other"]),
+    size_bytes: z.number().int().nonnegative(),
+    location: z.string().nullable(),
+    constant_hex: z
+        .string()
+        .regex(/^[0-9a-f]+$/u)
+        .nullable(),
+});
+/** One high-p-code operation recovered for a single function. */
+export const nativePcodeOperationSchema = z.strictObject({
+    id: z.string().min(1),
+    address: z.string().min(1),
+    sequence: z.number().int().nonnegative(),
+    opcode: z.string().min(1),
+    is_dead: z.boolean(),
+    inputs: z.array(nativeVarnodeSchema),
+    output: nativeVarnodeSchema.nullable(),
+});
+/** A def-use relation between operations in one recovered HighFunction. */
+export const nativePcodeDefUseSchema = z.strictObject({
+    definition: z.string().min(1),
+    use: z.string().min(1),
+    input_index: z.number().int().nonnegative(),
+});
+/** Memory and branch operations as directly named by Ghidra p-code. */
+export const nativePcodeEffectSchema = z.strictObject({
+    operation: z.string().min(1),
+    kind: z.enum([
+        "memory_read",
+        "memory_write",
+        "conditional_branch",
+        "indirect_branch",
+        "direct_call",
+        "indirect_call",
+    ]),
+    operand_input: z.number().int().nonnegative().nullable(),
+    value_input: z.number().int().nonnegative().nullable(),
+});
+/** Bounded data-flow observations; STORE is not necessarily a persistent/global write. */
+export const nativeValueFlowSchema = z.discriminatedUnion("available", [
+    z.strictObject({
+        available: z.literal(true),
+        provenance: z.literal("ghidra-high-pcode"),
+        operations: z.array(nativePcodeOperationSchema),
+        def_use: z.array(nativePcodeDefUseSchema),
+        effects: z.array(nativePcodeEffectSchema),
+        truncated: z.boolean(),
+        omitted_operations_lower_bound: z.number().int().nonnegative(),
+        known_omitted_inputs: z.number().int().nonnegative(),
+        known_omitted_edges: z.number().int().nonnegative(),
+        limitations: z.array(z.string().min(1)),
+    }),
+    z.strictObject({
+        available: z.literal(false),
+        reason: z.string().min(1),
+        limitations: z.array(z.string().min(1)),
+    }),
+]);

package/dist/domain/nodeRuntimeCharacterization.js

@@ -13,8 +13,7 @@ const nodeRuntimeCharacterizationPlanSchema = runtimeCharacterizationPlanSchema.
 });
 export const nodeCharacterizationPreparationInputSchema = z
     .strictObject({
-    preparation_approved: z.literal(true),
-    selected_alias: z.string().min(1).max(200),
+    selected_alias: z.string().min(1),
     expected_effect: nodeCharacterizationExpectedEffectSchema,
     instrumentation: javascriptExportInstrumentationInputSchema,
     replay: controlledReplayPlanInputSchema,
@@ -44,12 +43,10 @@ export const nodeCharacterizationPreparationInputSchema = z
         });
 });
 export const nodeCharacterizationExecutionInputSchema = z.strictObject({
-    execution_approved: z.literal(true),
     approved_plan_sha256: digestSchema,
     preparation: nodeCharacterizationPreparationInputSchema,
 });
 export const nodeCharacterizationPreparationOutputSchema = z.strictObject({
-    schema_version: z.literal(1),
     phase: z.literal("preparation"),
     plan: nodeRuntimeCharacterizationPlanSchema,
     transformation: javascriptExportTransformationManifestSchema,
@@ -57,7 +54,6 @@ export const nodeCharacterizationPreparationOutputSchema = z.strictObject({
     replay: controlledReplayPlanOutputSchema,
 });
 export const nodeCharacterizationExecutionOutputSchema = z.strictObject({
-    schema_version: z.literal(1),
     phase: z.literal("execution"),
     plan: nodeRuntimeCharacterizationPlanSchema,
     transformation: javascriptExportTransformationManifestSchema,