@vltpkg/graph 1.0.0-rc.9 → 1.0.2

package/README.md

@@ -1,3 +1,7 @@
+---
+title: '@vltpkg/graph'
+---
+
 ![graph](https://github.com/user-attachments/assets/dfbed9e0-8ef0-4a43-993d-d3e5d1e5ae1d)
 
 # @vltpkg/graph
@@ -41,57 +45,87 @@ At a glance:
   `node_modules/.vlt-lock.json` mirroring the current on-disk state to
   accelerate subsequent loads of the Actual graph.
 - Modifiers: Configuration for selectively altering dependency
-  resolution; Ideal/Actual builders support skipping node loads when
-  modifiers change.
+  resolution via DSS queries in `vlt.json`.
+- Peer Contexts: Isolation mechanism for peer dependencies that allows
+  multiple versions of the same package when peer requirements differ.
 
 ## API
 
-### `actual.load({ projectRoot: string }): Graph`
+### `actual.load(options): Graph`
 
 Recursively loads the `node_modules` folder found at `projectRoot` in
 order to create a graph representation of the current installed
 packages.
 
-### `async ideal.build({ projectRoot: string }): Promise<Graph>`
+### `ideal.build(options): Promise<Graph>`
 
-This method returns a new `Graph` object, reading from the
-`package.json` file located at `projectRoot` dir and building up the
-graph representation of nodes and edges from the files read from the
-local file system.
+Builds the ideal dependency graph by loading from lockfile (preferred)
+or actual graph, then expanding dependencies by fetching manifests.
+Requires `packageInfo` and `remover` in addition to standard options.
 
-### `lockfile.load({ mainManifest: Manifest, projectRoot: string }): Graph`
+### `lockfile.load(options): Graph`
 
 Loads the lockfile file found at `projectRoot` and returns the graph.
 
-### `reify(options): Promise<Diff>`
+### `lockfile.save(options): void`
+
+Saves the graph to `vlt-lock.json`.
+
+### `reify(options): Promise<ReifyResult>`
 
 Computes a `Diff` between the Actual and Ideal graphs and applies the
 minimal filesystem changes (creating/deleting links, writing
 lockfiles, hoisting, lifecycle scripts) to make the on-disk install
-match the Ideal graph.
+match the Ideal graph. Returns `{ diff, buildQueue }`.
+
+### `install(options, add?): Promise<{ graph, diff, buildQueue }>`
+
+High-level install orchestration that handles graph building, reify,
+and lockfile management. Supports `--frozen-lockfile`,
+`--clean-install`, and `--lockfile-only` modes.
+
+### `mermaidOutput(graph): string`
+
+Generates Mermaid flowchart syntax from graph data.
+
+### `humanReadableOutput(graph, options): string`
+
+Generates ASCII tree output with optional colors. Used in `vlt ls`.
+
+### `jsonOutput(graph): JSONOutputItem[]`
+
+Returns array of `{name, fromID, spec, type, to, overridden}` items.
 
 ## Usage
 
-Here's a quick example of how to use the `@vltpkg/graph.ideal.build`
-method to build a graph representation of the install defined at the
-`projectRoot` directory.
+### High-Level Install
 
-```
-import { ideal } from '@vltpkg/graph'
+```ts
+import { install } from '@vltpkg/graph'
 
-const graph = await ideal.build({ projectRoot: process.cwd() })
+const { graph, diff, buildQueue } = await install({
+  projectRoot: process.cwd(),
+  packageInfo,
+  packageJson,
+  scurry,
+  allowScripts: '*',
+})
 ```
 
 ### Load Actual Graph and Reify
 
 ```ts
 import { actual, ideal, reify } from '@vltpkg/graph'
+import { RollbackRemove } from '@vltpkg/rollback-remove'
+
+const remover = new RollbackRemove()
 
 // Load current on-disk state
 const from = actual.load({
   projectRoot: process.cwd(),
   packageJson,
   scurry,
+  loadManifests: true,
 })
 
 // Build intended end state (may start from lockfile or actual)
@@ -100,15 +134,18 @@ const to = await ideal.build({
   packageInfo,
   packageJson,
   scurry,
+  remover,
 })
 
 // Apply minimal changes to match Ideal
-await reify({
+const { diff, buildQueue } = await reify({
   graph: to,
   actual: from,
   packageInfo,
   packageJson,
   scurry,
+  remover,
+  allowScripts: '*',
 })
 ```
 
@@ -118,15 +155,48 @@ await reify({
 import { lockfile } from '@vltpkg/graph'
 
 // Load virtual graph from vlt-lock.json
-const g = lockfile.load({
+const graph = lockfile.load({
   projectRoot,
   mainManifest,
   packageJson,
-  scurry,
 })
 
-// Save both lockfile formats
-lockfile.save({ graph: g, projectRoot, packageJson, scurry })
+// Save to vlt-lock.json
+lockfile.save({ graph })
+```
+
+### Graph Visualization
+
+```ts
+import {
+  mermaidOutput,
+  humanReadableOutput,
+  jsonOutput,
+} from '@vltpkg/graph'
+
+// Mermaid flowchart (for docs, dashboards)
+const mermaid = mermaidOutput({
+  edges: [...graph.edges],
+  nodes: [...graph.nodes.values()],
+  importers: graph.importers,
+})
+
+// ASCII tree with colors (used in `vlt ls`)
+const tree = humanReadableOutput(
+  {
+    edges: [...graph.edges],
+    nodes: [...graph.nodes.values()],
+    importers: graph.importers,
+  },
+  { colors: true },
+)
+
+// JSON array of dependency items
+const json = jsonOutput({
+  edges: [...graph.edges],
+  nodes: [...graph.nodes.values()],
+  importers: graph.importers,
+})
 ```
 
 ## Architecture
@@ -137,6 +207,7 @@ Graph construction modes supported by the library:
   - Load and save via `src/lockfile/load.ts` and
     `src/lockfile/save.ts`
   - Hidden lockfile: `node_modules/.vlt-lock.json` for faster loads
+  - 📖 [Lockfile README](./src/lockfile/README.md)
 
 - Actual Graphs (filesystem-based)
   - Loaded by traversing `node_modules` via `src/actual/load.ts`
@@ -150,20 +221,28 @@ Graph construction modes supported by the library:
     `src/ideal/get-importer-specs.ts`
   - Fetches and expands manifests using `@vltpkg/package-info`, reuses
     existing nodes that satisfy specs
+  - 📖 [Ideal README](./src/ideal/README.md)
 
 Finally, `src/diff.ts` computes changes and `src/reify/` applies them
 to the filesystem.
 
+- 📖 [Reify README](./src/reify/README.md)
+- 📖 [Architecture Guide](./ARCHITECTURE.md)
+
 ## Related Workspaces
 
 - `@vltpkg/dep-id`: Unique IDs for packages, ensuring `Node` identity
 - `@vltpkg/spec`: Parse/normalize dependency specifiers and registry
   semantics
 - `@vltpkg/semver`: Semantic version parsing/comparison
+- `@vltpkg/satisfies`: Check if a DepID satisfies a Spec
 - `@vltpkg/package-info`: Fetch remote manifests and artifacts
   (registry, git, tarball)
 - `@vltpkg/package-json`: Read and cache local `package.json` files
 - `@vltpkg/workspaces`: Monorepo workspace discovery and grouping
+- `@vltpkg/rollback-remove`: Safe file removal with rollback
+  capability
+- `@vltpkg/vlt-json`: Load `vlt.json` configuration (modifiers, etc.)
 
 ## References
 

package/dist/{esm/actual → actual}/load.d.ts

@@ -91,10 +91,17 @@ export declare const asStoreConfigObject: (obj: unknown) => StoreConfigObject;
  * path-based or a registry spec, otherwise returns `undefined`.
  */
 export declare const getPathBasedId: (spec: Spec, path: Path) => DepID | undefined;
+/**
+ * Verify that all importer node_modules directories exist on disk.
+ * The hidden lockfile may report deps as installed even when a
+ * workspace's node_modules has been manually deleted. Throws if
+ * any importer node_modules directory is missing, causing the
+ * caller to fall through to filesystem-based graph loading.
+ */
+export declare const verifyImporterNodeModules: (graph: Graph, projectRoot: string) => void;
 /**
  * Read the file system looking for `node_modules` folders and
  * returns a new {@link Graph} that represents the relationship
  * between the dependencies found.
  */
 export declare const load: (options: LoadOptions) => Graph;
-//# sourceMappingURL=load.d.ts.map

package/dist/{esm/actual → actual}/load.js

@@ -6,7 +6,8 @@ import { shorten, getRawDependencies, getDependencies, } from "../dependencies.j
 import { Graph } from "../graph.js";
 import { loadHidden } from "../lockfile/load.js";
 import { saveHidden } from "../lockfile/save.js";
-import { readFileSync } from 'node:fs';
+import { existsSync, readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
 /**
  * Checks if a given object is a {@link StoreConfigObject}.
  */
@@ -179,7 +180,10 @@ const parseDir = (options, scurry, packageJson, depsFound, graph, fromNode, curr
             const depType = shorten(type, alias, fromNode.manifest);
             let spec = Spec.parse(alias, bareSpec, {
                 ...options,
-                registry: fromNode.registry,
+                // fall back to options.registry (which the lockfile merges into)
+                // so importer-level edges don't silently revert to the default
+                // npm registry. see vltpkg/vltpkg#1580.
+                registry: fromNode.registry ?? options.registry,
             });
             // Check for active modifiers and replace spec if a modifier is complete
             const { spec: modifiedSpec, queryModifier } = maybeApplyModifierToSpec(spec, alias, modifierRefs);
@@ -238,7 +242,7 @@ const parseDir = (options, scurry, packageJson, depsFound, graph, fromNode, curr
             const depType = shorten(type, name, fromNode.manifest);
             let spec = Spec.parse(name, bareSpec, {
                 ...options,
-                registry: fromNode.registry,
+                registry: fromNode.registry ?? options.registry,
             });
             // Check for active modifiers and replace spec for missing dependencies
             const { spec: modifiedSpec, queryModifier } = maybeApplyModifierToSpec(spec, name, modifierRefs);
@@ -247,6 +251,21 @@ const parseDir = (options, scurry, packageJson, depsFound, graph, fromNode, curr
         }
     }
 };
+/**
+ * Verify that all importer node_modules directories exist on disk.
+ * The hidden lockfile may report deps as installed even when a
+ * workspace's node_modules has been manually deleted. Throws if
+ * any importer node_modules directory is missing, causing the
+ * caller to fall through to filesystem-based graph loading.
+ */
+export const verifyImporterNodeModules = (graph, projectRoot) => {
+    for (const importer of graph.importers) {
+        const nm = resolve(projectRoot, importer.location, 'node_modules');
+        if (!existsSync(nm)) {
+            throw new Error(`Missing node_modules for importer: ${importer.location}`);
+        }
+    }
+};
 /**
  * Read the file system looking for `node_modules` folders and
  * returns a new {@link Graph} that represents the relationship
@@ -267,12 +286,17 @@ export const load = (options) => {
                 monorepo,
                 scurry,
             });
+            verifyImporterNodeModules(graph, projectRoot);
             done();
             return graph;
         }
         catch {
-            // if validation fails or any other error occurs,
-            // fall back to filesystem traversal
+            // Hidden lockfile is cache-only, safe to regenerate on any error
+            // as it will fall back to filesystem traversal. Deliberately also
+            // swallows EINVALIDNAME, unlike ideal/build.ts: this cache lives
+            // inside node_modules and regenerating it is the right response,
+            // whereas failing loud would let it brick installs.
+            // TODO: Warn version mismatch to @vltpkg/output for debugging
         }
     }
     const graph = new Graph({ ...options, mainManifest });
@@ -316,4 +340,3 @@ export const load = (options) => {
     done();
     return graph;
 };
-//# sourceMappingURL=load.js.map

package/dist/{esm/browser.d.ts → browser.d.ts}

@@ -12,4 +12,3 @@ declare const transfer: {
     load: (transfered: import("./transfer-data/load.ts").TransferData) => import("./transfer-data/load.ts").LoadResult;
 };
 export { asDependencyTypeShort, getBooleanFlagsFromNum, lockfile, longDependencyTypes, shorten, stringifyNode, transfer, };
-//# sourceMappingURL=browser.d.ts.map

package/dist/{esm/browser.js → browser.js}

@@ -14,4 +14,3 @@ const transfer = {
     load,
 };
 export { asDependencyTypeShort, getBooleanFlagsFromNum, lockfile, longDependencyTypes, shorten, stringifyNode, transfer, };
-//# sourceMappingURL=browser.js.map

package/dist/{esm/build.d.ts → build.d.ts}

@@ -26,4 +26,3 @@ export interface BuildOptions extends LoadOptions {
  * 6. Persists build results to lockfile
  */
 export declare const build: (options: BuildOptions) => Promise<BuildResult>;
-//# sourceMappingURL=build.d.ts.map

package/dist/{esm/build.js → build.js}

@@ -76,4 +76,3 @@ export const build = async (options) => {
     });
     return buildResult;
 };
-//# sourceMappingURL=build.js.map

package/dist/{esm/dependencies.d.ts → dependencies.d.ts}

@@ -63,4 +63,3 @@ export declare const getRawDependencies: (node: NodeLike) => Map<string, RawDepe
  * from a given node manifest, including missing dependencies.
  */
 export declare const getDependencies: (node: NodeLike, options: SpecOptions) => Map<string, Dependency>;
-//# sourceMappingURL=dependencies.d.ts.map

package/dist/{esm/dependencies.js → dependencies.js}

@@ -100,7 +100,9 @@ export const getDependencies = (node, options) => {
         const depType = shorten(type, name, node.manifest);
         const spec = Spec.parse(name, bareSpec, {
             ...options,
-            registry: node.registry,
+            // fall back to options.registry so deps don't lose the configured
+            // registry when the node itself has none. see vltpkg/vltpkg#1580.
+            registry: node.registry ?? options.registry,
         });
         res.set(name, {
             spec,
@@ -109,4 +111,3 @@ export const getDependencies = (node, options) => {
     }
     return res;
 };
-//# sourceMappingURL=dependencies.js.map

package/dist/{esm/diff.d.ts → diff.d.ts}

@@ -71,6 +71,7 @@ export declare class Diff {
                     engines?: Record<string, string>;
                     os?: string[] | string;
                     cpu?: string[] | string;
+                    libc?: string[] | string;
                 } | undefined;
                 buildState: "none" | "needed" | "built" | "failed";
             }[];
@@ -94,6 +95,7 @@ export declare class Diff {
                     engines?: Record<string, string>;
                     os?: string[] | string;
                     cpu?: string[] | string;
+                    libc?: string[] | string;
                 } | undefined;
                 buildState: "none" | "needed" | "built" | "failed";
             }[];
@@ -115,4 +117,3 @@ export declare class Diff {
     };
 }
 export {};
-//# sourceMappingURL=diff.d.ts.map

package/dist/{esm/diff.js → diff.js}

@@ -80,8 +80,12 @@ export class Diff {
                 continue;
             if (fromEdge?.to)
                 this.edges.delete.add(fromEdge);
-            if (edge.to)
+            if (edge.to) {
                 this.edges.add.add(edge);
+                if (!edge.optional) {
+                    this.optionalOnly = false;
+                }
+            }
         }
         for (const edge of this.from.edges) {
             // the node with this dep, in the to graph
@@ -145,4 +149,3 @@ ${lines
         };
     }
 }
