@nimbus-sh/worker 0.6.0 → 0.8.0

package/dist/npm/installer.js

@@ -24,11 +24,11 @@ import { BUNDLER_VERSION } from '@nimbus-sh/core/runtime/esbuild-service.js';
 import { NpmCache } from './cache.js';
 import { computeHoistPlan, } from './resolver.js';
 import { packumentUrl } from './r2-cache.js';
-import { npmAddedLine, npmHttpCacheLine, npmHttpFetchLine, npmTitleLine, } from './npm-log.js';
-import { applySwaps, findRejects, lookupSwap, lookupReject, shouldSkipPackage, shouldWarnSkipTransitive, isOptionalNativeBinding, formatSwapNotice, RegistryRejectError, emitRegistryEvent, } from '../facets/wasm-swap-registry.js';
+import { satisfiesRange, isSemverRange } from './semver.js';
+import { npmAddedLine, npmHttpCacheLine, npmHttpFetchLine, npmTitleLine, } from '@nimbus-sh/core/substrate/lifo/commands/system/npm-log.js';
+import { applySwaps, findRejects, lookupSwap, isOptionalNativeBinding, formatSwapNotice, emitRegistryEvent, } from '../facets/wasm-swap-registry.js';
 import { resolvePackageEntry } from '@nimbus-sh/core/_shared/exports-resolver.js';
 import { encodeWriteBatchStream } from '@nimbus-sh/platform/w7-frame.js';
-import { IsolatePool } from '@nimbus-sh/fabric/isolate-pool.js';
 import { Fanout, IN_DO_THRESHOLD } from '@nimbus-sh/fabric/fanout.js';
 import { TAR_STREAM_PREAMBLE, W7_FRAME_PREAMBLE } from '../loaders/generated-workers.js';
 import { installPackagesInFacet, } from './install-batch-facet.js';
