@massu/core 1.6.1 → 1.6.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@massu/core",
-  "version": "1.6.1",
+  "version": "1.6.2",
   "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-11T05:57:55.925Z.
 // 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.ts

@@ -14,11 +14,13 @@
 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 type Database from 'better-sqlite3';
+import { getCodeGraphDb, getDataDb, CodegraphDbNotInitializedError } from './db.ts';
+import { getConfig, getResolvedPaths } from './config.ts';
 import { getToolDefinitions, handleToolCall } from './tools.ts';
 import { getMemoryDb, pruneOldConversationTurns, pruneOldObservations } from './memory-db.ts';
 import { getCurrentTier } from './license.ts';
+import { getToolDbNeeds, UnknownToolError, type DbNeed } from './tool-db-needs.ts';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const PKG_VERSION = (() => {
@@ -44,14 +46,53 @@ interface JsonRpcResponse {
   error?: { code: number; message: string; data?: unknown };
 }
 
-// Server state
-let codegraphDb: ReturnType<typeof getCodeGraphDb> | null = null;
-let dataDb: ReturnType<typeof getDataDb> | null = null;
+// === Server state: lazy per-tool DB resolution ===
+//
+// Per plan-1.6.2-server-lazy-db-deps: DBs are opened ONLY when the
+// currently-dispatched tool declares it needs them in `TOOL_DB_NEEDS`.
+// Connections are cached at module scope so subsequent tool calls reuse
+// the open handle without re-opening (CodeGraph is read-only — safe to
+// share; Data DB has WAL journal — single-writer is fine).
+//
+// PRIOR DESIGN (eliminated 2026-05-10): `getDb()` eagerly opened BOTH
+// CodeGraph + Data on every `tools/call`, even for memory/audit/knowledge
+// tools that don't need codegraph. Missing `.codegraph/codegraph.db`
+// broke ALL tools. See `docs/plans/2026-05-10-server-lazy-db-deps.md`.
 
-function getDb() {
-  if (!codegraphDb) codegraphDb = getCodeGraphDb();
-  if (!dataDb) dataDb = getDataDb();
-  return { codegraphDb, dataDb: dataDb };
+let codegraphDbCache: Database.Database | null = null;
+let dataDbCache: Database.Database | null = null;
+
+/**
+ * Resolve the SQLite connections a tool needs, opening cached singletons
+ * lazily. Memory DB and Knowledge DB are opened per-call by their routed
+ * handlers (existing pattern in tools.ts) — only CodeGraph + Data are
+ * cached here.
+ *
+ * @throws {CodegraphDbNotInitializedError} when tool needs codegraph but
+ *   `.codegraph/codegraph.db` is missing. Caller (handleRequest) catches
+ *   and translates to a structured `-32001` JSON-RPC error.
+ */
+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')) {
+    if (!codegraphDbCache) codegraphDbCache = getCodeGraphDb();  // throws CodegraphDbNotInitializedError on missing
+    codegraphDbResolved = codegraphDbCache;
+  }
+
+  return { needs, dataDb: dataDbResolved, codegraphDb: codegraphDbResolved };
 }
 
 async function handleRequest(request: JsonRpcRequest): Promise<JsonRpcResponse> {
@@ -93,14 +134,50 @@ async function handleRequest(request: JsonRpcRequest): Promise<JsonRpcResponse>
       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,
-      };
+      // Lazy per-tool DB resolution. Throws if tool needs codegraph and
+      // .codegraph/codegraph.db is missing; caught below and translated
+      // to a structured -32001 error preserving the request id.
+      try {
+        const { dataDb: lDb, codegraphDb: cgDb } = resolveDbsForTool(toolName);
+        const result = await handleToolCall(toolName, toolArgs, lDb, cgDb);
+        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,
+              },
+            },
+          };
+        }
+        // Other errors propagate to the outer catch in the stdio handler
+        throw err;
+      }
     }
 
     case 'ping': {
@@ -172,22 +249,45 @@ process.stdin.on('data', async (chunk: string) => {
 
     if (!line) continue;
 
+    // Two-phase error handling: separate JSON-parse failures (genuine
+    // -32700) from request-processing failures (-32603 Internal error,
+    // preserving the request id when parseable).
+    let request: JsonRpcRequest | null = null;
     try {
-      const request = JSON.parse(line) as JsonRpcRequest;
-      const response = await handleRequest(request);
+      request = JSON.parse(line) as JsonRpcRequest;
+    } catch (parseError) {
+      // Real JSON parse failure — -32700 per JSON-RPC §5.1, id MUST be null
+      // because we couldn't extract one.
+      const errorResponse: JsonRpcResponse = {
+        jsonrpc: '2.0',
+        id: null,
+        error: {
+          code: -32700,
+          message: `Parse error: ${parseError instanceof Error ? parseError.message : String(parseError)}`,
+        },
+      };
+      process.stdout.write(JSON.stringify(errorResponse) + '\n');
+      continue;
+    }
 
+    try {
+      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) {
+      // Request-processing failure — propagate the request id (not null).
+      // -32603 Internal error per JSON-RPC §5.1. Specific subclasses
+      // (codegraph-not-init, unknown-tool) are caught earlier in the
+      // tools/call handler and translated to structured -32001/-32602.
       const errorResponse: JsonRpcResponse = {
         jsonrpc: '2.0',
-        id: null,
+        id: request.id ?? null,
         error: {
-          code: -32700,
-          message: `Parse error: ${error instanceof Error ? error.message : String(error)}`,
+          code: -32603,
+          message: `Internal error: ${error instanceof Error ? error.message : String(error)}`,
         },
       };
       process.stdout.write(JSON.stringify(errorResponse) + '\n');
@@ -196,9 +296,10 @@ process.stdin.on('data', async (chunk: string) => {
 });
 
 process.stdin.on('end', () => {
-  // Clean up database connections
-  if (codegraphDb) codegraphDb.close();
-  if (dataDb) dataDb.close();
+  // Clean up cached DB connections (Memory + Knowledge are per-call,
+  // already closed in their routing branches).
+  if (codegraphDbCache) codegraphDbCache.close();
+  if (dataDbCache) dataDbCache.close();
   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');
+}

package/src/tools.ts

@@ -75,14 +75,26 @@ function stripPrefix(name: string): string {
 
 /**
  * Ensure indexes are built and up-to-date.
+ *
  * Lazy initialization: only rebuilds if stale.
+ *
+ * **Codegraph-optional**: `codegraphDb` is now optional. When omitted, the
+ * JS index section (imports, tRPC, pages, middleware — all derived from
+ * CodeGraph AST data) is skipped. The Python index section (which only
+ * reads Python source files via tree-sitter into Data DB) still runs.
+ * This supports the lazy-per-tool-DB design from
+ * `plan-1.6.2-server-lazy-db-deps`: Python tools and any tool that needs
+ * fresh Python indexes can call `ensureIndexes(dataDb)` without requiring
+ * a CodeGraph DB.
  */
-function ensureIndexes(dataDb: Database.Database, codegraphDb: Database.Database, force: boolean = false): string {
+function ensureIndexes(dataDb: Database.Database, codegraphDb?: Database.Database, force: boolean = false): string {
   const results: string[] = [];
   const config = getConfig();
 
-  // JS indexes
-  if (force || isDataStale(dataDb, codegraphDb)) {
+  // JS indexes — require CodeGraph DB. Skipped when codegraphDb is undefined
+  // (e.g., a Python tool or memory tool triggered ensureIndexes for its
+  // own Python-index needs without needing JS indexes).
+  if (codegraphDb !== undefined && (force || isDataStale(dataDb, codegraphDb))) {
     const importCount = buildImportIndex(dataDb, codegraphDb);
     results.push(`Import edges: ${importCount}`);
 
@@ -259,24 +271,65 @@ export function getToolDefinitions(): ToolDefinition[] {
   ]);
 }
 
+/**
+ * Defensive assertion: a routing branch that consumes Data DB requires it
+ * to have been resolved by the dispatcher. Should never fire — the manifest
+ * declares which tools need Data DB and `server.ts:resolveDbsForTool`
+ * resolves accordingly. A throw here indicates a manifest/code drift.
+ */
+function assertDataDb(dataDb: Database.Database | undefined, toolName: string): Database.Database {
+  if (!dataDb) {
+    throw new Error(`Internal: tool "${toolName}" routed to a Data-DB branch but dispatcher did not resolve Data DB. Check TOOL_DB_NEEDS manifest entry includes 'data'.`);
+  }
+  return dataDb;
+}
+
+/**
+ * Defensive assertion mirror of {@link assertDataDb} for CodeGraph DB.
+ */
+function assertCodegraphDb(codegraphDb: Database.Database | undefined, toolName: string): Database.Database {
+  if (!codegraphDb) {
+    throw new Error(`Internal: tool "${toolName}" routed to a CodeGraph branch but dispatcher did not resolve CodeGraph DB. Check TOOL_DB_NEEDS manifest entry includes 'codegraph'.`);
+  }
+  return codegraphDb;
+}
+
 /**
  * Handle a tool call and return the result.
+ *
+ * **Pre-dispatch ordering invariant (P-A-002c, plan-1.6.2-server-lazy-db-deps)**:
+ *   1. Tier gate (`isToolAllowed`) — checked BEFORE any DB access so
+ *      free-tier users cannot provoke DB errors on paid tools.
+ *   2. Per-family routing (memory/observability/sentinel/knowledge/...) —
+ *      each family opens ONLY the DB connections its handler needs.
+ *   3. Code-intel families (Python, core JS) invoke `ensureIndexes` at
+ *      the top of their branch with the DBs they have. ensureIndexes is
+ *      NEVER called unconditionally for memory/audit/knowledge/etc.
+ *
+ * **DB params**: `dataDb` and `codegraphDb` are OPTIONAL — the dispatcher
+ * (`server.ts:resolveDbsForTool`) resolves them based on the tool's entry
+ * in `TOOL_DB_NEEDS`. Memory/Knowledge DBs are opened per-call inside
+ * their routing branches (existing pattern, unchanged).
+ *
+ * **Defensive checks**: branches that require a DB call `assertDataDb`
+ * or `assertCodegraphDb` first. These should never fire — `TOOL_DB_NEEDS`
+ * guarantees the dispatcher resolved the right DBs — but the runtime
+ * check catches manifest/code drift loudly instead of silently passing
+ * `undefined` into handlers.
  */
 export async function handleToolCall(
   name: string,
   args: Record<string, unknown>,
-  dataDb: Database.Database,
-  codegraphDb: Database.Database
+  dataDb?: Database.Database,
+  codegraphDb?: Database.Database
 ): Promise<ToolResult> {
-  // P3-017: Tier gate — check before any routing
+  // P3-017: Tier gate — check before any routing (ordering invariant step 1)
   const userTier = await getCurrentTier();
   const requiredTier = getToolTier(name);
   if (!isToolAllowed(name, userTier)) {
     return text(`This tool requires ${requiredTier} tier. Current tier: ${userTier}. Upgrade at https://massu.ai/pricing`);
   }
 
-  // Ensure indexes are built before any tool call
-  const syncMessage = ensureIndexes(dataDb, codegraphDb);
   const pfx = prefix();
 
   try {
@@ -307,7 +360,7 @@ export async function handleToolCall(
 
     // Route sentinel tools to sentinel handler
     if (name.startsWith(pfx + '_sentinel_')) {
-      return handleSentinelToolCall(name, args, dataDb);
+      return handleSentinelToolCall(name, args, assertDataDb(dataDb, name));
     }
 
     // Route analytics layer tools
@@ -375,9 +428,13 @@ export async function handleToolCall(
       finally { knowledgeDb.close(); }
     }
 
-    // Route Python tools (uses dataDb, not memDb)
+    // Route Python tools (uses dataDb only; codegraphDb not required).
+    // ensureIndexes runs WITHOUT codegraphDb — only the Python-index section
+    // rebuilds (against dataDb). JS-index section is skipped (no codegraph).
     if (isPythonTool(name)) {
-      return handlePythonToolCall(name, args, dataDb);
+      const pyDataDb = assertDataDb(dataDb, name);
+      ensureIndexes(pyDataDb);
+      return handlePythonToolCall(name, args, pyDataDb);
     }
 
     // Route license tools
@@ -387,22 +444,51 @@ export async function handleToolCall(
       finally { memDb.close(); }
     }
 
-    // Match core tools by base name
+    // Match core tools by base name. Each codegraph-dependent core tool
+    // asserts both DBs and runs ensureIndexes (full JS + Python rebuild
+    // when stale).
     const baseName = stripPrefix(name);
     switch (baseName) {
-      case 'sync':
-        return handleSync(dataDb, codegraphDb);
-      case 'context':
-        return handleContext(args.file as string, dataDb, codegraphDb);
-      case 'trpc_map':
-        return handleTrpcMap(args, dataDb);
-      case 'coupling_check':
-        return handleCouplingCheck(args, dataDb, codegraphDb);
-      case 'impact':
-        return handleImpact(args.file as string, dataDb, codegraphDb);
-      case 'domains':
-        return handleDomains(args, dataDb, codegraphDb);
+      case 'sync': {
+        const d = assertDataDb(dataDb, name);
+        const c = assertCodegraphDb(codegraphDb, name);
+        return handleSync(d, c);
+      }
+      case 'context': {
+        const d = assertDataDb(dataDb, name);
+        const c = assertCodegraphDb(codegraphDb, name);
+        ensureIndexes(d, c);
+        return handleContext(args.file as string, d, c);
+      }
+      case 'trpc_map': {
+        const d = assertDataDb(dataDb, name);
+        // trpc_map needs the tRPC index in Data DB. The index is built by
+        // ensureIndexes' JS section, which requires CodeGraph DB. If
+        // codegraphDb is provided (manifest declares 'codegraph'), rebuild
+        // the index; otherwise read whatever stale index exists.
+        ensureIndexes(d, codegraphDb);
+        return handleTrpcMap(args, d);
+      }
+      case 'coupling_check': {
+        const d = assertDataDb(dataDb, name);
+        const c = assertCodegraphDb(codegraphDb, name);
+        ensureIndexes(d, c);
+        return handleCouplingCheck(args, d, c);
+      }
+      case 'impact': {
+        const d = assertDataDb(dataDb, name);
+        const c = assertCodegraphDb(codegraphDb, name);
+        ensureIndexes(d, c);
+        return handleImpact(args.file as string, d, c);
+      }
+      case 'domains': {
+        const d = assertDataDb(dataDb, name);
+        const c = assertCodegraphDb(codegraphDb, name);
+        ensureIndexes(d, c);
+        return handleDomains(args, d, c);
+      }
       case 'schema':
+        // Filesystem-only; no DB access.
         return handleSchema(args);
       default:
         return text(`Unknown tool: ${name}`);