@4da/mcp-server 5.0.3 → 6.0.0

package/dist/tools/install-drift-notes.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Words for install drift (node_modules holding a different version than the
+ * lockfile pins), shared by vulnerability_scan, what_should_i_know,
+ * get_actionable_signals, dependency_health and upgrade_planner so every
+ * surface says the same thing about the same drifted package.
+ *
+ * The case this exists for (measured 2026-09-10): the lockfile pinned the
+ * patched hono 4.13.5 while node_modules still held the vulnerable 4.13.1.
+ * "Upgrade hono to 4.13.4" would be wrong advice there, because the lockfile
+ * is already past it. The fix is a reinstall, and the output has to say so.
+ */
+import type { InstallDriftRecord, VulnerabilityEntry, VulnerabilityScanResult } from "../live/types.js";
+/** A relative directory label for a sentence: the scan root reads as words, not ".". */
+export declare function placeLabel(label: string): string;
+/** The directories a row names, spelled for a message. */
+export declare function dirsLabel(dirs: string[], relative?: (dir: string) => string): string;
+/** Drift records for one npm lockfile instance (package at its lockfile version). */
+export declare function driftFor(drift: InstallDriftRecord[], name: string, lockfileVersion: string | null): InstallDriftRecord[];
+/** The action for a scan row about an installed version the lockfile does not pin. */
+export declare function driftAction(v: VulnerabilityEntry): string;
+/** Whether the lockfile's own version of a drifted package carries this same advisory. */
+export declare function lockfileAlsoAffected(v: VulnerabilityEntry, all: VulnerabilityEntry[]): boolean;
+/** Group the actionable drift rows of a scan per (package, installed, locked). */
+export declare function groupDriftRows(vulns: VulnerabilityEntry[]): VulnerabilityEntry[][];
+export interface DriftAdvisory {
+    title: string;
+    signal_type: "security_alert";
+    priority: "critical" | "high" | "medium";
+    action: string;
+    url: null;
+}
+/**
+ * One briefing advisory per drifted package whose installed copy OSV lists as
+ * vulnerable, graded the way the app grades its install-drift Preemption row
+ * (`evidence::install_drift`): high when the reinstall clears an advisory the
+ * running copy has, medium when the lockfile's pinned version is exposed too
+ * (the reinstall alone is then not the fix, and each advisory's own signal
+ * carries its grade). Always a security alert, so the verdict is at least
+ * review_needed and a vulnerable installed copy is never reported clean.
+ *
+ * Measured 2026-09-10: the hono incident's three advisories are medium on
+ * their own, and the installed copy stayed vulnerable for 25 days while a
+ * one-line reinstall would have cleared all three.
+ */
+export declare function installDriftAdvisories(scan: VulnerabilityScanResult): DriftAdvisory[];
+/** The `install_drift` rows and per-vulnerability annotations for one scan. */
+export interface DriftView {
+    rows: Array<Record<string, unknown>>;
+    annotate(v: VulnerabilityEntry): Record<string, unknown>;
+}
+export declare function buildDriftView(result: VulnerabilityScanResult, drift: InstallDriftRecord[], includeDev: boolean, relative: (dir: string) => string): DriftView;

package/dist/tools/install-drift-notes.js

