rea-agents 4.0.1 → 5.0.0

package/dist/ghidra/GhidraInstallationPolicy.js

@@ -0,0 +1,140 @@
+/** Ghidra build whose bridge behavior this REA release verifies. */
+export const SUPPORTED_GHIDRA_VERSION = "12.1.4";
+/**
+ * JDK major used when an installation omits `application.java.min`.
+ * Admission uses that installation's `application.java.min` and
+ * `application.java.max`. An empty maximum means the release sets no upper bound.
+ */
+export const SUPPORTED_GHIDRA_JAVA_MAJOR = 21;
+const GHIDRA_RELEASE_PATTERN = /^(\d+)\.(\d+)(?:\.(\d+))?([-+].*)?$/u;
+const JAVA_MAJOR_PATTERN = /^(\d+)(?:\.\d+)*$/u;
+/** Read the version and Java bounds Ghidra publishes for one installation. */
+export const ghidraApplicationProperties = (content) => ({
+    providerVersion: propertyValue(content, "application.version"),
+    javaMinimum: parseJavaBound(propertyValue(content, "application.java.min")),
+    javaMaximum: parseJavaBound(propertyValue(content, "application.java.max")),
+});
+/** 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) => {
+    const minimum = properties?.javaMinimum ?? { status: "absent" };
+    const maximum = properties?.javaMaximum ?? { status: "absent" };
+    if (minimum.status === "unresolved")
+        return unresolvedJavaRequirement(`application.java.min=${minimum.raw}`);
+    if (maximum.status === "unresolved")
+        return unresolvedJavaRequirement(`application.java.max=${maximum.raw}`);
+    const minimumMajor = minimum.status === "major" ? minimum.major : SUPPORTED_GHIDRA_JAVA_MAJOR;
+    const maximumMajor = maximum.status === "major" ? maximum.major : null;
+    if (maximumMajor !== null && maximumMajor < minimumMajor)
+        return unresolvedJavaRequirement(`application.java.max=${String(maximumMajor)} is below application.java.min=${String(minimumMajor)}`);
+    return { minimumMajor, maximumMajor, unresolved: null };
+};
+/** Caller-facing description of one resolved or unreadable JDK range. */
+export const ghidraJavaRangeLabel = (requirement) => {
+    if (requirement.unresolved !== null)
+        return "a 64-bit full JDK matching the installation's declared Java bounds";
+    if (requirement.maximumMajor === null)
+        return `a 64-bit full JDK ${String(requirement.minimumMajor)} or newer`;
+    if (requirement.maximumMajor === requirement.minimumMajor)
+        return `a 64-bit full JDK ${String(requirement.minimumMajor)}`;
+    return `a 64-bit full JDK ${String(requirement.minimumMajor)} through ${String(requirement.maximumMajor)}`;
+};
+/** Whether an observed JDK satisfies the installation's declared range. */
+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) => {
+    if (raw === null)
+        return { status: "absent" };
+    const major = integerGroup(JAVA_MAJOR_PATTERN.exec(raw)?.[1]);
+    return major === undefined
+        ? { status: "unresolved", raw }
+        : { status: "major", major };
+};
+const integerGroup = (value) => {
+    if (value === undefined)
+        return undefined;
+    const parsed = Number(value);
+    return Number.isSafeInteger(parsed) ? parsed : undefined;
+};
+const unresolvedJavaRequirement = (unresolved) => ({
+    minimumMajor: SUPPORTED_GHIDRA_JAVA_MAJOR,
+    maximumMajor: null,
+    unresolved,
+});
+const propertyValue = (content, name) => {
+    for (const line of content.split(/\r?\n/u)) {
+        const separator = line.indexOf("=");
+        if (separator < 0 || line.slice(0, separator).trim() !== name)
+            continue;
+        const value = line.slice(separator + 1).trim();
+        return value.length === 0 ? null : value;
+    }
+    return null;
+};

package/dist/ghidra/GhidraInventoryValues.js

@@ -1,9 +1,14 @@
 import { z } from "zod";
-import { AnalysisInputError, AnalysisOutputError } from "../domain/errors.js";
+import { nativeLoadImageObservationSchema } from "../domain/native/nativeLoadImage.js";
+import { AnalysisInputError, AnalysisOutputError, } from "../domain/analysisErrorCore.js";
 import { functionBodySchema, functionBodyEntryAgrees, } from "../domain/hopperValues.js";
