@nimbus-sh/platform 0.2.0 → 0.4.0

package/dist/composition.d.ts

@@ -1,4 +1,28 @@
-/** Shared composition state for core workspaces and the process fabric. */
+/**
+ * composition.ts — the ONE seam an embedder wires the fabric through.
+ *
+ * The fabric mints supervisor bindings and assembles staged boots for the
+ * programs it hosts, but the entrypoint class that answers those bindings
+ * and the artifact sources a stage names both belong to the embedder. The
+ * embedder states them once, in its composition root, with one call:
+ *
+ *   composeFabric({
+ *     supervisorEntrypoint: 'SupervisorRPC',
+ *     stagedBootAssembler: (env, stage) => assembleConfig(env, stage),
+ *   });
+ *
+ * First-write-wins, like every holder in this module: the composition
+ * root's module scope runs once per isolate, before any request.
+ *
+ * `ctx.exports` is runtime state, not composition: workerd mints it per
+ * instance, so the embedder captures it where the platform hands it over —
+ * the first fetch, or the DO constructor — with {@link adoptCtxExports}.
+ *
+ * This module stays a leaf (no fabric imports) so helpers (notably
+ * isolate-pool.ts) can read `ctx.exports` without transitively importing
+ * the Durable Object classes, which is what lets the pool be unit-tested
+ * in a plain Node/Bun process.
+ */
 export type EntrypointLoopbackFactory = <Stub = unknown>(options: {
     props: object;
 }) => Stub;

