prism-mcp-server 2.1.2 → 2.3.0

package/README.md

@@ -14,9 +14,26 @@
 
 ---
 
-## What's New in v2.0 "Mind Palace" 🧠
+## What's New in v2.3.0 — AI Reasoning Engine 🧠
 
-Prism MCP has been completely rebuilt from the ground up to support **local-first workflows**, **visual agent memory**, and **multi-client synchronization**.
+| Feature | Description |
+|---|---|
+| 🕸️ **Neural Graph** | Interactive knowledge graph on the Mind Palace Dashboard — visualize how projects connect through shared keywords and categories using Vis.js force-directed layout. |
+| 🛡️ **Prompt Injection Shield** | Gemini-powered security scan in `session_health_check` — detects system override attempts, jailbreaks, and data exfiltration hidden in agent memory. Tuned to avoid false positives on normal dev commands. |
+| 🧬 **Fact Merger** | Async LLM contradiction resolution on every handoff save — if old context says "Postgres" and new says "MySQL", Gemini silently merges the facts in the background. Zero latency impact (fire-and-forget). |
+
+<details>
+<summary><strong>What's in v2.2.0</strong></summary>
+
+| Feature | Description |
+|---|---|
+| 🩺 **Brain Health Check** | `session_health_check` — like Unix `fsck` for your agent's memory. Detects missing embeddings, duplicate entries, orphaned handoffs, and stale rollups. Use `auto_fix: true` to repair automatically. |
+| 📊 **Mind Palace Health** | Brain health indicator on the Mind Palace Dashboard — see your memory integrity at a glance. |
+
+</details>
+
+<details>
+<summary><strong>What's in v2.0 "Mind Palace"</strong></summary>
 
 | Feature | Description |
 |---|---|
@@ -29,6 +46,8 @@ Prism MCP has been completely rebuilt from the ground up to support **local-firs
 | 📝 **Code Mode Templates** | 8 pre-built QuickJS extraction templates for GitHub, Jira, OpenAPI, Slack, CSV, and DOM parsing — zero reasoning tokens. |
 | 🔍 **Reality Drift Detection** | Prism captures Git state on save and warns if files changed outside the agent's view. |
 
+</details>
+
 ---
 
 ## Quick Start (Zero Config — Local Mode)
@@ -301,7 +320,7 @@ graph TB
 | `knowledge_search` | Semantic search across accumulated knowledge |
 | `knowledge_forget` | Prune outdated or incorrect memories (4 modes + dry_run) |
 | `session_search_memory` | Vector similarity search across all sessions |
-| `backfill_embeddings` | Retroactively generate embeddings for existing entries |
+| `session_compact_ledger` | Auto-compact old ledger entries via Gemini-powered summarization |
 
 ### v2.0 Advanced Memory Tools
 
@@ -312,6 +331,12 @@ graph TB
 | `session_save_image` | Save a screenshot/image to the visual memory vault |
 | `session_view_image` | Retrieve and display a saved image from the vault |
 
+### v2.2 Brain Health Tools
+
+| Tool | Purpose | Key Args | Returns |
+|------|---------|----------|---------|
+| `session_health_check` | Scan brain for integrity issues (`fsck`) | `auto_fix` (boolean) | Health report & auto-repairs |
+
 ### Code Mode Templates (v2.1)
 
 Instead of writing custom JavaScript, pass a `template` name for instant extraction:
@@ -560,6 +585,8 @@ See [`vertex-ai/`](vertex-ai/) for setup and benchmarks.
 │       ├── googleAi.ts                  # Gemini SDK wrapper
 │       ├── executor.ts                  # QuickJS sandbox executor
 │       ├── autoCapture.ts               # Dev server HTML snapshot utility
+│       ├── healthCheck.ts               # Brain integrity engine (v2.2.0) + security scanner (v2.3.0)
+│       ├── factMerger.ts                # Async LLM contradiction resolution (v2.3.0)
 │       ├── git.ts                       # Git state capture + drift detection
 │       ├── embeddingApi.ts              # Embedding generation (Gemini)
 │       └── keywordExtractor.ts          # Zero-dependency NLP keyword extraction

package/dist/dashboard/server.js

