@4da/mcp-server 6.2.1 → 6.2.2

package/CHANGELOG.md

@@ -1,5 +1,42 @@
 # Changelog
 
+## 6.2.2 — 2026-10-11
+
+### Lockfile readers agree with the 4DA conformance corpus
+
+The dependency engine is now scored in CI against the conformance corpus of
+the 4DA desktop app (35 public repositories and synthetic cases, pinned OSV
+records, adjudicated truth; see `conformance/README.md`), the same truth the
+app's own engine is held to. The first run found five reader defects, all
+fixed. On the corpus, findings and inventory precision and recall are now
+1.0 in npm, crates.io, PyPI and Go, with no silent drops.
+
+- **Go modules before go 1.17 report what is built.** go.sum records the
+  go.mod hash of every module version the graph walk visits, but the source
+  only of modules the build compiles. A module with only a `/go.mod` line at
+  its selected version was reported as installed: 728 never-built modules on
+  hugo, node_exporter and traefik, with 182 advisory findings that did not apply. A
+  module now counts when go.sum hashes its source at the version minimal
+  version selection picks, and `replace` applies to these modules as it does
+  to go.mod's own requirements (including `old v1.2.3 => new v1.3.0`).
+- **Versions an advisory lists match by value, not spelling.** OSV lists
+  certifi `2020.12.05` (from the git tag) and pip installs `2020.12.5`, the
+  same PEP 440 version. The local range check (fix targets, `range_check`,
+  `dependency_check`) did not see it as affected by PYSEC-2024-230.
+- **uv and poetry: a git, URL or local source is not a PyPI release.**
+  pydantic's uv.lock pins pydantic-extra-types 2.10.0 from git `main`; it was
+  scanned as the PyPI release of that number. poetry `[package.source]` types
+  `git`, `url`, `file` and `directory` are skipped too; `legacy` (a private
+  index) still counts.
+- **yarn: an npm alias is scanned as the package it installs.**
+  `"string-width-cjs@npm:string-width@^4.2.0"` was read as a package named
+  `string-width-cjs`, which OSV does not know, so string-width 4.2.3 was never
+  checked. berry's `resolution:` and v1's alias spec now name the package.
+- **pnpm 5: entries keyed by a tarball URL are read.** pnpm writes `name:`
+  and `version:` fields under such a key; trpc's lockfile installs
+  @prisma/client 4.7.1 four times that way and none was read. A tarball that
+  is not a registry artifact (codeload, a git archive) is still skipped.
+
 ## 6.2.1 — 2026-10-11
 
 ### Feed tools leave out sources you turned off in the 4DA app

package/dist/live/index.d.ts

@@ -8,6 +8,7 @@
  * Set FOURDA_OFFLINE=true to disable all network calls.
  */
 import type { SqliteDatabase } from "../sqlite-driver.js";
+import { type AdvisorySource } from "./osv-scanner.js";
 import { FixPathSources } from "./fix-paths.js";
 import type { CheckEcosystem, ReleaseMetadataSource } from "./release-metadata.js";
 import { type ResolutionGroup } from "./resolution.js";
