@nimbus-sh/core 0.1.0 → 0.2.0

package/dist/runtime/cpython-runner.js

@@ -0,0 +1,425 @@
+/**
+ * cpython-runner.ts — `python` / `python3` / `pip`, on CPython 3.13 built for
+ * wasm32-wasi.
+ *
+ * This replaces the Pyodide runner, and the reason is not the interpreter: it
+ * is the filesystem. Pyodide is CPython built with Emscripten, so it brings its
+ * own MEMFS, and every invocation had to copy the session's files in and diff
+ * them back out through vfs-snapshot.ts. That made Python the last runtime with
+ * a private, parallel filesystem. This build talks to runtime/wasi/preamble.ts
+ * like clang, bash and ruby do — `open()` in Python is the same syscall as
+ * `open()` in C — so there is nothing to copy and nothing to diff.
+ *
+ * What follows from that:
+ *   - manifestVfs, not snapshotVfs: the facet is given sizes and modes and
+ *     demand-loads the handful of files the program actually opens.
+ *   - supervisorPid, not omitSupervisor: a pool without a supervisor can read
+ *     the seeded manifest and can never write anything back. It looks like it
+ *     works.
+ *   - No Python-level socket shim. CPython's _socket is real here, over
+ *     nimbus-net.c and the host's synthetic paths, so loopback is ordinary
+ *     socket code rather than a monkey-patch.
+ *
+ * The interpreter is a WASI reactor (see packages/worker/wasm/python), because
+ * a command module's _start runs once and that only covers `python script.py`.
+ *
+ * FOUR THINGS THIS RUNTIME REDISCOVERED THE HARD WAY, ALL OF WHICH ruby-runner
+ * ALREADY KNEW. Read the list rather than finding a fifth:
+ *   1. Every entry into the VM goes through WebAssembly.promising, not only the
+ *      calls known to park — a Suspending import traps on an unpromised stack
+ *      even when it returns a plain integer.
+ *   2. The supervisor is adopted AFTER __wasiInitFS, which clears it on purpose,
+ *      and the facet drains queued writes in a `finally`.
+ *   3. modes are seeded `{ '': 7, tmp: 7, home: 7 }` ahead of the manifest,
+ *      because manifestVfs's walk skips the empty root — without it the preopen
+ *      at '/' is mode 0 and every traversal under it is EACCES.
+ *   4. The loader pool is built per invocation, never cached: supervisorPid is
+ *      baked into the SUPERVISOR binding at construction, so a held pool hands
+ *      every later caller the first caller's write credential.
+ *
+ * One ordering in cpythonRunFacetFn is load-bearing and looks redundant: the
+ * supervisor stub is PUBLISHED on globalThis and only then adopted, because
+ * __wasiInitFS clears the adoption on purpose and the boot re-adopts it from
+ * there afterwards. Adopting once at the entry and deleting the Reflect.set
+ * leaves a guest that reads the seeded filesystem and silently writes nowhere —
+ * every write queued, none landed, no error anywhere. Ruby carries the same
+ * pair for the same reason. The drain in the `finally` is the other half: a
+ * program that wrote a file and then raised still wrote the file.
+ */
+import { resolveVfsPath } from '../vfs/path.js';
+import { hasLeadingCliFlag } from './cli-flags.js';
+import { CPYTHON_PREAMBLE_TAIL } from './cpython-preamble.js';
+import { PYTHON_SERVER_ADAPTER } from './python-server-adapter.js';
+import { requireVfsCred } from './os-contracts.js';
+import { buildPipInvocation, PYTHON_SITE_PACKAGES_ROOT, sessionUsesSciVariant, } from './python-pip.js';
+import { VIRTUAL_SOCKET_KERNEL_SRC } from './virtual-socket-kernel.generated.js';
+import { WASI_INSTANCE_PREAMBLE_SRC } from './wasi-instance.js';
+const PYTHON_VERSION_FLAGS = new Set(['--version', '-V']);
+const PYTHON_HELP_FLAGS = new Set(['--help', '-h']);
+/** Where `nimbus install python` stages the interpreter inside the session. */
+const CPYTHON_WASM_REL = 'share/cpython/python.wasm';
+/**
+ * The same interpreter with numpy and markupsafe's C speedups linked in, and
+ * their Python half. wasm32-wasi has no dlopen, so a compiled package is either
+ * in the binary or unavailable; EXTENSIONS.md has why that beat a runtime
+ * linker. Chosen per invocation from what the session has installed, so a
+ * session that installed none of it pays none of the 7.8 MiB.
+ */
+const CPYTHON_SCI_WASM_REL = 'share/cpython/python-sci.wasm';
+const CPYTHON_SCI_PACKAGES_REL = 'lib/sci-packages.zip';
+const CPYTHON_STDLIB_REL = 'lib/python313.zip';
+const CPYTHON_CACERT_REL = 'etc/ssl/cert.pem';
+/**
+ * The one canonical facet preamble. Composed in exactly one place: a
+ * hand-rolled second copy is how ruby-repl once drifted into booting a VM whose
+ * language prelude was missing.
+ */
+export function buildCPythonPreamble() {
+    return [
+        VIRTUAL_SOCKET_KERNEL_SRC,
+        WASI_INSTANCE_PREAMBLE_SRC,
+        CPYTHON_PREAMBLE_TAIL,
+    ].join('\n');
+}
+/**
+ * Python's CLI, as far as a sandbox needs it. Flags that only affect an
+ * interactive tty or bytecode caching are accepted and ignored; anything else
+ * is refused by name rather than silently doing something different.
+ */
+function parsePythonArgv(argv) {
+    const fail = (error) => ({ mode: 'inline', inlineCode: '', scriptPath: '', scriptArgs: [], exitCode: 2, error });
+    let i = 0;
+    while (i < argv.length) {
+        const a = argv[i];
+        if (a === '-c') {
+            const code = argv[i + 1];
+            if (code === undefined)
+                return fail('Argument expected for the -c option');
+            return { mode: 'inline', inlineCode: code, scriptPath: '', scriptArgs: argv.slice(i + 2), exitCode: 0 };
+        }
+        if (a === '-m') {
+            const mod = argv[i + 1];
+            if (mod === undefined)
+                return fail('Argument expected for the -m option');
+            const rest = argv.slice(i + 2);
+            const inlineCode = [
+                'import runpy, sys',
+                `sys.argv = ${JSON.stringify([mod, ...rest])}`,
+                `runpy.run_module(${JSON.stringify(mod)}, run_name='__main__', alter_sys=True)`,
+            ].join('\n');
+            return { mode: 'inline', inlineCode, scriptPath: '', scriptArgs: rest, exitCode: 0 };
+        }
+        if (a === '-') {
+            return { mode: 'stdin', inlineCode: '', scriptPath: '-', scriptArgs: argv.slice(i + 1), exitCode: 0 };
+        }
+        if (!a.startsWith('-')) {
+            return { mode: 'script', inlineCode: '', scriptPath: a, scriptArgs: argv.slice(i + 1), exitCode: 0 };
+        }
+        if (/^-[OBuEItcsx]+$/.test(a)) {
+            i++;
+            continue;
+        }
+        return fail(`unknown option: ${a}`);
+    }
+    // No mode argument. init.ts routes a bare `python` to the REPL before it gets
+    // here, so reaching this point means flags without a program.
+    return fail("no program given. Use 'python -c \"code\"', 'python -m <module>' or 'python script.py'.");
+}
+/**
+ * Whether this invocation should get a resident process rather than a one-shot.
+ * A script or `-m` can bind a port and keep serving; pip never does.
+ */
+function shouldRunAsResidentProcess(argv, parsed, pipMode) {
+    if (pipMode)
+        return false;
+    if (parsed.mode === 'script')
+        return true;
+    if (argv[0] === '-m' && argv[1] && argv[1] !== 'pip')
+        return true;
+    return false;
+}
+/** `python -m pip ...` is pip, reached the long way round. */
+async function buildPythonModulePipInvocation(argv, cwd, vfs, runtimeContext) {
+    if (argv[0] !== '-m' || argv[1] !== 'pip')
+        return { mode: 'none', code: '', exitCode: 0 };
+    return await buildPipInvocation(argv.slice(2), 'pip', cwd, vfs, runtimeContext);
+}
+function toArrayBuffer(bytes) {
+    return bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength);
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+/**
+ * Facet-side entry. Serialized with fn.toString(), so it captures nothing and
+ * names no import: everything it needs is on globalThis, put there by the
+ * preamble.
+ */
+async function cpythonRunFacetFn(args, facetEnv) {
+    const run = Reflect.get(globalThis, '__cpythonRun');
+    if (typeof run !== 'function') {
+        return {
+            stdout: '', stderr: '', exitCode: 127,
+            error: 'cpython preamble missing: __cpythonRun not in scope',
+        };
+    }
+    const adopt = Reflect.get(globalThis, '__wasiAdoptSupervisor');
+    const drain = Reflect.get(globalThis, '__wasiDrainPersist');
+    const supervisor = facetEnv && facetEnv.SUPERVISOR;
+    // Published where the boot re-adopts it after the mount: adopting only here
+    // would be undone by __wasiInitFS, which clears it on purpose.
+    if (supervisor)
+        Reflect.set(globalThis, '__nimbusPySupervisor', supervisor);
+    adopt?.(supervisor);
+    try {
+        return await run(args);
+    }
+    finally {
+        // In `finally`, not on the success path: a program that wrote a file and
+        // then raised still wrote the file, and those bytes are the user's.
+        await drain?.();
+    }
+}
+export function makeCPythonRunnerFactory(deps) {
+    return function cpythonRunnerFactory(manifest, installRoot, binName, _binKind) {
+        const findFile = (rel) => {
+            const entry = manifest.files.find((f) => f.path === rel);
+            return entry ? `${installRoot}/${entry.path}` : null;
+        };
+        const baseWasmVfs = findFile(CPYTHON_WASM_REL);
+        const sciWasmVfs = findFile(CPYTHON_SCI_WASM_REL);
+        const sciPackagesVfs = findFile(CPYTHON_SCI_PACKAGES_REL);
+        const stdlibVfs = findFile(CPYTHON_STDLIB_REL);
+        let seedCache = null;
+        return async function cpythonBinHandler(ctx) {
+            const cred = requireVfsCred(ctx.cred, binName);
+            const credKey = `${cred.uid}:${cred.gid}:${cred.groups.join(',')}`;
+            const vfs = deps.vfs.as(cred);
+            const argv = ctx.args || [];
+            const cwd = ctx.cwd || '/home/user';
+            const pipRuntimeContext = {
+                // No Pyodide lockfile: there is no curated wheel index behind this
+                // interpreter, so pip resolves against PyPI like anywhere else.
+                pyodideLockfileText: null,
+                runtimeArtifacts: manifest.runtime_artifacts || [],
+            };
+            const isPipBin = _binKind === 'pip' || binName === 'pip' || binName === 'pip3';
+            const pipInvocation = isPipBin
+                ? await buildPipInvocation(argv, binName, cwd, vfs, pipRuntimeContext)
+                : await buildPythonModulePipInvocation(argv, cwd, vfs, pipRuntimeContext);
+            if (pipInvocation.error) {
+                ctx.stderr.write(`${binName}: ${pipInvocation.error}\n`);
+                return pipInvocation.exitCode;
+            }
+            if (pipInvocation.mode !== 'pip' && hasLeadingCliFlag(argv, PYTHON_VERSION_FLAGS)) {
+                ctx.stdout.write('Python 3.13.14 (CPython, wasm32-wasi, Nimbus runtime)\n');
+                return 0;
+            }
+            if (pipInvocation.mode !== 'pip' && hasLeadingCliFlag(argv, PYTHON_HELP_FLAGS)) {
+                ctx.stdout.write(`usage: ${binName} [option] ... [-c cmd | -m mod | file | -] [arg] ...\n`);
+                ctx.stdout.write('Nimbus CPython 3.13 runtime (wasm32-wasi).\n');
+                ctx.stdout.write('Supported: -c <code>, -m <module>, <file.py>, stdin via -, and the session filesystem directly.\n');
+                ctx.stdout.write('zlib, lzma, bz2, hashlib, ssl, sqlite3 and sockets are built in; pure-Python wheels install with pip.\n');
+                return 0;
+            }
+            // Which interpreter this invocation gets. The sci variant is chosen from
+            // what the session has installed, never from a guess about what this
+            // program will import — the whole point of keying on state is that it is
+            // also right for `python -c` naming a module in a variable. Falling back
+            // when the variant is absent keeps a session installed before the variant
+            // shipped working, on the base interpreter, rather than failing to start.
+            const wantsSci = sessionUsesSciVariant(vfs)
+                && sciWasmVfs !== null && vfs.exists(sciWasmVfs);
+            const wasmVfs = wantsSci ? sciWasmVfs : baseWasmVfs;
+            const sciPackagesPath = wantsSci && sciPackagesVfs && vfs.exists(sciPackagesVfs)
+                ? sciPackagesVfs
+                : null;
+            if (!wasmVfs || !vfs.exists(wasmVfs)) {
+                ctx.stderr.write(`${binName}: python.wasm missing (re-run 'nimbus install python')\n`);
+                return 127;
+            }
+            if (!stdlibVfs || !vfs.exists(stdlibVfs)) {
+                ctx.stderr.write(`${binName}: python313.zip missing (re-run 'nimbus install python')\n`);
+                return 127;
+            }
+            const parsed = pipInvocation.mode === 'pip'
+                ? { mode: 'inline', inlineCode: pipInvocation.code, scriptPath: '', scriptArgs: [], exitCode: 0 }
+                : parsePythonArgv(argv);
+            if (parsed.error) {
+                ctx.stderr.write(`${binName}: ${parsed.error}\n`);
+                return parsed.exitCode;
+            }
+            let userCode = '';
+            let progName = binName;
+            let pyArgv = [binName];
+            if (parsed.mode === 'inline') {
+                userCode = parsed.inlineCode;
+                pyArgv = ['-c', ...parsed.scriptArgs];
+            }
+            else if (parsed.mode === 'script') {
+                const absPath = resolveVfsPath(parsed.scriptPath, cwd);
+                try {
+                    if (!vfs.exists(absPath)) {
+                        ctx.stderr.write(`${binName}: can't open file '${parsed.scriptPath}': [Errno 2] No such file or directory\n`);
+                        return 2;
+                    }
+                    userCode = new TextDecoder('utf-8').decode(vfs.readFile(absPath));
+                }
+                catch (e) {
+                    ctx.stderr.write(`${binName}: ${parsed.scriptPath}: ${errorMessage(e)}\n`);
+                    return 1;
+                }
+                progName = parsed.scriptPath;
+                pyArgv = [parsed.scriptPath, ...parsed.scriptArgs];
+            }
+            else {
+                const stdinReader = ctx.stdin;
+                userCode = (stdinReader && typeof stdinReader.read === 'function' ? await stdinReader.read() : '') ?? '';
+                pyArgv = ['-', ...parsed.scriptArgs];
+            }
+            // sys.argv is set from Python rather than from WASI argv: the reactor has
+            // no argv of its own, and this keeps the one place that decides what the
+            // program sees in TypeScript.
+            const prelude = [
+                PYTHON_SERVER_ADAPTER,
+                'import sys',
+                `sys.argv = ${JSON.stringify(pyArgv)}`,
+                // The variant's own packages. zipimport reads them straight out of the
+                // session filesystem, so they need no unpacking and no manifest entry
+                // beyond the archive itself.
+                ...(sciPackagesPath
+                    ? [`sys.path.insert(0, ${JSON.stringify(`/${sciPackagesPath.replace(/^\/+/, '')}`)})`]
+                    : []),
+                `sys.path.insert(0, ${JSON.stringify(`/${PYTHON_SITE_PACKAGES_ROOT}`)})`,
+                `sys.path.insert(0, ${JSON.stringify(cwd)})`,
+                // WASI has no process cwd, so wasi-libc starts every guest at '/'.
+                // Leaving it there silently reroutes every relative path a program
+                // opens — the shell says the user is in /home/user and Python resolves
+                // against the root.
+                'import os',
+                'try:',
+                `    os.chdir(${JSON.stringify(cwd)})`,
+                'except OSError:',
+                '    pass',
+            ].join('\n');
+            const cacertVfs = findFile(CPYTHON_CACERT_REL);
+            const userEnv = { ...(ctx.env || {}) };
+            if (!userEnv.HOME)
+                userEnv.HOME = '/home/user';
+            if (!userEnv.PYTHONUNBUFFERED)
+                userEnv.PYTHONUNBUFFERED = '1';
+            // Without this OpenSSL has no trust anchors at all — there is no
+            // /etc/ssl on a Nimbus session — and every HTTPS request fails
+            // verification with a message about a missing local issuer rather than
+            // about a missing bundle.
+            if (!userEnv.SSL_CERT_FILE && cacertVfs)
+                userEnv.SSL_CERT_FILE = `/${cacertVfs.replace(/^\/+/, '')}`;
+            // A manifest, not a copy: sizes and modes only, with the facet demand-
+            // loading whatever the program opens. The stdlib zip is covered by it
+            // like any other file, which is the whole point of not having a private
+            // filesystem any more.
+            const stdlibDir = stdlibVfs.replace(/\/[^/]+$/, '');
+            // Every runtime file the interpreter is told about has to be a root of
+            // its own. The trust store was reachable only while the cwd happened to
+            // be an ancestor of the install — from ~ the walk swept the whole runtime
+            // tree in — so `cd` into any subdirectory and SSL_CERT_FILE pointed at a
+            // path the facet could not see, and every pip install failed
+            // CERTIFICATE_VERIFY_FAILED with the bundle sitting right there.
+            const cacertDir = cacertVfs ? cacertVfs.replace(/\/[^/]+$/, '') : null;
+            const revision = Math.max(vfs.revision(cwd), vfs.revision(PYTHON_SITE_PACKAGES_ROOT), vfs.revision(stdlibVfs));
+            let fsSeed = seedCache && seedCache.cred === credKey
+                && seedCache.cwd === cwd && seedCache.revision === revision
+                ? seedCache.result
+                : null;
+            if (!fsSeed) {
+                // The host decides what "seed" means: a manifest the facet demand-loads
+                // against, or the bytes themselves. Which one it is follows from
+                // whether the host can park a guest mid-syscall, and nothing here
+                // depends on the answer.
+                fsSeed = deps.facets.seedFilesystem(vfs, cwd, {
+                    extraRoots: [PYTHON_SITE_PACKAGES_ROOT, stdlibDir, ...(cacertDir ? [cacertDir] : [])],
+                    revision,
+                });
+                seedCache = { cred: credKey, cwd, revision, result: fsSeed };
+            }
+            if ('error' in fsSeed) {
+                ctx.stderr.write(`${binName}: ${fsSeed.error}\n`);
+                return 1;
+            }
+            const snapshot = fsSeed.snapshot;
+            // Opened per invocation, not cached: the supervisor capability is bound
+            // to this process's pid when the facet opens, so one held across calls
+            // would hand every later caller the first caller's write credential.
+            const facet = deps.facets.open({
+                // The variant is in the tag because a host's constructor-time wasm
+                // fingerprint is name:length:first-byte:last-byte, not a content hash.
+                // Two variants differ by megabytes so they would not collide today, but
+                // a warm slot serving the wrong interpreter is not a failure worth
+                // leaving to a size coincidence.
+                tag: wantsSci ? 'cpython-runner:sci' : 'cpython-runner',
+                concurrency: 1,
+                // Never absent. Without the capability the facet reads its seed and can
+                // never write anything back — the program appears to run and its output
+                // never reaches the session.
+                syscalls: { vfs, pid: ctx.pid },
+                preamble: buildCPythonPreamble(),
+                wasmModules: { 'python.wasm': toArrayBuffer(vfs.readFile(wasmVfs)) },
+            });
+            const facetArgs = {
+                userCode: `${prelude}\n${userCode}`,
+                pyArgv,
+                userEnv,
+                progName,
+                cwd,
+                pythonHome: `/${installRoot.replace(/^\/+/, '')}`,
+                supervisorPid: ctx.pid,
+                fsSnapshot: snapshot,
+            };
+            // A script or `-m` can bind a port and keep serving, and such a program
+            // is not finished when it stops producing output — it is finished when it
+            // stops running. Pyodide gave those a dedicated socket process; that
+            // spawn is not ported yet, so for now they get a one-shot facet with a
+            // budget long enough not to cut a server off mid-request. Porting the
+            // resident process is the last piece, and until it lands a server holds
+            // its facet rather than being driven by inbound requests.
+            const resident = shouldRunAsResidentProcess(argv, parsed, pipInvocation.mode === 'pip');
+            if (resident) {
+                facet.dispose();
+                if (!deps.startResident) {
+                    ctx.stderr.write(`${binName}: this program keeps running after it starts, and this host has no `
+                        + 'process substrate to keep it on\n');
+                    return 1;
+                }
+                const command = [binName, ...argv].map((part) => (/^[A-Za-z0-9_./:=@+-]+$/.test(part) ? part : JSON.stringify(part))).join(' ');
+                const spawnResult = await deps.startResident({ wasmVfsPath: wasmVfs, startArgs: facetArgs, cwd, command });
+                if (spawnResult.stdout)
+                    ctx.stdout.write(spawnResult.stdout);
+                if (spawnResult.stderr)
+                    ctx.stderr.write(spawnResult.stderr);
+                return spawnResult.exitCode;
+            }
+            let result;
+            try {
+                result = await facet.submit(cpythonRunFacetFn, facetArgs, {
+                    timeoutMs: 120_000,
+                });
+            }
+            catch (e) {
+                ctx.stderr.write(`${binName}: ${errorMessage(e)}\n`);
+                return 1;
+            }
+            finally {
+                facet.dispose();
+            }
+            if (result.stdout)
+                ctx.stdout.write(result.stdout);
+            if (result.stderr)
+                ctx.stderr.write(result.stderr);
+            if (result.error) {
+                ctx.stderr.write(`${binName}: ${result.error}\n`);
+                return result.exitCode || 1;
+            }
+            return result.exitCode;
+        };
+    };
+}

