@4da/mcp-server 6.2.4 → 6.2.5

package/dist/live/advisory-groups.js

@@ -0,0 +1,131 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * One advisory, many records. OSV publishes the same issue as a GHSA record
+ * and as an ecosystem record (PYSEC, RUSTSEC, GO), each naming the other in
+ * `aliases`. Counting records counted one issue two or three times:
+ * - tokio 1.18.0 showed "6 advisories" for 3 (audit A9);
+ * - pygoat's django "96 known vulnerabilities" for 51 (readiness audit M1, 2026-10-16).
+ * Every count of advisories goes through here.
+ */
+import { isMaintenanceNotice } from "./maintenance.js";
+import { isMalware } from "./malware.js";
+const RANK = { unknown: 0, low: 1, medium: 2, high: 3, critical: 4 };
+/**
+ * Group the records of ONE installed copy by shared ids. The grouping is transitive: a record
+ * naming ids of two groups joins them.
+ */
+export function groupAdvisories(entries) {
+    let groups = [];
+    for (const v of entries ?? []) {
+        const ids = [v.vulnId, ...(v.aliases ?? [])];
+        const hit = groups.filter((g) => ids.some((id) => g.ids.has(id)));
+        const merged = { ids: new Set(ids), best: v, members: [v] };
+        for (const g of hit) {
+            for (const id of g.ids)
+                merged.ids.add(id);
+            merged.members.push(...g.members);
+            if ((RANK[g.best.severity] ?? 0) > (RANK[merged.best.severity] ?? 0))
+                merged.best = g.best;
+        }
+        groups = [...groups.filter((g) => !hit.includes(g)), merged];
+    }
+    return groups;
+}
+/**
+ * THE grade of one alias group, shared with the 4DA app (`fourda_depengine::severity`, vectors
+ * severity.jsonl sv-001..sv-019): the MOST severe OWN grade among the group's records; only when no
+ * record has one, the highest grade among their GHSA aliases that can be read (`aliasGrades`, null =
+ * held but ungraded), the smallest id on a tie. An unmaintained-package notice is never graded
+ * from an alias.
+ */
+export function gradeGroup(records, aliasGrades) {
+    let own = null;
+    for (const r of records) {
+        if (r.own === "unknown")
+            continue;
+        if (!own || RANK[r.own] > RANK[own.grade])
+            own = { id: r.id, grade: r.own };
+    }
+    let severity = null;
+    let inheritedFrom = null;
+    if (own) {
+        severity = own.grade;
+    }
+    else {
+        const ids = new Set(records.map((r) => r.id));
+        const ghsas = [...new Set(records.filter((r) => !r.maintenance).flatMap((r) => r.aliases.filter((a) => /^GHSA-/i.test(a) && !ids.has(a))))].sort();
+        let best = null;
+        for (const id of ghsas) {
+            const g = aliasGrades.get(id);
+            if (!g || g === "unknown")
+                continue;
+            if (!best || RANK[g] > RANK[best.grade])
+                best = { id, grade: g };
+        }
+        if (best) {
+            severity = best.grade;
+            inheritedFrom = best.id;
+        }
+    }
+    // A malicious-package record (malware.ts) is critical (the 4DA lead, 2026-10-18; sv-010 read high).
+    const malicious = records.some((r) => isMalware(r.id, r.aliases, r.cweIds ?? [], r.summary ?? ""));
+    const urgency = malicious
+        ? "critical"
+        : severity === "critical" || severity === "high" || severity === "medium"
+            ? severity
+            : severity === "low"
+                ? "watch"
+                : records.every((r) => r.maintenance)
+                    ? "watch"
+                    : "medium";
+    return { severity, inheritedFrom, ownFrom: own?.id ?? null, urgency };
+}
+/**
+ * One severity per advisory, in every tool (the rule shared with the 4DA app, gradeGroup): within
+ * one alias group of one installed copy, every record carries the group's grade. vulnerability_scan
+ * kept the "richest" record's grade while dependency_check, dependency_health and upgrade_planner
+ * kept the most severe, so CVE-2026-4277 (GHSA-pwjp-ccjc-ghwg rated LOW, PYSEC-2026-52 CVSS 9.8) was
+ * low in one tool and critical in the others (final release audit of 6.2.5, 2026-10-18). A record
+ * that does not carry the grade itself names where it came from (`severityFrom`: the group record,
+ * or the GHSA alias of an inherited grade). A grade a record took from its alias
+ * (osv-scanner.ts rateFromAliases) never overrides an own grade in its group.
+ */
+export function gradeAliasGroups(entries) {
+    const byCopy = new Map();
+    for (const v of entries) {
+        const key = `${v.ecosystem}\u0000${v.package}\u0000${v.currentVersion}\u0000${v.installDriftOf ?? ""}`;
+        byCopy.set(key, [...(byCopy.get(key) ?? []), v]);
+    }
+    const regraded = new Map();
+    for (const copy of byCopy.values()) {
+        for (const group of groupAdvisories(copy)) {
+            if (group.members.length < 2)
+                continue;
+            const inherited = (m) => Boolean(m.severityFrom) && m.severityFrom !== m.vulnId;
+            const aliasGrades = new Map();
+            for (const m of group.members)
+                if (inherited(m))
+                    aliasGrades.set(m.severityFrom, m.severity);
+            const grade = gradeGroup(group.members.map((m) => ({ id: m.vulnId, own: inherited(m) ? "unknown" : m.severity, aliases: [...m.aliases, ...(inherited(m) ? [m.severityFrom] : [])], maintenance: isMaintenanceNotice(m) })), aliasGrades);
+            const severity = grade.severity ?? "unknown";
+            const from = grade.inheritedFrom ?? grade.ownFrom;
+            for (const m of group.members) {
+                if (isMaintenanceNotice(m) && grade.inheritedFrom)
+                    continue;
+                if (m.severity === severity && (!inherited(m) || m.severityFrom === from))
+                    continue;
+                const next = { ...m, severity };
+                if (from && from !== m.vulnId)
+                    next.severityFrom = from;
+                else
+                    delete next.severityFrom;
+                regraded.set(m, next);
+            }
+        }
+    }
+    return regraded.size === 0 ? [...entries] : entries.map((e) => regraded.get(e) ?? e);
+}
+/** Distinct advisories among the records of one installed copy. */
+export function distinctAdvisoryCount(entries) {
+    return groupAdvisories(entries).length;
+}

