@nimbus-sh/worker 0.9.0 → 0.11.0

package/dist/npm/installer.js

@@ -1,5 +1,5 @@
 /**
- * npm-installer.ts — Unified npm installer for Nimbus.
+ * npm/installer.ts — Unified npm installer for Nimbus.
  *
  * Designed for bun/pnpm-level performance on Cloudflare DO + SQLite.
  *
@@ -22,11 +22,13 @@
 import { CRED_KERNEL } from '@nimbus-sh/core/runtime/os-contracts.js';
 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 { computeHoistPlan, hoistPlacements, } from './resolver.js';
+import { nestedPlacement, visiblePlacements } from './placement.js';
+import { packageLockMismatches, parsePackageLock, stringList, stringRecord } from './package-lock.js';
+import { npmRegistryOrigin, packumentUrl } from './r2-cache.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 { applySwaps, findRejects, lookupSwap, lookupReject, isOptionalNativeBinding, lookupStagedArtifact, applyStagedArtifact, policyNativePlatformReject, PACKAGE_ABI_POLICY, 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 { Fanout, IN_DO_THRESHOLD } from '@nimbus-sh/fabric/fanout.js';
@@ -115,6 +117,7 @@ export class NpmInstaller {
         }
     }
     async _installInner(projDir, nmDir, opts, log, start) {
+        const registry = npmRegistryOrigin(opts?.registry);
         const phases = {};
         const installed = [];
         const failed = [];
@@ -125,7 +128,10 @@ export class NpmInstaller {
         this.npmLog('verbose', npmTitleLine(opts?.packages ?? []));
         let phaseStart = Date.now();
         log('Checking lockfile...');
-        const { specs, devOnly, optionalRoots, advised } = await this.buildSpecs(projDir, opts?.packages, opts?.production);
+        // npm ci takes its roots from the lock, not from package.json specs.
+        const { specs, devOnly, optionalRoots, advised } = opts?.fromLockfile
+            ? { specs: {}, devOnly: new Set(), optionalRoots: new Set(), advised: new Set() }
+            : 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.
@@ -137,16 +143,30 @@ export class NpmInstaller {
                 log(`npm ERR! ${r.name}: ${r.reason}`);
             }
         };
-        if (Object.keys(specs).length === 0) {
+        const packageLock = opts?.fromLockfile
+            ? await this.treeFromPackageLock(projDir, opts.production === true, log, registry)
+            : null;
+        if (packageLock === null && Object.keys(specs).length === 0) {
             log('No dependencies to install.');
             return { installed, failed, totalFiles: 0, elapsed: Date.now() - start, cachedHits: 0, phases: {} };
         }
         const lockfile = this.cache.readLockfile(projDir);
         let resolved;
+        let nested;
         let usedLockfile = false;
-        if (lockfile && !opts?.packages && this.isLockfileValid(lockfile, specs)) {
+        if (packageLock !== null) {
+            ({ resolved, nested } = packageLock);
+            recordRefusals(packageLock.rejected);
+            for (const [name, reason] of packageLock.unresolved) {
+                failed.push(name);
+                log(`npm ERR! could not resolve ${name}: ${reason}`);
+            }
+            log(`Lockfile ${packageLock.lockName}: ${resolved.size + nested.size} packages to place.`);
+            phases['lock-check'] = Date.now() - phaseStart;
+        }
+        else if (lockfile && !opts?.packages && this.isLockfileValid(lockfile, specs)) {
             log(`Lockfile valid (${lockfile.size} packages). Skipping resolution.`);
-            resolved = this.lockfileToResolved(lockfile);
+            ({ resolved, nested } = this.lockfileToResolved(lockfile));
             usedLockfile = true;
             phases['lock-check'] = Date.now() - phaseStart;
         }
@@ -166,8 +186,9 @@ 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, { optionalRoots, devOnly, advised });
+            const tree = await this.resolveTreeViaFanout(specs, log, { optionalRoots, devOnly, advised, registry });
             resolved = tree.resolved;
+            nested = tree.nested;
             phases['resolve'] = Date.now() - phaseStart;
             // Transitive platform-gate refusals. Required ones join `failed`
             // with their reason; optional-edge ones stay out of the outcome
@@ -197,13 +218,15 @@ export class NpmInstaller {
         // ── Phase 2: Hoist ────────────────────────────────────────────────
         phaseStart = Date.now();
         setInstallPhase('hoist');
-        const hoistPlan = computeHoistPlan(resolved);
+        const hoistPlan = computeHoistPlan(resolved, nested);
         phases['hoist'] = Date.now() - phaseStart;
         // ── Phase 3: Diff (cache check) ─────────────────────────────────
+        // Per placement: a nested copy is checked at its own directory.
         phaseStart = Date.now();
         setInstallPhase('diff');
         const toFetch = [];
-        for (const [, pkg] of resolved) {
+        for (const target of hoistPlacements(hoistPlan)) {
+            const { pkg } = target;
             if (!pkg.tarballUrl) {
                 // Resolved metadata with no tarball cannot be installed. Silently
                 // dropping it here left the package absent from node_modules and
@@ -213,7 +236,7 @@ export class NpmInstaller {
                 continue;
             }
             // Check if already installed at the correct path
-            const pkgJsonPath = nmDir + '/' + pkg.name + '/package.json';
+            const pkgJsonPath = nmDir + '/' + target.placement + '/package.json';
             if (this.vfs.exists(pkgJsonPath)) {
                 try {
                     const existing = JSON.parse(this.vfs.readFileString(pkgJsonPath));
@@ -229,7 +252,7 @@ export class NpmInstaller {
             // Not present in the VFS at the right version — fetch it. The batch
             // facet consults the shared L2 (caches.default) + L3 (R2) tarball
             // tiers itself, so a cross-DO warm cache still lands here.
-            toFetch.push(pkg);
+            toFetch.push(target);
         }
         phases['diff'] = Date.now() - phaseStart;
         log(`To fetch: ${toFetch.length}, already installed: ${cachedHits}`);
@@ -257,7 +280,7 @@ export class NpmInstaller {
         const commitsBefore = this.storageCommitCount();
         if (toFetch.length > 0) {
             log(`Fetching ${toFetch.length} packages... (path: batch-facet)`);
-            const batchResult = await this.fetchViaBatchFacet(toFetch, hoistPlan, nmDir, opts?.pid);
+            const batchResult = await this.fetchViaBatchFacet(toFetch, nmDir, opts?.pid);
             totalFiles += batchResult.filesWritten;
             for (const name of batchResult.installed)
                 installed.push(name);
@@ -273,7 +296,7 @@ export class NpmInstaller {
         phases['link-bins'] = Date.now() - phaseStart;
         // ── Write lockfile ──────────────────────────────────────────────
         if (!usedLockfile || opts?.packages) {
-            this.writeLockfile(projDir, resolved, hoistPlan, nmDir);
+            this.writeLockfile(projDir, hoistPlan, nmDir);
         }
         // ── Update package.json if explicit packages were added ─────────
         if (opts?.packages && opts.packages.length > 0) {
@@ -400,7 +423,8 @@ export class NpmInstaller {
                 `${failed.length} missing: ${failed.join(', ')}`);
         }
         else {
-            log(`Done! ${installed.length} packages, ${totalFiles} files in ${(elapsed / 1000).toFixed(1)}s`);
+            const nestedNote = hoistPlan.nested.size > 0 ? ` (${hoistPlan.nested.size} nested)` : '';
+            log(`Done! ${installed.length} packages${nestedNote}, ${totalFiles} files in ${(elapsed / 1000).toFixed(1)}s`);
             // npm's own summary line, unstyled: the styled one the command site
             // prints carries a colour prefix that no log parser matches. Carried
             // at `http` — the level from which this stream is machine-readable —
@@ -442,8 +466,13 @@ export class NpmInstaller {
      *   width <  IN_DO_THRESHOLD (5)  → in-DO fanout in-DO loader-pool
      *   width >= IN_DO_THRESHOLD       → peer-DO fanout peer-DO (sibling NimbusSession DOs)
      *
+     * Resolution is per edge, not per name: the first version of a name goes
+     * to root; a later edge the nearest visible placement does not satisfy
+     * nests a copy under its dependent, never higher (placement.ts; live case
+     * in tests/unit/npm-install-nested-conflict.mjs).
+     *
      * The supervisor still owns:
-     *   - cycle detection (`seen`),
+     *   - placement (`placed` / `pending` / `settled`, by placement path),
      *   - X.5-F top-level / required-peer policy,
      *   - X.5-G G1 optional-native silent-skip,
      *   - X.5-drizzle best-effort tagging on optional-peer subtrees,
@@ -465,6 +494,7 @@ export class NpmInstaller {
      */
     async resolveTreeViaFanout(specs, log, opts = {}) {
         const t0 = Date.now();
+        const registry = npmRegistryOrigin(opts.registry);
         const optionalRoots = opts.optionalRoots ?? new Set();
         const devOnly = opts.devOnly ?? new Set();
         // Policy advisories already announced — one `note:` line per name
@@ -479,21 +509,27 @@ export class NpmInstaller {
             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.
+        // Per-walk state — supervisor side. Root by name, nested by placement
+        // path, `placed` is both; `pending` is dispatched and unanswered,
+        // `settled` answered whatever the answer was.
         const resolved = new Map();
+        const nested = new Map();
+        const placed = new Map();
+        const pending = new Set();
+        const settled = new Set();
         // Dependencies the walk asked for and could not resolve, name → reason.
-        // 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
         const bestEffortNames = new Set(); // X.5-drizzle
-        let queue = Object.entries(specs);
+        // A cycle with mutually incompatible ranges has no finite layout; the
+        // edge is refused at this depth rather than nested without end.
+        const MAX_NEST_DEPTH = 16;
+        let queue = Object.entries(specs).map(([name, range]) => ({ name, range, from: '', kind: 'dep' }));
         const cacheWritesPending = [];
         let totalPackumentBytes = 0;
         let totalPackumentsDecoded = 0;
@@ -544,21 +580,53 @@ export class NpmInstaller {
         // Frontier loop. Each iteration = ONE BFS layer dispatched as ONE
         // submitMany batch.
         while (queue.length > 0) {
-            // Dedupe + filter the layer up front. The task body also filters
-            // (defensive), but doing it here avoids dispatching wasted RPC
-            // for already-seen names.
+            // Decide each edge against what Node's walk from its dependent sees.
+            // One whose nearest visible placement is in flight waits a layer.
+            // A copy nested under a package is decided here in the layer after
+            // that package resolves, before anything beneath it can resolve, so
+            // no descendant is ever decided against a copy it will later shadow.
             const layer = [];
-            const layerSeenLocal = new Set();
-            for (const [name, range] of queue) {
-                if (seen.has(name) || layerSeenLocal.has(name))
+            const deferred = [];
+            for (const edge of queue) {
+                const req = parseRegistryRequest(edge.name, edge.range);
+                let target = edge.name;
+                let decided = false;
+                for (const candidate of visiblePlacements(edge.from, edge.name)) {
+                    if (pending.has(candidate)) {
+                        deferred.push(edge);
+                        decided = true;
+                        break;
+                    }
+                    const pkg = placed.get(candidate);
+                    if (!pkg)
+                        continue; // never asked or failed: the walk goes on upward
+                    if (!isSemverRange(req.range) || satisfiesRange(pkg.version, req.range)) {
+                        decided = true; // reuse
+                    }
+                    else if (edge.kind === 'peer') {
+                        decided = true; // reuse anyway, and say so the way npm does
+                        log(`  [warn] peer ${edge.name}@${edge.range} from ${edge.from} is met by ${pkg.name}@${pkg.version} (${candidate})`);
+                    }
+                    else {
+                        target = nestedPlacement(edge.from, edge.name);
+                    }
+                    break;
+                }
+                if (decided)
+                    continue;
+                if (settled.has(target))
+                    continue; // failed once, on record under the name
+                if (target.split('/node_modules/').length - 1 > MAX_NEST_DEPTH) {
+                    unresolved.set(edge.name, `${edge.name}@${edge.range} from ${edge.from} would nest deeper than ${MAX_NEST_DEPTH} levels (cycle with incompatible ranges)`);
+                    settled.add(target);
                     continue;
-                layerSeenLocal.add(name);
-                seen.add(name);
-                layer.push([name, range]);
+                }
+                pending.add(target);
+                layer.push({ edge, placement: target });
             }
-            queue = [];
+            queue = deferred;
             if (__f2Diag) {
-                log(`[f2-frontier] N=${layerN} width=${layer.length} resolved-so-far=${resolved.size} seen=${seen.size}`);
+                log(`[f2-frontier] N=${layerN} width=${layer.length} resolved-so-far=${resolved.size} settled=${settled.size}`);
             }
             if (layer.length === 0)
                 break;
@@ -570,7 +638,7 @@ export class NpmInstaller {
             // cache slice (only entries for THIS name) so the per-task RPC
             // stays small. Bounded to 16 versions per name — enough to cover
             // ~2 majors of typical packages, well under any RPC arg size cap.
-            const tasks = layer.map(([name, range]) => {
+            const tasks = layer.map(({ edge: { name, range }, placement }) => {
                 const cachedRows = this.cache.getRegistryVersions(name).slice(0, 16);
                 const cachedEntries = cachedRows.map((e) => ({
                     name: e.name,
@@ -594,8 +662,9 @@ export class NpmInstaller {
                     isOptional: optionalNames.has(name),
                     fetchTimeoutMs: 15_000,
                     retries: 3,
+                    registry,
                 };
-                return { key: name, args: taskSpec };
+                return { key: placement, args: taskSpec };
             });
             // Dispatch the layer. Fanout routes:
             //   <5 → in-DO fanout in-DO (IsolatePool), concurrency = layer.length (capped at 4)
@@ -617,7 +686,10 @@ export class NpmInstaller {
             // fanout failed to deliver is recorded instead of skipped.
             for (let i = 0; i < layer.length; i++) {
                 const res = results[i];
-                const [taskName] = layer[i];
+                const { edge, placement } = layer[i];
+                const taskName = edge.name;
+                pending.delete(placement);
+                settled.add(placement);
                 if (!res) {
                     unresolved.set(taskName, `resolver fanout returned no result at layer ${layerN}`);
                     continue;
@@ -643,10 +715,10 @@ export class NpmInstaller {
                 // One `npm http` line per packument, reporting the tier that actually
                 // served it. A skipped task issued no request, so it gets no line.
                 if (res.packumentSource === 'network') {
-                    this.npmLog('http', npmHttpFetchLine(packumentUrl(taskName), res.packumentElapsedMs));
+                    this.npmLog('http', npmHttpFetchLine(packumentUrl(taskName, registry), res.packumentElapsedMs));
                 }
                 else if (res.packumentSource !== 'skipped') {
-                    this.npmLog('http', npmHttpCacheLine(packumentUrl(taskName)));
+                    this.npmLog('http', npmHttpCacheLine(packumentUrl(taskName, registry)));
                 }
                 totalPackumentBytes += res.packumentBytesDecoded;
                 if (res.packumentSource === 'r2-cache')
@@ -716,37 +788,39 @@ export class NpmInstaller {
                         continue;
                     }
                 }
-                if (resolved.has(pkg.name))
+                // A W6 swap answers with another name; place what came back.
+                const isRoot = placement === taskName;
+                const actual = isRoot ? pkg.name : nestedPlacement(edge.from, pkg.name);
+                if (placed.has(actual))
                     continue;
-                resolved.set(pkg.name, pkg);
-                // Edge extraction.
+                placed.set(actual, pkg);
+                settled.add(actual);
+                if (isRoot)
+                    resolved.set(pkg.name, pkg);
+                else
+                    nested.set(actual, pkg);
+                // Edge extraction, from this package's own placement.
                 const inheritBestEffort = bestEffortNames.has(pkg.name);
                 for (const [depName, depRange] of Object.entries(pkg.dependencies)) {
-                    if (resolved.has(depName) || seen.has(depName))
-                        continue;
                     if (inheritBestEffort)
                         bestEffortNames.add(depName);
-                    queue.push([depName, depRange]);
+                    queue.push({ name: depName, range: depRange, from: actual, kind: 'dep' });
                 }
                 const optDeps = pkg.optionalDependencies;
                 if (optDeps) {
                     for (const [depName, depRange] of Object.entries(optDeps)) {
-                        if (resolved.has(depName) || seen.has(depName))
-                            continue;
                         optionalNames.add(depName);
                         if (inheritBestEffort)
                             bestEffortNames.add(depName);
-                        queue.push([depName, depRange]);
+                        queue.push({ name: depName, range: depRange, from: actual, kind: 'dep' });
                     }
                 }
                 if (pkg.peerDependencies) {
                     for (const [peerName, peerRange] of Object.entries(pkg.peerDependencies)) {
-                        if (resolved.has(peerName) || seen.has(peerName))
-                            continue;
                         topLevelNames.add(peerName);
                         if (inheritBestEffort)
                             bestEffortNames.add(peerName);
-                        queue.push([peerName, peerRange]);
+                        queue.push({ name: peerName, range: peerRange, from: actual, kind: 'peer' });
                     }
                 }
                 // X.5-F R2.5 + X.5-J: optional peers when THIS pkg is the
@@ -757,11 +831,9 @@ export class NpmInstaller {
                     const allPeers = pkg.__allPeerDependencies;
                     if (allPeers) {
                         for (const [peerName, peerRange] of Object.entries(allPeers)) {
-                            if (resolved.has(peerName) || seen.has(peerName))
-                                continue;
                             topLevelNames.add(peerName);
                             bestEffortNames.add(peerName);
-                            queue.push([peerName, peerRange]);
+                            queue.push({ name: peerName, range: peerRange, from: actual, kind: 'peer' });
                         }
                     }
                 }
@@ -776,13 +848,18 @@ export class NpmInstaller {
         // 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();
+        // Followed by name over every placement, root first.
+        const byName = new Map(resolved);
+        for (const pkg of nested.values())
+            if (!byName.has(pkg.name))
+                byName.set(pkg.name, pkg);
         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);
+            const pkg = byName.get(name);
             if (!pkg)
                 continue;
             const optional = pkg.optionalDependencies ?? {};
@@ -829,7 +906,7 @@ export class NpmInstaller {
             `, dispatch barriers=${dispatchBarriers}, ` +
             `elapsed=${((Date.now() - t0) / 1000).toFixed(1)}s` +
             (unresolved.size > 0 ? `, unresolved=${unresolved.size}` : ''));
-        return { resolved, unresolved, rejected };
+        return { resolved, nested, unresolved, rejected };
     }
     /**
      * Batch install via two-tier fan-out (Fanout).
@@ -855,31 +932,26 @@ export class NpmInstaller {
      *   Two-tier topology re-expands the fan-out without re-introducing
      *   the V8 cap risk.
      */
-    async fetchViaBatchFacet(toFetch, hoistPlan, nmDir, pid) {
+    async fetchViaBatchFacet(toFetch, nmDir, pid) {
         const log = (msg) => this.onProgress?.(msg);
         const installed = [];
         const failed = [];
         let filesWritten = 0;
         const mtime = Date.now();
         // Every entry in `toFetch` has a tarball URL — the diff phase fails
-        // the ones that don't rather than dropping them.
+        // the ones that don't rather than dropping them. `pkgDir` is the
+        // spec's identity: one version may land at two placements.
         const specs = toFetch
-            .map((p) => ({
+            .map(({ placement, pkg: p }) => ({
             name: p.name,
             version: p.version,
             tarballUrl: p.tarballUrl,
             integrity: p.integrity || '',
-            pkgDir: nmDir + '/' + p.name,
+            pkgDir: nmDir + '/' + placement,
             installRoot: nmDir,
             mtime,
             chunkSize: CHUNK_SIZE,
         }));
-        // hoistPlan is intentionally unused: the current installer maps
-        // every package to `${nmDir}/${name}` (flat hoisting). Accepting
-        // the plan as a parameter keeps the caller agnostic of the hoist
-        // strategy and lets a future nested-install variant slot in
-        // without changing the call site.
-        void hoistPlan;
         if (specs.length === 0) {
             return { installed, failed, filesWritten };
         }
@@ -899,13 +971,22 @@ export class NpmInstaller {
         // the two made the phase width control install parallelism, so widening it
         // for latency widened the cold-start burst along with it.
         const INSTALL_PEER_CAP = 8;
-        const shardCount = Math.min(specs.length, INSTALL_PEER_CAP);
-        // Round-robin assignment: spec at pkgIdx → shard pkgIdx % shardCount.
-        // This produces ⌈specs.length / shardCount⌉ specs per shard at
+        // A tarball's placements share a shard, which acquires it once.
+        const byTarball = new Map();
+        for (const spec of specs) {
+            const group = byTarball.get(spec.tarballUrl);
+            if (group)
+                group.push(spec);
+            else
+                byTarball.set(spec.tarballUrl, [spec]);
+        }
+        const shardCount = Math.min(byTarball.size, INSTALL_PEER_CAP);
+        // Round-robin assignment: tarball at idx → shard idx % shardCount.
+        // This produces ⌈tarballs / shardCount⌉ tarballs per shard at
         // most, with the imbalance bounded to ±1.
         const shards = Array.from({ length: shardCount }, () => []);
-        specs.forEach((spec, idx) => {
-            shards[idx % shardCount].push(spec);
+        [...byTarball.values()].forEach((group, idx) => {
+            shards[idx % shardCount].push(...group);
         });
         const nonEmptyShards = shards.filter((s) => s.length > 0);
         const topology = nonEmptyShards.length < IN_DO_THRESHOLD ? 'in-do (in-DO fanout)' : 'peer-do (peer-DO fanout)';
@@ -967,11 +1048,13 @@ export class NpmInstaller {
             let okCount = 0;
             let failCount = 0;
             const reported = new Set();
-            const specByPackage = new Map(specs.map((s) => [`${s.name}@${s.version}`, s]));
+            const specByDir = new Map(specs.map((s) => [s.pkgDir, s]));
             for (const r of result.perPackage) {
-                reported.add(`${r.name}@${r.version}`);
+                // A pre-placement shard reports no pkgDir; it only wrote root.
+                const dir = r.pkgDir ?? `${nmDir}/${r.name}`;
+                reported.add(dir);
                 // One `npm http` line per tarball, reporting the tier that served it.
-                const spec = specByPackage.get(`${r.name}@${r.version}`);
+                const spec = specByDir.get(dir);
                 if (spec && r.tarballSource) {
                     this.npmLog('http', r.tarballSource === 'registry'
                         ? npmHttpFetchLine(spec.tarballUrl, r.tarballElapsedMs ?? 0)
@@ -996,12 +1079,11 @@ export class NpmInstaller {
             // returns short would otherwise leave its packages in neither list,
             // which is the same silent partial one layer down.
             for (const s of specs) {
-                const id = `${s.name}@${s.version}`;
-                if (reported.has(id))
+                if (reported.has(s.pkgDir))
                     continue;
-                failed.push(id);
+                failed.push(`${s.name}@${s.version}`);
                 failCount++;
-                log(`  [warn] ${id}: install shard returned no result for this package`);
+                log(`  [warn] ${s.name}@${s.version}: install shard returned no result for this package (${s.pkgDir})`);
             }
             // Fold facet counters into the supervisor's diagnostic state.
             recordInstallFacetCounters(result.facetCounters);
@@ -1101,6 +1183,13 @@ export class NpmInstaller {
      * W6: apply the PACKAGE_ABI_POLICY swap rewrites and reject deny list
      * to a top-level spec map. Emits `[swap]` notices via onProgress.
      *
+     * A swap rewrites the spec's RANGE to an npm alias of the swap target
+     * (`esbuild` → `npm:esbuild-wasm@<range>`), never its key: the key names
+     * the install directory, so `resolved`, node_modules, the bin links, the
+     * lockfile and package.json all keep the name the user declared. The
+     * resolver facet treats the alias as authoritative and does not announce
+     * the swap a second time.
+     *
      * 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:`
@@ -1166,7 +1255,8 @@ export class NpmInstaller {
         // 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) {
+        // An edge is met by any placement Node's walk from the entry finds.
+        for (const [placement, entry] of lockfile) {
             const cached = this.cache.getRegistryEntry(entry.name, entry.resolvedVer);
             if (!cached)
                 return false;
@@ -1175,67 +1265,185 @@ export class NpmInstaller {
             for (const depName of Object.keys(deps)) {
                 if (Object.hasOwn(optional, depName))
                     continue;
-                if (!lockfile.has(depName))
+                if (!visiblePlacements(placement, depName).some((p) => lockfile.has(p)))
                     return false;
             }
             const peers = safeJsonParse(cached.peerDepsJson || '{}', {});
             for (const peerName of Object.keys(peers)) {
-                if (!lockfile.has(peerName))
+                if (!visiblePlacements(placement, peerName).some((p) => lockfile.has(p)))
                     return false;
             }
         }
         return true;
     }
     /**
-     * Convert a lockfile back to resolved packages (for cache restore).
+     * npm ci: the placements package-lock.json (or npm-shrinkwrap.json)
+     * records, checked against package.json first. The ABI policy the resolver
+     * applies still holds: platform-native optional shards are skipped, a
+     * required one is refused, and a swapped package resolves its swap target
+     * at the locked version.
      */
-    lockfileToResolved(lockfile) {
+    async treeFromPackageLock(projDir, production, log, registry) {
+        const lockName = ['npm-shrinkwrap.json', 'package-lock.json']
+            .find((name) => this.vfs.exists(`${projDir}/${name}`));
+        if (!lockName)
+            throw new Error('`npm ci` needs a package-lock.json or npm-shrinkwrap.json');
+        const lock = parsePackageLock(this.vfs.readFileString(`${projDir}/${lockName}`), lockName);
+        const pkgJsonPath = `${projDir}/package.json`;
+        if (!this.vfs.exists(pkgJsonPath))
+            throw new Error('`npm ci` needs a package.json');
+        const pkgJson = JSON.parse(this.vfs.readFileString(pkgJsonPath));
+        const mismatches = packageLockMismatches(pkgJson, lock);
+        if (mismatches.length > 0) {
+            throw new Error(`\`npm ci\` can only install packages when your package.json and ${lockName} are in sync. ` +
+                `Update the lock file with \`npm install\` before continuing.\n` +
+                mismatches.map((m) => `npm ERR! ${m}`).join('\n'));
+        }
+        const unsupported = Object.keys(lock.packages).find((key) => key !== '' && !key.startsWith('node_modules/'));
+        if (unsupported !== undefined) {
+            throw new Error(`${lockName} entry "${unsupported}" is a workspace or linked package, which \`npm ci\` here does not install`);
+        }
+        // Only a lock that will be installed as written clears the old tree.
+        if (this.vfs.exists(`${projDir}/node_modules`))
+            this.vfs.removeRecursive(`${projDir}/node_modules`);
         const resolved = new Map();
-        for (const [name, entry] of lockfile) {
-            // Reconstruct from registry cache
-            const cached = this.cache.getRegistryEntry(name, entry.resolvedVer);
-            if (cached) {
-                resolved.set(name, {
-                    name: cached.name,
-                    version: cached.version,
-                    tarballUrl: cached.tarballUrl,
-                    integrity: cached.integrity,
-                    dependencies: safeJsonParse(cached.depsJson, {}),
-                    exports: safeJsonParse(cached.exportsJson, null),
-                    main: cached.main,
-                    module: cached.moduleField,
-                    bin: safeJsonParse(cached.binJson, {}),
-                });
+        const nested = new Map();
+        const unresolved = new Map();
+        const rejected = [];
+        // Swapped lock entries by placement: each resolves its swap target at its own locked version.
+        const swapPlacements = [];
+        for (const [key, entry] of Object.entries(lock.packages)) {
+            if (key === '')
+                continue;
+            if (production && entry.dev === true)
+                continue;
+            const placement = key.slice('node_modules/'.length);
+            const folderName = placement.split('/node_modules/').pop() ?? placement;
+            const name = typeof entry.name === 'string' ? entry.name : folderName;
+            const version = typeof entry.version === 'string' ? entry.version : '';
+            const platform = {
+                name,
+                os: stringList(entry.os),
+                cpu: stringList(entry.cpu),
+                libc: stringList(entry.libc),
+                main: '',
+            };
+            if (entry.optional === true && isOptionalNativeBinding(platform)) {
+                log(`[resolve-fanout] [skip] ${name} — optional native binding (os=${platform.os ?? '*'}, cpu=${platform.cpu ?? '*'}, libc=${platform.libc ?? '*'})`);
+                continue;
             }
-            else {
-                // Registry cache miss — create minimal entry
-                resolved.set(name, {
-                    name,
-                    version: entry.resolvedVer,
-                    tarballUrl: '',
-                    integrity: entry.integrity,
-                    dependencies: safeJsonParse(entry.depsJson, {}),
-                    exports: null,
-                    main: '',
-                    module: '',
-                    bin: {},
-                });
+            const platformReject = policyNativePlatformReject(PACKAGE_ABI_POLICY, platform);
+            if (platformReject) {
+                log(`[resolve-fanout] [skip] ${name} — ${platformReject.reason}`);
+                rejected.push({ name, reason: platformReject.reason, required: entry.optional !== true });
+                continue;
+            }
+            // Policy follows the registry identity (`name`), placement the folder the lock
+            // names: an aliased entry (`node_modules/build`, name `esbuild`) resolves as
+            // the alias `build@npm:esbuild@<locked>`, so the swap target lands in build.
+            if (lookupSwap(name)) {
+                swapPlacements.push({ placement, folderName, spec: folderName === name ? version : `npm:${name}@${version}` });
+                continue;
+            }
+            if (entry.link === true || typeof entry.resolved !== 'string' || !version) {
+                unresolved.set(name, `${lockName} records no registry tarball for ${key}`);
+                continue;
+            }
+            const reject = lookupReject(name);
+            if (reject)
+                log(`[npm] note: ${name} has no Workers-compatible build: ${reject.reason}${reject.suggest ? ` … try: ${reject.suggest}` : ''}`);
+            const pkg = {
+                name,
+                version,
+                tarballUrl: entry.resolved,
+                integrity: typeof entry.integrity === 'string' ? entry.integrity : '',
+                dependencies: stringRecord(entry.dependencies),
+                optionalDependencies: stringRecord(entry.optionalDependencies),
+                peerDependencies: stringRecord(entry.peerDependencies),
+                os: platform.os,
+                cpu: platform.cpu,
+                libc: platform.libc,
+                exports: null,
+                main: '',
+                module: '',
+                bin: typeof entry.bin === 'string' ? { [folderName]: entry.bin } : stringRecord(entry.bin),
+            };
+            const staged = lookupStagedArtifact(name);
+            if (staged)
+                applyStagedArtifact(pkg, staged);
+            (placement.includes('/node_modules/') ? nested : resolved).set(placement, pkg);
+        }
+        // Root placements resolve together, as top-level specs. A nested one is its own
+        // resolution, rebased under its placement: its package there, anything it
+        // brings below it, unless the lock already placed that path.
+        const rootSwaps = swapPlacements.filter(({ placement }) => !placement.includes('/node_modules/'));
+        const batches = [];
+        if (rootSwaps.length > 0)
+            batches.push({ at: null, specs: Object.fromEntries(rootSwaps.map(({ folderName, spec }) => [folderName, spec])) });
+        for (const { placement, folderName, spec } of swapPlacements) {
+            if (placement.includes('/node_modules/'))
+                batches.push({ at: placement, specs: { [folderName]: spec } });
+        }
+        for (const { at, specs } of batches) {
+            const swapped = await this.resolveTreeViaFanout(specs, log, { registry });
+            const [folder] = Object.keys(specs);
+            const rebase = (path) => (at === null ? path : path === folder ? at : `${at}/node_modules/${path}`);
+            for (const [path, pkg] of [...swapped.resolved, ...swapped.nested]) {
+                const target = rebase(path);
+                const into = target.includes('/node_modules/') ? nested : resolved;
+                if (!into.has(target))
+                    into.set(target, pkg);
             }
+            for (const [name, reason] of swapped.unresolved)
+                unresolved.set(name, reason);
+            rejected.push(...swapped.rejected);
         }
-        return resolved;
+        return { resolved, nested, unresolved, rejected, lockName };
+    }
+    /** Convert a lockfile back to resolved packages: root by name, nested by placement path. */
+    lockfileToResolved(lockfile) {
+        const resolved = new Map();
+        const nested = new Map();
+        for (const [placement, entry] of lockfile) {
+            const name = entry.name;
+            // Reconstruct from the registry cache; on a miss, a minimal entry.
+            const cached = this.cache.getRegistryEntry(name, entry.resolvedVer);
+            (placement === name ? resolved : nested).set(placement, cached ? {
+                name: cached.name,
+                version: cached.version,
+                tarballUrl: cached.tarballUrl,
+                integrity: cached.integrity,
+                dependencies: safeJsonParse(cached.depsJson, {}),
+                exports: safeJsonParse(cached.exportsJson, null),
+                main: cached.main,
+                module: cached.moduleField,
+                bin: safeJsonParse(cached.binJson, {}),
+            } : {
+                name,
+                version: entry.resolvedVer,
+                tarballUrl: '',
+                integrity: entry.integrity,
+                dependencies: safeJsonParse(entry.depsJson, {}),
+                exports: null,
+                main: '',
+                module: '',
+                bin: {},
+            });
+        }
+        return { resolved, nested };
     }
     /**
      * Write lockfile to SQLite.
      */
-    writeLockfile(projDir, resolved, _hoistPlan, nmDir) {
+    writeLockfile(projDir, hoistPlan, nmDir) {
         const entries = new Map();
-        for (const [name, pkg] of resolved) {
-            entries.set(name, {
-                name,
+        for (const { placement, pkg } of hoistPlacements(hoistPlan)) {
+            entries.set(placement, {
+                name: pkg.name,
                 resolvedVer: pkg.version,
                 integrity: pkg.integrity,
                 depsJson: JSON.stringify(pkg.dependencies),
-                hoistedPath: nmDir + '/' + name,
+                hoistedPath: nmDir + '/' + placement,
             });
         }
         this.cache.writeLockfile(projDir, entries, this.ctx);
@@ -1259,7 +1467,7 @@ export class NpmInstaller {
         const binChunks = [];
         const mtime = Date.now();
         for (const binEntry of Object.values(manifest.bins)) {
-            const data = enc.encode(createNpmBinShim(binEntry));
+            const data = enc.encode(createNpmBinShim(binEntry, binDir));
             const linkPath = binDir + '/' + binEntry.name;
             binEntries.push({
                 path: linkPath,
@@ -1313,21 +1521,12 @@ export class NpmInstaller {
             if (!pkgJson.dependencies)
                 pkgJson.dependencies = {};
             for (const spec of explicitPackages) {
-                // Find the resolved package matching this spec
+                // `resolved` is keyed by the name the user typed — a swapped
+                // package resolves as an alias under that name (applySwaps), so
+                // `esbuild` is found as `esbuild` and package.json records the
+                // user's key, never the swap target.
                 const { name } = parseExplicitPackageSpec(spec);
-                // W6: if a swap fired, the user typed `name` but `resolved` is
-                // keyed by the swap target (e.g. user typed 'esbuild', resolved
-                // has 'esbuild-wasm'). Look up via lookupSwap to bridge the
-                // gap; write the user's original key into package.json so the
-                // file remains the user's source-of-truth and isn't silently
-                // mutated to the swap target (which would break cross-environment
-                // pushes).
-                let pkg = resolved.get(name);
-                if (!pkg) {
-                    const swap = lookupSwap(name);
-                    if (swap)
-                        pkg = resolved.get(swap.to);
-                }
+                const pkg = resolved.get(name);
                 if (pkg) {
                     pkgJson.dependencies[name] = '^' + pkg.version;
                 }