rea-agents 6.5.0 → 6.7.0

package/dist/kuna/KunaReferenceFiles.js

@@ -0,0 +1,258 @@
+import { createHash } from "node:crypto";
+import { z } from "zod";
+import { err, ok } from "../domain/result.js";
+import { compareKunaAddresses } from "./KunaAddress.js";
+import { parseKunaJson } from "./KunaJson.js";
+import { KunaJsonDocumentReader, parseKunaRow } from "./KunaJsonStream.js";
+/** The raw xref budget also bounds its materialized rows. */
+export const KUNA_XREF_OUTPUT_BYTES = 16 * 1024 * 1024;
+const addressKeys = new Set(["address", "from_address", "to_address"]);
+const address = z.string().regex(/^0x(?:0|[1-9a-f][0-9a-f]{0,15})$/u);
+const count = z.number().int().min(0).max(Number.MAX_SAFE_INTEGER);
+const kind = z.enum(["call", "jump", "data", "read", "write"]);
+const graphHeader = z.object({
+    schemaVersion: z.literal(4),
+    binary: z.object({
+        sourcePath: z.string(),
+        functionCount: count,
+        edgeCount: count,
+    }),
+});
+const graphNode = z.object({
+    address,
+    name: z.string().min(1),
+    kind: z.string().min(1),
+    hasIndirectCalls: z.boolean(),
+    forwardsTo: address.nullable(),
+    codeC: z.null(),
+    assembly: z.null(),
+    error: z.null(),
+});
+const graphEdge = z.object({
+    callerAddress: address,
+    calleeAddress: address,
+    kind,
+    calleeOrder: count,
+});
+const fieldsOf = (schema, excluded) => new Set(Object.keys(schema.shape).filter((key) => !excluded.includes(key)));
+const GRAPH_DOCUMENT = {
+    header: new Set(["schemaVersion"]),
+    sections: new Map([
+        ["binary", new Set(Object.keys(graphHeader.shape.binary.shape))],
+    ]),
+    rows: new Map([
+        [
+            "functions",
+            {
+                fields: fieldsOf(graphNode, [
+                    "address",
+                    "forwardsTo",
+                    "codeC",
+                    "assembly",
+                    "error",
+                ]),
+                addresses: new Set(["address", "forwardsTo"]),
+                empty: new Set(),
+                // `--functions ''` requests no bodies; one is refused unassembled.
+                nulls: new Set(["codeC", "assembly", "error"]),
+            },
+        ],
+        [
+            "edges",
+            {
+                fields: fieldsOf(graphEdge, ["callerAddress", "calleeAddress"]),
+                addresses: new Set(["callerAddress", "calleeAddress"]),
+                empty: new Set(),
+                nulls: new Set(),
+            },
+        ],
+    ]),
+};
+/**
+ * Validates `kuna decompile-graph --functions ''` as Kuna writes it and
+ * retains only the facts call queries use.
+ */
+export class KunaCallGraphReader extends KunaJsonDocumentReader {
+    #nodes = new Map();
+    /** Callees of every edge by caller, which also detects repeated edges. */
+    #targets = new Map();
+    /** Callee orders by caller; each caller's must be 0..n-1. */
+    #orders = new Map();
+    #callers = new Map();
+    #callees = new Map();
+    #edgeCount = 0;
+    #hasIndirectCalls = false;
+    constructor() {
+        super("kuna:call-graph", "Kuna's call graph", GRAPH_DOCUMENT);
+    }
+    finish(input) {
+        const completed = this.complete();
+        if (!completed.ok)
+            return completed;
+        const header = graphHeader.safeParse(completed.value.header);
+        if (!header.success)
+            return err(this.unusable("the graph header is not Kuna's schema 4"));
+        if (header.data.binary.sourcePath !== input)
+            return err(this.unusable("graph names a different input"));
+        if (header.data.binary.functionCount !== this.#nodes.size ||
+            header.data.binary.edgeCount !== this.#edgeCount)
+            return err(this.unusable("graph counts disagree with examined rows"));
+        const invalid = this.#invalidEdges();
+        // These indexes only validate edges; queries never read them.
+        this.#targets.clear();
+        this.#orders.clear();
+        if (invalid !== undefined)
+            return err(this.unusable(invalid));
+        for (const index of [this.#callers, this.#callees])
+            for (const list of index.values())
+                list.sort(compareKunaAddresses);
+        return ok({
+            nodes: this.#nodes,
+            callers: this.#callers,
+            callees: this.#callees,
+            edgeCount: this.#edgeCount,
+            hasIndirectCalls: this.#hasIndirectCalls,
+            bytes: completed.value.bytes,
+            sha256: completed.value.sha256,
+        });
+    }
+    acceptRow(member, fields) {
+        if (member === "edges") {
+            this.#index(parseKunaRow(graphEdge, "graph edge", fields));
+            return;
+        }
+        const node = parseKunaRow(graphNode, "graph function", fields);
+        if (this.#nodes.has(node.address))
+            throw new Error("graph repeats a function address");
+        this.#nodes.set(node.address, node);
+        this.#hasIndirectCalls ||= node.hasIndirectCalls;
+    }
+    discardRows() {
+        for (const index of [
+            this.#nodes,
+            this.#targets,
+            this.#orders,
+            this.#callers,
+            this.#callees,
+        ])
+            index.clear();
+    }
+    /**
+     * Index one edge as it arrives, so the working set grows under the row
+     * admission instead of after it; endpoints are checked once every node is
+     * known.
+     */
+    #index(edge) {
+        const { callerAddress: caller, calleeAddress: callee } = edge;
+        this.#edgeCount += 1;
+        const targets = this.#targets.get(caller) ?? new Set();
+        if (targets.has(callee))
+            throw new Error("graph repeats an edge");
+        targets.add(callee);
+        this.#targets.set(caller, targets);
+        const order = this.#orders.get(caller) ?? new Set();
+        if (order.has(edge.calleeOrder))
+            throw new Error("graph repeats a callee order");
+        order.add(edge.calleeOrder);
+        this.#orders.set(caller, order);
+        if (edge.kind !== "call")
+            return;
+        const incoming = this.#callers.get(callee) ?? [];
+        incoming.push(caller);
+        this.#callers.set(callee, incoming);
+        const outgoing = this.#callees.get(caller) ?? [];
+        outgoing.push(callee);
+        this.#callees.set(caller, outgoing);
+    }
+    /** Why the edges contradict the nodes, if they do. */
+    #invalidEdges() {
+        for (const [caller, targets] of this.#targets) {
+            if (!this.#nodes.has(caller))
+                return "graph edge has an unknown endpoint";
+            for (const callee of targets)
+                if (!this.#nodes.has(callee))
+                    return "graph edge has an unknown endpoint";
+        }
+        for (const order of this.#orders.values())
+            for (let index = 0; index < order.size; index += 1)
+                if (!order.has(index))
+                    return "graph callee orders are incomplete";
+        return undefined;
+    }
+}
+const xrefFunction = z.object({
+    name: z.string().min(1),
+    address,
+    address_hex: address,
+});
+const xrefRow = z.object({
+    address,
+    address_hex: address,
+    kind,
+    from_address: address,
+    from_address_hex: address,
+    to_address: address,
+    to_address_hex: address,
+    from_function: xrefFunction.nullable(),
+    to_function: xrefFunction.nullable(),
+    instruction: z.string(),
+});
+const xrefsDocument = z.object({
+    binary: z.string(),
+    direction: z.literal("to"),
+    count,
+    target: z.object({
+        address,
+        address_hex: address,
+        name: z.string().nullable(),
+        aliases: z.array(xrefFunction),
+    }),
+    xrefs: z.array(z.unknown()),
+});
+/** Native --to unifies forwarding aliases; REA xrefs asks for the exact address. */
+export const parseKunaIncomingReferences = (text, input, target) => {
+    try {
+        const document = xrefsDocument.parse(parseKunaJson(text, KUNA_XREF_OUTPUT_BYTES, addressKeys));
+        if (document.binary !== input ||
+            document.target.address !== target ||
+            document.target.address_hex !== target)
+            throw new Error("xref document names a different input or target");
+        if (document.count !== document.xrefs.length)
+            throw new Error("xref count disagrees with examined rows");
+        const aliases = new Set([target]);
+        for (const alias of document.target.aliases) {
+            if (alias.address !== alias.address_hex)
+                throw new Error("xref alias address disagrees with its hex field");
+            aliases.add(alias.address);
+        }
+        const addresses = new Set();
+        let excludedAliasRows = 0;
+        for (const raw of document.xrefs) {
+            const row = xrefRow.parse(raw);
+            if (row.address !== row.address_hex ||
+                row.address !== row.from_address ||
+                row.from_address !== row.from_address_hex ||
+                row.to_address !== row.to_address_hex)
+                throw new Error("xref endpoints disagree with numeric or directional fields");
+            for (const fn of [row.from_function, row.to_function])
+                if (fn !== null && fn.address !== fn.address_hex)
+                    throw new Error("xref function address disagrees with its hex field");
+            if (!aliases.has(row.to_address))
+                throw new Error("xref row targets neither the requested address nor an advertised alias");
+            if (row.to_address === target)
+                addresses.add(row.from_address);
+            else
+                excludedAliasRows += 1;
+        }
+        return ok({
+            addresses: [...addresses].sort(compareKunaAddresses),
+            rows: document.xrefs.length,
+            excludedAliasRows,
+            bytes: Buffer.byteLength(text),
+            sha256: createHash("sha256").update(text).digest("hex"),
+        });
+    }
+    catch (cause) {
+        return err(cause instanceof Error ? cause.message : String(cause));
+    }
+};

package/dist/kuna/KunaReferenceQueries.js

@@ -0,0 +1,211 @@
+import { AnalysisCancelledError, AnalysisResourceConstraintError, } from "../domain/analysisErrorCore.js";
+import { ProviderAdapterError } from "../domain/providerAdapterError.js";
+import { err, ok } from "../domain/result.js";
+import { kunaProjectDeadline } from "./KunaConfiguration.js";
+import { KUNA_XREF_OUTPUT_BYTES, KunaCallGraphReader, parseKunaIncomingReferences, } from "./KunaReferenceFiles.js";
+import { KUNA_PROVIDER_ID } from "./KunaRelease.js";
+import { kunaUnavailable } from "./KunaUnavailable.js";
+/** Charge raw JSON bytes conservatively; retained projections are smaller. */
+const XREF_CACHE_BYTES = 16 * 1024 * 1024;
+/** Also bound metadata for empty results and queued native queries. */
+const XREF_CACHE_ENTRIES = 128;
+const PENDING_XREF_QUERIES = 8;
+/** Lazy session facts, shared producers and bounded exact-address xref reuse. */
+export class KunaReferenceQueries {
+    work;
+    #graph;
+    /** Deterministic buffer failures belong to the same session as its graph. */
+    #graphFailure;
+    #pendingGraph;
+    #xrefs = new Map();
+    #pendingXrefs = new Map();
+    #xrefBytes = 0;
+    constructor(work) {
+        this.work = work;
+    }
+    async relationships(installation, address, operation, signal) {
+        const graph = await this.#loadGraph(installation, operation, signal);
+        return graph.ok
+            ? this.#relationships(graph.value, address, operation)
+            : graph;
+    }
+    /** Only a validated graph can establish that an inventory-missing entry exists. */
+    async functionAt(installation, address, operation, signal) {
+        const graph = await this.#loadGraph(installation, operation, signal);
+        if (!graph.ok)
+            return graph;
+        const node = graph.value.nodes.get(address);
+        return ok(node === undefined
+            ? undefined
+            : {
+                address: node.address,
+                source: this.#source(graph.value, node),
+            });
+    }
+    async #loadGraph(installation, operation, signal) {
+        if (this.#graphFailure !== undefined)
+            return err(this.#graphFailure);
+        if (this.#graph === undefined) {
+            if (this.#pendingGraph?.signal.aborted === true) {
+                const retired = await this.work.wait(this.#pendingGraph, signal, operation);
+                if (!retired.ok && !(retired.error instanceof AnalysisCancelledError))
+                    return retired;
+                if (signal?.aborted === true)
+                    return err(new AnalysisCancelledError(operation, { cause: signal?.reason }));
+                return this.#loadGraph(installation, operation, signal);
+            }
+            if (this.#pendingGraph === undefined) {
+                const pending = this.work.start((producerSignal) => this.work.scan({
+                    installation,
+                    operation: "kuna:call-graph",
+                    arguments: (input) => [
+                        "decompile-graph",
+                        input,
+                        "--functions",
+                        "",
+                    ],
+                    deadline: kunaProjectDeadline(installation.configuration),
+                }, new KunaCallGraphReader(), producerSignal, (failure) => {
+                    this.#graphFailure = failure;
+                }), (value) => {
+                    this.#graph = value;
+                });
+                this.#pendingGraph = pending;
+                const release = () => {
+                    if (this.#pendingGraph === pending)
+                        this.#pendingGraph = undefined;
+                };
+                void pending.promise.then(release, release);
+            }
+            return this.work.wait(this.#pendingGraph, signal, operation);
+        }
+        return ok(this.#graph);
+    }
+    #relationships(graph, address, operation) {
+        const node = graph.nodes.get(address);
+        if (node === undefined)
+            return err(kunaUnavailable(operation, `Kuna's graph has no function node at ${address}; its relationships are unknown.`));
+        const identities = (addresses) => addresses.map((entryAddress) => {
+            const entry = graph.nodes.get(entryAddress); // The parser proved both endpoints.
+            return {
+                address: entry.address,
+                name: entry.name,
+                classification: null,
+                body: {
+                    available: false,
+                    reason: "Kuna's graph reports no observed body ranges.",
+                },
+            };
+        });
+        return ok({
+            callers: identities(graph.callers.get(address) ?? []),
+            callees: identities(graph.callees.get(address) ?? []),
+            callersCoverage: graph.hasIndirectCalls
+                ? {
+                    status: "partial",
+                    limited_directions: ["callers"],
+                    limitations: [
+                        "Kuna reports unresolved indirect calls in the image; additional callers cannot be excluded.",
+                    ],
+                }
+                : { status: "complete" },
+            calleesCoverage: node.hasIndirectCalls
+                ? {
+                    status: "partial",
+                    limited_directions: ["callees"],
+                    limitations: [
+                        "Kuna reports indirect calls in this function without every target; additional callees remain unknown.",
+                    ],
+                }
+                : { status: "complete" },
+            source: this.#source(graph, node),
+        });
+    }
+    #source(graph, node) {
+        return {
+            kind: "kuna-call-graph",
+            schema_version: 4,
+            sha256: graph.sha256,
+            bytes: graph.bytes,
+            functions: graph.nodes.size,
+            edges: graph.edgeCount,
+            has_indirect_calls: graph.hasIndirectCalls,
+            function: {
+                address: node.address,
+                has_indirect_calls: node.hasIndirectCalls,
+                forwards_to: node.forwardsTo,
+                forwarding_target_in_graph: node.forwardsTo === null ? null : graph.nodes.has(node.forwardsTo),
+            },
+        };
+    }
+    async incoming(installation, address, signal) {
+        const cached = this.#xrefs.get(address);
+        if (cached !== undefined) {
+            this.#xrefs.delete(address);
+            this.#xrefs.set(address, cached);
+            return ok(cached);
+        }
+        let pending = this.#pendingXrefs.get(address);
+        if (pending?.signal.aborted === true) {
+            const retired = await this.work.wait(pending, signal, "xrefs");
+            if (!retired.ok && !(retired.error instanceof AnalysisCancelledError))
+                return retired;
+            if (signal?.aborted === true)
+                return err(new AnalysisCancelledError("xrefs", { cause: signal?.reason }));
+            return this.incoming(installation, address, signal);
+        }
+        if (pending === undefined) {
+            if (this.#pendingXrefs.size >= PENDING_XREF_QUERIES)
+                return err(new AnalysisResourceConstraintError("xrefs", "capacity", "The session's native reference-query queue is full; await an existing query before starting another.", { limit_queries: PENDING_XREF_QUERIES }));
+            pending = this.work.start(async (producerSignal) => {
+                const run = await this.work.run({
+                    installation,
+                    operation: "xrefs",
+                    arguments: (input) => ["xrefs", input, "--to", address, "--json"],
+                    deadline: kunaProjectDeadline(installation.configuration),
+                    outputBytes: KUNA_XREF_OUTPUT_BYTES,
+                    signal: producerSignal,
+                });
+                if (!run.ok)
+                    return run;
+                return this.#parsed(parseKunaIncomingReferences(run.value.stdout.text, run.value.input, address), "incoming references");
+            }, (value) => this.#cache(address, value));
+            this.#pendingXrefs.set(address, pending);
+            const current = pending;
+            const release = () => {
+                if (this.#pendingXrefs.get(address) === current)
+                    this.#pendingXrefs.delete(address);
+            };
+            void pending.promise.then(release, release);
+        }
+        return this.work.wait(pending, signal, "xrefs");
+    }
+    #cache(address, value) {
+        this.#xrefs.set(address, value);
+        this.#xrefBytes += value.bytes + 256;
+        while (this.#xrefBytes > XREF_CACHE_BYTES ||
+            this.#xrefs.size > XREF_CACHE_ENTRIES) {
+            const oldest = this.#xrefs.entries().next().value;
+            if (oldest === undefined)
+                break;
+            this.#xrefs.delete(oldest[0]);
+            this.#xrefBytes -= oldest[1].bytes + 256;
+        }
+    }
+    /** Release parsed facts after the session has drained all owned producers. */
+    clear() {
+        this.#graph = undefined;
+        this.#graphFailure = undefined;
+        this.#pendingGraph = undefined;
+        this.#xrefs.clear();
+        this.#pendingXrefs.clear();
+        this.#xrefBytes = 0;
+    }
+    #parsed(parsed, label) {
+        return parsed.ok
+            ? parsed
+            : err(new ProviderAdapterError(KUNA_PROVIDER_ID, "kuna:references", {
+                userMessage: `Kuna's ${label} cannot be used: ${parsed.error}`,
+            }));
+    }
+}

package/dist/kuna/KunaRelease.js

@@ -0,0 +1,10 @@
+/** Kuna release whose CLI and project layout REA verified; others report as unverified. */
+export const KUNA_VERIFIED_VERSION = "1.833";
+/** Stable provider ID shared by readiness, doctor and Evidence. */
+export const KUNA_PROVIDER_ID = "kuna";
+/** Remediation when `REA_KUNA_COMMAND` is missing or not an absolute path. */
+export const KUNA_COMMAND_REMEDIATION = `Set REA_KUNA_COMMAND to the absolute path of a caller-supplied kuna executable (verified with ${KUNA_VERIFIED_VERSION}). REA does not download, install or update Kuna.`;
+/** Remediation when the host cannot supervise a Kuna process tree. */
+export const KUNA_UNSUPPORTED_HOST_REMEDIATION = "Use Linux or macOS for the Kuna provider. Windows process-tree ownership for Kuna is not verified.";
+/** Remediation when `kuna --version` cannot establish the installed release. */
+export const KUNA_VERSION_PROBE_REMEDIATION = "Run the selected executable with --version: it must exit promptly and print `kuna <major>.<minor>`.";

package/dist/kuna/KunaRunSlots.js

@@ -0,0 +1,56 @@
+import { availableParallelism } from "node:os";
+/**
+ * Provider-wide admission for foreground decompile and reference walks.
+ *
+ * A single-function decompile analyzes the whole image again; one measured
+ * run held about 360 MiB resident and close to one core on a 200 KiB Mach-O.
+ * Foreground walks share the cores reserved beyond an export's `--jobs` workers.
+ * Requests beyond that budget wait in FIFO order. A native cleanup owner
+ * keeps its slot while it cannot prove that the process stopped.
+ */
+export class KunaRunSlots {
+    #capacity;
+    #active = 0;
+    #waiting = [];
+    constructor(capacity) {
+        this.#capacity = Math.max(1, capacity);
+    }
+    /** Slots for the cores an export with `jobs` workers leaves on this host. */
+    static forHost(jobs) {
+        return new KunaRunSlots(availableParallelism() - jobs);
+    }
+    /** Wait for a slot; undefined when the signal aborts first. */
+    acquire(signal) {
+        if (signal.aborted)
+            return Promise.resolve(undefined);
+        if (this.#active < this.#capacity) {
+            this.#active += 1;
+            return Promise.resolve(this.#release());
+        }
+        return new Promise((resolve) => {
+            const grant = () => {
+                signal.removeEventListener("abort", onAbort);
+                this.#active += 1;
+                resolve(this.#release());
+            };
+            const onAbort = () => {
+                const index = this.#waiting.indexOf(grant);
+                if (index !== -1)
+                    this.#waiting.splice(index, 1);
+                resolve(undefined);
+            };
+            signal.addEventListener("abort", onAbort, { once: true });
+            this.#waiting.push(grant);
+        });
+    }
+    #release() {
+        let released = false;
+        return () => {
+            if (released)
+                return;
+            released = true;
+            this.#active -= 1;
+            this.#waiting.shift()?.();
+        };
+    }
+}