@nimbus-sh/core 0.1.0 → 0.2.0

package/dist/runtime/runtime-registry.js

@@ -0,0 +1,363 @@
+/**
+ * runtime-registry.ts — shared shell-command factory for runtime
+ * dispatchers (node, bun, and future native-WASM / Python / Ruby /
+ * AssemblyScript runtimes).
+ *
+ * Why this exists
+ * ───────────────
+ * `node` and `bun` shell-command handlers in src/session/init.ts
+ * shared ~85% of their code: argv parsing for --version / --help /
+ * -e / script-path, VFS lookup, shebang strip, esbuild transform for
+ * .ts/.tsx/.jsx, dispatch to the runner. The duplication had drifted
+ * — only `node` had the primitive #1 nodeFlagSpan fix
+ * (init.ts:233-243), only `node` had primitive-#2 binSpawn ctx
+ * propagation (init.ts:391-403), only `bun` had install / run
+ * subcommand routing.
+ *
+ * `buildRuntimeHandler` returns a single shell-handler function that
+ * encodes the shared contract. Per-runtime variation is supplied
+ * via the `RuntimeSpec` parameter:
+ *
+ *   - name + version + helpText
+ *   - run(): runner fn (runFresh / runBunScript / wasm-runner)
+ *   - subcommands: optional map of `<verb> → handler` for
+ *     bun-style `bun install`, `bun run` (node has none today)
+ *   - transform(): optional code rewriter (bun prepends BUN_SHIM_PREAMBLE)
+ *   - supportsBinSpawn: true for node (the .bin handler propagates
+ *     a callerPid); other runtimes use a plain spawn flow.
+ *
+ * Anti-requirements observed
+ * ──────────────────────────
+ *   - NO setTimeout / NO retry / NO defensive-catch added.
+ *   - NO behavioral change vs the pre-refactor handlers — every
+ *     runtime-specific quirk is preserved exactly.
+ *   - Per-runtime test parity: existing runtime-primitives probes
+ *     (#1 npx / #2 .bin) and runtime-pkg probes (G1-G4) MUST still
+ *     pass against the refactored handlers — the contract is
+ *     observable behaviour, not implementation shape.
+ */
+import { normalizeVfsPath, resolveVfsPath, vfsPathExtension } from '../vfs/path.js';
+import { CRED_KERNEL } from './os-contracts.js';
+import { parseFacetBundleProfile } from './bundle-profile.js';
+import { bindImportMetaResolve, importMetaDefines } from './import-meta-transform.js';
+/** Extensions probed when a target names no exact file, in Node's order. */
+const SCRIPT_RESOLUTION_CANDIDATES = ['.js', '.ts', '.tsx', '.mjs', '.jsx', '/index.js', '/index.ts'];
+/**
+ * Resolve a runtime target — `./cli.ts`, `sub/x`, `.`, or a bare name — to a
+ * canonical VFS key, or null when nothing runnable sits there.
+ *
+ * A directory never resolves to itself: it falls through to the index
+ * candidates, so `bun ./tools` finds `tools/index.js` the way real bun does
+ * rather than trying to read the directory as source.
+ */
+export function resolveRuntimeScriptPath(fs, cwd, target, opts) {
+    const base = normalizeVfsPath(cwd || '/home/user');
+    let resolved;
+    if (target === '.' || target === './') {
+        // `node .` / `bun .` — the package's declared entry point.
+        let main = 'index.js';
+        try {
+            const pkg = JSON.parse(fs.readFileString(`${base}/package.json`));
+            main = (opts?.preferModuleField ? pkg.module : undefined) || pkg.main || 'index.js';
+        }
+        catch { /* no readable package.json — index.js */ }
+        resolved = resolveVfsPath(main, base);
+    }
+    else {
+        resolved = resolveVfsPath(target, base);
+    }
+    if (fs.isFile(resolved))
+        return resolved;
+    for (const candidate of SCRIPT_RESOLUTION_CANDIDATES) {
+        if (fs.isFile(resolved + candidate))
+            return resolved + candidate;
+    }
+    return null;
+}
+/**
+ * Build a shell-handler function for a runtime. The returned function
+ * is the value passed to `registry.register('<name>', handler)`.
+ *
+ * Captures `vfs`, `getEsbuild` (for lazy init) + the spec. The same factory is used for every runtime; the only
+ * runtime-specific code lives in `spec`.
+ */
+export function buildRuntimeHandler(spec, ctx0) {
+    const { vfs, getEsbuild, registry } = ctx0;
+    const fs = vfs.as(CRED_KERNEL);
+    /**
+     * The standard invocation: flag span, --version/--help/-e, then the
+     * script-path flow. Subcommand verbs are NOT considered here — the
+     * caller has already consumed them — so a verb handler can delegate
+     * back in with a rewritten argv without re-triggering itself.
+     */
+    async function runtimeInvocation(ctx, args) {
+        const name = spec.name;
+        const nimbusCtx = ctx;
+        // A facet-hosted runtime streams its output to the session terminal over
+        // the supervisor RPC and hands the shell an empty string. That is live and
+        // cheap, and it is only correct while the process's stdout IS the terminal:
+        // the stream bypasses the shell's stdout chain, so the moment fd 1 or fd 2
+        // is a file, a pipe, a command substitution, or the capture sink of a
+        // programmatic exec, the bytes have to come back in the result and be
+        // written through ctx.stdout instead. A context with no fd table of its own
+        // — the child_process broker synthesizes one — says so directly.
+        const captureOutput = !!nimbusCtx.__nimbusCaptureOutput
+            || ctx.isFdTerminal?.(1) === false
+            || ctx.isFdTerminal?.(2) === false;
+        const bundleProfile = parseFacetBundleProfile(nimbusCtx.__nimbusBundleProfile);
+        // ── Flag-span computation (primitive #1) ──
+        //
+        // Real-Node only treats args UP TO the first non-flag token as
+        // CLI flags. Pre-refactor, version/help/eval scanned the entire
+        // args array, breaking `node /path/to/tsc --version` (the user's
+        // --version was misinterpreted as a node flag).
+        let flagSpan = 0;
+        while (flagSpan < args.length && args[flagSpan].startsWith('-')) {
+            flagSpan++;
+            const prev = args[flagSpan - 1];
+            // -e / --eval consumes one value; advance past it.
+            if ((prev === '-e' || prev === '--eval') && flagSpan < args.length) {
+                flagSpan++;
+            }
+        }
+        const flagSlice = args.slice(0, flagSpan);
+        // ── --version ──
+        if (flagSlice.includes('-v') || flagSlice.includes('--version')) {
+            ctx.stdout.write(spec.version + '\n');
+            return 0;
+        }
+        // ── --help ──
+        if (flagSlice.includes('--help') || flagSlice.includes('-h')) {
+            ctx.stdout.write(spec.helpText);
+            if (!spec.helpText.endsWith('\n'))
+                ctx.stdout.write('\n');
+            return 0;
+        }
+        // ── -e / --eval ──
+        const evalIdx = flagSlice.indexOf('-e') !== -1
+            ? flagSlice.indexOf('-e')
+            : flagSlice.indexOf('--eval');
+        if (evalIdx !== -1) {
+            const code = args[evalIdx + 1];
+            if (!code) {
+                ctx.stderr.write(`${name}: -e requires an argument\n`);
+                return 1;
+            }
+            const result = await spec.run(code, {
+                cred: ctx.cred,
+                argv: args.slice(evalIdx + 2),
+                env: ctx.env,
+                cwd: ctx.cwd,
+                filename: '<eval>',
+                dirname: ctx.cwd || '/home/user',
+                command: `${name} -e ...`,
+                ...(captureOutput ? { captureOutput: true } : {}),
+                ...(bundleProfile ? { bundleProfile } : {}),
+            });
+            if (result.stdout)
+                ctx.stdout.write(result.stdout);
+            if (result.stderr)
+                ctx.stderr.write(result.stderr);
+            return result.exitCode;
+        }
+        // ── script path (or .wasm path for bypassesScriptRead) ──
+        const scriptIdx = flagSpan;
+        const scriptPath = args[scriptIdx];
+        if (!scriptPath) {
+            ctx.stderr.write(`${name}: REPL not supported. Use ${name} -e "code" or ${name} script.js\n`);
+            return 1;
+        }
+        // ── bypassesScriptRead branch (wasm-runner) ──
+        //
+        // The runner takes the path AS-IS (it's a .wasm, not JS source).
+        // We don't read or transform here; the runner reads the bytes
+        // and instantiates them. `.` resolution and extension probing are
+        // meaningless for a .wasm target and stay out of this branch.
+        if (spec.bypassesScriptRead) {
+            const filename = '/' + resolveVfsPath(scriptPath, ctx.cwd || '/home/user');
+            const dirname = filename.includes('/')
+                ? filename.substring(0, filename.lastIndexOf('/'))
+                : '/';
+            // `args.slice(scriptIdx + 1)` are the runner's user args (e.g.
+            // [exportName, intArg1, intArg2, ...] for wasm-runner).
+            const result = await spec.run('', {
+                cred: ctx.cred,
+                argv: args.slice(scriptIdx + 1),
+                env: ctx.env,
+                cwd: ctx.cwd,
+                filename,
+                dirname,
+                command: `${name} ${args.slice(0, scriptIdx + 1).join(' ')}`,
+                ...(captureOutput ? { captureOutput: true } : {}),
+                ...(bundleProfile ? { bundleProfile } : {}),
+            });
+            if (result.stdout)
+                ctx.stdout.write(result.stdout);
+            if (result.stderr)
+                ctx.stderr.write(result.stderr);
+            return result.exitCode;
+        }
+        // Resolve against cwd: `.` → the package entry, then extension probing.
+        const resolvedPath = resolveRuntimeScriptPath(fs, ctx.cwd || '/home/user', scriptPath, {
+            // bun prefers .module over .main when both exist; node uses .main.
+            preferModuleField: name === 'bun',
+        });
+        let code = null;
+        if (resolvedPath !== null) {
+            try {
+                code = fs.readFileString(resolvedPath);
+            }
+            catch { /* unreadable — reported below */ }
+        }
+        if (resolvedPath === null || code === null) {
+            ctx.stderr.write(`${name}: cannot find module '${scriptPath}'\n`);
+            return 1;
+        }
+        // Shebang strip (primitive #1).
+        if (code.startsWith('#!')) {
+            const nl = code.indexOf('\n');
+            code = nl >= 0 ? code.substring(nl + 1) : '';
+        }
+        // ── ESM-source detection (primitive: type:module entry scripts) ──
+        //
+        // Nimbus's facet pre-compile loop wraps every entry script in
+        // `new Function(...)` which runs it as CJS. A real `node script.js`
+        // dispatch honours the nearest package.json's `"type"` field
+        // (and the file extension) to decide whether to parse as ESM:
+        //
+        //   - .mjs          → always ESM
+        //   - .cjs          → always CJS
+        //   - .js           → ESM iff nearest package.json has "type": "module"
+        //   - no extension  → same rule as .js. Node allows an extensionless
+        //                     main entry and resolves its format from the
+        //                     package type, and that is the shape of nearly
+        //                     every npm `bin` script (typescript's `bin/tsc`,
+        //                     and the `node_modules/.bin/<cli>` target the bin
+        //                     dispatcher hands us).
+        //
+        // Without this, every modern ESM-only npm initialiser
+        // (create-vite, create-astro, create-svelte, modern create-*)
+        // crashes immediately with "Cannot use import statement outside
+        // a module" because their bin entry is `index.js` and the
+        // package.json declares `type: module`.
+        //
+        // We transform to CJS (format: 'cjs') so the facet's `new
+        // Function()` runs it as a CJS module body — same path that the
+        // bundle's `transformEsmInBundle` (W3.5 Fix B) takes for
+        // sub-module ESM files. esbuild's CJS output emits __require /
+        // module.exports / exports.X so the facet's pre-compile loop
+        // sees ordinary CJS source.
+        function nearestPackageTypeIsModule(absPath) {
+            // Walk up dirs looking for the nearest package.json. First one
+            // wins (Node spec); we do NOT consult ancestors past it.
+            let dir = absPath.replace(/^\/+/, '');
+            const slash = dir.lastIndexOf('/');
+            dir = slash > 0 ? dir.substring(0, slash) : '';
+            const visited = new Set();
+            while (dir && !visited.has(dir)) {
+                visited.add(dir);
+                const pj = dir + '/package.json';
+                if (fs.exists(pj)) {
+                    try {
+                        const pkg = JSON.parse(fs.readFileString(pj));
+                        return pkg && pkg.type === 'module';
+                    }
+                    catch {
+                        return false;
+                    }
+                }
+                const last = dir.lastIndexOf('/');
+                if (last <= 0)
+                    break;
+                dir = dir.substring(0, last);
+            }
+            return false;
+        }
+        const scriptExt = vfsPathExtension(resolvedPath);
+        const needsEsmTransform = scriptExt === '.mjs' ||
+            ((scriptExt === '.js' || scriptExt === '') && nearestPackageTypeIsModule(resolvedPath));
+        // esbuild transform for TypeScript / TSX / JSX (both node and bun)
+        // AND for ESM entry scripts (primitive ESM-detect).
+        if (scriptExt === '.ts' ||
+            scriptExt === '.tsx' ||
+            scriptExt === '.jsx' ||
+            needsEsmTransform) {
+            try {
+                const eb = getEsbuild();
+                const loader = scriptExt === '.tsx' ? 'tsx' :
+                    scriptExt === '.jsx' ? 'jsx' :
+                        scriptExt === '.ts' ? 'ts' :
+                            'js';
+                // Substitute `import.meta.url` at compile-time so esbuild's
+                // CJS output doesn't reduce it to `undefined` (its default
+                // for unknown import.meta references). The substitution
+                // value is a real `file://<absolute-path>` URL — exactly
+                // what real Node returns when running this script. Tools
+                // that compute `fileURLToPath(import.meta.url)` (create-vite,
+                // most modern CLIs) then resolve relative paths against
+                // the actual script location.
+                //
+                // Without this, `create-vite` does
+                //   r(import.meta.url) → fileURLToPath(undefined) → throws
+                //   → falls into a different code path
+                //   → readdirSync(wrong-template-dir) returns []
+                //   → "Scaffolding..." but writes no files.
+                const absUrl = 'file:///' + resolvedPath.replace(/^\/+/, '');
+                const transformed = await eb.transform(code, {
+                    loader,
+                    format: 'cjs',
+                    define: importMetaDefines(absUrl),
+                });
+                code = bindImportMetaResolve(transformed.code, absUrl);
+            }
+            catch (e) {
+                ctx.stderr.write(`${name}: transform error for ${scriptPath}: ${e?.message}\n`);
+                return 1;
+            }
+        }
+        const filename = '/' + resolvedPath;
+        const dirname = filename.includes('/')
+            ? filename.substring(0, filename.lastIndexOf('/'))
+            : '/';
+        // Primitive #1 / G4 — propagate bin-spawn ctx if the runtime
+        // supports it (currently node only).
+        const binSpawn = spec.supportsBinSpawn ? nimbusCtx.__nimbusBinSpawn : undefined;
+        const leadingFlags = args.slice(0, scriptIdx);
+        const result = await spec.run(code, {
+            cred: ctx.cred,
+            argv: [...leadingFlags, filename, ...args.slice(scriptIdx + 1)],
+            env: ctx.env,
+            cwd: ctx.cwd,
+            filename,
+            dirname,
+            command: binSpawn?.command || `${name} ${args.slice(0, scriptIdx + 1).join(' ')}`,
+            ...(binSpawn ? {
+                skipSpawn: true,
+                callerPid: binSpawn.callerPid,
+                forceLongRunning: binSpawn.forceLongRunning === true,
+                attachedTty: binSpawn.attachedTty === true,
+            } : {}),
+            ...(captureOutput ? { captureOutput: true } : {}),
+            ...(bundleProfile ? { bundleProfile } : {}),
+        });
+        if (result.stdout)
+            ctx.stdout.write(result.stdout);
+        if (result.stderr)
+            ctx.stderr.write(result.stderr);
+        return result.exitCode;
+    }
+    return async function runtimeHandler(ctx) {
+        const args = ctx.args || [];
+        // ── Subcommand dispatch ──
+        //
+        // BEFORE flag-span computation: subcommands like `bun install`
+        // have their first positional arg as the verb, NOT a node-style
+        // flag. A verb owns the whole invocation, but it may hand a
+        // rewritten argv back to the standard flow — that is how
+        // `bun run <file>` reaches the same execution path as `bun <file>`.
+        if (spec.subcommands && args.length > 0 && spec.subcommands[args[0]]) {
+            return spec.subcommands[args[0]](ctx, registry, (rewritten) => runtimeInvocation(ctx, rewritten));
+        }
+        return runtimeInvocation(ctx, args);
+    };
+}