@@ -70,7 +71,14 @@ export declare class LiveIntelligence {
     private warmup;
     /** When the last warmup came back offline; gates the retry so an offline host is not re-probed on every call. */
     private warmupFailedAt;
-    constructor(db: SqliteDatabase | null);
+    /**
+     * `advisorySource` replaces OSV.dev for vulnerability scans (the conformance
+     * harness passes pinned records). A source that needs no network keeps
+     * scanning enabled under FOURDA_OFFLINE; nothing else changes.
+     */
+    constructor(db: SqliteDatabase | null, options?: {
+        advisorySource?: AdvisorySource;
+    });
     /** Advisory, registry and parent-requirement lookups for fix paths; null when offline. */
     getFixPathSources(): FixPathSources | null;
     /**

package/dist/live/index.js

@@ -84,12 +84,17 @@ export class LiveIntelligence {
     warmup = null;
     /** When the last warmup came back offline; gates the retry so an offline host is not re-probed on every call. */
     warmupFailedAt = null;
-    constructor(db) {
+    /**
+     * `advisorySource` replaces OSV.dev for vulnerability scans (the conformance
+     * harness passes pinned records). A source that needs no network keeps
+     * scanning enabled under FOURDA_OFFLINE; nothing else changes.
+     */
+    constructor(db, options = {}) {
         this.db = db;
-        this.enabled = process.env.FOURDA_OFFLINE !== "true";
+        this.enabled = process.env.FOURDA_OFFLINE !== "true" || options.advisorySource?.network === false;
         this.cache = new LiveCache(db);
         this.rateLimiter = new RateLimiter(DEFAULT_RATE_LIMITS);
-        this.osvScanner = new OsvScanner(this.cache, this.rateLimiter);
+        this.osvScanner = new OsvScanner(this.cache, this.rateLimiter, options.advisorySource);
         this.hnFetcher = new HNFetcher(this.cache, this.rateLimiter);
         this.npmRegistry = new NpmRegistry(this.cache, this.rateLimiter);
         this.cratesRegistry = new CratesRegistry(this.cache, this.rateLimiter);

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

@@ -57,6 +57,65 @@ export function parsePnpmKey(rawKey) {
     }
     return null;
 }
+function yamlScalar(text, key) {
+    if (!text.startsWith(`${key}:`))
+        return null;
+    const value = unquote(text.slice(key.length + 1).trim()).trim();
+    return value === "" ? null : value;
+}
+function pnpmEntryField(entry, text) {
+    entry.inResolution = false;
+    const dev = /^dev:\s*(true|false)\s*$/.exec(text);
+    const name = yamlScalar(text, "name");
+    const version = yamlScalar(text, "version");
+    if (dev)
+        entry.dev = dev[1] === "true";
+    else if (name)
+        entry.name = name;
+    else if (version)
+        entry.version = exactVersion(version) ?? undefined;
+    else if (text.startsWith("resolution:")) {
+        entry.inResolution = true;
+        pnpmResolutionText(entry, text.slice("resolution:".length));
+    }
+}
+/** `resolution:` is a flow mapping, on one line or (pnpm 5) spread over several. */
+function pnpmResolutionText(entry, text) {
+    for (const part of text.split(/[,{}]/)) {
+        const field = part.trim();
+        if (field.startsWith("tarball:"))
+            entry.tarball = unquote(field.slice("tarball:".length).trim());
+        else if (/^(?:commit|repo|directory):/.test(field))
+            entry.local = true;
+    }
+}
+/** A registry tarball (`https://<registry>/<name>/-/<name>-<version>.tgz`, query allowed), not a codeload/git/arbitrary archive. */
+function isRegistryTarball(url) {
+    const pathPart = url.split(/[?#]/)[0];
+    return pathPart.includes("/-/") && /\.tgz$/i.test(pathPart);
+}
+/**
+ * The (name, version) a pnpm entry installs from a registry, or null.
+ *
+ * The key is not always `name@version`: pnpm 5 keys a package fetched by
+ * tarball URL by that URL and writes `name:`/`version:` fields under it.
+ * trpc's lockfile installs @prisma/client 4.7.1 four times that way, from
+ * registry.npmjs.com, and none of them was read (4DA conformance corpus,
+ * 2026-10-12). The fields win when present; a tarball that is not a registry
+ * artifact, a git checkout or a directory is not a registry release.
+ */
+function pnpmEntryIdentity(entry) {
+    if (entry.local)
+        return null;
+    const parsed = parsePnpmKey(entry.key);
+    if (entry.name && PACKAGE_NAME.test(entry.name)) {
+        if (entry.tarball && !isRegistryTarball(entry.tarball))
+            return null;
+        const version = entry.version ?? parsed?.[1];
+        return version ? [entry.name, version] : null;
+    }
+    return parsed;
+}
 /**
  * Reads a pnpm lockfile (v5.x, v6 or v9) into `versions`; the first version seen wins.
  *
@@ -80,30 +139,38 @@ 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 packageKey = null; // the packages/snapshots key whose fields are being read
+    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;
+    };
     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();
             section = text.endsWith(":") ? text.slice(0, -1) : "";
             blockIndent = DEPENDENCY_BLOCKS.has(text) ? 0 : -1;
             pending = null;
-            packageKey = null;
             continue;
         }
         if (section === "packages" || section === "snapshots") {
             if (indent === 2 && text.endsWith(":")) {
-                const parsed = parsePnpmKey(text.slice(0, -1));
-                packageKey = parsed ? `${parsed[0]}\0${parsed[1]}` : null;
-                if (parsed)
-                    transitive.push(parsed);
+                finish();
+                entry = { key: text.slice(0, -1), inResolution: false, local: false };
             }
-            else if (indent === 4 && packageKey) {
-                const dev = /^dev:\s*(true|false)\s*$/.exec(text);
-                if (dev)
-                    devByKey.set(packageKey, dev[1] === "true");
+            else if (entry && indent === 4) {
+                pnpmEntryField(entry, text);
+            }
+            else if (entry?.inResolution && indent > 4) {
+                pnpmResolutionText(entry, text);
             }
             continue;
         }
@@ -137,6 +204,7 @@ export function readPnpmLock(content, versions, instances) {
             pending = null;
         }
     }
+    finish();
     for (const [name, version] of transitive)
         setFirst(name, version);
     if (!instances)
@@ -148,6 +216,21 @@ export function readPnpmLock(content, versions, instances) {
     for (const [name, version] of transitive)
         instances.add(name, version, devByKey.get(`${name}\0${version}`));
 }
+/**
+ * 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.
+ */
+function yarnPackageName(block, firstLine, headerName) {
+    const resolution = /^\s+resolution:\s+"?((?:@[^\s/@"]+\/)?[^\s/@"]+)@npm:/m.exec(block);
+    if (resolution)
+        return resolution[1];
+    const alias = /^"?(?:@[^\s/@"]+\/)?[^\s/@"]+@npm:((?:@[^\s/@"]+\/)?[^\s/@"]+)@/.exec(firstLine);
+    return alias ? alias[1] : headerName;
+}
 /**
  * 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"`.
@@ -166,12 +249,13 @@ export function readYarnLock(content, versions, instances, specs) {
         const version = line ? exactVersion(line[1]) : null;
         if (!version)
             continue;
+        const name = yarnPackageName(block, firstLine, header[1]);
         // One block per resolved version. Blocks are sorted by spec, so the first
         // block of a name can be an old nested copy; `specs` lets the caller pick
         // the copy a package.json range resolves to instead.
-        if (!versions.has(header[1]))
-            versions.set(header[1], version);
-        instances?.add(header[1], version);
+        if (!versions.has(name))
+            versions.set(name, version);
+        instances?.add(name, version);
         if (specs) {
             for (const spec of firstLine.replace(/:\s*$/, "").split(",")) {
                 specs.set(unquote(spec.trim()).replace(/@npm:/, "@"), version);

package/dist/live/lockfile-parsers-pygo.d.ts

@@ -69,23 +69,53 @@ export declare function parseRequirements(content: string): Array<{
     version: string;
 }>;
 export declare function resolveGo(cwd: string): VersionSource;
-/** `require` lines (block and single form) with `replace` applied, and whether the go directive is >= 1.17. */
+/** A `replace` target: another module version, or null for a local directory. */
+type GoReplacement = {
+    module: string;
+    version: string;
+} | null;
+/**
+ * `require` lines (block and single form) with `replace` applied, the same
+ * lines as written, `replace` for any other module version, and whether the
+ * go directive is >= 1.17. A `replace` may name the version it replaces
+ * (`old v1.2.3 => new v1.3.0`); that one wins over a versionless one.
+ */
 export declare function parseGoMod(content: string): {
     requires: Array<{
         module: string;
         version: string;
         indirect: boolean;
     }>;
+    /** Requirements as written, before `replace`. */
+    rawRequires: Array<{
+        module: string;
+        version: string;
+        indirect: boolean;
+    }>;
+    /** What `replace` maps a module version to: undefined for nothing, null for local code. */
+    replacement: (module: string, version: string) => GoReplacement | undefined;
     goVersionAtLeast117: boolean;
 };
 /**
- * Per module, the highest version go.sum records — minimal version selection
- * picks the highest required version, and go.sum records every version the
- * module graph required. A module listed only by its `/go.mod` hash is still
- * in Go's build list (`go list -m all`): measured 2026-10-02 on gh cli v1.0
- * (go 1.13), skipping those lines missed 14 advisories (grpc 1.21.0,
- * jwt-go, gorilla/websocket, ...) the build list carries.
+ * Per module, the version the build selected according to go.sum (go < 1.17):
+ * the HIGHEST version recorded there by either line, since minimal version
+ * selection picks the highest version the module graph requires and go.sum
+ * records every one, kept only when go.sum also hashes that version's SOURCE
+ * (`module v1.2.3 h1:...`, not only `module v1.2.3/go.mod h1:...`).
+ *
+ * The go command records the go.mod hash of every module version it visits
+ * while walking the graph, but downloads and hashes the source only of
+ * modules whose packages the build imports. A module with only a `/go.mod`
+ * line at its selected version is in `go list -m all` but is never compiled.
+ * Counting those (the 6.2 rule) read 728 never-built modules as installed
+ * on hugo, node_exporter and traefik: 4DA conformance corpus, 2026-10-12,
+ * whose truth is the build list restricted to source-hashed modules, as the
+ * desktop app reads it. An older version's leftover source hash does not make
+ * that older version built either: node_exporter hashes gogo/protobuf
+ * v1.1.1's source while the graph selects v1.2.1 (go.mod hash only), so
+ * neither is installed.
  */
 export declare function selectedFromGoSum(content: string): Map<string, string>;
 /** Semver precedence over Go versions; build metadata (`+incompatible`) is ignored. */
 export declare function compareGoVersions(a: string, b: string): number;
+export {};

package/dist/live/lockfile-parsers-pygo.js

@@ -226,6 +226,24 @@ function unpinnedRequirementNames(content) {
     }
     return out;
 }
