@nimbus-sh/worker 0.1.5 → 0.1.6

package/dist/runtime/vfs-snapshot.js

@@ -0,0 +1,141 @@
+export function bytesToB64(bytes) {
+    let s = '';
+    for (let i = 0; i < bytes.length; i++)
+        s += String.fromCharCode(bytes[i]);
+    return btoa(s);
+}
+export function b64ToBytes(b64) {
+    const bin = atob(b64);
+    const out = new Uint8Array(bin.length);
+    for (let i = 0; i < bin.length; i++)
+        out[i] = bin.charCodeAt(i);
+    return out;
+}
+/**
+ * Snapshot a VFS subtree into a JSON-serializable WASI-shaped filesystem.
+ *
+ * The snapshot is intentionally bounded. Runtimes that need incremental or
+ * lazy file IO should add a streaming bridge; a single request payload is the
+ * right primitive only for normal source trees and small app state.
+ */
+export function snapshotVfs(vfs, vfsRoot, caps = {}) {
+    const maxBytes = caps.maxBytes ?? 32 * 1024 * 1024;
+    const maxFiles = caps.maxFiles ?? 5000;
+    const skipSubdirs = new Set(caps.skipSubdirs ?? ['.nimbus', 'node_modules', '.cache', '.npm']);
+    const root = vfsRoot.replace(/^\/+/, '').replace(/\/+$/, '');
+    const roots = Array.from(new Set([
+        root,
+        ...Array.from(caps.extraRoots ?? []).map((r) => r.replace(/^\/+/, '').replace(/\/+$/, '')).filter(Boolean),
+    ].filter(Boolean)));
+    const files = {};
+    const dirsSet = new Set();
+    let totalBytes = 0;
+    let fileCount = 0;
+    const stack = [];
+    const addDirWithParents = (path) => {
+        const clean = path.replace(/^\/+/, '').replace(/\/+$/, '');
+        if (!clean)
+            return;
+        const parts = clean.split('/').filter(Boolean);
+        for (let i = 1; i <= parts.length; i++) {
+            dirsSet.add(parts.slice(0, i).join('/'));
+        }
+    };
+    for (const start of roots) {
+        addDirWithParents(start);
+        if (vfs.exists(start))
+            stack.push(start);
+    }
+    while (stack.length > 0) {
+        const dir = stack.pop();
+        let entries;
+        try {
+            entries = vfs.readdir(dir);
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries) {
+            const childPath = `${dir}/${entry.name}`;
+            if (entry.type === 'directory') {
+                if (skipSubdirs.has(entry.name))
+                    continue;
+                addDirWithParents(childPath);
+                stack.push(childPath);
+                continue;
+            }
+            let bytes;
+            try {
+                bytes = vfs.readFile(childPath);
+            }
+            catch {
+                continue;
+            }
+            totalBytes += bytes.length;
+            fileCount++;
+            if (totalBytes > maxBytes) {
+                return { error: `runtime filesystem snapshot exceeded ${(maxBytes / 1024 / 1024).toFixed(0)} MiB cap (current dir: ${dir})` };
+            }
+            if (fileCount > maxFiles) {
+                return { error: `runtime filesystem snapshot exceeded ${maxFiles} file cap` };
+            }
+            addDirWithParents(dir);
+            files[childPath] = bytesToB64(bytes);
+        }
+    }
+    return { snapshot: { root, roots, preopens: [], files, dirs: Array.from(dirsSet).sort() }, bytes: totalBytes, files: fileCount };
+}
+/**
+ * Apply a runtime-produced filesystem diff back into the supervisor VFS.
+ * Operations are independent so one bad path never loses the rest of a run.
+ */
+export function flushVfsDiff(vfs, diff) {
+    let written = 0;
+    let deleted = 0;
+    let mkdirs = 0;
+    let rmdirs = 0;
+    let timesTouched = 0;
+    let symlinks = 0;
+    for (const path of diff.dirsCreated) {
+        try {
+            vfs.mkdir(path, { recursive: true });
+            mkdirs++;
+        }
+        catch { }
+    }
+    for (const [path, b64] of Object.entries(diff.filesWritten)) {
+        try {
+            const lastSlash = path.lastIndexOf('/');
+            if (lastSlash > 0) {
+                try {
+                    vfs.mkdir(path.substring(0, lastSlash), { recursive: true });
+                }
+                catch { }
+            }
+            vfs.writeFile(path, b64ToBytes(b64));
+            written++;
+        }
+        catch { }
+    }
+    for (const path of diff.filesDeleted) {
+        try {
+            vfs.unlink(path);
+            deleted++;
+        }
+        catch { }
+    }
+    for (const path of diff.dirsDeleted) {
+        try {
+            vfs.rmdir(path);
+            rmdirs++;
+        }
+        catch { }
+    }
+    if (diff.timesChanged)
+        timesTouched = Object.keys(diff.timesChanged).length;
+    if (diff.symlinksCreated)
+        symlinks = Object.keys(diff.symlinksCreated).length;
+    if (diff.symlinksDeleted)
+        symlinks += diff.symlinksDeleted.length;
+    return { written, deleted, mkdirs, rmdirs, timesTouched, symlinks };
+}

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

