gitnexus 1.6.7 → 1.6.8-rc.10

package/dist/core/ingestion/workers/parse-worker.js

@@ -11,15 +11,17 @@ import Go from 'tree-sitter-go';
 import Rust from 'tree-sitter-rust';
 import PHP from 'tree-sitter-php';
 import Ruby from 'tree-sitter-ruby';
-import { createRequire } from 'node:module';
+import { requireVendoredGrammar } from '../../tree-sitter/vendored-grammars.js';
 import { SupportedLanguages } from '../../../_shared/index.js';
 import { getProvider } from '../languages/index.js';
 import { getTreeSitterBufferSize, getTreeSitterContentByteLength, TREE_SITTER_MAX_BUFFER, } from '../constants.js';
 import { ARRAY_METHOD_HOC_BLOCKLIST_SET, DEFAULT_EXPORT_IDENTIFIER_BLOCKLIST_SET, deriveDefaultExportHocName, } from '../ts-js-hoc-utils.js';
 import { parseSourceSafe } from '../../tree-sitter/safe-parse.js';
+import { postResultCloneSafe } from './post-result.js';
+import { mergeResult } from './result-merge.js';
 // ── Worker grammar loading — enforcement boundary (#2091/#2093, #2101) ───────
-// The worker maintains its own grammar table (the guarded `_require`s below +
-// `languageMap`) and intentionally does NOT consult the runtime
+// The worker maintains its own grammar table (the guarded vendored-grammar
+// loads below + `languageMap`) and intentionally does NOT consult the runtime
 // `GITNEXUS_SKIP_OPTIONAL_GRAMMARS` opt-out. It does not need to: the MAIN
 // THREAD's `parseableScanned` filter (pipeline-phases/parse-impl.ts, gated on
 // `parser-loader.isLanguageAvailable`, which honors the runtime opt-out and a
@@ -30,33 +32,29 @@ import { parseSourceSafe } from '../../tree-sitter/safe-parse.js';
 // `isLanguageAvailable` must re-introduce the gate here. (The cleaner end-state
 // — routing this table through `parser-loader.getLanguageGrammar` so there is
 // one loader — is the deferred Tier-1 consolidation.)
-// tree-sitter-swift is an optionalDependency — may not be installed
-const _require = createRequire(import.meta.url);
+// Swift/Dart/Kotlin/C are vendored grammars loaded from `vendor/` by absolute
+// path (NEVER copied into node_modules — see vendored-grammars.ts / #2111). Each
+// may be absent on a platform without a prebuild or a toolchain-less /
+// `--ignore-scripts` install, so every load is guarded so a missing binding
+// cannot crash the worker at module-load (#2091/#2093, #2116).
 let Swift = null;
 try {
-    Swift = _require('tree-sitter-swift');
+    Swift = requireVendoredGrammar('tree-sitter-swift');
 }
 catch { }
-// tree-sitter-dart is an optionalDependency — may not be installed
 let Dart = null;
 try {
-    Dart = _require('tree-sitter-dart');
+    Dart = requireVendoredGrammar('tree-sitter-dart');
 }
 catch { }
-// tree-sitter-kotlin is an optionalDependency — may not be installed
 let Kotlin = null;
 try {
-    Kotlin = _require('tree-sitter-kotlin');
+    Kotlin = requireVendoredGrammar('tree-sitter-kotlin');
 }
 catch { }
-// tree-sitter-c is now vendored prebuild-only (#2116) and may be absent on a
-// toolchain-less / `--ignore-scripts` install. Guard it like Swift/Dart/Kotlin so
-// a missing binding cannot crash the worker at module-load (#2091/#2093); the
-// main-thread `isLanguageAvailable` filter keeps C files from being dispatched
-// here when the entry is absent.
 let C = null;
 try {
-    C = _require('tree-sitter-c');
+    C = requireVendoredGrammar('tree-sitter-c');
 }
 catch { }
 import { getLanguageFromFilename } from '../../../_shared/index.js';
@@ -678,6 +676,7 @@ const ROUTE_DECORATOR_NAMES = new Set([
     'PostMapping',
     'PutMapping',
     'DeleteMapping',
+    'PatchMapping',
 ]);
 // ============================================================================
 // ORM Query Detection (Prisma + Supabase)