@@ -0,0 +1,172 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Words for install drift (node_modules holding a different version than the
+ * lockfile pins), shared by vulnerability_scan, what_should_i_know,
+ * get_actionable_signals, dependency_health and upgrade_planner so every
+ * surface says the same thing about the same drifted package.
+ *
+ * The case this exists for (measured 2026-09-10): the lockfile pinned the
+ * patched hono 4.13.5 while node_modules still held the vulnerable 4.13.1.
+ * "Upgrade hono to 4.13.4" would be wrong advice there, because the lockfile
+ * is already past it. The fix is a reinstall, and the output has to say so.
+ */
+import { isActionableVulnerability } from "../live/maintenance.js";
+import { presentedSeverity, SEVERITY_RANK } from "../live/severity-scope.js";
+const norm = (p) => p.replace(/\\/g, "/").replace(/\/+$/, "").toLowerCase();
+/** A relative directory label for a sentence: the scan root reads as words, not ".". */
+export function placeLabel(label) {
+    return label === "." ? "the project root" : label;
+}
+/** The directories a row names, spelled for a message. */
+export function dirsLabel(dirs, relative = (d) => d.replace(/\\/g, "/")) {
+    const labels = [...new Set(dirs.map(relative))].map(placeLabel).sort();
+    return labels.length > 0 ? labels.join(", ") : "the project";
+}
+/** Drift records for one npm lockfile instance (package at its lockfile version). */
+export function driftFor(drift, name, lockfileVersion) {
+    return drift.filter((r) => r.package === name && r.lockfileVersion === lockfileVersion);
+}
+/** The action for a scan row about an installed version the lockfile does not pin. */
+export function driftAction(v) {
+    const command = v.installFix ?? "a reinstall";
+    return `Run \`${command}\` in ${dirsLabel(v.sourceDirs)} — node_modules has ${v.package}@${v.currentVersion}; the lockfile pins ${v.installDriftOf}`;
+}
+/** Whether the lockfile's own version of a drifted package carries this same advisory. */
+export function lockfileAlsoAffected(v, all) {
+    if (!v.installDriftOf)
+        return false;
+    const ids = new Set([v.vulnId, ...v.aliases]);
+    return all.some((x) => x.package === v.package &&
+        x.ecosystem === v.ecosystem &&
+        x.currentVersion === v.installDriftOf &&
+        isActionableVulnerability(x) &&
+        [x.vulnId, ...x.aliases].some((id) => ids.has(id)));
+}
+const topTier = (entries) => entries.map(presentedSeverity).reduce((a, b) => (SEVERITY_RANK[b] > SEVERITY_RANK[a] ? b : a), "unknown");
+/** Group the actionable drift rows of a scan per (package, installed, locked). */
+export function groupDriftRows(vulns) {
+    const groups = new Map();
+    for (const v of vulns) {
+        if (!v.installDriftOf || !isActionableVulnerability(v))
+            continue;
+        const key = `${v.ecosystem}\0${v.package}\0${v.currentVersion}\0${v.installDriftOf}`;
+        const list = groups.get(key);
+        if (list)
+            list.push(v);
+        else
+            groups.set(key, [v]);
+    }
+    return [...groups.values()];
+}
+/**
+ * One briefing advisory per drifted package whose installed copy OSV lists as
+ * vulnerable, graded the way the app grades its install-drift Preemption row
+ * (`evidence::install_drift`): high when the reinstall clears an advisory the
+ * running copy has, medium when the lockfile's pinned version is exposed too
+ * (the reinstall alone is then not the fix, and each advisory's own signal
+ * carries its grade). Always a security alert, so the verdict is at least
+ * review_needed and a vulnerable installed copy is never reported clean.
+ *
+ * Measured 2026-09-10: the hono incident's three advisories are medium on
+ * their own, and the installed copy stayed vulnerable for 25 days while a
+ * one-line reinstall would have cleared all three.
+ */
+export function installDriftAdvisories(scan) {
+    return groupDriftRows(scan.vulnerabilities).map((entries) => {
+        const first = entries[0];
+        const count = entries.length;
+        const pinExposed = entries.some((e) => lockfileAlsoAffected(e, scan.vulnerabilities));
+        const clearsAny = entries.some((e) => !lockfileAlsoAffected(e, scan.vulnerabilities));
+        return {
+            title: `${first.package}: the installed ${first.currentVersion} in node_modules has ${count} known vulnerabilit${count === 1 ? "y" : "ies"}; the lockfile pins ${first.installDriftOf}`,
+            signal_type: "security_alert",
+            priority: clearsAny ? "high" : "medium",
+            action: `${driftAction(first)}${!pinExposed
+                ? " (the lockfile version is not affected; the reinstall is the whole fix)"
+                : clearsAny
+                    ? " (the reinstall clears some of these; the lockfile version is still affected by the rest, so upgrade it too)"
+                    : " (the lockfile version is also affected; upgrade it, then reinstall)"}`,
+            url: null,
+        };
+    });
+}
+export function buildDriftView(result, drift, includeDev, relative) {
+    const actionable = result.vulnerabilities.filter(isActionableVulnerability);
+    // OSV's answer for one npm (package, version), whichever dependency asked it.
+    const affected = (pkg, version) => actionable.some((v) => v.ecosystem === "npm" && v.package === pkg && v.currentVersion === version);
+    // Null when the version was not in the scanned set (a dev dependency without
+    // include_dev) or the scan went offline with nothing to say about it.
+    const answer = (record, version) => {
+        if (record.isDev && !includeDev)
+            return null;
+        if (affected(record.package, version))
+            return true;
+        return result.offline ? null : false;
+    };
+    const rows = drift.map((record) => {
+        const vulnerableInstalled = answer(record, record.installedVersion);
+        const lockfileVulnerable = answer(record, record.lockfileVersion);
+        const dir = relative(record.dir);
+        const where = placeLabel(dir);
+        let note;
+        if (vulnerableInstalled === true && lockfileVulnerable === false) {
+            note = `The lockfile is patched but node_modules is not: run \`${record.fix}\` in ${where}.`;
+        }
+        else if (vulnerableInstalled === true) {
+            note = `The installed copy is vulnerable and so is the lockfile's version: upgrade, then run \`${record.fix}\` in ${where}.`;
+        }
+        else if (vulnerableInstalled === false) {
+            note = `node_modules is out of step with the lockfile (no known advisory affects the installed version): run \`${record.fix}\` in ${where}.`;
+        }
+        else {
+            const why = record.isDev && !includeDev ? "a dev dependency; pass include_dev to check it" : "the scan was offline";
+            note = `node_modules is out of step with the lockfile; the installed version was not checked (${why}): run \`${record.fix}\` in ${where}.`;
+        }
+        return {
+            package: record.package,
+            dir,
+            lockfile_version: record.lockfileVersion,
+            installed_version: record.installedVersion,
+            vulnerable_installed: vulnerableInstalled,
+            lockfile_version_vulnerable: lockfileVulnerable,
+            fix: record.fix,
+            note,
+        };
+    });
+    const inDirs = (dir, dirs) => dirs.some((d) => norm(d) === norm(dir));
+    const annotate = (v) => {
+        if (v.installDriftOf) {
+            const command = v.installFix ?? "a reinstall";
+            const where = dirsLabel(v.sourceDirs, relative);
+            return {
+                installed_version: v.currentVersion,
+                lockfile_version: v.installDriftOf,
+                install_note: lockfileAlsoAffected(v, result.vulnerabilities)
+                    ? `This is the copy in node_modules; the lockfile's ${v.installDriftOf} is also affected — upgrade, then run \`${command}\` in ${where}.`
+                    : `This is the copy in node_modules: the lockfile is patched (pins ${v.installDriftOf}) but node_modules still has ${v.currentVersion} — run \`${command}\` in ${where}.`,
+            };
+        }
+        if (v.ecosystem !== "npm")
+            return {};
+        // A lockfile row whose package node_modules holds at another version.
+        const behind = drift.filter((r) => r.package === v.package && r.lockfileVersion === v.currentVersion && inDirs(r.dir, v.sourceDirs));
+        if (behind.length > 0) {
+            const installed = [...new Set(behind.map((r) => r.installedVersion))].join(", ");
+            return {
+                installed_version: installed,
+                install_note: `node_modules has ${installed}, not this lockfile version — run \`${behind[0].fix}\` in ${dirsLabel(behind.map((r) => r.dir), relative)}; advisories against the installed copy are listed under its own version.`,
+            };
+        }
+        // A lockfile row that is also what a drifted workspace has installed.
+        const holders = drift.filter((r) => r.package === v.package && r.installedVersion === v.currentVersion && inDirs(r.dir, v.sourceDirs));
+        if (holders.length > 0) {
+            return {
+                installed_version: v.currentVersion,
+                lockfile_version: [...new Set(holders.map((r) => r.lockfileVersion))].join(", "),
+                install_note: `Also the copy node_modules holds in ${dirsLabel(holders.map((r) => r.dir), relative)}, where the lockfile pins a different version — run \`${holders[0].fix}\` there.`,
+            };
+        }
+        return {};
+    };
+    return { rows, annotate };
+}

