@nimbus-sh/fabric 0.8.0 → 0.10.0

package/src/isolate-pool.ts

@@ -7,9 +7,9 @@
  *      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
@@ -24,12 +24,18 @@
  * and binding types used by this implementation.
  */
 
-import { CF_COMPAT_DATE } from '@nimbus-sh/core/constants.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,
+  beginLoaderFetchWhenFree,
+  withDynamicWorkerCapNamed,
+  type DynamicWorkerClaim,
+  type EndLoaderFetch,
+} 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';
@@ -41,6 +47,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
@@ -62,8 +69,18 @@ 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;
+  /**
+   * The width the caller claimed for this pool's dispatches
+   * (`claimDynamicWorkers`): they are held inside it rather than on top of
+   * it, and a refused one waits for a slot of the claim.
+   */
+  claim?: DynamicWorkerClaim;
   /** Per-task timeout in ms. Default 60_000. */
   timeoutMs?: number;
   /**
@@ -157,15 +174,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
@@ -174,15 +195,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). */
@@ -240,6 +261,15 @@ interface ResolvedResilience {
   retries: number;
 }
 
+/**
+ * How long one call waits, in all, on the Dynamic Worker ledger after
+ * "Dynamic worker concurrency limit exceeded" before the refusal surfaces
+ * (beginLoaderFetchWhenFree: let in when a hold ends or the refusal's pause
+ * passes). 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
@@ -367,7 +397,7 @@ export function assembleLoaderWorkerModuleSource(
  * Typical use:
  *
  *   const pool = new IsolatePool(env, ctx, {
- *     concurrency: 4,
+ *     concurrency: 2,
  *     tag: 'npm-install',
  *   });
  *   const results = await pool.map(
@@ -379,6 +409,8 @@ export class IsolatePool {
   private readonly loader: WorkerLoader;
   /** The hosting actor, as the loader budget ledger's per-DO key. */
   private readonly ctx: DurableObjectState;
+  /** The width this pool's dispatches are held inside (IsolatePoolOptions.claim). */
+  private readonly claim: DynamicWorkerClaim | undefined;
   private readonly concurrency: number;
   private readonly defaultTimeoutMs: number;
   private readonly defaultRetries: number;
@@ -412,13 +444,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()
@@ -457,7 +489,8 @@ export class IsolatePool {
     }
     this.loader = loader;
     this.ctx = ctx;
-    this.concurrency = Math.max(1, opts?.concurrency ?? 4);
+    this.claim = opts?.claim;
+    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';
@@ -475,17 +508,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_]/, '_');
@@ -496,28 +548,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';
@@ -579,9 +615,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)) {
@@ -607,7 +643,7 @@ export class IsolatePool {
         );
       }
       seen.add(id);
-      out.push({ name, id, bytes });
+      out.push({ name, id, wasm: bytes });
     }
     return out;
   }
@@ -640,12 +676,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
@@ -672,11 +708,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,
@@ -722,7 +758,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);
 
