@nimbus-sh/core 0.3.0 → 0.4.0

package/dist/runtime/clang-runner.js

@@ -0,0 +1,866 @@
+/**
+ * clang-runner.ts — compile, link, and execute C programs for Nimbus WASI.
+ *
+ * Architecture (compile-link-run, two facet calls):
+ *
+ *   compile  : clang.wasm + sysroot subset for C includes + user .c
+ *              → produces .o bytes (returned to supervisor).
+ *   link     : lld.wasm + sysroot subset for link (crt1.o + libc.a)
+ *              + .o from compile → produces .wasm executable.
+ *   write    : final .wasm flushed to user VFS at the requested path.
+ *
+ * The filesystem both halves see is the one WASI layer every other
+ * non-node runtime uses (wasi-instance.ts), seeded and sealed.
+ *
+ * Splitting compile and link into separate facet calls keeps each
+ * call under the empirical payload ceiling. Each ships:
+ *
+ *   - compile: 31 MiB clang.wasm + ~1.3 MiB sysroot subset (C includes).
+ *   - link   : 19 MiB lld.wasm + ~0.75 MiB libs + tiny .o.
+ *
+ * Sysroot subset extraction happens supervisor-side via a small ustar
+ * parser. The full sysroot.tar is parsed once when the clang runtime
+ * warms for a session; compile/link calls reuse the filtered subsets.
+ *
+ * Dispatch stays direct: no sleeps, no caller-side retries, and no
+ * catch-and-continue around loader failures.
+ */
+import { CRED_KERNEL, requireVfsCred, WASM32_WASI_NIMBUS_ABI } from './os-contracts.js';
+import { resolveVfsPath } from '../vfs/path.js';
+import { hasLeadingCliFlag } from './cli-flags.js';
+import { WASI_ABI_NAMESPACE, WASI_INSTANCE_PREAMBLE_SRC } from './wasi-instance.js';
+const CLANG_VERSION_FLAGS = new Set(['--version', '-v']);
+/** Build the runner factory. Closes over the facet host + vfs. */
+export function makeClangRunnerFactory(deps) {
+    const runtimeVfs = deps.vfs.as(CRED_KERNEL);
+    return function clangRunnerFactory(manifest, installRoot, binName, binKind) {
+        const findFile = (rel) => {
+            const entry = manifest.files.find((f) => f.path === rel);
+            return entry ? `${installRoot}/${entry.path}` : null;
+        };
+        const clangVfsPath = findFile('bin/clang');
+        const lldVfsPath = findFile('bin/wasm-ld');
+        const sysrootVfsPath = findFile('share/clang/sysroot.tar');
+        let runtimePromise = null;
+        return async function clangBinHandler(ctx) {
+            const vfs = deps.vfs.as(requireVfsCred(ctx.cred, binName));
+            const argv = ctx.args || [];
+            const cwd = ctx.cwd || '/home/user';
+            // Fast paths — no wasm boot.
+            if (hasLeadingCliFlag(argv, CLANG_VERSION_FLAGS)) {
+                ctx.stdout.write(`Nimbus wasm-clang (binji-2020, LLVM 8.0.1)\n`);
+                ctx.stdout.write(`Target: ${WASM32_WASI_NIMBUS_ABI.id} (via wasm-ld linker)\n`);
+                return 0;
+            }
+            if (argv.includes('--help') || argv.includes('-h')) {
+                ctx.stdout.write(`usage: ${binName} [options] <source.c> -o <output>\n`);
+                ctx.stdout.write(`Wasm-compiled clang/wasm-ld bundle for Nimbus.\n`);
+                ctx.stdout.write(`Target: ${WASM32_WASI_NIMBUS_ABI.id}\n`);
+                ctx.stdout.write(`Supported: C compilation + linking to wasm.\n`);
+                return 0;
+            }
+            const isLinker = binKind === 'linker' || binName === 'wasm-ld';
+            // Resolve bundle paths.
+            if (!sysrootVfsPath || !runtimeVfs.exists(sysrootVfsPath)) {
+                ctx.stderr.write(`${binName}: sysroot.tar missing from install\n`);
+                return 127;
+            }
+            if (!clangVfsPath || !lldVfsPath) {
+                ctx.stderr.write(`${binName}: clang/wasm-ld missing from install\n`);
+                return 127;
+            }
+            // Parse argv: find input .c + output path.
+            const parsed = parseUserArgv(argv);
+            if (parsed.error) {
+                ctx.stderr.write(`${binName}: ${parsed.error}\n`);
+                return parsed.exitCode;
+            }
+            if (isLinker) {
+                // Direct wasm-ld invocation: pass argv through (advanced
+                // users only). Not on the hello-world path.
+                ctx.stderr.write(`${binName}: direct wasm-ld invocation not yet wired (v1.2)\n`);
+                return 2;
+            }
+            // Validate all user-supplied source inputs exist in the user's
+            // session VFS. Collect their bytes to seed the filesystem.
+            const userSourceFiles = {};
+            // Pre-built objects/archives the user passed (e.g. extra.o, libfoo.a)
+            // — shipped to the LINK step only (not compile).
+            const preBuiltLinkInputs = [];
+            const sourceInputs = [];
+            for (const input of parsed.inputPaths) {
+                const inputAbs = resolveVfsPath(input, cwd);
+                try {
+                    if (!vfs.exists(inputAbs)) {
+                        ctx.stderr.write(`${binName}: ${input}: No such file or directory\n`);
+                        return 1;
+                    }
+                    userSourceFiles[input] = vfs.readFile(inputAbs);
+                }
+                catch (error) {
+                    ctx.stderr.write(`${binName}: ${input}: ${errorMessage(error)}\n`);
+                    return 1;
+                }
+                if (isSourceExt(input)) {
+                    sourceInputs.push(input);
+                }
+                else {
+                    // .o / .a — pass through to link as a pre-built input. The
+                    // path in the seeded filesystem is the user-supplied relative path.
+                    preBuiltLinkInputs.push(input);
+                }
+            }
+            if (sourceInputs.length === 0 && preBuiltLinkInputs.length === 0) {
+                ctx.stderr.write(`${binName}: no compilable / linkable inputs\n`);
+                return 1;
+            }
+            let runtime;
+            try {
+                if (!runtimePromise) {
+                    runtimePromise = createClangFacetRuntime(deps.facets, {
+                        clangVfsPath,
+                        lldVfsPath,
+                        sysrootVfsPath,
+                        vfs: runtimeVfs,
+                    });
+                }
+                runtime = await runtimePromise;
+            }
+            catch (e) {
+                runtimePromise = null;
+                ctx.stderr.write(`${binName}: clang runtime warm-up failed: ${errorMessage(e)}\n`);
+                return 1;
+            }
+            // Walk the user's cwd to gather headers (.h/.hpp/.hxx/.inc/...)
+            // and any sibling headers users typically expect to be visible
+            // to #include "..." resolution. Real clang/gcc auto-search the
+            // dir of the including source for quote-form includes; we ship
+            // those files at their relative-to-cwd paths so the seeded
+            // filesystem reproduces the user's working tree.
+            //
+            // Size-capped (4 MiB, 200 files, depth 8) so accidental
+            // huge-projects don't OOM the facet. Real C-tutorial projects
+            // are vastly under the cap.
+            const userIncludeBundle = collectIncludeBundle(vfs, cwd.replace(/^\/+/, ''));
+            // ── COMPILE PHASE ────────────────────────────────────────────
+            // Reuse the warm clang pool and ship only the C-include
+            // subset plus user source/header files for this invocation.
+            // Build -I flag list. We pass each user -I path verbatim AND add
+            // an implicit '.' (cwd) for quote-form lookup. wasm-clang's -cc1
+            // mode does NOT add cwd to the quote search list by default
+            // (the driver normally does that for "foo.h" includes), so we
+            // wire it ourselves. This is what makes
+            //   clang main.c   (main.c does #include "greet.h", greet.h
+            //                    next to main.c)
+            // succeed without an explicit -I from the user.
+            const userIncludeFlags = [];
+            for (const ip of parsed.includePaths) {
+                userIncludeFlags.push('-I', ip);
+            }
+            userIncludeFlags.push('-I', '.');
+            // Compile each source to its own .o. Object file naming: replace
+            // the source extension with .o. Collisions across cwd subdirs
+            // (e.g. src/foo.c and lib/foo.c both → foo.o) are avoided by
+            // keeping the directory component (the seed preserves user layout).
+            const objPaths = [];
+            const objBytesMap = {};
+            for (const src of sourceInputs) {
+                const objPath = src.replace(/\.(c|cc|cpp|cxx|c\+\+|C)$/, '.o');
+                // For C++ inputs use -x c++; default -x c.
+                const isCpp = /\.(cc|cpp|cxx|c\+\+|C)$/.test(src);
+                const compileArgv = [
+                    'clang', '-cc1', '-emit-obj',
+                    '-disable-free',
+                    '-isysroot', '/',
+                    '-internal-isystem', '/include/c++/v1',
+                    '-internal-isystem', '/include',
+                    '-internal-isystem', '/lib/clang/8.0.1/include',
+                    '-ferror-limit', '19',
+                    '-fmessage-length', '80',
+                    '-fcolor-diagnostics',
+                    '-O2',
+                    ...userIncludeFlags,
+                    '-o', objPath,
+                    '-x', isCpp ? 'c++' : 'c',
+                    src,
+                ];
+                // Per compile we ship: the current source file + the user's
+                // header bundle. Multi-TU is handled at link time, not compile,
+                // so sibling sources stay out of the seed (smaller payload, no
+                // surface for unintended cross-TU textual inclusion via -I.).
+                const oneSourceFile = { [src]: userSourceFiles[src] };
+                const compileResult = await dispatchClangFacet(runtime.compile, {
+                    sysrootFiles: {
+                        ...runtime.compile.sysrootFiles,
+                        ...oneSourceFile,
+                        // User's headers from cwd tree (so quote-form #include
+                        // resolves; this is the primary clang-include-fix payload).
+                        ...userIncludeBundle,
+                    },
+                    argv: compileArgv,
+                    outputPaths: [objPath],
+                });
+                if (compileResult.stdout)
+                    ctx.stdout.write(compileResult.stdout);
+                if (compileResult.stderr)
+                    ctx.stderr.write(compileResult.stderr);
+                if (compileResult.error) {
+                    ctx.stderr.write(`${binName}: ${compileResult.error}\n`);
+                    return 1;
+                }
+                if (compileResult.exitCode !== 0) {
+                    return compileResult.exitCode;
+                }
+                const objBytes = compileResult.outputFiles[objPath];
+                if (!objBytes || objBytes.length === 0) {
+                    ctx.stderr.write(`${binName}: compile produced no ${objPath} (internal error)\n`);
+                    return 1;
+                }
+                objPaths.push(objPath);
+                objBytesMap[objPath] = objBytes;
+            }
+            // -c (compile-only): flush each .o to the user VFS, no link.
+            if (parsed.compileOnly) {
+                for (const objPath of objPaths) {
+                    const objVfsPath = resolveVfsPath(objPath, cwd);
+                    const parent = objVfsPath.replace(/\/[^/]+$/, '');
+                    if (parent && parent !== objVfsPath && !vfs.exists(parent)) {
+                        vfs.mkdir(parent, { recursive: true });
+                    }
+                    vfs.writeFile(objVfsPath, objBytesMap[objPath]);
+                }
+                // Honor user's -o for single-input compile-only: rename the one
+                // .o to the requested output if -o was passed.
+                if (sourceInputs.length === 1 && parsed.outputPath !== 'a.out') {
+                    const fromVfs = resolveVfsPath(objPaths[0], cwd);
+                    const toVfs = resolveVfsPath(parsed.outputPath, cwd);
+                    if (fromVfs !== toVfs) {
+                        try {
+                            vfs.writeFile(toVfs, vfs.readFile(fromVfs));
+                            vfs.unlink(fromVfs);
+                        }
+                        catch { /* best-effort */ }
+                    }
+                }
+                return 0;
+            }
+            // Add pre-built .o / .a inputs (the user passed them on argv
+            // alongside .c sources, e.g. `clang main.c extra.o -o out`).
+            const preBuiltBytesMap = {};
+            for (const lp of preBuiltLinkInputs) {
+                preBuiltBytesMap[lp] = userSourceFiles[lp];
+            }
+            // ── LINK PHASE ───────────────────────────────────────────────
+            // Reuse the warm wasm-ld pool and ship only the link
+            // sysroot subset plus object/archive inputs for this invocation.
+            const stackSize = 1024 * 1024;
+            // User-supplied -L paths and -l libraries flow through. The user
+            // -L paths point at user-VFS dirs; we currently don't ship user
+            // libraries (they'd need their own collect step), so -l<name>
+            // works only against the sysroot's -L paths today. -L user-side
+            // would no-op silently in v1 — out of scope for this wave.
+            const userLinkFlags = [];
+            for (const lp of parsed.libraryPaths) {
+                userLinkFlags.push('-L', lp);
+            }
+            const linkArgv = [
+                'wasm-ld',
+                '--no-threads',
+                '--export-dynamic',
+                '-z', `stack-size=${stackSize}`,
+                '-L/lib/wasm32-wasi',
+                // Stream-C: modern wasi-libc references __muloti4 / __divti3
+                // (128-bit math from utimensat's timespec arithmetic) — these
+                // live in compiler-rt's libclang_rt.builtins-wasm32.a at the
+                // clang resource dir. binji-2020's libc.a self-bundled them;
+                // modern doesn't, so we link compiler-rt explicitly. wasm-ld
+                // dead-strips unused builtins, so binji binaries are unaffected.
+                '-L/lib/clang/8.0.1/lib/wasi',
+                ...userLinkFlags,
+                '/lib/wasm32-wasi/crt1.o',
+                ...objPaths,
+                ...preBuiltLinkInputs,
+                '-lc',
+                ...parsed.libraries.map((l) => '-l' + l),
+                '-lclang_rt.builtins-wasm32',
+                '-o', parsed.outputPath,
+            ];
+            const linkResult = await dispatchClangFacet(runtime.link, {
+                sysrootFiles: { ...runtime.link.sysrootFiles, ...objBytesMap, ...preBuiltBytesMap },
+                argv: linkArgv,
+                outputPaths: [parsed.outputPath],
+            });
+            if (linkResult.stdout)
+                ctx.stdout.write(linkResult.stdout);
+            if (linkResult.stderr)
+                ctx.stderr.write(linkResult.stderr);
+            if (linkResult.error) {
+                ctx.stderr.write(`${binName}: ${linkResult.error}\n`);
+                return 1;
+            }
+            if (linkResult.exitCode !== 0) {
+                return linkResult.exitCode;
+            }
+            const wasmBytes = linkResult.outputFiles[parsed.outputPath];
+            if (!wasmBytes || wasmBytes.length === 0) {
+                ctx.stderr.write(`${binName}: link produced no ${parsed.outputPath} (internal error)\n`);
+                return 1;
+            }
+            // ── FLUSH OUTPUT ─────────────────────────────────────────────
+            const outVfsPath = resolveVfsPath(parsed.outputPath, cwd);
+            try {
+                const parent = outVfsPath.replace(/\/[^/]+$/, '');
+                if (parent && parent !== outVfsPath && !vfs.exists(parent)) {
+                    vfs.mkdir(parent, { recursive: true });
+                }
+                vfs.writeFile(outVfsPath, wasmBytes);
+                vfs.chmod(outVfsPath, 0o755);
+            }
+            catch (error) {
+                ctx.stderr.write(`${binName}: ${parsed.outputPath}: ${errorMessage(error)}\n`);
+                return 1;
+            }
+            // Real linkers chmod their output executable (+x even after a
+            // prior chmod -x) — so `./a.out` runs with no manual chmod.
+            return 0;
+        };
+    };
+}
+/** Recognized C / C++ source extensions for input classification. */
+function isSourceExt(p) {
+    return /\.(c|cc|cpp|cxx|c\+\+|C)$/.test(p);
+}
+/**
+ * Nimbus RUNS threaded wasm — see runtime/wasi-threads.ts — but this compiler
+ * cannot BUILD it. The bundled toolchain is LLVM 8 over a wasi-sdk-19 sysroot
+ * that ships one target directory, `lib/wasm32-wasi`, with no threads variant:
+ * no atomics-and-bulk-memory libc, no `libpthread.a`, and a fixed link line
+ * with no `--shared-memory`.
+ *
+ * Measured on the shipped sysroot, `-pthread` fell through parseUserArgv's
+ * catch-all for unrecognised flags, and what the user saw depended on their
+ * includes: `clang -pthread prog.c` on a program that does not include
+ * <pthread.h> built and ran with exit 0 and the flag quietly ignored, while a
+ * real threaded program died at `'pthread.h' file not found` — a diagnosis
+ * that names a missing header rather than a toolchain that has no threads at
+ * all, and points nowhere. Refuse at the front door instead, and say where the
+ * working path is, because Nimbus does run these programs once they are built
+ * correctly.
+ */
+function threadedBuildRefusal(argv) {
+    const flag = argv.find((a) => a === '-pthread' || a === '-mthread-model' || a === '--pthread'
+        || /^(-target|--target)=.*threads$/.test(a));
+    const target = argv.findIndex((a) => a === '-target' || a === '--target');
+    const targetsThreads = target >= 0 && /threads$/.test(argv[target + 1] || '');
+    if (!flag && !targetsThreads)
+        return null;
+    return `${flag ?? `${argv[target]} ${argv[target + 1]}`}: this toolchain cannot build threaded wasm.\n`
+        + `  The bundled sysroot is wasm32-wasi only — it has no wasm32-wasip1-threads libc.\n`
+        + `  Nimbus RUNS pthread programs (mutex, condvar, join, TLS, barrier, semaphore),\n`
+        + `  but they must be built with a full wasi-sdk and linked against the futex shim:\n`
+        + `    clang --target=wasm32-wasip1-threads --sysroot=$WASI_SYSROOT -pthread \\\n`
+        + `      -Wl,--import-memory,--shared-memory,--max-memory=67108864 \\\n`
+        + `      -o prog.wasm prog.c nimbus-threads.c\n`
+        + `  See docs/wasi-threads.md for nimbus-threads.c and why the shim is required.`;
+}
+function parseUserArgv(argv) {
+    const inputPaths = [];
+    const includePaths = [];
+    const libraryPaths = [];
+    const libraries = [];
+    let outputPath = 'a.out';
+    let compileOnly = false;
+    // Flags that take a separate argv slot for their value.
+    const takesArg = new Set(['-o', '-x', '-isystem', '-include', '-isysroot',
+        '-target', '--target', '-std', '-MF', '-MT', '-MQ']);
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a === '-o' && i + 1 < argv.length) {
+            outputPath = argv[i + 1];
+            i++;
+            continue;
+        }
+        if (a === '-c') {
+            compileOnly = true;
+            continue;
+        }
+        // -I<path> or -I <path>
+        if (a === '-I' && i + 1 < argv.length) {
+            includePaths.push(argv[i + 1]);
+            i++;
+            continue;
+        }
+        if (a.startsWith('-I')) {
+            includePaths.push(a.substring(2));
+            continue;
+        }
+        // -L<path> or -L <path>
+        if (a === '-L' && i + 1 < argv.length) {
+            libraryPaths.push(argv[i + 1]);
+            i++;
+            continue;
+        }
+        if (a.startsWith('-L')) {
+            libraryPaths.push(a.substring(2));
+            continue;
+        }
+        // -l<name> or -l <name>
+        if (a === '-l' && i + 1 < argv.length) {
+            libraries.push(argv[i + 1]);
+            i++;
+            continue;
+        }
+        if (a.startsWith('-l')) {
+            libraries.push(a.substring(2));
+            continue;
+        }
+        // Skip recognised takes-arg flags we don't yet interpret.
+        if (takesArg.has(a) && i + 1 < argv.length) {
+            i++;
+            continue;
+        }
+        // Any other -flag is opaque to the parser; the user passes them
+        // through (we don't currently relay arbitrary flags to clang-cc1,
+        // see compileArgv construction).
+        if (a.startsWith('-'))
+            continue;
+        // Positional. If it looks like a source file, take it; else ignore.
+        if (isSourceExt(a)) {
+            inputPaths.push(a);
+        }
+        else if (a.endsWith('.o') || a.endsWith('.a')) {
+            // Pre-built objects/archives — treat as link-only inputs. We
+            // surface them as inputs so the link step picks them up; the
+            // compile step skips them (it only walks .c/.cc/.cpp).
+            inputPaths.push(a);
+        }
+        // else: drop silently (e.g. typos). clang would warn; we don't yet.
+    }
+    const threaded = threadedBuildRefusal(argv);
+    if (threaded) {
+        return {
+            inputPaths: [], includePaths, libraryPaths, libraries,
+            outputPath: '', compileOnly, exitCode: 1, error: threaded,
+        };
+    }
+    if (inputPaths.length === 0) {
+        return {
+            inputPaths: [], includePaths, libraryPaths, libraries,
+            outputPath: '', compileOnly, exitCode: 2, error: 'no input files',
+        };
+    }
+    return {
+        inputPaths, includePaths, libraryPaths, libraries,
+        outputPath, compileOnly, exitCode: 0,
+    };
+}
+/**
+ * Recognise headers / inline-include files. The compile facet ships
+ * these alongside the .c sources so `#include "foo.h"` (quote-form)
+ * resolves against the directory of the including source file — which
+ * is how clang / gcc behave on real Unix.
+ */
+function isHeaderExt(name) {
+    return /\.(h|hh|hpp|hxx|H|inc|ipp|tcc)$/.test(name);
+}
+/**
+ * Walk a VFS directory recursively to collect headers + (optionally)
+ * source files, with bounded depth and total size cap, returning a
+ * map of root-relative-path → bytes.
+ *
+ * Layout convention: paths returned are RELATIVE TO `rootVfsPath`, so
+ * a header at `home/user/sub/foo.h` (when rootVfsPath is `home/user`)
+ * comes out as `sub/foo.h`. This matches the layout the user passes
+ * on argv (e.g. `clang sub/lib.c -o out`, with `lib.c` including
+ * `"helpers.h"` next to itself).
+ *
+ * `extra` extensions can be added (used to include `.c/.cpp/.o/.a` when
+ * looking under -L / sibling source dirs). Empty by default.
+ *
+ * Anti-DoS:
+ *   - MAX_FILES = 200 (covers realistic user projects without ballooning
+ *     the facet payload).
+ *   - MAX_BYTES = 4 MiB.
+ *   - MAX_DEPTH = 8 (deep enough for typical "src/", "include/", "lib/" trees).
+ *   - skipDirs prunes obvious non-source directories.
+ */
+function collectIncludeBundle(vfs, rootVfsPath, opts = {}) {
+    const extraExts = opts.extraExts ?? null;
+    const MAX_FILES = opts.maxFiles ?? 200;
+    const MAX_BYTES = opts.maxBytes ?? 4 * 1024 * 1024;
+    const MAX_DEPTH = opts.maxDepth ?? 8;
+    const out = {};
+    if (!vfs.exists(rootVfsPath) || !vfs.isDirectory(rootVfsPath))
+        return out;
+    // Directories pruned regardless of depth — these never contain user
+    // headers and would balloon the payload if traversed.
+    const skipDirs = new Set([
+        '.nimbus', 'node_modules', '.cache', '.npm', '.git',
+        'dist', 'build', '.next', '.nuxt', '.svelte-kit', 'coverage',
+    ]);
+    const root = rootVfsPath.replace(/^\/+/, '').replace(/\/+$/, '');
+    let totalBytes = 0;
+    let fileCount = 0;
+    const stack = [{ dir: root, depth: 0 }];
+    while (stack.length > 0) {
+        const { dir, depth } = stack.pop();
+        if (depth > MAX_DEPTH)
+            continue;
+        let entries;
+        try {
+            entries = vfs.readdir(dir);
+        }
+        catch {
+            continue;
+        }
+        for (const e of entries) {
+            const childAbs = dir + '/' + e.name;
+            const rel = childAbs.startsWith(root + '/') ? childAbs.substring(root.length + 1) : childAbs;
+            if (e.type === 'directory') {
+                if (skipDirs.has(e.name))
+                    continue;
+                stack.push({ dir: childAbs, depth: depth + 1 });
+                continue;
+            }
+            const isHeader = isHeaderExt(e.name);
+            const isExtra = extraExts && extraExts.test(e.name);
+            if (!isHeader && !isExtra)
+                continue;
+            let bytes;
+            try {
+                bytes = vfs.readFile(childAbs);
+            }
+            catch {
+                continue;
+            }
+            totalBytes += bytes.length;
+            fileCount++;
+            if (totalBytes > MAX_BYTES || fileCount > MAX_FILES) {
+                // Cap reached — stop walking but return what we have.
+                return out;
+            }
+            out[rel] = bytes;
+        }
+    }
+    return out;
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+// ── ustar parser (supervisor-side) ───────────────────────────────────
+/**
+ * Parse a POSIX ustar archive into a path→bytes map. Trims the
+ * leading "/" from paths so they are seen as "include/stdio.h"
+ * (not "/include/stdio.h"). Directories are NOT recorded — only
+ * regular file entries.
+ */
+function parseUstar(tarBytes) {
+    const files = new Map();
+    let off = 0;
+    while (off + 512 <= tarBytes.length) {
+        let nameEnd = off;
+        while (nameEnd < off + 100 && tarBytes[nameEnd] !== 0)
+            nameEnd++;
+        let name = '';
+        for (let i = off; i < nameEnd; i++)
+            name += String.fromCharCode(tarBytes[i]);
+        if (!name)
+            break;
+        const typeflag = tarBytes[off + 156];
+        let sizeStr = '';
+        for (let i = off + 124; i < off + 124 + 11; i++) {
+            const c = tarBytes[i];
+            if (c >= 0x30 && c <= 0x37)
+                sizeStr += String.fromCharCode(c);
+        }
+        const size = parseInt(sizeStr || '0', 8);
+        let prefixEnd = off + 345;
+        while (prefixEnd < off + 345 + 155 && tarBytes[prefixEnd] !== 0)
+            prefixEnd++;
+        let prefix = '';
+        for (let i = off + 345; i < prefixEnd; i++)
+            prefix += String.fromCharCode(tarBytes[i]);
+        const fullName = prefix ? `${prefix}/${name}` : name;
+        off += 512;
+        const isRegular = typeflag === 0 || typeflag === 0x30; // '0'
+        const isDir = typeflag === 0x35 || fullName.endsWith('/'); // '5'
+        if (isRegular && !isDir) {
+            const bytes = tarBytes.slice(off, off + size);
+            files.set(fullName.replace(/\/$/, ''), bytes);
+        }
+        off += Math.ceil(size / 512) * 512;
+    }
+    return files;
+}
+/**
+ * Filter the sysroot to just what the compile step needs:
+ *   - include/ (minus include/c++/) — C system headers
+ *   - lib/clang/8.0.1/include/ — clang intrinsic headers
+ *
+ * Excludes the C++ standard library headers (libc++/v1) which alone
+ * are ~4 MiB and aren't needed for plain C compilation.
+ */
+function filterSysrootForCompile(all) {
+    const out = {};
+    for (const [path, bytes] of all.entries()) {
+        if (path.startsWith('include/c++/'))
+            continue;
+        if (path.startsWith('include/')) {
+            out[path] = bytes;
+            continue;
+        }
+        if (path.startsWith('lib/clang/')) {
+            out[path] = bytes;
+            continue;
+        }
+    }
+    return out;
+}
+/**
+ * Filter the sysroot to just what the link step needs for a C program:
+ *   - lib/wasm32-wasi/crt1.o — the entry-point start file
+ *   - lib/wasm32-wasi/libc.a — libc archive (printf etc.)
+ *   - lib/wasm32-wasi/libc.imports — WASI symbol allow-list. Without
+ *     this, wasm-ld treats `__wasi_fd_close` etc. as undefined
+ *     symbols (the symbols are SUPPOSED to be unresolved imports,
+ *     not errors); the .imports file tells lld "these names are
+ *     external WASI imports, not link errors."
+ *   - lib/clang/8.0.1/lib/wasi/libclang_rt.builtins-wasm32.a — compiler-rt
+ *     builtins (e.g. __muloti4 for 128-bit math). Modern wasi-libc's
+ *     utimensat.o references __muloti4; binji-2020 self-bundled it
+ *     into libc.a, the modern build expects compiler-rt to provide.
+ *     wasm-ld dead-strips, so trivial mains pay zero cost.
+ *
+ * Excludes libc++/libc++abi (C++-only) and the WASI emulated-mman /
+ * pthread / canvas variants we don't drive in v1.1.
+ */
+function filterSysrootForLink(all) {
+    const out = {};
+    for (const [path, bytes] of all.entries()) {
+        if (path === 'lib/wasm32-wasi/crt1.o') {
+            out[path] = bytes;
+            continue;
+        }
+        if (path === 'lib/wasm32-wasi/libc.a') {
+            out[path] = bytes;
+            continue;
+        }
+        if (path === 'lib/wasm32-wasi/libc.imports') {
+            out[path] = bytes;
+            continue;
+        }
+        if (path === 'lib/clang/8.0.1/lib/wasi/libclang_rt.builtins-wasm32.a') {
+            out[path] = bytes;
+            continue;
+        }
+    }
+    return out;
+}
+async function createClangFacetRuntime(facets, args) {
+    if (!args.clangVfsPath || !args.lldVfsPath || !args.sysrootVfsPath) {
+        throw new Error('installed clang manifest is missing required files');
+    }
+    // Hand the file's own backing buffer to the loader when the Uint8Array
+    // spans it exactly (the uncached reads below always allocate a fresh
+    // whole buffer) — avoids a second 31 MiB copy of clang.wasm in the DO
+    // heap during warm-up. Falls back to a slice for sub-views.
+    const toAB = (u8) => (u8.byteOffset === 0 && u8.byteLength === u8.buffer.byteLength
+        ? u8.buffer
+        : u8.buffer.slice(u8.byteOffset, u8.byteOffset + u8.byteLength));
+    // Uncached reads: these are one-shot bulk reads of large runtime blobs
+    // (clang 31 MiB, wasm-ld 18.5 MiB, sysroot 9.3 MiB). Routing them
+    // through the LRU content cache would evict the user's hot working set
+    // and pin ~32 MiB of clang chunks resident in the DO heap for the whole
+    // session — a primary cause of supervisor-DO memory pressure that tips
+    // heavy sessions into an OOM reset mid-compile.
+    const clangBytes = args.vfs.readFileUncached(args.clangVfsPath);
+    const lldBytes = args.vfs.readFileUncached(args.lldVfsPath);
+    const sysroot = parseUstar(args.vfs.readFileUncached(args.sysrootVfsPath));
+    const makeTarget = (primaryName, primaryBytes, sysrootFiles) => ({
+        primaryName,
+        sysrootFiles,
+        facet: facets.open({
+            tag: `clang-runner-${primaryName}`,
+            concurrency: 1,
+            // No `syscalls`: the toolchain is sealed. It sees the sysroot subset and
+            // the translation unit it was handed, and the outputs are read back out
+            // of that filesystem — a compile cannot reach the session at all.
+            //
+            // Which is also why one warm facet may serve every tenant: with nothing
+            // of the session in it and nothing kept between calls, `clang main.c` is
+            // the same compile whoever asks.
+            reuse: 'global',
+            preamble: CLANG_RUNNER_PREAMBLE,
+            wasmModules: { 'primary.wasm': toAB(primaryBytes) },
+        }),
+    });
+    return {
+        compile: makeTarget('clang', clangBytes, filterSysrootForCompile(sysroot)),
+        link: makeTarget('wasm-ld', lldBytes, filterSysrootForLink(sysroot)),
+    };
+}
+async function dispatchClangFacet(target, args) {
+    // Encode sysroot files as base64 for facet transport. We do this on
+    // the supervisor to keep the facet preamble small and CPU-light.
+    const filesB64 = {};
+    for (const [path, bytes] of Object.entries(args.sysrootFiles)) {
+        filesB64[path] = uint8ToBase64(bytes);
+    }
+    const facetFn = async function clangFacetCall(inArgs) {
+        const wasm = Reflect.get(globalThis, '__NIMBUS_WASM');
+        const primaryMod = wasm?.['primary.wasm'];
+        if (!primaryMod) {
+            return {
+                exitCode: 127, stdout: '', stderr: '',
+                outputFiles: {},
+                error: 'clang-runner: __NIMBUS_WASM missing primary.wasm',
+            };
+        }
+        const fn = Reflect.get(globalThis, '__clangRun');
+        if (typeof fn !== 'function') {
+            return {
+                exitCode: 127, stdout: '', stderr: '',
+                outputFiles: {},
+                error: 'clang-runner preamble missing: __clangRun not in scope',
+            };
+        }
+        return await fn({
+            primaryName: inArgs.primaryName,
+            argv: inArgs.argv,
+            filesB64: inArgs.filesB64,
+            outputPaths: inArgs.outputPaths,
+            primaryMod,
+        });
+    };
+    try {
+        const result = await target.facet.submit(facetFn, {
+            primaryName: target.primaryName,
+            argv: args.argv,
+            filesB64,
+            outputPaths: args.outputPaths,
+        }, {
+            timeoutMs: 300_000,
+        });
+        // Decode outputFiles from base64 → Uint8Array.
+        const outputFiles = {};
+        for (const [path, b64] of Object.entries(result.outputFiles || {})) {
+            const bin = atob(b64);
+            const u8 = new Uint8Array(bin.length);
+            for (let i = 0; i < bin.length; i++)
+                u8[i] = bin.charCodeAt(i);
+            outputFiles[path] = u8;
+        }
+        return {
+            exitCode: result.exitCode,
+            stdout: result.stdout || '',
+            stderr: result.stderr || '',
+            outputFiles,
+            error: result.error,
+        };
+    }
+    catch (e) {
+        return {
+            exitCode: 1,
+            stdout: '',
+            stderr: '',
+            outputFiles: {},
+            error: `clang-runner dispatch failed: ${errorMessage(e)}`,
+        };
+    }
+}
+function uint8ToBase64(u8) {
+    // Chunked to avoid String.fromCharCode call-stack limits on big arrays.
+    const CHUNK = 0x8000;
+    let s = '';
+    for (let i = 0; i < u8.length; i += CHUNK) {
+        s += String.fromCharCode.apply(null, Array.from(u8.subarray(i, Math.min(i + CHUNK, u8.length))));
+    }
+    return btoa(s);
+}
+// ── Facet preamble ───────────────────────────────────────────────────
+const CLANG_RUNNER_PREAMBLE_TAIL = `
+// ── BEGIN: clang-runner preamble ──────────────────────────────────────
+//
+// The toolchain is a plain wasi_unstable (preview0) guest: clang.wasm
+// declares 27 imports and wasm-ld 25, every one of them in that namespace
+// and every one of them implemented by the WASI layer above. Its filesystem
+// is that layer's, seeded with the sysroot subset and the translation unit
+// and sealed — no supervisor is bound, so a compile cannot reach or disturb
+// the session VFS, and the named outputs are read back out at the end.
+
+globalThis.__clangRun = async function __clangRun(args) {
+  const stdout = [];
+  const stderr = [];
+
+  // Everything the seed carries is readable; directories are traversable.
+  // The layer denies by default for a mapped inode with no mode, and the
+  // producer here is a tar, which has no cred to project.
+  const modes = {};
+  const dirs = new Set();
+  for (const path of Object.keys(args.filesB64 || {})) {
+    const canon = path.replace(/^\\/+/, '');
+    modes[canon] = 6;
+    const parts = canon.split('/');
+    for (let i = 1; i < parts.length; i++) {
+      const dir = parts.slice(0, i).join('/');
+      dirs.add(dir);
+      modes[dir] = 7;
+    }
+  }
+  modes[''] = 7;
+
+  __wasiInitFS({
+    root: '',
+    // One preopen with the EMPTY name. That is what makes a bare relative
+    // input resolve: this toolchain's wasi-libc predates cwd support, so a
+    // relative path is matched only against a zero-length preopen name, and
+    // an absolute one ('-isysroot /' puts the sysroot at /include) against
+    // the same entry with the leading slash stripped. Naming it '/' serves
+    // the absolute paths and silently loses every relative one — the input
+    // file then fails to open with no path_open ever reaching this layer.
+    preopens: [{ wasiPath: '', vfsPath: '' }],
+    files: args.filesB64 || {},
+    dirs: Array.from(dirs).filter(Boolean),
+    modes,
+  });
+
+  let memory = null;
+  const wasi = __wasiMakeImports({
+    abi: 'preview0',
+    argv: args.argv || [],
+    env: { USER: 'user', HOME: '/', PWD: '/' },
+    getMemory: () => memory,
+    stdoutWrite: (s) => { stdout.push(s); },
+    stderrWrite: (s) => { stderr.push(s); },
+  });
+
+  let instance;
+  try {
+    const r = await WebAssembly.instantiate(args.primaryMod, {
+      ${WASI_ABI_NAMESPACE.preview0}: wasi.wasiImport,
+    });
+    instance = (r instanceof WebAssembly.Instance ? r : r.instance);
+  } catch (e) {
+    return {
+      exitCode: 1, stdout: stdout.join(''), stderr: stderr.join(''), outputFiles: {},
+      error: 'primary (' + args.primaryName + ') instantiate failed: ' + (e && e.message),
+    };
+  }
+  memory = instance.exports.memory;
+
+  const run = await __wasiRunStartAsync(instance, { memory });
+  if (run.error) {
+    stderr.push('[clang-runner] ' + args.primaryName + ' trapped: ' + run.error + '\\n');
+  }
+
+  return {
+    exitCode: run.exitCode,
+    stdout: stdout.join(''),
+    stderr: stderr.join(''),
+    outputFiles: __wasiReadFilesB64(args.outputPaths || []),
+  };
+};
+
+// ── END: clang-runner preamble ────────────────────────────────────────
+`;
+export const CLANG_RUNNER_PREAMBLE = `${WASI_INSTANCE_PREAMBLE_SRC}\n${CLANG_RUNNER_PREAMBLE_TAIL}`;