@vltpkg/cli-js 1.0.7 → 1.0.9

package/{chunk-3NGV7EC6.js → chunk-LHMEJF6J.js}

@@ -13,17 +13,19 @@ import {
   AbortError,
   SecurityArchive,
   pRetry
-} from "./chunk-ED2DDTQT.js";
+} from "./chunk-2YJ5MESP.js";
 import {
   Monorepo,
   PackageJson,
   getUser,
   minimatch,
   platformCheck
-} from "./chunk-SVBEF5PK.js";
+} from "./chunk-USTJECVS.js";
 import {
   asDepID,
+  baseDepID,
   getId,
+  getTuple,
   graphRun,
   hydrate,
   hydrate2,
@@ -33,7 +35,7 @@ import {
   joinExtra,
   splitDepID,
   splitExtra
-} from "./chunk-3OPNZI6G.js";
+} from "./chunk-YOE3VZFX.js";
 import {
   Spec as Spec2
 } from "./chunk-XKVU23NC.js";
@@ -47,12 +49,6 @@ import {
 import {
   graphStep
 } from "./chunk-UBLFPJHV.js";
-import {
-  XDG
-} from "./chunk-XNLSTHDK.js";
-import {
-  rimraf
-} from "./chunk-BJBFEQRR.js";
 import {
   Spec,
   Version,
@@ -93,6 +89,12 @@ import {
   shortDependencyTypes,
   subset
 } from "./chunk-VFBCWAOC.js";
+import {
+  XDG
+} from "./chunk-XNLSTHDK.js";
+import {
+  rimraf
+} from "./chunk-BHJT53TP.js";
 import {
   error,
   typeError
@@ -4755,6 +4757,34 @@ var Node = class _Node {
         break;
     }
   }
+  /**
+   * Update this node's DepID and peer suffix after canonicalization.
+   * Resets name/location memos that were derived from the previous id.
+   */
+  setPeerIdentity(id2, peerSetHash) {
+    const prevId = this.id;
+    const prevName = this.name;
+    const nameWasId = this.#name === prevId;
+    const prevDefault = `./node_modules/.vlt/${prevId}/node_modules/${prevName}`;
+    const locWasDefault = !this.#location || this.#location === prevDefault;
+    this.id = id2;
+    this.peerSetHash = peerSetHash;
+    if (nameWasId) this.#name = void 0;
+    const nextName = this.name;
+    if (prevName !== nextName) {
+      const oldSet = this.graph.nodesByName.get(prevName);
+      oldSet?.delete(this);
+      if (oldSet?.size === 0) {
+        this.graph.nodesByName.delete(prevName);
+      }
+      const nbn = this.graph.nodesByName.get(nextName) ?? /* @__PURE__ */ new Set();
+      nbn.add(this);
+      this.graph.nodesByName.set(nextName, nbn);
+    }
+    if (locWasDefault) {
+      this.location = `./node_modules/.vlt/${id2}/node_modules/${nextName}`;
+    }
+  }
   setDefaultLocation() {
     const def = `./node_modules/.vlt/${this.id}/node_modules/${this.name}`;
     if (!this.importer && (!this.#location || this.#location !== def && /^(?:\.\/)?node_modules\//.test(this.#location))) {
@@ -4825,6 +4855,13 @@ var Node = class _Node {
     return stringifyNode(this);
   }
 };
+var copyPackageMetadata = (to, from) => {
+  to.integrity ??= from.integrity;
+  to.resolved ??= from.resolved;
+  if (from.resolvedFromLockfile && to.integrity && to.resolved) {
+    to.resolvedFromLockfile = true;
+  }
+};
 var isNode = (value) => {
   return typeof value === "object" && value != null && "id" in value && "manifest" in value && value[Symbol.toStringTag] === "@vltpkg/graph.Node";
 };
@@ -6765,17 +6802,22 @@ var asOutdatedKind = (value) => {
   }
   return value;
 };
-var retrieveRemoteVersions = async (node, signal) => {
+var retrieveRemoteVersions = async (node, signal, getAuthHeader) => {
   const spec2 = hydrate(node.id, String(node.name), node.options);
   if (!spec2.registry || !node.name) {
     return [];
   }
-  const url = new URL(spec2.registry);
-  url.pathname = `/${node.name}`;
+  const base = spec2.registry.endsWith("/") ? spec2.registry : `${spec2.registry}/`;
+  const url = new URL(node.name, base);
+  const headers = {
+    Accept: "application/vnd.npm.install-v1+json"
+  };
+  const auth = await getAuthHeader?.(String(url));
+  if (auth) {
+    headers.authorization = auth;
+  }
   const response = await fetch(String(url), {
-    headers: {
-      Accept: "application/vnd.npm.install-v1+json"
-    },
+    headers,
     signal
   });
   if (response.status === 404) {
@@ -6806,7 +6848,7 @@ var parseInternals7 = (nodes) => {
   }
   return { kind };
 };
-var queueNode2 = async (state, node, kind) => {
+var queueNode2 = async (state, node, kind, onError) => {
   if (!node.name || !node.version) {
     return node;
   }
@@ -6814,19 +6856,27 @@ var queueNode2 = async (state, node, kind) => {
   let versions;
   try {
     versions = await pRetry(
-      () => retrieveRemoteVersions(node, state.signal),
+      () => retrieveRemoteVersions(
+        node,
+        state.signal,
+        state.getAuthHeader
+      ),
       {
         retries: state.retries,
         signal: state.signal
       }
     );
   } catch (err) {
-    console.warn(
-      error("Could not retrieve registry versions", {
-        name: node.name,
-        cause: err
-      })
-    );
+    if (onError) {
+      onError(node, err);
+    } else {
+      console.warn(
+        error("Could not retrieve registry versions", {
+          name: node.name,
+          cause: err
+        })
+      );
+    }
     versions = [];
   }
   const greaterVersions = versions.filter(
@@ -6899,12 +6949,20 @@ var outdated = async (state) => {
   }
   const { kind } = internals;
   const queue = [];
+  const failures = [];
   for (const node of state.partial.nodes) {
     if (node.mainImporter || node.manifest?.private || splitDepID(node.id)[0] !== "registry") {
       removeNode(state, node);
       continue;
     }
-    queue.push(queueNode2(state, node, kind));
+    queue.push(
+      queueNode2(
+        state,
+        node,
+        kind,
+        (node2, err) => failures.push({ node: node2, err })
+      )
+    );
   }
   const removeNodeQueue = await Promise.all(queue);
   for (const node of removeNodeQueue) {
@@ -6912,6 +6970,14 @@ var outdated = async (state) => {
       removeNode(state, node);
     }
   }
+  if (failures.length) {
+    console.warn(
+      error("Could not retrieve registry versions", {
+        found: failures.map(({ node }) => String(node.name)).sort(),
+        cause: failures[0]?.err
+      })
+    );
+  }
   return state;
 };
 
@@ -8519,6 +8585,7 @@ var setMethodToJSON = (node) => {
 var Query = class {
   #cache;
   #diffFiles;
+  #getAuthHeader;
   #edges;
   #nodes;
   #importers;
@@ -8562,10 +8629,12 @@ var Query = class {
     retries,
     securityArchive,
     hostContexts,
-    diffFiles
+    diffFiles,
+    getAuthHeader
   }) {
     this.#cache = /* @__PURE__ */ new Map();
     this.#diffFiles = diffFiles;
+    this.#getAuthHeader = getAuthHeader;
     this.#edges = edges;
     this.#nodes = nodes;
     this.#importers = importers;
@@ -8791,6 +8860,7 @@ var Query = class {
       },
       comment: "",
       diffFiles: this.#diffFiles,
+      getAuthHeader: this.#getAuthHeader,
       loose,
       importers,
       partial: { nodes, edges },
@@ -8882,6 +8952,7 @@ var asDependency = (obj) => {
   }
   return obj;
 };
+var addKey = (spec2) => spec2.name === "(unknown)" ? spec2.spec : spec2.name;
 var shorten = (typeLong, name, manifest) => {
   const shortName = dependencyTypes.get(typeLong);
   if (!shortName) {
@@ -8899,6 +8970,7 @@ var shorten = (typeLong, name, manifest) => {
   return "peer";
 };
 var isStringArray = (a) => Array.isArray(a) && !a.some((b) => typeof b !== "string");
+var shouldInstallDepType = (node, depType) => depType !== "devDependencies" || node.importer || node.id.startsWith("git");
 var getRawDependencies = (node) => {
   const dependencies = /* @__PURE__ */ new Map();
   const bundleDeps = node.manifest?.bundleDependencies ?? [];
@@ -8911,6 +8983,9 @@ var getRawDependencies = (node) => {
     if (obj) {
       for (const [name, bareSpec] of Object.entries(obj)) {
         if (bundled.has(name)) continue;
+        if (depType === "peerDependencies" && dependencies.has(name)) {
+          continue;
+        }
         dependencies.set(name, {
           name,
           type: depType,
@@ -9082,20 +9157,20 @@ var lockfileData = ({
   const cleanRegistries = isRecordStringString(registries) ? removeDefaultItems(defaultRegistries, registries) : void 0;
   const cleanScopeRegistries = isRecordStringString(scopeRegistries) ? removeDefaultItems(defaultScopeRegistries, scopeRegistries) : void 0;
   const cleanJsrRegistries = isRecordStringString(jsrRegistries) ? removeDefaultItems(defaultJsrRegistries, jsrRegistries) : void 0;
-  const hasItems = (clean) => clean && Object.keys(clean).length;
+  const hasItems2 = (clean) => clean && Object.keys(clean).length;
   return {
     lockfileVersion: LOCKFILE_VERSION,
     options: {
-      ...hasItems(cleanModifiers) ? { modifiers: cleanModifiers } : {},
-      ...hasItems(catalog) ? { catalog } : {},
-      ...hasItems(catalogs) ? { catalogs } : {},
-      ...hasItems(cleanScopeRegistries) ? { "scoped-registries": cleanScopeRegistries } : void 0,
-      ...hasItems(cleanJsrRegistries) ? { "jsr-registries": cleanJsrRegistries } : void 0,
+      ...hasItems2(cleanModifiers) ? { modifiers: cleanModifiers } : {},
+      ...hasItems2(catalog) ? { catalog } : {},
+      ...hasItems2(catalogs) ? { catalogs } : {},
+      ...hasItems2(cleanScopeRegistries) ? { "scoped-registries": cleanScopeRegistries } : void 0,
+      ...hasItems2(cleanJsrRegistries) ? { "jsr-registries": cleanJsrRegistries } : void 0,
       ...registry2 !== void 0 ? { registry: registry2 } : void 0,
       ...defaultRegistryAlias !== void 0 && defaultRegistryAlias !== defaultRegistryName ? { "default-registry-alias": defaultRegistryAlias } : void 0,
-      ...hasItems(cleanRegistries) ? { registries: cleanRegistries } : void 0,
-      ...hasItems(cleanGitHosts) ? { "git-hosts": cleanGitHosts } : void 0,
-      ...hasItems(cleanGitHostArchives) ? { "git-host-archives": cleanGitHostArchives } : void 0
+      ...hasItems2(cleanRegistries) ? { registries: cleanRegistries } : void 0,
+      ...hasItems2(cleanGitHosts) ? { "git-hosts": cleanGitHosts } : void 0,
+      ...hasItems2(cleanGitHostArchives) ? { "git-host-archives": cleanGitHostArchives } : void 0
     },
     nodes: formatNodes(
       graph.nodes.values(),
@@ -9238,10 +9313,35 @@ var Graph = class {
    * the ideal builder must reset edges and rebuild the graph.
    */
   optionsChanged = false;
+  /**
+   * The individual differences behind `optionsChanged`, in the order
+   * they are reported to the user. Empty when nothing changed.
+   */
+  optionsChanges = [];
+  /**
+   * Whether the lockfile on disk no longer matches this graph even
+   * though no node changed, e.g. an importer edge spec was rewritten to
+   * the value saved to `package.json`, or the config options the graph
+   * was built with differ from the ones stored in the lockfile. Reify
+   * saves the lockfiles from its no-diff early return when set.
+   */
+  lockfileStale = false;
+  /**
+   * Lockfile edge targets captured immediately before `resetEdges()`.
+   * Used by the ideal builder to reuse locked resolutions across a rebuild.
+   */
+  lockedResolutions;
   /**
    * Tracks the current peer context index.
    */
   currentPeerContextIndex = 0;
+  /**
+   * Count of structural writes: nodes placed or removed, edges reset,
+   * created or re-pointed. Never reset; callers snapshot it and compare,
+   * so the ideal builder can tell whether a rebuild touched anything the
+   * peer identities depend on.
+   */
+  mutations = 0;
   constructor(options) {
     const { mainManifest, monorepo } = options;
     this.#options = options;
@@ -9318,39 +9418,89 @@ var Graph = class {
    * Delete all nodes and edges that are unreachable from the importers.
    * The collection of deleted nodes is returned.
    *
-   * NOTE: This can be extremely slow for large graphs, and is almost always
-   * unnecessary! Only call when it is known that some unreachable nodes may
-   * have been created, for example when deleting the unneeded subgraph when an
+   * Marking is O(N+E) and always runs, but when nothing is unreachable
+   * and every reachable node is registered under its own id, `nodes` is
+   * left alone — no rebuild, no sort, and an empty map is returned.
+   * Only call when it is known that some unreachable nodes may have been
+   * created, for example when deleting the unneeded subgraph when an
    * optional node fails to resolve/install.
    */
   gc() {
     const { nodes } = this;
     this.edges.clear();
-    this.nodes = /* @__PURE__ */ new Map();
     const marked = new Set(this.importers);
-    for (const imp of marked) {
-      nodes.delete(imp.id);
-      this.nodes.set(imp.id, imp);
-      for (const edge of imp.edgesOut.values()) {
+    for (const node of marked) {
+      for (const edge of node.edgesOut.values()) {
         this.edges.add(edge);
         const { to } = edge;
-        if (!to || marked.has(to)) continue;
-        marked.add(to);
-        nodes.delete(to.id);
-        this.nodes.set(to.id, to);
+        if (to) marked.add(to);
+      }
+    }
+    let intact = marked.size === nodes.size;
+    if (intact) {
+      for (const node of marked) {
+        if (nodes.get(node.id) !== node) {
+          intact = false;
+          break;
+        }
       }
     }
+    if (intact) return /* @__PURE__ */ new Map();
+    this.nodes = /* @__PURE__ */ new Map();
+    for (const node of marked) {
+      nodes.delete(node.id);
+      this.nodes.set(node.id, node);
+    }
     for (const node of nodes.values()) {
       this.removeNode(node);
     }
+    this.sortNodes();
     return nodes;
   }
+  /**
+   * Rebuild `nodes` so importers come first, then remaining nodes in
+   * DepID order. Matches lockfile save so a built graph and a
+   * save→load round-trip iterate the same way.
+   *
+   * A graph coming from the lockfile loader is already in that order, so
+   * the pass below detects it and keeps the map as-is.
+   */
+  sortNodes() {
+    const cmp = (a, b) => a.id.localeCompare(b.id, "en");
+    const rest = [];
+    const importers = this.importers.values();
+    let seenImporters = 0;
+    let sorted = true;
+    let prev;
+    for (const node of this.nodes.values()) {
+      if (this.importers.has(node)) {
+        if (rest.length || importers.next().value !== node) {
+          sorted = false;
+        }
+        seenImporters++;
+        continue;
+      }
+      if (sorted && prev && cmp(prev, node) > 0) sorted = false;
+      prev = node;
+      rest.push(node);
+    }
+    if (sorted && seenImporters === this.importers.size) return;
+    rest.sort(cmp);
+    const nodes = /* @__PURE__ */ new Map();
+    for (const node of this.importers) nodes.set(node.id, node);
+    for (const node of rest) nodes.set(node.id, node);
+    this.nodes = nodes;
+  }
   /**
    * Create a new edge between two nodes of the graph in case both exist,
    * in case the destination node does not exists, then a dangling edge,
    * pointing to nothing will be created to represent that missing dependency.
    */
   addEdge(type2, spec2, from, to) {
+    if (to) {
+      const toNode = to;
+      toNode.detached = false;
+    }
     if (spec2.name === "(unknown)") {
       if (to) {
         spec2.name = to.name || "(unknown)";
@@ -9368,6 +9518,7 @@ var Graph = class {
       const edge = existing;
       if (edge.type === type2 && edge.spec.bareSpec === spec2.bareSpec) {
         if (to && to !== edge.to) {
+          this.mutations++;
           edge.to?.edgesIn.delete(edge);
           edge.to = to;
           edge.to.edgesIn.add(edge);
@@ -9376,6 +9527,7 @@ var Graph = class {
       }
       this.edges.delete(edge);
     }
+    this.mutations++;
     const f = from;
     const edgeOut = f.addEdgesTo(
       resolveSaveType(from, spec2.name, type2),
@@ -9392,22 +9544,28 @@ var Graph = class {
     const f = spec2.final;
     const sf = getResolutionCacheKey(f, fromNode.location, extra);
     const cached = this.resolutions.get(sf);
-    if (cached) return cached;
+    if (cached && !cached.detached) return cached;
     const nbn = this.nodesByName.get(f.name);
     if (!nbn) return void 0;
+    const sat = (n) => satisfies2(
+      n.id,
+      f,
+      fromNode.location,
+      this.projectRoot,
+      this.monorepo
+    );
+    let detached = cached?.detached && sat(cached) ? cached : void 0;
     for (const node of nbn) {
-      if (satisfies2(
-        node.id,
-        f,
-        fromNode.location,
-        this.projectRoot,
-        this.monorepo
-      )) {
-        this.resolutions.set(sf, node);
-        this.resolutionsReverse.get(node)?.add(sf);
-        return node;
+      if (!sat(node)) continue;
+      if (node.detached) {
+        detached ??= node;
+        continue;
       }
+      this.resolutions.set(sf, node);
+      this.resolutionsReverse.get(node)?.add(sf);
+      return node;
     }
+    return detached;
   }
   /**
    * Create a new node in the graph.
@@ -9425,7 +9583,7 @@ var Graph = class {
     const nbn = this.nodesByName.get(node.name) ?? /* @__PURE__ */ new Set();
     nbn.add(node);
     const newByNameSet = new Set(
-      [...nbn].sort((a, b) => a.id.localeCompare(b.id))
+      [...nbn].sort((a, b) => a.id.localeCompare(b.id, "en"))
     );
     this.nodesByName.set(node.name, newByNameSet);
     if (manifest) {
@@ -9442,6 +9600,7 @@ var Graph = class {
    * consider using `addNode()` and `addEdge()` instead.
    */
   placePackage(fromNode, depType, spec2, manifest, id2, extra) {
+    this.mutations++;
     if (!manifest && !id2) {
       this.addEdge(depType, spec2, fromNode);
       return;
@@ -9472,10 +9631,23 @@ var Graph = class {
       }
       return toFoundNode;
     }
+    let samePackage;
+    const base = baseDepID(depId);
+    const nbn = this.nodesByName.get(manifest?.name ?? spec2.name);
+    if (nbn) {
+      for (const n of nbn) {
+        if (baseDepID(n.id) !== base) continue;
+        if (!n.integrity && !n.resolved) continue;
+        samePackage = n;
+        if (n.integrity) break;
+      }
+    }
     const toNode = this.addNode(depId, manifest, spec2);
     toNode.registry = spec2.registry;
     toNode.dev = flags.dev;
     toNode.optional = flags.optional;
+    if (samePackage) copyPackageMetadata(toNode, samePackage);
+    toNode.integrity ??= manifest?.dist?.integrity;
     if (extra) {
       const { modifier, peerSetHash } = splitExtra(extra);
       toNode.modifier = modifier;
@@ -9519,6 +9691,7 @@ var Graph = class {
    * if it is valid to do so.
    */
   removeNode(node, replacement, keepEdges) {
+    this.mutations++;
     this.nodes.delete(node.id);
     const nbn = this.nodesByName.get(node.name);
     if (nbn?.size === 1) this.nodesByName.delete(node.name);
@@ -9552,6 +9725,7 @@ var Graph = class {
    * Removes the resolved node of a given edge.
    */
   removeEdgeResolution(edge, extra = "") {
+    this.mutations++;
     const node = edge.to;
     const resolutionKey = getResolutionCacheKey(
       edge.spec,
@@ -9574,9 +9748,10 @@ var Graph = class {
    * This allows the graph to be reconstructed efficiently using the existing nodes.
    */
   resetEdges() {
+    this.mutations++;
     this.edges.clear();
     for (const node of this.nodes.values()) {
-      node.detached = true;
+      node.detached = !node.importer;
       node.edgesOut.clear();
       node.edgesIn.clear();
     }
@@ -9743,7 +9918,7 @@ var loadNodes = (graph, nodes, options, actual2, throwOnMissingManifest) => {
       );
     }
     let version;
-    if (type2 === "registry" && registrySpec && registrySpec.indexOf("@") > 0) {
+    if (type2 === "registry" && registrySpec && registrySpec.indexOf("@", 1) > 0) {
       if (registryVersionCache) {
         const seenVersion = registryVersionCache.get(registrySpec);
         if (seenVersion) {
@@ -9836,8 +10011,8 @@ var removeDefaultItems2 = (defaultItems, items) => {
   }
   return res;
 };
+var hasItems = (o) => !!o && Object.keys(o).length > 0;
 var buildCurrentOptions = (options) => {
-  const hasItems = (o) => o && Object.keys(o).length > 0;
   const cleanModifiers = options.modifiers && isRecordStringString(options.modifiers.config) ? options.modifiers.config : void 0;
   const cleanRegistries = isRecordStringString(options.registries) ? removeDefaultItems2(defaultRegistries, options.registries) : void 0;
   const cleanScopeRegistries = isRecordStringString(options["scoped-registries"]) ? removeDefaultItems2(
@@ -9866,6 +10041,56 @@ var buildCurrentOptions = (options) => {
     ...hasItems(cleanGitHostArchives) ? { "git-host-archives": cleanGitHostArchives } : void 0
   };
 };
+var asRecord = (o) => o;
+var unionKeys = (a = {}, b = {}) => [.../* @__PURE__ */ new Set([...Object.keys(a), ...Object.keys(b)])].sort();
+var diffRecords = (section, from = {}, to = {}, changes, prefix) => {
+  for (const key of unionKeys(from, to)) {
+    if (from[key] !== to[key]) {
+      changes.push({
+        section,
+        key: prefix === void 0 ? key : `${prefix} ${key}`,
+        from: from[key],
+        to: to[key]
+      });
+    }
+  }
+};
+var diffLockfileOptions = (options, lockfileOptions = {}) => {
+  const current = asRecord(buildCurrentOptions(options));
+  const stored = asRecord(lockfileOptions);
+  const changes = [];
+  for (const section of unionKeys(stored, current)) {
+    const from = stored[section];
+    const to = current[section];
+    if (typeof from === "string" || typeof to === "string") {
+      if (from !== to) {
+        changes.push({
+          section,
+          from,
+          to
+        });
+      }
+    } else if (section === "catalogs") {
+      for (const name of unionKeys(from, to)) {
+        diffRecords(
+          section,
+          from?.[name],
+          to?.[name],
+          changes,
+          name
+        );
+      }
+    } else {
+      diffRecords(
+        section,
+        from,
+        to,
+        changes
+      );
+    }
+  }
+  return changes;
+};
 var loadObject = (options, lockfileData2) => {
   const version = lockfileData2.lockfileVersion;
   if (version == null) {
@@ -9902,13 +10127,17 @@ var loadObject = (options, lockfileData2) => {
     /* c8 ignore next */
   } = lockfileData2.options ?? {};
   const scopeRegistries = scopedRegistriesOption ?? lockfileData2.options["scope-registries"];
-  const currentOptions = buildCurrentOptions(options);
   const lockfileOptions = lockfileData2.options ?? {};
-  const optionsChanged = JSON.stringify(currentOptions) !== JSON.stringify(lockfileOptions);
+  const optionsChanges = diffLockfileOptions(options, lockfileOptions);
   const mergedOptions = {
     ...options,
-    catalog,
-    catalogs,
+    // catalog entries are indirections resolved at parse time: prefer
+    // the current config so loading a lockfile (e.g. the hidden
+    // lockfile cache) yields the same edge specs as a fresh scan of
+    // the project; fall back to the stored values so a standalone
+    // lockfile still parses when the config no longer defines them
+    catalog: hasItems(options.catalog) ? options.catalog : catalog,
+    catalogs: hasItems(options.catalogs) ? options.catalogs : catalogs,
     "scoped-registries": scopeRegistries ? { ...options["scoped-registries"], ...scopeRegistries } : options["scoped-registries"],
     registry: registry2 ?? options.registry,
     "default-registry-alias": defaultRegistryAlias ?? options["default-registry-alias"],
@@ -9921,7 +10150,8 @@ var loadObject = (options, lockfileData2) => {
     mainManifest,
     monorepo
   });
-  graph.optionsChanged = optionsChanged;
+  graph.optionsChanges = optionsChanges;
+  graph.optionsChanged = optionsChanges.length > 0;
   loadNodes(
     graph,
     lockfileData2.nodes,
@@ -9931,7 +10161,11 @@ var loadObject = (options, lockfileData2) => {
   );
   const specCache = options.modifiers || !options.specCache ? void 0 : {
     specCache: options.specCache,
-    prefix: JSON.stringify(lockfileOptions)
+    prefix: JSON.stringify([
+      lockfileOptions,
+      mergedOptions.catalog,
+      mergedOptions.catalogs
+    ])
   };
   loadEdges(graph, lockfileData2.edges, mergedOptions, specCache);
   for (const node of graph.nodes.values()) {
@@ -9940,6 +10174,7 @@ var loadObject = (options, lockfileData2) => {
       node.registry = firstEdge.spec.registry;
     }
   }
+  graph.sortNodes();
   return graph;
 };
 
@@ -10206,6 +10441,7 @@ var load4 = (options) => {
       });
     }
   }
+  graph.sortNodes();
   done();
   return graph;
 };
@@ -11188,6 +11424,8 @@ var specificitySort = (breadcrumbs) => {
 };
 
 // ../../src/graph/src/modifiers.ts
+var matchesImporter = (item, importer) => item.importer && (item.value === ":project" || item.value === ":root" && importer.mainImporter || item.value === ":workspace" && importer.importer);
+var matchesQualifier = (item, spec2) => !!item?.comparator({ semver: spec2.semver });
 var GraphModifier = class _GraphModifier {
   /** The loaded modifiers configuration */
   #config;
@@ -11229,6 +11467,27 @@ var GraphModifier = class _GraphModifier {
     if (this.#config) return this.#config;
     return this.#config = load("modifiers", assertRecordStringString) ?? {};
   }
+  /**
+   * Whether a modifier governs the direct `importer -> spec.name` edge,
+   * i.e. whether its value comes from config rather than from the
+   * manifest that declares it. Only a breadcrumb whose whole scope is
+   * that edge counts, and only if its qualifier accepts the spec:
+   * `:root > #a > #b` names b but governs an edge under a, and
+   * `#b:semver(^1)` leaves a `^2` edge alone, so in both cases the
+   * root's own b edge is still the manifest's to validate and heal.
+   */
+  targetsImporterEdge(importer, spec2) {
+    for (const { breadcrumb } of this.#modifiers) {
+      const { last } = breadcrumb;
+      if (last.name !== spec2.name) continue;
+      if (!matchesQualifier(last, spec2)) continue;
+      const { prev } = last;
+      if (!prev) return true;
+      if (prev.prev) continue;
+      if (matchesImporter(prev, importer)) return true;
+    }
+    return false;
+  }
   /**
    * Loads the modifiers defined in `vlt.json` into memory.
    */
@@ -11281,11 +11540,7 @@ var GraphModifier = class _GraphModifier {
    */
   tryImporter(importer) {
     for (const modifier of this.#modifiers) {
-      const { first } = modifier.breadcrumb;
-      const matchRoot = first.value === ":root" && importer.mainImporter;
-      const matchWorkspace = first.value === ":workspace" && importer.importer;
-      const matchAny = first.value === ":project" || matchRoot || matchWorkspace;
-      if (first.importer && matchAny) {
+      if (matchesImporter(modifier.breadcrumb.first, importer)) {
         const active = this.newModifier(importer, modifier);
         const single = active.modifier.breadcrumb.single;
         if (!single) {
@@ -11311,7 +11566,7 @@ var GraphModifier = class _GraphModifier {
    * iteration.
    */
   tryNewDependency(from, spec2) {
-    const { name, semver } = spec2;
+    const { name } = spec2;
     const all = /* @__PURE__ */ new Map();
     for (const modifier of this.#modifiers) {
       const entry = this.#activeEntries.get(modifier)?.get(name)?.get(from);
@@ -11338,9 +11593,7 @@ var GraphModifier = class _GraphModifier {
     return all.get(
       specificitySort(
         entries.filter(
-          (i) => i.interactiveBreadcrumb.current?.comparator({
-            semver
-          })
+          (i) => matchesQualifier(i.interactiveBreadcrumb.current, spec2)
         ).map((i) => i.modifier.breadcrumb)
       )[0]
     );
@@ -11560,8 +11813,10 @@ var init = async ({
 // ../../src/graph/src/ideal/remove-satisfied-specs.ts
 var removeSatisfiedSpecs = ({
   add,
-  graph
+  graph,
+  modifiers
 }) => {
+  const staleSpecs = /* @__PURE__ */ new Map();
   for (const [depID, dependencies] of add.entries()) {
     const importer = graph.nodes.get(depID);
     if (!importer) {
@@ -11584,6 +11839,9 @@ var removeSatisfiedSpecs = ({
         graph.projectRoot,
         graph.monorepo
       )) {
+        if ((edge.spec.bareSpec !== dependency.spec.bareSpec || dependency.type !== "implicit" && edge.type !== dependency.type) && !modifiers?.targetsImporterEdge(importer, dependency.spec)) {
+          staleSpecs.set(edge, dependency);
+        }
         dependencies.delete(name);
       }
     }
@@ -11593,6 +11851,7 @@ var removeSatisfiedSpecs = ({
       add.delete(depID);
     }
   }
+  return staleSpecs;
 };
 
 // ../../src/graph/src/ideal/get-importer-specs.ts
@@ -11623,28 +11882,34 @@ var getImporterSpecs = (options) => {
         removeResult.modifiedDependencies = true;
       }
     }
+    const declared = /* @__PURE__ */ new Map();
     for (const depType of longDependencyTypes) {
       const deps = Object.entries(importer.manifest?.[depType] ?? {});
       for (const [depName, depSpec] of deps) {
-        const edge = importer.edgesOut.get(depName);
-        if (edge?.to && depSpec === edge.spec.bareSpec) continue;
-        const spec2 = Spec2.parse(depName, depSpec, options);
-        if (spec2.type === "workspace" && !edge?.to) {
-          const wsExists = [...graph.importers].some(
-            (n) => n.name === depName
-          );
-          if (!wsExists) {
-            removeDeps.add(depName);
-            removeResult.modifiedDependencies = true;
-            continue;
-          }
+        if (depType === "peerDependencies" && declared.has(depName)) {
+          continue;
+        }
+        declared.set(depName, [depType, depSpec]);
+      }
+    }
+    for (const [depName, [depType, depSpec]] of declared) {
+      const edge = importer.edgesOut.get(depName);
+      const type2 = shorten(depType, depName, importer.manifest);
+      if (edge?.to && edge.spec.bareSpec === depSpec && edge.type === type2) {
+        continue;
+      }
+      const spec2 = Spec2.parse(depName, depSpec, options);
+      if (spec2.type === "workspace" && !edge?.to) {
+        const wsExists = [...graph.importers].some(
+          (n) => n.name === depName
+        );
+        if (!wsExists) {
+          removeDeps.add(depName);
+          removeResult.modifiedDependencies = true;
+          continue;
         }
-        const dependency = asDependency({
-          spec: spec2,
-          type: shorten(depType, depName, importer.manifest)
-        });
-        addDeps.set(depName, dependency);
       }
+      addDeps.set(depName, asDependency({ spec: spec2, type: type2 }));
     }
     addResult.set(importer.id, addDeps);
     removeResult.set(importer.id, removeDeps);
@@ -11670,7 +11935,7 @@ var getImporterSpecs = (options) => {
         const deps = Object.entries(manifest[depType] ?? {});
         for (const [depName, depSpec] of deps) {
           const edge = node.edgesOut.get(depName);
-          if (edge?.to && depSpec === edge.spec.bareSpec) continue;
+          if (edge?.to && edge.spec.bareSpec === depSpec) continue;
           const dependency = asDependency({
             spec: Spec2.parse(depName, depSpec, options),
             type: shorten(depType, depName, manifest)
@@ -11720,10 +11985,16 @@ var getImporterSpecs = (options) => {
       removeResult.delete(key);
     }
   }
-  removeSatisfiedSpecs({
+  const staleSpecs = removeSatisfiedSpecs({
     add: addResult,
-    graph
+    graph,
+    modifiers: options.modifiers
   });
+  for (const edge of staleSpecs.keys()) {
+    if (add.get(edge.from.id)?.has(edge.name)) {
+      staleSpecs.delete(edge);
+    }
+  }
   for (const addDeps of addResult.values()) {
     if (addDeps.size > 0) {
       addResult.modifiedDependencies = true;
@@ -11733,11 +12004,409 @@ var getImporterSpecs = (options) => {
   return {
     add: addResult,
     remove: removeResult,
+    staleSpecs,
     transientAdd,
     transientRemove
   };
 };
 
+// ../../src/graph/src/ideal/canonicalize-peer-ids.ts
+import { createHash } from "node:crypto";
+var NUL = "\0";
+var NL = "\n";
+var MISSING = "MISSING";
+var PEER_PREFIX = "peer.";
+var peerEnvDigest = (input, length = 16) => createHash("sha256").update(input).digest("hex").slice(0, length);
+var isProvisionalPeerSuffix = (suffix) => /^peer\.\d{1,15}$/.test(suffix);
+var hasProvisionalPeerIds = (graph) => {
+  for (const node of graph.nodes.values()) {
+    if (node.peerSetHash && isProvisionalPeerSuffix(node.peerSetHash)) {
+      return true;
+    }
+  }
+  return false;
+};
+var byteCompare = (a, b) => a < b ? -1 : a > b ? 1 : 0;
+var canCarryPeerSuffix = (node) => {
+  if (node.importer) return false;
+  const type2 = splitDepID(node.id)[0];
+  return type2 !== "file" && type2 !== "workspace";
+};
+var hasPeerDependencies = (node, graph) => {
+  const mani = node.manifest ?? graph.manifests.get(node.id);
+  return !!(mani?.peerDependencies && Object.keys(mani.peerDependencies).length > 0);
+};
+var hasPeerOutEdge = (node) => {
+  for (const edge of node.edgesOut.values()) {
+    if (edge.type === "peer" || edge.type === "peerOptional") {
+      return true;
+    }
+  }
+  return false;
+};
+var isPeerScoped = (node, graph) => {
+  if (!canCarryPeerSuffix(node)) return false;
+  return !!node.peerSetHash || hasPeerDependencies(node, graph) || hasPeerOutEdge(node);
+};
+var serializeEdges = (node, ref) => {
+  const entries = [];
+  for (const edge of node.edgesOut.values()) {
+    entries.push(
+      `${edge.name}${NUL}${edge.type}${NUL}${edge.to ? ref(edge.to) : MISSING}`
+    );
+  }
+  entries.sort(byteCompare);
+  return entries.join(NL);
+};
+var serializeNodeEnv = (node, opts = {}) => {
+  const { resolvedIds, intraSccIndex } = opts;
+  return serializeEdges(node, (to) => {
+    const idx = intraSccIndex?.get(to);
+    return idx === void 0 ? resolvedIds?.get(to) ?? to.id : `#${idx}`;
+  });
+};
+var withPeerSuffix = (node, peerSetHash) => {
+  const extra = joinExtra({
+    modifier: node.modifier,
+    peerSetHash
+  });
+  const parsed = splitDepID(node.id);
+  switch (parsed[0]) {
+    case "registry":
+      return joinDepIDTuple(["registry", parsed[1], parsed[2], extra]);
+    case "git":
+      return joinDepIDTuple(["git", parsed[1], parsed[2], extra]);
+    case "remote":
+      return joinDepIDTuple(["remote", parsed[1], extra]);
+    /* c8 ignore next 2 */
+    default:
+      return node.id;
+  }
+};
+var peerlessDepID = (node) => withPeerSuffix(node, "");
+var unitEntry = (node, opts) => `${peerlessDepID(node)}${NL}${serializeNodeEnv(node, opts)}`;
+var tarjan = (nodes, adj) => {
+  let index = 0;
+  const indices = /* @__PURE__ */ new Map();
+  const lowlink = /* @__PURE__ */ new Map();
+  const onStack = /* @__PURE__ */ new Set();
+  const stack = [];
+  const sccs = [];
+  const strongconnect = (v) => {
+    indices.set(v, index);
+    lowlink.set(v, index);
+    index++;
+    stack.push(v);
+    onStack.add(v);
+    const neighbors = adj.get(v) ?? [];
+    for (const w of neighbors) {
+      if (!indices.has(w)) {
+        strongconnect(w);
+        const lv = lowlink.get(v);
+        const lw = lowlink.get(w);
+        if (lv !== void 0 && lw !== void 0 && lw < lv) {
+          lowlink.set(v, lw);
+        }
+      } else if (onStack.has(w)) {
+        const lv = lowlink.get(v);
+        const iw = indices.get(w);
+        if (lv !== void 0 && iw !== void 0 && iw < lv) {
+          lowlink.set(v, iw);
+        }
+      }
+    }
+    if (lowlink.get(v) === indices.get(v)) {
+      const scc = [];
+      for (; ; ) {
+        const w = stack.pop();
+        if (!w) break;
+        onStack.delete(w);
+        scc.push(w);
+        if (w === v) break;
+      }
+      sccs.push(scc);
+    }
+  };
+  for (const v of nodes) {
+    if (!indices.has(v)) strongconnect(v);
+  }
+  return sccs;
+};
+var hasSelfEdge = (node) => {
+  for (const edge of node.edgesOut.values()) {
+    if (edge.to === node) return true;
+  }
+  return false;
+};
+var serializeWithColors = (node, sccSet, color, resolvedIds) => serializeEdges(
+  node,
+  (to) => sccSet.has(to) ? (
+    /* c8 ignore next */
+    color.get(to) ?? MISSING
+  ) : resolvedIds.get(to) ?? to.id
+);
+var mapGet = (m, key) => {
+  const v = m.get(key);
+  return v ?? "";
+};
+var refineSccOrder = (scc, resolvedIds) => {
+  const sccSet = new Set(scc);
+  const bases = [...new Set(scc.map(peerlessDepID))].sort(byteCompare);
+  const initRank = new Map(bases.map((b, i) => [b, String(i)]));
+  let color = new Map(
+    scc.map((n) => [n, mapGet(initRank, peerlessDepID(n))])
+  );
+  let classCount = new Set(color.values()).size;
+  for (; ; ) {
+    const rows = scc.map((n) => ({
+      n,
+      key: `${peerlessDepID(n)}${NUL}${mapGet(color, n)}${NUL}${serializeWithColors(n, sccSet, color, resolvedIds)}`
+    }));
+    const uniq = [...new Set(rows.map((r) => r.key))].sort(byteCompare);
+    const rank = new Map(uniq.map((k, i) => [k, String(i)]));
+    color = new Map(
+      rows.map((r) => [r.n, mapGet(rank, r.key)])
+    );
+    if (uniq.length === classCount) break;
+    classCount = uniq.length;
+  }
+  const order = [...scc].sort(
+    (a, b) => byteCompare(peerlessDepID(a), peerlessDepID(b)) || byteCompare(mapGet(color, a), mapGet(color, b)) || byteCompare(a.id, b.id)
+  );
+  return { order, colors: color };
+};
+var colorClassKey = (node, colors) => `${peerlessDepID(node)}${NUL}${mapGet(colors, node)}`;
+var mergeNode = (graph, winner, loser) => {
+  winner.dev &&= loser.dev;
+  winner.optional &&= loser.optional;
+  copyPackageMetadata(winner, loser);
+  if (!winner.manifest && loser.manifest) {
+    winner.manifest = loser.manifest;
+    graph.manifests.set(winner.id, loser.manifest);
+  }
+  for (const edge of loser.edgesIn) {
+    edge.to = winner;
+    winner.edgesIn.add(edge);
+  }
+  loser.edgesIn.clear();
+  for (const edge of loser.edgesOut.values()) {
+    graph.edges.delete(edge);
+    edge.to?.edgesIn.delete(edge);
+  }
+  loser.edgesOut.clear();
+  const nbn = graph.nodesByName.get(loser.name);
+  if (nbn) {
+    nbn.delete(loser);
+    if (nbn.size === 0) graph.nodesByName.delete(loser.name);
+  }
+};
+var applyAssignments = (graph, keep, losers) => {
+  const newKeys = /* @__PURE__ */ new Map();
+  for (const a of keep) newKeys.set(a.newId, a.node);
+  for (const a of keep) {
+    if (a.node.id !== a.newId && !newKeys.has(a.node.id)) {
+      graph.nodes.delete(a.node.id);
+      graph.manifests.delete(a.node.id);
+    }
+  }
+  for (const loser of losers.keys()) {
+    graph.nodes.delete(loser.id);
+    graph.manifests.delete(loser.id);
+  }
+  const moves = [];
+  for (const a of keep) {
+    if (a.node.id !== a.newId) {
+      const from = a.node.id;
+      a.node.setPeerIdentity(a.newId, a.suffix);
+      if (a.node.extracted) {
+        moves.push({ node: a.node, from, to: a.newId });
+      }
+    } else {
+      a.node.peerSetHash = a.suffix;
+    }
+  }
+  for (const a of keep) {
+    graph.nodes.set(a.newId, a.node);
+    if (a.node.manifest) {
+      graph.manifests.set(a.newId, a.node.manifest);
+    }
+  }
+  for (const [loser, winner] of losers) {
+    if (loser.extracted) {
+      moves.push({ node: loser, from: loser.id });
+    }
+    mergeNode(graph, winner, loser);
+  }
+  const names = /* @__PURE__ */ new Set();
+  for (const a of keep) names.add(a.node.name);
+  for (const loser of losers.keys()) names.add(loser.name);
+  for (const name of names) {
+    const nbn = graph.nodesByName.get(name);
+    if (!nbn) continue;
+    graph.nodesByName.set(
+      name,
+      new Set(
+        [...nbn].sort((a, b) => a.id.localeCompare(b.id, "en"))
+      )
+    );
+  }
+  graph.resolutions.clear();
+  graph.resolutionsReverse.clear();
+  if (losers.size > 0) graph.gc();
+  graph.sortNodes();
+  return moves;
+};
+var canonicalizePeerIds = (graph, options = {}) => {
+  const digest = options.digest ?? peerEnvDigest;
+  const scoped = [...graph.nodes.values()].filter((n) => isPeerScoped(n, graph)).sort((a, b) => byteCompare(a.id, b.id));
+  if (!scoped.length) return [];
+  const scopedSet = new Set(scoped);
+  const adj = /* @__PURE__ */ new Map();
+  for (const node of scoped) {
+    const next = [];
+    const seen = /* @__PURE__ */ new Set();
+    for (const edge of node.edgesOut.values()) {
+      const to = edge.to;
+      if (!to || !scopedSet.has(to) || seen.has(to)) continue;
+      seen.add(to);
+      next.push(to);
+    }
+    next.sort((a, b) => byteCompare(a.id, b.id));
+    adj.set(node, next);
+  }
+  const resolvedIds = /* @__PURE__ */ new Map();
+  const keep = [];
+  const byNewId = /* @__PURE__ */ new Map();
+  const losers = /* @__PURE__ */ new Map();
+  const takeSuffix = (node, ser, hex, roleIdx, roleCount) => {
+    const makeSuffix = (h) => roleCount > 1 ? `${PEER_PREFIX}${h}.${roleIdx}` : `${PEER_PREFIX}${h}`;
+    let suffix = makeSuffix(hex);
+    let newId = withPeerSuffix(node, suffix);
+    let occupant = byNewId.get(newId);
+    if (occupant && occupant.ser !== ser) {
+      suffix = makeSuffix(digest(ser, 32));
+      newId = withPeerSuffix(node, suffix);
+      occupant = byNewId.get(newId);
+      if (occupant && occupant.ser !== ser) {
+        suffix = `${suffix}.x`;
+        newId = withPeerSuffix(node, suffix);
+        occupant = void 0;
+      }
+    }
+    if (occupant?.ser === ser) {
+      losers.set(node, occupant.node);
+      resolvedIds.set(node, occupant.newId);
+      return;
+    }
+    const assigned = { node, ser, suffix, newId };
+    byNewId.set(newId, assigned);
+    keep.push(assigned);
+    resolvedIds.set(node, newId);
+  };
+  for (const scc of tarjan(scoped, adj)) {
+    if (scc.length === 1 && scc[0]) {
+      const node = scc[0];
+      const intraSccIndex2 = hasSelfEdge(node) ? /* @__PURE__ */ new Map([[node, 0]]) : void 0;
+      const ser = unitEntry(node, { resolvedIds, intraSccIndex: intraSccIndex2 });
+      takeSuffix(node, ser, digest(ser, 16), 0, 1);
+      continue;
+    }
+    const { order, colors } = refineSccOrder(scc, resolvedIds);
+    const seenClass = /* @__PURE__ */ new Set();
+    const reps = [];
+    for (const n of order) {
+      const key = colorClassKey(n, colors);
+      if (seenClass.has(key)) continue;
+      seenClass.add(key);
+      reps.push(n);
+    }
+    const classIdx = /* @__PURE__ */ new Map();
+    for (const [i, n] of reps.entries()) {
+      classIdx.set(colorClassKey(n, colors), i);
+    }
+    const intraSccIndex = /* @__PURE__ */ new Map();
+    for (const n of order) {
+      intraSccIndex.set(
+        n,
+        /* c8 ignore next */
+        classIdx.get(colorClassKey(n, colors)) ?? 0
+      );
+    }
+    const unit = reps.map((n) => unitEntry(n, { resolvedIds, intraSccIndex })).join(NL);
+    const hex = digest(unit, 16);
+    const roleIdx = /* @__PURE__ */ new Map();
+    const rolesPerBase = /* @__PURE__ */ new Map();
+    for (const n of reps) {
+      const base = peerlessDepID(n);
+      const key = colorClassKey(n, colors);
+      if (!roleIdx.has(key)) {
+        const next = rolesPerBase.get(base) ?? 0;
+        roleIdx.set(key, next);
+        rolesPerBase.set(base, next + 1);
+      }
+    }
+    for (const n of order) {
+      const key = colorClassKey(n, colors);
+      const idx = roleIdx.get(key) ?? 0;
+      const count = rolesPerBase.get(peerlessDepID(n)) ?? 1;
+      takeSuffix(n, unit, hex, idx, count);
+    }
+  }
+  return applyAssignments(graph, keep, losers);
+};
+
+// ../../src/graph/src/ideal/move-peer-store-dirs.ts
+import { existsSync as existsSync4 } from "node:fs";
+import { rename as rename2 } from "node:fs/promises";
+var movePeerStoreDirs = async (moves, {
+  scurry,
+  remover
+}) => {
+  if (!moves.length) return;
+  const store = scurry.resolve("node_modules/.vlt");
+  const key = String(Math.random()).substring(2);
+  const staged = await Promise.all(
+    moves.map(async ({ node, from, to }) => {
+      const src = scurry.resolve(store, from);
+      if (!to) {
+        try {
+          await remover.rm(src);
+        } catch {
+        }
+        return;
+      }
+      const tmp = scurry.resolve(store, `.VLT.MOVE.${key}.${to}`);
+      try {
+        await rename2(src, tmp);
+      } catch {
+        node.extracted = false;
+        return;
+      }
+      return { node, tmp, dest: scurry.resolve(store, to) };
+    })
+  );
+  await Promise.all(
+    staged.map(async (s) => {
+      if (!s) return;
+      const { node, tmp, dest } = s;
+      try {
+        await remover.rm(dest);
+        await rename2(tmp, dest);
+      } catch {
+        node.extracted = false;
+        try {
+          await remover.rm(tmp);
+        } catch {
+        }
+        return;
+      }
+      if (!existsSync4(node.resolvedLocation(scurry))) {
+        node.extracted = false;
+      }
+    })
+  );
+};
+
 // ../../src/graph/src/reify/calculate-save-value.ts
 var DEFAULT_SAVE_PREFIX = "^";
 var calculateSaveValue = (nodeType, spec2, existing, nodeVersion, saveExact, savePrefix) => {
@@ -11783,9 +12452,10 @@ var calculateSaveValue = (nodeType, spec2, existing, nodeVersion, saveExact, sav
 // ../../src/graph/src/fixup-added-names.ts
 var fixupAddedNames = (add, manifest, options, spec2) => {
   if (add && manifest?.name && spec2.name === "(unknown)") {
-    const s = add.get(String(spec2));
+    const key = addKey(spec2);
+    const s = add.get(key);
     if (s) {
-      add.delete(String(spec2));
+      add.delete(key);
       spec2 = Spec2.parse(manifest.name, spec2.bareSpec, options);
       const n = {
         type: s.type,
@@ -11948,17 +12618,28 @@ var parseSpec = (name, bareSpec, fromNode, graph) => Spec2.parse(name, bareSpec,
   ...graph.mainImporter.options,
   registry: fromNode.registry ?? graph.mainImporter.options.registry
 });
+var ownSpecs = (entry) => {
+  if (entry.sharedSpecs) {
+    entry.specs = new Map(entry.specs);
+    entry.sharedSpecs = false;
+  }
+  return entry.specs;
+};
+var bumpRev = (peerContext) => {
+  peerContext.rev = (peerContext.rev ?? 0) + 1;
+};
 var getForkKey = (peerContext, entries) => {
   const base = peerContext.index ?? 0;
   const sig = entries.map(
     (e) => `${e.spec.final.name}|${e.type}|${e.target?.id ?? "\u2205"}|${e.spec}`
   ).sort().join(";");
-  return `${base}::${sig}`;
+  return `${base}::${sig}::r${peerContext.rev ?? 0}`;
 };
 var shouldIgnoreContextMismatch = (peerName, contextTarget, fromNode, graph) => {
   const parentManifest = fromNode.manifest;
   if (!parentManifest) return false;
   for (const depType of longDependencyTypes) {
+    if (!shouldInstallDepType(fromNode, depType)) continue;
     const declared = parentManifest[depType]?.[peerName];
     if (!declared) continue;
     const parentSpec = parseSpec(peerName, declared, fromNode, graph);
@@ -11980,7 +12661,42 @@ var buildIncompatibleResult = (target, peerSpec, type2, fromNode, graph) => {
   }
   return void 0;
 };
-var checkPeerEdgesCompatible = (existingNode, fromNode, peerContext, graph) => {
+var findProvidedPeer = (peerName, peerSpec, fromNode, peerContext, parseOpts, satisfiesNodeSpec, pending) => {
+  const sibling = fromNode.edgesOut.get(peerName);
+  if (sibling?.to && satisfiesNodeSpec(sibling.to, peerSpec)) {
+    return { target: sibling.to, spec: peerSpec, type: sibling.type };
+  }
+  let declared;
+  const pendingDep = pending?.get(peerName);
+  if (pendingDep) {
+    declared = { spec: pendingDep.spec, type: pendingDep.type };
+  } else if (!pending && fromNode.manifest) {
+    const manifest = fromNode.manifest;
+    for (const depType of longDependencyTypes) {
+      if (!shouldInstallDepType(fromNode, depType)) continue;
+      const bare = manifest[depType]?.[peerName];
+      if (!bare) continue;
+      const type2 = shorten(depType, peerName, manifest);
+      if (type2 === "peerOptional") continue;
+      declared = { spec: Spec2.parse(peerName, bare, parseOpts), type: type2 };
+      break;
+    }
+  }
+  if (declared) {
+    const pf = declared.spec.final;
+    const sf = peerSpec.final;
+    if (pf.type === "registry" && sf.type === "registry" && pf.range && sf.range && !intersects(pf.range, sf.range)) {
+      return void 0;
+    }
+    return { spec: declared.spec, type: declared.type };
+  }
+  const entry = peerContext.get(peerName);
+  if (entry?.target && satisfiesNodeSpec(entry.target, peerSpec)) {
+    return { target: entry.target, spec: peerSpec, type: entry.type };
+  }
+  return void 0;
+};
+var checkPeerEdgesCompatible = (existingNode, fromNode, peerContext, graph, pending) => {
   const peerDeps = existingNode.manifest?.peerDependencies;
   if (!peerDeps || Object.keys(peerDeps).length === 0) {
     return { compatible: true };
@@ -12021,7 +12737,31 @@ var checkPeerEdgesCompatible = (existingNode, fromNode, peerContext, graph) => {
     if (existingEdge === void 0) {
       return { compatible: false };
     }
-    if (!existingEdge.to) continue;
+    if (!existingEdge.to) {
+      if (existingEdge.type === "peerOptional") {
+        const provided = findProvidedPeer(
+          peerName,
+          Spec2.parse(peerName, peerBareSpec, parseOpts),
+          fromNode,
+          peerContext,
+          parseOpts,
+          satisfiesNodeSpec,
+          pending
+        );
+        if (provided) {
+          return {
+            compatible: false,
+            forkEntry: {
+              spec: provided.spec,
+              target: provided.target,
+              type: provided.type
+            },
+            keepVersion: true
+          };
+        }
+      }
+      continue;
+    }
     const peerSpec = Spec2.parse(peerName, peerBareSpec, parseOpts);
     const contextEntry = peerContext.get(peerName);
     if (contextEntry?.target && contextEntry.target.id !== existingEdge.to.id && !shouldIgnoreContextMismatch(
@@ -12071,6 +12811,7 @@ var checkPeerEdgesCompatible = (existingNode, fromNode, peerContext, graph) => {
     let declaredType;
     if (manifest) {
       for (const depType of longDependencyTypes) {
+        if (!shouldInstallDepType(fromNode, depType)) continue;
         const deps = manifest[depType];
         if (deps && typeof deps === "object" && !Array.isArray(deps) && peerName in deps) {
           declared = deps[peerName];
@@ -12087,6 +12828,7 @@ var checkPeerEdgesCompatible = (existingNode, fromNode, peerContext, graph) => {
       const candidates = graph.nodesByName.get(peerName);
       if (candidates) {
         for (const candidateNode of candidates) {
+          if (candidateNode.detached) continue;
           if (candidateNode.id !== existingEdge.to.id && satisfiesNodeSpec(candidateNode, parentSpec) && satisfiesNodeSpec(candidateNode, peerSpec)) {
             return {
               compatible: false,
@@ -12104,8 +12846,8 @@ var checkPeerEdgesCompatible = (existingNode, fromNode, peerContext, graph) => {
   return { compatible: true };
 };
 var retrievePeerContextHash = (peerContext) => {
-  if (!peerContext?.index) return void 0;
-  return `peer.${peerContext.index}`;
+  if (!peerContext) return void 0;
+  return `peer.${peerContext.index ?? 0}`;
 };
 var peerSpecKey = (spec2) => {
   const f = spec2.final;
@@ -12140,6 +12882,15 @@ var checkEntriesToPeerContext = (peerContext, entries) => {
 };
 var addEntriesToPeerContext = (peerContext, entries, fromNode, monorepo) => {
   if (checkEntriesToPeerContext(peerContext, entries)) return true;
+  const satisfiesEntrySpecs = (node, entry, from) => [...entry.specs.values()].every(
+    (s) => satisfies2(
+      node.id,
+      s,
+      from.location,
+      from.projectRoot,
+      monorepo
+    )
+  );
   for (const { dependent, spec: spec2, target, type: type2 } of entries) {
     const name = target?.name ?? spec2.final.name;
     let entry = peerContext.get(name);
@@ -12152,34 +12903,31 @@ var addEntriesToPeerContext = (peerContext, entries, fromNode, monorepo) => {
         contextDependents: /* @__PURE__ */ new Set()
       };
       peerContext.set(name, entry);
+      bumpRev(peerContext);
       if (dependent) entry.contextDependents.add(dependent);
       continue;
     }
     if (incompatibleSpecs(spec2.final, entry)) return true;
-    if (target && [...entry.specs.values()].every(
-      (s) => satisfies2(
-        target.id,
-        s,
-        fromNode.location,
-        fromNode.projectRoot,
-        monorepo
-      )
-    )) {
+    const specKey = peerSpecKey(spec2);
+    if (!entry.specs.has(specKey)) ownSpecs(entry).set(specKey, spec2);
+    if (target && satisfiesEntrySpecs(target, entry, fromNode)) {
       if (target.id !== entry.target?.id && target.version !== entry.target?.version) {
         for (const dep of entry.contextDependents) {
           const edge = dep.edgesOut.get(name);
-          if (edge?.to && edge.to !== target) {
-            edge.to.edgesIn.delete(edge);
-            edge.to = target;
-            target.edgesIn.add(edge);
-          }
+          if (!edge?.to || edge.to === target) continue;
+          if (satisfiesEntrySpecs(edge.to, entry, dep)) continue;
+          dep.graph.mutations++;
+          edge.to.edgesIn.delete(edge);
+          edge.to = target;
+          target.edgesIn.add(edge);
         }
         entry.target = target;
+        bumpRev(peerContext);
+      } else if (!entry.target) {
+        entry.target = target;
+        bumpRev(peerContext);
       }
-      entry.target ??= target;
     }
-    const specKey = peerSpecKey(spec2);
-    if (!entry.specs.has(specKey)) entry.specs.set(specKey, spec2);
     if (dependent) entry.contextDependents.add(dependent);
   }
   return false;
@@ -12195,20 +12943,25 @@ var forkPeerContext = (graph, peerContext, entries) => {
   graph.peerContexts[nextPeerContext.index] = nextPeerContext;
   graph.peerContextForkCache.set(forkKey, nextPeerContext);
   for (const [name, entry] of peerContext.entries()) {
+    entry.sharedSpecs = true;
     nextPeerContext.set(name, {
       active: false,
-      specs: new Map(entry.specs),
-      target: void 0,
+      sharedSpecs: true,
+      specs: entry.specs,
+      target: entry.target,
       type: entry.type,
-      contextDependents: new Set(entry.contextDependents)
+      contextDependents: /* @__PURE__ */ new Set()
     });
   }
   for (const entry of entries) {
     const { dependent, spec: spec2, target, type: type2 } = entry;
     const name = target?.name ?? spec2.final.name;
+    const inherited = peerContext.get(name);
+    const specs = inherited?.target && inherited.target === target ? new Map(inherited.specs) : /* @__PURE__ */ new Map();
+    specs.set(peerSpecKey(spec2), spec2);
     const newEntry = {
       active: true,
-      specs: /* @__PURE__ */ new Map([[peerSpecKey(spec2), spec2]]),
+      specs,
       target,
       type: type2,
       contextDependents: dependent ? /* @__PURE__ */ new Set([dependent]) : /* @__PURE__ */ new Set()
@@ -12340,10 +13093,11 @@ var endPeerPlacement = (peerContext, nextDeps, nextPeerDeps, graph, spec2, fromN
       const siblingEntry = queuedEntries.find(
         (e) => (e.target?.name ?? e.spec.final.name) === name
       );
-      const siblingTarget = siblingEntry?.target ?? fromNode.edgesOut.get(name)?.to;
+      const siblingTarget = fromNode.edgesOut.get(name)?.to ?? siblingEntry?.target;
       if (siblingTarget && nodeSatisfiesSpec(siblingTarget, spec3, fromNode, graph)) {
         const existingEdge = node.edgesOut.get(name);
         if (existingEdge?.to && existingEdge.to !== siblingTarget) {
+          graph.mutations++;
           existingEdge.to.edgesIn.delete(existingEdge);
           existingEdge.to = siblingTarget;
           siblingTarget.edgesIn.add(existingEdge);
@@ -12368,7 +13122,7 @@ var endPeerPlacement = (peerContext, nextDeps, nextPeerDeps, graph, spec2, fromN
         graph.addEdge(type3, spec3, node, entry.target);
         const finalKey = peerSpecKey(spec3.final);
         if (!entry.specs.has(finalKey)) {
-          entry.specs.set(finalKey, spec3.final);
+          ownSpecs(entry).set(finalKey, spec3.final);
         }
         continue;
       }
@@ -12424,7 +13178,6 @@ var postPlacementPeerCheck = (graph, sortedLevelResults) => {
 };
 
 // ../../src/graph/src/ideal/append-nodes.ts
-var shouldInstallDepType = (node, depType) => depType !== "devDependencies" || node.importer || node.id.startsWith("git");
 var getFileTypeInfo = (spec2, fromNode, scurry) => {
   const f = spec2.final;
   if (f.type !== "file") return;
@@ -12441,56 +13194,86 @@ var getFileTypeInfo = (spec2, fromNode, scurry) => {
   };
 };
 var isStringArray2 = (a) => Array.isArray(a) && !a.some((b) => typeof b !== "string");
-var findCompatibleResolution = (spec2, fromNode, graph, peerContext, queryModifier, _peer) => {
-  const fromLoc = fromNode.location;
-  const projectRoot = graph.projectRoot;
-  const monorepo = graph.monorepo;
+var actualBases = /* @__PURE__ */ new WeakMap();
+var hasActualBase = (actual2, id2) => {
+  let bases = actualBases.get(actual2);
+  if (!bases) {
+    bases = new Set([...actual2.nodes.keys()].map(baseDepID));
+    actualBases.set(actual2, bases);
+  }
+  return bases.has(baseDepID(id2));
+};
+var lockedFits = (n, spec2, fromNode, graph) => {
   const final = spec2.final;
-  const satisfiesCache = /* @__PURE__ */ new Map();
-  const satisfiesFinal = (n) => {
-    const key = n.id;
-    const cached = satisfiesCache.get(key);
-    if (cached !== void 0) {
-      return cached;
-    }
-    const result = satisfies2(
-      key,
-      final,
-      fromLoc,
-      projectRoot,
-      monorepo
-    );
-    satisfiesCache.set(key, result);
-    return result;
-  };
-  const existingEdge = fromNode.edgesOut.get(spec2.name);
-  let existingNode;
-  if (existingEdge?.to && !existingEdge.to.detached && satisfiesFinal(existingEdge.to)) {
-    existingNode = existingEdge.to;
-  } else {
-    existingNode = graph.findResolution(spec2, fromNode, queryModifier);
+  if (satisfies2(
+    n.id,
+    final,
+    fromNode.location,
+    graph.projectRoot,
+    graph.monorepo
+  )) {
+    return true;
   }
+  if (final.type !== "registry") return false;
+  const [idType, idRegistry] = splitDepID(n.id);
+  if (idType !== "registry") return false;
+  const expected = getTuple(spec2, {
+    name: n.name,
+    version: n.version
+  });
+  if (idRegistry !== expected[1]) return false;
+  if (n.name !== final.name) return false;
+  if (!final.range) return true;
+  if (!n.version) return false;
+  const version = parse(n.version);
+  return !!version && final.range.test(version);
+};
+var findLockedNode = (graph, fromNode, name) => {
+  const locked = graph.lockedResolutions;
+  if (!locked) return;
+  let id2 = locked.get(`${fromNode.id}\0${name}`);
+  if (id2 === void 0) {
+    const baseFrom = baseDepID(fromNode.id);
+    if (baseFrom !== fromNode.id) {
+      id2 = locked.get(`${baseFrom}\0${name}`);
+    }
+  }
+  return id2 ? graph.nodes.get(id2) : void 0;
+};
+var findCompatibleResolution = (spec2, fromNode, graph, peerContext, candidate, pending) => {
+  const final = spec2.final;
+  let existingNode = candidate;
   let peerCompatResult = existingNode ? checkPeerEdgesCompatible(
     existingNode,
     fromNode,
     peerContext,
-    graph
+    graph,
+    pending
   ) : { compatible: true };
   if (existingNode && !peerCompatResult.compatible) {
     const candidates = graph.nodesByName.get(final.name);
     if (candidates && candidates.size > 1) {
-      for (const candidate of candidates) {
-        if (candidate === existingNode) continue;
-        if (candidate.detached) continue;
-        if (!satisfiesFinal(candidate)) continue;
+      for (const alt of candidates) {
+        if (alt === existingNode) continue;
+        if (alt.detached) continue;
+        if (!satisfies2(
+          alt.id,
+          final,
+          fromNode.location,
+          graph.projectRoot,
+          graph.monorepo
+        )) {
+          continue;
+        }
         const compat = checkPeerEdgesCompatible(
-          candidate,
+          alt,
           fromNode,
           peerContext,
-          graph
+          graph,
+          pending
         );
         if (compat.compatible) {
-          existingNode = candidate;
+          existingNode = alt;
           peerCompatResult = compat;
           break;
         }
@@ -12499,15 +13282,40 @@ var findCompatibleResolution = (spec2, fromNode, graph, peerContext, queryModifi
   }
   return { existingNode, peerCompatResult };
 };
-var fetchManifestsForDeps = async (packageInfo, graph, fromNode, deps, scurry, peerContext, modifierRefs, depth = 0) => {
+var lockedVersionFetch = (node, spec2, options) => {
+  if (spec2.final.type !== "registry" || !node.version) return;
+  const bare = hydrate2(node.id, spec2.name, options).bareSpec;
+  const exact = Spec2.parse(spec2.name, bare, options);
+  if (exact.final.registry !== spec2.final.registry) return;
+  return { spec: exact, version: node.version };
+};
+var hydrateLockedNode = (node, spec2, graph, packageInfo, options, from, hydrations) => {
+  const seen = hydrations.get(node.id);
+  if (seen) return seen;
+  const locked = lockedVersionFetch(node, spec2, options);
+  if (!locked) return;
+  const hydration = packageInfo.manifest(locked.spec, { from }).then(
+    (manifest) => manifest,
+    () => void 0
+  ).then((manifest) => {
+    if (manifest?.version !== locked.version) return;
+    node.manifest = normalizeManifest(manifest, String(locked.spec));
+    graph.manifests.set(node.id, node.manifest);
+  });
+  hydrations.set(node.id, hydration);
+  return hydration;
+};
+var fetchManifestsForDeps = async (packageInfo, graph, fromNode, deps, scurry, options, hydrations, peerContext, modifierRefs, depth = 0, explicit) => {
   const fetchTasks = [];
   const placementTasks = [];
   const reuseTasks = [];
   const forkRequests = [];
+  const entries = [];
   for (const { spec: originalSpec, type: type2 } of deps) {
     let spec2 = originalSpec;
     const fileTypeInfo = getFileTypeInfo(spec2, fromNode, scurry);
     const activeModifier = modifierRefs?.get(spec2.name);
+    const isExplicit = !!explicit?.get(fromNode.id)?.has(addKey(originalSpec));
     const queryModifier = activeModifier?.modifier.query;
     const completeModifier = activeModifier && activeModifier.interactiveBreadcrumb.current === activeModifier.modifier.breadcrumb.last;
     if (queryModifier && completeModifier && "spec" in activeModifier.modifier) {
@@ -12516,15 +13324,73 @@ var fetchManifestsForDeps = async (packageInfo, graph, fromNode, deps, scurry, p
         continue;
       }
     }
+    entries.push({
+      spec: spec2,
+      type: type2,
+      fileTypeInfo,
+      activeModifier,
+      queryModifier,
+      isExplicit,
+      // read after the modifier swap, so an --override that replaces the
+      // tag with a range keeps today's reuse
+      explicitTag: isExplicit && !!spec2.final.distTag
+    });
+  }
+  const pendingDeps = /* @__PURE__ */ new Map();
+  for (const e of entries) pendingDeps.set(e.spec.name, e);
+  const from = scurry.resolve(fromNode.location);
+  const pending = [];
+  for (const e of entries) {
+    const existing = fromNode.edgesOut.get(e.spec.name)?.to;
+    if (existing && !existing.detached && satisfies2(
+      existing.id,
+      e.spec.final,
+      fromNode.location,
+      graph.projectRoot,
+      graph.monorepo
+    )) {
+      e.candidate = existing;
+      continue;
+    }
+    const locked = findLockedNode(graph, fromNode, e.spec.name);
+    e.candidate = locked && lockedFits(locked, e.spec, fromNode, graph) ? locked : graph.findResolution(e.spec, fromNode, e.queryModifier);
+    if (e.explicitTag) continue;
+    if (e.candidate?.detached && !e.candidate.manifest) {
+      const hydration = hydrateLockedNode(
+        e.candidate,
+        e.spec,
+        graph,
+        packageInfo,
+        options,
+        from,
+        hydrations
+      );
+      if (hydration) pending.push(hydration);
+    }
+  }
+  await Promise.all(pending);
+  for (const {
+    spec: spec2,
+    type: type2,
+    fileTypeInfo,
+    activeModifier,
+    queryModifier,
+    isExplicit,
+    explicitTag,
+    candidate
+  } of entries) {
     const peer2 = type2 === "peer" || type2 === "peerOptional";
-    const { existingNode, peerCompatResult } = findCompatibleResolution(
+    const resolved = findCompatibleResolution(
       spec2,
       fromNode,
       graph,
       peerContext,
-      queryModifier,
-      peer2
+      candidate,
+      pendingDeps
     );
+    const dropForTag = explicitTag && !!resolved.existingNode && !resolved.existingNode.importer;
+    const existingNode = dropForTag ? void 0 : resolved.existingNode;
+    const peerCompatResult = dropForTag ? { compatible: true } : resolved.peerCompatResult;
     const effectivePeerContext = peerContext;
     if (!peerCompatResult.compatible && peerCompatResult.forkEntry) {
       forkRequests.push(peerCompatResult.forkEntry);
@@ -12550,11 +13416,15 @@ var fetchManifestsForDeps = async (packageInfo, graph, fromNode, deps, scurry, p
     const edgeOptional = type2 === "optional" || type2 === "peerOptional";
     const manifestPromise = (
       // the "detached" node state means that it has already been load as
-      // part of a graph (either lockfile or actual) and it has valid manifest
-      // data so we shortcut the package info manifest fetch here
-      existingNode?.detached && existingNode.manifest ? Promise.resolve(existingNode.manifest) : packageInfo.manifest(spec2, { from: scurry.resolve(fromNode.location) }).then((manifest) => manifest).catch((er) => {
+      // part of a graph (either lockfile or actual), or was hydrated with
+      // its locked version above, and it has valid manifest data so we
+      // shortcut the package info manifest fetch here
+      // `keepVersion` marks a fork that only differs by an optional peer
+      // link, so the copy keeps the version it forked from instead of
+      // re-resolving the range to the newest satisfying release
+      existingNode?.manifest && (existingNode.detached || peerCompatResult.keepVersion) ? Promise.resolve(existingNode.manifest) : packageInfo.manifest(spec2, { from }).then((manifest) => manifest).catch((er) => {
         if (isPathSecurityError(er)) throw er;
-        if (edgeOptional || fromNode.optional) {
+        if (!isExplicit && (edgeOptional || fromNode.optional)) {
           return void 0;
         }
         throw er;
@@ -12641,7 +13511,11 @@ var processPlacementTasks = async (graph, options, placementTasks, add, modifier
     }
     const eligibleForExtraction = type2 !== "peer" && type2 !== "peerOptional" && remover && extractPromises && actual2 && scurry && packageInfo && node.inVltStore() && !node.isOptional() && // this fixes an issue with installing `file:pathname` specs
     /* c8 ignore next */
-    !fileTypeInfo?.isDirectory && !node.importer;
+    !fileTypeInfo?.isDirectory && !node.importer && // provisional peer suffixes are rewritten by canonicalizePeerIds,
+    // which moves the store dir into place. Skip when a dir for this
+    // package version already exists: the rewrite most likely lands
+    // back on it, and re-extracting would be pure waste.
+    (!node.peerSetHash || !!fileTypeInfo || !hasActualBase(actual2, node.id));
     if (eligibleForExtraction) {
       if (seenExtracted?.has(node.id)) {
         continue;
@@ -12728,6 +13602,7 @@ var processPlacementTasks = async (graph, options, placementTasks, add, modifier
         }
       }
     }
+    for (const dep of nextDeps) nextPeerDeps.delete(dep.spec.name);
     const updateContext = endPeerPlacement(
       peerContext,
       nextDeps,
@@ -12749,9 +13624,10 @@ var processPlacementTasks = async (graph, options, placementTasks, add, modifier
   }
   return childDepsToProcess;
 };
-var appendNodes = async (packageInfo, graph, fromNode, deps, scurry, options, seen, add, modifiers, modifierRefs, extractPromises, actual2, seenExtracted, remover, transientAdd, transientRemove) => {
+var appendNodes = async (packageInfo, graph, fromNode, deps, scurry, options, seen, add, modifiers, modifierRefs, extractPromises, actual2, seenExtracted, remover, transientAdd, transientRemove, explicit) => {
   if (seen.has(fromNode.id)) return;
   seen.add(fromNode.id);
+  const hydrations = /* @__PURE__ */ new Map();
   let initialPeerContext = graph.peerContexts[0];
   if (!initialPeerContext)
     throw error("no initial peer context found in graph");
@@ -12798,9 +13674,12 @@ var appendNodes = async (packageInfo, graph, fromNode, deps, scurry, options, se
               (a, b) => a.spec.name.localeCompare(b.spec.name, "en")
             ),
             scurry,
+            options,
+            hydrations,
             peerContext,
             nodeModifierRefs,
-            depth
+            depth,
+            explicit
           );
           return {
             entry: {
@@ -12896,23 +13775,53 @@ var refreshIdealGraph = async ({
   packageInfo,
   scurry,
   actual: actual2,
+  explicit,
   remove,
   remover,
   transientAdd,
   transientRemove,
+  lockfileOnly,
   ...specOptions
 }) => {
   const seen = /* @__PURE__ */ new Set();
-  const extractPromises = [];
+  const extractPromises = lockfileOnly ? void 0 : [];
   const seenExtracted = /* @__PURE__ */ new Set();
   const orderedImporters = getOrderedImporters(graph);
+  const specTexts = /* @__PURE__ */ new Map();
+  for (const importer of graph.importers) {
+    for (const [name, edge] of importer.edgesOut) {
+      specTexts.set(`${importer.id}\0${name}`, edge.spec.bareSpec);
+    }
+  }
   const depsPerImporter = /* @__PURE__ */ new Map();
   for (const importer of orderedImporters) {
     const deps = getNodeOrderedDependencies(importer, { add, remove });
     depsPerImporter.set(importer, deps);
   }
   if (add.modifiedDependencies || remove.modifiedDependencies || graph.optionsChanged) {
+    const locked = /* @__PURE__ */ new Map();
+    const ambiguous = /* @__PURE__ */ new Set();
+    const record = (key, id2) => {
+      if (ambiguous.has(key)) return;
+      const prev = locked.get(key);
+      if (prev === void 0) {
+        locked.set(key, id2);
+      } else if (prev !== id2) {
+        locked.delete(key);
+        ambiguous.add(key);
+      }
+    };
+    for (const edge of graph.edges) {
+      if (!edge.to) continue;
+      record(`${edge.from.id}\0${edge.spec.name}`, edge.to.id);
+      const base = baseDepID(edge.from.id);
+      if (base !== edge.from.id) {
+        record(`${base}\0${edge.spec.name}`, edge.to.id);
+      }
+    }
+    graph.lockedResolutions = locked;
     graph.resetEdges();
+    if (graph.optionsChanged) graph.lockfileStale = true;
   }
   for (const importer of orderedImporters) {
     modifiers?.tryImporter(importer);
@@ -12936,20 +13845,34 @@ var refreshIdealGraph = async ({
       seenExtracted,
       remover,
       transientAdd,
-      transientRemove
+      transientRemove,
+      explicit
     );
   }
+  graph.lockedResolutions = void 0;
+  for (const importer of graph.importers) {
+    for (const [name, edge] of importer.edgesOut) {
+      if (specTexts.get(`${importer.id}\0${name}`) !== edge.spec.bareSpec) {
+        graph.lockfileStale = true;
+      }
+    }
+  }
   for (const node of graph.nodes.values()) {
     node.setDefaultLocation();
   }
-  if (extractPromises.length > 0) {
+  if (extractPromises?.length) {
     await Promise.all(extractPromises);
   }
 };
 
 // ../../src/graph/src/ideal/build-ideal-from-starting-graph.ts
 var buildIdealFromStartingGraph = async (options) => {
+  const mutationsBefore = options.graph.mutations;
   const importerSpecs = getImporterSpecs(options);
+  const explicit = /* @__PURE__ */ new Map();
+  for (const [id2, deps] of options.add) {
+    explicit.set(id2, new Set(deps.keys()));
+  }
   options.add.modifiedDependencies = options.add.modifiedDependencies || importerSpecs.add.modifiedDependencies;
   options.remove.modifiedDependencies = options.remove.modifiedDependencies || importerSpecs.remove.modifiedDependencies;
   for (const [nodeId, deps] of importerSpecs.add) {
@@ -12975,12 +13898,26 @@ var buildIdealFromStartingGraph = async (options) => {
       options.remove.get(nodeId)?.add(depName);
     }
   }
+  for (const [edge, dep] of importerSpecs.staleSpecs) {
+    edge.spec = dep.spec;
+    edge.type = resolveSaveType(edge.from, edge.name, dep.type);
+  }
+  if (importerSpecs.staleSpecs.size) {
+    options.graph.lockfileStale = true;
+  }
   await refreshIdealGraph({
     ...options,
+    explicit,
     transientAdd: importerSpecs.transientAdd,
     transientRemove: importerSpecs.transientRemove
   });
   options.graph.gc();
+  if (options.graph.mutations !== mutationsBefore || hasProvisionalPeerIds(options.graph)) {
+    await movePeerStoreDirs(
+      canonicalizePeerIds(options.graph),
+      options
+    );
+  }
   return options.graph;
 };
 
@@ -13031,8 +13968,8 @@ var build3 = async (options) => {
   });
   done();
   if (options.add) {
-    for (const [addKey, value] of options.add.entries()) {
-      if (value.size) validateFileDepNode(res, addKey);
+    for (const [addKey2, value] of options.add.entries()) {
+      if (value.size) validateFileDepNode(res, addKey2);
     }
   }
   if (options.remove) {
@@ -13726,10 +14663,11 @@ var addOrRemoveDeps = (nodeId, graph, addOrRemove, saveExact, savePrefix) => {
           found: dep.type
         });
       }
-      const n = node.edgesOut.get(name)?.to;
-      if (!n) {
+      const edge = node.edgesOut.get(name);
+      if (!edge?.to) {
         throw error("Dependency node could not be found");
       }
+      const n = edge.to;
       const [nodeType] = splitDepID(n.id);
       for (const dtype of longDependencyTypes) {
         if (dtype === depType || !manifest[dtype]) continue;
@@ -13753,6 +14691,10 @@ var addOrRemoveDeps = (nodeId, graph, addOrRemove, saveExact, savePrefix) => {
       );
       dependencies[name] = saveValue;
       manifestChanged = manifestChanged || saveValue !== existing;
+      if (saveValue !== edge.spec.bareSpec) {
+        edge.spec = Spec2.parse(name, saveValue, dep.spec.options);
+        graph.lockfileStale = true;
+      }
     }
   }
   return manifestChanged ? manifest : void 0;
@@ -13829,17 +14771,29 @@ var reify = async (options) => {
     loadManifests: true
   });
   const diff2 = new Diff(actual2, graph);
+  const saveImportersPackageJson = (
+    /* c8 ignore next */
+    options.add?.modifiedDependencies || options.remove?.modifiedDependencies ? updatePackageJson({
+      add: options.add,
+      remove: options.remove,
+      graph,
+      packageJson: options.packageJson,
+      saveExact: options.saveExact,
+      savePrefix: options.savePrefix
+    }) : void 0
+  );
   const noModifiedDependencies = !options.add?.modifiedDependencies && !options.remove?.modifiedDependencies;
   const hasLockfiles = !!scurry.lstatSync("vlt-lock.json") && !!scurry.lstatSync("node_modules/.vlt-lock.json");
   const skipOptionalOnly = noModifiedDependencies && diff2.optionalOnly;
   const skippable = skipOptionalOnly && !options.update && hasLockfiles;
   const res = { diff: diff2 };
   if (!diff2.hasChanges() || skippable) {
-    if (!hasLockfiles) {
-      saveHidden(options);
+    if (!hasLockfiles || graph.lockfileStale) {
+      if (!hasLockfiles || !diff2.hasChanges()) saveHidden(options);
       const lfData = lockfileData(options);
       saveData(lfData, scurry.resolve("vlt-lock.json"), false);
     }
+    saveImportersPackageJson?.();
     const pending = [...actual2.nodes.values()].filter((n) => n.buildState === "needed").map((n) => n.id);
     if (pending.length) {
       res.buildQueue = pending;
@@ -13849,7 +14803,12 @@ var reify = async (options) => {
   }
   let success = false;
   try {
-    const { buildQueue } = await reify_(options, diff2, remover);
+    const { buildQueue } = await reify_(
+      options,
+      diff2,
+      remover,
+      saveImportersPackageJson
+    );
     remover.confirm();
     success = true;
     res.buildQueue = buildQueue;
@@ -13862,29 +14821,9 @@ var reify = async (options) => {
   done();
   return res;
 };
-var reify_ = async (options, diff2, remover) => {
+var reify_ = async (options, diff2, remover, saveImportersPackageJson) => {
   const res = {};
-  const {
-    add,
-    remove,
-    packageInfo,
-    packageJson,
-    scurry,
-    allowScripts,
-    saveExact,
-    savePrefix
-  } = options;
-  const saveImportersPackageJson = (
-    /* c8 ignore next */
-    add?.modifiedDependencies || remove?.modifiedDependencies ? updatePackageJson({
-      add,
-      remove,
-      graph: options.graph,
-      packageJson,
-      saveExact,
-      savePrefix
-    }) : void 0
-  );
+  const { packageInfo, packageJson, scurry, allowScripts } = options;
   const lfData = lockfileData(options);
   const actions = addNodes(
     diff2,
@@ -13930,11 +14869,27 @@ var reify_ = async (options, diff2, remover) => {
 };
 
 // ../../src/graph/src/install.ts
-import { existsSync as existsSync6, rmSync as rmSync3 } from "node:fs";
+import { existsSync as existsSync7, rmSync as rmSync3 } from "node:fs";
 import { resolve as resolve12 } from "node:path";
 
+// ../../src/graph/src/lockfile/format-options-change.ts
+var redactUserinfo = (value) => {
+  if (!URL.canParse(value)) return value;
+  const url = new URL(value);
+  if (!url.username && !url.password) return value;
+  url.username = "";
+  url.password = "";
+  return url.href.replace("://", "://***@");
+};
+var formatOptionsChange = ({
+  section,
+  key,
+  from,
+  to
+}) => `${section}:${key === void 0 ? "" : ` ${key}`} ` + (from === void 0 ? "(missing)" : `"${redactUserinfo(from)}"`) + ` -> ${to === void 0 ? "(removed)" : `"${redactUserinfo(to)}"`}`;
+
 // ../../src/graph/src/uninstall.ts
-import { existsSync as existsSync4, rmSync } from "node:fs";
+import { existsSync as existsSync5, rmSync } from "node:fs";
 import { resolve as resolve10 } from "node:path";
 var uninstall = async (options, remove) => {
   const mainManifest = options.packageJson.read(options.projectRoot);
@@ -13966,6 +14921,7 @@ var uninstall = async (options, remove) => {
         }) : void 0
       );
       saveImportersPackageJson?.();
+      remover.confirm();
       return { graph, diff: void 0 };
     }
     const diff2 = await reify({
@@ -13985,7 +14941,7 @@ var uninstall = async (options, remove) => {
         options.projectRoot,
         "node_modules/.vlt-lock.json"
       );
-      if (existsSync4(hiddenLockfile)) {
+      if (existsSync5(hiddenLockfile)) {
         rmSync(hiddenLockfile, { force: true });
       }
     } catch {
@@ -13995,7 +14951,7 @@ var uninstall = async (options, remove) => {
 };
 
 // ../../src/graph/src/update.ts
-import { existsSync as existsSync5, rmSync as rmSync2 } from "node:fs";
+import { existsSync as existsSync6, rmSync as rmSync2 } from "node:fs";
 import { resolve as resolve11 } from "node:path";
 var update = async (options) => {
   let mainManifest = void 0;
@@ -14049,7 +15005,7 @@ var update = async (options) => {
         options.projectRoot,
         "node_modules/.vlt-lock.json"
       );
-      if (existsSync5(hiddenLockfile)) {
+      if (existsSync6(hiddenLockfile)) {
         rmSync2(hiddenLockfile, { force: true });
       }
     } catch {
@@ -14145,7 +15101,7 @@ var install = async (options, add) => {
   }
   if (options.expectLockfile || options.frozenLockfile) {
     const lockfilePath = resolve12(options.projectRoot, "vlt-lock.json");
-    if (!existsSync6(lockfilePath)) {
+    if (!existsSync7(lockfilePath)) {
       throw error(
         "vlt-lock.json file is required when using --expect-lockfile, --frozen-lockfile, or ci command",
         {
@@ -14173,6 +15129,7 @@ var install = async (options, add) => {
   });
   const specCache = /* @__PURE__ */ new Map();
   const lockfileData2 = options.frozenLockfile ? loadData(options.projectRoot) : void 0;
+  const modifiers = GraphModifier.maybeLoad(options);
   if (options.frozenLockfile) {
     if (add?.modifiedDependencies) {
       const dependencies = [];
@@ -14189,6 +15146,7 @@ var install = async (options, add) => {
     const lockfileGraph = load3({
       ...options,
       mainManifest,
+      modifiers,
       monorepo: fullMonorepo,
       specCache,
       lockfileData: lockfileData2
@@ -14204,12 +15162,15 @@ var install = async (options, add) => {
       graph: lockfileGraph,
       add: emptyAdd,
       remove: emptyRemove,
-      ...options
+      ...options,
+      modifiers
     });
     const specChanges = [];
     for (const importer of lockfileGraph.importers) {
       const deps = getDependencies(importer, options);
       for (const [depName, dep] of deps) {
+        if (modifiers?.targetsImporterEdge(importer, dep.spec))
+          continue;
         const edge = importer.edgesOut.get(depName);
         if (edge?.spec) {
           if (edge.spec.toString() !== dep.spec.toString()) {
@@ -14225,9 +15186,10 @@ var install = async (options, add) => {
     if (importerSpecs.add.modifiedDependencies || importerSpecs.remove.modifiedDependencies || specChanges.length > 0 || lockfileGraph.optionsChanged) {
       const details = [];
       if (lockfileGraph.optionsChanged) {
-        details.push(
-          "  Configuration options have changed (e.g. modifiers, registries, catalogs)"
-        );
+        details.push("  Configuration options have changed:");
+        for (const change of lockfileGraph.optionsChanges) {
+          details.push(`    ${formatOptionsChange(change)}`);
+        }
       }
       if (specChanges.length > 0) {
         details.push(...specChanges);
@@ -14275,7 +15237,7 @@ var install = async (options, add) => {
       options.projectRoot,
       "node_modules"
     );
-    if (existsSync6(nodeModulesPath)) {
+    if (existsSync7(nodeModulesPath)) {
       await remover.rm(nodeModulesPath);
       remover.confirm();
     }
@@ -14284,7 +15246,6 @@ var install = async (options, add) => {
     const remove = Object.assign(/* @__PURE__ */ new Map(), {
       modifiedDependencies: false
     });
-    const modifiers = GraphModifier.maybeLoad(options);
     let act = load4({
       ...options,
       mainManifest,
@@ -14311,7 +15272,6 @@ var install = async (options, add) => {
       lockfileData: lockfileData2
     });
     if (options.lockfileOnly) {
-      lockfile.save({ ...options, graph, modifiers });
       const saveImportersPackageJson = (
         /* c8 ignore next */
         add?.modifiedDependencies || remove.modifiedDependencies ? updatePackageJson({
@@ -14321,7 +15281,9 @@ var install = async (options, add) => {
           remove
         }) : void 0
       );
+      lockfile.save({ ...options, graph, modifiers });
       saveImportersPackageJson?.();
+      remover.confirm();
       return { graph, diff: void 0 };
     }
     const { diff: diff2, buildQueue } = await reify({
@@ -14343,7 +15305,7 @@ var install = async (options, add) => {
         options.projectRoot,
         "node_modules/.vlt-lock.json"
       );
-      if (existsSync6(hiddenLockfile)) {
+      if (existsSync7(hiddenLockfile)) {
         rmSync3(hiddenLockfile, { force: true });
       }
     } catch {
@@ -14354,6 +15316,7 @@ var install = async (options, add) => {
 
 export {
   asDependency,
+  addKey,
   asNode,
   run,
   runFG,