+/**
+ * Whether a lockfile [[package]] entry is a release from a package index.
+ * Only those are what PyPI advisories describe. Not one: the project itself
+ * and local code (uv `editable`/`virtual`/`directory`/`path`), a git checkout
+ * or a direct-URL archive (uv `git`/`url`; poetry `[package.source] type =
+ * "git" | "url" | "file" | "directory"`). A git checkout keeps the version
+ * number of a release it is not: pydantic's uv.lock pins
+ * pydantic-extra-types 2.10.0 from git `main` (4DA conformance corpus).
+ * poetry's `legacy` source is a private index, so its packages are releases.
+ */
+function fromPackageIndex(block, body) {
+    const uv = /^source\s*=\s*\{\s*([a-z-]+)\s*=/m.exec(body)?.[1];
+    if (uv && uv !== "registry")
+        return false;
+    const poetrySource = /^\[package\.source\]\s*$([\s\S]*?)(?=^\[|(?![\s\S]))/m.exec(block)?.[1] ?? "";
+    const poetryType = /^type\s*=\s*"([^"]*)"/m.exec(poetrySource)?.[1];
+    return !(poetryType && ["git", "url", "file", "directory"].includes(poetryType));
+}
 /**
  * [[package]] tables from poetry.lock (any version) or uv.lock. A pre-1.2
  * poetry.lock records `category = "dev"` for dev-only packages; newer files
@@ -242,8 +260,7 @@ export function readTomlPackageLock(content) {
         const version = field("version");
         if (!name || !version)
             continue;
-        // uv.lock lists the project itself (source = { editable/virtual = "." }); it is not a release.
-        if (/^source\s*=\s*\{\s*(?:editable|virtual)\s*=/m.test(body))
+        if (!fromPackageIndex(block, body))
             continue;
         const category = field("category");
         const normalized = normalizePythonName(name);
@@ -294,35 +311,47 @@ export function resolveGo(cwd) {
     catch {
         return emptySource();
     }
-    const versions = new Map();
-    const instances = new InstanceSet();
-    for (const { module, version } of mod.requires) {
-        versions.set(module, version);
-        instances.add(module, version);
-    }
+    // The build list: go.mod's requirements and, before go 1.17, the modules
+    // go.sum says the build selected; `replace` applies to both.
+    const selected = new Map(mod.rawRequires.map((r) => [r.module, r.version]));
     // From go 1.17 the go.mod `require` list names every module the build needs
     // (module-graph pruning), so it IS the selected set and go.sum (which keeps
     // hashes for versions the build never selects) would only over-report.
     // Before 1.17 go.mod lists direct requirements only; transitives come from
-    // go.sum, at the highest version whose module zip is hashed there — what
-    // minimal version selection picked.
+    // go.sum (selectedFromGoSum: the version MVS picked, when its source is built).
     if (!mod.goVersionAtLeast117) {
         const goSumPath = path.join(cwd, "go.sum");
         if (fs.existsSync(goSumPath)) {
             try {
                 for (const [module, version] of selectedFromGoSum(fs.readFileSync(goSumPath, "utf-8"))) {
-                    if (versions.has(module))
-                        continue;
-                    versions.set(module, version);
-                    instances.add(module, version);
+                    if (!selected.has(module))
+                        selected.set(module, version);
                 }
             }
             catch { /* skip */ }
         }
     }