-//# sourceMappingURL=diff.js.map

package/dist/{esm/edge.d.ts → edge.d.ts}

@@ -44,4 +44,3 @@ export declare class Edge implements EdgeLike {
     toString(): string;
 }
 export {};
-//# sourceMappingURL=edge.d.ts.map

package/dist/{esm/edge.js → edge.js}

@@ -75,4 +75,3 @@ export class Edge {
         return `Edge from: ${this.from.id} --|${this.type}|--> ${to}`;
     }
 }
-//# sourceMappingURL=edge.js.map

package/dist/{esm/fixup-added-names.d.ts → fixup-added-names.d.ts}

@@ -11,6 +11,8 @@ import type { SpecOptions } from '@vltpkg/spec';
  *
  * This helper function fixes unknown names in the `add` map by replacing
  * placeholder specs with the correct names from the provided manifest.
+ *
+ * It also fixes empty bareSpec values (from CLI args like `vlt install foo`)
+ * by calculating the proper semver range from the resolved manifest version.
  */
-export declare const fixupAddedNames: (add: Map<string, Dependency> | undefined, manifest: Pick<Manifest, "name"> | undefined, options: SpecOptions, spec: Spec) => Spec;
-//# sourceMappingURL=fixup-added-names.d.ts.map
+export declare const fixupAddedNames: (add: Map<string, Dependency> | undefined, manifest: Pick<Manifest, "name" | "version"> | undefined, options: SpecOptions, spec: Spec) => Spec;

