@4da/mcp-server 6.2.2 → 6.2.4

package/CHANGELOG.md

@@ -1,5 +1,71 @@
 # Changelog
 
+## 6.2.4 — 2026-10-12
+
+### Fix paths held to the 4DA rule vectors
+
+The fix-path rules (version order, OSV range evaluation, the fix target, the
+refresh-or-parent verdict, the refresh command, `range_check`) now run in CI
+against the shared rule vectors of the 4DA desktop app, the same 333 vectors
+its Rust engine runs (see `conformance/README.md`). All pass. The first run
+found these defects:
+
+- **pnpm workspaces: the refresh command missed members.** At a pnpm workspace
+  root, `pnpm update <pkg>` touches only the root project, so a member's
+  vulnerable transitive copy stayed (measured with pnpm 10.34.6). The command
+  is now `pnpm update -r <pkg> --depth Infinity` there, and
+  `pnpm update <pkg> --depth Infinity` elsewhere (vectors fc-005..fc-008).
+- **A blocking parent was not named when another parent's requirement could
+  not be read.** `upgrade_planner` gave up on the whole copy and kept a
+  generic "waiting on upstream". A requirement that excludes the target now
+  decides on its own, and the reason names it (rv-048).
+- **Unread requirements fall back to semver, and say so.** When not every
+  parent's requirement can be read (the registry did not answer) and none read
+  excludes the target, the verdict comes from semver compatibility: a target
+  in the installed version's caret range is a `lockfile_refresh` with
+  `refreshInferred: true` and a reason that says it was inferred; any other
+  target stays `waiting_on_upstream` (AD-055 ¶1; rv-002..rv-032 even ids,
+  rv-049, rv-050).
+- **npm aliases were unreadable requirements.** `"npm:string-width@^4.2.0"`,
+  how package-lock records cliui's `string-width-cjs`, is now read as `^4.2.0`
+  on string-width (rv-047).
+- **PEP 440 local labels did not order.** `1.0`, `1.0+abc.5`, `1.0+abc.7` and
+  `1.0+5` compared equal; they now order as PEP 440 says (vo-013..vo-015), so a
+  `last_affected` bound equal to a local-labelled install is read correctly.
+- Yarn 1 and bun have no command that moves one transitive copy in place, so
+  none is named; the manual steps (delete the lockfile entries, reinstall) are
+  unchanged.
+
+## 6.2.3 — 2026-10-11
+
+### Yarn 1 refresh instruction covers alias entries
+
+The yarn 1 refresh step said "delete the `<name>@` entries from yarn.lock". A
+yarn 1 block is keyed by every spec that resolved to it, and an alias block's
+first key names the alias (`"string-width-cjs@npm:string-width@^4.2.0"`), so
+following the step left those blocks and kept the vulnerable version. It now
+names both forms: keys `"<name>@…"` and alias keys `"…@npm:<name>@…"`.
+
+### Fix-path parents name the real package
+
+The parent reader behind the fix-path rule ("a lockfile refresh is enough"
+vs "the parent must move") parsed lockfiles with its own code and still had
+the two naming defects 6.2.2 fixed in the package readers. It now names
+packages with the readers' helpers.
+
+- **yarn (v1 and berry): npm aliases.** A parent installed under an alias was
+  reported by the alias: on hono's benchmarks/routers lockfile, string-width
+  4.2.3 and wrap-ansi 7.0.0 were named `string-width-cjs` and `wrap-ansi-cjs`.
+  An aliased dependency edge (`string-width-cjs: "npm:string-width@^4.2.0"`)
+  was never matched, so @isaacs/cliui was missing from string-width 4.2.3's
+  parents, and its range is now the real package's `^4.2.0`.
+- **pnpm 5: entries keyed by a tarball URL.** Such an entry was dropped as a
+  parent and as a dependency: trpc's tarball-keyed @prisma/client 4.7.1 was
+  missing from prisma 4.7.1's parents, and the four workspace projects that
+  depend on it were missing from @prisma/client's. A dependency value that
+  points at another entry (that tarball key, or a pnpm alias's
+  `/real/1.2.3`) is now an edge to the package it installs.
+
 ## 6.2.2 — 2026-10-11
 
 ### Lockfile readers agree with the 4DA conformance corpus

package/dist/live/fix-paths.d.ts

