gitnexus 1.6.7-rc.5 → 1.6.7-rc.7

package/dist/core/lbug/pool-adapter.js

@@ -39,6 +39,17 @@ const MAX_POOL_SIZE = 5;
 const IDLE_TIMEOUT_MS = 5 * 60 * 1000; // 5 minutes
 /** Max connections per repo (caps concurrent queries per repo) */
 const MAX_CONNS_PER_REPO = 8;
+// Behavior-neutral RSS tracing for the FTS evict→reload memory repro
+// (gitnexus/scripts/bench/fts-evict-reload-rss.mjs). Two invariants keep it safe
+// in the pool init/close hot path: it writes ONLY to stderr (stdout is the MCP
+// JSON-RPC channel), and the GITNEXUS_POOL_RSS_TRACE gate makes it a no-op — one
+// env-var compare per call, nothing else — unless a harness explicitly enables it.
+function traceRss(event, repoId) {
+    if (process.env.GITNEXUS_POOL_RSS_TRACE !== '1')
+        return;
+    const rssMb = Math.round(process.memoryUsage().rss / (1024 * 1024));
+    process.stderr.write(`[pool-rss] ${event} repo=${repoId} pool=${pool.size} dbCache=${dbCache.size} rssMB=${rssMb}\n`);
+}
 let idleTimer = null;
 // Stdout-capture state lives in `gitnexus/src/mcp/stdio-capture.ts` — a leaf
 // module with zero non-`node:` imports. We re-export the same symbols here
@@ -166,6 +177,7 @@ function closeOne(repoId) {
             // Isolate listener failures — teardown must complete.
         }
     }
