@nimbus-sh/worker 0.9.0 → 0.11.0

package/dist/runtime/ruby-resident.js

@@ -13,7 +13,7 @@ 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(),
+    state: z.enum(['listening', 'exited']),
     port: z.number().optional(),
     stdout: z.string().optional(),
     stderr: z.string().optional(),
@@ -35,7 +35,11 @@ export function rubyResidentStart(facetMgr) {
             // value may carry — so whichever host runs this process reads it itself.
             vfsWasmModules: { 'ruby+stdlib.wasm': args.wasmVfsPath },
             startArgs: args.startArgs,
+            foreground: { signal: args.signal, write: args.write },
         }).catch(() => null);
+        // Interrupted while it waited to bind or exit: the process is gone with it.
+        if (args.signal.aborted)
+            return { exitCode: 130, stdout: '', stderr: '' };
         if (!spawned) {
             return { exitCode: 1, stdout: '', stderr: 'ruby process boot failed\n' };
         }
@@ -69,34 +73,16 @@ export function rubyResidentStart(facetMgr) {
                 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 || '',
-            };
-        }
+        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: 0,
-            stdout: `${boot.stdout || ''}\x1b[2m[started (long-running): pid=${spawned.pid} cmd="${command}"]\x1b[0m\n`,
-            stderr: boot.stderr || '',
-            spawnedPid: spawned.pid,
+            exitCode: result.exitCode,
+            stdout: result.stdout,
+            stderr: result.stderr || result.error || '',
         };
     };
 }
