@nimbus-sh/fabric 0.7.1 → 0.9.0

package/src/isolate-pool.ts

@@ -7,15 +7,15 @@
  *      running 67 npm tarball extractions (cold-start dominates). We pin
  *      each job to `slot = cursor % concurrency` and use stable loader
  *      IDs `nfp:${fnHash}:slot-${i}:g${generation}`, so a pool of
- *      concurrency=4 keeps at most 4 warm isolates rather than N fresh ones.
+ *      concurrency=N keeps at most N warm isolates rather than one per job.
  *   2. **Nimbus defaults**: compatibilityDate = CF_COMPAT_DATE (matches
- *      the supervisor worker), compatibilityFlags = ['nodejs_compat'],
+ *      the supervisor worker), compatibilityFlags = GUEST_COMPAT_FLAGS,
  *      globalOutbound = undefined (inherit parent network so the facet can
  *      reach https://registry.npmjs.org without a proxy binding).
  *   3. **Supervisor autoinjection**. The pool grabs the embedder's
  *      registered supervisor entrypoint stub (see `supervisorEntrypoint` in
  *      composition.ts) and forwards it as `env.SUPERVISOR` to every facet,
- *      same pattern as git-network-facet.ts. Callers can add more bindings
+ *      same pattern as git/network-facet.ts. Callers can add more bindings
  *      via `extraBindings`.
  *   4. **Fail-loud defaults**: timeout 60s, retries 0, onError 'throw'.
  *      Caller opts in to leniency.
@@ -24,11 +24,12 @@
  * and binding types used by this implementation.
  */
 
-import { CF_COMPAT_DATE } from '@nimbus-sh/core/constants.js';
-import { hostRoute, supervisorEntrypoint, type HostRoute } from './composition.js';
+import { CF_COMPAT_DATE, GUEST_COMPAT_FLAGS } from '@nimbus-sh/core/constants.js';
+import { supervisorEntrypoint, type HostRoute } from './composition.js';
+import { supervisorBindingProps, supervisorLoaderKey } from './supervisor-props.js';
 import { disposeRpcResource } from '@nimbus-sh/platform/rpc-dispose.js';
 import { serializeFunction, hashSource } from './vendor/serialize.js';
-import { beginLoaderFetch, recordLoaderId, withDynamicWorkerCapNamed } from './budgets.js';
+import { beginLoaderFetch, withDynamicWorkerCapNamed } from './budgets.js';
 import { assertModuleMapWithinCodeLimit } from './budgets.js';
 import { recordFailure, setLastFacetId, getLastRpcFrame } from '@nimbus-sh/platform/oom-discriminator.js';
 import { classifyError } from '@nimbus-sh/platform/oom-classify.js';
@@ -40,6 +41,7 @@ import {
 } from './vendor/errors.js';
 import type { FacetBindings } from '@nimbus-sh/core/runtime/facet-host.js';
 import type { ModuleContent, WorkerLoader } from './vendor/types.js';
+import { hostWasmIdentity } from './host-wasm.js';
 
 /**
  * A function dispatched into a facet isolate, with the bindings that facet was
@@ -61,7 +63,11 @@ export interface IsolatePoolEnv {
 
 /** Options handed to IsolatePool's constructor. */
 export interface IsolatePoolOptions {
-  /** Maximum concurrent in-flight facets. Default 4. */
+  /**
+   * Maximum concurrent in-flight facets, each a distinct Dynamic Worker
+   * spent from the hosting DO's `DO_DYNAMIC_WORKER_LIMIT`. Default 1; a
+   * caller that wants more sizes it against that budget (Fanout does).
+   */
   concurrency?: number;
   /** Per-task timeout in ms. Default 60_000. */
   timeoutMs?: number;
@@ -156,15 +162,19 @@ export interface IsolatePoolOptions {
   /**
    * WebAssembly modules to ship into the facet via the LOADER's
    * `modules` map. Map keys are module specifier paths (e.g.
-   * `'esbuild.wasm'`); values are the raw bytes.
+   * `'esbuild.wasm'`); values are the raw bytes, or a module the host
+   * already holds compiled.
    *
-   * Workerd registers each entry as `{ wasm: ArrayBuffer }` in the
-   * worker's modules map. The pool prepends a static
+   * Workerd registers each entry as `{ wasm }` in the worker's modules
+   * map. The pool prepends a static
    * `import __NIMBUS_WASM_<id> from './<key>';` to the generated
-   * worker.js so workerd compiles each at module-load (startup phase,
-   * where wasm code generation is permitted). The compiled Modules
-   * are exposed via `globalThis.__NIMBUS_WASM[<key>]` for the user
-   * function to read at request time.
+   * worker.js; bytes are compiled at the facet's module-load (startup
+   * phase, where wasm code generation is permitted), and a compiled
+   * module is shared with the facet as is, its compiled code included
+   * (workerd src/workerd/api/worker-loader.c++,
+   * extractWasmModuleContent). The Modules are exposed via
+   * `globalThis.__NIMBUS_WASM[<key>]` for the user function to read at
+   * request time.
    *
    * Why this works when other paths don't:
    *   - request-time `WebAssembly.compile()` — disallowed by workerd
@@ -173,15 +183,15 @@ export interface IsolatePoolOptions {
    *     structured-clone refuses ("Unable to deserialize cloned data").
    *   - inlining bytes in the preamble — 16 MiB string per dispatch
    *     OOMs the supervisor at module-source allocation time.
-   *   - LOADER modules-map (this) — bytes ride INSIDE the worker code
-   *     blob; workerd compiles wasm during its own startup pipeline,
-   *     never crossing structured-clone, never executing JS eval.
+   *   - LOADER modules-map (this) — the module rides INSIDE the worker
+   *     code blob, never crossing structured-clone, never executing JS
+   *     eval.
    *
-   * The bytes ARE part of the loader-cache key (workerd hashes the
-   * whole WorkerCode), so changing the wasm bytes invalidates warm
-   * slots — desirable when the bundled wasm version changes.
+   * A compiled module must be described (host-wasm.ts describeHostWasm):
+   * its identity keys warm slots, as the bytes' fingerprint does, and its
+   * size counts toward the dynamic-worker code limit.
    */
-  wasmModules?: Record<string, ArrayBuffer>;
+  wasmModules?: Record<string, ArrayBuffer | WebAssembly.Module>;
 }
 
 /** Per-call override (merged with pool defaults). */
@@ -239,6 +249,14 @@ interface ResolvedResilience {
   retries: number;
 }
 
+/**
+ * How long one call waits, in all, for the platform to admit it after
+ * "Dynamic worker concurrency limit exceeded" (doubling from 50 ms, at most
+ * 2 s a wait). A deployed Durable Object admitted the refused batch after a
+ * 6 s pause; 15 s bounds a call that would never be admitted.
+ */
+const CAP_REFUSAL_WAIT_MS = 15_000;
+
 /**
  * esbuild runtime helpers re-declared at the top of every generated facet
  * module. esbuild emits `__name(fn, "fn")` wrappers around every named
@@ -366,7 +384,7 @@ export function assembleLoaderWorkerModuleSource(
  * Typical use:
  *
  *   const pool = new IsolatePool(env, ctx, {
- *     concurrency: 4,
+ *     concurrency: 2,
  *     tag: 'npm-install',
  *   });
  *   const results = await pool.map(
@@ -411,13 +429,13 @@ export class IsolatePool {
     /** Identifier used inside the generated worker for both the static
      *  import binding and the globalThis exposure. Sanitised from `name`. */
     id: string;
-    bytes: ArrayBuffer;
+    wasm: ArrayBuffer | WebAssembly.Module;
   }>;
-  /** Hash of (name + byte length + first/last bytes) of every wasm
-   *  module, folded into the loader cache key so changes invalidate
-   *  warm slots. Hashing the FULL bytes would be O(20+ MiB) per dispatch
-   *  and is unnecessary — wasm bytes are pinned at deploy time, the
-   *  length+endpoints are a strong-enough fingerprint. */
+  /** Hash of every constructor-time wasm module, folded into the loader
+   *  cache key so changes invalidate warm slots: a compiled module by the
+   *  identity its host described, bytes by name + length + first/last
+   *  byte. Hashing the FULL bytes would be O(20+ MiB) per dispatch and is
+   *  unnecessary — they are pinned at deploy time. */
   private readonly wasmHash: string;
   /**
    * Short prefix of the owning DO's id, baked into the loader.get()
@@ -456,7 +474,7 @@ export class IsolatePool {
     }
     this.loader = loader;
     this.ctx = ctx;
-    this.concurrency = Math.max(1, opts?.concurrency ?? 4);
+    this.concurrency = Math.max(1, opts?.concurrency ?? 1);
     this.defaultTimeoutMs = opts?.timeoutMs ?? 60_000;
     this.defaultRetries = Math.max(0, opts?.retries ?? 0);
     this.tag = opts?.tag ?? 'facet';
@@ -474,17 +492,36 @@ export class IsolatePool {
     // (e.g. 'esbuild.wasm' and 'esbuild_wasm' both sanitise to
     // 'esbuild_wasm') are rejected loudly because the generated worker
     // would otherwise have duplicate imports. Order is preserved.
-    const wasmEntries: Array<{ name: string; id: string; bytes: ArrayBuffer }> = [];
+    const wasmEntries: Array<{ name: string; id: string; wasm: ArrayBuffer | WebAssembly.Module }> = [];
+    const fingerprints: string[] = [];
     const seenIds = new Set<string>();
     if (opts?.wasmModules) {
-      for (const [name, bytes] of Object.entries(opts.wasmModules)) {
-        if (!(bytes instanceof ArrayBuffer)) {
+      for (const [name, wasm] of Object.entries(opts.wasmModules)) {
+        let fingerprint: string;
+        if (wasm instanceof ArrayBuffer) {
+          // Name + length + first/last byte: hashing 20+ MiB of wasm per
+          // dispatch would be wasteful, and these bytes change only with
+          // the deployed bundle.
+          const u = new Uint8Array(wasm);
+          const len = u.byteLength;
+          fingerprint = `${name}:${len}:${len > 0 ? u[0] : 0}:${len > 0 ? u[len - 1] : 0}`;
+        } else if (wasm instanceof WebAssembly.Module) {
+          const identity = hostWasmIdentity(wasm);
+          if (!identity) {
+            throw new BindingError(
+              `IsolatePool: wasmModules['${name}'] is a WebAssembly.Module nobody described; ` +
+              'pass it through describeHostWasm (@nimbus-sh/fabric/host-wasm.js) so warm slots ' +
+              'can be keyed by it and the code limit can count it.',
+            );
+          }
+          fingerprint = `${name}:host:${identity.id}:${identity.bytes}`;
+        } else {
           // Reached only when a caller broke the declared option type, so the
-          // value is whatever it really was rather than the ArrayBuffer here.
-          const got = (bytes as { constructor?: { name?: string } } | null | undefined)?.constructor?.name;
+          // value is whatever it really was rather than the union here.
+          const got = (wasm as { constructor?: { name?: string } } | null | undefined)?.constructor?.name;
           throw new BindingError(
-            `IsolatePool: wasmModules['${name}'] must be ArrayBuffer ` +
-            `(got ${got || typeof bytes}).`,
+            `IsolatePool: wasmModules['${name}'] must be an ArrayBuffer or a WebAssembly.Module ` +
+            `(got ${got || typeof wasm}).`,
           );
         }
         const id = name.replace(/[^A-Za-z0-9_]/g, '_').replace(/^[^A-Za-z_]/, '_');
@@ -495,28 +532,12 @@ export class IsolatePool {
           );
         }
         seenIds.add(id);
-        wasmEntries.push({ name, id, bytes });
+        wasmEntries.push({ name, id, wasm });
+        fingerprints.push(fingerprint);
       }
     }
     this.wasmModules = wasmEntries;
-    // Fingerprint: name + length + first/last byte of each module.
-    // Hashing 20+ MiB of wasm per dispatch would be wasteful; this
-    // fingerprint is bytes-stable for a given deployed bundle and only
-    // changes when the wasm itself changes (deploy-time event).
-    if (wasmEntries.length === 0) {
-      this.wasmHash = '0';
-    } else {
-      const fp = wasmEntries
-        .map((w) => {
-          const u = new Uint8Array(w.bytes);
-          const len = u.byteLength;
-          const first = len > 0 ? u[0] : 0;
-          const last  = len > 0 ? u[len - 1] : 0;
-          return `${w.name}:${len}:${first}:${last}`;
-        })
-        .join('|');
-      this.wasmHash = hashSource(fp);
-    }
+    this.wasmHash = fingerprints.length === 0 ? '0' : hashSource(fingerprints.join('|'));
 
     const bindings: Record<string, unknown> = { ...(opts?.extraBindings ?? {}) };
     this.supervisorKey = 's-none';
@@ -527,11 +548,11 @@ export class IsolatePool {
         // via supervisorDoIdOverride so SUPERVISOR.* RPCs route back
         // to the user's session DO, not the peer DO. Default to the
         // local ctx.id (single-DO callers and the in-DO in-DO fanout path).
-        const supDoId = opts?.supervisorDoIdOverride ?? ctx.id.toString();
-        const supPid = opts?.supervisorPid ?? 0;
-        bindings.SUPERVISOR = supervisorRpc({
-          props: { doId: supDoId, pid: supPid, route: opts?.supervisorRoute ?? hostRoute() ?? undefined },
+        const supervisor = supervisorBindingProps(ctx, opts?.supervisorPid ?? 0, {
+          doId: opts?.supervisorDoIdOverride,
+          route: opts?.supervisorRoute,
         });
+        bindings.SUPERVISOR = supervisorRpc({ props: supervisor });
         // Whatever the minted worker's env carries must be in its loader
         // cache key — workerd's loader cache survives a DO hibernation
         // wake while generation-strided pids (1000001 → 2000001) do not:
@@ -539,8 +560,9 @@ export class IsolatePool {
         // the new generation still credentialed to the dead pid, and
         // every pid-authorized RPC from it fails "process pid … does
         // not exist". doIdShort alone cannot cover this — it changes
-        // across sessions, not across wakes of the same session.
-        this.supervisorKey = `s${supDoId.slice(0, 12)}-${supPid}`;
+        // across sessions, not across wakes of the same session. So does
+        // the instance a binding delivers mutations to, when it names one.
+        this.supervisorKey = supervisorLoaderKey(`s${supervisor.doId.slice(0, 12)}-${supervisor.pid}`, supervisor);
       } else {
         // Supervisor entrypoint unavailable — running without ctx.exports
         // (e.g. unit-test harness, or LOADER.load contexts where the
@@ -577,9 +599,9 @@ export class IsolatePool {
    */
   #materialisePerCallWasm(
     perCall: Record<string, ArrayBuffer> | undefined,
-  ): Array<{ name: string; id: string; bytes: ArrayBuffer }> {
+  ): Array<{ name: string; id: string; wasm: ArrayBuffer }> {
     if (!perCall) return [];
-    const out: Array<{ name: string; id: string; bytes: ArrayBuffer }> = [];
+    const out: Array<{ name: string; id: string; wasm: ArrayBuffer }> = [];
     const ctorIds = new Set(this.wasmModules.map((w) => w.id));
     const seen = new Set<string>();
     for (const [name, bytes] of Object.entries(perCall)) {
@@ -605,7 +627,7 @@ export class IsolatePool {
         );
       }
       seen.add(id);
-      out.push({ name, id, bytes });
+      out.push({ name, id, wasm: bytes });
     }
     return out;
   }
