@4da/mcp-server 5.0.4 → 6.0.0

package/dist/tools/dependency-check-signals.js

@@ -0,0 +1,264 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * dependency_check signal evaluation — pure functions, no I/O.
+ *
+ * Each signal states a fact with its evidence and the verdict that fact
+ * implies on its own (`effect`). The item verdict is the strongest effect by
+ * a fixed precedence. `unknown` sits above `wait`/`proceed` and below
+ * `review`/`avoid`: a concrete negative finding stays actionable even when
+ * another source was unreachable, but a missing source never lets the
+ * verdict fall through to `proceed`.
+ */
+import { comparePrecedence, parseSemverPrecedence } from "../live/semver-precedence.js";
+/** Verdict precedence, strongest first. */
+const PRECEDENCE = ["avoid", "review", "unknown", "wait", "proceed"];
+export const WAIT_DAYS = 3;
+export const NEW_DEP_MIN_AGE_DAYS = 30;
+const DAY_MS = 86_400_000;
+/** The release `to` is judged against: the installed `from`, else the previous release on `to`'s line. */
+export function selectBaseline(index, item) {
+    if (item.from) {
+        const rec = index.releases[item.from] ?? null;
+        return {
+            record: rec,
+            kind: "from",
+            note: rec ? `installed ${item.from}` : `installed version ${item.from} is not listed on the registry`,
+        };
+    }
+    const target = parseSemverPrecedence(item.to);
+    if (!target)
+        return { record: null, kind: "previous_on_line", note: "target version is not readable semver" };
+    let best = null;
+    for (const rec of Object.values(index.releases)) {
+        if (rec.withdrawn)
+            continue;
+        const p = parseSemverPrecedence(rec.version);
+        if (!p || !sameLine(p, target) || comparePrecedence(p, target) >= 0)
+            continue;
+        if (p.prerelease.length > 0 && target.prerelease.length === 0)
+            continue;
+        if (!best || comparePrecedence(p, best.p) > 0)
+            best = { rec, p };
+    }
+    return best
+        ? { record: best.rec, kind: "previous_on_line", note: `previous release on the same line, ${best.rec.version}` }
+        : { record: null, kind: "previous_on_line", note: "first release on its line; nothing earlier to compare" };
+}
+/** Same compatibility line: same major, or same 0.minor below 1.0. */
+function sameLine(a, b) {
+    return a.major === b.major && (a.major !== 0 || a.minor === b.minor);
+}
+/** Runtime dependency names in `to` that the baseline did not have; null when either list is unknown. */
+export function introducedDependencies(to, base) {
+    if (!to.dependencies || !base?.dependencies)
+        return null;
+    const before = new Set(base.dependencies);
+    return to.dependencies.filter((d) => !before.has(d)).sort();
+}
+export function advisoriesSignal(item, facts) {
+    if (!facts.available) {
+        return { id: "advisories", value: null, evidence: `OSV.dev could not be reached: ${facts.detail}`, effect: "unknown" };
+    }
+    const fromIds = new Set(facts.from.map((a) => a.id));
+    const toIds = new Set(facts.to.map((a) => a.id));
+    const fixed = facts.from.filter((a) => !toIds.has(a.id) && !a.maintenance);
+    const value = { affecting_to: facts.to.map((a) => a.id), fixed_by_this_change: fixed.map((a) => a.id) };
+    const fixedNote = fixed.length > 0 ? ` This change fixes ${list(fixed)} affecting ${item.from}.` : "";
+    const serious = facts.to.filter((a) => !a.maintenance && (a.severity === "critical" || a.severity === "high"));
+    if (serious.length > 0) {
+        return { id: "advisories", value, effect: "avoid", evidence: `${item.to} is affected by ${list(serious)}.${fixedNote}` };
+    }
+    const other = facts.to.filter((a) => !a.maintenance);
+    const newNotices = facts.to.filter((a) => a.maintenance && !fromIds.has(a.id));
+    if (other.length > 0 || newNotices.length > 0) {
+        return {
+            id: "advisories",
+            value,
+            effect: "review",
+            evidence: `${item.to} is affected by ${list([...other, ...newNotices])}.${fixedNote}`,
+        };
+    }
+    // Only maintenance notices that `from` already carries can remain here.
+    const carried = facts.to.length > 0 ? ` (maintenance notice${facts.to.length > 1 ? "s" : ""} ${facts.to.map((a) => a.id).join(", ")} already apply to ${item.from})` : "";
+    return {
+        id: "advisories",
+        value,
+        effect: "proceed",
+        evidence: `No known advisory affects ${item.to}${carried}.${fixedNote}`,
+    };
+}
+function fmt(a) {
+    return `${a.id} (${a.maintenance ? "unmaintained notice" : a.severity})`;
+}
+/** At most three named in prose; the full id list is in the signal's `value`. */
+function list(advisories) {
+    const shown = advisories.slice(0, 3).map(fmt).join(", ");
+    return advisories.length > 3 ? `${shown} and ${advisories.length - 3} more` : shown;
+}
+export function releaseAgeSignal(item, to, advisories, now) {
+    if (!to.publishedAt) {
+        return { id: "release_age", value: null, evidence: `The registry gives no publish time for ${item.to}.`, effect: "unknown" };
+    }
+    const days = (now.getTime() - Date.parse(to.publishedAt)) / DAY_MS;
+    const value = { days: Math.round(days * 10) / 10, published_at: to.publishedAt };
+    const ageText = `${item.to} was published ${value.days} day${value.days === 1 ? "" : "s"} ago (${to.publishedAt})`;
+    if (days >= WAIT_DAYS) {
+        return { id: "release_age", value, evidence: `${ageText}.`, effect: "proceed" };
+    }
+    const fixed = advisories.value?.fixed_by_this_change ?? [];
+    if (fixed.length > 0) {
+        return {
+            id: "release_age",
+            value,
+            effect: "proceed",
+            evidence: `${ageText}, under the ${WAIT_DAYS}-day hold, but it fixes ${fixed.join(", ")} affecting ${item.from}; a security fix is not held back.`,
+        };
+    }
+    return {
+        id: "release_age",
+        value,
+        effect: "wait",
+        evidence: `${ageText}; releases younger than ${WAIT_DAYS} days are held so a compromised publish can be caught and pulled first.`,
+    };
+}
+export function publishTrustSignal(item, to, base) {
+    if (to.withdrawn === "unpublished") {
+        // Its publisher record is gone with it; comparing would report a "drop" we cannot see.
+        return { id: "publish_trust", value: null, evidence: `${item.to} was unpublished; its publish metadata is gone.`, effect: "info" };
+    }
+    if (!base.record) {
+        return {
+            id: "publish_trust",
+            value: { to: to.trust, baseline: null },
+            evidence: `${item.to}: ${to.trustEvidence}. No baseline: ${base.note}.`,
+            effect: "info",
+        };
+    }
+    const b = base.record;
+    const value = { to: to.trust, baseline: b.trust, baseline_version: b.version, baseline_kind: base.kind };
+    const evidence = `${item.to}: level ${to.trust}, ${to.trustEvidence}. ${b.version} (${base.note}): level ${b.trust}, ${b.trustEvidence}.`;
+    if (to.trust < b.trust) {
+        return { id: "publish_trust", value, effect: "review", evidence: `Publish trust dropped. ${evidence}` };
+    }
+    return { id: "publish_trust", value, effect: "proceed", evidence };
+}
+export function installScriptSignal(item, to, from) {
+    if (item.ecosystem !== "npm") {
+        return { id: "install_script_added", value: "not_applicable", evidence: "npm only (crates run build.rs at build time, which the registry does not expose).", effect: "info" };
+    }
+    const scripts = to.installScripts ?? [];
+    if (!item.from) {
+        return {
+            id: "install_script_added",
+            value: scripts,
+            effect: "info",
+            evidence: scripts.length > 0 ? `${item.to} runs install-time scripts: ${scripts.join(", ")}.` : `${item.to} declares no install-time scripts.`,
+        };
+    }
+    if (!from || from.installScripts === null) {
+        return { id: "install_script_added", value: null, effect: "unknown", evidence: `Install scripts of ${item.from} are unknown (${from ? "release metadata gone" : "not on the registry"}).` };
+    }
+    const added = scripts.filter((s) => !from.installScripts.includes(s));
+    if (added.length > 0) {
+        return {
+            id: "install_script_added",
+            value: added,
+            effect: "review",
+            evidence: `${item.to} adds install-time script${added.length > 1 ? "s" : ""} ${added.join(", ")} that ${item.from} did not have; it runs on every install.`,
+        };
+    }
+    return {
+        id: "install_script_added",
+        value: [],
+        effect: "proceed",
+        evidence: scripts.length > 0 ? `Install scripts unchanged (${scripts.join(", ")}).` : "Neither version declares install-time scripts.",
+    };
+}
+export function newDependenciesSignal(to, base, introduced, created) {
+    if (!base.record) {
+        return { id: "new_dependencies", value: null, evidence: `No baseline to diff against: ${base.note}.`, effect: "info" };
+    }
+    if (introduced === null) {
+        return { id: "new_dependencies", value: null, evidence: `Dependency lists for ${to.version} or ${base.record.version} are unavailable.`, effect: "unknown" };
+    }
+    if (introduced.length === 0) {
+        return { id: "new_dependencies", value: [], evidence: `No runtime dependency added since ${base.record.version}.`, effect: "proceed" };
+    }
+    const ref = to.publishedAt ? Date.parse(to.publishedAt) : Date.now();
+    const rows = introduced.map((name) => {
+        const fact = created.get(name);
+        if (!fact)
+            return { name, first_published: null, age_days: null, note: "not checked (per-call lookup cap)" };
+        if (fact.status !== "ok")
+            return { name, first_published: null, age_days: null, note: fact.detail, status: fact.status };
+        const age = fact.createdAt ? Math.round(((ref - Date.parse(fact.createdAt)) / DAY_MS) * 10) / 10 : null;
+        return { name, first_published: fact.createdAt, age_days: age };
+    });
+    const young = rows.filter((r) => r.age_days !== null && r.age_days < NEW_DEP_MIN_AGE_DAYS);
+    const missing = rows.filter((r) => "status" in r && r.status === "not_found");
+    const gaps = rows.filter((r) => r.age_days === null && !("status" in r && r.status === "not_found"));
+    const list = rows.map((r) => (r.age_days !== null ? `${r.name} (first published ${r.age_days} days before ${to.version})` : `${r.name} (${r.note})`)).join(", ");
+    if (young.length > 0 || missing.length > 0) {
+        return {
+            id: "new_dependencies",
+            value: rows,
+            effect: "review",
+            evidence: `${to.version} adds ${list} since ${base.record.version}. A brand-new or vanished package as a new dependency is how injected-dependency compromises arrive.`,
+        };
+    }
+    return {
+        id: "new_dependencies",
+        value: rows,
+        effect: gaps.length > 0 ? "unknown" : "proceed",
+        evidence: `${to.version} adds ${list} since ${base.record.version}.`,
+    };
+}
+export function withdrawnSignal(item, to) {
+    if (to.withdrawn) {
+        return { id: "yanked_or_deprecated", value: { [to.withdrawn]: true }, effect: "avoid", evidence: `${item.to} was ${to.withdrawn} from the registry.` };
+    }
+    if (to.deprecated) {
+        return { id: "yanked_or_deprecated", value: { deprecated: to.deprecated }, effect: "avoid", evidence: `${item.to} is deprecated: "${to.deprecated}".` };
+    }
+    return { id: "yanked_or_deprecated", value: null, effect: "proceed", evidence: `${item.to} is neither yanked nor deprecated.` };
+}
+export function upgradeTypeSignal(item) {
+    const kind = upgradeType(item.from, item.to);
+    const text = item.from ? `${item.from} -> ${item.to}: ${kind}` : `new dependency at ${item.to}`;
+    const zeroX = kind === "major" && /^0\./.test(item.from ?? "") ? " (0.x: a minor bump is breaking)" : "";
+    return { id: "upgrade_type", value: kind, evidence: `${text}${zeroX}.`, effect: "info" };
+}
+export function upgradeType(from, to) {
+    if (!from)
+        return "new_dependency";
+    const a = parseSemverPrecedence(from);
+    const b = parseSemverPrecedence(to);
+    if (!a || !b)
+        return "unknown";
+    const cmp = comparePrecedence(b, a);
+    if (cmp === 0)
+        return "none";
+    if (cmp < 0)
+        return "downgrade";
+    if (a.major !== b.major)
+        return "major";
+    if (a.minor !== b.minor)
+        return a.major === 0 ? "major" : "minor";
+    if (a.major === 0 && a.minor === 0 && a.patch !== b.patch)
+        return "major";
+    return "patch";
+}
+/** The item verdict and its one-line reason, from the strongest signal effect. */
+export function decide(signals) {
+    for (const verdict of PRECEDENCE) {
+        const hits = signals.filter((s) => s.effect === verdict);
+        if (hits.length === 0)
+            continue;
+        if (verdict === "proceed") {
+            const fixes = signals.find((s) => s.id === "release_age" && /security fix/.test(s.evidence));
+            return { verdict, reason: fixes ? fixes.evidence : "No advisory, age, trust, script or new-dependency concern found." };
+        }
+        return { verdict, reason: hits.map((s) => `${s.id}: ${s.evidence}`).join(" | ") };
+    }
+    return { verdict: "unknown", reason: "No signal could be evaluated." };
+}

