@nimbus-sh/platform 0.8.2 → 0.13.0

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,

package/src/heavy-alloc-coord.ts

@@ -11,6 +11,7 @@
 import {
   CHUNK_SIZE,
   SUPERVISOR_IN_FLIGHT_ALLOCATION_BUDGET_BYTES,
+  SUPERVISOR_LOAD_WAIT_MS,
   SUPERVISOR_READ_RESERVE_BYTES,
 } from './limits.js';
 import {
@@ -24,6 +25,58 @@ export interface SupervisorAllocationBudgetStats {
   readonly current: number;
   readonly peak: number;
   readonly queued: number;
+  readonly holders: SupervisorAllocationHolder[];
+  readonly waiting: SupervisorAllocationHolder[];
+}
+
+export type AllocationAttribution = 'prefetchBundleBytes' | 'preBundleSliceBytes';
+export interface SupervisorAllocationOwner {
+  owner: string;
+  pid?: number;
+  session?: string;
+  attribution?: AllocationAttribution;
+}
+export interface SupervisorAllocationHolder {
+  owner: string;
+  bytes: number;
+  ageMs: number;
+  pid?: number;
+  session?: string;
+}
+export interface SupervisorAllocationLease extends ResizableCreditLease {
+  attribute(attribution: AllocationAttribution): void;
+}
+interface AllocationHolder {
+  owner: SupervisorAllocationOwner;
+  credit: ResizableCreditLease;
+  since: number;
+}
+interface AllocationWaiter {
+  owner: SupervisorAllocationOwner;
+  bytes: number;
+  since: number;
+}
+const DEFAULT_ALLOCATION_OWNER: SupervisorAllocationOwner = { owner: 'supervisor allocation' };
+const MAX_ALLOCATION_OWNER_ROWS = 16;
+
+/**
+ * A facet's load the budget did not admit within its bound
+ * (SUPERVISOR_LOAD_WAIT_MS): nothing of it was read, and the facet is not
+ * started. Resource temporarily unavailable, as the ledger's refusal of a
+ * wait no release can satisfy is.
+ */
+export class SupervisorLoadWaitError extends Error {
+  readonly code = 'EAGAIN';
+  readonly errno = -11;
+  constructor(readonly load: string, readonly bytes: number, readonly waitedMs: number, readonly held: SupervisorAllocationBudgetStats) {
+    super(
+      `Resource temporarily unavailable: ${load} (${bytes.toLocaleString('en-US')} bytes) waited ${waitedMs} ms `
+        + `for this isolate's transient allocation budget and was not admitted (${held.current.toLocaleString('en-US')} `
+        + `of ${held.capacity.toLocaleString('en-US')} bytes held, ${held.queued} owners queued); `
+        + `holders=${JSON.stringify(held.holders)} waiting=${JSON.stringify(held.waiting)}`,
+    );
+    this.name = 'SupervisorLoadWaitError';
+  }
 }
 
 interface AllocationBudgetLifecycle {
@@ -44,6 +97,8 @@ export class SupervisorAllocationBudget {
    * cache it is filling.
    */
   private lifecycleHolders = 0;
+  private readonly holders = new Set<AllocationHolder>();
+  private readonly waiting = new Set<AllocationWaiter>();
 
   constructor(
     readonly capacity: number,
@@ -54,19 +109,33 @@ export class SupervisorAllocationBudget {
   }
 
   get stats(): SupervisorAllocationBudgetStats {
+    const now = Date.now();
+    const describe = (owner: SupervisorAllocationOwner, bytes: number, since: number): SupervisorAllocationHolder => ({
+      owner: owner.owner.slice(0, 256), bytes, ageMs: Math.max(0, now - since),
+      ...(owner.pid === undefined ? {} : { pid: owner.pid }), ...(owner.session === undefined ? {} : { session: owner.session }),
+    });
     return {
       capacity: this.capacity,
       ...this.credits.stats,
+      holders: [...this.holders].sort((a, b) => b.credit.bytes - a.credit.bytes).slice(0, MAX_ALLOCATION_OWNER_ROWS)
+        .map(({ owner, credit, since }) => describe(owner, credit.bytes, since)),
+      waiting: [...this.waiting].slice(0, MAX_ALLOCATION_OWNER_ROWS).map(({ owner, bytes, since }) => describe(owner, bytes, since)),
     };
   }
 
+  get attributed(): Record<AllocationAttribution, number> {
+    const totals = { prefetchBundleBytes: 0, preBundleSliceBytes: 0 };
+    for (const { owner, credit } of this.holders) if (owner.attribution !== undefined) totals[owner.attribution] += credit.bytes;
+    return totals;
+  }
+
   /**
    * Reserve bytes and, while held, mark the budget active so observers can
    * free heap headroom. For owners whose payload is what the headroom is for:
    * installs, clones, pre-bundles, boot payloads, streamed writes.
    */
-  acquire(bytes: number, signal?: AbortSignal): Promise<ResizableCreditLease> {
-    return this._acquire(bytes, signal, true);
+  acquire(bytes: number, signal?: AbortSignal, owner = DEFAULT_ALLOCATION_OWNER): Promise<SupervisorAllocationLease> {
+    return this._acquire(bytes, signal, true, owner);
   }
 
   /**
@@ -78,25 +147,119 @@ export class SupervisorAllocationBudget {
    * never warming. The byte credit is still taken — back-pressure is what
    * stops a large read overlapping a large write.
    */
-  acquireWithoutLifecycle(bytes: number, signal?: AbortSignal): Promise<ResizableCreditLease> {
-    return this._acquire(bytes, signal, false);
+  acquireWithoutLifecycle(bytes: number, signal?: AbortSignal, owner = DEFAULT_ALLOCATION_OWNER): Promise<SupervisorAllocationLease> {
+    return this._acquire(bytes, signal, false, owner);
+  }
+
+  /**
+   * Reserve what a facet's load holds while the loader takes its module map:
+   * `bytes`, or for a load larger than the whole budget the whole budget, so
+   * that it holds it alone and every owner after it waits. Granted in the
+   * budget's one FIFO order, so no owner queued after a load overtakes it,
+   * however small, and refused with SupervisorLoadWaitError when not granted
+   * within `waitMs`. Like a copy it holds bytes the session already has, for
+   * as long as the load takes, so the disposable VFS cache is not shrunk.
+   */
+  async acquireLoad(load: string, bytes: number, options: { waitMs: number; signal?: AbortSignal; owner?: SupervisorAllocationOwner }): Promise<SupervisorAllocationLease> {
+    options.signal?.throwIfAborted();
+    const wanted = Math.min(bytes, this.capacity);
+    // Granted at once when nothing is queued and it fits, with no bound to arm.
+    const owner = options.owner ?? { owner: load };
+    const now = this.tryAcquire(wanted, false, owner);
+    if (now) return now;
+    const started = Date.now();
+    const bound = new AbortController();
+    // Cleared as the wait settles: a pending timer keeps the hosting object from hibernating.
+    const timer = setTimeout(() => bound.abort(), options.waitMs);
+    try {
+      return await this._acquire(wanted, options.signal ? AbortSignal.any([bound.signal, options.signal]) : bound.signal, false, owner);
+    } catch (error) {
+      if (bound.signal.aborted && options.signal?.aborted !== true) throw new SupervisorLoadWaitError(load, bytes, Date.now() - started, this.stats);
+      throw error;
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+
+  /** Reclaimers of parked launches' retained credit, oldest registered first (reclaimable). */
+  private readonly reclaimers = new Set<() => void>();
+
+  /**
+   * Register `reclaim`, which gives a parked launch's retained credit back
+   * before it returns (its map dropped, its lease released, the launch sent
+   * back to prepare), for running work to call when nothing else frees what
+   * it needs (acquireRunning). Unregistered just before it is called; the
+   * returned function unregisters it.
+   */
+  reclaimable(reclaim: () => void): () => void {
+    this.reclaimers.add(reclaim);
+    // A running ask queued before this launch parked is owed it, once the registration has returned.
+    if (this.credits.aheadStarved) queueMicrotask(() => this.reclaimForRunning());
+    return () => {
+      this.reclaimers.delete(reclaim);
+    };
+  }
+
+  /**
+   * Running work's credit, the lock order's one exception
+   * (acquireSupervisorLoad): granted at once where it fits, ahead of every
+   * queued ask; else, queued ahead of them all, it reclaims parked launches'
+   * retained credit, the oldest first, until it is granted; else it waits
+   * only for credit other running work holds.
+   */
+  async acquireRunning(bytes: number, signal?: AbortSignal, drivesLifecycle = true, owner = DEFAULT_ALLOCATION_OWNER): Promise<SupervisorAllocationLease> {
+    const wanted = Math.min(bytes, this.capacity);
+    const waiter = { owner: { ...owner }, bytes: wanted, since: Date.now() };
+    this.waiting.add(waiter);
+    try {
+      const lease = this.credits.acquireAhead(wanted, signal);
+      this.reclaimForRunning();
+      const credit = await lease;
+      this.waiting.delete(waiter);
+      return this.wrap(credit, drivesLifecycle, waiter.owner);
+    } finally { this.waiting.delete(waiter); }
+  }
+
+  /** Reclaim parked launches' credit, the oldest parked first, while a running ask waits: what a reclaim frees goes to running asks first. */
+  private reclaimForRunning(): void {
+    for (const reclaim of this.reclaimers) {
+      if (!this.credits.aheadStarved) return;
+      this.reclaimers.delete(reclaim);
+      reclaim();
+    }
   }
 
-  /** Reserve bytes now or not at all, driving the lifecycle as acquire does. */
-  tryAcquire(bytes: number): ResizableCreditLease | null {
+  /** acquireRunning's credit now, ahead of every queued ask, without reclaiming, or null. */
+  tryAcquireRunning(bytes: number, owner = DEFAULT_ALLOCATION_OWNER): SupervisorAllocationLease | null {
+    const credit = this.credits.tryAcquireAhead(Math.min(bytes, this.capacity));
+    return credit ? this.wrap(credit, true, owner) : null;
+  }
+
+  /** Reserve bytes now or not at all, driving the lifecycle as acquire does (or not, `drivesLifecycle` false). */
+  tryAcquire(bytes: number, drivesLifecycle = true, owner = DEFAULT_ALLOCATION_OWNER): SupervisorAllocationLease | null {
     const credit = this.credits.tryAcquire(bytes);
-    return credit ? this.wrap(credit, true) : null;
+    return credit ? this.wrap(credit, drivesLifecycle, owner) : null;
   }
 
   private async _acquire(
     bytes: number,
     signal: AbortSignal | undefined,
     drivesLifecycle: boolean,
-  ): Promise<ResizableCreditLease> {
-    return this.wrap(await this.credits.acquire(bytes, signal), drivesLifecycle);
+    owner: SupervisorAllocationOwner,
+  ): Promise<SupervisorAllocationLease> {
+    const waiter = { owner: { ...owner }, bytes, since: Date.now() };
+    this.waiting.add(waiter);
+    try {
+      const credit = await this.credits.acquire(bytes, signal);
+      this.waiting.delete(waiter);
+      return this.wrap(credit, drivesLifecycle, waiter.owner);
+    }
+    finally { this.waiting.delete(waiter); }
   }
 
-  private wrap(credit: ResizableCreditLease, drivesLifecycle: boolean): ResizableCreditLease {
+  private wrap(credit: ResizableCreditLease, drivesLifecycle: boolean, owner: SupervisorAllocationOwner): SupervisorAllocationLease {
+    const holder = { owner: { ...owner }, credit, since: Date.now() };
+    this.holders.add(holder);
     if (drivesLifecycle) {
       this.lifecycleHolders++;
       if (!this.active) {
@@ -113,9 +276,12 @@ export class SupervisorAllocationBudget {
       shrinkTo: (nextBytes: number) => {
         credit.shrinkTo(nextBytes);
       },
+      tryGrowTo: (nextBytes: number) => credit.tryGrowTo(nextBytes),
+      attribute: (attribution) => { if (!released) holder.owner = { ...holder.owner, attribution }; },
       release: () => {
         if (released) return;
         released = true;
+        this.holders.delete(holder);
         credit.release();
         if (!drivesLifecycle) return;
         this.lifecycleHolders--;
@@ -217,35 +383,120 @@ const supervisorAllocationBudget = new SupervisorAllocationBudget(
 export function acquireSupervisorAllocation(
   bytes: number,
   signal?: AbortSignal,
-): Promise<ResizableCreditLease> {
-  return supervisorAllocationBudget.acquire(bytes, signal);
+  owner?: SupervisorAllocationOwner,
+): Promise<SupervisorAllocationLease> {
+  return supervisorAllocationBudget.acquire(bytes, signal, owner);
 }
 
 /** Reserve bytes now if they can be granted without waiting, else null. */
-export function tryAcquireSupervisorAllocation(bytes: number): ResizableCreditLease | null {
-  return supervisorAllocationBudget.tryAcquire(bytes);
+export function tryAcquireSupervisorAllocation(bytes: number, owner?: SupervisorAllocationOwner): SupervisorAllocationLease | null {
+  return supervisorAllocationBudget.tryAcquire(bytes, true, owner);
 }
 
 /**
- * Reserve bytes for a filesystem READ. Takes the same byte credit as any
- * other owner but does not shrink the disposable VFS cache, which reads are
- * there to fill.
+ * Reserve bytes for a running process's filesystem READ (its read RPCs):
+ * running work (acquireRunning), which does not shrink the disposable VFS
+ * cache, which reads are there to fill.
  */
 export function acquireSupervisorReadAllocation(
   bytes: number,
   signal?: AbortSignal,
-): Promise<ResizableCreditLease> {
-  return supervisorAllocationBudget.acquireWithoutLifecycle(bytes, signal);
+  owner?: SupervisorAllocationOwner,
+): Promise<SupervisorAllocationLease> {
+  return supervisorAllocationBudget.acquireRunning(bytes, signal, false, owner ?? { owner: 'running filesystem read' });
+}
+
+/**
+ * Reserve bytes for a short-lived copy of what the session already holds
+ * (a launch's module map made from a staged state), now or not at all, or
+ * by waiting (`signal`): the byte credit bounds how many such copies are
+ * live at once, but the disposable VFS cache is not shrunk for one, as it
+ * is not for a read. Shrinking it for every launch of a program already
+ * built cost each one its cache, and the copy is no install.
+ */
+export function tryAcquireSupervisorCopyAllocation(bytes: number, owner?: SupervisorAllocationOwner): SupervisorAllocationLease | null {
+  return supervisorAllocationBudget.tryAcquire(bytes, false, owner ?? { owner: 'supervisor copy' });
+}
+
+/** {@link tryAcquireSupervisorCopyAllocation}, waiting for room. */
+export function acquireSupervisorCopyAllocation(bytes: number, signal?: AbortSignal, owner?: SupervisorAllocationOwner): Promise<SupervisorAllocationLease> {
+  return supervisorAllocationBudget.acquireWithoutLifecycle(bytes, signal, owner ?? { owner: 'supervisor copy' });
+}
+
+/**
+ * `bytes` of this isolate for a facet's load (the wasm images read for it;
+ * `name` says whose), admitted on the supervisor budget
+ * (SupervisorAllocationBudget.acquireLoad): FIFO, the whole budget for one
+ * larger than it, refused by name after SUPERVISOR_LOAD_WAIT_MS. `signal`
+ * ends the wait.
+ *
+ * Lock order: supervisor credit, then a Dynamic Worker. Nothing waits for
+ * credit (SupervisorAllocationBudget acquire or acquireLoad, or growing a
+ * lease) while it holds a worker's fetch hold (beginLoaderFetch,
+ * claimAdmission, readmitRefused). While it holds one, it may give credit
+ * back, shrink it, or take credit without waiting (tryAcquire). Running work
+ * is the one exception, and comes first. Credit a running process needs (its
+ * write waves and the session RPCs it makes, through acquireRunning)
+ * overtakes every queued ask. When nothing else frees it, it reclaims parked
+ * launches' retained maps, oldest parked first: each is dropped, its launch
+ * is sent back to prepare, and the map is rebuilt at that launch's turn.
+ * Otherwise it waits only for credit other running work holds. A facet's load
+ * is not running work.
+ */
+export function acquireSupervisorLoad(name: string, bytes: number, signal?: AbortSignal, owner?: SupervisorAllocationOwner): Promise<SupervisorAllocationLease> {
+  return supervisorAllocationBudget.acquireLoad(name, bytes, { waitMs: SUPERVISOR_LOAD_WAIT_MS, signal, owner });
+}
+
+/** acquireSupervisorLoad's credit now, without waiting, or null: all a load may take while it holds a worker. */
+export function tryAcquireSupervisorLoad(bytes: number, owner: SupervisorAllocationOwner = { owner: 'facet load' }): SupervisorAllocationLease | null {
+  return supervisorAllocationBudget.tryAcquire(Math.min(bytes, supervisorAllocationBudget.capacity), false, owner);
+}
+
+/**
+ * Running work's credit (SupervisorAllocationBudget.acquireRunning): what a
+ * running process needs to go on (its write waves, the session RPCs it
+ * makes), never held up by a launch that is not running.
+ */
+export function acquireSupervisorRunningAllocation(bytes: number, signal?: AbortSignal, owner?: SupervisorAllocationOwner): Promise<SupervisorAllocationLease> {
+  return supervisorAllocationBudget.acquireRunning(bytes, signal, true, owner ?? { owner: 'running supervisor work' });
+}
+
+/** acquireSupervisorRunningAllocation's credit now, ahead of every queued ask, without reclaiming, or null. */
+export function tryAcquireSupervisorRunningAllocation(bytes: number, owner?: SupervisorAllocationOwner): SupervisorAllocationLease | null {
+  return supervisorAllocationBudget.tryAcquireRunning(bytes, owner ?? { owner: 'running supervisor work' });
+}
+
+/** Register a parked launch's reclaimer on the isolate's budget (SupervisorAllocationBudget.reclaimable). */
+export function reclaimableSupervisorAllocation(reclaim: () => void): () => void {
+  return supervisorAllocationBudget.reclaimable(reclaim);
+}
+
+/** Run `load` holding acquireSupervisorLoad's credit for `bytes`, given back as it settles; for a load no worker hold waits on. */
+export async function withSupervisorLoadAllocation<T>(
+  name: string,
+  bytes: number,
+  signal: AbortSignal | undefined,
+  load: () => Promise<T>,
+  owner?: SupervisorAllocationOwner,
+): Promise<T> {
+  if (bytes === 0) return load();
+  const lease = await acquireSupervisorLoad(name, bytes, signal, owner);
+  try {
+    return await load();
+  } finally {
+    lease.release();
+  }
 }
 
 /**
  * Reserve the full budget for an allocation whose retained size is not known
  * accurately enough to overlap safely with other heavy work.
  */
-export async function acquireHeavyAlloc(signal?: AbortSignal): Promise<() => void> {
+export async function acquireHeavyAlloc(signal?: AbortSignal, owner: SupervisorAllocationOwner = { owner: 'heavy supervisor work' }): Promise<() => void> {
   const lease = await acquireSupervisorAllocation(
     SUPERVISOR_IN_FLIGHT_ALLOCATION_BUDGET_BYTES,
     signal,
+    owner,
   );
   return lease.release;
 }
@@ -253,3 +504,7 @@ export async function acquireHeavyAlloc(signal?: AbortSignal): Promise<() => voi
 export function readSupervisorAllocationBudget(): SupervisorAllocationBudgetStats {
   return supervisorAllocationBudget.stats;
 }
+
+export function readSupervisorAllocationAttribution(): Record<AllocationAttribution, number> {
+  return supervisorAllocationBudget.attributed;
+}

package/src/hex.ts

@@ -0,0 +1,29 @@
+/**
+ * hex.ts — bytes as unseparated lowercase hex: the spelling of every content
+ * key, digest, object id and token Nimbus writes. It imports nothing, so a
+ * compiled guest body or a facet bundle takes it along; a hash is its
+ * caller's, as is any width, offset or truncation.
+ */
+
+/**
+ * Each byte value's two hex digits: for a reader that spells a window of a
+ * larger buffer in place (git's object ids in a pack or a tree), where V8
+ * encodes a view natively slower than this table walks it.
+ */
+export const HEX_BYTE: readonly string[] = Array.from({ length: 256 }, (_, byte) => byte.toString(16).padStart(2, '0'));
+/** Uint8Array.prototype, with ES2026's toHex where the runtime has it: this TypeScript's library does not declare it. */
+const prototype: Uint8Array & { toHex?: (this: Uint8Array) => string } = Uint8Array.prototype;
+const nativeHex = prototype.toHex;
+
+/**
+ * Lowercase hex of `bytes`. A listing encodes one key per file, so this is
+ * on the enumeration's hot path: the native encoder where the runtime has
+ * one, else a table (measured 0.03 and 0.17 µs per 32-byte key, against
+ * 0.82 for a toString/padStart loop).
+ */
+export function bytesToHex(bytes: Uint8Array): string {
+  if (nativeHex !== undefined) return nativeHex.call(bytes);
+  let out = '';
+  for (let i = 0; i < bytes.length; i++) out += HEX_BYTE[bytes[i]!];
+  return out;
+}

package/src/install-phase.ts

@@ -2,21 +2,7 @@
  * _shared/install-phase.ts — single source of truth for the npm-install
  * state-machine phase enum.
  *
- * History: CLN-1 (2026-05-11) — consolidated from two diverged copies.
- *   - `npm/installer.ts:93-95` was the progress-event variant. Included
- *     'lock-check' (a real progress event emitted while parsing
- *     package-lock.json) but lacked 'idle'.
- *   - `observability/diag-counters.ts:33-35` was the counter-state variant.
- *     Included 'idle' (the resting state when no install is in flight)
- *     but lacked 'lock-check'. The diag-counter's `setInstallPhase()`
- *     was actually called with 'idle' (installer.ts:184,201) — passing
- *     a value not declared in installer.ts's local type. The type check
- *     fell through to diag-counters' type because installer.ts imports
- *     setInstallPhase from there; the local `InstallPhase` definition
- *     in installer.ts was only used by `InstallProgress.phase`.
- *
- * Going forward both consumers import from this module; any new phase
- * value added here is automatically available everywhere.
+ * Every consumer imports it from here, so a phase added here is everyone's.
  *
  * Phase semantics (chronological order for a single install run):
  *

package/src/lexical-path.ts

@@ -0,0 +1,17 @@
+/**
+ * The names of `path` once it is resolved lexically, after the names of
+ * `base` (taken as they are, not reduced again): empty names and `.`
+ * dropped, each `..` taking back the name before it, and a `..` at the root
+ * staying at the root, as POSIX resolves `/..`. The one root-clamped lexical
+ * reduction; whether the path was absolute or ended in `/` is its caller's to
+ * keep. Lexical only: a `..` after a symlink is not the link's parent, so a
+ * walk that follows links resolves it as it goes.
+ */
+export function rootClampedSegments(path: string, base: readonly string[] = []): string[] {
+  const out = [...base];
+  for (const segment of path.split('/')) {
+    if (segment === '..') out.pop();
+    else if (segment !== '' && segment !== '.') out.push(segment);
+  }
+  return out;
+}

package/src/limits.ts

@@ -197,6 +197,26 @@ export const FACET_OWN_WRITE_MEMORY_BYTES = 32 * 1024 * 1024;
 // holds nothing more and the session answers.
 export const WASI_RESIDENT_STORE_BYTES = 32 * 1024 * 1024;
 
+// A file too big to hold whole (over WASI_RESIDENT_FILE_CAP_BYTES: a pack, a
+// deep history's .idx) is read through the resident store a page at a time:
+// git's own unit for a paged pack index, and a sixteenth of its 1 MiB pack
+// window, so one window is one batch read.
+export const RESIDENT_PAGE_BYTES = 64 * 1024;
+
+// The most a resident store holds of such pages, least recently used out
+// first; in a one-shot's heap, never more than half its budget. Measured on vscode's full history (2.18M objects):
+// a .idx of 57.5 MiB, of which every command touched ~49 MiB, and a .rev of
+// 8.6 MiB, so the bound keeps a deep history's index and its hot pack windows.
+export const RESIDENT_PAGE_CACHE_BYTES = 512 * 1024 * 1024;
+
+// The pages are a cache in the session's one storage limit (N18), which the
+// user's files share: they never hold more than this share of what they hold
+// plus what the ledger says is still free at the last grant, so a filling
+// session takes room from the cache, not from the user. Evicted pages are
+// reused by the same facet database; its size, which df counts, stays at its
+// high-water mark until the facet's storage is deleted.
+export const RESIDENT_PAGE_CACHE_FREE_SHARE = 0.25;
+
 // Shared allowance for transient allocations in the supervisor DO. With the
 // VFS LRU shrunk to 8 MiB during an active reservation, 40 MiB of admitted
 // payload plus the 9 MiB bundle baseline stays below the 64 MiB soft ceiling
@@ -204,6 +224,15 @@ export const WASI_RESIDENT_STORE_BYTES = 32 * 1024 * 1024;
 // This is 31.25% of the platform's 128 MiB hard isolate ceiling.
 export const SUPERVISOR_IN_FLIGHT_ALLOCATION_BUDGET_BYTES = 40 * 1024 * 1024;
 
+// The longest a facet's load waits for that allowance before it is refused
+// (acquireSupervisorLoadAllocation). The wait is FIFO, so a load waits only
+// for the holds ahead of it, each of which ends when its own work does. A
+// load is the one owner that waits while it holds a Dynamic Worker (the
+// loader asks for its code then), so a launch that holds credit while it
+// waits for a worker of the same Durable Object can close a cycle nothing
+// ends: the bound refuses the load, by name, instead of leaving both to hang.
+export const SUPERVISOR_LOAD_WAIT_MS = 60_000;
+
 // Reserved slice of that allowance for chunk-sized filesystem reads, so a
 // read is never queued behind a multi-megabyte owner for a wait that has
 // nothing to do with its own cost. A read only draws on this when the shared

package/src/module-source.ts

@@ -1,3 +1,5 @@
+import { utf8Length } from './utf8.js';
+
 /** A deployed source asset: its digest, not its pathname, is its identity. */
 export interface ModuleSourceAsset {
   path: string;
@@ -26,7 +28,7 @@ export class ModuleSource {
   private joined: string | undefined;
   readonly byteLength: number;
   constructor(readonly parts: readonly ModuleSourcePart[]) {
-    this.byteLength = parts.reduce((bytes, part) => bytes + (typeof part === 'string' ? new TextEncoder().encode(part).byteLength : part.byteLength), 0);
+    this.byteLength = parts.reduce((bytes, part) => bytes + (typeof part === 'string' ? utf8Length(part) : part.byteLength), 0);
   }
   get text(): string {
     return this.joined ??= this.parts.map((part) => typeof part === 'string' ? part : part.text).join('');

package/src/oom-classify.ts

@@ -273,6 +273,10 @@ export type DoCallClass =
   | 'storage_reset'
   /** The runtime flagged the error `retryable` itself. */
   | 'retryable_flag'
+  /** The platform failed the call without saying why ("internal error;
+   *  reference = …", isUnexplainedPlatformError): whether it ran is unknown.
+   *  Not a transient class: only a callee that converges repeats it. */
+  | 'platform_internal'
   /** The object shed the call under queue pressure. NEVER retried: retrying
    *  an overloaded object is what overloaded it. */
   | 'overloaded'
@@ -317,6 +321,7 @@ export function classifyDoCall(input: unknown): DoCallClass {
   const seen = new Set<Error>();
   const messages: string[] = [];
   let flagged = false;
+  let unexplained = false;
   let link: Error | null = input;
   while (link !== null && !seen.has(link)) {
     seen.add(link);
@@ -324,6 +329,7 @@ export function classifyDoCall(input: unknown): DoCallClass {
       || isDoOverloaded(link.message);
     if (overloaded) return 'overloaded';
     if ('retryable' in link && link.retryable === true) flagged = true;
+    if (isUnexplainedPlatformError(link)) unexplained = true;
     messages.push(link.message ?? '');
     const cause: unknown = link.cause;
     link = cause instanceof Error ? cause : null;
@@ -333,6 +339,8 @@ export function classifyDoCall(input: unknown): DoCallClass {
     if (pattern.test(chain)) return transient;
   }
   if (flagged) return 'retryable_flag';
+  // Only where nothing in the chain explains it: a wrapper's own words are not the platform's.
+  if (unexplained) return 'platform_internal';
   return 'permanent';
 }
 

package/src/realm-builtin.ts

@@ -0,0 +1,22 @@
+/**
+ * A Node builtin of the realm's own process (`process.getBuiltinModule`),
+ * never a program's: a Nimbus runtime that puts a program's process in front
+ * of the realm's (node-shims) records the realm's own under
+ * `Symbol.for('nimbus.fronts')`, and a warm isolate keeps the last program's
+ * process as the global after it ends. Its builtins carry Node's argument
+ * checks and errors for programs, which the runtime's own callers pay for
+ * on every call. Undefined where the realm has no such builtin.
+ */
+type BuiltinProcess = { getBuiltinModule?(id: string): unknown };
+type Fronts = WeakMap<object, { own: unknown }>;
+
+export function realmBuiltin<T>(id: string): T | undefined {
+  try {
+    const global = globalThis as { process?: BuiltinProcess } & Record<symbol, Fronts | undefined>;
+    const current = global.process;
+    const own = (current && global[Symbol.for('nimbus.fronts')]?.get(current)?.own) as BuiltinProcess | undefined;
+    return (own ?? current)?.getBuiltinModule?.(id) as T | undefined;
+  } catch {
+    return undefined;
+  }
+}