@@ -205,6 +191,19 @@ export function buildRubySocketProcessWorker(preamble) {
         '  return true;',
         '};',
         '',
+        // What the process writes goes out as it is written: to the command that
+        // launched it while that command waits, to the process log after. One
+        // write at a time, in order; the runner's own markers are not output.
+        'globalThis.__nimbusRubyEmitChain = globalThis.__nimbusRubyEmitChain || Promise.resolve();',
+        'globalThis.__nimbusRubyEmit = function __nimbusRubyEmit(stream, text) {',
+        '  const supervisor = globalThis.__nimbusRubySupervisor;',
+        '  if (!supervisor) return;',
+        '  const clean = String(text).replace(/__NIMBUS_RESUMED_(true|false)_[^\\n]*\\n?/g, "").replace(/__NIMBUS_RUBY_EXIT_-?\\d+\\n?/g, "");',
+        '  if (!clean) return;',
+        '  const bytes = new TextEncoder().encode(clean);',
+        '  globalThis.__nimbusRubyEmitChain = globalThis.__nimbusRubyEmitChain.then(() => supervisor[stream](bytes)).catch(() => {});',
+        '};',
+        '',
         'async function __nimbusStartRubyProcess(args) {',
         '  if (!globalThis.__nimbusRubyProcessPromise) {',
         '    const stdoutStart = (globalThis.__nimbusRubyStdout || []).length;',
@@ -216,7 +215,6 @@ export function buildRubySocketProcessWorker(preamble) {
         '      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;',
@@ -224,18 +222,20 @@ export function buildRubySocketProcessWorker(preamble) {
         '    });',
         '  }',
         '  const started = globalThis.__nimbusRubyProcessOutputStart || { stdoutStart: 0, stderrStart: 0 };',
-        '  const listen = globalThis.__nimbusVirtualSockets.waitForListen(10_000).then((port) => ({ state: port ? "listening" : "pending", port }));',
+        // No deadline: a server reports once it binds, however long its requires take.
+        '  const listen = globalThis.__nimbusVirtualSockets.waitForListen().then((port) => ({ state: "listening", 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("");',
+        // Streamed already, so the answer carries none of it.
+        '  await globalThis.__nimbusRubyEmitChain;',
+        '  const streamed = !!globalThis.__nimbusRubySupervisor;',
+        '  const stdout = streamed ? "" : (globalThis.__nimbusRubyStdout || []).slice(started.stdoutStart).join("");',
+        '  const stderr = streamed ? "" : (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 };',
+        '  const result = streamed ? { ...first.result, stdout: "", stderr: "" } : first.result;',
+        '  return { state: "exited", result, stdout, stderr };',
         '}',
         '',
         // Only adopt a real binding: routed handleHttpRequest/fetch hops resolve
@@ -244,25 +244,15 @@ export function buildRubySocketProcessWorker(preamble) {
         '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.
+        // The WASI filesystem takes the same stub: every file syscall the server
+        // makes reads and writes the session VFS directly, so a server that never
+        // exits has nothing to flush between requests.
         '  __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 || {}));',
+        '    return __nimbusStartRubyProcess(args || {});',
         '  }',
         '  async fetch(request) {',
         '    __nimbusAdoptRubySupervisor(this.env);',
@@ -273,7 +263,7 @@ export function buildRubySocketProcessWorker(preamble) {
         '    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));',
+        '    return globalThis.__nimbusVirtualSockets.handleHttpRequest(port, request);',
         '  }',
         '}',
     ].join('\n');

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

@@ -53,6 +53,7 @@ type R2BucketLike = {
     get(key: string): Promise<{
         arrayBuffer(): Promise<ArrayBuffer>;
         text(): Promise<string>;
+        readonly body: ReadableStream<Uint8Array>;
     } | null>;
 } | null | undefined;
 /** Minimal env shape this module consumes. */
@@ -95,15 +96,21 @@ export declare function fetchCatalog(env: RuntimeCatalogEnv): Promise<RuntimeCat
  */
 export declare function fetchManifest(env: RuntimeCatalogEnv, entry: CatalogVersionEntry): Promise<RuntimeManifest>;
 /**
- * Fetch the blob a manifest file entry points at, verified against the
- * digest that same entry carries.
+ * Stream the blob a manifest file entry points at, verified against the
+ * digest that same entry carries: from the colo cache when it has it, else
+ * from R2, read once either way. The stream errors at its end, rather than
+ * closing, with a {@link RuntimeBlobDigestMismatch} when its bytes do not
+ * hash to the digest; a colo-cache entry that fails is evicted and
+ * distrusted first, so the installer's second read of that blob comes from
+ * R2 whatever the cache holds by then. The installer commits
+ * a blob only after that clean close, so no step holds a blob whole.
  *
  * The digest is not optional and does not travel separately from the key:
  * a `ManifestFile` always has both, and it is the only thing this takes.
  * Blobs are interpreters, so an unverified read here is arbitrary code
  * execution in whichever session installs it.
  */
-export declare function fetchBlob(env: RuntimeCatalogEnv, file: ManifestFile): Promise<Uint8Array>;
+export declare function fetchBlob(env: RuntimeCatalogEnv, file: ManifestFile): Promise<ReadableStream<Uint8Array>>;
 export declare function runtimeAbiForCatalogName(name: string): RuntimePackageAbi;
 /**
  * The R2 catalog as a core `RuntimeSource` — the worker adapter half of the

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":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AAKH,OAAO,EAGL,KAAK,YAAY,EACjB,KAAK,eAAe,EACrB,MAAM,6CAA6C,CAAC;AAErD,OAAO,EAKL,KAAK,aAAa,EACnB,MAAM,4CAA4C,CAAC;AACpD,OAAO,EAGL,KAAK,iBAAiB,EACvB,MAAM,yCAAyC,CAAC;AAEjD,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;AAID,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,MAAM,GAAG,iBAAiB,CAExE;AAED;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,iBAAiB,GAAG,aAAa,CAwE1E"}
+{"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,OAAO,EAOL,KAAK,aAAa,EACnB,MAAM,4CAA4C,CAAC;AACpD,OAAO,EAGL,KAAK,iBAAiB,EACvB,MAAM,yCAAyC,CAAC;AAEjD,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;QACxB,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC,UAAU,CAAC,CAAC;KAC3C,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;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,SAAS,CAC7B,GAAG,EAAE,iBAAiB,EACtB,IAAI,EAAE,YAAY,GACjB,OAAO,CAAC,cAAc,CAAC,UAAU,CAAC,CAAC,CA8BrC;AA2DD,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,MAAM,GAAG,iBAAiB,CAExE;AAED;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,iBAAiB,GAAG,aAAa,CAwE1E"}

package/dist/runtime/runtime-catalog.js

@@ -46,11 +46,11 @@
  * makes a stale pin a cache miss rather than an outage.
  */
 import { z } from 'zod/v4';
-import { sha256Hex } from '@nimbus-sh/core/_shared/crypto.js';
+import { sha256Hex, sha256Incremental } from '@nimbus-sh/core/_shared/crypto.js';
 import { RUNTIME_CATALOG_SHA256 } from '../runtime-catalog.generated.js';
 import { HexSha256Schema, parseRuntimeManifest, } from '@nimbus-sh/core/runtime/runtime-manifest.js';
 import { runtimeEntrypoints } from '@nimbus-sh/core/runtime/installed-runtimes.js';
-import { splitRuntimeSpec, SUPERSEDED_RUNTIMES, } from '@nimbus-sh/core/runtime/runtime-package.js';
+import { blobPieces, RuntimeBlobDigestMismatch, splitRuntimeSpec, SUPERSEDED_RUNTIMES, } from '@nimbus-sh/core/runtime/runtime-package.js';
 import { NIMBUS_RUNTIME_ABIS, NATIVE_UNSUPPORTED_ABI, } from '@nimbus-sh/core/runtime/os-contracts.js';
 const CatalogVersionEntrySchema = z.object({
     manifest: z.string().min(1),
@@ -162,8 +162,14 @@ export async function fetchManifest(env, entry) {
     return parseRuntimeManifest(parseJsonBytes(bytes));
 }
 /**
- * Fetch the blob a manifest file entry points at, verified against the
- * digest that same entry carries.
+ * Stream the blob a manifest file entry points at, verified against the
+ * digest that same entry carries: from the colo cache when it has it, else
+ * from R2, read once either way. The stream errors at its end, rather than
+ * closing, with a {@link RuntimeBlobDigestMismatch} when its bytes do not
+ * hash to the digest; a colo-cache entry that fails is evicted and
+ * distrusted first, so the installer's second read of that blob comes from
+ * R2 whatever the cache holds by then. The installer commits
+ * a blob only after that clean close, so no step holds a blob whole.
  *
  * The digest is not optional and does not travel separately from the key:
  * a `ManifestFile` always has both, and it is the only thing this takes.
@@ -175,9 +181,15 @@ export async function fetchBlob(env, file) {
     if (!address) {
         throw new Error(`manifest entry ${file.path} has no usable sha256 (${file.sha256})`);
     }
-    const cached = await l2Get(address);
-    if (cached)
-        return cached;
+    const cached = l2Distrusted.has(address.sha256) ? null : await l2GetBody(address);
+    if (cached) {
+        return verifiedRead(address, cached, null, async (actual) => {
+            l2Distrusted.add(address.sha256);
+            await l2Evict(address);
+            return `sha256 mismatch for blob ${file.content}: manifest expects ${address.sha256}, `
+                + `the colo cache held ${actual} and was evicted`;
+        });
+    }
     const r2 = env.NIMBUS_RUNTIME_CACHE;
     if (!r2) {
         throw new Error('NIMBUS_RUNTIME_CACHE binding missing — blob cannot be fetched');
@@ -186,14 +198,59 @@ export async function fetchBlob(env, file) {
     if (!obj) {
         throw new Error(`blob ${file.content} not in R2 — manifest references a missing blob`);
     }
-    const bytes = new Uint8Array(await obj.arrayBuffer());
-    const verified = await verifyBytes(address, bytes);
-    if (!verified) {
-        throw new Error(`sha256 mismatch for blob ${file.content}: manifest expects ${address.sha256}, ` +
-            `R2 holds ${await sha256Hex(bytes)}`);
-    }
-    await l2Put(verified, 'application/octet-stream');
-    return verified.bytes;
+    return verifiedRead(address, obj.body, l2FillWriter(address), (actual) => `sha256 mismatch for blob ${file.content}: manifest expects ${address.sha256}, R2 holds ${actual}`);
+}
+/**
+ * `body` as a stream that errors at its end, with a
+ * {@link RuntimeBlobDigestMismatch}, rather than closing, unless it hashed to
+ * `address`. It is read once. When `fill` is given, the same read feeds L2:
+ * each piece reaches the cache before the consumer, and the cache entry is
+ * closed only after the digest matched; a mismatch, a failed read or an
+ * abandoned stream aborts it, and an aborted body stores nothing. The
+ * cache's own pace bounds the pair, so neither side buffers what the other
+ * lags by.
+ */
+function verifiedRead(address, body, fill, mismatch) {
+    const pieces = blobPieces(body);
+    const digest = sha256Incremental();
+    const drop = (reason) => {
+        fill?.abort(reason).catch(() => { });
+        fill = null;
+    };
+    return new ReadableStream({
+        async pull(controller) {
+            try {
+                const next = await pieces.next();
+                if (next.done) {
+                    const actual = await digest.hex();
+                    if (actual !== address.sha256)
+                        throw new RuntimeBlobDigestMismatch(await mismatch(actual));
+                    fill?.close().catch(() => { });
+                    controller.close();
+                    return;
+                }
+                await digest.update(next.value);
+                if (fill) {
+                    try {
+                        await fill.ready;
+                        fill.write(next.value).catch(() => { });
+                    }
+                    catch (error) {
+                        drop(error);
+                    }
+                }
+                controller.enqueue(next.value);
+            }
+            catch (error) {
+                drop(error);
+                throw error;
+            }
+        },
+        async cancel(reason) {
+            drop(reason);
+            await pieces.return(undefined);
+        },
+    }, { highWaterMark: 0 });
 }
 // ── RuntimeSource ────────────────────────────────────────────────────
 export function runtimeAbiForCatalogName(name) {
@@ -314,6 +371,59 @@ async function l2Put(verified, contentType) {
     }
     catch { /* best-effort */ }
 }
+/**
+ * The body of the blob entry at `address`, or null on a miss or a stripped
+ * Cache API. Unverified: served only through {@link verifiedRead}, whose
+ * mismatch evicts it and sends later reads of that blob to R2. Hashing an entry before serving it would read every
+ * blob from the cache twice, which was most of an install's time.
+ */
+async function l2GetBody(address) {
+    try {
+        const caches = globalThis.caches;
+        if (!caches?.default)
+            return null;
+        const hit = await caches.default.match(new Request(l2Url(address)));
+        return hit?.ok && hit.body ? hit.body : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Blob digests whose colo-cache entry failed verification in this isolate.
+ * Their reads go to R2 from then on: a purge lands some time after it is
+ * asked for, and a shared cache can be poisoned again, so the installer's
+ * second read of a failed blob must not depend on either.
+ */
+const l2Distrusted = new Set();
+/** Drop the entry at `address` from the colo cache for other isolates. */
+async function l2Evict(address) {
+    try {
+        await globalThis.caches?.default?.delete(new Request(l2Url(address)));
+    }
+    catch { /* best-effort */ }
+}
+/** A writer whose bytes become the L2 entry at `address` when it closes;
+ *  aborting it stores nothing. Null where there is no cache. */
+function l2FillWriter(address) {
+    try {
+        const caches = globalThis.caches;
+        if (!caches?.default)
+            return null;
+        const { readable, writable } = new TransformStream();
+        const resp = new Response(readable, {
+            headers: {
+                'Content-Type': 'application/octet-stream',
+                'Cache-Control': 'public, max-age=31536000, immutable',
+            },
+        });
+        caches.default.put(new Request(l2Url(address)), resp).catch(() => { });
+        return writable.getWriter();
+    }
+    catch {
+        return null;
+    }
+}
 function l2Url(address) {
     return `${L2_NS}/${address.scope}/${address.sha256}`;
 }

package/dist/runtime/sqlite-wasm-bytes.d.ts

@@ -10,10 +10,10 @@
  * via its `instantiateWasm` hook with that pre-compiled module —
  * request-time WebAssembly.compile(bytes) is blocked inside facets.
  *
- * Mirrors esbuild-wasm-bytes.ts: NO module-scope cache (no supervisor
- * residency), L2 colo cache via caches.default keyed by the version-pinned
- * asset URL, ASSETS as the source of truth, and a sha-256 integrity check on
- * both tiers so a stale or tampered asset never gets compiled.
+ * NO module-scope cache (no supervisor residency). The read itself is
+ * runtime/staged-source.ts: L2 keyed by the version-pinned asset URL, ASSETS
+ * as the source of truth, and a sha-256 check on both tiers so a stale or
+ * tampered asset never gets compiled.
  */
 /**
  * Path inside env.ASSETS where the sql.js wasm binary lives. Versioned so

package/dist/runtime/sqlite-wasm-bytes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sqlite-wasm-bytes.d.ts","sourceRoot":"","sources":["../../src/runtime/sqlite-wasm-bytes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAOH;;;;;GAKG;AACH,eAAO,MAAM,sBAAsB,+BAAyC,CAAC;AAE7E,kEAAkE;AAClE,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE;QAAE,KAAK,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAA;KAAE,CAAC;CACpD;AAED;;;GAGG;AACH,eAAO,MAAM,kBAAkB,2DAAqE,CAAC;AAErG;;;;;;GAMG;AACH,wBAAsB,oBAAoB,CAAC,GAAG,EAAE,kBAAkB,GAAG,OAAO,CAAC,WAAW,CAAC,CAwDxF"}
+{"version":3,"file":"sqlite-wasm-bytes.d.ts","sourceRoot":"","sources":["../../src/runtime/sqlite-wasm-bytes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAMH;;;;;GAKG;AACH,eAAO,MAAM,sBAAsB,+BAAyC,CAAC;AAE7E,kEAAkE;AAClE,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE;QAAE,KAAK,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAA;KAAE,CAAC;CACpD;AAED;;;GAGG;AACH,eAAO,MAAM,kBAAkB,2DAAqE,CAAC;AAErG;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,kBAAkB,GAAG,OAAO,CAAC,WAAW,CAAC,CAElF"}

package/dist/runtime/sqlite-wasm-bytes.js

@@ -10,15 +10,14 @@
  * via its `instantiateWasm` hook with that pre-compiled module —
  * request-time WebAssembly.compile(bytes) is blocked inside facets.
  *
- * Mirrors esbuild-wasm-bytes.ts: NO module-scope cache (no supervisor
- * residency), L2 colo cache via caches.default keyed by the version-pinned
- * asset URL, ASSETS as the source of truth, and a sha-256 integrity check on
- * both tiers so a stale or tampered asset never gets compiled.
+ * NO module-scope cache (no supervisor residency). The read itself is
+ * runtime/staged-source.ts: L2 keyed by the version-pinned asset URL, ASSETS
+ * as the source of truth, and a sha-256 check on both tiers so a stale or
+ * tampered asset never gets compiled.
  */
 import { SQLJS_VERSION } from '@nimbus-sh/core/constants.js';
 import { SQLITE_WASM_SHA256 } from '../sqlite-wasm-bundle.generated.js';
-import { disposeRpcResource } from '@nimbus-sh/platform/rpc-dispose.js';
-import { sha256Hex } from '@nimbus-sh/core/_shared/crypto.js';
+import { fetchStagedBytes } from './staged-source.js';
 /**
  * Path inside env.ASSETS where the sql.js wasm binary lives. Versioned so
  * a future sql.js bump produces a different asset name and forces a fresh
@@ -38,55 +37,20 @@ export const SQLITE_WASM_L2_KEY = `https://nimbus-cache.invalid/_assets/sqljs-${
  * failures are silent — ASSETS is always the source of truth. A non-200
  * from ASSETS, or a digest mismatch on either tier, throws.
  */
-export async function fetchSqliteWasmBytes(env) {
-    const caches = globalThis.caches;
-    // ── L2 fast path ────────────────────────────────────────────────
-    let ab = null;
-    try {
-        if (caches?.default) {
-            const hit = await caches.default.match(new Request(SQLITE_WASM_L2_KEY));
-            if (hit && hit.ok)
-                ab = await hit.arrayBuffer();
-        }
-    }
-    catch { /* fall through to ASSETS */ }
-    const fromCache = ab !== null;
-    if (!ab) {
-        // ── ASSETS path ───────────────────────────────────────────────
-        const url = `https://nimbus-internal.invalid${SQLITE_WASM_ASSET_PATH}`;
-        const res = await env.ASSETS.fetch(new Request(url));
-        try {
-            if (!res.ok) {
-                throw new Error(`sql.js wasm asset fetch failed: ${res.status} ${res.statusText} ` +
-                    `for ${SQLITE_WASM_ASSET_PATH} — deploy is missing the wasm asset`);
-            }
-            ab = await res.arrayBuffer();
-        }
-        finally {
-            disposeRpcResource(res);
-        }
-    }
-    const digest = await sha256Hex(ab);
-    if (digest !== SQLITE_WASM_SHA256) {
-        throw new Error(`sql.js wasm integrity check failed: expected ${SQLITE_WASM_SHA256}, got ` +
-            `${digest} (${fromCache ? 'L2 cache' : 'ASSETS'}) for ${SQLITE_WASM_ASSET_PATH} — ` +
-            'the staged asset is corrupt or out of sync; rerun ' +
-            'scripts/bundle-sqlite-wasm.mjs and redeploy');
-    }
-    // ── L2 write-back (best-effort) ─────────────────────────────────
-    if (!fromCache) {
-        try {
-            if (caches?.default) {
-                const writeBack = new Response(new Uint8Array(ab), {
-                    headers: {
-                        'Content-Type': 'application/wasm',
-                        'Cache-Control': 'public, max-age=31536000, immutable',
-                    },
-                });
-                await caches.default.put(new Request(SQLITE_WASM_L2_KEY), writeBack);
-            }
-        }
-        catch { /* silent */ }
-    }
-    return ab;
+export function fetchSqliteWasmBytes(env) {
+    return fetchStagedBytes(env, SQLITE_WASM_ASSET);
 }
+const SQLITE_WASM_ASSET = {
+    path: SQLITE_WASM_ASSET_PATH,
+    l2Key: SQLITE_WASM_L2_KEY,
+    sha256: SQLITE_WASM_SHA256,
+    contentType: 'application/wasm',
+    poisonedCache: 'reject',
+    missingBinding: `Nimbus: node:sqlite requires an env.ASSETS binding (serves ${SQLITE_WASM_ASSET_PATH})`,
+    fetchFailed: (res) => `sql.js wasm asset fetch failed: ${res.status} ${res.statusText} ` +
+        `for ${SQLITE_WASM_ASSET_PATH} — deploy is missing the wasm asset`,
+    integrityFailed: (digest, from) => `sql.js wasm integrity check failed: expected ${SQLITE_WASM_SHA256}, got ` +
+        `${digest} (${from}) for ${SQLITE_WASM_ASSET_PATH} — ` +
+        'the staged asset is corrupt or out of sync; rerun ' +
+        'scripts/bundle-sqlite-wasm.mjs and redeploy',
+};

package/dist/runtime/staged-source.d.ts

@@ -0,0 +1,67 @@
+/**
+ * staged-source.ts — the one supervisor-side read of a build artifact a bundle
+ * script staged under public/_assets/ instead of inlining it in the Worker
+ * bundle (wasm modules, facet source texts).
+ *
+ * The staging script pins each artifact by sha-256 in a `.generated.ts`. This
+ * module reads it through L2 (caches.default) under a key that changes with
+ * the bytes, with ASSETS as the source of truth, and hands out nothing that
+ * fails the pinned digest: a stale or partial asset never reaches workerd's
+ * loader or a facet. L2 is written only with verified bytes read from ASSETS.
+ *
+ * Artifacts differ only in what they name in errors and in what a bad L2 entry
+ * means to their caller (`poisonedCache`), so each passes those in.
+ */
+/** Minimal env shape — any env with an ASSETS Fetcher binding. */
+export interface StagedSourceEnv {
+    ASSETS?: {
+        fetch(req: Request): Promise<Response>;
+    };
+}
+/** One staged artifact, as its `.generated.ts` pins it. */
+export interface StagedAsset {
+    /** Asset path ASSETS serves, e.g. `/_assets/runtime/node-shims-<buildId>.js`. */
+    path: string;
+    /** L2 key; carries the build id or version, so it changes with the bytes. */
+    l2Key: string;
+    /** Full digest the bytes must match. */
+    sha256: string;
+    /** Content-Type of the L2 copy, where the artifact has one. */
+    contentType?: string;
+    /**
+     * An L2 entry that fails the digest: `reject` throws, `refetch` deletes the
+     * entry and reads ASSETS instead (whose bytes then replace it).
+     */
+    poisonedCache: 'reject' | 'refetch';
+    /** Message for a deploy with no ASSETS binding. */
+    missingBinding: string;
+    /** Message for a non-OK ASSETS response. */
+    fetchFailed(res: Response): string;
+    /** Message for bytes that do not match `sha256`. */
+    integrityFailed(digest: string, from: 'L2 cache' | 'ASSETS'): string;
+}
+/** Fetch a staged artifact's bytes and verify them against its pinned digest. */
+export declare function fetchStagedBytes(env: StagedSourceEnv, asset: StagedAsset): Promise<ArrayBuffer>;
+/** {@link fetchStagedBytes}, decoded as UTF-8. */
+export declare function fetchStagedText(env: StagedSourceEnv, asset: StagedAsset): Promise<string>;
+/**
+ * One load per isolate: every caller shares the first call's promise, and a
+ * rejected one is dropped so the next call loads again instead of pinning the
+ * error.
+ */
+export declare function memoizeUntilRejected<A, T>(load: (arg: A) => Promise<T>): (arg: A) => Promise<T>;
+/**
+ * The `StagedAsset` of a facet source text staged under
+ * public/_assets/runtime/ by `stagedBy` and needed by `requiredBy`: a bad L2
+ * entry is replaced from ASSETS, since every later fetch in the colo for the
+ * build would otherwise fail on it.
+ */
+export declare function stagedRuntimeSource(source: {
+    label: string;
+    entry: string;
+    buildId: string;
+    sha256: string;
+    stagedBy: string;
+    requiredBy: string;
+}): StagedAsset;
+//# sourceMappingURL=staged-source.d.ts.map

package/dist/runtime/staged-source.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"staged-source.d.ts","sourceRoot":"","sources":["../../src/runtime/staged-source.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAKH,kEAAkE;AAClE,MAAM,WAAW,eAAe;IAC9B,MAAM,CAAC,EAAE;QAAE,KAAK,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAA;KAAE,CAAC;CACrD;AAED,2DAA2D;AAC3D,MAAM,WAAW,WAAW;IAC1B,iFAAiF;IACjF,IAAI,EAAE,MAAM,CAAC;IACb,6EAA6E;IAC7E,KAAK,EAAE,MAAM,CAAC;IACd,wCAAwC;IACxC,MAAM,EAAE,MAAM,CAAC;IACf,+DAA+D;IAC/D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,aAAa,EAAE,QAAQ,GAAG,SAAS,CAAC;IACpC,mDAAmD;IACnD,cAAc,EAAE,MAAM,CAAC;IACvB,4CAA4C;IAC5C,WAAW,CAAC,GAAG,EAAE,QAAQ,GAAG,MAAM,CAAC;IACnC,oDAAoD;IACpD,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,GAAG,QAAQ,GAAG,MAAM,CAAC;CACtE;AAED,iFAAiF;AACjF,wBAAsB,gBAAgB,CAAC,GAAG,EAAE,eAAe,EAAE,KAAK,EAAE,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC,CA2CrG;AAED,kDAAkD;AAClD,wBAAsB,eAAe,CAAC,GAAG,EAAE,eAAe,EAAE,KAAK,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC,CAE/F;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,GAAG,EAAE,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,CAU/F;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE;IAC1C,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;CACpB,GAAG,WAAW,CAkBd"}