rea-agents 6.4.0 → 6.7.0

package/dist/ghidra/GhidraPspExtension.js

@@ -0,0 +1,210 @@
+import { createHash } from "node:crypto";
+import { lstat, opendir, realpath } from "node:fs/promises";
+import { isAbsolute, join } from "node:path";
+import { z } from "zod";
+import { sameRegularFileState } from "../filesystem/RegularFile.js";
+import { AnalysisCancelledError, AnalysisCapabilityUnavailableError, } from "../domain/analysisErrorCore.js";
+import { AnalysisError } from "../domain/analysisErrorBase.js";
+import { err, ok } from "../domain/result.js";
+import { parseGhidraJavaProperties } from "./GhidraJavaProperties.js";
+import { ArtifactReaderFailure } from "../artifacts/ArtifactReader.js";
+import { AnalysisCleanupLease } from "../artifacts/AnalysisCleanupLease.js";
+import { OwnedDirectoryHandle } from "../filesystem/OwnedDirectoryHandle.js";
+import { assertArtifactReadActive, artifactFileCancellationCause, artifactFilePrimaryFailure, bindArtifactFileCleanup, withArtifactRegularFile, } from "../artifacts/ArtifactFileOperation.js";
+/** Installed processor code and data, distinct from REA's analysis-extension ABI. */
+export const ghidraPspExtensionSchema = z.strictObject({
+    id: z.literal("ghidra-allegrex"),
+    root: z.string().refine(isAbsolute),
+    ghidra_version: z.string().min(1),
+    sha256: z.string().regex(/^[a-f0-9]{64}$/u),
+});
+// Resource bounds for scanning a caller-installed extension, not target limits.
+const MAX_ENTRIES = 1024;
+const MAX_BYTES = 64 * 1024 * 1024;
+const MAX_DEPTH = 16;
+const REQUIRED = [
+    "Module.manifest",
+    "extension.properties",
+    "data/languages/allegrex.ldefs",
+    "data/languages/allegrex.sla",
+    "data/languages/allegrex.pspec",
+    "data/languages/allegrex.cspec",
+];
+/** Read-only fingerprint of all installed files; no home scanning or installation. */
+export const inspectGhidraPspExtension = async (root, ghidraVersion, resources, signal) => {
+    try {
+        return await resources.run(() => fingerprint(root, ghidraVersion, resources, signal));
+    }
+    catch (cause) {
+        throw ghidraPspInspectionError(cause);
+    }
+};
+const fingerprint = async (root, ghidraVersion, resources, signal) => {
+    assertArtifactReadActive(signal);
+    if (!isAbsolute(root) || (await realpath(root)) !== root)
+        throw new Error("The installed Allegrex directory must be a canonical non-symlink path.");
+    const files = [];
+    let entries = 1; // The root itself consumes one inventory entry.
+    const visit = async (relative, depth) => {
+        assertArtifactReadActive(signal);
+        if (depth > MAX_DEPTH)
+            throw new Error("Allegrex extension directory nesting exceeds the inspection limit.");
+        const path = join(root, relative);
+        const metadata = await lstat(path);
+        if (metadata.isDirectory()) {
+            const children = await readChildren(path, MAX_ENTRIES - entries, resources, signal);
+            entries += children.length;
+            children.sort();
+            for (const child of children)
+                await visit(relative === "" ? child : `${relative}/${child}`, depth + 1);
+        }
+        else if (metadata.isFile()) {
+            files.push(relative);
+        }
+        else
+            throw new Error(`Allegrex extension entries must be regular files or directories: ${relative}`);
+    };
+    await visit("", 0);
+    for (const required of REQUIRED)
+        if (!files.includes(required))
+            throw new Error(`Missing installed Allegrex component: ${required}`);
+    if (!files.some((path) => path.startsWith("lib/") && path.endsWith(".jar")))
+        throw new Error("The installed Allegrex extension has no loader JAR.");
+    const hash = createHash("sha256");
+    let bytesRead = 0;
+    let properties = Buffer.alloc(0);
+    for (const relative of files) {
+        assertArtifactReadActive(signal);
+        const path = join(root, relative);
+        await withArtifactRegularFile(path, resources, signal, async (handle) => {
+            const before = await handle.stat();
+            if (!Number.isSafeInteger(before.size) ||
+                before.size > MAX_BYTES - bytesRead)
+                throw new Error("Allegrex extension bytes exceed the inspection limit.");
+            if (relative === "extension.properties" && before.size > 65536)
+                throw new Error("Allegrex extension properties exceed the inspection limit.");
+            hash.update(JSON.stringify([relative, before.size]));
+            const buffer = Buffer.alloc(Math.min(65536, before.size + 1));
+            let offset = 0;
+            const chunks = [];
+            // Serial reads keep final close behind every native read. One extra byte
+            // detects growth without a stream's read-ahead or unbounded allocation.
+            while (offset <= before.size) {
+                assertArtifactReadActive(signal);
+                const { bytesRead } = await handle.read(buffer, 0, Math.min(buffer.length, before.size - offset + 1), offset);
+                assertArtifactReadActive(signal);
+                if (bytesRead === 0)
+                    break;
+                offset += bytesRead;
+                if (offset > before.size)
+                    throw new Error(`Allegrex component changed during inspection: ${relative}`);
+                const chunk = buffer.subarray(0, bytesRead);
+                hash.update(chunk);
+                if (relative === "extension.properties")
+                    chunks.push(Buffer.from(chunk));
+            }
+            if (offset !== before.size)
+                throw new Error(`Truncated Allegrex component: ${relative}`);
+            if (!sameRegularFileState(before, await handle.stat()) ||
+                !sameRegularFileState(before, await lstat(path)))
+                throw new Error(`Allegrex component changed during inspection: ${relative}`);
+            bytesRead += before.size;
+            if (relative === "extension.properties")
+                properties = Buffer.concat(chunks);
+        });
+    }
+    // Ghidra's extension.properties version is the compatible Ghidra version,
+    // not the extension release (e.g. v21.4); content identity supplies the latter.
+    const parsedProperties = parseGhidraJavaProperties(properties.toString("latin1"));
+    if (!parsedProperties.ok)
+        throw new Error(`Invalid Allegrex extension properties: ${parsedProperties.error}`);
+    const property = (name) => parsedProperties.value.get(name);
+    if (property("name") !== "ghidra-allegrex" ||
+        property("version") !== ghidraVersion)
+        throw new Error(`Allegrex extension metadata does not match the selected Ghidra ${ghidraVersion}; install or rebuild a compatible extension.`);
+    assertArtifactReadActive(signal);
+    return {
+        id: "ghidra-allegrex",
+        root,
+        ghidra_version: ghidraVersion,
+        sha256: hash.digest("hex"),
+    };
+};
+/** Resolve prerequisites before opening or admitting cached PSP analysis. */
+export const resolveGhidraPspExtension = async (installation, resources, signal) => {
+    try {
+        assertArtifactReadActive(signal);
+        if (installation.status !== "available" ||
+            installation.platform !== "linux" ||
+            installation.architecture !== "x64")
+            throw new Error("The initial PSP profile requires a supported Linux x64 Ghidra installation.");
+        const root = join(await realpath(installation.installDir), "Ghidra", "Extensions", "ghidra-allegrex");
+        return ok(await inspectGhidraPspExtension(root, installation.providerVersion, resources, signal));
+    }
+    catch (cause) {
+        return err(ghidraPspInspectionError(cause));
+    }
+};
+/** Preserve the producer's primary failure and its live cleanup dependencies. */
+const ghidraPspInspectionError = (cause) => {
+    if (cause instanceof AnalysisError)
+        return cause;
+    const cleanup = cause instanceof ArtifactReaderFailure ? cause.cleanup : undefined;
+    const primary = artifactFilePrimaryFailure(cause);
+    const reason = `PSP_EXTENSION_UNAVAILABLE: ${primary instanceof Error ? primary.message : String(primary)} Use a compatible caller-installed ghidra-allegrex under GHIDRA_INSTALL_DIR/Ghidra/Extensions; REA does not install it.`;
+    const error = cause instanceof ArtifactReaderFailure && cause.reason === "cancelled"
+        ? new AnalysisCancelledError("resolve_analysis_profile", {
+            cause: artifactFileCancellationCause(cause),
+            cleanup,
+        })
+        : new AnalysisCapabilityUnavailableError("ghidra", "resolve_analysis_profile", reason, {
+            cause,
+            userMessage: reason,
+            cleanup,
+        });
+    bindArtifactFileCleanup(cause, error);
+    return error;
+};
+/** Close before descending, retaining the exact directory owner on uncertainty. */
+const readChildren = async (path, remainingEntries, resources, signal) => {
+    assertArtifactReadActive(signal);
+    const owner = new OwnedDirectoryHandle(await opendir(path));
+    let outcome;
+    try {
+        const names = [];
+        for (;;) {
+            assertArtifactReadActive(signal);
+            const child = await owner.handle.read();
+            assertArtifactReadActive(signal);
+            if (child === null)
+                break;
+            if (names.length >= remainingEntries)
+                throw new Error("Allegrex extension inventory exceeds the inspection limit.");
+            names.push(child.name);
+        }
+        outcome = { kind: "completed", names };
+    }
+    catch (cause) {
+        outcome = { kind: "failed", cause };
+    }
+    const lease = new AnalysisCleanupLease(() => owner.close(), [path]);
+    const attempt = await resources.release({
+        kind: "lease",
+        resource: path,
+        lease,
+    });
+    if (attempt.kind === "failed") {
+        const primary = outcome.kind === "failed"
+            ? outcome.cause
+            : signal?.aborted
+                ? new ArtifactReaderFailure("cancelled", "PSP inspection cancelled during directory close", { cause: signal.reason })
+                : attempt.cause;
+        const error = ghidraPspInspectionError(ArtifactReaderFailure.withCleanup(primary, ArtifactReaderFailure.cleanupObservation(attempt.cause, path)));
+        lease.bindCleanupError(error);
+        throw error;
+    }
+    if (outcome.kind === "failed")
+        throw outcome.cause;
+    assertArtifactReadActive(signal);
+    return outcome.names;
+};

