@nimbus-sh/fabric 0.8.0 → 0.9.0

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 }>;
 }
 
 /**

package/src/timers.ts

@@ -58,9 +58,12 @@ export const TIMER_REASONS_KEY = 'w1_next_alarm_reasons';
  * The host instance carrying the per-instance timer chain. The field lives on
  * the embedder's DO instance so one chain serializes every timer-map
  * read-modify-write for that instance (see {@link Timers.schedule}).
+ * `_timerEpoch` counts {@link Timers.reset}s: a schedule or dispatch writes
+ * only while the epoch it was requested in is still current.
  */
 export interface TimerHost {
   _timerChain?: Promise<unknown>;
+  _timerEpoch?: number;
 }
 
 /**
@@ -159,6 +162,7 @@ export class Timers {
       arms.push({ reason, whenMs });
       return Promise.resolve(true);
     }
+    const epoch = host._timerEpoch ?? 0;
     // Serialize every read-modify-write of the reasons map through one
     // per-instance chain: two schedulers firing back-to-back from one activity
     // hook would otherwise interleave their get→put cycles and silently drop
@@ -170,15 +174,20 @@ export class Timers {
         const existing = (await ctx.storage.get(TIMER_REASONS_KEY)) as
           | Record<string, number>
           | undefined;
+        // Requested before a reset: it belongs to the timers the reset voided.
+        if ((host._timerEpoch ?? 0) !== epoch) return false;
         const map: Record<string, number> = { ...(existing || {}) };
         // Earliest-deadline-first: only update if new request is sooner or
         // this reason has no pending entry.
+        let written: Promise<unknown> | undefined;
         if (!(reason in map) || whenMs < map[reason]) {
           map[reason] = whenMs;
-          await ctx.storage.put(TIMER_REASONS_KEY, map);
+          written = ctx.storage.put(TIMER_REASONS_KEY, map);
         }
-        const earliest = Math.min(...Object.values(map));
-        setAlarmFn.call(ctx.storage, earliest);
+        // Issued in the turn the epoch was checked in: a reset after this
+        // point wipes and disarms after these, never before.
+        setAlarmFn.call(ctx.storage, Math.min(...Object.values(map)));
+        await written;
         return true;
       } catch (e) {
         console.warn('[nimbus/W1] timers.schedule threw:', errorText(e));
@@ -190,6 +199,18 @@ export class Timers {
     return chained;
   }
 
+  /**
+   * Void every timer of this instance: a schedule or dispatch already
+   * requested — still queued on the chain, or a dispatch whose handlers are
+   * running — writes no reason and arms no alarm from here on. For a
+   * deliberate end of the actor's state (a session destroy): call it before
+   * wiping storage and deleting the alarm, so nothing in flight writes the
+   * map back or re-arms after the wipe. Requests made after it proceed.
+   */
+  reset(): void {
+    this.host._timerEpoch = (this.host._timerEpoch ?? 0) + 1;
+  }
+
   /**
    * Multi-reason timer dispatcher. Called from the DO's `alarm()` handler
    * with the embedder's handler map.
@@ -216,19 +237,28 @@ export class Timers {
     alarmInfo?: TimerAlarmInfo,
   ): Promise<void> {
     const { host, ctx } = this;
+    const epoch = host._timerEpoch ?? 0;
+    const current = (): boolean => (host._timerEpoch ?? 0) === epoch;
     // Same serialization as schedule: the dispatcher's read→handlers→write
     // cycle must not interleave with an activity-hook schedule.
     const chained = (host._timerChain ?? Promise.resolve()).then(
-      () => dispatchBody(ctx, handlers, onLegacyAlarm, alarmInfo),
-      () => dispatchBody(ctx, handlers, onLegacyAlarm, alarmInfo),
+      () => dispatchBody(ctx, current, handlers, onLegacyAlarm, alarmInfo),
+      () => dispatchBody(ctx, current, handlers, onLegacyAlarm, alarmInfo),
     );
     host._timerChain = chained;
     return chained;
   }
 }
 
+/**
+ * One dispatch. `current` answers whether the epoch it was requested in still
+ * stands: once a reset voids it, no further handler runs and nothing is
+ * written or armed — the reset's caller is wiping this state, and a write
+ * after the wipe would outlive it.
+ */
 async function dispatchBody(
   ctx: TimerContext,
+  current: () => boolean,
   handlers: TimerHandlers,
   onLegacyAlarm?: () => void,
   alarmInfo?: TimerAlarmInfo,
@@ -242,6 +272,7 @@ async function dispatchBody(
     const existing = (await ctx?.storage?.get?.(TIMER_REASONS_KEY)) as
       | Record<string, number>
       | undefined;
+    if (!current()) return;
     const map: Record<string, number> = { ...(existing || {}) };
     const hadMap = Object.keys(map).length > 0;
     if (!hadMap) {
@@ -255,6 +286,7 @@ async function dispatchBody(
         if (when <= now) fired.push(reason);
       }
       for (const reason of fired) {
+        if (!current()) return;
         delete map[reason];
         const handler = handlers[reason];
         // Unknown reasons silently dropped (forward-compat).
@@ -269,20 +301,24 @@ async function dispatchBody(
         }
       }
     }
+    // A reset while the handlers ran: the map read above is gone, and
+    // writing it back — or arming for it — would revive what was ended.
+    if (!current()) return;
     // Fold the in-dispatch arms, earliest-deadline-first per reason.
     for (const arm of arms) {
       if (!(arm.reason in map) || arm.whenMs < map[arm.reason]) {
         map[arm.reason] = arm.whenMs;
       }
     }
-    // Re-arm or clear.
+    // Re-arm or clear, issued in the turn the epoch was checked in: a reset
+    // after this point wipes and disarms after these, never before.
     const setAlarmFn = ctx?.storage?.setAlarm;
     if (Object.keys(map).length > 0) {
-      await ctx.storage.put(TIMER_REASONS_KEY, map);
-      const earliest = Math.min(...Object.values(map));
+      const written = ctx.storage.put(TIMER_REASONS_KEY, map);
       if (typeof setAlarmFn === 'function') {
-        setAlarmFn.call(ctx.storage, earliest);
+        setAlarmFn.call(ctx.storage, Math.min(...Object.values(map)));
       }
+      await written;
     } else if (hadMap) {
       try { await ctx.storage.delete(TIMER_REASONS_KEY); } catch {}
       // No remaining reasons → no setAlarm call → DO becomes

package/src/vendor/types.ts

@@ -9,12 +9,18 @@ export interface TextModule { text: string }
 export interface DataModule { data: ArrayBuffer }
 export interface JsonModule { json: unknown }
 /**
- * A compiled WebAssembly module, importable from a facet by module name.
- * Nimbus ships these on every path — sql.js for node:sqlite, the interpreter
- * images for python and ruby — so the omission here was the type lagging the
- * API, not a kind the loader lacks.
+ * A WebAssembly module, importable from a facet by module name. Nimbus ships
+ * these on every path — sql.js for node:sqlite, the interpreter images for
+ * python and ruby — so the omission here was the type lagging the API, not a
+ * kind the loader lacks. The loader takes either the bytes, which it
+ * compiles, or a module the caller holds compiled already, whose compiled
+ * code the dynamic worker then shares (workerd src/workerd/api/
+ * worker-loader.c++, extractWasmModuleContent). A module handed over this
+ * way should be described with describeHostWasm (host-wasm.ts): the
+ * code-size budget and the loader cache key cannot read a Module's size or
+ * identity from JS.
  */
-export interface WasmModule { wasm: ArrayBuffer }
+export interface WasmModule { wasm: ArrayBuffer | WebAssembly.Module }
 
 /** Plain string = type inferred from file extension (.js or .py). */
 export type ModuleContent =

package/src/workerd-facet-host.ts

@@ -28,7 +28,6 @@ import {
   facetNameCount,
   facetNameCountDurable,
   recordFacetNameMinted,
-  recordLoaderId,
   withDynamicWorkerCapNamed,
   withFacetBudgetNamed,
 } from './budgets.js';
@@ -121,9 +120,10 @@ interface FacetContainer {
   abort(name: string, reason?: unknown): void;
   delete(name: string): void;
   /**
-   * Present on deployed Cloudflare workerd, absent from the pinned
-   * `@cloudflare/workers-types` and from local workerd ≤ 1.20260603.1 — see
-   * {@link cloneStorage}, the one way the fabric calls it.
+   * Declared by `@cloudflare/workers-types` 5 and present in workerd
+   * ≥ 1.20260926.1 and in production; an embedder's older local workerd
+   * (≤ 1.20260603.1) lacks it — see {@link cloneStorage}, the one way the
+   * fabric calls it.
    */
   clone?(src: string, dst: string): void;
 }
@@ -212,7 +212,7 @@ export async function cloneStorage(
   if (typeof facets.clone !== 'function') {
     throw new Error(
       'Nimbus: ctx.facets.clone is unavailable in this runtime; the reflink image '
-        + 'path needs deployed Cloudflare workerd (local workerd <= 1.20260603.1 lacks it)',
+        + 'path needs workerd 1.20260926.1 or later, or deployed Cloudflare workerd',
     );
   }
   const { src, dst } = clone;
@@ -471,10 +471,13 @@ function spawnResident(
       );
     }
     evaluated = true;
-    return { class: residentProcessClass(ctx, env, disk, supervisor, params) };
+    return { class: residentProcessClass(env, disk, supervisor, params, loaderKey) };
   };
   const book = slotBook(ctx);
   const ledger = sessionLedger(ctx);
+  // A warm worker keeps the SUPERVISOR binding it was built with, and the
+  // loader outlives this instance.
+  const loaderKey = supervisorLoaderKey(params.workerKey, supervisor);
   let facet: ResidentFacetStub;
   try {
     // N18: the fill is admitted, and recorded under the facet's name, before
@@ -490,6 +493,12 @@ function spawnResident(
     throw withFacetBudgetNamed(facetNameCount(ctx), error);
   }
   if (explicit) book.live.add(name);
+  // The facet's worker is one Dynamic Worker in flight for as long as the
+  // process is resident, not only while a call is open: its WebSockets and
+  // streamed responses outlive the calls the ledger could bracket, and a
+  // request can reach it at any moment. Held from here to `release`, so no
+  // fan-out spends the slot a running process needs.
+  const endResidency = beginLoaderFetch(ctx, loaderKey);
   facetOfPid(ctx).set(params.pid, name);
 
   let disposed = false;
@@ -498,6 +507,7 @@ function spawnResident(
     disposed = true;
     released = true;
     facetOfPid(ctx).delete(params.pid);
+    endResidency();
     try { facets.abort(name, new Error('Nimbus: resident process released')); } catch { /* already gone */ }
     if (explicit) book.live.delete(name);
     // The two release classes: an ephemeral facet's SQLite is slot-reuse
@@ -564,11 +574,11 @@ function spawnResident(
  * the hosting DO's heap.
  */
 function residentProcessClass(
-  ctx: DurableObjectState,
   env: ResidentFacetEnv,
   disk: () => ResidentDiskReader,
   supervisor: ResidentSupervisorProps,
   params: ProcessHostParams,
+  loaderKey: string,
 ): unknown {
   const loader = env.LOADER;
   if (!loader || typeof loader.get !== 'function') {
@@ -577,18 +587,9 @@ function residentProcessClass(
         + 'the Worker Loader binding; add it via worker_loaders in wrangler.jsonc.',
     );
   }
-  // A warm worker keeps the SUPERVISOR binding it was built with, and the
-  // loader outlives this instance.
-  const loaderKey = supervisorLoaderKey(params.workerKey, supervisor);
-  try {
-    const worker = loader
-      .get(loaderKey, () => residentWorkerConfig(env, disk, supervisor, params.boot))
-      .getDurableObjectClass(RESIDENT_PROCESS_CLASS);
-    recordLoaderId(ctx, loaderKey);
-    return worker;
-  } catch (error) {
-    throw withDynamicWorkerCapNamed(ctx, error);
-  }
+  return loader
+    .get(loaderKey, () => residentWorkerConfig(env, disk, supervisor, params.boot))
+    .getDurableObjectClass(RESIDENT_PROCESS_CLASS);
 }
 
 async function runOneShot<T>(
@@ -638,22 +639,22 @@ async function runOneShot<T>(
       throw new Error('Nimbus: one-shot runtime entrypoint has no fetch method');
     }
     params.onLoaded?.();
-    // The unkeyed worker is a live dynamic worker for exactly this call, so
-    // the run is a Loader fetch on the hosting actor's ledger — bracketed,
-    // never wrapped: see beginLoaderFetch for the measured DO-poisoning
-    // hazard, and the pipelined-`fetch.call` note above for its sibling.
-    const endFetch = beginLoaderFetch(ctx);
-    let response: Response;
+    // The unkeyed worker is one distinct dynamic worker in flight until its
+    // response is consumed (the body streams from it), keyed by this run's
+    // writer id — bracketed, never wrapped: see beginLoaderFetch for the
+    // measured DO-poisoning hazard, and the pipelined-`fetch.call` note above
+    // for its sibling.
+    const endFetch = beginLoaderFetch(ctx, `one-shot:${params.writerId}`);
     try {
-      response = await ep.fetch(params.request);
+      const response = await ep.fetch(params.request);
+      try {
+        return await consume(response);
+      } finally {
+        disposeRpcResource(response);
+      }
     } finally {
       endFetch();
     }
-    try {
-      return await consume(response);
-    } finally {
-      disposeRpcResource(response);
-    }
   } catch (error) {
     throw withDynamicWorkerCapNamed(ctx, error);
   } finally {