@@ -36,12 +36,10 @@ import { setInstallPhase, recordInstallFacetCounters, recordPreBundleSummary, re
 import { recordCacheStatEvents } from '@nimbus-sh/core/_shared/cache-stats.js';
 import { estimateSupervisorHeap } from '@nimbus-sh/platform/heap-estimate.js';
 import { describeError } from '@nimbus-sh/platform/oom-classify.js';
-import { resolveOnePackumentInFacet, } from './resolve-one-facet.js';
+import { resolveOnePackumentInFacet, parseRegistryRequest, } from './resolve-one-facet.js';
 import { NPM_RESOLVE_PREAMBLE } from '../loaders/npm-resolve-preamble.js';
 import { prebundleOne, buildSliceForSpecifierWithCap, externalsForSpecifier, } from './pre-bundle-facet.js';
-import { PRE_BUNDLE_PREAMBLE } from '../loaders/pre-bundle-preamble.js';
-import { fetchEsbuildWasmBytes } from '../runtime/esbuild-wasm-bytes.js';
-import { CHUNK_SIZE, PRE_BUNDLE_CONCURRENCY, PRE_BUNDLE_SLICE_CAP_BYTES, SUPERVISOR_IN_FLIGHT_ALLOCATION_BUDGET_BYTES, } from '@nimbus-sh/platform/limits.js';
+import { CHUNK_SIZE, PRE_BUNDLE_CONCURRENCY, PRE_BUNDLE_SLICE_CAP_BYTES, } from '@nimbus-sh/platform/limits.js';
 import { acquireSupervisorAllocation } from '@nimbus-sh/platform/heavy-alloc-coord.js';
 import { countPackageFiles, BARREL_PKG_FILE_THRESHOLD, packageNameFromSpecifier } from '@nimbus-sh/core/runtime/barrel-detect.js';
 import { scanNamedImports, namedImportSignature, buildSyntheticEntry, buildScopedSliceForSynthetic, syntheticEntryPath, } from '../runtime/barrel-synthesizer.js';
@@ -53,6 +51,8 @@ export class NpmInstaller {
     vfs;
     cache;
     esbuild;
+    /** The session's esbuild facet pool, shared with the on-demand dev-server path. */
+    bundlePool;
     ctx;
     env;
     onProgress;
@@ -75,6 +75,7 @@ export class NpmInstaller {
         this.vfs = vfs.as(CRED_KERNEL);
         this.cache = new NpmCache(sql);
         this.esbuild = opts?.esbuild ?? null;
+        this.bundlePool = opts?.bundlePool ?? null;
         this.ctx = opts?.ctx;
         this.env = opts?.env;
         this.onProgress = opts?.onProgress;
@@ -93,6 +94,11 @@ export class NpmInstaller {
         const start = Date.now();
         const projDir = projectDir.replace(/^\/+/, '').replace(/\/+$/, '');
         const nmDir = projDir + '/node_modules';
+        // Per-invocation progress wins over whatever the ctor bound — the
+        // installer is shared, the terminal it should speak to is not.
+        const previousProgress = this.onProgress;
+        if (opts?.onProgress !== undefined)
+            this.onProgress = opts.onProgress;
         const log = (msg) => this.onProgress?.(msg);
         this.npmLog = opts?.npmLog ?? (() => { });
         // Reset phase to 'idle' on any exit path so /api/_diag/memory
@@ -105,6 +111,7 @@ export class NpmInstaller {
         finally {
             setInstallPhase('idle');
             this.npmLog = () => { };
+            this.onProgress = previousProgress;
         }
     }
     async _installInner(projDir, nmDir, opts, log, start) {
@@ -118,19 +125,22 @@ export class NpmInstaller {
         this.npmLog('verbose', npmTitleLine(opts?.packages ?? []));
         let phaseStart = Date.now();
         log('Checking lockfile...');
-        const specs = await this.buildSpecs(projDir, opts?.packages, opts?.production);
+        const { specs, devOnly, optionalRoots, advised } = await this.buildSpecs(projDir, opts?.packages, opts?.production);
+        // EBADPLATFORM refusals (os/cpu/libc allowlists on a required
+        // package) fail the install like real npm; every refused name was
+        // already logged as a [skip] line, name them again with the reason.
+        const recordRefusals = (rejected) => {
+            for (const r of rejected) {
+                if (!r.required)
+                    continue;
+                failed.push(r.name);
+                log(`npm ERR! ${r.name}: ${r.reason}`);
+            }
+        };
         if (Object.keys(specs).length === 0) {
             log('No dependencies to install.');
             return { installed, failed, totalFiles: 0, elapsed: Date.now() - start, cachedHits: 0, phases: {} };
         }
-        // W11: framework detection. If the project depends on a framework
-        // (next/astro/nuxt/remix/sveltekit) or generic vite, we exempt
-        // FRAMEWORK_REQUIRED_PACKAGES (vite, ...) from the SKIP_PACKAGES set
-        // so the framework's CLI can `import 'vite'` from node_modules.
-        const frameworkAware = await this.detectFrameworkAware(projDir);
-        if (frameworkAware) {
-            log(`Framework detected — installing framework-required packages (vite, …).`);
-        }
         const lockfile = this.cache.readLockfile(projDir);
         let resolved;
         let usedLockfile = false;
@@ -156,9 +166,13 @@ export class NpmInstaller {
             phaseStart = Date.now();
             setInstallPhase('resolve');
             log(`Resolving ${Object.keys(specs).length} dependencies (path: fanout, fetch: ${this.fetchFn ? 'facet-proxy' : 'global'})...`);
-            const tree = await this.resolveTreeViaFanout(specs, log, { frameworkAware });
+            const tree = await this.resolveTreeViaFanout(specs, log, { optionalRoots, devOnly, advised });
             resolved = tree.resolved;
             phases['resolve'] = Date.now() - phaseStart;
+            // Transitive platform-gate refusals. Required ones join `failed`
+            // with their reason; optional-edge ones stay out of the outcome
+            // lists. Either way the rest of the tree resolved and installs.
+            recordRefusals(tree.rejected);
             // A dependency the walk could not resolve is missing from the
             // install and from every subtree beneath it. Name it and its
             // reason, and carry it into `failed` so the command exits non-zero.
@@ -168,8 +182,9 @@ export class NpmInstaller {
             }
             if (resolved.size === 0) {
                 log('No packages resolved.');
+                const refused = new Set(tree.rejected.map((r) => r.name));
                 for (const name of Object.keys(specs)) {
-                    if (!tree.unresolved.has(name))
+                    if (!tree.unresolved.has(name) && !refused.has(name))
                         failed.push(name);
                 }
                 return {
@@ -306,7 +321,7 @@ export class NpmInstaller {
             //   the npm command-handler returns to the shell, the shell
             //   prints its prompt, and THEN the orphan promise's safeProgress
             //   fires — visually corrupting the freshly-rendered prompt
-            //   ("user@nimbus:~/app$ [npm] Pre-bundle complete: ...").
+            //   ("user@nimbus:~/example-app$ [npm] Pre-bundle complete: ...").
             //
             // Fix:
             //   Suppress writes to ctx.stdout once install() has returned.
@@ -433,7 +448,13 @@ export class NpmInstaller {
      *   - X.5-G G1 optional-native silent-skip,
      *   - X.5-drizzle best-effort tagging on optional-peer subtrees,
      *   - W6 swap / warn / reject decisions (top-level enforcement; the
-     *     per-package task ALSO checks these for transitive correctness),
+     *     per-package task ALSO checks these for transitive correctness).
+     *     A package is required iff it is reachable from a required root
+     *     (every selected spec except optionalDependencies roots) through
+     *     a chain of required edges (`dependencies` minus the package's
+     *     own optionalDependencies, required peers); W6 refusals are
+     *     classified against the closure computed over the resolved
+     *     graph at end of walk.
      *   - cache flushing (one batched putRegistryEntries at end).
      *
      * The per-package task (resolveOnePackumentInFacet) owns ONLY the
@@ -444,7 +465,19 @@ export class NpmInstaller {
      */
     async resolveTreeViaFanout(specs, log, opts = {}) {
         const t0 = Date.now();
-        const frameworkAware = !!opts.frameworkAware;
+        const optionalRoots = opts.optionalRoots ?? new Set();
+        const devOnly = opts.devOnly ?? new Set();
+        // Policy advisories already announced — one `note:` line per name
+        // per install, shared with applyW6Registry which runs first.
+        const advised = opts.advised ?? new Set();
+        const noteAdvisory = (ev) => {
+            if (advised.has(ev.from))
+                return;
+            advised.add(ev.from);
+            const hint = ev.suggest ? ` … try: ${ev.suggest}` : '';
+            const marker = devOnly.has(ev.from) ? ' (declared in devDependencies)' : '';
+            log(`[npm] note: ${ev.from} has no Workers-compatible build${marker}: ${ev.reason}${hint}`);
+        };
         const __f2Diag = (globalThis.process?.env?.NIMBUS_DIAG_INSTALL_PIPELINE === '1');
         // Per-walk state — supervisor side.
         const resolved = new Map();
@@ -452,6 +485,10 @@ export class NpmInstaller {
         // A name lands here at most once: the frontier marks it `seen` before
         // dispatch, so no later parent re-enqueues it.
         const unresolved = new Map();
+        // EBADPLATFORM refusals (os/cpu/libc allowlists), in walk order.
+        // Announced as `[skip]` lines at record time; required-vs-optional is
+        // classified at end of walk, when every required edge has been seen.
+        const refusals = new Map();
         const seen = new Set();
         const topLevelNames = new Set(Object.keys(specs));
         const optionalNames = new Set(); // X.5-G G1
@@ -554,9 +591,7 @@ export class NpmInstaller {
                     name,
                     range,
                     cachedEntries,
-                    topLevel: topLevelNames.has(name),
                     isOptional: optionalNames.has(name),
-                    frameworkAware,
                     fetchTimeoutMs: 15_000,
                     retries: 3,
                 };
@@ -587,7 +622,8 @@ export class NpmInstaller {
                     unresolved.set(taskName, `resolver fanout returned no result at layer ${layerN}`);
                     continue;
                 }
-                // Forward messages + events.
+                // Forward messages + events. `advisory` events are the policy's
+                // "cannot run here" list — one note per name per install.
                 for (const m of res.messages)
                     log(m);
                 for (const ev of res.events) {
@@ -595,6 +631,8 @@ export class NpmInstaller {
                         emitRegistryEvent(ev);
                     }
                     catch { /* swallow sink errors */ }
+                    if (ev.type === 'advisory')
+                        noteAdvisory(ev);
                 }
                 // Accumulate cache writes for end-of-walk flush.
                 for (const cw of res.cacheWrites)
@@ -617,7 +655,12 @@ export class NpmInstaller {
                     r2Losses++;
                 if (res.packumentBytesDecoded > 0)
                     totalPackumentsDecoded++;
-                // W6 reject error handling.
+                // w6-reject: an os/cpu/libc platform-gate refusal — npm's
+                // EBADPLATFORM. Announced as a [skip] line now and classified
+                // required-vs-optional at end of walk, when the required-edge
+                // closure is final; best-effort optional-peer subtrees still
+                // skip silently. Table rejects are advisories handled above and
+                // never reach this branch.
                 if (res.error && res.error.type === 'w6-reject') {
                     if (bestEffortNames.has(taskName)) {
                         // X.5-drizzle: silent-skip inside best-effort optional-peer
@@ -627,14 +670,11 @@ export class NpmInstaller {
                         emitRegistryEvent({ type: 'transitive-skip', from: taskName, reason });
                         continue;
                     }
-                    // Real reject: throw RegistryRejectError to abort install.
-                    const rejectEntry = {
-                        from: res.error.from,
-                        reason: res.error.reason,
-                        suggest: res.error.suggest,
-                        transitive: 'fail',
-                    };
-                    throw new RegistryRejectError([rejectEntry]);
+                    refusals.set(taskName, res.error.reason);
+                    const hint = res.error.suggest ? ` … try: ${res.error.suggest}` : '';
+                    log(`[resolve-fanout] [skip] ${taskName} — ${res.error.reason}${hint}`);
+                    emitRegistryEvent({ type: 'transitive-skip', from: taskName, reason: res.error.reason });
+                    continue;
                 }
                 // Resolution failure. Optional (X.5-G G1) and best-effort
                 // optional-peer (X.5-drizzle) edges are allowed to disappear;
@@ -710,22 +750,15 @@ export class NpmInstaller {
                     }
                 }
                 // X.5-F R2.5 + X.5-J: optional peers when THIS pkg is the
-                // user's top-level. Filter through the policy reject list.
+                // user's top-level. They resolve best-effort; a policy-listed
+                // name that resolves installs with an advisory like any
+                // package, and one that does not is skipped quietly.
                 if (topLevelNames.has(pkg.name)) {
                     const allPeers = pkg.__allPeerDependencies;
                     if (allPeers) {
                         for (const [peerName, peerRange] of Object.entries(allPeers)) {
                             if (resolved.has(peerName) || seen.has(peerName))
                                 continue;
-                            const peerFail = lookupReject(peerName);
-                            const peerWarn = shouldWarnSkipTransitive(peerName);
-                            const peerReject = peerFail || peerWarn;
-                            if (peerReject) {
-                                const reason = `optional peer in REJECT_INSTALL: ${peerName} — ${peerReject.reason}`;
-                                log(`[resolve-fanout] [skip] ${peerName} — ${reason}`);
-                                emitRegistryEvent({ type: 'transitive-skip', from: peerName, reason });
-                                continue;
-                            }
                             topLevelNames.add(peerName);
                             bestEffortNames.add(peerName);
                             queue.push([peerName, peerRange]);
@@ -735,6 +768,35 @@ export class NpmInstaller {
             }
             layerN++;
         }
+        // G2: a refused package is required iff it is reachable from a
+        // required root — every selected spec except optionalDependencies
+        // roots — through required edges (`dependencies` minus the package's
+        // own optionalDependencies, which npm overrides as optional, and
+        // required peers). Computed now over the resolved graph: the walk
+        // sees names in BFS order, so incremental propagation would freeze a
+        // dev/optional first sighting before a later required edge lands.
+        const requiredNames = new Set();
+        const pendingRequired = Object.keys(specs).filter((name) => !optionalRoots.has(name));
+        for (let i = 0; i < pendingRequired.length; i++) {
+            const name = pendingRequired[i];
+            if (requiredNames.has(name))
+                continue;
+            requiredNames.add(name);
+            const pkg = resolved.get(name);
+            if (!pkg)
+                continue;
+            const optional = pkg.optionalDependencies ?? {};
+            for (const dep of Object.keys(pkg.dependencies)) {
+                if (!Object.hasOwn(optional, dep))
+                    pendingRequired.push(dep);
+            }
+            for (const peer of Object.keys(pkg.peerDependencies ?? {}))
+                pendingRequired.push(peer);
+        }
+        const rejected = [];
+        for (const [name, reason] of refusals) {
+            rejected.push({ name, reason, required: requiredNames.has(name) });
+        }
         // End-of-walk: flush all cache writes in one RPC-equivalent call
         // (this.cache is a SQLite handle; one putRegistryEntries call =
         // O(N) prepared statements within a single DO event-loop turn,
@@ -767,7 +829,7 @@ export class NpmInstaller {
             `, dispatch barriers=${dispatchBarriers}, ` +
             `elapsed=${((Date.now() - t0) / 1000).toFixed(1)}s` +
             (unresolved.size > 0 ? `, unresolved=${unresolved.size}` : ''));
-        return { resolved, unresolved };
+        return { resolved, unresolved, rejected };
     }
     /**
      * Batch install via two-tier fan-out (Fanout).
@@ -985,102 +1047,71 @@ export class NpmInstaller {
         }
     }
     // ── Spec building ─────────────────────────────────────────────────────
-    /**
-     * Build the dependency specs from package.json + explicit packages.
-     */
-    /**
-     * W11: framework detection at install time. Reads package.json from the
-     * project root and runs detectFramework() against its deps + the basenames
-     * we can see in node_modules-adjacent siblings.
-     *
-     * Returns true if the project is detected as one of {next, astro, nuxt,
-     * remix, sveltekit, vite, wrangler}. False for 'unknown'.
-     */
-    async detectFrameworkAware(projDir) {
-        try {
-            const pkgPath = projDir + '/package.json';
-            if (!this.vfs.exists(pkgPath))
-                return false;
-            const pkg = JSON.parse(this.vfs.readFileString(pkgPath));
-            // Lazy-load the detector to avoid a hard dep cycle.
-            const { detectFramework } = await import('@nimbus-sh/core/runtime/framework-detect.js');
-            // Snapshot root files. Best-effort — if readdir throws we proceed
-            // with an empty set (still detects via deps for most frameworks).
-            const files = new Set();
-            try {
-                for (const e of this.vfs.readdir(projDir))
-                    files.add(e.name);
-            }
-            catch { /* tolerate */ }
-            // Optional file contents — read only the vite.config.* if present
-            // (used by the Remix gate).
-            const fileContents = {};
-            for (const c of ['vite.config.ts', 'vite.config.js', 'vite.config.mjs']) {
-                if (files.has(c)) {
-                    try {
-                        fileContents[c] = this.vfs.readFileString(projDir + '/' + c);
-                    }
-                    catch { }
-                }
-            }
-            const result = detectFramework({
-                pkg: { dependencies: pkg.dependencies, devDependencies: pkg.devDependencies, scripts: pkg.scripts },
-                files,
-                fileContents,
-            });
-            return result.framework !== 'unknown';
-        }
-        catch {
-            return false;
-        }
-    }
     async buildSpecs(projDir, explicitPackages, production) {
         const specs = {};
+        // Which names only a devDependency asked for — diagnostics only, so an
+        // advisory can say whether anything this project RUNS actually needs
+        // the package. A devDependency is still a required root.
+        const devOnly = new Set();
+        // package.json optionalDependencies: the only roots the required
+        // closure does not cover — npm installs them best-effort.
+        const optionalRoots = new Set();
+        // Names the top-level pass already announced — the walk dedupes its
+        // own advisories against it.
+        const advised = new Set();
         if (explicitPackages && explicitPackages.length > 0) {
             // Explicit packages: npm install react react-dom@18.2.0
             for (const pkg of explicitPackages) {
                 const parsed = parseExplicitPackageSpec(pkg);
                 specs[parsed.name] = parsed.range;
             }
-            return this.applyW6Registry(specs);
+            const applied = this.applyW6Registry(specs, new Set(), { advised });
+            return { specs: applied.specs, devOnly, optionalRoots, advised };
         }
         // Read from package.json
         const pkgJsonPath = projDir + '/package.json';
         if (!this.vfs.exists(pkgJsonPath))
-            return specs;
-        // Which names only a devDependency asked for, so a reject can say whether
-        // anything this project RUNS actually needs the package it refused.
-        const devOnly = new Set();
+            return { specs, devOnly, optionalRoots, advised };
         try {
             const pkgJson = JSON.parse(this.vfs.readFileString(pkgJsonPath));
-            // Always include dependencies
+            // Every declared dependency is a spec. What cannot run here is
+            // named by the advisory pass below; nothing a project declares is
+            // quietly left out of node_modules.
             for (const [name, range] of Object.entries(pkgJson.dependencies || {})) {
-                if (!shouldSkipPackage(name)) {
-                    specs[name] = range;
-                }
+                specs[name] = range;
             }
-            // Include devDeps unless production mode, skipping build-only
             for (const [name, range] of Object.entries(pkgJson.devDependencies || {})) {
-                if (shouldSkipPackage(name) || name in specs)
-                    continue;
-                if (production)
+                if (name in specs || production)
                     continue;
                 specs[name] = range;
                 devOnly.add(name);
             }
+            // npm semantics: an optionalDependencies entry overrides the same
+            // name in dependencies — it is a best-effort root, not required.
+            for (const [name, range] of Object.entries(pkgJson.optionalDependencies || {})) {
+                specs[name] = range;
+                optionalRoots.add(name);
+            }
         }
         catch { /* corrupt package.json */ }
-        return this.applyW6Registry(specs, devOnly);
+        const applied = this.applyW6Registry(specs, optionalRoots, { declared: true, devOnly, advised });
+        return { specs: applied.specs, devOnly, optionalRoots, advised };
     }
     /**
      * W6: apply the PACKAGE_ABI_POLICY swap rewrites and reject deny list
-     * to a top-level spec map. Emits `[swap]` notices via onProgress; throws
-     * a multi-line error on any reject (with `transitive='warn'` rejects
-     * also failing at top level — they only soften at depth>0).
+     * to a top-level spec map. Emits `[swap]` notices via onProgress.
+     *
+     * G2: rejects are advisories — a listed package stays in the spec map
+     * and installs like any other (npm parity: it cannot run here, but
+     * install is the wrong place to say so). Each gets one `[npm] note:`
+     * line per install and an `advisory` registry event; the require-side
+     * refusal carries the reason when the artifact is invoked.
+     * `advised` dedupes across the top-level pass and the walk (the
+     * package still resolves and can surface transitively).
      *
      * Idempotent: running on already-swapped specs is a no-op.
      */
-    applyW6Registry(specs, devOnly = new Set()) {
+    applyW6Registry(specs, optionalRoots = new Set(), options = {}) {
         const { specs: swapped, swaps } = applySwaps(specs);
         for (const s of swaps) {
             // onProgress is unguarded everywhere else in this file (rg the
@@ -1090,49 +1121,62 @@ export class NpmInstaller {
             // W6.5: telemetry — fire-and-forget; sink swallows its own errors.
             emitRegistryEvent({ type: 'swap', from: s.from, to: s.to, ctx: 'top' });
         }
-        const rejects = findRejects(swapped, 'top');
-        if (rejects.length > 0) {
-            // W6.5: emit one reject event per offending package BEFORE throwing,
-            // so the telemetry sink sees them even if the install aborts.
-            for (const r of rejects) {
-                emitRegistryEvent({
-                    type: 'reject',
-                    from: r.from,
-                    reason: r.reason,
-                    suggest: r.suggest,
-                    ctx: 'top',
-                });
-            }
-            throw new RegistryRejectError(rejects, devOnly);
+        for (const r of findRejects(swapped, 'top')) {
+            emitRegistryEvent({ type: 'advisory', from: r.from, reason: r.reason, suggest: r.suggest, ctx: 'top' });
+            if (options.advised?.has(r.from))
+                continue;
+            options.advised?.add(r.from);
+            const hint = r.suggest ? ` … try: ${r.suggest}` : '';
+            const marker = options.devOnly?.has(r.from) ? ' (declared in devDependencies)' : '';
+            this.onProgress?.(`[npm] note: ${r.from} has no Workers-compatible build${marker}: ${r.reason}${hint}`);
         }
-        return swapped;
+        return { specs: swapped };
     }
     // ── Lockfile ──────────────────────────────────────────────────────────
     /**
      * Check if a lockfile is still valid against current package.json specs.
      */
     isLockfileValid(lockfile, specs) {
-        // Every spec must be in the lockfile
-        for (const name of Object.keys(specs)) {
-            if (shouldSkipPackage(name))
+        // Every spec must be in the lockfile at a version that still
+        // satisfies the declared range — a package.json edit must never be
+        // answered by yesterday's pin.
+        for (const [name, range] of Object.entries(specs)) {
+            const entry = lockfile.get(name);
+            if (!entry)
+                return false;
+            // An npm: alias answers the INNER range — the same parser the
+            // resolver facet uses for alias specs turns `vliw: npm:react@^19`
+            // into range `^19` checked against the pin under `vliw`. A spec
+            // that is not a semver range at all (git:, github:, URL, file:)
+            // answers presence-only: the pin's record is the lockfile's whole
+            // truth for it.
+            const req = parseRegistryRequest(name, range);
+            if (!isSemverRange(req.range))
                 continue;
-            if (!lockfile.has(name))
+            if (!satisfiesRange(entry.resolvedVer, req.range))
                 return false;
         }
-        // X.5-F R2: every locked package's REQUIRED peerDependencies must
-        // also be in the lockfile. Lockfiles built before X.5-F lack peer
-        // entries; we invalidate them so the next install re-resolves and
-        // picks up peers (e.g. radix-react-dialog needs react+react-dom in
-        // the tree, ts-jest needs typescript). The peer info comes from
-        // the registry cache — if the cache miss happens too, we play it
-        // safe and invalidate (forcing a fresh resolve which is correct).
+        // Every locked package's REQUIRED edges — `dependencies` minus the
+        // names its optionalDependencies override, plus required peers —
+        // must also be in the lockfile. Lockfiles built before X.5-F lack
+        // peer entries and lockfiles written after a required refusal lack
+        // the refused name's siblings' targets; invalidating either forces
+        // the next install to re-resolve and re-report the refusal instead
+        // of printing Done! over a tree that is missing packages. The edge
+        // info comes from the registry cache — if the cache miss happens
+        // too, we play it safe and invalidate (a fresh resolve repopulates
+        // it and is always correct).
         for (const [, entry] of lockfile) {
             const cached = this.cache.getRegistryEntry(entry.name, entry.resolvedVer);
-            if (!cached) {
-                // Registry cache miss for this locked entry — can't verify
-                // peers. Invalidate to be safe (next install will repopulate
-                // the registry cache while resolving).
+            if (!cached)
                 return false;
+            const optional = safeJsonParse(cached.optionalDepsJson || '{}', {});
+            const deps = safeJsonParse(cached.depsJson || '{}', {});
+            for (const depName of Object.keys(deps)) {
+                if (Object.hasOwn(optional, depName))
+                    continue;
+                if (!lockfile.has(depName))
+                    return false;
             }
             const peers = safeJsonParse(cached.peerDepsJson || '{}', {});
             for (const peerName of Object.keys(peers)) {
@@ -1313,9 +1357,9 @@ export class NpmInstaller {
         //
         // We gate on this.esbuild presence purely as a feature flag: a caller
         // that constructs the installer without esbuild (e.g. minimal
-        // headless test) opts out of pre-bundling entirely. ctx and env must
-        // also be present because the facet pool needs them.
-        if (!this.esbuild || !this.ctx || !this.env)
+        // headless test) opts out of pre-bundling entirely. The session's
+        // bundle pool must also be present because the facets run in it.
+        if (!this.esbuild || !this.bundlePool)
             return;
         const usedSpecifiers = this.scanBareImports(projDir);
         // Vite plugins / postcss plugins / build-time tools NEVER ship to the
@@ -1509,12 +1553,12 @@ export class NpmInstaller {
         // esbuild's WASM linear memory is per-FACET (~30–80 MiB) and lives
         // outside the supervisor. Per-slot try/catch handles failures —
         // /preview/@modules/ on-demand bundling recovers.
-        // Fetch the esbuild-wasm bytes from the static-assets layer.
-        // The supervisor briefly holds the 12 MiB ArrayBuffer between this
-        // line and the LOADER hand-off below; after pool construction
-        // returns, the only reference is inside workerd's loader cache
-        // (where it should live). No supervisor-side caching — see
-        // src/esbuild-wasm-bytes.ts for the full architectural rationale.
+        // The esbuild-wasm bytes ride in the session's shared bundle pool
+        // (facets/esbuild-bundle-pool.ts), constructed once per session and
+        // disposed with the installer and dev server — not per pre-bundle
+        // phase — so the supervisor retains one copy, leased once from the
+        // shared allocation budget. See src/esbuild-wasm-bytes.ts for why
+        // the bytes are never cached supervisor-side beyond that.
         //
         // Bytes are shipped into each facet via IsolatePool's
         // `wasmModules` option which workerd registers in the LOADER
@@ -1540,7 +1584,7 @@ export class NpmInstaller {
         // slots' settled work, and surface in the supervisor as an
         // unhandled rejection. Swallow with a console.error so the
         // pre-bundle phase keeps running. Same pattern is used in the
-        // pool dispose finally block below.
+        // summary finally block below.
         const safeProgress = (msg) => {
             try {
                 this.onProgress?.(msg);
@@ -1552,42 +1596,18 @@ export class NpmInstaller {
                 catch { }
             }
         };
+        // Acquired BEFORE any per-slice lease below: first construction
+        // reserves the full supervisor budget while the wasm bytes are
+        // fetched, so a slice lease taken first would wait on itself.
         let pool;
-        let retainedWasmRelease = null;
-        const setupAllocation = await acquireSupervisorAllocation(SUPERVISOR_IN_FLIGHT_ALLOCATION_BUDGET_BYTES);
         try {
-            // No fallback: a missing wasm asset is a deploy bug. Surface loudly via
-            // the thrown fetch error so this background phase aborts cleanly.
-            const wasmBytes = await fetchEsbuildWasmBytes(this.env);
-            const maxRetainedWasmBytes = SUPERVISOR_IN_FLIGHT_ALLOCATION_BUDGET_BYTES - PRE_BUNDLE_SLICE_CAP_BYTES;
-            if (wasmBytes.byteLength > maxRetainedWasmBytes) {
-                throw new RangeError(`pre-bundle 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);
-            try {
-                pool = new IsolatePool(this.env, this.ctx, {
-                    concurrency: PRE_BUNDLE_CONCURRENCY,
-                    timeoutMs: 60_000,
-                    retries: 0,
-                    tag: 'pre-bundle',
-                    preamble: PRE_BUNDLE_PREAMBLE,
-                    wasmModules: { 'esbuild.wasm': wasmBytes },
-                });
-                retainedWasmRelease = setupAllocation.release;
-            }
-            catch (e) {
-                // Pool construction failures remain best-effort pre-bundle failures,
-                // not npm install failures.
-                safeProgress(`Pre-bundle skipped: failed to construct facet pool: ${e?.message || e}`);
-                return;
-            }
+            pool = await this.bundlePool.acquire();
         }
-        finally {
-            if (!retainedWasmRelease)
-                setupAllocation.release();
+        catch (e) {
+            // Pool construction failures remain best-effort pre-bundle failures,
+            // not npm install failures.
+            safeProgress(`Pre-bundle skipped: failed to construct facet pool: ${e?.message || e}`);
+            return;
         }
         const queue = pending.slice(); // copy; will shift
         let okCount = 0;
@@ -1777,10 +1797,11 @@ export class NpmInstaller {
             // failure mode that can throw inside runSlot is caught above
             // (slice walk, externals, pool.submit, putEsmBundle) — but a
             // future regression that adds an unguarded throw to runSlot
-            // would bubble out here. The outer try/finally guarantees
-            // pool.dispose() runs and the diag counters get updated for
-            // whatever partial run completed; the catch below additionally
-            // logs so the failure mode is visible in supervisor logs.
+            // would bubble out here. The outer try/finally guarantees the
+            // diag counters get updated for whatever partial run completed;
+            // the pool itself belongs to the session and outlives this phase.
+            // The catch below additionally logs so the failure mode is visible
+            // in supervisor logs.
             await Promise.all(Array.from({ length: PRE_BUNDLE_CONCURRENCY }, (_, i) => runSlot(i)));
         }
         catch (e) {
@@ -1822,11 +1843,6 @@ export class NpmInstaller {
                 }
                 catch { }
             }
-            try {
-                pool.dispose();
-            }
-            catch { /* best-effort */ }
-            retainedWasmRelease?.();
         }
     }
     /**