@nimbus-sh/platform 0.8.2 → 0.14.0

package/src/composition.ts

@@ -33,9 +33,11 @@
  * the Durable Object classes, which is what lets the pool be unit-tested
  * in a plain Node/Bun process.
  */
+import type { WorkerCode } from './worker-code.js';
+
 export type EntrypointLoopbackFactory = <Stub = unknown>(options: { props: object }) => Stub;
 export type CtxExports = Record<string, EntrypointLoopbackFactory | undefined>;
-export type StagedBootAssembler = (env: unknown, stage: unknown) => Promise<object>;
+export type StagedBootAssembler = (env: unknown, stage: unknown) => Promise<WorkerCode>;
 
 export interface FabricComposition {
   supervisorEntrypoint: string;
@@ -67,11 +69,17 @@ let composition: FabricComposition | null = null;
 let ctxExports: CtxExports | null = null;
 
 /**
- * A program's filesystem errors reach it across workerd RPC, from the host
- * that answers its supervisor binding, and the program branches on the POSIX
- * `code` each one carries. workerd carries an error's own properties across
- * RPC only when the sending AND the receiving isolate have
- * `enhanced_error_serialization`, on by compatibility date from 2026-04-21:
+ * The compatibility flags a host composes the fabric under, refused without.
+ * Composing refuses wherever it composes (module scope: the Worker fails at
+ * startup; NimbusWorkspace.create: that call throws), naming the fix. Off
+ * workerd (bun, node) there is no `Cloudflare` global to read, and neither
+ * flag has anything to act on.
+ *
+ * `enhanced_error_serialization`: a program's filesystem errors reach it
+ * across workerd RPC, from the host that answers its supervisor binding, and
+ * the program branches on the POSIX `code` each one carries. workerd carries
+ * an error's own properties across RPC only when the sending AND the
+ * receiving isolate have the flag, on by compatibility date from 2026-04-21:
  * the serializer writes a native error as a host object with its own
  * properties only under the flag (src/workerd/jsg/ser.c++,
  * Serializer::IsHostObject), and the receiver reads that detail back only
@@ -79,22 +87,34 @@ let ctxExports: CtxExports | null = null;
  * https://developers.cloudflare.com/workers/runtime-apis/rpc/error-handling/.
  * Programs load at CF_COMPAT_DATE, past it. The host runs at its embedder's
  * date, and below it every ENOENT would reach every program as a bare message
- * it maps to EIO. So composing refuses such a host, wherever it composes
- * (module scope: the Worker fails at startup; NimbusWorkspace.create: that
- * call throws), and names both fixes: the flag alone keeps
- * every other behavior of the embedder's date. Off workerd (bun, node) there
- * is no RPC hop and no `Cloudflare` global to read.
+ * it maps to EIO. The flag alone keeps every other behavior of that date.
+ *
+ * `enable_request_signal`, which no compatibility date enables: a process
+ * owns work for a response until its client is done with it, and a client
+ * that goes away is seen only as the incoming request's `signal` aborting
+ * (src/workerd/io/worker-entrypoint.c++, "The client has disconnected").
+ * Without it a response whose client left keeps its process's work, and the
+ * host that runs it, held until the process writes again, or for good.
  */
-function requireEnhancedErrorSerialization(): void {
+function requireHostFlags(): void {
   // `typeof` of an undeclared global is 'undefined', not a ReferenceError.
   if (typeof Cloudflare === 'undefined') return;
-  if (Cloudflare.compatibilityFlags.enhanced_error_serialization === true) return;
-  throw new Error(
-    'fabric: this Worker runs without the enhanced_error_serialization compatibility flag, so the '
-      + "code on a program's filesystem error (ENOENT, EEXIST, ...) would not survive the RPC back "
-      + 'to it. Add "enhanced_error_serialization" to compatibility_flags in your wrangler config, '
-      + 'or set compatibility_date to 2026-04-21 or later.',
-  );
+  if (Cloudflare.compatibilityFlags.enhanced_error_serialization !== true) {
+    throw new Error(
+      'fabric: this Worker runs without the enhanced_error_serialization compatibility flag, so the '
+        + "code on a program's filesystem error (ENOENT, EEXIST, ...) would not survive the RPC back "
+        + 'to it. Add "enhanced_error_serialization" to compatibility_flags in your wrangler config, '
+        + 'or set compatibility_date to 2026-04-21 or later.',
+    );
+  }
+  if (Cloudflare.compatibilityFlags.enable_request_signal !== true) {
+    throw new Error(
+      'fabric: this Worker runs without the enable_request_signal compatibility flag, so a process '
+        + 'cannot see a client leave the response it is serving, and keeps that work held. Add '
+        + '"enable_request_signal" to compatibility_flags in your wrangler config; no compatibility '
+        + 'date enables it.',
+    );
+  }
 }
 
 /**
@@ -102,10 +122,10 @@ function requireEnhancedErrorSerialization(): void {
  * a second call with different values throws, naming both, so an embedder
  * whose composition lost to an earlier import learns it at startup rather
  * than from a facet that reached the wrong host. A host without
- * `enhanced_error_serialization` is refused.
+ * `enhanced_error_serialization` or `enable_request_signal` is refused.
  */
 export function composeFabric(value: FabricComposition): void {
-  requireEnhancedErrorSerialization();
+  requireHostFlags();
   if (!composition) {
     composition = value;
     return;

package/src/crc32.ts

@@ -9,26 +9,23 @@
  * Measured 2026-09-24 (5k files x 2 KiB; 64 MiB in 1 MiB buffers):
  * node:zlib's crc32 is 5-40x faster than any JavaScript loop in bun, node and
  * workerd (compat 2026-04-01, nodejs_compat), but each call costs ~0.14 us in
- * workerd, so below 128 bytes the table loop wins there. It is reached through
- * `process.getBuiltinModule`, like core's incremental SHA-256, so this module
- * imports nothing and still loads where node:zlib is absent (a browser,
- * workerd without nodejs_compat). The JavaScript path is slicing-by-8: 2-3x
- * the byte-at-a-time table loop in bun and node, and level with it in workerd.
+ * workerd, so below 128 bytes the table loop wins there. It is the realm's
+ * own (realmBuiltin), like core's incremental SHA-256's, so this module still
+ * loads where node:zlib is absent (a browser, workerd without nodejs_compat).
+ * The JavaScript path is slicing-by-8: 2-3x the byte-at-a-time table loop in
+ * bun and node, and level with it in workerd.
  */
 
+import { realmBuiltin } from './realm-builtin.js';
+
 type NodeZlib = { crc32?(data: Uint8Array, value?: number): number };
-type BuiltinModules = { process?: { getBuiltinModule?(id: 'node:zlib'): NodeZlib | undefined } };
 
 /** Below this many bytes the native call's overhead exceeds the JavaScript loop's work (workerd). */
 const CRC_NATIVE_MIN_BYTES = 128;
 
 const nativeCrc32 = (() => {
-  try {
-    const crc32 = (globalThis as BuiltinModules).process?.getBuiltinModule?.('node:zlib')?.crc32;
-    return typeof crc32 === 'function' ? crc32 : null;
-  } catch {
-    return null;
-  }
+  const crc32 = realmBuiltin<NodeZlib>('node:zlib')?.crc32;
+  return typeof crc32 === 'function' ? crc32 : null;
 })();
 
 /** Eight 256-entry tables: table k maps a byte to its CRC after k further zero bytes. */

package/src/diag-counters.ts

@@ -33,6 +33,7 @@
 // (parsing package-lock.json). See _shared/install-phase.ts for full
 // semantics documentation.
 import type { InstallPhase } from './install-phase.js';
+import { readSupervisorAllocationAttribution, type AllocationAttribution, type SupervisorAllocationLease } from './heavy-alloc-coord.js';
 
 export interface DiagCounters {
   /** Top-level install phase. */
@@ -62,13 +63,22 @@ export interface DiagCounters {
    * `buildPrefetchBundle` accumulates raw VFS file contents into an in-heap
    * bundle object, and used to do so with nothing observing it: the estimator
    * read 9.4 MiB while those bytes were resetting the DO. Each build now takes
-   * an `acquireSupervisorAllocation` lease for the budget it may use and bumps
-   * this alongside it, so the reservation is ATTRIBUTED to the bundle path
-   * rather than landing in `unattributedReservationBytes`.
+   * an `acquireSupervisorAllocation` lease for the budget it may use, counted
+   * here while it is held (attributeAllocation), so the reservation is
+   * ATTRIBUTED to the bundle path rather than landing in
+   * `unattributedReservationBytes`.
    *
    * Surfaced as `breakdown.prefetchBundleBytes`. Back to zero between builds.
    */
   prefetchBundleBytes: number;
+  /**
+   * Bytes the slices of pre-bundles in flight hold: each build's lease
+   * (browser-prebundle.ts), counted while it is held (attributeAllocation),
+   * after it shrinks to the slice it walked.
+   *
+   * Surfaced as `breakdown.preBundleSliceBytes`. Back to zero between builds.
+   */
+  preBundleSliceBytes: number;
   /**
    * Bytes retained by the FacetManager's prefetch-bundle LRU right now.
    *
@@ -145,10 +155,9 @@ export interface DiagCounters {
   };
 }
 
-const _counters: DiagCounters = {
+const _counters: Omit<DiagCounters, 'prefetchBundleBytes' | 'preBundleSliceBytes'> = {
   installPhase: 'idle',
   inFlightRpcPayloadBytes: 0,
-  prefetchBundleBytes: 0,
   prefetchCacheBytes: 0,
   supervisorAnsweredBytes: 0,
   installFacet: {
@@ -174,7 +183,7 @@ const _counters: DiagCounters = {
 
 /** Read a snapshot — caller-side mutations don't affect the singleton. */
 export function readDiagCounters(): DiagCounters {
-  return { ..._counters };
+  return { ..._counters, ...readSupervisorAllocationAttribution() };
 }
 
 /** Count `bytes` the session answered a process's supervisor call with. */
@@ -229,24 +238,16 @@ export function rpcPayloadEnd(bytes: number): void {
   }
 }
 
+/** The counters that name the live allocation leases of one owner. */
+export type AllocationOwner = AllocationAttribution;
+
 /**
- * Track an in-flight prefetch-bundle build. Call with the byte reservation the
- * build took from the supervisor allocation budget, and pair with
- * `prefetchBundleEnd` in the matching `finally` so it returns to zero whether
- * the build succeeded or threw.
+ * Attribution belongs to the budget's actual lease. The public gauges are
+ * derived from its holders, never maintained in a second counter registry.
  */
-export function prefetchBundleStart(bytes: number): void {
-  const n = Number(bytes);
-  if (!Number.isFinite(n) || n <= 0) return;
-  _counters.prefetchBundleBytes += n;
-}
-
-/** Release an in-flight prefetch-bundle reservation. Floors at 0. */
-export function prefetchBundleEnd(bytes: number): void {
-  const n = Number(bytes);
-  if (!Number.isFinite(n) || n <= 0) return;
-  _counters.prefetchBundleBytes -= n;
-  if (_counters.prefetchBundleBytes < 0) _counters.prefetchBundleBytes = 0;
+export function attributeAllocation(owner: AllocationOwner, lease: SupervisorAllocationLease): SupervisorAllocationLease {
+  lease.attribute(owner);
+  return lease;
 }
 
 /**

package/src/heap-estimate.ts

@@ -58,11 +58,7 @@
  * recovery_event ring, separate from this module.
  */
 
-import {
-  PRE_BUNDLE_CONCURRENCY,
-  PRE_BUNDLE_SLICE_CAP_BYTES,
-  SUPERVISOR_HEAP_CEILING_BYTES,
-} from './limits.js';
+import { SUPERVISOR_HEAP_CEILING_BYTES } from './limits.js';
 import type { DiagCounters } from './diag-counters.js';
 import {
   readSupervisorAllocationBudget,
@@ -169,9 +165,11 @@ export interface HeapBreakdown {
   vfsLruBytes: number;
   /** SqliteVFS current logical retained write payload bytes. */
   vfsInFlightBytes: number;
-  /** Pre-bundle slice bytes resident in supervisor heap (peak across
-   *  in-flight pool slots × SLICE_CAP_BYTES). Drops to 0 once
-   *  A'.2/A'.3 stream the slice through ReadableStream-over-RPC. */
+  /**
+   * Bytes the slices of pre-bundles in flight hold (diag-counters
+   * `preBundleSliceBytes`): each build's lease, from its worst case down to
+   * the slice it walked, released as the build ends, however it ends.
+   */
   preBundleSliceBytes: number;
   /**
    * In-flight supervisor RPC payload bytes (Phase 2 A'.2).
@@ -243,32 +241,6 @@ export interface VfsHeapInputs {
  */
 const SUPERVISOR_BASELINE_BYTES = 9 * 1024 * 1024;
 
-/**
- * Estimate pre-bundle slice bytes resident in the supervisor heap.
- *
- * Pre A'.2: the supervisor builds the slice in heap (up to
- * SLICE_CAP_BYTES = 28 MiB per concurrent slot) before passing to the
- * pre-bundle facet. With PRE_BUNDLE_CONCURRENCY = 1 the cap is 28 MiB.
- *
- * Diag counters track pre-bundle attempts/completions but not
- * in-flight slice bytes specifically. Until A'.2 streams the slice,
- * we treat the slice as PRESENT in supervisor heap iff the pre-bundle
- * phase is active AND a slot is in flight (no completion yet for the
- * current attempted count).
- *
- * After A'.2 lands the slice flows via ReadableStream-over-RPC and
- * supervisor never holds the bytes — this contribution drops to 0.
- */
-export function estimatePreBundleSliceBytes(c: DiagCounters): number {
-  // Conservative: if the most recent batch attempted >0 specs and the
-  // batch hasn't fully completed, assume one slice's worth of bytes
-  // are in flight.
-  const f = c.preBundleFacet;
-  const inFlight = f.attempted - f.bundlesCompleted - f.errors - f.skipped;
-  if (inFlight <= 0) return 0;
-  return Math.min(inFlight, PRE_BUNDLE_CONCURRENCY) * PRE_BUNDLE_SLICE_CAP_BYTES;
-}
-
 /**
  * Build a heap estimate from runtime counters + VFS inputs.
  *
@@ -280,20 +252,19 @@ export function estimateSupervisorHeap(
   vfs: VfsHeapInputs,
 ): HeapEstimate {
   const allocationBudget = readSupervisorAllocationBudget();
-  const preBundleSliceBytes = estimatePreBundleSliceBytes(c);
-  // The prefetch build holds a lease, so its bytes are already inside
-  // allocationBudget.current — naming it here moves it out of the
-  // unattributed remainder rather than adding to the total twice.
+  // The prefetch build and the pre-bundle hold leases, so their bytes are
+  // already inside allocationBudget.current — naming them here moves them out
+  // of the unattributed remainder rather than adding to the total twice.
   const transientAttributedBytes =
     vfs.inFlightWriteBytes +
-    preBundleSliceBytes +
+    c.preBundleSliceBytes +
     c.inFlightRpcPayloadBytes +
     c.prefetchBundleBytes;
   const breakdown: HeapBreakdown = {
     supervisorBaselineBytes: SUPERVISOR_BASELINE_BYTES,
     vfsLruBytes: vfs.cacheHotBytes,
     vfsInFlightBytes: vfs.inFlightWriteBytes,
-    preBundleSliceBytes,
+    preBundleSliceBytes: c.preBundleSliceBytes,
     streamingBuffersBytes: c.inFlightRpcPayloadBytes,
     prefetchBundleBytes: c.prefetchBundleBytes,
     prefetchCacheBytes: c.prefetchCacheBytes,