package/dist/tools/dependency-check.d.ts

@@ -0,0 +1,98 @@
+/**
+ * dependency_check tool
+ *
+ * A pre-flight verdict for ONE proposed change per item: adding a dependency
+ * at a version, or bumping an installed one. An agent calls this before it
+ * edits a manifest and gets `proceed | wait | review | avoid | unknown`, a
+ * one-line reason, and the signals behind it, each with evidence.
+ *
+ * Signals (see dependency-check-signals.ts): known advisories on the target
+ * (OSV), release age (hold releases < 3 days unless they fix an advisory on
+ * the installed version), publish-trust drop, newly added install scripts
+ * (npm), newly introduced runtime dependencies that are themselves < 30 days
+ * old, yanked/deprecated/unpublished targets, and the upgrade type.
+ *
+ * Honesty contract: a registry or OSV that cannot be reached makes the item
+ * `unknown`, never `proceed`. A package missing from the public registry is
+ * `unknown` with that said (private package, or a misspelled/hallucinated
+ * name), never treated as clean.
+ *
+ * Privacy: registry requests carry the package name only — the installed and
+ * target versions are picked out of the full release list locally. Only OSV
+ * receives name + version, exactly as vulnerability_scan already does.
+ */
+import type { FourDADatabase } from "../db.js";
+import type { LiveIntelligence } from "../live/index.js";
+import { type Signal, type Verdict } from "./dependency-check-signals.js";
+export interface DependencyCheckParams {
+    items?: unknown;
+}
+export declare const dependencyCheckTool: {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            items: {
+                type: string;
+                minItems: number;
+                maxItems: number;
+                description: string;
+                items: {
+                    type: string;
+                    properties: {
+                        ecosystem: {
+                            type: string;
+                            enum: string[];
+                            description: string;
+                        };
+                        package: {
+                            type: string;
+                            description: string;
+                        };
+                        to: {
+                            type: string;
+                            description: string;
+                        };
+                        from: {
+                            type: string;
+                            description: string;
+                        };
+                    };
+                    required: string[];
+                };
+            };
+        };
+        required: string[];
+    };
+};
+interface ItemResult {
+    ecosystem: string;
+    package: string;
+    from: string | null;
+    to: string;
+    /** "latest" when the caller asked for it and `to` is what it resolved to. */
+    to_requested?: string;
+    verdict: Verdict;
+    reason: string;
+    signals: Signal[];
+}
+export declare function executeDependencyCheck(_db: FourDADatabase, params: DependencyCheckParams, liveIntel: LiveIntelligence | null, opts?: {
+    now?: Date;
+}): Promise<{
+    checked_at: string;
+    summary: string;
+    results: ItemResult[];
+    _meta: {
+        sources: string[];
+        verdict_rule: string;
+        privacy: string;
+        offline: boolean;
+        osv_cached: boolean;
+        provenance: {
+            mode: string;
+            note: string;
+        };
+    };
+}>;
+export {};