@@ -0,0 +1,16 @@
+/**
+ * virtual-socket-kernel.ts - shared in-facet loopback socket substrate.
+ *
+ * The supervisor-facing surface stays the existing PortRegistry:
+ * /port/<n>/ and /preview/?port=<n> route a real Worker Request to a
+ * facet's handleHttpRequest(Request). Inside the facet this kernel
+ * converts that Request into an accepted HTTP/1.1 byte stream so guest
+ * runtimes can implement normal socket APIs without Cloudflare inbound
+ * TCP support.
+ *
+ * Runtime adapters (Python socket.py, Ruby socket.rb, future
+ * wasm32-wasi-nimbus syscalls) should call this shared JS kernel rather
+ * than each implementing their own preview bridge.
+ */
+export declare const VIRTUAL_SOCKET_KERNEL_SRC = "\nconst __NIMBUS_SOCKET_TIMEOUT_MS = 30_000;\n\nclass __NimbusDeferred {\n  constructor() {\n    this.promise = new Promise((resolve, reject) => {\n      this.resolve = resolve;\n      this.reject = reject;\n    });\n  }\n}\n\nfunction __nimbusSocketBytes(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 new Uint8Array(value);\n  if (typeof value === \"string\") return new TextEncoder().encode(value);\n  if (value && typeof value.toJs === \"function\") return __nimbusSocketBytes(value.toJs());\n  return new Uint8Array(0);\n}\n\nfunction __nimbusConcatBytes(parts) {\n  let len = 0;\n  for (const p of parts) len += p.byteLength;\n  const out = new Uint8Array(len);\n  let off = 0;\n  for (const p of parts) {\n    out.set(p, off);\n    off += p.byteLength;\n  }\n  return out;\n}\n\nfunction __nimbusFindHeaderEnd(bytes) {\n  for (let i = 0; i + 3 < bytes.length; i++) {\n    if (bytes[i] === 13 && bytes[i + 1] === 10 && bytes[i + 2] === 13 && bytes[i + 3] === 10) return i + 4;\n  }\n  return -1;\n}\n\nfunction __nimbusHeaderValue(headers, name) {\n  const target = name.toLowerCase();\n  for (const [k, v] of headers) {\n    if (k.toLowerCase() === target) return v;\n  }\n  return null;\n}\n\nfunction __nimbusParseChunked(body) {\n  const dec = new TextDecoder();\n  const chunks = [];\n  let off = 0;\n  while (off < body.length) {\n    let lineEnd = -1;\n    for (let i = off; i + 1 < body.length; i++) {\n      if (body[i] === 13 && body[i + 1] === 10) { lineEnd = i; break; }\n    }\n    if (lineEnd < 0) return null;\n    const line = dec.decode(body.subarray(off, lineEnd)).trim();\n    const sizeText = line.split(\";\", 1)[0];\n    const size = parseInt(sizeText, 16);\n    if (!Number.isFinite(size) || size < 0) return null;\n    off = lineEnd + 2;\n    if (body.length < off + size + 2) return null;\n    if (size === 0) return __nimbusConcatBytes(chunks);\n    chunks.push(body.subarray(off, off + size));\n    off += size;\n    if (body[off] !== 13 || body[off + 1] !== 10) return null;\n    off += 2;\n  }\n  return null;\n}\n\nasync function __nimbusRequestBytes(request) {\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  const body = request.method === \"GET\" || request.method === \"HEAD\"\n    ? new Uint8Array(0)\n    : new Uint8Array(await request.arrayBuffer());\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 __nimbusConcatBytes([new TextEncoder().encode(lines.join(\"\\r\\n\")), body]);\n}\n\nclass __NimbusVirtualConnection {\n  constructor(id, requestBytes) {\n    this.id = id;\n    this.requestBytes = requestBytes;\n    this.requestOffset = 0;\n    this.output = [];\n    this.closed = false;\n    this.waiters = [];\n  }\n\n  read(maxBytes) {\n    if (this.requestOffset >= this.requestBytes.byteLength) return [];\n    const end = Math.min(this.requestOffset + Math.max(1, maxBytes | 0), this.requestBytes.byteLength);\n    const chunk = this.requestBytes.subarray(this.requestOffset, end);\n    this.requestOffset = end;\n    return Array.from(chunk);\n  }\n\n  write(bytesLike) {\n    const bytes = __nimbusSocketBytes(bytesLike);\n    if (bytes.byteLength > 0) this.output.push(bytes.slice());\n    this._wake();\n    return bytes.byteLength;\n  }\n\n  close() {\n    this.closed = true;\n    this._wake();\n  }\n\n  _wake() {\n    const waiters = this.waiters.splice(0);\n    for (const w of waiters) w.resolve();\n  }\n\n  _responseFromBytes() {\n    const bytes = __nimbusConcatBytes(this.output);\n    const headerEnd = __nimbusFindHeaderEnd(bytes);\n    if (headerEnd < 0) return null;\n    const headerText = new TextDecoder().decode(bytes.subarray(0, headerEnd));\n    const lines = headerText.replace(/\\r\\n/g, \"\\n\").split(\"\\n\").filter((line) => line.length > 0);\n    const statusLine = lines.shift() || \"HTTP/1.1 200 OK\";\n    const m = /^HTTP\\/\\d(?:\\.\\d)?\\s+(\\d{3})(?:\\s+(.*))?$/.exec(statusLine);\n    const status = m ? parseInt(m[1], 10) : 200;\n    const statusText = m && m[2] ? m[2] : \"\";\n    const headerPairs = [];\n    for (const line of lines) {\n      const idx = line.indexOf(\":\");\n      if (idx <= 0) continue;\n      headerPairs.push([line.slice(0, idx), line.slice(idx + 1).trimStart()]);\n    }\n    const body = bytes.subarray(headerEnd);\n    const contentLength = __nimbusHeaderValue(headerPairs, \"Content-Length\");\n    const transferEncoding = __nimbusHeaderValue(headerPairs, \"Transfer-Encoding\");\n    let responseBody = body;\n    if (transferEncoding && /chunked/i.test(transferEncoding)) {\n      const parsed = __nimbusParseChunked(body);\n      if (!parsed) return null;\n      responseBody = parsed;\n    } else if (contentLength != null) {\n      const expected = parseInt(contentLength, 10);\n      if (Number.isFinite(expected) && body.byteLength < expected) return null;\n      if (Number.isFinite(expected)) responseBody = body.subarray(0, expected);\n    } else if (!this.closed) {\n      return null;\n    }\n    const headers = new Headers();\n    for (const [k, v] of headerPairs) {\n      if (/^transfer-encoding$/i.test(k)) continue;\n      headers.append(k, v);\n    }\n    return new Response(responseBody, { status, statusText, headers });\n  }\n\n  async response(timeoutMs) {\n    const deadline = Date.now() + Math.max(1, timeoutMs || __NIMBUS_SOCKET_TIMEOUT_MS);\n    while (Date.now() < deadline) {\n      const response = this._responseFromBytes();\n      if (response) return response;\n      const waiter = new __NimbusDeferred();\n      this.waiters.push(waiter);\n      const remaining = Math.max(1, deadline - Date.now());\n      await Promise.race([\n        waiter.promise,\n        new Promise((resolve) => setTimeout(resolve, Math.min(remaining, 250))),\n      ]);\n    }\n    return new Response(\"Nimbus virtual socket: timed out waiting for response\", { status: 504 });\n  }\n}\n\nclass __NimbusVirtualListener {\n  constructor(port) {\n    this.port = port;\n    this.queue = [];\n    this.waiters = [];\n  }\n\n  push(conn) {\n    const waiter = this.waiters.shift();\n    if (waiter) waiter.resolve(conn);\n    else this.queue.push(conn);\n  }\n\n  accept() {\n    const queued = this.queue.shift();\n    if (queued) return Promise.resolve(queued);\n    const waiter = new __NimbusDeferred();\n    this.waiters.push(waiter);\n    return waiter.promise;\n  }\n\n  take() {\n    return this.queue.shift() || null;\n  }\n\n  pending() {\n    return this.queue.length;\n  }\n}\n\nclass __NimbusVirtualSocketKernel {\n  constructor() {\n    this.listeners = new Map();\n    this.connections = new Map();\n    this.nextConnectionId = 1;\n    this.nextEphemeralPort = 49152;\n    this.listenWaiters = [];\n  }\n\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    let listener = this.listeners.get(n);\n    if (!listener) {\n      listener = new __NimbusVirtualListener(n);\n      this.listeners.set(n, listener);\n      try { globalThis.__nimbusVirtualSocketDidListen?.(n); } catch {}\n      const waiters = this.listenWaiters.splice(0);\n      for (const waiter of waiters) waiter.resolve(n);\n    }\n    return n;\n  }\n\n  closeListener(port) {\n    this.listeners.delete(Number(port));\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\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  recv(id, maxBytes) {\n    const conn = this.connections.get(Number(id));\n    if (!conn) return [];\n    return conn.read(maxBytes);\n  }\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\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\n  pending(port) {\n    return this.listeners.get(Number(port))?.pending() || 0;\n  }\n\n  firstListeningPort() {\n    return this.listeners.size > 0 ? Array.from(this.listeners.keys())[0] : null;\n  }\n\n  waitReadable(ports, timeoutSeconds) {\n    const normalized = (Array.isArray(ports) ? ports : []).map((p) => Number(p)).filter((p) => Number.isInteger(p));\n    for (const port of normalized) {\n      if (this.pending(port) > 0) return Promise.resolve([port]);\n    }\n    const timeoutMs = timeoutSeconds == null ? __NIMBUS_SOCKET_TIMEOUT_MS : Math.max(0, Number(timeoutSeconds) * 1000);\n    const waiter = new __NimbusDeferred();\n    const check = () => {\n      const ready = normalized.filter((port) => this.pending(port) > 0);\n      if (ready.length > 0) waiter.resolve(ready);\n    };\n    const oldWaiters = this.listenWaiters;\n    const poll = setInterval(check, 25);\n    const timer = setTimeout(() => {\n      clearInterval(poll);\n      waiter.resolve([]);\n    }, timeoutMs);\n    return waiter.promise.finally(() => {\n      clearInterval(poll);\n      clearTimeout(timer);\n      this.listenWaiters = oldWaiters;\n    });\n  }\n\n  async waitForListen(timeoutMs) {\n    const existing = this.firstListeningPort();\n    if (existing) return existing;\n    const waiter = new __NimbusDeferred();\n    this.listenWaiters.push(waiter);\n    return await Promise.race([\n      waiter.promise,\n      new Promise((resolve) => setTimeout(() => resolve(null), Math.max(1, timeoutMs || 5_000))),\n    ]);\n  }\n\n  async handleHttpRequest(port, request) {\n    let listener = this.listeners.get(Number(port));\n    if (!listener) {\n      try { await globalThis.__nimbusVirtualSocketEnsureListener?.(Number(port)); } catch {}\n      listener = this.listeners.get(Number(port));\n    }\n    if (!listener) return new Response(\"Nimbus virtual socket: no listener on port \" + port, { status: 502 });\n    const id = this.nextConnectionId++;\n    const conn = new __NimbusVirtualConnection(id, await __nimbusRequestBytes(request));\n    this.connections.set(id, conn);\n    listener.push(conn);\n    try {\n      try { await globalThis.__nimbusVirtualSocketRequestQueued?.(Number(port)); } catch {}\n      return await conn.response(__NIMBUS_SOCKET_TIMEOUT_MS);\n    } finally {\n      conn.close();\n      this.connections.delete(id);\n    }\n  }\n}\n\nglobalThis.__nimbusVirtualSockets = globalThis.__nimbusVirtualSockets || new __NimbusVirtualSocketKernel();\n";
+//# sourceMappingURL=virtual-socket-kernel.d.ts.map

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

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

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