package/dist/ghidra/GhidraPspProfile.js

@@ -0,0 +1,62 @@
+import { ghidraMipsGnuAttributesUnsupportedReason, ghidraMipsIncompleteDeclarationsReason, ghidraMipsUnsupportedReason, } from "./GhidraMipsProfile.js";
+import { ghidraPowerPcUnsupportedReason } from "./GhidraPowerPcProfile.js";
+import { ghidraRiscvUnsupportedReason } from "./GhidraRiscvProfile.js";
+/** Allegrex's ELF machine declaration, not a filename or inferred instruction. */
+export const isGhidraPspTarget = (target) => target.kind === "executable" &&
+    target.format === "elf" &&
+    target.architecture === "mips" &&
+    target.mips !== undefined &&
+    (target.mips.flags & 0x00ff0000) === 0x00a20000;
+/** PSP has its own verified interpretation; generic MIPS rules remain unchanged. */
+export const ghidraProcessorUnsupportedReason = (target) => {
+    if (target.kind === "executable" && target.architecture === "powerpc")
+        return ghidraPowerPcUnsupportedReason(target);
+    if (target.kind === "executable" && target.architecture === "riscv")
+        return ghidraRiscvUnsupportedReason(target);
+    if (target.kind !== "executable" ||
+        target.architecture !== "mips" ||
+        !isGhidraPspTarget(target))
+        return ghidraMipsUnsupportedReason(target);
+    const metadata = target.mips;
+    if (metadata === undefined)
+        return "PSP analysis requires ELF metadata.";
+    const gnuAttributesReason = ghidraMipsGnuAttributesUnsupportedReason(metadata);
+    if (gnuAttributesReason !== null)
+        return gnuAttributesReason;
+    const incomplete = ghidraMipsIncompleteDeclarationsReason(metadata);
+    if (incomplete !== null)
+        return incomplete;
+    if (metadata.elfClass !== 32 || metadata.byteOrder !== "little")
+        return "The PSP Allegrex profile requires little-endian ELF32.";
+    if (metadata.type !== 2)
+        return "The PSP Allegrex profile supports static ET_EXEC only; PRX, shared and relocatable images require separate verification.";
+    // PSPSDK emits MIPS-II / Allegrex / EABI32 with NOREORDER. Do not accept
+    // unknown producer flags or treat this as proof of instruction semantics.
+    if (metadata.flags !== 0x10a23001)
+        return "The PSP Allegrex profile requires the verified PSPSDK ELF declaration 0x10a23001; other ISA/ABI/ASE flags are not inferred.";
+    const abi = metadata.abiFlags;
+    if (abi === undefined || abi === null)
+        return "The PSP Allegrex profile requires an inspected separate MIPS ABI flags record; missing declarations are not inferred.";
+    // PSPDEV v20261001: GNU readelf 2.44 and the 24-byte record agree on
+    // MIPS II, 32-bit registers, single-precision hard float and flags1=1.
+    // This is a bounded producer declaration, not a claim about VFPU semantics.
+    if (abi.version !== 0 ||
+        abi.isaLevel !== 2 ||
+        abi.isaRevision !== 0 ||
+        abi.gprSize !== 1 ||
+        abi.cpr1Size !== 1 ||
+        abi.cpr2Size !== 0 ||
+        abi.fpAbi !== 2 ||
+        abi.isaExtension !== 0 ||
+        abi.ases !== 0 ||
+        abi.flags1 !== 1 ||
+        abi.flags2 !== 0)
+        return "The separate MIPS ABI flags record does not match the verified PSP MIPS-II/32-bit/single-float declaration; other versions, register modes and extension flags require separate verification.";
+    return null;
+};
+/** Propagated with every PSP observation, including successful decompilation. */
+export const GHIDRA_PSP_LIMITATIONS = [
+    "PSP/Allegrex analysis uses the caller-installed ghidra-allegrex extension. ELF declarations and selected instruction checks are not proof of runtime semantics.",
+    "ghidra-allegrex does not model VFPU prefix effects completely in decompiled output. Verify vector behavior independently; pseudocode is not an execution oracle.",
+    "This PSP profile covers static ELF32 ET_EXEC only. PRX relocations, PBP/ISO containers, live overlays and PSP emulation are outside this verified lane.",
+];