+    const versions = new Map();
+    for (const [module, version] of selected) {
+        const target = mod.replacement(module, version);
+        if (target === null)
+            continue; // replaced by a local directory: local code, not a registry module
+        if (target)
+            versions.set(target.module, target.version);
+        else if (!versions.has(module))
+            versions.set(module, version);
+    }
+    const instances = new InstanceSet();
+    for (const [module, version] of versions)
+        instances.add(module, version);
     return found(versions, instances, goModPath, "lockfile");
 }
-/** `require` lines (block and single form) with `replace` applied, and whether the go directive is >= 1.17. */
+/**
+ * `require` lines (block and single form) with `replace` applied, the same
+ * lines as written, `replace` for any other module version, and whether the
+ * go directive is >= 1.17. A `replace` may name the version it replaces
+ * (`old v1.2.3 => new v1.3.0`); that one wins over a versionless one.
+ */
 export function parseGoMod(content) {
     const requires = new Map();
     const replaces = new Map();
@@ -354,42 +383,68 @@ export function parseGoMod(content) {
             const [left, right] = rest.split("=>").map((s) => s.trim().split(/\s+/));
             if (!left?.[0] || !right?.[0])
                 continue;
-            replaces.set(left[0], right[1] && GO_VERSION.test(right[1]) ? { module: right[0], version: right[1] } : null);
+            const key = left[1] ? `${left[0]} ${left[1]}` : left[0];
+            replaces.set(key, right[1] && GO_VERSION.test(right[1]) ? { module: right[0], version: right[1] } : null);
         }
     }
+    const replacement = (module, version) => {
+        const exact = `${module} ${version}`;
+        if (replaces.has(exact))
+            return replaces.get(exact);
+        return replaces.has(module) ? replaces.get(module) : undefined;
+    };
+    const rawRequires = [...requires.values()];
     const result = [];
-    for (const req of requires.values()) {
-        if (!replaces.has(req.module)) {
+    for (const req of rawRequires) {
+        const target = replacement(req.module, req.version);
+        if (target === undefined)
             result.push(req);
-            continue;
-        }
-        const target = replaces.get(req.module);
-        if (target)
+        else if (target)
             result.push({ module: target.module, version: target.version, indirect: req.indirect });
     }
     const go = /^go\s+(\d+)\.(\d+)/m.exec(content);
     const goVersionAtLeast117 = go ? Number(go[1]) > 1 || Number(go[2]) >= 17 : false;
-    return { requires: result, goVersionAtLeast117 };
+    return { requires: result, rawRequires, replacement, goVersionAtLeast117 };
 }
 /**
- * Per module, the highest version go.sum records — minimal version selection
- * picks the highest required version, and go.sum records every version the
- * module graph required. A module listed only by its `/go.mod` hash is still
- * in Go's build list (`go list -m all`): measured 2026-10-02 on gh cli v1.0
- * (go 1.13), skipping those lines missed 14 advisories (grpc 1.21.0,
- * jwt-go, gorilla/websocket, ...) the build list carries.
+ * Per module, the version the build selected according to go.sum (go < 1.17):
+ * the HIGHEST version recorded there by either line, since minimal version
+ * selection picks the highest version the module graph requires and go.sum
+ * records every one, kept only when go.sum also hashes that version's SOURCE
+ * (`module v1.2.3 h1:...`, not only `module v1.2.3/go.mod h1:...`).
+ *
+ * The go command records the go.mod hash of every module version it visits
+ * while walking the graph, but downloads and hashes the source only of
+ * modules whose packages the build imports. A module with only a `/go.mod`
+ * line at its selected version is in `go list -m all` but is never compiled.
+ * Counting those (the 6.2 rule) read 728 never-built modules as installed
+ * on hugo, node_exporter and traefik: 4DA conformance corpus, 2026-10-12,
+ * whose truth is the build list restricted to source-hashed modules, as the
+ * desktop app reads it. An older version's leftover source hash does not make
+ * that older version built either: node_exporter hashes gogo/protobuf
+ * v1.1.1's source while the graph selects v1.2.1 (go.mod hash only), so
+ * neither is installed.
  */
 export function selectedFromGoSum(content) {
-    const selected = new Map();
+    const highest = new Map();
+    const sourceHashed = new Set();
     for (const line of content.split(/\r?\n/)) {
         const [module, rawVersion] = line.trim().split(/\s+/);
-        const version = rawVersion?.replace(/\/go\.mod$/, "");
-        if (!module || !version || !GO_VERSION.test(version))
+        if (!module || !rawVersion)
+            continue;
+        const version = rawVersion.replace(/\/go\.mod$/, "");
+        if (!GO_VERSION.test(version))
             continue;
-        const current = selected.get(module);
+        if (version === rawVersion)
+            sourceHashed.add(`${module} ${version}`);
+        const current = highest.get(module);
         if (!current || compareGoVersions(version, current) > 0)
-            selected.set(module, version);
+            highest.set(module, version);
     }
+    const selected = new Map();
+    for (const [module, version] of highest)
+        if (sourceHashed.has(`${module} ${version}`))
+            selected.set(module, version);
     return selected;
 }
 /** Semver precedence over Go versions; build metadata (`+incompatible`) is ignored. */