@@ -74,10 +74,17 @@ export declare function verifyFixTargets(sources: FixPathSources | null, items:
 /** One clause for a target that is not the highest per-advisory fix, or null when it is. */
 export declare function targetNote(clean: CleanTarget): string | null;
 export interface RefreshVerdict {
-    /** True when every parent's requirement already admits a clean version. */
+    /** True when a lockfile refresh reaches a clean version (read, or inferred: see `inferred`). */
     refreshFixes: boolean;
+    /**
+     * True when no parent's requirement could be read (or not every one) and none
+     * excludes the target, so the verdict comes from semver compatibility
+     * (4DA AD-055 ¶1): a refresh when the target is caret-compatible with the
+     * installed version, the parent otherwise.
+     */
+    inferred: boolean;
     format: LockfileFormat;
-    /** The command, run in the lockfile's directory. */
+    /** The command, run in the lockfile's directory; for yarn 1 and bun, the manual steps (no command moves one copy in place). */
     command: string;
     /** Parent requirements that do NOT admit a clean version (why it is waiting on upstream). */
     blocking: Array<{
@@ -88,13 +95,30 @@ export interface RefreshVerdict {
     /** The version a refresh resolves to, when the registry's version list was read. */
     resolvesTo: string | null;
 }
-/** The refresh command for one lockfile format. */
-export declare function refreshCommand(format: LockfileFormat, name: string, installed: string, target: string): string;
+/**
+ * The command that refreshes one transitive copy in place, for the tools it
+ * can be named for (4DA AD-055 ¶4); null for yarn 1 and bun, which have none
+ * (see `manualRefreshSteps`).
+ *
+ * pnpm: at a workspace root (`pnpm-workspace.yaml`), `pnpm update <pkg>`
+ * touches only the root project's tree, so a member's transitive copy stayed
+ * where it was; `-r` reaches every member (measured with pnpm 10.34.6: a
+ * member's mkdirp -> minimist 1.2.5 moved to 1.2.8 only with `-r`). `--depth
+ * Infinity` is the form the fix-path oracle applied (2026-10-10, U04/U10);
+ * pnpm 8.15 to 10.34 also moved a root project's transitive copy without it.
+ */
+export declare function refreshCommand(format: LockfileFormat, name: string, installed: string, target: string, workspaceRoot?: boolean): string | null;
+/** For a lockfile with no in-place refresh command (yarn 1, bun): the steps that move the copy. */
+export declare function manualRefreshSteps(format: "yarn" | "bun", name: string): string;
+/** The refresh command for the project whose lockfile is `lockfile`; null when no command is named for it. */
+export declare function refreshCommandFor(lockfile: string, name: string, installed: string, target: string): string | null;
 /**
  * Whether refreshing `lockfile` moves `name@installed` to a clean version
- * without any parent changing its declared requirement. Null when the
- * lockfile or a requirement cannot be read (the caller keeps "waiting on
- * upstream", the conservative answer).
+ * without any parent changing its declared requirement: `refreshRule` over
+ * every requirement the parents declare (read from the lockfile, else the
+ * parent's registry metadata). Null when the lockfile cannot be read or no
+ * verdict is possible (the caller keeps "waiting on upstream", the
+ * conservative answer).
  */
 export declare function refreshVerdict(sources: FixPathSources, ecosystem: OsvEcosystem, lockfile: string, name: string, installed: string, target: string, advisories: AdvisoryRanges[] | null, published: string[] | null): Promise<RefreshVerdict | null>;
 /**

package/dist/live/fix-paths.js

@@ -27,9 +27,11 @@ import { fetchWithTimeout } from "./http-utils.js";
 import { escapeModulePath } from "./go-registry.js";
 import { advisoryRanges, advisoryAffects, isPrereleaseVersion, smallestCleanVersion } from "./osv-ranges.js";
 import * as fs from "node:fs";
-import { readLockfileParents } from "./lockfile-parents.js";
+import * as path from "node:path";
+import { lockfileFormat, readLockfileParents } from "./lockfile-parents.js";
 import { parseCargoLockPackages } from "./lockfile-parsers.js";
-import { cargoReqAdmits, npmRangeAdmits } from "./range-satisfies.js";
+import { cargoReqAdmits } from "./range-satisfies.js";
+import { refreshRule, requirementAdmits } from "./refresh-rule.js";
 import { compareVersions } from "./version-compare.js";
 import { CRATES_USER_AGENT } from "./crates-versions.js";
 const TIMEOUT_MS = 15_000;
@@ -302,83 +304,121 @@ export function targetNote(clean) {
     }
     return parts.length > 0 ? parts.join("; ") : null;
 }
-/** The refresh command for one lockfile format. */
-export function refreshCommand(format, name, installed, target) {
+/**
+ * The command that refreshes one transitive copy in place, for the tools it
+ * can be named for (4DA AD-055 ¶4); null for yarn 1 and bun, which have none
+ * (see `manualRefreshSteps`).
+ *
+ * pnpm: at a workspace root (`pnpm-workspace.yaml`), `pnpm update <pkg>`
+ * touches only the root project's tree, so a member's transitive copy stayed
+ * where it was; `-r` reaches every member (measured with pnpm 10.34.6: a
+ * member's mkdirp -> minimist 1.2.5 moved to 1.2.8 only with `-r`). `--depth
+ * Infinity` is the form the fix-path oracle applied (2026-10-10, U04/U10);
+ * pnpm 8.15 to 10.34 also moved a root project's transitive copy without it.
+ */
+export function refreshCommand(format, name, installed, target, workspaceRoot = false) {
     switch (format) {
         case "package-lock":
             return `npm update ${name}`;
         case "pnpm":
-            return `pnpm update ${name}`;
+            return `pnpm update ${workspaceRoot ? "-r " : ""}${name} --depth Infinity`;
         case "yarn-berry":
             return `yarn up -R ${name}`;
         case "yarn":
-            return `delete the ${name}@ entries from yarn.lock, then run yarn install`;
         case "bun":
-            return `delete the ${name} entries from bun.lock, then run bun install`;
+            return null;
         case "cargo":
             return `cargo update -p ${name}@${installed} --precise ${target}`;
     }
 }
+/** For a lockfile with no in-place refresh command (yarn 1, bun): the steps that move the copy. */
+export function manualRefreshSteps(format, name) {
+    // Yarn 1 keys a block by every spec that resolved to it, and an alias block's
+    // first key names the alias ("string-width-cjs@npm:string-width@^4.2.0"), so
+    // name both forms. Deleting the entries and reinstalling is what moved the
+    // copy in the fix-path oracle (case U11).
+    return format === "yarn"
+        ? `delete every yarn.lock entry that resolves to ${name} (keys "${name}@…" and alias keys "…@npm:${name}@…"), then run yarn install`
+        : `delete the ${name} entries from bun.lock, then run bun install`;
+}
+/** Whether a pnpm lockfile sits at a workspace root (`pnpm-workspace.yaml` beside it). */
+function isPnpmWorkspaceRoot(lockfile) {
+    return fs.existsSync(path.join(path.dirname(lockfile), "pnpm-workspace.yaml"));
+}
+/** The refresh command for the project whose lockfile is `lockfile`; null when no command is named for it. */
+export function refreshCommandFor(lockfile, name, installed, target) {
+    let content;
+    try {
+        content = fs.readFileSync(lockfile, "utf-8");
+    }
+    catch {
+        return null;
+    }
+    const format = lockfileFormat(lockfile, content);
+    return format ? refreshCommand(format, name, installed, target, format === "pnpm" && isPnpmWorkspaceRoot(lockfile)) : null;
+}
 /**
  * Whether refreshing `lockfile` moves `name@installed` to a clean version
- * without any parent changing its declared requirement. Null when the
- * lockfile or a requirement cannot be read (the caller keeps "waiting on
- * upstream", the conservative answer).
+ * without any parent changing its declared requirement: `refreshRule` over
+ * every requirement the parents declare (read from the lockfile, else the
+ * parent's registry metadata). Null when the lockfile cannot be read or no
+ * verdict is possible (the caller keeps "waiting on upstream", the
+ * conservative answer).
  */
 export async function refreshVerdict(sources, ecosystem, lockfile, name, installed, target, advisories, published) {
     const parents = readLockfileParents(lockfile, name, installed);
     if (!parents || parents.edges.length === 0)
         return null;
     const isCargo = parents.format === "cargo";
-    const admits = (range, version) => (isCargo ? cargoReqAdmits(range, version) : npmRangeAdmits(range, version));
+    const dialect = isCargo ? "cargo" : "npm";
     const clean = (v) => !advisories || !advisories.some((a) => advisoryAffects(a, v, ecosystem));
     const releases = (published ?? []).filter((v) => !isPrereleaseVersion(v, ecosystem));
-    const blocking = [];
-    let resolvesTo = null;
     const edgeReqs = await Promise.all(parents.edges.map((edge) => requirementsOf(sources, ecosystem, edge, name)));
+    const reqs = [];
     for (const [i, edge] of parents.edges.entries()) {
         const all = edgeReqs[i];
-        if (all === null || all.length === 0)
-            return null;
+        if (all === null || all.length === 0) {
+            reqs.push({ parent: edge.parent, text: null, dialect, edge }); // not read: the rule cannot count it as admitting
+            continue;
+        }
         // A parent can declare the same crate twice under different names (feature-gated
         // `mio-0_6` / `mio-0_7` aliases): only the requirements this copy satisfies apply.
-        const matching = all.filter((req) => admits(req, installed) === true);
-        const reqs = matching.length > 0 ? [...new Set(matching)] : [...new Set(all)];
-        for (const req of reqs) {
-            if (isCargo) {
-                // `cargo update --precise` moves to exactly the clean target, if every requirement admits it.
-                const ok = admits(req, target);
-                if (ok === null)
-                    return null;
-                if (!ok)
-                    blocking.push({ parent: edge.parent, parentVersion: edge.parentVersion, requirement: req });
-                else
-                    resolvesTo = target;
-                continue;
-            }
-            // npm, pnpm, yarn and bun resolve each requirement to its newest match.
-            if (releases.length > 0) {
+        const asReq = (text) => ({ parent: edge.parent, text, dialect });
+        const matching = all.filter((text) => requirementAdmits(asReq(text), installed) === true);
+        for (const text of new Set(matching.length > 0 ? matching : all))
+            reqs.push({ ...asReq(text), edge });
+    }
+    const rule = refreshRule(installed, target, reqs);
+    if (rule.verdict === "unknown")
+        return null;
+    const blocking = [];
+    const block = (r) => blocking.push({ parent: r.edge.parent, parentVersion: r.edge.parentVersion, requirement: r.text ?? "" });
+    for (const r of reqs)
+        if (requirementAdmits(r, target) === false)
+            block(r);
+    let resolvesTo = null;
+    if (rule.verdict === "refresh" && !rule.inferred) {
+        if (isCargo) {
+            // `cargo update --precise` moves to exactly the clean target, which every requirement admits.
+            resolvesTo = target;
+        }
+        else if (releases.length > 0) {
+            // npm, pnpm, yarn and bun resolve each requirement to its newest match, which must be clean too.
+            for (const r of reqs) {
                 const newest = releases
-                    .filter((v) => admits(req, v) === true)
+                    .filter((v) => requirementAdmits(r, v) === true)
                     .sort((a, b) => compareVersions(b, a, ecosystem))[0];
-                if (!newest || compareVersions(newest, target, ecosystem) < 0 || !clean(newest)) {
-                    blocking.push({ parent: edge.parent, parentVersion: edge.parentVersion, requirement: req });
-                }
-                else if (!resolvesTo || compareVersions(newest, resolvesTo, ecosystem) < 0) {
+                if (!newest || compareVersions(newest, target, ecosystem) < 0 || !clean(newest))
+                    block(r);
+                else if (!resolvesTo || compareVersions(newest, resolvesTo, ecosystem) < 0)
                     resolvesTo = newest;
-                }
-            }
-            else {
-                const ok = admits(req, target);
-                if (ok === null)
-                    return null;
-                if (!ok)
-                    blocking.push({ parent: edge.parent, parentVersion: edge.parentVersion, requirement: req });
             }
         }
     }
-    let command = refreshCommand(parents.format, name, installed, target);
-    if (isCargo && blocking.length === 0) {
+    const refreshFixes = rule.verdict === "refresh" && blocking.length === 0;
+    const named = refreshCommand(parents.format, name, installed, target, parents.format === "pnpm" && isPnpmWorkspaceRoot(lockfile));
+    let command = named ?? manualRefreshSteps(parents.format === "bun" ? "bun" : "yarn", name);
+    if (isCargo && refreshFixes) {
         let content;
         try {
             content = fs.readFileSync(lockfile, "utf-8");
@@ -393,11 +433,12 @@ export async function refreshVerdict(sources, ecosystem, lockfile, name, install
             command = `cargo update ${prereqs.map((p) => `-p ${p}`).join(" ")} && ${command}`;
     }
     return {
-        refreshFixes: blocking.length === 0,
+        refreshFixes,
+        inferred: rule.inferred,
         format: parents.format,
         command,
         blocking,
-        resolvesTo: blocking.length === 0 ? resolvesTo : null,
+        resolvesTo: refreshFixes ? resolvesTo : null,
     };
 }
 async function requirementsOf(sources, ecosystem, edge, name) {

package/dist/live/js-lockfile-readers.d.ts

@@ -17,12 +17,30 @@
  * file, link) is dropped instead of being queried as a package name.
  */
 import type { InstanceSet } from "./lockfile-types.js";
+/** An exact version with pnpm's peer suffixes removed: v6/v9 `1.2.3(react@18)`, v5 `1.2.3_react@18`. */
+export declare function exactVersion(raw: string): string | null;
 /**
  * Splits one `packages:` or `snapshots:` key into [name, version]:
  * v9 `'@scope/pkg@1.2.3(peer@4.5.6)'`, v6 `/pkg@1.2.3`, v5 `/@scope/pkg/1.2.3_peer@4.5.6`.
  * Returns null for a key that does not pin a registry version.
  */
 export declare function parsePnpmKey(rawKey: string): [string, string] | null;
+/** A `packages:`/`snapshots:` key, or a dependency value that points at one, in one spelling: unquoted, no leading `/`. */
+export declare function pnpmKeyRef(raw: string): string;
+export interface PnpmEntryReader {
+    /** One line inside a `packages:` or `snapshots:` section (indent > 0). */
+    line(indent: number, text: string): void;
+    /** Ends the entry being read: call at every section change and at the end of the file. */
+    finish(): void;
+}
+/**
+ * Reads `packages:`/`snapshots:` entries line by line and reports the
+ * registry (name, version) each installs (see pnpmEntryIdentity); entries
+ * that install no registry release are not reported.
+ */
+export declare function pnpmEntryReader(onEntry: (key: string, id: [string, string], dev: boolean | undefined) => void): PnpmEntryReader;
+/** Every `packages:`/`snapshots:` entry's registry (name, version), by pnpmKeyRef of its key. */
+export declare function pnpmEntryIdentities(content: string): Map<string, [string, string]>;
 /**
  * Reads a pnpm lockfile (v5.x, v6 or v9) into `versions`; the first version seen wins.
  *
@@ -37,6 +55,15 @@ export declare function parsePnpmKey(rawKey: string): [string, string] | null;
  * package key. pnpm 9 dropped that field, so its copies have unknown scope.
  */
 export declare function readPnpmLock(content: string, versions: Map<string, string>, instances?: InstanceSet): void;
+/**
+ * The registry package a yarn block installs. An npm alias
+ * (`"string-width-cjs": "npm:string-width@^4.2.0"`) keys the block by the
+ * alias, which is not a package: OSV knows `string-width`, so the alias was
+ * queried for nothing and the real package went unscanned (hono's
+ * benchmarks/routers yarn.lock, 4DA conformance corpus, 2026-10-12). berry
+ * names the real package in `resolution:`; v1 only in the alias spec.
+ */
+export declare function yarnPackageName(block: string, firstLine: string, headerName: string): string;
 /**
  * Reads a yarn lockfile (v1 or berry) into `versions`.
  * v1: `"@scope/pkg@^1.0.0", "@scope/pkg@^1.1.0":` then `  version "1.2.3"`.

package/dist/live/js-lockfile-readers.js

@@ -24,7 +24,7 @@ function unquote(s) {
     return s.length >= 2 && (s[0] === "'" || s[0] === '"') && s[s.length - 1] === s[0] ? s.slice(1, -1) : s;
 }
 /** An exact version with pnpm's peer suffixes removed: v6/v9 `1.2.3(react@18)`, v5 `1.2.3_react@18`. */
-function exactVersion(raw) {
+export function exactVersion(raw) {
     const version = unquote(raw.trim()).split("(")[0].split("_")[0].trim();
     return /^\d/.test(version) ? version : null;
 }
@@ -116,6 +116,60 @@ function pnpmEntryIdentity(entry) {
     }
     return parsed;
 }
+/** A `packages:`/`snapshots:` key, or a dependency value that points at one, in one spelling: unquoted, no leading `/`. */
+export function pnpmKeyRef(raw) {
+    return unquote(raw.trim()).replace(/^\//, "");
+}
+/**
+ * Reads `packages:`/`snapshots:` entries line by line and reports the
+ * registry (name, version) each installs (see pnpmEntryIdentity); entries
+ * that install no registry release are not reported.
+ */
+export function pnpmEntryReader(onEntry) {
+    let entry = null;
+    const finish = () => {
+        const id = entry ? pnpmEntryIdentity(entry) : null;
+        if (entry && id)
+            onEntry(entry.key, id, entry.dev);
+        entry = null;
+    };
+    return {
+        line(indent, text) {
+            if (indent === 2 && text.endsWith(":")) {
+                finish();
+                entry = { key: text.slice(0, -1), inResolution: false, local: false };
+            }
+            else if (entry && indent === 4) {
+                pnpmEntryField(entry, text);
+            }
+            else if (entry?.inResolution && indent > 4) {
+                pnpmResolutionText(entry, text);
+            }
+        },
+        finish,
+    };
+}
+/** Every `packages:`/`snapshots:` entry's registry (name, version), by pnpmKeyRef of its key. */
+export function pnpmEntryIdentities(content) {
+    const ids = new Map();
+    const reader = pnpmEntryReader((key, id) => ids.set(pnpmKeyRef(key), id));
+    let inEntries = false;
+    for (const line of content.split(/\r?\n/)) {
+        const text = line.trim();
+        if (text === "" || text.startsWith("#"))
+            continue;
+        const indent = line.length - line.trimStart().length;
+        if (indent === 0) {
+            reader.finish();
+            inEntries = text === "packages:" || text === "snapshots:";
+        }
+        else if (inEntries) {
+            reader.line(indent, text);
+        }
+    }
+    reader.finish();
+    return ids;
+}
 /**
  * Reads a pnpm lockfile (v5.x, v6 or v9) into `versions`; the first version seen wins.
  *
@@ -139,39 +193,25 @@ export function readPnpmLock(content, versions, instances) {
     let section = "";
     let blockIndent = -1; // column of the dependency block being read, or -1
     let pending = null; // v6/v9: a name whose `version:` line follows
-    let entry = null; // the packages/snapshots entry whose fields are being read
-    const finish = () => {
-        const id = entry ? pnpmEntryIdentity(entry) : null;
-        if (id) {
-            transitive.push(id);
-            if (entry.dev !== undefined)
-                devByKey.set(`${id[0]}\0${id[1]}`, entry.dev);
-        }
-        entry = null;
-    };
+    const entries = pnpmEntryReader((_key, id, dev) => {
+        transitive.push(id);
+        if (dev !== undefined)
+            devByKey.set(`${id[0]}\0${id[1]}`, dev);
+    });
     for (const line of content.split(/\r?\n/)) {
         const text = line.trim();
         if (text === "" || text.startsWith("#"))
             continue;
         const indent = line.length - line.trimStart().length;
         if (indent === 0) {
-            finish();
+            entries.finish();
             section = text.endsWith(":") ? text.slice(0, -1) : "";
             blockIndent = DEPENDENCY_BLOCKS.has(text) ? 0 : -1;
             pending = null;
             continue;
         }
         if (section === "packages" || section === "snapshots") {
-            if (indent === 2 && text.endsWith(":")) {
-                finish();
-                entry = { key: text.slice(0, -1), inResolution: false, local: false };
-            }
-            else if (entry && indent === 4) {
-                pnpmEntryField(entry, text);
-            }
-            else if (entry?.inResolution && indent > 4) {
-                pnpmResolutionText(entry, text);
-            }
+            entries.line(indent, text);
             continue;
         }
         if (section === "importers" && indent <= 4) {
@@ -204,7 +244,7 @@ export function readPnpmLock(content, versions, instances) {
             pending = null;
         }
     }
-    finish();
+    entries.finish();
     for (const [name, version] of transitive)
         setFirst(name, version);
     if (!instances)
@@ -224,7 +264,7 @@ export function readPnpmLock(content, versions, instances) {
  * benchmarks/routers yarn.lock, 4DA conformance corpus, 2026-10-12). berry
  * names the real package in `resolution:`; v1 only in the alias spec.
  */
-function yarnPackageName(block, firstLine, headerName) {
+export function yarnPackageName(block, firstLine, headerName) {
     const resolution = /^\s+resolution:\s+"?((?:@[^\s/@"]+\/)?[^\s/@"]+)@npm:/m.exec(block);
     if (resolution)
         return resolution[1];

package/dist/live/lockfile-parents.d.ts

@@ -45,8 +45,20 @@ export declare function packageLockParents(lock: {
  * dependency blocks resolve `name` to `version`. pnpm records resolved
  * versions only, so `range` is null. Importers (the project's own manifests)
  * become local edges with their `specifier` when the lockfile records one.
+ *
+ * Entries and dependency values are named the way the package reader names
+ * them (pnpmEntryIdentities): a pnpm 5 entry keyed by its tarball URL is the
+ * package its `name:`/`version:` fields say, and a dependency value that is a
+ * key rather than a version (that tarball key, or an alias's
+ * `/real/1.2.3`, `/real@1.2.3`, `real@1.2.3`) is an edge to the package it points at.
  */
 export declare function pnpmParents(content: string, name: string, version: string): ParentEdge[];
+/**
+ * Blocks whose dependencies resolve `name` to `version`. An npm alias edge
+ * (`string-width-cjs: "npm:string-width@^4.2.0"`) is an edge to the real
+ * package, with the real package's range; it resolves through the block whose
+ * spec is `string-width-cjs@npm:string-width@^4.2.0`.
+ */
 export declare function yarnParents(content: string, name: string, version: string): ParentEdge[];
 export declare function bunParents(lock: {
     packages?: Record<string, unknown>;

package/dist/live/lockfile-parents.js

@@ -11,7 +11,7 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { stripTrailingCommas } from "./bun-lockfile.js";
-import { parsePnpmKey } from "./js-lockfile-readers.js";
+import { exactVersion, parsePnpmKey, pnpmEntryIdentities, pnpmKeyRef, yarnPackageName } from "./js-lockfile-readers.js";
 import { packageNameFromNodeModulesPath, parseCargoLockPackages } from "./lockfile-parsers.js";
 const DEP_FIELDS = ["dependencies", "optionalDependencies", "peerDependencies"];
 /** The lockfile format of a path, or null for a file this module does not read. */
@@ -123,18 +123,32 @@ export function packageLockParents(lock, name, version) {
 // ---------------------------------------------------------------------------
 // pnpm-lock.yaml (v5, v6, v9)
 // ---------------------------------------------------------------------------
-function exactVersion(raw) {
-    const unquoted = raw.trim().replace(/^['"]|['"]$/g, "");
-    const v = unquoted.split("(")[0].split("_")[0].trim();
-    return /^\d/.test(v) ? v : null;
-}
 /**
  * Parents from `packages:` (v5/v6) or `snapshots:` (v9) entries whose
  * dependency blocks resolve `name` to `version`. pnpm records resolved
  * versions only, so `range` is null. Importers (the project's own manifests)
  * become local edges with their `specifier` when the lockfile records one.
+ *
+ * Entries and dependency values are named the way the package reader names
+ * them (pnpmEntryIdentities): a pnpm 5 entry keyed by its tarball URL is the
+ * package its `name:`/`version:` fields say, and a dependency value that is a
+ * key rather than a version (that tarball key, or an alias's
+ * `/real/1.2.3`, `/real@1.2.3`, `real@1.2.3`) is an edge to the package it points at.
  */
 export function pnpmParents(content, name, version) {
+    const ids = pnpmEntryIdentities(content);
+    /** The (name, version) a dependency line installs: `dep: 1.2.3`, or a value that points at an entry. */
+    const installs = (dep, value) => {
+        const exact = exactVersion(value);
+        if (exact)
+            return [dep, exact];
+        const ref = pnpmKeyRef(value);
+        return ids.get(ref) ?? parsePnpmKey(ref);
+    };
+    const isTarget = (dep, value) => {
+        const id = installs(dep, value);
+        return id !== null && id[0] === name && id[1] === version;
+    };
     const edges = [];
     const seen = new Set();
     let section = "";
@@ -142,7 +156,7 @@ export function pnpmParents(content, name, version) {
     let importer = null;
     let inDeps = false;
     let depIndent = -1;
-    let pendingImporterDep = false;
+    let pendingDep = null;
     let importerSpecifier = null;
     const add = (edge) => {
         const key = `${edge.parent}\0${edge.parentVersion}`;
@@ -166,7 +180,7 @@ export function pnpmParents(content, name, version) {
         }
         if (section === "packages" || section === "snapshots") {
             if (indent === 2 && text.endsWith(":")) {
-                parent = parsePnpmKey(text.slice(0, -1));
+                parent = ids.get(pnpmKeyRef(text.slice(0, -1))) ?? null;
                 inDeps = false;
             }
             else if (indent === 4 && parent) {
@@ -174,7 +188,7 @@ export function pnpmParents(content, name, version) {
             }
             else if (indent === 6 && parent && inDeps) {
                 const m = /^(?:'([^']+)'|"([^"]+)"|([^\s:'"]+)):\s*(.+)$/.exec(text);
-                if (m && (m[1] ?? m[2] ?? m[3]) === name && exactVersion(m[4]) === version) {
+                if (m && isTarget(m[1] ?? m[2] ?? m[3], m[4])) {
                     add({ parent: parent[0], parentVersion: parent[1], range: null, local: false });
                 }
             }
@@ -197,21 +211,23 @@ export function pnpmParents(content, name, version) {
         // A dependency of the project itself: v5 `name: 1.2.3`, v6/v9 `name:` + `specifier:` + `version:`.
         if (indent === depIndent + 2) {
             const m = /^(?:'([^']+)'|"([^"]+)"|([^\s:'"]+)):(?:\s+(.*))?$/.exec(text);
-            pendingImporterDep = !!m && (m[1] ?? m[2] ?? m[3]) === name;
+            pendingDep = m ? m[1] ?? m[2] ?? m[3] : null;
             importerSpecifier = null;
-            if (pendingImporterDep && m?.[4] && exactVersion(m[4]) === version) {
-                add({ parent: importer, parentVersion: null, range: null, local: true });
-                pendingImporterDep = false;
+            if (pendingDep && m?.[4]) {
+                if (isTarget(pendingDep, m[4]))
+                    add({ parent: importer, parentVersion: null, range: null, local: true });
+                pendingDep = null;
             }
         }
-        else if (indent === depIndent + 4 && pendingImporterDep) {
+        else if (indent === depIndent + 4 && pendingDep) {
             const spec = /^specifier:\s*(.+)$/.exec(text);
             if (spec)
                 importerSpecifier = spec[1].replace(/^['"]|['"]$/g, "");
             const ver = /^version:\s*(.+)$/.exec(text);
-            if (ver && exactVersion(ver[1]) === version) {
-                add({ parent: importer, parentVersion: null, range: importerSpecifier, local: true });
-                pendingImporterDep = false;
+            if (ver) {
+                if (isTarget(pendingDep, ver[1]))
+                    add({ parent: importer, parentVersion: null, range: importerSpecifier, local: true });
+                pendingDep = null;
             }
         }
     }
@@ -226,9 +242,11 @@ function parseYarnBlocks(content) {
     for (const block of content.split(/\r?\n(?=\S)/)) {
         const lines = block.split(/\r?\n/);
         const header = lines[0];
-        const name = /^"?(@?[^@\s"]+)@/.exec(header)?.[1];
-        if (!name || name.startsWith("__"))
+        const headerName = /^"?(@?[^@\s"]+)@/.exec(header)?.[1];
+        if (!headerName || headerName.startsWith("__"))
             continue;
+        // An npm alias block (`string-width-cjs@npm:string-width@^4.2.0`) installs the real package.
+        const name = yarnPackageName(block, header, headerName);
         const version = /^\s+version:?\s+"?([^"\s]+)"?\s*$/m.exec(block)?.[1];
         if (!version)
             continue;
@@ -260,21 +278,27 @@ function parseYarnBlocks(content) {
     }
     return blocks;
 }
+/**
+ * Blocks whose dependencies resolve `name` to `version`. An npm alias edge
+ * (`string-width-cjs: "npm:string-width@^4.2.0"`) is an edge to the real
+ * package, with the real package's range; it resolves through the block whose
+ * spec is `string-width-cjs@npm:string-width@^4.2.0`.
+ */
 export function yarnParents(content, name, version) {
     const blocks = parseYarnBlocks(content);
     const resolved = new Map();
     for (const b of blocks)
         for (const spec of b.specs)
-            resolved.set(spec, b.version);
+            resolved.set(spec, b);
     const edges = [];
     for (const b of blocks) {
         for (const [dep, rawRange] of b.deps) {
-            if (dep !== name)
-                continue;
-            const range = rawRange.replace(/^npm:/, "");
-            if (resolved.get(`${name}@${range}`) !== version)
+            const spec = rawRange.replace(/^npm:/, "");
+            const target = resolved.get(`${dep}@${spec}`);
+            if (!target || target.name !== name || target.version !== version)
                 continue;
-            edges.push({ parent: b.name, parentVersion: b.version, range, local: false });
+            const alias = /^npm:((?:@[^\s/@]+\/)?[^\s/@]+)@(.+)$/.exec(rawRange);
+            edges.push({ parent: b.name, parentVersion: b.version, range: alias ? alias[2] : spec, local: false });
         }
     }
     return edges;

package/dist/live/range-satisfies.d.ts

@@ -13,8 +13,10 @@
  */
 /**
  * Whether an npm range admits `version`. Null when the range is not a
- * registry semver range (git, file, link, workspace, alias, tag) or the
- * version is unreadable.
+ * registry semver range (git, file, link, workspace, tag) or the version is
+ * unreadable. An npm alias ("npm:string-width@^4.2.0", the spec a lockfile
+ * records for "string-width-cjs") is read by its range: it is the parent's
+ * requirement on the aliased package.
  */
 export declare function npmRangeAdmits(range: string, version: string): boolean | null;
 /** Whether a Cargo version requirement ("0.8", "^1.2", ">=0.10, <0.11", "=1.0.5") admits `version`. Null when unreadable. */

package/dist/live/range-satisfies.js

@@ -130,16 +130,18 @@ function test(set, version) {
 }
 /**
  * Whether an npm range admits `version`. Null when the range is not a
- * registry semver range (git, file, link, workspace, alias, tag) or the
- * version is unreadable.
+ * registry semver range (git, file, link, workspace, tag) or the version is
+ * unreadable. An npm alias ("npm:string-width@^4.2.0", the spec a lockfile
+ * records for "string-width-cjs") is read by its range: it is the parent's
+ * requirement on the aliased package.
  */
 export function npmRangeAdmits(range, version) {
     const v = parseSemverPrecedence(version);
     if (!v)
         return null;
-    // yarn berry writes "npm:^1.2.0"; an alias ("npm:other@^1") names another package.
-    const text = range.trim().replace(/^npm:(?=[\^~<>=\dvxX*\s]|$)/, "");
-    // Protocols (git+https:, file:, link:, workspace:, npm:alias@), paths, GitHub shorthand.
+    // yarn berry writes "npm:^1.2.0"; an alias writes "npm:<name>@<range>" (scoped names too).
+    const text = range.trim().replace(/^npm:(?:(?:@[^@\s/]+\/)?[^@\s/]+@)?(?=[\^~<>=\dvxX*\s]|$)/, "");
+    // Protocols (git+https:, file:, link:, workspace:), paths, GitHub shorthand.
     if (/^[a-z][a-z+]*:/i.test(text) || text.includes("/"))
         return null;
     // A dist-tag ("latest", "next", "beta").

package/dist/live/refresh-rule.d.ts

@@ -0,0 +1,36 @@
+/**
+ * THE refresh-or-parent rule for a transitive copy (4DA AD-055 ¶1): given
+ * every requirement read for the parents that pull `installed` in, does a
+ * lockfile refresh reach `target`?
+ *
+ * - Any requirement that excludes the target sends the fix to that parent,
+ *   even when another parent's requirement cannot be read.
+ * - Every requirement admitting it makes a refresh enough.
+ * - Nothing (or not everything) readable falls back to semver compatibility,
+ *   the caret rule: same major at >= 1.0, same minor below it, any bump at
+ *   0.0.z leaves it. That answer is `inferred`, and every rendering says so.
+ *
+ * The 4DA desktop app's `osv::fix_path::refresh_verdict` is the same rule;
+ * the shared rule vectors (`refresh_verdict.jsonl`) hold both engines to it.
+ * Pure: no I/O.
+ */
+/** How a requirement is written: npm (a bare version is an exact pin) or Cargo (a bare version is a caret). */
+export type RequirementDialect = "npm" | "cargo";
+export interface ParentRequirement {
+    parent: string;
+    /** The requirement as declared; null when it could not be read at all. */
+    text: string | null;
+    dialect: RequirementDialect;
+}
+export interface RefreshRule {
+    verdict: "refresh" | "parent_must_move" | "unknown";
+    /** True when no requirement decided and the verdict comes from semver compatibility. */
+    inferred: boolean;
+    /** Parents whose requirement excludes the target, in input order. */
+    via: string[];
+}
+/** Whether a requirement admits a version; null when either cannot be read. */
+export declare function requirementAdmits(req: ParentRequirement, version: string): boolean | null;
+/** True when moving from `installed` to `target` leaves the caret range of `installed`; null when either is unreadable. */
+export declare function leavesCaret(installed: string, target: string): boolean | null;
+export declare function refreshRule(installed: string, target: string, requirements: ParentRequirement[]): RefreshRule;

package/dist/live/refresh-rule.js

@@ -0,0 +1,49 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * THE refresh-or-parent rule for a transitive copy (4DA AD-055 ¶1): given
+ * every requirement read for the parents that pull `installed` in, does a
+ * lockfile refresh reach `target`?
+ *
+ * - Any requirement that excludes the target sends the fix to that parent,
+ *   even when another parent's requirement cannot be read.
+ * - Every requirement admitting it makes a refresh enough.
+ * - Nothing (or not everything) readable falls back to semver compatibility,
+ *   the caret rule: same major at >= 1.0, same minor below it, any bump at
+ *   0.0.z leaves it. That answer is `inferred`, and every rendering says so.
+ *
+ * The 4DA desktop app's `osv::fix_path::refresh_verdict` is the same rule;
+ * the shared rule vectors (`refresh_verdict.jsonl`) hold both engines to it.
+ * Pure: no I/O.
+ */
+import { cargoReqAdmits, npmRangeAdmits } from "./range-satisfies.js";
+import { parseSemverPrecedence } from "./semver-precedence.js";
+/** Whether a requirement admits a version; null when either cannot be read. */
+export function requirementAdmits(req, version) {
+    if (req.text === null)
+        return null;
+    return req.dialect === "cargo" ? cargoReqAdmits(req.text, version) : npmRangeAdmits(req.text, version);
+}
+/** True when moving from `installed` to `target` leaves the caret range of `installed`; null when either is unreadable. */
+export function leavesCaret(installed, target) {
+    const a = parseSemverPrecedence(installed.replace(/^v(?=\d)/, ""));
+    const b = parseSemverPrecedence(target.replace(/^v(?=\d)/, ""));
+    if (!a || !b)
+        return null;
+    if (a.major !== b.major)
+        return true;
+    if (a.major === 0 && a.minor !== b.minor)
+        return true;
+    return a.major === 0 && a.minor === 0 && a.patch !== b.patch;
+}
+export function refreshRule(installed, target, requirements) {
+    const read = requirements.map((r) => requirementAdmits(r, target));
+    const via = requirements.filter((_, i) => read[i] === false).map((r) => r.parent);
+    if (via.length > 0)
+        return { verdict: "parent_must_move", inferred: false, via: [...new Set(via)] };
+    if (read.length > 0 && read.every((ok) => ok === true))
+        return { verdict: "refresh", inferred: false, via: [] };
+    const leaves = leavesCaret(installed, target);
+    if (leaves === null)
+        return { verdict: "unknown", inferred: true, via: [] };
+    return { verdict: leaves ? "parent_must_move" : "refresh", inferred: true, via: [] };
+}

package/dist/live/version-compare.d.ts

@@ -20,6 +20,8 @@ interface Pep440 {
     pre: [number, number] | null;
     post: number | null;
     dev: number | null;
+    /** Local label segments ("1.0+ubuntu.1" -> ["ubuntu", 1]); empty for none. */
+    local: Array<number | string>;
 }
 export declare function parsePep440(version: string): Pep440 | null;
 export declare function comparePep440(a: Pep440, b: Pep440): number;

package/dist/live/version-compare.js

@@ -15,7 +15,7 @@
  */
 import { compareSemver, parseSemver } from "./semver-utils.js";
 import { compareVersionPrecedence, parseSemverPrecedence } from "./semver-precedence.js";
-const PEP440 = /^v?(?:(\d+)!)?(\d+(?:\.\d+)*)(?:[-_.]?(a|alpha|b|beta|c|rc|pre|preview)[-_.]?(\d*))?(?:(?:[-_.]?(?:post|rev|r)[-_.]?(\d*))|-(\d+))?(?:[-_.]?dev[-_.]?(\d*))?(?:\+[a-z0-9]+(?:[-_.][a-z0-9]+)*)?$/i;
+const PEP440 = /^v?(?:(\d+)!)?(\d+(?:\.\d+)*)(?:[-_.]?(a|alpha|b|beta|c|rc|pre|preview)[-_.]?(\d*))?(?:(?:[-_.]?(?:post|rev|r)[-_.]?(\d*))|-(\d+))?(?:[-_.]?dev[-_.]?(\d*))?(?:\+([a-z0-9]+(?:[-_.][a-z0-9]+)*))?$/i;
 export function parsePep440(version) {
     const m = PEP440.exec(version.trim());
     if (!m)
@@ -27,6 +27,7 @@ export function parsePep440(version) {
         pre: m[3] ? [preRank[m[3].toLowerCase()], m[4] ? Number(m[4]) : 0] : null,
         post: m[5] !== undefined ? (m[5] ? Number(m[5]) : 0) : m[6] !== undefined ? Number(m[6]) : null,
         dev: m[7] !== undefined ? (m[7] ? Number(m[7]) : 0) : null,
+        local: m[8] ? m[8].split(/[-_.]/).map((seg) => (/^\d+$/.test(seg) ? Number(seg) : seg.toLowerCase())) : [],
     };
 }
 export function comparePep440(a, b) {
@@ -55,7 +56,26 @@ export function comparePep440(a, b) {
         if (ka[i] !== kb[i])
             return ka[i] > kb[i] ? 1 : -1;
     }
-    return 0;
+    return compareLocal(a.local, b.local);
+}
+/**
+ * PEP 440 local labels, which decide only between otherwise equal versions:
+ * none sorts below any (1.0 < 1.0+abc.5); segment by segment, numbers compare
+ * numerically and sort above strings, strings compare case-folded; a label
+ * that extends another sorts above it (1.0+abc.5 < 1.0+abc.7 < 1.0+5).
+ * Dropping the label made these compare equal, so a `last_affected` bound
+ * equal to a local-labelled install was misread.
+ */
+function compareLocal(a, b) {
+    for (let i = 0; i < Math.min(a.length, b.length); i++) {
+        const [x, y] = [a[i], b[i]];
+        if (x === y)
+            continue;
+        if (typeof x !== typeof y)
+            return typeof x === "number" ? 1 : -1;
+        return x > y ? 1 : -1;
+    }
+    return Math.sign(a.length - b.length);
 }
 // ---------------------------------------------------------------------------
 // Dispatch

package/dist/tools/upgrade-planner-fixpaths.d.ts

@@ -28,6 +28,8 @@ export interface FixPathStep {
         dir: string;
         command: string;
     }>;
+    /** lockfile_refresh: true when not every parent's requirement could be read and the verdict comes from semver compatibility. */
+    refreshInferred?: boolean;
 }
 export interface FixPathInput {
     step: FixPathStep;

package/dist/tools/upgrade-planner.d.ts

@@ -57,9 +57,11 @@ interface UpgradeRecommendation {
     /**
      * Direct deps you can bump yourself; `lockfile_refresh` = transitive, and
      * every parent's declared requirement already admits a clean version, so
-     * `refreshCommands` fixes it; `waiting_on_upstream` = transitive, and a
-     * parent's requirement excludes every clean version (or could not be
-     * read); `reinstall` = the lockfile's version is fine
+     * `refreshCommands` fixes it (`refreshInferred` when that is inferred from
+     * semver because a requirement could not be read); `waiting_on_upstream` =
+     * transitive, and a parent's requirement excludes every clean version (or
+     * none could be read and the target leaves the semver-compatible range);
+     * `reinstall` = the lockfile's version is fine
      * but node_modules holds another one, so the fix is `installFix`;
      * `no_fix_available` = vulnerable with no fixed release to move to;
      * `not_built_on_this_host` = every advisory is against code this host never compiles.
@@ -78,6 +80,12 @@ interface UpgradeRecommendation {
         dir: string;
         command: string;
     }>;
+    /**
+     * lockfile_refresh: true when not every parent's requirement could be read
+     * (none read excludes the target) and the target is semver-compatible with
+     * the installed version, so the refresh is inferred rather than read.
+     */
+    refreshInferred?: boolean;
     /** False when the dependency is gated behind a target spec not active on this host (label, never suppressed). */
     platformActive: boolean;
     /** npm: the version node_modules holds, when it differs from `currentVersion` (the lockfile's). */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@4da/mcp-server",
-  "version": "6.2.2",
+  "version": "6.2.4",
   "mcpName": "io.github.4DA-Systems/4da-mcp-server",
   "description": "Upgrade intelligence for AI coding agents: what changes between your installed and target version (changelog, breaking changes, the files you import it from), a pre-install verdict on each bump, vulnerability scanning at osv-scanner parity across npm/pnpm/yarn, Cargo, Python and Go lockfiles, ranked upgrade plans, task-scoped briefings, decision memory. Local, no account; works standalone, and adds the 4DA desktop app's signals, knowledge gaps and stack-judged news when it is installed.",
   "type": "module",