@vltpkg/graph 1.0.7 → 1.0.9

package/dist/ideal/canonicalize-peer-ids.js

@@ -0,0 +1,421 @@
+import { joinDepIDTuple, joinExtra, splitDepID } from '@vltpkg/dep-id';
+import { createHash } from 'node:crypto';
+import { copyPackageMetadata } from "../node.js";
+const NUL = '\0';
+const NL = '\n';
+const MISSING = 'MISSING';
+const PEER_PREFIX = 'peer.';
+/**
+ * Any change to this digest, to `serializeNodeEnv`, to `unitEntry` or to
+ * the suffix format changes every peer id in the lockfile, and the ideal
+ * builder no longer re-hashes a graph it did not otherwise touch. Bump
+ * `LOCKFILE_VERSION` alongside it so old lockfiles hard-fail instead of
+ * lingering with stale ids.
+ */
+export const peerEnvDigest = (input, length = 16) => createHash('sha256').update(input).digest('hex').slice(0, length);
+/**
+ * `peer.<ordinal>` as minted by retrievePeerContextHash() during a
+ * rebuild, or written by lockfiles from before the hash format.
+ * Canonical suffixes are 16 or 32 hex chars, optionally followed by
+ * `.<role>` or `.x`; an all-digit hash is possible, hence the length
+ * bound rather than a plain `\d+`.
+ */
+export const isProvisionalPeerSuffix = (suffix) => /^peer\.\d{1,15}$/.test(suffix);
+/**
+ * True when any node still carries a provisional id, so the graph needs
+ * a canonicalization pass even if this build did not write to it.
+ */
+export const hasProvisionalPeerIds = (graph) => {
+    for (const node of graph.nodes.values()) {
+        if (node.peerSetHash &&
+            isProvisionalPeerSuffix(node.peerSetHash)) {
+            return true;
+        }
+    }
+    return false;
+};
+export const byteCompare = (a, b) => a < b ? -1
+    : a > b ? 1
+        : 0;
+const canCarryPeerSuffix = (node) => {
+    if (node.importer)
+        return false;
+    const type = splitDepID(node.id)[0];
+    return type !== 'file' && type !== 'workspace';
+};
+const hasPeerDependencies = (node, graph) => {
+    const mani = node.manifest ?? graph.manifests.get(node.id);
+    return !!(mani?.peerDependencies &&
+        Object.keys(mani.peerDependencies).length > 0);
+};
+const hasPeerOutEdge = (node) => {
+    for (const edge of node.edgesOut.values()) {
+        if (edge.type === 'peer' || edge.type === 'peerOptional') {
+            return true;
+        }
+    }
+    return false;
+};
+export const isPeerScoped = (node, graph) => {
+    if (!canCarryPeerSuffix(node))
+        return false;
+    return (!!node.peerSetHash ||
+        hasPeerDependencies(node, graph) ||
+        hasPeerOutEdge(node));
+};
+/**
+ * The dependency environment of a node: its out edges as
+ * `name NUL type NUL ref`, byte-sorted and NL-joined. Only how a target
+ * is referenced varies, so callers pass that policy in; the field set,
+ * delimiters, missing-target marker and ordering stay one definition.
+ */
+const 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);
+};
+export const serializeNodeEnv = (node, opts = {}) => {
+    const { resolvedIds, intraSccIndex } = opts;
+    return serializeEdges(node, to => {
+        const idx = intraSccIndex?.get(to);
+        return idx === undefined ?
+            (resolvedIds?.get(to) ?? to.id)
+            : `#${idx}`;
+    });
+};
+const 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;
+    }
+};
+/**
+ * The node's identity minus only its peer component. `baseDepID()` also
+ * drops the modifier, and intra-SCC targets serialize positionally, so
+ * with a bare base a cycle member's modifier would leave no trace in the
+ * cycle's identity and two cycles differing only by it would merge.
+ */
+const peerlessDepID = (node) => withPeerSuffix(node, '');
+/**
+ * One member's contribution to an SCC's identity. A singleton and a
+ * one-class SCC must produce the same string, or collapsing a cycle
+ * renames the survivor on the next pass.
+ */
+const unitEntry = (node, opts) => `${peerlessDepID(node)}${NL}${serializeNodeEnv(node, opts)}`;
+const tarjan = (nodes, adj) => {
+    let index = 0;
+    const indices = new Map();
+    const lowlink = new Map();
+    const onStack = new Set();
+    const stack = [];
+    const sccs = [];
+    const strongconnect = (v) => {
+        indices.set(v, index);
+        lowlink.set(v, index);
+        index++;
+        stack.push(v);
+        onStack.add(v);
+        /* c8 ignore next */
+        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 !== undefined && lw !== undefined && lw < lv) {
+                    lowlink.set(v, lw);
+                }
+            }
+            else if (onStack.has(w)) {
+                const lv = lowlink.get(v);
+                const iw = indices.get(w);
+                if (lv !== undefined && iw !== undefined && iw < lv) {
+                    lowlink.set(v, iw);
+                }
+            }
+        }
+        if (lowlink.get(v) === indices.get(v)) {
+            const scc = [];
+            for (;;) {
+                const w = stack.pop();
+                /* c8 ignore next */
+                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;
+};
+const hasSelfEdge = (node) => {
+    for (const edge of node.edgesOut.values()) {
+        if (edge.to === node)
+            return true;
+    }
+    return false;
+};
+const serializeWithColors = (node, sccSet, color, resolvedIds) => serializeEdges(node, to => sccSet.has(to) ?
+    /* c8 ignore next */
+    (color.get(to) ?? MISSING)
+    : (resolvedIds.get(to) ?? to.id));
+const mapGet = (m, key) => {
+    const v = m.get(key);
+    /* c8 ignore next */
+    return v ?? '';
+};
+/**
+ * Weisfeiler–Lehman color refinement to a partition fixpoint, then a
+ * canonical member order. Colors are dense ranks so the loop can
+ * stabilize; positional `#idx` refs are assigned to color classes.
+ */
+const 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))]));
+    // classic WL: each signature includes the node's own current color so
+    // refinement is monotone (the partition only ever gets finer), and the
+    // loop stops when the number of classes stops growing rather than when
+    // rank labels are literally identical, so it terminates in at most
+    // `scc.length` rounds even when labels permute on a stable partition
+    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 };
+};
+const colorClassKey = (node, colors) => `${peerlessDepID(node)}${NUL}${mapGet(colors, node)}`;
+const mergeNode = (graph, winner, loser) => {
+    winner.dev &&= loser.dev;
+    winner.optional &&= loser.optional;
+    // the loser may be the copy carrying lockfile/registry metadata or the
+    // manifest; preserve anything the winner is missing before deletion
+    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);
+    }
+    // the resolution caches are not read again before applyAssignments()
+    // clears both of them, so there is nothing to invalidate per loser
+};
+const applyAssignments = (graph, keep, losers) => {
+    const newKeys = 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 = 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;
+};
+/**
+ * Replace provisional / legacy `peer.<N>` DepID suffixes with a content
+ * hash of each node's resolved out-edge set. Called after `graph.gc()`.
+ */
+export const 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 = new Map();
+    for (const node of scoped) {
+        const next = [];
+        const seen = 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 = new Map();
+    const keep = [];
+    const byNewId = new Map();
+    const losers = 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);
+            /* c8 ignore start */
+            if (occupant && occupant.ser !== ser) {
+                suffix = `${suffix}.x`;
+                newId = withPeerSuffix(node, suffix);
+                occupant = undefined;
+            }
+            /* c8 ignore stop */
+        }
+        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 intraSccIndex = hasSelfEdge(node) ? new Map([[node, 0]]) : undefined;
+            const ser = unitEntry(node, { resolvedIds, intraSccIndex });
+            takeSuffix(node, ser, digest(ser, 16), 0, 1);
+            continue;
+        }
+        const { order, colors } = refineSccOrder(scc, resolvedIds);
+        const seenClass = 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 = new Map();
+        for (const [i, n] of reps.entries()) {
+            classIdx.set(colorClassKey(n, colors), i);
+        }
+        const intraSccIndex = 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 = new Map();
+        const rolesPerBase = 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);
+            /* c8 ignore next */
+            const idx = roleIdx.get(key) ?? 0;
+            /* c8 ignore next */
+            const count = rolesPerBase.get(peerlessDepID(n)) ?? 1;
+            takeSuffix(n, unit, hex, idx, count);
+        }
+    }
+    return applyAssignments(graph, keep, losers);
+};