package/dist/tools/knowledge-gap-citations.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Knowledge-gap citations: which unread items are evidence about which
+ * dependency. Mirrors `knowledge_decay::{load_gap_candidates,
+ * keyword_misses_from, normalize_gap_title}` in the desktop app.
+ */
+import type { FourDADatabase } from "../db.js";
+import type { SourceItemBriefRow } from "../types.js";
+import type { LinkerIndex } from "./knowledge-gap-scope.js";
+/** An unread item eligible to become a missed signal. */
+export type GapCandidate = SourceItemBriefRow & {
+    content_type: string | null;
+    relevance_score: number | null;
+    published_at: string | null;
+    /** osv rows: the advisory id; cve rows: the CVE id. */
+    source_id: string | null;
+    content_head: string;
+    title_lower: string;
+};
+/**
+ * Every unread candidate item, loaded ONCE and matched per dependency.
+ * Grounding (each guard killed an observed false-positive class):
+ * - relevance_score >= 0.2, the scoring pipeline's above-noise band, when the
+ *   database has a scoring pipeline at all;
+ * - a 30-day window: a gap is something you MISSED, not archaeology;
+ * - engagement: an item clicked or saved here (`interactions.item_id` /
+ *   `.action_type`, the canonical columns) or given feedback in the app;
+ * - the content types above, as the app excludes them.
+ * Optional columns are feature-detected: a standalone database may lack the
+ * scoring pipeline, and the tool must degrade, never throw.
+ */
+export declare function loadCandidates(db: FourDADatabase): GapCandidate[];
+/**
+ * Does this unread item cite `packageName`?
+ *
+ * An advisory row (osv/cve) cites a dependency only through the dependency
+ * linker's structured proof when the linker table exists, and otherwise only
+ * when the package is the advisory's SUBJECT ("[ID] package: ..."). Never
+ * through a word in its title: "[CVE-2026-63642] MagicMirror newsfeed
+ * Socket.IO notification allows blind server-side request forgery" has no
+ * linker row and no parseable subject, and it minted a critical socket.io gap
+ * on the word "Socket.IO" (measured 2026-09-11).
+ *
+ * Every other row cites a dependency when its TITLE names it at a word
+ * boundary, as the app matches titles only. The body does not count: four
+ * reposts of "I built 59 free browser-based dev tools in vanilla JS" evidenced
+ * a critical `rsa` gap through a "RSA & ECC Key Generator" line 1,330
+ * characters into the post. A package named by an ordinary English word also
+ * needs an ecosystem cue, which may come from the body.
+ */
+export declare function citesDependency(item: GapCandidate, packageName: string, linker: LinkerIndex | null): boolean;
+/**
+ * `knowledge_decay::normalize_gap_title`: lowercase, punctuation stripped,
+ * first ten words. Reposts of one story share it.
+ */
+export declare function normalizeGapTitle(title: string): string;

