fix: restrict entry-role classification to function/method-kind symbols

.claude/hooks/update-graph.sh

@@ -24,23 +24,42 @@ if [ -z "$FILE_PATH" ]; then
   exit 0
 fi
 
-# Only rebuild for source files codegraph tracks
-# Skip docs, configs, test fixtures, and non-code files
-case "$FILE_PATH" in
-  *.js|*.ts|*.tsx|*.jsx|*.py|*.go|*.rs|*.java|*.cs|*.php|*.rb|*.tf|*.hcl)
-    ;;
-  *)
-    exit 0
-    ;;
-esac
+PROJECT_DIR=$(git rev-parse --show-toplevel 2>/dev/null) || PROJECT_DIR="${CLAUDE_PROJECT_DIR:-.}"
+
+# Only rebuild for source files codegraph tracks.
+# Skip docs, configs, test fixtures, and non-code files.
+#
+# The real allowlist is EXTENSIONS (src/shared/constants.ts), derived from
+# LANGUAGE_REGISTRY (src/domain/parser.ts) — the single source of truth for
+# every language codegraph parses. `npm run build` snapshots it to
+# dist/hook-extensions.txt (see scripts/gen-hook-extensions.mjs) so this
+# hook can do a fast native bash/grep check on every Edit/Write instead of
+# spawning a second Node process, or hand-copying the list, on every edit.
+#
+# The case statement below is only a fallback for before the first build
+# (no dist/hook-extensions.txt yet). tests/unit/hook-extensions.test.ts
+# fails if it ever drifts behind EXTENSIONS — keep it updated when
+# LANGUAGE_REGISTRY gains a new extension.
+EXT=".${FILE_PATH##*.}"
+GENERATED_EXT_LIST="$PROJECT_DIR/dist/hook-extensions.txt"
+if [ -f "$GENERATED_EXT_LIST" ]; then
+  grep -qxF "$EXT" "$GENERATED_EXT_LIST" || exit 0
+else
+  case "$EXT" in
+    .R|.bash|.c|.cc|.cjs|.clj|.cljc|.cljs|.cpp|.cs|.cu|.cuh|.cxx|.dart|.erl|.ex|.exs|.fs|.fsi|.fsx|.gemspec|.gleam|.go|.groovy|.gvy|.h|.hcl|.hpp|.hrl|.hs|.java|.jl|.js|.jsx|.kt|.kts|.lua|.m|.mjs|.ml|.mli|.php|.phtml|.py|.pyi|.r|.rake|.rb|.rs|.scala|.sh|.sol|.sv|.swift|.tf|.ts|.tsx|.v|.zig)
+      ;;
+    *)
+      exit 0
+      ;;
+  esac
+fi
 
 # Skip test fixtures — they're copied to tmp dirs anyway
 if echo "$FILE_PATH" | grep -qE '(fixtures|__fixtures__|testdata)/'; then
   exit 0
 fi
 
 # Guard: codegraph DB must exist (project has been built at least once)
-PROJECT_DIR=$(git rev-parse --show-toplevel 2>/dev/null) || PROJECT_DIR="${CLAUDE_PROJECT_DIR:-.}"
 DB_PATH="$PROJECT_DIR/.codegraph/graph.db"
 if [ ! -f "$DB_PATH" ]; then
   exit 0

.claude/skills/titan-gate/SKILL.md

@@ -45,6 +45,8 @@ codegraph check --staged --cycles --blast-radius 30 --boundaries -T --json
 
 This checks: manifesto rules, new cycle introduction, blast radius threshold, and architecture boundary violations. Exit code 0 = pass, 1 = fail.
 
