@nimbus-sh/platform 0.8.2 → 0.14.0

package/dist/heavy-alloc-coord.js

@@ -7,8 +7,35 @@
  * budget. Full-budget owners are exclusive; weighted owners may overlap only
  * while their retained-byte claims fit together.
  */
-import { CHUNK_SIZE, SUPERVISOR_IN_FLIGHT_ALLOCATION_BUDGET_BYTES, SUPERVISOR_READ_RESERVE_BYTES, } from './limits.js';
+import { CHUNK_SIZE, SUPERVISOR_IN_FLIGHT_ALLOCATION_BUDGET_BYTES, SUPERVISOR_LOAD_WAIT_MS, SUPERVISOR_READ_RESERVE_BYTES, } from './limits.js';
 import { WeightedCreditPool, } from './weighted-credit-pool.js';
+const DEFAULT_ALLOCATION_OWNER = { 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 {
+    load;
+    bytes;
+    waitedMs;
+    held;
+    code = 'EAGAIN';
+    errno = -11;
+    constructor(load, bytes, waitedMs, held) {
+        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.load = load;
+        this.bytes = bytes;
+        this.waitedMs = waitedMs;
+        this.held = held;
+        this.name = 'SupervisorLoadWaitError';
+    }
+}
 /**
  * Reusable contract behind the supervisor singleton. A separate instance is
  * useful in tests and keeps the invariant independent of Nimbus internals.
@@ -24,24 +51,41 @@ export class SupervisorAllocationBudget {
      * cache it is filling.
      */
     lifecycleHolders = 0;
+    holders = new Set();
+    waiting = new Set();
     constructor(capacity, lifecycle = {}, reserve = {}) {
         this.capacity = capacity;
         this.lifecycle = lifecycle;
         this.credits = new WeightedCreditPool(capacity, reserve);
     }
     get stats() {
+        const now = Date.now();
+        const describe = (owner, bytes, since) => ({
+            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() {
+        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, signal) {
-        return this._acquire(bytes, signal, true);
+    acquire(bytes, signal, owner = DEFAULT_ALLOCATION_OWNER) {
+        return this._acquire(bytes, signal, true, owner);
     }
     /**
      * Reserve bytes WITHOUT driving the cache lifecycle, for owners that are
@@ -52,18 +96,116 @@ 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, signal) {
-        return this._acquire(bytes, signal, false);
+    acquireWithoutLifecycle(bytes, signal, owner = DEFAULT_ALLOCATION_OWNER) {
+        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, bytes, options) {
+        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). */
+    reclaimers = new Set();
+    /**
+     * 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) {
+        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, signal, drivesLifecycle = true, owner = DEFAULT_ALLOCATION_OWNER) {
+        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);
+        }
     }
-    /** Reserve bytes now or not at all, driving the lifecycle as acquire does. */
-    tryAcquire(bytes) {
+    /** Reclaim parked launches' credit, the oldest parked first, while a running ask waits: what a reclaim frees goes to running asks first. */
+    reclaimForRunning() {
+        for (const reclaim of this.reclaimers) {
+            if (!this.credits.aheadStarved)
+                return;
+            this.reclaimers.delete(reclaim);
+            reclaim();
+        }
+    }
+    /** acquireRunning's credit now, ahead of every queued ask, without reclaiming, or null. */
+    tryAcquireRunning(bytes, owner = DEFAULT_ALLOCATION_OWNER) {
+        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, drivesLifecycle = true, owner = DEFAULT_ALLOCATION_OWNER) {
         const credit = this.credits.tryAcquire(bytes);
-        return credit ? this.wrap(credit, true) : null;
+        return credit ? this.wrap(credit, drivesLifecycle, owner) : null;
     }
-    async _acquire(bytes, signal, drivesLifecycle) {
-        return this.wrap(await this.credits.acquire(bytes, signal), drivesLifecycle);
+    async _acquire(bytes, signal, drivesLifecycle, owner) {
+        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);
+        }
     }
-    wrap(credit, drivesLifecycle) {
+    wrap(credit, drivesLifecycle, owner) {
+        const holder = { owner: { ...owner }, credit, since: Date.now() };
+        this.holders.add(holder);
         if (drivesLifecycle) {
             this.lifecycleHolders++;
             if (!this.active) {
@@ -79,10 +221,14 @@ export class SupervisorAllocationBudget {
             shrinkTo: (nextBytes) => {
                 credit.shrinkTo(nextBytes);
             },
+            tryGrowTo: (nextBytes) => 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;
@@ -164,29 +310,102 @@ const supervisorAllocationBudget = new SupervisorAllocationBudget(SUPERVISOR_IN_
 /**
  * Reserve an exact number of supervisor-resident bytes.
  */
-export function acquireSupervisorAllocation(bytes, signal) {
-    return supervisorAllocationBudget.acquire(bytes, signal);
+export function acquireSupervisorAllocation(bytes, signal, owner) {
+    return supervisorAllocationBudget.acquire(bytes, signal, owner);
 }
 /** Reserve bytes now if they can be granted without waiting, else null. */
-export function tryAcquireSupervisorAllocation(bytes) {
-    return supervisorAllocationBudget.tryAcquire(bytes);
+export function tryAcquireSupervisorAllocation(bytes, owner) {
+    return supervisorAllocationBudget.tryAcquire(bytes, true, owner);
+}
+/**
+ * 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, signal, owner) {
+    return supervisorAllocationBudget.acquireRunning(bytes, signal, false, owner ?? { owner: 'running filesystem read' });
 }
 /**
- * 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 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 acquireSupervisorReadAllocation(bytes, signal) {
-    return supervisorAllocationBudget.acquireWithoutLifecycle(bytes, signal);
+export function tryAcquireSupervisorCopyAllocation(bytes, owner) {
+    return supervisorAllocationBudget.tryAcquire(bytes, false, owner ?? { owner: 'supervisor copy' });
+}
+/** {@link tryAcquireSupervisorCopyAllocation}, waiting for room. */
+export function acquireSupervisorCopyAllocation(bytes, signal, owner) {
+    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, bytes, signal, owner) {
+    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, owner = { owner: 'facet load' }) {
+    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, signal, owner) {
+    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, owner) {
+    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) {
+    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(name, bytes, signal, load, owner) {
+    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) {
-    const lease = await acquireSupervisorAllocation(SUPERVISOR_IN_FLIGHT_ALLOCATION_BUDGET_BYTES, signal);
+export async function acquireHeavyAlloc(signal, owner = { owner: 'heavy supervisor work' }) {
+    const lease = await acquireSupervisorAllocation(SUPERVISOR_IN_FLIGHT_ALLOCATION_BUDGET_BYTES, signal, owner);
     return lease.release;
 }
 export function readSupervisorAllocationBudget() {
     return supervisorAllocationBudget.stats;
 }
+export function readSupervisorAllocationAttribution() {
+    return supervisorAllocationBudget.attributed;
+}

package/dist/hex.d.ts

@@ -0,0 +1,20 @@
+/**
+ * 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 declare const HEX_BYTE: readonly string[];
+/**
+ * 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 declare function bytesToHex(bytes: Uint8Array): string;
+//# sourceMappingURL=hex.d.ts.map

package/dist/hex.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hex.d.ts","sourceRoot":"","sources":["../src/hex.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;;GAIG;AACH,eAAO,MAAM,QAAQ,EAAE,SAAS,MAAM,EAAiF,CAAC;AAKxH;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAKpD"}

package/dist/hex.js

@@ -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 = 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.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) {
+    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/dist/install-phase.d.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/dist/install-phase.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"install-phase.d.ts","sourceRoot":"","sources":["../src/install-phase.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,MAAM,MAAM,YAAY,GACpB,MAAM,GACN,YAAY,GACZ,SAAS,GACT,OAAO,GACP,MAAM,GACN,OAAO,GACP,OAAO,GACP,WAAW,GACX,QAAQ,GACR,MAAM,CAAC"}
+{"version":3,"file":"install-phase.d.ts","sourceRoot":"","sources":["../src/install-phase.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,MAAM,MAAM,YAAY,GACpB,MAAM,GACN,YAAY,GACZ,SAAS,GACT,OAAO,GACP,MAAM,GACN,OAAO,GACP,OAAO,GACP,WAAW,GACX,QAAQ,GACR,MAAM,CAAC"}

package/dist/lexical-path.d.ts

@@ -0,0 +1,11 @@
+/**
+ * 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 declare function rootClampedSegments(path: string, base?: readonly string[]): string[];
+//# sourceMappingURL=lexical-path.d.ts.map

package/dist/lexical-path.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lexical-path.d.ts","sourceRoot":"","sources":["../src/lexical-path.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,GAAE,SAAS,MAAM,EAAO,GAAG,MAAM,EAAE,CAOxF"}

package/dist/lexical-path.js

@@ -0,0 +1,19 @@
+/**
+ * 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, base = []) {
+    const out = [...base];
+    for (const segment of path.split('/')) {
+        if (segment === '..')
+            out.pop();
+        else if (segment !== '' && segment !== '.')
+            out.push(segment);
+    }
+    return out;
+}

package/dist/limits.d.ts

@@ -102,7 +102,11 @@ export declare const ONE_SHOT_MODULE_MAP_MAX_BYTES: number;
 export declare const SUPERVISOR_HEAP_CEILING_BYTES: number;
 export declare const FACET_OWN_WRITE_MEMORY_BYTES: number;
 export declare const WASI_RESIDENT_STORE_BYTES: number;
+export declare const RESIDENT_PAGE_BYTES: number;
+export declare const RESIDENT_PAGE_CACHE_BYTES: number;
+export declare const RESIDENT_PAGE_CACHE_FREE_SHARE = 0.25;
 export declare const SUPERVISOR_IN_FLIGHT_ALLOCATION_BUDGET_BYTES: number;
+export declare const SUPERVISOR_LOAD_WAIT_MS = 60000;
 export declare const SUPERVISOR_READ_RESERVE_BYTES: number;
 export declare const MAX_GLOBAL_WRITE_STREAM_CREDIT_BYTES: number;
 export declare const PRE_BUNDLE_SLICE_CAP_BYTES: number;

package/dist/limits.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"limits.d.ts","sourceRoot":"","sources":["../src/limits.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AASH;;;;;;GAMG;AACH,eAAO,MAAM,UAAU,QAAS,CAAC;AAEjC,eAAO,MAAM,iBAAiB,QAAkB,CAAC;AACjD,eAAO,MAAM,mBAAmB,MAAM,CAAC;AACvC,eAAO,MAAM,gBAAgB,KAAK,CAAC;AAEnC;;;;;GAKG;AACH,eAAO,MAAM,wBAAwB,MAAM,CAAC;AAI5C;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,sBAAsB,cAAiB,CAAC;AAMrD,eAAO,MAAM,qBAAqB,QAAS,CAAC;AAE5C;;;;;GAKG;AACH,eAAO,MAAM,0BAA0B,QAAa,CAAC;AAErD;;;;;;GAMG;AACH,eAAO,MAAM,oBAAoB,UAAY,CAAC;AAI9C;;;;;;;;GAQG;AACH,eAAO,MAAM,2BAA2B,QAAS,CAAC;AAIlD;;;;;;;GAOG;AACH,eAAO,MAAM,qBAAqB,OAAQ,CAAC;AAE3C;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,8BAA8B,QAAS,CAAC;AAIrD;;;;;;;;;GASG;AACH,eAAO,MAAM,yBAAyB,QAAS,CAAC;AAOhD,eAAO,MAAM,0BAA0B,QAAmB,CAAC;AAmB3D,eAAO,MAAM,6BAA6B,QAAmB,CAAC;AA6B9D,eAAO,MAAM,6BAA6B,QAAmB,CAAC;AAM9D,eAAO,MAAM,4BAA4B,QAAmB,CAAC;AAQ7D,eAAO,MAAM,yBAAyB,QAAmB,CAAC;AAO1D,eAAO,MAAM,4CAA4C,QAAmB,CAAC;AAY7E,eAAO,MAAM,6BAA6B,QAAc,CAAC;AAKzD,eAAO,MAAM,oCAAoC,QAAkB,CAAC;AAQpE,eAAO,MAAM,0BAA0B,QAA6B,CAAC;AACrE,eAAO,MAAM,sBAAsB,IAAI,CAAC"}
+{"version":3,"file":"limits.d.ts","sourceRoot":"","sources":["../src/limits.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AASH;;;;;;GAMG;AACH,eAAO,MAAM,UAAU,QAAS,CAAC;AAEjC,eAAO,MAAM,iBAAiB,QAAkB,CAAC;AACjD,eAAO,MAAM,mBAAmB,MAAM,CAAC;AACvC,eAAO,MAAM,gBAAgB,KAAK,CAAC;AAEnC;;;;;GAKG;AACH,eAAO,MAAM,wBAAwB,MAAM,CAAC;AAI5C;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,sBAAsB,cAAiB,CAAC;AAMrD,eAAO,MAAM,qBAAqB,QAAS,CAAC;AAE5C;;;;;GAKG;AACH,eAAO,MAAM,0BAA0B,QAAa,CAAC;AAErD;;;;;;GAMG;AACH,eAAO,MAAM,oBAAoB,UAAY,CAAC;AAI9C;;;;;;;;GAQG;AACH,eAAO,MAAM,2BAA2B,QAAS,CAAC;AAIlD;;;;;;;GAOG;AACH,eAAO,MAAM,qBAAqB,OAAQ,CAAC;AAE3C;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,8BAA8B,QAAS,CAAC;AAIrD;;;;;;;;;GASG;AACH,eAAO,MAAM,yBAAyB,QAAS,CAAC;AAOhD,eAAO,MAAM,0BAA0B,QAAmB,CAAC;AAmB3D,eAAO,MAAM,6BAA6B,QAAmB,CAAC;AA6B9D,eAAO,MAAM,6BAA6B,QAAmB,CAAC;AAM9D,eAAO,MAAM,4BAA4B,QAAmB,CAAC;AAQ7D,eAAO,MAAM,yBAAyB,QAAmB,CAAC;AAM1D,eAAO,MAAM,mBAAmB,QAAY,CAAC;AAM7C,eAAO,MAAM,yBAAyB,QAAoB,CAAC;AAQ3D,eAAO,MAAM,8BAA8B,OAAO,CAAC;AAOnD,eAAO,MAAM,4CAA4C,QAAmB,CAAC;AAS7E,eAAO,MAAM,uBAAuB,QAAS,CAAC;AAY9C,eAAO,MAAM,6BAA6B,QAAc,CAAC;AAKzD,eAAO,MAAM,oCAAoC,QAAkB,CAAC;AAQpE,eAAO,MAAM,0BAA0B,QAA6B,CAAC;AACrE,eAAO,MAAM,sBAAsB,IAAI,CAAC"}

package/dist/limits.js

@@ -174,12 +174,37 @@ export const FACET_OWN_WRITE_MEMORY_BYTES = 32 * 1024 * 1024;
 // or a program that reads much, not what a short run holds. Past it the store
 // 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
 // with 7 MiB left for metadata, structured-clone overhead, and runtime state.
 // 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/dist/module-source.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"module-source.d.ts","sourceRoot":"","sources":["../src/module-source.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,eAAe;IAC9B,MAAM,CAAC,EAAE;QAAE,KAAK,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAA;KAAE,CAAC;CACzD;AAED,4FAA4F;AAC5F,qBAAa,qBAAqB;IAGa,QAAQ,CAAC,KAAK,EAAE,iBAAiB;IAF9E,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;gBACV,KAAK,EAAE,WAAW,GAAG,UAAU,EAAW,KAAK,EAAE,iBAAiB;CAI/E;AAED,MAAM,MAAM,gBAAgB,GAAG,MAAM,GAAG,qBAAqB,CAAC;AAC9D,MAAM,MAAM,kBAAkB,GAAG,CAAC,MAAM,GAAG,iBAAiB,CAAC,EAAE,CAAC;AAEhE,gGAAgG;AAChG,qBAAa,YAAY;IAGX,QAAQ,CAAC,KAAK,EAAE,SAAS,gBAAgB,EAAE;IAFvD,OAAO,CAAC,MAAM,CAAqB;IACnC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;gBACP,KAAK,EAAE,SAAS,gBAAgB,EAAE;IAGvD,IAAI,IAAI,IAAI,MAAM,CAEjB;IACD,MAAM,IAAI,kBAAkB;CAG7B;AAED,qGAAqG;AACrG,wBAAgB,YAAY,CAAC,OAAO,EAAE,oBAAoB,EAAE,GAAG,MAAM,EAAE,CAAC,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,GAAG,SAAS,GAAG,qBAAqB,GAAG,YAAY,CAAC,EAAE,GAAG,YAAY,CAiB5K"}
+{"version":3,"file":"module-source.d.ts","sourceRoot":"","sources":["../src/module-source.ts"],"names":[],"mappings":"AAEA,8EAA8E;AAC9E,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,eAAe;IAC9B,MAAM,CAAC,EAAE;QAAE,KAAK,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAA;KAAE,CAAC;CACzD;AAED,4FAA4F;AAC5F,qBAAa,qBAAqB;IAGa,QAAQ,CAAC,KAAK,EAAE,iBAAiB;IAF9E,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;gBACV,KAAK,EAAE,WAAW,GAAG,UAAU,EAAW,KAAK,EAAE,iBAAiB;CAI/E;AAED,MAAM,MAAM,gBAAgB,GAAG,MAAM,GAAG,qBAAqB,CAAC;AAC9D,MAAM,MAAM,kBAAkB,GAAG,CAAC,MAAM,GAAG,iBAAiB,CAAC,EAAE,CAAC;AAEhE,gGAAgG;AAChG,qBAAa,YAAY;IAGX,QAAQ,CAAC,KAAK,EAAE,SAAS,gBAAgB,EAAE;IAFvD,OAAO,CAAC,MAAM,CAAqB;IACnC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;gBACP,KAAK,EAAE,SAAS,gBAAgB,EAAE;IAGvD,IAAI,IAAI,IAAI,MAAM,CAEjB;IACD,MAAM,IAAI,kBAAkB;CAG7B;AAED,qGAAqG;AACrG,wBAAgB,YAAY,CAAC,OAAO,EAAE,oBAAoB,EAAE,GAAG,MAAM,EAAE,CAAC,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,GAAG,SAAS,GAAG,qBAAqB,GAAG,YAAY,CAAC,EAAE,GAAG,YAAY,CAiB5K"}

package/dist/module-source.js

@@ -1,3 +1,4 @@
+import { utf8Length } from './utf8.js';
 /** Source already verified against its deployment pin. Shared across generated programs. */
 export class ImmutableModuleSource {
     asset;
@@ -16,7 +17,7 @@ export class ModuleSource {
     byteLength;
     constructor(parts) {
         this.parts = parts;
-        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() {
         return this.joined ??= this.parts.map((part) => typeof part === 'string' ? part : part.text).join('');

package/dist/oom-classify.d.ts

@@ -153,6 +153,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'

package/dist/oom-classify.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"oom-classify.d.ts","sourceRoot":"","sources":["../src/oom-classify.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6DG;AAEH,QAAA,MAAM,UAAU,kLAYN,CAAC;AAEX,MAAM,MAAM,QAAQ,GAAG,OAAO,UAAU,CAAC,MAAM,CAAC,CAAC;AAEjD,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,QAAQ,CAE5D;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,QAAQ,CAItD;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,QAAQ,CAmErD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAO1D;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAInD;AAYD;;;;;GAKG;AACH,wBAAgB,0BAA0B,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAElE;AAED;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAEtD;AAED;;;;;;;;GAQG;AACH,MAAM,MAAM,WAAW;AACrB,8CAA8C;AAC5C,oBAAoB;AACtB,8CAA8C;GAC5C,iBAAiB;AACnB,uEAAuE;GACrE,eAAe;AACjB,wDAAwD;GACtD,gBAAgB;AAClB;kDACkD;GAChD,YAAY;AACd,kEAAkE;GAChE,WAAW,CAAC;AAEhB;2DAC2D;AAC3D,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO,CAK7D;AAmBD;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,WAAW,CAsB1D;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAiBpD"}
+{"version":3,"file":"oom-classify.d.ts","sourceRoot":"","sources":["../src/oom-classify.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6DG;AAEH,QAAA,MAAM,UAAU,kLAYN,CAAC;AAEX,MAAM,MAAM,QAAQ,GAAG,OAAO,UAAU,CAAC,MAAM,CAAC,CAAC;AAEjD,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,QAAQ,CAE5D;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,QAAQ,CAItD;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,QAAQ,CAmErD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAO1D;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAInD;AAYD;;;;;GAKG;AACH,wBAAgB,0BAA0B,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAElE;AAED;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAEtD;AAED;;;;;;;;GAQG;AACH,MAAM,MAAM,WAAW;AACrB,8CAA8C;AAC5C,oBAAoB;AACtB,8CAA8C;GAC5C,iBAAiB;AACnB,uEAAuE;GACrE,eAAe;AACjB,wDAAwD;GACtD,gBAAgB;AAClB;;sEAEsE;GACpE,mBAAmB;AACrB;kDACkD;GAChD,YAAY;AACd,kEAAkE;GAChE,WAAW,CAAC;AAEhB;2DAC2D;AAC3D,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO,CAK7D;AAmBD;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,WAAW,CA0B1D;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAiBpD"}

package/dist/oom-classify.js

@@ -294,6 +294,7 @@ export function classifyDoCall(input) {
     const seen = new Set();
     const messages = [];
     let flagged = false;
+    let unexplained = false;
     let link = input;
     while (link !== null && !seen.has(link)) {
         seen.add(link);
@@ -303,6 +304,8 @@ export function classifyDoCall(input) {
             return 'overloaded';
         if ('retryable' in link && link.retryable === true)
             flagged = true;
+        if (isUnexplainedPlatformError(link))
+            unexplained = true;
         messages.push(link.message ?? '');
         const cause = link.cause;
         link = cause instanceof Error ? cause : null;
@@ -314,6 +317,9 @@ export function classifyDoCall(input) {
     }
     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/dist/realm-builtin.d.ts

@@ -0,0 +1,2 @@
+export declare function realmBuiltin<T>(id: string): T | undefined;
+//# sourceMappingURL=realm-builtin.d.ts.map

package/dist/realm-builtin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"realm-builtin.d.ts","sourceRoot":"","sources":["../src/realm-builtin.ts"],"names":[],"mappings":"AAYA,wBAAgB,YAAY,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,GAAG,CAAC,GAAG,SAAS,CASzD"}

package/dist/realm-builtin.js

@@ -0,0 +1,11 @@
+export function realmBuiltin(id) {
+    try {
+        const global = globalThis;
+        const current = global.process;
+        const own = (current && global[Symbol.for('nimbus.fronts')]?.get(current)?.own);
+        return (own ?? current)?.getBuiltinModule?.(id);
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/utf8.d.ts

@@ -1,5 +1,6 @@
 /**
- * utf8.ts — the UTF-8 length of a string, without encoding it.
+ * utf8.ts — the UTF-8 length of a string, and the order of two strings by
+ * their UTF-8 bytes, without encoding them.
  *
  * Bounds on names and payloads are in bytes, and the hot ones (every path a
  * W7 wave or a listing page carries) were measured by encoding the string
@@ -7,5 +8,24 @@
  * TextEncoder would write: one to four per code point, and three for a
  * lone surrogate, which it writes as U+FFFD.
  */
+/**
+ * From this many UTF-16 units, a string is counted natively (longUtf8Length),
+ * into a scratch buffer of SCRATCH_BYTES. The resident store's count on the
+ * launch's captures (worker vfs/resident/cell-cost.ts) keeps the same policy,
+ * and tests/unit/utf8-length.mjs holds both to TextEncoder.
+ */
+export declare const UTF8_LONG_UNITS = 256;
+export declare const UTF8_SCRATCH_BYTES: number;
 export declare function utf8Length(text: string): number;
+/**
+ * `a` against `b` (negative, 0, positive) as their UTF-8 bytes order them,
+ * as SQLite's `ORDER BY` of a text column and git's index do: code point
+ * order. A string UTF-8 cannot write (a lone surrogate) is ordered as WTF-8
+ * writes it, its surrogate a code point of its own: the order is total, as a
+ * listing's cursor needs, and decided at the first code point that differs,
+ * so a directory's entries follow it together. Units equal in both are
+ * passed as they are; two that differ, neither a surrogate, are their own
+ * code points; the rest, rare in a path, is surrogatesAt's.
+ */
+export declare function compareUtf8(a: string, b: string): number;
 //# sourceMappingURL=utf8.d.ts.map

package/dist/utf8.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"utf8.d.ts","sourceRoot":"","sources":["../src/utf8.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAqB/C"}
+{"version":3,"file":"utf8.d.ts","sourceRoot":"","sources":["../src/utf8.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH;;;;;GAKG;AACH,eAAO,MAAM,eAAe,MAAM,CAAC;AACnC,eAAO,MAAM,kBAAkB,QAAa,CAAC;AAK7C,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAsB/C;AA6BD;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAUxD"}