package/dist/composition.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"composition.d.ts","sourceRoot":"","sources":["../src/composition.ts"],"names":[],"mappings":"AAAA,2EAA2E;AAC3E,MAAM,MAAM,yBAAyB,GAAG,CAAC,IAAI,GAAG,OAAO,EAAE,OAAO,EAAE;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,KAAK,IAAI,CAAC;AAC7F,MAAM,MAAM,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,yBAAyB,GAAG,SAAS,CAAC,CAAC;AAC/E,MAAM,MAAM,mBAAmB,GAAG,CAAC,GAAG,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;AAEpF,MAAM,WAAW,iBAAiB;IAChC,oBAAoB,EAAE,MAAM,CAAC;IAC7B,mBAAmB,CAAC,EAAE,mBAAmB,CAAC;IAC1C,gEAAgE;IAChE,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,8DAA8D;IAC9D,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED,eAAO,MAAM,sBAAsB,mBAAmB,CAAC;AACvD,eAAO,MAAM,4BAA4B,iBAAiB,CAAC;AAI3D,8EAA8E;AAC9E,wBAAgB,aAAa,CAAC,KAAK,EAAE,iBAAiB,GAAG,IAAI,CAE5D;AAED,wBAAgB,eAAe,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI,CAEvD;AAED,wBAAgB,aAAa,IAAI,UAAU,GAAG,IAAI,CAEjD;AAED,wBAAgB,oBAAoB,CAAC,UAAU,CAAC,EAAE,OAAO,GAAG,yBAAyB,GAAG,IAAI,CAO3F;AAED,wBAAgB,wBAAwB,IAAI,MAAM,GAAG,IAAI,CAExD;AAED,wBAAgB,aAAa,IAAI,MAAM,CAEtC;AAED,wBAAgB,kBAAkB,IAAI,MAAM,CAE3C;AAED,wBAAgB,mBAAmB,IAAI,mBAAmB,CASzD"}
+{"version":3,"file":"composition.d.ts","sourceRoot":"","sources":["../src/composition.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,MAAM,yBAAyB,GAAG,CAAC,IAAI,GAAG,OAAO,EAAE,OAAO,EAAE;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,KAAK,IAAI,CAAC;AAC7F,MAAM,MAAM,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,yBAAyB,GAAG,SAAS,CAAC,CAAC;AAC/E,MAAM,MAAM,mBAAmB,GAAG,CAAC,GAAG,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;AAEpF,MAAM,WAAW,iBAAiB;IAChC,oBAAoB,EAAE,MAAM,CAAC;IAC7B,mBAAmB,CAAC,EAAE,mBAAmB,CAAC;IAC1C,gEAAgE;IAChE,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,8DAA8D;IAC9D,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED,eAAO,MAAM,sBAAsB,mBAAmB,CAAC;AACvD,eAAO,MAAM,4BAA4B,iBAAiB,CAAC;AAI3D,8EAA8E;AAC9E,wBAAgB,aAAa,CAAC,KAAK,EAAE,iBAAiB,GAAG,IAAI,CAE5D;AAED,wBAAgB,eAAe,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI,CAEvD;AAED,wBAAgB,aAAa,IAAI,UAAU,GAAG,IAAI,CAEjD;AAED,wBAAgB,oBAAoB,CAAC,UAAU,CAAC,EAAE,OAAO,GAAG,yBAAyB,GAAG,IAAI,CAO3F;AAED,wBAAgB,wBAAwB,IAAI,MAAM,GAAG,IAAI,CAExD;AAED,wBAAgB,aAAa,IAAI,MAAM,CAEtC;AAED,wBAAgB,kBAAkB,IAAI,MAAM,CAE3C;AAED,wBAAgB,mBAAmB,IAAI,mBAAmB,CASzD"}

package/dist/heavy-alloc-coord.d.ts

@@ -13,6 +13,8 @@ export interface SupervisorAllocationBudgetStats {
     readonly current: number;
     readonly peak: number;
     readonly queued: number;
+    /** Credit held for an owner's whole lifetime; see `acquireResident`. */
+    readonly resident: number;
 }
 interface AllocationBudgetLifecycle {
     onActive?: () => void;
@@ -51,6 +53,12 @@ export declare class SupervisorAllocationBudget {
      * stops a large read overlapping a large write.
      */
     acquireWithoutLifecycle(bytes: number, signal?: AbortSignal): Promise<ResizableCreditLease>;
+    /**
+     * Reserve bytes an owner holds for its whole lifetime, not for one
+     * operation. Recorded as a floor: a later claim larger than what remains
+     * around it is refused with both numbers rather than parked forever.
+     */
+    acquireResidentBytes(bytes: number, signal?: AbortSignal): Promise<ResizableCreditLease>;
     private _acquire;
 }
 /**
@@ -83,6 +91,11 @@ export declare function acquireSupervisorAllocation(bytes: number, signal?: Abor
  * there to fill.
  */
 export declare function acquireSupervisorReadAllocation(bytes: number, signal?: AbortSignal): Promise<ResizableCreditLease>;
+/**
+ * Reserve bytes for the whole life of the owner that takes them — an image
+ * a pool keeps until it is disposed. See `acquireResidentBytes`.
+ */
+export declare function acquireResidentSupervisorAllocation(bytes: number, signal?: AbortSignal): Promise<ResizableCreditLease>;
 /**
  * Reserve the full budget for an allocation whose retained size is not known
  * accurately enough to overlap safely with other heavy work.

package/dist/heavy-alloc-coord.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"heavy-alloc-coord.d.ts","sourceRoot":"","sources":["../src/heavy-alloc-coord.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAOH,OAAO,EAEL,KAAK,oBAAoB,EACzB,KAAK,yBAAyB,EAC/B,MAAM,2BAA2B,CAAC;AAEnC,MAAM,WAAW,+BAA+B;IAC9C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,UAAU,yBAAyB;IACjC,QAAQ,CAAC,EAAE,MAAM,IAAI,CAAC;IACtB,MAAM,CAAC,EAAE,MAAM,IAAI,CAAC;CACrB;AAED;;;GAGG;AACH,qBAAa,0BAA0B;IAWnC,QAAQ,CAAC,QAAQ,EAAE,MAAM;IACzB,OAAO,CAAC,QAAQ,CAAC,SAAS;IAX5B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAqB;IAC7C,OAAO,CAAC,MAAM,CAAS;IACvB;;;;OAIG;IACH,OAAO,CAAC,gBAAgB,CAAK;gBAGlB,QAAQ,EAAE,MAAM,EACR,SAAS,GAAE,yBAA8B,EAC1D,OAAO,GAAE,yBAA8B;IAKzC,IAAI,KAAK,IAAI,+BAA+B,CAK3C;IAED;;;;OAIG;IACH,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,oBAAoB,CAAC;IAI3E;;;;;;;;OAQG;IACH,uBAAuB,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,oBAAoB,CAAC;YAI7E,QAAQ;CAmCvB;AAED;;;GAGG;AACH,UAAU,aAAa;IACrB,8DAA8D;IAC9D,SAAS,CAAC,EAAE,MAAM,IAAI,CAAC;IACvB,8DAA8D;IAC9D,SAAS,CAAC,EAAE,MAAM,IAAI,CAAC;CACxB;AAiBD;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CAAC,CAAC,EAAE,aAAa,GAAG,MAAM,IAAI,CAWlE;AAqCD;;GAEG;AACH,wBAAgB,2BAA2B,CACzC,KAAK,EAAE,MAAM,EACb,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,oBAAoB,CAAC,CAE/B;AAED;;;;GAIG;AACH,wBAAgB,+BAA+B,CAC7C,KAAK,EAAE,MAAM,EACb,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,oBAAoB,CAAC,CAE/B;AAED;;;GAGG;AACH,wBAAsB,iBAAiB,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,IAAI,CAAC,CAMjF;AAED,wBAAgB,8BAA8B,IAAI,+BAA+B,CAEhF"}
+{"version":3,"file":"heavy-alloc-coord.d.ts","sourceRoot":"","sources":["../src/heavy-alloc-coord.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAOH,OAAO,EAEL,KAAK,oBAAoB,EACzB,KAAK,yBAAyB,EAC/B,MAAM,2BAA2B,CAAC;AAEnC,MAAM,WAAW,+BAA+B;IAC9C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,wEAAwE;IACxE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED,UAAU,yBAAyB;IACjC,QAAQ,CAAC,EAAE,MAAM,IAAI,CAAC;IACtB,MAAM,CAAC,EAAE,MAAM,IAAI,CAAC;CACrB;AAED;;;GAGG;AACH,qBAAa,0BAA0B;IAWnC,QAAQ,CAAC,QAAQ,EAAE,MAAM;IACzB,OAAO,CAAC,QAAQ,CAAC,SAAS;IAX5B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAqB;IAC7C,OAAO,CAAC,MAAM,CAAS;IACvB;;;;OAIG;IACH,OAAO,CAAC,gBAAgB,CAAK;gBAGlB,QAAQ,EAAE,MAAM,EACR,SAAS,GAAE,yBAA8B,EAC1D,OAAO,GAAE,yBAA8B;IAKzC,IAAI,KAAK,IAAI,+BAA+B,CAK3C;IAED;;;;OAIG;IACH,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,oBAAoB,CAAC;IAI3E;;;;;;;;OAQG;IACH,uBAAuB,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,oBAAoB,CAAC;IAI3F;;;;OAIG;IACH,oBAAoB,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,oBAAoB,CAAC;YAI1E,QAAQ;CAsCvB;AAED;;;GAGG;AACH,UAAU,aAAa;IACrB,8DAA8D;IAC9D,SAAS,CAAC,EAAE,MAAM,IAAI,CAAC;IACvB,8DAA8D;IAC9D,SAAS,CAAC,EAAE,MAAM,IAAI,CAAC;CACxB;AAiBD;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CAAC,CAAC,EAAE,aAAa,GAAG,MAAM,IAAI,CAWlE;AAqCD;;GAEG;AACH,wBAAgB,2BAA2B,CACzC,KAAK,EAAE,MAAM,EACb,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,oBAAoB,CAAC,CAE/B;AAED;;;;GAIG;AACH,wBAAgB,+BAA+B,CAC7C,KAAK,EAAE,MAAM,EACb,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,oBAAoB,CAAC,CAE/B;AAED;;;GAGG;AACH,wBAAgB,mCAAmC,CACjD,KAAK,EAAE,MAAM,EACb,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,oBAAoB,CAAC,CAE/B;AAED;;;GAGG;AACH,wBAAsB,iBAAiB,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,IAAI,CAAC,CAMjF;AAED,wBAAgB,8BAA8B,IAAI,+BAA+B,CAEhF"}

package/dist/heavy-alloc-coord.js

@@ -55,8 +55,18 @@ export class SupervisorAllocationBudget {
     acquireWithoutLifecycle(bytes, signal) {
         return this._acquire(bytes, signal, false);
     }
-    async _acquire(bytes, signal, drivesLifecycle) {
-        const credit = await this.credits.acquire(bytes, signal);
+    /**
+     * Reserve bytes an owner holds for its whole lifetime, not for one
+     * operation. Recorded as a floor: a later claim larger than what remains
+     * around it is refused with both numbers rather than parked forever.
+     */
+    acquireResidentBytes(bytes, signal) {
+        return this._acquire(bytes, signal, true, true);
+    }
+    async _acquire(bytes, signal, drivesLifecycle, resident = false) {
+        const credit = resident
+            ? await this.credits.acquireResident(bytes, signal)
+            : await this.credits.acquire(bytes, signal);
         if (drivesLifecycle) {
             this.lifecycleHolders++;
             if (!this.active) {
@@ -168,6 +178,13 @@ export function acquireSupervisorAllocation(bytes, signal) {
 export function acquireSupervisorReadAllocation(bytes, signal) {
     return supervisorAllocationBudget.acquireWithoutLifecycle(bytes, signal);
 }
+/**
+ * Reserve bytes for the whole life of the owner that takes them — an image
+ * a pool keeps until it is disposed. See `acquireResidentBytes`.
+ */
+export function acquireResidentSupervisorAllocation(bytes, signal) {
+    return supervisorAllocationBudget.acquireResidentBytes(bytes, signal);
+}
 /**
  * Reserve the full budget for an allocation whose retained size is not known
  * accurately enough to overlap safely with other heavy work.

package/dist/weighted-credit-pool.d.ts

@@ -9,6 +9,11 @@ export interface WeightedCreditPoolStats {
     readonly current: number;
     readonly peak: number;
     readonly queued: number;
+    /**
+     * Credit held by owners that keep it for their whole lifetime rather than
+     * for one operation — the floor no waiter can ever expect to get back.
+     */
+    readonly resident: number;
 }
 export interface WeightedCreditPoolOptions {
     /**
@@ -56,6 +61,14 @@ export declare class WeightedCreditPool {
     private isSmall;
     tryAcquire(bytes: number): ResizableCreditLease | null;
     acquire(bytes: number, signal?: AbortSignal): Promise<ResizableCreditLease>;
+    /**
+     * Take credit that will be held for the owner's whole lifetime rather than
+     * for one operation — the esbuild pool's wasm image is the case.
+     *
+     * Recorded as a floor so a later claim that could never fit around it is
+     * refused with both numbers instead of parking in the FIFO forever.
+     */
+    acquireResident(bytes: number, signal?: AbortSignal): Promise<ResizableCreditLease>;
     private validateRequest;
 }
 //# sourceMappingURL=weighted-credit-pool.d.ts.map

package/dist/weighted-credit-pool.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"weighted-credit-pool.d.ts","sourceRoot":"","sources":["../src/weighted-credit-pool.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,OAAO,IAAI,IAAI,CAAC;CACjB;AAED,MAAM,WAAW,oBAAqB,SAAQ,WAAW;IACvD,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CAC/B;AAED,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,yBAAyB;IACxC;;;OAGG;IACH,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IACpC;;;;OAIG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B;AAkHD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,qBAAa,kBAAkB;IAKjB,QAAQ,CAAC,QAAQ,EAAE,MAAM;IAJrC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAa;IACrC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAoB;IAC1C,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAS;gBAEtB,QAAQ,EAAE,MAAM,EAAE,OAAO,GAAE,yBAA8B;IAoB9E,IAAI,KAAK,IAAI,uBAAuB,CASnC;IAED,OAAO,CAAC,OAAO;IAIf,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,oBAAoB,GAAG,IAAI;IAOtD,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,oBAAoB,CAAC;IAiB3E,OAAO,CAAC,eAAe;CAOxB"}
+{"version":3,"file":"weighted-credit-pool.d.ts","sourceRoot":"","sources":["../src/weighted-credit-pool.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,OAAO,IAAI,IAAI,CAAC;CACjB;AAED,MAAM,WAAW,oBAAqB,SAAQ,WAAW;IACvD,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CAC/B;AAED,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB;;;OAGG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,yBAAyB;IACxC;;;OAGG;IACH,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IACpC;;;;OAIG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B;AAmJD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,qBAAa,kBAAkB;IAKjB,QAAQ,CAAC,QAAQ,EAAE,MAAM;IAJrC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAa;IACrC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAoB;IAC1C,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAS;gBAEtB,QAAQ,EAAE,MAAM,EAAE,OAAO,GAAE,yBAA8B;IAoB9E,IAAI,KAAK,IAAI,uBAAuB,CAUnC;IAED,OAAO,CAAC,OAAO;IAIf,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,oBAAoB,GAAG,IAAI;IAOtD,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,oBAAoB,CAAC;IAiB3E;;;;;;OAMG;IACH,eAAe,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,oBAAoB,CAAC;IASnF,OAAO,CAAC,eAAe;CAOxB"}

package/dist/weighted-credit-pool.js

@@ -3,27 +3,52 @@ class CreditLane {
     capacity;
     current = 0;
     peak = 0;
+    resident = 0;
     waiters = [];
     constructor(capacity) {
         this.capacity = capacity;
     }
     get stats() {
-        return { current: this.current, peak: this.peak, queued: this.waiters.length };
+        return {
+            current: this.current, peak: this.peak, queued: this.waiters.length, resident: this.resident,
+        };
     }
     tryAcquire(bytes) {
         if (this.waiters.length > 0 || this.current + bytes > this.capacity)
             return null;
-        return this.grant(bytes);
+        return this.grant(bytes, false);
     }
-    acquire(bytes, signal) {
+    /**
+     * The largest claim this lane can ever grant: capacity less what resident
+     * owners hold for their whole lifetime. A claim above it cannot be
+     * satisfied by waiting, because nothing it is waiting for will be
+     * released.
+     */
+    get grantableCeiling() {
+        return this.capacity - this.resident;
+    }
+    acquire(bytes, signal, resident = false) {
         if (signal?.aborted)
             return Promise.reject(abortError(signal));
-        const immediate = this.tryAcquire(bytes);
+        // Refuse a claim no amount of waiting can satisfy, rather than parking it
+        // in the FIFO forever. A parked claim is indistinguishable from a caller
+        // that stopped: no error, no timeout, and — because the queue refuses
+        // everyone behind it — no further progress anywhere in the isolate. That
+        // is what a real-vite launch looked like for four rounds of debugging.
+        if (bytes > this.grantableCeiling) {
+            return Promise.reject(new RangeError(`weighted credit claim of ${bytes} bytes can never be granted: capacity is ${this.capacity} `
+                + `and ${this.resident} bytes are held by resident owners, leaving ${this.grantableCeiling}`));
+        }
+        const immediate = resident ? null : this.tryAcquire(bytes);
         if (immediate)
             return Promise.resolve(immediate);
+        if (resident && this.waiters.length === 0 && this.current + bytes <= this.capacity) {
+            return Promise.resolve(this.grant(bytes, true));
+        }
         return new Promise((resolve, reject) => {
             const waiter = {
                 bytes,
+                resident,
                 resolve,
                 reject,
                 signal,
@@ -48,8 +73,10 @@ class CreditLane {
             this.drain();
         });
     }
-    grant(bytes) {
+    grant(bytes, resident) {
         this.current += bytes;
+        if (resident)
+            this.resident += bytes;
         this.peak = Math.max(this.peak, this.current);
         let leasedBytes = bytes;
         let released = false;
@@ -67,6 +94,8 @@ class CreditLane {
                     throw new RangeError(`weighted credit lease can only shrink to a positive safe integer no larger than ${leasedBytes}: ${nextBytes}`);
                 }
                 this.current -= leasedBytes - nextBytes;
+                if (resident)
+                    this.resident -= leasedBytes - nextBytes;
                 leasedBytes = nextBytes;
                 this.drain();
             },
@@ -75,6 +104,8 @@ class CreditLane {
                     return;
                 released = true;
                 this.current -= leasedBytes;
+                if (resident)
+                    this.resident -= leasedBytes;
                 if (this.current < 0) {
                     throw new Error('weighted credit accounting underflow');
                 }
@@ -95,7 +126,7 @@ class CreditLane {
                 return;
             this.waiters.shift();
             waiter.signal?.removeEventListener('abort', waiter.onAbort);
-            waiter.resolve(this.grant(waiter.bytes));
+            waiter.resolve(this.grant(waiter.bytes, waiter.resident));
         }
     }
 }
@@ -154,6 +185,7 @@ export class WeightedCreditPool {
             current: general.current + small.current,
             peak: general.peak + small.peak,
             queued: general.queued + small.queued,
+            resident: general.resident + small.resident,
         };
     }
     isSmall(bytes) {
@@ -184,6 +216,22 @@ export class WeightedCreditPool {
         }
         return this.general.acquire(bytes, signal);
     }
+    /**
+     * Take credit that will be held for the owner's whole lifetime rather than
+     * for one operation — the esbuild pool's wasm image is the case.
+     *
+     * Recorded as a floor so a later claim that could never fit around it is
+     * refused with both numbers instead of parking in the FIFO forever.
+     */
+    acquireResident(bytes, signal) {
+        try {
+            this.validateRequest(bytes);
+        }
+        catch (error) {
+            return Promise.reject(error);
+        }
+        return this.general.acquire(bytes, signal, true);
+    }
     validateRequest(bytes) {
         if (!Number.isSafeInteger(bytes) || bytes <= 0 || bytes > this.capacity) {
             throw new RangeError(`weighted credit request must be a positive safe integer no larger than ${this.capacity}: ${bytes}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nimbus-sh/platform",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "The measured Cloudflare platform truths Nimbus is built on — error taxonomy, limits tables, budget coordination, and wire-format primitives, with zero runtime dependencies.",
   "keywords": [
     "cloudflare",

package/src/composition.ts

@@ -1,4 +1,28 @@
-/** Shared composition state for core workspaces and the process fabric. */
+/**
+ * composition.ts — the ONE seam an embedder wires the fabric through.
+ *
+ * The fabric mints supervisor bindings and assembles staged boots for the
+ * programs it hosts, but the entrypoint class that answers those bindings
+ * and the artifact sources a stage names both belong to the embedder. The
+ * embedder states them once, in its composition root, with one call:
+ *
+ *   composeFabric({
+ *     supervisorEntrypoint: 'SupervisorRPC',
+ *     stagedBootAssembler: (env, stage) => assembleConfig(env, stage),
+ *   });
+ *
+ * First-write-wins, like every holder in this module: the composition
+ * root's module scope runs once per isolate, before any request.
+ *
+ * `ctx.exports` is runtime state, not composition: workerd mints it per
+ * instance, so the embedder captures it where the platform hands it over —
+ * the first fetch, or the DO constructor — with {@link adoptCtxExports}.
+ *
+ * This module stays a leaf (no fabric imports) so helpers (notably
+ * isolate-pool.ts) can read `ctx.exports` without transitively importing
+ * the Durable Object classes, which is what lets the pool be unit-tested
+ * in a plain Node/Bun process.
+ */
 export type EntrypointLoopbackFactory = <Stub = unknown>(options: { props: object }) => Stub;
 export type CtxExports = Record<string, EntrypointLoopbackFactory | undefined>;
 export type StagedBootAssembler = (env: unknown, stage: unknown) => Promise<object>;

package/src/heavy-alloc-coord.ts

@@ -24,6 +24,8 @@ export interface SupervisorAllocationBudgetStats {
   readonly current: number;
   readonly peak: number;
   readonly queued: number;
+  /** Credit held for an owner's whole lifetime; see `acquireResident`. */
+  readonly resident: number;
 }
 
 interface AllocationBudgetLifecycle {
@@ -82,12 +84,24 @@ export class SupervisorAllocationBudget {
     return this._acquire(bytes, signal, false);
   }
 
+  /**
+   * Reserve bytes an owner holds for its whole lifetime, not for one
+   * operation. Recorded as a floor: a later claim larger than what remains
+   * around it is refused with both numbers rather than parked forever.
+   */
+  acquireResidentBytes(bytes: number, signal?: AbortSignal): Promise<ResizableCreditLease> {
+    return this._acquire(bytes, signal, true, true);
+  }
+
   private async _acquire(
     bytes: number,
     signal: AbortSignal | undefined,
     drivesLifecycle: boolean,
+    resident = false,
   ): Promise<ResizableCreditLease> {
-    const credit = await this.credits.acquire(bytes, signal);
+    const credit = resident
+      ? await this.credits.acquireResident(bytes, signal)
+      : await this.credits.acquire(bytes, signal);
     if (drivesLifecycle) {
       this.lifecycleHolders++;
       if (!this.active) {
@@ -224,6 +238,17 @@ export function acquireSupervisorReadAllocation(
   return supervisorAllocationBudget.acquireWithoutLifecycle(bytes, signal);
 }
 
+/**
+ * Reserve bytes for the whole life of the owner that takes them — an image
+ * a pool keeps until it is disposed. See `acquireResidentBytes`.
+ */
+export function acquireResidentSupervisorAllocation(
+  bytes: number,
+  signal?: AbortSignal,
+): Promise<ResizableCreditLease> {
+  return supervisorAllocationBudget.acquireResidentBytes(bytes, signal);
+}
+
 /**
  * Reserve the full budget for an allocation whose retained size is not known
  * accurately enough to overlap safely with other heavy work.

package/src/weighted-credit-pool.ts

@@ -11,6 +11,11 @@ export interface WeightedCreditPoolStats {
   readonly current: number;
   readonly peak: number;
   readonly queued: number;
+  /**
+   * Credit held by owners that keep it for their whole lifetime rather than
+   * for one operation — the floor no waiter can ever expect to get back.
+   */
+  readonly resident: number;
 }
 
 export interface WeightedCreditPoolOptions {
@@ -29,6 +34,8 @@ export interface WeightedCreditPoolOptions {
 
 interface CreditWaiter {
   readonly bytes: number;
+  /** Whether the granted lease counts toward the resident floor. */
+  readonly resident: boolean;
   readonly resolve: (lease: ResizableCreditLease) => void;
   readonly reject: (error: Error) => void;
   readonly signal?: AbortSignal;
@@ -39,27 +46,55 @@ interface CreditWaiter {
 class CreditLane {
   private current = 0;
   private peak = 0;
+  private resident = 0;
   private readonly waiters: CreditWaiter[] = [];
 
   constructor(readonly capacity: number) {}
 
   get stats(): WeightedCreditPoolStats {
-    return { current: this.current, peak: this.peak, queued: this.waiters.length };
+    return {
+      current: this.current, peak: this.peak, queued: this.waiters.length, resident: this.resident,
+    };
   }
 
   tryAcquire(bytes: number): ResizableCreditLease | null {
     if (this.waiters.length > 0 || this.current + bytes > this.capacity) return null;
-    return this.grant(bytes);
+    return this.grant(bytes, false);
   }
 
-  acquire(bytes: number, signal?: AbortSignal): Promise<ResizableCreditLease> {
+  /**
+   * The largest claim this lane can ever grant: capacity less what resident
+   * owners hold for their whole lifetime. A claim above it cannot be
+   * satisfied by waiting, because nothing it is waiting for will be
+   * released.
+   */
+  get grantableCeiling(): number {
+    return this.capacity - this.resident;
+  }
+
+  acquire(bytes: number, signal?: AbortSignal, resident = false): Promise<ResizableCreditLease> {
     if (signal?.aborted) return Promise.reject(abortError(signal));
-    const immediate = this.tryAcquire(bytes);
+    // Refuse a claim no amount of waiting can satisfy, rather than parking it
+    // in the FIFO forever. A parked claim is indistinguishable from a caller
+    // that stopped: no error, no timeout, and — because the queue refuses
+    // everyone behind it — no further progress anywhere in the isolate. That
+    // is what a real-vite launch looked like for four rounds of debugging.
+    if (bytes > this.grantableCeiling) {
+      return Promise.reject(new RangeError(
+        `weighted credit claim of ${bytes} bytes can never be granted: capacity is ${this.capacity} `
+        + `and ${this.resident} bytes are held by resident owners, leaving ${this.grantableCeiling}`,
+      ));
+    }
+    const immediate = resident ? null : this.tryAcquire(bytes);
     if (immediate) return Promise.resolve(immediate);
+    if (resident && this.waiters.length === 0 && this.current + bytes <= this.capacity) {
+      return Promise.resolve(this.grant(bytes, true));
+    }
 
     return new Promise<ResizableCreditLease>((resolve, reject) => {
       const waiter: CreditWaiter = {
         bytes,
+        resident,
         resolve,
         reject,
         signal,
@@ -84,8 +119,9 @@ class CreditLane {
     });
   }
 
-  private grant(bytes: number): ResizableCreditLease {
+  private grant(bytes: number, resident: boolean): ResizableCreditLease {
     this.current += bytes;
+    if (resident) this.resident += bytes;
     this.peak = Math.max(this.peak, this.current);
     let leasedBytes = bytes;
     let released = false;
@@ -107,6 +143,7 @@ class CreditLane {
           );
         }
         this.current -= leasedBytes - nextBytes;
+        if (resident) this.resident -= leasedBytes - nextBytes;
         leasedBytes = nextBytes;
         this.drain();
       },
@@ -114,6 +151,7 @@ class CreditLane {
         if (released) return;
         released = true;
         this.current -= leasedBytes;
+        if (resident) this.resident -= leasedBytes;
         if (this.current < 0) {
           throw new Error('weighted credit accounting underflow');
         }
@@ -134,7 +172,7 @@ class CreditLane {
       if (this.current + waiter.bytes > this.capacity) return;
       this.waiters.shift();
       waiter.signal?.removeEventListener('abort', waiter.onAbort!);
-      waiter.resolve(this.grant(waiter.bytes));
+      waiter.resolve(this.grant(waiter.bytes, waiter.resident));
     }
   }
 }
@@ -195,6 +233,7 @@ export class WeightedCreditPool {
       current: general.current + small.current,
       peak: general.peak + small.peak,
       queued: general.queued + small.queued,
+      resident: general.resident + small.resident,
     };
   }
 
@@ -226,6 +265,22 @@ export class WeightedCreditPool {
     return this.general.acquire(bytes, signal);
   }
 
+  /**
+   * Take credit that will be held for the owner's whole lifetime rather than
+   * for one operation — the esbuild pool's wasm image is the case.
+   *
+   * Recorded as a floor so a later claim that could never fit around it is
+   * refused with both numbers instead of parking in the FIFO forever.
+   */
+  acquireResident(bytes: number, signal?: AbortSignal): Promise<ResizableCreditLease> {
+    try {
+      this.validateRequest(bytes);
+    } catch (error) {
+      return Promise.reject(error as Error);
+    }
+    return this.general.acquire(bytes, signal, true);
+  }
+
   private validateRequest(bytes: number): void {
     if (!Number.isSafeInteger(bytes) || bytes <= 0 || bytes > this.capacity) {
       throw new RangeError(