package/dist/ghidra/GhidraRawBinaryLanguage.js

@@ -0,0 +1,49 @@
+/**
+ * Map caller-visible CPU families to generic Ghidra languages with a
+ * supported generic compiler specification. These are analysis conventions,
+ * not evidence of the target's original compiler. Each family has one fixed
+ * byte order: m68k is big-endian and the others are little-endian. Big-endian
+ * ARM, Thumb-only, Cortex-M, and other processor variants are out of scope.
+ */
+export const ghidraRawBinaryLanguage = (architecture) => {
+    switch (architecture) {
+        case "6502":
+            return {
+                languageId: "6502:LE:16:default",
+                compilerSpecId: "default",
+                defaultAddressSpace: "RAM",
+            };
+        case "m68k":
+            // Ghidra's default 68000 language decodes the 68040 superset; no
+            // MC68000-only variant is declared in the 68000 processor module.
+            return {
+                languageId: "68000:BE:32:default",
+                compilerSpecId: "default",
+                defaultAddressSpace: "ram",
+            };
+        case "x86":
+            return {
+                languageId: "x86:LE:32:default",
+                compilerSpecId: "gcc",
+                defaultAddressSpace: "ram",
+            };
+        case "x86_64":
+            return {
+                languageId: "x86:LE:64:default",
+                compilerSpecId: "gcc",
+                defaultAddressSpace: "ram",
+            };
+        case "arm":
+            return {
+                languageId: "ARM:LE:32:v7",
+                compilerSpecId: "default",
+                defaultAddressSpace: "ram",
+            };
+        case "arm64":
+            return {
+                languageId: "AARCH64:LE:64:v8A",
+                compilerSpecId: "default",
+                defaultAddressSpace: "ram",
+            };
+    }
+};

