@massu/core 1.6.1 → 1.6.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@massu/core",
-  "version": "1.6.1",
+  "version": "1.6.3",
   "type": "module",
   "description": "AI Engineering Governance MCP Server - Session memory, knowledge system, feature registry, code intelligence, rule enforcement, tiered tooling (12 free / 72 total), 55+ workflow commands, 11 agents, 20+ patterns",
   "main": "src/server.ts",

package/src/db.ts

@@ -6,14 +6,37 @@ import { dirname, join } from 'path';
 import { existsSync, mkdirSync, readdirSync, statSync } from 'fs';
 import { getResolvedPaths } from './config.ts';
 
+/**
+ * Thrown by `getCodeGraphDb()` when `.codegraph/codegraph.db` is missing.
+ *
+ * Caught at the JSON-RPC dispatch layer (server.ts) and translated to a
+ * structured `-32001` error response carrying a remedy hint and the resolved
+ * DB path. The thrown error is INTERNAL; user-facing copy lives in the
+ * dispatcher's error envelope.
+ *
+ * @see `docs/plans/2026-05-10-server-lazy-db-deps.md` P-C-001 + P-A-004
+ */
+export class CodegraphDbNotInitializedError extends Error {
+  readonly dbPath: string;
+  constructor(dbPath: string) {
+    super(`CodeGraph database not found at ${dbPath}`);
+    this.name = 'CodegraphDbNotInitializedError';
+    this.dbPath = dbPath;
+  }
+}
+
 /**
  * Connection to CodeGraph's read-only SQLite database.
  * We NEVER write to this DB - it belongs to vanilla CodeGraph.
+ *
+ * Throws `CodegraphDbNotInitializedError` (internal signal) when the DB is
+ * missing. The MCP dispatcher catches and translates to a structured
+ * JSON-RPC error pointing at `npx @colbymchenry/codegraph init`.
  */
 export function getCodeGraphDb(): Database.Database {
   const dbPath = getResolvedPaths().codegraphDbPath;
   if (!existsSync(dbPath)) {
-    throw new Error(`CodeGraph database not found at ${dbPath}. Run 'npx @colbymchenry/codegraph sync' first.`);
+    throw new CodegraphDbNotInitializedError(dbPath);
   }
   const db = new Database(dbPath, { readonly: true });
   db.pragma('journal_mode = WAL');

package/src/security/registry-pubkey.generated.ts

@@ -1,4 +1,4 @@
-// AUTO-GENERATED by scripts/bundle-pubkey.mjs at 2026-05-10T21:58:17.622Z.
+// AUTO-GENERATED by scripts/bundle-pubkey.mjs at 2026-05-11T22:54:34.471Z.
 // Source pem: packages/core/security/registry-pubkey.pem
 // RAW-bytes sha256: 3b6226d036c472e533110d11a7d0cd2773ce1d7d4f1003517d5bd69c5418ed4c
 // DO NOT EDIT — regenerate via `node scripts/bundle-pubkey.mjs` or

package/src/server-dispatch.ts

@@ -0,0 +1,225 @@
+// Copyright (c) 2026 Massu. All rights reserved.
+// Licensed under BSL 1.1 - see LICENSE file for details.
+
+/**
+ * MCP server dispatch logic — pure, factory-based, no module-level mutable state.
+ *
+ * Production (`server.ts`) calls `createDispatcher()` once at startup and wires
+ * its `processLine` into stdin. Tests call `createDispatcher()` per test for
+ * fresh DB cache state (no test bleed).
+ *
+ * Three error envelopes live here (CR-12 / plan-1.6.2-server-lazy-db-deps):
+ *   -32001  Tool needs CodeGraph but `.codegraph/codegraph.db` is missing
+ *           (CodegraphDbNotInitializedError → structured remedy data)
+ *   -32602  Tool not registered in `TOOL_DB_NEEDS` manifest
+ *           (UnknownToolError → points at tool-db-needs.ts)
+ *   -32603  Other internal errors raised by handleToolCall — request id
+ *           is preserved (NOT id:null, which is reserved for -32700 parse
+ *           failures per JSON-RPC §5.1).
+ */
+
+import type Database from 'better-sqlite3';
+import { getCodeGraphDb, getDataDb, CodegraphDbNotInitializedError } from './db.ts';
+import { getConfig } from './config.ts';
+import { getToolDefinitions, handleToolCall } from './tools.ts';
+import { getToolDbNeeds, UnknownToolError, type DbNeed } from './tool-db-needs.ts';
+
+export interface JsonRpcRequest {
+  jsonrpc: '2.0';
+  id?: number | string;
+  method: string;
+  params?: Record<string, unknown>;
+}
+
+export interface JsonRpcResponse {
+  jsonrpc: '2.0';
+  id: number | string | null;
+  result?: unknown;
+  error?: { code: number; message: string; data?: unknown };
+}
+
+/** Per-line dispatch result. `emit=false` when the request was a notification (no id). */
+export interface ProcessLineResult {
+  response: JsonRpcResponse;
+  emit: boolean;
+}
+
+export interface DispatcherOptions {
+  /** Version string surfaced in `initialize.result.serverInfo.version`. */
+  serverInfoVersion: string;
+}
+
+export interface Dispatcher {
+  handleRequest(request: JsonRpcRequest): Promise<JsonRpcResponse>;
+  processLine(line: string): Promise<ProcessLineResult | null>;
+  closeCachedDbs(): void;
+}
+
+export function createDispatcher(options: DispatcherOptions): Dispatcher {
+  let codegraphDbCache: Database.Database | null = null;
+  let dataDbCache: Database.Database | null = null;
+
+  function resolveDbsForTool(toolName: string): {
+    needs: readonly DbNeed[];
+    dataDb?: Database.Database;
+    codegraphDb?: Database.Database;
+  } {
+    const needs = getToolDbNeeds(toolName, getConfig().toolPrefix);
+
+    let dataDbResolved: Database.Database | undefined;
+    let codegraphDbResolved: Database.Database | undefined;
+
+    if (needs.includes('data')) {
+      if (!dataDbCache) dataDbCache = getDataDb();
+      dataDbResolved = dataDbCache;
+    }
+
+    if (needs.includes('codegraph')) {
+      // Throws CodegraphDbNotInitializedError when .codegraph/codegraph.db is missing.
+      if (!codegraphDbCache) codegraphDbCache = getCodeGraphDb();
+      codegraphDbResolved = codegraphDbCache;
+    }
+
+    return { needs, dataDb: dataDbResolved, codegraphDb: codegraphDbResolved };
+  }
+
+  async function handleRequest(request: JsonRpcRequest): Promise<JsonRpcResponse> {
+    const { method, params, id } = request;
+
+    switch (method) {
+      case 'initialize': {
+        return {
+          jsonrpc: '2.0',
+          id: id ?? null,
+          result: {
+            protocolVersion: '2024-11-05',
+            capabilities: { tools: {} },
+            serverInfo: {
+              name: getConfig().toolPrefix || 'massu',
+              version: options.serverInfoVersion,
+            },
+          },
+        };
+      }
+
+      case 'notifications/initialized': {
+        return { jsonrpc: '2.0', id: id ?? null, result: {} };
+      }
+
+      case 'tools/list': {
+        const tools = getToolDefinitions();
+        return { jsonrpc: '2.0', id: id ?? null, result: { tools } };
+      }
+
+      case 'tools/call': {
+        const toolName = (params as { name?: string })?.name ?? '';
+        const toolArgs = (params as { arguments?: Record<string, unknown> })?.arguments ?? {};
+
+        try {
+          const { dataDb, codegraphDb } = resolveDbsForTool(toolName);
+          const result = await handleToolCall(toolName, toolArgs, dataDb, codegraphDb);
+          return { jsonrpc: '2.0', id: id ?? null, result };
+        } catch (err) {
+          if (err instanceof CodegraphDbNotInitializedError) {
+            return {
+              jsonrpc: '2.0',
+              id: id ?? null,
+              error: {
+                code: -32001,
+                message: 'Tool requires CodeGraph database which is not initialized for this repo',
+                data: {
+                  remedy: 'npx @colbymchenry/codegraph@0.7.4 init . && npx @colbymchenry/codegraph@0.7.4 index .',
+                  codegraphDbPath: err.dbPath,
+                  tool: toolName,
+                },
+              },
+            };
+          }
+          if (err instanceof UnknownToolError) {
+            return {
+              jsonrpc: '2.0',
+              id: id ?? null,
+              error: {
+                code: -32602,
+                message: `Unknown tool: ${err.toolName}`,
+                data: {
+                  remedy: 'Tool not registered in TOOL_DB_NEEDS manifest. See packages/core/src/tool-db-needs.ts.',
+                  tool: toolName,
+                },
+              },
+            };
+          }
+          throw err;
+        }
+      }
+
+      case 'ping': {
+        return { jsonrpc: '2.0', id: id ?? null, result: {} };
+      }
+
+      default: {
+        return {
+          jsonrpc: '2.0',
+          id: id ?? null,
+          error: { code: -32601, message: `Method not found: ${method}` },
+        };
+      }
+    }
+  }
+
+  async function processLine(line: string): Promise<ProcessLineResult | null> {
+    const trimmed = line.trim();
+    if (!trimmed) return null;
+
+    let request: JsonRpcRequest;
+    try {
+      request = JSON.parse(trimmed) as JsonRpcRequest;
+    } catch (parseError) {
+      // JSON-RPC §5.1: parse failure → -32700 + id:null (no id is extractable).
+      return {
+        response: {
+          jsonrpc: '2.0',
+          id: null,
+          error: {
+            code: -32700,
+            message: `Parse error: ${parseError instanceof Error ? parseError.message : String(parseError)}`,
+          },
+        },
+        emit: true,
+      };
+    }
+
+    try {
+      const response = await handleRequest(request);
+      // Notifications (no id) MUST NOT receive a response per JSON-RPC §4.1.
+      return { response, emit: request.id !== undefined };
+    } catch (error) {
+      // Request-processing failure: -32603 with the request id preserved.
+      // Specific subclasses (-32001/-32602) are handled inside tools/call.
+      return {
+        response: {
+          jsonrpc: '2.0',
+          id: request.id ?? null,
+          error: {
+            code: -32603,
+            message: `Internal error: ${error instanceof Error ? error.message : String(error)}`,
+          },
+        },
+        emit: true,
+      };
+    }
+  }
+
+  function closeCachedDbs(): void {
+    if (codegraphDbCache) {
+      codegraphDbCache.close();
+      codegraphDbCache = null;
+    }
+    if (dataDbCache) {
+      dataDbCache.close();
+      dataDbCache = null;
+    }
+  }
+
+  return { handleRequest, processLine, closeCachedDbs };
+}

package/src/server.ts

@@ -14,11 +14,9 @@
 import { readFileSync } from 'fs';
 import { resolve, dirname } from 'path';
 import { fileURLToPath } from 'url';
-import { getCodeGraphDb, getDataDb } from './db.ts';
-import { getConfig } from './config.ts';
-import { getToolDefinitions, handleToolCall } from './tools.ts';
 import { getMemoryDb, pruneOldConversationTurns, pruneOldObservations } from './memory-db.ts';
 import { getCurrentTier } from './license.ts';
+import { createDispatcher } from './server-dispatch.ts';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const PKG_VERSION = (() => {
@@ -30,92 +28,7 @@ const PKG_VERSION = (() => {
   }
 })();
 
-interface JsonRpcRequest {
-  jsonrpc: '2.0';
-  id?: number | string;
-  method: string;
-  params?: Record<string, unknown>;
-}
-
-interface JsonRpcResponse {
-  jsonrpc: '2.0';
-  id: number | string | null;
-  result?: unknown;
-  error?: { code: number; message: string; data?: unknown };
-}
-
-// Server state
-let codegraphDb: ReturnType<typeof getCodeGraphDb> | null = null;
-let dataDb: ReturnType<typeof getDataDb> | null = null;
-
-function getDb() {
-  if (!codegraphDb) codegraphDb = getCodeGraphDb();
-  if (!dataDb) dataDb = getDataDb();
-  return { codegraphDb, dataDb: dataDb };
-}
-
-async function handleRequest(request: JsonRpcRequest): Promise<JsonRpcResponse> {
-  const { method, params, id } = request;
-
-  switch (method) {
-    case 'initialize': {
-      return {
-        jsonrpc: '2.0',
-        id: id ?? null,
-        result: {
-          protocolVersion: '2024-11-05',
-          capabilities: {
-            tools: {},
-          },
-          serverInfo: {
-            name: getConfig().toolPrefix || 'massu',
-            version: PKG_VERSION,
-          },
-        },
-      };
-    }
-
-    case 'notifications/initialized': {
-      // Client acknowledges initialization - no response needed for notifications
-      return { jsonrpc: '2.0', id: id ?? null, result: {} };
-    }
-
-    case 'tools/list': {
-      const tools = getToolDefinitions();
-      return {
-        jsonrpc: '2.0',
-        id: id ?? null,
-        result: { tools },
-      };
-    }
-
-    case 'tools/call': {
-      const toolName = (params as { name: string })?.name;
-      const toolArgs = (params as { arguments?: Record<string, unknown> })?.arguments ?? {};
-
-      const { codegraphDb: cgDb, dataDb: lDb } = getDb();
-      const result = await handleToolCall(toolName, toolArgs, lDb, cgDb);
-
-      return {
-        jsonrpc: '2.0',
-        id: id ?? null,
-        result,
-      };
-    }
-
-    case 'ping': {
-      return { jsonrpc: '2.0', id: id ?? null, result: {} };
-    }
-
-    default: {
-      return {
-        jsonrpc: '2.0',
-        id: id ?? null,
-        error: { code: -32601, message: `Method not found: ${method}` },
-      };
-    }
-  }
-}
+const dispatcher = createDispatcher({ serverInfoVersion: PKG_VERSION });
 
 // === Startup: prune stale memory data (non-blocking) ===
 
@@ -167,38 +80,20 @@ process.stdin.on('data', async (chunk: string) => {
   // Process complete messages (newline-delimited JSON-RPC)
   let newlineIndex: number;
   while ((newlineIndex = buffer.indexOf('\n')) !== -1) {
-    const line = buffer.slice(0, newlineIndex).trim();
+    const line = buffer.slice(0, newlineIndex);
     buffer = buffer.slice(newlineIndex + 1);
 
-    if (!line) continue;
-
-    try {
-      const request = JSON.parse(line) as JsonRpcRequest;
-      const response = await handleRequest(request);
-
-      // Don't send responses for notifications (no id)
-      if (request.id !== undefined) {
-        const responseStr = JSON.stringify(response);
-        process.stdout.write(responseStr + '\n');
-      }
-    } catch (error) {
-      const errorResponse: JsonRpcResponse = {
-        jsonrpc: '2.0',
-        id: null,
-        error: {
-          code: -32700,
-          message: `Parse error: ${error instanceof Error ? error.message : String(error)}`,
-        },
-      };
-      process.stdout.write(JSON.stringify(errorResponse) + '\n');
+    const result = await dispatcher.processLine(line);
+    if (result && result.emit) {
+      process.stdout.write(JSON.stringify(result.response) + '\n');
     }
   }
 });
 
 process.stdin.on('end', () => {
-  // Clean up database connections
-  if (codegraphDb) codegraphDb.close();
-  if (dataDb) dataDb.close();
+  // Close cached CodeGraph + Data connections. Memory + Knowledge are
+  // per-call (closed inside their routing branches in tools.ts).
+  dispatcher.closeCachedDbs();
   process.exit(0);
 });
 

package/src/tool-db-needs.ts

@@ -0,0 +1,226 @@
+// Copyright (c) 2026 Massu. All rights reserved.
+// Licensed under BSL 1.1 - see LICENSE file for details.
+
+/**
+ * Per-tool SQLite database dependency manifest.
+ *
+ * **Role**: SOLE source of truth declaring which SQLite connections each MCP
+ * tool needs. The dispatcher (`server.ts` → `tools.ts:handleToolCall`) reads
+ * this map to lazy-resolve connections, opening ONLY the DBs a tool requires.
+ *
+ * **Why this exists**:
+ * Before plan `plan-1.6.2-server-lazy-db-deps`, the dispatcher eagerly opened
+ * BOTH CodeGraph + Data DBs on every tool/call (see legacy `server.ts:51-55,96`
+ * and `tools.ts:279`). When `.codegraph/codegraph.db` was missing, EVERY tool
+ * call failed — even memory/audit/knowledge tools that have no codegraph
+ * dependency. This manifest makes that bug class structurally impossible:
+ * a missing peripheral DB only blocks the tools that need it.
+ *
+ * **Structural drift-prevention (3 layers)**:
+ *   - L1: TypeScript compile time — exhaustiveness check via `keyof TOOL_DB_NEEDS`.
+ *   - L2: `tool-db-needs-completeness.test.ts` — TypeScript AST walk of every
+ *         tool module verifies declared needs match actual DB access pattern.
+ *         Aliasing/destructuring renames cannot bypass the AST walk.
+ *   - L3: `scripts/massu-pattern-scanner.sh` Check 14 — grep-level enforcement
+ *         that every tool in `getToolDefinitions()` has a manifest entry.
+ *
+ * **Adding a new MCP tool**:
+ *   1. Register in `tools.ts` (CR-11).
+ *   2. Add an entry here. Missing entries throw `UnknownToolError` at first
+ *      dispatch AND fail L2 + L3 above.
+ *
+ * @see `docs/plans/2026-05-10-server-lazy-db-deps.md` (`plan-1.6.2-server-lazy-db-deps`)
+ */
+
+/** SQLite connections the MCP server can resolve for a tool call. */
+export type DbNeed = 'codegraph' | 'data' | 'memory' | 'knowledge';
+
+/**
+ * Custom error thrown when `getToolDbNeeds()` is called with a tool name that
+ * isn't in the manifest. Caught at the JSON-RPC layer and translated to a
+ * structured `-32602` (Invalid params) error to the client.
+ */
+export class UnknownToolError extends Error {
+  readonly toolName: string;
+  constructor(toolName: string) {
+    super(`Tool not registered in TOOL_DB_NEEDS manifest: ${toolName}. Add an entry to packages/core/src/tool-db-needs.ts.`);
+    this.name = 'UnknownToolError';
+    this.toolName = toolName;
+  }
+}
+
+/**
+ * Per-tool DB-need declarations. Keys are tool SHORT-NAMES (without the
+ * `${toolPrefix}_` prefix). Values are the SQLite connections the handler
+ * (or its routed module) actually accesses.
+ *
+ * Sourced from exhaustive grep of `packages/core/src/{*-tools,analytics,
+ * cost-tracker,prompt-analyzer,audit-trail,validation-engine,adr-generator,
+ * security-scorer,dependency-scorer,team-knowledge,regression-detector,
+ * python-tools,license}.ts` on 2026-05-10. Verified line citations in
+ * `docs/plans/2026-05-10-server-lazy-db-deps.md §1.4`.
+ */
+export const TOOL_DB_NEEDS = {
+  // === Core code-intel tools (tools.ts:393-406) ===
+  // Use CodeGraph DB (read-only AST) + Data DB (Massu's import/trpc/sentinel
+  // tables). All call `ensureIndexes` directly or via shared infrastructure.
+  sync: ['codegraph', 'data'],
+  context: ['codegraph', 'data'],
+  coupling_check: ['codegraph', 'data'],
+  impact: ['codegraph', 'data'],
+  domains: ['codegraph', 'data'],
+
+  // `trpc_map` reads only Data DB (tRPC index lives there); no CodeGraph access.
+  trpc_map: ['data'],
+
+  // `schema` reads filesystem (Prisma schema files); no DB access at all.
+  schema: [],
+
+  // === Memory tools (memory-tools.ts) ===
+  // Routed via `name.startsWith(pfx + '_memory_')` at tools.ts:284-290.
+  // Handler opens memory DB per-call (with try/finally close).
+  memory_search: ['memory'],
+  memory_timeline: ['memory'],
+  memory_detail: ['memory'],
+  memory_sessions: ['memory'],
+  memory_failures: ['memory'],
+  memory_ingest: ['memory'],
+  memory_backfill: ['memory'],
+
+  // === Observability tools (observability-tools.ts) ===
+  // Routed via `isObservabilityTool(name)` at tools.ts:294-300. Memory DB only.
+  session_replay: ['memory'],
+  session_stats: ['memory'],
+  tool_patterns: ['memory'],
+  prompt_analysis: ['memory'],
+
+  // === Docs tools (docs-tools.ts) ===
+  // Routed via `name.startsWith(pfx + '_docs_')` at tools.ts:303-306.
+  // No DB access — pure filesystem traversal.
+  docs_audit: [],
+  docs_coverage: [],
+
+  // === Sentinel registry tools (sentinel-tools.ts:180-184) ===
+  // Routed via `name.startsWith(pfx + '_sentinel_')` at tools.ts:308.
+  // Handler signature: `(name, args, dataDb)` — Data DB only.
+  sentinel_register: ['data'],
+  sentinel_validate: ['data'],
+  sentinel_search: ['data'],
+  sentinel_detail: ['data'],
+  sentinel_impact: ['data'],
+  sentinel_parity: ['data'],
+
+  // === Knowledge layer tools (knowledge-tools.ts) ===
+  // Routed via `isKnowledgeTool(name)` at tools.ts:372-376. Primary DB is
+  // `knowledgeDb` (separate SQLite file). Handlers ALSO call `getDataDb()`
+  // (knowledge-tools.ts:1187,1275) and `getMemoryDb()` (knowledge-tools.ts:1332)
+  // for cross-DB joins — declare all three so the AST completeness test
+  // (P-B-002) verifies the full access pattern.
+  knowledge_search: ['knowledge', 'data', 'memory'],
+  knowledge_pattern: ['knowledge', 'data', 'memory'],
+  knowledge_rule: ['knowledge', 'data', 'memory'],
+  knowledge_correct: ['knowledge', 'data', 'memory'],
+  knowledge_incident: ['knowledge', 'data', 'memory'],
+  knowledge_plan: ['knowledge', 'data', 'memory'],
+  knowledge_command: ['knowledge', 'data', 'memory'],
+  knowledge_gaps: ['knowledge', 'data', 'memory'],
+  knowledge_verification: ['knowledge', 'data', 'memory'],
+  knowledge_effectiveness: ['knowledge', 'data', 'memory'],
+  knowledge_graph: ['knowledge', 'data', 'memory'],
+  knowledge_schema_check: ['knowledge', 'data', 'memory'],
+
+  // === Analytics / quality (analytics.ts) ===
+  // Routed via `isAnalyticsTool(name)`. Memory DB only.
+  quality_score: ['memory'],
+  quality_report: ['memory'],
+  quality_trend: ['memory'],
+
+  // === Cost tracker (cost-tracker.ts) ===
+  cost_session: ['memory'],
+  cost_feature: ['memory'],
+  cost_trend: ['memory'],
+
+  // === Prompt analyzer (prompt-analyzer.ts) ===
+  prompt_effectiveness: ['memory'],
+  prompt_suggestions: ['memory'],
+
+  // === Audit trail (audit-trail.ts) ===
+  audit_chain: ['memory'],
+  audit_log: ['memory'],
+  audit_report: ['memory'],
+
+  // === Validation engine (validation-engine.ts) ===
+  validation_check: ['memory'],
+  validation_report: ['memory'],
+
+  // === ADR generator (adr-generator.ts) ===
+  adr_create: ['memory'],
+  adr_list: ['memory'],
+  adr_detail: ['memory'],
+
+  // === Security scorer (security-scorer.ts) ===
+  security_score: ['memory'],
+  security_heatmap: ['memory'],
+  security_trend: ['memory'],
+
+  // === Dependency scorer (dependency-scorer.ts) ===
+  dep_score: ['memory'],
+  dep_alternatives: ['memory'],
+
+  // === Team knowledge (team-knowledge.ts) ===
+  team_expertise: ['memory'],
+  team_conflicts: ['memory'],
+  team_search: ['memory'],
+
+  // === Regression detector (regression-detector.ts) ===
+  regression_risk: ['memory'],
+  feature_health: ['memory'],
+
+  // === Python code-intel tools (python-tools.ts) ===
+  // Routed via `isPythonTool(name)` at tools.ts:379-381. Data DB only.
+  py_imports: ['data'],
+  py_routes: ['data'],
+  py_models: ['data'],
+  py_migrations: ['data'],
+  py_coupling: ['data'],
+  py_context: ['data'],
+  py_impact: ['data'],
+  py_domains: ['data'],
+
+  // === License tool (license.ts) ===
+  license_status: ['memory'],
+} as const satisfies Readonly<Record<string, readonly DbNeed[]>>;
+
+/**
+ * Configured tool-prefix-stripping helper. Pulled from the runtime config
+ * so this module stays project-prefix-agnostic.
+ */
+function stripConfiguredPrefix(toolName: string, prefix: string): string {
+  const pfx = `${prefix}_`;
+  return toolName.startsWith(pfx) ? toolName.slice(pfx.length) : toolName;
+}
+
+/**
+ * Look up the DB needs for a tool by its full name (with prefix). Strips the
+ * configured prefix and consults `TOOL_DB_NEEDS`. Throws `UnknownToolError`
+ * for tool names not in the manifest — the dispatcher MUST catch this and
+ * translate to a structured JSON-RPC error.
+ *
+ * @param toolName Full tool name including prefix (e.g., `"massu_memory_search"`)
+ * @param prefix Tool prefix (e.g., `"massu"`) — read from config at dispatch time
+ * @returns Array of DB connections the tool requires (may be empty)
+ * @throws {UnknownToolError} if `stripPrefix(toolName)` not in the manifest
+ */
+export function getToolDbNeeds(toolName: string, prefix: string): readonly DbNeed[] {
+  const shortName = stripConfiguredPrefix(toolName, prefix);
+  const needs = (TOOL_DB_NEEDS as Record<string, readonly DbNeed[]>)[shortName];
+  if (needs === undefined) {
+    throw new UnknownToolError(toolName);
+  }
+  return needs;
+}
+
+/** Convenience predicate: does a tool need CodeGraph DB? */
+export function toolNeedsCodegraph(toolName: string, prefix: string): boolean {
+  return getToolDbNeeds(toolName, prefix).includes('codegraph');
+}