@@ -0,0 +1,360 @@
+/**
+ * virtual-socket-kernel.ts - shared in-facet loopback socket substrate.
+ *
+ * The supervisor-facing surface stays the existing PortRegistry:
+ * /port/<n>/ and /preview/?port=<n> route a real Worker Request to a
+ * facet's handleHttpRequest(Request). Inside the facet this kernel
+ * converts that Request into an accepted HTTP/1.1 byte stream so guest
+ * runtimes can implement normal socket APIs without Cloudflare inbound
+ * TCP support.
+ *
+ * Runtime adapters (Python socket.py, Ruby socket.rb, future
+ * wasm32-wasi-nimbus syscalls) should call this shared JS kernel rather
+ * than each implementing their own preview bridge.
+ */
+export const VIRTUAL_SOCKET_KERNEL_SRC = `
+const __NIMBUS_SOCKET_TIMEOUT_MS = 30_000;
+
+class __NimbusDeferred {
+  constructor() {
+    this.promise = new Promise((resolve, reject) => {
+      this.resolve = resolve;
+      this.reject = reject;
+    });
+  }
+}
+
+function __nimbusSocketBytes(value) {
+  if (value instanceof Uint8Array) return value;
+  if (value instanceof ArrayBuffer) return new Uint8Array(value);
+  if (ArrayBuffer.isView(value)) return new Uint8Array(value.buffer, value.byteOffset, value.byteLength);
+  if (Array.isArray(value)) return new Uint8Array(value);
+  if (typeof value === "string") return new TextEncoder().encode(value);
+  if (value && typeof value.toJs === "function") return __nimbusSocketBytes(value.toJs());
+  return new Uint8Array(0);
+}
+
+function __nimbusConcatBytes(parts) {
+  let len = 0;
+  for (const p of parts) len += p.byteLength;
+  const out = new Uint8Array(len);
+  let off = 0;
+  for (const p of parts) {
+    out.set(p, off);
+    off += p.byteLength;
+  }
+  return out;
+}
+
+function __nimbusFindHeaderEnd(bytes) {
+  for (let i = 0; i + 3 < bytes.length; i++) {
+    if (bytes[i] === 13 && bytes[i + 1] === 10 && bytes[i + 2] === 13 && bytes[i + 3] === 10) return i + 4;
+  }
+  return -1;
+}
+
+function __nimbusHeaderValue(headers, name) {
+  const target = name.toLowerCase();
+  for (const [k, v] of headers) {
+    if (k.toLowerCase() === target) return v;
+  }
+  return null;
+}
+
+function __nimbusParseChunked(body) {
+  const dec = new TextDecoder();
+  const chunks = [];
+  let off = 0;
+  while (off < body.length) {
+    let lineEnd = -1;
+    for (let i = off; i + 1 < body.length; i++) {
+      if (body[i] === 13 && body[i + 1] === 10) { lineEnd = i; break; }
+    }
+    if (lineEnd < 0) return null;
+    const line = dec.decode(body.subarray(off, lineEnd)).trim();
+    const sizeText = line.split(";", 1)[0];
+    const size = parseInt(sizeText, 16);
+    if (!Number.isFinite(size) || size < 0) return null;
+    off = lineEnd + 2;
+    if (body.length < off + size + 2) return null;
+    if (size === 0) return __nimbusConcatBytes(chunks);
+    chunks.push(body.subarray(off, off + size));
+    off += size;
+    if (body[off] !== 13 || body[off + 1] !== 10) return null;
+    off += 2;
+  }
+  return null;
+}
+
+async function __nimbusRequestBytes(request) {
+  const url = new URL(request.url);
+  const path = (url.pathname || "/") + url.search;
+  const headers = new Headers(request.headers);
+  if (!headers.has("Host")) headers.set("Host", url.host || "nimbus.local");
+  const body = request.method === "GET" || request.method === "HEAD"
+    ? new Uint8Array(0)
+    : new Uint8Array(await request.arrayBuffer());
+  if (body.byteLength > 0 && !headers.has("Content-Length")) {
+    headers.set("Content-Length", String(body.byteLength));
+  }
+  const lines = [request.method + " " + path + " HTTP/1.1"];
+  headers.forEach((value, key) => lines.push(key + ": " + value));
+  lines.push("", "");
+  return __nimbusConcatBytes([new TextEncoder().encode(lines.join("\\r\\n")), body]);
+}
+
+class __NimbusVirtualConnection {
+  constructor(id, requestBytes) {
+    this.id = id;
+    this.requestBytes = requestBytes;
+    this.requestOffset = 0;
+    this.output = [];
+    this.closed = false;
+    this.waiters = [];
+  }
+
+  read(maxBytes) {
+    if (this.requestOffset >= this.requestBytes.byteLength) return [];
+    const end = Math.min(this.requestOffset + Math.max(1, maxBytes | 0), this.requestBytes.byteLength);
+    const chunk = this.requestBytes.subarray(this.requestOffset, end);
+    this.requestOffset = end;
+    return Array.from(chunk);
+  }
+
+  write(bytesLike) {
+    const bytes = __nimbusSocketBytes(bytesLike);
+    if (bytes.byteLength > 0) this.output.push(bytes.slice());
+    this._wake();
+    return bytes.byteLength;
+  }
+
+  close() {
+    this.closed = true;
+    this._wake();
+  }
+
+  _wake() {
+    const waiters = this.waiters.splice(0);
+    for (const w of waiters) w.resolve();
+  }
+
+  _responseFromBytes() {
+    const bytes = __nimbusConcatBytes(this.output);
+    const headerEnd = __nimbusFindHeaderEnd(bytes);
+    if (headerEnd < 0) return null;
+    const headerText = new TextDecoder().decode(bytes.subarray(0, headerEnd));
+    const lines = headerText.replace(/\\r\\n/g, "\\n").split("\\n").filter((line) => line.length > 0);
+    const statusLine = lines.shift() || "HTTP/1.1 200 OK";
+    const m = /^HTTP\\/\\d(?:\\.\\d)?\\s+(\\d{3})(?:\\s+(.*))?$/.exec(statusLine);
+    const status = m ? parseInt(m[1], 10) : 200;
+    const statusText = m && m[2] ? m[2] : "";
+    const headerPairs = [];
+    for (const line of lines) {
+      const idx = line.indexOf(":");
+      if (idx <= 0) continue;
+      headerPairs.push([line.slice(0, idx), line.slice(idx + 1).trimStart()]);
+    }
+    const body = bytes.subarray(headerEnd);
+    const contentLength = __nimbusHeaderValue(headerPairs, "Content-Length");
+    const transferEncoding = __nimbusHeaderValue(headerPairs, "Transfer-Encoding");
+    let responseBody = body;
+    if (transferEncoding && /chunked/i.test(transferEncoding)) {
+      const parsed = __nimbusParseChunked(body);
+      if (!parsed) return null;
+      responseBody = parsed;
+    } else if (contentLength != null) {
+      const expected = parseInt(contentLength, 10);
+      if (Number.isFinite(expected) && body.byteLength < expected) return null;
+      if (Number.isFinite(expected)) responseBody = body.subarray(0, expected);
+    } else if (!this.closed) {
+      return null;
+    }
+    const headers = new Headers();
+    for (const [k, v] of headerPairs) {
+      if (/^transfer-encoding$/i.test(k)) continue;
+      headers.append(k, v);
+    }
+    return new Response(responseBody, { status, statusText, headers });
+  }
+
+  async response(timeoutMs) {
+    const deadline = Date.now() + Math.max(1, timeoutMs || __NIMBUS_SOCKET_TIMEOUT_MS);
+    while (Date.now() < deadline) {
+      const response = this._responseFromBytes();
+      if (response) return response;
+      const waiter = new __NimbusDeferred();
+      this.waiters.push(waiter);
+      const remaining = Math.max(1, deadline - Date.now());
+      await Promise.race([
+        waiter.promise,
+        new Promise((resolve) => setTimeout(resolve, Math.min(remaining, 250))),
+      ]);
+    }
+    return new Response("Nimbus virtual socket: timed out waiting for response", { status: 504 });
+  }
+}
+
+class __NimbusVirtualListener {
+  constructor(port) {
+    this.port = port;
+    this.queue = [];
+    this.waiters = [];
+  }
+
+  push(conn) {
+    const waiter = this.waiters.shift();
+    if (waiter) waiter.resolve(conn);
+    else this.queue.push(conn);
+  }
+
+  accept() {
+    const queued = this.queue.shift();
+    if (queued) return Promise.resolve(queued);
+    const waiter = new __NimbusDeferred();
+    this.waiters.push(waiter);
+    return waiter.promise;
+  }
+
+  take() {
+    return this.queue.shift() || null;
+  }
+
+  pending() {
+    return this.queue.length;
+  }
+}
+
+class __NimbusVirtualSocketKernel {
+  constructor() {
+    this.listeners = new Map();
+    this.connections = new Map();
+    this.nextConnectionId = 1;
+    this.nextEphemeralPort = 49152;
+    this.listenWaiters = [];
+  }
+
+  listen(port) {
+    let n = Number(port);
+    if (!Number.isInteger(n) || n < 0 || n >= 65536) throw new Error("invalid port: " + port);
+    if (n === 0) {
+      while (this.listeners.has(this.nextEphemeralPort)) {
+        this.nextEphemeralPort++;
+        if (this.nextEphemeralPort >= 65535) this.nextEphemeralPort = 49152;
+      }
+      n = this.nextEphemeralPort++;
+      if (this.nextEphemeralPort >= 65535) this.nextEphemeralPort = 49152;
+    }
+    let listener = this.listeners.get(n);
+    if (!listener) {
+      listener = new __NimbusVirtualListener(n);
+      this.listeners.set(n, listener);
+      try { globalThis.__nimbusVirtualSocketDidListen?.(n); } catch {}
+      const waiters = this.listenWaiters.splice(0);
+      for (const waiter of waiters) waiter.resolve(n);
+    }
+    return n;
+  }
+
+  closeListener(port) {
+    this.listeners.delete(Number(port));
+  }
+
+  async accept(port) {
+    const listener = this.listeners.get(Number(port));
+    if (!listener) throw new Error("port is not listening: " + port);
+    const conn = await listener.accept();
+    return { id: conn.id, host: "127.0.0.1", port: 0 };
+  }
+
+  acceptNow(port) {
+    const listener = this.listeners.get(Number(port));
+    if (!listener) throw new Error("port is not listening: " + port);
+    const conn = listener.take();
+    return conn ? { id: conn.id, host: "127.0.0.1", port: 0 } : null;
+  }
+
+  recv(id, maxBytes) {
+    const conn = this.connections.get(Number(id));
+    if (!conn) return [];
+    return conn.read(maxBytes);
+  }
+
+  send(id, bytesLike) {
+    const conn = this.connections.get(Number(id));
+    if (!conn) throw new Error("connection is closed: " + id);
+    return conn.write(bytesLike);
+  }
+
+  close(id) {
+    const conn = this.connections.get(Number(id));
+    if (!conn) return;
+    conn.close();
+    this.connections.delete(Number(id));
+  }
+
+  pending(port) {
+    return this.listeners.get(Number(port))?.pending() || 0;
+  }
+
+  firstListeningPort() {
+    return this.listeners.size > 0 ? Array.from(this.listeners.keys())[0] : null;
+  }
+
+  waitReadable(ports, timeoutSeconds) {
+    const normalized = (Array.isArray(ports) ? ports : []).map((p) => Number(p)).filter((p) => Number.isInteger(p));
+    for (const port of normalized) {
+      if (this.pending(port) > 0) return Promise.resolve([port]);
+    }
+    const timeoutMs = timeoutSeconds == null ? __NIMBUS_SOCKET_TIMEOUT_MS : Math.max(0, Number(timeoutSeconds) * 1000);
+    const waiter = new __NimbusDeferred();
+    const check = () => {
+      const ready = normalized.filter((port) => this.pending(port) > 0);
+      if (ready.length > 0) waiter.resolve(ready);
+    };
+    const oldWaiters = this.listenWaiters;
+    const poll = setInterval(check, 25);
+    const timer = setTimeout(() => {
+      clearInterval(poll);
+      waiter.resolve([]);
+    }, timeoutMs);
+    return waiter.promise.finally(() => {
+      clearInterval(poll);
+      clearTimeout(timer);
+      this.listenWaiters = oldWaiters;
+    });
+  }
+
+  async waitForListen(timeoutMs) {
+    const existing = this.firstListeningPort();
+    if (existing) return existing;
+    const waiter = new __NimbusDeferred();
+    this.listenWaiters.push(waiter);
+    return await Promise.race([
+      waiter.promise,
+      new Promise((resolve) => setTimeout(() => resolve(null), Math.max(1, timeoutMs || 5_000))),
+    ]);
+  }
+
+  async handleHttpRequest(port, request) {
+    let listener = this.listeners.get(Number(port));
+    if (!listener) {
+      try { await globalThis.__nimbusVirtualSocketEnsureListener?.(Number(port)); } catch {}
+      listener = this.listeners.get(Number(port));
+    }
+    if (!listener) return new Response("Nimbus virtual socket: no listener on port " + port, { status: 502 });
+    const id = this.nextConnectionId++;
+    const conn = new __NimbusVirtualConnection(id, await __nimbusRequestBytes(request));
+    this.connections.set(id, conn);
+    listener.push(conn);
+    try {
+      try { await globalThis.__nimbusVirtualSocketRequestQueued?.(Number(port)); } catch {}
+      return await conn.response(__NIMBUS_SOCKET_TIMEOUT_MS);
+    } finally {
+      conn.close();
+      this.connections.delete(id);
+    }
+  }
+}
+
+globalThis.__nimbusVirtualSockets = globalThis.__nimbusVirtualSockets || new __NimbusVirtualSocketKernel();
+`;