+    traceRss('close', repoId);
 }
 /**
  * Create a new Connection from a repo's Database.
@@ -511,6 +523,7 @@ async function doInitLbug(repoId, dbPath) {
         closed: false,
     });
     ensureIdleTimer();
+    traceRss('init', repoId);
 }
 /**
  * Initialize a pool entry from a pre-existing Database object.
@@ -565,6 +578,7 @@ export async function initLbugWithDb(repoId, existingDb, dbPath) {
         closed: false,
     });
     ensureIdleTimer();
+    traceRss('init', repoId);
 }
 /**
  * Checkout a connection from the pool.

package/dist/mcp/local/local-backend.js

@@ -143,6 +143,18 @@ function logQueryError(context, err) {
     const msg = err instanceof Error ? err.message : String(err);
     logger.error({ context, err: msg }, 'GitNexus query failed');
 }
+/**
+ * A "missing table/label/relation" prepare error is benign for the query tool's
+ * best-effort enrichment: a repo analyzed without processes or communities simply
+ * has no `Process`/`Community` tables, so the `STEP_IN_PROCESS` / `MEMBER_OF`
+ * enrichment queries fail to prepare. That is a normal configuration, NOT a
+ * degraded result — it must not raise the `partial` flag (which callers would
+ * then learn to ignore). Real failures (timeouts, locks, native faults) do.
+ */
+function isBenignMissingTableError(err) {
+    const msg = err instanceof Error ? err.message : String(err ?? '');
+    return /does not exist|no such (table|label|rel)|unknown (table|label)|not (defined|found)/i.test(msg);
+}
 const isReadOnlyDbError = (err) => {
     // Walk the `cause` chain (bounded) so a wrapped read-only error (e.g. the
     // pool adapter's `{ cause }` wrapper) is still detected here — this is the
@@ -925,61 +937,117 @@ export class LocalBackend {
         timer.start('symbol_lookup');
         const processMap = new Map();
         const definitions = []; // standalone symbols not in any process
-        for (const [_, item] of merged) {
-            const sym = item.data;
-            if (!sym.nodeId) {
-                // File-level results go to definitions
-                definitions.push({
-                    name: sym.name,
-                    type: sym.type || 'File',
-                    filePath: sym.filePath,
-                });
-                continue;
-            }
-            // Find processes this symbol participates in
-            let processRows = [];
+        // Batch-fetch process participation, cohesion, and (optionally) content for
+        // ALL matched symbols in 2-3 graph queries instead of 2-3 *per symbol*. The
+        // previous per-symbol loop issued up to 3N sequential pool round-trips
+        // (searchLimit symbols × {STEP_IN_PROCESS, MEMBER_OF, content}); on a warm
+        // repo the IPC + query-setup overhead of those round-trips dominated query
+        // latency. Collapsing to `WHERE n.id IN $nodeIds` preserves identical output
+        // (the aggregation loop below is unchanged) while cutting the round-trips.
+        // Array params bind through the pool exactly as bm25Search's
+        // `WHERE n.id IN $nodeIds` already does. (Ported from gitnexus-enterprise
+        // PR #222 — N+1 → 2-3 batched queries.)
+        const nodeIds = merged.map(([, m]) => m.data?.nodeId).filter((id) => !!id);
+        const processRowsByNode = new Map();
+        const cohesionByNode = new Map();
+        const contentByNode = new Map();
+        // Set when a batched enrichment query throws a REAL failure (timeout, lock,
+        // native fault) — NOT the benign "no Process/Community table" case, which is
+        // a normal config (a repo analyzed without processes/communities) and must
+        // not raise a `partial` flag callers would learn to ignore. See
+        // isBenignMissingTableError + the response build below.
+        let enrichmentDegraded = false;
+        // Chunk the IN-list like the impact path (CHUNK_SIZE=100) so a large result
+        // set never builds an unbounded `IN` parameter. Default batch is
+        // processLimit*maxSymbolsPerProcess (≤ one chunk), but chunk for robustness.
+        const QUERY_CHUNK_SIZE = 100;
+        for (let i = 0; i < nodeIds.length; i += QUERY_CHUNK_SIZE) {
+            const ids = nodeIds.slice(i, i + QUERY_CHUNK_SIZE);
+            // Processes each symbol participates in. `n.id AS nodeId` is prepended as
+            // column 0 so rows from many symbols can be re-associated to their symbol.
             try {
-                processRows = await executeParameterized(repo.lbugPath, `
-          MATCH (n {id: $nodeId})-[r:CodeRelation {type: 'STEP_IN_PROCESS'}]->(p:Process)
-          RETURN p.id AS pid, p.label AS label, p.heuristicLabel AS heuristicLabel, p.processType AS processType, p.stepCount AS stepCount, r.step AS step
-        `, { nodeId: sym.nodeId });
+                const rows = await executeParameterized(repo.lbugPath, `
+          MATCH (n)-[r:CodeRelation {type: 'STEP_IN_PROCESS'}]->(p:Process)
+          WHERE n.id IN $nodeIds
+          RETURN n.id AS nodeId, p.id AS pid, p.label AS label, p.heuristicLabel AS heuristicLabel, p.processType AS processType, p.stepCount AS stepCount, r.step AS step
+        `, { nodeIds: ids });
+                for (const row of rows) {
+                    const nid = row.nodeId ?? row[0];
+                    let list = processRowsByNode.get(nid);
+                    if (!list)
+                        processRowsByNode.set(nid, (list = []));
+                    list.push(row);
+                }
             }
             catch (e) {
                 logQueryError('query:process-lookup', e);
+                if (!isBenignMissingTableError(e))
+                    enrichmentDegraded = true;
             }
-            // Get cluster membership + cohesion (cohesion used as internal ranking signal)
-            let cohesion = 0;
-            let module;
+            // Cluster membership + cohesion. Keep the FIRST community row per node to
+            // mirror the prior per-symbol `LIMIT 1` (each symbol keeps ITS community,
+            // not one community for the whole batch).
             try {
-                const cohesionRows = await executeParameterized(repo.lbugPath, `
-          MATCH (n {id: $nodeId})-[:CodeRelation {type: 'MEMBER_OF'}]->(c:Community)
-          RETURN c.cohesion AS cohesion, c.heuristicLabel AS module
-          LIMIT 1
-        `, { nodeId: sym.nodeId });
-                if (cohesionRows.length > 0) {
-                    cohesion = (cohesionRows[0].cohesion ?? cohesionRows[0][0]) || 0;
-                    module = cohesionRows[0].module ?? cohesionRows[0][1];
+                const rows = await executeParameterized(repo.lbugPath, `
+          MATCH (n)-[:CodeRelation {type: 'MEMBER_OF'}]->(c:Community)
+          WHERE n.id IN $nodeIds
+          RETURN n.id AS nodeId, c.cohesion AS cohesion, c.heuristicLabel AS module
+        `, { nodeIds: ids });
+                for (const row of rows) {
+                    const nid = row.nodeId ?? row[0];
+                    if (!cohesionByNode.has(nid)) {
+                        cohesionByNode.set(nid, {
+                            cohesion: (row.cohesion ?? row[1]) || 0,
+                            module: row.module ?? row[2],
+                        });
+                    }
                 }
             }
             catch (e) {
                 logQueryError('query:cluster-info', e);
+                if (!isBenignMissingTableError(e))
+                    enrichmentDegraded = true;
             }
-            // Optionally fetch content
-            let content;
+            // Optionally fetch content for every matched symbol.
             if (includeContent) {
                 try {
-                    const contentRows = await executeParameterized(repo.lbugPath, `
-            MATCH (n {id: $nodeId})
-            RETURN n.content AS content
-          `, { nodeId: sym.nodeId });
-                    if (contentRows.length > 0) {
-                        content = contentRows[0].content ?? contentRows[0][0];
+                    const rows = await executeParameterized(repo.lbugPath, `
+            MATCH (n)
+            WHERE n.id IN $nodeIds
+            RETURN n.id AS nodeId, n.content AS content
+          `, { nodeIds: ids });
+                    for (const row of rows) {
+                        const nid = row.nodeId ?? row[0];
+                        contentByNode.set(nid, row.content ?? row[1]);
                     }
                 }
                 catch (e) {
                     logQueryError('query:content-fetch', e);
+                    if (!isBenignMissingTableError(e))
+                        enrichmentDegraded = true;
                 }
             }
+        }
+        // Aggregation is unchanged from the per-symbol version — it now reads the
+        // pre-fetched maps instead of issuing a query per symbol. Iterating `merged`
+        // in the same (sorted) order preserves processMap insertion order, the
+        // definitions order, and the item.score association exactly.
+        for (const [_, item] of merged) {
+            const sym = item.data;
+            if (!sym.nodeId) {
+                // File-level results go to definitions
+                definitions.push({
+                    name: sym.name,
+                    type: sym.type || 'File',
+                    filePath: sym.filePath,
+                });
+                continue;
+            }
+            const processRows = processRowsByNode.get(sym.nodeId) ?? [];
+            const coh = cohesionByNode.get(sym.nodeId);
+            const cohesion = coh?.cohesion ?? 0;
+            const module = coh?.module;
+            const content = includeContent ? contentByNode.get(sym.nodeId) : undefined;
             const symbolEntry = {
                 id: sym.nodeId,
                 name: sym.name,
@@ -997,12 +1065,13 @@ export class LocalBackend {
             else {
                 // Add to each process it belongs to
                 for (const row of processRows) {
-                    const pid = row.pid ?? row[0];
-                    const label = row.label ?? row[1];
-                    const hLabel = row.heuristicLabel ?? row[2];
-                    const pType = row.processType ?? row[3];
-                    const stepCount = row.stepCount ?? row[4];
-                    const step = row.step ?? row[5];
+                    // Positional fallbacks shift +1 because `n.id AS nodeId` is column 0.
+                    const pid = row.pid ?? row[1];
+                    const label = row.label ?? row[2];
+                    const hLabel = row.heuristicLabel ?? row[3];
+                    const pType = row.processType ?? row[4];
+                    const stepCount = row.stepCount ?? row[5];
+                    const step = row.step ?? row[6];
                     if (!processMap.has(pid)) {
                         processMap.set(pid, {
                             id: pid,
@@ -1066,14 +1135,24 @@ export class LocalBackend {
         timer.mark('wall', performance.now() - wallStart);
         const timing = timer.summary();
         logQueryTiming(searchQuery, timing);
+        // Compose a single `warning` from all degraded conditions (FTS-missing
+        // and/or a real enrichment failure) so neither overwrites the other, and
+        // flag `partial` when enrichment was lost. Both are omitted on the clean
+        // path, leaving the success-path response shape byte-identical.
+        const warnings = [];
+        if (!ftsUsed) {
+            warnings.push('FTS indexes missing — keyword search degraded. Run: gitnexus analyze --repair-fts (or gitnexus analyze --force) to rebuild indexes.');
+        }
+        if (enrichmentDegraded) {
+            warnings.push('Symbol enrichment partially failed — some process/cohesion/content data may be missing from these results (see server logs).');
+        }
         return {
             processes,
             process_symbols: dedupedSymbols,
             definitions: definitions.slice(0, 20), // cap standalone definitions
             timing,
-            ...(!ftsUsed && {
-                warning: 'FTS indexes missing — keyword search degraded. Run: gitnexus analyze --repair-fts (or gitnexus analyze --force) to rebuild indexes.',
-            }),
+            ...(warnings.length > 0 && { warning: warnings.join(' ') }),
+            ...(enrichmentDegraded && { partial: true }),
         };
     }
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gitnexus",
-  "version": "1.6.7-rc.5",
+  "version": "1.6.7-rc.7",
   "description": "Graph-powered code intelligence for AI agents. Index any codebase, query via MCP or CLI.",
   "author": "Abhigyan Patwari",
   "license": "PolyForm-Noncommercial-1.0.0",
@@ -49,7 +49,7 @@
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage",
     "test:cross-platform": "tsx scripts/run-cross-platform.ts",
-    "postinstall": "node scripts/materialize-vendor-grammars.cjs && node scripts/build-tree-sitter-dart.cjs && node scripts/build-tree-sitter-proto.cjs && node scripts/build-tree-sitter-swift.cjs",
+    "postinstall": "node scripts/materialize-vendor-grammars.cjs && node scripts/build-tree-sitter-dart.cjs && node scripts/build-tree-sitter-proto.cjs && node scripts/build-tree-sitter-swift.cjs && node scripts/build-tree-sitter-kotlin.cjs",
     "prepare": "node scripts/build.js",
     "prepack": "node scripts/build.js"
   },

package/scripts/bench/fts-evict-reload-rss.mjs

@@ -0,0 +1,374 @@
+#!/usr/bin/env node
+// FTS evict→reload RSS repro (gitnexus-enterprise PR #222 / local U3).
+//
+// Settles ONE empirical question that no static read can answer: when a
+// LadybugDB database that has `LOAD EXTENSION fts` applied is closed and a
+// fresh one is opened + re-LOADed (the pool's evict→reload cycle), does the
+// native FTS arena get reclaimed by `db.close()` — or is it stranded, so RSS
+// climbs without bound over a long-lived MCP `serve` session?
+//
+//   • PLATEAU across cycles  → db.close() reclaims the FTS arena; the OSS pool's
+//     footprint is bounded by MAX_POOL_SIZE (~5 live arenas). No unbounded leak;
+//     the #222 worker-isolation rewrite (plan U4) is NOT justified for OSS.
+//   • MONOTONIC CLIMB         → the FTS arena is stranded per reopen; the user's
+//     hypothesis holds and U4 (route FTS reads through a reclaimable worker) is
+//     justified.
+//
+// SCOPE OF THE VERDICT (read before citing it). A per-reload FTS-arena leak
+// would be PROPORTIONAL to the index size. A small fixture therefore produces a
+// small per-cycle increment that an absolute threshold can read as PLATEAU even
+// when a production-scale graph would leak visibly. So:
+//   - `--rows` controls fixture size; run it LARGE (tens of thousands) before
+//     concluding "no leak". The default is deliberately not tiny.
+//   - The verdict (in fts-rss-verdict.mjs) keys on slope DECELERATION, not total
+//     delta, with a noise floor that scales with the working-set growth
+//     (peak−baseline) so sensitivity tracks fixture/arena size — NOT the pre-DB
+//     baseline RSS. A sustained sub-floor positive slope is INCONCLUSIVE (a slow
+//     creep RSS can't distinguish from noise), never a clean PLATEAU.
+//   - The PLATEAU verdict is only valid for the corpus size it was run at; the
+//     output states that size. The production-faithful confirmation is a
+//     `--via-pool` run against a real large analyzed repo over a long session.
+//
+// Two modes:
+//   (default) NATIVE — reproduces the native sequence doInitLbug()+closeOne()
+//     perform (open Database → new Connection → LOAD EXTENSION fts →
+//     QUERY_FTS_INDEX → close), against K self-built FTS fixtures, with no
+//     gitnexus build required. `--no-await-close` mirrors the pool's
+//     fire-and-forget close instead of awaiting (the production close shape).
+//   --via-pool <lbugPath> — drives the REAL gitnexus pool from compiled dist
+//     (initLbug → executeParameterized → closeLbug) against an existing analyzed
+//     repo, exercising the production path + the GITNEXUS_POOL_RSS_TRACE
+//     instrumentation. Probes ALL FTS indexes the repo has. Forces an explicit
+//     close+reinit each cycle. Run `node scripts/build.js` first so the dist
+//     reflects the current pool-adapter (incl. the RSS trace).
+//
+// Run with --expose-gc so RSS excludes V8-heap noise:
+//   node --expose-gc gitnexus/scripts/bench/fts-evict-reload-rss.mjs
+//   node --expose-gc gitnexus/scripts/bench/fts-evict-reload-rss.mjs --rows 40000 --cycles 30
+//   GITNEXUS_POOL_RSS_TRACE=1 node --expose-gc \
+//     gitnexus/scripts/bench/fts-evict-reload-rss.mjs --via-pool /path/to/repo/.gitnexus/lbug
+//
+// Flags by mode: --rows/--repos/--read-write/--no-await-close apply to NATIVE
+// only; --cycles applies to both. VIA-POOL warns when a NATIVE-only flag is set.
+//
+// Memory benches are noisy. Default is 24 cycles; trust the TREND (slope /
+// first-third vs last-third), never a single delta. A flat trend at a LARGE
+// fixture is a real NEGATIVE result (no unbounded leak), not a failed run.
+
+import { createRequire } from 'node:module';
+import os from 'node:os';
+import path from 'node:path';
+import fs from 'node:fs';
+// Pure verdict classifier (median, slopeMbPerCycle, classifyVerdict) lives in a
+// side-effect-free sibling module so it is unit-testable without loading the
+// native addon or running this bench. See fts-rss-verdict.mjs.
+import { classifyVerdict, median, slopeMbPerCycle } from './fts-rss-verdict.mjs';
+
+const require = createRequire(import.meta.url);
+const lbugModule = require('@ladybugdb/core');
+const lbug = lbugModule.default ?? lbugModule;
+
+const LBUG_MAX_DB_SIZE = 16 * 1024 * 1024 * 1024;
+
+// ── args ──────────────────────────────────────────────────────────────────
+function argVal(flag, dflt) {
+  const i = process.argv.indexOf(flag);
+  return i >= 0 && process.argv[i + 1] ? process.argv[i + 1] : dflt;
+}
+const CYCLES = Math.max(6, parseInt(argVal('--cycles', '24'), 10) || 24);
+const REPOS = Math.max(1, parseInt(argVal('--repos', '6'), 10) || 6); // >5 mirrors LRU thrash
+// Fixture size. Default is large enough that a size-proportional leak would be
+// visible across cycles; raise it further before trusting a PLATEAU verdict.
+const ROWS = Math.max(100, parseInt(argVal('--rows', '8000'), 10) || 8000);
+const VIA_POOL = argVal('--via-pool', null);
+const READONLY = !process.argv.includes('--read-write');
+const AWAIT_CLOSE = !process.argv.includes('--no-await-close');
+
+if (VIA_POOL) {
+  // These flags are consumed only by NATIVE mode; warn rather than ignore
+  // silently so a VIA-POOL run is not misread as honoring them.
+  const ignored = ['--rows', '--repos', '--read-write', '--no-await-close'].filter((f) =>
+    process.argv.includes(f),
+  );
+  if (ignored.length) {
+    console.error(
+      `[fts-rss] NOTE: ${ignored.join(', ')} apply to NATIVE mode only; ignored in --via-pool.`,
+    );
+  }
+}
+
+if (typeof global.gc !== 'function') {
+  console.error(
+    '[fts-rss] WARNING: run with --expose-gc for clean RSS samples ' +
+      '(`node --expose-gc <thisfile>`). Continuing without forced GC — results are noisier.',
+  );
+}
+
+const gc = () => {
+  if (typeof global.gc === 'function') {
+    global.gc();
+    global.gc();
+  }
+};
+const rssMb = () => Math.round(process.memoryUsage().rss / (1024 * 1024));
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+// ── fixture: a minimal FTS-bearing .lbug ────────────────────────────────────
+const WORDS = [
+  'login auth session token user password validate verify credential',
+  'parse tree syntax node grammar lexer token ast traversal visitor',
+  'graph query cypher match relation node edge pattern aggregate index',
+  'memory pool buffer arena allocate reclaim evict cache resident heap',
+  'search rank score bm25 fts index stem porter keyword document corpus',
+  'worker fork process spawn kill reclaim isolate native binding addon',
+];
+
+function buildFixture(dir) {
+  fs.mkdirSync(dir, { recursive: true });
+  const dbPath = path.join(dir, 'fixture.lbug');
+  const db = new lbug.Database(dbPath, 0, false, false, LBUG_MAX_DB_SIZE);
+  const conn = new lbug.Connection(db);
+  return (async () => {
+    await conn.query('LOAD EXTENSION fts');
+    await conn.query(
+      'CREATE NODE TABLE Doc(id STRING, name STRING, content STRING, PRIMARY KEY(id))',
+    );
+    // Batch-insert via UNWIND so large fixtures (`--rows`) build in seconds
+    // instead of one round-trip per row. The fixture size drives the per-arena
+    // FTS allocation, which is what makes a size-proportional leak observable.
+    const rows = [];
+    for (let i = 0; i < ROWS; i++) {
+      const w = WORDS[i % WORDS.length];
+      const name = `sym_${i}`;
+      const content = `${w} ${name} block number ${i} ${WORDS[(i + 3) % WORDS.length]}`;
+      rows.push({ id: `doc:${i}`, name, content });
+    }
+    const INSERT_CHUNK = 2000;
+    for (let i = 0; i < rows.length; i += INSERT_CHUNK) {
+      const chunk = rows.slice(i, i + INSERT_CHUNK);
+      const stmt = await conn.prepare(
+        'UNWIND $rows AS r CREATE (:Doc {id: r.id, name: r.name, content: r.content})',
+      );
+      await conn.execute(stmt, { rows: chunk });
+    }
+    await conn.query(
+      "CALL CREATE_FTS_INDEX('Doc', 'doc_fts', ['name', 'content'], stemmer := 'porter')",
+    );
+    await conn.close();
+    await db.close();
+    return dbPath;
+  })();
+}
+
+const QUERIES = ['login token', 'parse node', 'memory arena', 'search index', 'worker reclaim'];
+
+// ── NATIVE mode ─────────────────────────────────────────────────────────────
+async function runNative() {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'fts-rss-'));
+  console.error(
+    `[fts-rss] NATIVE: ${REPOS} fixtures × ${ROWS} rows × ${CYCLES} cycles ` +
+      `(readOnly=${READONLY}, awaitClose=${AWAIT_CLOSE})`,
+  );
+  console.error(`[fts-rss] building ${REPOS} FTS fixture(s) under ${root} …`);
+
+  const srcDb = await buildFixture(path.join(root, 'src'));
+  const repoPaths = [];
+  for (let k = 0; k < REPOS; k++) {
+    const dst = path.join(root, `repo-${k}`);
+    fs.cpSync(path.dirname(srcDb), dst, { recursive: true });
+    repoPaths.push(path.join(dst, 'fixture.lbug'));
+  }
+
+  // Mirror the pool's evict→reload: each visit opens a FRESH Database, makes a
+  // Connection, LOADs fts, runs an FTS query, then closes — no caching, so every
+  // visit is a reload. K>5 amplifies the LRU-thrash signal the pool would see.
+  const series = [];
+  gc();
+  await sleep(50);
+  const baseline = rssMb();
+  console.error(`[fts-rss] baseline RSS=${baseline}MB`);
+
+  for (let cycle = 0; cycle < CYCLES; cycle++) {
+    for (let k = 0; k < REPOS; k++) {
+      const db = new lbug.Database(repoPaths[k], 0, false, READONLY, LBUG_MAX_DB_SIZE);
+      const conn = new lbug.Connection(db);
+      try {
+        await conn.query('LOAD EXTENSION fts'); // the per-reload re-LOAD under test
+        const q = QUERIES[(cycle + k) % QUERIES.length];
+        const res = await conn.query(
+          `CALL QUERY_FTS_INDEX('Doc', 'doc_fts', '${q}') RETURN node.id AS id, score ORDER BY score DESC LIMIT 20`,
+        );
+        // Drain so the query actually materializes results.
+        if (res && typeof res.getAll === 'function') await res.getAll();
+      } catch (e) {
+        console.error(`[fts-rss] query error (cycle ${cycle}, repo ${k}): ${e?.message || e}`);
+      } finally {
+        // AWAIT_CLOSE (default) is the best case for reclamation. --no-await-close
+        // mirrors the pool's fire-and-forget close (closeOne: db.close().catch())
+        // so a leak that only manifests without awaiting is not hidden.
+        if (AWAIT_CLOSE) {
+          try {
+            await conn.close();
+            await db.close();
+          } catch {
+            /* ignore */
+          }
+        } else {
+          conn.close().catch(() => {});
+          db.close().catch(() => {});
+        }
+      }
+    }
+    gc();
+    // Longer settle when not awaiting close, so fire-and-forget native teardown
+    // has a chance to complete before the RSS sample (avoids a false PLATEAU).
+    await sleep(AWAIT_CLOSE ? 20 : 200);
+    const rss = rssMb();
+    series.push(rss);
+    console.error(`[fts-rss] cycle ${String(cycle + 1).padStart(3)}/${CYCLES}  rssMB=${rss}`);
+  }
+
+  fs.rmSync(root, { recursive: true, force: true });
+  return { baseline, series, corpus: `${REPOS}×${ROWS} rows, native, awaitClose=${AWAIT_CLOSE}` };
+}
+
+// ── VIA-POOL mode (real gitnexus pool from compiled dist) ───────────────────
+async function runViaPool(lbugPath) {
+  if (!fs.existsSync(lbugPath)) {
+    console.error(`[fts-rss] --via-pool path not found: ${lbugPath}`);
+    process.exit(2);
+  }
+  // Compiled dist is required (the pool pulls the native addon + many modules).
+  const distUrl = new URL('../../dist/core/lbug/pool-adapter.js', import.meta.url);
+  let pool;
+  try {
+    pool = await import(distUrl.href);
+  } catch (e) {
+    console.error(
+      `[fts-rss] could not import compiled pool-adapter (${e?.message}). ` +
+        `Run \`node scripts/build.js\` first, or use NATIVE mode.`,
+    );
+    process.exit(2);
+  }
+  const { initLbug, executeParameterized, closeLbug } = pool;
+  console.error(
+    `[fts-rss] VIA-POOL on ${lbugPath} × ${CYCLES} cycles ` +
+      `(explicit closeLbug+initLbug per cycle = forced evict→reload)`,
+  );
+
+  // Probe ALL FTS indexes the analyzed graph carries (mirrors fts-schema.ts
+  // FTS_INDEXES) so the per-cycle FTS arena load matches production, not a
+  // 2-of-5 subset that would understate it.
+  const FTS_INDEXES = [
+    { table: 'File', indexName: 'file_fts' },
+    { table: 'Function', indexName: 'function_fts' },
+    { table: 'Class', indexName: 'class_fts' },
+    { table: 'Method', indexName: 'method_fts' },
+    { table: 'Interface', indexName: 'interface_fts' },
+  ];
+
+  const series = [];
+  gc();
+  const baseline = rssMb();
+  console.error(`[fts-rss] baseline RSS=${baseline}MB`);
+
+  for (let cycle = 0; cycle < CYCLES; cycle++) {
+    try {
+      await initLbug(lbugPath, lbugPath);
+      const q = QUERIES[cycle % QUERIES.length];
+      for (const { table, indexName } of FTS_INDEXES) {
+        await executeParameterized(
+          lbugPath,
+          `CALL QUERY_FTS_INDEX('${table}', '${indexName}', $q) RETURN node.id AS id, score ORDER BY score DESC LIMIT 20`,
+          { q },
+        ).catch(() => []); // index may not exist for this graph — that's fine
+      }
+      await closeLbug(lbugPath); // force eviction → next cycle reopens + re-LOADs fts
+    } catch (e) {
+      console.error(`[fts-rss] pool cycle ${cycle} error: ${e?.message || e}`);
+    }
+    gc();
+    // closeLbug fires a fire-and-forget native close (pool closeOne:
+    // db.close().catch()), so settle longer than NATIVE's awaited close to let
+    // native teardown finish before sampling — else a real leak reads PLATEAU.
+    await sleep(200);
+    const rss = rssMb();
+    series.push(rss);
+    console.error(`[fts-rss] cycle ${String(cycle + 1).padStart(3)}/${CYCLES}  rssMB=${rss}`);
+  }
+  await closeLbug().catch(() => {});
+  return { baseline, series, corpus: `via-pool ${path.basename(path.dirname(lbugPath))}` };
+}
+
+// ── verdict ─────────────────────────────────────────────────────────────────
+function verdict({ baseline, series, corpus }) {
+  const third = Math.max(1, Math.floor(series.length / 3));
+  const firstMed = median(series.slice(0, third));
+  const lastMed = median(series.slice(-third));
+  const delta = lastMed - firstMed;
+  const slope = slopeMbPerCycle(series);
+
+  // All label logic lives in the pure, unit-tested classifier (fts-rss-verdict.mjs):
+  // epsilon-first flat→PLATEAU, decelerated→PLATEAU, sustained-sub-floor→INCONCLUSIVE,
+  // ≥floor sustained→CLIMB, step→INCONCLUSIVE; floor scales with the working-set
+  // growth (peak−baseline), not the pre-DB baseline RSS.
+  const {
+    verdict: label,
+    firstHalfSlope,
+    secondHalfSlope,
+    decelRatio,
+    floor,
+    stepDiscontinuity,
+    maxJump,
+    peak,
+  } = classifyVerdict(series, baseline);
+
+  console.log('\n==================== FTS evict→reload RSS verdict ====================');
+  console.log(`corpus: ${corpus}`);
+  console.log(`samples (MB): ${series.join(' ')}`);
+  console.log(
+    `baseline=${baseline}  firstThirdMed=${firstMed}  lastThirdMed=${lastMed}  delta=${delta}MB  ` +
+      `peak=${peak}  overallSlope=${slope.toFixed(2)}  firstHalfSlope=${firstHalfSlope.toFixed(2)}  ` +
+      `secondHalfSlope=${secondHalfSlope.toFixed(2)}MB/cycle  floor=${floor.toFixed(2)}  decelRatio=${decelRatio.toFixed(2)}  ` +
+      `maxJump=${maxJump}MB  step=${stepDiscontinuity}  cycles=${series.length}`,
+  );
+  if (label === 'CLIMB') {
+    console.log(
+      'VERDICT: CLIMB — the per-cycle increment is SUSTAINED (second-half slope ≈ first-half),\n' +
+        '         i.e. RSS rises ~linearly with no decay. The native FTS arena is NOT reclaimed\n' +
+        '         by db.close(); the leak is real over a long-lived session.\n' +
+        '         → plan U4 (worker/process isolation of the FTS read path) is JUSTIFIED.',
+    );
+  } else if (label === 'PLATEAU') {
+    console.log(
+      `VERDICT: PLATEAU at this corpus (${corpus}) — the per-cycle increment DECAYS to flat\n` +
+        '         (second-half slope below the noise floor). db.close() reclaims the FTS arena;\n' +
+        '         footprint is bounded (and the pool further caps it at MAX_POOL_SIZE). No\n' +
+        '         unbounded leak. Caveat: synthetic fixture — confirm with a --via-pool run\n' +
+        '         against a real large analyzed repo before fully closing plan U4.',
+    );
+  } else {
+    console.log(
+      `VERDICT: INCONCLUSIVE at this corpus (${corpus}) — the run is noisy (step discontinuity)\n` +
+        '         or still decelerating without reaching flat, so neither a clean PLATEAU nor a\n' +
+        '         sustained linear CLIMB can be asserted. NATIVE synthetic runs do not resolve\n' +
+        '         this reliably at scale. The definitive test is a --via-pool run against a real\n' +
+        '         large analyzed repo over many cycles (with GITNEXUS_POOL_RSS_TRACE=1). Plan U4\n' +
+        '         stays GATED — neither closed nor built on this evidence.',
+    );
+  }
+  console.log(
+    `MACHINE: ${JSON.stringify({ mode: VIA_POOL ? 'via-pool' : 'native', corpus, baseline, firstMed, lastMed, delta, overallSlope: Number(slope.toFixed(3)), firstHalfSlope: Number(firstHalfSlope.toFixed(3)), secondHalfSlope: Number(secondHalfSlope.toFixed(3)), floor: Number(floor.toFixed(3)), decelRatio: Number(decelRatio.toFixed(3)), maxJump, stepDiscontinuity, peak, cycles: series.length, verdict: label })}`,
+  );
+  console.log('=====================================================================\n');
+}
+
+// ── main ────────────────────────────────────────────────────────────────────
+(async () => {
+  const result = VIA_POOL ? await runViaPool(VIA_POOL) : await runNative();
+  verdict(result);
+  process.exit(0);
+})().catch((e) => {
+  console.error('[fts-rss] fatal:', e?.stack || e);
+  process.exit(1);
+});

package/scripts/bench/fts-rss-verdict.mjs

@@ -0,0 +1,105 @@
+// Pure, side-effect-free verdict classifier for the FTS evict→reload RSS bench
+// (fts-evict-reload-rss.mjs). Extracted so it can be unit-tested WITHOUT importing
+// the native LadybugDB addon or running the bench — this module has zero imports
+// and zero module-scope side effects. Do not add imports or top-level statements.
+//
+// The discriminant between a real leak and allocator warmup is SLOPE DECELERATION,
+// not total delta. A true per-reload leak (stranded FTS arena) rises ~linearly:
+// the second-half slope stays ≈ the first-half slope. Allocator working-set warmup
+// rises then flattens: the second-half slope decays to a fraction of the first.
+//
+// Thresholds:
+//   EPSILON (~0.1 MB/cycle) — below this the tail is effectively flat (no leak).
+//   SUSTAIN_FLOOR (0.5 MB/cycle) — the base noise floor.
+//   The floor SCALES with the working-set growth (peak − baseline), NOT the pre-DB
+//     `baseline` RSS: baseline is interpreter/addon overhead (and is LARGER in
+//     --via-pool mode), so a baseline-keyed floor would inflate and HIDE leaks. A
+//     bigger fixture has a bigger arena and bigger per-cycle noise, so the floor
+//     rises with the working set: floor = SUSTAIN_FLOOR · max(1, (peak−baseline)/REF).
+
+export const EPSILON_MB_PER_CYCLE = 0.1;
+export const SUSTAIN_FLOOR = 0.5;
+// Reference working-set (MB) at which the floor equals SUSTAIN_FLOOR; the floor
+// scales up linearly for larger arenas. ~200 MB ≈ a small FTS fixture's footprint.
+export const FLOOR_REF_WORKINGSET_MB = 200;
+
+export function median(xs) {
+  const s = [...xs].sort((a, b) => a - b);
+  const m = Math.floor(s.length / 2);
+  return s.length % 2 ? s[m] : Math.round((s[m - 1] + s[m]) / 2);
+}
+
+export function slopeMbPerCycle(series) {
+  // Least-squares slope of rss vs cycle index.
+  const n = series.length;
+  if (n < 2) return 0;
+  const xs = series.map((_, i) => i);
+  const xMean = xs.reduce((a, b) => a + b, 0) / n;
+  const yMean = series.reduce((a, b) => a + b, 0) / n;
+  let num = 0;
+  let den = 0;
+  for (let i = 0; i < n; i++) {
+    num += (xs[i] - xMean) * (series[i] - yMean);
+    den += (xs[i] - xMean) ** 2;
+  }
+  return den === 0 ? 0 : num / den;
+}
+
+/**
+ * Classify an RSS-per-cycle series into PLATEAU / CLIMB / INCONCLUSIVE.
+ * Pure: no I/O, no globals. `baseline` is the pre-DB RSS; `peak` defaults to the
+ * series max. Returns the label plus the diagnostics the bench prints.
+ */
+export function classifyVerdict(series, baseline, peak = Math.max(...series)) {
+  const cycles = series.length;
+  const half = Math.max(1, Math.floor(cycles / 2));
+  const firstHalfSlope = slopeMbPerCycle(series.slice(0, half));
+  const secondHalfSlope = slopeMbPerCycle(series.slice(-half));
+  const decelRatio = secondHalfSlope / Math.max(firstHalfSlope, 1e-9);
+
+  // Step discontinuity: a single cycle-to-cycle jump far larger than the typical
+  // per-cycle delta — a one-time allocator/arena reservation (then flat), not a
+  // per-reload leak, but a noisy run we won't claim a clean result on.
+  const deltas = series.slice(1).map((v, i) => v - series[i]);
+  const absDeltas = deltas.map(Math.abs).sort((a, b) => a - b);
+  const medAbsDelta = absDeltas.length ? absDeltas[Math.floor(absDeltas.length / 2)] : 0;
+  const maxJump = deltas.length ? Math.max(...deltas) : 0;
+  const stepDiscontinuity = maxJump > Math.max(30, 5 * Math.max(medAbsDelta, 1));
+
+  // Working-set-scaled floor (see header). Guard against a negative working set.
+  const workingSet = Math.max(0, peak - baseline);
+  const floor = SUSTAIN_FLOOR * Math.max(1, workingSet / FLOOR_REF_WORKINGSET_MB);
+
+  const SUSTAINED = 0.6; // decelRatio at/above which the tail is "not decaying"
+  let verdict;
+  if (stepDiscontinuity) {
+    verdict = 'INCONCLUSIVE';
+  } else if (secondHalfSlope < EPSILON_MB_PER_CYCLE) {
+    // Effectively flat — no leak, regardless of decelRatio (a flat-from-start run
+    // has decelRatio ≈ 1 but is still PLATEAU). This gate is what keeps a true
+    // negative from being over-corrected into INCONCLUSIVE.
+    verdict = 'PLATEAU';
+  } else if (secondHalfSlope >= floor) {
+    // Tail is still substantial: sustained → real leak; decelerating → unresolved.
+    verdict = decelRatio >= SUSTAINED ? 'CLIMB' : 'INCONCLUSIVE';
+  } else if (decelRatio < SUSTAINED) {
+    // Below the floor AND decelerating — warmup converged toward flat → PLATEAU.
+    verdict = 'PLATEAU';
+  } else {
+    // Below the floor but SUSTAINED — a slow steady creep RSS can't distinguish
+    // from noise at this scale. The honest label is "not resolved", NEVER a clean
+    // PLATEAU ("no leak"). This is the headline tri-review fix.
+    verdict = 'INCONCLUSIVE';
+  }
+
+  return {
+    verdict,
+    firstHalfSlope,
+    secondHalfSlope,
+    decelRatio,
+    floor,
+    stepDiscontinuity,
+    maxJump,
+    peak,
+  };
+}

package/scripts/build-tree-sitter-kotlin.cjs

@@ -0,0 +1,74 @@
+#!/usr/bin/env node
+/**
+ * Probe tree-sitter-kotlin native-binding availability at install time.
+ *
+ * Unlike Dart/Proto/Swift (vendored under vendor/ and materialized into
+ * node_modules/ at postinstall), tree-sitter-kotlin is a third-party npm
+ * `optionalDependency`. It ships SOURCE ONLY — no upstream `prebuilds/` dir —
+ * and its own `install` script runs `node-gyp-build`, which compiles the
+ * native binding from source via node-gyp. On a host without a C/C++ toolchain
+ * that build soft-fails: npm skips the optional dependency and the `gitnexus`
+ * install still succeeds. This probe surfaces a single, friendly install-time
+ * warning when the Kotlin binding is unavailable — whether npm pruned the
+ * optional dependency after a toolchain-less build failure (its dir is gone,
+ * which is the common case) or the dir survives but the binding won't load —
+ * instead of leaving a raw node-gyp error or a first-use runtime failure as the
+ * only signal. A deliberate opt-out (`--omit=optional`) stays silent. The probe
+ * does not copy, register, or mutate anything; the runtime require() path in
+ * parser-loader does the actual load. This probe MUST NEVER throw or exit
+ * non-zero — it must never break `gitnexus` install.
+ */
+const fs = require('fs');
+const path = require('path');
+
+if (process.env.GITNEXUS_SKIP_OPTIONAL_GRAMMARS === '1') {
+  console.warn(
+    '[tree-sitter-kotlin] Skipping native-binding probe (GITNEXUS_SKIP_OPTIONAL_GRAMMARS=1).',
+  );
+  process.exit(0);
+}
+
+const kotlinDir = path.join(__dirname, '..', 'node_modules', 'tree-sitter-kotlin');
+
+// `--omit=optional` / `--no-optional` / `.npmrc omit=optional` surface to
+// lifecycle scripts as `npm_config_omit` containing `optional` (a comma- or
+// space-separated list, e.g. `dev,optional`). That is a deliberate opt-out, so
+// an absent package for that reason should stay silent. Any OTHER absence means
+// npm attempted the optional dependency's native build and pruned the package
+// after it soft-failed (the toolchain-less case) — exactly when the guidance
+// below is worth surfacing.
+const omitsOptional = /(^|[,\s])optional([,\s]|$)/.test(process.env.npm_config_omit || '');
+
+function warnKotlinUnavailable(err) {
+  if (err) {
+    console.warn('[tree-sitter-kotlin] Native-binding probe failed:', err.message);
+  }
+  console.warn(
+    '[tree-sitter-kotlin] Kotlin (.kt/.kts) parsing will be unavailable. Non-Kotlin functionality is unaffected.',
+  );
+  console.warn(
+    '[tree-sitter-kotlin] This is expected on hosts without a C/C++ toolchain: tree-sitter-kotlin ships source only (no upstream prebuilt binaries) and compiles via node-gyp at install. Set GITNEXUS_SKIP_OPTIONAL_GRAMMARS=1 to skip this probe.',
+  );
+}
+
+try {
+  if (!fs.existsSync(path.join(kotlinDir, 'bindings', 'node', 'index.js'))) {
+    // The package never materialized. If the user deliberately omitted optional
+    // dependencies, stay silent — they opted out. Otherwise npm pruned the
+    // package after its native build soft-failed (no toolchain), and this is the
+    // dominant real-world failure case: surface the guidance the raw node-gyp
+    // error would otherwise be the only signal of.
+    if (!omitsOptional) {
+      warnKotlinUnavailable();
+    }
+    process.exit(0);
+  }
+
+  const nodeGypBuild = require('node-gyp-build');
+  nodeGypBuild(kotlinDir);
+} catch (err) {
+  // The package is present but its native binding can't be loaded (e.g. the dir
+  // survived with --ignore-scripts, or a partial/ABI-mismatched build).
+  warnKotlinUnavailable(err);
+  process.exit(0);
+}

package/scripts/install-duckdb-extension.mjs

@@ -14,7 +14,7 @@ function parseLbugMaxDbSize(raw) {
   return Math.floor(parsed);
 }
 
-async function installDuckDbExtension(extensionName) {
+async function installDuckDbExtension(extensionName, verifyOnly = false) {
   if (!extensionName || !EXTENSION_NAME_PATTERN.test(extensionName)) {
     throw new Error(`Invalid DuckDB extension name: ${extensionName ?? '<missing>'}`);
   }
@@ -22,9 +22,11 @@ async function installDuckDbExtension(extensionName) {
   const require = createRequire(import.meta.url);
   const lbugModule = require('@ladybugdb/core');
   const lbug = lbugModule.default ?? lbugModule;
-  const lbugMaxDbSize = parseLbugMaxDbSize(
-    process.argv[3] ?? process.env.GITNEXUS_LBUG_MAX_DB_SIZE,
-  );
+  // argv[3] is the optional positional size; ignore it when it is actually a
+  // flag token (e.g. `--verify-only`) and fall back to the env default.
+  const sizeArg =
+    process.argv[3] && !process.argv[3].startsWith('--') ? process.argv[3] : undefined;
+  const lbugMaxDbSize = parseLbugMaxDbSize(sizeArg ?? process.env.GITNEXUS_LBUG_MAX_DB_SIZE);
 
   const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'gitnexus-ext-install-'));
   const dbPath = path.join(tmpDir, 'install.lbug');
@@ -34,7 +36,18 @@ async function installDuckDbExtension(extensionName) {
   try {
     db = new lbug.Database(dbPath, 0, false, false, lbugMaxDbSize);
     conn = new lbug.Connection(db);
-    await conn.query(`INSTALL ${extensionName}`);
+    if (verifyOnly) {
+      // Prove a previously-baked extension is resolvable by a FRESH process
+      // under the current HOME (the runtime `LOAD EXTENSION` path) — no INSTALL,
+      // no network. Used as a Docker build-time gate so a HOME/extension-dir
+      // mismatch fails the build instead of silently degrading search at runtime.
+      await conn.query(`LOAD EXTENSION ${extensionName}`);
+      console.log(
+        `[install-ext] LOAD-only verify OK for '${extensionName}' (HOME=${process.env.HOME})`,
+      );
+    } else {
+      await conn.query(`INSTALL ${extensionName}`);
+    }
   } finally {
     if (conn) await conn.close().catch(() => {});
     if (db) await db.close().catch(() => {});
@@ -42,7 +55,10 @@ async function installDuckDbExtension(extensionName) {
   }
 }
 
-installDuckDbExtension(process.argv[2] ?? process.env.GITNEXUS_LBUG_EXTENSION_NAME).catch((err) => {
+installDuckDbExtension(
+  process.argv[2] ?? process.env.GITNEXUS_LBUG_EXTENSION_NAME,
+  process.argv.includes('--verify-only'),
+).catch((err) => {
   console.error(err instanceof Error ? (err.stack ?? err.message) : String(err));
   process.exitCode = 1;
 });