@nimbus-sh/platform 0.5.0 → 0.5.1

package/dist/composition.d.ts

@@ -11,8 +11,18 @@
  *     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.
+ * The composition belongs at module scope: it is per isolate, and the
+ * platform serves a worker's entrypoints from whichever isolate it likes,
+ * so an isolate that never ran an embedder's request path must still know
+ * the composition. Composing again with the same values is a no-op;
+ * composing again with different values throws, because the second caller
+ * would otherwise run against a host it never named (a Worker that imports
+ * Nimbus's own entry and composes its own host would be that caller).
+ *
+ * The one thing the entrypoints need from the composition, the route back
+ * to the host, travels with every binding the fabric mints
+ * ({@link hostRoute}), so an entrypoint answers correctly in an isolate
+ * whose composition is absent or different.
  *
  * `ctx.exports` is runtime state, not composition: workerd mints it per
  * instance, so the embedder captures it where the platform hands it over —
@@ -36,15 +46,41 @@ export interface FabricComposition {
     /** RPC method the host forwards to workspace.supervisorOp. */
     hostDispatchMethod?: string;
 }
+/**
+ * The way back to the host from a binding the fabric minted: the namespace
+ * binding the host's Durable Object lives under, the method it forwards
+ * supervisor envelopes through, and the entrypoint export that answers
+ * supervisor bindings. Minted from the composition in the host's isolate
+ * and carried in the binding's props, so the entrypoint that receives the
+ * call resolves the host from the props rather than from its own isolate's
+ * composition.
+ */
+export interface HostRoute {
+    supervisorEntrypoint: string;
+    hostNamespace: string;
+    hostDispatchMethod: string;
+}
 export declare const DEFAULT_HOST_NAMESPACE = "NIMBUS_SESSION";
 export declare const DEFAULT_HOST_DISPATCH_METHOD = "supervisorOp";
-/** Composition and loopback exports are first-write-wins for this isolate. */
+/**
+ * Compose once per isolate. A second call with the same values is a no-op;
+ * a second call with different values throws, naming both, so an embedder
+ * whose composition lost to an earlier import learns it at startup rather
+ * than from a facet that reached the wrong host.
+ */
 export declare function composeFabric(value: FabricComposition): void;
 export declare function adoptCtxExports(value: CtxExports): void;
 export declare function getCtxExports(): CtxExports | null;
-export declare function supervisorEntrypoint(exportsObj?: unknown): EntrypointLoopbackFactory | null;
+export declare function supervisorEntrypoint(exportsObj?: unknown, name?: string | undefined): EntrypointLoopbackFactory | null;
 export declare function supervisorEntrypointName(): string | null;
 export declare function hostNamespace(): string;
 export declare function hostDispatchMethod(): string;
+/**
+ * The composed route, for the props of a binding minted in this isolate.
+ * Null when nothing is composed, like {@link supervisorEntrypoint}: a
+ * program run without a composition gets no supervisor binding, and needs
+ * no route back to a host it cannot reach.
+ */
+export declare function hostRoute(): HostRoute | null;
 export declare function stagedBootAssembler(): StagedBootAssembler;
 //# sourceMappingURL=composition.d.ts.map

package/dist/composition.d.ts.map

@@ -1 +1 @@
-{"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"}
+{"version":3,"file":"composition.d.ts","sourceRoot":"","sources":["../src/composition.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;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;;;;;;;;GAQG;AACH,MAAM,WAAW,SAAS;IACxB,oBAAoB,EAAE,MAAM,CAAC;IAC7B,aAAa,EAAE,MAAM,CAAC;IACtB,kBAAkB,EAAE,MAAM,CAAC;CAC5B;AAED,eAAO,MAAM,sBAAsB,mBAAmB,CAAC;AACvD,eAAO,MAAM,4BAA4B,iBAAiB,CAAC;AAI3D;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,iBAAiB,GAAG,IAAI,CAmB5D;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,EAAE,IAAI,qBAAoC,GAAG,yBAAyB,GAAG,IAAI,CAMrI;AAED,wBAAgB,wBAAwB,IAAI,MAAM,GAAG,IAAI,CAExD;AAED,wBAAgB,aAAa,IAAI,MAAM,CAEtC;AAED,wBAAgB,kBAAkB,IAAI,MAAM,CAE3C;AAED;;;;;GAKG;AACH,wBAAgB,SAAS,IAAI,SAAS,GAAG,IAAI,CAO5C;AAED,wBAAgB,mBAAmB,IAAI,mBAAmB,CASzD"}

package/dist/composition.js

@@ -2,10 +2,30 @@ export const DEFAULT_HOST_NAMESPACE = 'NIMBUS_SESSION';
 export const DEFAULT_HOST_DISPATCH_METHOD = 'supervisorOp';
 let composition = null;
 let ctxExports = null;
-/** Composition and loopback exports are first-write-wins for this isolate. */
+/**
+ * Compose once per isolate. A second call with the same values is a no-op;
+ * a second call with different values throws, naming both, so an embedder
+ * whose composition lost to an earlier import learns it at startup rather
+ * than from a facet that reached the wrong host.
+ */
 export function composeFabric(value) {
-    if (!composition)
+    if (!composition) {
         composition = value;
+        return;
+    }
+    const differences = ['supervisorEntrypoint', 'hostNamespace', 'hostDispatchMethod', 'stagedBootAssembler']
+        .filter((key) => composition?.[key] !== value[key]);
+    if (differences.length === 0)
+        return;
+    const describe = (c) => JSON.stringify({
+        supervisorEntrypoint: c.supervisorEntrypoint,
+        hostNamespace: c.hostNamespace ?? DEFAULT_HOST_NAMESPACE,
+        hostDispatchMethod: c.hostDispatchMethod ?? DEFAULT_HOST_DISPATCH_METHOD,
+        stagedBootAssembler: c.stagedBootAssembler ? 'set' : 'unset',
+    });
+    throw new Error(`fabric: composed twice with different values (${differences.join(', ')}): `
+        + `first ${describe(composition)}, then ${describe(value)}. `
+        + 'One composition per isolate; a Worker that imports another Nimbus entry inherits its composition.');
 }
 export function adoptCtxExports(value) {
     if (!ctxExports)
@@ -14,9 +34,8 @@ export function adoptCtxExports(value) {
 export function getCtxExports() {
     return ctxExports;
 }
-export function supervisorEntrypoint(exportsObj) {
+export function supervisorEntrypoint(exportsObj, name = composition?.supervisorEntrypoint) {
     const exports = exportsObj ?? ctxExports;
-    const name = composition?.supervisorEntrypoint;
     if (!name)
         return null;
     if ((typeof exports !== 'object' && typeof exports !== 'function') || exports === null)
@@ -33,6 +52,21 @@ export function hostNamespace() {
 export function hostDispatchMethod() {
     return composition?.hostDispatchMethod ?? DEFAULT_HOST_DISPATCH_METHOD;
 }
+/**
+ * The composed route, for the props of a binding minted in this isolate.
+ * Null when nothing is composed, like {@link supervisorEntrypoint}: a
+ * program run without a composition gets no supervisor binding, and needs
+ * no route back to a host it cannot reach.
+ */
+export function hostRoute() {
+    if (!composition)
+        return null;
+    return {
+        supervisorEntrypoint: composition.supervisorEntrypoint,
+        hostNamespace: hostNamespace(),
+        hostDispatchMethod: hostDispatchMethod(),
+    };
+}
 export function stagedBootAssembler() {
     const assembler = composition?.stagedBootAssembler;
     if (!assembler) {

package/dist/diag-counters.d.ts

@@ -75,6 +75,12 @@ export interface DiagCounters {
      * Surfaced as `breakdown.prefetchCacheBytes`. A gauge, not a delta.
      */
     prefetchCacheBytes: number;
+    /**
+     * Bytes retained by the FacetManager's ESM→CJS transform cache, bounded by
+     * ESM_TRANSFORM_CACHE_MAX_BYTES. Surfaced as `breakdown.transformCacheBytes`.
+     * A gauge, not a delta.
+     */
+    transformCacheBytes: number;
     /** Install-facet counters. Populated by npm-installer after a
      *  successful batch-facet dispatch returns. Confirms the install ran
      *  in the facet (tarballsCompleted > 0) and surfaces the
@@ -175,6 +181,8 @@ export declare function prefetchBundleEnd(bytes: number): void;
  * owns the number and reports it whenever it admits or evicts an entry.
  */
 export declare function setPrefetchCacheBytes(bytes: number): void;
+/** Publish the transform cache's live retained total; same contract as above. */
+export declare function setTransformCacheBytes(bytes: number): void;
 /** Fold facet-returned counters into the supervisor's diag state.
  *  Called by npm-installer after the batch-facet returns; aggregates
  *  rather than replaces so multiple install runs in the same DO

package/dist/diag-counters.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"diag-counters.d.ts","sourceRoot":"","sources":["../src/diag-counters.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"diag-counters.d.ts","sourceRoot":"","sources":["../src/diag-counters.ts"],"names":[],"mappings":"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"}

package/dist/diag-counters.js

@@ -23,6 +23,7 @@ const _counters = {
     inFlightRpcPayloadBytes: 0,
     prefetchBundleBytes: 0,
     prefetchCacheBytes: 0,
+    transformCacheBytes: 0,
     installFacet: {
         tarballsCompleted: 0,
         cumulativeBytesDecoded: 0,
@@ -122,6 +123,11 @@ export function setPrefetchCacheBytes(bytes) {
     const n = Number(bytes);
     _counters.prefetchCacheBytes = Number.isFinite(n) && n > 0 ? n : 0;
 }
+/** Publish the transform cache's live retained total; same contract as above. */
+export function setTransformCacheBytes(bytes) {
+    const n = Number(bytes);
+    _counters.transformCacheBytes = Number.isFinite(n) && n > 0 ? n : 0;
+}
 /** Fold facet-returned counters into the supervisor's diag state.
  *  Called by npm-installer after the batch-facet returns; aggregates
  *  rather than replaces so multiple install runs in the same DO

package/dist/heap-estimate.d.ts

@@ -180,6 +180,12 @@ export interface HeapBreakdown {
      * the cache holds rather than a reservation it might use.
      */
     prefetchCacheBytes: number;
+    /**
+     * Bytes retained by the FacetManager's ESM→CJS transform cache
+     * (diag-counters `transformCacheBytes`), the other cache that persists
+     * across execs. Bounded by ESM_TRANSFORM_CACHE_MAX_BYTES.
+     */
+    transformCacheBytes: number;
     /**
      * Shared-budget occupancy not already represented by the named transient
      * counters. This covers full-budget owners and keeps cross-DO module-local

package/dist/heap-estimate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"heap-estimate.d.ts","sourceRoot":"","sources":["../src/heap-estimate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0DG;AAOH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AACvD,OAAO,EAEL,KAAK,+BAA+B,EACrC,MAAM,wBAAwB,CAAC;AAEhC;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB,sFAM1B,CAAC;AAEX;;;;;;;;GAQG;AACH,MAAM,WAAW,aAAa;IAC5B,wCAAwC;IACxC,MAAM,EAAE,MAAM,CAAC;IACf;;;;OAIG;IACH,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,+DAA+D;IAC/D,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,gBAAgB,EAAE,SAAS,aAAa,EAAO,CAAC;AAE7D;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B;;;OAGG;IACH,cAAc,EAAE,MAAM,CAAC;IACvB,mEAAmE;IACnE,YAAY,EAAE,MAAM,CAAC;IACrB;;;;OAIG;IACH,gBAAgB,EAAE,MAAM,CAAC;IACzB,gEAAgE;IAChE,SAAS,EAAE,aAAa,CAAC;IACzB;;;OAGG;IACH,UAAU,EAAE,SAAS,aAAa,EAAE,CAAC;IACrC;;;;OAIG;IACH,qBAAqB,EAAE,MAAM,GAAG,IAAI,CAAC;IACrC;;;;OAIG;IACH,gBAAgB,EAAE,+BAA+B,CAAC;CACnD;AAED,MAAM,WAAW,aAAa;IAC5B,mEAAmE;IACnE,uBAAuB,EAAE,MAAM,CAAC;IAChC,yEAAyE;IACzE,WAAW,EAAE,MAAM,CAAC;IACpB,8DAA8D;IAC9D,gBAAgB,EAAE,MAAM,CAAC;IACzB;;sEAEkE;IAClE,mBAAmB,EAAE,MAAM,CAAC;IAC5B;;;;;;;;;;;;OAYG;IACH,qBAAqB,EAAE,MAAM,CAAC;IAC9B;;;;OAIG;IACH,mBAAmB,EAAE,MAAM,CAAC;IAC5B;;;;;OAKG;IACH,kBAAkB,EAAE,MAAM,CAAC;IAC3B;;;;OAIG;IACH,4BAA4B,EAAE,MAAM,CAAC;CACtC;AAED;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B,sEAAsE;IACtE,aAAa,EAAE,MAAM,CAAC;IACtB,8DAA8D;IAC9D,kBAAkB,EAAE,MAAM,CAAC;CAC5B;AAyBD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,2BAA2B,CAAC,CAAC,EAAE,YAAY,GAAG,MAAM,CAQnE;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACpC,CAAC,EAAE,YAAY,EACf,GAAG,EAAE,aAAa,GACjB,YAAY,CAkDd"}
+{"version":3,"file":"heap-estimate.d.ts","sourceRoot":"","sources":["../src/heap-estimate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0DG;AAOH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AACvD,OAAO,EAEL,KAAK,+BAA+B,EACrC,MAAM,wBAAwB,CAAC;AAEhC;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB,sFAM1B,CAAC;AAEX;;;;;;;;GAQG;AACH,MAAM,WAAW,aAAa;IAC5B,wCAAwC;IACxC,MAAM,EAAE,MAAM,CAAC;IACf;;;;OAIG;IACH,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,+DAA+D;IAC/D,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,gBAAgB,EAAE,SAAS,aAAa,EAAO,CAAC;AAE7D;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B;;;OAGG;IACH,cAAc,EAAE,MAAM,CAAC;IACvB,mEAAmE;IACnE,YAAY,EAAE,MAAM,CAAC;IACrB;;;;OAIG;IACH,gBAAgB,EAAE,MAAM,CAAC;IACzB,gEAAgE;IAChE,SAAS,EAAE,aAAa,CAAC;IACzB;;;OAGG;IACH,UAAU,EAAE,SAAS,aAAa,EAAE,CAAC;IACrC;;;;OAIG;IACH,qBAAqB,EAAE,MAAM,GAAG,IAAI,CAAC;IACrC;;;;OAIG;IACH,gBAAgB,EAAE,+BAA+B,CAAC;CACnD;AAED,MAAM,WAAW,aAAa;IAC5B,mEAAmE;IACnE,uBAAuB,EAAE,MAAM,CAAC;IAChC,yEAAyE;IACzE,WAAW,EAAE,MAAM,CAAC;IACpB,8DAA8D;IAC9D,gBAAgB,EAAE,MAAM,CAAC;IACzB;;sEAEkE;IAClE,mBAAmB,EAAE,MAAM,CAAC;IAC5B;;;;;;;;;;;;OAYG;IACH,qBAAqB,EAAE,MAAM,CAAC;IAC9B;;;;OAIG;IACH,mBAAmB,EAAE,MAAM,CAAC;IAC5B;;;;;OAKG;IACH,kBAAkB,EAAE,MAAM,CAAC;IAC3B;;;;OAIG;IACH,mBAAmB,EAAE,MAAM,CAAC;IAC5B;;;;OAIG;IACH,4BAA4B,EAAE,MAAM,CAAC;CACtC;AAED;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B,sEAAsE;IACtE,aAAa,EAAE,MAAM,CAAC;IACtB,8DAA8D;IAC9D,kBAAkB,EAAE,MAAM,CAAC;CAC5B;AAyBD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,2BAA2B,CAAC,CAAC,EAAE,YAAY,GAAG,MAAM,CAQnE;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACpC,CAAC,EAAE,YAAY,EACf,GAAG,EAAE,aAAa,GACjB,YAAY,CAoDd"}

package/dist/heap-estimate.js

@@ -160,6 +160,7 @@ export function estimateSupervisorHeap(c, vfs) {
         streamingBuffersBytes: c.inFlightRpcPayloadBytes,
         prefetchBundleBytes: c.prefetchBundleBytes,
         prefetchCacheBytes: c.prefetchCacheBytes,
+        transformCacheBytes: c.transformCacheBytes,
         unattributedReservationBytes: Math.max(0, allocationBudget.current - transientAttributedBytes),
     };
     const estimatedBytes = breakdown.supervisorBaselineBytes +
@@ -169,6 +170,7 @@ export function estimateSupervisorHeap(c, vfs) {
         breakdown.streamingBuffersBytes +
         breakdown.prefetchBundleBytes +
         breakdown.prefetchCacheBytes +
+        breakdown.transformCacheBytes +
         breakdown.unattributedReservationBytes;
     const percentOfCeiling = Math.round((estimatedBytes / SUPERVISOR_HEAP_CEILING_BYTES) * 1000) / 10;
     return {

package/dist/limits.d.ts

@@ -69,6 +69,28 @@ export declare const SQLITE_MAX_ROW_BYTES = 2000000;
  * fabric defers async reconciliation off the gate entirely (`onColdStart`).
  */
 export declare const BLOCK_CONCURRENCY_CANCEL_MS = 30000;
+/**
+ * Cadence of the alarm that keeps a session Durable Object in memory while
+ * a resident process runs. The platform evicts an object after roughly ten
+ * seconds with no in-flight event; a pending promise (`ctx.waitUntil`) is
+ * not one, and facets die with their parent. Measured 2026-09-21 on local
+ * workerd and on Cloudflare: a quiet resident process survived 8 s of
+ * silence and was re-driven under a new pid namespace after 12 s.
+ */
+export declare const RESIDENT_KEEPALIVE_MS = 5000;
+/**
+ * How long the keep-alive holds a session after its last client is gone.
+ *
+ * The keep-alive exists so a quiet process survives while its user is
+ * present. Unbounded, it made every abandoned session with a dev server
+ * run forever: the probe suite's cancelled runs left staging with resident
+ * watchers polling `stat` at ~7.5/s in the isolate every session shares,
+ * and launches that pass on a fresh Worker reset there (2026-09-22). Past
+ * this grace with no attached socket and no request, the session idles
+ * out as it did before the keep-alive, and the launch journal re-drives
+ * the process when a client returns. Long enough for a tab reload.
+ */
+export declare const RESIDENT_KEEPALIVE_DETACHED_MS = 60000;
 /**
  * Bytes one hibernatable WebSocket attachment may serialize to. Verified in
  * workerd source at the pinned version (v1.20260603.1,

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;AAErD;;;;;GAKG;AACH,eAAO,MAAM,0BAA0B,QAAa,CAAC;AAErD;;;;GAIG;AACH,eAAO,MAAM,2BAA2B,MAAM,CAAC;AAE/C;;;;;;GAMG;AACH,eAAO,MAAM,oBAAoB,UAAY,CAAC;AAI9C;;;;;;;;GAQG;AACH,eAAO,MAAM,2BAA2B,QAAS,CAAC;AAIlD;;;;;;;;;GASG;AACH,eAAO,MAAM,yBAAyB,QAAS,CAAC;AAOhD,eAAO,MAAM,0BAA0B,QAAmB,CAAC;AA6B3D,eAAO,MAAM,6BAA6B,QAAmB,CAAC;AAO9D,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;AAErD;;;;;GAKG;AACH,eAAO,MAAM,0BAA0B,QAAa,CAAC;AAErD;;;;GAIG;AACH,eAAO,MAAM,2BAA2B,MAAM,CAAC;AAE/C;;;;;;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;AA6B3D,eAAO,MAAM,6BAA6B,QAAmB,CAAC;AAO9D,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"}

package/dist/limits.js

@@ -77,6 +77,29 @@ export const SQLITE_MAX_ROW_BYTES = 2_000_000;
  * fabric defers async reconciliation off the gate entirely (`onColdStart`).
  */
 export const BLOCK_CONCURRENCY_CANCEL_MS = 30_000;
+// ── Eviction window ─────────────────────────────────────────────────────
+/**
+ * Cadence of the alarm that keeps a session Durable Object in memory while
+ * a resident process runs. The platform evicts an object after roughly ten
+ * seconds with no in-flight event; a pending promise (`ctx.waitUntil`) is
+ * not one, and facets die with their parent. Measured 2026-09-21 on local
+ * workerd and on Cloudflare: a quiet resident process survived 8 s of
+ * silence and was re-driven under a new pid namespace after 12 s.
+ */
+export const RESIDENT_KEEPALIVE_MS = 5_000;
+/**
+ * How long the keep-alive holds a session after its last client is gone.
+ *
+ * The keep-alive exists so a quiet process survives while its user is
+ * present. Unbounded, it made every abandoned session with a dev server
+ * run forever: the probe suite's cancelled runs left staging with resident
+ * watchers polling `stat` at ~7.5/s in the isolate every session shares,
+ * and launches that pass on a fresh Worker reset there (2026-09-22). Past
+ * this grace with no attached socket and no request, the session idles
+ * out as it did before the keep-alive, and the launch journal re-drives
+ * the process when a client returns. Long enough for a tab reload.
+ */
+export const RESIDENT_KEEPALIVE_DETACHED_MS = 60_000;
 // ── WebSocket attachment bound ──────────────────────────────────────────
 /**
  * Bytes one hibernatable WebSocket attachment may serialize to. Verified in

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@nimbus-sh/platform",
-  "version": "0.5.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.",
+  "version": "0.5.1",
+  "description": "The measured Cloudflare platform truths Nimbus is built on \u2014 error taxonomy, limits tables, budget coordination, and wire-format primitives, with zero runtime dependencies.",
   "keywords": [
     "cloudflare",
     "workers",

package/src/composition.ts

@@ -11,8 +11,18 @@
  *     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.
+ * The composition belongs at module scope: it is per isolate, and the
+ * platform serves a worker's entrypoints from whichever isolate it likes,
+ * so an isolate that never ran an embedder's request path must still know
+ * the composition. Composing again with the same values is a no-op;
+ * composing again with different values throws, because the second caller
+ * would otherwise run against a host it never named (a Worker that imports
+ * Nimbus's own entry and composes its own host would be that caller).
+ *
+ * The one thing the entrypoints need from the composition, the route back
+ * to the host, travels with every binding the fabric mints
+ * ({@link hostRoute}), so an entrypoint answers correctly in an isolate
+ * whose composition is absent or different.
  *
  * `ctx.exports` is runtime state, not composition: workerd mints it per
  * instance, so the embedder captures it where the platform hands it over —
@@ -36,14 +46,51 @@ export interface FabricComposition {
   hostDispatchMethod?: string;
 }
 
+/**
+ * The way back to the host from a binding the fabric minted: the namespace
+ * binding the host's Durable Object lives under, the method it forwards
+ * supervisor envelopes through, and the entrypoint export that answers
+ * supervisor bindings. Minted from the composition in the host's isolate
+ * and carried in the binding's props, so the entrypoint that receives the
+ * call resolves the host from the props rather than from its own isolate's
+ * composition.
+ */
+export interface HostRoute {
+  supervisorEntrypoint: string;
+  hostNamespace: string;
+  hostDispatchMethod: string;
+}
+
 export const DEFAULT_HOST_NAMESPACE = 'NIMBUS_SESSION';
 export const DEFAULT_HOST_DISPATCH_METHOD = 'supervisorOp';
 let composition: FabricComposition | null = null;
 let ctxExports: CtxExports | null = null;
 
-/** Composition and loopback exports are first-write-wins for this isolate. */
+/**
+ * Compose once per isolate. A second call with the same values is a no-op;
+ * a second call with different values throws, naming both, so an embedder
+ * whose composition lost to an earlier import learns it at startup rather
+ * than from a facet that reached the wrong host.
+ */
 export function composeFabric(value: FabricComposition): void {
-  if (!composition) composition = value;
+  if (!composition) {
+    composition = value;
+    return;
+  }
+  const differences = (['supervisorEntrypoint', 'hostNamespace', 'hostDispatchMethod', 'stagedBootAssembler'] as const)
+    .filter((key) => composition?.[key] !== value[key]);
+  if (differences.length === 0) return;
+  const describe = (c: FabricComposition) => JSON.stringify({
+    supervisorEntrypoint: c.supervisorEntrypoint,
+    hostNamespace: c.hostNamespace ?? DEFAULT_HOST_NAMESPACE,
+    hostDispatchMethod: c.hostDispatchMethod ?? DEFAULT_HOST_DISPATCH_METHOD,
+    stagedBootAssembler: c.stagedBootAssembler ? 'set' : 'unset',
+  });
+  throw new Error(
+    `fabric: composed twice with different values (${differences.join(', ')}): `
+      + `first ${describe(composition)}, then ${describe(value)}. `
+      + 'One composition per isolate; a Worker that imports another Nimbus entry inherits its composition.',
+  );
 }
 
 export function adoptCtxExports(value: CtxExports): void {
@@ -54,9 +101,8 @@ export function getCtxExports(): CtxExports | null {
   return ctxExports;
 }
 
-export function supervisorEntrypoint(exportsObj?: unknown): EntrypointLoopbackFactory | null {
+export function supervisorEntrypoint(exportsObj?: unknown, name = composition?.supervisorEntrypoint): EntrypointLoopbackFactory | null {
   const exports = exportsObj ?? ctxExports;
-  const name = composition?.supervisorEntrypoint;
   if (!name) return null;
   if ((typeof exports !== 'object' && typeof exports !== 'function') || exports === null) return null;
   const factory = (exports as Record<string, unknown>)[name];
@@ -75,6 +121,21 @@ export function hostDispatchMethod(): string {
   return composition?.hostDispatchMethod ?? DEFAULT_HOST_DISPATCH_METHOD;
 }
 
+/**
+ * The composed route, for the props of a binding minted in this isolate.
+ * Null when nothing is composed, like {@link supervisorEntrypoint}: a
+ * program run without a composition gets no supervisor binding, and needs
+ * no route back to a host it cannot reach.
+ */
+export function hostRoute(): HostRoute | null {
+  if (!composition) return null;
+  return {
+    supervisorEntrypoint: composition.supervisorEntrypoint,
+    hostNamespace: hostNamespace(),
+    hostDispatchMethod: hostDispatchMethod(),
+  };
+}
+
 export function stagedBootAssembler(): StagedBootAssembler {
   const assembler = composition?.stagedBootAssembler;
   if (!assembler) {

package/src/diag-counters.ts

@@ -82,6 +82,12 @@ export interface DiagCounters {
    * Surfaced as `breakdown.prefetchCacheBytes`. A gauge, not a delta.
    */
   prefetchCacheBytes: number;
+  /**
+   * Bytes retained by the FacetManager's ESM→CJS transform cache, bounded by
+   * ESM_TRANSFORM_CACHE_MAX_BYTES. Surfaced as `breakdown.transformCacheBytes`.
+   * A gauge, not a delta.
+   */
+  transformCacheBytes: number;
   /** Install-facet counters. Populated by npm-installer after a
    *  successful batch-facet dispatch returns. Confirms the install ran
    *  in the facet (tarballsCompleted > 0) and surfaces the
@@ -141,6 +147,7 @@ const _counters: DiagCounters = {
   inFlightRpcPayloadBytes: 0,
   prefetchBundleBytes: 0,
   prefetchCacheBytes: 0,
+  transformCacheBytes: 0,
   installFacet: {
     tarballsCompleted: 0,
     cumulativeBytesDecoded: 0,
@@ -243,6 +250,12 @@ export function setPrefetchCacheBytes(bytes: number): void {
   _counters.prefetchCacheBytes = Number.isFinite(n) && n > 0 ? n : 0;
 }
 
+/** Publish the transform cache's live retained total; same contract as above. */
+export function setTransformCacheBytes(bytes: number): void {
+  const n = Number(bytes);
+  _counters.transformCacheBytes = Number.isFinite(n) && n > 0 ? n : 0;
+}
+
 /** Fold facet-returned counters into the supervisor's diag state.
  *  Called by npm-installer after the batch-facet returns; aggregates
  *  rather than replaces so multiple install runs in the same DO

package/src/heap-estimate.ts

@@ -200,6 +200,12 @@ export interface HeapBreakdown {
    * the cache holds rather than a reservation it might use.
    */
   prefetchCacheBytes: number;
+  /**
+   * Bytes retained by the FacetManager's ESM→CJS transform cache
+   * (diag-counters `transformCacheBytes`), the other cache that persists
+   * across execs. Bounded by ESM_TRANSFORM_CACHE_MAX_BYTES.
+   */
+  transformCacheBytes: number;
   /**
    * Shared-budget occupancy not already represented by the named transient
    * counters. This covers full-budget owners and keeps cross-DO module-local
@@ -297,6 +303,7 @@ export function estimateSupervisorHeap(
     streamingBuffersBytes: c.inFlightRpcPayloadBytes,
     prefetchBundleBytes: c.prefetchBundleBytes,
     prefetchCacheBytes: c.prefetchCacheBytes,
+    transformCacheBytes: c.transformCacheBytes,
     unattributedReservationBytes: Math.max(
       0,
       allocationBudget.current - transientAttributedBytes,
@@ -311,6 +318,7 @@ export function estimateSupervisorHeap(
     breakdown.streamingBuffersBytes +
     breakdown.prefetchBundleBytes +
     breakdown.prefetchCacheBytes +
+    breakdown.transformCacheBytes +
     breakdown.unattributedReservationBytes;
 
   const percentOfCeiling = Math.round(

package/src/limits.ts

@@ -89,6 +89,32 @@ export const SQLITE_MAX_ROW_BYTES = 2_000_000;
  */
 export const BLOCK_CONCURRENCY_CANCEL_MS = 30_000;
 
+// ── Eviction window ─────────────────────────────────────────────────────
+
+/**
+ * Cadence of the alarm that keeps a session Durable Object in memory while
+ * a resident process runs. The platform evicts an object after roughly ten
+ * seconds with no in-flight event; a pending promise (`ctx.waitUntil`) is
+ * not one, and facets die with their parent. Measured 2026-09-21 on local
+ * workerd and on Cloudflare: a quiet resident process survived 8 s of
+ * silence and was re-driven under a new pid namespace after 12 s.
+ */
+export const RESIDENT_KEEPALIVE_MS = 5_000;
+
+/**
+ * How long the keep-alive holds a session after its last client is gone.
+ *
+ * The keep-alive exists so a quiet process survives while its user is
+ * present. Unbounded, it made every abandoned session with a dev server
+ * run forever: the probe suite's cancelled runs left staging with resident
+ * watchers polling `stat` at ~7.5/s in the isolate every session shares,
+ * and launches that pass on a fresh Worker reset there (2026-09-22). Past
+ * this grace with no attached socket and no request, the session idles
+ * out as it did before the keep-alive, and the launch journal re-drives
+ * the process when a client returns. Long enough for a tab reload.
+ */
+export const RESIDENT_KEEPALIVE_DETACHED_MS = 60_000;
+
 // ── WebSocket attachment bound ──────────────────────────────────────────
 
 /**