package/dist/runtime/vfs-snapshot.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"vfs-snapshot.d.ts","sourceRoot":"","sources":["../../src/runtime/vfs-snapshot.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACzD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AAGjD;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,6CAA6C;IAC7C,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACrC,sBAAsB;IACtB,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,2BAA2B;IAC3B,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,0CAA0C;IAC1C,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACtC;;;;;OAKG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC1C;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IAC/B,UAAU,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;CAC/B;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,cAAc,CAAC;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;CACf;AAED,wBAAgB,UAAU,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAIpD;AAED,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,CAKlD;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CACzB,GAAG,EAAE,OAAO,EACZ,OAAO,EAAE,MAAM,EACf,IAAI,GAAE,eAAoB,GACzB,iBAAiB,GAAG;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,CA6HvC;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAC1B,GAAG,EAAE,OAAO,EACZ,IAAI,EAAE,UAAU,GACf;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CA2DxG"}
+{"version":3,"file":"vfs-snapshot.d.ts","sourceRoot":"","sources":["../../src/runtime/vfs-snapshot.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACzD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AAGjD;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,6CAA6C;IAC7C,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACrC,sBAAsB;IACtB,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,2BAA2B;IAC3B,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,0CAA0C;IAC1C,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACtC;;;;;OAKG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC1C;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IAC/B,UAAU,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;CAC/B;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,cAAc,CAAC;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;CACf;AAED,wBAAgB,UAAU,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAIpD;AAED,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,CAKlD;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CACzB,GAAG,EAAE,OAAO,EACZ,OAAO,EAAE,MAAM,EACf,IAAI,GAAE,eAAoB,GACzB,iBAAiB,GAAG;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,CA2IvC;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAC1B,GAAG,EAAE,OAAO,EACZ,IAAI,EAAE,UAAU,GACf;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CA2DxG"}

package/dist/runtime/vfs-snapshot.js

@@ -144,7 +144,21 @@ export function snapshotVfs(vfs, vfsRoot, caps = {}) {
         return { error: `runtime filesystem snapshot incomplete: ${failures.join('; ')}` };
     }
     return {
-        snapshot: { root, roots, preopens: [], files, dirs: Array.from(dirsSet).sort(), modes },
+        snapshot: {
+            root,
+            roots,
+            preopens: [],
+            files,
+            dirs: Array.from(dirsSet).sort(),
+            modes,
+            // Only when the walk hid nothing. The walk either finishes or returns an
+            // error above, so a snapshot taken with no skip list HAS listed each root
+            // exhaustively — which is what lets a guest treat a path it does not find
+            // as absent instead of asking for it. With the default skip list it has
+            // not, and claiming otherwise would make node_modules invisible rather
+            // than merely unseeded.
+            ...(skipSubdirs.size === 0 ? { enumeratedRoots: roots } : {}),
+        },
         bytes: totalBytes,
         files: fileCount,
     };

package/dist/runtime/vfs-supervisor.d.ts

@@ -0,0 +1,22 @@
+/**
+ * vfs-supervisor.ts — the session's syscall capability, served in place.
+ *
+ * The WASI layer treats its seed as a CACHE over the session filesystem and
+ * reaches the real thing through a {@link WasiSupervisorStub}. In a Durable
+ * Object that stub is an RPC handle minted for a pid, because the facet is a
+ * different isolate; in the caller's own isolate the filesystem is right here
+ * and the credential is already on the view.
+ *
+ * The methods are `async` because the shim's contract is, not because anything
+ * here waits. That is what makes this usable on a host with no JSPI: every
+ * mutation is queued and drained OUTSIDE the guest (`__wasiDrainPersist`, which
+ * a runner awaits after the program returns), so a promise there costs nothing.
+ * A READ is different — its promise would have to suspend the guest mid-syscall
+ * — which is why a host without parking must seed the filesystem completely and
+ * never reach the read paths at all. See FacetHost.parking.
+ */
+import type { CredentialedVfs } from '../vfs/sqlite-vfs.js';
+import type { WasiSupervisorStub } from './wasi/types.js';
+/** Serve the WASI syscall surface directly from `vfs`, as its own credential. */
+export declare function vfsSupervisor(vfs: CredentialedVfs): WasiSupervisorStub;
+//# sourceMappingURL=vfs-supervisor.d.ts.map

package/dist/runtime/vfs-supervisor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vfs-supervisor.d.ts","sourceRoot":"","sources":["../../src/runtime/vfs-supervisor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAC5D,OAAO,KAAK,EAAkB,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAE1E,iFAAiF;AACjF,wBAAgB,aAAa,CAAC,GAAG,EAAE,eAAe,GAAG,kBAAkB,CA4CtE"}

package/dist/runtime/vfs-supervisor.js

@@ -0,0 +1,65 @@
+/**
+ * vfs-supervisor.ts — the session's syscall capability, served in place.
+ *
+ * The WASI layer treats its seed as a CACHE over the session filesystem and
+ * reaches the real thing through a {@link WasiSupervisorStub}. In a Durable
+ * Object that stub is an RPC handle minted for a pid, because the facet is a
+ * different isolate; in the caller's own isolate the filesystem is right here
+ * and the credential is already on the view.
+ *
+ * The methods are `async` because the shim's contract is, not because anything
+ * here waits. That is what makes this usable on a host with no JSPI: every
+ * mutation is queued and drained OUTSIDE the guest (`__wasiDrainPersist`, which
+ * a runner awaits after the program returns), so a promise there costs nothing.
+ * A READ is different — its promise would have to suspend the guest mid-syscall
+ * — which is why a host without parking must seed the filesystem completely and
+ * never reach the read paths at all. See FacetHost.parking.
+ */
+/** Serve the WASI syscall surface directly from `vfs`, as its own credential. */
+export function vfsSupervisor(vfs) {
+    const key = (path) => path.replace(/^\/+/, '');
+    return {
+        async fsReadRange(vfsPath, offset, length) {
+            return vfs.readRange(key(vfsPath), offset, length);
+        },
+        async fsRevision(root) {
+            return vfs.revision(key(root));
+        },
+        async stat(vfsPath) {
+            const path = key(vfsPath);
+            if (!vfs.exists(path))
+                return null;
+            const stat = vfs.lstat(path);
+            return {
+                type: stat.type === 'directory' ? 'directory' : stat.type === 'symlink' ? 'symlink' : 'file',
+                size: stat.size,
+                mtime: stat.mtime,
+            };
+        },
+        async writeFile(vfsPath, bytes) {
+            const path = key(vfsPath);
+            const parent = path.includes('/') ? path.slice(0, path.lastIndexOf('/')) : '';
+            if (parent && !vfs.exists(parent))
+                vfs.mkdir(parent, { recursive: true });
+            vfs.writeFile(path, bytes);
+        },
+        async unlink(vfsPath) {
+            vfs.unlink(key(vfsPath));
+        },
+        async mkdir(vfsPath) {
+            vfs.mkdir(key(vfsPath), { recursive: true });
+        },
+        async rmdir(vfsPath) {
+            vfs.rmdir(key(vfsPath));
+        },
+        async rename(from, to) {
+            vfs.rename(key(from), key(to));
+        },
+        async symlink(target, vfsPath) {
+            vfs.symlink(target, key(vfsPath));
+        },
+        async utimes(vfsPath, atimeMs, mtimeMs) {
+            vfs.utimes(key(vfsPath), atimeMs, mtimeMs);
+        },
+    };
+}

package/dist/runtime/virtual-socket-kernel.generated.d.ts

@@ -0,0 +1,14 @@
+/**
+ * virtual-socket-kernel.generated.ts — AUTO-GENERATED. DO NOT EDIT.
+ *
+ * Produced by scripts/bundle-facet-workers.mjs from:
+ *   - @nimbus-sh/core src/runtime/virtual-socket-kernel.ts
+ *
+ * Self-contained IIFE that installs globalThis.__nimbusVirtualSockets.
+ * Consumed by python-runner.ts and ruby-runner.ts: spliced into the
+ * socket process worker module source passed to NimbusLoaderPool.
+ *
+ * Size: 33.72 KiB
+ */
+export declare const VIRTUAL_SOCKET_KERNEL_SRC: string;
+//# sourceMappingURL=virtual-socket-kernel.generated.d.ts.map

package/dist/runtime/virtual-socket-kernel.generated.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"virtual-socket-kernel.generated.d.ts","sourceRoot":"","sources":["../../src/runtime/virtual-socket-kernel.generated.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,eAAO,MAAM,yBAAyB,EAAE,MAAu5lC,CAAC"}

package/dist/runtime/virtual-socket-kernel.generated.js

@@ -0,0 +1,13 @@
+/**
+ * virtual-socket-kernel.generated.ts — AUTO-GENERATED. DO NOT EDIT.
+ *
+ * Produced by scripts/bundle-facet-workers.mjs from:
+ *   - @nimbus-sh/core src/runtime/virtual-socket-kernel.ts
+ *
+ * Self-contained IIFE that installs globalThis.__nimbusVirtualSockets.
+ * Consumed by python-runner.ts and ruby-runner.ts: spliced into the
+ * socket process worker module source passed to NimbusLoaderPool.
+ *
+ * Size: 33.72 KiB
+ */
+export const VIRTUAL_SOCKET_KERNEL_SRC = "(() => {\n  // ../core/src/runtime/virtual-socket-kernel.ts\n  var DEFAULT_LIMITS = {\n    responseTimeoutMs: 3e4,\n    maxRequestBodyBytes: 32 * 1024 * 1024,\n    maxResponseBufferBytes: 64 * 1024 * 1024\n  };\n  var EMPTY_BYTES = new Uint8Array(0);\n  var Deferred = class {\n    promise;\n    resolve;\n    reject;\n    constructor() {\n      let resolve = () => {\n      };\n      let reject = () => {\n      };\n      this.promise = new Promise((res, rej) => {\n        resolve = res;\n        reject = rej;\n      });\n      this.resolve = resolve;\n      this.reject = reject;\n    }\n  };\n  function isPyodideProxyLike(value) {\n    return value !== null && typeof value === \"object\" && typeof value.toJs === \"function\";\n  }\n  function toBytes(value) {\n    if (value instanceof Uint8Array) return value;\n    if (value instanceof ArrayBuffer) return new Uint8Array(value);\n    if (ArrayBuffer.isView(value)) return new Uint8Array(value.buffer, value.byteOffset, value.byteLength);\n    if (Array.isArray(value)) return Uint8Array.from(value);\n    if (typeof value === \"string\") return new TextEncoder().encode(value);\n    if (isPyodideProxyLike(value)) return toBytes(value.toJs());\n    return EMPTY_BYTES;\n  }\n  function concatBytes(parts) {\n    let length = 0;\n    for (const part of parts) length += part.byteLength;\n    const out = new Uint8Array(length);\n    let offset = 0;\n    for (const part of parts) {\n      out.set(part, offset);\n      offset += part.byteLength;\n    }\n    return out;\n  }\n  function responseCanHaveBody(requestMethod, status) {\n    if (requestMethod.toUpperCase() === \"HEAD\") return false;\n    return status !== 204 && status !== 205 && status !== 304;\n  }\n  function encodeHttpRequest(request, body) {\n    const url = new URL(request.url);\n    const path = (url.pathname || \"/\") + url.search;\n    const headers = new Headers(request.headers);\n    if (!headers.has(\"Host\")) headers.set(\"Host\", url.host || \"nimbus.local\");\n    if (body.byteLength > 0 && !headers.has(\"Content-Length\")) {\n      headers.set(\"Content-Length\", String(body.byteLength));\n    }\n    const lines = [`${request.method} ${path} HTTP/1.1`];\n    headers.forEach((value, key) => lines.push(`${key}: ${value}`));\n    lines.push(\"\", \"\");\n    return concatBytes([new TextEncoder().encode(lines.join(\"\\r\\n\")), body]);\n  }\n  function encodeHttpResponseHead(status, statusText, headers, chunkedBody) {\n    const lines = [`HTTP/1.1 ${status} ${statusText}`];\n    headers.forEach((value, key) => lines.push(`${key}: ${value}`));\n    if (chunkedBody) lines.push(\"Transfer-Encoding: chunked\");\n    lines.push(\"Connection: close\");\n    lines.push(\"\", \"\");\n    return new TextEncoder().encode(lines.join(\"\\r\\n\"));\n  }\n  function encodeChunkedFrame(bytes) {\n    return concatBytes([\n      new TextEncoder().encode(`${bytes.byteLength.toString(16)}\\r\n`),\n      bytes,\n      new TextEncoder().encode(\"\\r\\n\")\n    ]);\n  }\n  var CHUNKED_TERMINATOR = new TextEncoder().encode(\"0\\r\\n\\r\\n\");\n  var LOOPBACK_READ_HIGH_WATER_BYTES = 1024 * 1024;\n  var LOOPBACK_STREAM_CHUNK_BYTES = 64 * 1024;\n  var ByteChunkQueue = class {\n    constructor(limitTotalBytes, overflowLabel) {\n      this.limitTotalBytes = limitTotalBytes;\n      this.overflowLabel = overflowLabel;\n    }\n    limitTotalBytes;\n    overflowLabel;\n    chunks = [];\n    headOffset = 0;\n    enqueuedTotalBytes = 0;\n    undrainedBytes = 0;\n    /** Bytes enqueued but not yet read. Drives flow control on streamed queues. */\n    get pendingBytes() {\n      return this.undrainedBytes;\n    }\n    enqueue(bytes) {\n      if (bytes.byteLength === 0) return;\n      if (this.enqueuedTotalBytes + bytes.byteLength > this.limitTotalBytes) {\n        throw new Error(\n          `Nimbus virtual socket: ${this.overflowLabel} exceeds ${this.limitTotalBytes} bytes`\n        );\n      }\n      this.enqueuedTotalBytes += bytes.byteLength;\n      this.undrainedBytes += bytes.byteLength;\n      this.chunks.push(bytes);\n    }\n    /** Drain up to maxBytes from the head chunk; empty result means no data is queued. */\n    readUpTo(maxBytes) {\n      const head = this.chunks[0];\n      if (!head) return EMPTY_BYTES;\n      const available = head.byteLength - this.headOffset;\n      const take = Math.min(available, Math.max(1, maxBytes));\n      const out = head.subarray(this.headOffset, this.headOffset + take);\n      this.headOffset += take;\n      this.undrainedBytes -= take;\n      if (this.headOffset >= head.byteLength) {\n        this.chunks.shift();\n        this.headOffset = 0;\n      }\n      return out;\n    }\n  };\n  var HttpMessageParser = class {\n    phase = \"headers\";\n    settled = null;\n    headerBuffer = EMPTY_BYTES;\n    headerScanOffset = 0;\n    headerPairs = [];\n    framing = \"none\";\n    expectedBodyBytes = 0;\n    bodyChunks = [];\n    bodyByteCount = 0;\n    chunkState = \"size\";\n    chunkSizeLine = [];\n    chunkDataRemaining = 0;\n    get outcome() {\n      return this.settled;\n    }\n    feed(chunk) {\n      if (this.phase === \"done\" || chunk.byteLength === 0) return;\n      if (this.phase === \"headers\") {\n        this.feedHeaders(chunk);\n        return;\n      }\n      this.feedBody(chunk);\n    }\n    /** EOF from the peer closing the connection (or the request being torn down). */\n    finish() {\n      if (this.phase === \"done\") return;\n      if (this.phase === \"headers\") {\n        this.fail(`connection closed before ${this.messageLabel} headers`);\n        return;\n      }\n      if (this.framing === \"until-close\") {\n        this.completeWithBody(concatBytes(this.bodyChunks));\n        return;\n      }\n      this.fail(`connection closed before the ${this.messageLabel} completed`);\n    }\n    feedHeaders(chunk) {\n      this.headerBuffer = concatBytes([this.headerBuffer, chunk]);\n      const headerEnd = this.findHeaderEnd();\n      if (headerEnd < 0) {\n        this.headerScanOffset = Math.max(0, this.headerBuffer.byteLength - 3);\n        return;\n      }\n      const parsed = this.parseHeaderBlock(this.headerBuffer.subarray(0, headerEnd));\n      const leftover = this.headerBuffer.subarray(headerEnd);\n      this.headerBuffer = EMPTY_BYTES;\n      if (!parsed) return;\n      if (!this.bodyAllowed()) {\n        this.completeWithBody(null);\n        return;\n      }\n      const transferEncoding = this.headerValue(\"Transfer-Encoding\");\n      if (transferEncoding !== null && /chunked/i.test(transferEncoding)) {\n        this.framing = \"chunked\";\n      } else {\n        const contentLength = this.headerValue(\"Content-Length\");\n        const expected = contentLength === null ? Number.NaN : parseInt(contentLength, 10);\n        if (Number.isFinite(expected) && expected >= 0) {\n          this.framing = \"content-length\";\n          this.expectedBodyBytes = expected;\n          if (expected === 0) {\n            this.completeWithBody(EMPTY_BYTES);\n            return;\n          }\n        } else {\n          this.framing = this.defaultFramingWhenUnframed();\n          if (this.framing === \"none\") {\n            this.completeWithBody(null);\n            return;\n          }\n        }\n      }\n      this.phase = \"body\";\n      this.feedBody(leftover);\n    }\n    feedBody(chunk) {\n      if (this.framing === \"chunked\") {\n        this.feedChunkedBody(chunk);\n        return;\n      }\n      if (chunk.byteLength === 0) return;\n      if (this.framing === \"content-length\") {\n        const needed = this.expectedBodyBytes - this.bodyByteCount;\n        this.appendBody(chunk.subarray(0, Math.min(needed, chunk.byteLength)));\n        if (this.bodyByteCount >= this.expectedBodyBytes) {\n          this.completeWithBody(concatBytes(this.bodyChunks));\n        }\n        return;\n      }\n      this.appendBody(chunk);\n    }\n    feedChunkedBody(chunk) {\n      let i = 0;\n      while (i < chunk.byteLength && this.phase === \"body\") {\n        if (this.chunkState === \"size\") {\n          const byte = chunk[i++];\n          if (byte === 10) {\n            const line = new TextDecoder().decode(Uint8Array.from(this.chunkSizeLine)).trim();\n            this.chunkSizeLine.length = 0;\n            const size = parseInt(line.split(\";\", 1)[0], 16);\n            if (!Number.isFinite(size) || size < 0) {\n              this.fail(\"malformed chunked transfer encoding\");\n              return;\n            }\n            if (size === 0) {\n              this.completeWithBody(concatBytes(this.bodyChunks));\n              return;\n            }\n            this.chunkState = \"data\";\n            this.chunkDataRemaining = size;\n          } else if (byte !== 13) {\n            this.chunkSizeLine.push(byte);\n          }\n        } else if (this.chunkState === \"data\") {\n          const take = Math.min(this.chunkDataRemaining, chunk.byteLength - i);\n          this.appendBody(chunk.subarray(i, i + take));\n          i += take;\n          this.chunkDataRemaining -= take;\n          if (this.chunkDataRemaining === 0) this.chunkState = \"data-end\";\n        } else {\n          const byte = chunk[i++];\n          if (byte === 10) {\n            this.chunkState = \"size\";\n          } else if (byte !== 13) {\n            this.fail(\"malformed chunked transfer encoding\");\n            return;\n          }\n        }\n      }\n    }\n    appendBody(bytes) {\n      if (bytes.byteLength === 0) return;\n      this.bodyChunks.push(bytes);\n      this.bodyByteCount += bytes.byteLength;\n    }\n    findHeaderEnd() {\n      const bytes = this.headerBuffer;\n      for (let i = this.headerScanOffset; i + 3 < bytes.byteLength; i++) {\n        if (bytes[i] === 13 && bytes[i + 1] === 10 && bytes[i + 2] === 13 && bytes[i + 3] === 10) {\n          return i + 4;\n        }\n      }\n      return -1;\n    }\n    /** Returns false when the start line is malformed (the parser has already failed). */\n    parseHeaderBlock(headerBytes) {\n      const headerText = new TextDecoder().decode(headerBytes);\n      const lines = headerText.replace(/\\r\\n/g, \"\\n\").split(\"\\n\").filter((line) => line.length > 0);\n      const startLine = lines.shift() ?? \"\";\n      if (!this.parseStartLine(startLine)) return false;\n      for (const line of lines) {\n        const separator = line.indexOf(\":\");\n        if (separator <= 0) continue;\n        this.headerPairs.push([line.slice(0, separator), line.slice(separator + 1).trimStart()]);\n      }\n      return true;\n    }\n    headerValue(name) {\n      const target = name.toLowerCase();\n      for (const [key, value] of this.headerPairs) {\n        if (key.toLowerCase() === target) return value;\n      }\n      return null;\n    }\n    completeWithBody(body) {\n      this.phase = \"done\";\n      this.settled = { kind: \"message\", message: this.buildMessage(body) };\n    }\n    fail(message) {\n      this.phase = \"done\";\n      this.settled = { kind: \"failed\", message };\n    }\n  };\n  var HttpResponseParser = class extends HttpMessageParser {\n    constructor(requestMethod) {\n      super();\n      this.requestMethod = requestMethod;\n    }\n    requestMethod;\n    status = 200;\n    statusText = \"\";\n    get messageLabel() {\n      return \"response\";\n    }\n    parseStartLine(line) {\n      const match = /^HTTP\\/\\d(?:\\.\\d)?\\s+(\\d{3})(?:\\s+(.*))?$/.exec(line || \"HTTP/1.1 200 OK\");\n      this.status = match ? parseInt(match[1], 10) : 200;\n      this.statusText = match?.[2] ?? \"\";\n      return true;\n    }\n    bodyAllowed() {\n      return responseCanHaveBody(this.requestMethod, this.status);\n    }\n    defaultFramingWhenUnframed() {\n      return \"until-close\";\n    }\n    buildMessage(body) {\n      return { status: this.status, statusText: this.statusText, headerPairs: this.headerPairs, body };\n    }\n  };\n  var HttpRequestParser = class extends HttpMessageParser {\n    method = \"GET\";\n    target = \"/\";\n    get messageLabel() {\n      return \"request\";\n    }\n    parseStartLine(line) {\n      const match = /^([A-Za-z]+)\\s+(\\S+)\\s+HTTP\\/\\d(?:\\.\\d)?$/.exec(line);\n      if (!match) {\n        this.fail(`malformed HTTP request line: ${JSON.stringify(line.slice(0, 120))}`);\n        return false;\n      }\n      this.method = match[1].toUpperCase();\n      this.target = match[2];\n      return true;\n    }\n    bodyAllowed() {\n      return true;\n    }\n    defaultFramingWhenUnframed() {\n      return \"none\";\n    }\n    buildMessage(body) {\n      return { method: this.method, target: this.target, headerPairs: this.headerPairs, body };\n    }\n  };\n  function errorResponse(status, message) {\n    return {\n      status,\n      statusText: \"\",\n      headerPairs: [[\"content-type\", \"text/plain; charset=utf-8\"]],\n      body: new TextEncoder().encode(`Nimbus virtual socket: ${message}`)\n    };\n  }\n  function toResponse(settled) {\n    const headers = new Headers();\n    for (const [key, value] of settled.headerPairs) headers.append(key, value);\n    return new Response(settled.body, {\n      status: settled.status,\n      statusText: settled.statusText,\n      headers\n    });\n  }\n  var VirtualConnection = class {\n    constructor(id, requestMethod, requestBytes, limits) {\n      this.id = id;\n      this.inbound = new ByteChunkQueue(requestBytes.byteLength, \"request buffer\");\n      this.inbound.enqueue(requestBytes);\n      this.outbound = new ByteChunkQueue(limits.maxResponseBufferBytes, \"response buffer\");\n      this.parser = new HttpResponseParser(requestMethod);\n    }\n    id;\n    /** Request bytes the guest server reads; filled in one shot in stage 1. */\n    inbound;\n    /** Response bytes the guest server writes; drained into the parser. */\n    outbound;\n    parser;\n    responseReady = new Deferred();\n    settled = false;\n    closed = false;\n    read(maxBytes) {\n      return Array.from(this.inbound.readUpTo(Math.max(1, maxBytes | 0)));\n    }\n    /** The whole request is buffered before the connection is accepted, so nothing is ever awaited. */\n    readAsync(maxBytes) {\n      return Promise.resolve(this.read(maxBytes));\n    }\n    readBytesAsync(maxBytes) {\n      return Promise.resolve(this.inbound.readUpTo(Math.max(1, maxBytes | 0)));\n    }\n    /** Same reason: an empty read on an accepted connection is always genuine EOF. */\n    atEof() {\n      return true;\n    }\n    write(bytesLike) {\n      const bytes = toBytes(bytesLike);\n      if (bytes.byteLength === 0 || this.settled || this.closed) return bytes.byteLength;\n      this.outbound.enqueue(bytes.slice());\n      this.pumpParser();\n      return bytes.byteLength;\n    }\n    /** EOF from the server side (or request teardown); completes until-close bodies. */\n    close() {\n      if (this.closed) return;\n      this.closed = true;\n      if (this.settled) return;\n      this.parser.finish();\n      this.pumpParser();\n    }\n    /** Abort propagation: settle the pending preview request with a terminal status. */\n    abort(message, status) {\n      this.closed = true;\n      this.settle(errorResponse(status, message));\n    }\n    async response(timeoutMs) {\n      const timer = setTimeout(() => {\n        this.settle(errorResponse(504, \"timed out waiting for response\"));\n      }, Math.max(1, timeoutMs));\n      try {\n        return toResponse(await this.responseReady.promise);\n      } finally {\n        clearTimeout(timer);\n      }\n    }\n    pumpParser() {\n      for (; ; ) {\n        const chunk = this.outbound.readUpTo(Number.MAX_SAFE_INTEGER);\n        if (chunk.byteLength === 0) break;\n        this.parser.feed(chunk);\n      }\n      const outcome = this.parser.outcome;\n      if (!outcome) return;\n      if (outcome.kind === \"failed\") {\n        this.settle(errorResponse(502, outcome.message));\n        return;\n      }\n      const { status, statusText, headerPairs, body } = outcome.message;\n      this.settle({\n        status,\n        statusText,\n        // The framing is consumed here; the Worker Response re-frames the body itself.\n        headerPairs: headerPairs.filter(([key]) => !/^transfer-encoding$/i.test(key)),\n        body\n      });\n    }\n    settle(response) {\n      if (this.settled) return;\n      this.settled = true;\n      this.responseReady.resolve(response);\n    }\n  };\n  var LoopbackClientConnection = class {\n    constructor(id, port, route, limits) {\n      this.id = id;\n      this.port = port;\n      this.route = route;\n      this.limits = limits;\n    }\n    id;\n    port;\n    route;\n    limits;\n    parser = new HttpRequestParser();\n    /** Response bytes the guest client reads. */\n    inbound = new ByteChunkQueue(Number.MAX_SAFE_INTEGER, \"loopback response buffer\");\n    readable = null;\n    drained = null;\n    dispatched = false;\n    eof = false;\n    closed = false;\n    write(bytesLike) {\n      const bytes = toBytes(bytesLike);\n      if (bytes.byteLength === 0 || this.closed) return bytes.byteLength;\n      if (this.dispatched) {\n        throw new Error(\n          `Nimbus loopback socket: port ${this.port} answered with \"Connection: close\"; open a new connection for the next request`\n        );\n      }\n      this.parser.feed(bytes.slice());\n      const outcome = this.parser.outcome;\n      if (!outcome) return bytes.byteLength;\n      this.dispatched = true;\n      if (outcome.kind === \"failed\") this.failWith(400, outcome.message);\n      else void this.dispatch(outcome.message);\n      return bytes.byteLength;\n    }\n    read(maxBytes) {\n      return Array.from(this.readBytes(maxBytes));\n    }\n    /** Byte-array read. The fd-backed path uses this so a stream never round-trips through number[]. */\n    readBytes(maxBytes) {\n      const out = this.inbound.readUpTo(Math.max(1, maxBytes | 0));\n      if (this.drained && this.inbound.pendingBytes <= LOOPBACK_READ_HIGH_WATER_BYTES) {\n        const waiter = this.drained;\n        this.drained = null;\n        waiter.resolve();\n      }\n      return out;\n    }\n    atEof() {\n      return (this.eof || this.closed) && this.inbound.pendingBytes === 0;\n    }\n    /** Blocks the guest until response bytes arrive; an empty result is EOF. */\n    async readAsync(maxBytes) {\n      return Array.from(await this.readBytesAsync(maxBytes));\n    }\n    async readBytesAsync(maxBytes) {\n      for (; ; ) {\n        const chunk = this.readBytes(maxBytes);\n        if (chunk.byteLength > 0) return chunk;\n        if (this.eof || this.closed) return EMPTY_BYTES;\n        if (!this.dispatched) {\n          throw new Error(\n            \"Nimbus loopback socket: read before a complete HTTP request was written (loopback sockets carry HTTP requests, not arbitrary byte streams)\"\n          );\n        }\n        const waiter = this.readable ??= new Deferred();\n        await waiter.promise;\n      }\n    }\n    close() {\n      if (this.closed) return;\n      this.closed = true;\n      this.wakeReader();\n      if (this.drained) {\n        const waiter = this.drained;\n        this.drained = null;\n        waiter.resolve();\n      }\n    }\n    async dispatch(parsed) {\n      let request;\n      try {\n        request = this.buildRequest(parsed);\n      } catch (error) {\n        this.failWith(400, describeError(error));\n        return;\n      }\n      let response;\n      try {\n        response = await this.withTimeout(this.route(this.port, request));\n      } catch (error) {\n        this.failWith(502, describeError(error));\n        return;\n      }\n      await this.streamResponse(request.method, response);\n    }\n    buildRequest(parsed) {\n      const headers = new Headers();\n      let authority = `127.0.0.1:${this.port}`;\n      for (const [key, value] of parsed.headerPairs) {\n        if (/^host$/i.test(key)) {\n          authority = value;\n          continue;\n        }\n        if (/^(transfer-encoding|connection|content-length|keep-alive)$/i.test(key)) continue;\n        headers.append(key, value);\n      }\n      const target = parsed.target.startsWith(\"/\") ? parsed.target : `/${parsed.target}`;\n      const url = /^https?:\\/\\//i.test(parsed.target) ? parsed.target : `http://${authority}${target}`;\n      const body = parsed.body && parsed.body.byteLength > 0 ? parsed.body : null;\n      const methodTakesBody = parsed.method !== \"GET\" && parsed.method !== \"HEAD\";\n      return new Request(url, {\n        method: parsed.method,\n        headers,\n        body: methodTakesBody ? body : null\n      });\n    }\n    async streamResponse(method, response) {\n      const withBody = responseCanHaveBody(method, response.status) && response.body !== null;\n      const headers = new Headers(response.headers);\n      for (const hopByHop of [\"transfer-encoding\", \"content-length\", \"connection\", \"keep-alive\"]) {\n        headers.delete(hopByHop);\n      }\n      this.pushBytes(encodeHttpResponseHead(response.status, response.statusText, headers, withBody));\n      if (!withBody || !response.body) {\n        this.finishStream();\n        return;\n      }\n      const reader = response.body.getReader();\n      try {\n        for (; ; ) {\n          const { value, done } = await reader.read();\n          if (done) break;\n          if (this.closed) return;\n          const bytes = value instanceof Uint8Array ? value : new Uint8Array(value);\n          if (bytes.byteLength === 0) continue;\n          this.pushBytes(encodeChunkedFrame(bytes));\n          await this.awaitDrain();\n        }\n        this.pushBytes(CHUNKED_TERMINATOR);\n      } catch {\n      } finally {\n        try {\n          await reader.cancel();\n        } catch {\n        }\n        this.finishStream();\n      }\n    }\n    /** Synthesize a complete response so the guest sees an HTTP error, never a hang. */\n    failWith(status, detail) {\n      const body = new TextEncoder().encode(`Nimbus loopback socket: ${detail}`);\n      const headers = new Headers({\n        \"content-type\": \"text/plain; charset=utf-8\",\n        \"content-length\": String(body.byteLength)\n      });\n      this.pushBytes(encodeHttpResponseHead(status, \"\", headers, false));\n      this.pushBytes(body);\n      this.finishStream();\n    }\n    pushBytes(bytes) {\n      if (this.closed) return;\n      this.inbound.enqueue(bytes);\n      this.wakeReader();\n    }\n    finishStream() {\n      this.eof = true;\n      this.wakeReader();\n    }\n    wakeReader() {\n      const waiter = this.readable;\n      if (!waiter) return;\n      this.readable = null;\n      waiter.resolve();\n    }\n    /** Pause the body pump while the guest is behind, so a big stream cannot grow unbounded. */\n    awaitDrain() {\n      if (this.inbound.pendingBytes <= LOOPBACK_READ_HIGH_WATER_BYTES) return Promise.resolve();\n      return (this.drained ??= new Deferred()).promise;\n    }\n    withTimeout(promise) {\n      let timer = null;\n      const timeout = new Promise((_resolve, reject) => {\n        timer = setTimeout(\n          () => reject(new Error(`port ${this.port} did not respond within ${this.limits.responseTimeoutMs}ms`)),\n          Math.max(1, this.limits.responseTimeoutMs)\n        );\n      });\n      return Promise.race([promise, timeout]).finally(() => {\n        if (timer !== null) clearTimeout(timer);\n      });\n    }\n  };\n  function describeError(error) {\n    return error instanceof Error ? error.message : String(error);\n  }\n  function socketStreamFor(conn) {\n    return {\n      // Neither direction has a handshake: an accepted connection already holds\n      // the request, and a dialed one starts its exchange on the first write.\n      opened: Promise.resolve(),\n      readable: new ReadableStream(\n        {\n          async pull(controller) {\n            const bytes = await conn.readBytesAsync(LOOPBACK_STREAM_CHUNK_BYTES);\n            if (bytes.byteLength === 0) controller.close();\n            else controller.enqueue(bytes);\n          },\n          cancel() {\n            conn.close();\n          }\n        },\n        // highWaterMark 0 so the stream never pulls speculatively. A default\n        // strategy pulls once at construction, which on a client connection\n        // means reading before the guest has written its request.\n        { highWaterMark: 0 }\n      ),\n      writable: new WritableStream({\n        write(chunk) {\n          conn.write(chunk);\n        },\n        abort() {\n          conn.close();\n        }\n      }),\n      close() {\n        conn.close();\n        return Promise.resolve();\n      }\n    };\n  }\n  var VirtualListener = class {\n    constructor(port) {\n      this.port = port;\n    }\n    port;\n    queue = [];\n    acceptWaiters = [];\n    push(conn) {\n      const waiter = this.acceptWaiters.shift();\n      if (waiter) waiter.resolve(conn);\n      else this.queue.push(conn);\n    }\n    accept() {\n      const queued = this.queue.shift();\n      if (queued) return Promise.resolve(queued);\n      const waiter = new Deferred();\n      this.acceptWaiters.push(waiter);\n      return waiter.promise;\n    }\n    take() {\n      return this.queue.shift() ?? null;\n    }\n    pending() {\n      return this.queue.length;\n    }\n    drainQueued() {\n      return this.queue.splice(0);\n    }\n    rejectPendingAccepts(error) {\n      for (const waiter of this.acceptWaiters.splice(0)) waiter.reject(error);\n    }\n  };\n  var VirtualSocketKernel = class {\n    constructor(host, limits) {\n      this.host = host;\n      this.limits = { ...DEFAULT_LIMITS, ...limits };\n    }\n    host;\n    /** Public: runner glue inspects listeners.keys() for the default preview port. */\n    listeners = /* @__PURE__ */ new Map();\n    connections = /* @__PURE__ */ new Map();\n    limits;\n    nextConnectionId = 1;\n    nextEphemeralPort = 49152;\n    listenWaiters = [];\n    readableWaiters = /* @__PURE__ */ new Set();\n    listen(port) {\n      let n = Number(port);\n      if (!Number.isInteger(n) || n < 0 || n >= 65536) throw new Error(`invalid port: ${port}`);\n      if (n === 0) {\n        while (this.listeners.has(this.nextEphemeralPort)) {\n          this.nextEphemeralPort++;\n          if (this.nextEphemeralPort >= 65535) this.nextEphemeralPort = 49152;\n        }\n        n = this.nextEphemeralPort++;\n        if (this.nextEphemeralPort >= 65535) this.nextEphemeralPort = 49152;\n      }\n      if (!this.listeners.has(n)) {\n        this.listeners.set(n, new VirtualListener(n));\n        try {\n          this.host.__nimbusVirtualSocketDidListen?.(n);\n        } catch {\n        }\n        for (const waiter of this.listenWaiters.splice(0)) waiter.resolve(n);\n      }\n      return n;\n    }\n    closeListener(port) {\n      const n = Number(port);\n      const listener = this.listeners.get(n);\n      if (!listener) return;\n      this.listeners.delete(n);\n      for (const conn of listener.drainQueued()) {\n        this.connections.delete(conn.id);\n        conn.abort(`listener closed on port ${n}`, 502);\n      }\n      listener.rejectPendingAccepts(new Error(`port is not listening: ${n}`));\n    }\n    async accept(port) {\n      const listener = this.listeners.get(Number(port));\n      if (!listener) throw new Error(`port is not listening: ${port}`);\n      const conn = await listener.accept();\n      return { id: conn.id, host: \"127.0.0.1\", port: 0 };\n    }\n    acceptNow(port) {\n      const listener = this.listeners.get(Number(port));\n      if (!listener) throw new Error(`port is not listening: ${port}`);\n      const conn = listener.take();\n      return conn ? { id: conn.id, host: \"127.0.0.1\", port: 0 } : null;\n    }\n    /**\n     * Open a client connection to `port` on the session's loopback.\n     *\n     * The returned id is an ordinary connection id: send() writes the\n     * request, recv()/recvAsync() read the response, close() releases it.\n     * Only HTTP/1.1 crosses a loopback connection - see\n     * LoopbackClientConnection for why - and each one carries a single\n     * request/response exchange.\n     */\n    connect(port) {\n      const conn = this.openLoopbackClient(port);\n      this.connections.set(conn.id, conn);\n      return conn.id;\n    }\n    /**\n     * The same client connection as `connect`, handed back in Cloudflare's\n     * `Socket` shape.\n     *\n     * Guests whose sockets are real WASI file descriptors (ruby.wasm, and any\n     * future wasm32-wasi program) reach loopback through this: the WASI shim\n     * stores it in exactly the fd slot a `cloudflare:sockets` connection would\n     * occupy, so `fd_read` on an in-session port is the same suspending read as\n     * `fd_read` on a remote host.\n     */\n    connectStream(port) {\n      return socketStreamFor(this.openLoopbackClient(port));\n    }\n    /**\n     * An already-accepted connection in the same `Socket` shape, so a server's\n     * accepted socket is the same kind of file descriptor as a client's dialed\n     * one. `accept`/`acceptNow` still hand out the connection id, because accept\n     * itself stays on the cooperative pump - this only binds the result.\n     */\n    streamFor(id) {\n      const conn = this.connections.get(Number(id));\n      if (!conn) throw new Error(`connection is closed: ${id}`);\n      return socketStreamFor(conn);\n    }\n    openLoopbackClient(port) {\n      const n = Number(port);\n      if (!Number.isInteger(n) || n <= 0 || n >= 65536) throw new Error(`invalid port: ${port}`);\n      const route = this.host.__nimbusVirtualSocketRouteLoopback;\n      if (typeof route !== \"function\") {\n        throw new Error(\"Nimbus loopback sockets are unavailable in this runtime\");\n      }\n      return new LoopbackClientConnection(this.nextConnectionId++, n, route, this.limits);\n    }\n    /** Plain number array: Pyodide bytes() and the ruby.wasm base64 bridge both consume it. */\n    recv(id, maxBytes) {\n      const conn = this.connections.get(Number(id));\n      if (!conn) return [];\n      return conn.read(Number(maxBytes));\n    }\n    /**\n     * Suspending read. A client connection has nothing to hand back until\n     * the loopback response arrives, so guests that can suspend (Pyodide\n     * `run_sync`, a JSPI-suspending WASI call) await this instead of\n     * spinning on recv(). An empty result is EOF.\n     */\n    async recvAsync(id, maxBytes) {\n      const conn = this.connections.get(Number(id));\n      if (!conn) return [];\n      return conn.readAsync(Number(maxBytes));\n    }\n    /**\n     * Whether an empty recv() means end-of-response rather than \"not yet\".\n     * Guests that poll instead of suspending (ruby.wasm, whose JS bridge is\n     * synchronous) need the two apart to avoid truncating a response.\n     */\n    atEof(id) {\n      const conn = this.connections.get(Number(id));\n      return conn ? conn.atEof() : true;\n    }\n    send(id, bytesLike) {\n      const conn = this.connections.get(Number(id));\n      if (!conn) throw new Error(`connection is closed: ${id}`);\n      return conn.write(bytesLike);\n    }\n    close(id) {\n      const conn = this.connections.get(Number(id));\n      if (!conn) return;\n      conn.close();\n      this.connections.delete(Number(id));\n    }\n    pending(port) {\n      return this.listeners.get(Number(port))?.pending() ?? 0;\n    }\n    firstListeningPort() {\n      for (const port of this.listeners.keys()) return port;\n      return null;\n    }\n    /** select()-style readiness: resolves ports with queued connections, [] on timeout. */\n    waitReadable(ports, timeoutSeconds) {\n      const normalized = (Array.isArray(ports) ? ports : []).map((p) => Number(p)).filter((p) => Number.isInteger(p));\n      const readyNow = normalized.filter((port) => this.pending(port) > 0);\n      if (readyNow.length > 0) return Promise.resolve(readyNow);\n      const timeoutMs = timeoutSeconds == null ? this.limits.responseTimeoutMs : Math.max(0, Number(timeoutSeconds) * 1e3);\n      const deferred = new Deferred();\n      const waiter = {\n        ports: normalized,\n        deferred,\n        timer: setTimeout(() => {\n          this.readableWaiters.delete(waiter);\n          deferred.resolve([]);\n        }, timeoutMs)\n      };\n      this.readableWaiters.add(waiter);\n      return deferred.promise;\n    }\n    async waitForListen(timeoutMs) {\n      const existing = this.firstListeningPort();\n      if (existing) return existing;\n      const waiter = new Deferred();\n      this.listenWaiters.push(waiter);\n      let timer = null;\n      const timeout = new Promise((resolve) => {\n        timer = setTimeout(() => resolve(null), Math.max(1, timeoutMs ?? 5e3));\n      });\n      try {\n        return await Promise.race([waiter.promise, timeout]);\n      } finally {\n        if (timer !== null) clearTimeout(timer);\n      }\n    }\n    async handleHttpRequest(port, request) {\n      const n = Number(port);\n      let listener = this.listeners.get(n);\n      if (!listener) {\n        try {\n          await this.host.__nimbusVirtualSocketEnsureListener?.(n);\n        } catch {\n        }\n        listener = this.listeners.get(n);\n      }\n      if (!listener) {\n        return new Response(`Nimbus virtual socket: no listener on port ${port}`, { status: 502 });\n      }\n      const body = request.method === \"GET\" || request.method === \"HEAD\" ? EMPTY_BYTES : new Uint8Array(await request.arrayBuffer());\n      if (body.byteLength > this.limits.maxRequestBodyBytes) {\n        return new Response(\n          `Nimbus virtual socket: request body exceeds ${this.limits.maxRequestBodyBytes} bytes`,\n          { status: 413 }\n        );\n      }\n      const id = this.nextConnectionId++;\n      const conn = new VirtualConnection(id, request.method, encodeHttpRequest(request, body), this.limits);\n      this.connections.set(id, conn);\n      listener.push(conn);\n      this.notifyReadable(n);\n      const signal = request.signal;\n      const onAbort = () => conn.abort(\"client aborted the request\", 499);\n      if (signal?.aborted) onAbort();\n      else signal?.addEventListener(\"abort\", onAbort);\n      try {\n        try {\n          const accepted = await this.host.__nimbusVirtualSocketRequestQueued?.(n);\n          if (accepted === false) {\n            const detail = typeof this.host.__nimbusVirtualSocketLastError === \"string\" ? this.host.__nimbusVirtualSocketLastError.trim() : \"\";\n            const suffix = detail ? `: ${detail}` : \"\";\n            return new Response(\n              `Nimbus virtual socket: runtime handler did not accept the request${suffix}`,\n              { status: 502 }\n            );\n          }\n        } catch {\n        }\n        return await conn.response(this.limits.responseTimeoutMs);\n      } finally {\n        signal?.removeEventListener(\"abort\", onAbort);\n        conn.close();\n        this.connections.delete(id);\n      }\n    }\n    notifyReadable(port) {\n      for (const waiter of Array.from(this.readableWaiters)) {\n        if (!waiter.ports.includes(port)) continue;\n        const ready = waiter.ports.filter((p) => this.pending(p) > 0);\n        if (ready.length === 0) continue;\n        clearTimeout(waiter.timer);\n        this.readableWaiters.delete(waiter);\n        waiter.deferred.resolve(ready);\n      }\n    }\n  };\n  function installVirtualSocketKernel(scope = globalThis) {\n    if (!scope.__nimbusVirtualSockets) {\n      scope.__nimbusVirtualSockets = new VirtualSocketKernel(scope);\n    }\n    return scope.__nimbusVirtualSockets;\n  }\n\n  // <stdin>\n  installVirtualSocketKernel();\n})();\n";