package/dist/live/osv-ranges.d.ts

@@ -41,7 +41,14 @@ export interface AdvisoryRanges {
 export declare function collectAffectedSpans(affected: OsvVulnerability["affected"] | undefined, packageName: string, ecosystem: string): AffectedSpan[];
 /** One advisory's ranges for one package; null when the advisory is withdrawn. */
 export declare function advisoryRanges(vuln: OsvVulnerability, packageName: string, ecosystem: string): AdvisoryRanges | null;
-/** True when `version` lies in a span (or the explicit list) of this advisory. */
+/**
+ * True when `version` lies in a span (or the explicit list) of this advisory.
+ *
+ * A listed version matches when it is the same version in the ecosystem's
+ * order, not only the same string: OSV lists certifi `2020.12.05` (from the
+ * git tag) and pip installs `2020.12.5`, the same PEP 440 version, which OSV
+ * reports as affected by PYSEC-2024-230 (4DA conformance corpus, 2026-10-12).
+ */
 export declare function advisoryAffects(advisory: AdvisoryRanges, version: string, ecosystem: string): boolean;
 /** Whether a version is a prerelease in its ecosystem's own terms. */
 export declare function isPrereleaseVersion(version: string, ecosystem: string): boolean;

package/dist/live/osv-ranges.js

@@ -78,11 +78,21 @@ export function advisoryRanges(vuln, packageName, ecosystem) {
         maintenance: isMaintenanceNotice({ summary: vuln.summary ?? "" }) || informational === "unmaintained" || informational === "notice",
     };
 }
-/** True when `version` lies in a span (or the explicit list) of this advisory. */
+/**
+ * True when `version` lies in a span (or the explicit list) of this advisory.
+ *
+ * A listed version matches when it is the same version in the ecosystem's
+ * order, not only the same string: OSV lists certifi `2020.12.05` (from the
+ * git tag) and pip installs `2020.12.5`, the same PEP 440 version, which OSV
+ * reports as affected by PYSEC-2024-230 (4DA conformance corpus, 2026-10-12).
+ */
 export function advisoryAffects(advisory, version, ecosystem) {
     if (advisory.versions.includes(version))
         return true;
     const cmp = (a, b) => compareVersions(a, b, ecosystem);
+    if (isComparable(version, ecosystem) && advisory.versions.some((v) => v !== "0" && isComparable(v, ecosystem) && cmp(v, version) === 0)) {
+        return true;
+    }
     return advisory.spans.some((s) => cmp(version, s.introduced) >= 0 &&
         (s.fixed !== null ? cmp(version, s.fixed) < 0 : s.lastAffected !== null ? cmp(version, s.lastAffected) <= 0 : true));
 }

package/dist/live/osv-scanner.d.ts

@@ -9,22 +9,49 @@
 import type { LiveCache } from "./cache.js";
 import type { RateLimiter } from "./rate-limiter.js";
 import type { ResolvedDependency, OsvVulnerability, VulnerabilityEntry, VulnerabilityScanResult } from "./types.js";
