@nimbus-sh/core 0.3.0 → 0.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ashish Kumar Singh and Nimbus contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/README.md

@@ -0,0 +1,112 @@
+# @nimbus-sh/core
+
+> Part of [Nimbus](https://github.com/AshishKumar4/Nimbus), my hobby/research
+> cloud OS. This README is edited and maintained with Claude (AI) and
+> presented as-is.
+
+The backend-agnostic half of Nimbus: a durable POSIX-like filesystem, a shell
+with 60+ Unix commands, and the WASI runtime layer — with no Cloudflare
+dependency. You hand it a SQLite and get back `.fs` and `.exec`. On
+Cloudflare that SQLite is `ctx.storage.sql` inside your Durable Object; in bun
+or node it is `bun:sqlite` or `node:sqlite`.
+
+I extracted this package because I kept wanting Nimbus *inside* other
+projects — a Durable Object that already does something else but needs a real
+workspace, or a local script that needs the same filesystem semantics the
+hosted product has. The whole of it runs on two narrow ports (`SqlDatabase`
+and `SqlTransactions`), so the same code serves both hosts.
+
+## Quick start
+
+```ts
+import { Database } from 'bun:sqlite';
+import { NimbusWorkspace } from '@nimbus-sh/core/workspace';
+
+const db = new Database('workspace.sqlite');
+const sql = {
+  exec(q, ...p) {
+    const st = db.query(q);
+    if (st.columnNames.length === 0) { db.run(q, ...p); return []; }
+    return st.all(...p);
+  },
+};
+const transactions = { storage: { transactionSync: (cb) => db.transaction(cb)() } };
+
+const ws = await NimbusWorkspace.create({ sql, transactions, generation: 1 });
+
+await ws.fs.writeFile('/home/user/hello.txt', 'hi\n');
+const out = await ws.exec('cat /home/user/hello.txt | wc -c');   // { stdout: '3\n', exitCode: 0 }
+```
+
+Inside a Cloudflare Durable Object the same call is:
+
+```ts
+const ws = await NimbusWorkspace.create({
+  sql: this.ctx.storage.sql,
+  transactions: this.ctx,
+  generation,
+});
+```
+
+Files written through `.fs` are owned by the session user (uid 1000), not
+root, and the shell enforces the same permission model either way: a
+root-owned `/etc/passwd` refuses a write from `.fs`, and `id` resolves names
+through it.
+
+## Real runtimes, off Cloudflare
+
+The wasm runtimes are separate npm packages so nobody downloads a Python
+interpreter to get a filesystem. Install the ones you want and pass them in:
+
+```bash
+npm install @nimbus-sh/runtime-bash @nimbus-sh/runtime-cpython
+```
+
+```ts
+import bash from '@nimbus-sh/runtime-bash';
+import cpython from '@nimbus-sh/runtime-cpython';
+import { localFacetHost } from '@nimbus-sh/core';
+
+const ws = await NimbusWorkspace.create({
+  sql, transactions, generation: 1,
+  facets: localFacetHost(),
+  runtimes: [bash, cpython],
+});
+
+await ws.exec('bash -c "echo $((6*7))"');       // 42 — GNU bash 5.2, real BusyBox children
+await ws.exec(`python -c "import sqlite3; print('live')"`);  // CPython 3.13, real stdlib
+```
+
+`@nimbus-sh/runtime-ruby` (Ruby 3.3) and `@nimbus-sh/runtime-clang` (clang →
+`wasm32-wasi`, compile and run C in the workspace) work the same way. Every
+package carries the same manifest and the same sha256-verified blobs the
+hosted product serves from R2 — one publisher, two transports.
+
+Without `facets` and `runtimes` you still get the full shell and coreutils;
+the wasm runtimes are a dependency you add, not a mode you enable.
+
+## Sharing a database with your own app
+
+The workspace is designed to be a tenant in a database you own, not the owner
+of it:
+
+- It creates and touches only its own tables (`inodes`, `file_chunks`,
+  `content_lifecycle`, `vfs_*`).
+- `destroy()` drops exactly those tables. It never calls `deleteAll()`.
+- `transactionSync` must be a real transaction. An implementation that only
+  calls the callback turns every atomic write into a torn one.
+- `generation` must never repeat across restarts of your host — pids derive
+  from it, and a repeated generation would hand a dead process live write
+  authority.
+
+## What needs the Worker package instead
+
+Resident processes (long-running servers, attached TUIs), the session
+protocol, port routing to the public internet, and the hosted terminal all
+live in [`@nimbus-sh/worker`](https://www.npmjs.com/package/@nimbus-sh/worker),
+which composes on this package. If you want the full hosted product shape,
+start from `npx create-nimbus-app`.
+
+## License
+
+MIT.

package/dist/_shared/tarball-stream.d.ts

@@ -0,0 +1,93 @@
+/**
+ * tarball-stream.ts — pure streaming tar primitives.
+ *
+ * A leaf with no imports at all, deliberately: `bundle-facet-workers.mjs`
+ * esbuilds this file into a string constant the loader pool injects into
+ * dynamic workers, and a facet isolate resolves no specifier. Anything this
+ * file imported would have to travel with it.
+ *
+ * Zero dependencies. Works identically on the supervisor and inside a
+ * facet isolate. Never buffers the full decompressed tarball — peak
+ * transient heap is one file's bytes plus a 512-byte carry.
+ */
+/**
+ * Maximum size of a single file inside a tarball. Larger entries are skipped.
+ *
+ * History: 5 MB was too low — it silently dropped `esbuild-wasm/esbuild.wasm`
+ * (11.35 MB on v0.24.2), which made Nimbus-in-Nimbus `npm run dev` fail with
+ * `No such module "esbuild-wasm/esbuild.wasm"` since the missing file caused
+ * esbuild's VFS plugin to mark the import `external`, and workerd's LOADER
+ * has no entry for that specifier. 20 MB covers esbuild-wasm with headroom
+ * while keeping per-facet peak heap bounded for the streaming extractor.
+ */
+export declare const MAX_FILE_BYTES = 20000000;
+/**
+ * Read one tar header (USTAR) out of `block`. Returns parsed fields or
+ * `null` for an end-of-archive block (all zeros).
+ */
+/**
+ * Collapse "."/".." segments in a tar entry's package-relative path.
+ * Returns the canonical relative path, or '' when the entry escapes its
+ * package root (a leading ".." that pops above the root) — the caller
+ * treats '' as a no-name entry and skips it. Mirrors the segment logic in
+ * w7-frame's canonicalPath so joined write paths are always accepted.
+ */
+export declare function canonicalTarName(name: string): string;
+export declare function parseTarHeader(block: Uint8Array): {
+    name: string;
+    size: number;
+    typeFlag: number;
+} | null;
+/**
+ * Wrap a `ReadableStream<Uint8Array>` as an async iterable. Workerd and
+ * Node both support `Symbol.asyncIterator` on ReadableStream, but we
+ * spell the reader loop out so we don't depend on ambient lib typings.
+ */
+export declare function readableStreamToAsyncIterable(rs: ReadableStream<Uint8Array>): AsyncGenerator<Uint8Array, void, undefined>;
+/**
+ * Reason a tar entry was skipped and never yielded. Surfaced to callers
+ * via the optional `onSkip` callback on `streamTarEntries`.
+ *
+ * - 'too-large': size > MAX_FILE_BYTES. The most common reason Nimbus
+ *   cares about — it's what caused esbuild-wasm/esbuild.wasm to vanish
+ *   silently in Nimbus-in-Nimbus before the cap was raised.
+ * - 'non-regular': typeFlag indicates a symlink / hardlink / directory /
+ *   PaxHeader / GNU LongName etc. These aren't files we stage.
+ * - 'no-name': header parsed but name was empty (malformed or a PaxHeader
+ *   that our parser didn't recognize as non-regular).
+ */
+export type TarSkipReason = 'too-large' | 'non-regular' | 'no-name';
+/**
+ * Optional skip-observer passed to `streamTarEntries`. Called ONCE per
+ * skipped entry, with the declared name (may be empty for 'no-name'
+ * skips) and the declared size in bytes.
+ *
+ * Consumers typically push these into a per-package warnings array so
+ * users see what wasn't installed. The callback is synchronous and
+ * must not throw — thrown errors are swallowed to keep the extractor
+ * best-effort.
+ */
+export type TarSkipCallback = (name: string, size: number, reason: TarSkipReason) => void;
+/**
+ * Streaming tar extractor.
+ *
+ * Consumes an async iterable of Uint8Array chunks (the decompressed tar
+ * byte stream) and yields one `{ name, data }` entry per regular file,
+ * as each file completes.
+ *
+ * Memory invariant: holds at most one pending file's bytes (≤ MAX_FILE_BYTES)
+ * plus a small carry buffer for the tar header being assembled.
+ *
+ * Skips: symlinks, directories, hardlinks, long-name extensions (PaxHeader),
+ * and any file whose declared size exceeds MAX_FILE_BYTES.
+ *
+ * If `onSkip` is provided, it is invoked for each skipped entry with the
+ * name, declared size, and reason code. Callers that need to surface
+ * dropped-file warnings to users should pass one; legacy callers that
+ * omit the arg still behave exactly as before (silent skip).
+ */
+export declare function streamTarEntries(source: AsyncIterable<Uint8Array>, onSkip?: TarSkipCallback): AsyncGenerator<{
+    name: string;
+    data: Uint8Array;
+}, void, undefined>;
+//# sourceMappingURL=tarball-stream.d.ts.map

package/dist/_shared/tarball-stream.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tarball-stream.d.ts","sourceRoot":"","sources":["../../src/_shared/tarball-stream.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH;;;;;;;;;GASG;AACH,eAAO,MAAM,cAAc,WAAa,CAAC;AAEzC;;;GAGG;AACH;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAWrD;AAED,wBAAgB,cAAc,CAAC,KAAK,EAAE,UAAU,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CA+BzG;AAED;;;;GAIG;AACH,wBAAuB,6BAA6B,CAClD,EAAE,EAAE,cAAc,CAAC,UAAU,CAAC,GAC7B,cAAc,CAAC,UAAU,EAAE,IAAI,EAAE,SAAS,CAAC,CAW7C;AAED;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,aAAa,GAAG,WAAW,GAAG,aAAa,GAAG,SAAS,CAAC;AAEpE;;;;;;;;;GASG;AACH,MAAM,MAAM,eAAe,GAAG,CAC5B,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,aAAa,KAClB,IAAI,CAAC;AAEV;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAuB,gBAAgB,CACrC,MAAM,EAAE,aAAa,CAAC,UAAU,CAAC,EACjC,MAAM,CAAC,EAAE,eAAe,GACvB,cAAc,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,UAAU,CAAA;CAAE,EAAE,IAAI,EAAE,SAAS,CAAC,CA6GrE"}

package/dist/_shared/tarball-stream.js

@@ -0,0 +1,235 @@
+/**
+ * tarball-stream.ts — pure streaming tar primitives.
+ *
+ * A leaf with no imports at all, deliberately: `bundle-facet-workers.mjs`
+ * esbuilds this file into a string constant the loader pool injects into
+ * dynamic workers, and a facet isolate resolves no specifier. Anything this
+ * file imported would have to travel with it.
+ *
+ * Zero dependencies. Works identically on the supervisor and inside a
+ * facet isolate. Never buffers the full decompressed tarball — peak
+ * transient heap is one file's bytes plus a 512-byte carry.
+ */
+/**
+ * Maximum size of a single file inside a tarball. Larger entries are skipped.
+ *
+ * History: 5 MB was too low — it silently dropped `esbuild-wasm/esbuild.wasm`
+ * (11.35 MB on v0.24.2), which made Nimbus-in-Nimbus `npm run dev` fail with
+ * `No such module "esbuild-wasm/esbuild.wasm"` since the missing file caused
+ * esbuild's VFS plugin to mark the import `external`, and workerd's LOADER
+ * has no entry for that specifier. 20 MB covers esbuild-wasm with headroom
+ * while keeping per-facet peak heap bounded for the streaming extractor.
+ */
+export const MAX_FILE_BYTES = 20_000_000;
+/**
+ * Read one tar header (USTAR) out of `block`. Returns parsed fields or
+ * `null` for an end-of-archive block (all zeros).
+ */
+/**
+ * Collapse "."/".." segments in a tar entry's package-relative path.
+ * Returns the canonical relative path, or '' when the entry escapes its
+ * package root (a leading ".." that pops above the root) — the caller
+ * treats '' as a no-name entry and skips it. Mirrors the segment logic in
+ * w7-frame's canonicalPath so joined write paths are always accepted.
+ */
+export function canonicalTarName(name) {
+    const out = [];
+    for (const seg of name.split('/')) {
+        if (seg === '..') {
+            if (out.length === 0)
+                return '';
+            out.pop();
+        }
+        else if (seg !== '' && seg !== '.') {
+            out.push(seg);
+        }
+    }
+    return out.join('/');
+}
+export function parseTarHeader(block) {
+    if (block[0] === 0)
+        return null;
+    let name = '';
+    for (let i = 0; i < 100 && block[i] !== 0; i++) {
+        name += String.fromCharCode(block[i]);
+    }
+    let prefix = '';
+    for (let i = 345; i < 500 && block[i] !== 0; i++) {
+        prefix += String.fromCharCode(block[i]);
+    }
+    if (prefix)
+        name = prefix + '/' + name;
+    // Strip the npm `package/` convention.
+    name = name.replace(/^package\//, '');
+    // Canonicalize the entry-relative path. npm tarballs legitimately carry
+    // entries like "./dist/index.js" (agent-base, http-proxy-agent,
+    // protobufjs, ...); left as-is the "./" survives into the VFS write path
+    // and the w7-frame writer rejects the noncanonical path, failing the
+    // whole shared install wave and dropping shard-mates' completion markers.
+    // Collapsing here (the one place entry names are assembled) keeps every
+    // downstream join canonical. An entry that escapes its package root via
+    // ".." is dropped to '' → skipped as a no-name entry.
+    name = canonicalTarName(name);
+    let sizeStr = '';
+    for (let i = 124; i < 136 && block[i] !== 0; i++) {
+        sizeStr += String.fromCharCode(block[i]);
+    }
+    const size = parseInt(sizeStr.trim(), 8) || 0;
+    const typeFlag = block[156];
+    return { name, size, typeFlag };
+}
+/**
+ * Wrap a `ReadableStream<Uint8Array>` as an async iterable. Workerd and
+ * Node both support `Symbol.asyncIterator` on ReadableStream, but we
+ * spell the reader loop out so we don't depend on ambient lib typings.
+ */
+export async function* readableStreamToAsyncIterable(rs) {
+    const reader = rs.getReader();
+    try {
+        while (true) {
+            const { value, done } = await reader.read();
+            if (done)
+                return;
+            if (value && value.length > 0)
+                yield value;
+        }
+    }
+    finally {
+        try {
+            reader.releaseLock();
+        }
+        catch { /* ignore */ }
+    }
+}
+/**
+ * Streaming tar extractor.
+ *
+ * Consumes an async iterable of Uint8Array chunks (the decompressed tar
+ * byte stream) and yields one `{ name, data }` entry per regular file,
+ * as each file completes.
+ *
+ * Memory invariant: holds at most one pending file's bytes (≤ MAX_FILE_BYTES)
+ * plus a small carry buffer for the tar header being assembled.
+ *
+ * Skips: symlinks, directories, hardlinks, long-name extensions (PaxHeader),
+ * and any file whose declared size exceeds MAX_FILE_BYTES.
+ *
+ * If `onSkip` is provided, it is invoked for each skipped entry with the
+ * name, declared size, and reason code. Callers that need to surface
+ * dropped-file warnings to users should pass one; legacy callers that
+ * omit the arg still behave exactly as before (silent skip).
+ */
+export async function* streamTarEntries(source, onSkip) {
+    let carry = new Uint8Array(0);
+    let state = { kind: 'header' };
+    function concat(a, b) {
+        if (a.length === 0)
+            return b;
+        if (b.length === 0)
+            return a;
+        const out = new Uint8Array(a.length + b.length);
+        out.set(a, 0);
+        out.set(b, a.length);
+        return out;
+    }
+    for await (const chunkRaw of source) {
+        let buf = concat(carry, chunkRaw);
+        let cursor = 0;
+        while (true) {
+            if (state.kind === 'header') {
+                if (buf.length - cursor < 512)
+                    break;
+                const header = buf.subarray(cursor, cursor + 512);
+                const parsed = parseTarHeader(header);
+                cursor += 512;
+                if (!parsed)
+                    return; // end-of-archive
+                const { name, size, typeFlag } = parsed;
+                const pad = size === 0 ? 0 : (512 - (size % 512)) % 512;
+                const isRegularFile = (typeFlag === 48 /* '0' */ || typeFlag === 0);
+                if (size === 0) {
+                    if (isRegularFile && name) {
+                        yield { name, data: new Uint8Array(0) };
+                    }
+                    state = { kind: 'header' };
+                    continue;
+                }
+                if (!isRegularFile || !name || size > MAX_FILE_BYTES) {
+                    if (onSkip) {
+                        // Classify before entering the skip state so the reason is
+                        // exact. Precedence matches the condition order above:
+                        // non-regular first (directories/symlinks/PaxHeaders are
+                        // skipped regardless of size), then no-name, then too-large.
+                        const reason = !isRegularFile
+                            ? 'non-regular'
+                            : !name
+                                ? 'no-name'
+                                : 'too-large';
+                        try {
+                            onSkip(name, size, reason);
+                        }
+                        catch { /* best-effort */ }
+                    }
+                    state = { kind: 'skip', remaining: size + pad };
+                    continue;
+                }
+                state = {
+                    kind: 'file',
+                    name,
+                    remaining: size,
+                    fileBuf: new Uint8Array(size),
+                    fileOffset: 0,
+                    pad,
+                    skip: false,
+                };
+                continue;
+            }
+            if (state.kind === 'file') {
+                const avail = buf.length - cursor;
+                if (avail === 0)
+                    break;
+                if (state.remaining > 0) {
+                    const take = Math.min(state.remaining, avail);
+                    state.fileBuf.set(buf.subarray(cursor, cursor + take), state.fileOffset);
+                    state.fileOffset += take;
+                    state.remaining -= take;
+                    cursor += take;
+                    if (state.remaining > 0)
+                        break;
+                }
+                if (state.pad > 0) {
+                    const avail2 = buf.length - cursor;
+                    if (avail2 === 0)
+                        break;
+                    const take = Math.min(state.pad, avail2);
+                    state.pad -= take;
+                    cursor += take;
+                    if (state.pad > 0)
+                        break;
+                }
+                yield { name: state.name, data: state.fileBuf };
+                state = { kind: 'header' };
+                continue;
+            }
+            // state.kind === 'skip'
+            const avail = buf.length - cursor;
+            if (avail === 0)
+                break;
+            const take = Math.min(state.remaining, avail);
+            cursor += take;
+            state.remaining -= take;
+            if (state.remaining > 0)
+                break;
+            state = { kind: 'header' };
+        }
+        if (cursor >= buf.length) {
+            carry = new Uint8Array(0);
+        }
+        else if (cursor === 0) {
+            carry = buf;
+        }
+        else {
+            carry = buf.slice(cursor);
+        }
+    }
+}

package/dist/_shared/tarball.d.ts

@@ -0,0 +1,17 @@
+/**
+ * tarball.ts — a whole tarball, in memory, as a path→bytes map.
+ *
+ * The streaming primitives it walks with (`parseTarHeader`, `streamTarEntries`,
+ * `readableStreamToAsyncIterable`) live in `./tarball-stream.ts` — a
+ * dependency-free leaf, because `bundle-facet-workers.mjs` esbuilds that file
+ * into a string the loader pool injects into dynamic workers, where an import
+ * would not resolve.
+ *
+ * This half is for a caller that already holds the bytes: `gem install`, which
+ * fetches a `.gem` (a tar holding a gzipped tar) and needs both layers open at
+ * once. An installer streaming a tarball it is still downloading should drive
+ * `streamTarEntries` itself and never hold the whole thing.
+ */
+/** Extract every regular file. Gzipped input is decompressed first. */
+export declare function extractTarball(tarball: ArrayBuffer): Promise<Map<string, Uint8Array>>;
+//# sourceMappingURL=tarball.d.ts.map

package/dist/_shared/tarball.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tarball.d.ts","sourceRoot":"","sources":["../../src/_shared/tarball.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAOH,uEAAuE;AACvE,wBAAsB,cAAc,CAClC,OAAO,EAAE,WAAW,GACnB,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC,CAsBlC"}

package/dist/_shared/tarball.js

@@ -0,0 +1,39 @@
+/**
+ * tarball.ts — a whole tarball, in memory, as a path→bytes map.
+ *
+ * The streaming primitives it walks with (`parseTarHeader`, `streamTarEntries`,
+ * `readableStreamToAsyncIterable`) live in `./tarball-stream.ts` — a
+ * dependency-free leaf, because `bundle-facet-workers.mjs` esbuilds that file
+ * into a string the loader pool injects into dynamic workers, where an import
+ * would not resolve.
+ *
+ * This half is for a caller that already holds the bytes: `gem install`, which
+ * fetches a `.gem` (a tar holding a gzipped tar) and needs both layers open at
+ * once. An installer streaming a tarball it is still downloading should drive
+ * `streamTarEntries` itself and never hold the whole thing.
+ */
+import { streamTarEntries, readableStreamToAsyncIterable, } from './tarball-stream.js';
+/** Extract every regular file. Gzipped input is decompressed first. */
+export async function extractTarball(tarball) {
+    const files = new Map();
+    const raw = new Uint8Array(tarball);
+    // Adapter: wrap the single buffer as an async iterable. If gzipped, pipe
+    // through DecompressionStream so the streaming parser still sees tar bytes.
+    let source;
+    if (raw[0] === 0x1f && raw[1] === 0x8b) {
+        const rs = new Blob([tarball]).stream().pipeThrough(new DecompressionStream('gzip'));
+        source = readableStreamToAsyncIterable(rs);
+    }
+    else {
+        source = (async function* () { yield raw; })();
+    }
+    try {
+        for await (const entry of streamTarEntries(source)) {
+            files.set(entry.name, entry.data);
+        }
+    }
+    catch {
+        return files;
+    }
+    return files;
+}

package/dist/runtime/clang-runner.d.ts

@@ -0,0 +1,38 @@
+/**
+ * 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 type { RuntimeManifest } from './runtime-manifest.js';
+import type { SqliteVFS } from '../vfs/sqlite-vfs.js';
+import type { Command } from '../substrate/lifo/commands/types.js';
+import type { FacetHost } from './facet-host.js';
+/** Build the runner factory. Closes over the facet host + vfs. */
+export declare function makeClangRunnerFactory(deps: {
+    facets: FacetHost;
+    vfs: SqliteVFS;
+}): (manifest: RuntimeManifest, installRoot: string, binName: string, binKind: string | undefined) => Command;
+export declare const CLANG_RUNNER_PREAMBLE: string;
+//# sourceMappingURL=clang-runner.d.ts.map

package/dist/runtime/clang-runner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"clang-runner.d.ts","sourceRoot":"","sources":["../../src/runtime/clang-runner.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAC7D,OAAO,KAAK,EAAmB,SAAS,EAAE,MAAM,sBAAsB,CAAC;AACvE,OAAO,KAAK,EAAE,OAAO,EAAkB,MAAM,qCAAqC,CAAC;AACnF,OAAO,KAAK,EAAS,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAQxD,kEAAkE;AAClE,wBAAgB,sBAAsB,CAAC,IAAI,EAAE;IAC3C,MAAM,EAAE,SAAS,CAAC;IAClB,GAAG,EAAE,SAAS,CAAC;CAChB,GAAG,CAAC,QAAQ,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,SAAS,KAC7F,OAAO,CAiTV;AA8jBD,eAAO,MAAM,qBAAqB,QAAiE,CAAC"}