@nimbus-sh/worker 0.5.0 → 0.7.0

package/dist/facets/durable-images.js

@@ -12,16 +12,34 @@
  * durable spawn exists to survive. Durable images are kept for the
  * application's life and released only by explicit removal.
  *
- * Two blobs per launch: `runner` is the worker.js source text, `application`
- * is a JSON payload of `{ modules, env, vfsWasmModules }`. The digests in the
- * journal's `recipe.image` are sha256 hashes of those two payloads, and a
- * self-owned spawn mints them at spawn time; an embedder-owned spawn is given
- * them by its own bookkeeping instead.
+ * Two blobs per launch: `runner` is the main module's source text,
+ * `application` is a JSON payload of `{ modules, env, vfsWasmModules }` plus,
+ * when the launch set them, `vfsTextModules`, `mainModule` and `startArgs`.
+ * The digests in the journal's `recipe.image` are sha256 hashes of those two
+ * payloads, and a self-owned spawn mints them at spawn time; an
+ * embedder-owned spawn is given them by its own bookkeeping instead.
  */
 import { CRED_KERNEL } from '@nimbus-sh/core/runtime/os-contracts.js';
 /** The directory every durable application's image blobs live under. */
 export const DURABLE_IMAGE_DIR = '.nimbus/images';
 const imagePath = (digest) => `${DURABLE_IMAGE_DIR}/${digest}`;
+/** Remove only the owner's blobs that no other retained recipe references. */
+export function purgeDurableWorkerImages(vfs, owned, retained) {
+    const keep = new Set([...retained].flatMap((image) => [image.runner, image.application]));
+    const candidates = new Set([...owned].flatMap((image) => [image.runner, image.application]));
+    const kernel = vfs.as(CRED_KERNEL);
+    let removed = 0;
+    for (const digest of candidates) {
+        if (keep.has(digest) || !/^[a-f0-9]{64}$/.test(digest))
+            continue;
+        const path = imagePath(digest);
+        if (!kernel.exists(path))
+            continue;
+        kernel.unlink(path);
+        removed += 1;
+    }
+    return removed;
+}
 async function sha256Hex(text) {
     const digest = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(text));
     return Array.from(new Uint8Array(digest), (b) => b.toString(16).padStart(2, '0')).join('');
@@ -37,10 +55,15 @@ export async function persistDurableWorkerImage(vfs, workerCode, payload) {
     kernel.mkdir(DURABLE_IMAGE_DIR, { recursive: true });
     const runner = await sha256Hex(workerCode);
     kernel.writeFile(imagePath(runner), workerCode);
+    // Optional members are omitted rather than written null so an unchanged
+    // launch keeps the digest it had before the member existed.
     const applicationPayload = JSON.stringify({
         modules: payload.modules,
         env: payload.env ?? null,
         vfsWasmModules: payload.vfsWasmModules ?? null,
+        ...(payload.vfsTextModules !== undefined ? { vfsTextModules: payload.vfsTextModules } : {}),
+        ...(payload.mainModule !== undefined ? { mainModule: payload.mainModule } : {}),
+        ...(payload.startArgs !== undefined ? { startArgs: payload.startArgs } : {}),
     });
     const application = await sha256Hex(applicationPayload);
     kernel.writeFile(imagePath(application), applicationPayload);
@@ -65,11 +88,17 @@ export async function resolveDurableWorkerImage(vfs, recipe) {
         return null;
     }
     const runner = new TextDecoder().decode(runnerBytes);
-    const { modules = {}, env = null, vfsWasmModules = undefined } = JSON.parse(new TextDecoder().decode(applicationBytes));
+    const { modules = {}, env = null, vfsWasmModules = undefined, vfsTextModules, mainModule, startArgs, } = JSON.parse(new TextDecoder().decode(applicationBytes));
+    // The recipe's own record of the main module wins when the blob predates
+    // the member; both say the same thing for any launch written since.
+    const main = mainModule ?? recipe.mainModule ?? 'worker.js';
     return {
         env: env ?? null,
         globalOutbound: undefined,
-        modules: { 'worker.js': runner, ...modules },
+        modules: { ...modules, [main]: runner },
+        mainModule: main,
+        ...(startArgs !== undefined ? { startArgs } : {}),
         ...(vfsWasmModules !== null ? { vfsWasmModules } : {}),
+        ...(vfsTextModules !== undefined ? { vfsTextModules } : {}),
     };
 }