package/dist/runtime/wasi-instance.d.ts

@@ -112,13 +112,16 @@ export declare const WASI_INSTANCE_PREAMBLE_SRC = "\n// \u2500\u2500 BEGIN: wasi
  * invocation. Files are base64-encoded so the JSON-serializable
  * loader-pool `context` field can carry them.
  *
- * WASI socket and polling support B1+B3: added optional `times` and `symlinks` fields. Backward-
- * compatible — pre-B1 callers omit these and get default "now" timestamps
- * + empty symlink table.
+ * WASI socket and polling support B1+B3: added optional `times` and `symlinks` fields.
+ * `roots` is additive and lets language runtimes snapshot a cwd plus targeted
+ * persistent runtime state without widening every command to the whole home
+ * directory. Backward-compatible — callers that omit it use `root` only.
  */
 export interface WasiFsSnapshot {
     /** Canonical VFS root (no leading slash). E.g. `home/user/wasi-files`. */
     root: string;
+    /** Canonical VFS roots covered by this snapshot. Defaults to `[root]`. */
+    roots?: string[];
     /** Preopen list (order matters; preopens are assigned to fd 3, 4, …). */
     preopens: Array<{
         wasiPath: string;

package/dist/runtime/wasi-instance.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"wasi-instance.d.ts","sourceRoot":"","sources":["../../src/runtime/wasi-instance.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqGG;AAEH;;;;;GAKG;AACH,eAAO,MAAM,0BAA0B,u0pFAk2DtC,CAAC;AAEF;;;;;;;;GAQG;AACH,MAAM,WAAW,cAAc;IAC7B,0EAA0E;IAC1E,IAAI,EAAE,MAAM,CAAC;IACb,yEAAyE;IACzE,QAAQ,EAAE,KAAK,CAAC;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACvD,+DAA+D;IAC/D,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC9B,yCAAyC;IACzC,IAAI,EAAE,MAAM,EAAE,CAAC;IACf;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACxE;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACnC;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,UAAU;IACzB,mEAAmE;IACnE,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACrC,mCAAmC;IACnC,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,kCAAkC;IAClC,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,kCAAkC;IAClC,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC/E,gCAAgC;IAChC,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACzC,wBAAwB;IACxB,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;CAC5B;AAED,0DAA0D;AAC1D,eAAO,MAAM,oBAAoB,EAAE,SAAS,MAAM,EA2BhD,CAAC"}
+{"version":3,"file":"wasi-instance.d.ts","sourceRoot":"","sources":["../../src/runtime/wasi-instance.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqGG;AAEH;;;;;GAKG;AACH,eAAO,MAAM,0BAA0B,u0pFAk2DtC,CAAC;AAEF;;;;;;;;;GASG;AACH,MAAM,WAAW,cAAc;IAC7B,0EAA0E;IAC1E,IAAI,EAAE,MAAM,CAAC;IACb,0EAA0E;IAC1E,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,yEAAyE;IACzE,QAAQ,EAAE,KAAK,CAAC;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACvD,+DAA+D;IAC/D,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC9B,yCAAyC;IACzC,IAAI,EAAE,MAAM,EAAE,CAAC;IACf;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACxE;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACnC;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,UAAU;IACzB,mEAAmE;IACnE,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACrC,mCAAmC;IACnC,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,kCAAkC;IAClC,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,kCAAkC;IAClC,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC/E,gCAAgC;IAChC,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACzC,wBAAwB;IACxB,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;CAC5B;AAED,0DAA0D;AAC1D,eAAO,MAAM,oBAAoB,EAAE,SAAS,MAAM,EA2BhD,CAAC"}

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

@@ -49,33 +49,9 @@
  *     workerd CSP rejects that path.
  */
 import type { RuntimeRunOpts, RuntimeRunResult } from './runtime-registry.js';
+import { type VfsLike } from './vfs-snapshot.js';
 export declare const WASM_RUNNER_VERSION = "0.3.0";
 export declare const WASM_RUNNER_HELP: string;
-/**
- * Minimal VFS shape we depend on. Avoids importing the full
- * SqliteVFS type tree from the supervisor module graph — this file
- * is part of `src/runtime/`, importing supervisor-specific types
- * would create a cycle.
- *
- * filesystem WASI: extended for WASI file-IO. The snapshot path uses readdir +
- * isDirectory + stat to traverse the user's session subtree; the
- * flush path uses writeFile + mkdir + unlink + rmdir.
- */
-interface VfsLike {
-    exists(path: string): boolean;
-    isDirectory(path: string): boolean;
-    readFile(path: string): Uint8Array;
-    writeFile(path: string, content: Uint8Array | string): void;
-    readdir(path: string): {
-        name: string;
-        type: string;
-    }[];
-    mkdir(path: string, opts?: {
-        recursive?: boolean;
-    }): void;
-    unlink(path: string): void;
-    rmdir(path: string): void;
-}
 /**
  * Minimal processTable shape — the parts wasm-runner needs to
  * register a PID + mark exit so `ps` and `logs <pid>` see the

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

@@ -1 +1 @@
-{"version":3,"file":"wasm-runner.d.ts","sourceRoot":"","sources":["../../src/runtime/wasm-runner.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAqD9E,eAAO,MAAM,mBAAmB,UAAU,CAAC;AAE3C,eAAO,MAAM,gBAAgB,QA+BwC,CAAC;AAEtE;;;;;;;;;GASG;AACH,UAAU,OAAO;IACf,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;IAC9B,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;IACnC,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,CAAC;IACnC,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,UAAU,GAAG,MAAM,GAAG,IAAI,CAAC;IAC5D,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IACxD,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,IAAI,CAAC;IAC1D,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B;AA2CD;;;;;GAKG;AACH,UAAU,gBAAgB;IACxB,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,GAAG,EAAE,MAAM,GAAG;QAAE,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC;IACrE,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CACvC;AAED,UAAU,mBAAmB;IAC3B,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,GAAG,QAAQ,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACrE,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;IAC9B,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3C;AA2ID;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE;IACnC,GAAG,EAAE,OAAO,CAAC;IACb,GAAG,EAAE,GAAG,CAAC;IACT,GAAG,EAAE,kBAAkB,CAAC;IACxB,YAAY,EAAE,gBAAgB,CAAC;IAC/B,WAAW,EAAE,mBAAmB,CAAC;CAClC,IAEG,WAAW,OAAO,EAClB,OAAO,MAAM,EACb,MAAM,cAAc,KACnB,OAAO,CAAC,gBAAgB,CAAC,CAgd7B"}
+{"version":3,"file":"wasm-runner.d.ts","sourceRoot":"","sources":["../../src/runtime/wasm-runner.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAE9E,OAAO,EAA6B,KAAK,OAAO,EAAE,MAAM,mBAAmB,CAAC;AAoD5E,eAAO,MAAM,mBAAmB,UAAU,CAAC;AAE3C,eAAO,MAAM,gBAAgB,QA+BwC,CAAC;AA2CtE;;;;;GAKG;AACH,UAAU,gBAAgB;IACxB,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,GAAG,EAAE,MAAM,GAAG;QAAE,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC;IACrE,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CACvC;AAED,UAAU,mBAAmB;IAC3B,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,GAAG,QAAQ,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACrE,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;IAC9B,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3C;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE;IACnC,GAAG,EAAE,OAAO,CAAC;IACb,GAAG,EAAE,GAAG,CAAC;IACT,GAAG,EAAE,kBAAkB,CAAC;IACxB,YAAY,EAAE,gBAAgB,CAAC;IAC/B,WAAW,EAAE,mBAAmB,CAAC;CAClC,IAEG,WAAW,OAAO,EAClB,OAAO,MAAM,EACb,MAAM,cAAc,KACnB,OAAO,CAAC,gBAAgB,CAAC,CAgd7B"}