@nimbus-sh/platform 0.8.1 → 0.13.0

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,

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;
+}