@4da/mcp-server 5.0.4 → 6.0.1

package/README.md

@@ -2,30 +2,48 @@
 
 [![npm version](https://img.shields.io/npm/v/@4da/mcp-server?color=gold)](https://www.npmjs.com/package/@4da/mcp-server)
 [![License: Apache-2.0](https://img.shields.io/badge/License-Apache--2.0-blue.svg)](LICENSE)
-[![Node](https://img.shields.io/badge/Node-%3E%3D20-brightgreen)](https://nodejs.org/)
-[![smithery badge](https://smithery.ai/badge/@4da/mcp-server)](https://smithery.ai/server/@4da/mcp-server)
+[![Node](https://img.shields.io/badge/Node-%3E%3D22-brightgreen)](https://nodejs.org/)
+[![CI](https://github.com/4DA-Systems/4da-mcp-server/actions/workflows/ci.yml/badge.svg)](https://github.com/4DA-Systems/4da-mcp-server/actions/workflows/ci.yml)
 
-**Dependency intelligence for AI coding agents.** Live CVE scanning, dependency health checks, upgrade planning, ecosystem news, and persistent decision memory. Zero config, privacy-first.
+**Upgrade intelligence for AI coding agents.** Before your agent bumps a dependency it learns what changes between the version you run and the one you want, which of your files that touches, and which vulnerabilities the move fixes, from your own lockfiles, on your machine. Plus vulnerability scanning at osv-scanner parity, ranked upgrade plans and decision memory. Zero config, no account.
 
 ```
-You:     "Check my dependency health"
-Claude:  Health: 72/100. 47 dependencies scanned, 3 vulnerable, 1 deprecated, 8 outdated.
-
-         CRITICAL  openssl-sys 0.9.93  CVE-2025-4231        -> 0.9.96
-         HIGH      serde       1.0.197 RUSTSEC-2026-12      -> 1.0.210
-         MEDIUM    cookie      0.17.0  deprecated           -> 0.18.1
-
-         Quick wins: 6 patch upgrades, 2 minor. Run upgrade_planner for full plan.
+You:     "Upgrade axum to 0.8"
+Agent →  upgrade_impact { package: "axum", to_version: "0.8.4" }
+
+         axum 0.7.9 -> 0.8.4: 5 releases (0.8.2 yanked), changelog from the 0.8.4 crate.
+         12 breaking entries, 8 touch your code (Path, Query, Router, extract, serve):
+           breaking  Remove OptionalFromRequestParts impl for `Query`        (you use Query)
+           breaking  Require `Sync` for all handlers added to `Router`       (you use Router)
+           ...
+         Your code: 10 files import axum.
 ```
 
-One command to install. No API keys. No accounts. No code leaves your machine.
+*(Real output, abridged, run on this repository, 2026-10-02.)*
+
+One command to install. No API keys. No accounts. Your code never leaves your machine.
 
 ## Install
 
+Requires Node.js 22 or later.
+
+> **npm 12+:** npm 12 blocks dependency install scripts unless you allow them, which leaves the SQLite module (`better-sqlite3`) unbuilt. Allow it once, then clear the npx cache:
+> `npm config set allow-scripts=better-sqlite3 --location=user` and `npx clear-npx-cache`.
+> `npx @4da/mcp-server --doctor` checks this by opening a database. npm 10 and 11, which every current Node release ships, are not affected.
+
 ```bash
 claude mcp add 4da -- npx @4da/mcp-server
 ```
 
+**As a Claude Code plugin** (the MCP server plus a hook):
+
+```bash
+claude plugin marketplace add 4DA-Systems/4da-mcp-server
+claude plugin install 4da@4da
+```
+
+The hook: when your agent edits a dependency's version in `package.json`, `Cargo.toml`, `pyproject.toml`, `requirements.txt` or `go.mod`, it is told which packages moved and given the exact `dependency_check` and `upgrade_impact` calls to make before it installs and builds. The hook is plain Node, contacts nothing, and stays silent for every other edit.
+
 <details>
 <summary><b>Cursor / Windsurf</b></summary>
 
@@ -83,34 +101,39 @@ npx @4da/mcp-server --setup
 ```
 </details>
 
-Then ask your AI: **"Check my dependency health"** or **"Scan for vulnerabilities"**
+Then ask your AI: **"What changes if I upgrade X to Y?"**, **"Scan for vulnerabilities"** or **"What should I upgrade first?"**
 
 ## How It Works
 
-On startup, the server reads your manifest and lock files (`package.json`, `Cargo.toml`, `go.mod`, `pyproject.toml`), resolves exact dependency versions, and queries live APIs:
+The server reads every lockfile of the project it is started in, including independently-locked projects below the root (a repo with `src-tauri/Cargo.lock` beside a root `pnpm-lock.yaml` is scanned whole) and skipping what `.gitignore` excludes: `package-lock.json` / `npm-shrinkwrap.json`, `pnpm-lock.yaml` (v5–v9), `yarn.lock` (v1 and berry), `bun.lock`, `Cargo.lock` (Cargo workspaces included), `poetry.lock`, `uv.lock`, `Pipfile.lock`, `requirements.txt` pins, and `go.mod` / `go.sum` (Go's build list). Every installed copy is scanned, not one version per name, with the lockfile's own dev flags. It re-reads them whenever a lockfile changes, and for npm it also checks what `node_modules` actually holds.
+
+Measured against osv-scanner on 12 projects (npm, pnpm, Cargo, Poetry, requirements.txt, Go): precision 1.00, recall 0.995; re-run before release from the installed package on those and 11 more never used to build the readers (yarn, pnpm, bun, uv, Pipfile, Go included), with every difference settled by OSV or Go's own build list.
 
-- **OSV.dev** for known CVEs across all ecosystems
-- **npm registry** for version freshness, deprecation status, and weekly downloads
-- **crates.io sparse index** for Rust package versions (avoids the 1 req/s API limit)
-- **PyPI JSON API** for Python package metadata with license normalization
-- **Go module proxy** for Go module versions
-- **Hacker News Algolia API** for ecosystem news filtered by your tech stack
+- **OSV.dev** for known vulnerabilities, matched to exact installed versions
+- **npm registry, crates.io, PyPI, Go module proxy** for versions, deprecations and yanks
+- **The package's own registry archive** (registry.npmjs.org, static.crates.io) for the changelog `upgrade_impact` reads; never GitHub
+- **npm full packument** and the **crates.io versions API** for `dependency_check` (publish times, publishers, install scripts, per-version dependencies). These requests carry the package name only; the version you have installed is never sent to a registry. Packuments are cached on disk and revalidated with `If-None-Match`; crates.io API reads are spaced one per second.
+- **Hacker News Algolia API**, only when you call `ecosystem_pulse`
 
 Results are cached (24h for registry data, 1h for vulnerabilities, 30min for news) and rate-limited per source.
 
-**What's sent over the network:** package names + versions, generic tech keywords. The same data visible in your `package.json`. No source code, no file paths, no personal data. Set `FOURDA_OFFLINE=true` to disable all network calls.
+**What's sent over the network:** package names and versions (the same data visible in your lockfile), and, only for `ecosystem_pulse`, the names of a few of your dependencies as search terms. No source code, no file paths, no personal data. The call-site scan of `upgrade_impact` runs locally. Set `FOURDA_OFFLINE=true` to disable all network calls.
 
 > The one exception: if you *explicitly* configure an OpenAI embedding provider (`FOURDA_EMBED_PROVIDER=openai`) for semantic recall, the decision/memory text you store is sent to OpenAI to be embedded. The default — no embedding provider, or a local Ollama one — keeps everything on your machine, and `FOURDA_OFFLINE=true` overrides it regardless.
 
-**Ecosystems supported:** npm, crates.io (Rust), PyPI (Python), Go.
+**Ecosystems supported:** npm, crates.io (Rust), PyPI (Python), Go. `upgrade_impact`: npm and crates.io.
+
+**Known limits, stated plainly:** a `requirements.txt` without a lockfile names only your direct pins, so their transitive dependencies are not scanned (use `uv lock`, `poetry lock` or `pip-compile`). Many packages ship no changelog in their registry archive (fastembed, vite, zod among them); `upgrade_impact` then says so and gives the release-notes URL instead of guessing. Breaking entries are flagged from the changelog's headings and wording, and every entry carries the heading it sits under (`under`). Measured on 47 upgrades never used to build the rules, against three blind raters who saw each entry's heading: 99% of entries flagged breaking were breaking (95% CI 95-100%) and about 65% of breaking entries were flagged. Earlier corpora, before the last parser fixes, measured 73-87%, so treat the flags as a pre-sort: read every entry of a major upgrade. Each answer says this in `_meta.classification`.
 
 ## What You Can Ask
 
 ```
+"What changes if I upgrade axum to 0.8?"      -> upgrade_impact
 "Check my dependency health"                  -> dependency_health
 "Scan for vulnerabilities"                    -> vulnerability_scan
 "Which deps should I upgrade first?"          -> upgrade_planner
-"What should I know before I start coding?"   -> what_should_i_know
+"Is it safe to bump axios to 1.14.1?"         -> dependency_check
+"I'm about to bump fastembed 5 -> 7"          -> what_should_i_know
 "What's happening in the ecosystem?"          -> ecosystem_pulse
 "What's my tech stack?"                       -> get_context
 "Record a decision: we chose Postgres"        -> decision_memory
@@ -118,26 +141,28 @@ Results are cached (24h for registry data, 1h for vulnerabilities, 30min for new
 "Remember: never use ORM for batch inserts"   -> agent_memory
 ```
 
-## All 14 Tools
+## All 16 Tools
 
 ### Dependency Security
 
 | Tool | What it does |
 |------|-------------|
-| `vulnerability_scan` | Live CVE scanning via OSV.dev. Severity, fix versions, CVSS scores. |
-| `dependency_health` | Health score (0-100) + version freshness, deprecation, CVE counts per dependency. |
-| `upgrade_planner` | Ranked upgrade recommendations. Quick wins vs. breaking changes. Risk-sorted. |
+| `upgrade_impact` | What changes between the installed and a target version of one dependency: releases in between, changelog entries classified breaking / deprecation / security, the breaking ones that touch your code (symbols you import, and route or pattern syntax in your string literals, e.g. axum 0.8's `/:id` -> `/{id}`), the files that import it, advisories fixed. |
+| `vulnerability_scan` | Every installed copy in every lockfile matched against OSV.dev. Scope-adjusted severity, the fix version on your release line, where each version is pinned. Concise by default (one row per vulnerable package version, the 40 most severe, about 4k tokens on a 290-advisory project); `package` for one dependency; `response_format: "detailed"` for every advisory. |
+| `dependency_health` | Version freshness, deprecation (of the version you run) and vulnerability counts per dependency. |
+| `upgrade_planner` | The smallest version that fixes each vulnerability, majors flagged, transitive fixes waiting on upstream. `package` for a one-package plan. |
+| `dependency_check` | Call before adding a dependency or applying a bump. Verdict per item (`proceed` / `wait` / `review` / `avoid` / `unknown`) with evidence: advisories on the target, release age (holds releases under 3 days unless they fix an advisory you have), publish-trust drop, new install scripts, brand-new transitive dependencies, yanked or deprecated. npm and crates.io. |
 
 ### Intelligence
 
 | Tool | What it does |
 |------|-------------|
-| `what_should_i_know` | Pre-task intelligence briefing: vulns, decisions, signals, ecosystem updates. |
-| `ecosystem_pulse` | Live ecosystem news from Hacker News, filtered by your detected tech stack. |
+| `what_should_i_know` | Pre-task briefing built from the task: the dependencies it names, their versions and confirmed vulnerabilities, majors crossed, your recorded decisions, and a delegation verdict only confirmed evidence can raise. |
+| `ecosystem_pulse` | Hacker News headlines that name your dependencies, then your languages (labelled as such). Fetched only when called. |
 | `get_context` | Your tech stack, resolved dependency versions, interests, detected topics. |
-| `get_relevant_content`* | Scored content feed — articles, advisories, releases ranked by relevance. |
-| `get_actionable_signals`* | Classified alerts: security advisories, breaking changes, trending repos. |
-| `knowledge_gaps`* | Dependencies you use daily but never read about. Surfaces missed CVEs and updates. |
+| `get_relevant_content`* | Scored content feed that passed the desktop app's relevance judge. |
+| `get_actionable_signals`* | Judge-accepted feed items the app classified (advisories, breaking changes), plus your live vulnerabilities. |
+| `knowledge_gaps`* | Dependencies with judge-accepted advisories or releases you have not looked at. |
 | `record_feedback`* | Save or dismiss items so 4DA can record explicit interaction history. |
 
 ### Decisions & Memory
@@ -156,16 +181,22 @@ Results are cached (24h for registry data, 1h for vulnerabilities, 30min for new
 
 *\* Requires the [4DA desktop app](https://4da.ai) for full data.*
 
+### Prompt: `deps`
+
+A user-invoked workflow (shown as a slash command by hosts that surface MCP prompts). It tells the agent to run `upgrade_planner`, check every proposed bump with `dependency_check`, apply only `proceed` items in small batches with the project's own tests after each batch, stop and report every `review` / `avoid` / `wait` / `unknown` item with its evidence, and re-run `vulnerability_scan` at the end. Optional argument `scope` (e.g. `security only`).
+
 ## Standalone vs. Full Mode
 
-The MCP server works without the desktop app. On first run it creates a local database and scans your project:
+The MCP server works without the desktop app. It keeps a small local database in your user data folder (`%LOCALAPPDATA%\4da-mcp`, `~/Library/Application Support/4da-mcp` or `~/.local/share/4da-mcp`, never inside your repository) and scans your project on every start:
 
 | Capability | Standalone | With 4DA Desktop |
 |------------|-----------|-------------------|
+| Upgrade impact (changelog, breaking changes, your call sites) | Yes | Yes |
 | Vulnerability scanning (OSV.dev) | Yes | Yes |
 | Dependency health (4 registries) | Yes | Yes |
 | Upgrade planner | Yes | Yes |
-| Ecosystem news (Hacker News) | Yes | Yes |
+| Pre-install dependency check | Yes | Yes |
+| Ecosystem news (Hacker News, on request) | Yes | Yes |
 | Pre-task intelligence briefing | Yes | Yes |
 | Tech stack detection + resolved versions | Yes | Yes |
 | Decision memory + alignment checking | Yes | Yes |
@@ -226,10 +257,10 @@ npx @4da/mcp-server --version    # Print version
 ## FAQ
 
 **Does this send my code anywhere?**
-No. The server sends package names and versions to public APIs ([OSV.dev](https://osv.dev), npm registry, crates.io, PyPI, Go proxy) and generic tech keywords to [HN Algolia](https://hn.algolia.com/api). The same public data visible in your `package.json`. No source code, no file paths, no personal data. Set `FOURDA_OFFLINE=true` to disable all network calls. (The sole exception is opt-in OpenAI embeddings — see the network note above.)
+No. The server sends package names and versions to public APIs ([OSV.dev](https://osv.dev), npm registry, crates.io, PyPI, Go proxy), downloads the target version's archive from the package's own registry for `upgrade_impact`, and, only when you call `ecosystem_pulse`, sends a few dependency names as search terms to [HN Algolia](https://hn.algolia.com/api). No source code, no file paths, no personal data: the call-site scan runs locally. Set `FOURDA_OFFLINE=true` to disable all network calls. (The sole exception is opt-in OpenAI embeddings — see the network note above.)
 
 **Do I need the 4DA desktop app?**
-No. 9 tools work standalone: vulnerability scanning, dependency health, upgrade planning, ecosystem news, pre-task briefings, project context, decision memory, alignment checking, and agent memory. The desktop app adds a scored content feed from 20+ sources, graded against your actual stack.
+No. 11 tools work standalone: upgrade impact, pre-install dependency checks, vulnerability scanning, dependency health, upgrade planning, ecosystem news, pre-task briefings, project context, decision memory, alignment checking, and agent memory. The desktop app adds a scored content feed from 20+ sources, judged against your actual stack.
 
 **Which AI tools does this work with?**
 Any tool that supports [MCP](https://modelcontextprotocol.io): Claude Code, Claude Desktop, Cursor, Windsurf, VS Code (Copilot), and any custom MCP client.
@@ -237,11 +268,11 @@ Any tool that supports [MCP](https://modelcontextprotocol.io): Claude Code, Clau
 ## Build from Source
 
 ```bash
-git clone https://github.com/4DA-Systems/4DA.git
-cd 4DA/mcp-4da-server
+git clone https://github.com/4DA-Systems/4da-mcp-server.git
+cd 4da-mcp-server
 pnpm install
 pnpm build
-pnpm test    # 71 contract tests
+pnpm test    # offline
 ```
 
 ## License

package/dist/build-staleness.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Build staleness — is the running `dist/` older than `src/`?
+ *
+ * `.mcp.json` runs `node ./mcp-4da-server/dist/index.js`, and nothing rebuilds
+ * `dist/` when a merge lands. 2026-08-30: the live server was a dist built two
+ * days before its src — three already-fixed defects (platform filtering,
+ * knowledge-gap grading, feed hygiene) presented as live bugs and were nearly
+ * re-fixed. The same merged-but-not-running disease as a stale binary, with
+ * zero symptoms.
+ *
+ * This check only means something in a repo checkout: the published npm
+ * package ships no `src/`, so it returns null there (unknown-and-irrelevant,
+ * never a false alarm). In a checkout it compares the newest source mtime
+ * against the newest dist mtime — a `git pull` touches exactly the changed
+ * files, which is exactly the signal needed.
+ */
+export interface BuildStaleness {
+    stale: boolean;
+    /** Newest mtime under src/ (ms). */
+    src_newest_ms: number;
+    /** Newest mtime under dist/ (ms). */
+    dist_newest_ms: number;
+    /** Human-readable remedy, set when stale. */
+    note: string | null;
+}
+/** Reset the memo. Tests only. */
+export declare function _resetBuildStalenessCache(): void;
+/**
+ * Compare `src/` against `dist/` for the package this module runs from.
+ *
+ * Returns null when there is no `src/` beside the running `dist/` (the
+ * published package) or no dist output at all — unknown, never "fresh".
+ * Pass explicit directories in tests.
+ */
+export declare function checkBuildStaleness(distDir?: string, srcDir?: string): BuildStaleness | null;

package/dist/build-staleness.js

@@ -0,0 +1,95 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Build staleness — is the running `dist/` older than `src/`?
+ *
+ * `.mcp.json` runs `node ./mcp-4da-server/dist/index.js`, and nothing rebuilds
+ * `dist/` when a merge lands. 2026-08-30: the live server was a dist built two
+ * days before its src — three already-fixed defects (platform filtering,
+ * knowledge-gap grading, feed hygiene) presented as live bugs and were nearly
+ * re-fixed. The same merged-but-not-running disease as a stale binary, with
+ * zero symptoms.
+ *
+ * This check only means something in a repo checkout: the published npm
+ * package ships no `src/`, so it returns null there (unknown-and-irrelevant,
+ * never a false alarm). In a checkout it compares the newest source mtime
+ * against the newest dist mtime — a `git pull` touches exactly the changed
+ * files, which is exactly the signal needed.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+/** Editable-source extensions that produce build output. */
+const SRC_EXTENSIONS = new Set([".ts", ".json"]);
+/** Skip clock-skew false alarms: src must be newer by more than this. */
+const SKEW_TOLERANCE_MS = 2_000;
+function newestMtimeMs(dir, filter) {
+    let newest = 0;
+    let entries;
+    try {
+        entries = fs.readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return newest;
+    }
+    for (const entry of entries) {
+        const full = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+            if (entry.name === "node_modules" || entry.name.startsWith("."))
+                continue;
+            const sub = newestMtimeMs(full, filter);
+            if (sub > newest)
+                newest = sub;
+        }
+        else if (filter(entry.name)) {
+            try {
+                const m = fs.statSync(full).mtimeMs;
+                if (m > newest)
+                    newest = m;
+            }
+            catch {
+                // A file deleted mid-scan is not a staleness signal.
+            }
+        }
+    }
+    return newest;
+}
+let memo;
+/** Reset the memo. Tests only. */
+export function _resetBuildStalenessCache() {
+    memo = undefined;
+}
+/**
+ * Compare `src/` against `dist/` for the package this module runs from.
+ *
+ * Returns null when there is no `src/` beside the running `dist/` (the
+ * published package) or no dist output at all — unknown, never "fresh".
+ * Pass explicit directories in tests.
+ */
+export function checkBuildStaleness(distDir, srcDir) {
+    if (distDir === undefined && memo !== undefined)
+        return memo;
+    const here = distDir ?? path.dirname(fileURLToPath(import.meta.url));
+    const src = srcDir ?? path.join(here, "..", "src");
+    const result = compute(here, src);
+    if (distDir === undefined)
+        memo = result;
+    return result;
+}
+function compute(distDir, srcDir) {
+    if (!fs.existsSync(srcDir))
+        return null;
+    const srcNewest = newestMtimeMs(srcDir, (n) => SRC_EXTENSIONS.has(path.extname(n)));
+    const distNewest = newestMtimeMs(distDir, (n) => n.endsWith(".js"));
+    if (srcNewest === 0 || distNewest === 0)
+        return null;
+    const stale = srcNewest > distNewest + SKEW_TOLERANCE_MS;
+    const behindMinutes = Math.round((srcNewest - distNewest) / 60_000);
+    return {
+        stale,
+        src_newest_ms: srcNewest,
+        dist_newest_ms: distNewest,
+        note: stale
+            ? `This server's dist/ build is ~${behindMinutes} min older than src/ — its behavior does not include the latest merged fixes. Rebuild with: pnpm --dir mcp-4da-server run build`
+            : null,
+    };
+}

package/dist/db.d.ts

@@ -5,8 +5,31 @@
  * Only the record_feedback function performs writes.
  */
 import type BetterSqlite3 from "better-sqlite3";
-import type { SourceItem, RelevantItem, UserContext, RelevanceExplanation, FeedbackAction, FeedbackResult } from "./types.js";
+/** Null when better-sqlite3 can open a database here; otherwise why not, with the fix. */
+export declare function nativeBindingProblem(): string | null;
+import type { RelevantItem, UserContext, FeedbackAction, FeedbackResult } from "./types.js";
 import type { ProjectScanResult } from "./project-scanner.js";
+/**
+ * Where the deployed desktop app keeps its database, mirroring
+ * `src-tauri/src/state.rs::get_db_path` / `get_platform_data_dir`:
+ * FOURDA_DATA_DIR overrides; Windows `%APPDATA%\com.4da.app\data`, macOS
+ * `~/Library/Application Support/com.4da.app/data`, Linux
+ * `$XDG_DATA_HOME/4da/data` (default `~/.local/share/4da/data`).
+ *
+ * Measured 2026-10-03 (pre-publish verification): this looked in
+ * `~/.local/share/com.4da.app/data` on Linux, a directory the app never
+ * writes, so a Linux desktop user's server never found the app's database and
+ * never offered the desktop tools. The old path is still checked last, in case
+ * a database was ever placed there by hand.
+ */
+export declare function desktopAppDbPaths(platform?: NodeJS.Platform, env?: NodeJS.ProcessEnv, home?: string): string[];
+/**
+ * Where a standalone install keeps its database: a per-user data directory.
+ * It used to be `<cwd>/data/4da.db` — inside the user's own repository, where
+ * it could be committed, and one per directory the server happened to start
+ * in, so agent memory and decisions did not follow the user between projects.
+ */
+export declare function standaloneDbPath(): string;
 export interface DatabaseValidationResult {
     valid: boolean;
     error?: string;
@@ -39,6 +62,19 @@ export interface DataFreshness {
     is_stale: boolean;
     /** Human-readable summary with the remedy when stale. */
     note: string;
+    /** Set when `data/.engine-blocked` reports a schema-refused scheduled refresh. */
+    engine_blocked_at?: string;
+    /** The refusal error recorded by the blocked engine. */
+    engine_blocked_error?: string;
+    /**
+     * Set when `data/.db-recovered` reports that the headless refresh engine
+     * restored the database from a backup or quarantined it: when it happened.
+     */
+    db_recovered_at?: string;
+    /** `restored_from_backup` | `quarantined_no_backup` | `recovery_failed` (a newer engine may add kinds). */
+    db_recovery_kind?: string;
+    /** The preserved file's path, or the failure reason. */
+    db_recovery_detail?: string;
 }
 /**
  * Collapse near-duplicate stories (same news via reddit + rss + mastodon…) by
@@ -123,7 +159,15 @@ export declare class FourDADatabase {
      * Get relevant content items scored by the Rust pipeline (preferred) or
      * TypeScript fallback scoring when Rust scores are unavailable.
      */
-    getRelevantContent(minScore?: number, sourceType?: string, limit?: number, sinceHours?: number, requireCurrentVersion?: boolean): RelevantItem[];
+    getRelevantContent(minScore?: number, sourceType?: string, limit?: number, sinceHours?: number, requireCurrentVersion?: boolean, 
+    /**
+     * Restrict to items the scoring pipeline stamped with this signal_type.
+     * Lets a type-specific read (a security-only pass) fill its limit with
+     * matches instead of competing for the top-N slots across every type.
+     * Only meaningful over pipeline-stamped rows: without Rust scores there
+     * are no stored types, so the read returns nothing rather than pretend.
+     */
+    signalType?: string): RelevantItem[];
     /**
      * Read the live freshness state of the feed database. Answered from ground truth, not from any
      * claim that a refresh ran — so DB-backed tools can tell the caller whether the curated feed is
@@ -149,10 +193,6 @@ export declare class FourDADatabase {
      * Fallback: TypeScript keyword scoring for standalone mode (no Rust pipeline).
      */
     private getRelevantContentFallback;
-    /**
-     * Get a single source item by ID and type
-     */
-    getSourceItem(itemId: number, sourceType: string): SourceItem | null;
     /**
      * Look up persisted necessity scores for an item (written by Rust analysis pipeline).
      * Returns defaults (0.0/null) if no necessity data exists yet.
@@ -163,61 +203,16 @@ export declare class FourDADatabase {
      */
     getUserContext(includeAce?: boolean, includeLearned?: boolean): UserContext;
     /**
-     * Explain why an item was considered relevant
+     * Record user feedback on an item
      */
-    explainRelevance(itemId: number, sourceType: string): RelevanceExplanation | null;
+    recordFeedback(itemId: number, sourceType: string | undefined, action: FeedbackAction): FeedbackResult;
     /**
-     * Record user feedback on an item
+     * Ensure the `feedback` table exists. The desktop app always has it; a
+     * standalone database created before record_feedback wrote labels does not
+     * (createMinimalSchema runs only for brand-new files). Same DDL as desktop,
+     * so against the desktop database this is a no-op.
      */
-    recordFeedback(itemId: number, sourceType: string, action: FeedbackAction): FeedbackResult;
-    /**
-     * Ensure the agent_feedback table exists.
-     * Called on first use so existing databases (created before this feature)
-     * get the table added without requiring a migration.
-     */
-    private ensureAgentFeedbackTable;
-    /**
-     * Record agent feedback on recommended content items
-     */
-    recordAgentFeedback(itemIds: string[], outcome: string, context?: string, sessionTask?: string): {
-        success: boolean;
-        message: string;
-        recorded_count: number;
-    };
-    /**
-     * Get agent feedback statistics for the given period
-     */
-    getAgentFeedbackStats(days?: number): {
-        period_days: number;
-        outcomes: {
-            used: number;
-            rejected: number;
-            partially_used: number;
-            total: number;
-        };
-        by_source: Array<{
-            source_type: string;
-            used: number;
-            rejected: number;
-            partially_used: number;
-            total: number;
-            usefulness_rate: number;
-        }>;
-        top_used_items: Array<{
-            item_id: string;
-            title: string | null;
-            source_type: string | null;
-            used_count: number;
-            rejected_count: number;
-        }>;
-        recent_feedback: Array<{
-            item_id: string;
-            outcome: string;
-            context: string | null;
-            session_task: string | null;
-            recorded_at: string;
-        }>;
-    };
+    private ensureFeedbackTable;
     /**
      * Compute relevance score for an item based on user context
      */