gitnexus 1.6.12 → 1.6.13-rc.2

package/README.md

@@ -518,11 +518,11 @@ truthy, when the install is not an npm global/local install (npx cache, dev
 checkout, Docker image — the Docker CLI image sets the opt-out itself), or
 when opted out:
 
-| Variable | Effect |
-| --- | --- |
-| `GITNEXUS_NO_UPDATE_NOTIFIER` | Truthy (`1`, `true`, …) disables the update check on every surface. |
-| `NO_UPDATE_NOTIFIER` | Cross-tool convention; honored the same way. |
-| `npm_config_registry` | The check reads the `latest` dist-tag from this registry instead of `https://registry.npmjs.org`. Credentials are never sent, and registries that require authentication are not supported (the check silently skips). |
+| Variable                      | Effect                                                                                                                                                                                                                 |
+| ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `GITNEXUS_NO_UPDATE_NOTIFIER` | Truthy (`1`, `true`, …) disables the update check on every surface.                                                                                                                                                    |
+| `NO_UPDATE_NOTIFIER`          | Cross-tool convention; honored the same way.                                                                                                                                                                           |
+| `npm_config_registry`         | The check reads the `latest` dist-tag from this registry instead of `https://registry.npmjs.org`. Credentials are never sent, and registries that require authentication are not supported (the check silently skips). |
 
 Eval harnesses running a global install can set `GITNEXUS_NO_UPDATE_NOTIFIER`
 for a quiet registry.
@@ -614,20 +614,17 @@ runtime dependencies Windows does not ship by default:
 
 1. **Microsoft Visual C++ 2015-2022 Redistributable (x64)** —
    <https://aka.ms/vs/17/release/vc_redist.x64.exe>
-2. **OpenSSL 3** — `libssl-3-x64.dll` and `libcrypto-3-x64.dll`, resolvable on `PATH`
+2. **OpenSSL 3** — install it as a system runtime so `libssl-3-x64.dll` and
+   `libcrypto-3-x64.dll` resolve without borrowing them from another application.
 
-The redistributable alone is **not** sufficient. If Git for Windows is installed you already have
-the OpenSSL DLLs — run `gitnexus` from **Git Bash**, or prepend the directory to `PATH` in the
-shell you use:
+The redistributable alone is **not** sufficient. Do not prepend a third-party
+application directory (including Git for Windows) to `PATH` to pick up those DLLs.
 
