rea-agents 6.2.0 → 6.3.0

package/dist/domain/webCaptureDiff.js

@@ -1,4 +1,5 @@
-import { canonicalDigest } from "./comparisonSemantics.js";
+import { digestCanonicalValue } from "./canonicalDigest.js";
+import { compareUnicodeCodePoints } from "./unicodeCodePointOrder.js";
 import { webCaptureDiffSchema, } from "./webCaptureDiffSchemas.js";
 /** Compare normalized observations without treating incomplete absence as proof. */
 export const compareWebCaptures = (input) => {
@@ -41,8 +42,8 @@ const compareIdentities = (before, after) => {
     for (const identity of after.keys())
         if (!before.has(identity))
             changes.push({ identity, change: "added" });
-    return changes.sort((left, right) => left.identity.localeCompare(right.identity) ||
-        left.change.localeCompare(right.change));
+    return changes.sort((left, right) => compareUnicodeCodePoints(left.identity, right.identity) ||
+        compareUnicodeCodePoints(left.change, right.change));
 };
 const compareDimension = (before, after, complete, reason) => {
     const all = compareIdentities(before, after).filter(({ change }) => complete || change === "modified");
@@ -72,7 +73,7 @@ const accessibilityDimension = (before, after) => {
     const afterAccess = accessibilityComparable(after);
     const textComparable = beforeAccess.text && afterAccess.text;
     const nodesComparable = beforeAccess.nodes && afterAccess.nodes;
-    return compareDimension(singleton("accessibility_tree", digest(accessibilityProjection(before.accessibility, textComparable, nodesComparable))), singleton("accessibility_tree", digest(accessibilityProjection(after.accessibility, textComparable, nodesComparable))), beforeAccess.complete && afterAccess.complete, "Accessibility tree or text capture was incomplete in at least one observation.");
+    return compareDimension(singleton("accessibility_tree", digestCanonicalValue(accessibilityProjection(before.accessibility, textComparable, nodesComparable))), singleton("accessibility_tree", digestCanonicalValue(accessibilityProjection(after.accessibility, textComparable, nodesComparable))), beforeAccess.complete && afterAccess.complete, "Accessibility tree or text capture was incomplete in at least one observation.");
 };
 const storageDimension = (before, after) => {
     const keysComplete = storageKeysComparable(before) && storageKeysComparable(after);
@@ -86,32 +87,65 @@ const storageDimension = (before, after) => {
 const compareWebCaptureDimensions = (input) => {
     const before = input.before.inspection;
     const after = input.after.inspection;
-    const dimension = compareDimension;
     return {
-        dom_structure: dimension(singleton("document", digest(domProjection(before))), singleton("document", digest(domProjection(after))), sectionsComplete(before, ["frames", "dom"]) &&
+        dom_structure: compareDimension(singleton("document", digestCanonicalValue(domProjection(before))), singleton("document", digestCanonicalValue(domProjection(after))), sectionsComplete(before, ["frames", "dom"]) &&
             sectionsComplete(after, ["frames", "dom"]), "DOM or frame capture was incomplete in at least one observation."),
-        scripts: dimension(keyed(before.scripts.items.map(scriptProjection), (item) => item.script_key), keyed(after.scripts.items.map(scriptProjection), (item) => item.script_key), sectionsComplete(before, ["scripts"]) &&
+        scripts: compareDimension(keyed(before.scripts.items.map(scriptProjection), (item) => item.script_key), keyed(after.scripts.items.map(scriptProjection), (item) => item.script_key), sectionsComplete(before, ["scripts"]) &&
             sectionsComplete(after, ["scripts"]), "Script inventory was incomplete in at least one observation."),
-        resources: dimension(keyed(before.resources, (item) => item.resource_key), keyed(after.resources, (item) => item.resource_key), sectionsComplete(before, ["resources"]) &&
+        resources: compareDimension(keyed(before.resources, (item) => item.resource_key), keyed(after.resources, (item) => item.resource_key), sectionsComplete(before, ["resources"]) &&
             sectionsComplete(after, ["resources"]), "Resource inventory was incomplete in at least one observation."),
-        network: dimension(networkMap(before), networkMap(after), sectionsComplete(before, ["network_requests"]) &&
-            sectionsComplete(after, ["network_requests"]), "Network capture is attach-window limited or incomplete."),
-        metadata: dimension(singleton("metadata", digest(metadataProjection(before))), singleton("metadata", digest(metadataProjection(after))), sectionsComplete(before, ["metadata"]) &&
+        network: networkDimension(before, after),
+        metadata: compareDimension(singleton("metadata", digestCanonicalValue(metadataProjection(before))), singleton("metadata", digestCanonicalValue(metadataProjection(after))), sectionsComplete(before, ["metadata"]) &&
             sectionsComplete(after, ["metadata"]), "Safe metadata capture was incomplete in at least one observation."),
-        webmcp: dimension(webMcpMap(input.before.webmcp), webMcpMap(input.after.webmcp), webMcpComplete(input.before.webmcp) && webMcpComplete(input.after.webmcp), "WebMCP discovery was unavailable or incomplete in at least one capture."),
+        webmcp: compareDimension(webMcpMap(input.before.webmcp), webMcpMap(input.after.webmcp), webMcpComplete(input.before.webmcp) && webMcpComplete(input.after.webmcp), "WebMCP discovery was unavailable or incomplete in at least one capture."),
         accessibility: accessibilityDimension(before, after),
         storage: storageDimension(before, after),
     };
 };
-const keyed = (values, identity) => new Map(values.map((value) => [identity(value), digest(value)]));
-const networkMap = (inspection) => {
+const keyed = (values, identity) => new Map(values.map((value) => [identity(value), digestCanonicalValue(value)]));
+const bodyShapesSelected = (inspection) => !inspection.completeness.excluded.some(({ section, reason }) => section === "json_body_shapes" && reason === "not_approved") &&
+    (inspection.network.requests.length === 0 ||
+        inspection.network.requests.some(({ body_shapes }) => body_shapes.status !== "not_approved"));
+const networkIdentity = (request) => `net_${digestCanonicalValue({ method: request.method, url: request.url, resource_type: request.resource_type })}`;
+const networkDimension = (before, after) => {
+    const selected = bodyShapesSelected(before) && bodyShapesSelected(after);
+    const sources = new Map();
+    if (selected) {
+        const observedSources = (inspection) => {
+            const result = new Map();
+            for (const request of inspection.network.requests) {
+                const identity = networkIdentity(request);
+                const previous = result.get(identity);
+                result.set(identity, {
+                    request: previous?.request !== false && request.body_shapes.request !== null,
+                    response: previous?.response !== false &&
+                        request.body_shapes.response !== null,
+                });
+            }
+            return result;
+        };
+        const left = observedSources(before);
+        const right = observedSources(after);
+        for (const [identity, coverage] of left) {
+            const next = right.get(identity);
+            sources.set(identity, {
+                request: coverage.request && next?.request === true,
+                response: coverage.response && next?.response === true,
+            });
+        }
+    }
+    const shapesComplete = !selected ||
+        [before, after].every((inspection) => sectionsComplete(inspection, ["json_body_shapes"]) &&
+            inspection.network.requests.every(({ body_shapes }) => body_shapes.status === "included"));
+    return compareDimension(networkMap(before, sources), networkMap(after, sources), sectionsComplete(before, ["network_requests"]) &&
+        sectionsComplete(after, ["network_requests"]) &&
+        shapesComplete, "Network capture or selected JSON body-shape coverage is attach-window limited, unavailable, or incomplete.");
+};
+const networkMap = (inspection, sources) => {
     const grouped = new Map();
     for (const request of inspection.network.requests) {
-        const identity = `net_${digest({
-            method: request.method,
-            url: request.url,
-            resource_type: request.resource_type,
-        })}`;
+        const identity = networkIdentity(request);
+        const shapes = sources.get(identity);
         const values = grouped.get(identity) ?? [];
         values.push({
             status: request.status,
@@ -119,13 +153,18 @@ const networkMap = (inspection) => {
             encoded_data_length: request.encoded_data_length,
             redirects: (request.redirects ?? []).map(({ request_timestamp: _requestTimestamp, redirect_event_timestamp: _redirectEventTimestamp, ...redirect }) => redirect),
             initiator: request.initiator,
-            body_shapes: request.body_shapes,
+            ...(shapes?.request === true
+                ? { request_shape: request.body_shapes.request }
+                : {}),
+            ...(shapes?.response === true
+                ? { response_shape: request.body_shapes.response }
+                : {}),
         });
         grouped.set(identity, values);
     }
     return new Map([...grouped].map(([identity, values]) => [
         identity,
-        digest(values.map((value) => digest(value)).sort()),
+        digestCanonicalValue(values.map((value) => digestCanonicalValue(value)).sort()),
     ]));
 };
 const webMcpMap = (discovery) => discovery === null
@@ -147,7 +186,9 @@ const incompleteSections = (completeness) => new Set([
 const domProjection = (inspection) => ({
     frames: inspection.frames
         .map(({ url, origin }) => ({ url, origin }))
-        .sort((left, right) => left.url.localeCompare(right.url)),
+        .sort((left, right) => compareUnicodeCodePoints(left.url, right.url) ||
+        compareUnicodeCodePoints(left.origin ?? "", right.origin ?? "") ||
+        Number(left.origin !== null) - Number(right.origin !== null)),
     nodes: inspection.dom.nodes.map(({ index: _index, ...node }) => node),
 });
 const scriptProjection = (script) => ({
@@ -162,17 +203,18 @@ const scriptProjection = (script) => ({
 const metadataProjection = (inspection) => ({
     responses: inspection.metadata.responses
         .map(({ request_id: _requestId, ...response }) => response)
-        .map((value) => digest(value))
+        .map((value) => digestCanonicalValue(value))
+        .sort(),
+    dom_urls: inspection.metadata.dom_urls
+        .map((value) => digestCanonicalValue(value))
         .sort(),
-    dom_urls: inspection.metadata.dom_urls.map((value) => digest(value)).sort(),
     agent_hints: inspection.metadata.agent_hints
-        .map((value) => digest(value))
+        .map((value) => digestCanonicalValue(value))
         .sort(),
     excluded_dom_urls: inspection.metadata.excluded_dom_urls,
     headers_allowlisted: inspection.metadata.headers_allowlisted,
 });
 const singleton = (key, value) => new Map([[key, value]]);
-const digest = (value) => canonicalDigest(value);
 const accessibilityComparable = (inspection) => {
     const text = inspection.accessibility.text_capture.status === "included" &&
         inspection.accessibility.text_capture.excluded_fields === 0;
@@ -209,7 +251,7 @@ const storageMap = (storage, includeKeys, includeUsage, fingerprintIdentities) =
     const map = new Map([
         [
             "storage:summary",
-            digest({
+            digestCanonicalValue({
                 origin: storage.origin,
                 values_redacted: storage.values_redacted,
                 ...(includeUsage
@@ -225,7 +267,7 @@ const storageMap = (storage, includeKeys, includeUsage, fingerprintIdentities) =
         return map;
     const add = (kind, keys) => {
         for (const key of keys) {
-            map.set(`storage:${kind}:${key}`, digest(key));
+            map.set(`storage:${kind}:${key}`, digestCanonicalValue(key));
         }
     };
     add("local_storage", storage.local_storage_keys);
@@ -236,7 +278,7 @@ const storageMap = (storage, includeKeys, includeUsage, fingerprintIdentities) =
         const identity = `${fingerprint.scope}:${fingerprint.identity_sha256}`;
         if (!fingerprintIdentities.has(identity))
             continue;
-        map.set(`storage:content:${identity}`, digest(fingerprint.value_sha256));
+        map.set(`storage:content:${identity}`, digestCanonicalValue(fingerprint.value_sha256));
     }
     return map;
 };

package/dist/domain/webCaptureDiffSchemas.js

@@ -50,12 +50,6 @@ const dimensionSchema = z.union([
         reason: z.string(),
     }),
 ]);
-const legacyUnknownDimension = {
-    status: "unknown",
-    total_changes: 0,
-    changes: [],
-    reason: "Dimension was not recorded by this version 1 capture diff.",
-};
 /** Completeness-aware changes across stable browser evidence dimensions. */
 export const webCaptureDiffSchema = z
     .object({
@@ -69,8 +63,8 @@ export const webCaptureDiffSchema = z
         network: dimensionSchema,
         metadata: dimensionSchema,
         webmcp: dimensionSchema,
-        accessibility: dimensionSchema.default(legacyUnknownDimension),
-        storage: dimensionSchema.default(legacyUnknownDimension),
+        accessibility: dimensionSchema,
+        storage: dimensionSchema,
     }),
     limitations: z.array(z.string()),
 })

package/dist/domain/webInventory.js

@@ -1,5 +1,6 @@
 import { createHash } from "node:crypto";
 import canonicalize from "canonicalize";
+import { compareUnicodeCodePoints } from "./unicodeCodePointOrder.js";
 /** Assign deterministic identities to a bounded resource inventory. */
 export const stableWebResources = (resources) => {
     const keyed = resources.map((resource) => ({
@@ -8,8 +9,8 @@ export const stableWebResources = (resources) => {
     }));
     return [
         ...new Map(keyed.map((resource) => [resource.resource_key, resource])).values(),
-    ].sort((left, right) => left.resource_key.localeCompare(right.resource_key) ||
-        left.url.localeCompare(right.url));
+    ].sort((left, right) => compareUnicodeCodePoints(left.resource_key, right.resource_key) ||
+        compareUnicodeCodePoints(left.url, right.url));
 };
 /** Reconcile one script with resource-tree observations without fuzzy matching. */
 export const reconcileWebScript = (script, resources) => {

package/dist/domain/webMcpDiscovery.js

@@ -2,8 +2,8 @@ import { z } from "zod";
 import { browserCompletenessSchema } from "./browserCompleteness.js";
 import { browserAllowedOriginsSchema, browserEndpointSchema, } from "./browserObservation.js";
 import { browserVersionSchema } from "./browserObservationSchemas.js";
-import { jsonShapeSchema } from "./jsonShape.js";
-import { prefixedDigestSchema } from "./../domain/digests.js";
+import { jsonValueSchema } from "./jsonValue.js";
+import { digestSchema, prefixedDigestSchema } from "./../domain/digests.js";
 /** Input for passive discovery of page-registered WebMCP tools. */
 export const discoverWebMcpToolsInputSchema = z.strictObject({
     cdp_endpoint: browserEndpointSchema,
@@ -19,7 +19,8 @@ const webMcpToolSchema = z.object({
     frame_url: z.string(),
     owner_origin: z.string(),
     declaration_kind: z.enum(["declarative", "imperative"]),
-    input_schema_shape: jsonShapeSchema.nullable(),
+    input_schema: jsonValueSchema.nullable(),
+    input_schema_sha256: digestSchema.nullable(),
     annotations: z.object({
         read_only: z.boolean().nullable(),
         untrusted_content: z.boolean().nullable(),

package/dist/domain/webScriptExport.js

@@ -24,7 +24,7 @@ const sourceSchema = z.discriminatedUnion("kind", [
     }),
     z.strictObject({
         kind: z.literal("scenario-response"),
-        transaction_id: z.string().nullable(),
+        transaction_id: z.string().min(1),
         request_sequence: z.number().int().min(1),
         response_sequence: z.number().int().min(1).nullable(),
         status: z.number().nullable(),

package/dist/dotnet/ManagedMemberInstructionDecoder.js

@@ -1,4 +1,3 @@
-const opcode = (code) => OPCODES.get(code);
 const PREFIX_OPCODES = new Set([
     "unaligned.",
     "volatile.",
@@ -361,7 +360,7 @@ export const decodeInstructions = (il) => {
             const first = il.readUInt8(offset);
             offset += 1;
             const code = first === 0xfe ? 0xfe00 + il.readUInt8(offset++) : first;
-            const descriptor = opcode(code);
+            const descriptor = OPCODES.get(code);
             if (descriptor === undefined) {
                 issue = `Unsupported CIL opcode 0x${code.toString(16)} at IL offset ${String(start)}`;
                 break;

package/dist/dotnet/ManagedStaticProvider.js

@@ -2,7 +2,8 @@ import { createHash } from "node:crypto";
 import { createReadStream } from "node:fs";
 import { readFile } from "node:fs/promises";
 import { createAnalysisExecution, } from "../application/AnalysisProvider.js";
-import { MANAGED_STATIC_PROVIDER_IDENTITY as IDENTITY, managedStaticCapabilities, } from "./ManagedStaticProviderMetadata.js";
+import { managedStaticCapabilities } from "./ManagedStaticProviderMetadata.js";
+import { MANAGED_STATIC_PROVIDER } from "../application/InvestigationProviders.js";
 import { MANAGED_TOOL_CONTRACTS, managedTargetInputSchema, } from "../contracts/managed/managedToolContracts.js";
 import { AnalysisCancelledError, AnalysisCapabilityUnavailableError, } from "../domain/analysisErrorCore.js";
 import { EvidenceIntegrityError } from "../domain/evidenceErrors.js";
@@ -15,7 +16,7 @@ import { inspectManagedNativeBoundariesBytes } from "./ManagedNativeBoundaryInsp
 export class ManagedStaticProvider {
     #capabilities = managedStaticCapabilities();
     identity() {
-        return IDENTITY;
+        return MANAGED_STATIC_PROVIDER;
     }
     capabilities() {
         return this.#capabilities;
@@ -32,11 +33,11 @@ class ManagedStaticClient {
     }
     async execute(operation, parameters, options) {
         if (operation === "health")
-            return ok(createAnalysisExecution(null, IDENTITY));
+            return ok(createAnalysisExecution(null, MANAGED_STATIC_PROVIDER));
         if (!isManagedOperation(operation))
-            return err(new AnalysisCapabilityUnavailableError(IDENTITY.id, operation, "Operation is not implemented by the managed static provider."));
+            return err(new AnalysisCapabilityUnavailableError(MANAGED_STATIC_PROVIDER.id, operation, "Operation is not implemented by the managed static provider."));
         if (this.target.format !== "pe")
-            return err(new AnalysisCapabilityUnavailableError(IDENTITY.id, operation, `Managed static triage requires a PE target; observed ${this.target.format}.`));
+            return err(new AnalysisCapabilityUnavailableError(MANAGED_STATIC_PROVIDER.id, operation, `Managed static triage requires a PE target; observed ${this.target.format}.`));
         try {
             if (options?.signal?.aborted === true)
                 return err(new AnalysisCancelledError(operation));
@@ -51,7 +52,7 @@ class ManagedStaticClient {
                 throw new TypeError("Managed snapshot bytes are unavailable");
             this.#snapshotBytes = bytes;
             const result = inspectManagedOperation(operation, parameters, bytes, this.target);
-            return ok(createAnalysisExecution(result, IDENTITY, {
+            return ok(createAnalysisExecution(result, MANAGED_STATIC_PROVIDER, {
                 rawResult: null,
                 limitations: result.limitations,
                 subject: this.target,
@@ -61,7 +62,9 @@ class ManagedStaticClient {
         catch (cause) {
             if (options?.signal?.aborted === true)
                 return err(new AnalysisCancelledError(operation));
-            return err(new ProviderAdapterError(IDENTITY.id, operation, { cause }));
+            return err(new ProviderAdapterError(MANAGED_STATIC_PROVIDER.id, operation, {
+                cause,
+            }));
         }
     }
     close() {

package/dist/dotnet/ManagedStaticProviderMetadata.js

@@ -1,11 +1,8 @@
 import { MANAGED_STATIC_PROVIDER } from "../application/InvestigationProviders.js";
 import { MANAGED_TOOL_CONTRACTS, } from "../contracts/managed/managedToolContracts.js";
-/** Identity of execution-free managed metadata observations. */
-export const MANAGED_STATIC_PROVIDER_IDENTITY = Object.freeze(MANAGED_STATIC_PROVIDER);
-const IDENTITY = MANAGED_STATIC_PROVIDER_IDENTITY;
 /** Declare managed metadata coverage without opening or loading an assembly. */
 export const managedStaticCapabilities = () => Object.freeze(MANAGED_TOOL_CONTRACTS.map((contract) => Object.freeze({
-    provider: IDENTITY,
+    provider: MANAGED_STATIC_PROVIDER,
     operation: contract.name,
     available: true,
     reason: null,

package/dist/filesystem/RegularFile.js

@@ -0,0 +1,41 @@
+import { constants } from "node:fs";
+import { open } from "node:fs/promises";
+/** Identifies a selected path that cannot be read as one regular file. */
+export class NonRegularFileReadError extends Error {
+    path;
+    code;
+    constructor(path, directory) {
+        super(`Selected input must be a regular file: ${path}`);
+        this.path = path;
+        this.name = "NonRegularFileReadError";
+        this.code = directory ? "EISDIR" : "ENOTFILE";
+    }
+}
+/** Open and verify the selected file descriptor without blocking on pipes. */
+export const openRegularFile = async (path, options) => {
+    options.signal?.throwIfAborted();
+    const handle = await open(path, constants.O_RDONLY |
+        (constants.O_NONBLOCK ?? 0) |
+        (constants.O_NOCTTY ?? 0) |
+        (options.symlinks === "reject" ? (constants.O_NOFOLLOW ?? 0) : 0));
+    try {
+        options.signal?.throwIfAborted();
+        const metadata = await handle.stat();
+        options.signal?.throwIfAborted();
+        if (!metadata.isFile())
+            throw new NonRegularFileReadError(path, metadata.isDirectory());
+        return handle;
+    }
+    catch (cause) {
+        await handle.close().catch(() => undefined);
+        throw cause;
+    }
+};
+/** Compare one regular file's identity and mutable metadata across a read. */
+export const sameRegularFileState = (expected, observed) => observed.isFile() &&
+    expected.dev === observed.dev &&
+    expected.ino === observed.ino &&
+    expected.size === observed.size &&
+    expected.mode === observed.mode &&
+    expected.mtimeMs === observed.mtimeMs &&
+    expected.ctimeMs === observed.ctimeMs;

package/dist/generatedPackageMetadata.js

@@ -1,7 +1,7 @@
 /** Generated from package.json and package-lock.json; do not edit. */
 export const PACKAGE_METADATA = {
     name: "rea-agents",
-    version: "6.2.0", // x-release-please-version
+    version: "6.3.0", // x-release-please-version
     serverSdkVersion: "2.3.1",
     clientSdkVersion: "2.3.1",
     coreSdkVersion: "2.3.1",

package/dist/ghidra/GhidraClient.js

@@ -10,6 +10,7 @@ import { ProviderRunLineage } from "../process/ProviderRunLineage.js";
 import { ProviderProcessSupervisor, } from "../process/ProviderProcess.js";
 import { DEFAULT_GHIDRA_STARTUP_TIMEOUT_MS } from "../config/ghidraStartupTimeout.js";
 import { createGhidraDiagnostics } from "./GhidraDiagnostics.js";
+import { GhidraLaunchError } from "./GhidraLauncher.js";
 import { GhidraResponseBuffer } from "./GhidraResponseBuffer.js";
 import { GhidraResponseRouter } from "./GhidraResponseRouter.js";
 import { GhidraRequestQueue } from "./GhidraRequestQueue.js";
@@ -290,8 +291,17 @@ export class GhidraClient {
         }, { signal: deadline.signal })
             .catch((cause) => err(this.#failure("start", "Ghidra launcher failed", cause)));
         if (!launched.ok) {
+            const partialLaunch = launched.error instanceof GhidraLaunchError
+                ? launched.error.partialLaunch
+                : undefined;
+            if (partialLaunch !== undefined) {
+                this.#launch = partialLaunch;
+                this.#process = new ProviderProcessSupervisor(partialLaunch, {
+                    onDiagnostic: (event) => this.#onProcessDiagnostic(event),
+                });
+            }
             const failure = deadline.signal.aborted
-                ? this.#interruptionFailure(deadline)
+                ? this.#interruptionFailure(deadline, launched.error)
                 : launched.error instanceof GhidraSessionError
                     ? launched.error
                     : this.#failure("start", launched.error.message, launched.error);
@@ -519,10 +529,10 @@ export class GhidraClient {
         const failure = this.#interruptionFailure(deadline);
         return this.#startupFailure(failure);
     }
-    #interruptionFailure(deadline) {
+    #interruptionFailure(deadline, cause) {
         return deadline.interruption === "cancelled"
-            ? this.#failure("cancelled", "Ghidra startup was cancelled")
-            : this.#failure("timeout", "Ghidra startup deadline elapsed", undefined, {
+            ? this.#failure("cancelled", "Ghidra startup was cancelled", cause)
+            : this.#failure("timeout", "Ghidra startup deadline elapsed", cause, {
                 timeoutMs: deadline.timeoutMs,
             });
     }

package/dist/ghidra/GhidraInstallation.js

@@ -1,14 +1,84 @@
 import { snapshotEnvironment } from "../process/snapshotEnvironment.js";
 import { spawnSync } from "node:child_process";
 import { constants } from "node:fs";
-import { accessSync, readFileSync } from "node:fs";
+import { accessSync, closeSync, fstatSync, openSync, readFileSync, readSync, statSync, } from "node:fs";
 import { posix, win32 } from "node:path";
+import { parseExecutableHeader, } from "../domain/binaryTarget.js";
 import { ghidraApplicationProperties, ghidraJavaMajorAccepted, ghidraJavaRangeLabel, ghidraJavaRequirement, ghidraReleaseAccepted, ghidraReleaseCompatibility, ghidraReleaseLine, ghidraVersionDetail, SUPPORTED_GHIDRA_JAVA_MAJOR, SUPPORTED_GHIDRA_VERSION, } from "./GhidraInstallationPolicy.js";
 const NATIVE_PLATFORMS = {
     linux: { x64: "linux_x86_64", arm64: "linux_arm_64" },
     darwin: { x64: "mac_x86_64", arm64: "mac_arm_64" },
     win32: { x64: "win_x86_64" },
 };
+/** Executable format each supported host runs its own Ghidra native tools as. */
+const NATIVE_TOOL_FORMATS = {
+    linux: "elf",
+    darwin: "mach-o",
+    win32: "pe",
+};
+/** Node architecture identifiers as the executable-header parser reports them. */
+const NATIVE_ARCHITECTURES = [
+    { node: "x64", binary: "x86_64" },
+    { node: "ia32", binary: "x86" },
+    { node: "arm", binary: "arm" },
+    { node: "arm64", binary: "arm64" },
+];
+/** Bound installation discovery reads; larger headers remain unknown. */
+const EXECUTABLE_HEADER_PROBE_BYTES = 4096;
+/**
+ * Judge a native decompiler by its own executable header instead of the
+ * directory name that admits it.
+ *
+ * Only a header that positively contradicts the host is `incompatible`. An
+ * absent, unreadable, truncated, or unrecognized header stays `unknown`, so a
+ * file the other checks already accept is never refused on missing evidence.
+ */
+const assessNativeDecompiler = (path, platform, architecture, probe) => {
+    const expectedFormat = NATIVE_TOOL_FORMATS[platform];
+    const expectedArchitecture = NATIVE_ARCHITECTURES.find(({ node }) => node === architecture)?.binary;
+    if (expectedFormat === undefined || expectedArchitecture === undefined)
+        return {
+            status: "unknown",
+            detail: `${path} is executable, but no native tool format is defined for ${platform}/${architecture}`,
+        };
+    let parsed = probe === undefined
+        ? undefined
+        : parseExecutableHeader(probe.bytes, architecture, probe.size);
+    if (probe !== undefined && parsed !== undefined && !parsed.ok) {
+        // FAT parsing selects a host slice. A validated foreign slice can still
+        // prove that its complete architecture table excludes this host. If the
+        // host is listed but its slice is malformed, preserve the unknown outcome.
+        for (const { node } of NATIVE_ARCHITECTURES) {
+            if (node === architecture)
+                continue;
+            const alternative = parseExecutableHeader(probe.bytes, node, probe.size);
+            if (alternative.ok &&
+                !alternative.value.availableArchitectures.includes(expectedArchitecture)) {
+                parsed = alternative;
+                break;
+            }
+        }
+    }
+    if (parsed === undefined || !parsed.ok)
+        return {
+            status: "unknown",
+            detail: `${path} is executable, but its executable format for ${platform}/${architecture} could not be established`,
+        };
+    const observed = `${parsed.value.format} ${parsed.value.architecture}`;
+    const expected = `${expectedFormat} ${expectedArchitecture}`;
+    if (observed === expected)
+        return {
+            status: "compatible",
+            detail: `${path} reports ${observed}, which matches ${platform}/${architecture}`,
+        };
+    const nativeDirectory = NATIVE_PLATFORMS[platform]?.[architecture];
+    const executable = platform === "win32" ? "decompile.exe" : "decompile";
+    return {
+        status: "incompatible",
+        detail: `${path} reports ${observed}, but ${platform}/${architecture} requires ${expected}`,
+        remediation: `Provide an executable Ghidra/Features/Decompiler/os/${nativeDirectory ?? "<platform>"}/${executable} built for ${expected}, or its build/os equivalent. REA does not build or install native tools.`,
+    };
+};
 /** Inspect an installation without importing a target or modifying Ghidra. */
 export const inspectGhidraInstallation = (options, host = systemGhidraInstallationHost()) => {
     const platform = options.platform ?? process.platform;
@@ -137,14 +207,7 @@ 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.",
     }),
-    installationCheck({
-        name: "native_decompiler",
-        passed: coordinates.nativeDecompilerPath !== null,
-        code: "executable_missing",
-        detail: coordinates.nativeDecompilerPath ??
-            `Matching native decompiler for ${platform}/${architecture} was not found`,
-        remediation: `Provide an executable Ghidra/Features/Decompiler/os/${NATIVE_PLATFORMS[platform]?.[architecture] ?? "<platform>"}/${platform === "win32" ? "decompile.exe" : "decompile"}, or its build/os equivalent. REA does not build or install native tools.`,
-    }),
+    nativeDecompilerCheck({ coordinates, platform, architecture, host }),
     javaCheck(coordinates.java, coordinates.javaCommand, javaHome, coordinates.properties),
 ];
 /**
@@ -226,6 +289,23 @@ const installationCheck = (options) => options.passed
         detail: options.detail,
         remediation: options.remediation,
     };
+/** Require a present native decompiler without positively incompatible bytes. */
+const nativeDecompilerCheck = ({ coordinates, platform, architecture, host, }) => {
+    const path = coordinates.nativeDecompilerPath;
+    const compatibility = path === null
+        ? undefined
+        : assessNativeDecompiler(path, platform, architecture, host.executableHeader?.(path));
+    return installationCheck({
+        name: "native_decompiler",
+        passed: path !== null && compatibility?.status !== "incompatible",
+        code: "executable_missing",
+        detail: compatibility?.detail ??
+            `Matching native decompiler for ${platform}/${architecture} was not found`,
+        remediation: compatibility?.status === "incompatible"
+            ? compatibility.remediation
+            : `Provide an executable Ghidra/Features/Decompiler/os/${NATIVE_PLATFORMS[platform]?.[architecture] ?? "<platform>"}/${platform === "win32" ? "decompile.exe" : "decompile"}, or its build/os equivalent. REA does not build or install native tools.`,
+    });
+};
 const versionCheck = (properties) => {
     const raw = properties?.providerVersion;
     return installationCheck({
@@ -280,10 +360,31 @@ const systemGhidraInstallationHost = () => ({
             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);
+        }
+    },
     executable(path) {
         try {
             accessSync(path, constants.X_OK);
-            return true;
+            return statSync(path).isFile();
         }
         catch (cause) {
             // best-effort cleanup: optional executable probing; failure means missing.