@gjsify/cli 0.36.0 → 0.38.0

package/lib/utils/install-backend-native.js

@@ -1,80 +1,52 @@
 // Native install backend — GJS-runnable replacement for `npm install`.
 //
 // Pipeline: parse specs → resolve deps via @gjsify/npm-registry packuments and
-// @gjsify/semver → download tarballs in parallel → extract into a flat
-// node_modules/ via @gjsify/tar. Output layout matches `npm install` so the
-// existing `runGjsBundle()` prebuild detection works without branching.
+// @gjsify/semver → download tarballs in parallel → extract into node_modules/
+// via @gjsify/tar. Output layout matches `npm install` so `runGjsBundle()`'s
+// prebuild detection needs no branching. Hoisting is npm v3+: root placement
+// unless the root holds an incompatible version, then nested under the requester.
 //
-// Phase D.7b — version-conflict resolution via nested `node_modules`.
-// The resolver tracks per-package placement: a dep is hoisted to the
-// root when no conflict exists, nested under the requesting package
-// when its required version is incompatible with what's already at
-// the root. Mirrors npm v3+ behavior.
+// PLATFORM FILTERING (os/cpu/libc) — the tree is RESOLVED for every platform and
+// INSTALLED for one. A node the host cannot run is marked `inert` (npm's word):
+// not downloaded, not extracted, still in `gjsify-lock.json` with its
+// `os`/`cpu`/`libc`. A lockfile recording only what ONE host can install is a
+// machine snapshot — commit it and a colleague on another OS gets a tree missing
+// its binaries with no drift reported. So DECLARATIONS are locked and the VERDICT
+// is recomputed per host (`applyPlatformFilter`).
 //
-// PLATFORM FILTERING (os/cpu/libc) — the tree is RESOLVED for every platform
-// and INSTALLED for one. A node whose declaration excludes the host is marked
-// `inert` (npm's word — arborist build-ideal-tree.js's `node.inert = true`)
-// which skips its download + extract, but it stays in `gjsify-lock.json` with
-// its `os`/`cpu`/`libc` recorded. That split is deliberate and is the whole
-// reason lockfiles are shareable: a lockfile containing only what ONE host can
-// install is not a lockfile, it is a machine snapshot — commit it and every
-// colleague on another OS gets a tree missing its binaries with no drift
-// reported. So the DECLARATIONS are locked and the VERDICT is recomputed per
-// host at install time (see applyPlatformFilter).
+// Three invariants hold that up. Each is structural rather than documented,
+// because the first draft broke the first two while reading as if it did not.
+// The measured record is packages/infra/cli/AGENTS.md § `gjsify install`.
 //
-// THREE INVARIANTS MAKE THAT CLAIM TRUE, and each is structural rather than
-// documented, because the first draft of this feature broke the first two while
-// reading as if it did not — and shipped without the third:
-//
-//   1. THE RESOLVE IS TARGET-BLIND. `resolveDeps` is not given the platform
-//      target at all — it cannot be, so it cannot record a target-dependent
-//      declaration. The draft passed the target in to decide when to escalate to
-//      a full packument for `libc`, gated on `target.os === 'linux'`; a lockfile
-//      authored on macOS therefore carried NO `libc` for anything, and a Linux
-//      colleague running `--immutable` off that file got no libc filtering at
-//      all — precisely the direction this header promises is portable. The
-//      resolve now reads the FULL document for every package (see resolveDeps),
-//      which is also what arborist does for every dependency it resolves
-//      (`#fetchManifest` sets `fullMetadata: true`).
-//   2. `optional` IS DERIVED, NEVER TRUSTED. It is recomputed as a FIXPOINT over
-//      the placed graph on BOTH paths (computeOptionalFlags), before it is
-//      persisted and before the platform verdict reads it. The draft promoted a
-//      node out of the optional set at the reuse site, one shot, which made the
-//      answer depend on BFS edge order: a genuinely required transitive dep
-//      reached first through an optional edge stayed flagged optional, was
-//      persisted that way, and was then silently skipped on every machine
-//      instead of raising EBADPLATFORM. npm computes the same flags as a
+//   1. THE RESOLVE IS TARGET-BLIND — `resolveDeps` takes no target, so it cannot
+//      record a target-dependent declaration. The draft gated `libc` escalation
+//      on `target.os === 'linux'`, so a macOS-authored lockfile carried no `libc`
+//      for anything and a Linux colleague's `--immutable` got no libc filtering
+//      at all. The resolve now reads the FULL document for every package, as
+//      arborist does (`#fetchManifest` sets `fullMetadata: true`).
+//   2. `optional` IS DERIVED, NEVER TRUSTED — a fixpoint over the placed graph on
+//      BOTH paths (`computeOptionalFlags`), before it is persisted and before the
+//      platform verdict reads it. The draft promoted at the reuse site, one shot,
+//      making the answer depend on BFS edge order: a genuinely required
+//      transitive dep reached first through an optional edge stayed flagged
+//      optional, was persisted that way, and was then silently skipped on every
+//      machine instead of raising EBADPLATFORM. npm computes the same flags as a
 //      fixpoint for the same reason (refs/npm-cli/workspaces/arborist/lib/
-//      calc-dep-flags.js: "If a node is changed, we add to the queue and
-//      continue until no more changes").
-//   3. OPTIONALITY BELONGS TO THE EDGE, NOT TO THE BLOCK THE NAME WAS READ FROM.
-//      A name listed in BOTH `dependencies` and `optionalDependencies` is
-//      OPTIONAL: "entries in optionalDependencies will override entries of the
-//      same name in dependencies" (npm's package.json docs), which is why every
-//      walk over a node's dep edges here goes through {@link requiredDepEntries}
-//      instead of `Object.keys(node.dependencies)`. `@parcel/rust@2.16.4` is why
-//      it is written down: it declares all eight of its per-platform napi
-//      packages in both blocks, so a `dependencies`-only walk made
-//      `@parcel/rust-darwin-x64` REQUIRED and every Linux install of any tree
-//      containing parcel died with EBADPLATFORM — while `npm install` on the same
-//      manifest exits 0, installs
-//      `@parcel/rust-linux-x64-gnu`, and records the other seven as
-//      `"optional": true` in its own lockfile. The rule was already applied to
-//      swallowed resolve failures (`assertRequiredEdgesResolved`: "optionality
-//      lives on the edge, not on its endpoints") and missing from the two walks
-//      that decide fatal-vs-inert, which is the worst place to have half of it.
-//      It costs a lockfile field (`optionalDependencies` per entry, v4): without
-//      it the fresh-resolve path and the lockfile path would disagree about the
-//      same tree, which is the split invariant 2 exists to close.
-//      WHY THE DEFECT LOOKED LIKE IT DID NOT EXIST: the same napi shape is
-//      overwhelmingly published in ONE block — measured on the latest of `oxlint`,
-//      `esbuild` and `rollup`, all three list their per-platform bindings in
-//      `optionalDependencies` only (zero overlap), so they installed correctly
-//      throughout and every mock corpus reaches for that shape too. The block a
-//      publisher chooses is not a property this installer may assume.
+//      calc-dep-flags.js).
+//   3. OPTIONALITY BELONGS TO THE EDGE, not to the block the name came from. A
+//      name in BOTH `dependencies` and `optionalDependencies` is OPTIONAL (npm's
+//      documented override) — hence {@link requiredDepEntries} in every dep walk.
+//      `@parcel/rust@2.16.4` lists all eight of its napi platform packages in
+//      both blocks, so a `dependencies`-only walk made `@parcel/rust-darwin-x64`
+//      REQUIRED and every Linux install of a tree containing parcel died with
+//      EBADPLATFORM where `npm install` exits 0. It hid because that napi shape
+//      is overwhelmingly published in ONE block (`oxlint`, `esbuild`, `rollup`),
+//      which is what every mock corpus reaches for too. Costs a lockfile field
+//      (v4); without it the fresh-resolve and lockfile paths disagree about one
+//      tree.
 //
-// Out of scope (still deferred): peerDependencies validation,
-// lifecycle scripts, git/file specs.
+// Out of scope (still deferred): peerDependencies validation, lifecycle scripts,
+// git/file specs.
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import * as os from 'node:os';
@@ -89,40 +61,38 @@ import { assertNativeBackendNodeVersion } from './node-version.js';
 import { buildCmdShim, buildLauncherShims, buildNativeEnvPreamble, buildShLauncher, isGjsBundlePath, parseShebang, pickBinMap, } from './bin-shim.js';
 import { detectNativePackages } from './detect-native-packages.js';
 import { badPlatformError, checkPlatform, declaresPlatform, describePlatformTarget, readPlatformForce, resolveHostPlatform, } from './platform-check.js';
