@ctxo/cli 0.12.0 → 0.13.0

package/dist/index.js

@@ -3,6 +3,8 @@ import {
   ArchitecturalOverlay,
   BlastRadiusCalculator,
   BoundaryViolationDetector,
+  CoChangeReader,
+  ContextsViewReader,
   DeadCodeDetector,
   DriftDetector,
   PageRankCalculator,
@@ -11,18 +13,23 @@ import {
   SimpleGitAdapter,
   SqliteStorageAdapter,
   SymbolGraph,
+  SymbolTokenizer,
+  compareCodepoint,
   detectWorkspace,
-  loadCoChangeMap,
+  findCoChangedFilesForBlastRadius,
   loadConfig,
   makeGlobMatcher,
   maskingClusterLabelPatterns,
   statsEnabled
-} from "./chunk-HZ4UGA6J.js";
+} from "./chunk-BYX3UFBJ.js";
 import "./chunk-RFEXMBTG.js";
 import {
   DetailLevelSchema,
-  JsonIndexReader
-} from "./chunk-CDGQGCVN.js";
+  EdgeKindSchema,
+  JsonIndexReader,
+  SYMBOL_KINDS,
+  SymbolKindSchema
+} from "./chunk-DT3ZH4AU.js";
 import {
   createLogger
 } from "./chunk-5DSKZJNN.js";
@@ -102,10 +109,20 @@ async function startHttpTransport(serverFactory, port) {
   });
 }
 
+// src/cli/http-port.ts
+var DEFAULT_HTTP_PORT = "3001";
+function resolveHttpPort(args, env) {
+  const fromEnv = env["CTXO_HTTP_PORT"] || null;
+  if (args.length === 0) return fromEnv;
+  if (!args.includes("--http")) return null;
+  const portFlag = args.indexOf("--port");
+  return fromEnv || (portFlag === -1 ? void 0 : args[portFlag + 1]) || DEFAULT_HTTP_PORT;
+}
+
 // src/index.ts
 import { z as z15 } from "zod";
-import { existsSync as existsSync2, readFileSync as readFileSync2 } from "fs";
-import { join as join2, dirname } from "path";
+import { existsSync, readFileSync } from "fs";
+import { join, dirname } from "path";
 import { fileURLToPath } from "url";
 
 // src/core/masking/masking-pipeline.ts
