rn-update-cli 1.0.0

package/lib/utils/hermes-base.js

@@ -0,0 +1,1287 @@
+"use strict";
+/**
+ * [INPUT]: 依赖 Node 子进程/文件流/HTTP Range、Pakta CLI 临时目录与 ZIP 读取原语
+ * [OUTPUT]: 对外提供 Hermes base 选择、缓存、二进制字面量/指令等价校验、下载、清理及发布元数据能力
+ * [POS]: CLI Hermes delta 优化边界，所有失败降级到普通编译，不阻塞发布流程
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LITERAL_SEPARATOR = exports.DEFAULT_CACHE_MAX_FILES = exports.DEFAULT_CACHE_MAX_BYTES = exports.BUNDLE_ENTRY_NAMES = exports.MIN_HERMES_COMPILER_COMMITLY_DATE = exports.MIN_HERMES_COMPILER_BUILD = exports.HERMES_BASE_DETAIL_MAX_CHARS = exports.BundleHashMismatchError = exports.PermanentBaseError = void 0;
+exports.classifyHermesCommand = classifyHermesCommand;
+exports.sha256Hex = sha256Hex;
+exports.sha256File = sha256File;
+exports.readFileHbcVersion = readFileHbcVersion;
+exports.probeHbcVersion = probeHbcVersion;
+exports.bundleEntryMatcher = bundleEntryMatcher;
+exports.extractBundleFromArchive = extractBundleFromArchive;
+exports.cacheDir = cacheDir;
+exports.tmpDir = tmpDir;
+exports.cacheLimits = cacheLimits;
+exports.cacheLookup = cacheLookup;
+exports.cachePut = cachePut;
+exports.enforceCacheLimits = enforceCacheLimits;
+exports.cleanCache = cleanCache;
+exports.cacheStats = cacheStats;
+exports.cleanStaleTmp = cleanStaleTmp;
+exports.downloadToFile = downloadToFile;
+exports.fetchBaseBundle = fetchBaseBundle;
+exports.resolveHermesBase = resolveHermesBase;
+exports.hermescArgsWithBase = hermescArgsWithBase;
+exports.hermesBaseMeta = hermesBaseMeta;
+exports.truncateHermesBaseDetail = truncateHermesBaseDetail;
+exports.normalizeDisassemblyLine = normalizeDisassemblyLine;
+exports.compareHermesBytecode = compareHermesBytecode;
+exports.verifyHermesBaseEquivalence = verifyHermesBaseEquivalence;
+// Hermes `-base-bytecode` (delta optimizing mode) support.
+//
+// Hermes re-sorts its string table by identifier frequency on every compile, so
+// any source change renumbers most string IDs and the bytecode diff explodes
+// (see hermes-base-bytecode-方案.md). Compiling with the previous HBC of the
+// same app as `-base-bytecode` keeps old IDs stable and shrinks patches 5-30×.
+// This module resolves that base: gating by hermesc build, HBC version probe,
+// server lookup, a sha256-named local cache, download + verification, and the
+// optional disassembly equivalence check. Every failure degrades to the plain
+// compile — nothing here may block a release.
+const child_process_1 = require("child_process");
+const crypto_1 = require("crypto");
+const fs_extra_1 = __importDefault(require("fs-extra"));
+const os_1 = __importDefault(require("os"));
+const path_1 = __importDefault(require("path"));
+const stream_1 = require("stream");
+const promises_1 = require("stream/promises");
+const constants_1 = require("./constants");
+const hbcTransform_1 = require("./hbcTransform");
+const hermes_literals_1 = require("./hermes-literals");
+const i18n_1 = require("./i18n");
+const runtime_1 = require("./runtime");
+const zip_entries_1 = require("./zip-entries");
+const zip_range_1 = require("./zip-range");
+/**
+ * The base cannot be obtained whatever the transport or how often it is
+ * retried (wrong content on the server, no bundle in the package, ...).
+ */
+class PermanentBaseError extends Error {
+}
+exports.PermanentBaseError = PermanentBaseError;
+/** The fetched bundle's sha256 differs from what the server recorded. */
+class BundleHashMismatchError extends PermanentBaseError {
+    constructor(actual, expected) {
+        super(`bundleHash mismatch (${actual.slice(0, 12)} != ${expected.slice(0, 12)})`);
+    }
+}
+exports.BundleHashMismatchError = BundleHashMismatchError;
+/** time allowed for a response to start (headers) */
+const FETCH_HEADERS_TIMEOUT_MS = 30_000;
+/** a download that receives nothing for this long is abandoned */
+const STREAM_IDLE_TIMEOUT_MS = 60_000;
+/** cachePut leftovers (`<hash>.<pid>.tmp`) older than this are evicted */
+const STALE_CACHE_TMP_MS = 60 * 60 * 1000;
+/** the server column is VARCHAR(500); it truncates too, this just saves bytes */
+exports.HERMES_BASE_DETAIL_MAX_CHARS = 500;
+// ---------------------------------------------------------------------------
+// hermesc gating
+// ---------------------------------------------------------------------------
+/**
+ * Hermes V1 (static_h) builds before 2025-07-11 carried a delta-mode bug when a
+ * delta-produced base is reused; every released `hermes-compiler` is newer, and
+ * classic hermesc (HBC ≤96, react-native/sdks or hermes-engine) upgrades kinds
+ * in place and was never affected. Anything else is refused.
+ */
+exports.MIN_HERMES_COMPILER_BUILD = 250829098;
+exports.MIN_HERMES_COMPILER_COMMITLY_DATE = 20250901;
+function classifyHermesCommand(hermesCommand) {
+    const normalized = hermesCommand.split(path_1.default.sep).join('/');
+    if (/\/react-native\/sdks\/hermesc\//.test(normalized) ||
+        /\/hermes-engine\//.test(normalized)) {
+        return { allowed: true, kind: 'classic' };
+    }
+    const match = /\/hermes-compiler\//.exec(normalized);
+    if (match) {
+        const packageRoot = normalized.slice(0, match.index + match[0].length);
+        let version = '';
+        try {
+            version = String(JSON.parse(fs_extra_1.default.readFileSync(path_1.default.join(packageRoot, 'package.json'), 'utf8')).version ?? '');
+        }
+        catch {
+            return {
+                allowed: false,
+                kind: 'hermes-compiler',
+                reason: 'unreadable hermes-compiler version',
+            };
+        }
+        const build = /^(\d{9})\./.exec(version);
+        if (build) {
+            const ok = Number(build[1]) >= exports.MIN_HERMES_COMPILER_BUILD;
+            return {
+                allowed: ok,
+                kind: 'hermes-compiler',
+                version,
+                reason: ok
+                    ? undefined
+                    : `hermes-compiler ${version} predates the delta-mode fix`,
+            };
+        }
+        const commitly = /^0\.(\d+)\.\d+-commitly-(\d{8})/.exec(version);
+        if (commitly) {
+            const ok = Number(commitly[1]) >= 14 &&
+                Number(commitly[2]) >= exports.MIN_HERMES_COMPILER_COMMITLY_DATE;
+            return {
+                allowed: ok,
+                kind: 'hermes-compiler',
+                version,
+                reason: ok
+                    ? undefined
+                    : `hermes-compiler ${version} predates the delta-mode fix`,
+            };
+        }
+        const stable = /^0\.(\d+)\.\d+$/.exec(version);
+        if (stable) {
+            const ok = Number(stable[1]) >= 14;
+            return {
+                allowed: ok,
+                kind: 'hermes-compiler',
+                version,
+                reason: ok
+                    ? undefined
+                    : `hermes-compiler ${version} predates the delta-mode fix`,
+            };
+        }
+        return {
+            allowed: false,
+            kind: 'hermes-compiler',
+            version,
+            reason: `unrecognized hermes-compiler version ${version}`,
+        };
+    }
+    return {
+        allowed: false,
+        kind: 'unknown',
+        reason: 'hermesc location not recognized',
+    };
+}
+// ---------------------------------------------------------------------------
+// HBC helpers
+// ---------------------------------------------------------------------------
+function sha256Hex(data) {
+    return (0, crypto_1.createHash)('sha256').update(data).digest('hex');
+}
+/** sha256 of a file, streamed (a cached base can be tens of MB) */
+async function sha256File(file) {
+    const hash = (0, crypto_1.createHash)('sha256');
+    for await (const chunk of fs_extra_1.default.createReadStream(file))
+        hash.update(chunk);
+    return hash.digest('hex');
+}
+/** HBC version from the first bytes of a file, without reading the rest */
+async function readFileHbcVersion(file) {
+    const header = Buffer.alloc(128);
+    const fd = await fs_extra_1.default.open(file, 'r');
+    try {
+        const { bytesRead } = await fs_extra_1.default.read(fd, header, 0, 128, 0);
+        return (0, hbcTransform_1.getHbcVersion)(header.subarray(0, bytesRead));
+    }
+    catch {
+        return null;
+    }
+    finally {
+        await fs_extra_1.default.close(fd);
+    }
+}
+const PROBE_CACHE_FILE = 'hbc-versions.json';
+const PROBE_CACHE_ENTRIES = 16;
+/** identity of a hermesc binary for the probe cache: path + size + mtime */
+function probeCacheKey(hermesCommand) {
+    try {
+        const stat = fs_extra_1.default.statSync(hermesCommand);
+        return `${path_1.default.resolve(hermesCommand)}|${stat.size}|${Math.floor(stat.mtimeMs)}`;
+    }
+    catch {
+        return null;
+    }
+}
+function readProbeCache() {
+    try {
+        const parsed = JSON.parse(fs_extra_1.default.readFileSync(path_1.default.join(cacheDir(), PROBE_CACHE_FILE), 'utf8'));
+        return parsed && typeof parsed === 'object' ? parsed : {};
+    }
+    catch {
+        return {};
+    }
+}
+function writeProbeCache(entries) {
+    try {
+        const keys = Object.keys(entries);
+        // keep the most recently inserted entries only
+        const trimmed = Object.fromEntries(keys.slice(-PROBE_CACHE_ENTRIES).map((key) => [key, entries[key]]));
+        fs_extra_1.default.ensureDirSync(cacheDir());
+        fs_extra_1.default.writeFileSync(path_1.default.join(cacheDir(), PROBE_CACHE_FILE), JSON.stringify(trimmed));
+    }
+    catch {
+        // the cache is a convenience; probing again next time is fine
+    }
+}
+/**
+ * Which HBC version this hermesc emits. The answer is remembered per binary
+ * (path, size, mtime) in the cache dir so only the first run of a given
+ * hermesc pays for the empty-file compile.
+ */
+function probeHbcVersion(hermesCommand) {
+    const key = probeCacheKey(hermesCommand);
+    if (key) {
+        const cached = readProbeCache()[key];
+        if (Number.isInteger(cached) && cached > 0)
+            return cached;
+    }
+    const version = compileProbe(hermesCommand);
+    if (key && version !== null) {
+        const { [key]: _stale, ...others } = readProbeCache();
+        writeProbeCache({ ...others, [key]: version });
+    }
+    return version;
+}
+/** Compile an empty file to learn which HBC version this hermesc emits. */
+function compileProbe(hermesCommand) {
+    const dir = fs_extra_1.default.mkdtempSync(path_1.default.join(os_1.default.tmpdir(), 'rnu-hermes-probe-'));
+    try {
+        const input = path_1.default.join(dir, 'probe.js');
+        const output = path_1.default.join(dir, 'probe.hbc');
+        fs_extra_1.default.writeFileSync(input, '');
+        const result = (0, child_process_1.spawnSync)(hermesCommand, ['-emit-binary', '-out', output, input, '-O', '-w'], { stdio: 'ignore' });
+        if (result.status !== 0 || !fs_extra_1.default.existsSync(output)) {
+            return null;
+        }
+        const header = Buffer.alloc(128);
+        const fd = fs_extra_1.default.openSync(output, 'r');
+        try {
+            fs_extra_1.default.readSync(fd, header, 0, 128, 0);
+        }
+        finally {
+            fs_extra_1.default.closeSync(fd);
+        }
+        return (0, hbcTransform_1.getHbcVersion)(header);
+    }
+    catch {
+        return null;
+    }
+    finally {
+        fs_extra_1.default.removeSync(dir);
+    }
+}
+exports.BUNDLE_ENTRY_NAMES = [
+    'index.bundlejs',
+    'main.jsbundle',
+    'bundle.harmony.js',
+];
+const APK_BUNDLE = /^assets\/index\.android\.bundle$/;
+const IPA_BUNDLE = /^payload\/[^/]+\.app\/main\.jsbundle$/i;
+/** Which zip entry holds the JS/HBC bundle in each kind of artifact. */
+function bundleEntryMatcher(artifactType) {
+    switch (artifactType) {
+        case 'apk':
+            return (name) => APK_BUNDLE.test(name);
+        case 'ipa':
+            return (name) => IPA_BUNDLE.test(name.toLowerCase());
+        default:
+            return (name) => exports.BUNDLE_ENTRY_NAMES.includes(name);
+    }
+}
+/**
+ * Extract the JS/HBC bundle from a local artifact: a raw bundle file, a ppk,
+ * or a native package (apk / ipa / harmony app). Returns null when not found.
+ */
+async function extractBundleFromArchive(filePath) {
+    const ext = path_1.default.extname(filePath).toLowerCase();
+    if (ext === '.hbc' ||
+        ext === '.bundle' ||
+        ext === '.jsbundle' ||
+        ext === '.bundlejs' ||
+        ext === '.js') {
+        return fs_extra_1.default.readFile(filePath);
+    }
+    if (ext === '.ppk' || ext === '.apk' || ext === '.ipa') {
+        return readFirstZipEntry(filePath, bundleEntryMatcher(ext.slice(1)));
+    }
+    if (ext === '.app') {
+        // harmony .app wraps .hap archives; reuse the existing parser
+        const { default: AppInfoParser } = await Promise.resolve().then(() => __importStar(require('./app-info-parser')));
+        const parser = new AppInfoParser(filePath);
+        const [bundle] = await parser.parser.getEntriesFromHarmonyApp([
+            /^resources\/rawfile\/bundle\.harmony\.js$/,
+        ]);
+        return bundle ?? null;
+    }
+    // unknown extension: try as zip, then as raw file
+    const fromZip = await readFirstZipEntry(filePath, (name) => exports.BUNDLE_ENTRY_NAMES.includes(name)).catch(() => null);
+    return fromZip ?? fs_extra_1.default.readFile(filePath);
+}
+async function readFirstZipEntry(zipPath, matches) {
+    let found = null;
+    await (0, zip_entries_1.enumZipEntries)(zipPath, async (entry, zipFile) => {
+        if (!found && matches(entry.fileName)) {
+            found = await (0, zip_entries_1.readEntry)(entry, zipFile);
+        }
+    });
+    return found;
+}
+// ---------------------------------------------------------------------------
+// cache (sha256-named bundles)
+// ---------------------------------------------------------------------------
+exports.DEFAULT_CACHE_MAX_BYTES = 500 * 1024 * 1024;
+exports.DEFAULT_CACHE_MAX_FILES = 20;
+function cacheDir() {
+    return process.env.PAKTA_CACHE_DIR || path_1.default.join(constants_1.tempDir, 'cache');
+}
+function tmpDir() {
+    return path_1.default.join(constants_1.tempDir, 'tmp');
+}
+function cacheLimits(overrideMaxMb) {
+    const envMb = Number(process.env.PAKTA_CACHE_MAX_MB);
+    const maxBytes = overrideMaxMb && overrideMaxMb > 0
+        ? overrideMaxMb * 1024 * 1024
+        : Number.isFinite(envMb) && envMb > 0
+            ? envMb * 1024 * 1024
+            : exports.DEFAULT_CACHE_MAX_BYTES;
+    return { maxBytes, maxFiles: exports.DEFAULT_CACHE_MAX_FILES };
+}
+/** Returns the cached bundle path when present and its sha256 still matches. */
+async function cacheLookup(bundleHash) {
+    if (!/^[0-9a-f]{64}$/.test(bundleHash))
+        return null;
+    const file = path_1.default.join(cacheDir(), bundleHash);
+    if (!(await fs_extra_1.default.pathExists(file)))
+        return null;
+    if ((await sha256File(file).catch(() => '')) !== bundleHash) {
+        // corrupt entry: never trust cache content
+        await fs_extra_1.default.remove(file).catch(() => { });
+        return null;
+    }
+    const now = new Date();
+    await fs_extra_1.default.utimes(file, now, now).catch(() => { });
+    return file;
+}
+/** Store a bundle under its sha256 (LRU-evicting to the configured limits). */
+async function cachePut(bundle, maxMb, knownHash) {
+    const bundleHash = knownHash ?? sha256Hex(bundle);
+    const dir = cacheDir();
+    await fs_extra_1.default.ensureDir(dir);
+    const file = path_1.default.join(dir, bundleHash);
+    if (!(await fs_extra_1.default.pathExists(file))) {
+        const tmp = `${file}.${process.pid}.tmp`;
+        await fs_extra_1.default.writeFile(tmp, bundle);
+        await fs_extra_1.default.rename(tmp, file);
+    }
+    else {
+        const now = new Date();
+        await fs_extra_1.default.utimes(file, now, now).catch(() => { });
+    }
+    await enforceCacheLimits(maxMb, bundleHash);
+    return { path: file, bundleHash };
+}
+async function enforceCacheLimits(maxMb, keep) {
+    const dir = cacheDir();
+    if (!(await fs_extra_1.default.pathExists(dir)))
+        return;
+    const { maxBytes, maxFiles } = cacheLimits(maxMb);
+    const entries = [];
+    const staleTmpCutoff = Date.now() - STALE_CACHE_TMP_MS;
+    for (const name of await fs_extra_1.default.readdir(dir)) {
+        const isTmp = isCacheTmpName(name);
+        if (!isTmp && !/^[0-9a-f]{64}$/.test(name))
+            continue;
+        const stat = await fs_extra_1.default.stat(path_1.default.join(dir, name)).catch(() => null);
+        if (!stat?.isFile())
+            continue;
+        if (isTmp) {
+            // an interrupted cachePut; nothing will ever rename it into place
+            if (stat.mtimeMs < staleTmpCutoff)
+                await fs_extra_1.default.remove(path_1.default.join(dir, name)).catch(() => { });
+            continue;
+        }
+        entries.push({ name, size: stat.size, mtime: stat.mtimeMs });
+    }
+    entries.sort((a, b) => b.mtime - a.mtime); // newest first
+    let total = 0;
+    let count = 0;
+    for (const entry of entries) {
+        total += entry.size;
+        count += 1;
+        if (entry.name !== keep && (total > maxBytes || count > maxFiles)) {
+            await fs_extra_1.default.remove(path_1.default.join(dir, entry.name)).catch(() => { });
+        }
+    }
+}
+/** `<sha256>.<pid>.tmp`, the staging name cachePut writes before renaming */
+function isCacheTmpName(name) {
+    return /^[0-9a-f]{64}\.\d+\.tmp$/.test(name);
+}
+/** Remove every cached bundle (and staging leftovers); returns the bundle count. */
+async function cleanCache() {
+    const dir = cacheDir();
+    if (!(await fs_extra_1.default.pathExists(dir)))
+        return 0;
+    let bundles = 0;
+    for (const name of await fs_extra_1.default.readdir(dir)) {
+        const isBundle = /^[0-9a-f]{64}$/.test(name);
+        if (!isBundle && !isCacheTmpName(name))
+            continue;
+        await fs_extra_1.default.remove(path_1.default.join(dir, name));
+        if (isBundle)
+            bundles += 1;
+    }
+    return bundles;
+}
+async function cacheStats() {
+    const dir = cacheDir();
+    let files = 0;
+    let bytes = 0;
+    if (await fs_extra_1.default.pathExists(dir)) {
+        for (const name of await fs_extra_1.default.readdir(dir)) {
+            if (!/^[0-9a-f]{64}$/.test(name))
+                continue;
+            const stat = await fs_extra_1.default.stat(path_1.default.join(dir, name)).catch(() => null);
+            if (stat?.isFile()) {
+                files += 1;
+                bytes += stat.size;
+            }
+        }
+    }
+    return { dir, files, bytes };
+}
+/** Remove leftovers of interrupted runs (older than 24h) from the tmp dir. */
+async function cleanStaleTmp(maxAgeMs = 24 * 60 * 60 * 1000) {
+    const dir = tmpDir();
+    if (!(await fs_extra_1.default.pathExists(dir)))
+        return;
+    const cutoff = Date.now() - maxAgeMs;
+    for (const name of await fs_extra_1.default.readdir(dir)) {
+        const file = path_1.default.join(dir, name);
+        const stat = await fs_extra_1.default.stat(file).catch(() => null);
+        if (stat && stat.mtimeMs < cutoff)
+            await fs_extra_1.default.remove(file).catch(() => { });
+    }
+}
+// ---------------------------------------------------------------------------
+// download
+// ---------------------------------------------------------------------------
+async function downloadToFile(url, destination) {
+    const controller = new AbortController();
+    const headersTimer = setTimeout(() => controller.abort(new Error('timeout waiting for response')), FETCH_HEADERS_TIMEOUT_MS);
+    let response;
+    try {
+        response = await (0, runtime_1.webFetch)(url, { signal: controller.signal });
+    }
+    finally {
+        clearTimeout(headersTimer);
+    }
+    if (!response.ok || !response.body) {
+        throw new Error(`download failed: HTTP ${response.status} ${url}`);
+    }
+    await saveResponse(response, destination, controller);
+}
+function hasBundleLocation(record) {
+    return (record.bundleOffset != null &&
+        record.bundleCompressedSize != null &&
+        record.bundleCompression != null &&
+        (record.bundleCompression === zip_range_1.ZIP_STORED ||
+            record.bundleCompression === zip_range_1.ZIP_DEFLATED));
+}
+/**
+ * Stream a response body to disk, giving up when no bytes arrive for
+ * STREAM_IDLE_TIMEOUT_MS. `controller` is the one the request was made with
+ * (aborting it also tears down the socket); a foreign response gets its own.
+ */
+async function saveResponse(response, destination, controller = new AbortController()) {
+    if (!response.body)
+        throw new Error('empty response body');
+    await fs_extra_1.default.ensureDir(path_1.default.dirname(destination));
+    const abort = () => controller.abort(new Error(`download stalled for ${STREAM_IDLE_TIMEOUT_MS / 1000}s`));
+    let idle = setTimeout(abort, STREAM_IDLE_TIMEOUT_MS);
+    const watchdog = new stream_1.PassThrough({
+        transform(chunk, _encoding, callback) {
+            clearTimeout(idle);
+            idle = setTimeout(abort, STREAM_IDLE_TIMEOUT_MS);
+            callback(null, chunk);
+        },
+    });
+    try {
+        await (0, promises_1.pipeline)(stream_1.Readable.fromWeb(response.body), watchdog, fs_extra_1.default.createWriteStream(destination), { signal: controller.signal });
+    }
+    finally {
+        clearTimeout(idle);
+    }
+}
+/**
+ * Obtain the base bundle with as little traffic as possible, in order:
+ *  1. one Range request for the bundle's compressed bytes when the server
+ *     knows their location (ppk / apk / ipa published by a CLI that
+ *     reported it);
+ *  2. the archive's central directory over Range, then just the bundle
+ *     entry (any zip: ppk, apk, ipa — harmony .app nests a second zip and
+ *     is skipped);
+ *  3. the whole archive, as before.
+ * A server that ignores Range (HTTP 200) streams the full archive into
+ * `archive` without a second request. Every result is verified against
+ * `record.bundleHash`. A mismatch of the located bytes (1) may only mean the
+ * recorded location is stale, so the directory transport (2) still runs; a
+ * mismatch of the entry itself (2, 3) is final — the same bytes would come
+ * back however they are fetched — and raises BundleHashMismatchError.
+ */
+async function fetchBaseBundle(record, artifactType, archive, log = () => { }) {
+    const matches = bundleEntryMatcher(artifactType);
+    const verified = (bundle) => {
+        if (!bundle)
+            throw new PermanentBaseError('bundle entry not found');
+        const bundleHash = sha256Hex(bundle);
+        if (record.bundleHash && bundleHash !== record.bundleHash) {
+            throw new BundleHashMismatchError(bundleHash, record.bundleHash);
+        }
+        return { bundle, bundleHash };
+    };
+    const fromFullResponse = async (response) => {
+        await saveResponse(response, archive);
+        return {
+            ...verified(await extractBundleFromArchive(archive)),
+            transport: 'full',
+        };
+    };
+    const skip = (reason) => log((0, i18n_1.t)('hermesBaseRangeFallback', { reason }));
+    // harmony .app nests the bundle in a second zip, so a location inside the
+    // outer archive is never reported for it
+    if (artifactType !== 'app' && hasBundleLocation(record)) {
+        try {
+            const { data, fetchedBytes, totalBytes } = await (0, zip_range_1.fetchZipEntryData)(record.url, {
+                dataOffset: record.bundleOffset,
+                compressedSize: record.bundleCompressedSize,
+                compressionMethod: record.bundleCompression,
+            });
+            return {
+                ...verified(data),
+                transport: 'range-entry',
+                fetchedBytes,
+                totalBytes,
+            };
+        }
+        catch (error) {
+            if (error instanceof zip_range_1.RangeUnsupportedError) {
+                skip('server ignores Range');
+                return fromFullResponse(error.response);
+            }
+            skip(`entry range: ${error?.message ?? error}`);
+        }
+    }
+    if (artifactType !== 'app') {
+        try {
+            const remote = await (0, zip_range_1.openRemoteZip)(record.url);
+            if (remote.kind === 'full') {
+                skip('server ignores Range');
+                return fromFullResponse(remote.response);
+            }
+            const bundle = await (0, zip_range_1.readRemoteZipEntry)(remote.zipFile, matches, remote.reader);
+            return {
+                ...verified(bundle),
+                transport: 'range-zip',
+                fetchedBytes: remote.reader.fetchedBytes,
+                totalBytes: remote.reader.totalSize,
+            };
+        }
+        catch (error) {
+            if (error instanceof zip_range_1.RangeUnsupportedError) {
+                skip('server ignores Range');
+                return fromFullResponse(error.response);
+            }
+            // the real entry was read and is not the recorded one: final
+            if (error instanceof PermanentBaseError)
+                throw error;
+            skip(`zip range: ${error?.message ?? error}`);
+        }
+    }
+    await downloadToFile(record.url, archive);
+    return {
+        ...verified(await extractBundleFromArchive(archive)),
+        transport: 'full',
+    };
+}
+/**
+ * Pick and materialize the base bundle for this compile. Returns null (with
+ * the reason logged) whenever a base cannot be used; callers then compile
+ * without one.
+ */
+async function resolveHermesBase(params) {
+    const log = params.log ?? (() => { });
+    const { option, bytecodeVersion } = params;
+    if (option === 'none') {
+        log((0, i18n_1.t)('hermesBaseNone', { reason: 'disabled by option' }));
+        return null;
+    }
+    if (option !== 'auto') {
+        // explicit local artifact
+        try {
+            const bundle = await extractBundleFromArchive(option);
+            if (!bundle)
+                throw new Error('bundle entry not found');
+            const version = (0, hbcTransform_1.getHbcVersion)(bundle);
+            if (version !== bytecodeVersion) {
+                throw new Error(`HBC version ${version ?? 'n/a'} != ${bytecodeVersion}`);
+            }
+            const cached = await cachePut(bundle, params.cacheMaxMb);
+            log((0, i18n_1.t)('hermesBaseUsing', { source: option, version: bytecodeVersion }));
+            return {
+                path: cached.path,
+                bytecodeVersion,
+                bundleHash: cached.bundleHash,
+                source: 'local',
+            };
+        }
+        catch (error) {
+            log((0, i18n_1.t)('hermesBaseNone', {
+                reason: `${option}: ${error?.message ?? error}`,
+            }));
+            return null;
+        }
+    }
+    if (!params.appId) {
+        log((0, i18n_1.t)('hermesBaseNone', { reason: 'app not selected' }));
+        return null;
+    }
+    let record = null;
+    try {
+        record = await retryOnce(() => params.fetchBase(params.appId, bytecodeVersion));
+    }
+    catch (error) {
+        log((0, i18n_1.t)('hermesBaseNone', {
+            reason: `server lookup failed: ${error?.message ?? error}`,
+        }));
+        return null;
+    }
+    const source = record?.artifactType && record.artifactType !== 'ppk'
+        ? 'native-package'
+        : record?.bytecodeVersion == null
+            ? 'latest-version'
+            : 'download';
+    if (!record) {
+        log((0, i18n_1.t)('hermesBaseNone', { reason: 'no published version yet' }));
+        return null;
+    }
+    if (record.bytecodeVersion != null &&
+        record.bytecodeVersion !== bytecodeVersion) {
+        log((0, i18n_1.t)('hermesBaseNone', {
+            reason: `server base is HBC ${record.bytecodeVersion}, need ${bytecodeVersion}`,
+        }));
+        return null;
+    }
+    // 1. cache by bundleHash
+    if (record.bundleHash) {
+        const hit = await cacheLookup(record.bundleHash);
+        if (hit && record.bytecodeVersion == null) {
+            // the server does not know the HBC version (legacy version, native
+            // package): the download path checks it, the cache path must too
+            const version = await readFileHbcVersion(hit);
+            if (version !== bytecodeVersion) {
+                log((0, i18n_1.t)('hermesBaseNone', {
+                    reason: `cached base is HBC ${version ?? 'n/a'}, need ${bytecodeVersion}`,
+                }));
+                return null;
+            }
+        }
+        if (hit) {
+            log((0, i18n_1.t)('hermesBaseUsing', {
+                source: `cache ${record.bundleHash.slice(0, 12)}${record.versionId == null ? '' : ` (version ${record.versionId})`}`,
+                version: bytecodeVersion,
+            }));
+            return {
+                path: hit,
+                bytecodeVersion,
+                bundleHash: record.bundleHash,
+                versionId: record.versionId ?? undefined,
+                hash: record.hash,
+                source: 'cache',
+            };
+        }
+    }
+    // 2. download, extract, verify, cache — transport errors get a second try
+    for (let attempt = 1; attempt <= 2; attempt++) {
+        const dir = tmpDir();
+        await fs_extra_1.default.ensureDir(dir);
+        const artifactType = [
+            'ppk',
+            'apk',
+            'ipa',
+            'app',
+        ].includes(record.artifactType ?? '')
+            ? record.artifactType
+            : 'ppk';
+        const archive = path_1.default.join(dir, `base-${process.pid}-${Date.now()}-${attempt}.${artifactType}`);
+        try {
+            log((0, i18n_1.t)('hermesBaseDownloading', { url: record.url }));
+            const fetched = await fetchBaseBundle(record, artifactType, archive, log);
+            const { bundle, bundleHash: actualHash } = fetched;
+            if (fetched.transport !== 'full') {
+                log((0, i18n_1.t)('hermesBaseRangeFetched', {
+                    fetchedKb: Math.ceil((fetched.fetchedBytes ?? 0) / 1024),
+                    totalKb: Math.ceil((fetched.totalBytes ?? 0) / 1024),
+                }));
+            }
+            const version = (0, hbcTransform_1.getHbcVersion)(bundle);
+            if (version !== bytecodeVersion) {
+                log((0, i18n_1.t)('hermesBaseNone', {
+                    reason: `downloaded base is HBC ${version ?? 'n/a'}, need ${bytecodeVersion}`,
+                }));
+                return null;
+            }
+            const cached = await cachePut(bundle, params.cacheMaxMb, actualHash);
+            log((0, i18n_1.t)('hermesBaseUsing', {
+                source: record.versionId == null
+                    ? `native package ${record.hash.slice(0, 8)}`
+                    : `version ${record.versionId} ${record.hash.slice(0, 8)}`,
+                version: bytecodeVersion,
+            }));
+            return {
+                path: cached.path,
+                bytecodeVersion,
+                bundleHash: cached.bundleHash,
+                versionId: record.versionId ?? undefined,
+                hash: record.hash,
+                source,
+            };
+        }
+        catch (error) {
+            if (attempt === 2 || error instanceof PermanentBaseError) {
+                log((0, i18n_1.t)('hermesBaseNone', {
+                    reason: `download/verify failed: ${error?.message ?? error}`,
+                }));
+                return null;
+            }
+        }
+        finally {
+            await fs_extra_1.default.remove(archive).catch(() => { });
+        }
+    }
+    return null;
+}
+/** one retry after a short pause, for transient network failures */
+async function retryOnce(action) {
+    try {
+        return await action();
+    }
+    catch {
+        await new Promise((resolve) => setTimeout(resolve, 500));
+        return action();
+    }
+}
+function hermescArgsWithBase(baseArgs, basePath) {
+    return basePath ? [...baseArgs, `-base-bytecode=${basePath}`] : baseArgs;
+}
+function hermesBaseMeta(selection, bytecodeVersion, check) {
+    const meta = {
+        bytecodeVersion,
+        baseVersionId: selection?.versionId ?? null,
+        baseHash: selection?.hash ?? null,
+    };
+    if (check) {
+        meta.hermesBaseOutcome = check.outcome;
+        const detail = truncateHermesBaseDetail(check.detail);
+        if (detail)
+            meta.hermesBaseDetail = detail;
+    }
+    return meta;
+}
+/** one line, at most HERMES_BASE_DETAIL_MAX_CHARS code points; '' when empty */
+function truncateHermesBaseDetail(detail) {
+    const compact = (detail ?? '').replace(/\s+/g, ' ').trim();
+    const chars = Array.from(compact);
+    return chars.length <= exports.HERMES_BASE_DETAIL_MAX_CHARS
+        ? compact
+        : chars.slice(0, exports.HERMES_BASE_DETAIL_MAX_CHARS).join('');
+}
+// ---------------------------------------------------------------------------
+// equivalence check (streams two `-dump-bytecode` outputs, never writes them)
+// ---------------------------------------------------------------------------
+const STRING_TABLE_LINE = /^\s*[is](\d+)\[[^\]]*\](?: #[0-9A-F]+)?: (.*)$/;
+/**
+ * Normalize one disassembly line so that a delta-mode compile and a plain
+ * compile of the same source compare equal: string IDs are renumbered, literal
+ * buffers are laid out differently (offsets, short/long variants), and jump
+ * distances follow instruction widths. Everything else must match exactly.
+ */
+/** separates rendered literal entries inside one normalized line */
+exports.LITERAL_SEPARATOR = '\u001f';
+/**
+ * `NewArrayWithBuffer rX, sizeHint, count, offset` and
+ * `NewObjectWithBuffer rX, sizeHint, count, keyOffset, valueOffset` (HBC
+ * v87–96) or `NewObjectWithBuffer[AndParent] rX, [rP,] shapeIndex,
+ * valueOffset` (v98) with the literals decoded from the binary buffers at
+ * those offsets, so two builds that lay their buffers out differently still
+ * compare by what each instruction builds. The shape index is dropped like an
+ * offset: it only locates the keys. Null when the operands do not fit the
+ * layout; an offset that cannot be decoded is spelled out (and so never
+ * equals a decoded one).
+ */
+function renderBufferInstruction(opcode, operands, literals) {
+    const [sizeHint, count] = operands;
+    if (opcode.startsWith('NewArray')) {
+        if (operands.length !== 3)
+            return null;
+        const entries = literals.array(operands[2], count);
+        return `size=${sizeHint} n=${count} [${entries ? entries.join(exports.LITERAL_SEPARATOR) : `<undecodable@${operands[2]}>`}]`;
+    }
+    if (literals.layout === 'shaped') {
+        if (operands.length !== 2)
+            return null;
+        const [shapeIndex, valueOffset] = operands;
+        const shape = literals.shape(shapeIndex);
+        const keys = shape && literals.objectKeys(shape.keyOffset, shape.count);
+        const values = shape && literals.objectValues(valueOffset, shape.count);
+        if (!shape || !keys || !values) {
+            return `n=${shape?.count ?? '?'} {<undecodable@shape${shapeIndex}/${valueOffset}>}`;
+        }
+        const pairs = keys.map((k, i) => `${k}: ${values[i]}`);
+        return `n=${shape.count} {${pairs.join(exports.LITERAL_SEPARATOR)}}`;
+    }
+    if (operands.length !== 4)
+        return null;
+    const keys = literals.objectKeys(operands[2], count);
+    const values = literals.objectValues(operands[3], count);
+    if (!keys || !values) {
+        return `size=${sizeHint} n=${count} {<undecodable@${operands[2]}/${operands[3]}>}`;
+    }
+    const pairs = keys.map((k, i) => `${k}: ${values[i]}`);
+    return `size=${sizeHint} n=${count} {${pairs.join(exports.LITERAL_SEPARATOR)}}`;
+}
+function normalizeDisassemblyLine(line, strings, literals) {
+    // Cheap dispatch on the opcode before touching any regex: dumps run to
+    // millions of lines and only a handful of instructions need rewriting.
+    let indent = 0;
+    while (indent < line.length && isSpace(line.charCodeAt(indent)))
+        indent++;
+    let opEnd = indent;
+    while (opEnd < line.length && isLetter(line.charCodeAt(opEnd)))
+        opEnd++;
+    const opcode = line.slice(indent, opEnd);
+    if (opcode === 'Offset' && line.startsWith('Offset in debug table', indent)) {
+        return null;
+    }
+    let m;
+    if (opcode.startsWith('New') && opcode.includes('WithBuffer')) {
+        // v98's AndParent form takes the parent object in a second register,
+        // which is compared as is (it is not a buffer operand)
+        m =
+            /^(\s*New(?:Array|Object)WithBuffer)(?:Long)?(AndParent)?\s+(r\d+)(?:, (r\d+))?(.*)$/.exec(line);
+        if (m) {
+            const op = `${m[1]}${m[2] ?? ''}`;
+            const regs = m[4] ? `${m[3]} ${m[4]}` : m[3];
+            const nums = m[5].match(/\d+/g) ?? [];
+            if (literals) {
+                const rendered = renderBufferInstruction(m[1].trim(), nums.map(Number), literals);
+                if (rendered)
+                    return `${op} ${regs} ${rendered}`;
+            }
+            // no binary buffers: only the size hint survives; the buffer content
+            // is compared as a whole instead (compareBuffers)
+            return `${op} ${regs} sizes=${nums.slice(0, 1).join(',')}`;
+        }
+    }
+    if (opcode.charCodeAt(0) === 0x4a /* J */) {
+        m = /^(\s*J[A-Za-z]+?)(Long)?\s+(L\d+|\d+)(.*)$/.exec(line);
+        if (m)
+            return `${m[1]} <tgt>${m[4]}`;
+    }
+    if (opcode.startsWith('DefineOwnById')) {
+        m = /^(\s*DefineOwnById\w*\s+r\d+, r\d+, \d+, )(\d+)$/.exec(line);
+        if (m)
+            line = `${m[1]}"${strings.get(Number(m[2])) ?? `?${m[2]}`}"`;
+    }
+    // Operand-width variants of one instruction (GetByIdShort/GetById/GetByIdLong,
+    // LoadConstString/LoadConstStringLongIndex, ...) only differ by how wide a
+    // string/function id or offset is encoded — a foreign base hands the new
+    // code's hot strings large ids, so the delta build legitimately picks the
+    // wider form. Fold the suffix and the column padding that follows it.
+    if (opEnd > indent &&
+        (opEnd === line.length || isSpace(line.charCodeAt(opEnd)))) {
+        const folded = foldWidthSuffix(opcode);
+        line = `${line.slice(0, indent)}${folded}${line.slice(opEnd).replace(/\s+/g, ' ')}`;
+        // Switch jump tables sit after the instructions; their relative offset (and
+        // the table header hermesc prints for them) moves with instruction widths.
+        // The two switch instructions carry that offset in different operands:
+        //   StringSwitchImm rX, <id>, <jtOffset>, <defaultLabel>, <count>
+        //   UIntSwitchImm   rX, <jtOffset>, <defaultLabel>, <min>, <max>
+        // Folding only the first shape let a shifted UIntSwitchImm offset read as a
+        // real difference and drop an otherwise good delta build.
+        if (folded === 'StringSwitchImm') {
+            m = /^(\s*StringSwitchImm r\d+, \d+, )\d+(, L\d+, \d+)$/.exec(line);
+            if (m)
+                line = `${m[1]}<jt>${m[2]}`;
+        }
+        else if (folded === 'UIntSwitchImm') {
+            m = /^(\s*UIntSwitchImm r\d+, )\d+(, L\d+, \d+, \d+)$/.exec(line);
+            if (m)
+                line = `${m[1]}<jt>${m[2]}`;
+        }
+        else if (folded === 'offset' && /^\s*offset \d+$/.test(line)) {
+            line = line.replace(/\d+$/, '<jt>');
+        }
+    }
+    return line;
+}
+function isSpace(code) {
+    return code === 0x20 || code === 0x09 || code === 0x0d;
+}
+function isLetter(code) {
+    return (code >= 0x41 && code <= 0x5a) || (code >= 0x61 && code <= 0x7a);
+}
+/** strip one operand-width suffix (LongIndex, Long, Short) off an opcode */
+function foldWidthSuffix(opcode) {
+    for (const suffix of ['LongIndex', 'Long', 'Short']) {
+        if (opcode.length > suffix.length && opcode.endsWith(suffix)) {
+            return opcode.slice(0, -suffix.length);
+        }
+    }
+    return opcode;
+}
+/** Split a readable stream into lines without readline (Bun's readline async iterator misbehaves when pulled manually). */
+async function* streamLines(stream) {
+    let rest = '';
+    for await (const chunk of stream) {
+        rest += typeof chunk === 'string' ? chunk : chunk.toString('utf8');
+        let index = rest.indexOf('\n');
+        while (index >= 0) {
+            yield rest.slice(0, index);
+            rest = rest.slice(index + 1);
+            index = rest.indexOf('\n');
+        }
+    }
+    if (rest)
+        yield rest;
+}
+/** `Array Buffer:`, `Object Key Buffer:`, `Debug filename table:`, ... */
+const SECTION_HEADER = /^([A-Z][A-Za-z ]*):$/;
+/** literal buffer entry that refers to the string table by id */
+const BUFFER_STRING_ENTRY = /^\[String (\d+)\]$/;
+/** sections after the functions that only serve debuggers and profilers */
+const TRAILER_SECTION = /^(?:Debug |Textified callees table)/;
+/** stderr kept from a dump process */
+const DUMP_STDERR_KEEP = 4 * 1024;
+/** a diagnostic line is cut to this many characters */
+const DETAIL_LINE_MAX = 120;
+function isFunctionHeader(line) {
+    return line.startsWith('Function<') || line.startsWith('NCFunction<');
+}
+/**
+ * Structured reader over one `hermesc -dump-bytecode -pretty-disassemble`
+ * stream. Everything before the functions is either the string table (kept
+ * to resolve ids), a literal buffer (kept, with string ids resolved to text,
+ * so buffer *content* is compared) or ignored; the functions come out one at
+ * a time, normalized; the debug tables after them are drained and ignored.
+ */
+class DumpReader {
+    proc;
+    iterator;
+    strings = new Map();
+    /** literal buffers by section name, entries with string ids resolved */
+    buffers = new Map();
+    exit;
+    section = null;
+    pending = null;
+    inFunctions = false;
+    finished = false;
+    /** set when the binary literal buffers of this side could be read */
+    literals;
+    constructor(proc, dumpTo, buffers) {
+        this.proc = proc;
+        // the string table is filled while the preamble streams by, before the
+        // first instruction needs it
+        if (buffers)
+            this.literals = new hermes_literals_1.LiteralResolver(buffers, this.strings);
+        const pass = new stream_1.PassThrough();
+        proc.stdout.pipe(pass);
+        if (dumpTo)
+            proc.stdout.pipe(fs_extra_1.default.createWriteStream(dumpTo));
+        this.iterator = streamLines(pass);
+        let stderr = '';
+        proc.stderr?.on('data', (chunk) => {
+            stderr = (stderr + chunk.toString()).slice(-DUMP_STDERR_KEEP);
+        });
+        this.exit = new Promise((resolve) => {
+            // a spawn failure (ENOENT) may leave stdout open and never 'close'
+            proc.on('error', (error) => {
+                pass.end();
+                resolve({ code: null, signal: null, error, stderr });
+            });
+            proc.on('close', (code, signal) => resolve({ code, signal, stderr }));
+        });
+    }
+    async nextLine() {
+        if (this.pending !== null) {
+            const line = this.pending;
+            this.pending = null;
+            return line;
+        }
+        if (this.finished)
+            return null;
+        const { value, done } = await this.iterator.next();
+        if (done) {
+            this.finished = true;
+            return null;
+        }
+        return value;
+    }
+    /** consume the preamble up to (and returning) the first function header */
+    async skipPreamble() {
+        for (;;) {
+            const line = await this.nextLine();
+            if (line === null)
+                return null;
+            if (isFunctionHeader(line)) {
+                this.inFunctions = true;
+                return line;
+            }
+            const header = SECTION_HEADER.exec(line);
+            if (header) {
+                this.section = header[1];
+                if (this.section.endsWith('Buffer'))
+                    this.buffers.set(this.section, []);
+                continue;
+            }
+            if (this.section === 'Global String Table') {
+                const m = STRING_TABLE_LINE.exec(line);
+                if (m)
+                    this.strings.set(Number(m[1]), m[2]);
+            }
+            else if (this.section?.endsWith('Buffer') && line.trim() !== '') {
+                const entry = line.trim();
+                const ref = BUFFER_STRING_ENTRY.exec(entry);
+                const text = ref ? this.strings.get(Number(ref[1])) : undefined;
+                this.buffers
+                    .get(this.section)
+                    .push(ref
+                    ? `[String ${text === undefined ? `?${ref[1]}` : JSON.stringify(text)}]`
+                    : entry);
+            }
+        }
+    }
+    /** next function (header + normalized body), or null after the last one */
+    async nextFunction() {
+        const header = this.inFunctions
+            ? await this.nextLine()
+            : await this.skipPreamble();
+        if (header === null)
+            return null;
+        // a non-function header here is a trailer section: no more functions
+        if (!isFunctionHeader(header))
+            return null;
+        const lines = [];
+        for (;;) {
+            const line = await this.nextLine();
+            if (line === null)
+                break;
+            if (isFunctionHeader(line) || TRAILER_SECTION.test(line)) {
+                this.pending = line;
+                break;
+            }
+            if (line.trim() === '')
+                continue;
+            const normalized = normalizeDisassemblyLine(line, this.strings, this.literals);
+            if (normalized !== null)
+                lines.push(normalized);
+        }
+        return { header, lines };
+    }
+    /** drain whatever is left and report how the process ended */
+    async finish() {
+        while ((await this.nextLine()) !== null) { }
+        return this.exit;
+    }
+    kill() {
+        this.proc.kill();
+    }
+}
+function describeExit(exit) {
+    if (exit.error)
+        return exit.error.message;
+    const how = exit.signal !== null ? `signal ${exit.signal}` : `exit ${exit.code}`;
+    const stderr = exit.stderr.trim().split('\n').pop()?.trim();
+    return stderr ? `${how}: ${stderr}` : how;
+}
+function clip(line) {
+    const s = line.trim().split(exports.LITERAL_SEPARATOR).join(', ');
+    return s.length > DETAIL_LINE_MAX ? `${s.slice(0, DETAIL_LINE_MAX - 1)}…` : s;
+}
+/**
+ * For two New*WithBuffer lines that differ, the first literal that differs
+ * (the whole line would be clipped before the difference for long literals).
+ */
+function literalDifference(a, b) {
+    const open = /^(\s*New\w+WithBuffer(?:AndParent)? r\d+(?: r\d+)?(?: size=\d+)? n=\d+ [[{])/;
+    const ma = open.exec(a);
+    const mb = open.exec(b);
+    if (!ma || !mb)
+        return null;
+    const ea = a.slice(ma[1].length, -1).split(exports.LITERAL_SEPARATOR);
+    const eb = b.slice(mb[1].length, -1).split(exports.LITERAL_SEPARATOR);
+    const n = Math.min(ea.length, eb.length);
+    for (let i = 0; i < n; i++) {
+        if (ea[i] !== eb[i]) {
+            return `${clip(ma[1].slice(0, -1))} entry ${i}: ${clip(ea[i])} vs ${clip(eb[i])}`;
+        }
+    }
+    return null;
+}
+function compareBuffers(a, b) {
+    for (const name of new Set([...a.keys(), ...b.keys()])) {
+        const ea = a.get(name) ?? [];
+        const eb = b.get(name) ?? [];
+        const n = Math.min(ea.length, eb.length);
+        for (let i = 0; i < n; i++) {
+            if (ea[i] !== eb[i]) {
+                return `${name} entry ${i}: ${clip(ea[i])} vs ${clip(eb[i])}`;
+            }
+        }
+        if (ea.length !== eb.length) {
+            return `${name}: ${ea.length} vs ${eb.length} entries`;
+        }
+    }
+    return null;
+}
+function compareFunctions(a, b) {
+    if (a.header !== b.header) {
+        return `${clip(a.header)} vs ${clip(b.header)}`;
+    }
+    const n = Math.min(a.lines.length, b.lines.length);
+    for (let i = 0; i < n; i++) {
+        if (a.lines[i] !== b.lines[i]) {
+            const literal = literalDifference(a.lines[i], b.lines[i]);
+            return literal
+                ? `${clip(a.header)} +${i + 1}: ${literal}`
+                : `${clip(a.header)} +${i + 1}: ${clip(a.lines[i])} vs ${clip(b.lines[i])}`;
+        }
+    }
+    if (a.lines.length !== b.lines.length) {
+        return `${clip(a.header)}: ${a.lines.length} vs ${b.lines.length} lines`;
+    }
+    return null;
+}
+/**
+ * Compare two HBC files by disassembly (see normalizeDisassemblyLine): the
+ * literal buffers by content, then function by function. `-b` forces hermesc
+ * to treat inputs as bytecode whatever their extension. Both dumps are
+ * consumed as streams so the ~100 MB of text never touches the disk (unless
+ * `dumpTo` asks for it). A dump process that fails or ends early is reported
+ * as `dump-failed`, never as a difference: the two cases need different
+ * follow-ups. The detail names the first difference so a rejected base can be
+ * turned into a normalization rule or a bug report.
+ */
+async function compareHermesBytecode(hermesCommand, withBase, plain, options = {}) {
+    const spawnDump = (file) => (0, child_process_1.spawn)(hermesCommand, ['-b', '-dump-bytecode', '-pretty-disassemble', file], { stdio: ['ignore', 'pipe', 'pipe'] });
+    // The literal buffers are read from both files up front (header + three
+    // byte ranges). Only when both sides can be read do the instructions
+    // compare decoded literals; otherwise both fall back to the dumped buffers
+    // as a whole, so the two sides always normalize the same way.
+    const [buffersA, buffersB] = await Promise.all([
+        (0, hermes_literals_1.readLiteralBuffers)(withBase).catch(() => null),
+        (0, hermes_literals_1.readLiteralBuffers)(plain).catch(() => null),
+    ]);
+    const binary = buffersA && buffersB && buffersA.version === buffersB.version;
+    const literals = binary ? 'instruction' : 'buffer';
+    const a = new DumpReader(spawnDump(withBase), options.dumpTo?.withBase, binary ? buffersA : null);
+    const b = new DumpReader(spawnDump(plain), options.dumpTo?.plain, binary ? buffersB : null);
+    let functions = 0;
+    const different = (detail) => ({
+        status: 'different',
+        detail,
+        functions,
+        literals,
+    });
+    const dumpFailed = (side, exit) => ({
+        status: 'dump-failed',
+        detail: `${side} dump: ${describeExit(exit)}`,
+        functions,
+        literals,
+    });
+    try {
+        for (;;) {
+            const [fa, fb] = await Promise.all([a.nextFunction(), b.nextFunction()]);
+            if (fa === null || fb === null) {
+                // whoever ended: was that the end of a good dump or a failure?
+                if (fa === null) {
+                    const exit = await a.finish();
+                    if (exit.error || exit.code !== 0)
+                        return dumpFailed('base', exit);
+                }
+                if (fb === null) {
+                    const exit = await b.finish();
+                    if (exit.error || exit.code !== 0)
+                        return dumpFailed('plain', exit);
+                }
+                if (fa !== null || fb !== null) {
+                    const extra = fa ?? fb;
+                    return different(`function count: ${clip(extra.header)} only in the ${fa ? 'base' : 'plain'} compile`);
+                }
+                if (functions === 0) {
+                    return {
+                        status: 'dump-failed',
+                        detail: 'no functions in the disassembly',
+                        functions,
+                        literals,
+                    };
+                }
+                return { status: 'equivalent', functions, literals };
+            }
+            if (functions === 0 && !binary) {
+                // buffers precede the functions, so both are complete by now. This
+                // whole-buffer comparison is the fallback: the builder overlaps and
+                // deduplicates serialized literals, so a delta build may lay the same
+                // literals out differently and this can reject a good build.
+                const detail = compareBuffers(a.buffers, b.buffers);
+                if (detail)
+                    return different(detail);
+            }
+            const detail = compareFunctions(fa, fb);
+            if (detail)
+                return different(detail);
+            functions++;
+        }
+    }
+    finally {
+        a.kill();
+        b.kill();
+    }
+}
+/** Resolves true when equivalent; see compareHermesBytecode for the details. */
+async function verifyHermesBaseEquivalence(hermesCommand, withBase, plain) {
+    const result = await compareHermesBytecode(hermesCommand, withBase, plain);
+    return result.status === 'equivalent';
+}