package/dist/runtime/facet-host.d.ts

@@ -0,0 +1,159 @@
+/**
+ * facet-host.ts — where a program carrying compiled WebAssembly actually runs.
+ *
+ * Every WASM runtime Nimbus ships (bash, CPython, Ruby, clang, the generic
+ * `wasm-runner`) has the same shape: a self-contained scheduler shipped as
+ * SOURCE, a table of wasm modules that must be compiled before the scheduler
+ * can reach them, and a function submitted into that scope with plain data and
+ * back. Only the substrate underneath differs.
+ *
+ * On workerd that substrate is a dynamic worker: request-time
+ * `WebAssembly.instantiate(bytes)` is refused by CSP, so the bytes ride inside
+ * the loader's modules map and are compiled during the inner worker's
+ * module-load phase — the one phase where wasm code generation is permitted.
+ * Off workerd there is no such rule and the same scope is built in place
+ * ({@link ./local-facet-host.ts}).
+ *
+ * NOT named after either. `Facet` is what Nimbus has always called this — one
+ * program, its own module scope, its own wasm table — and the port is the
+ * whole of what a runtime needs from it, so a runner cannot tell which
+ * substrate answered and never asks.
+ */
+import type { CredentialedVfs } from '../vfs/sqlite-vfs.js';
+import type { WasiFsSnapshot } from './wasi-instance.js';
+import type { WasiParking } from './wasi/types.js';
+/**
+ * A function submitted into a facet.
+ *
+ * It is SERIALIZED on any host that runs it elsewhere, so it must be
+ * self-contained: closure references do not survive the crossing, and neither
+ * do module imports. Names the spec's `preamble` declares ARE in scope — that
+ * is what the preamble is for — and everything else travels as `args`.
+ *
+ * `bindings` carries whatever capabilities the host minted for this facet;
+ * `SUPERVISOR` is the session syscall capability, present only when the spec
+ * named a pid to act as.
+ */
+export type FacetFn<A, R> = (args: A, bindings: FacetBindings) => R | Promise<R>;
+/** Capabilities handed to the facet's function as its second argument. */
+export interface FacetBindings {
+    /** The session's syscall capability, bound to {@link FacetSpec.supervisorPid}. */
+    readonly SUPERVISOR?: unknown;
+}
+export interface FacetSpec {
+    /** Names the facet in diagnostics and in the host's own reuse key. */
+    tag: string;
+    /**
+     * Source evaluated once, before any function is submitted, in the scope those
+     * functions are evaluated in. This is how a runtime's scheduler and its WASI
+     * layer get there: they are far too large to travel per call, and they hold
+     * the state a session needs between calls (bash's process tree, CPython's
+     * `__main__`).
+     */
+    preamble?: string;
+    /**
+     * Wasm images the facet's scope exposes as compiled `WebAssembly.Module`s on
+     * `globalThis.__NIMBUS_WASM[<key>]`. Compiled by the host, because on workerd
+     * the caller is not allowed to.
+     */
+    wasmModules?: Record<string, ArrayBuffer>;
+    /**
+     * The session filesystem this facet's syscalls act on, and the process they
+     * act as. Absent for a facet that makes no syscall back into the session.
+     *
+     * Both halves, because the two hosts reach the same authority differently: a
+     * dynamic worker is a different isolate, so it is handed a capability minted
+     * for the PID and routed back to the session; a facet in the caller's own
+     * isolate is handed the credentialed VIEW. Naming only the pid would leave
+     * the second host nothing to serve from, and naming only the view would
+     * leave the first nothing to mint.
+     *
+     * Not a boolean: the supervisor derives the WRITE credential from the pid,
+     * so a facet given the capability without one can read the filesystem it was
+     * seeded with and silently write nowhere.
+     */
+    syscalls?: FacetSyscalls;
+    /** Facets the host may keep warm for this spec. Default 1. */
+    concurrency?: number;
+}
+/** The session a facet's syscalls reach, and who they reach it as. */
+export interface FacetSyscalls {
+    readonly vfs: CredentialedVfs;
+    readonly pid: number;
+}
+/**
+ * A seeded WASI filesystem: what {@link FacetHost.seedFilesystem} produced, and
+ * how much of the session it had to carry to produce it.
+ */
+export interface FacetFilesystemSeed {
+    snapshot: WasiFsSnapshot;
+    files: number;
+    bytes: number;
+}
+/** What a runner knows about the subtree its guest should see. */
+export interface FacetFilesystemOptions {
+    /** Directories outside `root` the program must also reach. */
+    extraRoots?: Iterable<string>;
+    /**
+     * The session revision the seed describes, when the caller has computed one.
+     * A host that serves reads back stamps it, which is what marks the seed a
+     * CACHE rather than the whole world; one that cannot has no use for it.
+     */
+    revision?: number;
+}
+export interface FacetSubmitOptions {
+    /**
+     * Deadline for this call, honoured by hosts that can abandon a facet.
+     *
+     * A host sharing the caller's thread cannot: a wasm guest in a synchronous
+     * loop holds the only thread there is, and nothing observes a timer until it
+     * yields. Such a host says so ({@link ./local-facet-host.ts}) rather than
+     * racing a timer and returning while the guest runs on.
+     */
+    timeoutMs?: number;
+    /** Wasm images for this call alone, merged over {@link FacetSpec.wasmModules}. */
+    wasmModules?: Record<string, ArrayBuffer>;
+}
+/**
+ * One facet's scope, for as long as a runtime needs it.
+ *
+ * Held rather than per-call because the scope IS the session: bash boots on the
+ * first submit and is fed on every one after, and a scope rebuilt between them
+ * would hand the second call a shell that had never run.
+ */
+export interface Facet {
+    submit<A, R>(fn: FacetFn<A, R>, args: A, options?: FacetSubmitOptions): Promise<Awaited<R>>;
+    /** Idempotent. The scope and everything it holds are dropped. */
+    dispose(): void;
+}
+export interface FacetHost {
+    /**
+     * Whether a guest in this host can be SUSPENDED in the middle of a syscall.
+     *
+     * The one place the substrates are not interchangeable, so it is stated
+     * rather than smoothed over — the same posture as `ProcessImageDelivery` in
+     * the process fabric. Everything else about running a wasm program is the
+     * same code either way; this is not, and it decides two things at once:
+     * which import table the guest gets ({@link WasiParking}), and how much
+     * filesystem it must be handed before it starts.
+     *
+     * `jspi` — the host can park the guest on a promise, so a syscall may go
+     *   back to the session mid-instruction and the seed can be a manifest.
+     * `none` — it cannot; V8 traps any call into a suspending import off a
+     *   stack `WebAssembly.promising` did not enter. Every syscall must answer
+     *   synchronously, so the seed has to BE the filesystem.
+     */
+    readonly parking: WasiParking;
+    /**
+     * Hand a facet the part of the session filesystem its program needs.
+     *
+     * The host decides the strategy, because the strategy IS the consequence of
+     * {@link FacetHost.parking} and nothing about the program bears on it. A
+     * runner names the roots and gets a seed; it never learns which kind it got.
+     */
+    seedFilesystem(vfs: CredentialedVfs, root: string, options?: FacetFilesystemOptions): FacetFilesystemSeed | {
+        error: string;
+    };
+    open(spec: FacetSpec): Facet;
+}
+//# sourceMappingURL=facet-host.d.ts.map

