crossbind 2.0.0-beta.60 → 2.0.0-beta.63

package/src/utils/dirLock.js

@@ -1,24 +1,35 @@
 import fs from 'node:fs';
 import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { Worker } from 'node:worker_threads';
 import logger from './logger.js';
 
-// A dependency source build can legitimately run for a long time; anything older
-// is assumed to be a crashed process whose lock must be broken.
-const DEFAULT_STALE_MS = 60 * 60 * 1000;
+// A holder refreshes its lock while it works, so a lock nobody refreshed for this long was left by a crash, even when
+// another process has taken over its PID since.
+const DEFAULT_STALE_MS = 30 * 1000;
+// A crossbind from before the refreshing kept its lock as long as its PID ran, and one whose PID cannot be read this long.
+const LEGACY_STALE_MS = 60 * 60 * 1000;
 const DEFAULT_POLL_MS = 2000;
+const DEFAULT_HELD_BY = 'another build is working on this dependency';
+// Breaking a lock takes no time, so a break file this old was left by a waiter that died breaking one.
+const BREAK_STALE_MS = 10 * 1000;
+// Windows keeps the name of a deleted file while another handle has it open.
+const DELETE_PENDING_MS = 2 * 1000;
 
 const sleep = (ms) => new Promise((resolve) => { setTimeout(resolve, ms); });
+const sleepSync = (ms) => Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
 
