@nimbus-sh/worker 0.2.0 → 0.2.2

package/dist/runtime/ruby-resident.js

@@ -0,0 +1,278 @@
+/**
+ * ruby-resident.ts — a Ruby program that keeps serving, as a Durable Object
+ * facet.
+ *
+ * The half of the Ruby runtime that names workerd. Everything about running
+ * the interpreter is in `@nimbus-sh/core`; this is the substrate a program
+ * that outlives its invocation needs — an actor that stays alive between
+ * requests, with inbound HTTP routed into the socket the program bound. A
+ * host without one supplies no {@link RubyResidentStart}, and such a program
+ * is refused rather than quietly run as a one-shot that dies with the call.
+ */
+import { z } from 'zod';
+import { buildRubyPreamble, normalizeRubyFacetResult, } from '@nimbus-sh/core/runtime/ruby-runner.js';
+import { VIRTUAL_SOCKET_KERNEL_SRC } from '@nimbus-sh/core/runtime/virtual-socket-kernel.generated.js';
+const RubySocketProcessBootResponseSchema = z.object({
+    state: z.string().optional(),
+    port: z.number().optional(),
+    stdout: z.string().optional(),
+    stderr: z.string().optional(),
+    result: z.unknown().optional(),
+}).passthrough();
+/**
+ * Start a Ruby program that binds a port as its own process, so it outlives
+ * the invocation that started it.
+ */
+export function rubyResidentStart(facetMgr) {
+    return async function startResidentRuby(args) {
+        const command = args.command;
+        const workerCode = buildRubySocketProcessWorker(buildRubyPreamble());
+        const spawned = await facetMgr.spawnWorker(workerCode, command, args.cwd, {
+            compatibilityFlags: ['nodejs_compat'],
+            // By path, not by value: the image is 34.3 MiB — more than a single RPC
+            // value may carry — so whichever host runs this process reads it itself.
+            vfsWasmModules: { 'ruby+stdlib.wasm': args.wasmVfsPath },
+            startArgs: args.startArgs,
+        }).catch(() => null);
+        if (!spawned) {
+            return { exitCode: 1, stdout: '', stderr: 'ruby process boot failed\n' };
+        }
+        const parsed = RubySocketProcessBootResponseSchema.safeParse(spawned.boot);
+        if (!parsed.success) {
+            facetMgr.finishProcess(spawned.pid, 1, 'ruby process boot failed');
+            return {
+                exitCode: 1,
+                stdout: '',
+                stderr: 'ruby process boot failed\n',
+            };
+        }
+        const boot = parsed.data;
+        if (boot.state === 'listening' && typeof boot.port === 'number' && boot.port > 0) {
+            facetMgr.registerPort(spawned.pid, Number(boot.port));
+            const routeablePorts = await facetMgr.waitForRouteablePorts(spawned.pid);
+            const routeablePort = routeablePorts.includes(Number(boot.port)) ? Number(boot.port) : routeablePorts[0];
+            if (!routeablePort) {
+                facetMgr.kill(spawned.pid);
+                return {
+                    exitCode: 1,
+                    stdout: boot.stdout || '',
+                    stderr: `${boot.stderr || ''}ruby: virtual socket port ${boot.port} failed to attach a route handler\n`,
+                };
+            }
+            return {
+                exitCode: 0,
+                stdout: `${boot.stdout || ''}\x1b[2m[started (long-running): pid=${spawned.pid} cmd="${command}" port=${routeablePort}]\x1b[0m\n`,
+                stderr: boot.stderr || '',
+                spawnedPid: spawned.pid,
+                port: routeablePort,
+            };
+        }
+        const reservedPorts = await facetMgr.waitForRouteablePorts(spawned.pid);
+        if (reservedPorts.length > 0) {
+            return {
+                exitCode: 0,
+                stdout: `${boot.stdout || ''}\x1b[2m[started (long-running): pid=${spawned.pid} cmd="${command}" port=${reservedPorts[0]}]\x1b[0m\n`,
+                stderr: boot.stderr || '',
+                spawnedPid: spawned.pid,
+                port: reservedPorts[0],
+            };
+        }
+        if (boot.state === 'exited') {
+            const result = normalizeRubyFacetResult(boot.result) || {
+                exitCode: 1,
+                stdout: '',
+                stderr: 'ruby process returned an invalid exit payload\n',
+            };
+            facetMgr.finishProcess(spawned.pid, result.exitCode, result.stderr || 'ruby process exited');
+            return {
+                exitCode: result.exitCode,
+                stdout: result.stdout,
+                stderr: result.stderr || result.error || '',
+            };
+        }
+        return {
+            exitCode: 0,
+            stdout: `${boot.stdout || ''}\x1b[2m[started (long-running): pid=${spawned.pid} cmd="${command}"]\x1b[0m\n`,
+            stderr: boot.stderr || '',
+            spawnedPid: spawned.pid,
+        };
+    };
+}
+export function buildRubySocketProcessWorker(preamble) {
+    return [
+        'import { DurableObject } from "cloudflare:workers";',
+        "import __NIMBUS_WASM_ruby_stdlib from './ruby+stdlib.wasm';",
+        'globalThis.__NIMBUS_WASM = globalThis.__NIMBUS_WASM || {};',
+        "globalThis.__NIMBUS_WASM['ruby+stdlib.wasm'] = __NIMBUS_WASM_ruby_stdlib;",
+        '',
+        VIRTUAL_SOCKET_KERNEL_SRC,
+        '',
+        // Listener lifecycle only. Socket bytes never cross this bridge: Ruby opens
+        // both accepted and dialed connections as file descriptors and reads and
+        // writes them as ordinary IO.
+        'globalThis.__nimbusRubySockets = {',
+        '  listen(port) { return globalThis.__nimbusVirtualSockets.listen(Number(port)); },',
+        '  closeListener(port) { globalThis.__nimbusVirtualSockets.closeListener(Number(port)); return true; },',
+        '  pending(port) { return globalThis.__nimbusVirtualSockets.pending(Number(port)); },',
+        '  acceptNowJson(port) { const conn = globalThis.__nimbusVirtualSockets.acceptNow(Number(port)); return conn ? JSON.stringify(conn) : ""; },',
+        '};',
+        '',
+        // Outbound half of the same loopback the shell's curl and node's patched
+        // fetch use: one mechanism, reached here through the supervisor RPC.
+        'globalThis.__nimbusVirtualSocketRouteLoopback = function __nimbusVirtualSocketRouteLoopback(port, request) {',
+        '  const supervisor = globalThis.__nimbusRubySupervisor;',
+        '  if (!supervisor || typeof supervisor.routeLoopback !== "function") {',
+        '    return Promise.reject(new Error("this Ruby process has no supervisor binding for loopback routing"));',
+        '  }',
+        '  return Promise.resolve(supervisor.routeLoopback(Number(port), request));',
+        '};',
+        '',
+        'globalThis.__nimbusVirtualPortRegistrationPromises = globalThis.__nimbusVirtualPortRegistrationPromises || [];',
+        'globalThis.__nimbusVirtualSocketDidListen = function __nimbusVirtualSocketDidListen(port) {',
+        '  const supervisor = globalThis.__nimbusRubySupervisor;',
+        '  if (!supervisor || typeof supervisor.registerPort !== "function") return;',
+        '  try {',
+        '    const p = supervisor.registerPort(Number(port)).catch((e) => {',
+        '      const msg = e && e.message ? e.message : String(e);',
+        '      (globalThis.__nimbusRubyStderr || (globalThis.__nimbusRubyStderr = [])).push("[ruby-runner] port registration failed: " + msg + "\\n");',
+        '    });',
+        '    globalThis.__nimbusVirtualPortRegistrationPromises.push(p);',
+        '  } catch (e) {',
+        '    const msg = e && e.message ? e.message : String(e);',
+        '    (globalThis.__nimbusRubyStderr || (globalThis.__nimbusRubyStderr = [])).push("[ruby-runner] port registration failed: " + msg + "\\n");',
+        '  }',
+        '};',
+        '',
+        preamble,
+        '',
+        // Drive the process when a connection is queued. This is the whole of the
+        // runtime's involvement in serving: it knows nothing about what is
+        // listening, only that the process should run until it parks.
+        //
+        // Steps go through the shared resume queue in the preamble, so a handler
+        // that parks does not stall other connections and no two drivers can enter
+        // a live fiber at once.
+        // Timed work the process still owes: the wall-clock moment its earliest
+        // sleeper is due. It lives on the global rather than in one driver's
+        // closure because no single request may own it. A timer belongs to the
+        // request context that created it, and workerd cancels that timer without
+        // a word when the request ends - so a driver anchored to the first
+        // connection stops dead the moment that connection answers, and every
+        // other connection waits out the response timeout instead.
+        'globalThis.__nimbusRubyWakeAt = globalThis.__nimbusRubyWakeAt || null;',
+        'globalThis.__nimbusRubyIdleDrivers = globalThis.__nimbusRubyIdleDrivers || new Set();',
+        'function __nimbusRubyNoteWake(wakeAfter) {',
+        '  globalThis.__nimbusRubyWakeAt = (wakeAfter === null || wakeAfter === undefined)',
+        '    ? null',
+        '    : Date.now() + Math.max(0, wakeAfter) * 1000;',
+        '  if (globalThis.__nimbusRubyWakeAt === null) return;',
+        '  const waiting = Array.from(globalThis.__nimbusRubyIdleDrivers);',
+        '  globalThis.__nimbusRubyIdleDrivers.clear();',
+        '  for (const wake of waiting) wake();',
+        '}',
+        // So instead every live request drives, for as long as it is live, and the
+        // moment one of them answers the others are already carrying the work.
+        // Steps are serialized by the resume queue, and a driver that wakes to
+        // find the deadline already moved knows another one got there first.
+        'async function __nimbusRubyDrive() {',
+        '  for (;;) {',
+        '    const due = globalThis.__nimbusRubyWakeAt;',
+        '    if (due === null) {',
+        '      // Nothing is due yet. Stay available anyway: this request holds a',
+        '      // live context, and whichever request discovers the next piece of',
+        '      // timed work may answer and be gone before that work comes due.',
+        '      await new Promise((resolve) => globalThis.__nimbusRubyIdleDrivers.add(resolve));',
+        '      continue;',
+        '    }',
+        '    const delay = due - Date.now();',
+        '    if (delay > 0) await new Promise((resolve) => setTimeout(resolve, delay));',
+        '    if (globalThis.__nimbusRubyWakeAt !== due) continue;',
+        '    const step = await globalThis.__nimbusRubyStep();',
+        '    if (!step.resumed || !step.alive) { globalThis.__nimbusRubyWakeAt = null; return; }',
+        '    __nimbusRubyNoteWake(step.wakeAfter);',
+        '  }',
+        '}',
+        'globalThis.__nimbusVirtualSocketRequestQueued = async function __nimbusVirtualSocketRequestQueued(port) {',
+        '  const step = await globalThis.__nimbusRubyStep();',
+        '  if (!step.resumed) return false;',
+        '  __nimbusRubyNoteWake(step.wakeAfter);',
+        '  __nimbusRubyDrive().catch((e) => {',
+        '    (globalThis.__nimbusRubyStderr || (globalThis.__nimbusRubyStderr = [])).push(',
+        '      "[ruby-runner] driving the process failed: " + ((e && e.message) || e) + "\\n");',
+        '  });',
+        '  return true;',
+        '};',
+        '',
+        'async function __nimbusStartRubyProcess(args) {',
+        '  if (!globalThis.__nimbusRubyProcessPromise) {',
+        '    const stdoutStart = (globalThis.__nimbusRubyStdout || []).length;',
+        '    const stderrStart = (globalThis.__nimbusRubyStderr || []).length;',
+        '    globalThis.__nimbusRubyProcessOutputStart = { stdoutStart, stderrStart };',
+        '    globalThis.__nimbusRubyProcessArgs = {',
+        '      userCode: args.userCode,',
+        '      rbArgv: args.rbArgv || [],',
+        '      userEnv: args.userEnv || {},',
+        '      progName: args.progName || "ruby",',
+        '      cwd: args.cwd || "/home/user",',
+        '      fsSnapshot: args.fsSnapshot,',
+        '    };',
+        '    globalThis.__nimbusRubyProcessPromise = globalThis.__rubyRun(globalThis.__nimbusRubyProcessArgs).then((result) => {',
+        '      globalThis.__nimbusRubyProcessResult = result;',
+        '      return result;',
+        '    });',
+        '  }',
+        '  const started = globalThis.__nimbusRubyProcessOutputStart || { stdoutStart: 0, stderrStart: 0 };',
+        '  const listen = globalThis.__nimbusVirtualSockets.waitForListen(10_000).then((port) => ({ state: port ? "listening" : "pending", port }));',
+        '  const exit = globalThis.__nimbusRubyProcessPromise.then((result) => ({ state: "exited", result }));',
+        '  const first = await Promise.race([listen, exit]);',
+        '  const registrations = globalThis.__nimbusVirtualPortRegistrationPromises || [];',
+        '  if (registrations.length > 0) await Promise.allSettled(registrations.splice(0));',
+        '  const stdout = (globalThis.__nimbusRubyStdout || []).slice(started.stdoutStart).join("");',
+        '  const stderr = (globalThis.__nimbusRubyStderr || []).slice(started.stderrStart).join("");',
+        '  if (first.state === "listening") return { state: "listening", port: first.port, stdout, stderr };',
+        '  if (first.state === "exited") return { state: "exited", result: first.result, stdout, stderr };',
+        '  const currentPort = globalThis.__nimbusVirtualSockets.firstListeningPort();',
+        '  if (currentPort) return { state: "listening", port: currentPort, stdout, stderr };',
+        '  return { state: "running", stdout, stderr };',
+        '}',
+        '',
+        // Only adopt a real binding: routed handleHttpRequest/fetch hops resolve
+        // the entrypoint without a supervisor, and overwriting with undefined
+        // would drop the live stub the process needs for its whole lifetime.
+        'function __nimbusAdoptRubySupervisor(env) {',
+        '  const supervisor = env && env.SUPERVISOR;',
+        '  if (supervisor) globalThis.__nimbusRubySupervisor = supervisor;',
+        // The WASI filesystem takes the same stub. That is what turns the
+        // spawn-time seed into a cache over the session VFS, so a server that
+        // never exits still persists its writes instead of losing them entirely.
+        '  __wasiAdoptSupervisor(supervisor);',
+        '}',
+        // A resident process parks between requests, and parking is the only
+        // moment "durable while running" can be made true: by the time the caller
+        // holds a response, everything the request wrote has reached the VFS.
+        'async function __nimbusParkRuby(value) {',
+        // Revalidate drains first, then spends ONE round trip on the subtree
+        // revision. An unchanged subtree keeps the whole cache; a changed one
+        // drops the clean half so the next read sees another process's writes.
+        '  await __wasiRevalidateFS();',
+        '  return value;',
+        '}',
+        'export class NimbusProcess extends DurableObject {',
+        '  async startProcess(args) {',
+        '    __nimbusAdoptRubySupervisor(this.env);',
+        '    return __nimbusParkRuby(await __nimbusStartRubyProcess(args || {}));',
+        '  }',
+        '  async fetch(request) {',
+        '    __nimbusAdoptRubySupervisor(this.env);',
+        '    return this.handleHttpRequest(request);',
+        '  }',
+        '  async handleHttpRequest(request) {',
+        '    __nimbusAdoptRubySupervisor(this.env);',
+        '    const hinted = Number(request.headers.get("X-Nimbus-Port") || 0);',
+        '    const port = hinted || Array.from(globalThis.__nimbusVirtualSockets.listeners.keys())[0];',
+        '    if (!port) return new Response("Nimbus Ruby process has no listening virtual socket", { status: 502 });',
+        '    return __nimbusParkRuby(await globalThis.__nimbusVirtualSockets.handleHttpRequest(port, request));',
+        '  }',
+        '}',
+    ].join('\n');
+}