package/dist/{esm/fixup-added-names.js → fixup-added-names.js}

@@ -1,4 +1,5 @@
 import { Spec } from '@vltpkg/spec';
+import { calculateSaveValue } from "./reify/calculate-save-value.js";
 /**
  * When adding new dependencies, it's very common to not have a dependency
  * name directly available to reference, e.g: `file:local/folder` or
@@ -8,6 +9,9 @@ import { Spec } from '@vltpkg/spec';
  *
  * This helper function fixes unknown names in the `add` map by replacing
  * placeholder specs with the correct names from the provided manifest.
+ *
+ * It also fixes empty bareSpec values (from CLI args like `vlt install foo`)
+ * by calculating the proper semver range from the resolved manifest version.
  */
 export const fixupAddedNames = (add, manifest, options, spec) => {
     // Handle nameless dependencies
@@ -26,6 +30,17 @@ export const fixupAddedNames = (add, manifest, options, spec) => {
             add.set(manifest.name, n);
         }
     }
+    // Fix empty bareSpec (usually from CLI args like `vlt install foo`)
+    // by calculating the proper semver range from the resolved manifest version
+    if (add && manifest?.version && !spec.bareSpec) {
+        const addEntry = add.get(spec.name);
+        if (addEntry) {
+            const saveValue = calculateSaveValue(spec.final.type, spec, undefined, manifest.version);
+            if (saveValue && saveValue !== spec.bareSpec) {
+                spec = Spec.parse(spec.name, saveValue, options);
+                addEntry.spec = spec;
+            }
+        }
+    }
     return spec;
 };