package/dist/tools/knowledge-gap-citations.js

@@ -0,0 +1,132 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Knowledge-gap citations: which unread items are evidence about which
+ * dependency. Mirrors `knowledge_decay::{load_gap_candidates,
+ * keyword_misses_from, normalize_gap_title}` in the desktop app.
+ */
+import { advisorySubject, isAdvisoryRow, mentionsPackage, samePackage } from "./knowledge-gap-grading.js";
+/**
+ * Content types the app never counts as missed intelligence
+ * (`load_gap_candidates`): someone else's project, a tutorial, a question.
+ */
+const NON_GAP_CONTENT_TYPES = ["show_and_tell", "tutorial", "question", "help_request", "hiring", "clickbait"];
+/** Sources whose rows are structured facts about a package (advisory records, registry releases). */
+const STRUCTURED_EVIDENCE = ["cve", "osv", "crates_io", "npm_registry", "pypi", "go_modules"];
+/**
+ * Every unread candidate item, loaded ONCE and matched per dependency.
+ * Grounding (each guard killed an observed false-positive class):
+ * - relevance_score >= 0.2, the scoring pipeline's above-noise band, when the
+ *   database has a scoring pipeline at all;
+ * - a 30-day window: a gap is something you MISSED, not archaeology;
+ * - engagement: an item clicked or saved here (`interactions.item_id` /
+ *   `.action_type`, the canonical columns) or given feedback in the app;
+ * - the content types above, as the app excludes them.
+ * Optional columns are feature-detected: a standalone database may lack the
+ * scoring pipeline, and the tool must degrade, never throw.
+ */
+export function loadCandidates(db) {
+    const has = (column) => db.hasColumn("source_items", column);
+    const hasContentType = has("content_type");
+    const hasRelevance = has("relevance_score");
+    // Prose evidence (news, social, papers) must have passed the relevance
+    // judge: its latest verdict >= 0.5, or, without judgments, the feed kept it.
+    // Structured rows (advisories, registry releases) are matched by subject and
+    // version instead. Measured 2026-10-01: "Breaking Windows Malware
+    // Detection" (judge 0.1) evidenced a high `windows` crate gap, and
+    // judge-rejected OpenAI company news an `openai` one.
+    const structured = `si.source_type IN (${STRUCTURED_EVIDENCE.map((s) => `'${s}'`).join(", ")})`;
+    const judgedIn = db.hasColumn("llm_judgments", "source_item_id")
+        ? `AND (${structured} OR (SELECT relevance_score FROM llm_judgments lj WHERE lj.source_item_id = si.id ORDER BY lj.id DESC LIMIT 1) >= 0.5)`
+        : has("feed_relevant")
+            ? `AND (${structured} OR si.feed_relevant = 1)`
+            : "";
+    const engaged = db.hasColumn("interactions", "item_id") && db.hasColumn("interactions", "action_type")
+        ? "AND si.id NOT IN (SELECT item_id FROM interactions WHERE item_id IS NOT NULL AND action_type IN ('click', 'save'))"
+        : "";
+    const judged = db.hasColumn("feedback", "source_item_id")
+        ? "AND si.id NOT IN (SELECT source_item_id FROM feedback WHERE source_item_id IS NOT NULL)"
+        : "";
+    const excludedTypes = NON_GAP_CONTENT_TYPES.map((t) => `'${t}'`).join(", ");
+    const rows = db
+        .getRawDb()
+        .prepare(`SELECT si.id, si.title, si.url, si.source_type, si.created_at,
+              ${hasContentType ? "si.content_type" : "NULL AS content_type"},
+              ${hasRelevance ? "si.relevance_score" : "NULL AS relevance_score"},
+              ${has("published_at") ? "si.published_at" : "NULL AS published_at"},
+              ${has("source_id") ? "si.source_id" : "NULL AS source_id"},
+              substr(COALESCE(si.content, ''), 1, 2000) AS content_head
+         FROM source_items si
+        WHERE si.created_at >= datetime('now', '-30 days')
+          ${hasRelevance ? "AND si.relevance_score IS NOT NULL AND si.relevance_score >= 0.2" : ""}
+          ${hasContentType ? `AND (si.content_type IS NULL OR si.content_type NOT IN (${excludedTypes}))` : ""}
+          ${engaged}
+          ${judged}
+          ${judgedIn}
+        ORDER BY si.created_at DESC, si.id DESC`)
+        .all();
+    return rows.map((row) => ({ ...row, title_lower: (row.title || "").toLowerCase() }));
+}
+/**
+ * Dependency names that are ordinary English words. A word-boundary match on
+ * these is no evidence the item is about the PACKAGE: live 2026-08-30, a
+ * `tower` gap was evidenced by a one-tap tower-stacker game and a drivable-car
+ * post. For these names the item must also carry an ecosystem cue.
+ */
+const GENERIC_WORD_DEPS = new Set([
+    "tower", "base64", "image", "time", "rand", "log", "tracing", "url", "zip",
+    "tar", "glob", "regex", "chrono", "notify", "either", "bytes", "flate",
+    // Company, product and protocol names a headline uses for the thing itself
+    // (2026-10-01: "RSA has launched Agent ID", "Windows 11 emergency update",
+    // "OpenAI halts release of Astra 6.1" evidenced rsa, windows, openai gaps).
+    "rsa", "windows", "openai", "stripe", "docker", "redis", "sentry", "next", "ai", "anthropic",
+]);
+// A token that ties the text to software packaging rather than the English word:
+// an ecosystem noun, a security noun, or a version number.
+const ECOSYSTEM_CUE = /\b(crate|crates\.io|cargo|rust|npm|node|package|library|dependenc|version|release[ds]?|upgrad|deprecat|cve|advisory|vulnerab)|\bv?\d+\.\d+/i;
+function hasEcosystemCue(item) {
+    return ECOSYSTEM_CUE.test(`${item.title || ""} ${item.content_head || ""}`);
+}
+/**
+ * Does this unread item cite `packageName`?
+ *
+ * An advisory row (osv/cve) cites a dependency only through the dependency
+ * linker's structured proof when the linker table exists, and otherwise only
+ * when the package is the advisory's SUBJECT ("[ID] package: ..."). Never
+ * through a word in its title: "[CVE-2026-63642] MagicMirror newsfeed
+ * Socket.IO notification allows blind server-side request forgery" has no
+ * linker row and no parseable subject, and it minted a critical socket.io gap
+ * on the word "Socket.IO" (measured 2026-09-11).
+ *
+ * Every other row cites a dependency when its TITLE names it at a word
+ * boundary, as the app matches titles only. The body does not count: four
+ * reposts of "I built 59 free browser-based dev tools in vanilla JS" evidenced
+ * a critical `rsa` gap through a "RSA & ECC Key Generator" line 1,330
+ * characters into the post. A package named by an ordinary English word also
+ * needs an ecosystem cue, which may come from the body.
+ */
+export function citesDependency(item, packageName, linker) {
+    if (isAdvisoryRow(item)) {
+        if (linker)
+            return linker.itemsFor(packageName).has(item.id);
+        const subject = advisorySubject(item.title || "");
+        return subject !== null && samePackage(subject, packageName);
+    }
+    if (!item.title_lower.includes(packageName.toLowerCase()))
+        return false;
+    if (!mentionsPackage(item.title || "", packageName))
+        return false;
+    return !GENERIC_WORD_DEPS.has(packageName.toLowerCase()) || hasEcosystemCue(item);
+}
+/**
+ * `knowledge_decay::normalize_gap_title`: lowercase, punctuation stripped,
+ * first ten words. Reposts of one story share it.
+ */
+export function normalizeGapTitle(title) {
+    return title
+        .toLowerCase()
+        .replace(/[^\p{Alphabetic}\p{N}\s]/gu, "")
+        .split(/\s+/)
+        .filter(Boolean)
+        .slice(0, 10)
+        .join(" ");
+}