+The `blast-radius` predicate is call-graph-shape-aware: a touched function's absolute transitive-caller count only counts toward the threshold if the diff actually changed that function's own declaration line or the set of call targets referenced in its body. A function whose body changed without touching a call expression or its own signature (e.g. an inline literal replaced by a named constant) is exempt even with a high absolute caller count — that fan-in is pre-existing risk already accepted by the codebase, not risk this diff introduced. This is the authoritative blast-radius pass/fail — see Step 8.
+
 Also run detailed impact analysis:
 
 ```bash
@@ -302,9 +304,9 @@ Advisory — prevents jumping ahead and creating conflicts.
 
 ## Step 8 — Blast radius check
 
-From diff-impact results:
-- Transitive blast radius > 30 → FAIL
-- Transitive blast radius > 15 → WARN
+The FAIL/PASS decision comes from Step 1's `codegraph check --staged --blast-radius 30` predicate — do not re-derive it from diff-impact's raw numbers, which are absolute transitive-caller counts and are NOT shape-aware:
+- Step 1's `blast-radius` predicate failed → FAIL (a touched function's own call graph shape genuinely changed and its transitive callers exceed 30)
+- Step 1's `blast-radius` predicate passed but a changed function's raw `transitiveCallers` (from diff-impact) > 15 → WARN (worth a second look even though not gating — this may include functions Step 1 exempted as pre-existing fan-in)
 - Historically coupled file NOT staged? → WARN ("consider also updating X")
 
 ---

.claude/skills/titan-grind/SKILL.md

@@ -109,8 +109,9 @@ Forge shapes the metal. Grind smooths the rough edges. Your goal: find helpers t
 
 12. **Capture dead-symbol baseline** (only if `grind.deadSymbolBaseline` is null):
     ```bash
-    codegraph roles --role dead -T --json | node -e "const d=[];process.stdin.on('data',c=>d.push(c));process.stdin.on('end',()=>{const items=JSON.parse(Buffer.concat(d));console.log(JSON.stringify({total:items.length,byRole:items.reduce((a,i)=>{a[i.role]=(a[i.role]||0)+1;return a},{})}));})"
+    codegraph roles --role dead -T --json | node -e "const d=[];process.stdin.on('data',c=>d.push(c));process.stdin.on('end',()=>{const data=JSON.parse(Buffer.concat(d));console.log(JSON.stringify({total:data.count,byRole:data.summary}));})"
     ```
+    `codegraph roles --json` returns `{ count, summary, symbols }` (not a bare array) — `summary` is already the per-role breakdown (e.g. `dead-leaf`, `dead-entry`, `dead-ffi`, `dead-unresolved`), so no manual reduce is needed.
     Store the total in `grind.deadSymbolBaseline`. Write `titan-state.json` immediately.
 
 13. **Drift detection.** Compare `titan-state.json → mainSHA` against current origin/main:
@@ -304,8 +305,8 @@ const tokens = helperName
   .slice(0, 3);
 const d=[];process.stdin.on('data',c=>d.push(c));
 process.stdin.on('end',()=>{ try {
-  const items=JSON.parse(Buffer.concat(d));
-  const candidates = items.filter(i =>
+  const data=JSON.parse(Buffer.concat(d));
+  const candidates = (data.symbols || []).filter(i =>
     i.name !== helperName &&
     tokens.some(t => i.name.toLowerCase().includes(t))
   );
@@ -579,7 +580,7 @@ After all targets in the phase are processed:
 
 ```bash
 codegraph build