package/dist/runtime/facet-host.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"facet-host.d.ts","sourceRoot":"","sources":["../../src/runtime/facet-host.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAC5D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACzD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAEnD;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,OAAO,CAAC,CAAC,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,EAAE,QAAQ,EAAE,aAAa,KAAK,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;AAEjF,0EAA0E;AAC1E,MAAM,WAAW,aAAa;IAC5B,kFAAkF;IAClF,QAAQ,CAAC,UAAU,CAAC,EAAE,OAAO,CAAC;CAC/B;AAED,MAAM,WAAW,SAAS;IACxB,sEAAsE;IACtE,GAAG,EAAE,MAAM,CAAC;IACZ;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;IAC1C;;;;;;;;;;;;;;OAcG;IACH,QAAQ,CAAC,EAAE,aAAa,CAAC;IACzB,8DAA8D;IAC9D,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,sEAAsE;AACtE,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,GAAG,EAAE,eAAe,CAAC;IAC9B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;CACtB;AAED;;;GAGG;AACH,MAAM,WAAW,mBAAmB;IAClC,QAAQ,EAAE,cAAc,CAAC;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;CACf;AAED,kEAAkE;AAClE,MAAM,WAAW,sBAAsB;IACrC,8DAA8D;IAC9D,UAAU,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IAC9B;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,kBAAkB;IACjC;;;;;;;OAOG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,kFAAkF;IAClF,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;CAC3C;AAED;;;;;;GAMG;AACH,MAAM,WAAW,KAAK;IACpB,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,OAAO,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,OAAO,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC;IAC5F,iEAAiE;IACjE,OAAO,IAAI,IAAI,CAAC;CACjB;AAED,MAAM,WAAW,SAAS;IACxB;;;;;;;;;;;;;;;OAeG;IACH,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC;IAC9B;;;;;;OAMG;IACH,cAAc,CACZ,GAAG,EAAE,eAAe,EACpB,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE,sBAAsB,GAC/B,mBAAmB,GAAG;QAAE,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;IAC3C,IAAI,CAAC,IAAI,EAAE,SAAS,GAAG,KAAK,CAAC;CAC9B"}

package/dist/runtime/facet-host.js

@@ -0,0 +1,22 @@
+/**
+ * facet-host.ts — where a program carrying compiled WebAssembly actually runs.
+ *
+ * Every WASM runtime Nimbus ships (bash, CPython, Ruby, clang, the generic
+ * `wasm-runner`) has the same shape: a self-contained scheduler shipped as
+ * SOURCE, a table of wasm modules that must be compiled before the scheduler
+ * can reach them, and a function submitted into that scope with plain data and
+ * back. Only the substrate underneath differs.
+ *
+ * On workerd that substrate is a dynamic worker: request-time
+ * `WebAssembly.instantiate(bytes)` is refused by CSP, so the bytes ride inside
+ * the loader's modules map and are compiled during the inner worker's
+ * module-load phase — the one phase where wasm code generation is permitted.
+ * Off workerd there is no such rule and the same scope is built in place
+ * ({@link ./local-facet-host.ts}).
+ *
+ * NOT named after either. `Facet` is what Nimbus has always called this — one
+ * program, its own module scope, its own wasm table — and the port is the
+ * whole of what a runtime needs from it, so a runner cannot tell which
+ * substrate answered and never asks.
+ */
+export {};