package/dist/facets/durable-slots.d.ts

@@ -41,5 +41,5 @@ export declare function acquireDurableFacetSlot(ctx: DurableObjectState, owner:
  * step of explicit removal, after the facet's SQLite is already gone. Answers
  * the freed name, or null when the owner held nothing.
  */
-export declare function freeDurableFacetSlot(ctx: DurableObjectState, owner: string): Promise<string | null>;
+export declare function freeDurableFacetSlot(ctx: DurableObjectState, owner: string, beforeFree?: (name: string) => void): Promise<string | null>;
 //# sourceMappingURL=durable-slots.d.ts.map

package/dist/facets/durable-slots.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"durable-slots.d.ts","sourceRoot":"","sources":["../../src/facets/durable-slots.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAUH,kDAAkD;AAClD,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAErD;AAED;;;;;;;;;GASG;AACH,wBAAsB,uBAAuB,CAC3C,GAAG,EAAE,kBAAkB,EACvB,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,MAAM,CAAC,CA4BjB;AAED;;;;GAIG;AACH,wBAAsB,oBAAoB,CACxC,GAAG,EAAE,kBAAkB,EACvB,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAYxB"}
+{"version":3,"file":"durable-slots.d.ts","sourceRoot":"","sources":["../../src/facets/durable-slots.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAUH,kDAAkD;AAClD,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAErD;AAED;;;;;;;;;GASG;AACH,wBAAsB,uBAAuB,CAC3C,GAAG,EAAE,kBAAkB,EACvB,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,MAAM,CAAC,CA4BjB;AAED;;;;GAIG;AACH,wBAAsB,oBAAoB,CACxC,GAAG,EAAE,kBAAkB,EACvB,KAAK,EAAE,MAAM,EACb,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,GAClC,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAaxB"}

package/dist/facets/durable-slots.js

@@ -78,11 +78,12 @@ export async function acquireDurableFacetSlot(ctx, owner) {
  * step of explicit removal, after the facet's SQLite is already gone. Answers
  * the freed name, or null when the owner held nothing.
  */
-export async function freeDurableFacetSlot(ctx, owner) {
+export async function freeDurableFacetSlot(ctx, owner, beforeFree) {
     return ctx.storage.transaction(async (txn) => {
         const held = await txn.get(ownerKey(owner));
         if (typeof held !== 'number')
             return null;
+        beforeFree?.(durableFacetName(held));
         await txn.delete(ownerKey(owner));
         const free = await txn.get(FREE_KEY);
         const freeList = Array.isArray(free) ? free.filter((n) => typeof n === 'number') : [];

package/dist/facets/esbuild-bundle-pool.d.ts

@@ -0,0 +1,49 @@
+/**
+ * EsbuildBundlePool — the session's single esbuild facet pool.
+ *
+ * Install-time pre-bundling and on-demand /@modules/ bundling dispatch the
+ * same worker (PRE_BUNDLE_PREAMBLE + esbuild.wasm, one slot). When each
+ * pipeline built its own IsolatePool the supervisor retained two copies of
+ * the ~12 MiB wasm bytes and warmed two loader slots per session, and the
+ * two pools never queued behind each other. One pool, owned by the session,
+ * holds one wasm copy — leased once from the shared supervisor allocation
+ * budget, the way the pre-bundler already accounted for its own — for as
+ * long as the installer and dev server live, and is disposed with them.
+ *
+ * Construction is lazy and everything heavy is imported on first use so
+ * the fabric/preamble/wasm subgraph stays out of the cold script-eval
+ * graph of sessions that never bundle.
+ */
+import type { IsolatePool } from '@nimbus-sh/fabric/isolate-pool.js';
+/** The pool surface both bundling pipelines dispatch through. */
+export type BundlePool = Pick<IsolatePool, 'submit'>;
+/** What a bundling pipeline receives from its host. */
+export interface BundlePoolProvider {
+    /** The session's pool, constructed on first call. */
+    acquire(): Promise<BundlePool>;
+}
+export declare class EsbuildBundlePool implements BundlePoolProvider {
+    private readonly env;
+    private readonly ctx;
+    private pool;
+    private pending;
+    /** Releases the wasm bytes' supervisor credit; held until dispose(). */
+    private releaseWasmCredit;
+    /** Bumped by dispose() so a construction it interrupted tears itself down. */
+    private generation;
+    constructor(env: unknown, ctx: DurableObjectState);
+    /**
+     * Callers MUST acquire the pool before taking any slice lease: the
+     * first construction reserves the full supervisor budget while the wasm
+     * bytes are fetched, so a caller already holding slice credit would
+     * wait on itself.
+     */
+    acquire(): Promise<IsolatePool>;
+    private construct;
+    /**
+     * Tear the pool down with its host. A later acquire() constructs a fresh
+     * pool, so a session that installs again after a teardown still bundles.
+     */
+    dispose(): void;
+}
+//# sourceMappingURL=esbuild-bundle-pool.d.ts.map

package/dist/facets/esbuild-bundle-pool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"esbuild-bundle-pool.d.ts","sourceRoot":"","sources":["../../src/facets/esbuild-bundle-pool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mCAAmC,CAAC;AASrE,iEAAiE;AACjE,MAAM,MAAM,UAAU,GAAG,IAAI,CAAC,WAAW,EAAE,QAAQ,CAAC,CAAC;AAErD,uDAAuD;AACvD,MAAM,WAAW,kBAAkB;IACjC,qDAAqD;IACrD,OAAO,IAAI,OAAO,CAAC,UAAU,CAAC,CAAC;CAChC;AAQD,qBAAa,iBAAkB,YAAW,kBAAkB;IASxD,OAAO,CAAC,QAAQ,CAAC,GAAG;IACpB,OAAO,CAAC,QAAQ,CAAC,GAAG;IATtB,OAAO,CAAC,IAAI,CAA4B;IACxC,OAAO,CAAC,OAAO,CAAqC;IACpD,wEAAwE;IACxE,OAAO,CAAC,iBAAiB,CAA6B;IACtD,8EAA8E;IAC9E,OAAO,CAAC,UAAU,CAAK;gBAGJ,GAAG,EAAE,OAAO,EACZ,GAAG,EAAE,kBAAkB;IAG1C;;;;;OAKG;IACH,OAAO,IAAI,OAAO,CAAC,WAAW,CAAC;YAqBjB,SAAS;IAmDvB;;;OAGG;IACH,OAAO,IAAI,IAAI;CAYhB"}

package/dist/facets/esbuild-bundle-pool.js

@@ -0,0 +1,122 @@
+import { acquireResidentSupervisorAllocation } from '@nimbus-sh/platform/heavy-alloc-coord.js';
+import { PRE_BUNDLE_CONCURRENCY, PRE_BUNDLE_SLICE_CAP_BYTES, SUPERVISOR_IN_FLIGHT_ALLOCATION_BUDGET_BYTES, } from '@nimbus-sh/platform/limits.js';
+function hasAssetsFetcher(env) {
+    if (typeof env !== 'object' || env === null)
+        return false;
+    const assets = Reflect.get(env, 'ASSETS');
+    return typeof assets === 'object' && assets !== null && typeof Reflect.get(assets, 'fetch') === 'function';
+}
+export class EsbuildBundlePool {
+    env;
+    ctx;
+    pool = null;
+    pending = null;
+    /** Releases the wasm bytes' supervisor credit; held until dispose(). */
+    releaseWasmCredit = null;
+    /** Bumped by dispose() so a construction it interrupted tears itself down. */
+    generation = 0;
+    constructor(env, ctx) {
+        this.env = env;
+        this.ctx = ctx;
+    }
+    /**
+     * Callers MUST acquire the pool before taking any slice lease: the
+     * first construction reserves the full supervisor budget while the wasm
+     * bytes are fetched, so a caller already holding slice credit would
+     * wait on itself.
+     */
+    acquire() {
+        if (this.pool)
+            return Promise.resolve(this.pool);
+        if (this.pending)
+            return this.pending;
+        const generation = this.generation;
+        const pending = this.construct().then(({ pool, releaseWasmCredit }) => {
+            if (this.generation !== generation) {
+                // dispose() ran while the wasm bytes were in flight.
+                try {
+                    pool.dispose();
+                }
+                catch { /* best-effort */ }
+                releaseWasmCredit();
+                throw new Error('EsbuildBundlePool: disposed during construction');
+            }
+            this.pool = pool;
+            this.releaseWasmCredit = releaseWasmCredit;
+            return pool;
+        }).finally(() => {
+            if (this.pending === pending)
+                this.pending = null;
+        });
+        this.pending = pending;
+        return pending;
+    }
+    async construct() {
+        if (!hasAssetsFetcher(this.env)) {
+            throw new Error('EsbuildBundlePool: env.ASSETS binding missing — the esbuild wasm asset cannot be fetched');
+        }
+        const env = this.env;
+        const [{ IsolatePool }, { PRE_BUNDLE_PREAMBLE }, { fetchEsbuildWasmBytes }] = await Promise.all([
+            import('@nimbus-sh/fabric/isolate-pool.js'),
+            import('../loaders/pre-bundle-preamble.js'),
+            import('../runtime/esbuild-wasm-bytes.js'),
+        ]);
+        // Resident, and sized to what the pool will KEEP — not the whole budget.
+        //
+        // The full-budget claim this used to make is grantable exactly once: the
+        // lease it shrinks to becomes a permanent floor, so a second pool
+        // construction asked for 40 MiB against 28.1 MiB that could ever be free
+        // and parked in the FIFO with no error and no CPU. Measured on a
+        // deployed worker: capacity 41,943,040, resident 11,907,565, queued 1 for
+        // 222 s with the isolate healthy the whole time — and because the queue
+        // refuses everyone behind a waiter, the whole session stopped making
+        // progress. The bound below is the same one the payload is checked
+        // against, so the slice cap stays free for the work the pool exists for.
+        const maxRetainedWasmBytes = SUPERVISOR_IN_FLIGHT_ALLOCATION_BUDGET_BYTES - PRE_BUNDLE_SLICE_CAP_BYTES;
+        const setupAllocation = await acquireResidentSupervisorAllocation(maxRetainedWasmBytes);
+        let retained = false;
+        try {
+            const wasmBytes = await fetchEsbuildWasmBytes(env);
+            if (wasmBytes.byteLength > maxRetainedWasmBytes) {
+                throw new RangeError(`esbuild wasm payload ${wasmBytes.byteLength} exceeds the ${maxRetainedWasmBytes}-byte retained budget`);
+            }
+            // IsolatePool keeps the constructor-time module bytes until dispose(),
+            // so retain their exact credit rather than treating construction as a
+            // handoff that immediately frees the ArrayBuffer.
+            setupAllocation.shrinkTo(wasmBytes.byteLength);
+            const pool = new IsolatePool(env, this.ctx, {
+                concurrency: PRE_BUNDLE_CONCURRENCY,
+                timeoutMs: 60_000,
+                retries: 0,
+                tag: 'esbuild-bundle',
+                preamble: PRE_BUNDLE_PREAMBLE,
+                wasmModules: { 'esbuild.wasm': wasmBytes },
+            });
+            retained = true;
+            return { pool, releaseWasmCredit: setupAllocation.release };
+        }
+        finally {
+            if (!retained)
+                setupAllocation.release();
+        }
+    }
+    /**
+     * Tear the pool down with its host. A later acquire() constructs a fresh
+     * pool, so a session that installs again after a teardown still bundles.
+     */
+    dispose() {
+        this.generation++;
+        const pool = this.pool;
+        this.pool = null;
+        this.pending = null;
+        if (pool) {
+            try {
+                pool.dispose();
+            }
+            catch { /* best-effort */ }
+        }
+        const release = this.releaseWasmCredit;
+        this.releaseWasmCredit = null;
+        release?.();
+    }
+}

package/dist/facets/exec-telemetry.d.ts

@@ -57,6 +57,14 @@ export interface ExecTelemetryRecord {
     fsRpcReads: number;
     /** Whether the prefetch bundle was served from cache (no VFS walk). */
     cacheHit: boolean;
+    /**
+     * Durable Object turns the bundle build was paged across — the alarm
+     * round trips `TurnBudget` took before the process could start. 0 when the
+     * whole build fit in the turn that asked for it, which is every cache hit
+     * and every small tree; the count is what says a large tree cost turns
+     * rather than a held thread.
+     */
+    turns: number;
     /** Exit code, for cross-referencing telemetry against failures. */
     exitCode: number;
     /** Wall-clock at record time (supervisor side). */

package/dist/facets/exec-telemetry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"exec-telemetry.d.ts","sourceRoot":"","sources":["../../src/facets/exec-telemetry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,yDAAyD;AACzD,MAAM,WAAW,mBAAmB;IAClC,uEAAuE;IACvE,OAAO,EAAE,MAAM,CAAC;IAChB,iEAAiE;IACjE,QAAQ,EAAE,MAAM,CAAC;IACjB,6CAA6C;IAC7C,MAAM,EAAE,MAAM,CAAC;IACf,+DAA+D;IAC/D,KAAK,EAAE,MAAM,CAAC;IACd;0EACsE;IACtE,WAAW,EAAE,MAAM,CAAC;IACpB,uEAAuE;IACvE,cAAc,EAAE,MAAM,CAAC;IACvB;;;;;;;;;OASG;IACH,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,EAAE,MAAM,CAAC;IACtB,aAAa,EAAE,MAAM,CAAC;IACtB,sEAAsE;IACtE,SAAS,EAAE,MAAM,CAAC;IAClB;;gEAE4D;IAC5D,UAAU,EAAE,MAAM,CAAC;IACnB,uEAAuE;IACvE,QAAQ,EAAE,OAAO,CAAC;IAClB,mEAAmE;IACnE,QAAQ,EAAE,MAAM,CAAC;IACjB,mDAAmD;IACnD,EAAE,EAAE,MAAM,CAAC;CACZ;AAED;;;GAGG;AACH,MAAM,MAAM,YAAY,GAAG,IAAI,CAC7B,mBAAmB,EACnB,QAAQ,GAAG,OAAO,GAAG,gBAAgB,GAAG,aAAa,GAAG,eAAe,GAAG,eAAe,CAC1F,CAAC;AAKF;;;;GAIG;AACH,wBAAgB,iBAAiB,IAAI,OAAO,CAE3C;AAED,qEAAqE;AACrE,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,mBAAmB,GAAG,IAAI,CAIlE;AAED,yEAAyE;AACzE,wBAAgB,iBAAiB,IAAI,mBAAmB,EAAE,CAEzD;AAED,6EAA6E;AAC7E,wBAAgB,kBAAkB,IAAI,IAAI,CAEzC"}
+{"version":3,"file":"exec-telemetry.d.ts","sourceRoot":"","sources":["../../src/facets/exec-telemetry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,yDAAyD;AACzD,MAAM,WAAW,mBAAmB;IAClC,uEAAuE;IACvE,OAAO,EAAE,MAAM,CAAC;IAChB,iEAAiE;IACjE,QAAQ,EAAE,MAAM,CAAC;IACjB,6CAA6C;IAC7C,MAAM,EAAE,MAAM,CAAC;IACf,+DAA+D;IAC/D,KAAK,EAAE,MAAM,CAAC;IACd;0EACsE;IACtE,WAAW,EAAE,MAAM,CAAC;IACpB,uEAAuE;IACvE,cAAc,EAAE,MAAM,CAAC;IACvB;;;;;;;;;OASG;IACH,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,EAAE,MAAM,CAAC;IACtB,aAAa,EAAE,MAAM,CAAC;IACtB,sEAAsE;IACtE,SAAS,EAAE,MAAM,CAAC;IAClB;;gEAE4D;IAC5D,UAAU,EAAE,MAAM,CAAC;IACnB,uEAAuE;IACvE,QAAQ,EAAE,OAAO,CAAC;IAClB;;;;;;OAMG;IACH,KAAK,EAAE,MAAM,CAAC;IACd,mEAAmE;IACnE,QAAQ,EAAE,MAAM,CAAC;IACjB,mDAAmD;IACnD,EAAE,EAAE,MAAM,CAAC;CACZ;AAED;;;GAGG;AACH,MAAM,MAAM,YAAY,GAAG,IAAI,CAC7B,mBAAmB,EACnB,QAAQ,GAAG,OAAO,GAAG,gBAAgB,GAAG,aAAa,GAAG,eAAe,GAAG,eAAe,CAC1F,CAAC;AAKF;;;;GAIG;AACH,wBAAgB,iBAAiB,IAAI,OAAO,CAE3C;AAED,qEAAqE;AACrE,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,mBAAmB,GAAG,IAAI,CAIlE;AAED,yEAAyE;AACzE,wBAAgB,iBAAiB,IAAI,mBAAmB,EAAE,CAEzD;AAED,6EAA6E;AAC7E,wBAAgB,kBAAkB,IAAI,IAAI,CAEzC"}