package/dist/ghidra/GhidraReleasePolicy.js

@@ -0,0 +1,93 @@
+/** Ghidra build whose bridge behavior this REA release verifies. */
+export const SUPPORTED_GHIDRA_VERSION = "12.1.4";
+/** Verified JDK major; admission uses the installation's declared bounds. */
+export const SUPPORTED_GHIDRA_JAVA_MAJOR = 21;
+const GHIDRA_RELEASE_PATTERN = /^(\d+)\.(\d+)(?:\.(\d+))?([-+].*)?$/u;
+/** Classify `application.version` against the verified release line. */
+export const ghidraReleaseCompatibility = (raw) => {
+    if (raw === null || raw === undefined)
+        return { status: "unresolved", raw: null };
+    const version = parseGhidraRelease(raw);
+    if (version === undefined)
+        return { status: "unresolved", raw };
+    if (raw === SUPPORTED_GHIDRA_VERSION)
+        return { status: "verified", version, raw };
+    const verified = verifiedGhidraRelease();
+    return version.major === verified.major && version.minor === verified.minor
+        ? { status: "compatible", version, raw }
+        : { status: "unsupported", version, raw };
+};
+/**
+ * Limitation recorded when a session runs a compatible build other than the
+ * verified release. The observed version stays on the provider identity.
+ */
+export const unverifiedGhidraBuildLimitation = (providerVersion) => {
+    const compatibility = ghidraReleaseCompatibility(providerVersion);
+    if (compatibility.status !== "compatible")
+        return undefined;
+    return `This session uses Ghidra ${providerVersion}. The bridge is verified against ${SUPPORTED_GHIDRA_VERSION}; other ${ghidraReleaseLine()} builds are accepted and the observed version is reported.`;
+};
+/** Release line accepted by this bridge, such as `12.1.x`. */
+export const ghidraReleaseLine = () => {
+    const verified = verifiedGhidraRelease();
+    return `${String(verified.major)}.${String(verified.minor)}.x`;
+};
+/** Detail for the installation version check, including the accepted line. */
+export const ghidraVersionDetail = (raw) => {
+    const compatibility = ghidraReleaseCompatibility(raw);
+    switch (compatibility.status) {
+        case "unresolved":
+            return compatibility.raw ?? "unknown";
+        case "verified":
+            return compatibility.raw;
+        case "compatible":
+            return `${compatibility.raw}; compatible ${ghidraReleaseLine()} release (verified build ${SUPPORTED_GHIDRA_VERSION})`;
+        case "unsupported":
+            return `${compatibility.raw}; accepted releases are ${ghidraReleaseLine()} (verified build ${SUPPORTED_GHIDRA_VERSION})`;
+        default: {
+            const unreachable = compatibility;
+            return unreachable;
+        }
+    }
+};
+/** Whether this release line can run the packaged bridge. */
+export const ghidraReleaseAccepted = (raw) => {
+    const status = ghidraReleaseCompatibility(raw).status;
+    return status === "verified" || status === "compatible";
+};
+const verifiedGhidraRelease = () => {
+    const version = parseGhidraRelease(SUPPORTED_GHIDRA_VERSION);
+    if (version === undefined)
+        throw new TypeError(`SUPPORTED_GHIDRA_VERSION ${SUPPORTED_GHIDRA_VERSION} is not a Ghidra release`);
+    return version;
+};
+const parseGhidraRelease = (raw) => {
+    const match = GHIDRA_RELEASE_PATTERN.exec(raw);
+    const major = integerGroup(match?.[1]);
+    const minor = integerGroup(match?.[2]);
+    if (match === null || major === undefined || minor === undefined)
+        return undefined;
+    const patch = match[3] === undefined ? 0 : integerGroup(match[3]);
+    return patch === undefined
+        ? undefined
+        : { major, minor, patch, suffix: match[4] ?? "" };
+};
+/**
+ * The version spelling Ghidra's `ApplicationVersion.toString` uses in its
+ * settings directory: numeric components normalized, a zero patch and an
+ * empty tag omitted. A build-metadata (`+`) suffix has no such spelling.
+ */
+export const ghidraConfigurationVersion = (raw) => {
+    const version = parseGhidraRelease(raw);
+    if (version === undefined || version.suffix.startsWith("+"))
+        return undefined;
+    const patch = version.patch === 0 ? "" : `.${String(version.patch)}`;
+    const suffix = version.suffix === "-" ? "" : version.suffix;
+    return `${String(version.major)}.${String(version.minor)}${patch}${suffix}`;
+};
+const integerGroup = (value) => {
+    if (value === undefined)
+        return undefined;
+    const parsed = Number(value);
+    return Number.isSafeInteger(parsed) ? parsed : undefined;
+};