-// 16-wide download pool. Matched to the shared Soup.Session's lifted
-// `max-conns-per-host` (see @gjsify/fetch `getSharedSession`) — a higher pool
-// here only translates into real concurrency because that cap was raised from
-// libsoup's default of 2. npm (`maxsockets` 15) and pnpm (`network-concurrency`
-// 16) use the same order of magnitude. Override with GJSIFY_INSTALL_CONCURRENCY.
+// 16-wide download pool, matched to the shared Soup.Session's lifted
+// `max-conns-per-host` (@gjsify/fetch `getSharedSession`) — without that lift
+// libsoup's default of 2 caps real concurrency however wide the pool is. Same
+// order of magnitude as npm (`maxsockets` 15) and pnpm (`network-concurrency` 16).
 const DEFAULT_CONCURRENCY = Number(process.env.GJSIFY_INSTALL_CONCURRENCY ?? '16') || 16;
 const LOCKFILE_NAME = 'gjsify-lock.json';
 /**
- * v3 adds the per-entry platform declaration (`os`/`cpu`/`libc`) plus
- * `optional`, which together let a foreign-platform package be recorded without
- * being installed. v4 adds the per-entry `optionalDependencies` map, without
- * which the optionality fixpoint cannot see WHICH of an entry's edges are
- * optional and a name declared in both blocks comes out required (header note,
- * invariant 3). Older lockfiles are still READ (see {@link readLockfile}).
+ * v3 adds the per-entry platform declaration (`os`/`cpu`/`libc`) plus `optional`,
+ * which together let a foreign-platform package be recorded without being
+ * installed. v4 adds the per-entry `optionalDependencies` map, without which the
+ * optionality fixpoint cannot see WHICH of an entry's edges are optional and a
+ * name declared in both blocks comes out required (header note, invariant 3).
+ * Older lockfiles are still READ — see {@link readLockfile}.
  */
 const LOCKFILE_VERSION = 4;
 /**
- * Lockfile versions this CLI can read. A v2 lockfile is a valid pin set that
- * simply predates the platform fields; rejecting it (the old
- * `!== LOCKFILE_VERSION → null` behaviour) would discard the whole file and let
- * the following fresh resolve bump every `^`-range to the newest in-range
- * version — the exact silent churn lockfile preservation exists to prevent, on
- * every user's first install after upgrading the CLI.
+ * Lockfile versions this CLI can read. A v2 file is a valid pin set that merely
+ * predates the platform fields; rejecting it (the old `!== LOCKFILE_VERSION →
+ * null` behaviour) discards the whole file and lets the following fresh resolve
+ * bump every `^`-range to the newest in-range version — the silent churn lockfile
+ * preservation exists to prevent, on every user's first install after a CLI
+ * upgrade.
  *
- * READING an older file is not the same as TRUSTING it for everything: only the
- * current version short-circuits the resolve (see the branch below), so a v2/v3
- * file seeds version preservation and is then rewritten. `--immutable` is the one
- * path that must consume what it was handed verbatim, so there — and only there —
- * a pre-v4 file keeps its pre-v4 edge fidelity: a both-blocks optional dep is
- * judged required, exactly as before this fix. That is a strictly unchanged
- * outcome rather than a new failure, and one plain `gjsify install` upgrades the
- * file. Failing `--immutable` on an old-but-readable lockfile instead would break
- * every CI whose committed file predates this CLI, including this repo's own
- * (still v2).
+ * READING an older file is not TRUSTING it for everything: only the current
+ * version short-circuits the resolve (see the branch below), so a v2/v3 file
+ * seeds version preservation and is then rewritten. `--immutable` must consume
+ * what it was handed verbatim, so there alone a pre-v4 file keeps its pre-v4 edge
+ * fidelity — a both-blocks optional dep is judged required, exactly as before
+ * this fix, which is an unchanged outcome rather than a new failure, and one
+ * plain `gjsify install` upgrades the file. Failing `--immutable` on an
+ * old-but-readable lockfile would instead break every CI whose committed file
+ * predates this CLI.
  */
 const READABLE_LOCKFILE_VERSIONS = new Set([2, 3, LOCKFILE_VERSION]);
 export async function installPackagesNative(opts) {
@@ -136,12 +106,12 @@ export async function installPackagesNative(opts) {
     const npmrc = await loadNpmrc(opts);
     const log = makeLogger(opts.verbose ?? false);
     // Serialize every mutation of THIS prefix across processes (ADR 0001):
-    // concurrent installs into the same node_modules used to interleave
-    // `rmSync` + extract on shared destination dirs and tear the lockfile.
-    // Re-entrant within the process (workspace installs already hold the
-    // root-prefix lock — this just bumps a refcount). Installs into other
-    // prefixes proceed concurrently; the shared XDG caches stay lock-free
-    // because their tmp+rename writes are atomic (install-cache-fs.ts).
+    // concurrent installs into the same node_modules used to interleave `rmSync` +
+    // extract on shared destination dirs and tear the lockfile. Re-entrant within
+    // the process (a workspace install already holds the root-prefix lock, so this
+    // only bumps a refcount). Other prefixes proceed concurrently; the shared XDG
+    // caches stay lock-free because their tmp+rename writes are atomic
+    // (install-cache-fs.ts).
     const lock = await acquireInstallLock(opts.prefix, { signal: opts.signal });
     try {
         return await installPackagesNativeLocked(opts, npmrc, log);
@@ -156,9 +126,9 @@ async function installPackagesNativeLocked(opts, npmrc, log) {
     const lockfilePath = path.join(opts.prefix, LOCKFILE_NAME);
     const existingLock = readLockfile(lockfilePath);
     // The triple this install materialises FOR. Normally the running host;
-    // `--os/--cpu/--libc` (npm's config keys `os`/`cpu`/`libc`, read from the
-    // environment by resolveHostPlatform) override it, which is what makes the
-    // darwin/win32/musl selection testable — and reviewable — from one machine.
+    // `--os/--cpu/--libc` (npm's config keys, read from the environment by
+    // `resolveHostPlatform`) override it, which is what makes the darwin/win32/musl
+    // branches reviewable from one machine.
     const target = resolveHostPlatform();
     const force = readPlatformForce(process.env);
     log('install: platform target %s%s', describePlatformTarget(target), force ? ' (--force: checks bypassed)' : '');
@@ -166,18 +136,16 @@ async function installPackagesNativeLocked(opts, npmrc, log) {
     /** Did a resolve actually run? Only then is there something new to persist. */
     let resolved = false;
     /**
-     * Edges whose resolve FAILED and was tolerated because the edge looked
-     * optional at the time it was visited. Checked against the final (fixpoint)
-     * optionality below — see {@link assertRequiredEdgesResolved}. Empty on the
-     * lockfile paths, which resolve nothing.
+     * Edges whose resolve FAILED and was tolerated because the edge looked optional
+     * when visited; re-judged against the fixpoint optionality below (see
+     * {@link assertRequiredEdgesResolved}). Empty on the lockfile paths, which
+     * resolve nothing.
      */
     let skippedEdges = new Set();
     if (opts.frozen) {
-        // --immutable / --frozen: lockfile is the authoritative source.
-        // Reject if the file is missing, version-mismatched, or its
-        // `requested` set has drifted from the live request — silently
-        // honoring a stale lockfile would mask real dep churn (the original
-        // bug --immutable exists to catch).
+        // --immutable / --frozen: the lockfile is authoritative. Reject a missing,
+        // version-mismatched or drifted file — silently honouring a stale lockfile
+        // masks the real dep churn `--immutable` exists to catch.
         if (!existingLock) {
             throw new Error(`install: --immutable requires ${LOCKFILE_NAME} at ${opts.prefix} — none found. ` +
                 `Run \`gjsify install\` (without --immutable) to generate one and commit it.`);
@@ -200,43 +168,39 @@ async function installPackagesNativeLocked(opts, npmrc, log) {
     else {
         // A resolve has to run (new/changed/removed dep, or no lockfile yet).
         //
-        // A pre-v4 lockfile lands here too, even when it matches the request,
-        // because each bump added something the verdict is recomputed FROM and a
-        // file that lacks it cannot be consumed verbatim: pre-v3 entries carry no
-        // platform declaration (so the foreign-platform tree would keep installing
-        // forever), pre-v4 entries carry no `optionalDependencies` map (so a name
-        // declared in both blocks looks required and its incompatible siblings
-        // fail the install — the `@parcel/rust` shape, header note invariant 3).
-        // One resolve — version-preserving, per the seeding below, so nothing
-        // bumps — upgrades the file. That matters beyond tidiness here: the
-        // lockfile is written BEFORE the platform filter runs, so the failing
-        // install left a v3 file behind that would otherwise reproduce its own
-        // EBADPLATFORM on every later run without ever resolving again.
+        // A pre-v4 lockfile lands here too even when it matches the request: each
+        // bump added something the verdict is recomputed FROM, so a file lacking it
+        // cannot be consumed verbatim — pre-v3 entries carry no platform
+        // declaration (the foreign-platform tree would keep installing forever),
+        // pre-v4 entries no `optionalDependencies` map (the `@parcel/rust` shape
+        // fails the install; header note, invariant 3). One version-preserving
+        // resolve upgrades the file, and that matters beyond tidiness: the lockfile
+        // is written BEFORE the platform filter runs, so a failing install left a
+        // v3 file behind that would otherwise reproduce its own EBADPLATFORM
+        // forever without ever resolving again.
         //
-        // Unless --refresh-lockfile was passed, seed it with the versions
-        // already pinned in the existing lockfile so unchanged deps keep their
-        // resolved version and only the genuinely new/changed deps move — the
-        // npm/yarn/pnpm `install` default. Without this, every `^`-range would
-        // re-resolve to the newest registry version, churning the whole tree
-        // (and silently bumping transitive deps) on a one-package add.
+        // Unless --refresh-lockfile was passed, seed from the versions already
+        // pinned so unchanged deps keep them and only genuinely new/changed deps
+        // move — the npm/yarn/pnpm `install` default. Without it every `^`-range
+        // re-resolves to the newest registry version, churning the whole tree (and
+        // silently bumping transitives) on a one-package add.
         const preferred = !opts.refreshLockfile && existingLock ? buildPreferredVersions(existingLock) : undefined;
         log('install: resolving %d top-level spec(s) → %s%s', opts.specs.length, opts.prefix, preferred ? ` (preserving ${preferred.size} locked name(s))` : '');
-        // NOTE the absent argument: `target` is deliberately NOT passed. The
-        // resolve must produce the same tree and the same recorded declarations
-        // on every machine (header note, invariant 1), and the cheapest way to
-        // keep that true is to give it nothing target-shaped to read.
+        // `target` is deliberately NOT passed: the resolve must produce the same
+        // tree and the same recorded declarations on every machine (header note,
+        // invariant 1), and giving it nothing target-shaped to read is what keeps
+        // that true.
         const resolveResult = await resolveDeps(opts.specs, npmrc, log, opts.overrides, opts.skipDeps, opts.signal, progress, preferred, opts.workspaceNames, opts.specOrigins, opts.optionalSpecs);
         nodes = resolveResult.nodes;
         skippedEdges = resolveResult.skippedEdges;
         resolved = true;
     }
-    // `optional` is DERIVED here, on BOTH paths, for the same reason
-    // `applyPlatformFilter` is: the answer must not depend on which path the tree
-    // arrived by, and a flag read back from a file is an INPUT nothing checked.
-    // Runs BEFORE writeLockfile (so the persisted flag is the final one) and
-    // before the platform verdict (which reads it to decide fatal vs. inert), and
-    // before the workspace filter below (which removes nodes and would truncate
-    // the walk).
+    // `optional` is DERIVED here on BOTH paths for the same reason
+    // `applyPlatformFilter` is: the answer must not depend on how the tree arrived,
+    // and a flag read back from a file is an INPUT nothing checked. Order matters —
+    // before `writeLockfile` (so the persisted flag is final), before the platform
+    // verdict (which reads it for fatal vs. inert), and before the workspace filter
+    // below (which removes nodes and would truncate the walk).
     computeOptionalFlags(nodes, requiredTopLevelNames(opts.specs, opts.optionalSpecs), log);
     assertRequiredEdgesResolved(nodes, skippedEdges);
     if (resolved && opts.lockfile) {
@@ -245,15 +209,13 @@ async function installPackagesNativeLocked(opts, npmrc, log) {
         writeLockfile(lockfilePath, opts.specs, nodes);
         log('install: wrote %s (%d entries)', LOCKFILE_NAME, nodes.length);
     }
-    // A package whose name is one of the monorepo's own workspaces is provided
-    // by a workspace symlink (wired by `workspaceInstall`), NOT by a registry
-    // tarball — even when the lockfile or a transitive edge pins a same-named
-    // published version. Drop those nodes from the fetch/extract set so
-    // `extractOne` never `rm`s + overwrites the workspace source symlink (its
-    // data-loss guard would otherwise abort the whole install). This keeps
+    // A package named after one of the monorepo's own workspaces is provided by a
+    // workspace symlink (wired by `workspaceInstall`), NOT by a registry tarball —
+    // even when the lockfile or a transitive edge pins a same-named published
+    // version. Dropping those nodes keeps `extractOne` from `rm`ing the workspace
+    // source symlink (its data-loss guard would abort the whole install), and keeps
     // `--immutable` robust against a committed lockfile that still carries such
-    // registry entries (it is built from the lockfile verbatim and never runs
-    // `resolveDeps`); a fresh resolve additionally skips them at the source.
+    // entries, since that path never runs `resolveDeps`.
     if (opts.workspaceNames && opts.workspaceNames.size > 0) {
         const before = nodes.length;
         nodes = nodes.filter((n) => !opts.workspaceNames.has(n.name));
@@ -271,9 +233,8 @@ async function installPackagesNativeLocked(opts, npmrc, log) {
     await linkBins(installable, opts.prefix, log);
     warnMissingNativeBuilds(installable, opts.prefix, log);
     log('install: done');
-    // Surface the top-level requested packages so callers can update
-    // package.json with the resolved version (mirrors `npm install --save`
-    // behavior). Sub-deps are not included.
+    // Top-level requested packages only, so callers can write the resolved version
+    // back into package.json (`npm install --save`).
     return topLevelResolutions(opts.specs, nodes);
 }
 function errMsg(err) {
@@ -282,29 +243,26 @@ function errMsg(err) {
     return String(err);
 }
 /**
- * Split a resolved tree into what THIS target can install, marking the rest
- * inert. Mirrors arborist's post-resolve platform pass
- * (`refs/npm-cli/workspaces/arborist/lib/arborist/build-ideal-tree.js`, the
- * `checkPlatform` loop around line 210) rather than filtering during the walk,
- * for two reasons: the verdict must be identical whether the tree came from a
- * fresh resolve or from `gjsify-lock.json`, and a node's optionality is only
- * final once every edge that could reach it has been visited.
+ * Split a resolved tree into what THIS target can install, marking the rest inert.
+ * A post-pass rather than a filter during the walk (as in arborist's
+ * `refs/npm-cli/workspaces/arborist/lib/arborist/build-ideal-tree.js`) for two
+ * reasons: the verdict must be identical whether the tree came from a fresh
+ * resolve or from `gjsify-lock.json`, and a node's optionality is only final once
+ * every edge that could reach it has been visited.
  *
  * The two outcomes are npm's, including the asymmetry around `force`:
- *   - REQUIRED + incompatible → EBADPLATFORM. A required dependency the host
- *     cannot run is a broken install, not a smaller one; failing loudly with
- *     `pkgid`/`current`/`required` is the only honest answer. `--force`
- *     suppresses it (the user is asserting something about their own machine).
- *   - OPTIONAL + incompatible → inert: not downloaded, not extracted, still in
- *     the lockfile. `--force` does NOT lift this — npm says so in as many words
- *     ("We ignore the --force and --engine-strict flags") and it is right:
- *     forcing an optional binary that cannot load buys a download and nothing
- *     else.
+ *   - REQUIRED + incompatible → EBADPLATFORM. A required dep the host cannot run
+ *     is a broken install, not a smaller one, so it fails loudly with
+ *     `pkgid`/`current`/`required`. `--force` suppresses it (the user is asserting
+ *     something about their own machine).
+ *   - OPTIONAL + incompatible → inert: not downloaded, not extracted, still in the
+ *     lockfile. `--force` does NOT lift this — npm says so in as many words ("We
+ *     ignore the --force and --engine-strict flags"), and forcing an optional
+ *     binary that cannot load buys a download and nothing else.
  *
- * The skip line goes through the debug logger with npm's `current`/`required`
- * payload, so `--verbose` recovers exactly WHY a package is absent. Silence
- * here is what made the original defect invisible in the other direction: 3.67
- * GB arrived with no line saying it should not have.
+ * The skip line carries npm's `current`/`required` payload so `--verbose` recovers
+ * WHY a package is absent. Silence here is what made the original defect invisible
+ * in the other direction: 3.67 GB arrived with no line saying it should not have.
  */
 export function applyPlatformFilter(nodes, target, force, log) {
     const installable = [];
@@ -343,15 +301,12 @@ export function applyPlatformFilter(nodes, target, force, log) {
 /**
  * Warn about a native package that installed WITHOUT a usable binary.
  *
- * gjsify install is node-free (it runs under GJS) and does NOT run a package's
- * `install`/`postinstall` lifecycle script — running e.g. `node-gyp rebuild` would
- * need Node + a C++ toolchain, breaking that property (see the header's "out of
- * scope"). Such a package works only if it SHIPS a prebuild for the platform (the
- * sanctioned path — `prebuilds/<platform>-<arch>/…`) or is later built by hand. When
- * neither is present the package silently loads no binary (the `@gjsify/node-gi
- * 0.21.0` case: installed, but `node_gi.node` absent → the consumer hit a runtime
- * failure with no hint). Surface it at install time with an actionable line. Pure
- * detection — no script is run, so node-free-ness is preserved.
+ * This install is node-free and does NOT run `install`/`postinstall` scripts —
+ * `node-gyp rebuild` would need Node plus a C++ toolchain. Such a package works
+ * only if it SHIPS a prebuild (`prebuilds/<platform>-<arch>/…`) or is built by
+ * hand; with neither it silently loads no binary, as `@gjsify/node-gi 0.21.0` did
+ * (installed, `node_gi.node` absent, consumer hit a runtime failure with no hint).
+ * Pure detection — no script is run, so node-free-ness is preserved.
  */
 export function warnMissingNativeBuilds(nodes, prefix, log) {
     const plat = process.platform;
@@ -404,8 +359,7 @@ export function warnMissingNativeBuilds(nodes, prefix, log) {
     }
 }
 function topLevelResolutions(specs, nodes) {
-    // Top-level installs live at `node_modules/<name>` (no nesting). Build
-    // a name → root-node lookup limited to the top-level set.
+    // Top-level installs live at `node_modules/<name>`, never nested.
     const byName = new Map();
     for (const n of nodes) {
         if (n.installPath === `node_modules/${n.name}`)
@@ -441,49 +395,39 @@ function parseSpecName(spec) {
  *     the root has an incompatible version. Subsequent dependents of the
  *     same conflicting version reuse the nested placement.
  *
- * The walk is BFS over (requester, depName, depRange) edges. Top-level
- * specs are seeded with a synthetic `null` requester so they hoist to
- * the root. Each placement returns a `ResolvedNode` whose `installPath`
- * captures where it lives in the tree.
+ * The walk is BFS over (requester, depName, depRange) edges. Top-level specs are
+ * seeded with a synthetic `null` requester so they hoist to the root.
  *
- * TAKES NO PLATFORM TARGET, and that is a load-bearing absence (header note,
- * invariant 1): the tree it produces and the `os`/`cpu`/`libc` it records must be
- * identical on every machine, so the platform verdict is a separate post-pass
- * (`applyPlatformFilter`) that this function cannot influence. An earlier draft
- * did take one — to decide when to escalate to a full packument for `libc`,
- * gated on `target.os === 'linux'` — and a macOS-authored lockfile ended up with
- * no `libc` recorded anywhere, i.e. unusable for filtering on the Linux hosts it
- * was committed for. Do not reintroduce the parameter: the resolve now reads the
- * full document unconditionally, which needs no target and no heuristic.
+ * TAKES NO PLATFORM TARGET, a load-bearing absence (header note, invariant 1): the
+ * tree and the `os`/`cpu`/`libc` it records must be identical on every machine, so the
+ * platform verdict is a separate post-pass this function cannot influence. Do not
+ * reintroduce the parameter — reading the full document unconditionally needs neither
+ * a target nor a heuristic.
  */
 async function resolveDeps(specs, npmrc, log, overrides, skipDeps, signal, progress, 
 /**
- * Lockfile-preservation oracle: `name → versions already pinned in the
- * existing lockfile`. When an edge's range is satisfiable by a pinned
- * version, that version is reused instead of the newest registry match.
- * Undefined ⇒ a fresh resolve that always picks the newest in-range version
- * (first install, or an explicit `--refresh-lockfile`).
+ * Lockfile-preservation oracle: `name → versions already pinned`. A pinned
+ * version satisfying the edge's range is reused instead of the newest registry
+ * match. Undefined ⇒ always pick the newest in-range version (first install, or
+ * `--refresh-lockfile`).
  */
 preferredVersions, 
 /**
- * Names of the monorepo's own workspace packages. An edge whose name is in
- * this set is satisfied by the workspace symlink, so it is skipped here —
- * the published version (and its subtree) never enters the resolved tree or
- * the lockfile.
+ * The monorepo's own workspace packages. Such an edge is satisfied by the
+ * workspace symlink, so it is skipped here — the published version and its
+ * subtree never enter the resolved tree or the lockfile.
  */
 workspaceNames, 
 /**
- * Requester labels for top-level specs (`"<name>@<range>"` → workspace
- * names) — see `InstallOptions.specOrigins`. Used only to attribute the
- * version-conflict warning.
+ * Requester labels for top-level specs (`"<name>@<range>"` → workspace names),
+ * see `InstallOptions.specOrigins`. Only attributes the conflict warning.
  */
 specOrigins, 
 /**
  * Names of top-level specs declared as `optionalDependencies` — see
- * {@link NativeInstallOptions.optionalSpecs}. Such an edge is seeded
- * `required: false`, so a resolve failure is skipped rather than fatal. It
- * also seeds the optional-flag walk, but the FINAL flag comes from
- * {@link computeOptionalFlags}, not from this walk.
+ * {@link NativeInstallOptions.optionalSpecs}. Seeds the edge `required: false`,
+ * so a resolve failure is skipped rather than fatal. The FINAL flag still comes
+ * from {@link computeOptionalFlags}, not from this walk.
  */
 optionalSpecs) {
     progress?.beginPhase('resolve', specs.length);
@@ -503,31 +447,26 @@ optionalSpecs) {
         const cached = packumentCache.get(name);
         if (cached)
             return cached;
-        // FULL document (`accept: application/json`), not the abbreviated
-        // "corgi" install document — the same choice arborist makes for every
-        // dependency it resolves (`#fetchManifest` sets `fullMetadata: true`,
+        // FULL document (`accept: application/json`), not the abbreviated "corgi"
+        // install document — the same choice arborist makes for every dependency it
+        // resolves (`#fetchManifest` sets `fullMetadata: true`,
         // refs/npm-cli/workspaces/arborist/lib/arborist/build-ideal-tree.js).
         //
-        // WHY, and why no cheaper trigger exists: the registry omits `libc` from
-        // the abbreviated body (measured — `@rollup/rollup-linux-x64-musl` returns
+        // WHY, and why no cheaper trigger exists: the registry omits `libc` from the
+        // abbreviated body (measured — `@rollup/rollup-linux-x64-musl` returns
         // `{os,cpu}` under the corgi accept header and `{os,cpu,libc}` under
-        // `application/json`), so the abbreviated body can never PROVE that a
-        // version has no libc restriction. Every "escalate only where it can
-        // matter" rule therefore has a hole, and the first draft's rule — escalate
-        // when the corgi entry declares `os` or `cpu` — had exactly the hole that
-        // matters here: the nine `@gjsify/*` bridges declare `libc: ["glibc"]`
-        // with NO `os`/`cpu`, so on Alpine the installer would have handed a
-        // glibc-only prebuild to a musl host and failed at `dlopen` instead of at
-        // install time.
+        // `application/json`), so that body can never PROVE a version has no libc
+        // restriction, and every "escalate only where it can matter" rule has a
+        // hole. The draft's rule — escalate when the corgi entry declares `os` or
+        // `cpu` — had exactly the hole that matters: the nine `@gjsify/*` bridges
+        // declare `libc: ["glibc"]` with NO `os`/`cpu`, so on Alpine the installer
+        // would have handed a glibc-only prebuild to a musl host and failed at
+        // `dlopen` instead of at install time.
         //
-        // Cost, measured over 15 representative deps of this workspace (transfer
-        // bytes, largest packages dominating): the full document is 1.26× the
-        // abbreviated one. Corgi-plus-escalate-everything would be 2.26× and
-        // twice the requests; corgi-plus-escalate-the-declaring-~12% (the draft)
-        // was ~1.15× and 1.12× the requests, i.e. this change costs ~10% more
-        // metadata bytes and ~11% FEWER round-trips than the shape it replaces.
-        // That is the whole trade: one authoritative document per package instead
-        // of two documents and a heuristic that cannot be made sound.
+        // The trade is one authoritative document per package instead of two plus an
+        // unsound heuristic; measured over 15 representative deps of this workspace,
+        // the full document costs 1.26× the abbreviated one in transfer bytes and
+        // ~11% FEWER round-trips than corgi-plus-escalate.
         const fresh = fetchPackumentWithDiskCache(name, npmrc, log, signal, 'full');
         packumentCache.set(name, fresh);
         return fresh;
@@ -538,15 +477,14 @@ optionalSpecs) {
     const root = new Map();
     /** See {@link ResolveResult.skippedEdges}. Keyed by {@link edgeKey}. */
     const skippedEdges = new Set();
-    // Top-level range bookkeeping for the version-conflict warning:
-    // `name → (applied range → requester labels)`. Only TOP-LEVEL specs
-    // participate: conflicting transitive edges are resolved correctly by
-    // nesting (Phase D.7b), but conflicting top-level specs — the shape
-    // `workspaceInstall` produces when two workspaces declare incompatible
-    // ranges of the same external dep — all compete for the single root
-    // slot, and today the resolver silently keeps one version for everyone
-    // (per-workspace dedup is Phase D.8). Until that lands, the conflict is
-    // surfaced loudly after the resolve (see emitTopLevelConflictWarnings).
+    // Bookkeeping for the version-conflict warning: `name → (applied range →
+    // requester labels)`. Only TOP-LEVEL specs participate — conflicting transitive
+    // edges are resolved correctly by nesting, but conflicting top-level specs (what
+    // `workspaceInstall` produces when two workspaces declare incompatible ranges of
+    // the same external dep) all compete for the single root slot and the resolver
+    // silently keeps one version for everyone. Per-workspace dedup is Phase D.8
+    // (status/open-todos.md); until it lands the conflict is surfaced loudly after
+    // the resolve (see emitTopLevelConflictWarnings).
     const topLevelRanges = new Map();
     const queue = specs.map(parseSpec).map((s) => {
         const range = applyOverride(s.name, s.range);
@@ -569,26 +507,19 @@ optionalSpecs) {
             required: !optionalSpecs?.has(s.name),
         };
     });
-    // Wave-based BFS. Each iteration drains the current queue level, prefetches
-    // every not-yet-cached packument in that level IN PARALLEL (bounded), then
-    // applies placement SERIALLY in the same FIFO order the single-edge loop
-    // used. Because newly-discovered children always append to the end of the
-    // queue, "the current queue contents" is exactly one BFS level — so the
-    // serial pass visits edges in the identical order, and `decidePlacement`'s
-    // order-dependent hoist/nest decisions (hence the lockfile) are byte-for-
-    // byte unchanged. Only the network moved: N sequential ~RTT packument
-    // fetches per level collapse into one bounded-parallel batch. This is the
-    // dominant cold-install cost — at libsoup's old `max-conns-per-host=2` it
-    // would have throttled anyway, so it lands alongside the connection-cap
-    // lift in `@gjsify/fetch`. `packumentCache` still guarantees ≤1 fetch per
-    // unique name across the whole resolve, so prefetching every wave name
-    // fetches exactly the same SET as before, just batched.
+    // Wave-based BFS: drain the current queue level, prefetch its not-yet-cached
+    // packuments in bounded parallel, then place SERIALLY in FIFO order. Newly
+    // discovered children always append, so "the current queue contents" is exactly
+    // one BFS level and the serial pass visits edges in the same order a single-edge
+    // loop would — which is what keeps `decidePlacement`'s order-dependent hoist/nest
+    // decisions, and hence the lockfile, unchanged. Only the network moved: N
+    // sequential ~RTT packument fetches per level collapse into one batch, the
+    // dominant cold-install cost. `packumentCache` still guarantees ≤1 fetch per
+    // unique name, so the same SET is fetched, just batched. Pointless before the
+    // `max-conns-per-host` lift in `@gjsify/fetch` — libsoup's default of 2 would
+    // have throttled it anyway.
     while (queue.length > 0) {
         const wave = queue.splice(0, queue.length);
-        // Prefetch every not-yet-cached packument referenced in this level.
-        // Names already in `packumentCache` (resolved in an earlier wave, or a
-        // duplicate within this one) are skipped — the de-dup keeps the batch
-        // to genuinely-new names.
         const toPrefetch = [];
         const queuedForFetch = new Set();
         for (const edge of wave) {
@@ -598,60 +529,47 @@ optionalSpecs) {
             toPrefetch.push(edge.name);
         }
         await prefetchPackuments(toPrefetch, fetchPkg, signal);
-        // Serial placement pass — identical decisions and order to the original
-        // single-edge loop, but every `fetchPkg` now resolves from the warmed
-        // cache instead of blocking on a fresh round-trip.
+        // Serial placement pass; every `fetchPkg` here resolves from the warmed cache
+        // instead of blocking on a fresh round-trip.
         for (let wi = 0; wi < wave.length; wi++) {
             const edge = wave[wi];
-            // A workspace member is satisfied by its workspace symlink, never by
-            // a registry tarball — skip the edge so the published version (and
-            // its subtree) never enters the resolved tree or the lockfile.
+            // A workspace member is satisfied by its symlink, never by a registry
+            // tarball — skip so the published version and its subtree never enter the
+            // resolved tree or the lockfile.
             if (workspaceNames?.has(edge.name))
                 continue;
-            // Walk the ancestor chain to see whether a satisfying placement is
-            // already visible from the requester's `node_modules` lookup. npm's
-            // resolver does this — each level of nesting acts as a fallback.
+            // Is a satisfying placement already visible from the requester's
+            // `node_modules` lookup? npm's resolver does the same — each level of
+            // nesting acts as a fallback.
             const visible = findVisible(edge.from, edge.name, byPath);
             if (visible && satisfiesRange(visible.version, edge.range)) {
-                // Compatible placement reachable; reuse, no new install.
-                //
-                // NOTHING IS PROMOTED HERE. A `visible.optional = false` on a
-                // required edge is the obvious move and it is wrong: the node's own
-                // dep edges were already queued with the STALE flag, so its
-                // children stayed optional and the one-shot promotion produced an
-                // order-dependent answer (the reviewed defect). Optionality is
-                // recomputed as a fixpoint over the finished graph instead —
-                // {@link computeOptionalFlags}, which is order-independent by
-                // construction and is the only writer of the final flag.
+                // Reuse; no new install. NOTHING IS PROMOTED HERE: setting
+                // `visible.optional = false` on a required edge is the obvious move
+                // and it is wrong, because the node's own dep edges were already
+                // queued with the STALE flag, so its children stay optional and the
+                // one-shot promotion answers by edge order (the reviewed defect).
+                // {@link computeOptionalFlags} is the only writer of the final flag.
                 continue;
             }
-            // No compatible existing placement. Resolve a version — preferring a
-            // version already pinned in the lockfile when it satisfies the range
-            // (so an add doesn't gratuitously bump unchanged deps).
+            // No compatible placement. Resolve a version, preferring one already
+            // pinned when it satisfies the range so an add does not bump unchanged
+            // deps.
             let version = null;
             try {
                 const packument = await fetchPkg(edge.name);
                 const preferred = preferredVersionFor(preferredVersions?.get(edge.name), edge.range);
                 version = pickVersion(packument, edge.range, preferred);
                 if (!version) {
-                    // Throw even for an optional edge and let the catch below
-                    // decide: ONE place that knows what a tolerated failure costs
-                    // (a log line and a `skippedEdges` entry). The `if
-                    // (!edge.required) continue` this replaces was a second,
-                    // silent copy of that decision — it skipped with no log line
-                    // at all and left nothing for the post-pass to re-judge.
+                    // Throw even for an optional edge and let the catch below decide:
+                    // ONE place knows what a tolerated failure costs (a log line and a
+                    // `skippedEdges` entry). A bare `if (!edge.required) continue` here
+                    // skipped silently and left nothing for the post-pass to re-judge.
                     throw new Error(`No version of ${edge.name} satisfies ${edge.range}`);
                 }
                 const v = packument.versions[version];
                 if (!v) {
                     throw new Error(`Packument for ${edge.name} promised ${version} but no entry exists`);
                 }
-                // Decision: hoist to root, or nest under the requester?
-                //   - Hoist iff the root has no conflicting placement (i.e. the
-                //     root slot for `name` is empty OR holds the same version).
-                //   - Otherwise nest. Top-level specs (from === null) always
-                //     hoist; the resolver guarantees they never conflict with
-                //     each other because the input set is checked once.
                 const installPath = decidePlacement(edge.from, edge.name, version, root);
                 const node = {
                     name: edge.name,
@@ -662,14 +580,13 @@ optionalSpecs) {
                     dependencies: v.dependencies ?? {},
                     optionalDependencies: v.optionalDependencies ?? {},
                     bin: v.bin,
-                    // Complete as published — `fetchPkg` reads the FULL document,
-                    // so all three fields come from one authoritative body and no
-                    // second fetch or per-package heuristic is involved.
+                    // Complete as published: `fetchPkg` reads the FULL document, so all
+                    // three fields come from one body — no second fetch, no heuristic.
                     platform: platformDeclarationOf(v),
-                    // Forward guess only; `computeOptionalFlags` overwrites it.
-                    // It is still worth setting: the child edges queued below read
-                    // it, which is what keeps a failure under a plainly-optional
-                    // subtree non-fatal at the point of failure.
+                    // Forward guess only; `computeOptionalFlags` overwrites it. Still
+                    // worth setting, because the child edges queued below read it, which
+                    // is what keeps a failure under a plainly-optional subtree non-fatal
+                    // at the point of failure.
                     optional: !edge.required,
                 };
                 byPath.set(installPath, node);
@@ -677,9 +594,8 @@ optionalSpecs) {
                     root.set(edge.name, node);
                 }
                 log('resolve: %s@%s ← %s (at %s)', edge.name, version, edge.range, installPath);
-                // Moving soft-total: resolved so far + edges still to visit in
-                // this wave + children already queued for the next wave. Same
-                // converging-estimate pattern yarn/pnpm use.
+                // Moving soft-total: resolved so far + edges left in this wave +
+                // children queued for the next. The converging estimate yarn/pnpm use.
                 progress?.update({
                     phase: 'resolve',
                     current: byPath.size,
@@ -688,25 +604,22 @@ optionalSpecs) {
                 });
                 if (!skipDeps) {
                     // REQUIRED edges only — a name this package also lists in
-                    // `optionalDependencies` is queued by the loop below instead,
-                    // once, as optional (header note, invariant 3). Queuing it here
-                    // as well would place it with a `required: true` forward guess,
-                    // making a resolve failure fatal and (via the fixpoint) its
-                    // incompatible platform siblings fatal too.
+                    // `optionalDependencies` is queued once by the loop below, as
+                    // optional (header note, invariant 3). Queuing it here too would
+                    // place it with a `required: true` forward guess, making a resolve
+                    // failure fatal and, via the fixpoint, its incompatible platform
+                    // siblings fatal too.
                     for (const [depName, depRange] of requiredDepEntries(node)) {
                         queue.push({
                             from: installPath,
                             name: depName,
-                            // A dependency of an OPTIONAL node inherits its
-                            // optionality — npm's `optionalSet`. Load-bearing for
-                            // the platform check, not a nicety: we resolve
-                            // foreign-platform optional packages on purpose (the
-                            // lockfile must stay portable), so their own required
-                            // deps get visited too. `fsevents` (darwin-only) is
-                            // the live shape — treating its subtree as required
-                            // would raise EBADPLATFORM for a package nothing on
-                            // this host will ever load, i.e. fail every Linux
-                            // install over a darwin-only optional dep.
+                            // A dependency of an OPTIONAL node inherits its optionality
+                            // (npm's `optionalSet`). Load-bearing for the platform check:
+                            // foreign-platform optional packages are resolved on purpose
+                            // to keep the lockfile portable, so their own required deps
+                            // get visited too. Treating darwin-only `fsevents`' subtree as
+                            // required would fail every Linux install with EBADPLATFORM
+                            // over a package nothing on the host will ever load.
                             range: applyOverride(depName, depRange),
                             required: !node.optional,
                         });
@@ -722,15 +635,14 @@ optionalSpecs) {
                 }
             }
             catch (e) {
-                // Optional deps that fail to resolve are skipped — yarn/npm
-                // behavior. Required deps re-throw.
+                // Optional deps that fail to resolve are skipped (yarn/npm behaviour);
+                // required deps re-throw.
                 if (!edge.required) {
-                    // RECORDED, not merely logged: `edge.required` is the walk's
-                    // forward guess, and a later required edge can still make this
-                    // node mandatory. `assertRequiredEdgesResolved` re-judges every
-                    // entry against the fixpoint flags, so a genuinely required
-                    // dependency cannot end up missing from the tree just because
-                    // BFS order happened to reach it through an optional edge first.
+                    // RECORDED, not merely logged: `edge.required` is the walk's forward
+                    // guess and a later required edge can still make this node mandatory.
+                    // `assertRequiredEdgesResolved` re-judges every entry against the
+                    // fixpoint flags, so a genuinely required dependency cannot go missing
+                    // just because BFS reached it through an optional edge first.
                     skippedEdges.add(edgeKey(edge.from, edge.name));
                     log('resolve: optional dep %s@%s skipped (%s)', edge.name, edge.range, errMsg(e));
                     continue;
@@ -741,24 +653,20 @@ optionalSpecs) {
     }
     progress?.endPhase('resolve');
     emitTopLevelConflictWarnings(topLevelRanges, root);
-    // NO declaration post-pass here, deliberately. `fetchPkg` already read the
-    // FULL document for every package, so each node's `platform` is complete as
-    // published and there is nothing left to escalate. The draft DID have a
-    // second `libc`-only fetch at exactly this line, and it took the platform
-    // target to decide when to fire — the one argument this function must never
-    // have (header note, invariant 1). Reintroducing the pass means
-    // reintroducing the parameter, which is how a macOS-authored lockfile ended
-    // up with no `libc` recorded for anyone.
+    // NO declaration post-pass here, deliberately: `fetchPkg` read the FULL document for
+    // every package, so each `platform` is complete as published. The draft's second
+    // `libc`-only fetch sat at exactly this line and needed the platform target to
+    // decide when to fire — reintroducing the pass reintroduces the one argument this
+    // function must never have (header note, invariant 1).
     //
-    // `optional` is likewise NOT finalised here: the flags on these nodes are
-    // still the walk's forward guess. `computeOptionalFlags` overwrites them at
-    // the call site, on this path and on the lockfile path alike.
+    // `optional` is likewise NOT finalised here; these flags are still the walk's
+    // forward guess, overwritten by `computeOptionalFlags` at the call site.
     return { nodes: Array.from(byPath.values()), skippedEdges };
 }
 /**
  * The platform declaration a packument version carries, or undefined when it
- * declares none (the common case — keeping it undefined keeps the node and the
- * lockfile entry minimal). Pure read, no I/O.
+ * declares none (the common case — undefined keeps the node and the lockfile entry
+ * minimal).
  */
 function platformDeclarationOf(version) {
     const declaration = { os: version.os, cpu: version.cpu, libc: version.libc };
@@ -768,19 +676,17 @@ function platformDeclarationOf(version) {
  * Identity of one dependency EDGE: the requester's `installPath` (empty string
  * for the project root) plus the dependency name.
  *
- * The PAIR is the identity, never the name alone. The same unresolvable name can
- * be legitimately absent below an optional subtree and a hard error below a
- * required one — only the requester says which, so a `skippedEdges` keyed by
- * name would collapse the two cases and answer whichever it saw last.
+ * The PAIR is the identity, never the name alone: the same unresolvable name can be
+ * legitimately absent below an optional subtree and a hard error below a required
+ * one, and only the requester says which — a `skippedEdges` keyed by name would
+ * collapse the two and answer whichever it saw last.
  *
- * `\n` is the separator because no npm package name and no install path can
- * contain one (npm rejects control characters in names, and every path here is
- * built out of names), so the key round-trips through {@link parseEdgeKey}
+ * `\n` separates because no npm package name and no install path can contain one
+ * (npm rejects control characters in names, and every path here is built out of
+ * names), so the key round-trips through {@link parseEdgeKey}
  * unambiguously. Deliberately NOT `\u0000`, the other obvious choice: the GJS
- * bundle minifier rewrites that escape into a raw NUL byte and GJS then refuses
- * to parse the bundle at all ("template literal not terminated"). A separator
- * that only fails once this file is bundled for the runtime it ships on is not
- * worth the theoretical tidiness.
+ * bundle minifier rewrites that escape into a raw NUL byte and GJS then refuses to
+ * parse the bundle at all ("template literal not terminated").
  */
 function edgeKey(from, name) {
     return `${from ?? ''}\n${name}`;
@@ -792,19 +698,19 @@ function parseEdgeKey(key) {
     return { from: from === '' ? null : from, name: key.slice(sep + 1) };
 }
 /**
- * Seed set for {@link computeOptionalFlags}: the NAMES of the top-level specs
- * the project did not declare optional. Everything else in the tree has to EARN
- * its required status by being reachable from one of these.
+ * Seed set for {@link computeOptionalFlags}: the NAMES of the top-level specs the
+ * project did not declare optional. Everything else must EARN its required status
+ * by being reachable from one of these.
  *
  * The parse is load-bearing. `specs` are flat `"<name>@<range>"` strings while
  * `optionalSpecs` holds bare NAMES (the range differs per requester — see
- * {@link NativeInstallOptions.optionalSpecs}), so testing a spec string against
- * the set is a lookup that can never hit: every top-level optionalDependency
- * would be seeded as REQUIRED, and the `optionalDependencies: { fsevents }`
- * shape would fail every Linux install with EBADPLATFORM instead of thinning.
- * An earlier version of this walk compared the two directly and did exactly
- * that; the `(c) an incompatible OPTIONAL top-level dep is skipped, not fatal`
- * case in `tests/e2e/install-platform-filter` is where it is pinned.
+ * {@link NativeInstallOptions.optionalSpecs}), so testing a spec string against the
+ * set is a lookup that can never hit: every top-level optionalDependency would be
+ * seeded REQUIRED and the `optionalDependencies: { fsevents }` shape would fail
+ * every Linux install with EBADPLATFORM instead of thinning. An earlier version
+ * compared the two directly and did exactly that; pinned by the "incompatible
+ * OPTIONAL top-level dep is skipped, not fatal" case in
+ * `tests/e2e/install-platform-filter`.
  */
 function requiredTopLevelNames(specs, optionalSpecs) {
     const names = new Set();
@@ -817,27 +723,21 @@ function requiredTopLevelNames(specs, optionalSpecs) {
     return names;
 }
 /**
- * A node's REQUIRED dependency edges: its `dependencies`, minus every name its
- * `optionalDependencies` also lists. The one place that decides what kind an edge
- * is — both the resolve walk and the optionality fixpoint read it, so the two
- * cannot drift.
+ * A node's REQUIRED dependency edges: its `dependencies` minus every name its
+ * `optionalDependencies` also lists. The ONE place that decides an edge's kind —
+ * both the resolve walk and the optionality fixpoint read it, so they cannot drift.
  *
- * THE SUBTRACTION IS npm's RULE, not a policy of ours: "entries in
- * optionalDependencies will override entries of the same name in dependencies, so
- * it's usually best to only put in one place" (npm's package.json docs). Measured
- * on `@parcel/rust@2.16.4`, which lists all eight per-platform napi packages in
- * both blocks: `npm install` exits 0, installs `@parcel/rust-linux-x64-gnu` only,
- * and writes `"optional": true` for all eight in its `package-lock.json`.
+ * The subtraction is npm's rule, not ours: "entries in optionalDependencies will
+ * override entries of the same name in dependencies" (npm's package.json docs).
  *
- * WHY IT IS NOT MERELY A DEDUP: the kind decides what an incompatible
- * `os`/`cpu`/`libc` MEANS (`applyPlatformFilter` — fatal vs. inert) and whether a
- * failed resolve is tolerated. Reading `dependencies` alone therefore does not
- * just visit a name twice, it promotes a foreign-platform binary to a required
- * dependency and fails installs npm completes.
+ * NOT MERELY A DEDUP: the kind decides what an incompatible `os`/`cpu`/`libc` MEANS
+ * (fatal vs. inert in `applyPlatformFilter`) and whether a failed resolve is
+ * tolerated. Reading `dependencies` alone does not just visit a name twice, it
+ * promotes a foreign-platform binary to a required dependency and fails installs npm
+ * completes — the header note's invariant 3.
  *
- * The inverse direction is deliberately NOT symmetric: a name in
- * `optionalDependencies` alone is optional (no `dependencies` entry to override),
- * which is what {@link resolveDeps}'s second queue loop covers.
+ * Deliberately NOT symmetric: a name in `optionalDependencies` alone is optional (no
+ * `dependencies` entry to override), covered by {@link resolveDeps}'s second queue loop.
  */
 export function requiredDepEntries(node) {
     const entries = [];
@@ -849,51 +749,38 @@ export function requiredDepEntries(node) {
     return entries;
 }
 /**
- * Recompute every node's `optional` flag as a FIXPOINT over the placed graph.
- * The only writer of the final flag; whatever the nodes arrive carrying is an
- * input nothing checked (a BFS forward guess on the resolve path, a value read
- * back out of a file on the lockfile path) and is overwritten unconditionally.
+ * Recompute every node's `optional` flag as a FIXPOINT over the placed graph. The
+ * only writer of the final flag; whatever the nodes arrive carrying is an input
+ * nothing checked (a BFS forward guess on the resolve path, a value read out of a
+ * file on the lockfile path) and is overwritten unconditionally.
  *
- * DEFINITION: a node is REQUIRED iff it is reachable from `requiredNames`
- * through REQUIRED edges alone ({@link requiredDepEntries} — `dependencies` minus
- * the names `optionalDependencies` overrides); every other node is optional.
- * Optionality is therefore INHERITED — a plain dependency OF an optional package
- * is still optional — which is what npm's `optionalSet` computes.
+ * DEFINITION: a node is REQUIRED iff reachable from `requiredNames` through
+ * REQUIRED edges alone ({@link requiredDepEntries}); every other node is optional.
+ * Optionality is therefore INHERITED — a plain dependency OF an optional package is
+ * still optional, which is what npm's `optionalSet` computes.
  *
  * WHY A FIXPOINT AND NOT A ONE-SHOT PROMOTION AT THE REUSE SITE (the reviewed
- * defect): the walk queues a node's own dep edges at the moment it is placed,
- * carrying the optionality it had THEN. Promoting the node later leaves its
- * children behind, so the answer depends on which edge BFS happened to traverse
- * first — a genuinely required transitive dep reached first through an optional
- * edge stayed flagged optional, was persisted that way, and was then silently
- * skipped by the platform filter on every machine instead of raising
- * EBADPLATFORM. A monotone worklist over the FINISHED graph cannot have that
- * property: "required" only ever spreads, so the result is independent of visit
- * order. npm reaches for the same shape and says so —
- * refs/npm-cli/workspaces/arborist/lib/calc-dep-flags.js: "If a node is changed,
- * we add to the queue and continue until no more changes."
+ * defect): the walk queues a node's dep edges when it is placed, carrying the
+ * optionality it had THEN, so promoting the node later leaves its children behind and
+ * the answer depends on which edge BFS traversed first. A required transitive dep
+ * reached first through an optional edge stayed flagged optional, was persisted that
+ * way, and was then silently skipped by the platform filter on every machine instead
+ * of raising EBADPLATFORM. A monotone worklist over the FINISHED graph cannot have
+ * that property: "required" only ever spreads, so the result is order-independent.
+ * Same shape as refs/npm-cli/workspaces/arborist/lib/calc-dep-flags.js.
  *
- * PATH-INDEPENDENCE IS THE OTHER REQUIREMENT, and it is why the lockfile carries
- * an `optionalDependencies` map per entry (v4). The walk USED to read
- * `dependencies` only, for exactly that reason — a lockfile entry recorded nothing
- * else, so consulting `node.optionalDependencies` would have made the two paths
- * compute different flags for the same tree. The premise was fixable and the
- * consequence was not: a publisher listing the same name in BOTH blocks means
- * "optional" to npm, came out REQUIRED here, and the shape is not rare — it is
- * `@parcel/rust@2.16.4` (all eight per-platform napi packages in both blocks), so
- * every Linux install of any tree containing parcel failed with EBADPLATFORM on
- * `@parcel/rust-darwin-x64` while `npm install` thinned the same tree and exited
- * 0. "Erring toward REQUIRED errs toward the loud failure" is true and was the
- * wrong trade: the loud failure was not a real one, and no `--force` lifts it
- * (nor should it). So the declaration is persisted and both paths subtract it.
- * Reading a pre-v4 lockfile leaves the map empty, which reproduces the old
- * behaviour for that file alone — see READABLE_LOCKFILE_VERSIONS.
+ * PATH-INDEPENDENCE is the other requirement, and why the lockfile carries an
+ * `optionalDependencies` map per entry (v4). This walk USED to read `dependencies`
+ * only, because a lockfile entry recorded nothing else and consulting
+ * `node.optionalDependencies` would have made the two paths compute different flags
+ * for one tree. That premise was fixable and its consequence — a both-blocks name
+ * coming out REQUIRED — was not (header note, invariant 3). A pre-v4 lockfile leaves
+ * the map empty and reproduces the old behaviour for that file alone
+ * (READABLE_LOCKFILE_VERSIONS).
  *
- * Runs before `writeLockfile` so the persisted flag is the final one, and before
- * `applyPlatformFilter` so the fatal-vs-inert decision reads it rather than the
- * guess. Exported so the unit spec can drive it with INJECTED graphs: the whole
- * fatal-vs-inert question is decided by these two functions in composition, and
- * that is worth pinning without a registry.
+ * Exported so the unit spec can drive it with INJECTED graphs — the whole
+ * fatal-vs-inert question is decided by this and `applyPlatformFilter` in
+ * composition, worth pinning without a registry.
  */
 export function computeOptionalFlags(nodes, requiredNames, log) {
     const byPath = new Map();
@@ -909,9 +796,9 @@ export function computeOptionalFlags(nodes, requiredNames, log) {
         required.add(node.installPath);
         worklist.push(node.installPath);
     };
-    // Top-level specs always hoist (`decidePlacement` returns the root slot for
-    // a null requester), so the seed lookup is exact. A name with no placement
-    // is a workspace member satisfied by its symlink — nothing to flag.
+    // Top-level specs always hoist (`decidePlacement` returns the root slot for a
+    // null requester), so the seed lookup is exact. A name with no placement is a
+    // workspace member satisfied by its symlink — nothing to flag.
     for (const name of requiredNames) {
         const seed = byPath.get(`node_modules/${name}`);
         if (seed)
@@ -934,11 +821,10 @@ export function computeOptionalFlags(nodes, requiredNames, log) {
                 enter(resolvedTo);
         }
     }
-    // Count the disagreements, don't just apply them. A nonzero `corrected` is
-    // the signal that the incoming flags (the walk's guess, or a lockfile
-    // written by an older CLI) were wrong for this tree — the class of bug this
-    // pass exists for, otherwise invisible because the corrected result looks
-    // exactly like a correct one.
+    // Count the disagreements, don't just apply them: a nonzero `corrected` is the
+    // signal that the incoming flags (the walk's guess, or a lockfile from an older
+    // CLI) were wrong for this tree. Otherwise invisible, because a corrected result
+    // looks exactly like a correct one.
     let corrected = 0;
     for (const node of nodes) {
         const optional = !required.has(node.installPath);
@@ -949,26 +835,22 @@ export function computeOptionalFlags(nodes, requiredNames, log) {
     log('install: optionality fixpoint — %d of %d node(s) reachable only via optional edges%s', nodes.length - required.size, nodes.length, corrected > 0 ? `; corrected ${corrected} incoming flag(s)` : '');
 }
 /**
- * Re-judge every failure the resolve swallowed against the FIXPOINT flags, and
- * throw if one of them turned out to be required after all.
+ * Re-judge every failure the resolve swallowed against the FIXPOINT flags, and throw
+ * if one turned out to be required after all.
  *
- * `resolveDeps` tolerates a failed edge on the strength of `edge.required`,
- * which is a forward guess made while the graph was still incomplete. This is
- * the second half of that bargain: without it, a genuinely required dependency
- * disappears from the tree for no better reason than BFS reaching it through an
- * optional edge first — an install that "succeeded" and produced a tree that
- * cannot run, with the explanation confined to a `--verbose` line nobody read.
+ * `resolveDeps` tolerates a failed edge on the strength of `edge.required`, a
+ * forward guess made while the graph was incomplete. Without this second half of the
+ * bargain a genuinely required dependency disappears from the tree for no better
+ * reason than BFS reaching it through an optional edge first — an install that
+ * "succeeded" and produced a tree that cannot run, explained only by a `--verbose`
+ * line nobody read.
  *
- * Same shape as npm's `#pruneFailedOptional()` ("if (!node.optional) throw
- * node.errors[0]"), including its position AFTER the flag pass. The difference
- * is what we hold: npm placed a real (broken) Node and still has the original
- * error, we recorded only the edge — so the message has to name the edge and
- * point at the verbose line that carries the cause.
+ * Same shape and position as npm's `#pruneFailedOptional()` (after the flag pass).
+ * The difference is what we hold: npm placed a real broken Node and still has the
+ * original error, we recorded only the edge, so the message names the edge and points
+ * at the verbose line carrying the cause.
  *
- * Three tolerated cases, and each is a property of the EDGE, not of the tree:
- * a root edge the project itself declared optional, an edge under a subtree the
- * fixpoint says is optional-only, and a required node's own
- * `optionalDependencies` entry.
+ * The three tolerated cases below are each a property of the EDGE, not of the tree.
  */
 function assertRequiredEdgesResolved(nodes, skippedEdges) {
     if (skippedEdges.size === 0)
@@ -978,35 +860,28 @@ function assertRequiredEdgesResolved(nodes, skippedEdges) {
         byPath.set(node.installPath, node);
     for (const key of skippedEdges) {
         const { from, name } = parseEdgeKey(key);
-        // Top-level edge: tolerated only because the project's own manifest put
-        // the spec in `optionalDependencies` (that is the ONLY way
-        // `requiredTopLevelNames` leaves it out of the seed set). The manifest
-        // is the whole truth for a root edge — no later edge can revise it.
+        // Top-level edge: tolerated only because the project's own manifest put the
+        // spec in `optionalDependencies` (the ONLY way `requiredTopLevelNames` leaves
+        // it out of the seed set), and no later edge can revise the manifest.
         if (from === null)
             continue;
         const requester = byPath.get(from);
-        // Requester never made it into the tree. Nothing depends on this edge
-        // any more, so nothing is missing.
+        // Requester never made it into the tree, so nothing depends on this edge.
         if (!requester)
             continue;
-        // The whole subtree is reachable only through optional edges — npm's
-        // `optionalSet`, skipped in silence.
+        // The whole subtree is optional-only — npm's `optionalSet`, skipped silently.
         if (requester.optional)
             continue;
-        // A REQUIRED package's own optionalDependency stays optional whatever
-        // the package's flag says: optionality lives on the edge, not on its
-        // endpoints (header note, invariant 3 — the same rule
-        // {@link requiredDepEntries} applies to the two graph walks). This branch
-        // is what keeps a darwin-only `fsevents` under a required `chokidar` from
-        // failing every Linux install.
-        //
-        // Membership, not `requiredDepEntries`: the failed edge may name something
-        // no longer in `dependencies` at all, and what is being asked here is
-        // whether the requester declared THIS name optional.
+        // A REQUIRED package's own optionalDependency stays optional whatever the
+        // package's flag says: optionality lives on the edge, not on its endpoints
+        // (header note, invariant 3). This branch is what keeps a darwin-only
+        // `fsevents` under a required `chokidar` from failing every Linux install.
         //
-        // Safe on both paths because `skippedEdges` is only ever non-empty on
-        // the fresh-resolve path, where `optionalDependencies` is populated; the
-        // lockfile paths resolve nothing and reach here with an empty set.
+        // Membership, not `requiredDepEntries`: the failed edge may name something no
+        // longer in `dependencies` at all, and the question is whether the requester
+        // declared THIS name optional. Safe on both paths — `skippedEdges` is only
+        // ever non-empty on the fresh-resolve path, where `optionalDependencies` is
+        // populated.
         if (name in requester.optionalDependencies)
             continue;
         throw new Error(`install: required dependency ${name} of ${requester.name}@${requester.version} ` +
@@ -1019,17 +894,15 @@ function assertRequiredEdgesResolved(nodes, skippedEdges) {
     }
 }
 /**
- * Loud, single-line-per-package warning for top-level version-range
- * conflicts (ADR 0001, step 3). Fires when two or more top-level specs
- * requested DIFFERENT ranges of the same package and the version that ended
- * up hoisted to the root does not satisfy all of them — i.e. some requester
- * silently got a version outside its declared range. Compatible ranges
- * (`^1.2` + `^1.4` both satisfied by `1.9.0`) stay silent; ranges that are
- * not semver (dist-tags like `latest`) cannot be compared and are skipped.
+ * Loud one-line-per-package warning for top-level version-range conflicts (ADR
+ * 0001). Fires when two or more top-level specs requested DIFFERENT ranges of the
+ * same package and the version hoisted to the root does not satisfy all of them, so
+ * some requester silently got a version outside its declared range. Compatible
+ * ranges (`^1.2` + `^1.4` both satisfied by `1.9.0`) stay silent; non-semver ranges
+ * (dist-tags like `latest`) cannot be compared and are skipped.
  *
- * This makes the current single-root-slot behavior honest instead of silent;
- * the real fix — a per-workspace dedup pass that gives each conflicting
- * requester its own nested copy — is Phase D.8 (see status/open-todos.md).
+ * This makes the single-root-slot behaviour honest rather than silent; the real fix
+ * is a per-workspace dedup pass, Phase D.8 (status/open-todos.md).
  */
 function emitTopLevelConflictWarnings(topLevelRanges, root) {
     for (const [name, ranges] of topLevelRanges) {
@@ -1060,27 +933,17 @@ function emitTopLevelConflictWarnings(topLevelRanges, root) {
     }
 }
 /**
- * Warm `packumentCache` for a batch of package names with bounded parallelism
- * (same `DEFAULT_CONCURRENCY` width as the download pool). Rejections — e.g. a
- * 404 on an optional dep — are swallowed here: the promise stays cached in its
- * rejected state and the caller's per-edge `await fetchPkg(name)` re-surfaces
- * it, so required deps still throw and optional ones are skipped exactly as in
- * the single-edge path. Swallowing also stops one bad optional dependency from
- * aborting the whole wave's batch.
- */
-/**
- * Fetch a packument with on-disk ETag revalidation. Reads the cached
- * `{ etag, packument }` for `(registry, name)`, sends it as `If-None-Match`,
- * and on a `304 Not Modified` returns the cached body without re-downloading
- * it; on a `200` it stores the fresh body + ETag and returns it. The cache is
- * keyed by the registry the name resolves to, so scope-registry overrides never
- * cross-contaminate. Falls back to a plain fetch when there's no cached entry
- * or the registry doesn't send an ETag (the 304 fast-path simply never fires).
+ * Fetch a packument with on-disk ETag revalidation: the cached
+ * `{ etag, packument }` for `(registry, name)` goes out as `If-None-Match`, a `304`
+ * returns the cached body, a `200` stores the fresh body + ETag. Keyed by the
+ * registry the NAME resolves to, so scope-registry overrides never
+ * cross-contaminate. Falls back to a plain fetch with no cached entry or no ETag
+ * from the registry (the 304 fast-path then simply never fires).
  *
- * `shape` selects WHICH document: `'corgi'` (abbreviated — every resolve) or
- * `'full'` (the escalation that carries `libc`). It is threaded all the way
- * through — request `accept`, cache read AND cache write — because the two are
- * different bodies with independently-versioned ETags for one URL. Mixing them
+ * `shape` selects WHICH document — `'corgi'` (abbreviated) or `'full'`, the only one
+ * this backend's resolve asks for because it is the only one carrying `libc`. It is
+ * threaded through request `accept`, cache read AND cache write, because the two are
+ * different bodies with independently-versioned ETags for one URL; mixing them
  * anywhere in that chain produces a `libc`-less body that looks like a hit.
  */
 async function fetchPackumentWithDiskCache(name, npmrc, log, signal, shape = 'corgi') {
@@ -1106,10 +969,18 @@ async function fetchPackumentWithDiskCache(name, npmrc, log, signal, shape = 'co
             putCachedPackument(registry, name, result.etag, result.packument, shape);
         return result.packument;
     }
-    // 304 with no cached body to satisfy it (a stale `If-None-Match` raced a
-    // cache eviction). Re-fetch unconditionally so we always return a body.
+    // 304 with no cached body to satisfy it — a stale `If-None-Match` raced a cache
+    // eviction. Re-fetch unconditionally so a body is always returned.
     return fetchPackument(name, { npmrc, signal, fullMetadata, onRetry });
 }
+/**
+ * Warm `packumentCache` for a batch of names with bounded parallelism (the download
+ * pool's `DEFAULT_CONCURRENCY` width). Rejections — a 404 on an optional dep, say —
+ * are swallowed: the promise stays cached in its rejected state and the caller's
+ * per-edge `await fetchPkg(name)` re-surfaces it, so required deps still throw and
+ * optional ones are skipped exactly as on the single-edge path. Swallowing also stops
+ * one bad optional dependency from aborting the whole wave's batch.
+ */
 async function prefetchPackuments(names, fetchPkg, signal) {
     if (names.length === 0)
         return;
@@ -1131,27 +1002,18 @@ async function prefetchPackuments(names, fetchPkg, signal) {
     await Promise.all(Array.from({ length: concurrency }, () => worker()));
 }
 /**
- * Walk the ancestor `node_modules` chain from `requesterPath` upward,
- * looking for a placement of `name` that the requester would resolve
- * through Node's CommonJS lookup. Returns the first match — that's the
- * one the requester actually sees at runtime.
+ * The placement of `name` that `requesterPath` would resolve through Node's
+ * `node_modules` lookup — its own nested copy first (nested deps shadow ancestor
+ * ones), then each ancestor, then the root. The first match is what the requester
+ * actually sees at runtime.
  */
 function findVisible(requesterPath, name, byPath) {
-    // From the requester's directory, Node walks up node_modules dirs
-    // looking for `<dir>/node_modules/<name>`. Translate that to lockfile
-    // paths: any prefix of the requester's `installPath` that ends in a
-    // package directory gives a candidate `<prefix>/node_modules/<name>`.
-    //
-    // The requester itself ALSO checks its OWN `node_modules` first
-    // (i.e. `<requesterPath>/node_modules/<name>` — nested deps shadow
-    // ancestor ones). Then it walks up.
     const candidates = [];
     if (requesterPath !== null) {
         candidates.push(`${requesterPath}/node_modules/${name}`);
-        // Walk up: strip the last `/node_modules/<pkg>` segment and try again.
+        // Walk up by stripping the deepest `/node_modules/<pkg>` segment each time.
         let p = requesterPath;
         while (true) {
-            // Find the deepest `/node_modules/<pkg>` in `p`, strip it.
             const idx = p.lastIndexOf('/node_modules/');
             if (idx < 0)
                 break;
@@ -1161,8 +1023,7 @@ function findVisible(requesterPath, name, byPath) {
                 break;
         }
     }
-    // The root `node_modules/<name>` is the final candidate (covers the
-    // `requesterPath === null` case too).
+    // Also covers `requesterPath === null`.
     candidates.push(`node_modules/${name}`);
     for (const candidate of candidates) {
         const hit = byPath.get(candidate);
@@ -1172,13 +1033,10 @@ function findVisible(requesterPath, name, byPath) {
     return null;
 }
 /**
- * Decide where to install `name@version` for a request from `requesterPath`.
- *
- *   - Root is empty for `name`: hoist (return `node_modules/<name>`).
- *   - Root has the SAME version: reuse the root placement.
- *   - Root has a DIFFERENT version: nest under the requester.
- *
- * Top-level requesters (requesterPath === null) always hoist.
+ * Where to install `name@version` for a request from `requesterPath`: hoist to
+ * `node_modules/<name>` when the root slot is empty or already holds this version,
+ * nest under the requester when the root holds a different one. Top-level requesters
+ * (`requesterPath === null`) always hoist.
  */
 function decidePlacement(requesterPath, name, version, root) {
     const rootSlot = root.get(name);
@@ -1187,16 +1045,15 @@ function decidePlacement(requesterPath, name, version, root) {
     if (rootSlot.version === version)
         return `node_modules/${name}`;
     if (requesterPath === null) {
-        // Top-level specs are deduplicated by the caller before reaching
-        // here; this branch is defensive (would only fire on a duplicate
-        // top-level spec with conflicting versions).
+        // Defensive: the caller dedups top-level specs, so this only fires on a
+        // duplicate top-level spec with conflicting versions.
         return `node_modules/${name}`;
     }
     return `${requesterPath}/node_modules/${name}`;
 }
 function satisfiesRange(version, range) {
-    // dist-tag (e.g. `latest`) cannot be matched here — caller passed a
-    // raw range. Dist-tags only meaningful at fresh-resolve time.
+    // A dist-tag (`latest`) cannot be matched here; those are only meaningful at
+    // fresh-resolve time.
     try {
         return satisfies(version, new Range(range));
     }
@@ -1209,11 +1066,8 @@ function readLockfile(lockfilePath) {
         return null;
     try {
         const parsed = JSON.parse(fs.readFileSync(lockfilePath, 'utf-8'));
-        // Accept every readable version, not just the current one — see
-        // READABLE_LOCKFILE_VERSIONS for why returning null on a v2 file is
-        // worse than reading it. The caller decides what it may be used FOR:
-        // a v2 file seeds version preservation but never short-circuits the
-        // resolve, because it carries no platform declarations.
+        // Every readable version, not just the current one — READABLE_LOCKFILE_VERSIONS
+        // has the reason. The caller decides what it may be used FOR.
         if (!READABLE_LOCKFILE_VERSIONS.has(parsed.lockfileVersion))
             return null;
         if (!parsed.packages || typeof parsed.packages !== 'object')
@@ -1234,16 +1088,14 @@ function writeLockfile(lockfilePath, specs, nodes) {
             resolved: node.tarballUrl,
             integrity: node.integrity,
             dependencies: Object.keys(node.dependencies).length > 0 ? node.dependencies : undefined,
-            // The EDGE KINDS, for the same reason the platform declaration is
-            // here: `computeOptionalFlags` runs on the lockfile path too and
-            // cannot recompute what the file does not carry (v4, header note
-            // invariant 3). Omitted when empty, which is most packages.
+            // The EDGE KINDS, for the same reason the platform declaration is here:
+            // `computeOptionalFlags` runs on the lockfile path too and cannot recompute
+            // what the file does not carry (v4, header note invariant 3).
             optionalDependencies: Object.keys(node.optionalDependencies).length > 0 ? node.optionalDependencies : undefined,
             bin: node.bin,
-            // The DECLARATION, never the verdict: `inert` is per-host and
-            // deliberately absent from the file (a lockfile that recorded which
-            // packages the author's machine skipped would install a different
-            // tree for everyone else — the failure this design exists to avoid).
+            // The DECLARATION, never the verdict: `inert` is per-host and deliberately
+            // absent from the file, since a lockfile recording which packages the
+            // author's machine skipped installs a different tree for everyone else.
             os: node.platform?.os,
             cpu: node.platform?.cpu,
             libc: node.platform?.libc,
@@ -1255,17 +1107,16 @@ function writeLockfile(lockfilePath, specs, nodes) {
         requested: [...specs],
         packages,
     };
-    // Atomic tmp+rename so a crash mid-write (or a reader racing the writer)
-    // can never observe a torn gjsify-lock.json — `--immutable` would
-    // otherwise hard-fail on the corrupt file with a misleading error.
+    // Atomic tmp+rename so a crash mid-write, or a reader racing the writer, can never
+    // observe a torn gjsify-lock.json — `--immutable` would otherwise hard-fail on the
+    // corrupt file with a misleading error.
     atomicWriteStrict(lockfilePath, JSON.stringify(lockfile, null, 2) + '\n');
 }
 /**
- * Build the lockfile-preservation oracle: `name → every version currently
- * pinned in the lockfile` (a name can appear at more than one install path /
- * version when the tree nested a conflicting copy). Consulted during a resolve
- * so unchanged deps keep their pinned version instead of bumping to the newest
- * in-range match.
+ * The lockfile-preservation oracle: `name → every version currently pinned` (a name
+ * can appear at more than one path/version when the tree nested a conflicting copy).
+ * Consulted during a resolve so unchanged deps keep their pinned version instead of
+ * bumping to the newest in-range match.
  */
 function buildPreferredVersions(lockfile) {
     const byName = new Map();
@@ -1302,35 +1153,30 @@ function lockfileToNodes(lockfile) {
     return Object.entries(lockfile.packages).map(([installPath, entry]) => {
         const platform = { os: entry.os, cpu: entry.cpu, libc: entry.libc };
         return {
-            // Recover the package name from the path: the last segment is
-            // either `<name>` (unscoped) or `@scope/<name>` (scoped).
             name: nameFromInstallPath(installPath),
             version: entry.version,
             tarballUrl: entry.resolved,
             integrity: entry.integrity,
             installPath,
             dependencies: entry.dependencies ?? {},
-            // Empty for a pre-v4 entry, which is why such a file never
-            // short-circuits the resolve: with no edge kinds recorded, a name the
-            // publisher put in both blocks reads as required here (the pre-fix
-            // behaviour). `--immutable` is the one path that consumes it anyway —
-            // see READABLE_LOCKFILE_VERSIONS.
+            // Empty for a pre-v4 entry, which is why such a file never short-circuits
+            // the resolve: with no edge kinds recorded, a name the publisher put in both
+            // blocks reads as required here. `--immutable` consumes it anyway — see
+            // READABLE_LOCKFILE_VERSIONS.
             optionalDependencies: entry.optionalDependencies ?? {},
             bin: entry.bin,
-            // Rebuilt from the recorded declaration so `applyPlatformFilter`
-            // reaches the SAME verdict on this path as on the fresh-resolve
-            // path — for THIS host, which is generally not the host that wrote
-            // the file. A v2 entry has none of these fields, so nothing is
-            // filtered; that install behaves exactly as it did before the
-            // feature (see READABLE_LOCKFILE_VERSIONS).
+            // Rebuilt from the recorded declaration so `applyPlatformFilter` reaches the
+            // SAME verdict here as on the fresh-resolve path, for THIS host — generally
+            // not the host that wrote the file. A v2 entry has none of these fields, so
+            // nothing is filtered and the install behaves as it did pre-feature.
             platform: declaresPlatform(platform) ? platform : undefined,
             optional: entry.optional === true,
         };
     });
 }
 function nameFromInstallPath(installPath) {
-    // Last `node_modules/` boundary, then the rest is the package name
-    // (single segment unscoped, or `@scope/pkg` scoped).
+    // Everything after the last `node_modules/` boundary is the package name — one
+    // segment unscoped, `@scope/pkg` scoped.
     const idx = installPath.lastIndexOf('/node_modules/');
     const after = idx < 0 ? installPath.replace(/^node_modules\//, '') : installPath.slice(idx + '/node_modules/'.length);
     return after;
@@ -1343,10 +1189,9 @@ function lockfileMatchesRequest(lockfile, specs) {
     return a.every((v, i) => v === b[i]);
 }
 /**
- * Human-readable diff between `lockfile.requested` and the live request.
- * Returns null when the two sets are identical (the lockfile is in sync).
- * Used by `--immutable` to surface exactly which deps drifted, so CI
- * failures don't force the user to diff lockfile JSON by hand.
+ * Human-readable diff between `lockfile.requested` and the live request, or null when
+ * they are identical. `--immutable` uses it to name exactly which deps drifted, so a
+ * CI failure does not force the user to diff lockfile JSON by hand.
  */
 function describeLockfileDrift(lockfile, specs) {
     const lockSet = new Set(lockfile.requested);
@@ -1368,20 +1213,14 @@ function describeLockfileDrift(lockfile, specs) {
         lines.push(`  - ${removed.sort().join('\n  - ')}`);
     return lines.join('\n');
 }
-// Exported for unit-testing — keep the function name + signature
-// stable, the install-backend itself still calls it via the local
-// binding below. Internal API.
+// Internal API, exported for `install-backend-parse-spec.spec.ts`.
 export function parseSpec(raw) {
-    // Bare names without an explicit `@version` resolve to the `latest`
-    // dist-tag. This matches npm CLI behaviour (`npm install foo` →
-    // foo@latest) and — crucially — picks up prereleases when the
-    // publisher has tagged them as `latest`. Using semver `*` here
-    // would silently exclude any version with a `-` (rc, beta, alpha,
-    // …) suffix per semver §9 ("Pre-release versions have a lower
-    // precedence than the associated normal version"); ts-for-gir
-    // shipped only prereleases (4.0.0-rc.17 is the `latest` tag, no
-    // stable 4.x yet) and `*` was selecting the abandoned 3.3.0
-    // instead.
+    // A bare name resolves to the `latest` DIST-TAG, matching `npm install foo`, and
+    // that choice is what picks up prereleases the publisher tagged `latest`. Semver
+    // `*` would silently exclude every version with a `-` suffix (semver §9: "Pre-
+    // release versions have a lower precedence than the associated normal version");
+    // ts-for-gir shipped only prereleases (`latest` = 4.0.0-rc.17, no stable 4.x) and
+    // `*` selected the abandoned 3.3.0 instead.
     if (raw.startsWith('@')) {
         const slash = raw.indexOf('/');
         if (slash < 0)
@@ -1396,19 +1235,18 @@ export function parseSpec(raw) {
         return { name: raw, range: 'latest' };
     return { name: raw.slice(0, at), range: raw.slice(at + 1) || 'latest' };
 }
-// Exported for unit-testing. Internal API.
+// Internal API, exported for `install-backend-parse-spec.spec.ts`.
 export function pickVersion(packument, range, preferred) {
-    // Lockfile preservation: if a version already pinned in the lockfile still
-    // satisfies the range and is still published, reuse it instead of bumping to
-    // the newest match. `preferred` is only ever a concrete semver (never a
-    // dist-tag), so this never hijacks a `latest`/`next` range.
+    // Lockfile preservation: a pinned version that still satisfies the range and is
+    // still published is reused rather than bumped. `preferred` is only ever a concrete
+    // semver, never a dist-tag, so this cannot hijack a `latest`/`next` range.
     if (preferred && packument.versions[preferred] && satisfiesRange(preferred, range)) {
         return preferred;
     }
     // dist-tag fast path: `latest`, `next`, ...
     if (packument['dist-tags'][range])
         return packument['dist-tags'][range];
-    // Validate range early so a typo fails loudly.
+    // Validate the range early so a typo fails loudly.
     let parsedRange;
     try {
         parsedRange = new Range(range);
@@ -1428,17 +1266,15 @@ export function pickVersion(packument, range, preferred) {
     return maxSatisfying(versions, parsedRange);
 }
 async function downloadAndExtractAll(nodes, prefix, npmrc, log, signal, progress) {
-    // Sort by install-path depth ascending so parents extract before
-    // children. Extracting a parent on top of an existing child would
-    // wipe out the child.
+    // Depth ascending, so parents extract before children — extracting a parent on
+    // top of an existing child wipes the child out.
     const queue = [...nodes].sort((a, b) => depth(a.installPath) - depth(b.installPath) || (a.installPath < b.installPath ? -1 : 1));
     const workers = [];
     const concurrency = Math.max(1, Math.min(DEFAULT_CONCURRENCY, queue.length));
     progress?.beginPhase('download', queue.length);
     let completed = 0;
-    // Count how many nodes were already correctly materialised on disk and
-    // skipped (the npm "unchanged" set). Surfaced in the summary log so a warm
-    // install makes it obvious why the phase finished in seconds.
+    // Nodes already correctly materialised on disk (npm's "unchanged" set). Surfaced in
+    // the summary log so a warm install explains why the phase finished in seconds.
     let skipped = 0;
     const tickProgress = (node, wasSkipped) => {
         completed++;
@@ -1451,9 +1287,8 @@ async function downloadAndExtractAll(nodes, prefix, npmrc, log, signal, progress
             name: `${node.name}@${node.version}`,
         });
     };
-    // Parents (depth 1) are extracted serially first to avoid concurrent
-    // `rm -rf` + extract races with their children. Once depth-1 is done,
-    // depths >=2 run with full concurrency.
+    // Depth-1 parents extract serially first, to avoid `rm -rf` + extract racing their
+    // own children; depths ≥2 then run at full concurrency.
     let cursor = 0;
     const depth1End = queue.findIndex((n) => depth(n.installPath) > 1);
     const splitAt = depth1End < 0 ? queue.length : depth1End;
@@ -1471,13 +1306,11 @@ async function downloadAndExtractAll(nodes, prefix, npmrc, log, signal, progress
     for (let i = 0; i < concurrency; i++) {
         workers.push((async () => {
             while (true) {
-                // Honour an aborted overall-install budget inside the pool.
-                // Without this, a fired --timeout (or Ctrl-C) only aborts
-                // the NETWORK fetches; a tree that is mostly cache-hits /
-                // already-extracted keeps churning the extract loop to
-                // completion, so the install never actually stops when
-                // asked to (a contributor to the observed "it never
-                // completed; I killed it" hang).
+                // Honour an aborted overall-install budget inside the pool. Without
+                // this a fired --timeout (or Ctrl-C) aborts only the NETWORK fetches,
+                // so a mostly-cached tree churns the extract loop to completion and
+                // the install never stops when asked — one contributor to the observed
+                // "it never completed; I killed it" hang.
                 if (signal?.aborted)
                     throw abortError(signal);
                 const idx = cursor++;
@@ -1498,20 +1331,17 @@ async function downloadAndExtractAll(nodes, prefix, npmrc, log, signal, progress
     }
 }
 /**
- * Is `name@version` already correctly materialised at `dest`? Reads
- * `<dest>/package.json` and returns true iff its `name` AND `version` match the
- * resolved node exactly. This is the npm/yarn/pnpm "unchanged node" check — an
- * already-present, correct copy is skipped instead of being `rm`-ed and
- * re-extracted.
+ * Is `name@version` already correctly materialised at `dest`? The npm/yarn/pnpm
+ * "unchanged node" check: an already-present, correct copy is skipped instead of being
+ * `rm`-ed and re-extracted.
  *
- * Conservative by design: a missing / unreadable / unparseable package.json, or
- * ANY name/version mismatch, returns false so the caller falls through to the
- * full rm + extract. The only thing this fast-paths is the exact-match case,
- * which is the overwhelming majority of nodes on a warm re-install (the whole
- * resolved tree minus the genuinely-new subtree). Skipping the re-extract is
- * what turns a warm `gjsify install` on a 2000+-package workspace from a
- * many-minute re-extract of every tarball (each gunzip routed through GJS's
- * Gio.ZlibDecompressor on the single GLib main loop) into a near-instant no-op.
+ * Conservative by design — a missing/unreadable/unparseable package.json or ANY
+ * name/version mismatch returns false, so the caller falls through to the full rm +
+ * extract. Only the exact-match case is fast-pathed, which is the overwhelming
+ * majority of nodes on a warm re-install, and that is what turns a warm `gjsify
+ * install` on a 2000+-package workspace from a many-minute re-extract of every tarball
+ * (each gunzip routed through GJS's Gio.ZlibDecompressor on the single GLib main loop)
+ * into a near-instant no-op.
  */
 function isAlreadyExtracted(dest, node) {
     const manifestPath = path.join(dest, 'package.json');
@@ -1524,11 +1354,9 @@ function isAlreadyExtracted(dest, node) {
     }
     try {
         const parsed = JSON.parse(raw);
-        // Match version exactly. Match name too when present — a stale dir from
-        // a previous resolve could hold a different package at the same path
-        // (e.g. a nested placement that moved), in which case the version alone
-        // could coincidentally collide. A missing `name` (rare, malformed) is
-        // tolerated as long as the version matches.
+        // Name too, when present: a stale dir from a previous resolve can hold a
+        // different package at the same path (a nested placement that moved), where the
+        // version alone could coincidentally collide. A missing `name` is tolerated.
         if (parsed.version !== node.version)
             return false;
         if (typeof parsed.name === 'string' && parsed.name !== node.name)
@@ -1546,38 +1374,30 @@ function isAlreadyExtracted(dest, node) {
  */
 async function extractOne(node, prefix, npmrc, log, signal) {
     const dest = path.join(prefix, node.installPath);
-    // Defense-in-depth against the workspace-source-wipe data-loss bug:
-    // every extractable node MUST land inside a `node_modules/` directory.
-    // The resolver only ever produces `installPath`s of that shape, so this
-    // can only fail if a workspace package leaked into the fetch/extract
-    // queue (the root cause fixed in `workspaceInstall`). Refusing here means
-    // a regression in the resolver can never again `rmSync` a working-tree
-    // source dir — the realpath check additionally rejects a `dest` that
-    // resolves THROUGH a symlink into a directory outside node_modules.
+    // Defence-in-depth against the workspace-source-wipe data-loss bug: this can only
+    // fail if a workspace package leaked into the fetch/extract queue (the root cause
+    // fixed in `workspaceInstall`), and refusing here means a resolver regression can
+    // never again `rmSync` a working-tree source dir.
     assertNodeModulesDest(dest, node);
-    // Idempotent fast-path: the package is already extracted at the resolved
-    // version. Skip the cache read + rm + re-extract entirely — this is the
-    // npm/yarn/pnpm default (only added/changed nodes are written), and it is
-    // the dominant cost on a warm re-install. Force a full re-extract with
-    // GJSIFY_INSTALL_FORCE_EXTRACT=1 (debug / corrupted-tree recovery).
+    // Idempotent fast-path — skip the cache read + rm + re-extract for a node already
+    // extracted at the resolved version. The npm/yarn/pnpm default (only added/changed
+    // nodes are written) and the dominant cost on a warm re-install.
+    // GJSIFY_INSTALL_FORCE_EXTRACT=1 forces a full re-extract for corrupted-tree recovery.
     if (process.env.GJSIFY_INSTALL_FORCE_EXTRACT !== '1' && isAlreadyExtracted(dest, node)) {
         log('up-to-date: %s@%s (already extracted at %s)', node.name, node.version, node.installPath);
         return true;
     }
-    // Hit the content-addressable cache before touching the network.
-    // Tarballs are immutable per SRI integrity, so a hash hit means the
-    // cached bytes are byte-identical to whatever the registry would
-    // return — no need to verify by re-download.
+    // Content-addressable cache before the network: tarballs are immutable per SRI
+    // integrity, so a hash hit is byte-identical to what the registry would return and
+    // needs no verifying re-download.
     let bytes = getCachedTarball(node.integrity);
     if (bytes) {
         log('cache-hit: %s@%s ← %s', node.name, node.version, node.integrity);
     }
     else if ((bytes = getForeignCachedTarball(node.integrity))) {
-        // Second-chance: npm's cacache content store (same SRI key). A user
-        // who has run `npm install` before already has the tarball on disk —
-        // read it instead of the network. Write it through to OUR store so
-        // the next `gjsify install` is a first-class hit even if npm later
-        // prunes its cache.
+        // Second chance: npm's cacache content store, same SRI key — anyone who has run
+        // `npm install` already has the tarball on disk. Written through to OUR store so
+        // the next `gjsify install` hits first-class even if npm prunes its cache.
         log('npm-cache-hit: %s@%s ← %s', node.name, node.version, node.integrity);
         putCachedTarball(node.integrity, bytes);
     }
@@ -1591,35 +1411,31 @@ async function extractOne(node, prefix, npmrc, log, signal) {
                 log('tarball %s@%s: retry %d after %dms (%s)', node.name, node.version, attempt, delayMs, errMsg(error));
             },
         });
-        // Best-effort cache write — failures are swallowed by `putCachedTarball`
-        // so a read-only HOME / out-of-disk cache volume doesn't break the install.
+        // Best-effort: `putCachedTarball` swallows failures so a read-only HOME or an
+        // out-of-disk cache volume does not break the install.
         putCachedTarball(node.integrity, bytes);
     }
-    // `rmWithRetry` (not a bare rmSync): on Windows the delete of a freshly
-    // extracted tree fails with EBUSY/EPERM while any handle is still open, and
-    // stays pending afterwards — so the mkdirSync on the next line would hit
-    // EPERM/ENOTEMPTY. No-op cost on POSIX. This runs for EVERY package.
+    // `rmWithRetry`, not a bare rmSync: on Windows deleting a freshly extracted tree
+    // fails EBUSY/EPERM while any handle is open and stays pending afterwards, so the
+    // mkdirSync below would hit EPERM/ENOTEMPTY. No-op cost on POSIX.
     rmWithRetry(dest);
     fs.mkdirSync(dest, { recursive: true });
     await extractWithStallGuard(bytes, dest, node, signal);
     return false;
 }
 /**
- * Cap over `extractTarball`, which takes no AbortSignal and no timeout of its
- * own. A single tarball extract completes in well under a second even for
- * large packages; anything past `EXTRACT_STALL_MS` means the decompress/write
- * wedged — the classic dropped Gio stream close-event under GJS, a
- * never-settling await that nothing downstream can break. Unlike a network
- * fetch (30s per-request budget in @gjsify/npm-registry), extraction has no
- * self-healing path, so one stuck package used to hang the whole install at
- * 0% CPU indefinitely. We race the extract against (a) a stall timer and (b)
- * the overall-install abort signal, so a wedge surfaces as an actionable
- * error and the install fails fast instead of hanging.
+ * Cap over `extractTarball`, which takes no AbortSignal and no timeout of its own. One
+ * extract completes in well under a second even for large packages, so anything past
+ * `EXTRACT_STALL_MS` means the decompress/write wedged — the classic dropped Gio stream
+ * close-event under GJS, a never-settling await nothing downstream can break. Unlike a
+ * network fetch (30s per-request budget in @gjsify/npm-registry) extraction has no
+ * self-healing path, so one stuck package used to hang the whole install at 0% CPU
+ * indefinitely. Racing the extract against a stall timer AND the overall-install abort
+ * signal turns that into an actionable error.
  *
- * Rejecting the race does not tear down the underlying (leaked) extract
- * promise — the process exit that follows reclaims its resources. Override /
- * disable the cap via `GJSIFY_EXTRACT_STALL_MS` (0 disables the timer; the
- * signal race still applies).
+ * Rejecting the race does not tear down the leaked extract promise; the process exit
+ * that follows reclaims it. `GJSIFY_EXTRACT_STALL_MS=0` disables the timer, leaving the
+ * signal race in place.
  */
 const EXTRACT_STALL_MS = (() => {
     const raw = process.env.GJSIFY_EXTRACT_STALL_MS;
@@ -1629,7 +1445,7 @@ const EXTRACT_STALL_MS = (() => {
     return Number.isFinite(n) && n >= 0 ? n : 120_000;
 })();
 async function extractWithStallGuard(bytes, dest, node, signal) {
-    // Fast path: nothing to guard against (timer disabled + no signal).
+    // Nothing to guard against: timer disabled and no signal.
     if (EXTRACT_STALL_MS === 0 && !signal) {
         await extractTarball(bytes, dest);
         return;
@@ -1638,13 +1454,11 @@ async function extractWithStallGuard(bytes, dest, node, signal) {
     let onAbort;
     try {
         await new Promise((resolve, reject) => {
-            // Test seam (matches GJSIFY_INSTALL_FORCE_EXTRACT precedent): simulate
-            // an extract that never settles, so a suite can prove the stall timer
-            // + abort-signal race actually break the wedge. Never call
-            // extractTarball — leave the inner promise pending forever.
+            // Test seam: simulate an extract that never settles, so a suite can prove
+            // the stall timer + abort-signal race actually break the wedge.
             if (process.env.GJSIFY_TEST_HANG_EXTRACT !== '1') {
-                // extractTarball keeps running if we lose the race; its settlement
-                // (resolve or reject) is a no-op on the already-settled promise.
+                // extractTarball keeps running if it loses the race; its settlement is
+                // then a no-op on the already-settled promise.
                 extractTarball(bytes, dest).then(() => resolve(), reject);
             }
             if (EXTRACT_STALL_MS > 0) {
@@ -1689,19 +1503,16 @@ function abortError(signal) {
     return err;
 }
 /**
- * Guard: a tarball may only be extracted into a `node_modules/` directory.
+ * Guard: a tarball may only be extracted into a `node_modules/` directory. Two checks,
+ * both against ever wiping a working-tree source dir (the
+ * install-deletes-workspace-sources data-loss bug):
  *
- * Two checks, both belt-and-suspenders against ever wiping a working-tree
- * source dir (the install-deletes-workspace-sources data-loss bug):
- *
- *   1. The logical `installPath` must contain a `node_modules` path segment.
- *      The resolver always produces such paths; a workspace package that
- *      slipped into the queue would not.
- *   2. If `dest` already exists and resolves (via symlink) to a directory
- *      whose REAL path is not under a `node_modules/` segment, refuse. This
- *      catches the case where `node_modules/<name>` is a symlink to a
- *      workspace's source tree — `rmSync(dest, { recursive: true })` would
- *      then delete the link's target contents.
+ *   1. The logical `installPath` must contain a `node_modules` segment. The resolver
+ *      always produces such paths; a workspace package that slipped in would not.
+ *   2. An existing `dest` whose REAL path (after symlinks) is not under a
+ *      `node_modules/` segment is refused — that is `node_modules/<name>` symlinked to
+ *      a workspace source tree, where `rmSync(dest, { recursive: true })` deletes the
+ *      link's target contents.
  */
 function assertNodeModulesDest(dest, node) {
     const segments = dest.split(path.sep);
@@ -1715,8 +1526,7 @@ function assertNodeModulesDest(dest, node) {
         real = fs.realpathSync(dest);
     }
     catch {
-        // `dest` doesn't exist yet (fresh install) — nothing to resolve, the
-        // logical-path check above is sufficient.
+        // `dest` does not exist yet (fresh install); the logical-path check suffices.
         return;
     }
     const realSegments = real.split(path.sep);
@@ -1727,8 +1537,7 @@ function assertNodeModulesDest(dest, node) {
     }
 }
 function depth(installPath) {
-    // Count `node_modules/` segments to know nesting depth.
-    // `node_modules/foo` = 1, `node_modules/foo/node_modules/bar` = 2, etc.
+    // `node_modules/foo` = 1, `node_modules/foo/node_modules/bar` = 2, …
     return installPath.split('/node_modules/').length;
 }
 /**
@@ -1750,20 +1559,18 @@ function readShebang(file) {
 /**
  * Materialise ONE `node_modules/.bin/<name>` entry for `targetAbs`.
  *
- * Exported (and platform-injectable) so the Windows branch is unit-tested from
- * a Linux host — the file layout and shim contents are asserted there; only the
- * `symlinkSync`/`CreateSymbolicLink` syscall behaviour itself is OS-bound.
+ * Exported and platform-injectable so the Windows branch is unit-tested from a Linux
+ * host; only the `symlinkSync`/`CreateSymbolicLink` syscall itself is OS-bound.
  *
- * POSIX: a relative symlink, with a copy as the fallback (some filesystems and
- * container overlays reject symlinks).
+ * POSIX: a relative symlink, falling back to a copy (some filesystems and container
+ * overlays reject symlinks).
  *
- * Windows: `.bin/<name>` is not on `PATHEXT` and Windows has no shebang
- * handling, so a symlink OR a copy of a `#!/usr/bin/env node` script is
- * unrunnable — and a *file* symlink additionally needs elevation or Developer
- * Mode, so the previous code reliably fell into its copy fallback and produced
- * a dead entry. npm solves this with three sibling files (`<name>` for
- * git-bash/MSYS/WSL, `<name>.cmd` for cmd.exe, `<name>.ps1` for pwsh); we write
- * the same set from the same templates. See `./bin-shim.ts`.
+ * Windows: `.bin/<name>` is not on `PATHEXT` and Windows has no shebang handling, so a
+ * symlink OR a copy of a `#!/usr/bin/env node` script is unrunnable — and a *file*
+ * symlink additionally needs elevation or Developer Mode, so the previous code reliably
+ * fell into its copy fallback and produced a dead entry. npm's answer is three sibling
+ * files (`<name>` for git-bash/MSYS/WSL, `<name>.cmd` for cmd.exe, `<name>.ps1` for
+ * pwsh); the same set is written from the same templates (`./bin-shim.ts`).
  */
 export function writeBinEntry(opts) {
     const { binDir, binName, targetAbs, gjs, nodeFallbackAbs } = opts;
@@ -1771,8 +1578,8 @@ export function writeBinEntry(opts) {
     const linkPath = path.join(binDir, binName);
     if (gjs) {
         const isBundle = isGjsBundlePath(targetAbs);
-        // Replace the whole sibling set: a previous install may have written a
-        // plain symlink (or npm's three-file shim) under this very name.
+        // Replace the whole sibling set — a previous install may have written a plain
+        // symlink, or npm's three-file shim, under this very name.
         for (const stale of [linkPath, `${linkPath}.cmd`, `${linkPath}.ps1`])
             rmWithRetry(stale);
         fs.writeFileSync(linkPath, buildShLauncher(targetAbs, { envPreamble: gjs.envPreamble, isGjsBundle: isBundle, nodeFallbackAbs }));
@@ -1783,9 +1590,9 @@ export function writeBinEntry(opts) {
             /* inert on Windows; harmless under WSL/MSYS */
         }
         if (platform === 'win32' && isBundle) {
-            // No dedicated DLL-search variable on Windows: LoadLibrary searches
-            // PATH, and GLib's search-path separator is `;` there too — so both
-            // variables take the same `;`-joined value.
+            // No dedicated DLL-search variable on Windows: LoadLibrary searches PATH, and
+            // GLib's search-path separator is `;` there too, so both variables take the
+            // same `;`-joined value.
             const joined = gjs.prebuildDirs.join(';');
             const prependEnv = gjs.prebuildDirs.length > 0 ? { GI_TYPELIB_PATH: joined, PATH: joined } : {};
             const shims = buildLauncherShims({
@@ -1830,15 +1637,14 @@ export function writeBinEntry(opts) {
     }
 }
 async function linkBins(nodes, prefix, log) {
-    // Only root-level packages publish bins into the top-level
-    // `node_modules/.bin/`. Nested-package bins are addressable by their
-    // direct dependents through the nested .bin (npm matches this) — we
-    // omit nested-bin linking for now since no consumer of the install
-    // backend depends on it (gjsify's own use cases all hit root bins).
+    // Only root-level packages publish bins into the top-level `node_modules/.bin/`.
+    // Nested-bin linking is omitted because no consumer of this backend needs it — a
+    // nested package's bins are addressable by its direct dependents through the nested
+    // .bin, which is what npm does too.
     const binDir = path.join(prefix, 'node_modules', '.bin');
     let created = 0;
-    // Computed on first use only: the scan walks the whole prefix, and most
-    // installs contain no package declaring `gjsify.bin` at all.
+    // Computed on first use: the scan walks the whole prefix, and most installs contain
+    // no package declaring `gjsify.bin` at all.
     let gjsEnv;
     const gjsEnvForPrefix = () => {
         if (gjsEnv === undefined) {
@@ -1851,11 +1657,11 @@ async function linkBins(nodes, prefix, log) {
         if (depth(node.installPath) !== 1)
             continue;
         const pkgDir = path.join(prefix, node.installPath);
-        // The INSTALLED manifest is the source of truth here, not the packument
-        // the resolver carried: `gjsify.bin` is a gjsify-specific field npm's
-        // abbreviated packument does not include, so a packument-only read can
-        // never see it. Falls back to the resolved npm `bin` when the extracted
-        // manifest is unreadable, which keeps the previous behaviour intact.
+        // The INSTALLED manifest is the source of truth here, not the packument the
+        // resolver carried: `gjsify.bin` is a gjsify-specific field npm's abbreviated
+        // packument does not include, so a packument-only read structurally cannot see
+        // it. Falls back to the resolved npm `bin` when the extracted manifest is
+        // unreadable.
         const manifest = readInstalledManifest(pkgDir) ?? (node.bin === undefined ? null : { bin: node.bin });
         if (manifest === null)
             continue;
@@ -1873,8 +1679,8 @@ async function linkBins(nodes, prefix, log) {
             catch {
                 /* best effort */
             }
-            // Only a fallback that EXISTS is worth writing: a launcher naming a
-            // missing Node entry would trade exit 127 for a different exit 127.
+            // Only a fallback that EXISTS is worth writing: a launcher naming a missing
+            // Node entry trades exit 127 for a different exit 127.
             const fallbackRel = picked.nodeFallback?.get(binName);
             const fallbackAbs = fallbackRel === undefined ? undefined : path.join(pkgDir, fallbackRel);
             writeBinEntry({
@@ -1891,12 +1697,10 @@ async function linkBins(nodes, prefix, log) {
         log('bin: linked %d entry(ies) under .bin/', created);
 }
 /**
- * Read an extracted package's `package.json`.
- *
- * Returns `null` rather than throwing: a node can legitimately have no manifest
- * on disk yet (an optional dependency skipped for this platform), and bin
- * linking is not the place to fail an otherwise-complete install. The caller
- * falls back to the resolved npm `bin`.
+ * Read an extracted package's `package.json`, returning `null` rather than throwing: a
+ * node can legitimately have no manifest on disk (an optional dependency skipped for
+ * this platform), and bin linking is not the place to fail an otherwise-complete
+ * install. The caller falls back to the resolved npm `bin`.
  */
 function readInstalledManifest(pkgDir) {
     try {
@@ -1908,14 +1712,11 @@ function readInstalledManifest(pkgDir) {
     }
 }
 /**
- * `fs.rmSync(..., { force: true })` with the Windows retry npm/rimraf apply.
- *
- * On Windows a delete fails with `EBUSY`/`EPERM` while any process holds a
- * handle (antivirus scan, an editor, a still-terminating child), and the
- * deletion stays *pending* until the last handle closes — so an immediately
- * following create can hit `EPERM`/`ENOTEMPTY`. Node implements the retry loop
- * for us behind `maxRetries`; it is a no-op on POSIX, where the first attempt
- * always succeeds.
+ * `fs.rmSync(..., { force: true })` with the Windows retry npm/rimraf apply: there a
+ * delete fails `EBUSY`/`EPERM` while any process holds a handle (antivirus scan, an
+ * editor, a still-terminating child) and stays *pending* until the last handle closes,
+ * so an immediately following create can hit `EPERM`/`ENOTEMPTY`. Node implements the
+ * retry loop behind `maxRetries`; a no-op on POSIX, where the first attempt succeeds.
  */
 function rmWithRetry(target) {
     fs.rmSync(target, { recursive: true, force: true, maxRetries: 10, retryDelay: 100 });
@@ -1928,11 +1729,9 @@ async function loadNpmrc(opts) {
         authTokens: {},
         basicAuth: {},
     };
-    // Layered .npmrc lookup (most-specific wins): home → project (cwd's
-    // prefix). npm itself merges through `XDG_CONFIG_HOME/npm/npmrc` and a
-    // workspace-root one too; the gjsify project-local case is what users
-    // hit most often (mock-registry tests, scoped-registry overrides), so
-    // we cover that explicitly.
+    // Layered .npmrc lookup, most-specific wins: home → project (the prefix). npm also
+    // merges `XDG_CONFIG_HOME/npm/npmrc` and a workspace-root file; the project-local
+    // case is the one users hit (mock-registry tests, scoped-registry overrides).
     for (const candidate of [path.join(home, '.npmrc'), path.join(opts.prefix, '.npmrc')]) {
         if (!fs.existsSync(candidate))
             continue;
@@ -1944,11 +1743,11 @@ async function loadNpmrc(opts) {
             console.warn(`gjsify install: ignoring malformed ${candidate}: ${e.message}`);
         }
     }
-    // env-var override (npm convention: `npm_config_registry`).
+    // npm convention.
     const envRegistry = process.env.npm_config_registry;
     if (envRegistry)
         parsed.registry = envRegistry;
-    // Explicit caller-provided registry trumps everything else.
+    // An explicit caller-provided registry trumps everything else.
     if (opts.registry)
         parsed.registry = opts.registry;
     return parsed;