@@ -166,10 +183,10 @@ var LogicSliceQuery = class {
   getLogicSlice(graph, symbolId, maxDepth = Infinity) {
     const root = graph.getNode(symbolId);
     if (!root) return void 0;
-    const visited = /* @__PURE__ */ new Set([symbolId]);
+    const visited = /* @__PURE__ */ new Set([root.symbolId]);
     const dependencies = [];
     const collectedEdges = [];
-    const queue = [{ id: symbolId, depth: 0 }];
+    const queue = [{ id: root.symbolId, depth: 0 }];
     while (queue.length > 0) {
       const current = queue.shift();
       if (current.depth >= maxDepth) continue;
@@ -191,6 +208,11 @@ var LogicSliceQuery = class {
 // src/core/detail-levels/detail-formatter.ts
 var L1_MAX_LINES = 150;
 var L4_TOKEN_BUDGET = 8e3;
+function withoutAnnotations(node) {
+  if (node.annotations === void 0) return node;
+  const { annotations: _annotations, ...rest } = node;
+  return rest;
+}
 var DetailFormatter = class {
   format(slice, level) {
     switch (level) {
@@ -209,7 +231,7 @@ var DetailFormatter = class {
     const lineCount = root.endLine - root.startLine + 1;
     const clampedRoot = lineCount > L1_MAX_LINES ? { ...root, endLine: root.startLine + L1_MAX_LINES - 1 } : root;
     return {
-      root: clampedRoot,
+      root: withoutAnnotations(clampedRoot),
       dependencies: [],
       edges: [],
       level: 1,
@@ -222,8 +244,8 @@ var DetailFormatter = class {
     const directDepIds = new Set(directEdges.map((e) => e.to));
     const directDeps = slice.dependencies.filter((d) => directDepIds.has(d.symbolId));
     return {
-      root: slice.root,
-      dependencies: directDeps,
+      root: withoutAnnotations(slice.root),
+      dependencies: directDeps.map(withoutAnnotations),
       edges: directEdges,
       level: 2,
       levelDescription: "L2: Root + direct dependencies (depth 1)"
@@ -231,8 +253,8 @@ var DetailFormatter = class {
   }
   formatL3(slice) {
     return {
-      root: slice.root,
-      dependencies: slice.dependencies,
+      root: withoutAnnotations(slice.root),
+      dependencies: slice.dependencies.map(withoutAnnotations),
       edges: slice.edges,
       level: 3,
       levelDescription: "L3: Full transitive dependency closure"
@@ -313,6 +335,7 @@ var TRUNCATABLE_FIELDS = {
   deadFiles: "Use find_dead_code with includeTests to adjust scope.",
   files: "Use get_changed_symbols with a narrower since ref or smaller maxFiles.",
   clusters: "Use get_architectural_overlay with mode=communities and layer filter for a focused view.",
+  candidates: "Use get_architectural_overlay with mode=contexts and candidate: <id> for one candidate in full, or ctxo contexts --json for the full contexts view.",
   clustersAffected: "Use get_blast_radius on individual changed symbols for per-cluster impact."
 };
 function getThreshold() {
@@ -472,10 +495,11 @@ function buildGraphFromStorage(storage) {
 function buildGraphAndFilesFromJsonIndex(ctxoRoot) {
   const reader = new JsonIndexReader(ctxoRoot);
   const indices = reader.readAll();
+  return { graph: buildGraphFromIndices(indices), indexedFiles: indices.map((fileIndex) => fileIndex.file) };
+}
+function buildGraphFromIndices(indices) {
   const graph = new SymbolGraph();
-  const indexedFiles = [];
   for (const fileIndex of indices) {
-    indexedFiles.push(fileIndex.file);
     for (const sym of fileIndex.symbols) {
       graph.addNode(sym);
     }
@@ -485,7 +509,7 @@ function buildGraphAndFilesFromJsonIndex(ctxoRoot) {
       graph.addEdge(edge);
     }
   }
-  return { graph, indexedFiles };
+  return graph;
 }
 function getGraphAndFiles(ctxoRoot, storage) {
   const json = buildGraphAndFilesFromJsonIndex(ctxoRoot);
@@ -585,6 +609,10 @@ async function buildSnapshotStaleness(storage, git) {
 }
 
 // src/adapters/mcp/get-why-context.ts
+function graphOf(indices, storage) {
+  const graph = buildGraphFromIndices(indices);
+  return graph.nodeCount > 0 ? graph : buildGraphFromStorage(storage);
+}
 var InputSchema2 = z2.object({
   symbolId: z2.string().min(1),
   maxCommits: z2.number().int().min(1).optional()
@@ -601,15 +629,15 @@ function handleGetWhyContext(storage, git, masking, staleness, ctxoRoot = ".ctxo
           content: [{ type: "text", text: JSON.stringify({ error: true, message: parsed.error.message }) }]
         };
       }
-      const { symbolId, maxCommits } = parsed.data;
-      const symbol = storage.getSymbolById(symbolId);
-      if (!symbol) {
+      const { symbolId: inputId, maxCommits } = parsed.data;
+      const indices = indexReader.readAll();
+      const symbolId = storage.getSymbolById(inputId) ? inputId : graphOf(indices, storage).getNode(inputId)?.symbolId;
+      if (!symbolId) {
         return {
           content: [{ type: "text", text: JSON.stringify({ found: false, hint: 'Symbol not found. Run "ctxo index" to build the codebase index.' }) }]
         };
       }
       const filePath = symbolId.split("::")[0];
-      const indices = indexReader.readAll();
       const fileIndex = indices.find((i) => i.file === filePath);
       let commitHistory;
       let antiPatterns;
@@ -645,6 +673,7 @@ function handleGetWhyContext(storage, git, masking, staleness, ctxoRoot = ".ctxo
             events: relevant,
             confidence: drift.confidence,
             snapshotsAvailable: drift.snapshotsAvailable,
+            distinctCommits: drift.distinctCommits,
             stabilitySummary: drift.stability,
             ...drift.hint ? { hint: drift.hint } : {}
           };
@@ -789,7 +818,7 @@ var InputSchema4 = z4.object({
   confidence: z4.enum(["confirmed", "likely", "potential"]).optional(),
   intent: z4.string().optional().describe('Filter results by intent keywords (e.g., "test", "adapter", "security")')
 });
-function handleGetBlastRadius(storage, masking, staleness, ctxoRoot = ".ctxo", git, clusterLabelMasker) {
+function handleGetBlastRadius(storage, masking, staleness, ctxoRoot = ".ctxo", git, clusterLabelMasker, coChange) {
   const calculator = new BlastRadiusCalculator();
   const getGraph = () => getGraphAndFiles(ctxoRoot, storage);
   return async (args) => {
@@ -802,12 +831,15 @@ function handleGetBlastRadius(storage, masking, staleness, ctxoRoot = ".ctxo", g
       }
       const { symbolId } = parsed.data;
       const { graph, indexedFiles } = getGraph();
-      if (!graph.hasNode(symbolId)) {
+      const root = graph.getNode(symbolId);
+      if (!root) {
         return {
           content: [{ type: "text", text: JSON.stringify({ found: false, hint: 'Symbol not found. Run "ctxo index" to build the codebase index.' }) }]
         };
       }
-      const result = calculator.calculate(graph, symbolId);
+      const rootId = root.symbolId;
+      const coChangeMap = coChange?.readCoChangeMap();
+      const result = calculator.calculate(graph, rootId, coChangeMap);
       let symbols = result.impactedSymbols;
       if (parsed.data.confidence) {
         symbols = symbols.filter((s) => s.confidence === parsed.data.confidence);
@@ -818,7 +850,7 @@ function handleGetBlastRadius(storage, masking, staleness, ctxoRoot = ".ctxo", g
       const potentialCount = symbols.filter((s) => s.confidence === "potential").length;
       const rawSnapshot = storage.readCommunities();
       const snapshot = rawSnapshot && clusterLabelMasker?.isEnabled() ? clusterLabelMasker.maskSnapshot(rawSnapshot) : rawSnapshot;
-      const clusterBreakdown = snapshot ? computeClusterBreakdown(snapshot, symbolId, symbols.map((s) => s.symbolId)) : void 0;
+      const clusterBreakdown = snapshot ? computeClusterBreakdown(snapshot, rootId, symbols.map((s) => s.symbolId)) : void 0;
       const body = {
         symbolId,
         impactScore: symbols.length,
@@ -836,6 +868,8 @@ function handleGetBlastRadius(storage, masking, staleness, ctxoRoot = ".ctxo", g
           body.multiClusterHint = clusterBreakdown.multiClusterHint;
         }
       }
+      const coChangedFiles = findCoChangedFilesForBlastRadius(coChangeMap, rootId, result.impactedSymbols);
+      if (coChangedFiles.length > 0) body.coChangedFiles = coChangedFiles;
       const stalenessMeta = git ? await buildSnapshotStaleness(storage, git) : void 0;
       const extras = stalenessMeta ? { snapshotStaleness: stalenessMeta } : void 0;
       const payload = masking.mask(JSON.stringify(wrapResponse(body, extras)));
@@ -856,10 +890,11 @@ function handleGetBlastRadius(storage, masking, staleness, ctxoRoot = ".ctxo", g
 
 // src/adapters/mcp/get-architectural-overlay.ts
 import { z as z5 } from "zod";
-var OVERLAY_MODES = ["regex", "communities", "both"];
+var OVERLAY_MODES = ["regex", "communities", "both", "contexts"];
 var InputSchema5 = z5.object({
   layer: z5.string().optional(),
-  mode: z5.enum(OVERLAY_MODES).optional()
+  mode: z5.enum(OVERLAY_MODES).optional(),
+  candidate: z5.number().int().positive().optional()
 });
 function buildCommunityOverlay(snapshot, options = {}) {
   const previewLimit = options.memberPreviewLimit ?? 15;
@@ -904,7 +939,136 @@ function buildCommunityOverlay(snapshot, options = {}) {
     commitSha: snapshot.commitSha
   };
 }
-function handleGetArchitecturalOverlay(storage, masking, staleness, git, clusterLabelMasker) {
+var HUB_COLLISION_LIMIT = 50;
+var SUMMARY_TERM_LIMIT = 5;
+var DETAIL_FILE_LIMIT = 15;
+var DETAIL_COLLISION_LIMIT = 10;
+var DETAIL_OCCURRENCE_LIMIT = 5;
+var DETAIL_DATA_LIMIT = 15;
+var DETAIL_ACCESS_LIMIT = 10;
+var NO_VIEW_HINT = "No contexts view available. Run ctxo index to generate one.";
+var SUMMARY_HINT = "Pass candidate: <id> for one candidate in full; run ctxo contexts --json for the whole view.";
+var DETAIL_HINT = "Run ctxo contexts --json for full member sets.";
+function labelMaskerFor(view, labelMasker) {
+  const masker = labelMasker?.isEnabled() ? labelMasker : void 0;
+  if (!masker) return (label) => label;
+  for (const label of [...new Set(view.candidates.map((c) => c.label))].sort(compareCodepoint)) masker.mask(label);
+  return (label) => masker.mask(label);
+}
+function collisionSummary(collision) {
+  return {
+    name: collision.name,
+    minJaccard: collision.minJaccard,
+    candidates: [...new Set(collision.occurrences.map((occurrence) => occurrence.candidate))].sort((a, b) => a - b),
+    occurrenceCount: collision.occurrences.length
+  };
+}
+function contextsSummary(view, maskLabel) {
+  return {
+    commitSha: view.commitSha,
+    coverage: view.coverage,
+    candidates: view.candidates.map((candidate) => ({
+      id: candidate.id,
+      label: maskLabel(candidate.label),
+      fingerprint: candidate.fingerprint,
+      fileCount: candidate.fileCount,
+      cohesion: candidate.cohesion,
+      topTerms: candidate.topTerms.slice(0, SUMMARY_TERM_LIMIT),
+      ...candidate.sharedTables.length > 0 ? { sharedTableCount: candidate.sharedTables.length } : {}
+    })),
+    hubs: view.hubs.slice(0, HUB_COLLISION_LIMIT).map((hub) => ({
+      file: hub.file,
+      reasons: hub.reasons,
+      ...hub.candidate !== void 0 ? { candidate: hub.candidate } : {}
+    })),
+    hubsTotal: view.hubs.length,
+    collisions: view.collisions.slice(0, HUB_COLLISION_LIMIT).map(collisionSummary),
+    collisionsTotal: view.collisions.length,
+    unclustered: { count: view.unclustered.count },
+    dataResourcesTotal: view.dataResources.length,
+    sharedResourcesTotal: view.dataResources.filter((resource) => resource.accesses.length >= 2).length,
+    externalResourcesTotal: view.dataResources.filter((resource) => resource.external).length,
+    hint: SUMMARY_HINT
+  };
+}
+function sharedTableDetail(table, id) {
+  const own = table.accesses.filter((access) => access.candidate === id);
+  const others = table.accesses.filter((access) => access.candidate !== id).slice(0, DETAIL_ACCESS_LIMIT - own.length);
+  return {
+    ...table,
+    accesses: [...own, ...others].sort((a, b) => a.candidate - b.candidate),
+    accessCount: table.accesses.length
+  };
+}
+function ownDataResources(view, id) {
+  const own = [];
+  for (const resource of view.dataResources) {
+    const access = resource.accesses.find((entry) => entry.candidate === id);
+    if (!access) continue;
+    own.push({
+      name: resource.name,
+      ...resource.kind !== void 0 ? { kind: resource.kind } : {},
+      external: resource.external,
+      modes: access.modes,
+      ...resource.owner !== void 0 ? { owner: resource.owner } : {},
+      writerCount: resource.writers.length
+    });
+  }
+  return own;
+}
+function contextsDetail(view, id, maskLabel, extras) {
+  const candidate = view.candidates.find((c) => c.id === id);
+  if (!candidate) {
+    return { found: false, hint: `No candidate ${id} in the contexts view. Call without candidate for the list.` };
+  }
+  const hubs = view.hubs.filter((hub) => hub.candidate === id);
+  const collisions = view.collisions.filter(
+    (collision) => collision.occurrences.some((occurrence) => occurrence.candidate === id)
+  );
+  const dataResources = ownDataResources(view, id);
+  const shownTables = candidate.sharedTables.slice(0, DETAIL_DATA_LIMIT).map((table) => sharedTableDetail(table, id));
+  const shownResources = dataResources.slice(0, DETAIL_DATA_LIMIT);
+  const body = {
+    commitSha: view.commitSha,
+    candidate: {
+      ...candidate,
+      label: maskLabel(candidate.label),
+      files: candidate.files.slice(0, DETAIL_FILE_LIMIT),
+      sharedTables: shownTables,
+      sharedTableCount: candidate.sharedTables.length
+    },
+    hubs: hubs.slice(0, HUB_COLLISION_LIMIT).map((hub) => ({ file: hub.file, reasons: hub.reasons, dependents: hub.dependents, damping: hub.damping })),
+    hubsTotal: hubs.length,
+    collisions: collisions.slice(0, DETAIL_COLLISION_LIMIT).map((collision) => ({
+      ...collisionSummary(collision),
+      occurrences: collision.occurrences.filter((occurrence) => occurrence.candidate === id).slice(0, DETAIL_OCCURRENCE_LIMIT).map((occurrence) => ({
+        symbolId: occurrence.symbolId,
+        members: occurrence.members.slice(0, DETAIL_OCCURRENCE_LIMIT),
+        memberCount: occurrence.members.length
+      }))
+    })),
+    collisionsTotal: collisions.length,
+    dataResources: shownResources,
+    dataResourcesTotal: dataResources.length,
+    hint: DETAIL_HINT
+  };
+  fitDataToLimit(body, shownTables, shownResources, extras);
+  return body;
+}
+function fitDataToLimit(body, tables, resources, extras) {
+  const limit = getThreshold();
+  const size = () => Buffer.byteLength(JSON.stringify(wrapResponse(body, extras)), "utf-8");
+  while ((tables.length > 0 || resources.length > 0) && size() > limit) {
+    if (resources.length >= tables.length) resources.pop();
+    else tables.pop();
+  }
+}
+function buildContextsOverlay(view, options = {}) {
+  if (!view) return { found: false, hint: NO_VIEW_HINT };
+  const maskLabel = labelMaskerFor(view, options.labelMasker);
+  return options.candidate === void 0 ? contextsSummary(view, maskLabel) : contextsDetail(view, options.candidate, maskLabel, options.extras);
+}
+function handleGetArchitecturalOverlay(storage, masking, staleness, git, clusterLabelMasker, contextsView) {
   const overlay = new ArchitecturalOverlay();
   return async (args) => {
     try {
@@ -935,6 +1099,15 @@ function handleGetArchitecturalOverlay(storage, masking, staleness, git, cluster
         );
         return { content: buildContent(payload2) };
       }
+      if (mode === "contexts") {
+        const body2 = buildContextsOverlay(contextsView?.readContextsView(), {
+          candidate: parsed.data.candidate,
+          labelMasker: clusterLabelMasker,
+          extras
+        });
+        const payload2 = masking.mask(JSON.stringify(wrapResponse(body2, extras)));
+        return { content: buildContent(payload2) };
+      }
       const rawSnapshot = mode === "regex" ? void 0 : storage.readCommunities();
       const snapshot = rawSnapshot && clusterLabelMasker?.isEnabled() ? clusterLabelMasker.maskSnapshot(rawSnapshot) : rawSnapshot;
       const community = snapshot ? buildCommunityOverlay(snapshot) : void 0;
@@ -1036,12 +1209,18 @@ var DEFAULT_TOKEN_BUDGET = 4e3;
 var ContextAssembler = class {
   logicSlice = new LogicSliceQuery();
   blastRadius = new BlastRadiusCalculator();
-  assembleForTask(graph, symbolId, taskType, indices, tokenBudget = DEFAULT_TOKEN_BUDGET) {
+  /**
+   * `coChangeMap` is the same lookup `get_blast_radius` uses: with it, a potential dependent whose file
+   * co-changes with the target's becomes likely. It changes the tier shown on an entry, not which entries
+   * make the context or how they rank.
+   */
+  assembleForTask(graph, symbolId, taskType, indices, tokenBudget = DEFAULT_TOKEN_BUDGET, coChangeMap) {
     const target = graph.getNode(symbolId);
     if (!target) return void 0;
+    const targetId = target.symbolId;
     const weights = getWeightsForTask(taskType);
-    const slice = this.logicSlice.getLogicSlice(graph, symbolId);
-    const blastResult = this.blastRadius.calculate(graph, symbolId);
+    const slice = this.logicSlice.getLogicSlice(graph, targetId);
+    const blastResult = this.blastRadius.calculate(graph, targetId, coChangeMap);
     const candidateMap = /* @__PURE__ */ new Map();
     if (slice) {
       for (const dep of slice.dependencies) {
@@ -1057,10 +1236,11 @@ var ContextAssembler = class {
       const existing = candidateMap.get(entry.symbolId);
       if (existing) {
         existing.signals.isDependent = true;
+        existing.signals.dependentConfidence = entry.confidence;
       } else {
         candidateMap.set(entry.symbolId, {
           node,
-          signals: { isDirectDep: false, isInterfaceOrType: this.isInterfaceOrType(node.kind), isDependent: true, complexity: 0, hasAntiPattern: false }
+          signals: { isDirectDep: false, isInterfaceOrType: this.isInterfaceOrType(node.kind), isDependent: true, dependentConfidence: entry.confidence, complexity: 0, hasAntiPattern: false }
         });
       }
     }
@@ -1087,12 +1267,12 @@ var ContextAssembler = class {
       totalTokens += entry.tokens;
     }
     const warnings = [];
-    const targetFile = symbolId.split("::")[0] ?? "";
+    const targetFile = targetId.split("::")[0] ?? "";
     const targetIndex = fileIndexMap.get(targetFile);
     if (targetIndex && targetIndex.antiPatterns.length > 0) {
       warnings.push(`\u26A0 Target symbol has ${targetIndex.antiPatterns.length} anti-pattern(s) in file history`);
     }
-    return { target, taskType, context, totalTokens, tokenBudget, warnings };
+    return { target: withoutAnnotations(target), taskType, context, totalTokens, tokenBudget, warnings };
   }
   assembleRanked(graph, query, strategy = "combined", tokenBudget = DEFAULT_TOKEN_BUDGET) {
     const allNodes = graph.allNodes();
@@ -1169,7 +1349,8 @@ var ContextAssembler = class {
       relevanceScore: this.computeScore(signals, weights),
       reason: reasons.join(", ") || "related symbol",
       lines: node.endLine - node.startLine + 1,
-      tokens: this.estimateTokens(node)
+      tokens: this.estimateTokens(node),
+      ...signals.dependentConfidence ? { confidence: signals.dependentConfidence } : {}
     };
   }
   isInterfaceOrType(kind) {
@@ -1185,14 +1366,7 @@ var ContextAssembler = class {
     return (node.endLine - node.startLine + 1) * 10;
   }
 };
-var VALID_SYMBOL_KINDS = /* @__PURE__ */ new Set([
-  "function",
-  "class",
-  "interface",
-  "method",
-  "variable",
-  "type"
-]);
+var VALID_SYMBOL_KINDS = new Set(SYMBOL_KINDS);
 function synthesizeNodeFromId(symbolId) {
   const parts = symbolId.split("::");
   if (parts.length !== 3) return void 0;
@@ -1209,7 +1383,7 @@ var InputSchema7 = z7.object({
   taskType: TaskTypeSchema,
   tokenBudget: z7.number().min(100).optional().default(4e3)
 });
-function handleGetContextForTask(storage, masking, staleness, ctxoRoot = ".ctxo") {
+function handleGetContextForTask(storage, masking, staleness, ctxoRoot = ".ctxo", coChange) {
   const assembler = new ContextAssembler();
   const indexReader = new JsonIndexReader(ctxoRoot);
   const getGraph = () => getGraphAndFiles(ctxoRoot, storage);
@@ -1224,7 +1398,7 @@ function handleGetContextForTask(storage, masking, staleness, ctxoRoot = ".ctxo"
       const { symbolId, taskType, tokenBudget } = parsed.data;
       const { graph, indexedFiles } = getGraph();
       const indices = indexReader.readAll();
-      const result = assembler.assembleForTask(graph, symbolId, taskType, indices, tokenBudget);
+      const result = assembler.assembleForTask(graph, symbolId, taskType, indices, tokenBudget, coChange?.readCoChangeMap());
       if (!result) {
         return {
           content: [{ type: "text", text: JSON.stringify({ found: false, hint: 'Symbol not found. Run "ctxo index".' }) }]
@@ -1249,179 +1423,6 @@ function handleGetContextForTask(storage, masking, staleness, ctxoRoot = ".ctxo"
 // src/adapters/mcp/get-ranked-context.ts
 import { z as z8 } from "zod";
 
-// src/core/search/symbol-tokenizer.ts
-var STOP_WORDS = /* @__PURE__ */ new Set([
-  "get",
-  "set",
-  "is",
-  "has",
-  "can",
-  "do",
-  "the",
-  "a",
-  "an",
-  "of",
-  "to",
-  "in",
-  "for",
-  "on",
-  "with",
-  "at",
-  "by",
-  "from",
-  "as",
-  "into",
-  "not",
-  "no",
-  "or"
-]);
-var DEFAULT_OPTIONS = {
-  includeStopWords: false,
-  includeOriginal: true,
-  includeFilePath: false
-};
-var SymbolTokenizer = class _SymbolTokenizer {
-  options;
-  constructor(options) {
-    this.options = { ...DEFAULT_OPTIONS, ...options };
-  }
-  /**
-   * Tokenize a symbol name into searchable tokens.
-   *
-   * Examples:
-   *   "getCoChangeMetrics"    → ["get", "co", "change", "metrics"]  (or without stop words: ["co", "change", "metrics"])
-   *   "SqliteStorageAdapter"  → ["sqlite", "storage", "adapter"]
-   *   "i_storage_port"        → ["i", "storage", "port"]
-   *   "BM25Scorer"            → ["bm", "25", "scorer"]
-   *   "DB_PASSWORD"           → ["db", "password"]
-   */
-  tokenize(symbolName, filePath) {
-    const splitTokens = _SymbolTokenizer.splitName(symbolName);
-    const lowered = splitTokens.map((t) => t.toLowerCase());
-    const tokens = this.options.includeStopWords ? lowered : lowered.filter((t) => !STOP_WORDS.has(t));
-    if (this.options.includeOriginal) {
-      const original = symbolName.toLowerCase();
-      if (!tokens.includes(original)) {
-        tokens.unshift(original);
-      }
-    }
-    if (this.options.includeFilePath && filePath) {
-      const pathTokens = _SymbolTokenizer.tokenizeFilePath(filePath);
-      for (const pt of pathTokens) {
-        if (!tokens.includes(pt)) {
-          tokens.push(pt);
-        }
-      }
-    }
-    return tokens;
-  }
-  /**
-   * Tokenize a search query. Queries use stop words and don't include originals.
-   */
-  tokenizeQuery(query) {
-    const words = query.trim().split(/\s+/);
-    const tokens = [];
-    for (const word of words) {
-      const split = _SymbolTokenizer.splitName(word);
-      for (const t of split) {
-        const lowered = t.toLowerCase();
-        if (lowered.length > 0 && !tokens.includes(lowered)) {
-          tokens.push(lowered);
-        }
-      }
-    }
-    return tokens;
-  }
-  /**
-   * Split a name into constituent words based on naming convention boundaries.
-   *
-   * Rules:
-   *  1. Split on underscores and hyphens (snake_case, kebab-case)
-   *  2. Split on camelCase/PascalCase boundaries (uppercase after lowercase)
-   *  3. Split acronym boundaries (e.g., "HTMLParser" → ["HTML", "Parser"])
-   *  4. Split on digit ↔ letter boundaries
-   */
-  static splitName(name) {
-    if (!name || name.length === 0) return [];
-    const segments = name.split(/[_\-./\\]+/).filter((s) => s.length > 0);
-    const tokens = [];
-    for (const segment of segments) {
-      tokens.push(..._SymbolTokenizer.splitCamelCase(segment));
-    }
-    return tokens.filter((t) => t.length > 0);
-  }
-  /**
-   * Split a single segment on camelCase/PascalCase/digit boundaries.
-   */
-  static splitCamelCase(segment) {
-    const tokens = [];
-    let current = "";
-    for (let i = 0; i < segment.length; i++) {
-      const ch = segment[i];
-      const prev = i > 0 ? segment[i - 1] : "";
-      if (current.length > 0) {
-        const prevIsDigit = isDigit(prev);
-        const currIsDigit = isDigit(ch);
-        if (prevIsDigit !== currIsDigit) {
-          tokens.push(current);
-          current = ch;
-          continue;
-        }
-      }
-      if (current.length > 0 && isLower(prev) && isUpper(ch)) {
-        tokens.push(current);
-        current = ch;
-        continue;
-      }
-      if (current.length > 1 && isUpper(ch) === false && isUpper(prev) && !isDigit(ch)) {
-        const lastChar = current[current.length - 1];
-        if (isUpper(lastChar)) {
-          tokens.push(current.slice(0, -1));
-          current = lastChar + ch;
-          continue;
-        }
-      }
-      current += ch;
-    }
-    if (current.length > 0) {
-      tokens.push(current);
-    }
-    return tokens;
-  }
-  /**
-   * Extract searchable tokens from a file path.
-   * "src/core/search/symbol-tokenizer.ts" → ["src", "core", "search", "symbol", "tokenizer", "ts"]
-   */
-  static tokenizeFilePath(filePath) {
-    const withoutExt = filePath.replace(/\.[^.]+$/, "");
-    const segments = withoutExt.split(/[/\\]+/);
-    const tokens = [];
-    for (const seg of segments) {
-      const parts = seg.split(/[_\-.]+/).filter((s) => s.length > 0);
-      for (const p of parts) {
-        const lowered = p.toLowerCase();
-        if (lowered.length > 0 && !tokens.includes(lowered)) {
-          tokens.push(lowered);
-        }
-      }
-    }
-    return tokens;
-  }
-  /** Check if a token is a stop word */
-  static isStopWord(token) {
-    return STOP_WORDS.has(token.toLowerCase());
-  }
-};
-function isUpper(ch) {
-  return ch >= "A" && ch <= "Z";
-}
-function isLower(ch) {
-  return ch >= "a" && ch <= "z";
-}
-function isDigit(ch) {
-  return ch >= "0" && ch <= "9";
-}
-
 // src/core/search/fuzzy-corrector.ts
 var FuzzyCorrector = class {
   /** term → frequency (for tie-breaking) */
@@ -1805,7 +1806,6 @@ var InputSchema8 = z8.object({
   query: z8.string().min(1),
   tokenBudget: z8.number().min(100).optional().default(4e3),
   strategy: z8.enum(["combined", "dependency", "importance"]).optional().default("combined"),
-  fuzzy: z8.boolean().optional().default(true),
   searchMode: z8.enum(["fts", "legacy"]).optional().default("fts")
 });
 function handleGetRankedContext(storage, masking, staleness, ctxoRoot = ".ctxo", searchEngine) {
@@ -1898,7 +1898,7 @@ function handleGetRankedContext(storage, masking, staleness, ctxoRoot = ".ctxo",
 import { z as z9 } from "zod";
 var InputSchema9 = z9.object({
   pattern: z9.string().min(1),
-  kind: z9.enum(["function", "class", "interface", "method", "variable", "type"]).optional(),
+  kind: SymbolKindSchema.optional(),
   filePattern: z9.string().optional(),
   limit: z9.number().int().min(1).max(100).optional().default(25),
   mode: z9.enum(["regex", "fts"]).optional().default("regex")
@@ -2062,7 +2062,7 @@ function handleGetChangedSymbols(storage, git, masking, staleness, ctxoRoot = ".
 import { z as z11 } from "zod";
 var InputSchema11 = z11.object({
   symbolId: z11.string().min(1),
-  edgeKinds: z11.array(z11.enum(["imports", "calls", "extends", "implements", "uses"])).optional(),
+  edgeKinds: z11.array(EdgeKindSchema).optional(),
   transitive: z11.boolean().optional().default(false),
   maxDepth: z11.number().int().min(1).max(10).optional().default(5),
   intent: z11.string().optional().describe('Filter results by intent keywords (e.g., "test", "adapter", "core")')
@@ -2079,14 +2079,16 @@ function handleFindImporters(storage, masking, staleness, ctxoRoot = ".ctxo") {
       }
       const { symbolId, edgeKinds, transitive, maxDepth } = parsed.data;
       const { graph, indexedFiles } = getGraph();
-      if (!graph.hasNode(symbolId)) {
+      const root = graph.getNode(symbolId);
+      if (!root) {
         return {
           content: [{ type: "text", text: JSON.stringify({ found: false, hint: 'Symbol not found. Run "ctxo index" to build the codebase index.' }) }]
         };
       }
+      const rootId = root.symbolId;
       const importers = [];
       if (!transitive) {
-        const reverseEdges = graph.getReverseEdges(symbolId);
+        const reverseEdges = graph.getDependentEdges(rootId);
         const seen = /* @__PURE__ */ new Map();
         for (const edge of reverseEdges) {
           if (edgeKinds && !edgeKinds.includes(edge.kind)) continue;
@@ -2113,12 +2115,13 @@ function handleFindImporters(storage, masking, staleness, ctxoRoot = ".ctxo") {
           }
         }
       } else {
-        const visited = /* @__PURE__ */ new Set([symbolId]);
-        const queue = [{ id: symbolId, depth: 0 }];
+        const definitions = graph.dataResourceIdentity(rootId)?.definitions.map((definition) => definition.symbolId) ?? [];
+        const visited = /* @__PURE__ */ new Set([rootId, ...definitions]);
+        const queue = [{ id: rootId, depth: 0 }];
         while (queue.length > 0) {
           const current = queue.shift();
           if (current.depth >= maxDepth) continue;
-          const reverseEdges = graph.getReverseEdges(current.id);
+          const reverseEdges = graph.getDependentEdges(current.id);
           for (const edge of reverseEdges) {
             if (edgeKinds && !edgeKinds.includes(edge.kind)) continue;
             if (visited.has(edge.from)) continue;
@@ -2163,6 +2166,7 @@ function handleFindImporters(storage, masking, staleness, ctxoRoot = ".ctxo") {
 
 // src/adapters/mcp/get-class-hierarchy.ts
 import { z as z12 } from "zod";
+var HIERARCHY_EDGE_KINDS = /* @__PURE__ */ new Set(["extends", "implements"]);
 var InputSchema12 = z12.object({
   symbolId: z12.string().min(1).optional(),
   direction: z12.enum(["ancestors", "descendants", "both"]).optional().default("both")
@@ -2197,7 +2201,7 @@ function handleGetClassHierarchy(storage, masking, staleness, ctxoRoot = ".ctxo"
     }
     const ancestors = [];
     const descendants = [];
-    const isHierarchyEdge = (kind) => kind === "extends" || kind === "implements";
+    const isHierarchyEdge = (kind) => HIERARCHY_EDGE_KINDS.has(kind);
     if (direction === "ancestors" || direction === "both") {
       const visited = /* @__PURE__ */ new Set([symbolId]);
       const queue = [{ id: symbolId, depth: 0 }];
@@ -2261,7 +2265,7 @@ function handleGetClassHierarchy(storage, masking, staleness, ctxoRoot = ".ctxo"
     return { content };
   }
   function handleFull(graph, maskingPort, stalenessCheck, indexedFiles) {
-    const isHierarchyEdge = (kind) => kind === "extends" || kind === "implements";
+    const isHierarchyEdge = (kind) => HIERARCHY_EDGE_KINDS.has(kind);
     const hierarchyEdges = graph.allEdges().filter((e) => isHierarchyEdge(e.kind));
     const involved = /* @__PURE__ */ new Set();
     for (const edge of hierarchyEdges) {
@@ -2319,7 +2323,7 @@ function handleGetClassHierarchy(storage, masking, staleness, ctxoRoot = ".ctxo"
 import { z as z13 } from "zod";
 var InputSchema13 = z13.object({
   limit: z13.number().int().min(1).max(200).optional().default(25),
-  kind: z13.enum(["function", "class", "interface", "method", "variable", "type"]).optional(),
+  kind: SymbolKindSchema.optional(),
   filePattern: z13.string().optional(),
   damping: z13.number().min(0).max(1).optional().default(0.85)
 });
@@ -2370,23 +2374,11 @@ function handleGetSymbolImportance(storage, masking, staleness, ctxoRoot = ".ctx
 
 // src/adapters/mcp/get-pr-impact.ts
 import { z as z14 } from "zod";
-import { readFileSync, existsSync } from "fs";
-import { join } from "path";
 var InputSchema14 = z14.object({
   since: z14.string().optional().default("HEAD~1"),
   maxFiles: z14.number().int().min(1).optional().default(50),
   confidence: z14.enum(["confirmed", "likely", "potential"]).optional()
 });
-function loadCoChanges(ctxoRoot) {
-  const path = join(ctxoRoot, "index", "co-changes.json");
-  if (!existsSync(path)) return void 0;
-  try {
-    const matrix = JSON.parse(readFileSync(path, "utf-8"));
-    return loadCoChangeMap(matrix);
-  } catch {
-    return void 0;
-  }
-}
 function computeClustersAffected(snapshot, changedSymbolIds) {
   const totals = /* @__PURE__ */ new Map();
   for (const entry of snapshot.communities) {
@@ -2400,7 +2392,7 @@ function computeClustersAffected(snapshot, changedSymbolIds) {
   }
   return [...totals.entries()].map(([id, { label, count }]) => ({ id, label, symbolCount: count })).sort((a, b) => b.symbolCount - a.symbolCount || a.id - b.id);
 }
-function handleGetPrImpact(storage, git, masking, staleness, ctxoRoot = ".ctxo", clusterLabelMasker) {
+function handleGetPrImpact(storage, git, masking, staleness, ctxoRoot = ".ctxo", clusterLabelMasker, coChange) {
   const calculator = new BlastRadiusCalculator();
   const getGraph = () => getGraphAndFiles(ctxoRoot, storage);
   return async (args) => {
@@ -2419,7 +2411,7 @@ function handleGetPrImpact(storage, git, masking, staleness, ctxoRoot = ".ctxo",
         };
       }
       const { graph, indexedFiles } = getGraph();
-      const coChangeMap = loadCoChanges(ctxoRoot);
+      const coChangeMap = coChange?.readCoChangeMap();
       const allNodes = graph.allNodes();
       const nodesByFile = /* @__PURE__ */ new Map();
       for (const node of allNodes) {
@@ -2478,7 +2470,7 @@ function handleGetPrImpact(storage, git, masking, staleness, ctxoRoot = ".ctxo",
         if (coChangeMap) {
           const entries = coChangeMap.get(filePath);
           if (entries && entries.length > 0) {
-            coChangedWith = entries.sort((a, b) => b.frequency - a.frequency).slice(0, 5).map((e) => e.file1 === filePath ? e.file2 : e.file1);
+            coChangedWith = [...entries].sort((a, b) => b.frequency - a.frequency).slice(0, 5).map((e) => e.file1 === filePath ? e.file2 : e.file1);
           }
         }
         files.push({
@@ -2512,6 +2504,7 @@ function handleGetPrImpact(storage, git, masking, staleness, ctxoRoot = ".ctxo",
           violations: relevant,
           confidence: violationResult.confidence,
           snapshotsAvailable: violationResult.snapshotsAvailable,
+          distinctCommits: violationResult.distinctCommits,
           ...violationResult.hint ? { hint: violationResult.hint } : {}
         };
         clustersAffected = computeClustersAffected(snapshot, changedSymbolIds);
@@ -2633,10 +2626,10 @@ var ClusterLabelMasker = class {
 // src/index.ts
 var log4 = createLogger("ctxo:mcp");
 function loadMaskingConfig(ctxoRoot) {
-  const jsonConfigPath = join2(ctxoRoot, "masking.json");
-  if (existsSync2(jsonConfigPath)) {
+  const jsonConfigPath = join(ctxoRoot, "masking.json");
+  if (existsSync(jsonConfigPath)) {
     try {
-      const raw = readFileSync2(jsonConfigPath, "utf-8");
+      const raw = readFileSync(jsonConfigPath, "utf-8");
       const patterns = JSON.parse(raw);
       log4.info(`Loaded ${patterns.length} custom masking pattern(s)`);
       return MaskingPipeline.fromConfig(patterns);
@@ -2653,7 +2646,7 @@ var PKG_VERSION = (() => {
   try {
     const __filename = fileURLToPath(import.meta.url);
     const __dirname = dirname(__filename);
-    const pkg = JSON.parse(readFileSync2(join2(__dirname, "..", "package.json"), "utf-8"));
+    const pkg = JSON.parse(readFileSync(join(__dirname, "..", "package.json"), "utf-8"));
     return pkg.version ?? "0.0.0";
   } catch {
     return "0.0.0";
@@ -2661,9 +2654,9 @@ var PKG_VERSION = (() => {
 })();
 async function main() {
   const args = process.argv.slice(2);
-  const httpPortStr = process.env.CTXO_HTTP_PORT || (args.includes("--http") ? args[args.indexOf("--port") + 1] || "3001" : null);
+  const httpPortStr = resolveHttpPort(args, process.env);
   if (!httpPortStr && args.length > 0) {
-    const { CliRouter } = await import("./cli-router-LO2SWFC4.js");
+    const { CliRouter } = await import("./cli-router-RR4CM62C.js");
     const router = new CliRouter(process.cwd());
     await router.route(args);
     return;
@@ -2678,15 +2671,16 @@ async function main() {
     maskingClusterLabelPatterns(loadConfig(ctxoRoot).config)
   );
   const git = new SimpleGitAdapter(process.cwd());
+  const coChange = new CoChangeReader(ctxoRoot);
   const recorder = readStatsEnabled(ctxoRoot) ? new SessionRecorderAdapter(storage.getDb(), () => storage.persist()) : null;
   const server = new McpServer({ name: "ctxo", version: PKG_VERSION });
   const { StalenessDetector } = await import("./staleness-detector-4HJYBQ7Z.js");
   const staleness = new StalenessDetector(process.cwd(), ctxoRoot);
-  registerTools(server, storage, masking, git, staleness, recorder, ctxoRoot, clusterLabelMasker);
+  registerTools(server, storage, masking, git, staleness, recorder, ctxoRoot, clusterLabelMasker, coChange);
   if (httpPortStr) {
     await startHttpTransport(async () => {
       const s = new McpServer({ name: "ctxo", version: PKG_VERSION });
-      registerTools(s, storage, masking, git, staleness, recorder, ctxoRoot, clusterLabelMasker);
+      registerTools(s, storage, masking, git, staleness, recorder, ctxoRoot, clusterLabelMasker, coChange);
       return s;
     }, parseInt(httpPortStr, 10));
   } else {
@@ -2694,24 +2688,25 @@ async function main() {
     await server.connect(transport);
   }
 }
-function registerTools(server, storage, masking, git, staleness, recorder, ctxoRoot = ".ctxo", clusterLabelMasker) {
+function registerTools(server, storage, masking, git, staleness, recorder, ctxoRoot = ".ctxo", clusterLabelMasker, coChange) {
   const toolAnnotations = {
     readOnlyHint: true,
     destructiveHint: false,
     idempotentHint: true,
     openWorldHint: false
   };
+  const SYMBOL_ID_FORMAT = "format: file::name::kind; a SQL table, view or procedure also as name::kind, for example dbo.loans::table";
   const logicSliceHandler = withRecording("get_logic_slice", handleGetLogicSlice(storage, masking, staleness, ctxoRoot), recorder);
   const whyContextHandler = withRecording("get_why_context", handleGetWhyContext(storage, git, masking, staleness, ctxoRoot, clusterLabelMasker), recorder);
   const changeIntelligenceHandler = withRecording("get_change_intelligence", handleGetChangeIntelligence(storage, git, masking, staleness, ctxoRoot), recorder);
   server.registerTool(
     "get_logic_slice",
     {
-      description: 'Retrieve a symbol and all its transitive dependencies as a Logic-Slice. Use this when you need to UNDERSTAND what a symbol depends on (downstream view). L1=signature only, L2=direct deps, L3=full closure, L4=with token budget. Use `intent` to filter dependencies by keyword (e.g., "core", "adapter"). All responses include `_meta` with item counts and truncation info. For impact analysis (what BREAKS if this changes), use get_blast_radius instead. For task-specific context, use get_context_for_task.',
+      description: 'Retrieve a symbol and all its transitive dependencies as a Logic-Slice. Use this when you need to UNDERSTAND what a symbol depends on (downstream view). L1=signature only, L2=direct deps, L3=full closure, L4=with token budget and symbol annotations (attributes, columns; only L4 includes them). Use `intent` to filter dependencies by keyword (e.g., "core", "adapter"). All responses include `_meta` with item counts and truncation info. For impact analysis (what BREAKS if this changes), use get_blast_radius instead. For task-specific context, use get_context_for_task.',
       inputSchema: {
-        symbolId: z15.string().optional().describe("Single symbol ID (format: file::name::kind)"),
+        symbolId: z15.string().optional().describe(`Single symbol ID (${SYMBOL_ID_FORMAT})`),
         symbolIds: z15.array(z15.string()).optional().describe("Batch: array of symbol IDs"),
-        level: z15.number().min(1).max(4).optional().default(3).describe("Detail level (L1=signature, L2=direct deps, L3=full closure, L4=with token budget)"),
+        level: z15.number().min(1).max(4).optional().default(3).describe("Detail level (L1=signature, L2=direct deps, L3=full closure, L4=with token budget and annotations)"),
         intent: z15.string().optional().describe('Filter dependencies by intent keywords (e.g., "core", "adapter")')
       },
       annotations: toolAnnotations
@@ -2723,7 +2718,7 @@ function registerTools(server, storage, masking, git, staleness, recorder, ctxoR
     {
       description: "Retrieve git commit history intent and anti-pattern warnings (reverts, rollbacks) for a symbol. Use this when you need to understand WHY code was written this way or whether it has a history of problems. Pair with get_change_intelligence for complexity/churn scores.",
       inputSchema: {
-        symbolId: z15.string().min(1).describe("The symbol ID (format: file::name::kind)"),
+        symbolId: z15.string().min(1).describe(`The symbol ID (${SYMBOL_ID_FORMAT})`),
         maxCommits: z15.number().int().min(1).optional().describe("Limit commit history to N most recent commits")
       },
       annotations: toolAnnotations
@@ -2741,13 +2736,13 @@ function registerTools(server, storage, masking, git, staleness, recorder, ctxoR
     },
     (args) => changeIntelligenceHandler(args)
   );
-  const blastRadiusHandler = withRecording("get_blast_radius", handleGetBlastRadius(storage, masking, staleness, ctxoRoot, git, clusterLabelMasker), recorder);
+  const blastRadiusHandler = withRecording("get_blast_radius", handleGetBlastRadius(storage, masking, staleness, ctxoRoot, git, clusterLabelMasker, coChange), recorder);
   server.registerTool(
     "get_blast_radius",
     {
-      description: "BEFORE modifying any function or class, call this to understand impact. Returns all symbols that would break if the target changes, split into confirmed (direct importers), likely (co-changed), and potential (transitive) tiers with risk scores. Use `confidence` to filter by tier, `intent` to filter by keyword. Large results are auto-truncated with `_meta.hint` for drill-in. For what a symbol DEPENDS ON (downstream), use get_logic_slice instead. For full PR-level analysis, use get_pr_impact.",
+      description: "BEFORE modifying any symbol (a function, class, method or type, or a SQL table, view or procedure), call this to understand impact. Returns every symbol that depends on the target, directly or transitively, with risk scores that fall with depth. Each dependent is in the tier of its strongest edge: confirmed (`calls`, `extends`, `implements` and the data edges `reads`, `writes`, `executes`), likely (co-changed or `uses`), and potential (`imports`). When co-change history exists, `coChangedFiles` lists up to 10 files that often change together with the target's file but have no dependency path to it (informational: not counted in the tiers or risk scores). Use `confidence` to filter by tier, `intent` to filter by keyword. Large results are auto-truncated with `_meta.hint` for drill-in. For what a symbol DEPENDS ON (downstream), use get_logic_slice instead. For full PR-level analysis, use get_pr_impact.",
       inputSchema: {
-        symbolId: z15.string().min(1).describe("The symbol ID (format: file::name::kind)"),
+        symbolId: z15.string().min(1).describe(`The symbol ID (${SYMBOL_ID_FORMAT}). Every definition of a SQL object, and its name::kind id, has the same dependents`),
         confidence: z15.enum(["confirmed", "likely", "potential"]).optional().describe("Filter by confidence tier"),
         intent: z15.string().optional().describe('Filter impacted symbols by intent keywords (e.g., "test", "adapter")')
       },
@@ -2755,13 +2750,15 @@ function registerTools(server, storage, masking, git, staleness, recorder, ctxoR
     },
     (args) => blastRadiusHandler(args)
   );
-  const overlayHandler = withRecording("get_architectural_overlay", handleGetArchitecturalOverlay(storage, masking, staleness, git, clusterLabelMasker), recorder);
+  const overlayHandler = withRecording("get_architectural_overlay", handleGetArchitecturalOverlay(storage, masking, staleness, git, clusterLabelMasker, new ContextsViewReader(ctxoRoot)), recorder);
   server.registerTool(
     "get_architectural_overlay",
     {
-      description: "Get the project architectural layer map \u2014 identifies which symbols belong to Domain, Infrastructure, and Adapter layers. Use this when onboarding to a new codebase or validating that a change respects layer boundaries. For symbol-level analysis, use get_logic_slice or get_blast_radius.",
+      description: 'Get the project architecture map. mode "both" (default) returns the regex layer map (Domain, Infrastructure, Adapter, Test, Composition, Configuration) plus data-driven Louvain communities; "regex" or "communities" returns one of them. mode "contexts" returns candidate bounded contexts computed by `ctxo index`: file-level clusters of dependencies and co-change with hub files damped. The summary lists every candidate with label, size, cohesion and top terms, plus hubs and name collisions (type names whose shapes differ between candidates). Use this when onboarding to a new codebase, validating layer boundaries, or preparing a context map. For symbol-level analysis, use get_logic_slice or get_blast_radius. Pass candidate: <id> for one candidate in full: its files, cross-candidate edges, co-change pairs, hubs and collisions. The summary also gives each candidate\'s sharedTableCount and the totals dataResourcesTotal, sharedResourcesTotal and externalResourcesTotal. With candidate: <id>, the detail adds sharedTables (SQL tables and views that files of this candidate and at least one other read or write, with access modes per candidate; up to the first 15 by name, each with up to 10 accesses) and the candidate\'s own dataResources (up to the first 15 by name, each with its access modes, writer count, the owning candidate when only one writes it, and an external flag for resources that no .sql file defines). Both lists hold fewer entries when the response limit requires; sharedTableCount and dataResourcesTotal keep the full counts, and ctxo contexts --json has the full lists.',
       inputSchema: {
-        layer: z15.string().optional().describe("Filter by specific layer name")
+        layer: z15.string().optional().describe("Filter by specific layer name"),
+        mode: z15.enum(OVERLAY_MODES).optional().describe('View to return: "both" (default) layers plus communities, "regex" layer map, "communities" Louvain clusters, "contexts" candidate contexts (file level)'),
+        candidate: z15.number().int().positive().optional().describe('With mode "contexts": the id of one candidate to return in full (files, terms, cross edges, co-change pairs, its hubs and collisions); omit for the summary of all candidates')
       },
       annotations: toolAnnotations
     },
@@ -2771,7 +2768,7 @@ function registerTools(server, storage, masking, git, staleness, recorder, ctxoR
   server.registerTool(
     "find_dead_code",
     {
-      description: 'Find unreachable symbols and files that are never imported or called anywhere. Use this during cleanup, refactoring, or before deleting code to confirm it is truly unused. Use `intent` to filter results by keyword (e.g., "adapter", "function"). Large results are auto-truncated with `_meta`. For reverse dependency lookup of a specific symbol, use find_importers instead.',
+      description: 'Find unreachable symbols and files that are never imported or called anywhere. Use this during cleanup, refactoring, or before deleting code to confirm it is truly unused. Symbols in .sql files are never reported. Use `intent` to filter results by keyword (e.g., "adapter", "function"). Large results are auto-truncated with `_meta`. For reverse dependency lookup of a specific symbol, use find_importers instead.',
       inputSchema: {
         includeTests: z15.boolean().optional().default(false).describe("Include test files in analysis (default: exclude)"),
         intent: z15.string().optional().describe('Filter dead code results by intent keywords (e.g., "adapter", "function")')
@@ -2780,13 +2777,13 @@ function registerTools(server, storage, masking, git, staleness, recorder, ctxoR
     },
     (args) => deadCodeHandler(args)
   );
-  const contextForTaskHandler = withRecording("get_context_for_task", handleGetContextForTask(storage, masking, staleness, ctxoRoot), recorder);
+  const contextForTaskHandler = withRecording("get_context_for_task", handleGetContextForTask(storage, masking, staleness, ctxoRoot, coChange), recorder);
   server.registerTool(
     "get_context_for_task",
     {
-      description: 'Get task-optimized context for a symbol based on what you are about to do. Specify taskType: "fix" (bug investigation \u2014 includes history + anti-patterns), "extend" (add feature \u2014 includes deps + blast radius), "refactor" (restructure \u2014 includes importers + complexity), or "understand" (learn \u2014 includes full slice + architecture). This is the BEST starting point when you know both the symbol and your intent.',
+      description: 'Get task-optimized context for a symbol based on what you are about to do. Specify taskType: "fix" (bug investigation - includes history + anti-patterns), "extend" (add feature - includes deps + blast radius), "refactor" (restructure - includes importers + complexity), or "understand" (learn - includes full slice + architecture). Context entries that depend on the symbol (its blast radius) carry an optional `confidence` tier: confirmed, likely or potential, where co-change history can raise potential to likely. This is the BEST starting point when you know both the symbol and your intent.',
       inputSchema: {
-        symbolId: z15.string().min(1).describe("The symbol ID (format: file::name::kind)"),
+        symbolId: z15.string().min(1).describe(`The symbol ID (${SYMBOL_ID_FORMAT})`),
         taskType: z15.enum(["fix", "extend", "refactor", "understand"]).describe("Task type determines which context is most relevant"),
         tokenBudget: z15.number().optional().default(4e3).describe("Max tokens for context (default 4000)")
       },
@@ -2802,7 +2799,8 @@ function registerTools(server, storage, masking, git, staleness, recorder, ctxoR
       inputSchema: {
         query: z15.string().min(1).describe("Search query (matches symbol names)"),
         tokenBudget: z15.number().optional().default(4e3).describe("Max tokens for results (default 4000)"),
-        strategy: z15.enum(["combined", "dependency", "importance"]).optional().default("combined").describe("Ranking strategy")
+        strategy: z15.enum(["combined", "dependency", "importance"]).optional().default("combined").describe("Ranking strategy"),
+        searchMode: z15.enum(["fts", "legacy"]).optional().default("fts").describe('"fts" (default): BM25 ranking with camelCase splitting, trigram fallback and typo correction; "legacy": substring matching; strategy "importance" always uses legacy matching')
       },
       annotations: toolAnnotations
     },
@@ -2815,9 +2813,10 @@ function registerTools(server, storage, masking, git, staleness, recorder, ctxoR
       description: "Search symbols by exact name or regex pattern across the codebase index. Use this when you know (part of) the symbol name and need to find its ID for use with other tools. For semantic/relevance-based search, use get_ranked_context instead.",
       inputSchema: {
         pattern: z15.string().min(1).describe("Search pattern (substring or regex)"),
-        kind: z15.enum(["function", "class", "interface", "method", "variable", "type"]).optional().describe("Filter by symbol kind"),
+        kind: SymbolKindSchema.optional().describe("Filter by symbol kind (table, view and procedure come from SQL plugins)"),
         filePattern: z15.string().optional().describe("Filter by file path substring"),
-        limit: z15.number().int().min(1).max(100).optional().default(25).describe("Max results (default 25)")
+        limit: z15.number().int().min(1).max(100).optional().default(25).describe("Max results (default 25)"),
+        mode: z15.enum(["regex", "fts"]).optional().default("regex").describe('"regex" (default): case-insensitive regex or substring match on names; "fts": BM25 relevance search')
       },
       annotations: toolAnnotations
     },
@@ -2842,8 +2841,8 @@ function registerTools(server, storage, masking, git, staleness, recorder, ctxoR
     {
       description: 'Find all symbols that import or depend on a given symbol (reverse dependency / "who uses this?"). Use this to check if a symbol is safe to modify or delete. Supports transitive traversal for deep impact chains. Use `intent` to filter by keyword (e.g., "test", "core"). For forward dependencies (what this symbol uses), use get_logic_slice. For aggregated impact with risk scores, use get_blast_radius.',
       inputSchema: {
-        symbolId: z15.string().min(1).describe("The symbol ID (format: file::name::kind)"),
-        edgeKinds: z15.array(z15.enum(["imports", "calls", "extends", "implements", "uses"])).optional().describe("Filter by edge kinds"),
+        symbolId: z15.string().min(1).describe(`The symbol ID (${SYMBOL_ID_FORMAT}). Every definition of a SQL object, and its name::kind id, has the same importers`),
+        edgeKinds: z15.array(EdgeKindSchema).optional().describe("Filter by edge kinds (reads, writes and executes are data access)"),
         transitive: z15.boolean().optional().default(false).describe("Follow transitive reverse edges (default false)"),
         maxDepth: z15.number().int().min(1).max(10).optional().default(5).describe("Max BFS depth for transitive mode (default 5)"),
         intent: z15.string().optional().describe('Filter importers by intent keywords (e.g., "test", "core", "adapter")')
@@ -2872,7 +2871,7 @@ function registerTools(server, storage, masking, git, staleness, recorder, ctxoR
       description: "Rank symbols by structural importance using PageRank centrality on the dependency graph. Use this to identify the most critical symbols in the codebase \u2014 high-PageRank symbols are heavily depended upon and risky to change. For finding unused/unimportant code, use find_dead_code instead.",
       inputSchema: {
         limit: z15.number().int().min(1).max(200).optional().default(25).describe("Max results (default 25)"),
-        kind: z15.enum(["function", "class", "interface", "method", "variable", "type"]).optional().describe("Filter by symbol kind"),
+        kind: SymbolKindSchema.optional().describe("Filter by symbol kind (table, view and procedure come from SQL plugins)"),
         filePattern: z15.string().optional().describe("Filter by file path substring"),
         damping: z15.number().min(0).max(1).optional().default(0.85).describe("PageRank damping factor (default 0.85)")
       },
@@ -2880,7 +2879,7 @@ function registerTools(server, storage, masking, git, staleness, recorder, ctxoR
     },
     (args) => symbolImportanceHandler(args)
   );
-  const prImpactHandler = withRecording("get_pr_impact", handleGetPrImpact(storage, git, masking, staleness, ctxoRoot, clusterLabelMasker), recorder);
+  const prImpactHandler = withRecording("get_pr_impact", handleGetPrImpact(storage, git, masking, staleness, ctxoRoot, clusterLabelMasker, coChange), recorder);
   server.registerTool(
     "get_pr_impact",
     {