package/dist/ghidra/GhidraRequestQueue.js

@@ -1,4 +1,6 @@
+import { ProviderCleanupError } from "../domain/providerCleanupError.js";
 import { err } from "../domain/result.js";
+import { GhidraSessionError, } from "./GhidraSessionError.js";
 /** FIFO that admits one Ghidra Program request at a time. */
 export class GhidraRequestQueue {
     execute;
@@ -17,16 +19,16 @@ export class GhidraRequestQueue {
         if (this.#closedFailure !== undefined)
             return Promise.resolve(err(this.#closedFailure));
         if (options.signal?.aborted === true)
-            return Promise.resolve(err(this.failure("cancelled", "Ghidra request was cancelled")));
+            return Promise.resolve(err(this.#cancelled(options.signal)));
         return new Promise((resolve) => {
             let entry;
             const onAbort = options.signal === undefined
                 ? undefined
-                : () => this.#rejectQueued(entry, err(this.failure("cancelled", "Ghidra request was cancelled")));
+                : () => this.#rejectQueued(entry, err(this.#cancelled(options.signal)));
             entry = {
                 method,
                 parameters,
-                signal: options.signal,
+                options,
                 resolve,
                 onAbort,
             };
@@ -55,51 +57,61 @@ export class GhidraRequestQueue {
         if (entry === undefined)
             return;
         this.#release(entry);
-        if (entry.signal?.aborted === true) {
-            entry.resolve(err(this.failure("cancelled", "Ghidra request was cancelled")));
+        if (entry.options.signal?.aborted === true) {
+            entry.resolve(err(this.#cancelled(entry.options.signal)));
             this.#drain();
             return;
         }
         this.#active = true;
-        let executionSettled = false;
-        let activeCancellation;
-        const onAbort = entry.signal === undefined
-            ? undefined
-            : () => {
-                if (executionSettled)
-                    return;
-                this.failQueued(this.failure("process", "Ghidra session closed after active request cancellation"));
-                activeCancellation = this.onActiveCancellation();
-            };
-        if (onAbort !== undefined)
-            entry.signal?.addEventListener("abort", onAbort, { once: true });
-        void this.execute(entry.method, entry.parameters, entry.signal === undefined ? {} : { signal: entry.signal })
-            .then(async (result) => {
-            if (activeCancellation !== undefined) {
-                try {
-                    await activeCancellation;
-                }
-                catch (cause) {
-                    result = err(this.failure("process", cause instanceof Error
-                        ? `Ghidra cleanup after cancellation failed: ${cause.message}`
-                        : "Ghidra cleanup after cancellation failed", cause));
-                }
-            }
-            executionSettled = true;
-            entry.resolve(result);
-        })
-            .catch((cause) => {
-            executionSettled = true;
-            entry.resolve(err(this.failure("protocol", "Ghidra serial request execution rejected unexpectedly", cause)));
-        })
+        void this.#executeEntry(entry)
+            .then(entry.resolve)
             .finally(() => {
-            if (entry.signal !== undefined && onAbort !== undefined)
-                entry.signal.removeEventListener("abort", onAbort);
             this.#active = false;
             if (this.#closedFailure === undefined)
                 this.#drain();
         });
     }
+    async #executeEntry(entry) {
+        let cancellation;
+        const onAbort = () => {
+            this.failQueued(this.failure("process", "Ghidra session closed after active request cancellation"));
+            cancellation = {
+                failure: this.#cancelled(entry.options.signal),
+                // Capture rejection immediately, including a synchronous callback throw.
+                // Execution and finalization may settle in either order.
+                cleanup: Promise.resolve()
+                    .then(() => this.onActiveCancellation())
+                    .then((value) => ({ kind: "returned", value }), (cause) => ({ kind: "rejected", cause })),
+            };
+        };
+        entry.options.signal?.addEventListener("abort", onAbort, { once: true });
+        try {
+            let result;
+            try {
+                result = await this.execute(entry.method, entry.parameters, entry.options);
+            }
+            catch (cause) {
+                result = err(cause instanceof GhidraSessionError
+                    ? cause
+                    : this.failure("protocol", "Ghidra serial request execution rejected unexpectedly", cause));
+            }
+            if (cancellation === undefined)
+                return result;
+            const primary = result.ok ? cancellation.failure : result.error;
+            const cleanup = await cancellation.cleanup;
+            if (cleanup.kind === "rejected")
+                return err(this.#withUnexpectedCleanupRejection(primary, cleanup.cause));
+            return err(cleanup.value.ok
+                ? primary
+                : primary.withCleanupFailure(cleanup.value.error));
+        }
+        finally {
+            entry.options.signal?.removeEventListener("abort", onAbort);
+        }
+    }
+    #cancelled(signal) {
+        return this.failure("cancelled", "Ghidra request was cancelled", signal?.reason, signal === undefined ? {} : { cancellation: { reason: signal.reason } });
+    }
     #rejectQueued(entry, result) {
         const index = this.#queue.indexOf(entry);
         if (index < 0)
@@ -108,8 +120,20 @@ export class GhidraRequestQueue {
         this.#release(entry);
         entry.resolve(result);
     }
+    #withUnexpectedCleanupRejection(primary, cause) {
+        const described = this.failure(primary.kind, primary.message, cause);
+        const rejection = described.diagnostics.failure_cause;
+        const cleanupFailure = new ProviderCleanupError("ghidra", ["Ghidra cancellation cleanup"], {
+            reason: "Cancellation cleanup rejected before release was confirmed",
+            unexpected_cleanup_rejection: rejection ?? { type: typeof cause },
+        }, { cause });
+        return primary.withCleanupFailure(cleanupFailure, {
+            ...primary.diagnostics,
+            unexpected_cleanup_rejection: rejection ?? { type: typeof cause },
+        });
+    }
     #release(entry) {
-        if (entry.signal !== undefined && entry.onAbort !== undefined)
-            entry.signal.removeEventListener("abort", entry.onAbort);
+        if (entry.options.signal !== undefined && entry.onAbort !== undefined)
+            entry.options.signal.removeEventListener("abort", entry.onAbort);
     }
 }

package/dist/ghidra/GhidraRiscvProfile.js

@@ -0,0 +1,100 @@
+/**
+ * Ghidra's generic RISC-V languages model the double-float ABI: the shipped
+ * `riscv.ldefs` maps `RISCV:LE:{32,64}:default` to the `riscv{32,64}-fp.cspec`
+ * compiler specification. Soft, single and quad ABI declarations therefore need
+ * their own verification rather than inheriting this lane.
+ */
+const EF_RISCV_RVC = 0x0001;
+const EF_RISCV_FLOAT_ABI = 0x0006;
+const EF_RISCV_FLOAT_ABI_DOUBLE = 0x0004;
+const EF_RISCV_RVE = 0x0008;
+const EF_RISCV_TSO = 0x0010;
+const ET_REL = 1;
+const ET_EXEC = 2;
+const ET_DYN = 3;
+/**
+ * Bits this lane reads. Anything else in `e_flags` — reserved today or defined by
+ * a newer psABI — is refused rather than assumed compatible.
+ */
+const EF_RISCV_DECLARED_BITS = EF_RISCV_RVC | EF_RISCV_FLOAT_ABI;
+/** Header declarations outside the verified generic-language lane. */
+const riscvUnsupportedFloatAbi = (abi) => abi === 0
+    ? "unspecified (soft-float convention)"
+    : abi === 0x0002
+        ? "single-float"
+        : "quad-float";
+/**
+ * Keep family recognition separate from the deliberately bounded Ghidra lane.
+ *
+ * Ghidra 12.1.4 selects `RISCV:LE:32:AndeStar_v5` for an ordinary RV32 ELF: its
+ * `riscv.opinion` pins `variant="default"` for the 64-bit constraint and leaves
+ * the 32-bit one with the comment that the loader "must choose between 'default'
+ * and 'AndeStar' variants". The lane therefore pins the language instead of
+ * accepting the header-based guess.
+ */
+export const ghidraRiscvUnsupportedReason = (target) => {
+    if (target.kind !== "executable" || target.architecture !== "riscv")
+        return null;
+    const metadata = target.riscv;
+    if (target.format !== "elf")
+        return "RISC-V analysis requires ELF header metadata; a family name alone does not select an ISA or ABI.";
+    if (metadata.byteOrder !== "little")
+        return "This Ghidra RISC-V lane supports little-endian images only; Ghidra 12.1.4 ships no big-endian RISC-V language.";
+    if (metadata.elfClass !== 32 && metadata.elfClass !== 64)
+        return "This Ghidra RISC-V lane requires ELF32 or ELF64; the class decides which generic language is pinned.";
+    if ((metadata.flags & EF_RISCV_RVE) !== 0)
+        return "EF_RISCV_RVE declares the embedded 15-register ABI, which needs its own processor specification and compiler verification.";
+    if ((metadata.flags & EF_RISCV_TSO) !== 0)
+        return "EF_RISCV_TSO declares the total-store-order memory model; this lane verifies the baseline model only.";
+    if (metadata.type !== ET_EXEC)
+        return `This Ghidra RISC-V lane supports fixed-address ET_EXEC only; ${metadata.type === ET_REL
+            ? "relocatable"
+            : metadata.type === ET_DYN
+                ? "shared and position-independent"
+                : `e_type ${metadata.type}`} images need separate load verification. ET_EXEC alone does not establish static linkage, which this lane does not inspect.`;
+    const abi = metadata.flags & EF_RISCV_FLOAT_ABI;
+    if (abi !== EF_RISCV_FLOAT_ABI_DOUBLE)
+        return `This Ghidra RISC-V lane requires the EF_RISCV_FLOAT_ABI_DOUBLE declaration (${riscvUnsupportedFloatAbi(abi)} observed); the pinned generic language uses the double-float compiler specification.`;
+    const unsupportedFlags = (metadata.flags & ~EF_RISCV_DECLARED_BITS) >>> 0;
+    if (unsupportedFlags !== 0)
+        return `RISC-V e_flags declares bits outside the verified lane (0x${unsupportedFlags.toString(16)}); reserved or newer declarations are not treated as compatible with this profile.`;
+    return null;
+};
+/** Pin a language only for declarations admitted by the same lane boundary. */
+export const ghidraRiscvLanguageOverride = (target) => target.kind === "executable" &&
+    target.architecture === "riscv" &&
+    ghidraRiscvUnsupportedReason(target) === null
+    ? {
+        languageId: `RISCV:LE:${target.riscv.elfClass}:default`,
+        compilerSpecId: "gcc",
+    }
+    : undefined;
+/** Commit source ELF interpretation without confusing target ISA with host CPU. */
+export const ghidraRiscvProfileParameters = (target) => target.kind === "executable" &&
+    target.architecture === "riscv" &&
+    target.riscv !== undefined
+    ? {
+        riscv_elf: {
+            elf_class: target.riscv.elfClass,
+            byte_order: target.riscv.byteOrder,
+            type: target.riscv.type,
+            flags: target.riscv.flags,
+            float_abi_double: (target.riscv.flags & EF_RISCV_FLOAT_ABI) ===
+                EF_RISCV_FLOAT_ABI_DOUBLE,
+            rvc_declared: (target.riscv.flags & EF_RISCV_RVC) !== 0,
+            rve_declared: (target.riscv.flags & EF_RISCV_RVE) !== 0,
+            tso_declared: (target.riscv.flags & EF_RISCV_TSO) !== 0,
+        },
+        riscv_support_lane: target.riscv.elfClass === 32
+            ? "elf32-exec-le-double-float-generic-v1"
+            : "elf64-exec-le-double-float-generic-v1",
+    }
+    : {};
+/** The pinned language is an analysis convention, not proof of the producer. */
+export const ghidraRiscvLimitations = (target) => target.kind === "executable" && target.architecture === "riscv"
+    ? [
+        `RISC-V ELF: REA pins Ghidra's generic \`RISCV:LE:${target.riscv.elfClass}:default\` language with the \`gcc\` compiler specification instead of accepting the loader's header-based choice, which selects \`RISCV:LE:32:AndeStar_v5\` for ordinary RV32 images on Ghidra 12.1.4.`,
+        "The pinned generic language models the double-float ABI declared by `e_flags`; the declaration is recorded as an ELF fact and is not evidence of the original compiler or of verified instruction semantics.",
+        "Admission reads `e_type` only: a fixed-address ET_EXEC declaration does not establish static linkage, and program headers (`PT_INTERP`, dynamic dependencies) are not inspected by this lane.",
+    ]
+    : [];