@@ -638,12 +660,12 @@ export class IsolatePool {
    * hashing the wasm were marginal; the correctness cost was severe.
    */
   #fingerprintWasm(
-    entries: Array<{ name: string; bytes: ArrayBuffer }>,
+    entries: Array<{ name: string; wasm: ArrayBuffer }>,
   ): string {
     if (entries.length === 0) return '0';
     const parts: string[] = [];
     for (const w of entries) {
-      const u = new Uint8Array(w.bytes);
+      const u = new Uint8Array(w.wasm);
       const len = u.byteLength;
       // djb2 over the bytes. Faster than crypto.subtle.digest at small
       // sizes, deterministic, and good enough for cache-key
@@ -670,11 +692,11 @@ export class IsolatePool {
    */
   #buildCode(
     fnSource: string,
-    perCallWasmEntries?: Array<{ name: string; id: string; bytes: ArrayBuffer }>,
+    perCallWasmEntries?: Array<{ name: string; id: string; wasm: ArrayBuffer }>,
   ) {
     const workerOpts = {
       compatibilityDate: CF_COMPAT_DATE,
-      compatibilityFlags: ['nodejs_compat'],
+      compatibilityFlags: [...GUEST_COMPAT_FLAGS],
       // Inherit parent network so the facet can reach registry.npmjs.org.
       globalOutbound: undefined,
       env: this.bindings,
@@ -720,7 +742,7 @@ export class IsolatePool {
     // (matters only for human-readable diffs; workerd doesn't care).
     const modules: Record<string, ModuleContent> = { 'worker.js': moduleSource };
     for (const w of allWasmEntries) {
-      modules[w.name] = { wasm: w.bytes };
+      modules[w.name] = { wasm: w.wasm };
     }
     assertModuleMapWithinCodeLimit(modules);
 
@@ -841,11 +863,10 @@ export class IsolatePool {
       // binding stub once the whole pool is done, which does NOT
       // invalidate any in-flight slot's entrypoint reference.
       const stub = this.loader.get(id, async () => code);
-      recordLoaderId(this.ctx, id);
       const entrypoint = stub.getEntrypoint();
       // Direct property call, awaited by this frame — bracketed, never
       // wrapped. See beginLoaderFetch for the measured DO-poisoning hazard.
-      const endFetch = beginLoaderFetch(this.ctx);
+      const endFetch = beginLoaderFetch(this.ctx, id);
       try {
         return await invoke(entrypoint, attempt);
       } catch (err) {
@@ -861,6 +882,8 @@ export class IsolatePool {
     const maxAttempts = 1 + resilience.retries;
     let lastError: Error | undefined;
     let retriedCloneRefusal = false;
+    let capRefusals = 0;
+    let capWaitedMs = 0;
     let attempt = 0;
     while (attempt < maxAttempts) {
       try {
@@ -942,6 +965,17 @@ export class IsolatePool {
           // reverse direction. This refresh targets the stale-loader case.
           continue;
         }
+        if (cause === 'dynamic_worker_cap' && capWaitedMs < CAP_REFUSAL_WAIT_MS) {
+          // The platform refused to start this call: it still counts a
+          // worker this Durable Object's ledger has already given back (a
+          // fan-out's workers stay counted for a moment after their calls
+          // return). Nothing ran, so the call waits, as the platform asks,
+          // and is sent again; it does not spend an attempt.
+          const delay = Math.min(CAP_REFUSAL_WAIT_MS - capWaitedMs, 50 * 2 ** capRefusals++, 2000);
+          capWaitedMs += delay;
+          await new Promise<void>((resolve) => setTimeout(resolve, delay));
+          continue;
+        }
         if (attempt < maxAttempts - 1) {
           // 100 * 2^attempt, capped at 2s so retries don't compound waiting.
           const delay = Math.min(2000, 100 * Math.pow(2, attempt));
@@ -950,9 +984,9 @@ export class IsolatePool {
         attempt++;
       }
     }
-    // On the way out only, so retries do not stack the annotation: a cap hit
-    // carries the ledger — which ids hold slots, and that a keyed id never
-    // gives one back — instead of the platform's bare message.
+    // On the way out only, so retries do not stack the annotation: a limit
+    // hit carries the ledger — which workers were in flight — instead of the
+    // platform's bare message.
     const named = withDynamicWorkerCapNamed(this.ctx, lastError!);
     if (maxAttempts > 1) {
       throw new RetryExhaustedError(maxAttempts, named);

package/src/process-fabric.ts

@@ -74,7 +74,7 @@
  * `ResidentDiskReader` it was given.
  */
 
-import type { HostRoute } from './composition.js';
+import type { SupervisorBindingProps } from './supervisor-props.js';
 import { z } from 'zod/v4';
 import type { RouteableFacetTarget } from '@nimbus-sh/core/runtime/os-contracts.js';
 import type { ServiceStub } from './vendor/types.js';
@@ -133,6 +133,14 @@ export const ResidentCodeSpecSchema = z.object({
    * image store below and the spec names it.
    */
   vfsTextModules: z.record(z.string(), z.string()).optional(),
+  /**
+   * VFS paths of generated CommonJS PACKS (encodeCommonJsPack): each image
+   * carries many `{ cjs }` modules, and the map gains every one of them at
+   * load. A node process's module cells travel this way — one module per
+   * file, so the guest's registry compiles only what the program requires,
+   * and one image per launch, so the boot spec names a path and not thousands.
+   */
+  vfsCommonJsPacks: z.array(z.string()).optional(),
   /**
    * The isolate's exact `env`: one entry per binding the embedder minted,
    * carried by reference so loopback stubs survive untouched. Defined —
@@ -210,8 +218,10 @@ export const FACET_IMAGE_DIR = 'var/lib/nimbus/facet-images';
  * generated text into `startArgs` would make every image per-PROGRAM and
  * shareable across spawns and sessions; the sweep bounds the store either way.
  */
-export async function facetImageDigest(source: string): Promise<string> {
-  const digest = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(source));
+export async function facetImageDigest(image: string | Uint8Array): Promise<string> {
+  // An image is its UTF-8 bytes; a caller holding them is not made to encode a second copy.
+  const bytes = typeof image === 'string' ? new TextEncoder().encode(image) : image;
+  const digest = await crypto.subtle.digest('SHA-256', bytes);
   return Array.from(new Uint8Array(digest), (b) => b.toString(16).padStart(2, '0')).join('');
 }
 
@@ -263,16 +273,27 @@ export async function residentLoaderConfig(
   spec: ResidentCodeSpec,
   disk: ResidentDiskReader,
 ): Promise<Record<string, unknown>> {
-  const resolved: Record<string, string | { wasm: ArrayBuffer }> = {};
+  const resolved: Record<string, string | { wasm: ArrayBuffer } | { cjs: string }> = {};
   for (const [moduleName, path] of Object.entries(spec.vfsWasmModules ?? {})) {
     const bytes = await disk.readFile(path);
+    // The read's own buffer when it fits exactly, and only otherwise a copy.
+    // These are the largest members a spec carries — ruby's interpreter image
+    // is 34.3 MiB, esbuild's 13.3 — and an unconditional slice held both
+    // copies at once in the coordinator's 128 MiB isolate, at the one moment
+    // the module map is also resident.
+    const exact = bytes.byteOffset === 0 && bytes.byteLength === bytes.buffer.byteLength;
     resolved[moduleName] = {
-      wasm: bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength) as ArrayBuffer,
+      wasm: exact
+        ? bytes.buffer as ArrayBuffer
+        : bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength) as ArrayBuffer,
     };
   }
   for (const [moduleName, path] of Object.entries(spec.vfsTextModules ?? {})) {
     resolved[moduleName] = await readFacetImage(disk, path);
   }
+  for (const path of spec.vfsCommonJsPacks ?? []) {
+    Object.assign(resolved, decodeCommonJsPack(await readFacetImage(disk, path)));
+  }
   return {
     compatibilityDate: spec.compatibilityDate,
     compatibilityFlags: spec.compatibilityFlags,
@@ -283,6 +304,40 @@ export async function residentLoaderConfig(
   };
 }
 
+/**
+ * One image holding many `{ cjs }` modules: a JSON index of `[name, length]`
+ * rows, a newline, and the module texts back to back. Lengths are UTF-16 code
+ * units, the unit the decoded text is sliced in, so decoding copies nothing:
+ * each module is a slice of the one string read.
+ *
+ * Encoded as its parts, in order, never joined: the image store encodes them
+ * straight into the image's bytes, and a joined copy would be a second full
+ * copy of the program's code on the coordinator.
+ */
+export function encodeCommonJsPack(modules: Record<string, string>): string[] {
+  const index: [string, number][] = [];
+  const parts: string[] = [''];
+  for (const [name, text] of Object.entries(modules)) {
+    index.push([name, text.length]);
+    parts.push(text);
+  }
+  parts[0] = JSON.stringify(index) + '\n';
+  return parts;
+}
+
+export function decodeCommonJsPack(pack: string): Record<string, { cjs: string }> {
+  const newline = pack.indexOf('\n');
+  const index = z.array(z.tuple([z.string(), z.number().int().nonnegative()])).parse(JSON.parse(pack.slice(0, newline)));
+  const modules: Record<string, { cjs: string }> = {};
+  let offset = newline + 1;
+  for (const [name, length] of index) {
+    modules[name] = { cjs: pack.slice(offset, offset + length) };
+    offset += length;
+  }
+  if (offset !== pack.length) throw new Error(`Nimbus: CommonJS pack holds ${pack.length - offset} bytes its index does not name`);
+  return modules;
+}
+
 /**
  * Read one content-addressed facet image and verify it against the digest its
  * path claims. Content addressing is only a guarantee if the bytes are checked
@@ -295,15 +350,16 @@ async function readFacetImage(disk: ResidentDiskReader, path: string): Promise<s
   if (!expected) {
     throw new Error(`Nimbus: '${path}' is not a content-addressed facet image path`);
   }
-  const source = new TextDecoder().decode(await disk.readFile(path));
-  const actual = await facetImageDigest(source);
+  // Verified from the bytes read, and decoded only after: re-encoding the decoded string held a third copy of the largest member.
+  const bytes = await disk.readFile(path);
+  const actual = await facetImageDigest(bytes);
   if (actual !== expected) {
     throw new Error(
       `Nimbus: facet image '${path}' does not match its digest (read ${actual}); `
         + 'the image store is corrupt and the process cannot boot from it',
     );
   }
-  return source;
+  return new TextDecoder().decode(bytes);
 }
 
 // ── The hosting substrate ───────────────────────────────────────────────────
@@ -311,18 +367,13 @@ async function readFacetImage(disk: ResidentDiskReader, path: string): Promise<s
 /**
  * The identity a resident process's SUPERVISOR binding is minted for. Always
  * the COORDINATOR's — a process hosted somewhere else still reads and writes
- * the user's disk, and still reports to the user's process table.
+ * the user's disk, and still reports to the user's process table. Minted by
+ * `supervisorBindingProps` on the coordinator; `route` is absent only when
+ * the coordinator's isolate composed nothing, in which case no supervisor
+ * binding is minted either.
  */
-export interface ResidentSupervisorProps {
-  doId: string;
-  pid: number;
+export interface ResidentSupervisorProps extends SupervisorBindingProps {
   writerId: string;
-  /**
-   * The way back to the coordinator, minted with the binding. Absent only
-   * when the coordinator's isolate composed nothing, in which case no
-   * supervisor binding is minted either.
-   */
-  route?: HostRoute;
 }
 
 /** Everything a host needs to run one process. Substrate-free by construction. */
@@ -345,6 +396,13 @@ export interface ProcessHostParams {
    * the store on release.
    */
   facet?: { name: string; durable: boolean };
+  /**
+   * Bytes the process's store is filled with before it runs (its data plan).
+   * The hosting actor's storage ledger (N18) admits them under the facet's
+   * name before the facet starts: ENOSPC, and no facet, when they would cross
+   * the storage limit.
+   */
+  storageBytes?: number;
 }
 
 /**
@@ -415,17 +473,14 @@ export interface ProcessImageDelivery {
    *   across one. A peer-hosted process can only ever receive an image
    *   through `moduleCeilingBytes` below, or by streaming it.
    *
-   * Reachable in PRODUCTION but not from a type checker or `wrangler dev`, and
-   * the difference is worth stating precisely because inferring one from the
-   * other is how a wrong claim gets written down. `@cloudflare/workers-types`
-   * 4.20260605.1 declares `get`/`abort`/`delete` and no `clone`, and the pinned
-   * workerd is 1.20260603.1 — but the deployed runtime is Cloudflare's, not the
-   * one wrangler bundles, and there it is present and works: enumerating the
-   * binding on a live Worker at this repo's own compatibility_date returns
-   * `["abort","clone","constructor","delete","get"]`, and a clone into a
-   * destination of a DIFFERENT class had all 500 seeded files readable from the
-   * destination's CONSTRUCTOR. No compat-date gate. So calling it is a
-   * lockfile-and-types problem, not a platform one.
+   * Present in production, and since the pins moved to
+   * `@cloudflare/workers-types` 5.20260928.1 and workerd 1.20260926.1 also in
+   * the type checker and `wrangler dev` (DurableObjectFacets.clone;
+   * src/workerd/api/actor-state.h). Before that the types declared no `clone`
+   * and the pinned workerd 1.20260603.1 lacked it, while on a live Worker the
+   * binding enumerated `["abort","clone","constructor","delete","get"]` and a
+   * clone into a destination of a DIFFERENT class had all 500 seeded files
+   * readable from the destination's CONSTRUCTOR. No compat-date gate.
    *
    * The hazard that comes with it, measured rather than assumed: ANY `src`
    * that does not resolve to a populated facet — a typo, a name not created
@@ -475,7 +530,7 @@ export interface OneShotCodeSpec {
   compatibilityDate: string;
   compatibilityFlags: string[];
   mainModule: string;
-  modules: Record<string, string | { wasm: ArrayBuffer }>;
+  modules: Record<string, string | { wasm: ArrayBuffer } | { cjs: string }>;
 }
 
 /**
@@ -657,6 +712,8 @@ export interface ResidentProcessSpawn {
    * ephemeral process, which takes a `proc-slot-<n>` name from the book.
    */
   facet?: { name: string; durable: boolean };
+  /** See {@link ProcessHostParams.storageBytes}. */
+  storageBytes?: number;
   /**
    * Called before any concrete host capability can expose this writer.
    * A spawn must not proceed unless the supervisor accepts the authority.
@@ -701,6 +758,7 @@ export class ProcessFabric {
         writerId,
         startArgs: spawn.startArgs,
         ...(spawn.facet !== undefined ? { facet: spawn.facet } : {}),
+        ...(spawn.storageBytes !== undefined ? { storageBytes: spawn.storageBytes } : {}),
       });
     } catch (error) {
       spawn.onWriterRetired(writerId);