-// Reads the PID recorded in the lock file and reports whether that process is
-// still running: 'alive' (signal delivered, or owned by another user), 'dead'
-// (no such process), or 'unknown' (missing/unparseable PID).
-export function lockHolderStatus(lockPath) {
-    let pid;
+// The holder's PID, and from this crossbind on the token of its acquisition on the next line.
+function readLock(lockPath) {
     try {
-        pid = Number.parseInt(fs.readFileSync(lockPath, 'utf8').trim(), 10);
+        const [pid, token] = fs.readFileSync(lockPath, 'utf8').split('\n').map((line) => line.trim());
+        return { pid: Number.parseInt(pid, 10), token: token || undefined, isLegacy: Boolean(pid) && !token };
     } catch {
-        return 'unknown';
+        return {};
     }
+}
+
+function statusOf(pid) {
     if (!Number.isInteger(pid) || pid <= 0) return 'unknown';
     try {
         process.kill(pid, 0);
@@ -30,42 +41,140 @@ export function lockHolderStatus(lockPath) {
     }
 }
 
-export default async function withDirLock(lockPath, fn, options = {}) {
+// Reads the PID recorded in the lock file and reports whether that process is
+// still running: 'alive' (signal delivered, or owned by another user), 'dead'
+// (no such process), or 'unknown' (missing/unparseable PID).
+export function lockHolderStatus(lockPath) {
+    return statusOf(readLock(lockPath).pid);
+}
+
+let refresher;
+
+// Refreshes the held locks from a thread of its own, so a holder blocked in execFileSync still shows it is working.
+function lockRefresher() {
+    if (!refresher) {
+        refresher = new Worker(`
+            const fs = require('node:fs');
+            const { parentPort } = require('node:worker_threads');
+            const timers = new Map();
+            parentPort.on('message', ({ hold, release, everyMs }) => {
+                clearInterval(timers.get(hold ?? release));
+                timers.delete(hold ?? release);
+                if (!hold) return;
+                timers.set(hold, setInterval(() => {
+                    const now = new Date();
+                    try {
+                        fs.utimesSync(hold, now, now);
+                    } catch {
+                        // released since the last refresh
+                    }
+                }, everyMs));
+            });
+        `, { eval: true, execArgv: [] });
+        refresher.on('error', (error) => logger.info(`crossbind: cannot refresh held locks (${error.message}); a waiting process may take one over.`));
+        refresher.unref();
+    }
+    return refresher;
+}
+
+// Takes the lock, yielding each wait so the async and the sync lock share one procedure.
+function* acquire(lockPath, token, options) {
     const staleMs = options.staleMs ?? DEFAULT_STALE_MS;
     const pollMs = options.pollMs ?? DEFAULT_POLL_MS;
     fs.mkdirSync(path.dirname(lockPath), { recursive: true });
 
     let hasWarned = false;
+    let deniedSince;
+    let suspect;
     for (;;) {
         try {
             const fd = fs.openSync(lockPath, 'wx');
-            fs.writeSync(fd, String(process.pid));
+            fs.writeSync(fd, `${process.pid}\n${token}\n`);
             fs.closeSync(fd);
-            break;
+            lockRefresher().postMessage({ hold: lockPath, everyMs: staleMs / 6 });
+            return;
         } catch (e) {
+            if (e.code === 'EPERM' && process.platform === 'win32') {
+                deniedSince ??= performance.now();
+                if (performance.now() - deniedSince < DELETE_PENDING_MS) {
+                    yield pollMs;
+                    continue;
+                }
+            }
             if (e.code !== 'EEXIST') throw e;
-            const status = lockHolderStatus(lockPath);
-            const mtimeMs = fs.statSync(lockPath, { throwIfNoEntry: false })?.mtimeMs;
-            const mtimeStale = mtimeMs !== undefined && Date.now() - mtimeMs > staleMs;
-            // A provably-dead holder (e.g. a Ctrl-C that skipped the finally cleanup) is broken
-            // at once; a live holder is never stolen, even past the stale window; when the holder
-            // can't be determined we fall back to the mtime age.
-            if (status === 'dead' || (status !== 'alive' && mtimeStale)) {
-                logger.info(`crossbind: breaking stale lock ${lockPath} (holder ${status}).`);
-                fs.rmSync(lockPath, { force: true });
+        }
+        // The file is read before its holder, so a lock another waiter took meanwhile never passes for the stale one.
+        const lock = fs.statSync(lockPath, { throwIfNoEntry: false });
+        const holder = readLock(lockPath);
+        const status = statusOf(holder.pid);
+        // A provably-dead holder (e.g. a Ctrl-C that skipped the finally cleanup) is broken at once. Any other goes once
+        // nobody refreshed it within the stale window for two refreshes in a row, so a holder waking from sleep refreshes
+        // it first; an older crossbind's lock only once its holder is gone.
+        if (lock && status === 'dead' && breakStaleLock(lockPath, lock, 'its holder is gone')) continue;
+        const age = lock ? Date.now() - lock.mtimeMs : 0;
+        const isUnrefreshed = holder.isLegacy ? status !== 'alive' && age > LEGACY_STALE_MS : age > staleMs;
+        if (lock && isUnrefreshed) {
+            if (suspect?.ino !== lock.ino || suspect.mtimeMs !== lock.mtimeMs) {
+                suspect = { ino: lock.ino, mtimeMs: lock.mtimeMs, since: performance.now() };
+            } else if (performance.now() - suspect.since >= staleMs / 3 && breakStaleLock(lockPath, lock, 'nobody refreshes it')) {
                 continue;
             }
-            if (!hasWarned) {
-                logger.info(`crossbind: waiting for ${lockPath} (another build is working on this dependency)…`);
-                hasWarned = true;
-            }
-            await sleep(pollMs);
         }
+        if (!hasWarned) {
+            logger.info(`crossbind: waiting for ${lockPath} (${options.heldBy ?? DEFAULT_HELD_BY})…`);
+            hasWarned = true;
+        }
+        yield pollMs;
     }
+}
 
+// Waiters that all saw the stale holder break the lock one at a time, and only the file they saw: otherwise one removes
+// the lock another has just taken. False while another waiter is breaking it.
+function breakStaleLock(lockPath, stale, reason) {
+    const breakPath = `${lockPath}.break`;
+    try {
+        fs.closeSync(fs.openSync(breakPath, 'wx'));
+    } catch (e) {
+        if (e.code !== 'EEXIST') throw e;
+        const mtimeMs = fs.statSync(breakPath, { throwIfNoEntry: false })?.mtimeMs;
+        if (mtimeMs !== undefined && Date.now() - mtimeMs > BREAK_STALE_MS) fs.rmSync(breakPath, { force: true });
+        return false;
+    }
+    try {
+        const lock = fs.statSync(lockPath, { throwIfNoEntry: false });
+        if (lock?.ino === stale.ino && lock.mtimeMs === stale.mtimeMs) {
+            logger.info(`crossbind: breaking stale lock ${lockPath} (${reason}).`);
+            fs.rmSync(lockPath, { force: true });
+        }
+    } finally {
+        fs.rmSync(breakPath, { force: true });
+    }
+    return true;
+}
+
+// A holder that stopped refreshing may have lost the lock to another process, whose lock it must leave.
+function release(lockPath, token) {
+    lockRefresher().postMessage({ release: lockPath });
+    if (readLock(lockPath).token === token) fs.rmSync(lockPath, { force: true });
+}
+
+export default async function withDirLock(lockPath, fn, options = {}) {
+    const token = randomUUID();
+    for (const ms of acquire(lockPath, token, options)) await sleep(ms);
     try {
         return await fn();
     } finally {
-        fs.rmSync(lockPath, { force: true });
+        release(lockPath, token);
+    }
+}
+
+// For a caller that holds the lock across execFileSync, where the event loop cannot run anyway.
+export function withDirLockSync(lockPath, fn, options = {}) {
+    const token = randomUUID();
+    for (const ms of acquire(lockPath, token, options)) sleepSync(ms);
+    try {
+        return fn();
+    } finally {
+        release(lockPath, token);
     }
 }

package/src/utils/downloadAndExtractFile.js

@@ -4,14 +4,23 @@ import crypto from 'node:crypto';
 import { spawnSync } from 'node:child_process';
 import { Readable } from 'node:stream';
 import { pipeline } from 'node:stream/promises';
+import logger from './logger.js';
 
-export default async function downloadAndExtractFile(url, output, sha256) {
+// Upstream hosts drop a request now and then (ftp.gnu.org refused eight parallel libiconv fetches at once), so a
+// request that failed for a passing reason is tried again after these pauses. Any other 4xx is the server's answer.
+const RETRY_DELAYS_MS = [1000, 2000, 4000];
+const RETRYABLE_STATUS = new Set([408, 429]);
+
+const sleep = (ms) => new Promise((resolve) => { setTimeout(resolve, ms); });
+const retryable = (error) => Object.assign(error, { retryable: true });
+
+export default async function downloadAndExtractFile(url, output, sha256, options = {}) {
     const archive = path.basename(url);
     if (fs.existsSync(`${output}/source`) && sourceCameFrom(output, archive)) {
         return false;
     }
     fs.rmSync(`${output}/source`, { recursive: true, force: true });
-    const filePath = await downloadFile(url, output);
+    const filePath = await downloadFile(url, output, options);
     verifyIntegrity(filePath, url, sha256);
     extractArchive(filePath, url, output);
     fs.writeFileSync(`${output}/source.archive`, archive);
@@ -86,29 +95,47 @@ export function assertHttps(target, context = target) {
 
 // fetch follows redirects itself, which release downloads rely on (github and the osgeo
 // mirrors both bounce), so the download needs no redirect library of its own.
-export async function downloadFile(url, folder) {
+export async function downloadFile(url, folder, { retryDelaysMs = RETRY_DELAYS_MS } = {}) {
     mkdirSync(folder, { recursive: true });
     const dest = `${folder}/${path.basename(url)}`;
     if (fs.existsSync(dest)) return dest;
 
     assertHttps(url);
+    for (let attempt = 1; ; attempt += 1) {
+        try {
+            await fetchTo(url, dest);
+            return dest;
+        } catch (err) {
+            if (!err.retryable) throw err;
+            if (attempt > retryDelaysMs.length) {
+                throw new Error(`${err.message} (after ${attempt} attempts)`, { cause: err });
+            }
+            const delay = retryDelaysMs[attempt - 1];
+            logger.info(`${err.message} Trying again in ${delay / 1000}s…`);
+            await sleep(delay);
+        }
+    }
+}
+
+async function fetchTo(url, dest) {
     let response;
     try {
         response = await fetch(url, { headers: { 'User-Agent': 'curl/8.7.1' }, redirect: 'follow' });
     } catch (err) {
-        throw new Error(`crossbind: cannot reach ${url}: ${err.message}`, { cause: err });
+        throw retryable(new Error(`crossbind: cannot reach ${url}: ${err.message}`, { cause: err }));
     }
     // A redirect chain must not be able to downgrade the transport on its last hop.
     if (response.url) assertHttps(response.url, `${url} (redirected to ${response.url})`);
     if (!response.ok) {
-        throw new Error(`crossbind: download failed for ${url} — HTTP ${response.status}.`);
+        await response.body?.cancel();
+        const error = new Error(`crossbind: download failed for ${url} — HTTP ${response.status}.`);
+        throw response.status >= 500 || RETRYABLE_STATUS.has(response.status) ? retryable(error) : error;
     }
     try {
         await pipeline(Readable.fromWeb(response.body), fs.createWriteStream(dest));
     } catch (err) {
         // A half-written archive would fail its hash check later with a confusing message.
         fs.rmSync(dest, { force: true });
-        throw new Error(`crossbind: download failed for ${url}: ${err.message}`, { cause: err });
+        throw retryable(new Error(`crossbind: download failed for ${url}: ${err.message}`, { cause: err }));
     }
-    return dest;
 }

package/src/utils/embindArgumentGuards.js

@@ -0,0 +1,84 @@
+// A release build of embind passes whatever JavaScript hands an integer or enum parameter straight to
+// the wire, where anything that is not a number becomes 0: an enum member given to an `int` parameter,
+// a Number given to an enum parameter, a one-letter string given to a `char`. The call then runs with 0
+// and reports no error. These rewrites convert what has one meaning and throw a TypeError for the rest,
+// as embind's assertion builds do.
+
+const GUARDS = [
+    {
+        registration: '_embind_register_integer',
+        from: 'toWireType:(destructors,value)=>value,readValueFromPointer:integerReadValueFromPointer(',
+        to: 'toWireType:(destructors,value)=>{'
+            + 'if(typeof value=="number"||typeof value=="boolean"||typeof value=="bigint")return value;'
+            + 'if(typeof value=="string"&&size==1&&value.length==1)return value.charCodeAt(0);'
+            + 'if(value!==null&&typeof value=="object"&&typeof value.value=="number")return value.value;'
+            + 'throw new TypeError(name+" takes a number, got "+(typeof value=="string"?JSON.stringify(value):value===null?"null":typeof value))'
+            + '},readValueFromPointer:integerReadValueFromPointer(',
+    },
+    {
+        registration: '_embind_register_enum',
+        from: 'toWireType:(destructors,c)=>c.value,',
+        to: 'toWireType:(destructors,c)=>{'
+            + 'if(typeof c=="number")return c;'
+            + 'if(c!==null&&typeof c=="object"&&typeof c.value=="number")return c.value;'
+            + 'throw new TypeError(name+" takes a member of the enum or its number, got "+(typeof c=="string"?JSON.stringify(c):c===null?"null":typeof c))'
+            + '},',
+    },
+];
+
+// The release glue spells the bigint conversion `typeof value=="number"`, the debug glue `typeof value == 'number'`.
+const BIGINT_FROM_NUMBER = /if\s*\(\s*typeof value\s*==\s*["']number["']\s*\)\s*\{\s*value\s*=\s*BigInt\(value\)\s*;?\s*\}/g;
+const SAFE_BIGINT_FROM_NUMBER = 'if(typeof value=="number"){if(!Number.isSafeInteger(value))throw new TypeError("a 64-bit integer parameter takes a BigInt or a safe integer Number, got "+value);value=BigInt(value)}';
+
+// Returns the rewritten glue and whether a bigint registration kept a conversion this rewrite does not recognise.
+export function guardBigIntArguments(glue) {
+    const text = glue.replace(BIGINT_FROM_NUMBER, SAFE_BIGINT_FROM_NUMBER);
+    return { text, missed: text.includes('_embind_register_bigint') && !text.includes('Number.isSafeInteger(value)') };
+}
+
+// The debug glue the dev servers load spells both registrations over lines, and its integer conversion already
+// throws for anything but a number or a boolean, so the member and character conversions go ahead of that check.
+// Each applies inside its own registration only: the debug float conversion reads the same as the integer one.
+const DEBUG_GUARDS = [
+    {
+        registration: '__embind_register_integer',
+        end: 'readValueFromPointer: integerReadValueFromPointer(',
+        from: /toWireType: \(destructors, value\) => \{(\s*)(?=if \(typeof value != ["']number["'])/,
+        to: 'toWireType: (destructors, value) => {$1'
+            + 'if (typeof value == "string" && size == 1 && value.length == 1) value = value.charCodeAt(0);$1'
+            + 'if (value !== null && typeof value == "object" && typeof value.value == "number") value = value.value;$1',
+        applied: 'value = value.charCodeAt(0);',
+    },
+    {
+        registration: '__embind_register_enum',
+        end: 'readValueFromPointer: enumReadValueFromPointer(',
+        from: /toWireType: \(destructors, c\) => c\.value,/,
+        to: 'toWireType: (destructors, c) => {'
+            + 'if (typeof c == "number") return c;'
+            + 'if (c !== null && typeof c == "object" && typeof c.value == "number") return c.value;'
+            + 'throw new TypeError(name + " takes a member of the enum or its number, got " + (typeof c == "string" ? JSON.stringify(c) : c === null ? "null" : typeof c))'
+            + '},',
+        applied: 'takes a member of the enum or its number',
+    },
+];
+
+function guardDebugRegistration(glue, { registration, end, from, to, applied }) {
+    const start = glue.indexOf(`var ${registration} = `);
+    const stop = start < 0 ? -1 : glue.indexOf(end, start);
+    if (stop < 0) return { text: glue, missed: false };
+    const code = glue.slice(start, stop);
+    if (code.includes(applied)) return { text: glue, missed: false };
+    const rewritten = code.replace(from, to);
+    return { text: glue.slice(0, start) + rewritten + glue.slice(stop), missed: rewritten === code };
+}
+
+// Returns the rewritten glue and the registrations whose code no longer looks the way these rewrites expect.
+export function guardEmbindArguments(glue) {
+    const missed = GUARDS.filter(({ registration, from, to }) => glue.includes(`${registration}=`) && !glue.includes(from) && !glue.includes(to))
+        .map(({ registration }) => registration);
+    const released = GUARDS.reduce((current, { from, to }) => current.split(from).join(to), glue);
+    return DEBUG_GUARDS.reduce(({ text, missed: names }, guard) => {
+        const result = guardDebugRegistration(text, guard);
+        return { text: result.text, missed: result.missed ? [...names, guard.registration] : names };
+    }, { text: released, missed });
+}

package/src/utils/embindCallArguments.js

@@ -0,0 +1,19 @@
+// Linked with -sDYNAMIC_EXECUTION=0, embind's craftInvokerFunction keeps argsWired, invokerFuncArgs and
+// destructors once per bound function, shared by all its calls. A call frees its arguments from there
+// once it returns, or once its promise settles for an async (_JSPI) function, so a call started before
+// then overwrites them and the earlier call frees the later call's arguments instead of its own, which
+// leak: two pending calls of one _JSPI method, or a method called again from a JavaScript callback it
+// runs. Emscripten 6.0.9 builds it this way, as did upstream main on 2026-09-30; this rewrite declares
+// the three inside the invoker, so each call gets its own.
+
+// The release glue spells it on one line, the debug glue one statement per line with an argument
+// count check first.
+const SHARED = /var argsWired\s*=\s*new Array\(expectedArgCount\);\s*var invokerFuncArgs\s*=\s*\[\];\s*var destructors\s*=\s*\[\];\s*var invokerFn\s*=\s*function\s*\(\.\.\.args\)\s*\{(\s*(?:checkArgCount\([^;]*\);\s*)?)destructors\.length\s*=\s*0;/g;
+const PER_CALL = 'var invokerFn=function(...args){$1var argsWired=new Array(expectedArgCount);var invokerFuncArgs=[];var destructors=[];';
+const SEPARATED = /var invokerFn\s*=\s*function\s*\(\.\.\.args\)\s*\{\s*(?:checkArgCount\([^;]*\);\s*)?var argsWired\s*=/;
+
+// Returns the rewritten glue and whether it still holds an invoker this rewrite does not recognise.
+export function separateCallArguments(glue) {
+    const text = glue.replace(SHARED, PER_CALL);
+    return { text, missed: text.includes('argsWired') && !SEPARATED.test(text) };
+}

package/src/utils/embindJspiQueue.js

@@ -0,0 +1,25 @@
+// JSPI suspends a call's wasm frames, but its C stack frames stay on the one stack every call of the module shares,
+// and Emscripten 6.0.9 gives a suspended call no stack of its own: a call that resumes after a later one started
+// returns over that one's frames, which the later one still uses. This rewrite runs the module's async (_JSPI)
+// bindings one at a time, as Asyncify runs its async operations: a call made while another is pending enters wasm
+// once that one settles. embind still converts the arguments when the call is made, so a wrong one throws there.
+
+// The release glue spells it on one line, the debug glue across lines.
+const PROMISING = /rtn\s*=\s*WebAssembly\.promising\(rtn\)/g;
+const QUEUED = 'rtn=crossbindJspiQueue(WebAssembly.promising(rtn))';
+const REQUIRE_FUNCTION = /var embind__requireFunction\s*=/;
+// Declared in the module factory, so each instance queues on its own, as each has its own C stack.
+const QUEUE = 'var crossbindJspiQueue=(()=>{var pending=null;return fn=>(...args)=>{'
+    + 'var call=pending?pending.then(()=>fn(...args)):fn(...args);'
+    + 'var settled=pending=call.then(()=>{},()=>{});'
+    + 'settled.then(()=>{if(pending===settled)pending=null});'
+    + 'return call}})();';
+
+// Returns the rewritten glue and whether it holds a promising export this rewrite does not recognise.
+export function queueJspiCalls(glue) {
+    const text = glue.replace(PROMISING, QUEUED);
+    if (text === glue || !REQUIRE_FUNCTION.test(text)) {
+        return { text: glue, missed: glue.includes('WebAssembly.promising(rtn') && !glue.includes(QUEUED) };
+    }
+    return { text: text.replace(REQUIRE_FUNCTION, (declaration) => `${QUEUE}${declaration}`), missed: false };
+}

package/src/utils/embindRsFingerprint.js

@@ -0,0 +1,26 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { getContentHash, getFileHash } from './hash.js';
+import { collectRustSources } from './inputStamp.js';
+import resolveEmbindRustRoot from './resolveEmbindRust.js';
+
+// Every cargo staticlib bundles the embind-rs it was built from. An archive from another one links stale glue, and next
+// to an archive built after it every embind_rs symbol is defined twice, so a prebuilt records the one it came from.
+export const EMBIND_RS_FINGERPRINT_FILE = 'crossbind-embind-rs.fingerprint';
+
+// Paths count relative to the crate, so an archive built from the same embind-rs elsewhere matches.
+export function getEmbindRsFingerprint() {
+    const crate = `${resolveEmbindRustRoot()}/crate`;
+    const files = [...collectRustSources([crate]), `${crate}/Cargo.toml`];
+    return getContentHash(files.map((file) => `${path.relative(crate, file)}:${getFileHash(file)}`).sort().join('\n'));
+}
+
+export function isEmbindRsFingerprintStale(prebuiltDir, fingerprint) {
+    const file = `${prebuiltDir}/${EMBIND_RS_FINGERPRINT_FILE}`;
+    return !fs.existsSync(file) || fs.readFileSync(file, { encoding: 'utf8' }) !== fingerprint;
+}
+
+export function writeEmbindRsFingerprint(prebuiltDir, fingerprint) {
+    fs.mkdirSync(prebuiltDir, { recursive: true });
+    fs.writeFileSync(`${prebuiltDir}/${EMBIND_RS_FINGERPRINT_FILE}`, fingerprint);
+}

package/src/utils/execContainer.js

@@ -0,0 +1,49 @@
+import { execFileSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import getOsUserAndGroupId from './getOsUserAndGroupId.js';
+
+function samePath(a, b) {
+    const real = (p) => {
+        try {
+            return fs.realpathSync(p);
+        } catch {
+            return path.resolve(p);
+        }
+    };
+    return real(a) === real(b);
+}
+
+// docker exec attaches to a container the user created, so nothing else checks what it mounts. A
+// container without a tool's cache mount keeps that cache inside itself, where the host reads paths
+// that were never written: fail first, with the way to fix it.
+export default function assertExecContainer({ name, mounts, workdir, hint, mountNote }) {
+    let info;
+    try {
+        // stderr is dropped: docker's own "No such container" would land before the message below.
+        info = JSON.parse(execFileSync('docker', ['container', 'inspect', name], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }))[0];
+    } catch {
+        throw new Error(`crossbind: RUNNER=DOCKER_EXEC needs a container named '${name}', which does not exist.\n${hint}`);
+    }
+    if (!info?.State?.Running) {
+        throw new Error(
+            `crossbind: the container '${name}' exists but is not running. Start it with \`docker start ${name}\`, or recreate it.\n${hint}`,
+        );
+    }
+    for (const [destination, source] of mounts) {
+        const mount = (info.Mounts ?? []).find((m) => m.Destination === destination);
+        if (!mount || !samePath(mount.Source, source)) {
+            const found = mount ? ` - it mounts ${mount.Source} there` : '';
+            throw new Error(
+                `crossbind: the container '${name}' does not mount ${source} at ${destination}${found}. ${mountNote}\n${hint}`,
+            );
+        }
+    }
+    // `docker run --workdir` creates the directory; `docker exec --workdir` does not, and the tool
+    // dies with an OCI "chdir to cwd" error that names nothing the user can act on.
+    try {
+        execFileSync('docker', ['exec', '--user', getOsUserAndGroupId(), name, 'mkdir', '-p', workdir], { stdio: 'ignore' });
+    } catch (e) {
+        throw new Error(`crossbind: could not create the working directory ${workdir} inside '${name}'.\n${hint}`, { cause: e });
+    }
+}

package/src/utils/headerImports.js

@@ -0,0 +1,56 @@
+import fs from 'node:fs';
+import appSourceFiles from './appSources.js';
+
+// `import * as x` and `export *` take every name the header exports.
+export const ALL_NAMES = '*';
+
+const IDENTIFIER = /^[A-Za-z_$][\w$]*$/;
+// The clause shapes are spelled out, so a match cannot run from one statement into the next.
+const HEADER_IMPORT = /\b(import|export)\s+(type\s+)?((?:[A-Za-z_$][\w$]*\s*,\s*)?(?:\{[^}]*\}|\*(?:\s*as\s+[A-Za-z_$][\w$]*)?)|[A-Za-z_$][\w$]*)\s*from\s*(['"])([^'"\n]+)\4/g;
+// `import('x.h')`, `import 'x.h'` and `require('x.h')` hand the app the whole module. A lazy import may carry a bundler
+// comment (`/* webpackChunkName: "x" */`) or a template literal. A comment ends at its first `*/`, so a run of them
+// matches one way only.
+const WHOLE_MODULE = /\b(?:import\s*\(\s*(?:\/\*(?:[^*]|\*(?!\/))*\*\/\s*)*|import\s+|require\s*\(\s*)(['"`])([^'"`$\n]+)\1/g;
+
+// A comment runs to its first `*/`, or to the end when it never closes, so each is read once.
+function listedNames(list) {
+    return list.replace(/\/\*(?:[^*]|\*(?!\/))*(?:\*\/|$)|\/\/[^\n]*/g, '').split(',')
+        .map((entry) => entry.trim())
+        .filter((entry) => entry && !/^type\s/.test(entry))
+        .map((entry) => entry.split(/\s+as\s+/)[0])
+        .filter((name) => name !== 'default' && IDENTIFIER.test(name));
+}
+
+// A specifier built at run time is not found.
+export function findHeaderImports(text, headerExtensions) {
+    const isHeader = new RegExp(`\\.(${headerExtensions.join('|')})$`);
+    const listed = [...text.matchAll(HEADER_IMPORT)].flatMap(([, , type, clause, , specifier]) => {
+        if (type || !isHeader.test(specifier)) return [];
+        const open = clause.indexOf('{');
+        const close = open === -1 ? -1 : clause.indexOf('}', open);
+        const hasList = close !== -1;
+        if ((hasList ? clause.slice(0, open) + clause.slice(close + 1) : clause).includes('*')) return [{ specifier, names: ALL_NAMES }];
+        const names = listedNames(hasList ? clause.slice(open + 1, close) : '');
+        return names.length ? [{ specifier, names }] : [];
+    });
+    const whole = [...text.matchAll(WHOLE_MODULE)]
+        .filter(([, , specifier]) => isHeader.test(specifier))
+        .map(([, , specifier]) => ({ specifier, names: ALL_NAMES }));
+    return [...listed, ...whole];
+}
+
+const scanned = new Map();
+
+// A source is read again only when its size or modification time changed.
+export function findHeaderImportsIn(projectDir, headerExtensions) {
+    const extensions = headerExtensions.join(',');
+    return appSourceFiles(projectDir).flatMap((importer) => {
+        const { mtimeMs, size } = fs.statSync(importer);
+        const cached = scanned.get(importer);
+        if (cached?.mtimeMs !== mtimeMs || cached.size !== size || cached.extensions !== extensions) {
+            const imports = findHeaderImports(fs.readFileSync(importer, 'utf8'), headerExtensions);
+            scanned.set(importer, { mtimeMs, size, extensions, imports });
+        }
+        return scanned.get(importer).imports.map((found) => ({ importer, ...found }));
+    });
+}

package/src/utils/hostPlatform.js

@@ -0,0 +1,21 @@
+// What `-p host` builds: the platform whose binaries this machine runs. Node reports glibc and musl
+// Linux alike; as the addon loader decides, a glibc process names its glibc in the report header.
+export default function hostPlatform(platform = process.platform, readReport = processReport) {
+    if (platform !== 'linux') return platform;
+    const header = readReport()?.header;
+    return !header || header.glibcVersionRuntime ? 'linux' : 'linuxmusl';
+}
+
+export const resolveHostPlatform = (platforms, host = hostPlatform()) => platforms.map((platform) => (platform === 'host' ? host : platform));
+
+function processReport() {
+    if (!process.report) return undefined;
+    // Only the header is read; the network section can stall on DNS lookups.
+    const { excludeNetwork } = process.report;
+    process.report.excludeNetwork = true;
+    try {
+        return process.report.getReport();
+    } finally {
+        process.report.excludeNetwork = excludeNetwork;
+    }
+}

package/src/utils/inputStamp.js

@@ -21,6 +21,29 @@ export function collectInputFiles(roots, exts, extraFiles = []) {
     return [...files].filter((file) => fs.existsSync(file)).sort();
 }
 
+// A cargo target dir holds build-script output, which changes on every build.
+const RUST_EXCLUDED_DIRS = [...EXCLUDED_DIRS, 'target'];
+
+// An app-local .rs file reaches its generated bridge through #[path], so the bridge text stays
+// the same across a body edit: the sources themselves have to be stamped.
+export function collectRustSources(roots) {
+    const files = new Set();
+    [...new Set(roots)].forEach((root) => {
+        findFiles('**/*.rs', {
+            cwd: root,
+            ignore: RUST_EXCLUDED_DIRS.map((dir) => `**/${dir}/**`),
+        }).forEach((file) => files.add(file));
+    });
+    return [...files].sort();
+}
+
+export function collectRustBridgeFiles(cacheDir) {
+    return [
+        ...findFiles('rust-bridges/*/{Cargo.toml,src/lib.rs}', { cwd: cacheDir }),
+        ...findFiles('rust-crates/*.rs', { cwd: cacheDir }),
+    ].sort();
+}
+
 export function computeInputStamp(roots, exts, extraFiles, salt) {
     const lines = collectInputFiles(roots, exts, extraFiles).map((file) => `${file}:${getFileHash(file)}`);
     lines.push(salt);

package/src/utils/iosToolchain.js

@@ -0,0 +1,6 @@
+// The Xcode every iOS archive is built with, and the deployment target it is built for: port archives
+// and Conan packages link into the same app, so they move together.
+export const IOS_DEVELOPER_DIR = '/Applications/Xcode.app/Contents/Developer';
+export const XCODE_TOOLCHAIN_BIN = `${IOS_DEVELOPER_DIR}/Toolchains/XcodeDefault.xctoolchain/usr/bin`;
+// Xcode 27 refuses deployment targets below 15.0; React Native's own floor is 15.1.
+export const IOS_DEPLOYMENT_TARGET = '15.1';

package/src/utils/isSourceCmakePackage.js

@@ -0,0 +1,10 @@
+import fs from 'node:fs';
+
+// A cmake package that ships its sources rather than a prebuilt: its own CMakeLists (at the package root, not a
+// generated dist/prebuilt one) is compiled into the consuming build via add_subdirectory.
+export default function isSourceCmakePackage(config) {
+    return config.export?.type === 'cmake'
+        && config.paths.cmake !== config.paths.cliCMakeListsTxt
+        && !config.paths.cmakeDir.endsWith('/prebuilt')
+        && fs.existsSync(config.paths.cmake);
+}