-//# sourceMappingURL=fixup-added-names.js.map

package/dist/{esm/graph.d.ts → graph.d.ts}

@@ -78,6 +78,19 @@ export declare class Graph implements GraphLike {
      * The peer context sets used to resolve peer dependencies within this graph.
      */
     peerContexts: PeerContext[];
+    /**
+     * Cache of forked peer contexts so identical fork operations can reuse
+     * previously created contexts instead of duplicating them.
+     *
+     * Key format is internal and constructed in `ideal/peers.ts`.
+     */
+    peerContextForkCache: Map<string, PeerContext>;
+    /**
+     * Whether the options used to create this graph differ from the
+     * options stored in the lockfile it was loaded from. When true,
+     * the ideal builder must reset edges and rebuild the graph.
+     */
+    optionsChanged: boolean;
     /**
      * Tracks the current peer context index.
      */
@@ -144,4 +157,3 @@ export declare class Graph implements GraphLike {
     [kCustomInspect](_: number, options: InspectOptions): string;
 }
 export {};
-//# sourceMappingURL=graph.d.ts.map

package/dist/{esm/graph.js → graph.js}

@@ -1,7 +1,7 @@
 import { getId, joinDepIDTuple, splitExtra } from '@vltpkg/dep-id';
 import { error } from '@vltpkg/error-cause';
 import { satisfies } from '@vltpkg/satisfies';
-import { getOptions, Spec } from '@vltpkg/spec';
+import { assertPathSafeName, getOptions, Spec } from '@vltpkg/spec';
 import { inspect } from 'node:util';
 import { lockfileData } from "./lockfile/save.js";
 import { Edge } from "./edge.js";
@@ -23,9 +23,12 @@ const getResolutionCacheKey = (spec, location, extra) => {
     const fromPrefix = f.type === 'file' ? location + ' : ' : '';
     // the unique key should also precise what is the type of the spec,
     // and in the case of a registry, what registry it is from.
-    const typePrecisionKey = f.registry ?
+    const typePrecisionKey = f.registry || f.type === 'registry' ?
+        // registry-type specs always get a registry segment, even when
+        // no registry is configured, since findResolution trusts cache
+        // hits without re-running satisfies()
         `${cacheKeySeparator}registry` +
-            `${cacheKeySeparator}${f.registry}`
+            `${cacheKeySeparator}${f.registry ?? '<none>'}`
         : f.gitRemote ?
             `${cacheKeySeparator}git` + `${cacheKeySeparator}${f.gitRemote}`
             : `${cacheKeySeparator}${f.type}`;
@@ -86,6 +89,19 @@ export class Graph {
      * The peer context sets used to resolve peer dependencies within this graph.
      */
     peerContexts;
+    /**
+     * Cache of forked peer contexts so identical fork operations can reuse
+     * previously created contexts instead of duplicating them.
+     *
+     * Key format is internal and constructed in `ideal/peers.ts`.
+     */
+    peerContextForkCache = new Map();
+    /**
+     * Whether the options used to create this graph differ from the
+     * options stored in the lockfile it was loaded from. When true,
+     * the ideal builder must reset edges and rebuild the graph.
+     */
+    optionsChanged = false;
     /**
      * Tracks the current peer context index.
      */
@@ -99,7 +115,7 @@ export class Graph {
             registries: options.registries,
             'git-hosts': options['git-hosts'],
             'git-host-archives': options['git-host-archives'],
-            'scope-registries': options['scope-registries'],
+            'scoped-registries': options['scoped-registries'],
             'jsr-registries': options['jsr-registries'],
             catalog: options.catalog,
             catalogs: options.catalogs,
@@ -130,6 +146,12 @@ export class Graph {
                 wsNode.setImporterLocation(`./${ws.path}`);
                 if (wsNode.manifest) {
                     this.manifests.set(wsNode.id, wsNode.manifest);
+                    // set bins for workspace nodes so they can be linked
+                    // when another importer depends on this workspace
+                    /* c8 ignore next 3 - tested by integration tests */
+                    if (wsNode.manifest.bin) {
+                        wsNode.bins = wsNode.manifest.bin;
+                    }
                 }
                 this.importers.add(wsNode);
                 // creates a virtual edge to connect the workspaces to the root node
@@ -192,6 +214,8 @@ export class Graph {
             if (to) {
                 spec.name = to.name /* c8 ignore next */ || '(unknown)';
                 spec.spec = `${to.name}@${spec.bareSpec}`;
+                // this alias becomes the symlink segment in add-edge
+                assertPathSafeName(spec.name, spec.spec);
             }
             else {
                 throw error('Impossible to place a missing, nameless dependency', { spec });
@@ -297,6 +321,18 @@ export class Graph {
             toFoundNode.detached = false;
             toFoundNode.dev &&= flags.dev;
             toFoundNode.optional &&= flags.optional;
+            // Hydrate manifest and integrity on existing nodes (e.g. loaded
+            // from a lockfile without manifest data).  Without this, nodes
+            // that already have `resolved` set from the lockfile will never
+            // get their integrity populated because `setResolved()` is
+            // skipped when `resolved` is already present.
+            if (manifest) {
+                if (!toFoundNode.manifest) {
+                    toFoundNode.manifest = manifest;
+                    this.manifests.set(toFoundNode.id, manifest);
+                }
+                toFoundNode.integrity ??= manifest.dist?.integrity;
+            }
             return toFoundNode;
         }
         // creates a new node and edges to its parent
@@ -312,9 +348,9 @@ export class Graph {
         }
         // add extra manifest info if available
         if (manifest) {
-            const { bin, engines, os, cpu } = manifest;
+            const { bin, engines, os, cpu, libc } = manifest;
             // add platform info if available
-            if (engines || os || cpu) {
+            if (engines || os || cpu || libc) {
                 const platform = {};
                 if (engines)
                     platform.engines = engines;
@@ -322,6 +358,8 @@ export class Graph {
                     platform.os = os;
                 if (cpu)
                     platform.cpu = cpu;
+                if (libc)
+                    platform.libc = libc;
                 toNode.platform = platform;
             }
             // add bin info if available
@@ -405,11 +443,11 @@ export class Graph {
         this.edges.clear();
         // Clear all node edge relationships
         for (const node of this.nodes.values()) {
-            // marking nodes as detached needs to be restricted to only those
-            // that had a manifest, otherwise we'd be skipping fetching manifest
-            // for nodes we don't have a manifest during the ideal build phase
-            if (node.manifest)
-                node.detached = true;
+            // Mark nodes as detached so ideal rebuild treats them as candidates
+            // that must be (re)placed during traversal. Detached nodes with a
+            // manifest can skip refetch; detached nodes without a manifest must
+            // fetch from package-info during ideal rebuild.
+            node.detached = true;
             // detaches all edges from this node
             node.edgesOut.clear();
             node.edgesIn.clear();
@@ -427,4 +465,3 @@ export class Graph {
         return `${this[Symbol.toStringTag]} ${inspect(data, options)}`;
     }
 }
-//# sourceMappingURL=graph.js.map

package/dist/{esm/ideal → ideal}/append-nodes.d.ts

@@ -13,8 +13,19 @@ import type { TransientAddMap, TransientRemoveMap } from './types.ts';
  * Append new nodes in the given `graph` for dependencies specified at `add`
  * and missing dependencies from the `deps` parameter.
  *
- * It also applies any modifiers that applies to a given node as it processes
- * and builds the graph.
+ * Uses **breadth-first traversal** (BFS) with **deterministic ordering** to
+ * ensure reproducible builds. The algorithm:
+ *
+ * 1. Process all deps at the current level in parallel
+ * 2. After each level, run `postPlacementPeerCheck` to handle peer contexts
+ * 3. Collect child deps for the next level
+ * 4. Repeat until no more deps to process
+ *
+ * **Peer Context Isolation**: Each workspace importer gets its own peer context
+ * to prevent cross-workspace leakage. Without this, `react@^18` from workspace A
+ * could incorrectly satisfy `react@^19` peer deps in workspace B.
+ *
+ * **Early Extraction**: When `actual` graph is provided, nodes are extracted
+ * to the vlt store during graph construction (not after), improving performance.
  */
 export declare const appendNodes: (packageInfo: PackageInfoClient, graph: Graph, fromNode: Node, deps: Dependency[], scurry: PathScurry, options: SpecOptions, seen: Set<DepID>, add?: Map<string, Dependency>, modifiers?: GraphModifier, modifierRefs?: Map<string, ModifierActiveEntry>, extractPromises?: Promise<ExtractResult>[], actual?: Graph, seenExtracted?: Set<DepID>, remover?: RollbackRemove, transientAdd?: TransientAddMap, transientRemove?: TransientRemoveMap) => Promise<void>;
-//# sourceMappingURL=append-nodes.d.ts.map