package/dist/runtime/runtime-catalog.d.ts

@@ -15,17 +15,9 @@
  * Catalog schema (RuntimeCatalog):
  *   { version: 1, runtimes: { <name>: { default, versions: { <ver>: { manifest, manifest_sha256, size_bytes, license } } } } }
  *
- * Manifest schema (RuntimeManifest):
- *   { name, version, license, wasi_namespace,
- *     files: [{ path, content, sha256, size, mode? }],
- *     entrypoints: [{ binName, runner, args[], kind? }],
- *     runtime_artifacts?: [
- *       { path, kind: "workerd-adapter", id, source_sha256?, sha256 },
- *       { path, kind: "python-package", id, language: "python", packageName,
- *         version, abi, pyodideVersion, pythonVersion, wheelFileName,
- *         wheelSha256, loadMode: "startup-module", imports[], dependencies[],
- *         extensionModules[] }
- *     ] }
+ * Manifest schema: `@nimbus-sh/core` runtime/runtime-manifest.ts. What a
+ * runtime IS does not depend on which tier served it, so this module only
+ * fetches and verifies manifests; it does not describe them.
  *
  * R2 and Cache API failures throw; the shell verb formats the diagnostic for
  * the user.
@@ -53,8 +45,7 @@
  * that happens — there is no "trust the key instead" fallback. That also
  * makes a stale pin a cache miss rather than an outage.
  */