@@ -758,7 +794,7 @@ export class IsolatePool {
     invoke: (entrypoint: { execute(...args: unknown[]): Promise<unknown>; fetch(input: RequestInfo, init?: RequestInit): Promise<Response> }, attempt: number) => Promise<T>,
     resilience: ResolvedResilience,
     perCallWasm?: Record<string, ArrayBuffer>,
-    wasAborted?: () => boolean,
+    signal?: AbortSignal,
   ): Promise<T> {
     // A warm slot executes one dispatch at a time: queue behind the
     // previous owner, then record this dispatch as the new tail. The
@@ -776,7 +812,7 @@ export class IsolatePool {
     }
     const inFlight: Promise<unknown>[] = [];
     try {
-      return await this.#dispatchSlotOwned(fnSource, fnHash, slotIndex, invoke, resilience, perCallWasm, inFlight, wasAborted);
+      return await this.#dispatchSlotOwned(fnSource, fnHash, slotIndex, invoke, resilience, perCallWasm, inFlight, signal);
     } finally {
       // Do not delay the caller's own outcome — the tail releases when
       // the RPCs the body launched have actually settled.
@@ -793,7 +829,7 @@ export class IsolatePool {
     resilience: ResolvedResilience,
     perCallWasm: Record<string, ArrayBuffer> | undefined,
     inFlight: Promise<unknown>[],
-    wasAborted?: () => boolean,
+    signal?: AbortSignal,
   ): Promise<T> {
     // Per-call wasm fingerprint. Mixed into the cache key so two calls
     // with different bytes hit different slots (no cache poisoning).
@@ -817,6 +853,9 @@ export class IsolatePool {
     // slot updated on every dispatch.
     try { setLastFacetId(id, slotIndex); } catch { /* best-effort */ }
 
+    // A hold the ledger already took for the next attempt, when a refused
+    // call waited on it for room; otherwise the attempt begins its own.
+    let admitted: EndLoaderFetch | undefined;
     const runOnce = async (): Promise<T> => {
       // loader.get() is synchronous from the caller's POV; the callback
       // is only invoked on cache miss. We wrap the callback tightly so a
@@ -842,15 +881,20 @@ export class IsolatePool {
       // fine and stays — it only tears down the long-lived SUPERVISOR
       // 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);
+      //
+      // The hold comes first, so it ends whatever setup throws: a retry's
+      // was taken when the ledger let it in.
+      const endFetch = admitted ?? beginLoaderFetch(this.ctx, id, this.claim);
+      admitted = undefined;
       try {
+        const stub = this.loader.get(id, async () => code);
+        const entrypoint = stub.getEntrypoint();
+        // Direct property call, awaited by this frame — bracketed, never
+        // wrapped. See beginLoaderFetch for the measured DO-poisoning hazard.
         return await invoke(entrypoint, attempt);
       } catch (err) {
+        // The ledger learns a limit refusal from the hold it ends.
+        endFetch(err);
         if (err instanceof Error) {
           throw new ExecutionError(err.message, err.stack);
         }
@@ -863,6 +907,8 @@ export class IsolatePool {
     const maxAttempts = 1 + resilience.retries;
     let lastError: Error | undefined;
     let retriedCloneRefusal = false;
+    // When this call's waits for room after a limit refusal run out.
+    let capDeadline: number | undefined;
     let attempt = 0;
     while (attempt < maxAttempts) {
       try {
@@ -921,7 +967,7 @@ export class IsolatePool {
             message: lastError.message,
           });
         } catch { /* fail-soft */ }
-        if (wasAborted?.()) {
+        if (signal?.aborted) {
           // The caller aborted this dispatch's Request. workerd cancelled
           // the isolate's execution context wherever it was suspended —
           // mid-syscall, mid-stream — so the interpreter's heap may hold
@@ -944,6 +990,30 @@ export class IsolatePool {
           // reverse direction. This refresh targets the stale-loader case.
           continue;
         }
+        if (cause === 'dynamic_worker_cap') {
+          // The platform refused to start this call. Nothing ran, so the
+          // call waits, as the platform asks, and is sent again without
+          // spending an attempt: on the ledger, which lets it in when a
+          // hold ends, or when the pause this refusal started has passed
+          // (the platform still counts a worker the ledger has given back:
+          // a fan-out's workers stay counted for a moment after their
+          // calls return).
+          capDeadline ??= Date.now() + CAP_REFUSAL_WAIT_MS;
+          const remainingMs = capDeadline - Date.now();
+          if (remainingMs > 0) {
+            // The deadline's timer is cleared once the wait settles: a
+            // pending timer keeps the hosting object from hibernating.
+            const deadline = new AbortController();
+            const timer = setTimeout(() => deadline.abort(), remainingMs);
+            const waitFor = signal ? AbortSignal.any([deadline.signal, signal]) : deadline.signal;
+            admitted = await beginLoaderFetchWhenFree(this.ctx, id, { claim: this.claim, signal: waitFor })
+              .catch(() => undefined)
+              .finally(() => clearTimeout(timer));
+            if (admitted) continue;
+            // The caller aborted while waiting: surface its abort as above.
+            if (signal?.aborted) throw lastError;
+          }
+        }
         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));
@@ -952,9 +1022,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);
@@ -1021,7 +1091,7 @@ export class IsolatePool {
       (entrypoint) => entrypoint.fetch(request.clone()),
       resilience,
       opts?.wasmModules,
-      () => request.signal.aborted,
+      request.signal,
     );
   }
 

package/src/process-fabric.ts

@@ -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 —
@@ -265,7 +273,7 @@ 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.
@@ -283,6 +291,9 @@ export async function residentLoaderConfig(
   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,
@@ -293,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
@@ -428,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
@@ -488,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 }>;
 }
 
 /**