package/dist/tools/knowledge-gap-exposure.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Knowledge-gap exposure: which stored advisories reach the installs a gap
+ * names, and each advisory ROW's live verdict. The MCP twin of the app's
+ * `osv::exposure::advisory_row_reaches` and `knowledge_decay::{
+ * installs_still_vulnerable, affected_project_paths, advisory_tier_for}`
+ * (AD-045: an advisory is judged against the install it names, in the
+ * install's own ecosystem).
+ *
+ * The first cut read one package-wide verdict from every stored advisory at
+ * once, so one unreadable row, one sibling project's version, or another
+ * ecosystem's same-named package decided the gap for every project in it.
+ */
+import type { FourDADatabase } from "../db.js";
+import { type Exposure } from "./knowledge-gap-grading.js";
+import { type Install } from "./knowledge-gap-installs.js";
+import { type AdvisoryRangeEvent, type AdvisoryTier } from "./knowledge-gap-ranges.js";
+/** One stored advisory record for one (package, ecosystem). */
+export interface AdvisoryEntry {
+    packageName: string;
+    /** Null when the table predates its ecosystem column. */
+    ecosystem: string | null;
+    /** Null when `affected_ranges` is missing or unreadable. */
+    ranges: AdvisoryRangeEvent[][] | null;
+    tier: AdvisoryTier | null;
+}
+/**
+ * An advisory row's verdict against the installs its gap names.
+ * - `reached`: some install sits inside one of the row's advisories.
+ * - `clear`: every install is outside them — fixed at or below the installed
+ *   version, or a package of the same name in another ecosystem.
+ * - `unknown`: an install whose version (or the row's ranges) cannot be read.
+ *   Kept conservatively: an unknown install stays exposed (AD-040 rule 3).
+ */
+export type RowVerdict = "reached" | "clear" | "unknown";
+/**
+ * One install against every stored advisory for its package, judged advisory
+ * by advisory: exposed if any readable advisory of its ecosystem contains it,
+ * safe if every readable one excludes it, unknown only when nothing readable
+ * exists (or its version cannot be read). An unreadable row is simply not
+ * evidence: it no longer turns a patched package into an unknown one, and
+ * unknown into "vulnerable".
+ */
+export declare function installExposure(install: Install, entries: AdvisoryEntry[]): Exposure;
+/** A gap's exposure: exposed if any install is, unknown if any install is, else safe. */
+export declare function gapExposure(installs: Install[], entries: AdvisoryEntry[]): Exposure;
+/** An advisory row's entries against the installs its gap names (`advisory_row_reaches`). */
+export declare function rowVerdict(entries: AdvisoryEntry[], installs: Install[]): RowVerdict;
+/**
+ * The tier of the most severe stored advisory that contains an install the
+ * gap names, in that install's ecosystem (`knowledge_decay::advisory_tier_for`),
+ * or null when none of the reaching advisories is graded.
+ */
+export declare function reachingTier(entries: AdvisoryEntry[], installs: Install[]): AdvisoryTier | null;
+/** Read access to the OSV mirror (`osv_advisories`), feature-detected column by column. */
+export declare class AdvisoryStore {
+    private readonly byPackage;
+    private readonly byId;
+    private readonly idMatchesAliases;
+    private readonly rowsById;
+    constructor(db: FourDADatabase);
+    /** Every live advisory stored for this dependency, in any ecosystem. */
+    forPackage(name: string): AdvisoryEntry[];
+    /**
+     * The entries for dependency `name` that an advisory ROW stands for
+     * (`osv::exposure::advisory_records`). An osv row carries its advisory id in
+     * `source_items.source_id`; a cve row carries the CVE id, which the mirror
+     * keeps in `aliases` (a JSON array). Names compare case-insensitively with
+     * `-` equal to `_`. Null when the row resolves to no stored entry for this
+     * dependency: the caller keeps its conservative fallback.
+     */
+    forRow(sourceId: string | null | undefined, name: string): AdvisoryEntry[] | null;
+}

package/dist/tools/knowledge-gap-exposure.js

@@ -0,0 +1,160 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Knowledge-gap exposure: which stored advisories reach the installs a gap
+ * names, and each advisory ROW's live verdict. The MCP twin of the app's
+ * `osv::exposure::advisory_row_reaches` and `knowledge_decay::{
+ * installs_still_vulnerable, affected_project_paths, advisory_tier_for}`
+ * (AD-045: an advisory is judged against the install it names, in the
+ * install's own ecosystem).
+ *
+ * The first cut read one package-wide verdict from every stored advisory at
+ * once, so one unreadable row, one sibling project's version, or another
+ * ecosystem's same-named package decided the gap for every project in it.
+ */
+import { parseSemverPrecedence } from "../live/semver-precedence.js";
+import { samePackage } from "./knowledge-gap-grading.js";
+import { denotes, otherSpelling, sameEcosystem } from "./knowledge-gap-installs.js";
+import { advisoryTier, moreSevereTier, parseAffectedRanges, rangesContain, } from "./knowledge-gap-ranges.js";
+import { allRows } from "./knowledge-gap-scope.js";
+/**
+ * An advisory counts against an install only for the install's own
+ * ecosystem; when either side's ecosystem is unknown it is judged against
+ * every record, as `advisory_row_reaches` does.
+ */
+function appliesTo(entry, install) {
+    return entry.ecosystem === null || install.ecosystem === null || sameEcosystem(entry.ecosystem, install.ecosystem);
+}
+/** Inside the entry's readable ranges: true/false; null when either side cannot be read. */
+function contains(entry, install) {
+    if (entry.ranges === null || install.version === null)
+        return null;
+    return rangesContain(entry.ranges, install.version);
+}
+/**
+ * One install against every stored advisory for its package, judged advisory
+ * by advisory: exposed if any readable advisory of its ecosystem contains it,
+ * safe if every readable one excludes it, unknown only when nothing readable
+ * exists (or its version cannot be read). An unreadable row is simply not
+ * evidence: it no longer turns a patched package into an unknown one, and
+ * unknown into "vulnerable".
+ */
+export function installExposure(install, entries) {
+    if (install.version === null || parseSemverPrecedence(install.version) === null)
+        return "unknown";
+    const readable = entries.filter((e) => appliesTo(e, install) && e.ranges !== null);
+    if (readable.length === 0)
+        return "unknown";
+    return readable.some((e) => contains(e, install) === true) ? "exposed" : "safe";
+}
+/** A gap's exposure: exposed if any install is, unknown if any install is, else safe. */
+export function gapExposure(installs, entries) {
+    const verdicts = installs.map((install) => installExposure(install, entries));
+    if (verdicts.includes("exposed"))
+        return "exposed";
+    return verdicts.length === 0 || verdicts.includes("unknown") ? "unknown" : "safe";
+}
+/** An advisory row's entries against the installs its gap names (`advisory_row_reaches`). */
+export function rowVerdict(entries, installs) {
+    let unknown = installs.length === 0;
+    for (const install of installs) {
+        const applicable = entries.filter((e) => appliesTo(e, install));
+        if (applicable.length === 0)
+            continue; // another ecosystem's package of the same name
+        let judged = false;
+        for (const entry of applicable) {
+            const inside = contains(entry, install);
+            if (inside === true)
+                return "reached";
+            if (inside === false)
+                judged = true;
+        }
+        if (!judged)
+            unknown = true;
+    }
+    return unknown ? "unknown" : "clear";
+}
+/**
+ * The tier of the most severe stored advisory that contains an install the
+ * gap names, in that install's ecosystem (`knowledge_decay::advisory_tier_for`),
+ * or null when none of the reaching advisories is graded.
+ */
+export function reachingTier(entries, installs) {
+    let best = null;
+    for (const entry of entries) {
+        if (entry.tier === null)
+            continue;
+        if (installs.some((install) => appliesTo(entry, install) && contains(entry, install) === true)) {
+            best = moreSevereTier(best, entry.tier);
+        }
+    }
+    return best;
+}
+function toEntry(row) {
+    return {
+        packageName: row.package_name,
+        ecosystem: row.ecosystem,
+        ranges: parseAffectedRanges(row.affected_ranges),
+        tier: advisoryTier(row.cvss_score, row.severity_label),
+    };
+}
+/** Read access to the OSV mirror (`osv_advisories`), feature-detected column by column. */
+export class AdvisoryStore {
+    byPackage = null;
+    byId = null;
+    idMatchesAliases = false;
+    rowsById = new Map();
+    constructor(db) {
+        const has = (column) => db.hasColumn("osv_advisories", column);
+        if (!has("package_name") || !has("affected_ranges"))
+            return;
+        const columns = [
+            "package_name",
+            has("ecosystem") ? "ecosystem" : "NULL AS ecosystem",
+            "affected_ranges",
+            has("cvss_score") ? "cvss_score" : "NULL AS cvss_score",
+            has("severity_label") ? "severity_label" : "NULL AS severity_label",
+        ].join(", ");
+        const live = has("withdrawn_at") ? "AND withdrawn_at IS NULL" : "";
+        const raw = db.getRawDb();
+        try {
+            this.byPackage = raw.prepare(`SELECT ${columns} FROM osv_advisories WHERE lower(package_name) IN (lower(?), lower(?)) ${live}`);
+            if (has("advisory_id")) {
+                this.idMatchesAliases = has("aliases");
+                const match = this.idMatchesAliases ? "(advisory_id = ? OR aliases LIKE ? ESCAPE '\\')" : "advisory_id = ?";
+                this.byId = raw.prepare(`SELECT ${columns} FROM osv_advisories WHERE ${match} ${live}`);
+            }
+        }
+        catch {
+            // An unreadable mirror is no mirror: every verdict stays conservative.
+        }
+    }
+    /** Every live advisory stored for this dependency, in any ecosystem. */
+    forPackage(name) {
+        if (!this.byPackage)
+            return [];
+        return allRows(this.byPackage, name, otherSpelling(name))
+            .filter((row) => denotes(row.package_name, row.ecosystem, name))
+            .map(toEntry);
+    }
+    /**
+     * The entries for dependency `name` that an advisory ROW stands for
+     * (`osv::exposure::advisory_records`). An osv row carries its advisory id in
+     * `source_items.source_id`; a cve row carries the CVE id, which the mirror
+     * keeps in `aliases` (a JSON array). Names compare case-insensitively with
+     * `-` equal to `_`. Null when the row resolves to no stored entry for this
+     * dependency: the caller keeps its conservative fallback.
+     */
+    forRow(sourceId, name) {
+        const id = (sourceId ?? "").trim();
+        if (!this.byId || id === "")
+            return null;
+        let rows = this.rowsById.get(id);
+        if (!rows) {
+            const args = this.idMatchesAliases ? [id, `%"${id.replace(/[\\%_]/g, "\\$&")}"%`] : [id];
+            rows = allRows(this.byId, ...args);
+            this.rowsById.set(id, rows);
+        }
+        const mine = rows.filter((row) => samePackage(row.package_name, name));
+        return mine.length > 0 ? mine.map(toEntry) : null;
+    }
+}