-import { z } from 'zod/v4';
-import { PYODIDE_PACKAGE_ABI } from '@nimbus-sh/core/runtime/os-contracts.js';
+import { type ManifestFile, type RuntimeManifest } from '@nimbus-sh/core/runtime/runtime-manifest.js';
 /** Minimal R2Bucket shape we depend on. */
 type R2BucketLike = {
     get(key: string): Promise<{
@@ -82,74 +73,7 @@ export interface RuntimeCatalog {
     version: 1;
     runtimes: Record<string, CatalogRuntimeEntry>;
 }
-export interface ManifestFile {
-    /** VFS path relative to ~/.nimbus/runtimes/<name>/<version>/. */
-    path: string;
-    /** R2 key for the content blob. */
-    content: string;
-    /** Hex sha256 of the content blob bytes. */
-    sha256: string;
-    /** Byte size. */
-    size: number;
-    /** Optional file mode hint ("exec" → registered as a shell bin). */
-    mode?: 'exec';
-}
-export interface ManifestEntrypoint {
-    /** Shell command name. */
-    binName: string;
-    /** Runner key (e.g. "clang-runner") — package manager dispatches to
-     *  the right runner factory by this. */
-    runner: string;
-    /** Default args prepended to user args at invocation. */
-    args: string[];
-    /** Optional secondary classification (e.g. "linker" for wasm-ld). */
-    kind?: string;
-}
-export interface RuntimeArtifactMetadata {
-    path: string;
-    kind: string;
-    id: string;
-    source_sha256?: string;
-    sha256: string;
-}
-export type RuntimePythonPackageAbi = typeof PYODIDE_PACKAGE_ABI;
-export interface RuntimePythonExtensionModuleMetadata {
-    /** Path inside Python site-packages, as stored in the wheel. */
-    path: string;
-    /** Path inside the installed Nimbus runtime root. */
-    runtimePath: string;
-    sha256: string;
-}
-export interface RuntimePythonPackageArtifactMetadata extends RuntimeArtifactMetadata {
-    kind: 'python-package';
-    language: 'python';
-    packageName: string;
-    version: string;
-    abi: RuntimePythonPackageAbi;
-    pyodideVersion: string;
-    pythonVersion: string;
-    wheelFileName: string;
-    wheelSha256: string;
-    loadMode: 'startup-module';
-    imports: string[];
-    dependencies: string[];
-    extensionModules: RuntimePythonExtensionModuleMetadata[];
-}
-export interface RuntimeManifest {
-    name: string;
-    version: string;
-    license: string;
-    /** Which WASI namespace the binaries import — `wasi_unstable` for
-     *  binji clang. `null` for non-WASI runtimes (e.g. Pyodide). */
-    wasi_namespace: string | null;
-    files: ManifestFile[];
-    entrypoints: ManifestEntrypoint[];
-    runtime_artifacts?: RuntimeArtifactMetadata[];
-}
-export declare const RuntimePythonPackageArtifactMetadataSchema: z.ZodType<RuntimePythonPackageArtifactMetadata>;
 export declare function parseRuntimeCatalog(value: unknown): RuntimeCatalog;
-export declare function parseRuntimeManifest(value: unknown): RuntimeManifest;
-export declare function isRuntimePythonPackageArtifactMetadata(artifact: RuntimeArtifactMetadata): artifact is RuntimePythonPackageArtifactMetadata;
 /**
  * Fetch the top-level catalog, verified against the build-time pin.
  *

package/dist/runtime/runtime-catalog.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"runtime-catalog.d.ts","sourceRoot":"","sources":["../../src/runtime/runtime-catalog.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"runtime-catalog.d.ts","sourceRoot":"","sources":["../../src/runtime/runtime-catalog.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AAKH,OAAO,EAGL,KAAK,YAAY,EACjB,KAAK,eAAe,EACrB,MAAM,6CAA6C,CAAC;AAErD,2CAA2C;AAC3C,KAAK,YAAY,GAAG;IAClB,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;QACxB,WAAW,IAAI,OAAO,CAAC,WAAW,CAAC,CAAC;QACpC,IAAI,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;KACzB,GAAG,IAAI,CAAC,CAAC;CACX,GAAG,IAAI,GAAG,SAAS,CAAC;AAErB,8CAA8C;AAC9C,MAAM,WAAW,iBAAiB;IAChC,oBAAoB,CAAC,EAAE,YAAY,CAAC;CACrC;AAID,MAAM,WAAW,mBAAmB;IAClC,QAAQ,EAAE,MAAM,CAAC;IACjB;2EACuE;IACvE,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,mBAAmB,CAAC,CAAC;CAC/C;AAED,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,CAAC,CAAC;IACX,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,mBAAmB,CAAC,CAAC;CAC/C;AAiBD,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,cAAc,CAElE;AA4DD;;;;;;;GAOG;AACH,wBAAsB,YAAY,CAAC,GAAG,EAAE,iBAAiB,GAAG,OAAO,CAAC,cAAc,CAAC,CAuBlF;AAED;;;;;;;GAOG;AACH,wBAAsB,aAAa,CACjC,GAAG,EAAE,iBAAiB,EACtB,KAAK,EAAE,mBAAmB,GACzB,OAAO,CAAC,eAAe,CAAC,CA8B1B;AAED;;;;;;;;GAQG;AACH,wBAAsB,SAAS,CAC7B,GAAG,EAAE,iBAAiB,EACtB,IAAI,EAAE,YAAY,GACjB,OAAO,CAAC,UAAU,CAAC,CA4BrB"}

package/dist/runtime/runtime-catalog.js

@@ -15,17 +15,9 @@
  * Catalog schema (RuntimeCatalog):
  *   { version: 1, runtimes: { <name>: { default, versions: { <ver>: { manifest, manifest_sha256, size_bytes, license } } } } }
  *
- * Manifest schema (RuntimeManifest):
- *   { name, version, license, wasi_namespace,
- *     files: [{ path, content, sha256, size, mode? }],
- *     entrypoints: [{ binName, runner, args[], kind? }],
- *     runtime_artifacts?: [
- *       { path, kind: "workerd-adapter", id, source_sha256?, sha256 },
- *       { path, kind: "python-package", id, language: "python", packageName,
- *         version, abi, pyodideVersion, pythonVersion, wheelFileName,
- *         wheelSha256, loadMode: "startup-module", imports[], dependencies[],
- *         extensionModules[] }
- *     ] }
+ * Manifest schema: `@nimbus-sh/core` runtime/runtime-manifest.ts. What a
+ * runtime IS does not depend on which tier served it, so this module only
+ * fetches and verifies manifests; it does not describe them.
  *
  * R2 and Cache API failures throw; the shell verb formats the diagnostic for
  * the user.
@@ -56,8 +48,7 @@
 import { z } from 'zod/v4';
 import { sha256Hex } from '@nimbus-sh/core/_shared/crypto.js';
 import { RUNTIME_CATALOG_SHA256 } from '../runtime-catalog.generated.js';
-import { PYODIDE_PACKAGE_ABI } from '@nimbus-sh/core/runtime/os-contracts.js';
-const HexSha256Schema = z.string().regex(/^[a-f0-9]{64}$/);
+import { HexSha256Schema, parseRuntimeManifest, } from '@nimbus-sh/core/runtime/runtime-manifest.js';
 const CatalogVersionEntrySchema = z.object({
     manifest: z.string().min(1),
     manifest_sha256: HexSha256Schema.optional(),
@@ -71,63 +62,9 @@ const RuntimeCatalogSchema = z.object({
         versions: z.record(z.string(), CatalogVersionEntrySchema),
     })),
 });
-const ManifestFileSchema = z.object({
-    path: z.string().min(1),
-    content: z.string().min(1),
-    sha256: HexSha256Schema,
-    size: z.number().int().nonnegative(),
-    mode: z.literal('exec').optional(),
-});
-const ManifestEntrypointSchema = z.object({
-    binName: z.string().min(1),
-    runner: z.string().min(1),
-    args: z.array(z.string()),
-    kind: z.string().optional(),
-});
-const RuntimeArtifactMetadataSchema = z.object({
-    path: z.string().min(1),
-    kind: z.string().min(1),
-    id: z.string().min(1),
-    source_sha256: HexSha256Schema.optional(),
-    sha256: HexSha256Schema,
-}).passthrough();
-export const RuntimePythonPackageArtifactMetadataSchema = RuntimeArtifactMetadataSchema.and(z.object({
-    kind: z.literal('python-package'),
-    language: z.literal('python'),
-    packageName: z.string().min(1),
-    version: z.string().min(1),
-    abi: z.literal(PYODIDE_PACKAGE_ABI),
-    pyodideVersion: z.string().min(1),
-    pythonVersion: z.string().min(1),
-    wheelFileName: z.string().min(1),
-    wheelSha256: HexSha256Schema,
-    loadMode: z.literal('startup-module'),
-    imports: z.array(z.string()),
-    dependencies: z.array(z.string()),
-    extensionModules: z.array(z.object({
-        path: z.string().min(1),
-        runtimePath: z.string().min(1),
-        sha256: HexSha256Schema,
-    })),
-}));
-const RuntimeManifestSchema = z.object({
-    name: z.string().min(1),
-    version: z.string().min(1),
-    license: z.string(),
-    wasi_namespace: z.string().nullable(),
-    files: z.array(ManifestFileSchema),
-    entrypoints: z.array(ManifestEntrypointSchema),
-    runtime_artifacts: z.array(RuntimeArtifactMetadataSchema).optional(),
-});
 export function parseRuntimeCatalog(value) {
     return RuntimeCatalogSchema.parse(value);
 }
-export function parseRuntimeManifest(value) {
-    return RuntimeManifestSchema.parse(value);
-}
-export function isRuntimePythonPackageArtifactMetadata(artifact) {
-    return RuntimePythonPackageArtifactMetadataSchema.safeParse(artifact).success;
-}
 // ── L2 content addressing ────────────────────────────────────────────
 /** R2 key of the top-level catalog. */
 const CATALOG_R2_KEY = 'catalog/v1.json';

package/dist/session/init.d.ts

@@ -3,12 +3,21 @@
  *
  * Why this is one big function and not a class:
  * initSession runs once per /ws upgrade and walks the session
- * through Phase R (rehydrate from SQL), Phase B (build kernel +
- * shell + register commands), Phase W (attach terminal), and
- * (cold-only) Phase O (MOTD + framework hint). The phases share
- * lots of locals (vfs, kernel, registry, shell) and ordering
- * matters strictly — there's no interesting reuse boundary that a
- * class decomposition would expose.
+ * through Phase R (rehydrate from SQL), Phase B (compose the
+ * workspace + register the session's commands), Phase W (attach
+ * terminal), and (cold-only) Phase O (MOTD + framework hint). The
+ * phases share lots of locals (vfs, kernel, registry, shell) and
+ * ordering matters strictly — there's no interesting reuse boundary
+ * that a class decomposition would expose.
+ *
+ * What it no longer does is COMPOSE the operating system. The kernel,
+ * the provider mounts, the command registry, the coreutils, the exec
+ * resolver, the default environment and the shell come from
+ * `NimbusWorkspace` (@nimbus-sh/core/workspace), which an embedder off
+ * Cloudflare builds the same way. What stays here is everything that
+ * only makes sense with a socket, a Durable Object and a product behind
+ * it: the terminal and its scrollback, the phase machine, the persisted
+ * shell state, npm, git, vite, wrangler and the facet-backed runtimes.
  *
  * The function is intentionally written so that a reader sees:
  *   1. setPhase('rehydrate') ...
@@ -38,6 +47,6 @@ type InitHost = SessionInternal & {
     readonly ctx: any;
     readonly env: any;
 };
-export declare function initSession(self: InitHost, ws: WebSocket): void;
+export declare function initSession(self: InitHost, ws: WebSocket): Promise<void>;
 export {};
 //# sourceMappingURL=init.d.ts.map

package/dist/session/init.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../src/session/init.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAkFH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAErD;;;;;;;;GAQG;AACH,KAAK,QAAQ,GAAG,eAAe,GAAG;IAAE,QAAQ,CAAC,GAAG,EAAE,GAAG,CAAC;IAAC,QAAQ,CAAC,GAAG,EAAE,GAAG,CAAA;CAAE,CAAC;AAa3E,wBAAgB,WAAW,CAAC,IAAI,EAAE,QAAQ,EAAE,EAAE,EAAE,SAAS,GAAG,IAAI,CAivF/D"}
+{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../src/session/init.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AA6EH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAErD;;;;;;;;GAQG;AACH,KAAK,QAAQ,GAAG,eAAe,GAAG;IAAE,QAAQ,CAAC,GAAG,EAAE,GAAG,CAAC;IAAC,QAAQ,CAAC,GAAG,EAAE,GAAG,CAAA;CAAE,CAAC;AAa3E,wBAAsB,WAAW,CAAC,IAAI,EAAE,QAAQ,EAAE,EAAE,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CAsrF9E"}