@massu/core 1.6.0 → 1.6.2

package/dist/hooks/session-start.js

@@ -8690,25 +8690,20 @@ init_parse_guard();
 import { Parser as Parser6 } from "web-tree-sitter";
 init_parse_guard();
 
-// ../adapter-go-chi/dist/index.js
-import { Parser as Parser8 } from "web-tree-sitter";
+// src/detect/adapters/go-chi.ts
+import { goChiAdapter } from "@massu/adapter-go-chi";
 
-// dist/adapter.js
-import { Query as Query2 } from "web-tree-sitter";
-import { Language as Language2, Parser as Parser7 } from "web-tree-sitter";
-var MAX_AST_FILE_BYTES2 = 1 * 1024 * 1024;
+// src/detect/adapters/rails.ts
+import { railsAdapter } from "@massu/adapter-rails";
 
-// ../adapter-rails/dist/index.js
-import { Parser as Parser9 } from "web-tree-sitter";
+// src/detect/adapters/phoenix.ts
+import { phoenixAdapter } from "@massu/adapter-phoenix";
 
-// ../adapter-phoenix/dist/index.js
-import { Parser as Parser10 } from "web-tree-sitter";
+// src/detect/adapters/aspnet.ts
+import { aspnetAdapter } from "@massu/adapter-aspnet";
 
-// ../adapter-aspnet/dist/index.js
-import { Parser as Parser11 } from "web-tree-sitter";
-
-// ../adapter-spring/dist/index.js
-import { Parser as Parser12 } from "web-tree-sitter";
+// src/detect/adapters/spring.ts
+import { springAdapter } from "@massu/adapter-spring";
 
 // src/detect/codebase-introspector.ts
 function introspect(detection, projectRoot) {

package/docs/AUTHORING-ADAPTERS.md

@@ -200,6 +200,47 @@ adapter authors to opt-in to the new shape.
 Additive changes (new optional fields on result types, new
 TreeSitterLanguage enum entries) are minor-version compatible.
 
+## Manifest sha256 round-trip — what to do when CI fails
+
+> Plan 3c Phase 9b P-D-004 runbook excerpt.
+
+The `tarball-e2e` CI job runs `adapter-manifest-roundtrip.test.ts` against the
+live registry manifest at `https://registry.massu.ai/adapters/manifest.json`.
+The test rebuilds every workspace adapter's `dist/`, computes the sha256, and
+asserts it matches the manifest's `sha256` entry for that `{package, version}`
+pair.
+
+**If the round-trip fails after a workspace adapter source edit**, the
+manifest must be re-signed BEFORE merge. The flow:
+
+1. **Verify your edit is intentional.** Run `npm run build` from the repo
+   root and inspect `git diff packages/adapter-<f>/dist/`. If the diff is
+   non-trivial, the source change is real and needs a manifest re-sign.
+2. **Bump the adapter version** in `packages/adapter-<f>/package.json` (e.g.
+   `1.0.0` → `1.0.1` for a bugfix; `1.1.0` for an additive feature). Manifest
+   entries are versioned, so re-signing without a version bump would break
+   reproducibility for users on the prior version.
+3. **Compute the new sha256** via `node packages/core/scripts/compute-adapter-shasums.mjs`
+   (or equivalent) — this writes to `~/.massu/build-shasums.json`.
+4. **Re-sign the manifest.** Run `bash scripts/provision/registry-publish.sh
+   path/to/manifest-body.json` — reads the Ed25519 private key from macOS
+   Keychain (`massu/registry/signing/private`), produces an envelope, deploys
+   to Vercel.
+5. **Re-run the round-trip test locally**: `MASSU_MANIFEST_ROUNDTRIP=1 npm test
+   -- adapter-manifest-roundtrip` — should now PASS.
+6. **Commit + open PR**. The CI gate will re-verify against the freshly-deployed
+   manifest.
+
+If CI fails on a transient registry outage (5xx, DNS, CDN cache miss), the
+test SKIPs cleanly with a console.warn — does NOT fail the job. Re-run the
+job to recover.
+
+**Non-monorepo adapter authors** (third-party packages NOT under `packages/adapter-*`):
+the round-trip test SKIPs your package automatically (workspace dir absent in
+the monorepo). Your install-time verification chain runs against the registry
+sha256 directly via `discover.ts:295-360` — that path catches the same drift
+class without requiring the test.
+
 ## See also
 
 - [`SECURITY.md`](./SECURITY.md) — signing model, key rotation, supply-chain risks

package/docs/SECURITY.md

@@ -240,6 +240,45 @@ per the canonical plan). The maintainer will:
 5. Add the affected adapter to the manifest's `unpublished: true` list
    if applicable, so all consumers refuse to load on next refresh.
 
