@4da/mcp-server 6.2.4 → 6.2.5

package/dist/db.js

@@ -34,37 +34,66 @@ export function nativeBindingProblem() {
 }
 import { dbRecoveryNote, readDbRecoveredMarker, readEngineBlockMarker } from "./freshness-markers.js";
 /**
- * Resolve the database path by checking multiple locations in priority order:
- * 1. FOURDA_DB_PATH env var
- * 2. data/4da.db relative to cwd: the desktop app's development database,
- *    when the server is started in a checkout of the app's repository
- * 3. The deployed desktop app's database (desktopAppDbPaths)
- * 4. Otherwise the standalone database (standaloneDbPath), created on first use
+ * Resolve the database path, in priority order:
+ * 1. FOURDA_DB_PATH (relative paths resolve against cwd). A relative path
+ *    must name an existing file; an absolute one may name a new file in an
+ *    existing directory, which becomes a standalone database (see
+ *    explicitDbPathProblem()).
+ * 2. The deployed desktop app's database (desktopAppDbPaths)
+ * 3. Otherwise the standalone database (standaloneDbPath), created on first use
  *
- * Until 6.0.2 a step between 2 and 3 looked for data/4da.db two directories
- * above this file, which found the app's database while this server was the
- * app repository's mcp-4da-server/ folder. Since the server moved to its own
- * repository (6.0.1) that resolves to node_modules/@4da/ or to the folder
- * holding a clone, never to an app database, so it was removed.
+ * Nothing is discovered from the working directory. Until 6.2.5 a
+ * `data/4da.db` under cwd was adopted (meant for the app repository's
+ * development database): any cloned repository could plant one, its rows came
+ * back as the user's own decisions, and a standalone-looking file was reopened
+ * writable (audit 2026-10-12, B-4/B-5). The app repository's `.mcp.json` sets
+ * FOURDA_DB_PATH explicitly instead.
  */