package/dist/live/cache.js

@@ -37,6 +37,14 @@ export function closeServerCacheDb() {
         serverCache.close();
     serverCache = null;
 }
+/**
+ * A row fetched "in the future" was written under a clock that was ahead, or the clock has
+ * since gone back (an RTC reset). Its expires_at came from that clock too, so it could keep a
+ * year-old "no advisories" answer live: scan 0 vulnerable, dependency_check proceed,
+ * what_should_i_know safe_to_delegate (audit 6.2.5 B-3). Such a row is never an answer, fresh or
+ * stale, and is purged at start. Five minutes of skew between processes is tolerated.
+ */
+const SANE_FETCHED_AT = "fetched_at <= datetime('now', '+5 minutes')";
 /**
  * Registry, OSV and changelog responses with a TTL.
  *
@@ -82,7 +90,7 @@ export class LiveCache {
             const hit = this.memory.get(key);
             return hit && this.live(hit) ? JSON.parse(hit.data) : null;
         }
-        const row = this.db.prepare("SELECT data FROM live_cache WHERE cache_key = ? AND expires_at > datetime('now')").get(key);
+        const row = this.db.prepare(`SELECT data FROM live_cache WHERE cache_key = ? AND expires_at > datetime('now') AND ${SANE_FETCHED_AT}`).get(key);
         if (!row)
             return null;
         try {
@@ -97,7 +105,7 @@ export class LiveCache {
             const hit = this.memory.get(key);
             return hit ? { data: JSON.parse(hit.data), fetchedAt: hit.fetched_at } : null;
         }
-        const row = this.db.prepare("SELECT data, fetched_at FROM live_cache WHERE cache_key = ?").get(key);
+        const row = this.db.prepare(`SELECT data, fetched_at FROM live_cache WHERE cache_key = ? AND ${SANE_FETCHED_AT}`).get(key);
         if (!row)
             return null;
         try {
@@ -150,7 +158,7 @@ export class LiveCache {
                     purged++;
             return purged;
         }
-        const result = this.db.prepare("DELETE FROM live_cache WHERE expires_at <= datetime('now')").run();
+        const result = this.db.prepare(`DELETE FROM live_cache WHERE expires_at <= datetime('now') OR NOT (${SANE_FETCHED_AT})`).run();
         return result.changes;
     }
     invalidateSource(source) {

package/dist/live/cargo-platform.d.ts

@@ -22,6 +22,12 @@ export declare function activeCratesForHost(dir: string): Set<string> | null;
  * untrusted input. `CARGO_TARGET_DIR` points at the same scratch directory so
  * cargo's metadata writes never land in the user's tree either.
  *
+ * The scratch directory lives in the server's per-user data directory, not
+ * the system temp directory. On a shared machine `/tmp` is writable by every
+ * user, so a `/tmp/.cargo/config.toml` or a pre-created
+ * `/tmp/4da-mcp-cargo-resolve/.cargo/config.toml` planted by another account
+ * could set `build.rustc-wrapper` and run code as this user (audit 6.2.5 C-2).
+ *
  * Exported for tests.
  */
 export declare function cargoTreeInvocation(dir: string): {

package/dist/live/cargo-platform.js

@@ -42,8 +42,8 @@
  */
 import { execFileSync } from "node:child_process";
 import * as fs from "node:fs";
-import * as os from "node:os";
 import * as path from "node:path";
+import { serverDataDir } from "../db.js";
 import { fileSignature } from "./file-signature.js";
 /** Rust target triple for the current host, or null for a platform we do not map. */
 export function hostTriple() {
@@ -133,10 +133,16 @@ function computeActiveCrates(dir) {
  * untrusted input. `CARGO_TARGET_DIR` points at the same scratch directory so
  * cargo's metadata writes never land in the user's tree either.
  *
+ * The scratch directory lives in the server's per-user data directory, not
+ * the system temp directory. On a shared machine `/tmp` is writable by every
+ * user, so a `/tmp/.cargo/config.toml` or a pre-created
+ * `/tmp/4da-mcp-cargo-resolve/.cargo/config.toml` planted by another account
+ * could set `build.rustc-wrapper` and run code as this user (audit 6.2.5 C-2).
+ *
  * Exported for tests.
  */
 export function cargoTreeInvocation(dir) {
-    const scratch = path.join(os.tmpdir(), "4da-mcp-cargo-resolve");
+    const scratch = path.join(serverDataDir(), "cargo-resolve");
     return {
         args: [
             "tree",

package/dist/live/changelog.js

@@ -107,7 +107,36 @@ export function parseVersionHeading(raw) {
         return null;
     return { version, date: extractDate(rest) };
 }
-const ATX = /^(#{1,6})\s+(.*?)\s*#*\s*$/;
+/**
+ * An ATX heading `## text ##` as [level, text], parsed by hand in linear time.
+ * The regex it replaces (`/^(#{1,6})\s+(.*?)\s*#*\s*$/`) was cubic on interior
+ * whitespace: a 1,000-space heading in a package's CHANGELOG took over 20 s on
+ * the event loop (audit 2026-10-12, B-10). Same result otherwise ("C#" reads "C").
+ */
+function parseAtx(line) {
+    const open = /^#{1,6}/.exec(line);
+    if (!open)
+        return null;
+    const level = open[0].length;
+    const after = line.slice(level);
+    const body = after.trimStart();
+    if (body.length === after.length)
+        return null; // "#tag" or "#######": not a heading
+    let end = body.length;
+    while (end > 0 && /\s/.test(body[end - 1]))
+        end--;
+    while (end > 0 && body[end - 1] === "#")
+        end--;
+    while (end > 0 && /\s/.test(body[end - 1]))
+        end--;
+    return [level, body.slice(0, end)];
+}
+/**
+ * Lines longer than this are cut before the line-shape regexes run, so every
+ * one of them works on bounded input and a hostile line costs milliseconds.
+ * No real heading, label or entry comes near it.
+ */
+const MAX_LINE = 4096;
 /**
  * A setext / reStructuredText underline. `=` and `-` at any length (Markdown);
  * the other RST adornments need three, so a stray `**` is not a heading rule.
@@ -279,7 +308,10 @@ function adornmentLevel(ch) {
 }
 /** Parse a changelog into version sections, in document order (usually newest first). */
 export function parseChangelog(text) {
-    const lines = text.replace(/\r\n?/g, "\n").split("\n");
+    const lines = text
+        .replace(/\r\n?/g, "\n")
+        .split("\n")
+        .map((l) => (l.length > MAX_LINE ? l.slice(0, MAX_LINE) : l));
     const state = {
         sections: [],
         current: null,
@@ -318,14 +350,14 @@ export function parseChangelog(text) {
         }
         if (LINK_DEF.test(line))
             continue;
-        const atx = ATX.exec(line);
+        const atx = parseAtx(line);
         if (atx) {
-            const heading = parseVersionHeading(atx[2]);
-            const level = atx[1].length;
+            const [level, text] = atx;
+            const heading = parseVersionHeading(text);
             if (heading)
                 openSection(state, heading, level);
             else
-                subHeading(state, atx[2], level);
+                subHeading(state, text, level);
             continue;
         }
         const next = lines[i + 1];

package/dist/live/dependency-set.d.ts

@@ -10,4 +10,12 @@ import type { ResolvedDependency, VulnerabilityScanResult } from "./types.js";
  */
 export declare function commonPathRoot(dirs: string[]): string | null;
 export declare function dedupeDependencies(deps: ResolvedDependency[]): ResolvedDependency[];
-export declare function emptyVulnResult(projectPath: string, offline: boolean): VulnerabilityScanResult;
+/**
+ * A scan with no findings. `unchecked` dependencies (offline: none of them
+ * could be asked) are counted in `totalScanned` and reported as unchecked,
+ * never as clean.
+ */
+export declare function emptyVulnResult(projectPath: string, offline: boolean, unchecked?: {
+    count: number;
+    reason: string;
+} | null): VulnerabilityScanResult;

package/dist/live/dependency-set.js

@@ -77,12 +77,17 @@ function mergeInstallContext(existing, dep) {
         existing.installedVersion = dep.installedVersion;
     }
 }
-export function emptyVulnResult(projectPath, offline) {
+/**
+ * A scan with no findings. `unchecked` dependencies (offline: none of them
+ * could be asked) are counted in `totalScanned` and reported as unchecked,
+ * never as clean.
+ */
+export function emptyVulnResult(projectPath, offline, unchecked = null) {
     return {
         scannedAt: new Date().toISOString(),
         projectPath,
         ecosystemsScanned: [],
-        totalScanned: 0,
+        totalScanned: unchecked?.count ?? 0,
         totalVulnerable: 0,
         platformInactiveVulnerable: 0,
         bySeverity: { critical: 0, high: 0, medium: 0, low: 0, unknown: 0 },
@@ -91,5 +96,8 @@ export function emptyVulnResult(projectPath, offline) {
         scanDurationMs: 0,
         cached: false,
         offline,
+        unchecked: unchecked?.count ?? 0,
+        uncheckedReason: unchecked?.reason ?? null,
+        staleAnswers: 0,
     };
 }

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

@@ -26,7 +26,38 @@ import type { LiveCache } from "./cache.js";
 import type { RateLimiter } from "./rate-limiter.js";
 import { type AdvisoryRanges, type CleanTarget } from "./osv-ranges.js";
 import { type LockfileFormat } from "./lockfile-parents.js";
+import { type AdvisoryQuery, type HeldDependency } from "./held-dependencies.js";
 import type { OsvEcosystem } from "./types.js";
+/** What a registry says about one package's releases, for fix targets and parent advice. */
+export interface PackageReleaseFacts {
+    /** Published, installable versions: every release except the `withdrawn` ones. */
+    versions: string[];
+    /**
+     * Releases the registry withdrew, never a fix target (withdrawn-releases.ts, the 4DA app's
+     * rule): yanked (crates.io; PyPI: every file), and npm `deprecated` only where a later,
+     * non-deprecated stable release exists on the same caret line and `latest` is not deprecated.
+     */
+    withdrawn: string[];
+    /** Per withdrawn release, the registry's words ("4.18.0 is deprecated on npm ("Bad release...")"). */
+    withdrawnWhy: Record<string, string>;
+    /** The registry's latest release (npm `latest` tag; crates.io the highest non-yanked), or null. */
+    latest: string | null;
+    /** The package-level deprecation of the newest release (npm), or null. */
+    deprecatedLatest: string | null;
+    /**
+     * npm: releases that carry a `deprecated` message the withdrawal rule does NOT withdraw (a
+     * notice on a whole line, such as glob's "Old versions of glob are not supported"), with the
+     * message. Still candidates; a tool that offers one says it is deprecated (final release audit
+     * of 6.2.5: the plan targeted glob 10.5.0 while dependency_check said review on it).
+     */
+    lineNotices?: Record<string, string>;
+    /**
+     * npm: per release, the dependencies it holds (exact pins and narrow ranges, held-dependencies.ts):
+     * name -> spec. A release that holds none is absent. Its advisories come with the release
+     * (audit 6.2.5 D-4: express 4.20.0 exact-pins qs 6.11.0).
+     */
+    heldSpecs?: Record<string, Record<string, string>>;
+}
 export interface CrateDepReq {
     req: string;
     optional: boolean;
@@ -34,12 +65,20 @@ export interface CrateDepReq {
 export interface CratesSparse {
     /** Versions not yanked. */
     versions: string[];
+    /** Yanked versions. */
+    yanked?: string[];
     /** version -> dependency crate name -> requirements (one per target/kind entry; dev-dependencies left out). */
     reqs: Record<string, Record<string, CrateDepReq[]>>;
 }
+/** Per published release of a parent: its requirements on one package, and whether it declares it only as a peer. */
+export type RequirementHistory = Record<string, {
+    reqs: string[];
+    peer: boolean;
+}>;
 export declare class FixPathSources {
     private cache;
     private rateLimiter;
+    private npmDocs;
     constructor(cache: LiveCache, rateLimiter: RateLimiter);
     /** Every non-withdrawn OSV advisory for a package, as ranges; null when OSV could not be read. */
     packageAdvisories(ecosystem: OsvEcosystem, name: string): Promise<AdvisoryRanges[] | null>;
@@ -51,15 +90,138 @@ export declare class FixPathSources {
      * records none). Null when unknown; [] when the parent declares none.
      */
     parentRequirements(ecosystem: OsvEcosystem, parent: string, parentVersion: string, dep: string): Promise<string[] | null>;
-    private npmVersions;
+    /**
+     * What every published release of `parent` requires of `dep`, from the
+     * registry: version -> requirements (`reqs: []` when that release does not
+     * depend on it). npm reads dependencies and optionalDependencies of the
+     * abbreviated document (as `parentRequirements`), and, when neither holds
+     * it, peerDependencies, flagged `peer`: npm 7+ installs a missing peer, so
+     * moving a package into peerDependencies is not dropping it (readiness
+     * review 2026-10-17, finding 10). crates.io: the sparse index. Null when
+     * unknown or unsupported. Used to find the smallest parent release that
+     * admits a clean version (audit H1).
+     */
+    requirementHistory(ecosystem: OsvEcosystem, parent: string, dep: string): Promise<RequirementHistory | null>;
+    /**
+     * One npm abbreviated document per package, shared by the release facts and the requirement
+     * history of a plan (a parent's document was downloaded twice: NodeGoat's mongodb, ~600
+     * releases). Kept in memory for a short while, at most a few at a time; a failure is not kept.
+     */
+    private npmDocument;
+    /**
+     * Release facts for a parent or a fix target: what is installable, what is
+     * deprecated or yanked, and the latest release. Null when the registry
+     * could not be read or is not supported.
+     */
+    releaseFacts(ecosystem: OsvEcosystem, name: string): Promise<PackageReleaseFacts | null>;
+    /**
+     * npm's abbreviated document: versions without READMEs, with each
+     * version's `deprecated` message. A withdrawn release is never offered as a
+     * fix target: lodash 4.18.0 ("Bad release. Please use lodash@4.17.21
+     * instead.") was recommended by vulnerability_scan (audit B-8, 2026-10-12).
+     * Withdrawn means the app's rule (withdrawn-releases.ts): a deprecated
+     * release with a later clean one on its caret line. A whole-major notice
+     * (glob, tar 6.x) withdraws nothing, or glob 10.4.5 is sent to 12.0.0.
+     */
+    private npmFacts;
     /** A crate's sparse-index record: versions and per-version dependency requirements. */
     cratesSparse(name: string): Promise<CratesSparse | null>;
-    private pypiVersions;
+    /**
+     * PyPI's JSON API: every release with files; one whose every file is yanked is withdrawn
+     * (PEP 592, the app's `parse_pypi`). A release with no files cannot be installed and is not listed.
+     */
+    private pypiFacts;
     private goVersions;
 }
-export type FixTargetResult = CleanTarget;
-/** The minimal clean target for one installed copy, or null when the advisories could not be read. */
-export declare function cleanFixTarget(sources: FixPathSources, ecosystem: OsvEcosystem, name: string, perAdvisoryFixes: string[]): Promise<FixTargetResult | null>;
+export type FixTargetResult = CleanTarget & {
+    /** No target and a malicious landing: "<pkg> is flagged malicious (<id>): remove or replace <pkg>" (#994 review). */
+    landingNote?: string;
+    /**
+     * True when the package's advisories could not be read (OSV /v1/query
+     * failed) but the registry could: `target` is then only the smallest
+     * installable release at or above the highest per-advisory fix, which is
+     * deprecated, yanked or unpublished (`floorWithdrawn` says which). It is
+     * NOT checked against the package's other advisories; callers report the
+     * fix as checked against the installed version's advisories only.
+     */
+    advisoriesUnread?: boolean;
+    /**
+     * True when the package's registry could not be read: withdrawn (yanked, deprecated) releases
+     * were not checked, and the target comes from the advisory data alone, as before FX-H5.
+     */
+    registryUnread?: boolean;
+    /** The registry's words for each `withheld` release and each withdrawn line fix. */
+    withheldWhy?: Record<string, string>;
+    /**
+     * Per-advisory fixes the registry withdrew, keyed by that fix: the release to take instead
+     * (`fix: null` when none past it is known) and the withdrawn ones passed (installableFix).
+     */
+    lineFixes?: Record<string, {
+        fix: string | null;
+        withheld: string[];
+    }>;
+    /**
+     * npm: the target carries a deprecation notice the withdrawal rule keeps (one on its whole line,
+     * no later release on the line free of it: glob 10.5.0, "Old versions of glob are not
+     * supported"). It stays the target, the smallest fix without a major upgrade, and every tool
+     * says it is deprecated, as dependency_check does with `review` (final release audit 7f).
+     */
+    targetNotice?: string;
+    /** The package's malware advisories (#981 rule a): a release one affects is never the target. */
+    malware?: string[];
+    /**
+     * npm (audit 6.2.5 D-4): the release the package's own advisories pointed at, passed because a
+     * dependency it holds (an exact pin, or a narrow range whose newest release is affected) brings
+     * an advisory in; `heldPast` names each release passed and why. `target` is then the smallest
+     * later release on that line whose own advisories AND held dependencies are clean.
+     */
+    heldFrom?: string;
+    heldPast?: Array<{
+        version: string;
+        affected: HeldDependency[];
+    }>;
+    /** The target holds an affected dependency and no later release searched (`searched`) clears it: not a clean fix. */
+    heldBlocked?: {
+        affected: HeldDependency[];
+        searched: string[];
+    };
+    /** Whether the target's held dependencies are affected could not be checked, and why: not a clean fix either. */
+    heldUnchecked?: string;
+};
+/**
+ * Whether a checked target may be reported as checked against every advisory (fix_checked
+ * `all_advisories`): its own advisories were read, and, for npm, what it installs at a fixed
+ * version was judged clean (audit 6.2.5 D-4).
+ */
+export declare function targetCheckedAll(clean: FixTargetResult): boolean;
+/** The words for a target's held dependencies (FixTargetResult.heldFrom / heldBlocked / heldUnchecked), or null when there is nothing to say. */
+export declare function heldNote(clean: FixTargetResult): string | null;
+/**
+ * The minimal clean target for one installed copy, or null when neither the
+ * advisories nor anything that changes the answer could be read.
+ *
+ * Advisories unreadable, registry readable (audit H5: OSV /v1/query down):
+ * a deprecated or yanked release is still never the target. lodash 4.17.20
+ * went to 4.18.0 ("Bad release") because the whole check was skipped; the
+ * registry facts alone move it to 4.18.1, flagged `advisoriesUnread`.
+ *
+ * With no per-advisory fix at all (advisories that give only `last_affected`,
+ * audit A6), and the installed version known, the registry is asked for the
+ * first published release above the installed one that no known advisory
+ * affects: a fix candidate the advisories never named, flagged
+ * `noAdvisoryFix`, instead of "no fix".
+ */
+export declare function cleanFixTarget(sources: FixPathSources, ecosystem: OsvEcosystem, name: string, perAdvisoryFixes: string[], installed?: string | null): Promise<FixTargetResult | null>;
+/** #981 (b): an advisory whose ranges cannot be read leaves the release unknown, never skipped silently. */
+export declare function unreadableText(ids: string[]): string;
+/** The 4DA lead's rule (2026-10-18): no release is offered that brings in an advisory the installed version does not have. */
+export declare function introducesText(ids: string[]): string;
+/** #981 round 3: an installed copy a malicious advisory affects names no release; the advice is to remove or replace it. */
+export declare function malwareText(name: string, ids: string[]): string;
+/** The words for a target that carries a line-wide deprecation notice (FixTargetResult.targetNotice). */
+export declare function lineNoticeText(version: string, message: string): string;
+/** `withheldNote` for a checked target: the withdrawn releases passed, in plain words; null when none. */
+export declare function withheldText(clean: FixTargetResult, ecosystem: string): string | null;
 /**
  * Verified targets for many installed copies at once, within a time budget:
  * the copies that could not be checked in time (or offline) are simply
@@ -70,9 +232,27 @@ export declare function verifyFixTargets(sources: FixPathSources | null, items:
     ecosystem: OsvEcosystem;
     name: string;
     fixes: string[];
-}>, budgetMs: number, concurrency?: number): Promise<Map<string, CleanTarget>>;
-/** 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;
+    installed?: string;
+}>, budgetMs: number, concurrency?: number, options?: {
+    heldQuery?: AdvisoryQuery;
+}): Promise<Map<string, FixTargetResult>>;
+/** Said whenever the registry could not be read: withdrawn releases are then not ruled out, never silently. */
+export declare const REGISTRY_UNREAD_NOTE = "the registry could not be read, so whether it yanked or deprecated this release was not checked";
+/**
+ * One clause for a target that is not the highest per-advisory fix, or null when it is.
+ * Withdrawn releases passed on the way are named in the registry's own words (FX-H5).
+ */
+export declare function targetNote(clean: FixTargetResult, ecosystem?: string): string | null;
+/**
+ * A finding's own fix as the registry still offers it (the app's `installable_fix`): the
+ * advisory's fixed version, or, when the registry withdrew it, the release to take instead
+ * (null: none past it is known), with the withdrawn ones and the plain-words note.
+ */
+export declare function rowFix(fixed: string | null, clean: FixTargetResult | undefined, ecosystem: string): {
+    fixed: string | null;
+    withheld: string[];
+    note: string | null;
+};
 export interface RefreshVerdict {
     /** True when a lockfile refresh reaches a clean version (read, or inferred: see `inferred`). */
     refreshFixes: boolean;
@@ -86,11 +266,15 @@ export interface RefreshVerdict {
     format: LockfileFormat;
     /** 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). */
+    /**
+     * Parent requirements that do NOT admit a clean version (why it is waiting on upstream).
+     * `bundled`: the copy ships inside that parent's tarball, so neither a refresh nor an override reaches it (audit E8).
+     */
     blocking: Array<{
         parent: string;
         parentVersion: string | null;
         requirement: string;
+        bundled?: boolean;
     }>;
     /** The version a refresh resolves to, when the registry's version list was read. */
     resolvesTo: string | null;
@@ -108,6 +292,70 @@ export interface RefreshVerdict {
  * 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;
+/**
+ * Whether an override (npm `overrides`, pnpm `pnpm.overrides`, yarn `resolutions`) can reach the copy
+ * these blocking parents hold: never when one of them ships it bundled (rule vectors rv-066..rv-068).
+ */
+export declare function overrideReaches(blocking: Array<{
+    bundled?: boolean;
+}>): boolean;
+/**
+ * How a DIRECT dependency moves to its fix target, worded for the tool and the manifest that
+ * declares it: a port of the 4DA app's `osv/direct_upgrade.rs` (rule vectors fc-028..fc-053),
+ * read from the declaring project's own manifest. A command is named only where it was run
+ * against the tool (2026-10-15/16: npm 10.9.2, pnpm 10.34.6, yarn 1.22.22, yarn 4.9.1, cargo
+ * 1.95, go 1.24) and moved the dependency while keeping it as declared. Plain `npm install x@v`
+ * wrote `^v` over an exact pin and over `~` (readiness review 2026-10-17, finding 4).
+ *
+ * Null, and the plan keeps its plain "bump it where it is declared", for anything this cannot
+ * read with certainty: a dependency declared in two sections; a declared spec that does not
+ * admit the installed copy; `>=`, `||`, x-range, tag, git, `workspace:` or alias specs; a git,
+ * path or alternate-registry crate; a yarn workspace member (`yarn up` is project-wide); a Go
+ * `replace`; hashed or compiled (pip-compile, uv) requirements; bun or an unknown tool.
+ */
+export type DirectFix = {
+    command: string;
+    refresh?: false;
+}
+/**
+ * The declaration ALREADY admits the target (navcal: sharp, next and vite under `^`): the minimal
+ * advice is the tool's in-range lockfile refresh, which leaves the manifest untouched, not a bump
+ * of the declaration (the 4DA app's DirectFix::Refresh). Each was run on a project declaring
+ * `ms ^2.1.1` locked at 2.1.1 (2026-10-18): it moved the lock to 2.1.3 and left package.json
+ * unchanged; plain `pnpm update ms` rewrote `^2.1.1` to `^2.1.3`, hence `--no-save`. Cargo:
+ * `itoa = "1.0.5"` locked 1.0.11 with Cargo.toml unchanged. Any readable range qualifies,
+ * `>=` and `||` included: no operator needs carrying.
+ */
+ | {
+    command: string;
+    refresh: true;
+} | {
+    instruction: string;
+};
+type NpmManager = "npm" | "pnpm" | "yarn1" | "yarn-berry";
+/** The spec `name` is declared with, when exactly one of dependencies / devDependencies / optionalDependencies holds it. */
+export declare function npmDeclared(packageJson: string, name: string): string | null;
+/** The command that moves a declared npm-family dependency, keeping its operator (quoted: `^` is cmd.exe's escape). */
+export declare function npmDirectCommand(manager: NpmManager, declared: string, name: string, target: string): string | null;
+interface CargoDecl {
+    kind: "normal" | "dev" | "build";
+    target: string | null;
+    key: string;
+    req: string | null;
+    workspace: boolean;
+    otherSource: boolean;
+}
+/** Every declaration of `crate` in a Cargo.toml (by crate name, so a renamed dependency is found through `package = ...`). */
+export declare function cargoDeclarations(manifest: string, crate: string): CargoDecl[];
+/** `go get <module>@v<target>` when go.mod requires the module directly at `installed` and no `replace` points it elsewhere. */
+export declare function goDirectCommand(goMod: string, module: string, installed: string, target: string): string | null;
+/** The edit of the requirements line that pins the package with `==` at `installed` (markers, extras kept). */
+export declare function pypiDirectInstruction(requirements: string, file: string, name: string, installed: string, target: string): string | null;
+/**
+ * The fix for `name` at `installed`, declared in the project at `projectDir`, read from its own
+ * manifest; null when it cannot be named with certainty (see DirectFix).
+ */
+export declare function directFix(projectDir: string, ecosystem: string, name: string, installed: string, target: string): DirectFix | 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. */
@@ -140,3 +388,4 @@ export declare function refreshVerdict(sources: FixPathSources, ecosystem: OsvEc
  * at its newest matching version.
  */
 export declare function cargoPrecisePrerequisites(sources: FixPathSources, lockContent: string, name: string, installed: string, target: string): Promise<string[] | null>;
+export {};