-codegraph roles --role dead -T --json | node -e "const d=[];process.stdin.on('data',c=>d.push(c));process.stdin.on('end',()=>{const items=JSON.parse(Buffer.concat(d));console.log(JSON.stringify({total:items.length,byRole:items.reduce((a,i)=>{a[i.role]=(a[i.role]||0)+1;return a},{})}));})"
+codegraph roles --role dead -T --json | node -e "const d=[];process.stdin.on('data',c=>d.push(c));process.stdin.on('end',()=>{const data=JSON.parse(Buffer.concat(d));console.log(JSON.stringify({total:data.count,byRole:data.summary}));})"
 ```
 
 Store in `grind.deadSymbolCurrent`. Write `titan-state.json`.

.gitignore

@@ -14,6 +14,7 @@ crates/codegraph-core/*.node
 .claude/worktrees/
 generated/DEPENDENCIES.md
 generated/DEPENDENCIES.json
+token-benchmark.partial.json
 artifacts/
 pkg/
 target/

CLAUDE.md

@@ -74,6 +74,7 @@ npm run test:coverage            # Coverage report
 npx vitest run tests/parsers/javascript.test.ts   # Single test file
 npx vitest run -t "finds cycles"                  # Single test by name
 npm run build:wasm               # Rebuild WASM grammars from devDeps (built automatically on npm install)
+npm run doctor                   # Check this worktree for a stale native binary / missing WASM grammars (runs automatically via pretest)
 ```
 
 **Linter/Formatter:** [Biome](https://biomejs.dev/) — config in `biome.json`, scoped to `src/` and `tests/`.
@@ -103,6 +104,7 @@ Source is TypeScript in `src/`, compiled via `tsup`. The Rust native engine live
 | `shared/paginate.ts` | Pagination helpers for bounded query results |
 | **`infrastructure/`** | **Platform and I/O plumbing** |
 | `infrastructure/config.ts` | `.codegraphrc.json` loading, env overrides, `apiKeyCommand` secret resolution |
+| `infrastructure/doctor.ts` | Environment health checks — stale `better-sqlite3` native ABI, incomplete `grammars/`; see `npm run doctor` |
 | `infrastructure/logger.ts` | Structured logging (`warn`, `debug`, `info`, `error`) |
 | `infrastructure/native.ts` | Native napi-rs addon loader with WASM fallback |
 | `infrastructure/registry.ts` | Global repo registry (`~/.codegraph/registry.json`) for multi-repo MCP |

CONTRIBUTING.md

@@ -17,6 +17,16 @@ npm test                         # run the full test suite
 
 **Requirements:** Node.js >= 20
 
+**Working in multiple git worktrees?** Each worktree gets its own untracked
+`node_modules/` and `grammars/` — neither is shared via git — so every fresh
+`git worktree add` needs its own `npm install`. A worktree set up before a
+host Node upgrade, or where `npm install` was interrupted, can be left with a
+`better-sqlite3` binary compiled for the wrong Node ABI or an incomplete
+`grammars/` directory; both fail in confusing ways deep inside a build or test
+run. Run `npm run doctor` to check (or `npm run doctor -- --fix` to repair
+in place, scoped to the current worktree) — it also runs automatically before
+`npm test` via `pretest`.
+
 ## Contributor License Agreement (CLA)
 
 All contributors must sign the [Contributor License Agreement](CLA.md) before
@@ -88,6 +98,7 @@ npm run test:coverage            # Coverage report
 npx vitest run tests/parsers/go.test.js   # Single test file
 npx vitest run -t "finds cycles"          # Single test by name
 npm run build:wasm               # Rebuild WASM grammars
+npm run doctor                   # Check for a stale native binary / missing WASM grammars
 ```
 
 ## Branch Naming Convention

crates/codegraph-core/src/db/connection.rs

@@ -857,6 +857,14 @@ impl NativeDatabase {
     /// Batches are received as `serde_json::Value` and deserialized via serde so
     /// that `null` visibility values map to `None` instead of crashing napi's
     /// `Option<String>` object conversion (#709).
+    ///
+    /// `file_hashes` is committed in its own transaction, separate from node
+    /// insertion (#1731) — callers that need edge-consistent hashes (i.e. the
+    /// standard incremental build pipeline) should pass an empty array here
+    /// and commit hashes themselves once resolveImports/buildEdges have
+    /// finished rebuilding the affected files' edges (see
+    /// `insertNodes.commitFileHashes` on the JS side, or
+    /// `insert_nodes::commit_file_hashes` for the all-Rust orchestrator).
     #[napi(ts_args_type = "batches: Array<{ file: string; definitions: Array<{ name: string; kind: string; line: number; endLine?: number; visibility?: string; children: Array<{ name: string; kind: string; line: number; endLine?: number; visibility?: string }> }>; exports: Array<{ name: string; kind: string; line: number }> }>, fileHashes: FileHashEntry[], removedFiles: string[]")]
     pub fn bulk_insert_nodes(
         &self,
@@ -869,9 +877,13 @@ impl NativeDatabase {
                 napi::Error::from_reason(format!("bulk_insert_nodes: invalid batches: {e}"))
             })?;
         let conn = self.conn()?;
-        Ok(insert_nodes::do_insert_nodes(conn, &batches, &file_hashes, &removed_files)
+        let insert_ok = insert_nodes::do_insert_nodes(conn, &batches, &removed_files)
             .inspect_err(|e| eprintln!("[NativeDatabase] bulk_insert_nodes failed: {e}"))
-            .is_ok())
+            .is_ok();
+        let hashes_ok = insert_nodes::commit_file_hashes(conn, &file_hashes)
+            .inspect_err(|e| eprintln!("[NativeDatabase] bulk_insert_nodes hash commit failed: {e}"))
+            .is_ok();
+        Ok(insert_ok && hashes_ok)
     }
 
     /// Bulk-insert edge rows using chunked multi-value INSERT statements.

crates/codegraph-core/src/db/repository/graph_read.rs

@@ -28,6 +28,41 @@ fn escape_like(s: &str) -> String {
     out
 }
 
+/// Append an `AND (col LIKE ? [OR col LIKE ? ...])` fragment for a multi-value
+/// file filter and push the corresponding escaped LIKE params. Mirrors
+/// `buildFileConditionSQL()` / `NodeQuery.fileFilter()` in
+/// `src/db/query-builder.ts`, which is why callers must accept `Vec<String>`
+/// (repeatable `-f/--file`) rather than a single `String`. No-op when `files`
+/// is empty. Advances `*idx` past the placeholders it consumes.
+fn push_file_filter(
+    sql: &mut String,
+    params_v: &mut Vec<Box<dyn rusqlite::types::ToSql>>,
+    idx: &mut usize,
+    column: &str,
+    files: &[String],
+) {
+    if files.is_empty() {
+        return;
+    }
+    let start = *idx;
+    if files.len() == 1 {
+        sql.push_str(&format!(" AND {column} LIKE ?{start} ESCAPE '\\'"));
+        params_v.push(Box::new(format!("%{}%", escape_like(&files[0]))));
+        *idx += 1;
+        return;
+    }
+    let clauses: Vec<String> = files
+        .iter()
+        .enumerate()
+        .map(|(i, _)| format!("{column} LIKE ?{} ESCAPE '\\'", start + i))
+        .collect();
+    sql.push_str(&format!(" AND ({})", clauses.join(" OR ")));
+    for f in files {
+        params_v.push(Box::new(format!("%{}%", escape_like(f))));
+    }
+    *idx += files.len();
+}
+
 /// Check if a file path looks like a test file (mirrors `isTestFile` in JS).
 fn is_test_file(file: &str) -> bool {
     file.contains(".test.")
@@ -143,7 +178,7 @@ struct FnDepsCallerWithId {
 fn build_fn_deps_match_query(
     name: &str,
     kind: Option<&str>,
-    file: Option<&str>,
+    file: Option<&[String]>,
 ) -> (String, Vec<Box<dyn rusqlite::types::ToSql>>) {
     let default_kinds: Vec<String> = vec![
         "function".to_string(),
@@ -180,8 +215,7 @@ fn build_fn_deps_match_query(
         idx += kinds.len();
     }
     if let Some(f) = file {
-        sql.push_str(&format!(" AND n.file LIKE ?{idx} ESCAPE '\\'"));
-        params_v.push(Box::new(format!("%{}%", escape_like(f))));
+        push_file_filter(&mut sql, &mut params_v, &mut idx, "n.file", f);
     }
 
     (sql, params_v)
@@ -1086,7 +1120,7 @@ impl NativeDatabase {
         &self,
         name_pattern: String,
         kinds: Option<Vec<String>>,
-        file: Option<String>,
+        file: Option<Vec<String>>,
     ) -> napi::Result<Vec<NativeNodeRowWithFanIn>> {
         let conn = self.conn()?;
 
@@ -1112,8 +1146,7 @@ impl NativeDatabase {
             }
         }
         if let Some(ref f) = file {
-            sql.push_str(&format!(" AND n.file LIKE ?{idx} ESCAPE '\\'"));
-            param_values.push(Box::new(format!("%{}%", escape_like(f))));
+            push_file_filter(&mut sql, &mut param_values, &mut idx, "n.file", f);
         }
 
         let mut stmt = conn
@@ -1642,8 +1675,15 @@ impl NativeDatabase {
             .map(|k| format!("'{k}'"))
             .collect::<Vec<_>>()
             .join(",");
+        // ORDER BY id: without an explicit order, SQLite's row order for a
+        // bare WHERE scan is unspecified — it happened to track physical/
+        // insertion order, which is only deterministic now that the build
+        // pipeline inserts nodes in a fixed (BTreeMap-sorted) order (#1734).
+        // Sorting explicitly here removes the dependency on that unspecified
+        // behavior so downstream consumers (e.g. community detection) build
+        // the same graph on every run regardless of how rows are stored.
         let sql = format!(
-            "SELECT id, name, kind, file FROM nodes WHERE kind IN ({kinds_sql})"
+            "SELECT id, name, kind, file FROM nodes WHERE kind IN ({kinds_sql}) ORDER BY id"
         );
         let mut stmt = conn
             .prepare_cached(&sql)
@@ -1668,7 +1708,8 @@ impl NativeDatabase {
         let conn = self.conn()?;
         let mut stmt = conn
             .prepare_cached(
-                "SELECT source_id, target_id, confidence FROM edges WHERE kind = 'calls'",
+                "SELECT source_id, target_id, confidence FROM edges WHERE kind = 'calls' \
+                 ORDER BY source_id, target_id",
             )
             .map_err(|e| napi::Error::from_reason(format!("get_call_edges prepare: {e}")))?;
         let rows = stmt
@@ -1688,8 +1729,10 @@ impl NativeDatabase {
     #[napi]
     pub fn get_file_nodes_all(&self) -> napi::Result<Vec<NativeFileNodeRow>> {
         let conn = self.conn()?;
+        // ORDER BY id — see the comment in get_callable_nodes for why an
+        // explicit order matters for build-to-build determinism (#1734).
         let mut stmt = conn
-            .prepare_cached("SELECT id, name, file FROM nodes WHERE kind = 'file'")
+            .prepare_cached("SELECT id, name, file FROM nodes WHERE kind = 'file' ORDER BY id")
             .map_err(|e| napi::Error::from_reason(format!("get_file_nodes_all prepare: {e}")))?;
         let rows = stmt
             .query_map([], |row| {
@@ -1710,7 +1753,8 @@ impl NativeDatabase {
         let conn = self.conn()?;
         let mut stmt = conn
             .prepare_cached(
-                "SELECT source_id, target_id FROM edges WHERE kind IN ('imports','imports-type')",
+                "SELECT source_id, target_id FROM edges WHERE kind IN ('imports','imports-type') \
+                 ORDER BY source_id, target_id",
             )
             .map_err(|e| napi::Error::from_reason(format!("get_import_edges prepare: {e}")))?;
         let rows = stmt
@@ -2114,7 +2158,7 @@ impl NativeDatabase {
         name: String,
         depth: Option<i32>,
         no_tests: Option<bool>,
-        file: Option<String>,
+        file: Option<Vec<String>>,
         kind: Option<String>,
     ) -> napi::Result<FnDepsResult> {
         let conn = self.conn()?;