grepmax 0.17.2 → 0.17.3

package/README.md

@@ -64,6 +64,7 @@ gmax log src/lib/auth.ts                 # Git commit history for a path or symb
 gmax test handleAuth                     # Find tests via reverse call graph
 gmax impact handleAuth                   # Dependents + affected tests
 gmax similar handleAuth                  # Find similar code patterns
+gmax dead handleAuth                     # Unused-symbol check via call graph (DEAD / PUBLIC EXPORT / LIVE)
 gmax context "auth system" --budget 4000 # Token-budgeted topic summary
 ```
 
@@ -121,6 +122,7 @@ Plugins auto-update when you run `npm install -g grepmax@latest` — no need to
 | `trace_calls` | Call graph: importers, callers (multi-hop), callees with file:line. |
 | `extract_symbol` | Complete function/class body by symbol name. |
 | `peek_symbol` | Compact overview: signature + callers + callees. |
+| `dead` | Unused-symbol check via call graph. Returns `DEAD`, `PUBLIC EXPORT`, or `LIVE` with caller count. |
 | `list_symbols` | Indexed symbols with role and export status. |
 | `index_status` | Index health: chunks, files, projects, watcher status. |
 | `summarize_project` | Project overview: languages, structure, key symbols, entry points. |
@@ -277,6 +279,7 @@ fixtures/
 | `GMAX_WORKER_THREADS` | Worker threads for embedding | 50% of cores |
 | `GMAX_DEBUG` | Debug logging | Off |
 | `GMAX_SUMMARIZER` | Enable summarizer auto-start (`1`) | Off |
+| `GMAX_RERANK` | Enable ColBERT rerank (`1`) — off by default since v0.17.1 ([why](docs/known-limitations.md)) | Off |
 
 ## Troubleshooting
 
@@ -293,6 +296,20 @@ gmax watch stop && gmax watch --daemon -b  # Restart daemon
 
 See [CLAUDE.md](CLAUDE.md) for development setup, commands, and architecture details.
 
+### Benchmarks
+
+Two evaluation harnesses live in the repo. Both emit stable JSON via `:json` variants.
+
+```bash
+pnpm bench:recall          # 97-case internal eval against gmax's own repo
+pnpm bench:recall:json
+pnpm bench:oss             # P1 definition-lookup across express, lodash, platform (sverklo-bench fixtures)
+pnpm bench:oss:json
+GMAX_EVAL_RERANK=1 pnpm bench:oss   # toggle ColBERT rerank
+```
+
+The OSS bench requires the fixture repos to be indexed first — see [`docs/known-limitations.md`](docs/known-limitations.md) for the most recent rerank-on-vs-off comparison across 4 datasets / 131 cases.
+
 ## Attribution
 
 grepmax is built upon the foundation of [mgrep](https://github.com/mixedbread-ai/mgrep) by MixedBread. See the [NOTICE](NOTICE) file for details.

package/dist/eval-graph-sanity.js

@@ -0,0 +1,225 @@
+"use strict";
+/**
+ * Phase 0 sanity check for Bundle B G1' (graph-as-recall-recovery).
+ *
+ * For each platform hard-miss case (BeyondError, ErrorCodes, resolveActor,
+ * errorHandler), mirror the searcher's dense+FTS+RRF pipeline to produce
+ * the post-fusion top-200 candidate pool, then count how many of those
+ * 200 chunks have `referenced_symbols` containing the target symbol.
+ *
+ * ≥1 hit per case = 1-hop outbound graph walk can recover the target
+ * (the seed chunk's defined symbol points at the target via the call
+ * graph) → worth building the recovery layer.
+ *
+ * 0 hits across all 4 = the signal isn't in the graph at this seed
+ * depth → stop and report the negative result.
+ *
+ * Run: `npx tsx src/eval-graph-sanity.ts`
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var _a, _b;
+var _c;
+Object.defineProperty(exports, "__esModule", { value: true });
+(_a = (_c = process.env).GMAX_WORKER_COUNT) !== null && _a !== void 0 ? _a : (_c.GMAX_WORKER_COUNT = "1");
+const path = __importStar(require("node:path"));
+const config_1 = require("./config");
+const vector_db_1 = require("./lib/store/vector-db");
+const exit_1 = require("./lib/utils/exit");
+const pool_1 = require("./lib/workers/pool");
+const filter_builder_1 = require("./lib/utils/filter-builder");
+const PLATFORM_ROOT = path.join((_b = process.env.HOME) !== null && _b !== void 0 ? _b : "", "Development/beyond/platform");
+const HARD_MISS_TARGETS = [
+    "BeyondError",
+    "ErrorCodes",
+    "resolveActor",
+    "errorHandler",
+];
+const PRE_K = 500;
+const STAGE1_K = 200;
+const RRF_K = 60;
+function toStringArray(val) {
+    if (!val)
+        return [];
+    if (Array.isArray(val)) {
+        return val.filter((v) => typeof v === "string");
+    }
+    const maybe = val;
+    if (typeof maybe.toArray === "function") {
+        try {
+            const arr = maybe.toArray();
+            return Array.isArray(arr)
+                ? arr.filter((v) => typeof v === "string")
+                : [];
+        }
+        catch (_a) {
+            return [];
+        }
+    }
+    return [];
+}
+function probe(target) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const db = new vector_db_1.VectorDB(config_1.PATHS.lancedbDir);
+        const table = yield db.ensureTable();
+        const pool = (0, pool_1.getWorkerPool)();
+        const { dense } = yield pool.encodeQuery(target);
+        const pathPrefix = PLATFORM_ROOT.endsWith("/") ? PLATFORM_ROOT : `${PLATFORM_ROOT}/`;
+        const where = `path LIKE '${(0, filter_builder_1.escapeSqlString)(pathPrefix)}%'`;
+        const columns = [
+            "id",
+            "path",
+            "chunk_index",
+            "start_line",
+            "end_line",
+            "defined_symbols",
+            "referenced_symbols",
+        ];
+        const vectorRows = (yield table
+            .vectorSearch(dense)
+            .select([...columns, "_distance"])
+            .where(where)
+            .limit(PRE_K)
+            .toArray());
+        let ftsRows = [];
+        try {
+            ftsRows = (yield table
+                .search(target)
+                .select([...columns, "_score"])
+                .where(where)
+                .limit(PRE_K)
+                .toArray());
+        }
+        catch (e) {
+            console.warn(`[sanity] FTS unavailable for "${target}": ${e.message}`);
+        }
+        const candidateScores = new Map();
+        const docMap = new Map();
+        vectorRows.forEach((doc, rank) => {
+            const key = doc.id ||
+                `${doc.path}:${doc.chunk_index}`;
+            docMap.set(key, doc);
+            candidateScores.set(key, (candidateScores.get(key) || 0) + 1.0 / (RRF_K + rank + 1));
+        });
+        ftsRows.forEach((doc, rank) => {
+            const key = doc.id ||
+                `${doc.path}:${doc.chunk_index}`;
+            if (!docMap.has(key))
+                docMap.set(key, doc);
+            candidateScores.set(key, (candidateScores.get(key) || 0) + 1.0 / (RRF_K + rank + 1));
+        });
+        const fused = Array.from(candidateScores.entries())
+            .sort((a, b) => b[1] - a[1])
+            .slice(0, STAGE1_K)
+            .map(([key]) => docMap.get(key))
+            .filter(Boolean);
+        let withRef = 0;
+        let withDef = 0;
+        let rankOfFirstRef = -1;
+        let rankOfFirstDef = -1;
+        const sampleRefHits = [];
+        fused.forEach((doc, i) => {
+            const refs = toStringArray(doc.referenced_symbols);
+            const defs = toStringArray(doc.defined_symbols);
+            if (refs.includes(target)) {
+                withRef++;
+                if (rankOfFirstRef < 0)
+                    rankOfFirstRef = i + 1;
+                if (sampleRefHits.length < 3) {
+                    sampleRefHits.push({ rank: i + 1, path: String(doc.path) });
+                }
+            }
+            if (defs.includes(target)) {
+                withDef++;
+                if (rankOfFirstDef < 0)
+                    rankOfFirstDef = i + 1;
+            }
+        });
+        yield db.close();
+        return {
+            target,
+            poolSize: fused.length,
+            vectorRows: vectorRows.length,
+            ftsRows: ftsRows.length,
+            withRef,
+            withDef,
+            rankOfFirstRef,
+            rankOfFirstDef,
+            sampleRefHits,
+        };
+    });
+}
+function main() {
+    return __awaiter(this, void 0, void 0, function* () {
+        console.log(`Phase 0 sanity check — graph reachability on platform hard-miss cases`);
+        console.log(`pathPrefix: ${PLATFORM_ROOT}`);
+        console.log(`STAGE1_K=${STAGE1_K}, PRE_K=${PRE_K}\n`);
+        let anyReachable = false;
+        const summary = [];
+        for (const target of HARD_MISS_TARGETS) {
+            const res = yield probe(target);
+            summary.push(res);
+            const refOK = res.withRef > 0 ? "✓" : "✗";
+            const defOK = res.withDef > 0 ? "✓" : "✗";
+            console.log(`${refOK} ${target.padEnd(16)} pool=${String(res.poolSize).padStart(3)}  ` +
+                `refs=${String(res.withRef).padStart(3)}/200  defs=${defOK} (${res.withDef})  ` +
+                `1st-ref@${res.rankOfFirstRef > 0 ? res.rankOfFirstRef : "—"}  ` +
+                `1st-def@${res.rankOfFirstDef > 0 ? res.rankOfFirstDef : "—"}`);
+            for (const s of res.sampleRefHits) {
+                console.log(`    ↳ rank ${s.rank}: ${s.path}`);
+            }
+            if (res.withRef > 0)
+                anyReachable = true;
+        }
+        console.log(`\nVerdict: ${anyReachable ? "BUILD (≥1 case has graph signal in top-200)" : "ABORT (graph is empty at this depth — pick a different mechanism)"}`);
+        console.log(`\nJSON:`);
+        console.log(JSON.stringify(summary, null, 2));
+        yield (0, exit_1.gracefulExit)(0);
+    });
+}
+if (require.main === module) {
+    main().catch((e) => {
+        console.error(e);
+        process.exit(1);
+    });
+}

package/dist/eval-graph-spotcheck.js

@@ -0,0 +1,83 @@
+"use strict";
+/**
+ * Pulls the chunks for a known BeyondError-using file out of the index
+ * and prints their `referenced_symbols` arrays. Lets us see what the
+ * chunker actually extracts vs what's missing — whether BeyondError is
+ * absent due to chunker scope (e.g., only same-function refs are tagged)
+ * or whether the tagging is just sparse.
+ */
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var _a;
+var _b;
+Object.defineProperty(exports, "__esModule", { value: true });
+(_a = (_b = process.env).GMAX_WORKER_COUNT) !== null && _a !== void 0 ? _a : (_b.GMAX_WORKER_COUNT = "1");
+const config_1 = require("./config");
+const vector_db_1 = require("./lib/store/vector-db");
+const exit_1 = require("./lib/utils/exit");
+const filter_builder_1 = require("./lib/utils/filter-builder");
+const CANDIDATES = [
+    "/Users/reoiv/Development/beyond/platform/packages/api/src/middleware/error.ts",
+    "/Users/reoiv/Development/beyond/platform/packages/api/src/graphql/shared/error-mapping.ts",
+    "/Users/reoiv/Development/beyond/platform/packages/api/src/lib/service-errors.ts",
+];
+function toStrArr(v) {
+    if (!v)
+        return [];
+    if (Array.isArray(v))
+        return v.filter((x) => typeof x === "string");
+    const m = v;
+    if (typeof m.toArray === "function") {
+        try {
+            const a = m.toArray();
+            return Array.isArray(a) ? a.filter((x) => typeof x === "string") : [];
+        }
+        catch (_a) {
+            return [];
+        }
+    }
+    return [];
+}
+function main() {
+    return __awaiter(this, void 0, void 0, function* () {
+        const db = new vector_db_1.VectorDB(config_1.PATHS.lancedbDir);
+        const table = yield db.ensureTable();
+        for (const file of CANDIDATES) {
+            console.log(`\n── ${file}`);
+            const rows = (yield table
+                .query()
+                .select(["start_line", "end_line", "chunk_type", "defined_symbols", "referenced_symbols"])
+                .where(`path = '${(0, filter_builder_1.escapeSqlString)(file)}'`)
+                .limit(20)
+                .toArray());
+            if (rows.length === 0) {
+                console.log("  (no chunks indexed for this path)");
+                continue;
+            }
+            for (const r of rows) {
+                const defs = toStrArr(r.defined_symbols);
+                const refs = toStrArr(r.referenced_symbols);
+                const hasBE = refs.includes("BeyondError");
+                console.log(`  lines ${r.start_line}-${r.end_line} (${r.chunk_type})  ` +
+                    `defs=[${defs.slice(0, 4).join(",")}${defs.length > 4 ? "…" : ""}]  ` +
+                    `refs(${refs.length})=[${refs.slice(0, 8).join(",")}${refs.length > 8 ? "…" : ""}]  ` +
+                    `BeyondError-ref=${hasBE ? "✓" : "✗"}`);
+            }
+        }
+        yield db.close();
+        yield (0, exit_1.gracefulExit)(0);
+    });
+}
+if (require.main === module) {
+    main().catch((e) => {
+        console.error(e);
+        process.exit(1);
+    });
+}

package/dist/eval-graph-totals.js

@@ -0,0 +1,131 @@
+"use strict";
+/**
+ * Diagnostic counterpart to eval-graph-sanity.ts.
+ *
+ * Phase 0 found that 0/200 fusion-pool chunks reference any of the 4
+ * hard-miss targets via `referenced_symbols`. That can mean either:
+ *   (a) chunker isn't extracting these refs (upstream miss), OR
+ *   (b) refs exist but live outside the fusion top-200.
+ *
+ * This script measures the *total* `array_contains(referenced_symbols, X)`
+ * count across the whole platform index for each target. If those counts
+ * are also ~0, the graph is empty at the data-extraction layer, not the
+ * retrieval layer.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var _a, _b;
+var _c;
+Object.defineProperty(exports, "__esModule", { value: true });
+(_a = (_c = process.env).GMAX_WORKER_COUNT) !== null && _a !== void 0 ? _a : (_c.GMAX_WORKER_COUNT = "1");
+const path = __importStar(require("node:path"));
+const config_1 = require("./config");
+const vector_db_1 = require("./lib/store/vector-db");
+const exit_1 = require("./lib/utils/exit");
+const filter_builder_1 = require("./lib/utils/filter-builder");
+const PLATFORM_ROOT = path.join((_b = process.env.HOME) !== null && _b !== void 0 ? _b : "", "Development/beyond/platform");
+const TARGETS = ["BeyondError", "ErrorCodes", "resolveActor", "errorHandler"];
+function main() {
+    return __awaiter(this, void 0, void 0, function* () {
+        const db = new vector_db_1.VectorDB(config_1.PATHS.lancedbDir);
+        const table = yield db.ensureTable();
+        const pathPrefix = PLATFORM_ROOT.endsWith("/") ? PLATFORM_ROOT : `${PLATFORM_ROOT}/`;
+        const scope = `path LIKE '${(0, filter_builder_1.escapeSqlString)(pathPrefix)}%'`;
+        console.log(`Platform graph density check — pathPrefix=${PLATFORM_ROOT}\n`);
+        for (const sym of TARGETS) {
+            const esc = (0, filter_builder_1.escapeSqlString)(sym);
+            const refRows = yield table
+                .query()
+                .select(["path"])
+                .where(`${scope} AND array_contains(referenced_symbols, '${esc}')`)
+                .limit(2000)
+                .toArray();
+            const defRows = yield table
+                .query()
+                .select(["path"])
+                .where(`${scope} AND array_contains(defined_symbols, '${esc}')`)
+                .limit(2000)
+                .toArray();
+            console.log(`${sym.padEnd(16)}  def-chunks=${String(defRows.length).padStart(3)}  ref-chunks=${String(refRows.length).padStart(4)}`);
+        }
+        // Also count chunks with non-empty referenced_symbols overall to baseline
+        // graph density.
+        const allRows = yield table
+            .query()
+            .select(["referenced_symbols"])
+            .where(scope)
+            .limit(20000)
+            .toArray();
+        let nonEmpty = 0;
+        let totalRefs = 0;
+        for (const row of allRows) {
+            const raw = row.referenced_symbols;
+            let arr = [];
+            if (Array.isArray(raw))
+                arr = raw.filter((v) => typeof v === "string");
+            else if (raw && typeof raw.toArray === "function") {
+                try {
+                    const a = raw.toArray();
+                    if (Array.isArray(a))
+                        arr = a.filter((v) => typeof v === "string");
+                }
+                catch (_a) { }
+            }
+            if (arr.length > 0) {
+                nonEmpty++;
+                totalRefs += arr.length;
+            }
+        }
+        console.log(`\nPlatform corpus: ${allRows.length} chunks sampled (cap 20k), ` +
+            `${nonEmpty} with non-empty referenced_symbols (${((nonEmpty / allRows.length) * 100).toFixed(1)}%), ` +
+            `avg refs/chunk = ${(totalRefs / Math.max(1, nonEmpty)).toFixed(1)}`);
+        yield db.close();
+        yield (0, exit_1.gracefulExit)(0);
+    });
+}
+if (require.main === module) {
+    main().catch((e) => {
+        console.error(e);
+        process.exit(1);
+    });
+}

package/dist/eval-oss.js

@@ -0,0 +1,244 @@
+"use strict";
+/**
+ * OSS-fixture evaluation harness — runs the search pipeline against
+ * sverklo-bench P1 (definition lookup) fixtures ported from
+ * github.com/sverklo/sverklo-bench (tasks/express.gen.ts,
+ * tasks/lodash.gen.ts). Used to answer "does ColBERT rerank help on a
+ * third-party fixture set, or are our 97 internal cases biased?"
+ *
+ * Usage:
+ *   pnpm tsx src/eval-oss.ts express                  # rerank off (default)
+ *   GMAX_EVAL_RERANK=1 pnpm tsx src/eval-oss.ts express
+ *   pnpm tsx src/eval-oss.ts lodash --json
+ *   pnpm tsx src/eval-oss.ts all                      # all datasets
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var _a, _b, _c, _d;
+var _e;
+Object.defineProperty(exports, "__esModule", { value: true });
+// Same precaution as src/eval.ts — pin worker pool to 1 to avoid ONNX
+// concurrency issues during the back-to-back search runs.
+(_a = (_e = process.env).GMAX_WORKER_COUNT) !== null && _a !== void 0 ? _a : (_e.GMAX_WORKER_COUNT = "1");
+const path = __importStar(require("node:path"));
+const searcher_1 = require("./lib/search/searcher");
+const vector_db_1 = require("./lib/store/vector-db");
+const exit_1 = require("./lib/utils/exit");
+const config_1 = require("./config");
+// ─── express 4.21.1 P1 — sverklo-bench/tasks/express.gen.ts resolved against
+//     a fresh checkout. `merge` dropped: it's the utils-merge package, not
+//     an in-tree definition, so the sverklo resolver returns no location.
+const EXPRESS_CASES = [
+    { id: "ex-p1-01", query: "createApplication", expectedFile: "lib/express.js", expectedLine: 37 },
+    { id: "ex-p1-02", query: "Route", expectedFile: "lib/router/route.js", expectedLine: 43 },
+    { id: "ex-p1-03", query: "Layer", expectedFile: "lib/router/layer.js", expectedLine: 33 },
+    { id: "ex-p1-04", query: "View", expectedFile: "lib/view.js", expectedLine: 52 },
+    { id: "ex-p1-05", query: "query", expectedFile: "lib/express.js", expectedLine: 79, note: "re-export site — middleware/query.js doesn't match the function-decl patterns" },
+    { id: "ex-p1-06", query: "init", expectedFile: "lib/middleware/init.js", expectedLine: 28 },
+    { id: "ex-p1-07", query: "acceptParams", expectedFile: "lib/utils.js", expectedLine: 126 },
+    { id: "ex-p1-08", query: "stringify", expectedFile: "lib/response.js", expectedLine: 1155 },
+    { id: "ex-p1-09", query: "compileETag", expectedFile: "lib/utils.js", expectedLine: 150 },
+];
+// ─── lodash 4.17.21 P1 — hand-verified line numbers in lodash.js, copied
+//     verbatim from sverklo-bench/tasks/lodash.gen.ts. All 10 live in the
+//     same 17K-line UMD file, so line-window matching (NOT path-only match)
+//     is what makes this fixture set discriminating.
+const LODASH_CASES = [
+    { id: "ld-p1-01", query: "map", expectedFile: "lodash.js", expectedLine: 9620 },
+    { id: "ld-p1-02", query: "filter", expectedFile: "lodash.js", expectedLine: 9239 },
+    { id: "ld-p1-03", query: "reduce", expectedFile: "lodash.js", expectedLine: 9745 },
+    { id: "ld-p1-04", query: "debounce", expectedFile: "lodash.js", expectedLine: 10372 },
+    { id: "ld-p1-05", query: "throttle", expectedFile: "lodash.js", expectedLine: 10965 },
+    { id: "ld-p1-06", query: "merge", expectedFile: "lodash.js", expectedLine: 13505, note: "var merge = createAssigner(...) binding site, not the re-export at 16689" },
+    { id: "ld-p1-07", query: "cloneDeep", expectedFile: "lodash.js", expectedLine: 11155 },
+    { id: "ld-p1-08", query: "get", expectedFile: "lodash.js", expectedLine: 13194 },
+    { id: "ld-p1-09", query: "set", expectedFile: "lodash.js", expectedLine: 13741 },
+    { id: "ld-p1-10", query: "chunk", expectedFile: "lodash.js", expectedLine: 6903 },
+];
+// ─── platform monorepo (private) — 15 hand-curated P1 cases across packages
+//     to test the "modular monorepo" shape that neither express nor lodash
+//     covers. Symbols resolved against the live checkout. Bare-symbol
+//     queries match sverklo's P1 methodology so results are comparable.
+const PLATFORM_CASES = [
+    { id: "pf-p1-01", query: "formatCents", expectedFile: "packages/shared/src/format.ts", expectedLine: 8 },
+    { id: "pf-p1-02", query: "formatTimeAgo", expectedFile: "packages/shared/src/format.ts", expectedLine: 44 },
+    { id: "pf-p1-03", query: "BeyondError", expectedFile: "packages/shared/src/errors.ts", expectedLine: 37 },
+    { id: "pf-p1-04", query: "ErrorCodes", expectedFile: "packages/shared/src/errors.ts", expectedLine: 5 },
+    { id: "pf-p1-05", query: "createDb", expectedFile: "packages/db/src/index.ts", expectedLine: 42 },
+    { id: "pf-p1-06", query: "createDbAsync", expectedFile: "packages/db/src/index.ts", expectedLine: 50 },
+    { id: "pf-p1-07", query: "authMiddleware", expectedFile: "packages/api/src/middleware/auth.ts", expectedLine: 39 },
+    { id: "pf-p1-08", query: "requireAuth", expectedFile: "packages/api/src/middleware/auth.ts", expectedLine: 45 },
+    { id: "pf-p1-09", query: "resolveActor", expectedFile: "packages/api/src/middleware/auth.ts", expectedLine: 71 },
+    { id: "pf-p1-10", query: "getActor", expectedFile: "packages/api/src/middleware/auth.ts", expectedLine: 1136 },
+    { id: "pf-p1-11", query: "rateLimit", expectedFile: "packages/api/src/middleware/rate-limit.ts", expectedLine: 94 },
+    { id: "pf-p1-12", query: "checkRateLimitKey", expectedFile: "packages/api/src/middleware/rate-limit.ts", expectedLine: 158 },
+    { id: "pf-p1-13", query: "errorHandler", expectedFile: "packages/api/src/middleware/error.ts", expectedLine: 128 },
+    { id: "pf-p1-14", query: "activityTracker", expectedFile: "packages/api/src/middleware/activity-tracker.ts", expectedLine: 17 },
+    { id: "pf-p1-15", query: "initializeApp", expectedFile: "packages/api/src/app.ts", expectedLine: 68 },
+];
+const DATASETS = {
+    express: {
+        name: "express",
+        projectRoot: path.join((_b = process.env.HOME) !== null && _b !== void 0 ? _b : "", "Development/sandbox/bench-fixtures/express"),
+        cases: EXPRESS_CASES,
+    },
+    lodash: {
+        name: "lodash",
+        projectRoot: path.join((_c = process.env.HOME) !== null && _c !== void 0 ? _c : "", "Development/sandbox/bench-fixtures/lodash"),
+        cases: LODASH_CASES,
+    },
+    platform: {
+        name: "platform",
+        projectRoot: path.join((_d = process.env.HOME) !== null && _d !== void 0 ? _d : "", "Development/beyond/platform"),
+        cases: PLATFORM_CASES,
+    },
+};
+// A chunk matches when its file path ends with the expected file AND the
+// expected line falls within [start_line, end_line]. end_line falls back
+// to start_line + 200 when missing (lodash's mega-IIFE chunks are
+// typically much smaller than this, but the guard avoids false negatives
+// from short tail chunks).
+function chunkMatches(chunk, expectedFile, expectedLine) {
+    var _a, _b, _c, _d, _e, _f;
+    const path = String(((_a = chunk.metadata) === null || _a === void 0 ? void 0 : _a.path) || "").toLowerCase();
+    if (!path.endsWith(`/${expectedFile.toLowerCase()}`) && !path.endsWith(expectedFile.toLowerCase())) {
+        return false;
+    }
+    const start = Number((_d = (_c = (_b = chunk.generated_metadata) === null || _b === void 0 ? void 0 : _b.start_line) !== null && _c !== void 0 ? _c : chunk.start_line) !== null && _d !== void 0 ? _d : 0);
+    const numLines = Number((_f = (_e = chunk.generated_metadata) === null || _e === void 0 ? void 0 : _e.num_lines) !== null && _f !== void 0 ? _f : 0);
+    const end = numLines > 0 ? start + numLines : start + 200;
+    // chunks are 0-indexed start_line; expected line is 1-indexed
+    return expectedLine - 1 >= start && expectedLine - 1 <= end;
+}
+function evaluateOss(response, c, timeMs) {
+    const idx = response.data.findIndex((chunk) => chunkMatches(chunk, c.expectedFile, c.expectedLine));
+    const rank = idx + 1; // 0 = miss
+    const rr = rank > 0 ? 1 / rank : 0;
+    const recall10 = rank > 0 && rank <= 10 ? 1 : 0;
+    return {
+        id: c.id,
+        query: c.query,
+        expectedFile: c.expectedFile,
+        expectedLine: c.expectedLine,
+        rank,
+        rr,
+        recall10,
+        timeMs,
+        note: c.note,
+    };
+}
+function runDataset(ds, rerank, topK) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const vectorDb = new vector_db_1.VectorDB(config_1.PATHS.lancedbDir);
+        const searcher = new searcher_1.Searcher(vectorDb);
+        const pathPrefix = ds.projectRoot.endsWith("/") ? ds.projectRoot : `${ds.projectRoot}/`;
+        const results = [];
+        for (const c of ds.cases) {
+            const t0 = performance.now();
+            const res = yield searcher.search(c.query, topK, { rerank }, undefined, pathPrefix);
+            const timeMs = performance.now() - t0;
+            results.push(evaluateOss(res, c, timeMs));
+        }
+        yield vectorDb.close();
+        const hits = results.filter((r) => r.rank > 0).length;
+        const hitsAt1 = results.filter((r) => r.rank === 1).length;
+        const mrr = results.reduce((s, r) => s + r.rr, 0) / results.length;
+        const recall10 = results.reduce((s, r) => s + r.recall10, 0) / results.length;
+        const avgTime = results.reduce((s, r) => s + r.timeMs, 0) / results.length;
+        return {
+            summary: {
+                dataset: ds.name,
+                rerank,
+                cases: results.length,
+                hits,
+                hitsAt1,
+                mrrAt10: Number(mrr.toFixed(4)),
+                recallAt10: Number(recall10.toFixed(4)),
+                avgTimeMs: Math.round(avgTime),
+            },
+            results,
+        };
+    });
+}
+function run() {
+    return __awaiter(this, void 0, void 0, function* () {
+        var _a;
+        const args = process.argv.slice(2);
+        const datasetArg = (_a = args.find((a) => !a.startsWith("--"))) !== null && _a !== void 0 ? _a : "all";
+        const jsonMode = args.includes("--json") || process.env.GMAX_EVAL_JSON === "1";
+        const rerank = process.env.GMAX_EVAL_RERANK === "1";
+        const topK = 20;
+        const wanted = datasetArg === "all" ? Object.keys(DATASETS) : [datasetArg];
+        const out = [];
+        const log = jsonMode ? console.error : console.log;
+        log(`OSS eval (rerank=${rerank ? "on" : "off"})`);
+        for (const name of wanted) {
+            const ds = DATASETS[name];
+            if (!ds) {
+                console.error(`Unknown dataset: ${name}. Known: ${Object.keys(DATASETS).join(", ")}`);
+                process.exit(1);
+            }
+            log(`\n── ${ds.name} (${ds.cases.length} cases, ${ds.projectRoot})`);
+            const r = yield runDataset(ds, rerank, topK);
+            out.push(r);
+            if (!jsonMode) {
+                for (const res of r.results) {
+                    const status = res.rank > 0 ? `rank ${res.rank}` : "miss";
+                    console.log(`  ${res.id}  ${res.query.padEnd(20)} → ${status.padEnd(8)} ${res.expectedFile}:${res.expectedLine} [${res.timeMs.toFixed(0)}ms]`);
+                }
+                const s = r.summary;
+                console.log(`  → MRR@10=${s.mrrAt10}  Recall@10=${s.recallAt10}  hits@1=${s.hitsAt1}/${s.cases}  avg=${s.avgTimeMs}ms`);
+            }
+        }
+        if (jsonMode) {
+            process.stdout.write(`${JSON.stringify({ rerank, datasets: out }, null, 2)}\n`);
+        }
+        yield (0, exit_1.gracefulExit)(0);
+    });
+}
+if (require.main === module && process.env.GMAX_EVAL_AUTORUN !== "0") {
+    run().catch((e) => {
+        console.error(e);
+        process.exit(1);
+    });
+}

package/dist/eval.js

@@ -582,9 +582,14 @@ function run() {
         // changes show up clearly. Set GMAX_EVAL_RERANK=1 to measure the full
         // production pipeline (slower, but more representative).
         const rerank = process.env.GMAX_EVAL_RERANK === "1";
+        // Optional pathPrefix scoping — needed by PageRank tiebreaker (which is
+        // per-project) and to isolate this bench from cross-project chunks indexed
+        // by the same daemon. Defaults to unscoped so historical numbers stay
+        // comparable.
+        const evalPathPrefix = process.env.GMAX_EVAL_PATH_PREFIX || undefined;
         for (const c of exports.cases) {
             const queryStart = performance.now();
-            const res = yield searcher.search(c.query, topK, { rerank });
+            const res = yield searcher.search(c.query, topK, { rerank }, undefined, evalPathPrefix);
             const queryEnd = performance.now();
             const timeMs = queryEnd - queryStart;
             results.push(evaluateCase(res, c, timeMs));

package/dist/lib/search/pagerank.js

@@ -0,0 +1,267 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.computePageRank = computePageRank;
+exports.buildGraphFromDb = buildGraphFromDb;
+exports.writeDiskCache = writeDiskCache;
+exports.loadOrComputePageRank = loadOrComputePageRank;
+exports.pageRankBoostForSymbols = pageRankBoostForSymbols;
+exports._clearMemoryCacheForTests = _clearMemoryCacheForTests;
+exports._cachePathForTests = _cachePathForTests;
+const crypto = __importStar(require("node:crypto"));
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const config_1 = require("../../config");
+const filter_builder_1 = require("../utils/filter-builder");
+const DEFAULT_DAMPING = 0.85;
+const DEFAULT_MAX_ITER = 50;
+const DEFAULT_TOL = 1e-6;
+const DEFAULT_TTL_MS = 60 * 60 * 1000;
+const memoryCache = new Map();
+function computePageRank(graph, damping = DEFAULT_DAMPING, maxIter = DEFAULT_MAX_ITER, tol = DEFAULT_TOL) {
+    const N = graph.nodes.length;
+    const result = new Map();
+    if (N === 0)
+        return result;
+    const idx = new Map();
+    for (let i = 0; i < N; i++)
+        idx.set(graph.nodes[i], i);
+    const outNeighbors = Array.from({ length: N }, () => []);
+    for (const [src, targets] of graph.edges) {
+        const si = idx.get(src);
+        if (si === undefined)
+            continue;
+        const seen = new Set();
+        for (const tgt of targets) {
+            const ti = idx.get(tgt);
+            if (ti === undefined || ti === si || seen.has(ti))
+                continue;
+            seen.add(ti);
+            outNeighbors[si].push(ti);
+        }
+    }
+    const outDegree = new Int32Array(N);
+    for (let i = 0; i < N; i++)
+        outDegree[i] = outNeighbors[i].length;
+    const inNeighbors = Array.from({ length: N }, () => []);
+    for (let i = 0; i < N; i++) {
+        for (const j of outNeighbors[i])
+            inNeighbors[j].push(i);
+    }
+    let pr = new Float64Array(N).fill(1 / N);
+    let next = new Float64Array(N);
+    const teleport = (1 - damping) / N;
+    for (let iter = 0; iter < maxIter; iter++) {
+        let dangling = 0;
+        for (let i = 0; i < N; i++) {
+            if (outDegree[i] === 0)
+                dangling += pr[i];
+        }
+        const danglingShare = (damping * dangling) / N;
+        for (let i = 0; i < N; i++) {
+            let sum = 0;
+            const ins = inNeighbors[i];
+            for (let k = 0; k < ins.length; k++) {
+                const j = ins[k];
+                sum += pr[j] / outDegree[j];
+            }
+            next[i] = teleport + danglingShare + damping * sum;
+        }
+        let delta = 0;
+        for (let i = 0; i < N; i++)
+            delta += Math.abs(next[i] - pr[i]);
+        const tmp = pr;
+        pr = next;
+        next = tmp;
+        if (delta < tol)
+            break;
+    }
+    for (let i = 0; i < N; i++)
+        result.set(graph.nodes[i], pr[i]);
+    return result;
+}
+function toStringArray(val) {
+    if (!val)
+        return [];
+    if (Array.isArray(val))
+        return val.filter((v) => typeof v === "string");
+    const maybe = val;
+    if (typeof maybe.toArray === "function") {
+        try {
+            const arr = maybe.toArray();
+            return Array.isArray(arr)
+                ? arr.filter((v) => typeof v === "string")
+                : [];
+        }
+        catch (_a) {
+            return [];
+        }
+    }
+    return [];
+}
+function buildGraphFromDb(db, pathPrefix) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const table = yield db.ensureTable();
+        const prefix = pathPrefix.endsWith("/") ? pathPrefix : `${pathPrefix}/`;
+        const rows = yield table
+            .query()
+            .select(["defined_symbols", "referenced_symbols"])
+            .where(`path LIKE '${(0, filter_builder_1.escapeSqlString)(prefix)}%'`)
+            .toArray();
+        const nodes = new Set();
+        const edges = new Map();
+        for (const row of rows) {
+            const defs = toStringArray(row.defined_symbols);
+            const refs = toStringArray(row.referenced_symbols);
+            for (const d of defs)
+                nodes.add(d);
+            if (refs.length === 0)
+                continue;
+            for (const d of defs) {
+                let set = edges.get(d);
+                if (!set) {
+                    set = new Set();
+                    edges.set(d, set);
+                }
+                for (const r of refs)
+                    set.add(r);
+            }
+        }
+        return { nodes: Array.from(nodes), edges };
+    });
+}
+function cachePathFor(pathPrefix) {
+    const hash = crypto
+        .createHash("sha1")
+        .update(pathPrefix)
+        .digest("hex")
+        .slice(0, 16);
+    return path.join(config_1.PATHS.globalRoot, "pagerank", `${hash}.json`);
+}
+function getTtlMs() {
+    var _a;
+    const env = Number.parseInt((_a = process.env.GMAX_PAGERANK_TTL_MS) !== null && _a !== void 0 ? _a : "", 10);
+    return Number.isFinite(env) && env > 0 ? env : DEFAULT_TTL_MS;
+}
+function readDiskCache(pathPrefix) {
+    const file = cachePathFor(pathPrefix);
+    if (!fs.existsSync(file))
+        return null;
+    try {
+        const data = JSON.parse(fs.readFileSync(file, "utf8"));
+        const computedAt = Date.parse(data.computedAt);
+        if (!Number.isFinite(computedAt))
+            return null;
+        if (Date.now() - computedAt > getTtlMs())
+            return null;
+        const scores = new Map();
+        let max = 0;
+        for (const [k, v] of Object.entries(data.scores)) {
+            const n = Number(v);
+            if (!Number.isFinite(n))
+                continue;
+            scores.set(k, n);
+            if (n > max)
+                max = n;
+        }
+        return { scores, max, computedAt };
+    }
+    catch (_a) {
+        return null;
+    }
+}
+function writeDiskCache(pathPrefix, scores) {
+    const file = cachePathFor(pathPrefix);
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    const obj = {
+        pathPrefix,
+        computedAt: new Date().toISOString(),
+        nodeCount: scores.size,
+        scores: Object.fromEntries(scores),
+    };
+    fs.writeFileSync(file, JSON.stringify(obj), "utf8");
+}
+function loadOrComputePageRank(db, pathPrefix) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const mem = memoryCache.get(pathPrefix);
+        if (mem && Date.now() - mem.computedAt < getTtlMs()) {
+            return { scores: mem.scores, max: mem.max };
+        }
+        const disk = readDiskCache(pathPrefix);
+        if (disk) {
+            memoryCache.set(pathPrefix, disk);
+            return { scores: disk.scores, max: disk.max };
+        }
+        const graph = yield buildGraphFromDb(db, pathPrefix);
+        const scores = computePageRank(graph);
+        let max = 0;
+        for (const v of scores.values())
+            if (v > max)
+                max = v;
+        const entry = { scores, max, computedAt: Date.now() };
+        memoryCache.set(pathPrefix, entry);
+        try {
+            writeDiskCache(pathPrefix, scores);
+        }
+        catch (_a) { }
+        return { scores, max };
+    });
+}
+function pageRankBoostForSymbols(symbols, scores, max) {
+    if (!symbols || symbols.length === 0 || max <= 0)
+        return 0;
+    let best = 0;
+    for (const s of symbols) {
+        const v = scores.get(s);
+        if (v !== undefined && v > best)
+            best = v;
+    }
+    return best / max;
+}
+function _clearMemoryCacheForTests() {
+    memoryCache.clear();
+}
+function _cachePathForTests(pathPrefix) {
+    return cachePathFor(pathPrefix);
+}

package/dist/lib/search/searcher.js

@@ -15,6 +15,7 @@ const config_1 = require("../../config");
 const filter_builder_1 = require("../utils/filter-builder");
 const pool_1 = require("../workers/pool");
 const intent_1 = require("./intent");
+const pagerank_1 = require("./pagerank");
 function buildWhereClause(pathPrefix, filters, searchIntent) {
     var _a;
     const parts = [];
@@ -338,7 +339,7 @@ class Searcher {
     }
     search(query, top_k, _search_options, _filters, pathPrefix, intent, signal) {
         return __awaiter(this, void 0, void 0, function* () {
-            var _a, _b, _c, _d, _e, _f, _g, _h;
+            var _a, _b, _c, _d, _e, _f, _g, _h, _j;
             const finalLimit = top_k !== null && top_k !== void 0 ? top_k : 10;
             // ColBERT rerank is opt-in as of v0.17.1. On the 97-case eval it
             // regresses MRR@10 by ~3% and doubles query latency; sweep across
@@ -371,7 +372,7 @@ class Searcher {
             try {
                 table = yield this.db.ensureTable();
             }
-            catch (_j) {
+            catch (_k) {
                 return { data: [] };
             }
             // Ensure FTS index exists (lazy init, retry periodically on failure)
@@ -391,10 +392,15 @@ class Searcher {
                 }
             }
             // Phase A: Lightweight retrieval — only columns needed for RRF, cosine, boost, dedup
+            // PageRank tiebreaker needs defined_symbols for the per-chunk lookup; include
+            // it in the lightweight path only when the flag is on so we don't bloat the
+            // default query path.
+            const pagerankEnabled = process.env.GMAX_PAGERANK === "1" && !!pathPrefix;
             const LIGHTWEIGHT_COLUMNS = [
                 "id", "path", "hash", "chunk_index", "start_line", "end_line",
                 "is_anchor", "chunk_type", "role", "complexity", "is_exported",
                 "content", "parent_symbol", "referenced_symbols", "pooled_colbert_48d",
+                ...(pagerankEnabled ? ["defined_symbols"] : []),
             ];
             // _distance is auto-added by vectorSearch, _score by FTS — include each
             // in the respective query to suppress LanceDB deprecation warnings
@@ -432,7 +438,7 @@ class Searcher {
                             this.ftsAvailable = true;
                             console.warn("[Searcher] Rebuilt FTS index with position support — retry search");
                         }
-                        catch (_k) { }
+                        catch (_l) { }
                     }
                     else {
                         console.warn(`[Searcher] FTS search failed (will retry later): ${msg}`);
@@ -571,6 +577,40 @@ class Searcher {
                         : undefined,
                 };
             });
+            // PageRank tiebreaker (opt-in via GMAX_PAGERANK=1). Small additive delta on
+            // top of the post-boost score, sourced from the per-project call graph. Read
+            // docs/plans/2026-05-25-semantic-search-landscape.md (Bundle B / G1) for the
+            // measurement criterion that decides whether this flag becomes default-on.
+            if (pagerankEnabled && pathPrefix) {
+                try {
+                    const { scores: prScores, max: prMax } = yield (0, pagerank_1.loadOrComputePageRank)(this.db, pathPrefix);
+                    if (prMax > 0) {
+                        const envWeight = Number.parseFloat((_h = process.env.GMAX_PR_WEIGHT) !== null && _h !== void 0 ? _h : "");
+                        const PR_WEIGHT = Number.isFinite(envWeight) && envWeight >= 0 ? envWeight : 0.05;
+                        for (const item of scored) {
+                            const raw = item.record.defined_symbols;
+                            let defs = [];
+                            if (Array.isArray(raw)) {
+                                defs = raw.filter((v) => typeof v === "string");
+                            }
+                            else if (raw && typeof raw.toArray === "function") {
+                                try {
+                                    const arr = raw.toArray();
+                                    if (Array.isArray(arr)) {
+                                        defs = arr.filter((v) => typeof v === "string");
+                                    }
+                                }
+                                catch (_m) { }
+                            }
+                            const norm = (0, pagerank_1.pageRankBoostForSymbols)(defs, prScores, prMax);
+                            item.score += PR_WEIGHT * norm;
+                        }
+                    }
+                }
+                catch (e) {
+                    console.warn(`[Searcher] PageRank tiebreaker failed: ${e}`);
+                }
+            }
             // Note: "boosted" was not previously declared -- fix to use "scored"
             scored.sort((a, b) => b.score - a.score);
             // Item 11: Intelligent Deduplication
@@ -578,7 +618,7 @@ class Searcher {
             // Item 10: Per-file diversification
             const seenFiles = new Map();
             const diversified = [];
-            const envMaxPerFile = Number.parseInt((_h = process.env.GMAX_MAX_PER_FILE) !== null && _h !== void 0 ? _h : "", 10);
+            const envMaxPerFile = Number.parseInt((_j = process.env.GMAX_MAX_PER_FILE) !== null && _j !== void 0 ? _j : "", 10);
             const MAX_PER_FILE = Number.isFinite(envMaxPerFile) && envMaxPerFile > 0 ? envMaxPerFile : 3;
             for (const item of uniqueScored) {
                 const path = item.record.path || "";

package/mlx-embed-server/server.py

@@ -25,6 +25,30 @@ os.environ["HF_HUB_DISABLE_IMPLICIT_TOKEN"] = "1"
 os.environ["HF_HUB_VERBOSITY"] = "error"
 os.environ["HF_HUB_DISABLE_PROGRESS_BARS"] = "1"
 os.environ["TOKENIZERS_PARALLELISM"] = "false"
+
+# Auto-enable offline mode when the model is already cached, so steady-state
+# startups don't HEAD-check huggingface.co (annoying firewall prompts, slow
+# starts on flaky networks). First run with an empty cache stays online so
+# the model can be fetched. Force one or the other with GMAX_HF_ONLINE=1
+# or GMAX_HF_OFFLINE=1.
+def _hf_cache_has_model(model_id: str) -> bool:
+    hf_home = os.environ.get("HF_HOME") or os.path.expanduser(
+        os.path.join("~", ".cache", "huggingface")
+    )
+    cache_dir = os.path.join(
+        hf_home, "hub", "models--" + model_id.replace("/", "--")
+    )
+    return os.path.isdir(cache_dir) and bool(os.listdir(cache_dir))
+
+_model_id_for_cache_check = os.environ.get(
+    "MLX_EMBED_MODEL", "ibm-granite/granite-embedding-small-english-r2"
+)
+if os.environ.get("GMAX_HF_OFFLINE") == "1" or (
+    os.environ.get("GMAX_HF_ONLINE") != "1"
+    and _hf_cache_has_model(_model_id_for_cache_check)
+):
+    os.environ["HF_HUB_OFFLINE"] = "1"
+    os.environ["TRANSFORMERS_OFFLINE"] = "1"
 warnings.filterwarnings("ignore", message=".*PyTorch.*")
 warnings.filterwarnings("ignore", message=".*resource_tracker.*")
 logging.getLogger("huggingface_hub").setLevel(logging.ERROR)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "grepmax",
-  "version": "0.17.2",
+  "version": "0.17.3",
   "author": "Robert Owens <78518764+reowens@users.noreply.github.com>",
   "homepage": "https://github.com/reowens/grepmax",
   "bugs": {
@@ -28,6 +28,8 @@
     "benchmark:chart": "npx tsx src/bench/generate-benchmark-chart.ts",
     "bench:recall": "npx tsx src/eval.ts",
     "bench:recall:json": "GMAX_EVAL_JSON=1 npx tsx src/eval.ts",
+    "bench:oss": "npx tsx src/eval-oss.ts all",
+    "bench:oss:json": "GMAX_EVAL_JSON=1 npx tsx src/eval-oss.ts all",
     "format": "biome check --write .",
     "format:check": "biome check .",
     "lint": "biome lint .",

package/plugins/grepmax/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "grepmax",
-  "version": "0.17.2",
+  "version": "0.17.3",
   "description": "Semantic code search for Claude Code. Automatically indexes your project and provides intelligent search capabilities.",
   "author": {
     "name": "Robert Owens",

package/plugins/grepmax/skills/grepmax/SKILL.md

@@ -13,6 +13,7 @@ allowed-tools: "Bash(gmax:*), Read"
 - **Quick symbol overview?** → `Bash(gmax peek <symbol>)` (signature + callers + callees)
 - **Need file structure?** → `Bash(gmax skeleton <path>)`
 - **Need call flow?** → `Bash(gmax trace <symbol>)`
+- **Is a symbol unused?** → `Bash(gmax dead <symbol>)` (call-graph check — hypothesis, not proof)
 
 ## Quick start
 
@@ -40,7 +41,7 @@ If search returns "This project hasn't been added to gmax yet", run `Bash(gmax a
 
 ### Search — `gmax "query" --agent`
 
-The `--agent` flag produces compact, token-efficient output for AI agents. It works on most commands — `search`, `peek`, `extract`, `trace`, `test`, `impact`, `similar`, `log`, `related`, `symbols`, `status`, `project`, `context`, `skeleton`, and `doctor`.
+The `--agent` flag produces compact, token-efficient output for AI agents. It works on most commands — `search`, `peek`, `extract`, `trace`, `test`, `impact`, `similar`, `dead`, `log`, `related`, `symbols`, `status`, `project`, `context`, `skeleton`, and `doctor`.
 
 ```
 gmax "where do we handle authentication" --agent
@@ -177,6 +178,14 @@ gmax similar src/lib/auth.ts           # files with similar structure
 gmax similar handleAuth -m 5 --agent   # top 5, compact output
 ```
 
+### Dead — `gmax dead <symbol>`
+```
+gmax dead handleAuth                   # zero-inbound-callers check via the call graph
+gmax dead handleAuth --agent           # TSV: status\tdef:line\tcaller_count\tcallers_top3
+gmax dead handleAuth --in src/         # restrict to a sub-path
+```
+Status is `DEAD` (no callers, not exported), `PUBLIC EXPORT` (no internal callers but the defining chunk is exported — check external usage), or `LIVE` (with caller count + top-3 file:line). The call graph reflects what tree-sitter chunked: dynamic dispatch, reflection, eval, and string-built call sites won't show up — `DEAD` is a hypothesis, not a proof.
+
 ### Context — `gmax context <topic> --budget <tokens>`
 ```
 gmax context "authentication system" --budget 4000
@@ -219,13 +228,14 @@ gmax llm on/off/start/stop/status          # manage local LLM server
 10. **Test** — `Bash(gmax test <symbol>)` to find tests covering a symbol before editing
 11. **Impact** — `Bash(gmax impact <symbol>)` for blast radius before significant changes
 12. **Similar** — `Bash(gmax similar <symbol>)` to find similar patterns for DRY analysis
-13. **Context** — `Bash(gmax context "topic" --budget 4000)` for a token-budgeted topic summary
-14. **Related** — `Bash(gmax related <file>)` to see what else to look at
-15. **Status** — `Bash(gmax status)` to check index state across all projects
+13. **Dead** — `Bash(gmax dead <symbol>)` to check if a symbol has zero inbound callers (hypothesis, not proof)
+14. **Context** — `Bash(gmax context "topic" --budget 4000)` for a token-budgeted topic summary
+15. **Related** — `Bash(gmax related <file>)` to see what else to look at
+16. **Status** — `Bash(gmax status)` to check index state across all projects
 
 ## Tips
 
-- **Use `--agent` for compact output** — works on most commands: search, peek, extract, trace, log, test, impact, similar, related, status, project, doctor.
+- **Use `--agent` for compact output** — works on most commands: search, peek, extract, trace, log, test, impact, similar, dead, related, status, project, doctor.
 - **Be specific.** 5+ words. "auth" returns noise. "where does the server validate JWT tokens" is specific.
 - **Use `--role ORCHESTRATION`** to skip type definitions and find the actual logic.
 - **Use `--symbol`** when the query is a function/class name — gets search + trace in one call.