@@ -68,6 +68,90 @@ export async function startDashboardServer() {
                 res.writeHead(200, { "Content-Type": "application/json" });
                 return res.end(JSON.stringify({ context, ledger, history }));
             }
+            // ─── API: Brain Health Check (v2.2.0) ───
+            if (url.pathname === "/api/health") {
+                try {
+                    const { runHealthCheck } = await import("../utils/healthCheck.js");
+                    const stats = await storage.getHealthStats(PRISM_USER_ID);
+                    const report = runHealthCheck(stats);
+                    res.writeHead(200, { "Content-Type": "application/json" });
+                    return res.end(JSON.stringify(report));
+                }
+                catch (err) {
+                    console.error("[Dashboard] Health check error:", err);
+                    res.writeHead(200, { "Content-Type": "application/json" });
+                    return res.end(JSON.stringify({
+                        status: "unknown",
+                        summary: "Health check unavailable",
+                        issues: [],
+                        counts: { errors: 0, warnings: 0, infos: 0 },
+                        totals: { activeEntries: 0, handoffs: 0, rollups: 0 },
+                        timestamp: new Date().toISOString(),
+                    }));
+                }
+            }
+            // ─── API: Knowledge Graph Data (v2.3.0) ───
+            if (url.pathname === "/api/graph") {
+                // Fetch recent ledger entries to build the graph
+                // We look at the last 100 entries to keep the graph relevant but performant
+                const entries = await storage.getLedgerEntries({
+                    limit: "100",
+                    order: "created_at.desc",
+                    select: "project,keywords",
+                });
+                // Deduplication sets for nodes and edges
+                const nodes = [];
+                const edges = [];
+                const nodeIds = new Set(); // track unique node IDs
+                const edgeIds = new Set(); // track unique edges
+                // Helper: add a node only if it doesn't already exist
+                const addNode = (id, group, label) => {
+                    if (!nodeIds.has(id)) {
+                        nodes.push({ id, label: label || id, group });
+                        nodeIds.add(id);
+                    }
+                };
+                // Helper: add an edge only if it doesn't already exist
+                const addEdge = (from, to) => {
+                    const id = `${from}-${to}`; // deterministic edge ID
+                    if (!edgeIds.has(id)) {
+                        edges.push({ from, to });
+                        edgeIds.add(id);
+                    }
+                };
+                // Transform relational data into graph nodes & edges
+                entries.forEach(row => {
+                    if (!row.project)
+                        return; // skip rows without project
+                    // 1. Project node (hub — large purple dot)
+                    addNode(row.project, "project");
+                    // 2. Keyword nodes (spokes — small dots)
+                    let keywords = [];
+                    // Handle SQLite (JSON string) vs Supabase (native array)
+                    if (Array.isArray(row.keywords)) {
+                        keywords = row.keywords;
+                    }
+                    else if (typeof row.keywords === "string") {
+                        try {
+                            keywords = JSON.parse(row.keywords);
+                        }
+                        catch { /* skip malformed */ }
+                    }
+                    // Create nodes + edges for each keyword
+                    keywords.forEach((kw) => {
+                        if (kw.length < 3)
+                            return; // skip noise like "a", "is"
+                        // Handle categories (cat:debugging) vs raw keywords
+                        const isCat = kw.startsWith("cat:");
+                        const group = isCat ? "category" : "keyword";
+                        const label = isCat ? kw.replace("cat:", "") : kw;
+                        addNode(kw, group, label); // keyword/category node
+                        addEdge(row.project, kw); // edge: project → keyword
+                    });
+                });
+                res.writeHead(200, { "Content-Type": "application/json" });
+                return res.end(JSON.stringify({ nodes, edges }));
+            }
             // ─── 404 ───
             res.writeHead(404, { "Content-Type": "text/plain" });
             res.end("Not found");

package/dist/dashboard/ui.js