+import { jsonValueSchema } from "../domain/jsonValue.js";
 import { err, ok } from "../domain/result.js";
 /** Read-only direct inventory operations admitted by the Ghidra adapter. */
 export const GHIDRA_INVENTORY_OPERATIONS = [
+    "inspect_native_load_image",
+    "read_bytes",
+    "address_to_file_offset",
     "address_name",
     "list_documents",
     "list_names",
@@ -30,6 +35,16 @@ const searchInput = {
     document,
 };
 const inputSchemas = {
+    inspect_native_load_image: z.strictObject({}),
+    read_bytes: z.strictObject({
+        document,
+        address: explicitAddress,
+        length: z.number().int().min(1).max(Number.MAX_SAFE_INTEGER).default(256),
+    }),
+    address_to_file_offset: z.strictObject({
+        document,
+        address: explicitAddress,
+    }),
     address_name: z.object({ document, address: explicitAddress }).strict(),
     list_documents: z.object({}).strict(),
     list_names: z.object({ document, address: filteredAddress }).strict(),
@@ -173,6 +188,28 @@ const containingProcedure = z.discriminatedUnion("found", [
         .strict(),
 ]);
 const resultSchemas = {
+    inspect_native_load_image: nativeLoadImageObservationSchema,
+    read_bytes: z
+        .strictObject({
+        address: canonicalAddress,
+        requested_bytes: z.number().int().min(1),
+        returned_bytes: z.number().int().min(0),
+        bytes_hex: z.string().regex(/^(?:[a-f0-9]{2})*$/u),
+        complete: z.boolean(),
+    })
+        .superRefine((value, context) => {
+        if (value.returned_bytes * 2 !== value.bytes_hex.length ||
+            value.returned_bytes > value.requested_bytes ||
+            value.complete !== (value.returned_bytes === value.requested_bytes))
+            context.addIssue({
+                code: "custom",
+                message: "Read-byte length and completeness disagree",
+            });
+    }),
+    address_to_file_offset: z.strictObject({
+        address: canonicalAddress,
+        file_offset: z.number().int().min(0).max(Number.MAX_SAFE_INTEGER),
+    }),
     address_name: z.string().nullable(),
     list_documents: z.array(z.string().min(1)).length(1),
     list_names: z.array(symbolItem),
@@ -188,6 +225,6 @@ const resultSchemas = {
 export const parseGhidraInventoryResult = (operation, value) => {
     const parsed = resultSchemas[operation].safeParse(value);
     return parsed.success
-        ? ok(parsed.data)
+        ? ok(jsonValueSchema.parse(parsed.data))
         : err(new AnalysisOutputError(operation, "Ghidra bridge output did not match the inventory contract", { cause: parsed.error }));
 };

package/dist/ghidra/GhidraLauncher.js

@@ -1,11 +1,13 @@
 import { mkdir } from "node:fs/promises";
 import { basename, dirname, join, win32 } from "node:path";
 import writeFileAtomic from "write-file-atomic";
-import { AnalysisCancelledError } from "../domain/errors.js";
+import { windowsPrivateRuntime } from "../windows/WindowsPrivateRuntime.js";
+import { AnalysisCancelledError } from "../domain/analysisErrorCore.js";
 import { err, ok } from "../domain/result.js";
 import { cleanupOwnedProcessGroup, cleanupWindowsProcessTree, } from "../process/ProcessOwnership.js";
 import { spawnOwnedProviderProcess, } from "../process/ProviderProcess.js";
 import { ghidraJavaEnvironment } from "./GhidraInstallation.js";
+import { snapshotGhidraExtensions, } from "./extensions/GhidraExtensions.js";
 /** Local launch failure retained as the cause of a provider-neutral error. */
 export class GhidraLaunchError extends Error {
     constructor(message, options) {
@@ -26,15 +28,9 @@ export class GhidraHeadlessLauncher {
         const platform = this.options.platform ?? process.platform;
         let started;
         try {
-            await Promise.all([
-                paths.projectRoot,
-                paths.homeRoot,
-                paths.tempRoot,
-                paths.cacheRoot,
-                paths.configRoot,
-                paths.dataRoot,
-            ].map((path) => mkdir(path, { recursive: true, mode: 0o700 })));
-            await writeFileAtomic(paths.descriptorPath, `${JSON.stringify({
+            await createGhidraRuntimeDirectories(paths, platform);
+            const extensions = await snapshotGhidraExtensions(this.options.analysisExtensions ?? [], session.runtimeRoot);
+            await writeGhidraRuntimeFile(paths.descriptorPath, `${JSON.stringify({
                 transport: session.transport,
                 endpoint_path: session.endpointPath,
                 token: session.token,
@@ -42,7 +38,10 @@ export class GhidraHeadlessLauncher {
                 target_sha256: session.targetSha256,
                 provider_version: session.providerVersion,
                 profile_digest: session.profileDigest,
-            })}\n`, { encoding: "utf8", mode: 0o600 });
+                ...(extensions.length === 0
+                    ? {}
+                    : { analysis_extensions: extensions }),
+            })}\n`, platform);
             if (isAborted(options.signal))
                 return err(new AnalysisCancelledError("open_binary"));
             const headlessArguments = ghidraHeadlessArguments({
@@ -52,6 +51,9 @@ export class GhidraHeadlessLauncher {
                 descriptorPath: paths.descriptorPath,
                 ghidraLogPath: paths.ghidraLogPath,
                 scriptLogPath: paths.scriptLogPath,
+                ...(this.options.dosCom === undefined
+                    ? {}
+                    : { dosCom: this.options.dosCom }),
                 ...(this.options.dosMz === undefined
                     ? {}
                     : { dosMz: this.options.dosMz }),
@@ -73,19 +75,17 @@ export class GhidraHeadlessLauncher {
                 expectedCommand: null,
                 windowsVerbatimArguments: platform === "win32",
                 platform,
-                env: ghidraLaunchEnvironment(paths, this.options.javaHome, platform),
+                env: ghidraLaunchEnvironment(paths, this.options.javaHome, platform, command.command),
             });
-            await writeFileAtomic(paths.ownershipPath, `${JSON.stringify({
+            await writeGhidraRuntimeFile(paths.ownershipPath, `${JSON.stringify({
                 run_id: session.runId,
                 pid: started.ownership.leaderPid,
                 process_group_id: started.ownership.processGroupId,
                 parent_pid: process.pid,
-                ownership_kind: platform === "win32"
-                    ? "windows-process-tree-p0"
-                    : "posix-process-group",
+                ownership_kind: platform === "win32" ? "windows-job-object" : "posix-process-group",
                 launcher: this.options.analyzeHeadlessPath,
                 created_at: new Date().toISOString(),
-            })}\n`, { encoding: "utf8", mode: 0o600 });
+            })}\n`, platform);
             if (isAborted(options.signal)) {
                 await cleanupStartedProcess(started, platform);
                 return err(new AnalysisCancelledError("open_binary"));
@@ -100,7 +100,10 @@ export class GhidraHeadlessLauncher {
         }
         catch (cause) {
             if (started !== undefined)
-                await cleanupStartedProcess(started, platform).catch(() => undefined);
+                await cleanupStartedProcess(started, platform).catch((cause) => {
+                    // best-effort cleanup: started-process cleanup must not mask the launch failure.
+                    void cause;
+                });
             return isAborted(options.signal)
                 ? err(new AnalysisCancelledError("open_binary"))
                 : err(new GhidraLaunchError("Ghidra headless launch failed", { cause }));
@@ -146,9 +149,11 @@ const quoteWindowsBatchToken = (value) => {
         throw new GhidraLaunchError("Windows Ghidra P0 paths cannot contain command-interpreter metacharacters");
     return `"${value}"`;
 };
-const cleanupStartedProcess = (started, platform) => platform === "win32"
-    ? cleanupWindowsProcessTree(started.ownership.leaderPid)
-    : cleanupOwnedProcessGroup(started.ownership);
+const cleanupStartedProcess = (started, platform) => started.cleanup !== undefined
+    ? started.cleanup()
+    : platform === "win32"
+        ? cleanupWindowsProcessTree(started.ownership.leaderPid)
+        : cleanupOwnedProcessGroup(started.ownership);
 /** Build the complete read-only headless invocation in deterministic order. */
 export const ghidraHeadlessArguments = (options) => [
     options.projectRoot,
@@ -164,7 +169,18 @@ export const ghidraHeadlessArguments = (options) => [
             "-cspec",
             "default",
         ]
-        : []),
+        : options.dosCom === true
+            ? [
+                "-loader",
+                "BinaryLoader",
+                "-loader-baseAddr",
+                "1000:0100",
+                "-processor",
+                "x86:LE:16:Real Mode",
+                "-cspec",
+                "default",
+            ]
+            : []),
     "-readOnly",
     "-deleteProject",
     "-log",
@@ -173,8 +189,16 @@ export const ghidraHeadlessArguments = (options) => [
     options.scriptLogPath,
     "-scriptPath",
     dirname(options.bridgeScriptPath),
+    ...(options.dosCom === true
+        ? [
+            "-preScript",
+            join(dirname(options.bridgeScriptPath), "ReaGhidraPrepareCom.java"),
+        ]
+        : []),
     "-postScript",
-    basename(options.bridgeScriptPath),
+    // Ghidra checks the caller's cwd before scriptPath for a basename. Select
+    // the packaged source explicitly so unrelated entries cannot shadow it.
+    options.bridgeScriptPath,
     options.descriptorPath,
 ];
 const ghidraRuntimePaths = (runtimeRoot) => ({
@@ -189,18 +213,50 @@ const ghidraRuntimePaths = (runtimeRoot) => ({
     ghidraLogPath: join(runtimeRoot, "ghidra.log"),
     scriptLogPath: join(runtimeRoot, "script.log"),
 });
-const ghidraLaunchEnvironment = (paths, javaHome, platform) => {
-    // analyzeHeadless.bat wraps GHIDRA_HEADLESS_JAVA_OPTIONS in its own quotes
-    // when it builds VMARG_LIST. Nested quotes break cmd.exe tokenization before
-    // Ghidra starts, so keep this option list unquoted on every platform.
-    const javaOptions = `-Duser.home=${paths.homeRoot} -Djava.io.tmpdir=${paths.tempRoot}`;
+const createGhidraRuntimeDirectories = async (paths, platform) => {
+    if (platform === "win32") {
+        const runtime = windowsPrivateRuntime(dirname(paths.projectRoot));
+        for (const path of [
+            paths.projectRoot,
+            paths.homeRoot,
+            paths.tempRoot,
+            paths.cacheRoot,
+            paths.configRoot,
+            paths.dataRoot,
+        ])
+            runtime.mkdir(basename(path));
+        return;
+    }
+    await Promise.all([
+        paths.projectRoot,
+        paths.homeRoot,
+        paths.tempRoot,
+        paths.cacheRoot,
+        paths.configRoot,
+        paths.dataRoot,
+    ].map((path) => mkdir(path, { recursive: true, mode: 0o700 })));
+};
+const writeGhidraRuntimeFile = async (path, content, platform) => {
+    if (platform === "win32") {
+        windowsPrivateRuntime(dirname(path)).writeFile(basename(path), content);
+        return;
+    }
+    await writeFileAtomic(path, content, { encoding: "utf8", mode: 0o600 });
+};
+const ghidraLaunchEnvironment = (paths, javaHome, platform, executable) => {
     return {
         ...ghidraJavaEnvironment(javaHome, process.env, platform),
+        ...ghidraHeadlessJavaOptions(paths.homeRoot, paths.tempRoot, platform),
         HOME: paths.homeRoot,
         TMPDIR: paths.tempRoot,
         ...(platform === "win32"
             ? {
+                // Batch FOR /F launches another command interpreter through ComSpec.
+                // Use the same executable with the spelling consumed by cmd.exe.
+                ComSpec: executable.replaceAll("/", "\\"),
                 USERPROFILE: paths.homeRoot,
+                APPDATA: paths.configRoot,
+                LOCALAPPDATA: paths.cacheRoot,
                 TEMP: paths.tempRoot,
                 TMP: paths.tempRoot,
             }
@@ -208,7 +264,24 @@ const ghidraLaunchEnvironment = (paths, javaHome, platform) => {
         XDG_CACHE_HOME: paths.cacheRoot,
         XDG_CONFIG_HOME: paths.configRoot,
         XDG_DATA_HOME: paths.dataRoot,
-        GHIDRA_HEADLESS_JAVA_OPTIONS: javaOptions,
     };
 };
+/** Encode provider-owned JVM paths for the parser that actually consumes them. */
+export const ghidraHeadlessJavaOptions = (homeRoot, tempRoot, platform) => {
+    const options = [`-Duser.home=${homeRoot}`, `-Djava.io.tmpdir=${tempRoot}`];
+    // analyzeHeadless.bat quotes VMARG_LIST, then launch.bat expands it again.
+    // Inner quotes fail in cmd.exe; unquoted paths with spaces split at the JVM.
+    // JDK_JAVA_OPTIONS is parsed by Java itself, outside that batch expansion.
+    return platform === "win32"
+        ? {
+            JDK_JAVA_OPTIONS: [...options, "-XX:-UsePerfData"]
+                .map(quoteWindowsBatchToken)
+                .join(" "),
+            GHIDRA_HEADLESS_JAVA_OPTIONS: "",
+        }
+        : {
+            JDK_JAVA_OPTIONS: "",
+            GHIDRA_HEADLESS_JAVA_OPTIONS: options.join(" "),
+        };
+};
 const isAborted = (signal) => signal?.aborted === true;

package/dist/ghidra/GhidraLoadImageAttest.js

@@ -0,0 +1,36 @@
+import { jsonValueSchema } from "../domain/jsonValue.js";
+import { nativeLoadImageObservationSchema, nativeLoadImageSchema, } from "../domain/native/nativeLoadImage.js";
+import { ProviderAdapterError } from "../domain/providerAdapterError.js";
+import { err, ok } from "../domain/result.js";
+import { attestGhidraDosComLoadImage, attestGhidraDosLoadImage, } from "./GhidraLoadImageValues.js";
+/** Independently verify measured load-image observations for admitted DOS targets. */
+export const attestGhidraNativeLoadImage = async (target, operation, measured, client, mapSessionError) => {
+    const observations = nativeLoadImageObservationSchema.parse(measured);
+    if (target.format !== "dos-mz" && target.format !== "dos-com") {
+        return ok(jsonValueSchema.parse(nativeLoadImageSchema.parse({
+            status: "unsupported",
+            reason: "Independent load-image verification currently supports DOS MZ and explicit DOS COM targets only.",
+            observations,
+            limitations: [
+                "Other formats expose measured mappings and source identities; no format-specific verification was performed.",
+            ],
+        })));
+    }
+    if (client.readTargetSnapshot === undefined)
+        return err(new ProviderAdapterError("ghidra", operation, {
+            diagnostics: {
+                reason: "The Ghidra client does not expose its immutable target snapshot for independent load-image verification.",
+            },
+        }));
+    const snapshot = await client.readTargetSnapshot();
+    if (!snapshot.ok)
+        return err(mapSessionError(snapshot.error));
+    const attested = (target.format === "dos-com"
+        ? attestGhidraDosComLoadImage
+        : attestGhidraDosLoadImage)(snapshot.value, target.sha256 ?? "", observations);
+    if (!attested.ok)
+        return err(new ProviderAdapterError("ghidra", operation, {
+            diagnostics: { reason: attested.error },
+        }));
+    return ok(jsonValueSchema.parse(attested.value));
+};

package/dist/ghidra/GhidraLoadImageValues.js

@@ -0,0 +1,199 @@
+import { createHash } from "node:crypto";
+import { nativeLoadImageSchema, } from "../domain/native/nativeLoadImage.js";
+import { parseDosMzHeader } from "../domain/dosMz.js";
+import { validateDosComLength } from "../domain/dosCom.js";
+import { err, ok } from "../domain/result.js";
+const sha256 = (bytes) => createHash("sha256").update(bytes).digest("hex");
+const address = (offset) => `0x${offset.toString(16)}`;
+const limitations = [
+    "Verification covers original/modified FileBytes, every initialized target-backed header/module mapping, relocation records and the external entry point. Mapping ends are inclusive.",
+    "Appended overlay bytes are identified by file extent and included in FileBytes identity; they must not be mapped as initialized header/module memory. Uninitialized allocations are reported but their contents and DOS runtime behavior are not verified.",
+    "The fixed load segment 0x1000 describes Ghidra's analysis image, not a running DOS process. Verified import does not establish original source ownership or recovered program behavior.",
+    "A mismatching memory digest identifies the reported source range; it does not locate the first differing byte inside that range.",
+];
+/** Verify measured MZ import state against the session's immutable snapshot. */
+export const attestGhidraDosLoadImage = (bytes, targetSha256, observations) => {
+    if (sha256(bytes) !== targetSha256)
+        return err("Ghidra load-image snapshot digest does not match the admitted target");
+    const parsed = parseDosMzHeader(bytes);
+    if (!parsed.ok)
+        return parsed;
+    const header = parsed.value;
+    const loadSegment = 0x1000;
+    const modified = Buffer.from(bytes);
+    const expectedRelocations = [];
+    for (let index = 0; index < header.relocationCount; index += 1) {
+        const table = header.relocationTableOffset + index * 4;
+        const offset = bytes.readUInt16LE(table);
+        const segment = bytes.readUInt16LE(table + 2);
+        const fileOffset = header.headerBytes + segment * 16 + offset;
+        const original = modified
+            .subarray(fileOffset, fileOffset + 2)
+            .toString("hex");
+        const relocated = (modified.readUInt16LE(fileOffset) + loadSegment) & 0xffff;
+        modified.writeUInt16LE(relocated, fileOffset);
+        expectedRelocations.push({
+            address: address(loadSegment * 16 + segment * 16 + offset),
+            segment: (loadSegment + segment) & 0xffff,
+            offset,
+            status: "APPLIED",
+            type: 0,
+            values: [segment, offset, relocated],
+            original_bytes_hex: original,
+            memory_bytes_hex: modified
+                .subarray(fileOffset, fileOffset + 2)
+                .toString("hex"),
+        });
+    }
+    const checks = [];
+    const check = (name, expected, observed, fileOffset = null, location = null) => {
+        checks.push({
+            name,
+            matched: JSON.stringify(expected) === JSON.stringify(observed),
+            expected,
+            observed,
+            file_offset: fileOffset,
+            address: location,
+        });
+    };
+    check("executable_format", "Old-style DOS Executable (MZ)", observations.executable_format);
+    check("language_id", "x86:LE:16:Real Mode", observations.language_id);
+    check("compiler_spec_id", "default", observations.compiler_spec_id);
+    check("image_base", "0x0", observations.image_base);
+    check("default_address_space", "ram", observations.default_address_space);
+    check("source_file_count", 1, observations.source_files.length);
+    const source = observations.source_files[0];
+    check("source_file_size", bytes.length, source?.size ?? null);
+    check("original_file_sha256", targetSha256, source?.original_sha256 ?? null);
+    check("modified_file_sha256", sha256(modified), source?.modified_sha256 ?? null);
+    const entryAddress = address(((loadSegment + header.entrySegment) & 0xffff) * 16 + header.entryOffset);
+    check("entry_points", [entryAddress], [...observations.entry_points].sort());
+    // A multiset preserves duplicate relocations and aliases; iteration order is not semantic.
+    const rows = (values) => values
+        .map(({ segment: _segment, offset: _offset, ...value }) => JSON.stringify(value))
+        .sort();
+    check("relocation_address_aliases", [], observations.relocations.filter((row) => row.segment === null ||
+        row.offset === null ||
+        address(row.segment * 16 + row.offset) !== row.address));
+    check("relocation_records", rows(expectedRelocations), rows(observations.relocations));
+    checkMappings(header, loadSegment * 16, bytes, modified, observations, check);
+    return ok(nativeLoadImageSchema.parse({
+        status: checks.every((item) => item.matched) ? "verified" : "mismatch",
+        format: "dos-mz",
+        target_sha256: targetSha256,
+        load_segment: loadSegment,
+        header_bytes: header.headerBytes,
+        module_bytes: header.moduleBytes,
+        overlay_bytes: header.overlayBytes,
+        entry: {
+            relative_segment: header.entrySegment,
+            offset: header.entryOffset,
+            linear_address: entryAddress,
+        },
+        observations,
+        checks,
+        limitations,
+    }));
+};
+const checkMappings = (header, loadBase, bytes, modified, observations, check) => {
+    const backed = observations.mappings.filter((mapping) => mapping.source_file_index !== null);
+    const sorted = [...backed].sort((left, right) => (left.file_offset ?? -1) - (right.file_offset ?? -1));
+    let covered = 0;
+    for (let index = 0; index < sorted.length; index += 1) {
+        const mapping = sorted[index];
+        if (mapping === undefined)
+            continue;
+        const start = mapping.file_offset;
+        const end = start === null ? null : start + mapping.length;
+        const headerMapping = start !== null && end !== null && start >= 0 && end <= header.headerBytes;
+        const moduleMapping = start !== null &&
+            end !== null &&
+            start >= header.headerBytes &&
+            end <= header.imageBytes;
+        const at = `mapping[${index}]`;
+        check(`${at}.source_file_index`, 0, mapping.source_file_index, start, mapping.start);
+        check(`${at}.file_coverage_start`, covered, start, start, mapping.start);
+        check(`${at}.partition`, true, headerMapping || moduleMapping, start, mapping.start);
+        check(`${at}.initialized`, true, mapping.initialized, start, mapping.start);
+        check(`${at}.loaded`, moduleMapping, mapping.loaded, start, mapping.start);
+        check(`${at}.overlay`, headerMapping, mapping.overlay, start, mapping.start);
+        check(`${at}.address_space`, headerMapping ? "HEADER" : observations.default_address_space, mapping.address_space, start, mapping.start);
+        const expectedStart = start === null
+            ? null
+            : headerMapping
+                ? `HEADER:${address(start)}`
+                : address(loadBase + start - header.headerBytes);
+        const expectedEnd = start === null
+            ? null
+            : headerMapping
+                ? `HEADER:${address(start + mapping.length - 1)}`
+                : address(loadBase + start - header.headerBytes + mapping.length - 1);
+        check(`${at}.start`, expectedStart, mapping.start, start, mapping.start);
+        check(`${at}.end`, expectedEnd, mapping.end, start, mapping.end);
+        check(`${at}.memory_sha256`, start !== null && end !== null && end <= bytes.length
+            ? sha256(modified.subarray(start, end))
+            : null, mapping.sha256, start, mapping.start);
+        covered = end ?? covered;
+    }
+    check("initialized_file_coverage_end", header.imageBytes, covered);
+    check("initialized_unbacked_mappings", [], observations.mappings.filter((mapping) => mapping.initialized && mapping.source_file_index === null));
+};
+/** Verify the explicit DOS COM interpretation against measured bytes and context. */
+export const attestGhidraDosComLoadImage = (bytes, targetSha256, observations) => {
+    if (sha256(bytes) !== targetSha256)
+        return err("Ghidra COM snapshot digest does not match the admitted target");
+    const length = validateDosComLength(bytes.length);
+    if (!length.ok)
+        return length;
+    const checks = [];
+    const check = (name, expected, observed, fileOffset = null, location = null) => {
+        checks.push({
+            name,
+            matched: JSON.stringify(expected) === JSON.stringify(observed),
+            expected,
+            observed,
+            file_offset: fileOffset,
+            address: location,
+        });
+    };
+    const source = observations.source_files[0];
+    check("executable_format", "Raw Binary", observations.executable_format);
+    check("language_id", "x86:LE:16:Real Mode", observations.language_id);
+    check("compiler_spec_id", "default", observations.compiler_spec_id);
+    check("image_base", "0x0", observations.image_base);
+    check("default_address_space", "ram", observations.default_address_space);
+    check("source_file_count", 1, observations.source_files.length);
+    check("source_file_size", bytes.length, source?.size ?? null);
+    check("original_file_sha256", targetSha256, source?.original_sha256 ?? null);
+    check("modified_file_sha256", targetSha256, source?.modified_sha256 ?? null);
+    check("entry_points", ["0x10100"], [...observations.entry_points].sort());
+    check("entry_context", [
+        {
+            address: "0x10100",
+            registers: ["CS", "DS", "ES", "SS"].map((name) => ({
+                name,
+                value_hex: "0x1000",
+            })),
+        },
+    ], observations.entry_context);
+    check("relocation_records", [], observations.relocations);
+    checkMappings({ headerBytes: 0, imageBytes: bytes.length }, 0x10100, bytes, bytes, observations, check);
+    return ok(nativeLoadImageSchema.parse({
+        status: checks.every((item) => item.matched) ? "verified" : "mismatch",
+        format: "dos-com",
+        target_sha256: targetSha256,
+        load_segment: 0x1000,
+        header_bytes: 0,
+        module_bytes: bytes.length,
+        overlay_bytes: 0,
+        entry: { relative_segment: 0, offset: 0x100, linear_address: "0x10100" },
+        observations,
+        checks,
+        limitations: [
+            "DOS COM is a headerless interpretation explicitly selected by the caller, not format identification from file bytes.",
+            "Verification covers complete original/modified source identity, mapped file bytes, entry and measured CS/DS/ES/SS entry context. Context 0x1000 is imposed for analysis; it is not an observed running process.",
+            "The PSP, initial stack contents/registers, DOS interrupts, PC-98 devices and runtime behavior are not modeled or verified. No original executable bytes are changed.",
+            "Mapping ends are inclusive; a mismatching digest identifies its source range, not the first differing byte.",
+        ],
+    }));
+};