rea-agents 6.5.0 → 6.7.0

package/dist/ghidra/GhidraInstallation.js

@@ -1,11 +1,18 @@
+import { AnalysisError } from "../domain/analysisErrorBase.js";
+import { AnalysisCancelledError } from "../domain/analysisErrorCore.js";
+import { probeGhidraJava, } from "./GhidraJavaProbe.js";
+import { ok } from "../domain/result.js";
+import { projectAnalysisError } from "../domain/analysisErrorProjection.js";
+import { readGhidraExecutableHeader } from "./GhidraExecutableHeader.js";
 import { snapshotEnvironment } from "../process/snapshotEnvironment.js";
-import { spawnSync } from "node:child_process";
+import { readGhidraInstallationProperties, } from "./GhidraInstallationProperties.js";
 import { constants } from "node:fs";
-import { accessSync, closeSync, fstatSync, openSync, readFileSync, readSync, realpathSync, statSync, } from "node:fs";
+import { accessSync, realpathSync, statSync } from "node:fs";
 import { delimiter as pathDelimiter, dirname, posix, win32 } from "node:path";
 import { parseExecutableHeader, } from "../domain/binaryTarget.js";
 import { isMachOFormat, } from "../domain/binaryTargetTypes.js";
-import { ghidraApplicationProperties, ghidraJavaMajorAccepted, ghidraJavaRangeLabel, ghidraJavaRequirement, ghidraReleaseAccepted, ghidraReleaseCompatibility, ghidraReleaseLine, ghidraVersionDetail, SUPPORTED_GHIDRA_VERSION, } from "./GhidraInstallationPolicy.js";
+import { ghidraApplicationProperties, ghidraJavaMajorAccepted, ghidraJavaRangeLabel, ghidraJavaRequirement, } from "./GhidraInstallationPolicy.js";
+import { ghidraReleaseAccepted, ghidraReleaseCompatibility, ghidraReleaseLine, ghidraVersionDetail, SUPPORTED_GHIDRA_VERSION, } from "./GhidraReleasePolicy.js";
 const NATIVE_PLATFORMS = {
     linux: { x64: "linux_x86_64", arm64: "linux_arm_64" },
     darwin: { x64: "mac_x86_64", arm64: "mac_arm_64" },
@@ -24,16 +31,6 @@ const NATIVE_ARCHITECTURES = [
     { node: "arm", binary: "arm" },
     { node: "arm64", binary: "arm64" },
 ];
-/** Bound installation discovery reads; larger headers remain unknown. */
-const EXECUTABLE_HEADER_PROBE_BYTES = 4096;
-/**
- * Bound the Java version probe so a chatty or hostile JVM cannot force an
- * unbounded in-memory capture. Well-behaved JVMs print a few kilobytes for
- * `-XshowSettings:properties`; the same 1 MiB budget used for other Java
- * listings leaves ample headroom. A probe that exceeds the budget yields no
- * observation and is reported through the existing failed-probe path.
- */
-const JAVA_PROBE_MAX_OUTPUT_BYTES = 1024 * 1024;
 /**
  * Judge a native decompiler by its own executable header instead of the
  * directory name that admits it.
@@ -92,10 +89,14 @@ const assessNativeDecompiler = (path, platform, architecture, probe) => {
     };
 };
 /** Inspect an installation without importing a target or modifying Ghidra. */
-export const inspectGhidraInstallation = (options, host = systemGhidraInstallationHost()) => {
+export const inspectGhidraInstallation = async (options, host = systemGhidraInstallationHost()) => {
+    if (options.signal?.aborted)
+        throw new AnalysisCancelledError("ghidra:installation", {
+            cause: options.signal.reason,
+        });
     const platform = options.platform ?? process.platform;
     const architecture = options.architecture ?? process.arch;
-    const coordinates = installationCoordinates(options, platform, architecture, host);
+    const coordinates = await installationCoordinates(options, platform, architecture, host);
     const checks = installationChecks({
         coordinates,
         platform,
@@ -104,21 +105,31 @@ export const inspectGhidraInstallation = (options, host = systemGhidraInstallati
         host,
     });
     const failed = checks.find((check) => check.status === "failed");
+    const javaObservation = coordinates.java ?? coordinates.javaProbeFailure?.properties;
     const observation = {
         platform,
         architecture,
         applicationPropertiesPath: coordinates.applicationPropertiesPath,
+        configurationDirectoryName: coordinates.properties?.configurationDirectoryName ?? null,
         nativeDecompilerPath: coordinates.nativeDecompilerPath,
+        ...(coordinates.nativeDecompilerHeader.ok
+            ? {}
+            : {
+                nativeDecompilerHeaderFailure: coordinates.nativeDecompilerHeader.error,
+            }),
         javaCommand: coordinates.javaCommand,
-        ...(coordinates.java?.vmName === undefined
+        ...(coordinates.javaProbeFailure === undefined
             ? {}
-            : { javaVmName: coordinates.java.vmName }),
-        ...(coordinates.java?.osArch === undefined
+            : { javaProbeFailure: coordinates.javaProbeFailure }),
+        ...(javaObservation?.vmName == null
             ? {}
-            : { javaOsArch: coordinates.java.osArch }),
-        ...(coordinates.java?.osName === undefined
+            : { javaVmName: javaObservation.vmName }),
+        ...(javaObservation?.osArch == null
             ? {}
-            : { javaOsName: coordinates.java.osName }),
+            : { javaOsArch: javaObservation.osArch }),
+        ...(javaObservation?.osName == null
+            ? {}
+            : { javaOsName: javaObservation.osName }),
         checks,
     };
     if (failed !== undefined)
@@ -128,10 +139,15 @@ export const inspectGhidraInstallation = (options, host = systemGhidraInstallati
             installDir: coordinates.installDir,
             analyzeHeadlessPath: coordinates.analyzeHeadlessPath,
             providerVersion: coordinates.properties?.providerVersion ?? null,
-            javaHome: coordinates.java?.home ?? options.javaHome ?? null,
-            javaVersion: coordinates.java?.version ?? null,
+            javaHome: javaObservation?.home ?? options.javaHome ?? null,
+            javaVersion: javaObservation?.version ?? null,
             rejection: { code: failed.code, reason: failed.remediation },
         };
+    if (options.signal?.aborted)
+        throw new AnalysisCancelledError("ghidra:installation", {
+            cause: options.signal.reason,
+            diagnostics: ghidraInstallationDiagnostics(availableInstallation(coordinates, observation)),
+        });
     return availableInstallation(coordinates, observation);
 };
 const availableInstallation = (coordinates, observation) => {
@@ -154,7 +170,7 @@ const availableInstallation = (coordinates, observation) => {
         javaVersion: coordinates.java.version,
     };
 };
-const installationCoordinates = (options, platform, architecture, host) => {
+const installationCoordinates = async (options, platform, architecture, host) => {
     const path = platform === "win32" ? win32 : posix;
     // An explicit setting remains authoritative even when malformed or stale;
     // automatic discovery is only a fallback when the caller supplied none.
@@ -177,25 +193,64 @@ const installationCoordinates = (options, platform, architecture, host) => {
         ].find((candidate) => host.executable(candidate)) ?? null);
     const properties = applicationPropertiesPath === null
         ? undefined
-        : host.readText(applicationPropertiesPath);
-    const javaCommand = options.javaHome === undefined
-        ? platform === "win32"
-            ? "java.exe"
-            : "java"
-        : path.join(options.javaHome, "bin", platform === "win32" ? "java.exe" : "java");
+        : await host.readText(applicationPropertiesPath, {
+            resourceOwner: options.resourceOwner,
+            ...(options.signal === undefined ? {} : { signal: options.signal }),
+        });
+    const nativeDecompilerHeader = nativeDecompilerPath === null || host.executableHeader === undefined
+        ? ok(undefined)
+        : await host.executableHeader(nativeDecompilerPath, {
+            resourceOwner: options.resourceOwner,
+            ...(options.signal === undefined ? {} : { signal: options.signal }),
+        });
+    if (!nativeDecompilerHeader.ok &&
+        (nativeDecompilerHeader.error instanceof AnalysisCancelledError ||
+            nativeDecompilerHeader.error.cleanupIncomplete))
+        throw nativeDecompilerHeader.error;
+    const javaCommand = (() => {
+        if (options.javaHome !== undefined)
+            return path.join(options.javaHome, "bin", platform === "win32" ? "java.exe" : "java");
+        if (platform !== "darwin")
+            return platform === "win32" ? "java.exe" : "java";
+        // Check the caller's PATH, never a file named java in the working directory.
+        const javaOnPath = options.environment.PATH?.split(":").some((directory) => path.isAbsolute(directory) &&
+            host.executable(path.join(directory, "java")));
+        if (javaOnPath)
+            return "java";
+        // Prefer the Homebrew prefix matching the process architecture.
+        const prefixes = architecture === "arm64"
+            ? ["/opt/homebrew", "/usr/local"]
+            : ["/usr/local", "/opt/homebrew"];
+        return (prefixes
+            .map((prefix) => path.join(prefix, "opt/openjdk/libexec/openjdk.jdk/Contents/Home/bin/java"))
+            .find((candidate) => host.executable(candidate)) ?? "java");
+    })();
+    // Relative JAVA_HOME is refused by configuration validation without execution.
+    const javaProbe = options.javaHome === undefined || path.isAbsolute(options.javaHome)
+        ? await host.probeJava(javaCommand, ghidraJavaEnvironment(options.javaHome, options.environment, platform), {
+            resourceOwner: options.resourceOwner,
+            ...(options.signal === undefined ? {} : { signal: options.signal }),
+        })
+        : undefined;
+    if (javaProbe !== undefined &&
+        !javaProbe.ok &&
+        javaProbe.error instanceof AnalysisError)
+        throw javaProbe.error;
     return {
         installDir,
         applicationPropertiesPath,
         analyzeHeadlessPath,
         nativeDecompilerPath,
+        nativeDecompilerHeader,
         properties: properties === undefined
             ? undefined
             : ghidraApplicationProperties(properties),
         javaCommand,
-        // The configuration check rejects a relative JAVA_HOME. Probing it would
-        // run whatever `bin/java` the current directory holds.
-        java: options.javaHome === undefined || path.isAbsolute(options.javaHome)
-            ? host.probeJava(javaCommand, ghidraJavaEnvironment(options.javaHome, options.environment, platform))
+        java: javaProbe?.ok === true ? javaProbe.value : undefined,
+        javaProbeFailure: javaProbe !== undefined &&
+            !javaProbe.ok &&
+            !(javaProbe.error instanceof AnalysisError)
+            ? javaProbe.error
             : undefined,
     };
 };
@@ -232,8 +287,8 @@ const installationChecks = ({ coordinates, platform, architecture, javaHome, hos
         detail: coordinates.analyzeHeadlessPath ?? "analyzeHeadless unavailable",
         remediation: "Restore support/analyzeHeadless or support/analyzeHeadless.bat from the official Ghidra release.",
     }),
-    nativeDecompilerCheck({ coordinates, platform, architecture, host }),
-    javaCheck(coordinates.java, coordinates.javaCommand, javaHome, coordinates.properties),
+    nativeDecompilerCheck({ coordinates, platform, architecture }),
+    javaCheck(coordinates.java, coordinates.javaCommand, javaHome, coordinates.properties, platform, coordinates.javaProbeFailure),
 ];
 /**
  * REA's configuration parser, and so the MCP server and analysis, accept only
@@ -264,14 +319,41 @@ const configurationCheck = (installDir, javaHome, platform) => {
         remediation: `Set ${settings} to ${relative.length === 1 ? "an absolute path" : "absolute paths"}. REA's analysis and MCP server reject relative paths even when they resolve from the current directory.`,
     });
 };
-/** Project an installation probe into caller-visible, secret-free diagnostics. */
+/** Project an installation probe into caller-visible, bounded diagnostics. */
 export const ghidraInstallationDiagnostics = (inspection) => ({
     install_dir: inspection.installDir,
     analyze_headless_path: inspection.analyzeHeadlessPath,
     native_decompiler_path: inspection.nativeDecompilerPath,
+    ...(inspection.nativeDecompilerHeaderFailure === undefined
+        ? {}
+        : {
+            native_decompiler_header_failure: projectAnalysisError(inspection.nativeDecompilerHeaderFailure),
+        }),
     application_properties_path: inspection.applicationPropertiesPath,
     provider_version: inspection.providerVersion,
     java_command: inspection.javaCommand,
+    ...(inspection.javaProbeFailure === undefined
+        ? {}
+        : {
+            java_probe_failure: {
+                code: inspection.javaProbeFailure.code,
+                ...(inspection.javaProbeFailure.processErrorCode === undefined
+                    ? {}
+                    : {
+                        process_error_code: inspection.javaProbeFailure.processErrorCode,
+                    }),
+                detail: inspection.javaProbeFailure.detail,
+                ...(inspection.javaProbeFailure.cancellation === undefined
+                    ? {}
+                    : { cancellation_observed: true }),
+                ...(inspection.javaProbeFailure.properties === undefined
+                    ? {}
+                    : { properties: { ...inspection.javaProbeFailure.properties } }),
+                ...(inspection.javaProbeFailure.output === undefined
+                    ? {}
+                    : { output: { ...inspection.javaProbeFailure.output } }),
+            },
+        }),
     java_home: inspection.javaHome,
     java_version: inspection.javaVersion,
     java_vm_name: inspection.javaVmName ?? null,
@@ -318,11 +400,16 @@ const installationCheck = (options) => options.passed
         remediation: options.remediation,
     };
 /** Require a present native decompiler without positively incompatible bytes. */
-const nativeDecompilerCheck = ({ coordinates, platform, architecture, host, }) => {
+const nativeDecompilerCheck = ({ coordinates, platform, architecture, }) => {
     const path = coordinates.nativeDecompilerPath;
     const compatibility = path === null
         ? undefined
-        : assessNativeDecompiler(path, platform, architecture, host.executableHeader?.(path));
+        : !coordinates.nativeDecompilerHeader.ok
+            ? {
+                status: "unknown",
+                detail: `${path} header is unknown: ${coordinates.nativeDecompilerHeader.error.message}`,
+            }
+            : assessNativeDecompiler(path, platform, architecture, coordinates.nativeDecompilerHeader.value);
     // Ghidra resolves its native decompiler directory from the JVM's os.arch,
     // not the host process architecture. A JDK running under emulation (for
     // example x86_64 under Rosetta on Apple silicon) selects a directory that
@@ -330,8 +417,12 @@ const nativeDecompilerCheck = ({ coordinates, platform, architecture, host, }) =
     // Ghidra resolves the OS directory from the JVM os.name/os.arch pair, so a
     // JVM reporting a non-host os.name (for example through -Dos.name=Windows)
     // selects a different OS directory even when os.arch matches.
-    const osArch = coordinates.java?.osArch;
-    const osName = coordinates.java?.osName;
+    const osArch = coordinates.java?.osArch ??
+        coordinates.javaProbeFailure?.properties?.osArch ??
+        undefined;
+    const osName = coordinates.java?.osName ??
+        coordinates.javaProbeFailure?.properties?.osName ??
+        undefined;
     const selectedDirectory = jvmOsArchNativeDirectory(platform, osArch);
     const validatedDirectory = NATIVE_PLATFORMS[platform]?.[architecture];
     // Without a JVM observation the java check reports the missing runtime;
@@ -433,7 +524,7 @@ const versionCheck = (properties) => {
         remediation: `Install a Ghidra ${ghidraReleaseLine()} release (verified with ${SUPPORTED_GHIDRA_VERSION}), or update REA for another Ghidra line.`,
     });
 };
-const javaCheck = (observation, command, configuredHome, properties) => {
+const javaCheck = (observation, command, configuredHome, properties, platform, failure) => {
     const requirement = ghidraJavaRequirement(properties);
     const range = ghidraJavaRangeLabel(requirement);
     const supported = observation !== undefined &&
@@ -451,8 +542,8 @@ const javaCheck = (observation, command, configuredHome, properties) => {
             observation.runtime !== "jdk");
     const detail = observation === undefined
         ? requirement.unresolved === null
-            ? command
-            : `${command}; ${requirement.unresolved}`
+            ? (failure?.detail ?? `${command}: Java probe was not attempted`)
+            : `${failure?.detail ?? command}; ${requirement.unresolved}`
         : `${observation.version}; ${bitness}; ${observation.runtime === "jdk" ? "JDK" : "runtime only"}; ${observation.home}; accepted ${range}`;
     return installationCheck({
         name: "java",
@@ -460,55 +551,24 @@ const javaCheck = (observation, command, configuredHome, properties) => {
         code: requirement.unresolved !== null
             ? "version_unresolved"
             : observation === undefined
-                ? "runtime_missing"
+                ? (failure?.code ?? "version_unresolved")
                 : knownMismatch
                     ? "unsupported_version"
                     : "version_unresolved",
         detail,
-        remediation: javaRemediation(requirement, configuredHome, range),
+        remediation: javaRemediation(requirement, configuredHome, range, platform),
     });
 };
-const javaRemediation = (requirement, configuredHome, range) => {
+const javaRemediation = (requirement, configuredHome, range, platform) => {
     if (requirement.unresolved !== null)
         return `The Ghidra installation's Java bounds could not be read (${requirement.unresolved}). Install a 64-bit full JDK inside the declared application.java.min and application.java.max.`;
     return configuredHome === undefined
-        ? `Install ${range}, or set JAVA_HOME before starting REA.`
+        ? `Select ${range} on PATH, or set JAVA_HOME to its installation root before starting REA.${platform === "darwin" ? " Homebrew OpenJDK can be keg-only: set JAVA_HOME to the selected formula's libexec/openjdk.jdk/Contents/Home (for example /opt/homebrew/opt/openjdk/libexec/openjdk.jdk/Contents/Home or /usr/local/opt/openjdk/libexec/openjdk.jdk/Contents/Home). The installed JDK must satisfy the declared Ghidra Java bounds." : ""}`
         : `Update JAVA_HOME to the root of ${range} installation.`;
 };
-const systemGhidraInstallationHost = () => ({
-    readText(path) {
-        try {
-            // Ghidra loads this file with Properties.load(InputStream), which maps
-            // bytes as ISO-8859-1 rather than decoding UTF-8.
-            return readFileSync(path).toString("latin1");
-        }
-        catch (cause) {
-            // best-effort cleanup: optional install probing; unreadable means unknown.
-            void cause;
-            return undefined;
-        }
-    },
-    executableHeader(path) {
-        let handle;
-        try {
-            handle = openSync(path, constants.O_RDONLY | constants.O_NONBLOCK | constants.O_NOCTTY);
-            const metadata = fstatSync(handle);
-            if (!metadata.isFile())
-                return undefined;
-            const bytes = Buffer.alloc(EXECUTABLE_HEADER_PROBE_BYTES);
-            const read = readSync(handle, bytes, 0, bytes.length, 0);
-            return { bytes: bytes.subarray(0, read), size: metadata.size };
-        }
-        catch (cause) {
-            // best-effort cleanup: a header that cannot be read stays unknown.
-            void cause;
-            return undefined;
-        }
-        finally {
-            if (handle !== undefined)
-                closeSync(handle);
-        }
-    },
+export const systemGhidraInstallationHost = () => ({
+    readText: readGhidraInstallationProperties,
+    executableHeader: readGhidraExecutableHeader,
     executable(path) {
         try {
             accessSync(path, constants.X_OK);
@@ -520,59 +580,7 @@ const systemGhidraInstallationHost = () => ({
             return false;
         }
     },
-    probeJava(command, environment) {
-        const observed = spawnSync(command, [
-            "-Dstdout.encoding=UTF-8",
-            "-Dstderr.encoding=UTF-8",
-            // JDK 17/18 use the legacy names; JDK 19+ use the names above.
-            "-Dsun.stdout.encoding=UTF-8",
-            "-Dsun.stderr.encoding=UTF-8",
-            "-XX:-UsePerfData",
-            "-XshowSettings:properties",
-            "-version",
-        ], {
-            encoding: "utf8",
-            env: environment,
-            timeout: 5_000,
-            maxBuffer: JAVA_PROBE_MAX_OUTPUT_BYTES,
-            windowsHide: true,
-        });
-        if (observed.error !== undefined || observed.status !== 0)
-            return undefined;
-        const output = `${observed.stdout ?? ""}\n${observed.stderr ?? ""}`;
-        const version = javaProperty(output, "java.version");
-        const home = javaProperty(output, "java.home");
-        const vmName = javaProperty(output, "java.vm.name");
-        const osArch = javaProperty(output, "os.arch");
-        const osName = javaProperty(output, "os.name");
-        const reportedBits = javaProperty(output, "sun.arch.data.model");
-        const parsedBits = reportedBits !== null && /^\d+$/.test(reportedBits)
-            ? Number(reportedBits)
-            : null;
-        const bits = parsedBits !== null && Number.isSafeInteger(parsedBits)
-            ? parsedBits
-            : null;
-        if (version === null ||
-            version.length === 0 ||
-            home === null ||
-            home.length === 0)
-            return undefined;
-        return {
-            version,
-            major: javaMajor(version),
-            home,
-            ...(vmName === null ? {} : { vmName }),
-            ...(osArch === null ? {} : { osArch }),
-            ...(osName === null ? {} : { osName }),
-            bits,
-            ...(reportedBits === null || bits !== null
-                ? {}
-                : { unparsedBits: reportedBits }),
-            runtime: executablePath((process.platform === "win32" ? win32 : posix).join(home, "bin", process.platform === "win32" ? "javac.exe" : "javac"))
-                ? "jdk"
-                : "jre",
-        };
-    },
+    probeJava: probeGhidraJava,
     discoverInstallDirOnPath: discoverGhidraInstallationOnPath,
 });
 /** Find a PATH launcher whose real target is inside a complete Ghidra tree. */
@@ -626,10 +634,3 @@ const executablePath = (path) => {
         return false;
     }
 };
-const javaProperty = (output, name) => new RegExp(`^[ \\t]*${name.replaceAll(".", "\\.")}[ \\t]*=[ \\t]*([^\\r\\n]*?)[ \\t]*\\r?$`, "mu").exec(output)?.[1] ?? null;
-const javaMajor = (version) => {
-    const first = Number.parseInt(version.split(".")[0] ?? "0", 10);
-    if (first !== 1)
-        return first;
-    return Number.parseInt(version.split(".")[1] ?? "0", 10);
-};

package/dist/ghidra/GhidraInstallationPolicy.js

@@ -1,82 +1,45 @@
 import { parseGhidraJavaProperties } from "./GhidraJavaProperties.js";
-/** 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;
+import { ghidraConfigurationVersion } from "./GhidraReleasePolicy.js";
 /** Read the version and Java bounds Ghidra publishes for one installation. */
 export const ghidraApplicationProperties = (content) => {
     const parsed = parseGhidraJavaProperties(content);
     if (!parsed.ok)
         return {
             providerVersion: null,
+            configurationDirectoryName: null,
             javaMinimum: { status: "unresolved", raw: parsed.error },
             javaMaximum: { status: "unresolved", raw: parsed.error },
             parseError: parsed.error,
         };
     const providerVersion = parsed.value.get("application.version");
+    // ApplicationIdentifier removes Java's ASCII whitespace and uppercases the
+    // release name. Derive only a single safe component for official Ghidra builds.
+    const releaseName = parsed.value
+        .get("application.release.name")
+        ?.replaceAll(/[ \t\n\r\f\v]/gu, "")
+        .toUpperCase();
+    // providerVersion above remains the original evidence.
+    const configurationVersion = providerVersion === undefined
+        ? undefined
+        : ghidraConfigurationVersion(providerVersion);
+    const configurationDirectoryName = providerVersion !== undefined &&
+        configurationVersion !== undefined &&
+        releaseName !== undefined &&
+        /^[A-Za-z0-9][A-Za-z0-9._+-]*$/u.test(providerVersion) &&
+        /^[A-Za-z0-9][A-Za-z0-9._-]*$/u.test(releaseName)
+        ? `ghidra_${configurationVersion}_${releaseName}`
+        : null;
     const minimum = parsed.value.get("application.java.min");
     const maximum = parsed.value.get("application.java.max");
     return {
         providerVersion: providerVersion ?? null,
+        configurationDirectoryName,
         javaMinimum: minimum === undefined ? { status: "absent" } : parseJavaBound(minimum),
         // Ghidra uses an explicitly empty maximum to mean no upper bound.
         javaMaximum: parseJavaMaximum(maximum),
         parseError: null,
     };
 };
-/** 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";
-};
 /** Resolve JDK majors from `application.java.min` and `application.java.max`. */
 export const ghidraJavaRequirement = (properties) => {
     if (properties?.parseError !== null && properties?.parseError !== undefined)
@@ -111,21 +74,6 @@ export const ghidraJavaRangeLabel = (requirement) => {
 export const ghidraJavaMajorAccepted = (major, requirement) => requirement.unresolved === null &&
     major >= requirement.minimumMajor &&
     (requirement.maximumMajor === null || major <= requirement.maximumMajor);
-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 };
-};
 const parseJavaBound = (raw) => {
     const major = parseJavaInteger(raw);
     return major === undefined
@@ -178,13 +126,6 @@ const javaDecimalDigit = (character) => {
         blockStart -= 1;
     return (code - blockStart) % 10;
 };
-const integerGroup = (value) => {
-    if (value === undefined)
-        return undefined;
-    const parsed = Number(value);
-    return Number.isSafeInteger(parsed) ? parsed : undefined;
-};
 const unresolvedJavaRequirement = (unresolved) => ({
     unresolved,
 });
-/** Parse Java Properties.load(InputStream) syntax from its ISO-8859-1 text. */

package/dist/ghidra/GhidraInstallationProperties.js

@@ -0,0 +1,57 @@
+import { createHash } from "node:crypto";
+import { ArtifactFileCancelled, ArtifactFileCleanupFailure, artifactFilePrimaryFailure, withArtifactRegularFile, } from "../artifacts/ArtifactFileOperation.js";
+import { jsonValueSchema } from "../domain/jsonValue.js";
+import { NonRegularFileReadError } from "../filesystem/RegularFile.js";
+import { readStableFileBytes } from "../filesystem/readStableFileBytes.js";
+import { ghidraApplicationProperties } from "./GhidraInstallationPolicy.js";
+import { ghidraFileFailure } from "./GhidraFileArtifacts.js";
+/** Metadata admission budget, not a Java Properties format limit. */
+export const MAX_GHIDRA_INSTALLATION_PROPERTIES_BYTES = 1024 * 1024;
+/** Preserve Java's Latin-1 byte mapping and follow the caller's selected symlinks. */
+export const readGhidraInstallationProperties = async (path, options) => {
+    try {
+        return await options.resourceOwner.run(() => withArtifactRegularFile(path, {
+            retain: (resource) => options.resourceOwner.retain({ close: () => resource.lease.release() }, resource.resource),
+        }, options.signal, async (file) => (await readStableFileBytes(file, path, MAX_GHIDRA_INSTALLATION_PROPERTIES_BYTES, {
+            symlinks: "follow",
+            ...(options.signal === undefined
+                ? {}
+                : { signal: options.signal }),
+        })).toString("latin1"), "follow"));
+    }
+    catch (cause) {
+        const physical = artifactFilePrimaryFailure(cause);
+        if (!(cause instanceof ArtifactFileCleanupFailure) &&
+            physical instanceof Error &&
+            "code" in physical &&
+            "syscall" in physical &&
+            physical.syscall === "open" &&
+            (physical.code === "ENOENT" || physical.code === "ENOTDIR"))
+            return undefined;
+        const completed = cause instanceof ArtifactFileCancelled
+            ? cause.fileCancellation.outcome.value
+            : cause instanceof ArtifactFileCleanupFailure &&
+                cause.fileCleanupFailure.outcome.kind === "completed"
+                ? cause.fileCleanupFailure.outcome.value
+                : undefined;
+        const diagnostics = {
+            path,
+            stage: "installation_properties",
+            ...(physical instanceof NonRegularFileReadError
+                ? { system_code: physical.code }
+                : {}),
+            ...(typeof completed !== "string"
+                ? {}
+                : {
+                    completed_properties: {
+                        bytes: Buffer.byteLength(completed, "latin1"),
+                        sha256: createHash("sha256")
+                            .update(completed, "latin1")
+                            .digest("hex"),
+                        properties: jsonValueSchema.parse(ghidraApplicationProperties(completed)),
+                    },
+                }),
+        };
+        throw ghidraFileFailure(cause, "ghidra:installation", diagnostics);
+    }
+};