reverseport 0.0.0-stage → 1.2.0

package/dist/application/LinuxHopper.js

@@ -0,0 +1,232 @@
+import { createHash } from "node:crypto";
+import { execFile } from "node:child_process";
+import { createReadStream } from "node:fs";
+import { access, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { promisify } from "node:util";
+import { execFileOutput } from "../process/ExecFileOutput.js";
+import { downloadHopperPackage, HOPPER_DOWNLOAD_BYTES, } from "./HopperDownload.js";
+const execFileAsync = promisify(execFile);
+const DOWNLOAD_PREFIX = "https://www.hopperapp.com:443/downloader/public/";
+const SUPPORTED_HOPPER_SHA256 = new Set([
+    "0294ced141cc373468ee22d8343e7dac41980cb05a937994ca81c9f09afe7ded",
+    "1339f9e58377442b0c6fcb0dfc3cec20d593cc557408521fad9a00dbc6b8da13",
+]);
+const SUPPORTED_RELEASES = {
+    deb: {
+        filename: `${DOWNLOAD_PREFIX}Hopper-6.4.2-Linux-demo.deb`,
+        file_length: "35755772",
+        file_hash: "e4f79dff602648a8ff4a88b773875b6bfac0dc65",
+    },
+    rpm: {
+        filename: `${DOWNLOAD_PREFIX}Hopper-6.4.2-Linux-demo.rpm`,
+        file_length: "32264475",
+        file_hash: "b9a65f2f583a386d440d4401d9140aef3bf305de",
+    },
+    arch: {
+        filename: `${DOWNLOAD_PREFIX}Hopper-6.4.2-Linux-demo.pkg.tar.xz`,
+        file_length: "29405968",
+        file_hash: "92d780b61cab38eda95dc4112dee4fbeb0920f46",
+    },
+};
+/** Describe the release and package-manager commands without downloading or writing. */
+export const linuxHopperInstallDisclosure = (family, isRoot) => {
+    const release = SUPPORTED_RELEASES[family];
+    return {
+        downloadUrl: release.filename,
+        expectedBytes: Number(release.file_length),
+        expectedSha1: release.file_hash,
+        commands: linuxPackageManagerCommands(family, `<verified-hopper.${family}>`, isRoot).map(({ executable, args }) => `${executable} ${args.join(" ")}`),
+    };
+};
+/** Parse an os-release document without executing its shell syntax. */
+export const parseLinuxDistribution = (text) => {
+    const fields = new Map();
+    for (const line of text.split("\n")) {
+        const match = /^([A-Z_]+)=(.*)$/u.exec(line.trim());
+        if (match === null)
+            continue;
+        const key = match[1];
+        const encoded = match[2];
+        if (key === undefined || encoded === undefined)
+            continue;
+        const value = encoded.startsWith('"') && encoded.endsWith('"')
+            ? encoded.slice(1, -1).replaceAll('\\"', '"').replaceAll("\\\\", "\\")
+            : encoded;
+        fields.set(key, value);
+    }
+    const id = (fields.get("ID") ?? "unknown").toLowerCase();
+    const versionId = fields.get("VERSION_ID");
+    const packageFamily = packageFamilyFor(id, fields.get("ID_LIKE"));
+    const supported = packageFamily !== undefined &&
+        (id === "arch" ||
+            id === "cachyos" ||
+            (id === "omarchy" && packageFamily === "arch") ||
+            (id === "ubuntu" && versionAtLeast(versionId, 24)) ||
+            (id === "fedora" && versionAtLeast(versionId, 41)) ||
+            (id === "nobara" && versionAtLeast(versionId, 44)));
+    const identity = {
+        id,
+        ...(versionId === undefined ? {} : { versionId }),
+    };
+    return supported
+        ? { ...identity, packageFamily, supported: true }
+        : { ...identity, packageFamily, supported: false };
+};
+/** Read and classify the current Linux distribution. */
+export const readLinuxDistribution = async () => {
+    try {
+        return parseLinuxDistribution(await readFile("/etc/os-release", "utf8"));
+    }
+    catch (cause) {
+        // best-effort cleanup: optional host probing; unknown distribution means unsupported.
+        void cause;
+        return undefined;
+    }
+};
+/** Download, verify, install, and read back the official Hopper Linux package. */
+export const installLinuxHopper = async (host = systemLinuxHopperInstallHost(process.env), options = {}) => {
+    if (options.signal?.aborted === true)
+        return { status: "failed", reason: "cancelled" };
+    const distribution = await host.distribution();
+    if (distribution?.supported !== true)
+        return { status: "failed", reason: "unsupported_host" };
+    let temporary;
+    try {
+        const release = (options.releases ?? SUPPORTED_RELEASES)[distribution.packageFamily];
+        const archiveDownload = await host.download(release.filename, options);
+        if (!archiveDownload.ok)
+            return { status: "failed", reason: "download" };
+        if (!packageIntegrityMatches(archiveDownload.bytes, release))
+            return { status: "failed", reason: "integrity" };
+        temporary = await host.createTemporaryDirectory();
+        const archive = join(temporary, `hopper.${distribution.packageFamily}`);
+        await host.writeArchive(archive, archiveDownload.bytes);
+        if (!(await host.installPackage(distribution.packageFamily, archive)))
+            return { status: "failed", reason: "authorization_or_package_manager" };
+        const launcherPath = "/opt/hopper/bin/Hopper";
+        const launcherStatus = await host.launcherStatus(launcherPath);
+        if (launcherStatus !== "ready")
+            return {
+                status: "failed",
+                reason: launcherStatus === "missing" ? "launcher_missing" : launcherStatus,
+            };
+        return { status: "installed", launcherPath };
+    }
+    catch (cause) {
+        if (isAbortCause(cause))
+            return { status: "failed", reason: "cancelled" };
+        return { status: "failed", reason: "download" };
+    }
+    finally {
+        if (temporary !== undefined)
+            await host.cleanup(temporary);
+    }
+};
+/** Canonical launcher path for a legacy user-local Linux Hopper installation. */
+export const linuxHopperLauncherPath = (home) => join(home, ".local/share/rea/hopper/bin/Hopper");
+/** Compose package-manager and linker checks from the selected caller environment. */
+export const systemLinuxHopperInstallHost = (environment) => ({
+    distribution: readLinuxDistribution,
+    download: downloadHopperPackage,
+    createTemporaryDirectory: () => mkdtemp(join(tmpdir(), "rea-hopper-")),
+    writeArchive: (path, bytes) => writeFile(path, bytes, { mode: 0o600 }),
+    installPackage: (family, archive) => installSystemPackage(family, archive, environment),
+    async launcherStatus(path) {
+        try {
+            await access(path);
+            const linked = await execFileOutput("ldd", [path], { env: environment });
+            if (!linuxSharedLibrariesAvailable(`${linked.stdout}\n${linked.stderr}`))
+                return "runtime_dependencies";
+            return (await linuxHopperBinarySupported(path))
+                ? "ready"
+                : "unsupported_hopper_build";
+        }
+        catch (cause) {
+            // best-effort cleanup: optional launcher probing; unreadable means missing.
+            void cause;
+            return "missing";
+        }
+    },
+    cleanup: (path) => rm(path, { recursive: true, force: true }),
+});
+/** Match the Linux Hopper build validated by the packaged demo-dialog adapter. */
+export const linuxHopperBinarySupported = async (path) => {
+    try {
+        const hash = createHash("sha256");
+        for await (const chunk of createReadStream(path))
+            hash.update(chunk);
+        return linuxHopperLauncherDigestSupported(hash.digest("hex"));
+    }
+    catch (cause) {
+        // best-effort cleanup: optional build probing; unreadable means unsupported.
+        void cause;
+        return false;
+    }
+};
+/** Match a launcher extracted from one of the pinned official Linux packages. */
+export const linuxHopperLauncherDigestSupported = (digest) => SUPPORTED_HOPPER_SHA256.has(digest);
+/** Interpret ldd output conservatively so a present but broken launcher is unhealthy. */
+export const linuxSharedLibrariesAvailable = (output) => !/(?:=>\s+not found|error while loading shared libraries)/iu.test(output);
+const installSystemPackage = async (family, archive, environment) => {
+    try {
+        for (const command of linuxPackageManagerCommands(family, archive, process.getuid?.() === 0))
+            await execFileAsync(command.executable, command.args, {
+                env: environment,
+            });
+        return true;
+    }
+    catch (cause) {
+        // Package-manager failure is reported by the false return.
+        void cause;
+        return false;
+    }
+};
+/** Select the native package manager and authorization boundary without shell evaluation. */
+export const linuxPackageManagerCommands = (family, archive, isRoot) => {
+    const runtimeDependencies = family === "deb"
+        ? ["xvfb", "xauth", "python3", "libx11-6", "libxtst6"]
+        : family === "rpm"
+            ? [
+                "xorg-x11-server-Xvfb",
+                "xorg-x11-xauth",
+                "python3",
+                "libX11",
+                "libXtst",
+            ]
+            : ["xorg-server-xvfb", "xorg-xauth", "python", "libx11", "libxtst"];
+    const commands = family === "deb"
+        ? [["apt-get", "install", "-y", archive, ...runtimeDependencies]]
+        : family === "rpm"
+            ? [["dnf", "install", "-y", archive, ...runtimeDependencies]]
+            : [
+                ["pacman", "-S", "--needed", "--noconfirm", ...runtimeDependencies],
+                ["pacman", "-U", "--noconfirm", archive],
+            ];
+    return commands.map((command) => {
+        const executable = isRoot ? command[0] : "pkexec";
+        if (executable === undefined)
+            throw new Error("package command is empty");
+        return { executable, args: isRoot ? command.slice(1) : command };
+    });
+};
+const packageIntegrityMatches = (bytes, release) => bytes.byteLength === Number(release.file_length) &&
+    bytes.byteLength <= HOPPER_DOWNLOAD_BYTES &&
+    createHash("sha1").update(bytes).digest("hex") === release.file_hash;
+const packageFamilyFor = (id, idLike) => {
+    const identities = new Set([
+        id,
+        ...(idLike?.toLowerCase().split(/\s+/u) ?? []),
+    ]);
+    if (identities.has("ubuntu") || identities.has("debian"))
+        return "deb";
+    if (identities.has("fedora") || identities.has("rhel"))
+        return "rpm";
+    if (identities.has("arch"))
+        return "arch";
+    return undefined;
+};
+const versionAtLeast = (version, minimum) => version !== undefined &&
+    Number.parseInt(version.split(".")[0] ?? "0", 10) >= minimum;
+const isAbortCause = (cause) => cause instanceof Error && cause.name === "AbortError";

package/dist/application/MacHopper.js

@@ -0,0 +1,235 @@
+import { createHash } from "node:crypto";
+import { execFile } from "node:child_process";
+import { access, mkdir, mkdtemp, readdir, rename, rm, writeFile, } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { promisify } from "node:util";
+import { z } from "zod";
+import { homeDirectoryFromEnvironment } from "../config/homeDirectory.js";
+import { downloadHopperPackage, HOPPER_DOWNLOAD_BYTES, } from "./HopperDownload.js";
+const execFileAsync = promisify(execFile);
+const RELEASES_URL = "https://www.hopperapp.com/include/files-api.php?request=releases&public=true";
+const DOWNLOAD_PREFIX = "https://www.hopperapp.com:443/downloader/public/";
+const BUNDLE_IDENTIFIER = "com.cryptic-apps.hopper-web-4";
+/** Stable network and command effects disclosed before macOS Hopper setup. */
+export const macHopperInstallDisclosure = {
+    networkOrigins: [RELEASES_URL, DOWNLOAD_PREFIX],
+    commands: [
+        "hdiutil attach -readonly -nobrowse -mountpoint <private-mount> <verified-hopper.dmg>",
+        "codesign --verify --deep --strict <mounted-hopper.app>",
+        "ditto <mounted-hopper.app> <user-Applications-stage>",
+        "open <installed-hopper.app>",
+    ],
+};
+/** Download, verify, and install Hopper into the current user's Applications directory. */
+export const installMacHopper = async (options = {}, host = systemMacHopperInstallHost(homeDirectoryFromEnvironment(process.env, process.platform), process.env)) => {
+    let temporary;
+    let mounted = false;
+    let result;
+    try {
+        result = await (async () => {
+            const metadata = await host.download(RELEASES_URL);
+            if (!metadata.ok)
+                return { status: "failed", reason: "release_metadata" };
+            const parsed = releasesSchema.safeParse(parseJson(metadata.bytes));
+            if (!parsed.success)
+                return { status: "failed", reason: "release_metadata" };
+            const release = parsed.data["OS X"];
+            if (!release.filename.startsWith(DOWNLOAD_PREFIX))
+                return { status: "failed", reason: "release_metadata" };
+            const archive = await host.download(release.filename);
+            if (!archive.ok)
+                return { status: "failed", reason: "download" };
+            if (!integrityMatches(archive.bytes, release))
+                return { status: "failed", reason: "integrity" };
+            const destination = host.destination();
+            const destinationExists = await host.destinationExists(destination);
+            if (destinationExists && options.replaceExisting !== true)
+                return { status: "failed", reason: "destination_exists" };
+            temporary = await host.createTemporaryDirectory();
+            const packagePath = join(temporary, "hopper.dmg");
+            const mountPath = join(temporary, "mounted");
+            await host.createMountDirectory(mountPath);
+            await host.writePackage(packagePath, archive.bytes);
+            if (!(await host.mount(packagePath, mountPath)))
+                return { status: "failed", reason: "mount" };
+            mounted = true;
+            const source = await host.appBundle(mountPath);
+            if (source === undefined || !(await host.validBundle(source)))
+                return { status: "failed", reason: "bundle" };
+            const stage = `${destination}.rea-stage`;
+            if (!(await host.installBundle(source, destination, stage, destinationExists)))
+                return { status: "failed", reason: "copy" };
+            const launcherPath = join(destination, "Contents/MacOS/hopper");
+            if (!(await host.launcherReady(launcherPath)))
+                return { status: "failed", reason: "launcher_missing" };
+            await host.openApplication(destination);
+            return { status: "installed", launcherPath };
+        })();
+    }
+    catch (cause) {
+        // Install-stage failures share the download reason; the stage is cleaned below.
+        void cause;
+        result = { status: "failed", reason: "download" };
+    }
+    let cleanupFailure;
+    if (temporary !== undefined) {
+        const temporaryPath = temporary;
+        const mountPath = join(temporary, "mounted");
+        const cleanup = async () => {
+            if (mounted) {
+                await host.unmount(mountPath);
+                mounted = false;
+            }
+            await host.cleanup(temporaryPath);
+        };
+        try {
+            await cleanup();
+        }
+        catch (cause) {
+            cleanupFailure = `Hopper DMG cleanup failed: ${failureMessage(cause)}`;
+            host.retainCleanup?.(cleanup);
+        }
+    }
+    return cleanupFailure === undefined ? result : { ...result, cleanupFailure };
+};
+/** Compose installer paths and subprocesses from one selected caller context. */
+export const systemMacHopperInstallHost = (homeDirectory, environment) => {
+    const pendingCleanup = new Set();
+    return {
+        download: downloadHopperPackage,
+        createTemporaryDirectory: () => mkdtemp(join(tmpdir(), "rea-hopper-mac-")),
+        createMountDirectory: (path) => mkdir(path),
+        writePackage: (path, bytes) => writeFile(path, bytes, { mode: 0o600 }),
+        async mount(packagePath, mountPath) {
+            return commandSucceeds("hdiutil", [
+                "attach",
+                "-readonly",
+                "-nobrowse",
+                "-mountpoint",
+                mountPath,
+                packagePath,
+            ], environment);
+        },
+        async unmount(mountPath) {
+            if (!(await commandSucceeds("hdiutil", ["detach", mountPath, "-force"], environment)))
+                throw new Error(`hdiutil detach failed for ${JSON.stringify(mountPath)}`);
+        },
+        async appBundle(mountPath) {
+            const entries = await readdir(mountPath, { withFileTypes: true });
+            const app = entries.find((entry) => entry.isDirectory() && /^Hopper.*\.app$/iu.test(entry.name));
+            return app === undefined ? undefined : join(mountPath, app.name);
+        },
+        async validBundle(appPath) {
+            if (!(await commandSucceeds("codesign", ["--verify", "--deep", "--strict", appPath], environment)))
+                return false;
+            try {
+                const identifier = (await execFileAsync("/usr/libexec/PlistBuddy", [
+                    "-c",
+                    "Print :CFBundleIdentifier",
+                    join(appPath, "Contents/Info.plist"),
+                ], { env: environment })).stdout.trim();
+                return identifier === BUNDLE_IDENTIFIER;
+            }
+            catch (cause) {
+                // best-effort cleanup: optional bundle probing; unreadable means invalid.
+                void cause;
+                return false;
+            }
+        },
+        async destinationExists(path) {
+            try {
+                await access(path);
+                return true;
+            }
+            catch (cause) {
+                // best-effort cleanup: optional existence probing; absence means missing.
+                void cause;
+                return false;
+            }
+        },
+        async installBundle(source, destination, stage, replaceExisting) {
+            const previous = `${stage}-previous`;
+            try {
+                await mkdir(join(homeDirectory, "Applications"), { recursive: true });
+                await rm(stage, { recursive: true, force: true });
+                await rm(previous, { recursive: true, force: true });
+                await execFileAsync("ditto", [source, stage], { env: environment });
+                await access(join(stage, "Contents/MacOS/hopper"));
+                if (replaceExisting)
+                    await rename(destination, previous);
+                await rename(stage, destination);
+                if (replaceExisting)
+                    await rm(previous, { recursive: true, force: true });
+                return true;
+            }
+            catch (cause) {
+                // Install failure rolls back below; the false return reports it.
+                void cause;
+                await rm(stage, { recursive: true, force: true });
+                if (replaceExisting) {
+                    try {
+                        await rename(previous, destination);
+                    }
+                    catch (rollbackCause) {
+                        // The original destination was not moved, or rollback is impossible.
+                        void rollbackCause;
+                    }
+                }
+                return false;
+            }
+        },
+        async launcherReady(path) {
+            try {
+                await access(path);
+                return true;
+            }
+            catch (cause) {
+                // best-effort cleanup: optional launcher probing; absence means not ready.
+                void cause;
+                return false;
+            }
+        },
+        async openApplication(path) {
+            await execFileAsync("open", [path], { env: environment });
+        },
+        cleanup: (path) => rm(path, { recursive: true, force: true }),
+        retainCleanup: (cleanup) => pendingCleanup.add(cleanup),
+        async close() {
+            let failure;
+            for (const cleanup of pendingCleanup) {
+                try {
+                    await cleanup();
+                    pendingCleanup.delete(cleanup);
+                }
+                catch (cause) {
+                    failure ??= `Hopper DMG cleanup remains incomplete: ${failureMessage(cause)}`;
+                }
+            }
+            return failure;
+        },
+        destination: () => join(homeDirectory, "Applications/Hopper Disassembler.app"),
+    };
+};
+const parseJson = (bytes) => JSON.parse(new TextDecoder().decode(bytes));
+const integrityMatches = (bytes, release) => bytes.byteLength === Number(release.file_length) &&
+    bytes.byteLength <= HOPPER_DOWNLOAD_BYTES &&
+    createHash("sha1").update(bytes).digest("hex") === release.file_hash;
+const commandSucceeds = async (command, args, environment) => {
+    try {
+        await execFileAsync(command, args, { env: environment });
+        return true;
+    }
+    catch (cause) {
+        // best-effort cleanup: optional command probing; failure means unavailable.
+        void cause;
+        return false;
+    }
+};
+const failureMessage = (cause) => cause instanceof Error ? cause.message : String(cause);
+const releaseSchema = z.object({
+    filename: z.string().url(),
+    file_length: z.string().regex(/^\d+$/u),
+    file_hash: z.string().regex(/^[a-f0-9]{40}$/u),
+});
+const releasesSchema = z.object({ "OS X": releaseSchema });

package/dist/application/MipsElfMetadata.js

@@ -0,0 +1,175 @@
+import { err, ok } from "../domain/result.js";
+import { readMipsElfSharedLoad, } from "./MipsElfSharedLoad.js";
+/**
+ * Read ELF32 MIPS ABI and shared-load declarations from the caller's already-open file.
+ * Inspect both typed tables (not section names), including records beyond the
+ * initial header probe. A missing record is unknown, not a default FP ABI.
+ * The caller supplies its cancellation check so its tagged error is preserved.
+ */
+export const readMipsElfMetadata = async (handle, metadata, checkCancelled) => {
+    checkCancelled();
+    if (metadata.elfClass !== 32)
+        return err("MIPS ABI record inspection currently supports ELF32 only");
+    const fileSize = (await handle.stat()).size;
+    checkCancelled();
+    const read = async (offset, length, label) => {
+        checkCancelled();
+        if (!Number.isSafeInteger(fileSize) ||
+            offset < 0 ||
+            length < 0 ||
+            offset > fileSize - length)
+            return err(`MIPS ${label} lies outside the file`);
+        const bytes = Buffer.alloc(length);
+        let total = 0;
+        while (total < length) {
+            checkCancelled();
+            const observed = await handle.read(bytes, total, length - total, offset + total);
+            checkCancelled();
+            if (observed.bytesRead === 0)
+                return err(`truncated MIPS ${label}`);
+            total += observed.bytesRead;
+        }
+        return ok(bytes);
+    };
+    const header = await read(0, 52, "ELF32 header");
+    if (!header.ok)
+        return header;
+    const bytes = header.value;
+    const little = metadata.byteOrder === "little";
+    const u16 = (data, offset) => little ? data.readUInt16LE(offset) : data.readUInt16BE(offset);
+    const u32 = (data, offset) => little ? data.readUInt32LE(offset) : data.readUInt32BE(offset);
+    if (bytes.toString("hex", 0, 4) !== "7f454c46" ||
+        bytes[4] !== 1 ||
+        bytes[5] !== (little ? 1 : 2) ||
+        u16(bytes, 18) !== 8 ||
+        u16(bytes, 16) !== metadata.type ||
+        u32(bytes, 36) !== metadata.flags)
+        return err("MIPS ELF header no longer matches the resolved identity");
+    if (bytes[6] !== 1 || u32(bytes, 20) !== 1 || u16(bytes, 40) !== 52)
+        return err("invalid MIPS ELF32 version or header size");
+    const tables = [
+        {
+            label: "program header table",
+            offset: u32(bytes, 28),
+            count: u16(bytes, 44),
+            stride: u16(bytes, 42),
+            entrySize: 32,
+            typeOffset: 0,
+            dataOffset: 4,
+            sizeOffset: 16,
+            recordType: 0x70000003, // PT_MIPS_ABIFLAGS
+            optional: false,
+        },
+        {
+            label: "section header table",
+            offset: u32(bytes, 32),
+            count: u16(bytes, 48),
+            stride: u16(bytes, 46),
+            entrySize: 40,
+            typeOffset: 4,
+            dataOffset: 16,
+            sizeOffset: 20,
+            recordType: 0x7000002a, // SHT_MIPS_ABIFLAGS
+            optional: true,
+        },
+    ];
+    // Extended numbering needs a separate section-zero reader. Refuse it rather
+    // than silently treating an unexamined table as having no ABI declarations.
+    if (u16(bytes, 44) === 0xffff || u16(bytes, 48) >= 0xff00)
+        return err("extended or reserved MIPS ELF table numbering is unsupported");
+    let record;
+    let sharedLoad;
+    let programHeaders;
+    const relocationSections = [];
+    const limitations = [];
+    for (const table of tables) {
+        if (table.count === 0) {
+            if (table.offset !== 0)
+                return err(`unsupported extended or inconsistent MIPS ${table.label}`);
+            continue;
+        }
+        if (table.offset < 52 || table.stride !== table.entrySize)
+            return err(`invalid MIPS ${table.label} offset or entry size`);
+        const count = table.optional
+            ? Math.min(table.count, Math.max(0, Math.floor((fileSize - table.offset) / table.entrySize)))
+            : table.count;
+        if (count < table.count)
+            limitations.push(`MIPS ${table.label} at file offset ${table.offset} extends beyond the captured file: examined ${count} of ${table.count} complete headers. ABI declarations in unavailable headers remain unknown.`);
+        if (count === 0)
+            continue;
+        // Counts are bounded by the ELF16 fields and strides by their exact ELF32
+        // structure sizes. Never allocate according to an untrusted section size.
+        const contents = await read(table.offset, count * table.entrySize, table.label);
+        if (!contents.ok)
+            return contents;
+        if (!table.optional && metadata.type === 3)
+            programHeaders = contents.value;
+        let found = false;
+        for (let i = 0; i < count; i += 1) {
+            checkCancelled();
+            const position = i * table.entrySize;
+            const type = u32(contents.value, position + table.typeOffset);
+            if (metadata.type === 3 && table.optional && (type === 4 || type === 9))
+                relocationSections.push({
+                    type,
+                    offset: u32(contents.value, position + 16),
+                    size: u32(contents.value, position + 20),
+                    entrySize: u32(contents.value, position + 36),
+                });
+            if (type !== table.recordType)
+                continue;
+            if (found)
+                return err(`duplicate MIPS ABI records in ${table.label}`);
+            found = true;
+            const offset = u32(contents.value, position + table.dataOffset);
+            const size = u32(contents.value, position + table.sizeOffset);
+            if (size !== 24)
+                return err("unsupported MIPS ABI record size; expected 24 bytes");
+            const candidate = await read(offset, 24, "ABI record");
+            if (!candidate.ok)
+                return candidate;
+            if (record !== undefined && !record.equals(candidate.value))
+                return err("conflicting MIPS program/section ABI declarations");
+            record = candidate.value;
+        }
+    }
+    if (metadata.type === 3 && programHeaders !== undefined) {
+        if (limitations.length > 0)
+            sharedLoad = {
+                status: "unavailable",
+                reason: `MIPS shared-image relocation declaration sources are incomplete. ${limitations.join(" ")}`,
+            };
+        else {
+            const shared = await readMipsElfSharedLoad(programHeaders, little, fileSize, read, checkCancelled, relocationSections);
+            sharedLoad = shared.ok
+                ? shared.value
+                : { status: "unavailable", reason: shared.error };
+        }
+    }
+    const shared = metadata.type === 3
+        ? {
+            sharedLoad: sharedLoad ?? {
+                status: "unavailable",
+                reason: "MIPS shared image has no inspected program header table",
+            },
+        }
+        : {};
+    if (record === undefined)
+        return ok({ abiFlags: null, limitations, ...shared });
+    // Preserve declarations verbatim, including unknown versions/values. Provider
+    // admission, not parsing, decides which interpretations have been verified.
+    const abiFlags = {
+        version: u16(record, 0),
+        isaLevel: record.readUInt8(2),
+        isaRevision: record.readUInt8(3),
+        gprSize: record.readUInt8(4),
+        cpr1Size: record.readUInt8(5),
+        cpr2Size: record.readUInt8(6),
+        fpAbi: record.readUInt8(7),
+        isaExtension: u32(record, 8),
+        ases: u32(record, 12),
+        flags1: u32(record, 16),
+        flags2: u32(record, 20),
+    };
+    return ok({ abiFlags, limitations, ...shared });
+};