rea-agents 6.4.0 → 6.7.0

package/dist/ghidra/GhidraMipsProfile.js

@@ -1,3 +1,82 @@
+const MIPS_FP_ABI_SOFT = 3;
+const MIPS_ET_REL = 1;
+const MIPS_ET_EXEC = 2;
+const MIPS_ET_DYN = 3;
+const MIPS16_HEADER_ASE = 0x04000000;
+/** A distinct compressed shared-image shape; admission still checks every declaration. */
+const isGhidraMips16SharedTarget = (target) => target.kind === "executable" &&
+    target.architecture === "mips" &&
+    target.mips.type === MIPS_ET_DYN &&
+    (target.mips.flags & 0x0f000000) === MIPS16_HEADER_ASE;
+/** Derive the verified MIPS32 import pin from this target's observed byte order. */
+export const ghidraMipsLanguageOverride = (target) => (isGhidraMips16SharedTarget(target) || hasLegacyMipsHeaderShape(target)) &&
+    ghidraMipsUnsupportedReason(target) === null &&
+    target.architecture === "mips"
+    ? {
+        languageId: `MIPS:${target.mips.byteOrder === "little" ? "LE" : "BE"}:32:default`,
+        compilerSpecId: "default",
+    }
+    : undefined;
+/**
+ * Recordless legacy ELF32 MIPS admission: the header declares no ABI field and
+ * carries no ABI flags record, so o32 is an analysis assumption derived from
+ * ELF32/ET_EXEC structure, never a declared fact. Ghidra's header
+ * auto-selection picks a 64-bit language for exactly these files, so the lane
+ * pins the 32-bit language instead.
+ */
+const hasLegacyMipsHeaderShape = (target) => {
+    if (target.kind !== "executable" ||
+        target.architecture !== "mips" ||
+        target.format !== "elf" ||
+        target.mips === undefined)
+        return false;
+    const { flags, abiFlags, limitations } = target.mips;
+    const arch = flags & 0xf0000000;
+    return (
+    // The lane and its verification cover executable firmware images only;
+    // recordless relocatable objects stay outside the inferred-o32 assumption.
+    target.mips.elfClass === 32 &&
+        target.mips.type === MIPS_ET_EXEC &&
+        (arch === 0x50000000 || arch === 0x70000000) &&
+        (flags & 0x0000f000) === 0 &&
+        (flags & 0x20) === 0 &&
+        // EF_MIPS_ABI_ON32 (bit 0x40) declares the old n32 ABI; it is not an
+        // unspecified-ABI header and must not inherit the o32 assumption.
+        (flags & 0x40) === 0 &&
+        (flags & 0x100) === 0 &&
+        // Undefined means the record was not inspected; only an inspected
+        // absence establishes the recordless legacy admission. An inspection
+        // that could not examine every declaration source stays unknown.
+        abiFlags === null &&
+        (limitations === undefined || limitations.length === 0));
+};
+/** Return a refusal for GNU ABI attributes this existing MIPS lane cannot model. */
+/**
+ * Every MIPS lane, including PSP, needs every ABI declaration source examined:
+ * headers outside the captured file may hold declarations that would refuse it.
+ */
+export const ghidraMipsIncompleteDeclarationsReason = (metadata) => (metadata.limitations?.length ?? 0) > 0
+    ? [
+        "MIPS ABI declaration inspection is incomplete; unsupported attributes or conflicting declaration sources may remain unknown.",
+        ...(metadata.limitations ?? []),
+    ].join(" ")
+    : null;
+export const ghidraMipsGnuAttributesUnsupportedReason = (metadata) => {
+    const attributes = metadata.gnuAttributes;
+    if (attributes === undefined)
+        return "GNU MIPS ABI attribute inspection is unavailable; provider selection cannot treat it as absent.";
+    if (attributes === null)
+        return null;
+    if (attributes.msa !== null && attributes.msa !== 0)
+        return "The GNU MIPS MSA ABI attribute declares an unsupported or unknown vector argument ABI.";
+    if (metadata.abiFlags === null &&
+        attributes.fpAbi !== null &&
+        attributes.fpAbi !== 0 &&
+        attributes.fpAbi !== 1 &&
+        attributes.fpAbi !== 5)
+        return "Without a MIPS ABI flags record, the GNU floating-point ABI attribute must be absent, any, double-precision, or FPXX for the verified recordless lane.";
+    return null;
+};
 /** Keep family recognition separate from the deliberately bounded Ghidra lane. */
 export const ghidraMipsUnsupportedReason = (target) => {
     if (target.kind !== "executable" || target.architecture !== "mips")
@@ -5,24 +84,74 @@ export const ghidraMipsUnsupportedReason = (target) => {
     const metadata = target.mips;
     if (target.format !== "elf" || metadata === undefined)
         return "MIPS analysis requires ELF header metadata; a family name alone does not select an ISA or ABI.";
+    const shared = isGhidraMips16SharedTarget(target);
     if (metadata.elfClass !== 32)
         return "This Ghidra MIPS lane supports ELF32 only; MIPS64 and n64 remain unsupported.";
-    if (metadata.type !== 2)
-        return "This Ghidra MIPS lane supports ET_EXEC only; relocatable objects, shared images and PSP PRX need separate load verification.";
-    if ((metadata.flags & 0x0f000000) !== 0)
+    const gnuAttributesReason = ghidraMipsGnuAttributesUnsupportedReason(metadata);
+    if (gnuAttributesReason !== null)
+        return gnuAttributesReason;
+    if (metadata.type !== MIPS_ET_EXEC &&
+        metadata.type !== MIPS_ET_REL &&
+        !shared)
+        return "This Ghidra MIPS lane supports ET_EXEC and ET_REL only; shared images and PSP PRX need separate load verification.";
+    if ((metadata.flags & 0x0f000000) !== 0 && !shared)
         return "MIPS16, microMIPS and other ASE encodings are outside this standard-instruction MIPS lane.";
     if ((metadata.flags & 0x00ff0000) !== 0)
         return "Machine-specific MIPS variants, including PSP Allegrex, need a separately supported processor profile.";
-    if ((metadata.flags & 0xf0000000) !== 0x70000000)
-        return "This Ghidra MIPS lane requires EF_MIPS_ARCH_32R2; other ISA revisions need separate verification.";
+    const arch = metadata.flags & 0xf0000000;
+    if (arch !== 0x70000000 && arch !== 0x50000000)
+        return "This Ghidra MIPS lane requires EF_MIPS_ARCH_32R2 or a recordless legacy EF_MIPS_ARCH_32 header; other ISA revisions need separate verification.";
+    const recordlessShape = (metadata.flags & 0x0000f000) === 0 &&
+        (metadata.flags & 0x20) === 0 &&
+        metadata.abiFlags === null;
+    if (recordlessShape) {
+        if ((metadata.flags & 0x100) !== 0)
+            return "EF_MIPS_32BITMODE declares code for a 64-bit processor in 32-bit mode; it is outside the recordless MIPS32 admission.";
+        if ((metadata.flags & 0x40) !== 0)
+            return "EF_MIPS_ABI_ON32 declares the n32 ABI; recordless headers carrying it are outside the recordless legacy admission.";
+        if ((metadata.flags & 0x00000200) !== 0)
+            return "EF_MIPS_FP64 requires separate verification of 64-bit floating-point register semantics in this Ghidra lane.";
+        if ((metadata.flags & 0x00000400) !== 0)
+            return "EF_MIPS_NAN2008 requires separate verification of NaN encoding semantics in this Ghidra lane.";
+        if (hasLegacyMipsHeaderShape(target))
+            return null;
+        // A recordless relocatable object is not an incomplete inspection; the
+        // lane is scoped to executable firmware images by design.
+        if (metadata.type !== MIPS_ET_EXEC)
+            return "The recordless legacy admission covers ET_EXEC firmware images only; recordless relocatable objects need their own verified build, and the declared-ABI lane requires an ABI flags record.";
+        // The inspection could not examine every ABI declaration source, so the
+        // recordless admission is not established for this header.
+        return [
+            "This recordless legacy admission requires a complete ABI-record inspection; ABI declarations in unavailable headers remain unknown.",
+            ...(metadata.limitations ?? []),
+        ].join(" ");
+    }
     if ((metadata.flags & 0x0000f000) !== 0x00001000 ||
         (metadata.flags & 0x20) !== 0)
-        return "This Ghidra MIPS lane requires an explicit o32 ABI; unspecified, n32 and EABI targets remain unsupported.";
+        return "This Ghidra MIPS lane requires an explicit o32 ABI or a recordless legacy header with an unspecified ABI; n32, EABI and mixed declarations remain unsupported.";
+    if (arch !== 0x70000000)
+        return "This Ghidra MIPS lane requires EF_MIPS_ARCH_32R2 for headers that declare an ABI; EF_MIPS_ARCH_32 headers are admitted only through the recordless legacy admission.";
     if ((metadata.flags & 0x00000200) !== 0)
         return "EF_MIPS_FP64 requires separate verification of 64-bit floating-point register semantics in this Ghidra lane.";
     if ((metadata.flags & 0x00000400) !== 0)
         return "EF_MIPS_NAN2008 requires separate verification of NaN encoding semantics in this Ghidra lane.";
+    if (shared) {
+        if ((metadata.flags & 0x40) !== 0)
+            return "EF_MIPS_ABI_ON32 declares an unverified ABI for the MIPS16 shared-image lane.";
+        const load = metadata.sharedLoad;
+        if (load === undefined || load.status !== "complete")
+            return `MIPS16 shared images require complete dynamic relocation inspection. ${load?.reason ?? "The source declarations have not been inspected."}`;
+        if (load.relocationTypes.some((type) => type !== 0 && type !== 3))
+            return "This MIPS16 shared-image lane verifies R_MIPS_NONE and R_MIPS_REL32 only; other dynamic relocation types require separate verification.";
+        if (load.symbolRelativeCount !== 0)
+            return "Symbol-bearing R_MIPS_REL32 is unsupported: Ghidra normalizes MIPS16 function addresses and can lose the source function-pointer mode tag. Symbol-index-zero REL32 is verified separately.";
+    }
+    const incomplete = ghidraMipsIncompleteDeclarationsReason(metadata);
+    if (incomplete !== null)
+        return incomplete;
     const abi = metadata.abiFlags;
+    if (shared && abi === null && (metadata.limitations?.length ?? 0) === 0)
+        return null; // Inspected absence leaves FP semantics unknown, never inferred.
     if (abi === undefined || abi === null)
         return [
             "This Ghidra MIPS lane requires an inspected ABI flags record; header flags alone do not establish the floating-point ABI.",
@@ -32,23 +161,87 @@ export const ghidraMipsUnsupportedReason = (target) => {
         return "This Ghidra MIPS lane requires ABI flags version 0; newer record semantics are unsupported.";
     if (abi.isaLevel !== 32 || abi.isaRevision !== 2)
         return "MIPS ABI flags must agree with the declared MIPS32r2 ISA.";
-    if (abi.gprSize !== 1 || abi.cpr1Size !== 1 || abi.cpr2Size !== 0)
-        return "This Ghidra MIPS lane requires 32-bit GPR/CPR1 and no CPR2; other register modes need separate verification.";
-    if (abi.fpAbi !== 1 && abi.fpAbi !== 5)
-        return "This Ghidra MIPS lane admits double-precision or FPXX ABI declarations only; soft-float, FP64 and unspecified modes need separate verification.";
-    if (abi.isaExtension !== 0 || abi.ases !== 0)
-        return "MIPS ABI flags declare an ISA extension or ASE outside this standard-instruction lane.";
+    if (abi.gprSize !== 1 || abi.cpr2Size !== 0)
+        return "This Ghidra MIPS lane requires 32-bit GPRs and no CPR2; other register modes need separate verification.";
+    const hardFloat = abi.cpr1Size === 1 && (abi.fpAbi === 1 || abi.fpAbi === 5);
+    const softFloat = abi.cpr1Size === 0 && abi.fpAbi === MIPS_FP_ABI_SOFT;
+    if (!hardFloat && !softFloat)
+        return "This Ghidra MIPS lane admits double-precision or FPXX ABI declarations with 32-bit CPR1, or soft-float without CPR1; single-float, FP64 and unspecified modes need separate verification.";
+    if (abi.isaExtension !== 0 || abi.ases !== (shared ? 0x400 : 0))
+        return "MIPS ABI flags declare an ISA extension or ASE outside this profile's verified instruction declarations.";
+    // MIPS_AFL_FLAGS1_ODDSPREG (bit 0) is the GCC and LLVM default for MIPS32 o32
+    // whatever the FP ABI; soft-float objects from both carry it. With no CPR1 it
+    // selects nothing, so it is accepted for soft-float as well as hard-float.
     if ((abi.flags1 & ~1) !== 0 || abi.flags2 !== 0)
         return "MIPS ABI flags contain unsupported general flags.";
     return null;
 };
+/** A legacy lane is established only after every MIPS declaration is admitted. */
+export const isLegacyMipsAdmission = (target) => hasLegacyMipsHeaderShape(target) &&
+    ghidraMipsUnsupportedReason(target) === null;
+/** Soft-float prototype policy applied by ReaGhidraMipsSoftFloat.java after analysis. */
+export const GHIDRA_MIPS_SOFT_FLOAT_STORAGE = "o32-soft-float-prototype-v1";
+/** Whether the admitted target declares the soft-float o32 ABI. */
+export const isGhidraMipsSoftFloatTarget = (target) => target.kind === "executable" &&
+    target.architecture === "mips" &&
+    target.mips?.abiFlags?.cpr1Size === 0 &&
+    target.mips.abiFlags.fpAbi === MIPS_FP_ABI_SOFT;
+/** Fail closed unless soft-float storage ran exactly for soft-float targets. */
+export const ghidraMipsSoftFloatFailure = (expected, report) => expected === (report !== undefined)
+    ? undefined
+    : expected
+        ? "The Ghidra session did not report the committed MIPS soft-float prototype."
+        : "The Ghidra session reported MIPS soft-float storage that the profile did not commit.";
+/** Keep REA's soft-float prototype distinct from Ghidra's hard-float o32 model. */
+export const ghidraMipsSoftFloatLimitations = (expected, report) => expected
+    ? [
+        "Soft-float o32: Ghidra's MIPS32 compiler specifications model hard-float o32 only. After analysis REA installs a program-specific `__rea_soft_float` prototype, derived from the default o32 model without its floating-point registers and rules, and assigns it to every function, external function and function-pointer definition whose declared types use float or double, so those values keep their types and use integer registers and stack slots.",
+        ...(report === undefined
+            ? []
+            : [
+                `Soft-float prototype outcome: ${report.functions} functions and ${report.definitions} function-pointer definitions use __rea_soft_float.`,
+            ]),
+    ]
+    : [];
+/** Ghidra-placed relocatable objects need coordinates and relocation caveats. */
+export const ghidraMipsRelocatableLimitations = (target) => target.kind === "executable" &&
+    target.architecture === "mips" &&
+    target.mips?.type === MIPS_ET_REL
+    ? [
+        "Relocatable MIPS ELF: Ghidra assigns each allocated section an analysis address and applies the object's relocations there. Returned addresses are analysis coordinates, not the addresses a kernel or linker would choose at load time.",
+        "Undefined symbols (for example kernel exports used by a module) are placed in Ghidra's EXTERNAL block; their definitions are outside this artifact. inspect_native_load_image reports each relocation with Ghidra's status; HI16 entries report PARTIAL because Ghidra applies them together with their paired LO16.",
+    ]
+    : [];
+/** Shared-image results are analysis observations, not dynamic-loader execution. */
+export const ghidraMipsSharedLimitations = (target) => isGhidraMips16SharedTarget(target) && target.architecture === "mips"
+    ? [
+        "MIPS16 shared ELF: the endian-matched generic MIPS32 language uses the provider's per-address ISA_MODE context. The program language variant is not the instruction's encoding mode.",
+        "Shared-image addresses are Ghidra analysis coordinates, not runtime addresses. The source bytes remain unchanged; inspect_native_load_image retains original relocation bytes, loaded memory bytes and provider relocation status. External GOT bindings remain unverified without their defining images.",
+        ...(target.mips.abiFlags === null
+            ? [
+                "No MIPS ABI flags record was found in the completely examined declaration tables. The header declares o32 but does not establish the floating-point ABI; the default compiler specification does not verify floating-point argument or return storage.",
+            ]
+            : []),
+    ]
+    : [];
 /** Commit source ELF interpretation without confusing target ISA with host CPU. */
-export const ghidraMipsProfileParameters = (target) => {
+export const ghidraMipsProfileParameters = (target, languageOverride) => {
     if (target.kind !== "executable" ||
         target.architecture !== "mips" ||
         target.mips === undefined)
         return {};
     const abi = target.mips.abiFlags;
+    // A deliberate caller-selected language wins over the legacy pin; the pin
+    // exists because header auto-selection misselects a 64-bit language.
+    const legacy = isLegacyMipsAdmission(target);
+    const language = ghidraMipsLanguageOverride(target);
+    const pinnedLanguage = legacy && languageOverride === undefined && language !== undefined
+        ? {
+            language_id: language.languageId,
+            compiler_spec_id: language.compilerSpecId ?? "default",
+            language_selection: "provider-pinned-v1",
+        }
+        : {};
     return {
         mips_elf: {
             elf_class: target.mips.elfClass,
@@ -73,7 +266,58 @@ export const ghidraMipsProfileParameters = (target) => {
                     flags1: abi.flags1,
                     flags2: abi.flags2,
                 },
+            ...(target.mips.gnuAttributes === undefined
+                ? {}
+                : {
+                    gnu_attributes: target.mips.gnuAttributes === null
+                        ? null
+                        : {
+                            fp_abi: target.mips.gnuAttributes.fpAbi,
+                            msa: target.mips.gnuAttributes.msa,
+                        },
+                }),
+            ...(target.mips.sharedLoad === undefined
+                ? {}
+                : {
+                    shared_load: target.mips.sharedLoad.status === "complete"
+                        ? {
+                            status: "complete",
+                            relocation_count: target.mips.sharedLoad.relocationCount,
+                            relocation_types: [
+                                ...target.mips.sharedLoad.relocationTypes,
+                            ],
+                            symbol_relative_count: target.mips.sharedLoad.symbolRelativeCount,
+                        }
+                        : {
+                            status: "unavailable",
+                            reason: target.mips.sharedLoad.reason,
+                        },
+                }),
         },
-        mips_support_lane: "elf32-exec-o32-arch32r2-standard-v3",
+        ...(isGhidraMipsSoftFloatTarget(target)
+            ? { mips_soft_float_storage: GHIDRA_MIPS_SOFT_FLOAT_STORAGE }
+            : {}),
+        instruction_context_evidence: "per-address-isa-mode-v1",
+        mips_support_lane: legacy
+            ? "elf32-exec-arch32-legacy-pinned-v1"
+            : isGhidraMips16SharedTarget(target)
+                ? "elf32-dyn-o32-arch32r2-mips16-local-rel32-v1"
+                : target.mips.type === MIPS_ET_REL
+                    ? "elf32-rel-o32-arch32r2-standard-v1"
+                    : "elf32-exec-o32-arch32r2-standard-v3",
+        ...(legacy ? { mips_abi_basis: "inferred-o32-assumption-v1" } : {}),
+        ...pinnedLanguage,
     };
 };
+/** Read the provider-pinned import language back from a resolved legacy profile. */
+export const ghidraPinnedMipsLanguage = (parameters) => {
+    if (parameters.language_selection !== "provider-pinned-v1")
+        return undefined;
+    const languageId = parameters.language_id;
+    const compilerSpecId = parameters.compiler_spec_id;
+    if (typeof languageId !== "string" || typeof compilerSpecId !== "string")
+        return undefined;
+    return compilerSpecId === "language-default"
+        ? { languageId }
+        : { languageId, compilerSpecId };
+};

package/dist/ghidra/GhidraNativeAotSnapshotOwner.js

@@ -0,0 +1,221 @@
+import { analysisErrorWithCleanupFailure } from "../domain/analysisErrorCleanup.js";
+import { AnalysisCancelledError } from "../domain/analysisErrorCore.js";
+import { NATIVE_AOT_MAX_REPORT_BYTES, NATIVE_AOT_MAX_SOURCE_BYTES, nativeAotSnapshotOverCapacity, parseNativeAotPe, } from "../domain/native/nativeAotPe.js";
+import { nativeAotSnapshotObservationSchema, } from "../domain/native/nativeAotSnapshotObservation.js";
+import { ProviderAdapterError } from "../domain/providerAdapterError.js";
+import { err, ok } from "../domain/result.js";
+import { SharedStartupAttempt, STARTUP_OWNER_CLOSED, } from "../process/SharedStartupAttempt.js";
+import { GhidraSessionError } from "./GhidraSessionError.js";
+/** Own one captured PE derivation; each caller owns only its wait and projection. */
+export class GhidraNativeAotSnapshotOwner {
+    input;
+    #base;
+    #conflict;
+    #closed = false;
+    #cached;
+    #attempt;
+    #failure;
+    #capture;
+    constructor(input) {
+        this.input = input;
+    }
+    get cleanupFailure() {
+        const cleanup = this.#failure?.cleanupFailure;
+        return cleanup?.cleanupIncomplete ? cleanup : undefined;
+    }
+    async derive(imageBase, operation, callerSignal, observations) {
+        if (callerSignal?.aborted)
+            return err(this.#cancelled(operation, callerSignal.reason, observations));
+        if (this.#closed)
+            return err(this.#cancelled(operation, STARTUP_OWNER_CLOSED, observations));
+        if (this.#conflict !== undefined)
+            return err(this.#identityError(operation, imageBase, observations));
+        let normalized;
+        try {
+            const base = BigInt(imageBase);
+            if (base < 0n)
+                throw new RangeError("Loaded image base must be nonnegative");
+            normalized = `0x${base.toString(16)}`;
+        }
+        catch (cause) {
+            return err(new ProviderAdapterError("ghidra", operation, {
+                diagnostics: {
+                    reason: "Ghidra returned an invalid loaded image base for NativeAOT identity binding.",
+                    observed_image_base: imageBase,
+                    measured_observation: observations,
+                },
+                cause,
+            }));
+        }
+        if (this.#base !== undefined && this.#base !== normalized) {
+            this.#conflict = { imageBase, observations };
+            this.#cached = undefined;
+            this.#attempt?.close();
+            return err(this.#identityError(operation, imageBase, observations));
+        }
+        this.#base ??= normalized;
+        if (this.cleanupFailure !== undefined && this.#failure !== undefined)
+            return err(this.#projectFailure(operation, this.#failure, imageBase, observations));
+        if (this.#cached !== undefined) {
+            const cached = this.#cached;
+            await Promise.resolve();
+            if (this.#conflict !== undefined)
+                return err(this.#identityError(operation, imageBase, observations));
+            return this.#closed || callerSignal?.aborted
+                ? err(this.#cancelled(operation, callerSignal?.aborted
+                    ? callerSignal.reason
+                    : STARTUP_OWNER_CLOSED, observations, this.#observation(cached)))
+                : ok(cached);
+        }
+        const draining = this.#attempt;
+        if (draining?.signal.aborted) {
+            const waited = await draining.wait(callerSignal);
+            if (waited.status !== "cancelled" &&
+                !waited.value.ok &&
+                (waited.value.error.kind !== "cancelled" ||
+                    waited.value.error.cleanupFailure?.cleanupIncomplete))
+                return err(this.#projectFailure(operation, waited.value.error, imageBase, observations));
+            if (waited.status === "cancelled")
+                return err(this.#cancelled(operation, callerSignal?.reason, observations));
+            if (callerSignal?.aborted)
+                return err(waited.value.ok
+                    ? this.#cancelled(operation, callerSignal.reason, observations, this.#observation(waited.value.value))
+                    : this.#cancelled(operation, callerSignal.reason, observations, waited.value.error.partialObservation));
+            return this.derive(imageBase, operation, callerSignal, observations);
+        }
+        const attempt = this.#attempt ?? this.#start(normalized);
+        const waited = await attempt.wait(callerSignal);
+        if (waited.status === "cancelled")
+            return err(this.#cancelled(operation, callerSignal?.reason, observations));
+        const settled = waited.value;
+        // A completed physical failure or retained cleanup outranks a later abort.
+        if (!settled.ok) {
+            return err(this.#projectFailure(operation, settled.error, imageBase, observations));
+        }
+        if (this.#conflict !== undefined)
+            return err(this.#identityError(operation, imageBase, observations));
+        if (this.#closed || attempt.signal.aborted || callerSignal?.aborted)
+            return err(this.#cancelled(operation, callerSignal?.aborted
+                ? callerSignal.reason
+                : this.#closed
+                    ? STARTUP_OWNER_CLOSED
+                    : attempt.signal.reason, observations, this.#observation(settled.value)));
+        return settled;
+    }
+    readTypeDetail(address) {
+        return this.#closed || this.#conflict !== undefined
+            ? undefined
+            : this.#cached?.readTypeDetail(address, NATIVE_AOT_MAX_REPORT_BYTES);
+    }
+    #projectFailure(operation, failure, imageBase, observations) {
+        if (failure.kind !== "cancelled" || this.#conflict === undefined)
+            return this.input.projectFailure(operation, failure.withDiagnostics({
+                ...failure.diagnostics,
+                measured_observation: observations,
+            }));
+        return this.#identityError(operation, imageBase, observations, failure);
+    }
+    async close() {
+        this.#closed = true;
+        this.#cached = undefined;
+        const attempt = this.#attempt;
+        attempt?.close();
+        await attempt?.promise;
+    }
+    #start(imageBase) {
+        this.#failure = undefined;
+        this.#capture = undefined;
+        const attempt = new SharedStartupAttempt((signal) => this.#read(imageBase, signal));
+        this.#attempt = attempt;
+        void attempt.promise.then((settled) => {
+            if (this.#attempt !== attempt)
+                return;
+            this.#attempt = undefined;
+            if (!settled.ok)
+                this.#failure = settled.error;
+            else if (!this.#closed &&
+                this.#conflict === undefined &&
+                !attempt.signal.aborted)
+                this.#cached = settled.value;
+        });
+        return attempt;
+    }
+    async #read(imageBase, signal) {
+        try {
+            if (this.input.readSnapshot === undefined)
+                return err(new GhidraSessionError("protocol", "The Ghidra client does not expose its immutable target snapshot for NativeAOT metadata inspection."));
+            const snapshot = await this.input.readSnapshot(NATIVE_AOT_MAX_SOURCE_BYTES, signal);
+            if (!snapshot.ok)
+                return snapshot;
+            this.#capture = this.#captureFacts(snapshot.value);
+            const partialObservation = this.#observation();
+            if (signal.aborted)
+                return err(new GhidraSessionError("cancelled", "NativeAOT snapshot derivation stopped", {}, {
+                    cause: signal.reason,
+                    cancellation: { reason: signal.reason },
+                    ...(partialObservation === undefined
+                        ? {}
+                        : { partialObservation }),
+                }));
+            const parsed = snapshot.value.kind === "over-capacity"
+                ? {
+                    summary: nativeAotSnapshotOverCapacity(this.input.targetSha256, snapshot.value.sourceBytesAtLeast, NATIVE_AOT_MAX_REPORT_BYTES),
+                    readTypeDetail: () => undefined,
+                }
+                : parseNativeAotPe(snapshot.value.bytes, this.input.targetSha256, NATIVE_AOT_MAX_REPORT_BYTES, imageBase);
+            return ok(parsed);
+        }
+        catch (cause) {
+            const partialObservation = this.#observation();
+            return err(new GhidraSessionError("protocol", "NativeAOT metadata could not be derived from the captured target snapshot.", {}, {
+                cause,
+                ...(partialObservation === undefined ? {} : { partialObservation }),
+            }));
+        }
+    }
+    #captureFacts(snapshot) {
+        return snapshot.kind === "captured"
+            ? { status: "captured", bytes: snapshot.bytes.length }
+            : {
+                status: "over-capacity",
+                source_bytes_at_least: snapshot.sourceBytesAtLeast,
+                maximum_bytes: snapshot.maximumBytes,
+            };
+    }
+    #observation(result) {
+        if (this.#capture === undefined || this.#base === undefined)
+            return undefined;
+        return nativeAotSnapshotObservationSchema.parse({
+            kind: "native-aot-snapshot",
+            analysis_artifact_sha256: this.input.targetSha256,
+            image_base: this.#base,
+            capture: this.#capture,
+            ...(result === undefined ? {} : { metadata_recovery: result.summary }),
+        });
+    }
+    #cancelled(operation, reason, observations, partialObservation) {
+        return new AnalysisCancelledError(operation, {
+            cause: reason,
+            diagnostics: { measured_observation: observations },
+            partialObservation,
+        });
+    }
+    #identityError(operation, imageBase, observations, source = this.#failure) {
+        const primary = new ProviderAdapterError("ghidra", operation, {
+            partialObservation: source?.partialObservation ?? this.#observation(),
+            diagnostics: {
+                reason: "The Ghidra session reported conflicting loaded image bases (a different loaded image base after binding); reopen the analysis session to establish a new identity.",
+                artifact_sha256: this.input.targetSha256,
+                bound_image_base: this.#base ?? null,
+                observed_image_base: imageBase,
+                measured_observation: observations,
+                conflicting_image_base: this.#conflict?.imageBase ?? null,
+                conflicting_observation: this.#conflict?.observations ?? null,
+            },
+        });
+        const cleanup = source?.cleanupFailure ?? this.cleanupFailure;
+        return cleanup?.cleanupIncomplete
+            ? analysisErrorWithCleanupFailure(primary, cleanup, operation).bindCleanupDependencies([primary, cleanup])
+            : primary;
+    }
+}

package/dist/ghidra/GhidraPeProfile.js

@@ -0,0 +1,91 @@
+import { ghidraPdbLimitations, } from "./GhidraSessionValues.js";
+const PDB_LOCATOR_INLINE_BYTE_BUDGET = 1024;
+/** Establish equivalence only for the declared fields and recognized formats. */
+const reportedPdbMatchesDeclaration = (declared, reported) => {
+    if (reported.resource_limit?.omitted_attributes.some((attribute) => attribute === "file" || attribute === "guid" || attribute === "age") ||
+        (reported.file !== declared.pdbPath &&
+            reported.file !== declared.pdbFileName) ||
+        reported.age === null ||
+        !/^(?:0x)?[0-9a-f]+$/iu.test(reported.age) ||
+        Number.parseInt(reported.age, 16) !== declared.age)
+        return false;
+    if (declared.guid === null)
+        return reported.guid === null;
+    if (reported.guid === null)
+        return false;
+    let guid = reported.guid;
+    if (guid.startsWith("{") && guid.endsWith("}"))
+        guid = guid.slice(1, -1);
+    if (!/^(?:[0-9a-f]{32}|[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12})$/iu.test(guid))
+        return false;
+    return (guid.replaceAll("-", "").toLowerCase() ===
+        declared.guid.replaceAll("-", "").toLowerCase());
+};
+/** Measure JSON quotes, escapes and UTF-8 without allocating the encoded string. */
+const pdbLocatorFitsInlineBudget = (value) => {
+    if (value.length * 6 + 2 <= PDB_LOCATOR_INLINE_BYTE_BUDGET)
+        return true;
+    if (value.length + 2 > PDB_LOCATOR_INLINE_BYTE_BUDGET)
+        return false;
+    let bytes = 2;
+    for (let index = 0; index < value.length; index += 1) {
+        const point = value.codePointAt(index) ?? 0;
+        if (point > 0xffff) {
+            bytes += 4;
+            index += 1;
+        }
+        else if (point >= 0xd800 && point <= 0xdfff) {
+            // JSON.stringify escapes unpaired UTF-16 surrogates as six ASCII bytes.
+            bytes += 6;
+        }
+        else if (point < 0x20) {
+            bytes +=
+                point === 8 ||
+                    point === 9 ||
+                    point === 10 ||
+                    point === 12 ||
+                    point === 13
+                    ? 2
+                    : 6;
+        }
+        else if (point === 0x22 || point === 0x5c) {
+            bytes += 2;
+        }
+        else {
+            bytes += point < 0x80 ? 1 : point < 0x800 ? 2 : 3;
+        }
+        if (bytes > PDB_LOCATOR_INLINE_BYTE_BUDGET)
+            return false;
+    }
+    return true;
+};
+/** Use reported Program facts first, retaining declared PE facts as a fallback. */
+export const ghidraPePdbLimitations = (target, pdb) => {
+    if (target.format !== "pe")
+        return [];
+    const reported = ghidraPdbLimitations(pdb);
+    if (target.codeView === undefined ||
+        (pdb !== undefined && reportedPdbMatchesDeclaration(target.codeView, pdb)))
+        return reported;
+    const { pdbFileName, guid, age } = target.codeView;
+    // Include JSON escaping in the inline budget before allocating that representation.
+    const locator = pdbLocatorFitsInlineBudget(pdbFileName)
+        ? JSON.stringify(pdbFileName)
+        : `(declared locator omitted from this inline caveat: ${PDB_LOCATOR_INLINE_BYTE_BUDGET}-byte resource budget)`;
+    const identity = guid === null
+        ? `age (decimal) ${age}`
+        : `GUID ${guid}, age (decimal) ${age}`;
+    const state = pdb === undefined
+        ? "Ghidra did not report PDB attributes; load state unknown"
+        : pdb.loaded === false
+            ? "Ghidra reports not loaded"
+            : pdb.loaded === true
+                ? "Ghidra reports a loaded PDB; this declared identity is not an independent matching-PDB attestation"
+                : "Ghidra reports load state unknown";
+    const comparison = pdb !== undefined &&
+        [pdb.file, pdb.guid, pdb.age].some((value) => value !== null)
+        ? " Reported and declared PDB observations are retained separately; equivalence is not established."
+        : "";
+    const declared = `The PE CodeView record references PDB ${locator} (${identity}); ${state}.${comparison} Original PDB names and types may be missing. Use list_procedures and address-based analysis to inspect recovered functions. REA does not admit a caller-selected PDB companion.`;
+    return pdb === undefined ? [declared] : [...reported, declared];
+};