package/dist/tools/dependency-check.js

@@ -0,0 +1,295 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * dependency_check tool
+ *
+ * A pre-flight verdict for ONE proposed change per item: adding a dependency
+ * at a version, or bumping an installed one. An agent calls this before it
+ * edits a manifest and gets `proceed | wait | review | avoid | unknown`, a
+ * one-line reason, and the signals behind it, each with evidence.
+ *
+ * Signals (see dependency-check-signals.ts): known advisories on the target
+ * (OSV), release age (hold releases < 3 days unless they fix an advisory on
+ * the installed version), publish-trust drop, newly added install scripts
+ * (npm), newly introduced runtime dependencies that are themselves < 30 days
+ * old, yanked/deprecated/unpublished targets, and the upgrade type.
+ *
+ * Honesty contract: a registry or OSV that cannot be reached makes the item
+ * `unknown`, never `proceed`. A package missing from the public registry is
+ * `unknown` with that said (private package, or a misspelled/hallucinated
+ * name), never treated as clean.
+ *
+ * Privacy: registry requests carry the package name only — the installed and
+ * target versions are picked out of the full release list locally. Only OSV
+ * receives name + version, exactly as vulnerability_scan already does.
+ */
+import { isMaintenanceNotice } from "../live/maintenance.js";
+import { compareVersionPrecedence, parseSemverPrecedence } from "../live/semver-precedence.js";
+import { advisoriesSignal, decide, installScriptSignal, introducedDependencies, newDependenciesSignal, publishTrustSignal, releaseAgeSignal, selectBaseline, upgradeTypeSignal, withdrawnSignal, } from "./dependency-check-signals.js";
+const MAX_ITEMS = 25;
+/** First-publish lookups for newly introduced dependencies, per call (each is a registry read). */
+const MAX_NEW_DEP_LOOKUPS = 40;
+const NPM_CONCURRENCY = 4;
+const PRIVACY_NOTE = "Registry requests carried package names only (npm full packument, crates.io versions API and sparse index); " +
+    "installed and target versions were never sent to a registry. OSV.dev received package names and versions, as vulnerability_scan does.";
+const VERDICT_RULE = "avoid > review > unknown > wait > proceed. unknown = a registry or OSV.dev lookup failed (never read as proceed); " +
+    "a concrete avoid/review finding still wins over a missing source.";
+export const dependencyCheckTool = {
+    name: "dependency_check",
+    description: [
+        "Pre-flight verdict for adding a dependency or changing one to a specific version. Call BEFORE you add a package to a manifest or apply a version bump (including bumps proposed by upgrade_planner or a bot), and act on the verdict.",
+        "",
+        "Per item it returns `verdict` (proceed | wait | review | avoid | unknown), a one-line `reason`, and `signals`, each with `id`, `value`, `evidence` and the verdict that signal implies alone (`effect`):",
+        "- advisories: known OSV advisories affecting `to`, and those this change fixes on `from`. High/critical on `to` -> avoid; other -> review.",
+        "- release_age: days since `to` was published. Under 3 days -> wait, unless `to` fixes an advisory affecting `from` (a security fix is not held).",
+        "- publish_trust: trust level of `to` vs `from` (or, for a new dependency, the previous release on the same line). 2 = trusted publisher (npm `_npmUser.trustedPublisher`, crates.io `trustpub_data`), 1 = npm provenance attestation, 0 = neither. A drop -> review.",
+        "- install_script_added (npm): `to` runs preinstall/install/postinstall and `from` did not -> review. For a new dependency, information only.",
+        "- new_dependencies: runtime dependencies added since the baseline, each with its first-publish age. Any under 30 days old, or no longer on the registry -> review.",
+        "- yanked_or_deprecated: `to` yanked, unpublished or deprecated -> avoid.",
+        "- upgrade_type: patch | minor | major (a 0.x minor counts as major) | downgrade | new_dependency. Information only.",
+        "",
+        "Verdict precedence: avoid > review > unknown > wait > proceed. `unknown` means a registry or OSV.dev lookup failed, or the package is not on the public registry (private package, or a misspelled/hallucinated name); it is never a silent proceed. Apply only `proceed` items; report the others with their evidence. For WHAT the bump changes in your code, call upgrade_impact.",
+        "",
+        "Privacy: registry requests carry the package NAME only (npm full packument, crates.io versions API and sparse index); the installed and target versions are never sent to a registry. OSV.dev receives package names and versions, as vulnerability_scan does. Set FOURDA_OFFLINE=true to disable all lookups (every item then returns unknown).",
+    ].join("\n"),
+    inputSchema: {
+        type: "object",
+        properties: {
+            items: {
+                type: "array",
+                minItems: 1,
+                maxItems: 25,
+                description: "The proposed changes to check, 1 to 25.",
+                items: {
+                    type: "object",
+                    properties: {
+                        ecosystem: { type: "string", enum: ["npm", "crates.io"], description: "Package registry." },
+                        package: {
+                            type: "string",
+                            description: 'Package name exactly as published (e.g. "axios", "@scope/pkg", "serde_json").',
+                        },
+                        to: { type: "string", description: 'Exact version you intend to install (e.g. "1.14.1"), or "latest" for the newest stable release; not a range.' },
+                        from: { type: "string", description: "Exact version currently installed. Omit when adding a new dependency." },
+                    },
+                    required: ["ecosystem", "package", "to"],
+                },
+            },
+        },
+        required: ["items"],
+    },
+};
+export async function executeDependencyCheck(_db, params, liveIntel, opts = {}) {
+    const requested = validateItems(params.items);
+    const now = opts.now ?? new Date();
+    const checkedAt = now.toISOString();
+    if (!liveIntel || !liveIntel.isEnabled()) {
+        const reason = "Live lookups are disabled (FOURDA_OFFLINE=true); nothing about these versions could be checked.";
+        return finish(checkedAt, requested.map((item) => ({ ...head(item), verdict: "unknown", reason, signals: [] })), { offline: true, osvCached: false });
+    }
+    const sources = liveIntel.getReleaseSources();
+    const indexes = await fetchIndexes(requested, sources);
+    // `to: "latest"` becomes the newest stable release the registry lists. Agents
+    // adding a package pass it naturally; rejecting it cost a retry in 7 of 24
+    // dependency_check trials of the 2026-10-03 agent eval.
+    const items = requested.map((item) => resolveLatest(item, indexes.get(lookupKey(item))));
+    const osvDeps = items.flatMap((item) => [item.to, item.from].filter((v) => Boolean(v)).map((version) => osvDep(item, version)));
+    const scan = await liveIntel.queryAdvisories(osvDeps);
+    const byInstance = new Map();
+    for (const v of scan.vulnerabilities) {
+        const key = instanceKey(v.ecosystem, v.package, v.currentVersion);
+        byInstance.set(key, [...(byInstance.get(key) ?? []), v]);
+    }
+    const advisoriesFor = (item) => scan.offline
+        ? { available: false, detail: "lookup failed or was rate limited" }
+        : {
+            available: true,
+            to: refs(byInstance.get(instanceKey(item.ecosystem, item.package, item.to))),
+            from: item.from ? refs(byInstance.get(instanceKey(item.ecosystem, item.package, item.from))) : [],
+        };
+    // Phase 2: first-publish dates of newly introduced dependencies.
+    const plans = items.map((item) => planItem(item, indexes.get(lookupKey(item))));
+    const wantedCreated = new Map();
+    for (const p of plans) {
+        for (const name of p.introduced ?? []) {
+            if (wantedCreated.size >= MAX_NEW_DEP_LOOKUPS)
+                break;
+            wantedCreated.set(`${p.item.ecosystem}\0${name}`, { ecosystem: p.item.ecosystem, name });
+        }
+    }
+    const created = new Map();
+    await mapLimit([...wantedCreated.entries()], NPM_CONCURRENCY, async ([key, { ecosystem, name }]) => {
+        const lookup = await sources[ecosystem].getCreatedAt(name);
+        created.set(key, lookup.status === "ok" ? { status: "ok", createdAt: lookup.data } : lookup);
+    });
+    const results = plans.map((p) => {
+        if (p.blocked) {
+            // No release metadata: only the advisory lookup can still speak, and
+            // only a negative finding is worth more than "unknown".
+            const advisories = advisoriesSignal(p.item, advisoriesFor(p.item));
+            const negative = advisories.effect === "avoid" || advisories.effect === "review";
+            return {
+                ...head(p.item),
+                verdict: negative ? advisories.effect : "unknown",
+                reason: negative ? `advisories: ${advisories.evidence} | ${p.blocked}` : p.blocked,
+                signals: [advisories],
+            };
+        }
+        const { item, index } = p;
+        const to = index.releases[item.to];
+        const base = selectBaseline(index, item);
+        const advisories = advisoriesSignal(item, advisoriesFor(item));
+        const createdForItem = new Map();
+        for (const name of p.introduced ?? []) {
+            const fact = created.get(`${item.ecosystem}\0${name}`);
+            if (fact)
+                createdForItem.set(name, fact);
+        }
+        const signals = [
+            advisories,
+            releaseAgeSignal(item, to, advisories, now),
+            publishTrustSignal(item, to, base),
+            installScriptSignal(item, to, item.from ? index.releases[item.from] ?? null : null),
+            newDependenciesSignal(to, base, p.introduced, createdForItem),
+            withdrawnSignal(item, to),
+            upgradeTypeSignal(item),
+        ];
+        return { ...head(item), ...decide(signals), signals };
+    });
+    return finish(checkedAt, results, { offline: scan.offline, osvCached: scan.cached });
+}
+function planItem(item, lookup) {
+    if (lookup.status === "unreachable") {
+        return { item, blocked: `Registry could not be reached (${lookup.detail}); nothing about ${item.to} was verified.`, index: null, introduced: null };
+    }
+    if (lookup.status === "not_found") {
+        return {
+            item,
+            blocked: `${lookup.detail}. If it is a private package this tool cannot judge it; otherwise check the name for a typo or a hallucinated package before adding it.`,
+            index: null,
+            introduced: null,
+        };
+    }
+    const index = lookup.data;
+    const to = index.releases[item.to];
+    if (!to) {
+        return { item, blocked: `${item.package}@${item.to} is not a published version on ${item.ecosystem}.`, index, introduced: null };
+    }
+    return { item, blocked: null, index, introduced: introducedDependencies(to, selectBaseline(index, item).record) };
+}
+async function fetchIndexes(items, sources) {
+    const wanted = new Map();
+    for (const item of items) {
+        const key = lookupKey(item);
+        const entry = wanted.get(key) ?? { item, versions: new Set() };
+        entry.versions.add(item.to);
+        if (item.from)
+            entry.versions.add(item.from);
+        wanted.set(key, entry);
+    }
+    const out = new Map();
+    await mapLimit([...wanted.entries()], NPM_CONCURRENCY, async ([key, { item, versions }]) => {
+        out.set(key, await sources[item.ecosystem].getReleases(item.package, [...versions]));
+    });
+    return out;
+}
+function validateItems(raw) {
+    if (!Array.isArray(raw) || raw.length < 1 || raw.length > MAX_ITEMS) {
+        throw new Error(`items must be an array of 1 to ${MAX_ITEMS} { ecosystem, package, to, from? } objects`);
+    }
+    return raw.map((r, i) => {
+        const o = (r ?? {});
+        const where = `items[${i}]`;
+        if (o.ecosystem !== "npm" && o.ecosystem !== "crates.io")
+            throw new Error(`${where}.ecosystem must be "npm" or "crates.io"`);
+        if (typeof o.package !== "string" || !o.package.trim())
+            throw new Error(`${where}.package must be a non-empty string`);
+        const to = typeof o.to === "string" && o.to.trim().toLowerCase() === LATEST ? LATEST : exactVersion(o.to, `${where}.to`);
+        const from = o.from === undefined || o.from === null || o.from === "" ? undefined : exactVersion(o.from, `${where}.from`);
+        return { ecosystem: o.ecosystem, package: o.package.trim(), to, ...(from ? { from } : {}) };
+    });
+}
+function exactVersion(v, where) {
+    const s = typeof v === "string" ? v.trim().replace(/^v(?=\d)/, "") : "";
+    if (!parseSemverPrecedence(s)) {
+        const latest = where.endsWith(".to") ? ' or "latest"' : "";
+        throw new Error(`${where} must be an exact version like 1.2.3${latest} (got ${JSON.stringify(v)}), not a range`);
+    }
+    return s;
+}
+const LATEST = "latest";
+/**
+ * `to: "latest"` -> the highest release that is neither a prerelease nor
+ * withdrawn (a deprecated latest stays: deprecation is a finding to report).
+ * Left as "latest" when the registry read failed or lists no release; the item
+ * is then blocked with the registry's own reason, or "not a published version".
+ */
+function resolveLatest(item, lookup) {
+    if (item.to !== LATEST || lookup.status !== "ok")
+        return item;
+    const candidates = Object.values(lookup.data.releases).filter((r) => !r.withdrawn && parseSemverPrecedence(r.version));
+    const stable = candidates.filter((r) => parseSemverPrecedence(r.version).prerelease.length === 0);
+    const pool = stable.length > 0 ? stable : candidates;
+    const newest = pool.reduce((max, r) => (max === null || (compareVersionPrecedence(r.version, max) ?? 0) > 0 ? r.version : max), null);
+    return newest ? { ...item, to: newest, requested: LATEST } : item;
+}
+function osvDep(item, version) {
+    return {
+        name: item.package,
+        version,
+        ecosystem: item.ecosystem,
+        isDev: false,
+        isDirect: true,
+        devScopeKnown: true,
+        target: null,
+        platformActive: true,
+        sourceDirs: [],
+    };
+}
+function refs(entries) {
+    const seen = new Set();
+    return (entries ?? []).flatMap((v) => {
+        if (seen.has(v.vulnId))
+            return [];
+        seen.add(v.vulnId);
+        return [{ id: v.vulnId, severity: v.severity, summary: v.summary, maintenance: isMaintenanceNotice(v) }];
+    });
+}
+const instanceKey = (eco, name, version) => `${eco}\0${name}\0${version}`;
+const lookupKey = (item) => `${item.ecosystem}\0${item.package}`;
+const head = (item) => ({
+    ecosystem: item.ecosystem,
+    package: item.package,
+    from: item.from ?? null,
+    to: item.to,
+    ...(item.requested ? { to_requested: item.requested } : {}),
+});
+function finish(checkedAt, results, meta) {
+    const counts = new Map();
+    for (const r of results)
+        counts.set(r.verdict, (counts.get(r.verdict) ?? 0) + 1);
+    const order = ["avoid", "review", "unknown", "wait", "proceed"];
+    const parts = order.filter((v) => counts.has(v)).map((v) => `${counts.get(v)} ${v}`);
+    return {
+        checked_at: checkedAt,
+        summary: `${results.length} checked: ${parts.join(", ")}. Apply only "proceed" items; report the rest with their evidence.`,
+        results,
+        _meta: {
+            sources: ["registry.npmjs.org", "crates.io", "index.crates.io", "osv.dev"],
+            verdict_rule: VERDICT_RULE,
+            privacy: PRIVACY_NOTE,
+            offline: meta.offline,
+            osv_cached: meta.osvCached,
+            provenance: {
+                mode: "live_registry_check",
+                note: "Point-in-time facts from the public registries and OSV.dev at checked_at. Says nothing about code behaviour; a proceed is the absence of known warning signs, not a review of the release.",
+            },
+        },
+    };
+}
+async function mapLimit(items, limit, fn) {
+    let next = 0;
+    const workers = Array.from({ length: Math.min(limit, items.length) }, async () => {
+        while (next < items.length)
+            await fn(items[next++]);
+    });
+    await Promise.all(workers);
+}