+## Migration: 1.5.x → 1.6.0 (workspace adapter publish)
+
+> Plan 3c Phase 9b shipped 2026-05-09. See root `CHANGELOG.md` `[1.6.0]`.
+
+`1.6.0` is **additive** — end-users on `1.5.x` are unaffected. No
+breaking changes. No config migration. The 5 first-party AST adapters
+(`rails`, `phoenix`, `aspnet`, `spring`, `go-chi`) continue to ship
+CORE-BUNDLED in `@massu/core` itself; zero-config detection still works
+out of the box.
+
+What's new for users who want REGISTRY-VERIFIED trust:
+
+```bash
+npm install @massu/core@^1.6.0 @massu/adapter-rails@^1.0.0
+```
+
+After install, `npx massu adapters list` will show TWO entries for
+`rails`:
+
+- `rails` — CORE-BUNDLED (from `@massu/core`'s bundled `dist/detect/adapters/rails.js`).
+- `@massu/adapter-rails` — REGISTRY-VERIFIED (from `node_modules/@massu/adapter-rails/dist/`,
+  sha256-cross-checked against the signed manifest at
+  `https://registry.massu.ai/adapters/manifest.json`).
+
+The two co-exist. Discovery prefers REGISTRY-VERIFIED when present
+(the standalone package opts the user into the more-verified path);
+CORE-BUNDLED remains the fallback. There is no "elevation" — they are
+two distinct trust-class entries.
+
+### peerDependency note
+
+`@massu/adapter-*@1.0.0` declares `peerDependencies: { "@massu/core": "^1.6.0" }`.
+Users pinning `@massu/core@1.5.x` who install a standalone adapter will
+see an npm peerDep warning (non-fatal). For cleanest UX, upgrade
+`@massu/core` to `^1.6.0` before installing standalone adapters. The
+adapter source is binary-identical between CORE-BUNDLED and
+REGISTRY-VERIFIED — the warning is informational, not a runtime
+incompatibility.
+
 ## See also
 
 - [`AUTHORING-ADAPTERS.md`](./AUTHORING-ADAPTERS.md) — how to write a

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@massu/core",
-  "version": "1.6.0",
+  "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",
@@ -22,8 +22,8 @@
     "build:adapter-types": "tsc -p tsconfig.adapter-types.json",
     "build:adapter-subpath": "tsx scripts/bundle-adapters.ts --subpath-only",
     "build:bundle-adapters": "tsx scripts/bundle-adapters.ts",
-    "build:cli": "esbuild --bundle --platform=node --format=esm --outfile=dist/cli.js src/cli.ts --external:better-sqlite3 --external:yaml --external:zod --external:chokidar --external:proper-lockfile --external:fsevents --external:web-tree-sitter --external:tweetnacl --external:tar --external:smol-toml --external:vscode-languageserver-protocol --banner:js='#!/usr/bin/env node\nimport{createRequire as __cr}from\"module\";const require=__cr(import.meta.url);'",
-    "build:hooks": "esbuild --bundle --platform=node --format=esm --outdir=dist/hooks src/hooks/*.ts --external:better-sqlite3 --external:yaml --external:zod --external:chokidar --external:proper-lockfile --external:fsevents --external:web-tree-sitter --external:tweetnacl --external:tar --external:smol-toml --external:vscode-languageserver-protocol --banner:js='import{createRequire as __cr}from\"module\";const require=__cr(import.meta.url);'",
+    "build:cli": "esbuild --bundle --platform=node --format=esm --outfile=dist/cli.js src/cli.ts --external:better-sqlite3 --external:yaml --external:zod --external:chokidar --external:proper-lockfile --external:fsevents --external:web-tree-sitter --external:tweetnacl --external:tar --external:smol-toml --external:vscode-languageserver-protocol --external:@massu/adapter-rails --external:@massu/adapter-phoenix --external:@massu/adapter-aspnet --external:@massu/adapter-spring --external:@massu/adapter-go-chi --banner:js='#!/usr/bin/env node\nimport{createRequire as __cr}from\"module\";const require=__cr(import.meta.url);'",
+    "build:hooks": "esbuild --bundle --platform=node --format=esm --outdir=dist/hooks src/hooks/*.ts --external:better-sqlite3 --external:yaml --external:zod --external:chokidar --external:proper-lockfile --external:fsevents --external:web-tree-sitter --external:tweetnacl --external:tar --external:smol-toml --external:vscode-languageserver-protocol --external:@massu/adapter-rails --external:@massu/adapter-phoenix --external:@massu/adapter-aspnet --external:@massu/adapter-spring --external:@massu/adapter-go-chi --banner:js='import{createRequire as __cr}from\"module\";const require=__cr(import.meta.url);'",
     "prepublishOnly": "bash ../../scripts/prepublish-check.sh && node ../../scripts/bundle-pubkey.mjs && npm run build",
     "bench:watch": "tsx test/perf/watch-benchmark.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-09T23:01:13.664Z.
+// 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');
+}