gitnexus 1.6.6-rc.21 → 1.6.6-rc.23

package/README.md

@@ -151,7 +151,8 @@ Your AI agent gets these tools automatically:
 ```bash
 gitnexus setup                   # Configure MCP for your editors (one-time)
 gitnexus analyze [path]          # Index a repository (or update stale index)
-gitnexus analyze --force         # Force full re-index
+gitnexus analyze --repair-fts    # Fast path: rebuild/verify only FTS indexes on existing index data
+gitnexus analyze --force         # Full rebuild: re-parse + graph rebuild + FTS rebuild
 gitnexus analyze --embeddings    # Enable embedding generation (slower, better search)
 gitnexus analyze --skip-agents-md  # Preserve custom AGENTS.md/CLAUDE.md gitnexus section edits
 gitnexus analyze --verbose       # Log skipped files when parsers are unavailable

package/dist/cli/analyze.d.ts

@@ -9,6 +9,7 @@
  */
 export interface AnalyzeOptions {
     force?: boolean;
+    repairFts?: boolean;
     /**
      * Embedding generation toggle. Commander parses `--embeddings [limit]` as:
      *   - `undefined` when the flag is omitted

package/dist/cli/analyze.js

@@ -216,6 +216,12 @@ export const analyzeCommand = async (inputPath, options) => {
         }
         process.env.GITNEXUS_EMBEDDING_DEVICE = options.embeddingDevice;
     }
+    if (options?.repairFts && options?.force) {
+        cliError('  Cannot combine `--repair-fts` with `--force`. ' +
+            'Use `--repair-fts` for fast FTS-only repair, or `--force` for a full rebuild.\n');
+        process.exitCode = 1;
+        return;
+    }
     console.log('\n  GitNexus Analyzer\n');
     // `--index-only` is the stronger contract — it suppresses every form of file
     // injection, including community skill writes that `--skills` would normally
@@ -368,9 +374,11 @@ export const analyzeCommand = async (inputPath, options) => {
             // needs a fresh pipelineResult. Has no bearing on the registry
             // collision guard (see allowDuplicateName below).
             force: options?.force || options?.skills,
+            repairFts: options?.repairFts,
             embeddings: embeddingsEnabled,
             embeddingsNodeLimit,
             dropEmbeddings: options?.dropEmbeddings,
+            verbose: options?.verbose,
             skipGit: options?.skipGit,
             skipAgentsMd,
             skipSkills,
@@ -411,6 +419,18 @@ export const analyzeCommand = async (inputPath, options) => {
             // runFullAnalysis never opens LadybugDB, so no native handles prevent exit.
             return;
         }
+        if (result.ftsRepairedOnly) {
+            clearInterval(elapsedTimer);
+            process.removeListener('SIGINT', sigintHandler);
+            console.log = origLog;
+            // eslint-disable-next-line no-console -- restoring after intentional progress-bar routing
+            console.warn = origWarn;
+            // eslint-disable-next-line no-console -- restoring after intentional progress-bar routing
+            console.error = origError;
+            bar.stop();
+            console.log('  FTS indexes repaired successfully\n');
+            return;
+        }
         // Post-finalize invariant (#1169): runFullAnalysis nominally writes
         // meta.json and registers the repo, but on Windows it has been
         // observed to return successfully with neither artifact present

package/dist/cli/index.js

@@ -17,6 +17,7 @@ program
     .command('analyze [path]')
     .description('Index a repository (full analysis)')
     .option('-f, --force', 'Force full re-index even if up to date')
+    .option('--repair-fts', 'Repair/rebuild search FTS indexes without full re-analysis')
     .option('--embeddings [limit]', 'Enable embedding generation for semantic search (off by default). ' +
     'Optional [limit] overrides the 50,000-node safety cap; pass 0 to disable the cap entirely.')
     .option('--drop-embeddings', 'Drop existing embeddings on rebuild. By default, an `analyze` without `--embeddings` ' +

package/dist/core/ingestion/languages/cpp/conversion-rank.d.ts

@@ -1,31 +1,29 @@
 /**
- * C++ conversion-rank scoring for overload resolution (#1578).
+ * C++ conversion-rank scoring for overload resolution (#1578, #1637).
  *
- * Operates on **normalized** type strings (output of
- * `normalizeCppParamType` in `arity-metadata.ts`). After normalization:
- *   - int/long/short/unsigned → 'int'
- *   - float/double → 'double'
- *   - char → 'char', bool → 'bool'
- *
- * Because the normalizer collapses promotion pairs (int↔long,
- * float↔double) to the same string, those promotions are invisible at
- * this layer — they appear as exact matches (rank 0).
+ * Operates on normalized type strings (output of `normalizeCppParamType`
+ * in `arity-metadata.ts`) plus optional shape sidecars from #1630.
+ * Normalization intentionally collapses cv/ref/pointer spelling for stable
+ * graph IDs, so pointer/nullptr rules must consult `ParameterTypeClass`.
  *
  * Post-normalization ranking:
- *   - rank 0 — exact (same normalized type)
- *   - rank 1 — integral promotion (char→int, bool→int)
- *   - rank 2 — standard arithmetic conversion (int↔double, char→double,
- *              bool→double)
- *   - Infinity — mismatch (string↔int, user types, pointers, etc.)
+ *   - rank 0: exact (same normalized type)
+ *   - rank 1: integral promotion (char -> int, bool -> int)
+ *   - rank 2: standard conversion (arithmetic, nullptr -> T*, T* -> bool,
+ *             T* -> void*)
+ *   - rank 3: nullptr -> bool (kept worse than nullptr -> T*)
+ *   - rank 4: ellipsis conversion (worst viable)
+ *   - Infinity: mismatch (string -> int, user types, unsupported shapes)
  *
- * This function is intentionally C++-specific (issue #1578 pitfall:
- * keep conversion-rank tables out of shared overload-narrowing). Other
- * languages may define their own `ConversionRankFn` in the future.
+ * This function is intentionally C++-specific. Other languages may define
+ * their own `ConversionRankFn` in the future.
  */
+import type { ParameterTypeClass } from '../../../../_shared/index.js';
 /**
  * Return the conversion rank from `argType` to `paramType`.
  *
- * @returns 0 for exact match, 1 for integral promotion (char/bool→int),
- *          2 for standard arithmetic conversion, Infinity for mismatch.
+ * @returns 0 for exact match, 1 for integral promotion, 2 for standard
+ *          conversion, 3 for nullptr -> bool, 4 for ellipsis, Infinity
+ *          for mismatch.
  */
-export declare function cppConversionRank(argType: string, paramType: string): number;
+export declare function cppConversionRank(argType: string, paramType: string, argTypeClass?: ParameterTypeClass, paramTypeClass?: ParameterTypeClass): number;

package/dist/core/ingestion/languages/cpp/conversion-rank.js

@@ -1,30 +1,26 @@
 /**
- * C++ conversion-rank scoring for overload resolution (#1578).
+ * C++ conversion-rank scoring for overload resolution (#1578, #1637).
  *
- * Operates on **normalized** type strings (output of
- * `normalizeCppParamType` in `arity-metadata.ts`). After normalization:
- *   - int/long/short/unsigned → 'int'
- *   - float/double → 'double'
- *   - char → 'char', bool → 'bool'
- *
- * Because the normalizer collapses promotion pairs (int↔long,
- * float↔double) to the same string, those promotions are invisible at
- * this layer — they appear as exact matches (rank 0).
+ * Operates on normalized type strings (output of `normalizeCppParamType`
+ * in `arity-metadata.ts`) plus optional shape sidecars from #1630.
+ * Normalization intentionally collapses cv/ref/pointer spelling for stable
+ * graph IDs, so pointer/nullptr rules must consult `ParameterTypeClass`.
  *
  * Post-normalization ranking:
- *   - rank 0 — exact (same normalized type)
- *   - rank 1 — integral promotion (char→int, bool→int)
- *   - rank 2 — standard arithmetic conversion (int↔double, char→double,
- *              bool→double)
- *   - Infinity — mismatch (string↔int, user types, pointers, etc.)
+ *   - rank 0: exact (same normalized type)
+ *   - rank 1: integral promotion (char -> int, bool -> int)
+ *   - rank 2: standard conversion (arithmetic, nullptr -> T*, T* -> bool,
+ *             T* -> void*)
+ *   - rank 3: nullptr -> bool (kept worse than nullptr -> T*)
+ *   - rank 4: ellipsis conversion (worst viable)
+ *   - Infinity: mismatch (string -> int, user types, unsupported shapes)
  *
- * This function is intentionally C++-specific (issue #1578 pitfall:
- * keep conversion-rank tables out of shared overload-narrowing). Other
- * languages may define their own `ConversionRankFn` in the future.
+ * This function is intentionally C++-specific. Other languages may define
+ * their own `ConversionRankFn` in the future.
  */
 /** Set of normalized arithmetic types that support implicit conversion. */
 const ARITHMETIC = new Set(['int', 'double', 'char', 'bool']);
-/** Integral promotion targets: char→int and bool→int are rank 1. */
+/** Integral promotion targets: char -> int and bool -> int are rank 1. */
 const INTEGRAL_PROMOTION = new Map([
     ['char', 'int'],
     ['bool', 'int'],
@@ -32,16 +28,38 @@ const INTEGRAL_PROMOTION = new Map([
 /**
  * Return the conversion rank from `argType` to `paramType`.
  *
- * @returns 0 for exact match, 1 for integral promotion (char/bool→int),
- *          2 for standard arithmetic conversion, Infinity for mismatch.
+ * @returns 0 for exact match, 1 for integral promotion, 2 for standard
+ *          conversion, 3 for nullptr -> bool, 4 for ellipsis, Infinity
+ *          for mismatch.
  */
-export function cppConversionRank(argType, paramType) {
-    if (argType === paramType)
-        return 0;
-    // Integral promotions: char→int, bool→int (ISO C++ [conv.prom])
+export function cppConversionRank(argType, paramType, argTypeClass, paramTypeClass) {
+    if (argType === paramType) {
+        return exactShapeCompatible(argTypeClass, paramTypeClass) ? 0 : Infinity;
+    }
+    if (paramType === '...')
+        return 4;
     if (INTEGRAL_PROMOTION.get(argType) === paramType)
         return 1;
     if (ARITHMETIC.has(argType) && ARITHMETIC.has(paramType))
         return 2;
+    if (argType === 'null' && isPointer(paramTypeClass))
+        return 2;
+    if (argType === 'null' && paramType === 'bool')
+        return 3;
+    if (isPointer(argTypeClass) && paramType === 'bool')
+        return 2;
+    if (isPointer(argTypeClass) && isPointer(paramTypeClass) && paramType === 'void')
+        return 2;
     return Infinity;
 }
+function isPointer(typeClass) {
+    return typeClass?.indirection === 'pointer' && typeClass.pointerDepth > 0;
+}
+function exactShapeCompatible(argTypeClass, paramTypeClass) {
+    if (argTypeClass === undefined || paramTypeClass === undefined)
+        return true;
+    if (argTypeClass.indirection === 'unknown' || paramTypeClass.indirection === 'unknown') {
+        return true;
+    }
+    return isPointer(argTypeClass) === isPointer(paramTypeClass);
+}

package/dist/core/ingestion/scope-resolution/passes/free-call-fallback.js

@@ -202,7 +202,7 @@ export function emitFreeCallFallback(graph, scopes, parsedFiles, nodeLookup, _re
                         callerScope: site.inScope,
                         scopes,
                     })
-                    : undefined, site.argumentTypes, options.conversionRankFn);
+                    : undefined, site.argumentTypes, site.argumentTypeClasses, options.conversionRankFn);
             }
             if (fnDef === undefined)
                 continue;
@@ -261,7 +261,7 @@ function buildGlobalCallableIndex(scopes) {
     }
     return out;
 }
-function pickUniqueGlobalCallable(name, model, globalCallablesBySimpleName, callerFilePath, isFileLocalDef, callArity, isCallerVisible, callArgTypes, conversionRankFn) {
+function pickUniqueGlobalCallable(name, model, globalCallablesBySimpleName, callerFilePath, isFileLocalDef, callArity, isCallerVisible, callArgTypes, callArgTypeClasses, conversionRankFn) {
     const scopeDefs = [];
     const scopeSeen = new Set();
     for (const def of globalCallablesBySimpleName.get(name) ?? []) {
@@ -300,6 +300,7 @@ function pickUniqueGlobalCallable(name, model, globalCallablesBySimpleName, call
     // disambiguate (e.g., `f(int)` vs `f(double)` called with `f(2.5)`).
     if (scopeDefs.length > 1) {
         const narrowed = narrowOverloadCandidates(scopeDefs, callArity, callArgTypes, {
+            argumentTypeClasses: callArgTypeClasses,
             conversionRankFn,
         });
         if (narrowed.length === 1)
@@ -340,6 +341,7 @@ function pickUniqueGlobalCallable(name, model, globalCallablesBySimpleName, call
     // Same argument-type + conversion-rank narrowing for the model pool.
     if (defs.length > 1) {
         const narrowed = narrowOverloadCandidates(defs, callArity, callArgTypes, {
+            argumentTypeClasses: callArgTypeClasses,
             conversionRankFn,
         });
         if (narrowed.length === 1)

package/dist/core/ingestion/scope-resolution/passes/overload-narrowing.d.ts

@@ -37,7 +37,7 @@
  *       (monotonicity).
  *   5. Empty input returns empty output.
  */
-import type { ArityVerdict, Callsite, ConstraintContext, SymbolDefinition } from '../../../../_shared/index.js';
+import type { ArityVerdict, Callsite, ConstraintContext, ParameterTypeClass, SymbolDefinition } from '../../../../_shared/index.js';
 /**
  * Per-slot conversion-rank function. Returns a numeric cost for
  * converting `argType` to `paramType`:
@@ -49,7 +49,7 @@ import type { ArityVerdict, Callsite, ConstraintContext, SymbolDefinition } from
  * Each language provides its own implementation. The function operates
  * on normalized type strings (output of the language's type normalizer).
  */
-export type ConversionRankFn = (argType: string, paramType: string) => number;
+export type ConversionRankFn = (argType: string, paramType: string, argTypeClass?: ParameterTypeClass, paramTypeClass?: ParameterTypeClass) => number;
 /**
  * Optional hook bundle for narrowing extension points. Threaded in
  * from `pickOverload` / `pickImplicitThisOverload` so per-language

package/dist/core/ingestion/scope-resolution/passes/overload-narrowing.js

@@ -81,8 +81,9 @@ export function narrowOverloadCandidates(overloads, argCount, argTypes, hookCtx)
             for (let i = 0; i < argTypes.length && i < params.length; i++) {
                 if (argTypes[i] === '')
                     continue;
-                if (argTypes[i] !== params[i])
+                if (!exactTypeSlotMatches(argTypes[i], params[i], hookCtx?.argumentTypeClasses?.[i], d.parameterTypeClasses?.[i])) {
                     return false;
+                }
             }
             return true;
         });
@@ -97,7 +98,7 @@ export function narrowOverloadCandidates(overloads, argCount, argTypes, hookCtx)
             // are returned; multiple survivors are genuinely ambiguous. When
             // ranking also yields empty, fall through to the arity-filtered
             // `candidates` set — matches pre-#1606 behavior.
-            const ranked = rankByConversion(candidates, argTypes, hookCtx.conversionRankFn);
+            const ranked = rankByConversion(candidates, argTypes, hookCtx.conversionRankFn, hookCtx.argumentTypeClasses);
             if (ranked.length > 0)
                 result = ranked;
         }
@@ -134,6 +135,22 @@ export function narrowOverloadCandidates(overloads, argCount, argTypes, hookCtx)
     }
     return result;
 }
+function exactTypeSlotMatches(argType, paramType, argTypeClass, paramTypeClass) {
+    if (argType !== paramType)
+        return false;
+    // C++ normalizes away pointer markers (`int*` -> `int`). When both sides
+    // provide shape sidecars, do not let that collapse make `int` exactly match
+    // `int*`. Unknown sidecar evidence preserves the previous string-only path.
+    if (argTypeClass === undefined || paramTypeClass === undefined)
+        return true;
+    if (argTypeClass.indirection === 'unknown' || paramTypeClass.indirection === 'unknown') {
+        return true;
+    }
+    return isPointerShape(argTypeClass) === isPointerShape(paramTypeClass);
+}
+function isPointerShape(typeClass) {
+    return typeClass.indirection === 'pointer' && typeClass.pointerDepth > 0;
+}
 /**
  * Pairwise dominance comparison (ISO C++ [over.ics.rank]).
  *
@@ -146,7 +163,7 @@ export function narrowOverloadCandidates(overloads, argCount, argTypes, hookCtx)
  * Candidates with at least one `Infinity`-ranked slot (incompatible
  * type) are excluded before pairwise comparison begins.
  */
-function rankByConversion(candidates, argTypes, rankFn) {
+function rankByConversion(candidates, argTypes, rankFn, argTypeClasses) {
     // Step 1: compute per-slot ranks and exclude non-viable candidates.
     const viable = [];
     for (const d of candidates) {
@@ -155,12 +172,17 @@ function rankByConversion(candidates, argTypes, rankFn) {
             continue;
         const ranks = [];
         let ok = true;
-        for (let i = 0; i < argTypes.length && i < params.length; i++) {
+        for (let i = 0; i < argTypes.length; i++) {
+            const paramType = parameterTypeAt(params, i);
+            if (paramType === undefined) {
+                ok = false;
+                break;
+            }
             if (argTypes[i] === '') {
                 ranks.push(0); // unknown arg → any-match (rank 0)
                 continue;
             }
-            const r = rankFn(argTypes[i], params[i]);
+            const r = rankFn(argTypes[i], paramType, argTypeClasses?.[i], parameterTypeClassAt(d.parameterTypeClasses, i));
             if (!isFinite(r)) {
                 ok = false;
                 break;
@@ -190,6 +212,18 @@ function rankByConversion(candidates, argTypes, rankFn) {
     }
     return viable.filter((_, idx) => !dominated.has(idx)).map((v) => v.def);
 }
+function parameterTypeAt(params, argIndex) {
+    if (argIndex < params.length)
+        return params[argIndex];
+    return params[params.length - 1] === '...' ? '...' : undefined;
+}
+function parameterTypeClassAt(params, argIndex) {
+    if (params === undefined)
+        return undefined;
+    if (argIndex < params.length)
+        return params[argIndex];
+    return params[params.length - 1]?.base === '...' ? params[params.length - 1] : undefined;
+}
 /**
  * Compare two per-slot rank vectors.
  * Returns  -1 if `a` dominates `b` (not worse everywhere, better somewhere),

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

@@ -1454,7 +1454,8 @@ export const createFTSIndex = async (tableName, indexName, properties, stemmer =
     if (ensuredFTSIndexes.has(key))
         return;
     if (!(await loadFTSExtension())) {
-        return;
+        throw new Error(`FTS extension unavailable - cannot create FTS index ${tableName}.${indexName}. ` +
+            'Run `gitnexus doctor` and ensure the LadybugDB FTS extension is installed and loadable on this machine.');
     }
     const propList = properties.map((p) => `'${p}'`).join(', ');
     const query = `CALL CREATE_FTS_INDEX('${tableName}', '${indexName}', [${propList}], stemmer := '${stemmer}')`;

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

@@ -20,6 +20,10 @@ export interface AnalyzeOptions {
      * bypass. See `allowDuplicateName` below.
      */
     force?: boolean;
+    /** Repair only search indexes without re-running full parsing/indexing. */
+    repairFts?: boolean;
+    /** Emit per-index FTS create logs. */
+    verbose?: boolean;
     embeddings?: boolean;
     /**
      * Override the auto-skip node-count cap for embedding generation.
@@ -74,6 +78,8 @@ export interface AnalyzeResult {
     alreadyUpToDate?: boolean;
     /** The raw pipeline result — only populated when needed by callers (e.g. skill generation). */
     pipelineResult?: any;
+    /** True when analyze only repaired FTS indexes and skipped pipeline re-analysis. */
+    ftsRepairedOnly?: boolean;
 }
 export { deriveEmbeddingMode, DEFAULT_EMBEDDING_NODE_LIMIT } from './embedding-mode.js';
 export type { EmbeddingMode } from './embedding-mode.js';

package/dist/core/run-analyze.js

@@ -13,7 +13,7 @@ import fs from 'fs/promises';
 import { execFileSync } from 'child_process';
 import { runPipelineFromRepo } from './ingestion/pipeline.js';
 import { initLbug, loadGraphToLbug, getLbugStats, executeQuery, executeWithReusedStatement, closeLbug, loadCachedEmbeddings, deleteNodesForFile, deleteAllCommunitiesAndProcesses, queryImporters, } from './lbug/lbug-adapter.js';
-import { createSearchFTSIndexes } from './search/fts-indexes.js';
+import { createSearchFTSIndexes, verifySearchFTSIndexes } from './search/fts-indexes.js';
 import { getStoragePaths, saveMeta, loadMeta, ensureGitNexusIgnored, registerRepo, cleanupOldKuzuFiles, INCREMENTAL_SCHEMA_VERSION, } from '../storage/repo-manager.js';
 import { computeFileHashes, diffFileHashes } from '../storage/file-hash.js';
 import { extractChangedSubgraph, computeEffectiveWriteSet, } from './incremental/subgraph-extract.js';
@@ -68,6 +68,70 @@ export async function runFullAnalysis(repoPath, options, callbacks) {
     const repoHasGit = hasGitDir(repoPath);
     const currentCommit = repoHasGit ? getCurrentCommit(repoPath) : '';
     const existingMeta = await loadMeta(storagePath);
+    // ── FTS-only repair path ────────────────────────────────────────────
+    if (options.repairFts) {
+        if (!existingMeta) {
+            throw new Error('Cannot repair FTS indexes because this repository has not been analyzed yet. ' +
+                'Run `gitnexus analyze` first to create the initial index, then retry `--repair-fts`.');
+        }
+        let lbugStat;
+        try {
+            lbugStat = await fs.lstat(lbugPath);
+        }
+        catch {
+            throw new Error(`Cannot repair FTS indexes: graph store at ${lbugPath} is missing. ` +
+                'Run `gitnexus analyze` (full) to rebuild from scratch.');
+        }
+        if (!lbugStat.isFile()) {
+            const foundType = lbugStat.isDirectory()
+                ? 'a directory'
+                : lbugStat.isSymbolicLink()
+                    ? 'a symbolic link'
+                    : lbugStat.isSocket()
+                        ? 'a socket'
+                        : lbugStat.isBlockDevice()
+                            ? 'a block device'
+                            : lbugStat.isCharacterDevice()
+                                ? 'a character device'
+                                : lbugStat.isFIFO()
+                                    ? 'a FIFO'
+                                    : 'not a regular file';
+            throw new Error(`Cannot repair FTS indexes: graph store at ${lbugPath} is ${foundType} (expected a file). ` +
+                'Run `gitnexus analyze` (full) to rebuild from scratch.');
+        }
+        try {
+            await initLbug(lbugPath);
+            progress('fts', 85, 'Repairing search indexes...');
+            await createSearchFTSIndexes({
+                onIndexStart: options.verbose
+                    ? (table, indexName) => log(`FTS: creating ${table}.${indexName}`)
+                    : undefined,
+                onIndexReady: options.verbose
+                    ? (table, indexName) => log(`FTS: ready ${table}.${indexName}`)
+                    : undefined,
+            });
+            const missing = await verifySearchFTSIndexes(executeQuery);
+            if (missing.length > 0) {
+                throw new Error(`FTS repair failed - missing indexes after rebuild: ${missing.join(', ')}. ` +
+                    'Run `gitnexus analyze --force` to perform a full graph+FTS rebuild; ' +
+                    'if that also fails, verify FTS extension availability via `gitnexus doctor`.');
+            }
+            await ensureGitNexusIgnored(repoPath);
+            progress('fts', 90, 'Search indexes ready');
+            progress('done', 100, 'Done');
+            return {
+                repoName: options.registryName ??
+                    getInferredRepoName(repoPath) ??
+                    path.basename(resolveRepoIdentityRoot(repoPath)),
+                repoPath,
+                stats: existingMeta.stats ?? {},
+                ftsRepairedOnly: true,
+            };
+        }
+        finally {
+            await closeLbug().catch(() => { });
+        }
+    }
     // ── Crash recovery: dirty flag forces full rebuild ────────────────
     // If the previous incremental run set incrementalInProgress and didn't
     // clear it, the on-disk index may be in a half-state. Cheapest path
@@ -420,7 +484,19 @@ export async function runFullAnalysis(repoPath, options, callbacks) {
         }
         // ── Phase 3: FTS (85–90%) ─────────────────────────────────────────
         progress('fts', 85, 'Creating search indexes...');
-        await createSearchFTSIndexes();
+        await createSearchFTSIndexes({
+            onIndexStart: options.verbose
+                ? (table, indexName) => log(`FTS: creating ${table}.${indexName}`)
+                : undefined,
+            onIndexReady: options.verbose
+                ? (table, indexName) => log(`FTS: ready ${table}.${indexName}`)
+                : undefined,
+        });
+        const missingIndexNames = await verifySearchFTSIndexes(executeQuery);
+        if (missingIndexNames.length > 0) {
+            throw new Error(`FTS verification failed - missing indexes after analyze: ${missingIndexNames.join(', ')}. ` +
+                'Check FTS extension availability, then retry `gitnexus analyze --force` for a full rebuild.');
+        }
         progress('fts', 90, 'Search indexes ready');
         // ── Phase 3.5: Re-insert cached embeddings ────────────────────────
         // Runs on BOTH the full-rebuild path and the incremental path:

package/dist/core/search/fts-indexes.d.ts

@@ -1 +1,6 @@
-export declare function createSearchFTSIndexes(): Promise<void>;
+export interface CreateSearchFTSIndexesOptions {
+    onIndexStart?: (table: string, indexName: string) => void;
+    onIndexReady?: (table: string, indexName: string) => void;
+}
+export declare function createSearchFTSIndexes(options?: CreateSearchFTSIndexesOptions): Promise<void>;
+export declare function verifySearchFTSIndexes(executeQuery: (cypher: string) => Promise<unknown[]>): Promise<string[]>;

package/dist/core/search/fts-indexes.js

@@ -1,7 +1,34 @@
 import { createFTSIndex } from '../lbug/lbug-adapter.js';
 import { FTS_INDEXES } from './fts-schema.js';
-export async function createSearchFTSIndexes() {
+export async function createSearchFTSIndexes(options) {
     for (const { table, indexName, properties } of FTS_INDEXES) {
+        options?.onIndexStart?.(table, indexName);
         await createFTSIndex(table, indexName, [...properties]);
+        options?.onIndexReady?.(table, indexName);
     }
 }
+export async function verifySearchFTSIndexes(executeQuery) {
+    const safeIdentifier = (value) => {
+        if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(value)) {
+            throw new Error(`Invalid FTS identifier: ${value}`);
+        }
+        return value;
+    };
+    const missing = [];
+    for (const { table, indexName } of FTS_INDEXES) {
+        const safeTable = safeIdentifier(table);
+        const safeIndex = safeIdentifier(indexName);
+        const probe = `
+      CALL QUERY_FTS_INDEX('${safeTable}', '${safeIndex}', '__gitnexus_fts_probe__', conjunctive := false)
+      RETURN score
+      LIMIT 1
+    `;
+        try {
+            await executeQuery(probe);
+        }
+        catch {
+            missing.push(`${table}.${indexName}`);
+        }
+    }
+    return missing;
+}

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

@@ -894,7 +894,7 @@ export class LocalBackend {
             definitions: definitions.slice(0, 20), // cap standalone definitions
             timing,
             ...(!ftsUsed && {
-                warning: 'FTS indexes missing — keyword search degraded. Run: gitnexus analyze --force to rebuild indexes.',
+                warning: 'FTS indexes missing — keyword search degraded. Run: gitnexus analyze --repair-fts (or gitnexus analyze --force) to rebuild indexes.',
             }),
         };
     }

package/dist/server/api.js

@@ -1071,7 +1071,7 @@ export const createServer = async (port, host = '127.0.0.1') => {
             const response = { results: results.searchResults ?? results };
             if (results.ftsAvailable === false) {
                 response.warning =
-                    'FTS indexes missing — keyword search degraded. Run: gitnexus analyze --force to rebuild indexes.';
+                    'FTS indexes missing — keyword search degraded. Run: gitnexus analyze --repair-fts (or gitnexus analyze --force) to rebuild indexes.';
             }
             res.json(response);
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gitnexus",
-  "version": "1.6.6-rc.21",
+  "version": "1.6.6-rc.23",
   "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",