@@ -1743,6 +1742,15 @@ const processFileGroup = (files, language, queryString, result, onFileProcessed)
         if (language === SupportedLanguages.Python) {
             extractFastAPIRouterBindings(file.path, parseContent, result.routerIncludes, result.routerImports, (result.routerModuleAliases ??= []));
         }
+        // Language-specific decorator route extraction via provider hook.
+        // The provider's extractDecoratorRoutes walks the AST for framework-specific
+        // route patterns (e.g., Java Spring class-level prefix joining). Routes are
+        // appended to decoratorRoutes for the routes phase to emit as Route nodes.
+        if (provider.extractDecoratorRoutes) {
+            const frameworkRoutes = provider.extractDecoratorRoutes(tree, file.path, lineOffset);
+            for (const r of frameworkRoutes)
+                result.decoratorRoutes.push(r);
+        }
         // Vue: emit CALLS edges for components used in <template>
         if (language === SupportedLanguages.Vue) {
             const templateComponents = extractTemplateComponents(file.content);
@@ -1783,41 +1791,8 @@ let accumulated = {
     fileCount: 0,
 };
 let cumulativeProcessed = 0;
-// Use a loop instead of push(...spread) to avoid hitting V8's argument limit
-// when merging large result sets (push(...arr) calls apply() under the hood
-// and blows the stack when arr has >~65k elements).
-const appendAll = (target, src) => {
-    for (let i = 0; i < src.length; i++)
-        target.push(src[i]);
-};
-const mergeResult = (target, src) => {
-    appendAll(target.nodes, src.nodes);
-    appendAll(target.relationships, src.relationships);
-    appendAll(target.symbols, src.symbols);
-    appendAll(target.calls, src.calls);
-    appendAll(target.assignments, src.assignments);
-    appendAll(target.routes, src.routes);
-    appendAll(target.fetchCalls, src.fetchCalls);
-    appendAll(target.fetchWrapperDefs, src.fetchWrapperDefs);
-    appendAll(target.decoratorRoutes, src.decoratorRoutes);
-    if (src.routerIncludes)
-        appendAll(target.routerIncludes, src.routerIncludes);
-    if (src.routerImports)
-        appendAll(target.routerImports, src.routerImports);
-    if (src.routerModuleAliases) {
-        target.routerModuleAliases ??= [];
-        appendAll(target.routerModuleAliases, src.routerModuleAliases);
-    }
-    appendAll(target.toolDefs, src.toolDefs);
-    appendAll(target.ormQueries, src.ormQueries);
-    appendAll(target.constructorBindings, src.constructorBindings);
-    appendAll(target.fileScopeBindings, src.fileScopeBindings);
-    appendAll(target.parsedFiles, src.parsedFiles);
-    for (const [lang, count] of Object.entries(src.skippedLanguages)) {
-        target.skippedLanguages[lang] = (target.skippedLanguages[lang] || 0) + count;
-    }
-    target.fileCount += src.fileCount;
-};
+// `mergeResult` (+ its `appendAll`) lives in ./result-merge.ts (extracted so it
+// can be unit-tested without importing this entry module).
 // Signal the pool that worker-side initialization (parser imports, language
 // grammars, type-env setup, all helper modules) is complete and the message
 // handler below is about to be attached. The pool's `waitForWorkerReady`
@@ -1910,7 +1885,7 @@ parentPort.on('message', (msg) => {
                     accumulated.parsedFiles = [];
                 }
             }
-            parentPort.postMessage({ type: 'result', data: accumulated });
+            postResultCloneSafe(accumulated);
             // Reset for potential reuse
             accumulated = {
                 nodes: [],

package/dist/core/ingestion/workers/post-result.d.ts

@@ -0,0 +1,22 @@
+import type { ParseWorkerResult } from './parse-worker.js';
+/**
+ * Deliver the accumulated result to the pool, surviving a non-cloneable value
+ * (#2112). Fast path: post as-is — on a healthy result this is the only thing
+ * that runs, so clone-safety adds zero overhead to normal runs. If structured
+ * clone rejects the payload (a function/symbol leaked into an extraction
+ * record — the reporter's case was a node `properties` value pointing at a
+ * native `toString`), rewrite the boundary-crossing arrays so the result is
+ * cloneable, record the affected paths on `result.skippedPaths`, warn the
+ * operator naming the offending field + file (so the still-unpinned leak is
+ * diagnosable from logs and fixable at source), and re-post.
+ *
+ * Recovery is attempted for ANY first-post failure, not only a `DataCloneError`.
+ * structuredClone invokes getters, and a getter that THROWS surfaces its own
+ * error (a `RangeError`, etc.) — NOT a `DataCloneError` (confirmed against a
+ * real MessageChannel). Gating recovery on `DataCloneError` let such a throw
+ * re-throw past the sanitizer and re-arm, under `POOL_SIZE=1`, the worker-death
+ * cascade this net prevents. The recovery path is wrapped in its own try/catch
+ * so a still-uncloneable re-post fails closed to a primitive-only
+ * `{type:'error'}` DELIBERATELY rather than escaping the worker.
+ */
+export declare function postResultCloneSafe(result: ParseWorkerResult): void;

package/dist/core/ingestion/workers/post-result.js

@@ -0,0 +1,87 @@
+/**
+ * Worker → main result delivery with clone-safety (#2112).
+ *
+ * Extracted from `parse-worker.ts` into its own side-effect-free module so it
+ * can be imported and exercised directly (the parse worker is an entry module:
+ * importing it would construct the parser, post `ready`, and attach the real
+ * message handler). The integration test imports `postResultCloneSafe` from
+ * here to cover the production wiring end to end rather than re-implementing it.
+ */
+import { parentPort } from 'node:worker_threads';
+import { makeWorkerResultCloneSafe } from './clone-safety.js';
+/**
+ * Strict mode (opt-in via `GITNEXUS_STRICT_CLONE=1`, inherited by workers). When
+ * on, a clone failure THROWS with the offending key path instead of silently
+ * sanitizing + delivering — so a leak introduced by a future provider/extractor
+ * change fails LOUDLY (in CI / dev) at its origin rather than being quietly
+ * stripped in production. The silent-recovery behavior is exactly what hid the
+ * original #2112 leak; strict mode removes the silence where we want loudness.
+ * Off in production, where the net's job is to keep the run alive.
+ */
+const STRICT_CLONE = process.env.GITNEXUS_STRICT_CLONE === '1';
+/**
+ * Deliver the accumulated result to the pool, surviving a non-cloneable value
+ * (#2112). Fast path: post as-is — on a healthy result this is the only thing
+ * that runs, so clone-safety adds zero overhead to normal runs. If structured
+ * clone rejects the payload (a function/symbol leaked into an extraction
+ * record — the reporter's case was a node `properties` value pointing at a
+ * native `toString`), rewrite the boundary-crossing arrays so the result is
+ * cloneable, record the affected paths on `result.skippedPaths`, warn the
+ * operator naming the offending field + file (so the still-unpinned leak is
+ * diagnosable from logs and fixable at source), and re-post.
+ *
+ * Recovery is attempted for ANY first-post failure, not only a `DataCloneError`.
+ * structuredClone invokes getters, and a getter that THROWS surfaces its own
+ * error (a `RangeError`, etc.) — NOT a `DataCloneError` (confirmed against a
+ * real MessageChannel). Gating recovery on `DataCloneError` let such a throw
+ * re-throw past the sanitizer and re-arm, under `POOL_SIZE=1`, the worker-death
+ * cascade this net prevents. The recovery path is wrapped in its own try/catch
+ * so a still-uncloneable re-post fails closed to a primitive-only
+ * `{type:'error'}` DELIBERATELY rather than escaping the worker.
+ */
+export function postResultCloneSafe(result) {
+    try {
+        parentPort.postMessage({ type: 'result', data: result });
+        return;
+    }
+    catch {
+        // Fall through to recovery on ANY failure (DataCloneError OR a throwing
+        // getter's own error). A healthy post returned above and never reaches here.
+    }
+    try {
+        // `as unknown as Record<string, unknown>` is the standard widening for a
+        // no-index-signature interface (TS rejects a single-step `as`). The field
+        // sets are typed to `keyof ParseWorkerResult` so renaming a field is a
+        // compile error here, not a silent loss of the drop-whole / skip protection.
+        const { skipped } = makeWorkerResultCloneSafe(result, {
+            dropWholeElement: new Set(['parsedFiles']),
+            skipFields: new Set(['skippedPaths']),
+        });
+        if (skipped.length > 0) {
+            if (STRICT_CLONE) {
+                // Surface the leak loudly with its exact key path(s) instead of
+                // delivering a sanitized result. Routes to the catch below → a
+                // primitive-only {type:'error'} the pool reports, failing CI.
+                const detail = skipped.map((s) => `${s.path}: ${s.reason}`).join('; ');
+                throw new Error(`GITNEXUS_STRICT_CLONE: worker result was not structured-cloneable — ${detail}`);
+            }
+            result.skippedPaths = [...(result.skippedPaths ?? []), ...skipped];
+            const sample = skipped
+                .slice(0, 5)
+                .map((s) => `${s.path} (${s.reason})`)
+                .join('; ');
+            const more = skipped.length > 5 ? ` …and ${skipped.length - 5} more` : '';
+            if (parentPort) {
+                parentPort.postMessage({
+                    type: 'warning',
+                    message: `Sanitized ${skipped.length} file(s) with non-serializable parse output before delivery: ${sample}${more}`,
+                });
+            }
+        }
+        parentPort.postMessage({ type: 'result', data: result });
+    }
+    catch (err) {
+        const e = err instanceof Error ? err : new Error(String(err));
+        parentPort.postMessage({ type: 'error', error: e.message, errorStack: e.stack });
+    }
+}

package/dist/core/ingestion/workers/result-merge.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Merge of accumulated parse-worker results (sub-batch result → the conceptual
+ * job's running accumulator).
+ *
+ * Extracted from `parse-worker.ts` into this side-effect-free module so the
+ * merge can be imported and unit-tested directly — the parse worker is an entry
+ * module (importing it constructs the parser, posts `ready`, and attaches the
+ * real MessagePort handler), so a main-thread test cannot import a helper out of
+ * it. Mirrors the `post-result.ts` extraction.
+ *
+ * `import type` of `ParseWorkerResult` is erased at runtime, so there is no
+ * import cycle with `parse-worker.ts` (which imports this module's runtime).
+ */
+import type { ParseWorkerResult } from './parse-worker.js';
+/**
+ * Merge `src` into `target` in place: append every boundary-crossing array,
+ * sum the per-language skip counts, union the clone-safety `skippedPaths`, and
+ * add the file count.
+ */
+export declare const mergeResult: (target: ParseWorkerResult, src: ParseWorkerResult) => void;

package/dist/core/ingestion/workers/result-merge.js

@@ -0,0 +1,43 @@
+// Use a loop instead of push(...spread) to avoid hitting V8's argument limit
+// when merging large result sets (push(...arr) calls apply() under the hood
+// and blows the stack when arr has >~65k elements).
+const appendAll = (target, src) => {
+    for (let i = 0; i < src.length; i++)
+        target.push(src[i]);
+};
+/**
+ * Merge `src` into `target` in place: append every boundary-crossing array,
+ * sum the per-language skip counts, union the clone-safety `skippedPaths`, and
+ * add the file count.
+ */
+export const mergeResult = (target, src) => {
+    appendAll(target.nodes, src.nodes);
+    appendAll(target.relationships, src.relationships);
+    appendAll(target.symbols, src.symbols);
+    appendAll(target.calls, src.calls);
+    appendAll(target.assignments, src.assignments);
+    appendAll(target.routes, src.routes);
+    appendAll(target.fetchCalls, src.fetchCalls);
+    appendAll(target.fetchWrapperDefs, src.fetchWrapperDefs);
+    appendAll(target.decoratorRoutes, src.decoratorRoutes);
+    if (src.routerIncludes)
+        appendAll(target.routerIncludes, src.routerIncludes);
+    if (src.routerImports)
+        appendAll(target.routerImports, src.routerImports);
+    if (src.routerModuleAliases) {
+        target.routerModuleAliases ??= [];
+        appendAll(target.routerModuleAliases, src.routerModuleAliases);
+    }
+    appendAll(target.toolDefs, src.toolDefs);
+    appendAll(target.ormQueries, src.ormQueries);
+    appendAll(target.constructorBindings, src.constructorBindings);
+    appendAll(target.fileScopeBindings, src.fileScopeBindings);
+    appendAll(target.parsedFiles, src.parsedFiles);
+    for (const [lang, count] of Object.entries(src.skippedLanguages)) {
+        target.skippedLanguages[lang] = (target.skippedLanguages[lang] || 0) + count;
+    }
+    if (src.skippedPaths && src.skippedPaths.length > 0) {
+        (target.skippedPaths ??= []).push(...src.skippedPaths);
+    }
+    target.fileCount += src.fileCount;
+};

package/dist/core/ingestion/workers/worker-pool.d.ts

@@ -273,6 +273,12 @@ export declare function resolveAutoPoolSize(): number;
  *   time spent across all attempts/splits/retries. When the budget is
  *   exhausted, the pool surfaces the in-flight path via `WorkerPoolDispatchError`
  *   instead of letting timeouts compound indefinitely.
+ *
+ * Upstream of these layers, the parse worker self-sanitizes a result that the
+ * structured-clone algorithm can't serialize (#2112) — stripping or dropping
+ * the offending value and reporting the affected paths on the result — so a
+ * single non-cloneable value can't masquerade as a worker death and exhaust a
+ * slot's respawn budget here.
  */
 export declare const createWorkerPool: (workerUrl: URL, poolSize?: number, options?: WorkerPoolOptions) => WorkerPool;
 export {};

package/dist/core/ingestion/workers/worker-pool.js

@@ -523,6 +523,12 @@ function createJobs(items, maxItems, maxBytes, timeoutMs, chunkHash) {
  *   time spent across all attempts/splits/retries. When the budget is
  *   exhausted, the pool surfaces the in-flight path via `WorkerPoolDispatchError`
  *   instead of letting timeouts compound indefinitely.
+ *
+ * Upstream of these layers, the parse worker self-sanitizes a result that the
+ * structured-clone algorithm can't serialize (#2112) — stripping or dropping
+ * the offending value and reporting the affected paths on the result — so a
+ * single non-cloneable value can't masquerade as a worker death and exhaust a
+ * slot's respawn budget here.
  */
 export const createWorkerPool = (workerUrl, poolSize, options) => {
     // Validate worker script exists before spawning to prevent uncaught
@@ -1313,14 +1319,19 @@ export const createWorkerPool = (workerUrl, poolSize, options) => {
                     if (settled || stopped)
                         return;
                     // Native postMessage delivers POJO directly via Node's
-                    // structured clone. V8 deserialization failures (malformed
-                    // frame, non-cloneable value) surface as a `messageerror`
-                    // event handled below — they never reach this handler. The
-                    // only thing we need to guard for here is a worker that
-                    // sends a message without a `type` discriminant (a bug in
-                    // the worker, not a wire-format issue): without the guard
-                    // `null.type` would throw a TypeError out of the
-                    // EventEmitter listener → uncaughtException on the main
+                    // structured clone. Two distinct clone failure modes exist,
+                    // and NEITHER reaches this handler: (1) a SENDER-side
+                    // non-cloneable value (a function/symbol that leaked into the
+                    // result) throws a synchronous `DataCloneError` on the
+                    // worker's own postMessage — the parse worker self-sanitizes
+                    // such results before delivery (#2112) and falls back to a
+                    // primitive-only `{type:'error'}` if it still can't serialize;
+                    // (2) a RECEIVER-side deserialization failure surfaces as a
+                    // `messageerror` event handled below. The only thing THIS
+                    // handler guards is a worker that sends a message without a
+                    // `type` discriminant (a worker bug, not a wire-format issue):
+                    // without the guard `null.type` would throw a TypeError out of
+                    // the EventEmitter listener → uncaughtException on the main
                     // thread.
                     const msg = raw;
                     if (msg === null || typeof msg !== 'object' || typeof msg.type !== 'string') {
@@ -1417,12 +1428,15 @@ export const createWorkerPool = (workerUrl, poolSize, options) => {
                             `Likely OOM or native addon failure${inFlightSuffix}.`, excludes);
                     }
                 };
-                // `messageerror` fires when V8 fails to deserialize a postMessage
-                // payload (e.g., the worker tries to send a non-cloneable value
-                // back, or structured-clone hits an unsupported shape). The worker
-                // stays ALIVE but the message is lost — without this handler the
-                // pool would sit on the dropped message until the idle timeout
-                // expires. Treat it as worker death so the resilience layers fire:
+                // `messageerror` fires when V8 fails to DESERIALIZE a postMessage
+                // payload on THIS (receiver) side — a value that serialized on the
+                // worker but can't be reconstructed here. (A non-cloneable value on
+                // the SENDER side instead throws a synchronous DataCloneError on the
+                // worker's own postMessage; that path is caught and sanitized
+                // worker-side (#2112) and never arrives here.) The worker stays ALIVE
+                // but the message is lost — without this handler the pool would sit on
+                // the dropped message until the idle timeout expires. Treat it as
+                // worker death so the resilience layers fire:
                 // requeue the remainder via `recoverAndResume`, attribute the
                 // in-flight file from the `starting-file` signal (if observed),
                 // and let the per-slot respawn budget and circuit breaker decide

package/dist/core/lbug/lbug-adapter.d.ts

@@ -233,6 +233,25 @@ export declare const loadVectorExtension: (targetConn?: lbug.Connection, opts?:
  * @param stemmer - Stemming algorithm (default: 'porter')
  */
 export declare const createFTSIndex: (tableName: string, indexName: string, properties: string[], stemmer?: string) => Promise<void>;
+/**
+ * Create the HNSW vector index on the CodeEmbedding table.
+ *
+ * MUST run via `conn.query()` (here through `queryAndDrain`), NOT through the
+ * prepared `executeQuery`/`conn.prepare()` path: `CALL CREATE_VECTOR_INDEX(...)`
+ * compiles to multiple statements, which LadybugDB cannot prepare — it fails
+ * with "Connection Exception: We do not support prepare multiple statements."
+ * Routing index creation through `executeQuery` (prepared) is exactly what
+ * broke vector-index creation during `analyze` (#2114; the singleton
+ * `executeQuery` was switched to the prepared path in #1655 while FTS index
+ * creation kept using `conn.query()`, which is why FTS survived and VECTOR did
+ * not). Mirrors `createFTSIndex` above.
+ *
+ * Returns `true` on success (or when the index already exists — idempotent so
+ * incremental re-runs don't spuriously downgrade to exact scan), `false` when
+ * the VECTOR extension is unavailable or the connection is read-only. Any other
+ * failure propagates so the caller can log it.
+ */
+export declare const createVectorIndex: () => Promise<boolean>;
 /**
  * Lazy-create an FTS index, caching the fact in-process.
  *

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

@@ -8,7 +8,7 @@ import os from 'os';
 import crypto from 'crypto';
 import lbug from '@ladybugdb/core';
 import { closeQueryResults } from './query-result-utils.js';
-import { NODE_TABLES, REL_TABLE_NAME, SCHEMA_QUERIES, EMBEDDING_TABLE_NAME, STALE_HASH_SENTINEL, } from './schema.js';
+import { NODE_TABLES, REL_TABLE_NAME, SCHEMA_QUERIES, EMBEDDING_TABLE_NAME, CREATE_VECTOR_INDEX_QUERY, STALE_HASH_SENTINEL, } from './schema.js';
 import { streamAllCSVsToDisk } from './csv-generator.js';
 import { extensionManager } from './extension-loader.js';
 import { closeLbugConnection, isDbBusyError, isOpenRetryExhausted, isWalCorruptionError, openLbugConnection, toNativeSafePath, WAL_RECOVERY_SUGGESTION, waitForWindowsHandleRelease, } from './lbug-config.js';
@@ -119,6 +119,11 @@ let currentDbPath = null;
 let currentDbReadOnly = false;
 let ftsLoaded = false;
 let vectorExtensionLoaded = false;
+// In-process guard so a repeated createVectorIndex() within one connection
+// lifetime skips the DB round-trip (mirrors ensuredFTSIndexes). Reset wherever
+// vectorExtensionLoaded resets, so it can never stay true against a swapped or
+// closed connection.
+let vectorIndexEnsured = false;
 /**
  * In-process cache of FTS indexes observed against the current singleton
  * connection. Avoids repeated `CALL CREATE_FTS_INDEX` calls, which can trip
@@ -494,6 +499,7 @@ const resetOpenConnectionState = () => {
     currentDbPath = null;
     ftsLoaded = false;
     vectorExtensionLoaded = false;
+    vectorIndexEnsured = false;
     ensuredFTSIndexes.clear();
 };
 const runSchemaCreationQueries = async (dbPath) => {
@@ -572,6 +578,7 @@ export const withLbugDb = async (dbPath, operation, options = {}) => {
                 currentDbPath = null;
                 ftsLoaded = false;
                 vectorExtensionLoaded = false;
+                vectorIndexEnsured = false;
                 ensuredFTSIndexes.clear();
             });
             // Sleep outside the lock — no need to block others while waiting
@@ -596,6 +603,7 @@ const doInitLbug = async (dbPath, readOnly = false) => {
         currentDbPath = null;
         ftsLoaded = false;
         vectorExtensionLoaded = false;
+        vectorIndexEnsured = false;
         ensuredFTSIndexes.clear();
     }
     // ---------------------------------------------------------------------------
@@ -1476,6 +1484,7 @@ export const closeLbug = async () => {
     currentDbPath = null;
     ftsLoaded = false;
     vectorExtensionLoaded = false;
+    vectorIndexEnsured = false;
     ensuredFTSIndexes.clear();
 };
 export const isLbugReady = () => conn !== null && db !== null;
@@ -1708,6 +1717,52 @@ export const createFTSIndex = async (tableName, indexName, properties, stemmer =
         throw e;
     }
 };
+/**
+ * Create the HNSW vector index on the CodeEmbedding table.
+ *
+ * MUST run via `conn.query()` (here through `queryAndDrain`), NOT through the
+ * prepared `executeQuery`/`conn.prepare()` path: `CALL CREATE_VECTOR_INDEX(...)`
+ * compiles to multiple statements, which LadybugDB cannot prepare — it fails
+ * with "Connection Exception: We do not support prepare multiple statements."
+ * Routing index creation through `executeQuery` (prepared) is exactly what
+ * broke vector-index creation during `analyze` (#2114; the singleton
+ * `executeQuery` was switched to the prepared path in #1655 while FTS index
+ * creation kept using `conn.query()`, which is why FTS survived and VECTOR did
+ * not). Mirrors `createFTSIndex` above.
+ *
+ * Returns `true` on success (or when the index already exists — idempotent so
+ * incremental re-runs don't spuriously downgrade to exact scan), `false` when
+ * the VECTOR extension is unavailable or the connection is read-only. Any other
+ * failure propagates so the caller can log it.
+ */
+export const createVectorIndex = async () => {
+    if (!conn) {
+        throw new Error('LadybugDB not initialized. Call initLbug first.');
+    }
+    // Already built on this connection — skip the round-trip (mirrors createFTSIndex).
+    if (vectorIndexEnsured)
+        return true;
+    if (!(await loadVectorExtension())) {
+        return false;
+    }
+    try {
+        await queryAndDrain(conn, CREATE_VECTOR_INDEX_QUERY);
+        vectorIndexEnsured = true;
+        return true;
+    }
+    catch (e) {
+        const msg = e instanceof Error ? e.message : String(e);
+        // Idempotent: a prior analyze already built the HNSW index.
+        if (msg.includes('already exists')) {
+            vectorIndexEnsured = true;
+            return true;
+        }
+        // Read-only DB (e.g. the MCP query pool): writable analyze owns creation.
+        if (isReadOnlyDbError(e))
+            return false;
+        throw e;
+    }
+};
 /**
  * Lazy-create an FTS index, caching the fact in-process.
  *

package/dist/core/run-analyze.d.ts

@@ -55,6 +55,16 @@ export interface AnalyzeOptions {
      * "main" fallback for non-CLI callers (e.g. the server analyze worker).
      */
     defaultBranch?: string;
+    /**
+     * Index-branch selector (#2106). Distinct from `defaultBranch` (which only
+     * affects generated AGENTS.md/CLAUDE.md base_ref text). When set, this run is
+     * labelled as that branch and routed to a per-branch index slot unless it is
+     * the primary branch. When `undefined`, the branch is auto-detected from the
+     * checked-out HEAD (the flat/primary slot for the first-indexed branch, a
+     * `branches/<slug>/` sub-directory otherwise). Detached HEAD / non-git always
+     * maps to the flat slot.
+     */
+    branch?: string;
     /**
      * User-provided alias for the registry `name` (#829). When set,
      * forwarded to `registerRepo` so the indexed repo is stored under
@@ -78,6 +88,13 @@ export interface AnalyzeOptions {
      * removed); `undefined` defers to the env / auto-formula fallback.
      */
     workerPoolSize?: number;
+    /**
+     * Extra fetch-wrapper function names to treat as HTTP consumers, forwarded to
+     * `PipelineOptions.fetchWrappers` (#1589/#1852 residual). Sourced from the CLI
+     * `.gitnexusrc` `fetchWrappers` list. `undefined`/empty leaves the route
+     * consumer scan unchanged.
+     */
+    fetchWrappers?: string[];
 }
 export interface AnalyzeResult {
     repoName: string;
@@ -102,6 +119,13 @@ export interface AnalyzeResult {
      * the persisted meta surface the degraded state instead of reporting healthy.
      */
     ftsSkipped?: boolean;
+    /**
+     * True when the index this run produced/validated is the primary/flat slot
+     * (#2106 R2). `false` for a non-primary branch index. Lets the CLI skip
+     * repo-root AGENTS.md/CLAUDE.md refreshes (e.g. the base_ref fast-path) for a
+     * branch analyze, mirroring the in-pipeline `if (!placement.branch)` gate.
+     */
+    isPrimaryBranch?: boolean;
 }
 export { deriveEmbeddingMode, DEFAULT_EMBEDDING_NODE_LIMIT } from './embedding-mode.js';
 export type { EmbeddingMode } from './embedding-mode.js';
@@ -117,4 +141,25 @@ export declare const PHASE_LABELS: Record<string, string>;
  * the {@link AnalyzeCallbacks} interface — it never writes to stdout/stderr
  * directly and never calls `process.exit()`.
  */
+/**
+ * Build the primary-inversion warning (#2106 R8), or `undefined` when there is
+ * nothing to warn about. Pure + exported for testing. Both inputs are trimmed
+ * (a diagnostic — a missed warning is low-harm; a false warning is the thing to
+ * avoid). `defaultBranch` is the repo's `origin/HEAD` branch (null when unset,
+ * e.g. fresh clones / CI), `flatOwner` is the branch that owns the flat slot.
+ */
+export declare const primaryInversionWarning: (defaultBranch: string | null | undefined, flatOwner: string | null | undefined) => string | undefined;
+/**
+ * Collect the recorded parse-cache chunk keys across the flat + every branch
+ * meta under a flat `.gitnexus` storage, EXCLUDING `excludeDir` (the current
+ * run's own meta dir) so a single-branch repo collects nothing and its prune
+ * stays byte-identical to today (#2106 R6). `complete` is false when a sibling
+ * meta.json exists but fails to parse — callers then retain the whole shared
+ * cache rather than over-evict another branch's still-live shards. Exported for
+ * testing.
+ */
+export declare const collectBranchCacheKeys: (storagePath: string, excludeDir?: string) => Promise<{
+    keys: Set<string>;
+    complete: boolean;
+}>;
 export declare function runFullAnalysis(repoPath: string, options: AnalyzeOptions, callbacks: AnalyzeCallbacks): Promise<AnalyzeResult>;