@@ -1,5 +1,5 @@
 /**
- * Mind Palace Dashboard — UI Renderer (v2.0 — Step 8)
+ * Mind Palace Dashboard — UI Renderer (v2.2.0)
  *
  * Pure CSS + Vanilla JS single-page dashboard.
  * No build step, no Tailwind, no framework — served as a template literal.
@@ -22,6 +22,8 @@ export function renderDashboardHTML() {
   <title>Prism MCP — Mind Palace</title>
   <link rel="preconnect" href="https://fonts.googleapis.com">
   <link href="https://fonts.googleapis.com/css2?family=Inter:wght@300;400;500;600;700&family=JetBrains+Mono:wght@400;500&display=swap" rel="stylesheet">
+  <!-- Vis.js for Neural Graph (v2.3.0) -->
+  <script type="text/javascript" src="https://unpkg.com/vis-network/standalone/umd/vis-network.min.js"></script>
   <style>
     *, *::before, *::after { box-sizing: border-box; margin: 0; padding: 0; }
 
@@ -224,6 +226,50 @@ export function renderDashboardHTML() {
     /* ─── Fade in animation ─── */
     @keyframes fadeIn { from { opacity: 0; transform: translateY(10px); } to { opacity: 1; transform: translateY(0); } }
     .fade-in { animation: fadeIn 0.4s ease-out forwards; }
+
+    /* ─── Brain Health Indicator (v2.2.0) ─── */
+    .health-status {
+      display: flex; align-items: center; gap: 0.75rem;
+      padding: 0.75rem 1rem; border-radius: var(--radius-sm);
+      background: rgba(15,23,42,0.6); margin-bottom: 1rem;
+    }
+    .health-dot {
+      width: 12px; height: 12px; border-radius: 50%;
+      flex-shrink: 0; position: relative;
+    }
+    .health-dot::after {
+      content: ''; position: absolute; inset: -3px;
+      border-radius: 50%; animation: healthPulse 2s ease-in-out infinite;
+    }
+    .health-dot.healthy { background: var(--accent-green); }
+    .health-dot.healthy::after { border: 2px solid rgba(16,185,129,0.3); }
+    .health-dot.degraded { background: var(--accent-amber); }
+    .health-dot.degraded::after { border: 2px solid rgba(245,158,11,0.3); }
+    .health-dot.unhealthy { background: var(--accent-rose); }
+    .health-dot.unhealthy::after { border: 2px solid rgba(244,63,94,0.3); }
+    .health-dot.unknown { background: var(--text-muted); }
+    .health-dot.unknown::after { border: 2px solid rgba(100,116,139,0.3); }
+    @keyframes healthPulse { 0%,100% { opacity: 1; } 50% { opacity: 0.4; } }
+    .health-label { font-size: 0.8rem; font-weight: 500; }
+    .health-summary { font-size: 0.75rem; color: var(--text-muted); }
+    .health-issues { font-size: 0.8rem; color: var(--text-secondary); margin-top: 0.5rem; }
+    .health-issues .issue-row {
+      padding: 0.3rem 0; display: flex; gap: 0.5rem; align-items: flex-start;
+    }
+
+    /* ─── Neural Graph (v2.3.0) ─── */
+    #network-container {
+      width: 100%; height: 300px;
+      border-radius: var(--radius);
+      background: rgba(0,0,0,0.2);
+      border: 1px solid var(--border-glass);
+    }
+    .refresh-btn {
+      margin-left: auto; background: none; border: none;
+      color: var(--text-muted); cursor: pointer; font-size: 0.85rem;
+      transition: color 0.2s;
+    }
+    .refresh-btn:hover { color: var(--accent-purple); }
   </style>
 </head>
 <body>