package/dist/ideal/get-importer-specs.d.ts

@@ -1,11 +1,14 @@
-import type { AddImportersDependenciesMap, RemoveImportersDependenciesMap } from '../dependencies.ts';
+import type { AddImportersDependenciesMap, Dependency, RemoveImportersDependenciesMap } from '../dependencies.ts';
 import type { BuildIdealAddOptions, BuildIdealFromGraphOptions, BuildIdealRemoveOptions, TransientAddMap, TransientRemoveMap } from './types.ts';
+import type { Edge } from '../edge.ts';
 import type { SpecOptions } from '@vltpkg/spec';
 import type { PackageJson } from '@vltpkg/package-json';
 import type { PathScurry } from 'path-scurry';
+import type { GraphModifier } from '../modifiers.ts';
 export type GetImporterSpecsOptions = BuildIdealAddOptions & BuildIdealFromGraphOptions & BuildIdealRemoveOptions & SpecOptions & {
     scurry: PathScurry;
     packageJson: PackageJson;
+    modifiers?: GraphModifier;
 };
 /**
  * Given a {@link Graph} and a list of {@link Dependency}, merges the
@@ -15,6 +18,7 @@ export type GetImporterSpecsOptions = BuildIdealAddOptions & BuildIdealFromGraph
 export declare const getImporterSpecs: (options: GetImporterSpecsOptions) => {
     add: AddImportersDependenciesMap;
     remove: RemoveImportersDependenciesMap;
+    staleSpecs: Map<Edge, Dependency>;
     transientAdd: TransientAddMap;
     transientRemove: TransientRemoveMap;
 };

package/dist/ideal/get-importer-specs.js

@@ -40,33 +40,49 @@ export const getImporterSpecs = (options) => {
                 removeResult.modifiedDependencies = true;
             }
         }
-        // if a dependency is listed in the manifest but not in the graph,
-        // add that dependency to the list of dependencies to be added
+        // which declaration each name is placed with, same rule as
+        // getRawDependencies: the last type listing it wins, except that a
+        // peer entry for a name already listed elsewhere only constrains
+        // the dependency, it is not its own dependency to place
+        const declared = 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);
-                // skip if the edge exists and already uses the same spec
-                if (edge?.to && depSpec === edge.spec.bareSpec)
+                if (depType === 'peerDependencies' && declared.has(depName)) {
+                    continue;
+                }
+                declared.set(depName, [depType, depSpec]);
+            }
+        }
+        // if a dependency is listed in the manifest but not in the graph,
+        // add that dependency to the list of dependencies to be added
+        for (const [depName, [depType, depSpec]] of declared) {
+            const edge = importer.edgesOut.get(depName);
+            // skip if the edge exists and already uses the same spec and
+            // type. dangling (MISSING) targets still need to be queued so
+            // the ideal rebuild runs resetEdges() and places in traversal
+            // order. checked before parsing: the text parsed fine when the
+            // edge was loaded, and the workspace check below only fires on
+            // !edge?.to
+            const type = shorten(depType, depName, importer.manifest);
+            if (edge?.to &&
+                edge.spec.bareSpec === depSpec &&
+                edge.type === type) {
+                continue;
+            }
+            const spec = Spec.parse(depName, depSpec, options);
+            // if a workspace dep references a workspace that no longer exists
+            // (folder was removed), mark it for removal instead of trying to
+            // resolve it — the workspace can't be satisfied
+            if (spec.type === 'workspace' && !edge?.to) {
+                const wsExists = [...graph.importers].some(n => n.name === depName);
+                if (!wsExists) {
+                    removeDeps.add(depName);
+                    removeResult.modifiedDependencies = true;
                     continue;
-                const spec = Spec.parse(depName, depSpec, options);
-                // if a workspace dep references a workspace that no longer exists
-                // (folder was removed), mark it for removal instead of trying to
-                // resolve it — the workspace can't be satisfied
-                if (spec.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,
-                    type: shorten(depType, depName, importer.manifest),
-                });
-                addDeps.set(depName, dependency);
             }
+            addDeps.set(depName, asDependency({ spec, type }));
         }
         addResult.set(importer.id, addDeps);
         removeResult.set(importer.id, removeDeps);
@@ -107,8 +123,9 @@ export const getImporterSpecs = (options) => {
                 const deps = Object.entries(manifest[depType] ?? {});
                 for (const [depName, depSpec] of deps) {
                     const edge = node.edgesOut.get(depName);
-                    // skip if the edge exists and already uses the same spec
-                    if (edge?.to && depSpec === edge.spec.bareSpec)
+                    // skip if the edge exists and already uses the same spec.
+                    // dangling targets still need to be queued for the ideal rebuild.
+                    if (edge?.to && edge.spec.bareSpec === depSpec)
                         continue;
                     // add the dependency to the addDeps map
                     const dependency = asDependency({
@@ -171,10 +188,19 @@ export const getImporterSpecs = (options) => {
         }
     }
     // removes already satisfied dependencies from the dependencies list
-    removeSatisfiedSpecs({
+    const staleSpecs = removeSatisfiedSpecs({
         add: addResult,
         graph,
+        modifiers: options.modifiers,
     });
+    // a name the caller asked for is left to appendNodes and reify's
+    // package.json update: healing it here would put the request text in
+    // the lockfile without ever touching package.json
+    for (const edge of staleSpecs.keys()) {
+        if (add.get(edge.from.id)?.has(edge.name)) {
+            staleSpecs.delete(edge);
+        }
+    }
     // set the modifiedDependencies flag if any
     // of the importers have modified dependencies
     for (const addDeps of addResult.values()) {
@@ -186,6 +212,7 @@ export const getImporterSpecs = (options) => {
     return {
         add: addResult,
         remove: removeResult,
+        staleSpecs,
         transientAdd,
         transientRemove,
     };

package/dist/ideal/move-peer-store-dirs.d.ts

@@ -0,0 +1,7 @@
+import type { PathScurry } from 'path-scurry';
+import type { RollbackRemove } from '@vltpkg/rollback-remove';
+import type { PeerStoreMove } from './canonicalize-peer-ids.ts';
+export declare const movePeerStoreDirs: (moves: PeerStoreMove[], { scurry, remover, }: {
+    scurry: PathScurry;
+    remover: RollbackRemove;
+}) => Promise<void>;

package/dist/ideal/move-peer-store-dirs.js

@@ -0,0 +1,59 @@
+import { existsSync } from 'node:fs';
+import { rename } from 'node:fs/promises';
+export const movePeerStoreDirs = async (moves, { scurry, remover, }) => {
+    if (!moves.length)
+        return;
+    const store = scurry.resolve('node_modules/.vlt');
+    const key = String(Math.random()).substring(2);
+    // phase 1: vacate every source before any destination is written.
+    // a canonical id can equal another node's previous id, so a
+    // destination may still hold a directory that a sibling move is about
+    // to relocate; parking sources on unique hidden paths first keeps the
+    // moves from racing each other
+    const staged = await Promise.all(moves.map(async ({ node, from, to }) => {
+        const src = scurry.resolve(store, from);
+        if (!to) {
+            // nothing links to a merged-away copy any more, so one that
+            // cannot be discarded is a stale dir, not a broken install
+            try {
+                await remover.rm(src);
+            }
+            catch { }
+            return;
+        }
+        const tmp = scurry.resolve(store, `.VLT.MOVE.${key}.${to}`);
+        try {
+            await rename(src, tmp);
+        }
+        catch {
+            node.extracted = false;
+            return;
+        }
+        return { node, tmp, dest: scurry.resolve(store, to) };
+    }));
+    // phase 2: settle each parked directory on its canonical id
+    await Promise.all(staged.map(async (s) => {
+        if (!s)
+            return;
+        const { node, tmp, dest } = s;
+        try {
+            // frees the path and registers it for rollback; also the EPERM
+            // mitigation Windows needs before renaming a directory
+            await remover.rm(dest);
+            await rename(tmp, dest);
+        }
+        catch {
+            node.extracted = false;
+            // the node is re-extracted on its canonical id, so the parked
+            // copy would only linger as a `.VLT.MOVE` orphan in the store
+            try {
+                await remover.rm(tmp);
+            }
+            catch { }
+            return;
+        }
+        if (!existsSync(node.resolvedLocation(scurry))) {
+            node.extracted = false;
+        }
+    }));
+};

package/dist/ideal/peers.d.ts

@@ -13,10 +13,16 @@ import type { Node } from '../node.ts';
  */
 type PeerEdgeCompatResult = {
     compatible: boolean;
-    /** When incompatible, entry to add to forked context (target always present) */
-    forkEntry?: PeerContextEntryInput & {
-        target: Node;
-    };
+    /**
+     * When incompatible, entry to add to forked context. The target is
+     * absent only when the parent declares the peer but has not placed it
+     * yet: the fork still has to be minted so the re-placed copy gets a
+     * distinct id, and the parent's own edge resolves the peer at the end
+     * of the level.
+     */
+    forkEntry?: PeerContextEntryInput;
+    /** the existing version is fine, only an optional peer link differs */
+    keepVersion?: boolean;
 };
 /**
  * Check if an existing node's peer edges would still resolve to the same
@@ -36,7 +42,7 @@ type PeerEdgeCompatResult = {
  *    on the same package, and there's a graph node that would satisfy it but
  *    differs from what the existing node expects.
  */
-export declare const checkPeerEdgesCompatible: (existingNode: Node, fromNode: Node, peerContext: PeerContext, graph: Graph) => PeerEdgeCompatResult;
+export declare const checkPeerEdgesCompatible: (existingNode: Node, fromNode: Node, peerContext: PeerContext, graph: Graph, pending?: Map<string, Dependency>) => PeerEdgeCompatResult;
 /**
  * Retrieve a unique hash value for a given peer context set.
  */
@@ -80,6 +86,11 @@ export declare const checkEntriesToPeerContext: (peerContext: PeerContext, entri
  * peer context set. Extra info such as a target or dependent nodes is
  * optional.
  *
+ * When an entry gains a target that satisfies every spec collected so far,
+ * dependents of that entry are re-pointed at it only if their current target
+ * no longer satisfies one of those specs, so two equally valid resolutions
+ * never swap back and forth across rebuilds.
+ *
  * Returns true if forking is needed, false otherwise.
  */
 export declare const addEntriesToPeerContext: (peerContext: PeerContext, entries: PeerContextEntryInput[], fromNode: Node, monorepo?: Monorepo) => boolean;