-function getDefaultDbPath() {
-    // 1. Environment variable (highest priority)
-    if (process.env.FOURDA_DB_PATH) {
-        return process.env.FOURDA_DB_PATH;
-    }
-    // 2. Relative to cwd (the app repository's development database)
-    const cwdPath = path.resolve(process.cwd(), "data", "4da.db");
-    if (fs.existsSync(cwdPath)) {
-        return cwdPath;
-    }
-    // 3. The desktop app's own database, where the deployed app keeps it.
+export function getDefaultDbPath() {
+    const explicit = process.env.FOURDA_DB_PATH?.trim();
+    if (explicit)
+        return path.resolve(process.cwd(), explicit);
     for (const appDataPath of desktopAppDbPaths()) {
         if (fs.existsSync(appDataPath))
             return appDataPath;
     }
-    // 4. No desktop database: the standalone database, in the user's data dir.
     return standaloneDbPath();
 }
+/**
+ * Why the explicit FOURDA_DB_PATH cannot be used, or null.
+ *
+ * - An existing file: used.
+ * - A RELATIVE path naming no file is refused. It resolves against whatever
+ *   directory the host started the server in: `./data/4da.db` from 4DA's
+ *   `.mcp.json` silently created a fresh standalone database named like the
+ *   app's inside any repository, and every decision and memory written there
+ *   was lost to the real one (audit B-5).
+ * - An ABSOLUTE path naming no file, in a directory that exists, is a
+ *   deliberate choice of where the standalone database lives (the G7 agent
+ *   eval sets `<run>/server-home/standalone.db`): it is created, and the
+ *   first tool answer says so (FourDADatabase.takeCreationNote()).
+ * - An absolute path whose directory does not exist is refused: a typo there
+ *   would otherwise create directories.
+ */
+export function explicitDbPathProblem(env = process.env) {
+    const explicit = env.FOURDA_DB_PATH?.trim();
+    if (!explicit)
+        return null;
+    const absolute = path.resolve(process.cwd(), explicit);
+    if (fs.existsSync(absolute))
+        return null;
+    if (path.isAbsolute(explicit)) {
+        if (fs.existsSync(path.dirname(absolute)))
+            return null;
+        return (`FOURDA_DB_PATH is set to "${explicit}", but its directory ${path.dirname(absolute)} does not exist. ` +
+            `Nothing was created. Create the directory to have a new standalone database made there, point ` +
+            `FOURDA_DB_PATH at an existing 4DA database, or unset it to use the desktop app's database or this server's own.`);
+    }
+    return (`FOURDA_DB_PATH is set to the relative path "${explicit}", but there is no database at ${absolute} ` +
+        `(relative paths resolve against the server's working directory). Nothing was created there. Point it at an ` +
+        `existing 4DA database, use an absolute path to have a new standalone database created, or unset it to use ` +
+        `the desktop app's database or this server's own.`);
+}
 /**
  * Where the deployed desktop app keeps its database, mirroring
  * `src-tauri/src/state.rs::get_db_path` / `get_platform_data_dir`:
@@ -266,13 +295,32 @@ export class FourDADatabase {
     _isStandalone = false;
     /** Absolute path of the open database file. */
     dbPath;
+    /** Set when this open created the database at an explicit FOURDA_DB_PATH; reported once. */
+    creationNote = null;
+    /** "Created a new standalone database at ..." the first time it is asked after the database was created there; null afterwards. */
+    takeCreationNote() {
+        const note = this.creationNote;
+        this.creationNote = null;
+        return note;
+    }
     constructor(dbPath) {
+        // An explicit argument (tests, tools) may create a new file; the env var may not.
+        if (!dbPath) {
+            const problem = explicitDbPathProblem();
+            if (problem)
+                throw new Error(problem);
+        }
         const resolvedPath = dbPath || getDefaultDbPath();
         // Resolve path - if relative, resolve from cwd
         const absolutePath = path.isAbsolute(resolvedPath)
             ? resolvedPath
             : path.resolve(process.cwd(), resolvedPath);
         const isNew = !fs.existsSync(absolutePath);
+        const envPath = process.env.FOURDA_DB_PATH?.trim();
+        if (isNew && !dbPath && envPath && path.resolve(process.cwd(), envPath) === path.resolve(absolutePath)) {
+            this.creationNote = `Created a new standalone database at ${absolutePath}: FOURDA_DB_PATH named no existing file.`;
+            console.error(`[4DA] ${this.creationNote}`);
+        }
         // Ensure parent directory exists (standalone mode may need to create it)
         if (isNew) {
             const dir = path.dirname(absolutePath);
@@ -441,6 +489,13 @@ export class FourDADatabase {
         const absolutePath = path.isAbsolute(resolvedPath)
             ? resolvedPath
             : path.resolve(process.cwd(), resolvedPath);
+        // The path FOURDA_DB_PATH names is never created: report it, not standalone.
+        const envPath = process.env.FOURDA_DB_PATH?.trim();
+        if (envPath && path.resolve(process.cwd(), envPath) === path.resolve(absolutePath)) {
+            const problem = explicitDbPathProblem();
+            if (problem)
+                return { valid: false, standalone: false, error: problem };
+        }
         // Check if file exists — if not, standalone mode will create it
         if (!fs.existsSync(absolutePath)) {
             return {

package/dist/doctor.js

@@ -13,7 +13,7 @@
  *   4da-mcp --doctor
  */
 import { existsSync } from "node:fs";
-import { FourDADatabase } from "./db.js";
+import { explicitDbPathProblem, FourDADatabase } from "./db.js";
 import { NODE_SQLITE_MIN, sqliteDriverStatus } from "./sqlite-driver.js";
 import { checkBuildStaleness } from "./build-staleness.js";
 export function runDoctor() {
@@ -76,10 +76,13 @@ export function runDoctor() {
     const envDb = process.env.FOURDA_DB_PATH;
     if (envDb) {
         const envExists = existsSync(envDb);
+        const problem = explicitDbPathProblem();
         checks.push({
             name: "FOURDA_DB_PATH",
-            status: envExists ? "pass" : "fail",
-            detail: envExists ? envDb : `Set to ${envDb} but file does not exist`,
+            status: envExists ? "pass" : problem ? "fail" : "warn",
+            detail: envExists
+                ? envDb
+                : problem ?? `Set to ${envDb}, which does not exist yet: the server creates a new standalone database there on first use.`,
         });
     }
     // 5. Build freshness — repo checkouts only. `.mcp.json` runs dist/, and

package/dist/embeddings.d.ts

@@ -17,7 +17,7 @@
  * No sqlite-vec: similarity is a plain JS cosine over Float32 BLOBs, which is
  * trivially fast for the few-hundred-row local knowledge tables this serves.
  */
-import type { FourDADatabase } from "./db.js";
+import { type FourDADatabase } from "./db.js";
 export interface EmbeddingConfig {
     provider: "ollama" | "openai";
     model: string;

package/dist/embeddings.js

@@ -19,9 +19,8 @@
  * trivially fast for the few-hundred-row local knowledge tables this serves.
  */
 import { readFileSync, existsSync, statSync } from "node:fs";
-import { join, dirname } from "node:path";
-import { fileURLToPath } from "node:url";
-const __dirname = dirname(fileURLToPath(import.meta.url));
+import { join, dirname, resolve } from "node:path";
+import { desktopAppDbPaths } from "./db.js";
 const DEFAULT_OLLAMA_EMBED_MODEL = "nomic-embed-text";
 const DEFAULT_OPENAI_EMBED_MODEL = "text-embedding-3-small";
 const DEFAULT_OLLAMA_URL = "http://localhost:11434";
@@ -30,25 +29,28 @@ export function isOfflineMode() {
     return String(process.env.FOURDA_OFFLINE || "").toLowerCase() === "true";
 }
 /**
- * Locate settings.json the same way llm.ts does, so embedding config lives
- * alongside the rest of the user's local configuration.
+ * Locate settings.json: FOURDA_SETTINGS_PATH, else the one beside an explicit
+ * FOURDA_DB_PATH (relative paths resolve against cwd, as the database's do),
+ * else the desktop app's own data directory.
+ *
+ * Never the working directory or its parent. Until 6.2.5 `cwd/data`,
+ * `cwd/../data` and the package's own `../data` were searched, so a cloned
+ * repository with `data/settings.json` could point semantic recall at any
+ * host, and stored agent memory and decisions were sent there to be embedded
+ * (audit 2026-10-12, B-3).
  */
 function findSettingsFile() {
-    const envPath = process.env.FOURDA_SETTINGS_PATH;
+    const envPath = process.env.FOURDA_SETTINGS_PATH?.trim();
     if (envPath && existsSync(envPath))
         return envPath;
-    const dbPath = process.env.FOURDA_DB_PATH;
+    const dbPath = process.env.FOURDA_DB_PATH?.trim();
     if (dbPath) {
-        const sibling = join(dirname(dbPath), "settings.json");
+        const sibling = join(dirname(resolve(process.cwd(), dbPath)), "settings.json");
         if (existsSync(sibling))
             return sibling;
     }
-    const candidates = [
-        join(process.cwd(), "data", "settings.json"),
-        join(__dirname, "..", "data", "settings.json"),
-        join(process.cwd(), "..", "data", "settings.json"),
-    ];
-    for (const candidate of candidates) {
+    for (const appDb of desktopAppDbPaths()) {
+        const candidate = join(dirname(appDb), "settings.json");
         if (existsSync(candidate))
             return candidate;
     }

package/dist/index.js

@@ -35,21 +35,20 @@
  */
 import { serveStdio } from "@modelcontextprotocol/server/stdio";
 import { Server } from "@modelcontextprotocol/server";
-import { readFileSync, existsSync } from "node:fs";
+import { readFileSync } from "node:fs";
 import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
-import { homedir } from "node:os";
 import { startHttpServer } from "./http-transport.js";
 import { runSetup } from "./setup.js";
 import { runDoctor } from "./doctor.js";
-import { scanProjectTree, treeResolutionGroups } from "./project-tree.js";
+import { exclusionNotes, scanProjectTree, treeResolutionGroups } from "./project-tree.js";
 import { IgnoreRules } from "./gitignore.js";
 import { LiveIntelligence } from "./live/index.js";
 import { setLiveIntelligence } from "./live-singleton.js";
 import { SERVER_INSTRUCTIONS } from "./server-instructions.js";
 import { validateToolArgs } from "./tool-args.js";
 // Tool registry: listing, schema resources, category metadata
-import { getCategoryManifest, getSchemaResources, getSlimToolList, getToolSchemaDocument, hasToolSchema, TOOL_REGISTRY, } from "./schema-registry.js";
+import { getSlimToolList, listResources, readResource, startupToolsLine, toolEntry, unknownPromptError, unknownToolError, } from "./schema-registry.js";
 // Map-based tool dispatch (replaces per-tool imports + switch statement)
 import { DATABASE_FREE_TOOLS, dispatchTool } from "./tool-dispatch.js";
 import { SqliteUnavailableError, sqliteDriverStatus } from "./sqlite-driver.js";
@@ -95,8 +94,10 @@ let liveIntel = null;
  */
 function getDatabase() {
     if (!db) {
-        const dbPath = process.env.FOURDA_DB_PATH;
-        db = createDatabase(dbPath);
+        // No argument: the constructor resolves FOURDA_DB_PATH itself and applies
+        // its rules (a relative path must exist). Passing the env value as an
+        // explicit path bypassed them.
+        db = createDatabase();
         // Initialize live intelligence layer
         liveIntel = new LiveIntelligence(db.getRawDb());
         setLiveIntelligence(liveIntel);
@@ -117,12 +118,16 @@ function getDatabase() {
                 ...scan.frameworks,
             ].filter(Boolean);
             console.error(`[4DA] Standalone mode: scanned ${scan.projectPath} (${tree.length} project${tree.length === 1 ? "" : "s"})`);
+            // Initialize live intelligence with per-ecosystem resolved versions
+            // (targets carry platform-gated dep info so advisories can be flagged
+            // platform-relevant for the host). Also with NO groups: the walk's
+            // report of what it found but does not read (pom.xml, build.gradle,
+            // test-fixture lockfiles) is what every tool's coverage note is built
+            // from. Started inside spring-petclinic, 6.2.5 kept nothing and said
+            // "none of an unsupported one either" (readiness audit H3).
+            liveIntel.initFromProjectTree(cwd, groups, discovery);
             if (groups.length > 0) {
                 console.error(`[4DA]   Detected: ${detected.join(", ") || "lockfiles"} | ${scan.dependencies.length} deps, ${scan.devDependencies.length} dev deps at the root`);
-                // Initialize live intelligence with per-ecosystem resolved versions
-                // (targets carry platform-gated dep info so advisories can be flagged
-                // platform-relevant for the host).
-                liveIntel.initFromProjectTree(cwd, groups, discovery);
                 if (liveIntel.isEnabled()) {
                     console.error(`[4DA]   Live intelligence: enabled (OSV.dev)`);
                     // The vulnerability scan goes through the warmup so a briefing that
@@ -133,7 +138,7 @@ function getDatabase() {
                 }
             }
             else {
-                console.error(`[4DA]   No project manifests found in ${cwd} — tools will return empty results`);
+                console.error(`[4DA]   ${noSupportedProjectNote(cwd, discovery)}`);
             }
         }
         else {
@@ -180,6 +185,18 @@ function getDatabase() {
                 if (groups.size > 0) {
                     liveIntel.initFromDependencyGroups([...groups.values()]);
                 }
+                else {
+                    // The app tracks nothing under this directory (it indexes the
+                    // projects it was pointed at, not every directory a host starts the
+                    // server in). Its tables say nothing about this project, so read it
+                    // from disk as standalone mode does; never write the scan into the
+                    // app's database. Without this every tool read the project as empty
+                    // and the planner answered "0 steps" (audit 6.2.5 D-1).
+                    const root = resolveProjectDir();
+                    const { entries: tree, discovery } = scanProjectTree(root);
+                    liveIntel.initFromProjectTree(root, treeResolutionGroups(tree), discovery);
+                    console.error(`[4DA]   The 4DA app tracks no project at ${root}; reading its lockfiles directly.`);
+                }
                 // Headlines are fetched only when ecosystem_pulse is called: the
                 // search terms come from the user's projects.
                 if (liveIntel.isEnabled()) {
@@ -222,12 +239,22 @@ function initWithoutDatabase() {
     const { entries, discovery } = scanProjectTree(cwd);
     const groups = treeResolutionGroups(entries);
     console.error(`[4DA] No SQLite driver: the dependency tools run without a database (${cwd}).`);
-    if (groups.length === 0)
-        return;
+    // Kept with no groups too: the coverage notes come from the walk (H3).
     liveIntel.initFromProjectTree(cwd, groups, discovery);
+    if (groups.length === 0) {
+        console.error(`[4DA]   ${noSupportedProjectNote(cwd, discovery)}`);
+        return;
+    }
     if (liveIntel.isEnabled())
         liveIntel.startVulnerabilityWarmup(cwd);
 }
+/** The startup line for a directory with no lockfile this server reads: what it did find, never just "nothing". */
+function noSupportedProjectNote(cwd, discovery) {
+    const notes = exclusionNotes(discovery);
+    return notes.length > 0
+        ? `No lockfile of a supported ecosystem in ${cwd}. ${notes.join(" ")}`
+        : `No project manifests found in ${cwd} — tools will return empty results`;
+}
 /** The database for a tool call; null only for a database-free tool when no SQLite driver is usable. */
 function databaseFor(tool) {
     try {
@@ -306,108 +333,43 @@ export function buildServer() {
             tools: getSlimToolList(isStandaloneMode() ? true : undefined),
         };
     });
-    // List schema resources: full tool schemas as MCP Resources for lazy
-    // loading, plus the skill and category manifests.
-    server.setRequestHandler("resources/list", async () => {
-        const resources = [
-            ...getSchemaResources(),
-            // Skill manifest for agent dispatch
-            {
-                uri: "4da://skills",
-                name: "Skill manifest",
-                description: "Registry of 4DA skills for Claude Code agent dispatch",
-                mimeType: "application/json",
-            },
-            // Category manifest for tool discovery
-            {
-                uri: "4da://categories",
-                name: "Tool categories",
-                description: "Tool groupings by category with tag metadata",
-                mimeType: "application/json",
-            },
-        ];
-        return { resources };
-    });
-    // Read a resource (schema or skill manifest)
-    server.setRequestHandler("resources/read", async (request) => {
-        const uri = request.params.uri;
-        // Handle category manifest
-        if (uri === "4da://categories") {
-            return {
-                contents: [
-                    {
-                        uri,
-                        mimeType: "application/json",
-                        text: JSON.stringify(getCategoryManifest(), null, 2),
-                    },
-                ],
-            };
-        }
-        // Handle skill manifest
-        if (uri === "4da://skills") {
-            const skillsPath = join(homedir(), ".local", "share", "4da", "skills", "registry.json");
-            if (!existsSync(skillsPath)) {
-                throw new Error("Skill manifest not found. Run 4DA setup to create it.");
-            }
-            const skillsContent = readFileSync(skillsPath, "utf-8");
-            return {
-                contents: [
-                    {
-                        uri,
-                        mimeType: "application/json",
-                        text: skillsContent,
-                    },
-                ],
-            };
-        }
-        // Parse tool name from URI: 4da://schema/{tool_name}
-        const match = uri.match(/^4da:\/\/schema\/(.+)$/);
-        if (!match) {
-            throw new Error(`Invalid resource URI: ${uri}`);
-        }
-        const toolName = match[1];
-        const document = hasToolSchema(toolName) ? getToolSchemaDocument(toolName) : null;
-        if (!document) {
-            throw new Error(`Unknown tool: ${toolName}`);
-        }
-        return {
-            contents: [
-                {
-                    uri,
-                    mimeType: "application/json",
-                    text: JSON.stringify(document, null, 2),
-                },
-            ],
-        };
-    });
+    // Resources: every tool's full schema (lazy loading), and the category
+    // manifest. An unknown URI is a resource-not-found protocol error.
+    // Filtered as tools/list is: standalone mode advertised the 5 desktop-only schemas (audit L6).
+    server.setRequestHandler("resources/list", async () => ({ resources: listResources(isStandaloneMode() ? true : undefined) }));
+    server.setRequestHandler("resources/read", async (request) => readResource(request.params.uri, isStandaloneMode() ? true : undefined));
     // Prompts: user-invoked workflows (surfaced as slash commands by some hosts).
     server.setRequestHandler("prompts/list", async () => ({ prompts: listPrompts() }));
     server.setRequestHandler("prompts/get", async (request) => {
         const prompt = getPrompt(request.params.name, request.params.arguments);
-        if (!prompt) {
-            throw new Error(`Unknown prompt: ${request.params.name}`);
-        }
+        if (!prompt)
+            throw unknownPromptError(request.params.name);
         return prompt;
     });
     // Execute a tool
     server.setRequestHandler("tools/call", async (request) => {
         const { name, arguments: args } = request.params;
+        // An unknown tool NAME is a JSON-RPC Invalid Params error (MCP spec), not
+        // a tool result: it used to come back as `isError` content like a tool
+        // that ran and failed.
+        const entry = toolEntry(name);
+        if (!entry)
+            throw unknownToolError(name);
         // Arguments are checked against the published schema before anything
         // runs, so a wrong type or a misspelled parameter comes back as a
         // correctable error rather than a Node exception or a silent no-op.
-        const entry = TOOL_REGISTRY[name];
-        if (entry) {
-            const problem = validateToolArgs(name, entry.definition.inputSchema, (args ?? {}));
-            if (problem) {
-                return {
-                    content: [{ type: "text", text: JSON.stringify({ error: problem }) }],
-                    isError: true,
-                };
-            }
+        const problem = validateToolArgs(name, entry.definition.inputSchema, (args ?? {}));
+        if (problem) {
+            return {
+                content: [{ type: "text", text: JSON.stringify({ error: problem }) }],
+                isError: true,
+            };
         }
         try {
             const database = databaseFor(name);
-            return await dispatchTool(name, database, args);
+            const result = await dispatchTool(name, database, args);
+            const note = database?.takeCreationNote() ?? null;
+            return note ? withDatabaseNote(result, note) : result;
         }
         catch (error) {
             // A database that turns out damaged mid-session (SQLITE_CORRUPT on a
@@ -431,6 +393,15 @@ export function buildServer() {
     });
     return server;
 }
+function withDatabaseNote(result, note) {
+    const r = result;
+    if (r.structuredContent) {
+        const payload = r.structuredContent;
+        const structuredContent = { ...payload, _meta: { ...(payload._meta ?? {}), database_note: note } };
+        return { ...result, structuredContent, content: [{ type: "text", text: JSON.stringify(structuredContent) }] };
+    }
+    return { ...result, content: [...r.content, { type: "text", text: JSON.stringify({ _meta: { database_note: note } }) }] };
+}
 // =============================================================================
 // Server Lifecycle
 // =============================================================================
@@ -593,9 +564,8 @@ async function main() {
             db.close();
         process.exit(0);
     });
-    const toolCount = getSlimToolList(validation.standalone ? true : undefined).length;
-    const toolLabel = validation.standalone ? "standalone tools" : "tools";
-    console.error(`4DA MCP Server v${SERVER_VERSION} started — ${toolCount} ${toolLabel}, stdio transport`);
+    // What this start will serve: with the database refused, every call returns that error (audit L6).
+    console.error(`4DA MCP Server v${SERVER_VERSION} started — ${startupToolsLine(validation, Boolean(sqlite.driver), DATABASE_FREE_TOOLS.size)}, stdio transport`);
     console.error("  Use --http for Streamable HTTP, --setup to configure editors, --doctor to check health");
 }
 main().catch((error) => {

package/dist/live/advisory-groups.d.ts

@@ -0,0 +1,68 @@
+/**
+ * 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 type { VulnerabilityEntry } from "./types.js";
+export interface AdvisoryGroup {
+    /** Every id the group's records carry, aliases included. */
+    ids: Set<string>;
+    /** The most severe record, so merging never softens a verdict. */
+    best: VulnerabilityEntry;
+    members: VulnerabilityEntry[];
+}
+/**
+ * Group the records of ONE installed copy by shared ids. The grouping is transitive: a record
+ * naming ids of two groups joins them.
+ */
+export declare function groupAdvisories(entries: readonly VulnerabilityEntry[] | undefined): AdvisoryGroup[];
+/** One record of an alias group, as the group grade reads it. */
+export interface GradedRecord {
+    id: string;
+    /** Its own grade: the curated label first, the CVSS band second (osv-scanner.ts deriveSeverity); unknown when it has none. */
+    own: VulnerabilityEntry["severity"];
+    aliases: readonly string[];
+    maintenance: boolean;
+    /** The record's CWE ids (`database_specific.cwe_ids`) and summary, for the malware predicate. */
+    cweIds?: readonly string[];
+    summary?: string;
+}
+/** The grade of one alias group, and where it came from. */
+export interface GroupGrade {
+    /** Null when nothing grades it, even through its aliases. */
+    severity: Exclude<VulnerabilityEntry["severity"], "unknown"> | null;
+    /** The GHSA alias an inherited grade came from; null for a grade a record of the group has itself. */
+    inheritedFrom: string | null;
+    /** The group record whose own grade it is, when it is one. */
+    ownFrom: string | null;
+    /**
+     * The base urgency the Upgrade Plan and the alerts rank by, before the scope rule: the tier
+     * (`low` reading `watch`); a group nothing grades is `medium`; a group of maintenance notices only
+     * `watch`; a malicious-package record (MAL-) `high`.
+     */
+    urgency: "critical" | "high" | "medium" | "watch";
+}
+/**
+ * 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 declare function gradeGroup(records: readonly GradedRecord[], aliasGrades: ReadonlyMap<string, VulnerabilityEntry["severity"] | null>): GroupGrade;
+/**
+ * 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 declare function gradeAliasGroups(entries: readonly VulnerabilityEntry[]): VulnerabilityEntry[];
+/** Distinct advisories among the records of one installed copy. */
+export declare function distinctAdvisoryCount(entries: readonly VulnerabilityEntry[] | undefined): number;