@@ -233,7 +279,7 @@ export function renderDashboardHTML() {
       <div class="logo">
         <span class="logo-icon">🧠</span>
         Prism Mind Palace
-        <span class="version-badge">v2.0</span>
+        <span class="version-badge">v2.2.0</span>
       </div>
       <div class="selector">
         <select id="projectSelect">
@@ -271,6 +317,19 @@ export function renderDashboardHTML() {
           <div class="git-row"><span class="git-label">Key Context</span><span class="git-value" id="keyContext" style="font-family:var(--font-sans);max-width:200px;text-align:right">—</span></div>
         </div>
 
+        <!-- Brain Health (v2.2.0) -->
+        <div class="card" id="healthCard" style="display:none">
+          <div class="card-title"><span class="dot" style="background:var(--accent-green)"></span> Brain Health 🩺</div>
+          <div class="health-status">
+            <div class="health-dot unknown" id="healthDot"></div>
+            <div>
+              <div class="health-label" id="healthLabel">Scanning...</div>
+              <div class="health-summary" id="healthSummary"></div>
+            </div>
+          </div>
+          <div class="health-issues" id="healthIssues"></div>
+        </div>
+
         <!-- Morning Briefing -->
         <div class="card" id="briefingCard" style="display:none">
           <div class="card-title"><span class="dot" style="background:var(--accent-amber)"></span> Morning Briefing 🌅</div>
@@ -286,6 +345,17 @@ export function renderDashboardHTML() {
 
       <!-- Right Column -->
       <div class="grid" style="align-content: start;">
+
+        <!-- Neural Graph (v2.3.0) -->
+        <div class="card">
+          <div class="card-title">
+            <span class="dot" style="background:var(--accent-blue)"></span>
+            Neural Graph 🕸️
+            <button onclick="loadGraph()" class="refresh-btn">↻</button>
+          </div>
+          <div id="network-container">Loading nodes...</div>
+        </div>
+
         <!-- Time Travel -->
         <div class="card">
           <div class="card-title"><span class="dot" style="background:var(--accent-purple)"></span> Time Travel History 🕰️</div>
@@ -413,6 +483,49 @@ export function renderDashboardHTML() {
           ledgerEl.innerHTML = '<div style="color:var(--text-muted);font-size:0.85rem;padding:1rem;text-align:center">No ledger entries yet.</div>';
         }
 
+        // ─── Brain Health (v2.2.0) ───
+        try {
+          var healthRes = await fetch('/api/health');
+          var healthData = await healthRes.json();
+          var healthCard = document.getElementById('healthCard');
+          var healthDot = document.getElementById('healthDot');
+          var healthLabel = document.getElementById('healthLabel');
+          var healthSummary = document.getElementById('healthSummary');
+          var healthIssues = document.getElementById('healthIssues');
+
+          // Set the dot color based on status
+          healthDot.className = 'health-dot ' + (healthData.status || 'unknown');
+
+          // Map status to emoji + label
+          var statusMap = { healthy: '✅ Healthy', degraded: '⚠️ Degraded', unhealthy: '🔴 Unhealthy' };
+          healthLabel.textContent = statusMap[healthData.status] || '❓ Unknown';
+
+          // Stats summary line
+          var t = healthData.totals || {};
+          healthSummary.textContent = (t.activeEntries || 0) + ' entries · ' +
+            (t.handoffs || 0) + ' handoffs · ' +
+            (t.rollups || 0) + ' rollups';
+
+          // Issue rows
+          var issues = healthData.issues || [];
+          if (issues.length > 0) {
+            var sevIcons = { error: '🔴', warning: '🟡', info: '🔵' };
+            healthIssues.innerHTML = issues.map(function(i) {
+              return '<div class="issue-row">' +
+                '<span>' + (sevIcons[i.severity] || '❓') + '</span>' +
+                '<span>' + escapeHtml(i.message) + '</span>' +
+                '</div>';
+            }).join('');
+          } else {
+            healthIssues.innerHTML = '<div style="color:var(--accent-green);font-size:0.8rem">🎉 No issues found</div>';
+          }
+
+          healthCard.style.display = 'block';
+        } catch(he) {
+          // Health check not available — silently skip
+          console.warn('Health check unavailable:', he);
+        }
+
         document.getElementById('content').className = 'grid grid-main fade-in';
         document.getElementById('content').style.display = 'grid';
       } catch(e) {
@@ -438,6 +551,73 @@ export function renderDashboardHTML() {
 
     // Allow Enter key in select to trigger load
     document.getElementById('projectSelect').addEventListener('change', loadProject);
+
+    // ─── Neural Graph (v2.3.0) ───
+    // Renders a force-directed graph of projects ↔ keywords ↔ categories
+    async function loadGraph() {
+      var container = document.getElementById('network-container');
+      if (!container) return;
+
+      try {
+        var res = await fetch('/api/graph');
+        var data = await res.json();
+
+        // Empty state — no ledger entries yet
+        if (data.nodes.length === 0) {
+          container.innerHTML = '<div style="display:flex;align-items:center;justify-content:center;height:100%;color:var(--text-muted);font-size:0.85rem">No knowledge associations found yet.</div>';
+          return;
+        }
+
+        // Vis.js dark-theme config matching the glassmorphism palette
+        var options = {
+          nodes: {
+            shape: 'dot',           // all nodes are circles
+            borderWidth: 0,         // no borders for clean look
+            font: { color: '#94a3b8', face: 'Inter', size: 12 }
+          },
+          edges: {
+            width: 1,               // thin edges for subtlety
+            color: { color: 'rgba(139,92,246,0.15)', highlight: '#8b5cf6' },
+            smooth: { type: 'continuous' }  // smooth curves
+          },
+          groups: {
+            project: {              // Hub nodes — large purple
+              color: { background: '#8b5cf6', border: '#7c3aed' },
+              size: 20,
+              font: { size: 14, color: '#f1f5f9', face: 'Inter' }
+            },
+            category: {             // Category nodes — cyan diamonds
+              color: { background: '#06b6d4', border: '#0891b2' },
+              size: 10,
+              shape: 'diamond'
+            },
+            keyword: {              // Keyword nodes — small dark dots
+              color: { background: '#1e293b', border: '#334155' },
+              size: 6,
+              font: { size: 10, color: '#64748b' }
+            }
+          },
+          physics: {
+            stabilization: false,   // animate on load for visual pop
+            barnesHut: {
+              gravitationalConstant: -3000,  // spread nodes apart
+              springConstant: 0.04,          // gentle spring force
+              springLength: 80               // default edge length
+            }
+          },
+          interaction: { hover: true }  // highlight on hover
+        };
+
+        // Create the network visualization
+        new vis.Network(container, data, options);
+      } catch (e) {
+        console.error('Graph error', e);
+        container.innerHTML = '<div style="padding:1rem;color:var(--accent-rose)">Graph failed to load</div>';
+      }
+    }
+
+    // Initialize the graph on page load
+    loadGraph();
   </script>
 </body>
 </html>`;

package/dist/server.js

@@ -72,17 +72,21 @@ import { WEB_SEARCH_TOOL, BRAVE_WEB_SEARCH_CODE_MODE_TOOL, LOCAL_SEARCH_TOOL, BR
 // Session memory tools — only used if Supabase is configured
 import { SESSION_SAVE_LEDGER_TOOL, SESSION_SAVE_HANDOFF_TOOL, SESSION_LOAD_CONTEXT_TOOL, KNOWLEDGE_SEARCH_TOOL, KNOWLEDGE_FORGET_TOOL, 
 // ─── v0.4.0: New tool definitions (Enhancements #2 and #4) ───
-SESSION_COMPACT_LEDGER_TOOL, SESSION_SEARCH_MEMORY_TOOL, SESSION_BACKFILL_EMBEDDINGS_TOOL, 
+SESSION_COMPACT_LEDGER_TOOL, SESSION_SEARCH_MEMORY_TOOL, 
 // ─── v2.0: Time Travel tool definitions ───
 MEMORY_HISTORY_TOOL, MEMORY_CHECKOUT_TOOL, 
 // ─── v2.0: Visual Memory tool definitions ───
-SESSION_SAVE_IMAGE_TOOL, SESSION_VIEW_IMAGE_TOOL, sessionSaveLedgerHandler, sessionSaveHandoffHandler, sessionLoadContextHandler, knowledgeSearchHandler, knowledgeForgetHandler, 
+SESSION_SAVE_IMAGE_TOOL, SESSION_VIEW_IMAGE_TOOL, 
+// ─── v2.2.0: Health Check tool definition ───
+SESSION_HEALTH_CHECK_TOOL, sessionSaveLedgerHandler, sessionSaveHandoffHandler, sessionLoadContextHandler, knowledgeSearchHandler, knowledgeForgetHandler, 
 // ─── v0.4.0: New tool handlers ───
-compactLedgerHandler, sessionSearchMemoryHandler, backfillEmbeddingsHandler, 
+compactLedgerHandler, sessionSearchMemoryHandler, 
 // ─── v2.0: Time Travel handlers ───
 memoryHistoryHandler, memoryCheckoutHandler, 
 // ─── v2.0: Visual Memory handlers ───
-sessionSaveImageHandler, sessionViewImageHandler, } from "./tools/index.js";
+sessionSaveImageHandler, sessionViewImageHandler, 
+// ─── v2.2.0: Health Check handler ───
+sessionHealthCheckHandler, } from "./tools/index.js";
 // ─── Dynamic Tool Registration ───────────────────────────────────
 // Base tools: always available regardless of configuration
 const BASE_TOOLS = [
@@ -106,12 +110,13 @@ const SESSION_MEMORY_TOOLS = [
     KNOWLEDGE_FORGET_TOOL, // knowledge_forget — prune bad/old memories
     SESSION_COMPACT_LEDGER_TOOL, // session_compact_ledger — auto-compact old ledger entries (v0.4.0)
     SESSION_SEARCH_MEMORY_TOOL, // session_search_memory — semantic search via embeddings (v0.4.0)
-    SESSION_BACKFILL_EMBEDDINGS_TOOL, // session_backfill_embeddings — repair missing embeddings
     MEMORY_HISTORY_TOOL, // memory_history — view version timeline (v2.0)
     MEMORY_CHECKOUT_TOOL, // memory_checkout — revert to past version (v2.0)
     // ─── v2.0: Visual Memory tools ───
     SESSION_SAVE_IMAGE_TOOL, // session_save_image — save image to media vault (v2.0)
     SESSION_VIEW_IMAGE_TOOL, // session_view_image — retrieve image from vault (v2.0)
+    // ─── v2.2.0: Health Check tool ───
+    SESSION_HEALTH_CHECK_TOOL, // session_health_check — brain integrity checker (v2.2.0)
 ];
 // Combine: if session memory is enabled, add those tools too
 const ALL_TOOLS = [
@@ -477,10 +482,6 @@ export function createServer() {
                     if (!SESSION_MEMORY_ENABLED)
                         throw new Error("Session memory not configured. Set SUPABASE_URL and SUPABASE_KEY.");
                     return await sessionSearchMemoryHandler(args);
-                case "session_backfill_embeddings":
-                    if (!SESSION_MEMORY_ENABLED)
-                        throw new Error("Session memory not configured. Set SUPABASE_URL and SUPABASE_KEY.");
-                    return await backfillEmbeddingsHandler(args);
                 // ─── v2.0: Time Travel Tools ───
                 case "memory_history":
                     if (!SESSION_MEMORY_ENABLED)
@@ -499,6 +500,11 @@ export function createServer() {
                     if (!SESSION_MEMORY_ENABLED)
                         throw new Error("Session memory not configured. Set SUPABASE_URL and SUPABASE_KEY.");
                     return await sessionViewImageHandler(args);
+                // ─── v2.2.0: Health Check Tool ───
+                case "session_health_check":
+                    if (!SESSION_MEMORY_ENABLED)
+                        throw new Error("Session memory not configured. Set SUPABASE_URL and SUPABASE_KEY.");
+                    return await sessionHealthCheckHandler(args);
                 default:
                     return {
                         content: [{ type: "text", text: `Unknown tool: ${name}` }],

package/dist/storage/sqlite.js

@@ -726,4 +726,123 @@ export class SqliteStorage {
         const result = await this.db.execute("SELECT DISTINCT project FROM session_handoffs ORDER BY project ASC");
         return result.rows.map(row => row.project);
     }
+    // ─── v2.2.0 Health Check (fsck) ─────────────────────────────
+    /**
+     * Gather raw health statistics for the integrity checker.
+     *
+     * This method runs 5 lightweight SQL queries and returns raw data.
+     * The heavy analysis (duplicate detection via Jaccard similarity)
+     * happens in healthCheck.ts in pure JS — keeping SQLite free of
+     * C-extension dependencies like Levenshtein.
+     */
+    async getHealthStats(userId) {
+        // ── Check 1: Count entries with no embedding vector ──────────
+        // When Gemini API is down during save, the fire-and-forget
+        // embedding call fails silently. These rows need backfill.
+        const missingResult = await this.db.execute({
+            sql: `
+        SELECT COUNT(*) as cnt
+        FROM session_ledger
+        WHERE user_id = ?
+          AND archived_at IS NULL
+          AND embedding IS NULL
+      `,
+            args: [userId], // bind user_id to the ? placeholder
+        });
+        const missingEmbeddings = Number(// extract count, default 0
+        missingResult.rows[0]?.cnt ?? 0);
+        // ── Check 2: Fetch active summaries for JS duplicate detection ─
+        // We pull id + project + summary into memory so healthCheck.ts
+        // can run Jaccard similarity in pure JS (~5ms for typical sets).
+        // The Compactor keeps the active ledger small, so this is safe.
+        const summariesResult = await this.db.execute({
+            sql: `
+        SELECT id, project, summary
+        FROM session_ledger
+        WHERE user_id = ?
+          AND archived_at IS NULL
+      `,
+            args: [userId], // bind user_id to the ? placeholder
+        });
+        // Map raw DB rows to typed objects for the health engine
+        const activeLedgerSummaries = summariesResult.rows.map(row => ({
+            id: row.id, // unique entry identifier
+            project: row.project, // project this entry belongs to
+            summary: row.summary, // text we compare for duplicates
+        }));
+        // ── Check 3: Find orphaned handoffs ──────────────────────────
+        // An orphaned handoff = handoff state exists but zero active
+        // ledger entries back it. Usually from testing or bugs.
+        // LEFT JOIN + HAVING COUNT = 0 finds projects with no entries.
+        const orphanResult = await this.db.execute({
+            sql: `
+        SELECT h.project
+        FROM session_handoffs h
+        LEFT JOIN session_ledger l
+          ON h.project = l.project
+          AND h.user_id = l.user_id
+          AND l.archived_at IS NULL
+        WHERE h.user_id = ?
+        GROUP BY h.project
+        HAVING COUNT(l.id) = 0
+      `,
+            args: [userId], // bind user_id to the ? placeholder
+        });
+        // Map to simple project name objects
+        const orphanedHandoffs = orphanResult.rows.map(row => ({
+            project: row.project, // the orphaned project name
+        }));
+        // ── Check 4: Count stale rollups ─────────────────────────────
+        // A rollup entry should have archived originals backing it.
+        // If those originals were hard-deleted, the rollup is stale.
+        // Self-join: rollups (is_rollup=1) LEFT JOIN archived entries.
+        const staleResult = await this.db.execute({
+            sql: `
+        SELECT r.id
+        FROM session_ledger r
+        LEFT JOIN session_ledger a
+          ON a.archived_at IS NOT NULL
+          AND a.project = r.project
+          AND a.user_id = r.user_id
+        WHERE r.user_id = ?
+          AND r.is_rollup = 1
+          AND r.archived_at IS NULL
+        GROUP BY r.id
+        HAVING COUNT(a.id) = 0
+      `,
+            args: [userId], // bind user_id to the ? placeholder
+        });
+        // Count how many rollups have zero archived originals
+        const staleRollups = staleResult.rows.length;
+        // ── Totals: aggregate counts for health report summary ───────
+        // Three scalar subqueries in one shot for efficiency.
+        const totalsResult = await this.db.execute({
+            sql: `
+        SELECT
+          (SELECT COUNT(*) FROM session_ledger
+            WHERE user_id = ? AND archived_at IS NULL) as active,
+          (SELECT COUNT(*) FROM session_handoffs
+            WHERE user_id = ?) as handoffs,
+          (SELECT COUNT(*) FROM session_ledger
+            WHERE user_id = ? AND is_rollup = 1
+            AND archived_at IS NULL) as rollups
+      `,
+            args: [userId, userId, userId], // bind user_id 3x (one per subquery)
+        });
+        // Extract each total, fallback to 0 if undefined
+        const totalActiveEntries = Number(totalsResult.rows[0]?.active ?? 0);
+        const totalHandoffs = Number(totalsResult.rows[0]?.handoffs ?? 0);
+        const totalRollups = Number(totalsResult.rows[0]?.rollups ?? 0);
+        // ── Return the complete raw health stats ─────────────────────
+        // healthCheck.ts engine will analyze this + produce HealthReport
+        return {
+            missingEmbeddings, // entries needing embedding repair
+            activeLedgerSummaries, // raw summaries for JS dupe detection
+            orphanedHandoffs, // projects with handoff but no ledger
+            staleRollups, // rollups with no archived originals
+            totalActiveEntries, // grand total of active entries
+            totalHandoffs, // grand total of handoff records
+            totalRollups, // grand total of rollup entries
+        };
+    }
 }