-export declare class OsvScanner {
-    private cache;
-    private rateLimiter;
+/**
+ * Where advisories come from. The scanner asks which advisory ids affect each
+ * exact (ecosystem, name, version), then for the records behind those ids.
+ *
+ * - OsvHttpSource (the server's): OSV.dev's own evaluator decides membership
+ *   (`/v1/querybatch`), records come from `/v1/vulns/{id}`, both cached.
+ * - PinnedRecordsSource (pinned-advisories.ts): a fixed set of records on
+ *   disk, membership decided locally by osv-ranges.ts. No network. The
+ *   conformance harness scores the engine with it against the 4DA corpus.
+ */
+export interface AdvisorySource {
+    /** True when answers come over the network: rate-limited, and cached per dependency. */
+    readonly network: boolean;
+    /** The advisory ids affecting each dependency, in input order. Throws when it cannot answer for all of them. */
+    query(deps: ResolvedDependency[]): Promise<string[][]>;
+    /** The full record of each id it can find; a missing id is left out, never fatal. */
+    details(ids: string[]): Promise<Map<string, OsvVulnerability>>;
+}
+/** OSV.dev over HTTP: querybatch for membership, per-id hydration for records. */
+export declare class OsvHttpSource implements AdvisorySource {
+    private readonly cache;
+    private readonly rateLimiter;
+    readonly network = true;
     constructor(cache: LiveCache, rateLimiter: RateLimiter);
-    scan(deps: ResolvedDependency[], projectPath: string): Promise<VulnerabilityScanResult>;
-    private batchQuery;
+    query(deps: ResolvedDependency[]): Promise<string[][]>;
     /**
      * Hydrate advisory detail for the given IDs. Cache-first (24h), then fetch the
      * misses from `/v1/vulns/{id}` with bounded concurrency. A failed fetch is
      * skipped (not fatal) — the caller falls back to the index-only shape so a
      * real advisory is never silently dropped just because its detail 404'd.
      */
-    private hydrateDetails;
+    details(ids: string[]): Promise<Map<string, OsvVulnerability>>;
     /** One advisory's record; retried once after a throttle, a server error or a network failure. Null when it cannot be had. */
     private fetchDetail;
 }
+export declare class OsvScanner {
+    private cache;
+    private rateLimiter;
+    private source;
+    constructor(cache: LiveCache, rateLimiter: RateLimiter, source?: AdvisorySource);
+    scan(deps: ResolvedDependency[], projectPath: string): Promise<VulnerabilityScanResult>;
+    private batchQuery;
+}
 /**
  * Overwrite the dep-context fields of a cached advisory entry with the CURRENT
  * resolution's context. The advisory facts (id, severity, summary, fix version)

package/dist/live/osv-scanner.js

@@ -49,79 +49,18 @@ async function pool(items, limit, work) {
     await Promise.all(Array.from({ length: Math.min(limit, items.length) }, worker));
     return out;
 }
-export class OsvScanner {
+/** OSV.dev over HTTP: querybatch for membership, per-id hydration for records. */
+export class OsvHttpSource {
     cache;
     rateLimiter;
+    network = true;
     constructor(cache, rateLimiter) {
         this.cache = cache;
         this.rateLimiter = rateLimiter;
     }
-    async scan(deps, projectPath) {
-        const start = Date.now();
-        const scannable = deps.filter((d) => d.version !== null);
-        const ecosystems = [...new Set(scannable.map((d) => d.ecosystem))];
-        // Check cache for each dep individually
-        const uncached = [];
-        const cachedVulns = [];
-        for (const dep of scannable) {
-            const cacheKey = `osv:${dep.ecosystem}:${dep.name}:${dep.version}`;
-            const cached = this.cache.get(cacheKey);
-            if (cached !== null) {
-                cachedVulns.push(...cached.map((v) => restampDepContext(v, dep)));
-            }
-            else {
-                uncached.push(dep);
-            }
-        }
-        // Fetch uncached from OSV
-        let fetchedVulns = [];
-        let offline = false;
-        if (uncached.length > 0) {
-            if (!this.rateLimiter.canProceed("osv")) {
-                offline = true;
-            }
-            else {
-                try {
-                    fetchedVulns = await this.batchQuery(uncached);
-                }
-                catch {
-                    offline = true;
-                    // Try stale cache for uncached deps
-                    for (const dep of uncached) {
-                        const cacheKey = `osv:${dep.ecosystem}:${dep.name}:${dep.version}`;
-                        const stale = this.cache.getStale(cacheKey);
-                        if (stale)
-                            cachedVulns.push(...stale.data.map((v) => restampDepContext(v, dep)));
-                    }
-                }
-            }
-        }
-        const allVulns = [...cachedVulns, ...fetchedVulns];
-        const vulnerablePackages = new Set(allVulns.map((v) => v.package));
-        const platformInactiveVulnerable = new Set(allVulns.filter((v) => !v.platformActive).map((v) => v.package)).size;
-        const bySeverity = { critical: 0, high: 0, medium: 0, low: 0, unknown: 0 };
-        for (const v of allVulns) {
-            bySeverity[v.severity]++;
-        }
-        return {
-            scannedAt: new Date().toISOString(),
-            projectPath,
-            ecosystemsScanned: ecosystems,
-            totalScanned: scannable.length,
-            totalVulnerable: vulnerablePackages.size,
-            platformInactiveVulnerable,
-            bySeverity,
-            vulnerabilities: allVulns,
-            cleanCount: offline ? 0 : scannable.length - vulnerablePackages.size,
-            scanDurationMs: Date.now() - start,
-            cached: uncached.length === 0,
-            offline,
-        };
-    }
-    async batchQuery(deps) {
-        // Phase 1 — enumerate advisory IDs per dep via the lightweight batch index.
+    async query(deps) {
         // querybatch returns only `{ id, modified }`; the rich fields (severity,
-        // fixed version, summary, references) come from per-advisory hydration below.
+        // fixed version, summary, references) come from per-advisory hydration.
         const chunks = [];
         for (let offset = 0; offset < deps.length; offset += MAX_BATCH_SIZE)
             chunks.push(deps.slice(offset, offset + MAX_BATCH_SIZE));
@@ -147,27 +86,9 @@ export class OsvScanner {
                 throw new Error(`OSV API error: ${response.status}`);
             }
             const data = (await response.json());
-            return chunk.map((dep, i) => ({ dep, ids: (data.results[i]?.vulns ?? []).map((v) => v.id) }));
+            return chunk.map((_, i) => (data.results[i]?.vulns ?? []).map((v) => v.id));
         });
-        const matches = answered.flat();
-        // Phase 2 — hydrate each unique advisory once (cached, bounded concurrency).
-        const uniqueIds = [...new Set(matches.flatMap((m) => m.ids))];
-        const detailById = await this.hydrateDetails(uniqueIds);
-        // Phase 3 — map to entries and cache per-dep (empty results cached too, so
-        // clean deps are not re-queried).
-        const results = [];
-        const rows = [];
-        for (const { dep, ids } of matches) {
-            // Drop advisories OSV has withdrawn/retracted — surfacing them is a false
-            // positive. Un-hydrated ids (detail fetch failed) are kept: we can't know,
-            // and dropping a real advisory is worse than keeping an un-enriched one.
-            const liveIds = ids.filter((id) => !detailById.get(id)?.withdrawn);
-            const depVulns = liveIds.map((id) => mapVulnerability(detailById.get(id) ?? { id }, dep));
-            rows.push([`osv:${dep.ecosystem}:${dep.name}:${dep.version}`, depVulns]);
-            results.push(...depVulns);
-        }
-        this.cache.setMany(rows, "osv", OSV_CACHE_TTL);
-        return results;
+        return answered.flat();
     }
     /**
      * Hydrate advisory detail for the given IDs. Cache-first (24h), then fetch the
@@ -175,7 +96,7 @@ export class OsvScanner {
      * skipped (not fatal) — the caller falls back to the index-only shape so a
      * real advisory is never silently dropped just because its detail 404'd.
      */
-    async hydrateDetails(ids) {
+    async details(ids) {
         const out = new Map();
         const toFetch = [];
         for (const id of ids) {
@@ -221,6 +142,107 @@ export class OsvScanner {
         return null;
     }
 }
+export class OsvScanner {
+    cache;
+    rateLimiter;
+    source;
+    constructor(cache, rateLimiter, source) {
+        this.cache = cache;
+        this.rateLimiter = rateLimiter;
+        this.source = source ?? new OsvHttpSource(cache, rateLimiter);
+    }
+    async scan(deps, projectPath) {
+        const start = Date.now();
+        const scannable = deps.filter((d) => d.version !== null);
+        const ecosystems = [...new Set(scannable.map((d) => d.ecosystem))];
+        // Per-dependency caching and the rate limit are for network answers; a
+        // pinned source answers locally and must never seed the shared cache.
+        const network = this.source.network;
+        // Check cache for each dep individually
+        const uncached = [];
+        const cachedVulns = [];
+        for (const dep of scannable) {
+            const cacheKey = `osv:${dep.ecosystem}:${dep.name}:${dep.version}`;
+            const cached = network ? this.cache.get(cacheKey) : null;
+            if (cached !== null) {
+                cachedVulns.push(...cached.map((v) => restampDepContext(v, dep)));
+            }
+            else {
+                uncached.push(dep);
+            }
+        }
+        // Fetch uncached from OSV
+        let fetchedVulns = [];
+        let offline = false;
+        if (uncached.length > 0) {
+            if (network && !this.rateLimiter.canProceed("osv")) {
+                offline = true;
+            }
+            else {
+                try {
+                    fetchedVulns = await this.batchQuery(uncached);
+                }
+                catch {
+                    offline = true;
+                    // Try stale cache for uncached deps
+                    for (const dep of uncached) {
+                        if (!network)
+                            break;
+                        const cacheKey = `osv:${dep.ecosystem}:${dep.name}:${dep.version}`;
+                        const stale = this.cache.getStale(cacheKey);
+                        if (stale)
+                            cachedVulns.push(...stale.data.map((v) => restampDepContext(v, dep)));
+                    }
+                }
+            }
+        }
+        const allVulns = [...cachedVulns, ...fetchedVulns];
+        const vulnerablePackages = new Set(allVulns.map((v) => v.package));
+        const platformInactiveVulnerable = new Set(allVulns.filter((v) => !v.platformActive).map((v) => v.package)).size;
+        const bySeverity = { critical: 0, high: 0, medium: 0, low: 0, unknown: 0 };
+        for (const v of allVulns) {
+            bySeverity[v.severity]++;
+        }
+        return {
+            scannedAt: new Date().toISOString(),
+            projectPath,
+            ecosystemsScanned: ecosystems,
+            totalScanned: scannable.length,
+            totalVulnerable: vulnerablePackages.size,
+            platformInactiveVulnerable,
+            bySeverity,
+            vulnerabilities: allVulns,
+            cleanCount: offline ? 0 : scannable.length - vulnerablePackages.size,
+            scanDurationMs: Date.now() - start,
+            cached: uncached.length === 0,
+            offline,
+        };
+    }
+    async batchQuery(deps) {
+        // Phase 1 — enumerate advisory IDs per dep (OSV: the lightweight batch index).
+        const idsPerDep = await this.source.query(deps);
+        const matches = deps.map((dep, i) => ({ dep, ids: idsPerDep[i] ?? [] }));
+        // Phase 2 — the record behind each unique advisory, once.
+        const uniqueIds = [...new Set(matches.flatMap((m) => m.ids))];
+        const detailById = await this.source.details(uniqueIds);
+        // Phase 3 — map to entries and cache per-dep (empty results cached too, so
+        // clean deps are not re-queried; network answers only).
+        const results = [];
+        const rows = [];
+        for (const { dep, ids } of matches) {
+            // Drop advisories OSV has withdrawn/retracted — surfacing them is a false
+            // positive. Un-hydrated ids (detail fetch failed) are kept: we can't know,
+            // and dropping a real advisory is worse than keeping an un-enriched one.
+            const liveIds = ids.filter((id) => !detailById.get(id)?.withdrawn);
+            const depVulns = liveIds.map((id) => mapVulnerability(detailById.get(id) ?? { id }, dep));
+            rows.push([`osv:${dep.ecosystem}:${dep.name}:${dep.version}`, depVulns]);
+            results.push(...depVulns);
+        }
+        if (this.source.network)
+            this.cache.setMany(rows, "osv", OSV_CACHE_TTL);
+        return results;
+    }
+}
 /**
  * Overwrite the dep-context fields of a cached advisory entry with the CURRENT
  * resolution's context. The advisory facts (id, severity, summary, fix version)

package/dist/live/pinned-advisories.d.ts

@@ -0,0 +1,31 @@
+/**
+ * An advisory source that serves a fixed set of OSV records and decides
+ * membership itself, with no network.
+ *
+ * The server asks OSV.dev which advisories affect a version (OsvHttpSource,
+ * osv-scanner.ts). The 4DA conformance corpus pins every OSV record that names
+ * one of its packages, byte for byte as api.osv.dev served it, and its truth
+ * is OSV's own evaluation of each installed version. Scoring the engine
+ * against that corpus offline needs the same question answered locally: which
+ * pinned records affect this exact (ecosystem, name, version)? That is the
+ * job of osv-ranges.ts (spans and explicit version lists, ordered the
+ * ecosystem's way), so this also holds the local evaluator to OSV's answers.
+ *
+ * Withdrawn records are still returned by `query`: the scanner drops them
+ * after reading the record, exactly as it does with OSV's answers.
+ */
+import type { AdvisorySource } from "./osv-scanner.js";
+import type { OsvVulnerability, ResolvedDependency } from "./types.js";
+export declare class PinnedRecordsSource implements AdvisorySource {
+    readonly network = false;
+    private readonly byId;
+    private readonly byPackage;
+    constructor(records: Iterable<OsvVulnerability>);
+    /** Every `*.json` OSV record in a directory (the corpus's `osv/`). */
+    static fromDirectory(dir: string): PinnedRecordsSource;
+    get size(): number;
+    /** The ids of the pinned records that affect this exact version (withdrawn ones included). */
+    affecting(ecosystem: string, name: string, version: string): string[];
+    query(deps: ResolvedDependency[]): Promise<string[][]>;
+    details(ids: string[]): Promise<Map<string, OsvVulnerability>>;
+}

package/dist/live/pinned-advisories.js

@@ -0,0 +1,80 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * An advisory source that serves a fixed set of OSV records and decides
+ * membership itself, with no network.
+ *
+ * The server asks OSV.dev which advisories affect a version (OsvHttpSource,
+ * osv-scanner.ts). The 4DA conformance corpus pins every OSV record that names
+ * one of its packages, byte for byte as api.osv.dev served it, and its truth
+ * is OSV's own evaluation of each installed version. Scoring the engine
+ * against that corpus offline needs the same question answered locally: which
+ * pinned records affect this exact (ecosystem, name, version)? That is the
+ * job of osv-ranges.ts (spans and explicit version lists, ordered the
+ * ecosystem's way), so this also holds the local evaluator to OSV's answers.
+ *
+ * Withdrawn records are still returned by `query`: the scanner drops them
+ * after reading the record, exactly as it does with OSV's answers.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { advisoryAffects, collectAffectedSpans } from "./osv-ranges.js";
+import { samePackageName } from "./version-compare.js";
+/** The registry's identity for a package name, as an index key (samePackageName's rules). */
+function nameKey(ecosystem, name) {
+    if (ecosystem === "PyPI")
+        return name.toLowerCase().replace(/[-_.]+/g, "-");
+    if (ecosystem === "crates.io")
+        return name.toLowerCase().replace(/_/g, "-");
+    return name;
+}
+/** Explicitly listed versions for one package of one record. */
+function listedVersions(vuln, name, ecosystem) {
+    return (vuln.affected ?? [])
+        .filter((a) => a.package.ecosystem === ecosystem && samePackageName(a.package.name, name, ecosystem))
+        .flatMap((a) => a.versions ?? []);
+}
+export class PinnedRecordsSource {
+    network = false;
+    byId = new Map();
+    byPackage = new Map();
+    constructor(records) {
+        for (const record of records) {
+            this.byId.set(record.id, record);
+            const keys = new Set((record.affected ?? []).map((a) => `${a.package.ecosystem}\0${nameKey(a.package.ecosystem, a.package.name)}`));
+            for (const key of keys) {
+                const list = this.byPackage.get(key);
+                if (list)
+                    list.push(record);
+                else
+                    this.byPackage.set(key, [record]);
+            }
+        }
+    }
+    /** Every `*.json` OSV record in a directory (the corpus's `osv/`). */
+    static fromDirectory(dir) {
+        const files = fs.readdirSync(dir).filter((f) => f.endsWith(".json")).sort();
+        return new PinnedRecordsSource(files.map((f) => JSON.parse(fs.readFileSync(path.join(dir, f), "utf8"))));
+    }
+    get size() {
+        return this.byId.size;
+    }
+    /** The ids of the pinned records that affect this exact version (withdrawn ones included). */
+    affecting(ecosystem, name, version) {
+        const candidates = this.byPackage.get(`${ecosystem}\0${nameKey(ecosystem, name)}`) ?? [];
+        return candidates
+            .filter((vuln) => advisoryAffects({ id: vuln.id, spans: collectAffectedSpans(vuln.affected, name, ecosystem), versions: listedVersions(vuln, name, ecosystem) }, version, ecosystem))
+            .map((vuln) => vuln.id);
+    }
+    async query(deps) {
+        return deps.map((dep) => (dep.version === null ? [] : this.affecting(dep.ecosystem, dep.name, dep.version)));
+    }
+    async details(ids) {
+        const out = new Map();
+        for (const id of ids) {
+            const record = this.byId.get(id);
+            if (record)
+                out.set(id, record);
+        }
+        return out;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@4da/mcp-server",
-  "version": "6.2.1",
+  "version": "6.2.2",
   "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",