-```powershell
-$env:PATH = "C:\Program Files\Git\mingw64\bin;$env:PATH"
-gitnexus analyze --repair-fts
-```
-
-Without them the index is still built, but without search tables, so `query` returns empty keyword
-results until you re-run `gitnexus analyze --repair-fts` from a shell where the DLLs resolve
-([#2669](https://github.com/abhigyanpatwari/GitNexus/issues/2669)).
+Without both runtimes the index is still built, but without search tables, so
+`query` returns empty keyword results until you install the prerequisites and
+re-run `gitnexus analyze --repair-fts`
+([#2669](https://github.com/abhigyanpatwari/GitNexus/issues/2669),
+[#3218](https://github.com/abhigyanpatwari/GitNexus/issues/3218)).
 
 ### Installation fails with native module errors
 
@@ -671,20 +668,20 @@ GitNexus uses optional DuckDB extensions for BM25 and vector search. The `gitnex
 
 Configure the behavior with these environment variables:
 
-| Variable                                     | Values                         | Default                | Effect                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
-| -------------------------------------------- | ------------------------------ | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `GITNEXUS_LBUG_EXTENSION_INSTALL`            | `auto`, `load-only`, `never`   | `auto`                 | `auto` runs one bounded install if LOAD fails — a plain `INSTALL`, escalating to `FORCE INSTALL` only when the LOAD error shows the present extension file is broken. `load-only` only uses already-installed extensions (recommended for offline / firewalled environments). `never` skips optional extensions entirely.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
-| `GITNEXUS_LBUG_EXTENSION_INSTALL_TIMEOUT_MS` | positive integer               | `15000`                | Wall-clock budget for the out-of-process extension-install child before it is killed.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
-| `GITNEXUS_FTS_STEMMER`                       | supported LadybugDB stemmer    | `porter`               | Stemmer used when rebuilding BM25/FTS indexes. Use `none` for CJK-heavy repositories, or a language stemmer such as `german`, `french`, or `spanish` when that better matches repository comments and identifiers. Re-run `gitnexus analyze --repair-fts` after changing it.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
-| `GITNEXUS_FTS_CJK_SEGMENTATION`              | `none`, `bigram`               | `none`                 | `bigram` inserts overlapping character-bigram boundaries into Chinese/Japanese Han-ideograph spans in `content`/`description` before FTS indexing, so LadybugDB's space-only tokenizer can see sub-phrase word boundaries. Scoped to CJK Unified Ideographs only — Japanese Hiragana/Katakana and Korean Hangul are not currently segmented. Unlike `GITNEXUS_FTS_STEMMER`, this rewrites stored text — enabling it on an already-indexed repo requires a full `gitnexus analyze --force`; neither `--repair-fts` nor a plain incremental `analyze` applies it to previously-indexed files. Set the same value wherever `analyze` and search-serving processes (CLI query, MCP server, web server) run.                                                                                                                                       |
-| `GITNEXUS_STORAGE_PATH`                      | absolute, non-empty directory  | unset (repo-local)     | Complete external index directory. This preserves the existing configuration semantics and takes precedence over `GITNEXUS_STORAGE_ROOT` when both are set.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
-| `GITNEXUS_STORAGE_ROOT`                      | absolute, non-empty directory  | unset (repo-local)     | Absolute root directory for external indexes. GitNexus creates an isolated `<repo-basename>-<canonical-path-hash>/` slot beneath it for each repository, then registers the resolved slot so `status`, MCP, and `serve` can reopen it later.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
-| `GITNEXUS_CONTENT_RETENTION`                 | `full`, `symbol`, `none`       | `full`                 | Source-text retention profile: `full` keeps file and symbol text, `symbol` keeps symbol snippets without full file content, and `none` keeps the structural graph without source body text.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
-| `GITNEXUS_STREAM_GRAPH_EMIT`                 | `0`, `1`                       | `1` (on)               | **On by default** on a full rebuild (`--force`); incremental runs ignore it. Holds structural relationships (CALLS, IMPORTS, ACCESSES, CONTAINS, ...) as CSV-on-disk plus compact in-memory columns instead of as objects in three overlapping indexes, cutting peak in-memory graph heap by ~1.4x at no measurable CPU cost (measured A/B on a synthetic 400k-node / 1.08M-edge graph: 819 MB -> 584 MB, iteration at parity, scaling verified linear from 100k to 800k nodes, with every edge still visible through the graph interface; no end-to-end measurement on a real repository yet). Nothing is traded away — community detection, process extraction, PDG taint summaries and the local-symbol pruner all read a complete relationship set and behave identically. Set to `0` only to bisect a suspected streaming-related fault. |
-| `GITNEXUS_COMMUNITY_ENGINE`                  | `graphology`, `icebug`, `auto` | `graphology`           | Community-detection engine used during analyze. `graphology` is the supported default. `icebug` and `auto` are **experimental** and currently behave identically: both try the optional `@ladybugmem/icebug` native Leiden over a CSR export and fall back to Graphology if it is not installed, cannot load, or lacks the deterministic thread/seed controls. Experimental engines partition differently, so community IDs are not comparable across engines.                                                                                                                                                                                                                                                                                                                                                                                |
-| `GITNEXUS_WAL_CHECKPOINT_THRESHOLD`          | integer `>= -1`                | `67108864` (64 MiB)    | LadybugDB WAL auto-checkpoint threshold during analyze (bytes). Auto-checkpoint remains enabled; `-1` keeps Ladybug's stock ~16 MiB. Larger thresholds reduce checkpoint frequency but increase the WAL size at rotation time — choose a smaller value on disk-constrained environments.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
-| `GITNEXUS_LBUG_BUFFER_POOL_SIZE`             | integer `>= 0` (bytes)         | min(2 GiB, 80% RAM)    | LadybugDB buffer-pool ceiling for every GitNexus database (analyze, MCP server, serve, group bridges). Bounded so a long-lived `gitnexus mcp` process or a large incremental `analyze` cannot grow toward LadybugDB's native 80%-of-RAM default and OOM the host (#2557). `0` restores that native unbounded default; invalid values warn and fall back to the default. During `analyze` the pool is right-sized to the graph and, on non-4 KiB-page hosts (Apple Silicon 16 KiB, Ascend/aarch64 64 KiB), scaled by the page-size granule ratio up to min(2 GiB × pageSize/4 KiB, 80% RAM) (#2631); this env var overrides all of that as an absolute value.                                                                                                                                                                                  |
-| `GITNEXUS_LBUG_MAX_DB_SIZE`                  | positive integer (bytes)       | `17179869184` (16 GiB) | Upper bound for a single LadybugDB database file. This is an mmap/disk-address-space ceiling, not a memory limit — it does not constrain the buffer pool (use `GITNEXUS_LBUG_BUFFER_POOL_SIZE` for that). Raise it when indexing genuinely huge monorepos; invalid values silently fall back to the default.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| Variable                                     | Values                         | Default                                            | Effect                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| -------------------------------------------- | ------------------------------ | -------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `GITNEXUS_LBUG_EXTENSION_INSTALL`            | `auto`, `load-only`, `never`   | `load-only` globally; `analyze` defaults to `auto` | The process-wide default is `load-only` so serve/MCP/query never install over the network. `gitnexus analyze` overrides to `auto` unless you set the env. FTS loads the packaged per-platform artifact first (macOS, Windows, and Linux), then a named `LOAD`, then `INSTALL` only under `auto`. `never` skips optional extensions entirely.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| `GITNEXUS_LBUG_EXTENSION_INSTALL_TIMEOUT_MS` | positive integer               | `15000`                                            | Wall-clock budget for the out-of-process extension-install child before it is killed.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| `GITNEXUS_FTS_STEMMER`                       | supported LadybugDB stemmer    | `porter`                                           | Stemmer used when rebuilding BM25/FTS indexes. Use `none` for CJK-heavy repositories, or a language stemmer such as `german`, `french`, or `spanish` when that better matches repository comments and identifiers. Re-run `gitnexus analyze --repair-fts` after changing it.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| `GITNEXUS_FTS_CJK_SEGMENTATION`              | `none`, `bigram`               | `none`                                             | `bigram` inserts overlapping character-bigram boundaries into Chinese/Japanese Han-ideograph spans in `content`/`description` before FTS indexing, so LadybugDB's space-only tokenizer can see sub-phrase word boundaries. Scoped to CJK Unified Ideographs only — Japanese Hiragana/Katakana and Korean Hangul are not currently segmented. Unlike `GITNEXUS_FTS_STEMMER`, this rewrites stored text — enabling it on an already-indexed repo requires a full `gitnexus analyze --force`; neither `--repair-fts` nor a plain incremental `analyze` applies it to previously-indexed files. Set the same value wherever `analyze` and search-serving processes (CLI query, MCP server, web server) run.                                                                                                                                       |
+| `GITNEXUS_STORAGE_PATH`                      | absolute, non-empty directory  | unset (repo-local)                                 | Complete external index directory. This preserves the existing configuration semantics and takes precedence over `GITNEXUS_STORAGE_ROOT` when both are set.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| `GITNEXUS_STORAGE_ROOT`                      | absolute, non-empty directory  | unset (repo-local)                                 | Absolute root directory for external indexes. GitNexus creates an isolated `<repo-basename>-<canonical-path-hash>/` slot beneath it for each repository, then registers the resolved slot so `status`, MCP, and `serve` can reopen it later.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| `GITNEXUS_CONTENT_RETENTION`                 | `full`, `symbol`, `none`       | `full`                                             | Source-text retention profile: `full` keeps file and symbol text, `symbol` keeps symbol snippets without full file content, and `none` keeps the structural graph without source body text.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| `GITNEXUS_STREAM_GRAPH_EMIT`                 | `0`, `1`                       | `1` (on)                                           | **On by default** on a full rebuild (`--force`); incremental runs ignore it. Holds structural relationships (CALLS, IMPORTS, ACCESSES, CONTAINS, ...) as CSV-on-disk plus compact in-memory columns instead of as objects in three overlapping indexes, cutting peak in-memory graph heap by ~1.4x at no measurable CPU cost (measured A/B on a synthetic 400k-node / 1.08M-edge graph: 819 MB -> 584 MB, iteration at parity, scaling verified linear from 100k to 800k nodes, with every edge still visible through the graph interface; no end-to-end measurement on a real repository yet). Nothing is traded away — community detection, process extraction, PDG taint summaries and the local-symbol pruner all read a complete relationship set and behave identically. Set to `0` only to bisect a suspected streaming-related fault. |
+| `GITNEXUS_COMMUNITY_ENGINE`                  | `graphology`, `icebug`, `auto` | `graphology`                                       | Community-detection engine used during analyze. `graphology` is the supported default. `icebug` and `auto` are **experimental** and currently behave identically: both try the optional `@ladybugmem/icebug` native Leiden over a CSR export and fall back to Graphology if it is not installed, cannot load, or lacks the deterministic thread/seed controls. Experimental engines partition differently, so community IDs are not comparable across engines.                                                                                                                                                                                                                                                                                                                                                                                |
+| `GITNEXUS_WAL_CHECKPOINT_THRESHOLD`          | integer `>= -1`                | `67108864` (64 MiB)                                | LadybugDB WAL auto-checkpoint threshold during analyze (bytes). Auto-checkpoint remains enabled; `-1` keeps Ladybug's stock ~16 MiB. Larger thresholds reduce checkpoint frequency but increase the WAL size at rotation time — choose a smaller value on disk-constrained environments.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
+| `GITNEXUS_LBUG_BUFFER_POOL_SIZE`             | integer `>= 0` (bytes)         | min(2 GiB, 80% RAM)                                | LadybugDB buffer-pool ceiling for every GitNexus database (analyze, MCP server, serve, group bridges). Bounded so a long-lived `gitnexus mcp` process or a large incremental `analyze` cannot grow toward LadybugDB's native 80%-of-RAM default and OOM the host (#2557). `0` restores that native unbounded default; invalid values warn and fall back to the default. During `analyze` the pool is right-sized to the graph and, on non-4 KiB-page hosts (Apple Silicon 16 KiB, Ascend/aarch64 64 KiB), scaled by the page-size granule ratio up to min(2 GiB × pageSize/4 KiB, 80% RAM) (#2631); this env var overrides all of that as an absolute value.                                                                                                                                                                                  |
+| `GITNEXUS_LBUG_MAX_DB_SIZE`                  | positive integer (bytes)       | `17179869184` (16 GiB)                             | Upper bound for a single LadybugDB database file. This is an mmap/disk-address-space ceiling, not a memory limit — it does not constrain the buffer pool (use `GITNEXUS_LBUG_BUFFER_POOL_SIZE` for that). Raise it when indexing genuinely huge monorepos; invalid values silently fall back to the default.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
 
 ```bash
 # Offline/airgapped: never reach the network for extensions

package/dist/cli/analyze.js

@@ -12,7 +12,7 @@ import os from 'os';
 import { spawn } from 'child_process';
 import v8 from 'v8';
 import cliProgress from 'cli-progress';
-import { FTS_DISABLED_MESSAGE, isExplicitFtsDisablement } from '../core/search/fts-policy.js';
+import { formatAnalyzeFtsSkipSummary } from '../core/search/fts-policy.js';
 import { isLbugReady, LbugWipeError } from '../core/lbug/lbug-adapter.js';
 import { boundedCheckpointBeforeExit } from '../core/lbug/shutdown-helpers.js';
 import { findUndeclaredRelationPairError } from '../core/lbug/rel-pair-routing.js';
@@ -1189,8 +1189,9 @@ const analyzeCommandImpl = async (inputPath, cliOptions, runnerIdentityAtBootstr
             console.error = origError;
             bar.stop();
             console.log('  Already up to date\n');
-            if (isExplicitFtsDisablement(result.ftsSkipReason))
-                console.log(`  ${FTS_DISABLED_MESSAGE}\n`);
+            if (result.ftsSkipped) {
+                console.log(`  ${formatAnalyzeFtsSkipSummary(result.ftsSkipReason)}\n`);
+            }
             if (runOptions.registryName) {
                 console.log(`  Registry name: ${result.repoName}\n`);
             }
@@ -1320,27 +1321,9 @@ const analyzeCommandImpl = async (inputPath, cliOptions, runnerIdentityAtBootstr
         // progress-bar log() that fired mid-run has already scrolled away, so the
         // degraded-search state must also appear in the final summary (#1161).
         if (result.ftsSkipped) {
-            // #2658 review L2: a build/verify failure is NOT an extension-unavailable
-            // problem — sending the user to install the extension is the wrong remedy.
-            if (isExplicitFtsDisablement(result.ftsSkipReason)) {
-                console.log(`\n  ${FTS_DISABLED_MESSAGE}`);
-            }
-            else if (result.ftsSkipReason === 'build-failed') {
-                console.log(`\n  Warning: full-text/BM25 search is disabled — the search index build failed this run.\n` +
-                    `  The FTS extension is available; rerun \`gitnexus analyze --repair-fts\`. If it persists,\n` +
-                    `  check the disk for space or corruption. Run \`gitnexus doctor\` for details.`);
-            }
-            else {
-                console.log(
-                // NOT "then rerun" (#2841 §5.C): this run stamped `lastCommit`, so a
-                // plain rerun on an unchanged tree takes the up-to-date fast path and
-                // returns before Phase 3 could rebuild anything — the advice would be
-                // ineffective exactly when the user follows it. `--repair-fts` is the
-                // verb that rebuilds the search indexes without re-parsing the repo.
-                `\n  Warning: full-text/BM25 search is disabled — the LadybugDB FTS extension was unavailable.\n` +
-                    `  Install it once with network access (GITNEXUS_LBUG_EXTENSION_INSTALL=auto), then run\n` +
-                    `  \`gitnexus analyze --repair-fts\` to build the search indexes. Run \`gitnexus doctor\` for details.`);
-            }
+            // Total switch (#2658 L2 + native-abort/tuple-missing): a new skip
+            // reason must not inherit the network-install remedy.
+            console.log(`\n  ${formatAnalyzeFtsSkipSummary(result.ftsSkipReason)}`);
         }
         try {
             await fs.access(getGlobalRegistryPath());

package/dist/cli/doctor.js

@@ -4,10 +4,11 @@ import { isHttpMode } from '../core/embeddings/http-client.js';
 import { getLocalEmbeddingRuntimeBlocker, localEmbeddingPrefixUnloadableMessage, localEmbeddingStackMissingMessage, } from '../core/embeddings/runtime-support.js';
 import { isPrefixRuntimeLoadable, resolveEmbeddingRuntime, } from '../core/embeddings/runtime-install.js';
 import { cudaRedirectDoctorStatus } from '../core/embeddings/onnxruntime-node-resolver.js';
-import { checkLbugNative, probeFtsExtensionLoad, probeVectorExtensionLoad, } from '../core/lbug/native-check.js';
+import { checkLbugNative, ftsAvailabilityLabel, probeFtsExtensionLoad, probeVectorExtensionLoad, } from '../core/lbug/native-check.js';
 import { getEffectiveBufferPoolSize, getOsPageSize, isPageSizeAwareLadybug, } from '../core/lbug/lbug-config.js';
-import { diagnoseExtensionLoad } from '../core/lbug/extension-load-error.js';
-import { getExtensionInstallPolicy } from '../core/lbug/extension-loader.js';
+import { diagnoseExtensionLoad, extractExtensionPath } from '../core/lbug/extension-load-error.js';
+import { resolveFtsVersionPair } from '../core/lbug/vendored-extension-path.js';
+import { getExtensionInstallPolicy, resolveAnalyzeInstallPolicy, } from '../core/lbug/extension-loader.js';
 import { updateEligibleInstallSync } from '../core/install-context.js';
 import { readValidatedUpdateCacheSync } from '../core/update-cache.js';
 import { t } from './i18n/index.js';
@@ -208,7 +209,7 @@ export const doctorCommand = async () => {
     const ftsProbe = nativeCheck.ok
         ? await probeFtsExtensionLoad()
         : { loaded: false, reason: 'LadybugDB native module (lbugjs.node) failed to load' };
-    console.log(`  ${label('doctor.labels.fullTextSearch', 18)}${ftsProbe.loaded ? 'available' : 'unavailable'}`);
+    console.log(`  ${label('doctor.labels.fullTextSearch', 18)}${ftsAvailabilityLabel(ftsProbe)}`);
     if (!ftsProbe.loaded && ftsProbe.reason) {
         console.log(`  ${padDisplayEnd('', 18)}${ftsProbe.reason}`);
         // Add an actionable remedy for recognized failure classes (#2374). The
@@ -216,7 +217,10 @@ export const doctorCommand = async () => {
         // ("specified module could not be found") is opaque, so name the fix (VC++
         // redist, then OpenSSL) instead of leaving the user to reinstall in vain.
         // `unknown`'s remedy is "run doctor", which would be circular here.
-        const { kind, remedy } = diagnoseExtensionLoad(ftsProbe.reason);
+        // Policy `never` is not a load failure — skip structural diagnosis.
+        const { kind, remedy } = ftsProbe.suppressed
+            ? { kind: 'unknown', remedy: '' }
+            : diagnoseExtensionLoad(ftsProbe.reason, 'FTS', extractExtensionPath(ftsProbe.reason), resolveFtsVersionPair(extractExtensionPath(ftsProbe.reason)));
         if (kind !== 'unknown') {
             console.log(`  ${padDisplayEnd('', 18)}${remedy}`);
         }
@@ -246,13 +250,14 @@ export const doctorCommand = async () => {
     // Surface the optional-extension install policy so offline users can see
     // whether analyze/query will reach the network (extension.ladybugdb.com).
     // Literal label (like the 'native' line) to avoid adding i18n keys.
-    const installPolicy = getExtensionInstallPolicy();
-    const policyHint = installPolicy === 'load-only'
+    const serveQueryPolicy = getExtensionInstallPolicy();
+    const analyzePolicy = resolveAnalyzeInstallPolicy();
+    const policyHint = (policy) => policy === 'load-only'
         ? ' (offline; load only, no network install)'
-        : installPolicy === 'never'
+        : policy === 'never'
             ? ' (optional extensions disabled)'
             : ' (installs missing extensions over network)';
-    console.log(`  ${padDisplayEnd('Ext install:', 18)}${installPolicy}${policyHint}`);
+    console.log(`  ${padDisplayEnd('Ext install:', 18)}serve/query=${serveQueryPolicy}${policyHint(serveQueryPolicy)}; analyze=${analyzePolicy}${policyHint(analyzePolicy)}`);
     console.log(`  ${label('doctor.labels.exactScanLimit', 18)}${t('doctor.chunks', { count: capabilities.exactScanLimit })}`);
     if (capabilities.reason)
         console.log(`  ${label('doctor.labels.note', 18)}${capabilities.reason}`);

package/dist/core/lbug/extension-load-error.d.ts

@@ -1,4 +1,10 @@
-export type ExtensionLoadErrorKind = 'missing_file' | 'corrupt_file' | 'missing_dependency' | 'unknown';
+export type ExtensionLoadErrorKind = 'missing_file' | 'corrupt_file' | 'missing_dependency' | 'version_skew' | 'unknown';
+export interface ExtensionVersionPair {
+    expected?: string;
+    found?: string;
+}
+/** Kinds whose remedy must replace the generic network-install tail. */
+export declare const usesClassifiedLoadRemedy: (kind: ExtensionLoadErrorKind) => boolean;
 export interface ExtensionLoadDiagnosis {
     readonly kind: ExtensionLoadErrorKind;
     /** Actionable, literal-English remedy suited to the class. */
@@ -63,5 +69,5 @@ export declare function inspectExtensionBinary(extensionPath: string | null | un
  * classifier (which still carries the language-independent hedged fallback). This
  * is the entry point every surface should call.
  */
-export declare function diagnoseExtensionLoad(reason: string | undefined | null, label?: string): ExtensionLoadDiagnosis;
+export declare function diagnoseExtensionLoad(reason: string | undefined | null, label?: string, explicitPath?: string | null, versions?: ExtensionVersionPair): ExtensionLoadDiagnosis;
 export {};

package/dist/core/lbug/extension-load-error.js

@@ -24,6 +24,8 @@
  * lbug) and never throws — any read failure degrades to the string classifier.
  */
 import { closeSync, openSync, readSync } from 'node:fs';
+/** Kinds whose remedy must replace the generic network-install tail. */
+export const usesClassifiedLoadRemedy = (kind) => kind === 'missing_dependency' || kind === 'version_skew';
 /** LadybugDB says the extension file was never installed. INSTALL can heal it. */
 const MISSING_FILE_SIGNATURES = [
     /has not been installed/i,
@@ -92,6 +94,10 @@ const LOAD_FAILURE_WRAPPER = /failed to load library/i;
 // VECTOR through the same classifier, and FTS-specific advice (`--repair-fts`
 // repairs FTS indexes only) must not be dispensed for other extensions.
 const repairFtsHint = (label, lead) => label === 'FTS' ? ` (${lead}\`gitnexus analyze --repair-fts\`)` : '';
+const VERSION_SKEW_HINT = 'This is a version mismatch, not a missing host runtime.';
+const versionSkewRemedy = (label, expected, found) => `The ${label} extension version ${found} does not match the expected ${expected}. ` +
+    `Use a matching artifact${repairFtsHint(label, 'or ')} and run \`gitnexus doctor\`. ` +
+    VERSION_SKEW_HINT;
 const missingFileRemedy = (label) => `The ${label} extension is not installed. Re-run with network access and ` +
     `GITNEXUS_LBUG_EXTENSION_INSTALL=auto${repairFtsHint(label, 'or ')} to download it.`;
 const corruptFileRemedy = (label) => `The ${label} extension file is present but unreadable (corrupt, truncated, or built for another ` +
@@ -102,22 +108,18 @@ const corruptFileRemedy = (label) => `The ${label} extension file is present but
 // drift between them (#2383 F5).
 const VC_REDIST_INSTALL_HINT = 'the Microsoft Visual C++ 2015-2022 Redistributable (x64) from ' +
     'https://aka.ms/vs/17/release/vc_redist.x64.exe';
-// Git for Windows already ships the OpenSSL 3 DLLs in its mingw64 bin directory,
-// so the identical command that fails in PowerShell succeeds in Git Bash (#2669
-// reporter, who had the VC++ redist installed and still failed until that
-// directory was on PATH). Deliberately a fixed system path and never a
-// user-profile one: remedy text is NOT path-redacted (fts-indexes.ts redacts
-// only the reason), and fts-degraded-warning.test.ts asserts that no
-// `C:\Users\…` path ever reaches a user through this surface.
-const GIT_BASH_OPENSSL_HINT = ' If Git for Windows is installed you already have those DLLs: run the same command from Git Bash, ' +
-    'or prepend "C:\\Program Files\\Git\\mingw64\\bin" to PATH.';
+// U7 arm B (OQ1 unanswered; KTD13 forbids shipping OpenSSL DLLs without a
+// named CVE owner). Name the system runtimes. Do not tell anyone to borrow
+// DLLs from Git for Windows or prepend a third-party application directory.
+const WINDOWS_OPENSSL_RUNTIME_HINT = ' If the error persists, install OpenSSL 3 as a system runtime so ' +
+    'libcrypto-3-x64.dll and libssl-3-x64.dll resolve without borrowing them ' +
+    'from another application.';
 // MSVC-first per DuckDB's canonical answer for this exact error; OpenSSL second.
 const windowsMissingDependencyRemedy = (label) => `The ${label} extension is present but a required runtime library is missing (Windows error 126). ` +
     'Reinstalling the extension will NOT help. Install ' +
     VC_REDIST_INSTALL_HINT +
-    '; if the error persists, the extension also needs OpenSSL 3 ' +
-    '(libcrypto-3-x64.dll / libssl-3-x64.dll) on the DLL search path.' +
-    GIT_BASH_OPENSSL_HINT;
+    '.' +
+    WINDOWS_OPENSSL_RUNTIME_HINT;
 const posixMissingDependencyRemedy = (label) => `The ${label} extension is present but a shared library it depends on could not be loaded (named in ` +
     'the error above). Reinstalling the extension will NOT help — install that library or add it to ' +
     'your loader search path.';
@@ -170,8 +172,7 @@ export function classifyExtensionLoadError(reason, label = 'FTS') {
 const structuralMissingDependencyRemedy = (label) => `The ${label} extension file is valid, so the failure is a missing or incompatible runtime dependency, ` +
     'not the extension itself — reinstalling will NOT help. On Windows, install ' +
     VC_REDIST_INSTALL_HINT +
-    ' and ensure OpenSSL 3 is available; on Linux/macOS install the shared library named in the error above.' +
-    GIT_BASH_OPENSSL_HINT;
+    ' and install OpenSSL 3 as a system runtime; on Linux/macOS install the shared library named in the error above.';
 /**
  * Pull the extension file path out of lbug's load error. lbug's wrapper is
  * English regardless of OS language — `Failed to load library: {path} which is
@@ -301,10 +302,10 @@ export function inspectExtensionBinary(extensionPath) {
  * classifier (which still carries the language-independent hedged fallback). This
  * is the entry point every surface should call.
  */
-export function diagnoseExtensionLoad(reason, label = 'FTS') {
+export function diagnoseExtensionLoad(reason, label = 'FTS', explicitPath, versions) {
     const text = reason ?? '';
     const stringResult = classifyExtensionLoadError(text, label);
-    const fileState = inspectExtensionBinary(extractExtensionPath(text));
+    const fileState = inspectExtensionBinary(explicitPath ?? extractExtensionPath(text));
     if (fileState === 'corrupt') {
         return { kind: 'corrupt_file', remedy: corruptFileRemedy(label) };
     }
@@ -319,6 +320,12 @@ export function diagnoseExtensionLoad(reason, label = 'FTS') {
         if (stringResult.kind === 'corrupt_file') {
             return stringResult;
         }
+        if (versions?.expected && versions.found && versions.expected !== versions.found) {
+            return {
+                kind: 'version_skew',
+                remedy: versionSkewRemedy(label, versions.expected, versions.found),
+            };
+        }
         // A structurally sound binary that still failed to load ⇒ a dependency/runtime
         // problem, decided WITHOUT the localized tail. Keep the string classifier's
         // sharper remedy when it recognized the specific case (e.g. English 126).

package/dist/core/lbug/extension-loader.d.ts

@@ -1,4 +1,10 @@
 import { type ExtensionLoadDiagnosis } from './extension-load-error.js';
+export type ExtensionAttemptSource = 'vendored' | 'named' | 'install';
+/** Structured load attempt — source and tuple labels only, never a path. */
+export interface ExtensionLoadAttempt {
+    source: ExtensionAttemptSource;
+    tuple?: string;
+}
 /**
  * Lifecycle policy for an optional DuckDB extension.
  *
@@ -27,6 +33,8 @@ export interface ExtensionCapability {
      * cached remedy instead of re-inspecting the extension file on every call (#2383 F3).
      */
     diagnosis?: ExtensionLoadDiagnosis;
+    /** What this ensure() tried, labels only (KTD7). */
+    attempts?: ExtensionLoadAttempt[];
 }
 /** Per-call overrides applied on top of `ExtensionManager` defaults. */
 export interface ExtensionEnsureOptions {
@@ -44,6 +52,10 @@ export interface ExtensionEnsureOptions {
      * degradation goes unreported.
      */
     quiet?: boolean;
+    /** Injected vendor tree for tests / e2e. Never an attacker-controlled env. */
+    vendorRoot?: string;
+    /** Injected Node platform tuple (`linux-x64`). Defaults to this process. */
+    platformTuple?: string;
 }
 export interface ExtensionManagerOptions {
     policy?: ExtensionInstallPolicy;
@@ -81,12 +93,13 @@ export declare const installDuckDbExtensionOutOfProcess: (extensionName: string,
 /**
  * Centralized lifecycle manager for optional LadybugDB extensions.
  *
- * Always tries `LOAD EXTENSION <name>` first — it is per-connection,
- * idempotent, and never touches the network. If `LOAD` fails and the active
- * policy permits, the manager runs a single bounded out-of-process `INSTALL`
- * attempt per process and retries `LOAD`. Capability outcomes are cached so
- * unavailable extensions degrade search features without ever blocking
- * subsequent analyze or query calls.
+ * Tries `LOAD` first — it is per-connection, idempotent, and never
+ * touches the network. For FTS, a packaged vendored path is path-LOADed
+ * before the named `LOAD EXTENSION fts`. If `LOAD` fails and the active
+ * policy permits, the manager runs a single bounded out-of-process
+ * `INSTALL` attempt per process and retries `LOAD`. Capability outcomes
+ * are cached so unavailable extensions degrade search features without
+ * ever blocking subsequent analyze or query calls.
  *
  * Policy precedence (most specific wins):
  *   per-call `opts.policy` → constructor `options.policy` → env → `load-only`
@@ -118,6 +131,8 @@ export declare class ExtensionManager {
      * existed all along (#2374).
      */
     private tryLoad;
+    private tryLoadPath;
+    private composeReason;
     private markLoaded;
     private markUnavailable;
 }

package/dist/core/lbug/extension-loader.js

@@ -1,7 +1,9 @@
 import { spawn } from 'child_process';
 import { fileURLToPath } from 'node:url';
 import { LBUG_MAX_DB_SIZE } from './lbug-config.js';
-import { diagnoseExtensionLoad } from './extension-load-error.js';
+import { escapeCypherString } from './cypher-escape.js';
+import { diagnoseExtensionLoad, extractExtensionPath, } from './extension-load-error.js';
+import { defaultVendorRoot, isUnsupportedFtsTuple, nodePlatformTuple, resolveFtsVersionPair, resolveVendoredFtsPath, } from './vendored-extension-path.js';
 import { logger } from '../logger.js';
 const DEFAULT_EXTENSION_INSTALL_TIMEOUT_MS = 15_000;
 const EXTENSION_NAME_PATTERN = /^[A-Za-z][A-Za-z0-9_]*$/;
@@ -112,12 +114,13 @@ export const installDuckDbExtensionOutOfProcess = async (extensionName, timeoutM
 /**
  * Centralized lifecycle manager for optional LadybugDB extensions.
  *
- * Always tries `LOAD EXTENSION <name>` first — it is per-connection,
- * idempotent, and never touches the network. If `LOAD` fails and the active
- * policy permits, the manager runs a single bounded out-of-process `INSTALL`
- * attempt per process and retries `LOAD`. Capability outcomes are cached so
- * unavailable extensions degrade search features without ever blocking
- * subsequent analyze or query calls.
+ * Tries `LOAD` first — it is per-connection, idempotent, and never
+ * touches the network. For FTS, a packaged vendored path is path-LOADed
+ * before the named `LOAD EXTENSION fts`. If `LOAD` fails and the active
+ * policy permits, the manager runs a single bounded out-of-process
+ * `INSTALL` attempt per process and retries `LOAD`. Capability outcomes
+ * are cached so unavailable extensions degrade search features without
+ * ever blocking subsequent analyze or query calls.
  *
  * Policy precedence (most specific wins):
  *   per-call `opts.policy` → constructor `options.policy` → env → `load-only`
@@ -155,19 +158,46 @@ export class ExtensionManager {
         const timeoutMs = opts.installTimeoutMs ?? this.options.installTimeoutMs ?? getExtensionInstallTimeoutMs();
         const warn = this.options.warn ?? ((msg) => logger.warn(msg));
         const quiet = opts.quiet === true;
+        const attempts = [];
+        let lastInspectPath = null;
+        const versionsFor = (inspectPath) => name === 'fts' ? resolveFtsVersionPair(inspectPath, opts.vendorRoot) : undefined;
         if (policy === 'never') {
-            this.markUnavailable(name, label, 'extension install policy is "never"', warn, quiet);
+            this.markUnavailable(name, label, 'extension install policy is "never"', warn, quiet, attempts, null);
             return false;
         }
+        if (name === 'fts') {
+            const tuple = opts.platformTuple ?? nodePlatformTuple();
+            const vendorRoot = opts.vendorRoot ?? defaultVendorRoot();
+            const vendored = resolveVendoredFtsPath({ vendorRoot, tuple });
+            if (vendored) {
+                attempts.push({ source: 'vendored', tuple });
+                const vendoredError = await this.tryLoadPath(query, vendored);
+                if (vendoredError === null) {
+                    this.markLoaded(name, attempts);
+                    return true;
+                }
+                lastInspectPath = vendored;
+            }
+            else if (isUnsupportedFtsTuple(tuple, vendorRoot)) {
+                attempts.push({ source: 'vendored', tuple });
+                this.markUnavailable(name, label, this.composeReason(`no packaged FTS artifact for ${tuple}`, attempts), warn, quiet, attempts, null);
+                return false;
+            }
+        }
+        attempts.push({ source: 'named' });
         const loadError = await this.tryLoad(query, name);
         if (loadError === null) {
-            this.markLoaded(name);
+            this.markLoaded(name, attempts);
             return true;
         }
+        const namedPath = extractExtensionPath(loadError);
+        if (namedPath)
+            lastInspectPath = namedPath;
         if (policy === 'load-only') {
-            this.markUnavailable(name, label, `load-only policy (no install attempted); LOAD ${name} failed: ${loadError}`, warn, quiet);
+            this.markUnavailable(name, label, this.composeReason(`load-only policy (no install attempted); LOAD ${name} failed: ${loadError}`, attempts), warn, quiet, attempts, lastInspectPath, versionsFor(lastInspectPath));
             return false;
         }
+        attempts.push({ source: 'install' });
         let install = this.installAttempted.get(name);
         if (!install) {
             const installFn = this.options.installExtension ?? installDuckDbExtensionOutOfProcess;
@@ -177,15 +207,15 @@ export class ExtensionManager {
             this.installAttempted.set(name, install);
         }
         if (!install.success) {
-            this.markUnavailable(name, label, `${install.message}; LOAD ${name} had failed: ${loadError}`, warn, quiet);
+            this.markUnavailable(name, label, this.composeReason(`${install.message}; LOAD ${name} had failed: ${loadError}`, attempts), warn, quiet, attempts, lastInspectPath, versionsFor(lastInspectPath));
             return false;
         }
         const retryError = await this.tryLoad(query, name);
         if (retryError === null) {
-            this.markLoaded(name);
+            this.markLoaded(name, attempts);
             return true;
         }
-        this.markUnavailable(name, label, `LOAD ${name} failed after successful INSTALL: ${retryError}`, warn, quiet);
+        this.markUnavailable(name, label, this.composeReason(`LOAD ${name} failed after successful INSTALL: ${retryError}`, attempts), warn, quiet, attempts, extractExtensionPath(retryError), versionsFor(extractExtensionPath(retryError)));
         return false;
     }
     /**
@@ -206,17 +236,42 @@ export class ExtensionManager {
             return alreadyAvailable(msg) ? null : oneLine(msg);
         }
     }
-    markLoaded(name) {
-        this.capabilities.set(name, { name, loaded: true });
+    async tryLoadPath(query, absPath) {
+        try {
+            await query(`LOAD EXTENSION '${escapeCypherString(absPath)}'`);
+            return null;
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            return alreadyAvailable(msg) ? null : oneLine(msg);
+        }
+    }
+    composeReason(base, attempts) {
+        if (!attempts.some((attempt) => attempt.source === 'vendored'))
+            return base;
+        const trail = attempts
+            .map((attempt) => attempt.source === 'vendored' ? `vendored ${attempt.tuple}` : attempt.source)
+            .join(', ');
+        return `${base} (attempts: ${trail})`;
+    }
+    markLoaded(name, attempts = []) {
+        const record = attempts.some((attempt) => attempt.source === 'vendored') ? attempts : undefined;
+        this.capabilities.set(name, {
+            name,
+            loaded: true,
+            ...(record ? { attempts: record } : {}),
+        });
     }
-    markUnavailable(name, label, reason, warn, quiet = false) {
+    markUnavailable(name, label, reason, warn, quiet = false, attempts = [], inspectPath = null, versions) {
         // Classify once here (the single load-failure sink, run per Database not per
         // request) so the hot per-request warning path does no file I/O (#2383 F3).
+        // Diagnose the LAST attempt's file, never a path scraped from concatenated text.
         this.capabilities.set(name, {
             name,
             loaded: false,
             reason,
-            diagnosis: diagnoseExtensionLoad(reason, label),
+            attempts,
+            diagnosis: diagnoseExtensionLoad(reason, label, inspectPath, versions),
         });
         const message = `GitNexus: ${label} extension unavailable; continuing without ${label} features. ${reason}`;
         // A quiet probe must not register the dedup key: the owning caller may hit

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

@@ -1,6 +1,6 @@
 import lbug from '@ladybugdb/core';
 import { KnowledgeGraph } from '../graph/types.js';
-import type { ContentRetention } from '../../storage/repo-meta.js';
+import { type ContentRetention } from '../../storage/repo-meta.js';
 import { NodeTableName } from './schema.js';
 import type { GraphEmitManifest } from './graph-emit-sink.js';
 import type { PdgEmitManifest } from './pdg-emit-sink.js';
@@ -22,10 +22,9 @@ export declare const getDatabase: () => lbug.Database | null;
 /**
  * Return true when the error message indicates a write was attempted against
  * a read-only LadybugDB connection. The MCP query pool opens DBs read-only,
- * so any path that calls a `CREATE_*` procedure there will surface this
- * (e.g. defensive `ensureFTSIndex` calls). Owners of the writable analyze
- * path should ignore this error — index creation is owned by `gitnexus
- * analyze` and either already happened or will happen on the next run.
+ * so any path that calls a `CREATE_*` procedure there will surface this.
+ * Index creation is owned by `gitnexus analyze` and either already happened
+ * or will happen on the next run.
  */
 export declare const isReadOnlyDbError: (err: unknown) => boolean;
 /**
@@ -640,8 +639,8 @@ export declare const loadFTSExtension: (targetConn?: lbug.Connection, opts?: Ext
 export declare const loadVectorExtension: (targetConn?: lbug.Connection, opts?: ExtensionEnsureOptions) => Promise<boolean>;
 /**
  * Default stemmer for FTS indexes. Single source so the analyze path
- * (`getSearchFTSStemmer`) and the read-only `createFTSIndex`/`ensureFTSIndex`
- * defaults can never silently diverge.
+ * (`getSearchFTSStemmer`) and `createFTSIndex` defaults can never silently
+ * diverge.
  */
 export declare const DEFAULT_FTS_STEMMER = "porter";
 /**
@@ -848,24 +847,6 @@ export declare const ensureEmbeddingRowDmlSafe: (indexRows?: IndexCatalogSnapsho
 export declare const ensureFtsRowDmlSafe: (indexRows?: IndexCatalogSnapshot, options?: {
     skipFts?: boolean;
 }) => Promise<boolean>;
-/**
- * Lazy-create an FTS index, caching the fact in-process.
- *
- * Kept for writable maintenance paths that need to lazily materialize an
- * index. Read-only query paths must not call this; production analysis owns
- * creating the configured search indexes before the database is served.
- *
- * Safe to call repeatedly — the in-process Set guarantees only the first
- * call hits LadybugDB. `closeLbug` clears the cache so re-init starts fresh.
- *
- * Defense in depth: if the active connection is read-only (e.g. the MCP
- * pool adapter), `CREATE_FTS_INDEX` will fail with "Cannot execute write
- * operations in a read-only database". Treat that as a no-op and cache
- * the key so callers don't loop on a path that can never succeed here —
- * the index is owned by `gitnexus analyze` (writable) and either already
- * exists or will be created on the next analyze.
- */
-export declare const ensureFTSIndex: (tableName: string, indexName: string, properties: string[], stemmer?: string) => Promise<void>;
 export type FtsQueryFailureClass = 'missing-index' | 'missing-table' | 'other';
 /**
  * Classify a `QUERY_FTS_INDEX` failure so a genuinely-missing index (normal —