@wrongstack/tools 1.0.10 → 1.0.12

package/dist/{chunk-ENE22I5W.js → chunk-K37AKCTN.js}

@@ -1,6 +1,7 @@
 import {
-  parseTreeSitterAst
-} from "./chunk-XRNN44QY.js";
+  parseTreeSitterAst,
+  treeSitterDeclarationName
+} from "./chunk-2IRHFHZY.js";
 import {
   spawnStream
 } from "./chunk-UVYRQKPZ.js";
@@ -15,7 +16,7 @@ import {
   outgoingCallsService,
   runStartupIndex,
   searchCodebaseIndex
-} from "./chunk-HYHE4VNA.js";
+} from "./chunk-UMOP3VGK.js";
 import {
   IndexTimeoutError,
   SCHEMA_VERSION,
@@ -26,7 +27,7 @@ import {
   posixIndexPath,
   resolveIndexDir,
   xxhash64String
-} from "./chunk-NEYUPZL6.js";
+} from "./chunk-6D3UIQMF.js";
 import {
   EXT_TO_LANG,
   detectLang,
@@ -49,6 +50,7 @@ async function loadTs() {
   }
   return tsModule;
 }
+var TREE_SITTER_RULE_LANGS = /* @__PURE__ */ new Set(["py", "go", "rs"]);
 var PolyglotInvariantEngine = class {
   /**
    * Evaluate whether a code mutation respects backward compatibility invariants.
@@ -165,6 +167,8 @@ var PolyglotInvariantEngine = class {
     return {
       valid: violations.length === 0,
       violations,
+      lang,
+      supported: origContract.supported && modContract.supported,
       stats: {
         originalSymbols: origContract.functions.size + origContract.interfaces.size,
         modifiedSymbols: modContract.functions.size + modContract.interfaces.size,
@@ -200,137 +204,206 @@ var PolyglotInvariantEngine = class {
     const exports = /* @__PURE__ */ new Set();
     const functions = /* @__PURE__ */ new Map();
     const interfaces = /* @__PURE__ */ new Map();
+    function hasModifier(node, kind) {
+      if (!ts.canHaveModifiers(node)) return false;
+      return ts.getModifiers(node)?.some((m) => m.kind === kind) ?? false;
+    }
     function isExportedNode(node) {
-      if (ts.canHaveModifiers(node)) {
-        const modifiers = ts.getModifiers(node);
-        if (modifiers?.some((m) => m.kind === ts.SyntaxKind.ExportKeyword)) {
-          return true;
-        }
+      return hasModifier(node, ts.SyntaxKind.ExportKeyword);
+    }
+    function recordExport(node, name) {
+      if (!isExportedNode(node)) return false;
+      if (hasModifier(node, ts.SyntaxKind.DefaultKeyword)) exports.add("default");
+      else if (name) exports.add(name);
+      return true;
+    }
+    function paramsOf(params) {
+      return params.map((p) => ({
+        name: p.name.getText(sourceFile),
+        isOptional: Boolean(p.questionToken),
+        hasDefault: Boolean(p.initializer),
+        isRest: Boolean(p.dotDotDotToken),
+        type: p.type ? p.type.getText(sourceFile) : void 0
+      }));
+    }
+    function bindingNames(name) {
+      if (ts.isIdentifier(name)) return [name.text];
+      const names = [];
+      for (const element of name.elements) {
+        if (!ts.isOmittedExpression(element)) names.push(...bindingNames(element.name));
       }
-      return false;
+      return names;
+    }
+    function isFunctionLike(node) {
+      return ts.isFunctionDeclaration(node) || ts.isFunctionExpression(node) || ts.isArrowFunction(node) || ts.isMethodDeclaration(node) || ts.isConstructorDeclaration(node) || ts.isGetAccessor(node) || ts.isSetAccessor(node);
     }
+    let functionDepth = 0;
     function visit(node) {
-      if (ts.isExportDeclaration(node) && node.exportClause && ts.isNamedExports(node.exportClause)) {
-        for (const element of node.exportClause.elements) {
-          exports.add(element.name.text);
+      if (ts.isExportDeclaration(node)) {
+        if (node.exportClause && ts.isNamedExports(node.exportClause)) {
+          for (const element of node.exportClause.elements) {
+            exports.add(element.name.text);
+          }
+        } else if (node.exportClause && ts.isNamespaceExport(node.exportClause)) {
+          exports.add(node.exportClause.name.text);
+        } else if (node.moduleSpecifier && ts.isStringLiteral(node.moduleSpecifier)) {
+          exports.add(`* from '${node.moduleSpecifier.text}'`);
         }
       }
-      if (ts.isFunctionDeclaration(node) && node.name) {
-        const name = node.name.text;
-        const isExp = isExportedNode(node);
-        if (isExp) exports.add(name);
-        const params = node.parameters.map((p) => {
-          const pName = p.name.getText(sourceFile);
-          const isOptional = Boolean(p.questionToken);
-          const hasDefault = Boolean(p.initializer);
-          const isRest = Boolean(p.dotDotDotToken);
-          const type = p.type ? p.type.getText(sourceFile) : void 0;
-          return { name: pName, isOptional, hasDefault, isRest, type };
-        });
-        const returnType = node.type ? node.type.getText(sourceFile) : void 0;
-        functions.set(name, { name, isExported: isExp, params, returnType });
-      }
-      if (ts.isClassDeclaration(node) && node.name) {
-        const className = node.name.text;
-        const isExp = isExportedNode(node);
-        if (isExp) exports.add(className);
-        for (const member of node.members) {
-          if (ts.isMethodDeclaration(member) && member.name && ts.isIdentifier(member.name)) {
-            const methodName = member.name.text;
-            const fullMethodName = `${className}.${methodName}`;
-            const params = member.parameters.map((p) => {
-              const pName = p.name.getText(sourceFile);
-              const isOptional = Boolean(p.questionToken);
-              const hasDefault = Boolean(p.initializer);
-              const isRest = Boolean(p.dotDotDotToken);
-              const type = p.type ? p.type.getText(sourceFile) : void 0;
-              return { name: pName, isOptional, hasDefault, isRest, type };
+      if (ts.isExportAssignment(node)) {
+        exports.add(node.isExportEquals ? "export =" : "default");
+      }
+      if (functionDepth === 0) {
+        if (ts.isFunctionDeclaration(node)) {
+          const name = node.name?.text;
+          const isExp = recordExport(node, name);
+          const key = name ?? (isExp ? "default" : void 0);
+          if (key) {
+            functions.set(key, {
+              name: key,
+              isExported: isExp,
+              params: paramsOf(node.parameters),
+              returnType: node.type ? node.type.getText(sourceFile) : void 0
             });
-            const returnType = member.type ? member.type.getText(sourceFile) : void 0;
+          }
+        }
+        if (ts.isVariableStatement(node)) {
+          const isExp = isExportedNode(node);
+          for (const decl of node.declarationList.declarations) {
+            const names = bindingNames(decl.name);
+            if (isExp) for (const n of names) exports.add(n);
+            const init = decl.initializer;
+            if (ts.isIdentifier(decl.name) && init && (ts.isArrowFunction(init) || ts.isFunctionExpression(init))) {
+              const name = decl.name.text;
+              functions.set(name, {
+                name,
+                isExported: isExp,
+                params: paramsOf(init.parameters),
+                returnType: init.type ? init.type.getText(sourceFile) : void 0
+              });
+            }
+          }
+        }
+        if (ts.isClassDeclaration(node)) {
+          const className = node.name?.text ?? "default";
+          const isExp = recordExport(node, node.name?.text);
+          for (const member of node.members) {
+            let memberName;
+            let params;
+            let returnType;
+            if (ts.isConstructorDeclaration(member)) {
+              memberName = "constructor";
+              params = member.parameters;
+            } else if (ts.isMethodDeclaration(member) && (ts.isIdentifier(member.name) || ts.isPrivateIdentifier(member.name))) {
+              memberName = member.name.text;
+              params = member.parameters;
+              returnType = member.type ? member.type.getText(sourceFile) : void 0;
+            }
+            if (memberName === void 0 || params === void 0) continue;
+            const fullMethodName = `${className}.${memberName}`;
+            const existing = functions.get(fullMethodName);
+            if (existing && !("body" in member && member.body)) continue;
             functions.set(fullMethodName, {
               name: fullMethodName,
               isExported: isExp,
-              params,
+              params: paramsOf(params),
               returnType
             });
           }
         }
-      }
-      if (ts.isInterfaceDeclaration(node) && node.name) {
-        const name = node.name.text;
-        const isExp = isExportedNode(node);
-        if (isExp) exports.add(name);
-        const properties = [];
-        const methods = [];
-        for (const member of node.members) {
-          if (ts.isPropertySignature(member) && member.name) {
-            const propName = member.name.getText(sourceFile);
-            const isOptional = Boolean(member.questionToken);
-            const type = member.type ? member.type.getText(sourceFile) : void 0;
-            properties.push({ name: propName, isOptional, type });
-          } else if (ts.isMethodSignature(member) && member.name) {
-            const methodName = member.name.getText(sourceFile);
-            const isOptional = Boolean(member.questionToken);
-            const params = member.parameters.map((p) => ({
-              name: p.name.getText(sourceFile),
-              isOptional: Boolean(p.questionToken),
-              hasDefault: Boolean(p.initializer),
-              isRest: Boolean(p.dotDotDotToken)
-            }));
-            const returnType = member.type ? member.type.getText(sourceFile) : void 0;
-            methods.push({ name: methodName, isOptional, params, returnType });
+        if (ts.isEnumDeclaration(node)) {
+          recordExport(node, node.name.text);
+        }
+        if (ts.isModuleDeclaration(node) && ts.isIdentifier(node.name)) {
+          recordExport(node, node.name.text);
+        }
+        if (ts.isInterfaceDeclaration(node)) {
+          const name = node.name.text;
+          const isExp = recordExport(node, name);
+          const properties = [];
+          const methods = [];
+          for (const member of node.members) {
+            if (ts.isPropertySignature(member) && member.name) {
+              const propName = member.name.getText(sourceFile);
+              const isOptional = Boolean(member.questionToken);
+              const type = member.type ? member.type.getText(sourceFile) : void 0;
+              properties.push({ name: propName, isOptional, type });
+            } else if (ts.isMethodSignature(member) && member.name) {
+              const methodName = member.name.getText(sourceFile);
+              const isOptional = Boolean(member.questionToken);
+              const params = member.parameters.map((p) => ({
+                name: p.name.getText(sourceFile),
+                isOptional: Boolean(p.questionToken),
+                hasDefault: Boolean(p.initializer),
+                isRest: Boolean(p.dotDotDotToken)
+              }));
+              const returnType = member.type ? member.type.getText(sourceFile) : void 0;
+              methods.push({ name: methodName, isOptional, params, returnType });
+            }
           }
+          interfaces.set(name, { name, isExported: isExp, properties, methods });
         }
-        interfaces.set(name, { name, isExported: isExp, properties, methods });
-      }
-      if (ts.isTypeAliasDeclaration(node) && node.name && ts.isTypeLiteralNode(node.type)) {
-        const name = node.name.text;
-        const isExp = isExportedNode(node);
-        if (isExp) exports.add(name);
-        const properties = [];
-        for (const member of node.type.members) {
-          if (ts.isPropertySignature(member) && member.name) {
-            const propName = member.name.getText(sourceFile);
-            const isOptional = Boolean(member.questionToken);
-            const type = member.type ? member.type.getText(sourceFile) : void 0;
-            properties.push({ name: propName, isOptional, type });
+        if (ts.isTypeAliasDeclaration(node)) {
+          const name = node.name.text;
+          const isExp = recordExport(node, name);
+          if (ts.isTypeLiteralNode(node.type)) {
+            const properties = [];
+            for (const member of node.type.members) {
+              if (ts.isPropertySignature(member) && member.name) {
+                const propName = member.name.getText(sourceFile);
+                const isOptional = Boolean(member.questionToken);
+                const type = member.type ? member.type.getText(sourceFile) : void 0;
+                properties.push({ name: propName, isOptional, type });
+              }
+            }
+            interfaces.set(name, { name, isExported: isExp, properties, methods: [] });
           }
         }
-        interfaces.set(name, { name, isExported: isExp, properties, methods: [] });
       }
+      const fn = isFunctionLike(node);
+      if (fn) functionDepth++;
       ts.forEachChild(node, visit);
+      if (fn) functionDepth--;
     }
     ts.forEachChild(sourceFile, visit);
-    return { lang, exports, functions, interfaces };
+    return { lang, exports, functions, interfaces, supported: true };
   }
   /**
-   * Polyglot extraction (Python, Go, Rust, Java, etc.) via Tree-sitter WASM.
+   * Polyglot extraction (Python, Go, Rust) via Tree-sitter WASM.
    */
   async extractTreeSitterContract(code, lang) {
     const exports = /* @__PURE__ */ new Set();
     const functions = /* @__PURE__ */ new Map();
     const interfaces = /* @__PURE__ */ new Map();
+    if (!TREE_SITTER_RULE_LANGS.has(lang)) {
+      return { lang, exports, functions, interfaces, supported: false };
+    }
     const parsed = await parseTreeSitterAst({ content: code, lang });
     if (!parsed) {
-      return { lang, exports, functions, interfaces };
+      return { lang, exports, functions, interfaces, supported: false };
     }
     const { tree, parser } = parsed;
     try {
       let walk2 = function(node) {
         const type = node.type;
+        let pushed;
         if (lang === "py") {
           if (type === "function_definition") {
             const nameNode = node.childForFieldName("name");
             if (nameNode) {
               const name = nameNode.text;
-              const isExported = !name.startsWith("_");
-              if (isExported) exports.add(name);
+              const qualified = qualify(name);
+              const isExported = !insideFunction() && !qualified.split(".").some((s) => s.startsWith("_") && !(s.startsWith("__") && s.endsWith("__")));
+              if (isExported) exports.add(qualified);
               const paramsNode = node.childForFieldName("parameters");
               const params = [];
               if (paramsNode) {
                 for (let i = 0; i < paramsNode.namedChildCount; i++) {
                   const param = paramsNode.namedChild(i);
                   if (!param) continue;
+                  if (param.type === "positional_separator" || param.type === "keyword_separator" || param.type === "comment") {
+                    continue;
+                  }
                   const pText = param.text;
                   const isRest = pText.startsWith("*");
                   const hasDefault = param.type === "default_parameter" || param.type === "typed_default_parameter" || pText.includes("=");
@@ -343,13 +416,18 @@ var PolyglotInvariantEngine = class {
                   });
                 }
               }
-              functions.set(name, { name, isExported, params });
+              functions.set(qualified, { name: qualified, isExported, params });
+              pushed = { name, isType: false };
             }
           } else if (type === "class_definition") {
             const nameNode = node.childForFieldName("name");
             if (nameNode) {
               const name = nameNode.text;
-              if (!name.startsWith("_")) exports.add(name);
+              const qualified = qualify(name);
+              if (!insideFunction() && !qualified.split(".").some((s) => s.startsWith("_"))) {
+                exports.add(qualified);
+              }
+              pushed = { name, isType: true };
             }
           }
         } else if (lang === "go") {
@@ -357,23 +435,34 @@ var PolyglotInvariantEngine = class {
             const nameNode = node.childForFieldName("name");
             if (nameNode) {
               const name = nameNode.text;
+              let key = name;
+              if (type === "method_declaration") {
+                const receiver = node.childForFieldName("receiver")?.text ?? "";
+                const receiverType = /([A-Za-z_]\w*)\s*(?:\[[^\]]*\])?\s*\)\s*$/.exec(
+                  receiver
+                )?.[1];
+                if (receiverType) key = `${receiverType}.${name}`;
+              }
               const isExported = /^[A-Z]/.test(name);
-              if (isExported) exports.add(name);
+              if (isExported) exports.add(key);
               const paramsNode = node.childForFieldName("parameters");
               const params = [];
               if (paramsNode) {
                 for (let i = 0; i < paramsNode.namedChildCount; i++) {
                   const param = paramsNode.namedChild(i);
-                  if (!param) continue;
-                  params.push({
-                    name: param.text,
-                    isOptional: false,
-                    hasDefault: false,
-                    isRest: param.type === "variadic_parameter_declaration"
-                  });
+                  if (!param || param.type === "comment") continue;
+                  const isRest = param.type === "variadic_parameter_declaration";
+                  const names = param.childrenForFieldName("name").filter((n) => n !== null);
+                  if (names.length === 0) {
+                    params.push({ name: param.text, isOptional: false, hasDefault: false, isRest });
+                  } else {
+                    for (const n of names) {
+                      params.push({ name: n.text, isOptional: false, hasDefault: false, isRest });
+                    }
+                  }
                 }
               }
-              functions.set(name, { name, isExported, params });
+              functions.set(key, { name: key, isExported, params });
             }
           } else if (type === "type_spec") {
             const nameNode = node.childForFieldName("name");
@@ -398,18 +487,24 @@ var PolyglotInvariantEngine = class {
             }
           }
         } else if (lang === "rs") {
-          if (type === "function_item") {
+          if (type === "impl_item") {
+            const implType = node.childForFieldName("type")?.text.replace(/<[\s\S]*$/, "");
+            if (implType) pushed = { name: implType.trim(), isType: true };
+          } else if (type === "function_item") {
             const nameNode = node.childForFieldName("name");
             if (nameNode) {
               const name = nameNode.text;
-              const isExported = node.children.some((c) => c.type === "visibility_modifier");
-              if (isExported) exports.add(name);
+              const qualified = qualify(name);
+              const isExported = !insideFunction() && node.children.some((c) => c.type === "visibility_modifier");
+              if (isExported) exports.add(qualified);
               const paramsNode = node.childForFieldName("parameters");
               const params = [];
               if (paramsNode) {
                 for (let i = 0; i < paramsNode.namedChildCount; i++) {
                   const param = paramsNode.namedChild(i);
-                  if (!param) continue;
+                  if (!param || param.type === "attribute_item" || param.type === "line_comment" || param.type === "block_comment") {
+                    continue;
+                  }
                   params.push({
                     name: param.text,
                     isOptional: false,
@@ -418,20 +513,21 @@ var PolyglotInvariantEngine = class {
                   });
                 }
               }
-              functions.set(name, { name, isExported, params });
+              functions.set(qualified, { name: qualified, isExported, params });
+              pushed = { name, isType: false };
             }
           } else if (type === "trait_item") {
             const nameNode = node.childForFieldName("name");
             if (nameNode) {
               const name = nameNode.text;
               const isExported = node.children.some((c) => c.type === "visibility_modifier");
-              if (isExported) exports.add(name);
+              if (isExported) exports.add(qualify(name));
               const methods = [];
               const bodyNode = node.childForFieldName("body");
               if (bodyNode) {
                 for (let i = 0; i < bodyNode.namedChildCount; i++) {
                   const child = bodyNode.namedChild(i);
-                  if (child && child.type === "function_item") {
+                  if (child && (child.type === "function_item" || child.type === "function_signature_item")) {
                     const mName = child.childForFieldName("name")?.text;
                     const hasDefaultBody = Boolean(child.childForFieldName("body"));
                     if (mName) {
@@ -444,19 +540,30 @@ var PolyglotInvariantEngine = class {
                   }
                 }
               }
-              interfaces.set(name, { name, isExported, properties: [], methods });
+              interfaces.set(qualify(name), {
+                name: qualify(name),
+                isExported,
+                properties: [],
+                methods
+              });
+              pushed = { name, isType: true };
             }
           }
         }
+        if (pushed) scope.push(pushed);
         for (let i = 0; i < node.namedChildCount; i++) {
           const child = node.namedChild(i);
           if (child) walk2(child);
         }
+        if (pushed) scope.pop();
       };
       var walk = walk2;
       const root = tree.rootNode;
+      const scope = [];
+      const qualify = (name) => scope.length > 0 ? `${scope.map((s) => s.name).join(".")}.${name}` : name;
+      const insideFunction = () => scope.some((s) => !s.isType);
       walk2(root);
-      return { lang, exports, functions, interfaces };
+      return { lang, exports, functions, interfaces, supported: true };
     } finally {
       tree.delete();
       parser.delete();
@@ -560,6 +667,11 @@ async function mutateTsSymbol(content, lang, symbolName, newBody, target = "body
     );
   }
   const match = candidates[0];
+  if (target === "body" && !match.body) {
+    throw new Error(
+      `'${match.qualified}' (L${match.line}) is a ${ts.SyntaxKind[match.node.kind]} with no replaceable body. Pass target: "full" with the complete new declaration, or name a function/method inside it.`
+    );
+  }
   let fullNode = match.node;
   if (ts.isVariableDeclaration(match.node)) {
     const list = match.node.parent;
@@ -578,6 +690,11 @@ async function mutateTsSymbol(content, lang, symbolName, newBody, target = "body
     const baseIndent = indentAt(content, fullNode.getStart(sourceFile));
     formattedReplacement = `{
 ${reindent(newBody, `${baseIndent}  `)}
+${baseIndent}}`;
+  } else if (target === "body" && match.body && !ts.isBlock(match.body) && !ts.isTypeNode(match.body) && /^return\b/.test(formattedReplacement)) {
+    const baseIndent = indentAt(content, fullNode.getStart(sourceFile));
+    formattedReplacement = `{
+${reindent(newBody, `${baseIndent}  `)}
 ${baseIndent}}`;
   }
   const updatedContent = content.slice(0, startPos) + formattedReplacement + content.slice(endPos);
@@ -590,49 +707,113 @@ ${baseIndent}}`;
     updatedContent
   };
 }
+var NON_DECLARATION_TYPES = /parameter|argument|declarator$|^field_declaration$|^field$/;
+var TREE_SITTER_BODY_TYPES = [
+  "compound_statement",
+  "statement_block",
+  "block",
+  "function_body",
+  "body_statement",
+  "code_block",
+  "do_block"
+];
+function bodyOf(node) {
+  return node.childForFieldName("body") ?? node.children.find((c) => c !== null && TREE_SITTER_BODY_TYPES.includes(c.type)) ?? null;
+}
+function indentUnit(bodyText, declIndent, lang) {
+  for (const line of bodyText.split("\n").slice(1)) {
+    if (!line.trim()) continue;
+    const lead = /^[ \t]*/.exec(line)?.[0] ?? "";
+    if (lead.startsWith(declIndent) && lead.length > declIndent.length) {
+      return lead.slice(declIndent.length);
+    }
+    break;
+  }
+  return lang === "go" ? "	" : "    ";
+}
 async function mutateTreeSitterSymbol(content, lang, symbolName, newBody, target = "body") {
   const parsed = await parseTreeSitterAst({ content, lang });
   if (!parsed) return null;
   const { tree, parser } = parsed;
   try {
     let walk2 = function(node) {
-      if (targetNode) return;
-      const nameNode = node.childForFieldName("name") ?? node.childForFieldName("declarator");
-      if (nameNode && nameNode.text === symbolName) {
-        targetNode = node;
-        bodyNode = node.childForFieldName("body") ?? node.children.find(
-          (c) => [
-            "compound_statement",
-            "statement_block",
-            "block",
-            "function_body",
-            "body_statement",
-            "code_block",
-            "do_block"
-          ].includes(c.type)
-        ) ?? null;
-        return;
+      let pushed;
+      if (node.type === "impl_item") {
+        pushed = node.childForFieldName("type")?.text.replace(/<[\s\S]*$/, "").trim() || void 0;
+      } else if (!NON_DECLARATION_TYPES.test(node.type)) {
+        const name = treeSitterDeclarationName(node);
+        if (name !== void 0) {
+          let prefix = scope;
+          if (node.type === "method_declaration" && lang === "go") {
+            const receiver = node.childForFieldName("receiver")?.text ?? "";
+            const receiverType = /([A-Za-z_]\w*)\s*(?:\[[^\]]*\])?\s*\)\s*$/.exec(receiver)?.[1];
+            if (receiverType) prefix = [...scope, receiverType];
+          }
+          matches.push({
+            node,
+            body: bodyOf(node),
+            qualified: [...prefix, name].join("."),
+            line: node.startPosition.row + 1
+          });
+          pushed = name;
+        }
       }
+      if (pushed !== void 0) scope.push(pushed);
       for (let i = 0; i < node.namedChildCount; i++) {
         const child = node.namedChild(i);
         if (child) walk2(child);
       }
+      if (pushed !== void 0) scope.pop();
     };
     var walk = walk2;
     const root = tree.rootNode;
-    let targetNode = null;
-    let bodyNode = null;
+    const matches = [];
+    const scope = [];
     walk2(root);
-    if (!targetNode) return null;
-    const replaceTarget = target === "full" || !bodyNode ? targetNode : bodyNode;
+    let candidates = matches.filter(
+      (m) => m.qualified === symbolName || m.qualified.endsWith(`.${symbolName}`)
+    );
+    if (candidates.length === 0) return null;
+    if (candidates.length > 1 && candidates.every((m) => m.qualified === candidates[0]?.qualified)) {
+      const withBody = candidates.filter((m) => m.body !== null);
+      if (withBody.length === 1) candidates = withBody;
+    }
+    if (candidates.length > 1) {
+      const listed = candidates.map((m) => `${m.qualified} (L${m.line})`).join(", ");
+      const example = candidates.find((m) => m.qualified.includes("."))?.qualified;
+      throw new Error(
+        `Symbol '${symbolName}' is ambiguous: ${candidates.length} declarations match \u2014 ${listed}. ` + (example ? `Pass a qualified name, e.g. symbol: "${example}".` : "Rename-free disambiguation is impossible here; use the edit tool.")
+      );
+    }
+    const match = candidates[0];
+    if (target === "body" && !match.body) {
+      throw new Error(
+        `'${match.qualified}' (L${match.line}) is a ${match.node.type} with no replaceable body. Pass target: "full" with the complete new declaration.`
+      );
+    }
+    const replaceTarget = target === "full" ? match.node : match.body;
     const startPos = replaceTarget.startIndex;
     const endPos = replaceTarget.endIndex;
     const startLine = replaceTarget.startPosition.row + 1;
     const endLine = replaceTarget.endPosition.row + 1;
     let formattedReplacement = newBody.trim();
-    if (target === "body" && lang === "py") {
-      const indent = "    ";
-      formattedReplacement = formattedReplacement.split("\n").map((l) => l.trim() ? `${indent}${l}` : "").join("\n");
+    if (target === "body") {
+      const declIndent = indentAt(content, match.node.startIndex);
+      const lineStart = content.lastIndexOf("\n", startPos - 1) + 1;
+      const lead = content.slice(lineStart, startPos);
+      if (replaceTarget.text.startsWith("{")) {
+        if (!formattedReplacement.startsWith("{")) {
+          const unit2 = indentUnit(replaceTarget.text, declIndent, lang);
+          formattedReplacement = `{
+${reindent(newBody, `${declIndent}${unit2}`)}
+${declIndent}}`;
+        }
+      } else if (/^[ \t]*$/.test(lead)) {
+        formattedReplacement = reindent(newBody, lead).slice(lead.length);
+      } else {
+        formattedReplacement = `
+${reindent(newBody, `${declIndent}    `)}`;
+      }
     }
     const updatedContent = content.slice(0, startPos) + formattedReplacement + content.slice(endPos);
     const newEndLine = startLine + formattedReplacement.split("\n").length - 1;
@@ -648,7 +829,7 @@ async function mutateTreeSitterSymbol(content, lang, symbolName, newBody, target
     parser.delete();
   }
 }
-var TEST_CALLEES = String.raw`(?:it|test|describe|suite|bench|context|specify)`;
+var TEST_CALLEES = "(?:it|test|describe|suite|bench|context|specify)";
 function notFoundMessage(symbol, relPath, content) {
   const base = `Symbol '${symbol}' could not be located in AST of '${relPath}'`;
   const escaped = symbol.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
@@ -704,6 +885,7 @@ Pass allowBreakingChanges: true if this breaking change is intended.`
 
 // src/codebase-index/codebase-ast-replace-tool.ts
 import * as path2 from "node:path";
+import { ToolValidationError } from "@wrongstack/core/types";
 var codebaseAstReplaceTool = {
   name: "codebase-ast-replace",
   category: "Edit",
@@ -750,6 +932,21 @@ var codebaseAstReplaceTool = {
   // to the executor (is_error:false) — the UI showed "ok", the audit log and
   // spans recorded success, and only a model reading the payload noticed.
   async execute(input, ctx) {
+    for (const field of ["file", "symbol", "newBody"]) {
+      const value = input?.[field];
+      if (typeof value !== "string" || field !== "newBody" && !value.trim()) {
+        throw new ToolValidationError({
+          message: `codebase-ast-replace: ${field} is required and must be a${field === "newBody" ? " string" : " non-empty string"}`,
+          field
+        });
+      }
+    }
+    if (input.target !== void 0 && input.target !== "body" && input.target !== "full") {
+      throw new ToolValidationError({
+        message: `codebase-ast-replace: target must be "body" or "full", got ${JSON.stringify(input.target)}`,
+        field: "target"
+      });
+    }
     const projectRoot = ctx.projectRoot ?? ctx.cwd ?? process.cwd();
     const file = await safeResolveProjectPath(input.file, ctx);
     const result = await replaceSymbolInFile({ ...input, file }, projectRoot);
@@ -766,8 +963,12 @@ var codebaseAstReplaceTool = {
 
 // src/codebase-index/codebase-impact-analysis-tool.ts
 import * as path3 from "node:path";
+import { ToolValidationError as ToolValidationError2 } from "@wrongstack/core/types";
 import { toErrorMessage } from "@wrongstack/core/utils";
-var TEST_FILE_REGEX = /(?:test|spec|mock|fixture|bench)[s]?[/\\._]/i;
+var TEST_FILE_REGEX = /(?:^|[/\\._-])(?:tests?|specs?|mocks?|fixtures?|bench(?:es|marks?)?)(?:[/\\._-]|$)/i;
+function isTestFilePath(relPath) {
+  return TEST_FILE_REGEX.test(relPath);
+}
 var codebaseImpactAnalysisTool = {
   name: "codebase-impact-analysis",
   category: "Project",
@@ -775,6 +976,9 @@ var codebaseImpactAnalysisTool = {
   permission: "auto",
   mutating: false,
   capabilities: ["fs.read"],
+  // The index host has its own 30s read watchdog; leave headroom so its
+  // structured timeout reaches the agent instead of a generic TOOL_TIMEOUT.
+  timeoutMs: 35e3,
   description: "Perform a blast radius and impact analysis before modifying or refactoring a function, class, or type. Identifies all production call sites, affected test suites, and breaking change risks across the entire codebase.",
   usageHint: 'CALL BEFORE MODIFYING FUNCTION SIGNATURES, PARAMETERS, OR RETURN TYPES:\n\n- Pass `symbol: "calculateDiscount"` to get the complete blast radius.\n- Groups affected code into production callers vs. test files.\n- Provides a step-by-step action plan of every file and line that must be updated alongside the change.\n- Pair with `codebase-targeted-test` to verify affected test suites afterwards.',
   inputSchema: {
@@ -801,12 +1005,21 @@ var codebaseImpactAnalysisTool = {
     const indexDir = codebaseIndexDirOverride(ctx);
     const limit = 200;
     const transitive = input.transitive ?? true;
-    let rawSites = [];
-    let symbolFound = true;
-    let indexUnavailable = false;
-    let indexError;
+    if (!input?.symbol || typeof input.symbol !== "string" || !input.symbol.trim()) {
+      throw new ToolValidationError2({
+        message: "codebase-impact-analysis: symbol is required and cannot be empty",
+        field: "symbol"
+      });
+    }
+    const state = getIndexState();
+    if (state.lastError) {
+      const circuit = state.circuit;
+      const retryHint = circuit.state === "open" ? `Indexing is paused (circuit open, retry in ${Math.ceil(circuit.cooldownRemainingMs / 1e3)}s).` : "Try /codebase-reindex.";
+      throw new Error(`Index build failed: ${state.lastError}. ${retryHint}`);
+    }
+    let serviced;
     try {
-      const serviced = await incomingCallsService({
+      serviced = await incomingCallsService({
         projectRoot,
         indexDir,
         symbol: input.symbol,
@@ -814,20 +1027,38 @@ var codebaseImpactAnalysisTool = {
         limit,
         transitive
       });
-      rawSites = serviced.calls;
-      symbolFound = serviced.symbolFound;
     } catch (err) {
-      symbolFound = false;
-      indexUnavailable = true;
-      indexError = toErrorMessage(err);
-    }
-    if (indexUnavailable) {
-      const detail = indexError ? ` (${indexError})` : "";
+      if (err.name === "IndexRefreshInProgressError") {
+        throw new Error(
+          `Index refresh in progress (${state.currentFile}/${state.totalFiles} files); '${input.symbol}' has no cached answer yet \u2014 retry after the completed generation is published.`,
+          { cause: err }
+        );
+      }
       throw new Error(
-        `Index query failed for '${input.symbol}'. Run codebase-index, then retry.${detail}`
+        `Index query failed for '${input.symbol}'. Run codebase-index, then retry. (${toErrorMessage(err)})`,
+        { cause: err }
       );
     }
+    const rawSites = serviced.calls;
+    const { symbolFound, totalMatches, stale } = serviced;
     if (!symbolFound) {
+      let hasPersistedIndex = state.ready;
+      if (!hasPersistedIndex) {
+        try {
+          const stats = await codebaseIndexStats({ projectRoot, indexDir });
+          hasPersistedIndex = stats.totalFiles > 0 || stats.lastIndexed !== null;
+        } catch (err) {
+          throw new Error(
+            `Symbol '${input.symbol}' was not found and the persisted index could not be verified: ${toErrorMessage(err)}. Try /codebase-reindex.`,
+            { cause: err }
+          );
+        }
+      }
+      if (!hasPersistedIndex) {
+        throw new Error(
+          "No persisted index data found. Run codebase-index to build it, then retry codebase-impact-analysis."
+        );
+      }
       const reason = `Symbol '${input.symbol}' was not found in the index` + (input.file ? ` for file filter '${input.file}'` : "") + ". Use codebase-search to verify the name.";
       return {
         status: "ok",
@@ -844,14 +1075,18 @@ var codebaseImpactAnalysisTool = {
     }
     const prodFilesSet = /* @__PURE__ */ new Set();
     const testFilesSet = /* @__PURE__ */ new Set();
+    const directProdFilesSet = /* @__PURE__ */ new Set();
+    const indirectProdFilesSet = /* @__PURE__ */ new Set();
     const callSites = [];
     for (const site of rawSites) {
       const relPath = path3.relative(projectRoot, site.symbol.file).replace(/\\/g, "/");
-      const isTest = TEST_FILE_REGEX.test(relPath);
+      const isTest = isTestFilePath(relPath);
+      const indirect = !site.callType;
       if (isTest) {
         testFilesSet.add(relPath);
       } else {
         prodFilesSet.add(relPath);
+        (indirect ? indirectProdFilesSet : directProdFilesSet).add(relPath);
       }
       callSites.push({
         file: relPath,
@@ -859,22 +1094,34 @@ var codebaseImpactAnalysisTool = {
         callerName: site.symbol.name,
         callerKind: site.symbol.kind,
         callType: site.callType,
-        isTest
+        isTest,
+        ...indirect ? { indirect: true } : {}
       });
     }
     const prodFiles = [...prodFilesSet];
     const testFiles = [...testFilesSet];
-    const totalCallSites = callSites.length;
+    const directProdFiles = [...directProdFilesSet];
+    const indirectOnlyProdFiles = [...indirectProdFilesSet].filter(
+      (file) => !directProdFilesSet.has(file)
+    );
+    const totalCallSites = callSites.filter((site) => !site.indirect).length;
+    const indirectCallers = callSites.length - totalCallSites;
     let riskLevel = "low";
-    if (prodFiles.length > 5 || totalCallSites > 10) {
+    if (directProdFiles.length > 5 || totalCallSites > 10) {
       riskLevel = "high";
-    } else if (prodFiles.length > 1 || totalCallSites > 3) {
+    } else if (directProdFiles.length > 1 || totalCallSites > 3) {
       riskLevel = "medium";
     }
+    if (riskLevel === "low" && prodFiles.length > 5) riskLevel = "medium";
     const recommendedActionPlan = [];
-    if (prodFiles.length > 0) {
+    if (directProdFiles.length > 0) {
       recommendedActionPlan.push(
-        `Update ${totalCallSites} call site(s) across ${prodFiles.length} production file(s): ${prodFiles.slice(0, 3).join(", ")}${prodFiles.length > 3 ? ` +${prodFiles.length - 3} more` : ""}`
+        `Update ${totalCallSites} call site(s) across ${directProdFiles.length} production file(s): ${directProdFiles.slice(0, 3).join(", ")}${directProdFiles.length > 3 ? ` +${directProdFiles.length - 3} more` : ""}`
+      );
+    }
+    if (indirectOnlyProdFiles.length > 0) {
+      recommendedActionPlan.push(
+        `Re-verify ${indirectOnlyProdFiles.length} production file(s) that reach it only indirectly: ${indirectOnlyProdFiles.slice(0, 3).join(", ")}${indirectOnlyProdFiles.length > 3 ? ` +${indirectOnlyProdFiles.length - 3} more` : ""}`
       );
     }
     if (testFiles.length > 0) {
@@ -886,7 +1133,16 @@ var codebaseImpactAnalysisTool = {
         `No existing test files directly cover '${input.symbol}'. Consider adding a test suite.`
       );
     }
-    const summary = `Blast Radius for '${input.symbol}': ${riskLevel.toUpperCase()} RISK (${totalCallSites} call sites in ${prodFiles.length} prod files, ${testFiles.length} test suites).`;
+    const capped = totalMatches > callSites.length;
+    if (capped) riskLevel = "high";
+    let summary = `Blast Radius for '${input.symbol}': ${riskLevel.toUpperCase()} RISK (${totalCallSites} call sites in ${directProdFiles.length} prod files, ${testFiles.length} test suites`;
+    summary += indirectCallers > 0 ? `; ${indirectCallers} indirect caller(s)).` : ").";
+    if (capped) {
+      summary += ` Only the first ${callSites.length} of ${totalMatches} callers were analyzed; pass \`file\` to narrow.`;
+    }
+    if (stale) {
+      summary += ` Index refresh in progress; served from the previous generation \u2014 call sites in files being indexed may lag.`;
+    }
     return {
       status: "ok",
       symbol: input.symbol,
@@ -897,13 +1153,14 @@ var codebaseImpactAnalysisTool = {
       affectedTestFiles: testFiles,
       callSites,
       recommendedActionPlan,
-      symbolFound: true
+      symbolFound: true,
+      ...stale ? { stale: true } : {}
     };
   }
 };
 
 // src/codebase-index/codebase-incoming-calls-tool.ts
-import { ToolValidationError } from "@wrongstack/core/types";
+import { ToolValidationError as ToolValidationError3 } from "@wrongstack/core/types";
 import { toErrorMessage as toErrorMessage2 } from "@wrongstack/core/utils";
 var codebaseIncomingCallsTool = {
   name: "codebase-incoming-calls",
@@ -942,7 +1199,7 @@ var codebaseIncomingCallsTool = {
   },
   async execute(input, ctx) {
     if (!input?.symbol || typeof input.symbol !== "string" || !input.symbol.trim()) {
-      throw new ToolValidationError({
+      throw new ToolValidationError3({
         message: "codebase-incoming-calls: symbol is required and cannot be empty",
         field: "symbol"
       });
@@ -984,7 +1241,7 @@ var codebaseIncomingCallsTool = {
       if (!hasPersistedIndex) {
         try {
           const stats = await codebaseIndexStats({
-            projectRoot: ctx.projectRoot,
+            projectRoot,
             indexDir: codebaseIndexDirOverride(ctx)
           });
           hasPersistedIndex = stats.totalFiles > 0 || stats.lastIndexed !== null;
@@ -1015,7 +1272,7 @@ var codebaseIncomingCallsTool = {
     }
     if (ambiguous) {
       notes.push(
-        `Symbol "${input.symbol}" exists in multiple files. Results include callers of all same-named symbols. Use codebase-search to find the exact file and pass it as \`file\`.`
+        `Symbol "${input.symbol}" exists in multiple files. Callers resolved to another file were excluded, but callers whose target could not be pinned to a file are still included. Verify with codebase-search before relying on the list.`
       );
     }
     if (stale) {
@@ -1034,10 +1291,10 @@ var codebaseIncomingCallsTool = {
 };
 
 // src/codebase-index/codebase-index-tool.ts
-import { ToolValidationError as ToolValidationError3 } from "@wrongstack/core/types";
+import { ToolValidationError as ToolValidationError5 } from "@wrongstack/core/types";
 
 // src/codebase-index/codebase-search-tool.ts
-import { ToolValidationError as ToolValidationError2 } from "@wrongstack/core/types";
+import { ToolValidationError as ToolValidationError4 } from "@wrongstack/core/types";
 import { toErrorMessage as toErrorMessage3 } from "@wrongstack/core/utils";
 var INDEXABLE_LANG_IDS = [
   ...new Set(Object.values(EXT_TO_LANG))
@@ -1115,13 +1372,13 @@ var codebaseSearchTool = {
   },
   async execute(input, ctx, execOpts) {
     if (!input?.query || typeof input.query !== "string" || !input.query.trim()) {
-      throw new ToolValidationError2({
+      throw new ToolValidationError4({
         message: "codebase-search: query is required and cannot be empty",
         field: "query"
       });
     }
     if (input.lspKind !== void 0 && (!Number.isInteger(input.lspKind) || input.lspKind < 1 || input.lspKind > 26)) {
-      throw new ToolValidationError2({
+      throw new ToolValidationError4({
         message: "codebase-search: lspKind must be an integer between 1 and 26",
         field: "lspKind"
       });
@@ -1225,7 +1482,7 @@ var codebaseIndexTool = {
     properties: {
       force: {
         type: "boolean",
-        description: "Force a full reindex \u2014 clears the index first and reindexes all files."
+        description: "Force a reindex that ignores mtime/content-hash caches. Without `langs` it clears the index and rebuilds every file; with `langs` it re-parses only those languages and keeps the rest."
       },
       langs: {
         type: "array",
@@ -1239,7 +1496,7 @@ var codebaseIndexTool = {
     signal?.throwIfAborted();
     if (input.langs) {
       if (!Array.isArray(input.langs) || input.langs.length === 0) {
-        throw new ToolValidationError3({
+        throw new ToolValidationError5({
           message: "codebase-index: langs cannot be an empty array. Pass at least one valid language or omit langs.",
           field: "langs"
         });
@@ -1248,7 +1505,7 @@ var codebaseIndexTool = {
         (lang) => !INDEXABLE_LANG_IDS.includes(lang)
       );
       if (unknown.length > 0) {
-        throw new ToolValidationError3({
+        throw new ToolValidationError5({
           message: `codebase-index: unknown lang(s) ${unknown.map((l) => `"${l}"`).join(", ")}. Valid ids: ${INDEXABLE_LANG_IDS.join(", ")}.`,
           field: "langs"
         });
@@ -1289,7 +1546,8 @@ var codebaseIndexTool = {
 
 // src/codebase-index/codebase-invariant-check-tool.ts
 import * as fs2 from "node:fs/promises";
-import { ToolValidationError as ToolValidationError4 } from "@wrongstack/core/types";
+import { ToolValidationError as ToolValidationError6 } from "@wrongstack/core/types";
+var KNOWN_LANGS = /* @__PURE__ */ new Set([...Object.values(EXT_TO_LANG), "other"]);
 var codebaseInvariantCheckTool = {
   name: "codebase-invariant-check",
   category: "Inspect",
@@ -1298,8 +1556,8 @@ var codebaseInvariantCheckTool = {
   subjectKey: "file",
   mutating: false,
   capabilities: ["fs.read"],
-  description: "Mathematically verify AST backward-compatibility invariants between original code and candidate mutations across TypeScript, Python, Go, Rust, Java, etc. Detects missing exports (INV-001), mandatory parameter additions (INV-002), interface breaking expansions (INV-003), and return type changes (INV-004) with zero hallucinations.",
-  usageHint: "PRE-FLIGHT AST INVARIANT AUDIT:\n\n- Provide `file` and `modifiedCode` (or both `originalCode` and `modifiedCode`).\n- Returns `valid: true` if changes are strictly backward compatible.\n- Returns structured `violations[]` with exact rule IDs, offending symbol names, and fix instructions.",
+  description: "Deterministically check AST backward-compatibility invariants between original code and a candidate mutation for TypeScript/JavaScript, Python, Go and Rust. Detects removed exports (INV-001), mandatory parameter additions (INV-002), interface breaking expansions (INV-003), and incompatible return type changes (INV-004). Other languages return `verified: false`.",
+  usageHint: "PRE-FLIGHT AST INVARIANT AUDIT:\n\n- Provide `file` and `modifiedCode` (or both `originalCode` and `modifiedCode`).\n- Returns `valid: true` when no rule was violated; check `verified` \u2014 it is false for languages without rules.\n- Returns structured `violations[]` with exact rule IDs, offending symbol names, and fix instructions.",
   inputSchema: {
     type: "object",
     properties: {
@@ -1327,9 +1585,21 @@ var codebaseInvariantCheckTool = {
   // (is_error:false) whose payload was indistinguishable from "this change
   // breaks compatibility", so an unreadable file read as a real violation.
   async execute(input, ctx) {
+    if (typeof input?.modifiedCode !== "string") {
+      throw new ToolValidationError6({
+        message: "codebase-invariant-check: modifiedCode must be a string.",
+        field: "modifiedCode"
+      });
+    }
+    if (input.lang !== void 0 && !KNOWN_LANGS.has(input.lang)) {
+      throw new ToolValidationError6({
+        message: `codebase-invariant-check: unknown lang "${String(input.lang)}". Valid ids: ${[...KNOWN_LANGS].sort().join(", ")}.`,
+        field: "lang"
+      });
+    }
     let originalCode = input.originalCode;
     let lang = input.lang;
-    if (!originalCode && input.file) {
+    if (originalCode === void 0 && input.file) {
       const resolved = await safeResolveProjectPath(input.file, ctx);
       originalCode = await fs2.readFile(resolved, "utf8");
       if (!lang) {
@@ -1337,7 +1607,7 @@ var codebaseInvariantCheckTool = {
       }
     }
     if (originalCode === void 0) {
-      throw new ToolValidationError4({
+      throw new ToolValidationError6({
         message: "Neither originalCode nor file was provided for invariant comparison.",
         field: "originalCode"
       });
@@ -1348,10 +1618,11 @@ var codebaseInvariantCheckTool = {
       lang,
       filePath: input.file
     });
-    const summary = res.valid ? "AST Invariants PASSED. Mutation is 100% backward compatible." : `AST Invariants FAILED with ${res.violations.length} violation(s):
+    const summary = !res.supported ? `AST Invariants NOT VERIFIED: no invariant rules exist for '${res.lang}' (supported: ts, tsx, js, jsx, py, go, rs). Review compatibility manually.` : res.valid ? "AST Invariants PASSED. No export removal, mandatory parameter/property addition, or incompatible return type change detected." : `AST Invariants FAILED with ${res.violations.length} violation(s):
 ` + res.violations.map((v) => ` - [${v.ruleId}] ${v.symbolName}: ${v.message}`).join("\n");
     return {
       valid: res.valid,
+      verified: res.supported,
       violations: res.violations,
       summary
     };
@@ -1359,7 +1630,7 @@ var codebaseInvariantCheckTool = {
 };
 
 // src/codebase-index/codebase-outgoing-calls-tool.ts
-import { ToolValidationError as ToolValidationError5 } from "@wrongstack/core/types";
+import { ToolValidationError as ToolValidationError7 } from "@wrongstack/core/types";
 import { toErrorMessage as toErrorMessage4 } from "@wrongstack/core/utils";
 var codebaseOutgoingCallsTool = {
   name: "codebase-outgoing-calls",
@@ -1398,7 +1669,7 @@ var codebaseOutgoingCallsTool = {
   },
   async execute(input, ctx) {
     if (!input?.symbol || typeof input.symbol !== "string" || !input.symbol.trim()) {
-      throw new ToolValidationError5({
+      throw new ToolValidationError7({
         message: "codebase-outgoing-calls: symbol is required and cannot be empty",
         field: "symbol"
       });
@@ -1440,7 +1711,7 @@ var codebaseOutgoingCallsTool = {
       if (!hasPersistedIndex) {
         try {
           const stats = await codebaseIndexStats({
-            projectRoot: ctx.projectRoot,
+            projectRoot,
             indexDir: codebaseIndexDirOverride(ctx)
           });
           hasPersistedIndex = stats.totalFiles > 0 || stats.lastIndexed !== null;
@@ -1489,6 +1760,10 @@ var codebaseOutgoingCallsTool = {
   }
 };
 
+// src/codebase-index/codebase-repo-map-tool.ts
+import * as path7 from "node:path";
+import { ToolValidationError as ToolValidationError8 } from "@wrongstack/core/types";
+
 // src/codebase-index/repo-map.ts
 import { existsSync } from "node:fs";
 import * as path6 from "node:path";
@@ -1513,7 +1788,7 @@ async function loadTs3() {
 }
 function applyReplacements(content, replacements) {
   if (replacements.length === 0) return content;
-  const sorted = [...replacements].sort((a, b) => a.start - b.start);
+  const sorted = [...replacements].sort((a, b) => a.start - b.start || b.end - a.end);
   let result = "";
   let lastIndex = 0;
   for (const r of sorted) {
@@ -1541,23 +1816,51 @@ async function extractTsSkeleton(content, lang, opts) {
   const symbolRanges = [];
   let symbolCount = 0;
   const includeLineNumbers = opts.includeLineNumbers ?? true;
+  const exportedByName = /* @__PURE__ */ new Set();
+  for (const statement of sourceFile.statements) {
+    if (ts.isExportDeclaration(statement) && !statement.moduleSpecifier && statement.exportClause && ts.isNamedExports(statement.exportClause)) {
+      for (const element of statement.exportClause.elements) {
+        exportedByName.add((element.propertyName ?? element.name).text);
+      }
+    } else if (ts.isExportAssignment(statement) && !statement.isExportEquals && ts.isIdentifier(statement.expression)) {
+      exportedByName.add(statement.expression.text);
+    } else if (ts.isExportAssignment(statement) && statement.isExportEquals && ts.isIdentifier(statement.expression)) {
+      exportedByName.add(statement.expression.text);
+    }
+  }
   function isExported(node) {
-    if (!ts.canHaveModifiers(node)) return false;
-    const modifiers = ts.getModifiers(node);
-    return modifiers?.some((m) => m.kind === ts.SyntaxKind.ExportKeyword) ?? false;
+    if (ts.canHaveModifiers(node)) {
+      const modifiers = ts.getModifiers(node);
+      if (modifiers?.some((m) => m.kind === ts.SyntaxKind.ExportKeyword)) return true;
+    }
+    if (ts.isVariableStatement(node)) {
+      return node.declarationList.declarations.some(
+        (d) => ts.isIdentifier(d.name) && exportedByName.has(d.name.text)
+      );
+    }
+    const name = node.name;
+    return name !== void 0 && ts.isIdentifier(name) && exportedByName.has(name.text);
+  }
+  function removeDeclaration(node) {
+    replacements.push({ start: node.getStart(sourceFile, true), end: node.getEnd(), text: "" });
   }
   function visit(node, depth) {
     if (opts.maxDepth !== void 0 && depth > opts.maxDepth) {
       return;
     }
+    if (opts.includeDocs === false) {
+      for (const doc of node.jsDoc ?? []) {
+        replacements.push({ start: doc.getStart(sourceFile), end: doc.getEnd(), text: "" });
+      }
+    }
+    if (opts.exportsOnly && depth === 0 && (ts.isVariableStatement(node) || ts.isModuleDeclaration(node)) && !isExported(node)) {
+      removeDeclaration(node);
+      return;
+    }
     if (ts.isFunctionDeclaration(node) || ts.isMethodDeclaration(node) || ts.isConstructorDeclaration(node) || ts.isGetAccessor(node) || ts.isSetAccessor(node)) {
       symbolCount++;
       if (opts.exportsOnly && depth === 0 && !isExported(node)) {
-        replacements.push({
-          start: node.getStart(sourceFile),
-          end: node.getEnd(),
-          text: ""
-        });
+        removeDeclaration(node);
         return;
       }
       const nodeStart = sourceFile.getLineAndCharacterOfPosition(node.getStart(sourceFile)).line + 1;
@@ -1619,11 +1922,7 @@ async function extractTsSkeleton(content, lang, opts) {
     } else if (ts.isClassDeclaration(node) || ts.isInterfaceDeclaration(node) || ts.isTypeAliasDeclaration(node) || ts.isEnumDeclaration(node)) {
       symbolCount++;
       if (opts.exportsOnly && depth === 0 && !isExported(node)) {
-        replacements.push({
-          start: node.getStart(sourceFile),
-          end: node.getEnd(),
-          text: ""
-        });
+        removeDeclaration(node);
         return;
       }
       let name;
@@ -1675,6 +1974,37 @@ function collapseTsImports(code) {
   }
   return resultLines.join("\n");
 }
+function isPrivateTopLevel(node, lang) {
+  if (lang === "py") {
+    const decl = node.type === "decorated_definition" ? node.childForFieldName("definition") : node;
+    if (decl?.type !== "function_definition" && decl?.type !== "class_definition") return false;
+    return decl.childForFieldName("name")?.text.startsWith("_") ?? false;
+  }
+  if (lang === "go") {
+    let name;
+    if (node.type === "function_declaration" || node.type === "method_declaration") {
+      name = node.childForFieldName("name")?.text;
+    } else if (node.type === "type_declaration" && node.namedChildCount === 1) {
+      name = node.namedChild(0)?.childForFieldName("name")?.text;
+    }
+    return name !== void 0 && !/^[A-Z]/.test(name);
+  }
+  if (lang === "rs") {
+    const items = [
+      "function_item",
+      "struct_item",
+      "enum_item",
+      "trait_item",
+      "type_item",
+      "const_item",
+      "static_item",
+      "mod_item"
+    ];
+    if (!items.includes(node.type)) return false;
+    return !node.children.some((c) => c?.type === "visibility_modifier");
+  }
+  return false;
+}
 async function extractTreeSitterSkeleton(content, lang, opts) {
   const parsed = await parseTreeSitterAst({ content, lang });
   if (!parsed) return null;
@@ -1684,9 +2014,17 @@ async function extractTreeSitterSkeleton(content, lang, opts) {
   let symbolCount = 0;
   const includeLineNumbers = opts.includeLineNumbers ?? true;
   try {
-    let walk2 = function(node) {
+    let walk2 = function(node, depth) {
       const type = node.type;
-      if (type === "function_definition" || type === "function_declaration" || type === "method_declaration" || type === "function_item" || type === "method" || type === "singleton_method" || type === "func_literal") {
+      if (opts.includeDocs === false && /comment$/.test(type)) {
+        replacements.push({ start: node.startIndex, end: node.endIndex, text: "" });
+        return;
+      }
+      if (opts.exportsOnly && depth === 1 && isPrivateTopLevel(node, lang)) {
+        replacements.push({ start: node.startIndex, end: node.endIndex, text: "" });
+        return;
+      }
+      if (type === "function_definition" || type === "function_declaration" || type === "method_declaration" || type === "constructor_declaration" || type === "function_item" || type === "method" || type === "singleton_method" || type === "func_literal") {
         symbolCount++;
         const nodeStart = node.startPosition.row + 1;
         const nodeEnd = node.endPosition.row + 1;
@@ -1708,11 +2046,27 @@ async function extractTreeSitterSkeleton(content, lang, opts) {
           bodyEnd = bodyNode.endPosition.row + 1;
           const label = includeLineNumbers ? `/* L${bodyStart}-L${bodyEnd} */` : "/* ... */";
           if (lang === "py") {
-            replacements.push({
-              start: bodyNode.startIndex,
-              end: bodyNode.endIndex,
-              text: includeLineNumbers ? `... # L${bodyStart}-L${bodyEnd}` : "..."
-            });
+            const stub = includeLineNumbers ? `... # L${bodyStart}-L${bodyEnd}` : "...";
+            const first = bodyNode.namedChild(0);
+            const hasDocstring = opts.includeDocs !== false && first?.type === "expression_statement" && first.namedChild(0)?.type === "string";
+            const docLineStart = first ? content.lastIndexOf("\n", first.startIndex - 1) + 1 : 0;
+            const docIndent = first ? content.slice(docLineStart, first.startIndex) : "";
+            if (hasDocstring && first && /^[ \t]*$/.test(docIndent)) {
+              if (bodyNode.namedChildCount > 1) {
+                replacements.push({
+                  start: first.endIndex,
+                  end: bodyNode.endIndex,
+                  text: `
+${docIndent}${stub}`
+                });
+              }
+            } else {
+              replacements.push({
+                start: bodyNode.startIndex,
+                end: bodyNode.endIndex,
+                text: stub
+              });
+            }
           } else if (lang === "ruby") {
             replacements.push({
               start: bodyNode.startIndex,
@@ -1729,8 +2083,7 @@ async function extractTreeSitterSkeleton(content, lang, opts) {
             });
           }
         }
-        const nameNode = node.childForFieldName("name") ?? node.childForFieldName("declarator");
-        const symbolName = nameNode ? nameNode.text : void 0;
+        const symbolName = treeSitterDeclarationName(node);
         symbolRanges.push({
           name: symbolName,
           kind: type.includes("function") ? "function" : "method",
@@ -1752,12 +2105,12 @@ async function extractTreeSitterSkeleton(content, lang, opts) {
       }
       for (let i = 0; i < node.namedChildCount; i++) {
         const child = node.namedChild(i);
-        if (child) walk2(child);
+        if (child) walk2(child, depth + 1);
       }
     };
     var walk = walk2;
     const root = tree.rootNode;
-    walk2(root);
+    walk2(root, 0);
     const skeleton = applyReplacements(content, replacements);
     return { skeleton, symbolCount, symbols: symbolRanges };
   } finally {
@@ -2116,7 +2469,7 @@ async function generateRepoMap(opts) {
     return b.row.rank - a.row.rank;
   }).map(({ row, absolute }) => ({ absolute, relative: relativeOf(row.file) }));
   const known = new Set(candidates.map((c) => c.absolute));
-  const missingFocus = focus.filter((file) => !known.has(file)).map((file) => ({ absolute: file, relative: relativeOf(file) }));
+  const missingFocus = focus.filter((file) => !known.has(file) && isIndexablePath(file)).map((file) => ({ absolute: file, relative: relativeOf(file) }));
   const bodyBudget = Math.max(0, charBudget - header.length - 2);
   const { sections, files } = await renderSkeletonSections(
     [...missingFocus, ...candidates],
@@ -2138,6 +2491,8 @@ async function generateRepoMap(opts) {
 }
 
 // src/codebase-index/codebase-repo-map-tool.ts
+var MIN_MAP_TOKENS = 100;
+var MAX_MAP_TOKENS = 2e4;
 var codebaseRepoMapTool = {
   name: "codebase-repo-map",
   category: "Project",
@@ -2151,8 +2506,10 @@ var codebaseRepoMapTool = {
     type: "object",
     properties: {
       maxTokens: {
-        type: "number",
-        description: "Maximum token budget (approximate) for the map. Defaults to 1200."
+        type: "integer",
+        description: `Maximum token budget (approximate) for the map. Defaults to 1200, range ${MIN_MAP_TOKENS}-${MAX_MAP_TOKENS}.`,
+        minimum: MIN_MAP_TOKENS,
+        maximum: MAX_MAP_TOKENS
       },
       focusFiles: {
         type: "array",
@@ -2166,10 +2523,31 @@ var codebaseRepoMapTool = {
   // `status: 'error'` payload was recorded as a successful call).
   async execute(input, ctx) {
     const projectRoot = ctx.projectRoot ?? ctx.cwd ?? process.cwd();
+    const maxTokens = Number.isFinite(input.maxTokens) ? Math.min(Math.max(Math.trunc(input.maxTokens), MIN_MAP_TOKENS), MAX_MAP_TOKENS) : void 0;
+    let focusFiles;
+    if (input.focusFiles !== void 0) {
+      if (!Array.isArray(input.focusFiles)) {
+        throw new ToolValidationError8({
+          message: "codebase-repo-map: focusFiles must be an array of file paths.",
+          field: "focusFiles"
+        });
+      }
+      focusFiles = [];
+      for (const file of input.focusFiles) {
+        if (typeof file !== "string" || !file.trim()) {
+          throw new ToolValidationError8({
+            message: "codebase-repo-map: focusFiles entries must be non-empty file paths.",
+            field: "focusFiles"
+          });
+        }
+        await safeResolveProjectPath(file.trim(), ctx);
+        focusFiles.push(path7.resolve(projectRoot, file.trim()));
+      }
+    }
     const result = await generateRepoMap({
       projectRoot,
-      maxTokens: input.maxTokens,
-      focusFiles: input.focusFiles,
+      maxTokens,
+      focusFiles,
       // Honour a caller-supplied index location so the map reads the same
       // index the other codebase-* tools do.
       indexDir: codebaseIndexDirOverride(ctx)
@@ -2214,8 +2592,10 @@ var codebaseSkeletonTool = {
         description: "Only include exported/public declarations (defaults to false)."
       },
       maxFiles: {
-        type: "number",
-        description: "Max files to include if path is a directory (defaults to 20, max 50)."
+        type: "integer",
+        description: "Max files to include if path is a directory (defaults to 20, max 50).",
+        minimum: 1,
+        maximum: 50
       }
     },
     required: ["path"],
@@ -2239,7 +2619,8 @@ var codebaseSkeletonTool = {
       exportsOnly: input.exportsOnly ?? false
     };
     if (stat3.isDirectory()) {
-      const maxFiles = Math.min(Math.max(1, input.maxFiles ?? 20), 50);
+      const requested = Number.isFinite(input.maxFiles) ? Math.trunc(input.maxFiles) : 20;
+      const maxFiles = Math.min(Math.max(1, requested), 50);
       const dirResult = await extractDirectorySkeleton({
         dirPath: targetPath,
         maxFiles,
@@ -2362,25 +2743,38 @@ var codebaseStatsTool = {
 
 // src/codebase-index/codebase-targeted-test-tool.ts
 import * as fs7 from "node:fs/promises";
-import * as path7 from "node:path";
+import * as path8 from "node:path";
+import { ToolValidationError as ToolValidationError9 } from "@wrongstack/core/types";
 import { toErrorMessage as toErrorMessage7 } from "@wrongstack/core/utils";
-var TEST_FILE_REGEX2 = /(?:test|spec|mock|fixture|bench)[s]?[/\\._]/i;
+function parseTestCounts(output) {
+  const vitestLine = output.match(/^\s*Tests\s+(.+)$/m)?.[1];
+  const scope = vitestLine ?? output;
+  const last = (re) => {
+    let value;
+    for (const m of scope.matchAll(re)) value = Number(m[1]);
+    return value;
+  };
+  const passed = last(/(\d+)\s+passed/gi);
+  const failed = last(/(\d+)\s+failed/gi);
+  if (passed === void 0 && failed === void 0) return null;
+  return { passed: passed ?? 0, failed: failed ?? 0 };
+}
 async function findConventionTestFiles(projectRoot, sourceRelPath) {
-  const parsed = path7.parse(sourceRelPath);
+  const parsed = path8.parse(sourceRelPath);
   const candidates = [
-    path7.join(parsed.dir, `${parsed.name}.test${parsed.ext}`),
-    path7.join(parsed.dir, `${parsed.name}.spec${parsed.ext}`),
-    path7.join(parsed.dir, `${parsed.name}_test${parsed.ext}`),
-    path7.join(parsed.dir, `test_${parsed.name}${parsed.ext}`),
-    path7.join("tests", `${parsed.name}.test${parsed.ext}`),
-    path7.join("tests", `${parsed.name}.spec${parsed.ext}`),
-    path7.join("test", `${parsed.name}.test${parsed.ext}`),
-    path7.join(parsed.dir, "__tests__", `${parsed.name}.test${parsed.ext}`),
-    path7.join(parsed.dir, "__tests__", `${parsed.name}${parsed.ext}`)
+    path8.join(parsed.dir, `${parsed.name}.test${parsed.ext}`),
+    path8.join(parsed.dir, `${parsed.name}.spec${parsed.ext}`),
+    path8.join(parsed.dir, `${parsed.name}_test${parsed.ext}`),
+    path8.join(parsed.dir, `test_${parsed.name}${parsed.ext}`),
+    path8.join("tests", `${parsed.name}.test${parsed.ext}`),
+    path8.join("tests", `${parsed.name}.spec${parsed.ext}`),
+    path8.join("test", `${parsed.name}.test${parsed.ext}`),
+    path8.join(parsed.dir, "__tests__", `${parsed.name}.test${parsed.ext}`),
+    path8.join(parsed.dir, "__tests__", `${parsed.name}${parsed.ext}`)
   ];
   const found = [];
   for (const cand of candidates) {
-    const absPath = path7.resolve(projectRoot, cand);
+    const absPath = path8.resolve(projectRoot, cand);
     try {
       const st = await fs7.stat(absPath);
       if (st.isFile()) {
@@ -2391,6 +2785,35 @@ async function findConventionTestFiles(projectRoot, sourceRelPath) {
   }
   return found;
 }
+var IndexDiscoveryError = class extends Error {
+  name = "IndexDiscoveryError";
+};
+async function selectTestRunner(projectRoot, suites) {
+  const runnerOf = (suite) => suite.endsWith("_test.go") ? "go" : suite.endsWith(".py") ? "pytest" : "js";
+  const runners = new Set(suites.map(runnerOf));
+  if (runners.size > 1) {
+    throw new ToolValidationError9({
+      message: `codebase-targeted-test: the suites need different runners (${[...runners].join(", ")}): ${suites.join(", ")}. Run each language's suites in a separate call.`,
+      field: "testFiles"
+    });
+  }
+  const runner = runners.values().next().value;
+  if (runner === "go") {
+    const packages = [...new Set(suites.map((s) => `./${path8.posix.dirname(s)}`))];
+    return { cmd: "go", args: ["test", ...packages.map((p) => p === "./." ? "." : p)] };
+  }
+  if (runner === "pytest") return { cmd: "pytest", args: [...suites] };
+  return { cmd: "npx", args: [...await jsRunnerArgs(projectRoot), ...suites] };
+}
+async function jsRunnerArgs(projectRoot) {
+  try {
+    const manifest = JSON.parse(await fs7.readFile(path8.join(projectRoot, "package.json"), "utf8"));
+    const deps = { ...manifest?.dependencies, ...manifest?.devDependencies };
+    if ("jest" in deps && !("vitest" in deps)) return ["jest"];
+  } catch {
+  }
+  return ["vitest", "run"];
+}
 var codebaseTargetedTestTool = {
   name: "codebase-targeted-test",
   category: "Code Quality",
@@ -2423,36 +2846,72 @@ var codebaseTargetedTestTool = {
   async execute(input, ctx, execOpts) {
     const projectRoot = ctx.projectRoot ?? ctx.cwd ?? process.cwd();
     const suitesSet = /* @__PURE__ */ new Set();
-    try {
-      if (input.testFiles) {
-        for (const tf of input.testFiles) suitesSet.add(tf.replace(/\\/g, "/"));
+    const toProjectRelative = async (raw, field) => {
+      if (typeof raw !== "string" || !raw.trim() || raw.trim().startsWith("-")) {
+        throw new ToolValidationError9({
+          message: `codebase-targeted-test: invalid path ${JSON.stringify(raw)} \u2014 expected a project file path, not a flag.`,
+          field
+        });
+      }
+      const resolved = await safeResolveProjectPath(raw.trim(), ctx);
+      return path8.relative(projectRoot, resolved).replace(/\\/g, "/");
+    };
+    const explicitSuites = [];
+    if (input.testFiles !== void 0) {
+      if (!Array.isArray(input.testFiles)) {
+        throw new ToolValidationError9({
+          message: "codebase-targeted-test: testFiles must be an array of file paths.",
+          field: "testFiles"
+        });
       }
-      if (input.symbol) {
+      for (const tf of input.testFiles)
+        explicitSuites.push(await toProjectRelative(tf, "testFiles"));
+    }
+    const sourceFile = input.file !== void 0 ? await toProjectRelative(input.file, "file") : void 0;
+    if (explicitSuites.length === 0 && !input.symbol?.trim() && sourceFile === void 0) {
+      throw new ToolValidationError9({
+        message: "codebase-targeted-test: pass at least one of `symbol`, `file`, or `testFiles`.",
+        field: "symbol"
+      });
+    }
+    const symbol = input.symbol?.trim();
+    let discoveryError;
+    try {
+      for (const tf of explicitSuites) suitesSet.add(tf);
+      if (symbol) {
         try {
           const indexDir = codebaseIndexDirOverride(ctx);
           const serviced = await incomingCallsService({
             projectRoot,
             indexDir,
-            symbol: input.symbol,
+            symbol,
             file: input.file,
             limit: 100,
             transitive: true
           });
           for (const site of serviced.calls) {
-            const relPath = path7.relative(projectRoot, site.symbol.file).replace(/\\/g, "/");
-            if (TEST_FILE_REGEX2.test(relPath)) {
+            const relPath = path8.relative(projectRoot, site.symbol.file).replace(/\\/g, "/");
+            if (relPath.startsWith("../") || path8.isAbsolute(relPath)) continue;
+            if (isTestFilePath(relPath)) {
               suitesSet.add(relPath);
             }
           }
-        } catch {
+        } catch (err) {
+          discoveryError = err;
         }
       }
-      if (input.file) {
-        const convFiles = await findConventionTestFiles(projectRoot, input.file);
+      if (sourceFile !== void 0) {
+        const convFiles = await findConventionTestFiles(projectRoot, sourceFile);
         for (const cf of convFiles) suitesSet.add(cf);
       }
       const discoveredSuites = [...suitesSet];
       if (discoveredSuites.length === 0) {
+        if (discoveryError !== void 0) {
+          throw new IndexDiscoveryError(
+            `Could not discover tests for '${symbol}': the codebase index query failed (${toErrorMessage7(discoveryError)}). Run codebase-index, or pass \`file\`/\`testFiles\`.`,
+            { cause: discoveryError }
+          );
+        }
         return {
           status: "no_tests_found",
           discoveredSuites: [],
@@ -2464,15 +2923,10 @@ var codebaseTargetedTestTool = {
         };
       }
       const start = Date.now();
-      let runnerCmd = "npx";
-      let runnerArgs = ["vitest", "run", ...discoveredSuites];
-      if (discoveredSuites.every((s) => s.endsWith(".py"))) {
-        runnerCmd = "pytest";
-        runnerArgs = discoveredSuites;
-      } else if (discoveredSuites.every((s) => s.endsWith("_test.go"))) {
-        runnerCmd = "go";
-        runnerArgs = ["test", ...discoveredSuites];
-      }
+      const { cmd: runnerCmd, args: runnerArgs } = await selectTestRunner(
+        projectRoot,
+        discoveredSuites
+      );
       const signal = execOpts?.signal ?? ctx.signal ?? new AbortController().signal;
       const gen = spawnStream({
         cmd: runnerCmd,
@@ -2487,16 +2941,15 @@ var codebaseTargetedTestTool = {
       }
       const streamRes = genResult.value;
       const durationMs = Date.now() - start;
-      const combinedOutput = normalizeCommandOutput(
-        `${streamRes.stdout}
-${streamRes.stderr}`.trim(),
-        { maxBytes: 4e3 }
-      );
+      const rawOutput = `${streamRes.stdout}
+${streamRes.stderr}`.trim();
+      const combinedOutput = normalizeCommandOutput(rawOutput, { maxBytes: 4e3 });
       const isPassed = streamRes.exitCode === 0;
-      const passMatch = combinedOutput.match(/(\d+)\s+passed/i);
-      const failMatch = combinedOutput.match(/(\d+)\s+failed/i);
-      const passed = passMatch ? parseInt(passMatch[1] ?? "0", 10) : isPassed ? discoveredSuites.length : 0;
-      const failed = failMatch ? parseInt(failMatch[1] ?? "0", 10) : isPassed ? 0 : 1;
+      const counts = parseTestCounts(
+        normalizeCommandOutput(rawOutput, { maxBytes: Number.MAX_SAFE_INTEGER })
+      );
+      const passed = counts ? counts.passed : isPassed ? discoveredSuites.length : 0;
+      const failed = counts ? counts.failed : isPassed ? 0 : 1;
       const testsRun = passed + failed;
       return {
         status: isPassed ? "passed" : "failed",
@@ -2508,6 +2961,7 @@ ${streamRes.stderr}`.trim(),
         output: combinedOutput
       };
     } catch (err) {
+      if (err instanceof IndexDiscoveryError || err instanceof ToolValidationError9) throw err;
       const suites = suitesSet.size > 0 ? ` (discovered suites: ${[...suitesSet].join(", ")})` : "";
       throw new Error(`Targeted test run failed to execute: ${toErrorMessage7(err)}${suites}`, {
         cause: err
@@ -2518,8 +2972,8 @@ ${streamRes.stderr}`.trim(),
 
 // src/codebase-index/dead-code-scan.ts
 import * as fs8 from "node:fs";
-import * as path8 from "node:path";
-import { ToolValidationError as ToolValidationError6 } from "@wrongstack/core/types";
+import * as path9 from "node:path";
+import { ToolValidationError as ToolValidationError10 } from "@wrongstack/core/types";
 var deadCodeScanTool = {
   name: "dead-code-scan",
   category: "Project",
@@ -2557,11 +3011,11 @@ var deadCodeScanTool = {
       userEntryPoints = [];
       for (const ep of input.entryPoints) {
         const resolved = await safeResolveProjectPath(
-          path8.isAbsolute(ep) ? ep : path8.resolve(projectRoot, ep),
+          path9.isAbsolute(ep) ? ep : path9.resolve(projectRoot, ep),
           ctx
         );
         if (!fs8.existsSync(resolved)) {
-          throw new ToolValidationError6({
+          throw new ToolValidationError10({
             message: `dead-code-scan: entry point not found: "${ep}"`,
             field: "entryPoints"
           });
@@ -2595,8 +3049,8 @@ function tryReadJson(filePath) {
   }
 }
 function resolveAgainst(base, relative12) {
-  if (path8.isAbsolute(relative12)) return relative12;
-  return path8.resolve(base, relative12);
+  if (path9.isAbsolute(relative12)) return relative12;
+  return path9.resolve(base, relative12);
 }
 function discoverEntryPoints(projectRoot, userEntryPoints) {
   const entries = /* @__PURE__ */ new Set();
@@ -2606,7 +3060,7 @@ function discoverEntryPoints(projectRoot, userEntryPoints) {
       if (fs8.existsSync(resolved)) entries.add(resolved);
     }
   }
-  const rootPkg = tryReadJson(path8.join(projectRoot, "package.json"));
+  const rootPkg = tryReadJson(path9.join(projectRoot, "package.json"));
   if (rootPkg) {
     addPkgJsonEntryPoints(projectRoot, rootPkg, entries);
   }
@@ -2620,34 +3074,34 @@ function discoverEntryPoints(projectRoot, userEntryPoints) {
     workspaces = [];
   }
   for (const wsDir of workspaces) {
-    const pkgJsonPath = path8.join(wsDir, "package.json");
+    const pkgJsonPath = path9.join(wsDir, "package.json");
     const pkg = tryReadJson(pkgJsonPath);
     if (pkg) {
       addPkgJsonEntryPoints(wsDir, pkg, entries);
-      const convention1 = path8.join(wsDir, "src", "index.ts");
+      const convention1 = path9.join(wsDir, "src", "index.ts");
       if (fs8.existsSync(convention1)) entries.add(convention1);
-      const convention2 = path8.join(wsDir, "src", "main.ts");
+      const convention2 = path9.join(wsDir, "src", "main.ts");
       if (fs8.existsSync(convention2)) entries.add(convention2);
-      const convention3 = path8.join(wsDir, "index.ts");
+      const convention3 = path9.join(wsDir, "index.ts");
       if (fs8.existsSync(convention3)) entries.add(convention3);
     }
   }
   if (!rootPkg || !workspaces.length) {
     for (const name of ["src/index.ts", "src/main.ts", "index.ts"]) {
-      const convention = path8.join(projectRoot, name);
+      const convention = path9.join(projectRoot, name);
       if (fs8.existsSync(convention)) entries.add(convention);
     }
   }
   return [...entries];
 }
 var BUILD_OUTPUT_DIRS = ["dist", "out", "build", "release"];
-var BUILD_OUTPUT_DIR_NAMES = BUILD_OUTPUT_DIRS.map((d) => `${path8.sep}${d}${path8.sep}`);
+var BUILD_OUTPUT_DIR_NAMES = BUILD_OUTPUT_DIRS.map((d) => `${path9.sep}${d}${path9.sep}`);
 function trySourceEquivalent(resolved) {
-  resolved = resolved.replace(/[/\\]/g, path8.sep);
+  resolved = resolved.replace(/[/\\]/g, path9.sep);
   for (const marker of BUILD_OUTPUT_DIR_NAMES) {
     const idx = resolved.indexOf(marker);
     if (idx === -1) continue;
-    const base = resolved.replace(marker, `${path8.sep}src${path8.sep}`);
+    const base = resolved.replace(marker, `${path9.sep}src${path9.sep}`);
     const candidate = base.replace(/\.(js|mjs|cjs)$/, ".ts");
     if (candidate !== base && fs8.existsSync(candidate)) {
       return candidate;
@@ -2693,44 +3147,48 @@ function addPkgJsonEntryPoints(pkgDir, pkg, entries) {
       tryAddEntryPath(pkgDir, pkg[key], entries);
     }
   }
-  const exports_ = pkg.exports;
-  if (exports_ && typeof exports_ === "object") {
-    for (const value of Object.values(exports_)) {
-      if (typeof value === "string") {
-        tryAddEntryPath(pkgDir, value, entries);
-      } else if (value && typeof value === "object") {
-        for (const nested of Object.values(value)) {
-          if (typeof nested === "string") {
-            tryAddEntryPath(pkgDir, nested, entries);
-          }
-        }
-      }
-    }
+  const targets = [];
+  collectExportTargets(pkg.exports, targets, 0);
+  for (const target of targets) tryAddEntryPath(pkgDir, target, entries);
+}
+function collectExportTargets(value, out, depth) {
+  if (depth > 8) return;
+  if (typeof value === "string") {
+    out.push(value);
+    return;
+  }
+  if (Array.isArray(value)) {
+    for (const item of value) collectExportTargets(item, out, depth + 1);
+    return;
+  }
+  if (value && typeof value === "object") {
+    for (const item of Object.values(value)) collectExportTargets(item, out, depth + 1);
   }
 }
 function expandGlobPattern(entry, projectRoot) {
   const dirs = [];
   if (entry.includes("*")) {
     const base = entry.replace(/\/\*+$/, "");
-    const baseDir = path8.resolve(projectRoot, base);
+    const baseDir = path9.resolve(projectRoot, base);
     try {
       const children = fs8.readdirSync(baseDir, { withFileTypes: true });
       for (const child of children) {
         if (child.isDirectory()) {
-          dirs.push(path8.join(baseDir, child.name));
+          dirs.push(path9.join(baseDir, child.name));
         }
       }
     } catch {
     }
   } else {
-    dirs.push(path8.resolve(projectRoot, entry));
+    dirs.push(path9.resolve(projectRoot, entry));
   }
   return dirs;
 }
 function extractWorkspaceGlobs(pkg, projectRoot) {
   const dirs = [];
-  const workspaces = pkg.workspaces;
-  if (Array.isArray(workspaces)) {
+  const raw = pkg.workspaces;
+  const workspaces = Array.isArray(raw) ? raw : raw && typeof raw === "object" && Array.isArray(raw.packages) ? raw.packages : void 0;
+  if (workspaces) {
     for (const entry of workspaces) {
       if (typeof entry === "string") {
         dirs.push(...expandGlobPattern(entry, projectRoot));
@@ -2740,7 +3198,7 @@ function extractWorkspaceGlobs(pkg, projectRoot) {
   return dirs;
 }
 function extractPnpmWorkspaceDirs(projectRoot) {
-  const yamlPath = path8.join(projectRoot, "pnpm-workspace.yaml");
+  const yamlPath = path9.join(projectRoot, "pnpm-workspace.yaml");
   if (!fs8.existsSync(yamlPath)) return [];
   try {
     const content = fs8.readFileSync(yamlPath, "utf8");
@@ -2775,10 +3233,17 @@ function extractPnpmWorkspaceDirs(projectRoot) {
     return [];
   }
 }
+var NON_CODE_LANGS = /* @__PURE__ */ new Set(["json", "yaml", "toml", "md"]);
+var RECEIVER_ONLY_MEMBER_CALL_LANGS = /* @__PURE__ */ new Set([
+  "ts",
+  "tsx",
+  "js",
+  "jsx"
+]);
 function resolveModulePath(importerPath, moduleSpecifier, indexedFiles) {
   if (!moduleSpecifier.startsWith(".")) return [];
-  const dir = path8.dirname(importerPath);
-  const base = path8.resolve(dir, moduleSpecifier);
+  const dir = path9.dirname(importerPath);
+  const base = path9.resolve(dir, moduleSpecifier);
   const results = [];
   const stripped = base.replace(/\.(ts|tsx|js|jsx|mjs|cjs)$/, "");
   const skipBase = stripped !== base && /\.(ts|tsx|js|jsx|mjs|cjs)$/.test(base);
@@ -2790,18 +3255,18 @@ function resolveModulePath(importerPath, moduleSpecifier, indexedFiles) {
     if (indexedFiles.has(candidate + ".jsx")) results.push(candidate + ".jsx");
     if (indexedFiles.has(candidate + ".mjs")) results.push(candidate + ".mjs");
     if (indexedFiles.has(candidate + ".cjs")) results.push(candidate + ".cjs");
-    if (indexedFiles.has(path8.join(candidate, "index.ts")))
-      results.push(path8.join(candidate, "index.ts"));
-    if (indexedFiles.has(path8.join(candidate, "index.tsx")))
-      results.push(path8.join(candidate, "index.tsx"));
-    if (indexedFiles.has(path8.join(candidate, "index.js")))
-      results.push(path8.join(candidate, "index.js"));
-    if (indexedFiles.has(path8.join(candidate, "index.jsx")))
-      results.push(path8.join(candidate, "index.jsx"));
-    if (indexedFiles.has(path8.join(candidate, "index.mjs")))
-      results.push(path8.join(candidate, "index.mjs"));
-    if (indexedFiles.has(path8.join(candidate, "index.cjs")))
-      results.push(path8.join(candidate, "index.cjs"));
+    if (indexedFiles.has(path9.join(candidate, "index.ts")))
+      results.push(path9.join(candidate, "index.ts"));
+    if (indexedFiles.has(path9.join(candidate, "index.tsx")))
+      results.push(path9.join(candidate, "index.tsx"));
+    if (indexedFiles.has(path9.join(candidate, "index.js")))
+      results.push(path9.join(candidate, "index.js"));
+    if (indexedFiles.has(path9.join(candidate, "index.jsx")))
+      results.push(path9.join(candidate, "index.jsx"));
+    if (indexedFiles.has(path9.join(candidate, "index.mjs")))
+      results.push(path9.join(candidate, "index.mjs"));
+    if (indexedFiles.has(path9.join(candidate, "index.cjs")))
+      results.push(path9.join(candidate, "index.cjs"));
   }
   return [...new Set(results)];
 }
@@ -2833,7 +3298,7 @@ function runDeadCodeScan(projectRoot, opts = {}) {
       symbolById.set(s.id, s);
     }
     const discoveredFiles = discoverEntryPoints(projectRoot, opts.userEntryPoints);
-    const entryFileSet = new Set(discoveredFiles.map((f) => path8.resolve(f)));
+    const entryFileSet = new Set(discoveredFiles.map((f) => path9.resolve(f)));
     const indexedFiles = /* @__PURE__ */ new Set();
     for (const s of allSymbols) indexedFiles.add(s.file);
     for (const fm of store.getAllFileMetas()) indexedFiles.add(fm.file);
@@ -2904,12 +3369,31 @@ function runDeadCodeScan(projectRoot, opts = {}) {
     const dead = [];
     const symbolsByFile = /* @__PURE__ */ new Map();
     const usedFiles = /* @__PURE__ */ new Set();
+    const liveScopesByFile = /* @__PURE__ */ new Map();
+    for (const s of allSymbols) {
+      if (!alive.has(s.id)) continue;
+      const scopePath = s.scope ? `${s.scope}.${s.name}` : s.name;
+      let scopes = liveScopesByFile.get(s.file);
+      if (!scopes) {
+        scopes = /* @__PURE__ */ new Set();
+        liveScopesByFile.set(s.file, scopes);
+      }
+      scopes.add(scopePath);
+    }
+    const isMemberOfLiveDeclaration = (s) => {
+      if (!s.scope) return false;
+      const lang = detectLang(s.file);
+      if (lang === null || !RECEIVER_ONLY_MEMBER_CALL_LANGS.has(lang)) return false;
+      return liveScopesByFile.get(s.file)?.has(s.scope) ?? false;
+    };
     for (const s of allSymbols) {
-      if (alive.has(s.id)) {
+      if (alive.has(s.id) || isMemberOfLiveDeclaration(s)) {
         usedFiles.add(s.file);
         continue;
       }
       if (s.kind === "parameter") continue;
+      const symbolLang = detectLang(s.file);
+      if (symbolLang !== null && NON_CODE_LANGS.has(symbolLang)) continue;
       if (s.kind === "let" || s.kind === "var") {
         continue;
       }
@@ -2931,14 +3415,7 @@ function runDeadCodeScan(projectRoot, opts = {}) {
     }
     const deadFiles = [];
     for (const [file, syms] of symbolsByFile) {
-      let anyAlive = false;
-      for (const s of allSymbols) {
-        if (s.file === file && alive.has(s.id)) {
-          anyAlive = true;
-          break;
-        }
-      }
-      if (!anyAlive) {
+      if (!usedFiles.has(file)) {
         deadFiles.push({
           file,
           symbolCount: syms.length,
@@ -2949,7 +3426,7 @@ function runDeadCodeScan(projectRoot, opts = {}) {
     const deadPackages = [];
     const pkgEntries = findPackageEntries(projectRoot);
     for (const [pkgName, pkgDir] of pkgEntries) {
-      const pkgFiles = allSymbols.filter((s) => s.file.startsWith(pkgDir + path8.sep));
+      const pkgFiles = allSymbols.filter((s) => s.file.startsWith(pkgDir + path9.sep));
       if (pkgFiles.length === 0) continue;
       const pkgUsed = pkgFiles.filter((s) => alive.has(s.id));
       if (pkgUsed.length === 0) {
@@ -2985,7 +3462,7 @@ function runDeadCodeScan(projectRoot, opts = {}) {
 }
 function findPackageEntries(projectRoot) {
   const pkgMap = /* @__PURE__ */ new Map();
-  const rootPkg = tryReadJson(path8.join(projectRoot, "package.json"));
+  const rootPkg = tryReadJson(path9.join(projectRoot, "package.json"));
   if (rootPkg && typeof rootPkg.name === "string") {
     pkgMap.set(rootPkg.name, projectRoot);
   }
@@ -2995,7 +3472,7 @@ function findPackageEntries(projectRoot) {
       wsDirs = extractPnpmWorkspaceDirs(projectRoot);
     }
     for (const wsDir of wsDirs) {
-      const wsPkg = tryReadJson(path8.join(wsDir, "package.json"));
+      const wsPkg = tryReadJson(path9.join(wsDir, "package.json"));
       if (wsPkg && typeof wsPkg.name === "string") {
         pkgMap.set(wsPkg.name, wsDir);
       }
@@ -3006,13 +3483,13 @@ function findPackageEntries(projectRoot) {
 
 // src/codebase-index/atlas-brief.ts
 import { existsSync as existsSync4 } from "node:fs";
-import * as path10 from "node:path";
+import * as path11 from "node:path";
 
 // src/codebase-index/atlas-projection.ts
 import { createHash } from "node:crypto";
 import { existsSync as existsSync3 } from "node:fs";
 import * as fs9 from "node:fs/promises";
-import * as path9 from "node:path";
+import * as path10 from "node:path";
 
 // src/codebase-index/atlas-export.ts
 var EXPORT_PACKAGE_LIMIT = 40;
@@ -3224,7 +3701,7 @@ ${renderFileRows(document)}
 }
 
 // src/codebase-index/atlas-projection.ts
-var ATLAS_DIR = path9.join(".wrongstack", "atlas");
+var ATLAS_DIR = path10.join(".wrongstack", "atlas");
 var ATLAS_JSON = "atlas.json";
 var ATLAS_MARKDOWN = "ATLAS.md";
 var ATLAS_MANIFEST = "manifest.json";
@@ -3237,9 +3714,27 @@ var RANK_PRECISION = 4;
 function round(value) {
   return Number(value.toFixed(RANK_PRECISION));
 }
+function compareText(a, b) {
+  return a < b ? -1 : a > b ? 1 : 0;
+}
+function atlasPackageName(packageLabel, relativePath) {
+  return packageLabel || relativePath.split("/")[0] || "(root)";
+}
+function atlasPackageFileCounts(store, relativeOf) {
+  const labels = store.getFilePackages();
+  const counts = /* @__PURE__ */ new Map();
+  for (const meta of store.getAllFileMetas()) {
+    const name = atlasPackageName(labels.get(meta.file), relativeOf(meta.file));
+    counts.set(name, (counts.get(name) ?? 0) + 1);
+  }
+  return counts;
+}
+function markdownCell(value) {
+  return value.replace(/\s+/g, " ").replace(/\|/g, "\\|").trim();
+}
 function relativeFactory(projectRoot) {
   return (file) => {
-    const relative12 = path9.relative(projectRoot, file);
+    const relative12 = path10.relative(projectRoot, file);
     if (!relative12 || relative12.startsWith("..")) return posixIndexPath(file);
     return posixIndexPath(relative12);
   };
@@ -3274,13 +3769,15 @@ function renderMarkdown(document) {
     "| --- | ---: | --- | ---: |"
   ];
   for (const pkg of document.packages) {
-    lines.push(`| ${pkg.name} | ${pkg.files} | \`${pkg.hub}\` | ${pkg.rank.toFixed(4)} |`);
+    lines.push(
+      `| ${markdownCell(pkg.name)} | ${pkg.files} | \`${markdownCell(pkg.hub)}\` | ${pkg.rank.toFixed(4)} |`
+    );
   }
   const described = document.packages.filter((pkg) => pkg.summary !== void 0);
   if (described.length > 0) {
     lines.push("", "## Subsystems", "");
     for (const pkg of described) {
-      lines.push(`- **${pkg.name}** \u2014 ${pkg.summary}`);
+      lines.push(`- **${markdownCell(pkg.name)}** \u2014 ${markdownCell(pkg.summary ?? "")}`);
     }
   }
   lines.push(
@@ -3293,9 +3790,9 @@ function renderMarkdown(document) {
     "| ---: | --- | ---: | ---: | --- |"
   );
   for (const file of document.files.slice(0, MARKDOWN_FILE_LIMIT)) {
-    const declarations = file.symbols.slice(0, MARKDOWN_SYMBOLS_PER_FILE).map((symbol) => `\`${symbol.name}\``).join(", ");
+    const declarations = file.symbols.slice(0, MARKDOWN_SYMBOLS_PER_FILE).map((symbol) => `\`${markdownCell(symbol.name)}\``).join(", ");
     lines.push(
-      `| ${file.rank.toFixed(4)} | \`${file.path}\` | ${file.inDeg} | ${file.outDeg} | ${declarations} |`
+      `| ${file.rank.toFixed(4)} | \`${markdownCell(file.path)}\` | ${file.inDeg} | ${file.outDeg} | ${declarations} |`
     );
   }
   return `${lines.join("\n").trimEnd()}
@@ -3304,14 +3801,14 @@ function renderMarkdown(document) {
 function buildAtlas(store, projectRoot) {
   const relativeOf = relativeFactory(projectRoot);
   const stats = store.getStats();
-  const packageCounts = store.getPackageFileCounts();
+  const packageCounts = atlasPackageFileCounts(store, relativeOf);
   const ranked = store.getRankedFiles(ATLAS_FILE_LIMIT);
   const concepts = store.getReadyConceptSummaries();
   const subsystemSummaries = new Map(
     store.getSubsystems().map((subsystem) => [subsystem.id, subsystem.summary])
   );
   const packages = /* @__PURE__ */ new Map();
-  const packageNameOf = (row) => row.package || relativeOf(row.file).split("/")[0] || "(root)";
+  const packageNameOf = (row) => atlasPackageName(row.package, relativeOf(row.file));
   for (const row of ranked) {
     const relative12 = relativeOf(row.file);
     const name = packageNameOf(row);
@@ -3320,7 +3817,7 @@ function buildAtlas(store, projectRoot) {
       const summary = subsystemSummaries.get(name);
       packages.set(name, {
         name,
-        files: packageCounts.get(row.package) ?? 0,
+        files: packageCounts.get(name) ?? 0,
         hub: relative12,
         rank: round(row.rank),
         // Absent rather than empty: an un-enriched repository must project the
@@ -3354,14 +3851,12 @@ function buildAtlas(store, projectRoot) {
     weight: edge.weight,
     refType: edge.refType
   })).filter((edge) => known.has(edge.from) && known.has(edge.to)).sort(
-    (a, b) => a.from.localeCompare(b.from) || a.to.localeCompare(b.to) || a.refType.localeCompare(b.refType)
+    (a, b) => compareText(a.from, b.from) || compareText(a.to, b.to) || compareText(a.refType, b.refType)
   );
   const document = {
     schema: ATLAS_SCHEMA,
     counts: { files: stats.totalFiles, symbols: stats.totalSymbols, packages: packages.size },
-    packages: [...packages.values()].sort(
-      (a, b) => b.rank - a.rank || a.name.localeCompare(b.name)
-    ),
+    packages: [...packages.values()].sort((a, b) => b.rank - a.rank || compareText(a.name, b.name)),
     edges,
     files
   };
@@ -3389,7 +3884,7 @@ function stableJson(value) {
 }
 async function writeAtlas(store, projectRoot) {
   const projection = buildAtlas(store, projectRoot);
-  const dir = path9.join(projectRoot, ATLAS_DIR);
+  const dir = path10.join(projectRoot, ATLAS_DIR);
   await fs9.mkdir(dir, { recursive: true });
   const written = [
     [ATLAS_JSON, stableJson(projection.document)],
@@ -3397,7 +3892,7 @@ async function writeAtlas(store, projectRoot) {
     [ATLAS_MARKDOWN, projection.markdown]
   ];
   for (const [name, body] of written) {
-    await fs9.writeFile(path9.join(dir, name), body, "utf8");
+    await fs9.writeFile(path10.join(dir, name), body, "utf8");
   }
   return {
     dir: posixIndexPath(ATLAS_DIR),
@@ -3418,7 +3913,7 @@ async function checkAtlasFreshness(store, projectRoot) {
   });
   let raw;
   try {
-    raw = await fs9.readFile(path9.join(projectRoot, ATLAS_DIR, ATLAS_MANIFEST), "utf8");
+    raw = await fs9.readFile(path10.join(projectRoot, ATLAS_DIR, ATLAS_MANIFEST), "utf8");
   } catch {
     return stale("missing");
   }
@@ -3464,7 +3959,7 @@ async function checkAtlasFreshness(store, projectRoot) {
   };
 }
 function hasIndex(projectRoot, indexDir) {
-  return existsSync3(path9.join(resolveIndexDir(projectRoot, indexDir), "index.db"));
+  return existsSync3(path10.join(resolveIndexDir(projectRoot, indexDir), "index.db"));
 }
 async function withStore(projectRoot, indexDir, job) {
   if (!hasIndex(projectRoot, indexDir)) return { indexed: false };
@@ -3486,7 +3981,7 @@ function exportProjectAtlasHtml(projectRoot, opts = {}) {
     projectRoot,
     opts.indexDir,
     (store) => renderAtlasHtml(buildAtlas(store, projectRoot).document, {
-      projectName: opts.projectName ?? path9.basename(projectRoot)
+      projectName: opts.projectName ?? path10.basename(projectRoot)
     })
   );
 }
@@ -3502,7 +3997,7 @@ function trim(text) {
 }
 async function buildAtlasBrief(store, projectRoot) {
   const relativeOf = (file) => {
-    const relative12 = path10.relative(projectRoot, file);
+    const relative12 = path11.relative(projectRoot, file);
     return posixIndexPath(relative12 && !relative12.startsWith("..") ? relative12 : file);
   };
   const stats = store.getStats();
@@ -3516,16 +4011,16 @@ async function buildAtlasBrief(store, projectRoot) {
       ...concept !== void 0 && concept !== "" ? { concept: trim(concept) } : {}
     };
   });
-  const counts = store.getPackageFileCounts();
+  const counts = atlasPackageFileCounts(store, relativeOf);
   const hubOf = /* @__PURE__ */ new Map();
   for (const row of store.getRankedFiles(Math.max(counts.size * 4, BRIEF_HUB_LIMIT))) {
-    const name = row.package || relativeOf(row.file).split("/")[0] || "(root)";
+    const name = atlasPackageName(row.package, relativeOf(row.file));
     const current = hubOf.get(name);
     if (current === void 0 || row.rank > current.rank) {
       hubOf.set(name, { file: relativeOf(row.file), rank: row.rank });
     }
   }
-  const packages = [...hubOf.entries()].sort((a, b) => b[1].rank - a[1].rank || a[0].localeCompare(b[0])).slice(0, BRIEF_PACKAGE_LIMIT).map(([name, hub]) => ({ name, files: counts.get(name) ?? 0, hub: hub.file }));
+  const packages = [...hubOf.entries()].sort((a, b) => b[1].rank - a[1].rank || compareText(a[0], b[0])).slice(0, BRIEF_PACKAGE_LIMIT).map(([name, hub]) => ({ name, files: counts.get(name) ?? 0, hub: hub.file }));
   const subsystems = store.getSubsystems().filter((subsystem) => subsystem.summary !== "").slice(0, BRIEF_SUBSYSTEM_LIMIT).map((subsystem) => ({ name: subsystem.name, summary: trim(subsystem.summary) }));
   const brief = {
     ranked: hubs.length > 0,
@@ -3548,7 +4043,7 @@ async function buildAtlasBrief(store, projectRoot) {
   return brief;
 }
 async function buildProjectAtlasBrief(projectRoot, opts = {}) {
-  if (!existsSync4(path10.join(resolveIndexDir(projectRoot, opts.indexDir), "index.db"))) {
+  if (!existsSync4(path11.join(resolveIndexDir(projectRoot, opts.indexDir), "index.db"))) {
     return { indexed: false };
   }
   const store = indexStorePool.acquire(projectRoot, { indexDir: opts.indexDir });
@@ -3560,12 +4055,15 @@ async function buildProjectAtlasBrief(projectRoot, opts = {}) {
 }
 
 // src/codebase-index/codebase-context-tool.ts
-import { ToolValidationError as ToolValidationError7 } from "@wrongstack/core/types";
+import { ToolValidationError as ToolValidationError11 } from "@wrongstack/core/types";
 import { toErrorMessage as toErrorMessage8 } from "@wrongstack/core/utils";
 var TOOL_TIMEOUT_MS = 35e3;
 var VECTOR_HIT_LIMIT = 12;
 var VECTOR_MIN_SCORE = 0.25;
 var queryEmbedder;
+function finiteIntOrUndefined(value) {
+  return typeof value === "number" && Number.isFinite(value) ? Math.trunc(value) : void 0;
+}
 function setContextQueryEmbedder(port) {
   queryEmbedder = port;
 }
@@ -3605,12 +4103,16 @@ var codebaseContextTool = {
         description: "What you are trying to do or understand, in plain words."
       },
       limit: {
-        type: "number",
-        description: "Number of files to return (default 12, max 50)."
+        type: "integer",
+        description: "Number of files to return (default 12, max 50).",
+        minimum: 1,
+        maximum: 50
       },
       symbolsPerFile: {
-        type: "number",
-        description: "Declarations shown per file (default 4, max 20)."
+        type: "integer",
+        description: "Declarations shown per file (default 4, max 20).",
+        minimum: 1,
+        maximum: 20
       },
       pathPrefix: {
         type: "string",
@@ -3623,7 +4125,7 @@ var codebaseContextTool = {
   async execute(input, ctx, execOpts) {
     const query = typeof input.query === "string" ? input.query.trim() : "";
     if (query.length === 0) {
-      throw new ToolValidationError7({
+      throw new ToolValidationError11({
         message: "codebase-context requires a non-empty `query`.",
         field: "query"
       });
@@ -3641,9 +4143,11 @@ var codebaseContextTool = {
         indexDir,
         query,
         ...vectorFiles.length > 0 ? { vectorFiles } : {},
-        limit: input.limit,
-        symbolsPerFile: input.symbolsPerFile,
-        pathPrefix: input.pathPrefix
+        // A NaN slipping past the schema survived the server's min/max clamp
+        // and truncated the answer to zero files.
+        limit: finiteIntOrUndefined(input.limit),
+        symbolsPerFile: finiteIntOrUndefined(input.symbolsPerFile),
+        pathPrefix: input.pathPrefix?.replace(/\\/g, "/")
       });
     } catch (err) {
       if (signal?.aborted) throw err;
@@ -3673,7 +4177,7 @@ var codebaseContextTool = {
 // src/codebase-index/concept-enrichment.ts
 import { existsSync as existsSync5 } from "node:fs";
 import * as fs10 from "node:fs/promises";
-import * as path11 from "node:path";
+import * as path12 from "node:path";
 var MAX_SOURCE_CHARS = 12e3;
 var MAX_CRUX_LINES = 12;
 var MAX_DECLARATIONS = 24;
@@ -3692,7 +4196,9 @@ async function enrichConcepts(store, port, relativeOf, options = {}) {
   const startedAt = Date.now();
   const errors = [];
   const signal = options.signal;
-  const concurrency = Math.max(1, Math.min(options.concurrency ?? DEFAULT_CONCURRENCY, 16));
+  const requestedConcurrency = Number.isFinite(options.concurrency) ? Math.trunc(options.concurrency) : DEFAULT_CONCURRENCY;
+  const concurrency = Math.max(1, Math.min(requestedConcurrency, 16));
+  const maxFiles = options.maxFiles !== void 0 && Number.isFinite(options.maxFiles) ? Math.max(0, Math.trunc(options.maxFiles)) : void 0;
   const pruned = store.pruneOrphanConcepts();
   const markedStale = store.markStaleConcepts();
   const hashByFile = /* @__PURE__ */ new Map();
@@ -3707,6 +4213,7 @@ async function enrichConcepts(store, port, relativeOf, options = {}) {
   const queue = [];
   let cached = 0;
   for (const file of ordered) {
+    if (maxFiles !== void 0 && queue.length >= maxFiles) break;
     const hash = hashByFile.get(file);
     if (hash === void 0) continue;
     const concept = existing.get(file);
@@ -3716,7 +4223,6 @@ async function enrichConcepts(store, port, relativeOf, options = {}) {
       continue;
     }
     queue.push(file);
-    if (options.maxFiles !== void 0 && queue.length >= options.maxFiles) break;
   }
   let summarised = 0;
   let failed = 0;
@@ -3787,7 +4293,7 @@ async function summariseOne(store, port, relativeOf, file, hashByFile, existing,
   const result = await port.describeFile({
     file: relativeOf(file),
     absolutePath: file,
-    language: "",
+    language: detectLang(file) ?? "",
     source: truncated ? source.slice(0, MAX_SOURCE_CHARS) : source,
     truncated,
     declarations,
@@ -3816,13 +4322,18 @@ async function deriveSubsystems(store, port, relativeOf, signal) {
   if (describe === void 0) return 0;
   const summaries = store.getReadyConceptSummaries();
   if (summaries.size === 0) return 0;
+  const rankOf = store.getFileRankMap();
+  const packageOf = store.getFilePackages();
+  const ordered = [...summaries.keys()].sort(
+    (a, b) => (rankOf.get(b) ?? 0) - (rankOf.get(a) ?? 0) || a.localeCompare(b)
+  );
   const byPackage = /* @__PURE__ */ new Map();
-  for (const row of store.getRankedFiles(summaries.size * 2)) {
-    const summary = summaries.get(row.file);
+  for (const file of ordered) {
+    const summary = summaries.get(file);
     if (summary === void 0) continue;
-    const name = row.package || relativeOf(row.file).split("/")[0] || "(root)";
+    const name = packageOf.get(file) || relativeOf(file).split("/")[0] || "(root)";
     const bucket = byPackage.get(name);
-    const entry = { file: relativeOf(row.file), summary, rank: row.rank };
+    const entry = { file: relativeOf(file), summary, rank: rankOf.get(file) ?? 0 };
     if (bucket === void 0) byPackage.set(name, [entry]);
     else if (bucket.length < SUBSYSTEM_FILE_SAMPLE) bucket.push(entry);
   }
@@ -3855,7 +4366,7 @@ async function deriveSubsystems(store, port, relativeOf, signal) {
 }
 async function enrichProjectConcepts(projectRoot, port, options = {}) {
   const { indexDir, ...rest } = options;
-  if (!existsSync5(path11.join(resolveIndexDir(projectRoot, indexDir), "index.db"))) {
+  if (!existsSync5(path12.join(resolveIndexDir(projectRoot, indexDir), "index.db"))) {
     return { indexed: false };
   }
   const store = indexStorePool.acquire(projectRoot, { indexDir });
@@ -3864,7 +4375,7 @@ async function enrichProjectConcepts(projectRoot, port, options = {}) {
       store,
       port,
       (file) => {
-        const relative12 = path11.relative(projectRoot, file);
+        const relative12 = path12.relative(projectRoot, file);
         const chosen = relative12 && !relative12.startsWith("..") ? relative12 : file;
         return posixIndexPath(chosen);
       },
@@ -3877,7 +4388,7 @@ async function enrichProjectConcepts(projectRoot, port, options = {}) {
 
 // src/codebase-index/embedding-pass.ts
 import { existsSync as existsSync6 } from "node:fs";
-import * as path12 from "node:path";
+import * as path13 from "node:path";
 var DEFAULT_BATCH_SIZE = 16;
 var MAX_EMBED_CHARS = 2e3;
 var FALLBACK_DECLARATIONS = 12;
@@ -3901,7 +4412,9 @@ async function embedFiles(store, port, relativeOf, options = {}) {
   const startedAt = Date.now();
   const errors = [];
   const signal = options.signal;
-  const batchSize = Math.max(1, Math.min(options.batchSize ?? DEFAULT_BATCH_SIZE, 128));
+  const requestedBatch = Number.isFinite(options.batchSize) ? Math.trunc(options.batchSize) : DEFAULT_BATCH_SIZE;
+  const batchSize = Math.max(1, Math.min(requestedBatch, 128));
+  const maxFiles = options.maxFiles !== void 0 && Number.isFinite(options.maxFiles) ? Math.max(0, Math.trunc(options.maxFiles)) : void 0;
   const providerChanged = store.reconcileVectorProvider(port.id);
   const pruned = store.pruneOrphanFileVectors();
   const stored = store.getFileVectorStates(port.id);
@@ -3913,6 +4426,7 @@ async function embedFiles(store, port, relativeOf, options = {}) {
   const queue = [];
   let cached = 0;
   for (const file of ordered) {
+    if (maxFiles !== void 0 && queue.length >= maxFiles) break;
     const declarations = summaries.has(file) ? [] : store.getFileSymbols(file, FALLBACK_DECLARATIONS).map((symbol) => symbol.name);
     const { text, fromDeclarations: fromDeclarations2 } = embedTextFor(
       relativeOf(file),
@@ -3926,7 +4440,6 @@ async function embedFiles(store, port, relativeOf, options = {}) {
       continue;
     }
     queue.push({ file, text, hash, fromDeclarations: fromDeclarations2 });
-    if (options.maxFiles !== void 0 && queue.length >= options.maxFiles) break;
   }
   let embedded = 0;
   let fromDeclarations = 0;
@@ -3937,15 +4450,24 @@ async function embedFiles(store, port, relativeOf, options = {}) {
     try {
       const vectors = await port.embed(batch.map((entry) => entry.text));
       const rows = [];
+      let rejected = 0;
       for (let i = 0; i < batch.length; i++) {
         const entry = batch[i];
         const vector = vectors[i];
-        if (vector === void 0 || vector.length !== port.dimensions) continue;
+        if (vector === void 0 || vector.length !== port.dimensions || !vector.every(Number.isFinite)) {
+          rejected++;
+          continue;
+        }
         rows.push({ file: entry.file, vector, sourceHash: entry.hash, provider: port.id });
         if (entry.fromDeclarations) fromDeclarations++;
       }
       store.upsertFileVectors(rows);
       embedded += rows.length;
+      if (rejected > 0 && errors.length < 20) {
+        errors.push(
+          `batch at ${start}: dropped ${rejected} vector(s) that were missing, the wrong width, or non-finite`
+        );
+      }
     } catch (error) {
       if (errors.length < 20) {
         errors.push(`batch at ${start}: ${error instanceof Error ? error.message : String(error)}`);
@@ -3967,7 +4489,7 @@ async function embedFiles(store, port, relativeOf, options = {}) {
 }
 async function embedProjectFiles(projectRoot, port, options = {}) {
   const { indexDir, ...rest } = options;
-  if (!existsSync6(path12.join(resolveIndexDir(projectRoot, indexDir), "index.db"))) {
+  if (!existsSync6(path13.join(resolveIndexDir(projectRoot, indexDir), "index.db"))) {
     return { indexed: false };
   }
   const store = indexStorePool.acquire(projectRoot, { indexDir });
@@ -3976,7 +4498,7 @@ async function embedProjectFiles(projectRoot, port, options = {}) {
       store,
       port,
       (file) => {
-        const relative12 = path12.relative(projectRoot, file);
+        const relative12 = path13.relative(projectRoot, file);
         return posixIndexPath(relative12 && !relative12.startsWith("..") ? relative12 : file);
       },
       rest
@@ -4040,4 +4562,4 @@ export {
   embedFiles,
   embedProjectFiles
 };
-//# sourceMappingURL=chunk-ENE22I5W.js.map
+//# sourceMappingURL=chunk-K37AKCTN.js.map