gitnexus 1.6.6-rc.89 → 1.6.6-rc.90

package/dist/cli/analyze.js

@@ -828,6 +828,14 @@ const analyzeCommandImpl = async (inputPath, options) => {
         console.log(`\n  Repository indexed successfully (${totalTime}s)\n`);
         console.log(`  ${(s.nodes ?? 0).toLocaleString()} nodes | ${(s.edges ?? 0).toLocaleString()} edges | ${s.communities ?? 0} clusters | ${s.processes ?? 0} flows`);
         console.log(`  ${repoPath}`);
+        // Persistent (non-scrolling) warning when FTS indexing was skipped — the
+        // 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) {
+            console.log(`\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 rerun, or\n` +
+                `  run \`gitnexus analyze --repair-fts\` when connected. Run \`gitnexus doctor\` for details.`);
+        }
         try {
             await fs.access(getGlobalRegistryPath());
         }

package/dist/cli/doctor.js

@@ -2,6 +2,7 @@ import { getRuntimeCapabilities, getRuntimeFingerprint } from '../core/platform/
 import { resolveEmbeddingConfig } from '../core/embeddings/config.js';
 import { isHttpMode } from '../core/embeddings/http-client.js';
 import { checkLbugNative } from '../core/lbug/native-check.js';
+import { getExtensionInstallPolicy } from '../core/lbug/extension-loader.js';
 import { t } from './i18n/index.js';
 function isCombiningMark(codePoint) {
     return ((codePoint >= 0x0300 && codePoint <= 0x036f) ||
@@ -66,6 +67,16 @@ export const doctorCommand = async () => {
     console.log(`  ${label('doctor.labels.fullTextSearch', 18)}${capabilities.fts}`);
     console.log(`  ${label('doctor.labels.vectorIndex', 18)}${capabilities.vector}`);
     console.log(`  ${label('doctor.labels.semanticMode', 18)}${capabilities.semanticMode}`);
+    // 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'
+        ? ' (offline; load only, no network install)'
+        : installPolicy === 'never'
+            ? ' (optional extensions disabled)'
+            : ' (installs missing extensions over network)';
+    console.log(`  ${padDisplayEnd('Ext install:', 18)}${installPolicy}${policyHint}`);
     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/embeddings/embedding-pipeline.d.ts

@@ -9,6 +9,20 @@
  * 5. Create vector index for semantic search
  */
 import { type EmbeddingProgress, type EmbeddingConfig, type EmbeddableNode, type SemanticSearchResult, type EmbeddingContext } from './types.js';
+import type { ExtensionInstallPolicy } from '../lbug/extension-loader.js';
+/**
+ * Resolve the extension-install policy for the embedding WRITE path (analyze).
+ *
+ * Generating embeddings is an explicit opt-in to a feature that requires the
+ * VECTOR extension, so when the operator has NOT pinned a policy we default to
+ * `auto` (one bounded, out-of-process INSTALL) — matching the documented
+ * "auto = default for analyze" intent in extension-loader.ts. An explicit
+ * GITNEXUS_LBUG_EXTENSION_INSTALL=load-only|never|auto always wins, so an
+ * offline or locked-down operator is never silently forced onto the network
+ * (the #1153 regression caused by hard-coding `auto` here). Read on every call
+ * (not memoized) so test env stubbing works.
+ */
+export declare const resolveEmbeddingInstallPolicy: () => ExtensionInstallPolicy;
 /**
  * Bump this when the embedding text template changes in a way that should
  * invalidate existing vectors, such as metadata/header shape changes,

package/dist/core/embeddings/embedding-pipeline.js

@@ -21,13 +21,30 @@ import { loadVectorExtension } from '../lbug/lbug-adapter.js';
 import { getExactScanLimit } from '../platform/capabilities.js';
 import { logger } from '../logger.js';
 const isDev = process.env.NODE_ENV === 'development';
-const vectorUnavailableMessage = 'VECTOR extension is unavailable for this LadybugDB runtime; semantic search will use exact scan when embeddings exist.';
+const vectorUnavailableMessage = 'VECTOR extension unavailable; semantic embeddings fall back to exact scan. ' +
+    'To enable vector search, install it once with network access ' +
+    '(GITNEXUS_LBUG_EXTENSION_INSTALL=auto), or pre-install it for offline use. ' +
+    'Set GITNEXUS_LBUG_EXTENSION_INSTALL=never to skip installs and silence this.';
+/**
+ * Resolve the extension-install policy for the embedding WRITE path (analyze).
+ *
+ * Generating embeddings is an explicit opt-in to a feature that requires the
+ * VECTOR extension, so when the operator has NOT pinned a policy we default to
+ * `auto` (one bounded, out-of-process INSTALL) — matching the documented
+ * "auto = default for analyze" intent in extension-loader.ts. An explicit
+ * GITNEXUS_LBUG_EXTENSION_INSTALL=load-only|never|auto always wins, so an
+ * offline or locked-down operator is never silently forced onto the network
+ * (the #1153 regression caused by hard-coding `auto` here). Read on every call
+ * (not memoized) so test env stubbing works.
+ */
+export const resolveEmbeddingInstallPolicy = () => {
+    const raw = process.env.GITNEXUS_LBUG_EXTENSION_INSTALL;
+    if (raw === 'load-only' || raw === 'never' || raw === 'auto')
+        return raw;
+    return 'auto';
+};
 const ensureVectorExtensionAvailable = async () => {
-    const vectorReady = await loadVectorExtension();
-    if (!vectorReady) {
-        return false;
-    }
-    return true;
+    return loadVectorExtension(undefined, { policy: resolveEmbeddingInstallPolicy() });
 };
 /**
  * Bump this when the embedding text template changes in a way that should
@@ -176,7 +193,7 @@ export const runEmbeddingPipeline = async (executeQuery, executeWithReusedStatem
     let totalChunks = 0;
     try {
         const vectorAvailable = await ensureVectorExtensionAvailable();
-        if (!vectorAvailable && isDev) {
+        if (!vectorAvailable) {
             logger.warn(vectorUnavailableMessage);
         }
         // Phase 1: Load embedding model
@@ -427,7 +444,11 @@ export const semanticSearch = async (executeQuery, query, k = 10, maxDistance =
     const queryVec = embeddingToArray(queryEmbedding);
     const queryVecStr = `[${queryVec.join(',')}]`;
     let bestChunks = new Map();
-    if (await loadVectorExtension()) {
+    // Query/read path: NEVER spawn a network INSTALL on a user query. If the
+    // VECTOR extension was not pre-installed, fall back to exact scan rather than
+    // blocking the query on a download (offline-first; see extension-loader.ts
+    // "load-only" — used by all serve/MCP query paths).
+    if (await loadVectorExtension(undefined, { policy: 'load-only' })) {
         try {
             bestChunks = await collectBestChunks(k, async (fetchLimit) => {
                 const vectorQuery = `

package/dist/core/ingestion/languages/javascript/captures.js

@@ -31,6 +31,7 @@ import { splitImportStatement } from '../typescript/import-decomposer.js';
 import { getJsParser, getJsScopeQuery, jsCachedTreeMatchesGrammar } from './query.js';
 import { computeTsArityMetadata } from '../typescript/arity-metadata.js';
 import { synthesizeTsReceiverBinding } from '../typescript/receiver-binding.js';
+import { isArrayMethodCallbackArrow } from '../typescript/array-callback.js';
 import { getTreeSitterBufferSize } from '../../constants.js';
 import { parseSourceSafe } from '../../../tree-sitter/safe-parse.js';
 /** JS function-like node types that may carry a synthesized `this` binding.
@@ -601,6 +602,20 @@ export function emitJsScopeCaptures(sourceText, filePath, cachedTree) {
                 continue;
             }
         }
+        // #1876: drop @declaration.function for array higher-order-method
+        // callbacks (`const x = arr.map(a => …)`). The HOC-wrapped-arrow
+        // pattern matches them, but the binding holds a value, not a callable.
+        // The binding keeps its separate @declaration.const / .variable match,
+        // and the arrow's own @scope.function match (a different pattern) is
+        // untouched, so inner-call attribution falls through to the enclosing
+        // scope instead of a phantom Function.
+        const fnDeclAnchor = grouped['@declaration.function'];
+        if (fnDeclAnchor !== undefined) {
+            const arrowNode = findFunctionNode(tree.rootNode, fnDeclAnchor.range);
+            if (arrowNode !== null && isArrayMethodCallbackArrow(arrowNode)) {
+                continue;
+            }
+        }
         // Synthesize arity metadata on function-like declarations.
         const declAnchor = pickFirstDefined(grouped, FUNCTION_DECL_TAGS);
         if (declAnchor !== undefined) {

package/dist/core/ingestion/languages/javascript/query.js

@@ -144,6 +144,12 @@ const JAVASCRIPT_SCOPE_QUERY = `
 ;; HOC-wrapped variable declarations: const X = HOC((args) => { ... }).
 ;; Covers React.forwardRef, memo, useCallback, useMemo, observer,
 ;; debounce, and any user-defined HOC factory.
+;;
+;; #1876: this shape also matches array higher-order-method callbacks
+;; (const x = arr.map(a => ...)), where x is a value, not a function.
+;; Those are filtered out emit-side in captures.ts via
+;; isArrayMethodCallbackArrow (member-expression callee whose property
+;; is a known Array method), so only the @declaration.const survives.
 (lexical_declaration
   (variable_declarator
     name: (identifier) @declaration.name

package/dist/core/ingestion/languages/typescript/array-callback.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Array higher-order-method callback detection (issue #1876).
+ *
+ * The HOC-wrapped-arrow declaration pattern in the JS/TS scope queries
+ * (`const X = call((args) => …)`) was added for React idioms
+ * (`forwardRef` / `memo` / `useCallback`). It has the same AST shape as
+ * an array higher-order-method call (`const x = arr.map(a => …)`), so
+ * those callbacks also match and produce a spurious `@declaration.function`
+ * named after the binding — duplicating the `@declaration.const` /
+ * `@declaration.variable` def that the same binding already gets.
+ *
+ * For an array-method callback the binding holds a *value* (the method's
+ * result), not a callable, so the `Function` def is semantically wrong.
+ * `isArrayMethodCallbackArrow` lets the emitter (`captures.ts`) drop that
+ * `@declaration.function` match, leaving only the value def.
+ *
+ * Shared by both the JavaScript and TypeScript capture emitters — the
+ * relevant grammar nodes (`arrow_function`, `function_expression`,
+ * `arguments`, `call_expression`, `member_expression`,
+ * `property_identifier`) are identical across `tree-sitter-javascript`
+ * and `tree-sitter-typescript`.
+ *
+ * Pure given the input node. No I/O, no globals.
+ */
+import type { SyntaxNode } from '../../utils/ast-helpers.js';
+/**
+ * Array prototype higher-order methods whose result is a value, not a
+ * function. A callback passed to one of these is an anonymous callback,
+ * never a top-level function definition. Identifier-callee HOCs
+ * (`forwardRef(...)`, `useCallback(...)`, custom factories) are
+ * deliberately NOT listed — they keep their `Function` classification.
+ *
+ * Trade-off (unchanged from before #1876): a custom *fluent-API* member
+ * call with a callback whose method name is not in this set
+ * (`qb.where(x => …)`) still classifies as `Function`. There is no clean
+ * syntactic line beyond the well-known Array surface, so the set is
+ * intentionally closed and easy to extend.
+ *
+ * Receiver-blind, by design: the match keys on the method NAME only, never
+ * the receiver type (tree-sitter has no type information here). So an in-set
+ * name on a NON-array receiver — `Map`/`Set` `.forEach`, an RxJS
+ * `observable.map(…)`, a query builder `.sort(…)`, a lodash chain
+ * `.filter(…)` — is ALSO treated as a callback and has its
+ * `@declaration.function` dropped. This is an accepted limitation, not a
+ * regression: those bindings hold the call's *result value*, not a callable,
+ * so a value def is the correct classification anyway. The only genuine loss
+ * is a bespoke DSL whose in-set-named method returns something callable —
+ * rare enough to accept rather than guard with type inference. Pinned by the
+ * "in-set method on a non-array receiver" case in `*-captures.test.ts`.
+ */
+export declare const ARRAY_CALLBACK_METHODS: ReadonlySet<string>;
+/**
+ * True when `node` (an `arrow_function` / `function_expression`) is the
+ * callback argument of an array higher-order-method call, i.e. the
+ * enclosing call's callee is a `member_expression` whose property is one
+ * of {@link ARRAY_CALLBACK_METHODS}.
+ *
+ * Returns false for direct assignments (`const fn = () => {}` — parent is
+ * `variable_declarator`, not `arguments`) and for identifier-callee HOCs
+ * (`forwardRef(() => …)` — callee is an `identifier`, not a
+ * `member_expression`), so neither is ever suppressed.
+ *
+ * Intentional non-suppressing gaps (preserve current behavior, no
+ * regression): parenthesized callee `(arr.map)(cb)` (`parenthesized_expression`)
+ * and computed callee `arr['map'](cb)` (`subscript_expression`).
+ */
+export declare function isArrayMethodCallbackArrow(node: SyntaxNode): boolean;

package/dist/core/ingestion/languages/typescript/array-callback.js

@@ -0,0 +1,94 @@
+/**
+ * Array higher-order-method callback detection (issue #1876).
+ *
+ * The HOC-wrapped-arrow declaration pattern in the JS/TS scope queries
+ * (`const X = call((args) => …)`) was added for React idioms
+ * (`forwardRef` / `memo` / `useCallback`). It has the same AST shape as
+ * an array higher-order-method call (`const x = arr.map(a => …)`), so
+ * those callbacks also match and produce a spurious `@declaration.function`
+ * named after the binding — duplicating the `@declaration.const` /
+ * `@declaration.variable` def that the same binding already gets.
+ *
+ * For an array-method callback the binding holds a *value* (the method's
+ * result), not a callable, so the `Function` def is semantically wrong.
+ * `isArrayMethodCallbackArrow` lets the emitter (`captures.ts`) drop that
+ * `@declaration.function` match, leaving only the value def.
+ *
+ * Shared by both the JavaScript and TypeScript capture emitters — the
+ * relevant grammar nodes (`arrow_function`, `function_expression`,
+ * `arguments`, `call_expression`, `member_expression`,
+ * `property_identifier`) are identical across `tree-sitter-javascript`
+ * and `tree-sitter-typescript`.
+ *
+ * Pure given the input node. No I/O, no globals.
+ */
+/**
+ * Array prototype higher-order methods whose result is a value, not a
+ * function. A callback passed to one of these is an anonymous callback,
+ * never a top-level function definition. Identifier-callee HOCs
+ * (`forwardRef(...)`, `useCallback(...)`, custom factories) are
+ * deliberately NOT listed — they keep their `Function` classification.
+ *
+ * Trade-off (unchanged from before #1876): a custom *fluent-API* member
+ * call with a callback whose method name is not in this set
+ * (`qb.where(x => …)`) still classifies as `Function`. There is no clean
+ * syntactic line beyond the well-known Array surface, so the set is
+ * intentionally closed and easy to extend.
+ *
+ * Receiver-blind, by design: the match keys on the method NAME only, never
+ * the receiver type (tree-sitter has no type information here). So an in-set
+ * name on a NON-array receiver — `Map`/`Set` `.forEach`, an RxJS
+ * `observable.map(…)`, a query builder `.sort(…)`, a lodash chain
+ * `.filter(…)` — is ALSO treated as a callback and has its
+ * `@declaration.function` dropped. This is an accepted limitation, not a
+ * regression: those bindings hold the call's *result value*, not a callable,
+ * so a value def is the correct classification anyway. The only genuine loss
+ * is a bespoke DSL whose in-set-named method returns something callable —
+ * rare enough to accept rather than guard with type inference. Pinned by the
+ * "in-set method on a non-array receiver" case in `*-captures.test.ts`.
+ */
+export const ARRAY_CALLBACK_METHODS = new Set([
+    'map',
+    'filter',
+    'find',
+    'findIndex',
+    'findLast',
+    'findLastIndex',
+    'forEach',
+    'reduce',
+    'reduceRight',
+    'some',
+    'every',
+    'flatMap',
+    'sort',
+]);
+/**
+ * True when `node` (an `arrow_function` / `function_expression`) is the
+ * callback argument of an array higher-order-method call, i.e. the
+ * enclosing call's callee is a `member_expression` whose property is one
+ * of {@link ARRAY_CALLBACK_METHODS}.
+ *
+ * Returns false for direct assignments (`const fn = () => {}` — parent is
+ * `variable_declarator`, not `arguments`) and for identifier-callee HOCs
+ * (`forwardRef(() => …)` — callee is an `identifier`, not a
+ * `member_expression`), so neither is ever suppressed.
+ *
+ * Intentional non-suppressing gaps (preserve current behavior, no
+ * regression): parenthesized callee `(arr.map)(cb)` (`parenthesized_expression`)
+ * and computed callee `arr['map'](cb)` (`subscript_expression`).
+ */
+export function isArrayMethodCallbackArrow(node) {
+    const args = node.parent;
+    if (args === null || args.type !== 'arguments')
+        return false;
+    const call = args.parent;
+    if (call === null || call.type !== 'call_expression')
+        return false;
+    const callee = call.childForFieldName('function');
+    if (callee === null || callee.type !== 'member_expression')
+        return false;
+    const property = callee.childForFieldName('property');
+    if (property === null || property.type !== 'property_identifier')
+        return false;
+    return ARRAY_CALLBACK_METHODS.has(property.text);
+}

package/dist/core/ingestion/languages/typescript/captures.js

@@ -30,6 +30,7 @@ import { getTsParser, getTsScopeQuery, tsCachedTreeMatchesGrammar } from './quer
 import { recordCacheHit, recordCacheMiss } from './cache-stats.js';
 import { synthesizeTsReceiverBinding } from './receiver-binding.js';
 import { computeTsArityMetadata } from './arity-metadata.js';
+import { isArrayMethodCallbackArrow } from './array-callback.js';
 import { getTreeSitterBufferSize } from '../../constants.js';
 import { parseSourceSafe } from '../../../tree-sitter/safe-parse.js';
 /** tree-sitter-typescript node types for function-like scopes that may
@@ -228,6 +229,20 @@ export function emitTsScopeCaptures(sourceText, filePath, cachedTree) {
                 continue;
             }
         }
+        // #1876: drop @declaration.function for array higher-order-method
+        // callbacks (`const x = arr.map(a => …)`). The HOC-wrapped-arrow
+        // pattern matches them, but the binding holds a value, not a callable.
+        // The binding keeps its separate @declaration.const / .variable match,
+        // and the arrow's own @scope.function match (a different pattern) is
+        // untouched, so inner-call attribution falls through to the enclosing
+        // scope instead of a phantom Function.
+        const fnDeclAnchor = grouped['@declaration.function'];
+        if (fnDeclAnchor !== undefined) {
+            const arrowNode = findFunctionNode(tree.rootNode, fnDeclAnchor.range, groupedNodes['@declaration.function']);
+            if (arrowNode !== null && isArrayMethodCallbackArrow(arrowNode)) {
+                continue;
+            }
+        }
         // Synthesize arity metadata on function-like declaration anchors
         // before pushing the match. The registry uses these to narrow
         // overloads — TypeScript supports overload signatures via

package/dist/core/ingestion/languages/typescript/query.js

@@ -246,20 +246,22 @@ const TYPESCRIPT_SCOPE_QUERY = `
 ;; that promotes the binding to the parent scope (where \`const X\`
 ;; lives).
 ;;
-;; Trade-off — chained array-method form: \`const x = arr.find((y) => p(y))\`
-;; has the same syntactic shape and would also match, naming the
-;; \`.find\` callback as \`x\`. The resulting \`Function:x\` is mostly
-;; harmless: \`x\` is consumed as a value (\`if (x) { ... }\`), never
-;; invoked as a function, so it gets zero incoming \`CALLS\` edges. The
-;; one outgoing edge \`Function:x → p\` is a minor mis-attribution that
-;; could in principle be fixed by adding a \`function: [(identifier)
-;; (member_expression)]\` predicate that excludes property-identifiers
-;; matching a known array-method blocklist (\`map\` / \`filter\` / \`find\`
-;; / \`reduce\` / \`forEach\` / \`some\` / \`every\`). We don't do that here
-;; because (a) the false-positive cost is negligible, (b) the blocklist
-;; would need maintenance, and (c) any user-defined fluent-API method
-;; with a callback argument would still false-positive — there's no
-;; clean syntactic line.
+;; #1876 — chained array-method form: \`const x = arr.find((y) => p(y))\`
+;; has the same syntactic shape and matches here too, naming the
+;; \`.find\` callback as \`x\`. Because \`x\` holds a value (the method
+;; result), not a callable, the spurious \`Function:x\` def is dropped
+;; emit-side in captures.ts: \`isArrayMethodCallbackArrow\` skips any
+;; \`@declaration.function\` whose enclosing call has a member-expression
+;; callee with a known Array-method property (\`ARRAY_CALLBACK_METHODS\`:
+;; \`map\` / \`filter\` / \`find\` / \`reduce\` / \`forEach\` / \`some\` /
+;; \`every\` / …). Only the \`@declaration.variable\` survives, so the
+;; binding is a single value def and calls inside the callback attribute
+;; to the enclosing scope rather than \`Function:x\`.
+;;
+;; Residual (intentional): a user-defined fluent-API method with a
+;; callback (\`qb.where(x => …)\`) is NOT in the blocklist and still
+;; classifies as \`Function\` — there's no clean syntactic line beyond
+;; the well-known Array surface, so the set is closed and easy to extend.
 ;;
 ;; Trade-off — multi-arrow arguments: \`const x = call(arrow1, arrow2)\`
 ;; would emit TWO matches with the same name \`x\`. tree-sitter-query

package/dist/core/ingestion/scope-extractor.d.ts

@@ -58,7 +58,7 @@
  *   - `ParsedFile.localDefs`     — flattened union of `Scope.ownedDefs`.
  *   - `ParsedFile.referenceSites` — pre-resolution usage facts.
  */
-import type { CaptureMatch, ParsedFile } from '../../_shared/index.js';
+import type { CaptureMatch, ParsedFile, SymbolDefinition } from '../../_shared/index.js';
 import type { LanguageProvider } from './language-provider.js';
 /**
  * The subset of `LanguageProvider` hooks that `extract()` reads. Declared
@@ -86,3 +86,35 @@ export type ScopeExtractorHooks = Pick<LanguageProvider, 'resolveScopeKind' | 'b
  * templates with mixed PHP/HTML/JS).
  */
 export declare function extract(matches: readonly CaptureMatch[], filePath: string, provider: ScopeExtractorHooks): ParsedFile;
+/**
+ * Collapse rule for the deferred node-creation migration (#1876).
+ *
+ * When graph-node creation moves from the legacy DAG onto the
+ * registry-primary path, a single source binding can carry more than one
+ * `SymbolDefinition` for the same name in the same scope — e.g. a direct
+ * arrow `const fn = () => {}` is classified BOTH as a `Function` (the
+ * arrow) and a `Variable` (the binding). Emitting one graph node per def
+ * would reproduce exactly the duplicate-node bug this issue tracks.
+ *
+ * `selectNodeBearingDef` picks the ONE def that should bear the graph node
+ * for such a binding group:
+ *
+ *   1. a function-like def (`Function` / `Method` / `Constructor`) if any —
+ *      the binding is callable and must keep incoming `CALLS` edges;
+ *   2. otherwise a value def (`Const` / `Variable`) — the binding holds a
+ *      value (e.g. an array-method result after the U1/U2 narrowing);
+ *   3. otherwise the first def — deterministic fallback for label sets this
+ *      rule does not rank.
+ *
+ * INPUT CONTRACT: `group` must be the defs bound to ONE name within ONE
+ * scope (a binding group). It deliberately does NOT dedup by range —
+ * `SymbolDefinition` carries no range and `makeDefId` encodes only the
+ * start position, so containment is uncomputable here; the caller forms the
+ * group (e.g. from a scope's `ownedDefs` keyed by name) before calling.
+ *
+ * Pure. No production call site yet — this dead export is intentional and
+ * tracked by #1876 (the deferred node-creation migration); it is the
+ * executable contract that follow-up will consume, pinned today by the
+ * scope-extractor unit test.
+ */
+export declare function selectNodeBearingDef(group: readonly SymbolDefinition[]): SymbolDefinition | undefined;

package/dist/core/ingestion/scope-extractor.js

@@ -569,6 +569,59 @@ function normalizeNodeLabel(kindStr) {
             return undefined;
     }
 }
+/** Function-like labels: callable defs that must keep incoming CALLS edges. */
+const NODE_BEARING_FUNCTION_LABELS = new Set([
+    'Function',
+    'Method',
+    'Constructor',
+]);
+/** Value labels: non-callable bindings (a `const`/`let`/`var` holds a value). */
+const NODE_BEARING_VALUE_LABELS = new Set([
+    'Const',
+    'Variable',
+]);
+/**
+ * Collapse rule for the deferred node-creation migration (#1876).
+ *
+ * When graph-node creation moves from the legacy DAG onto the
+ * registry-primary path, a single source binding can carry more than one
+ * `SymbolDefinition` for the same name in the same scope — e.g. a direct
+ * arrow `const fn = () => {}` is classified BOTH as a `Function` (the
+ * arrow) and a `Variable` (the binding). Emitting one graph node per def
+ * would reproduce exactly the duplicate-node bug this issue tracks.
+ *
+ * `selectNodeBearingDef` picks the ONE def that should bear the graph node
+ * for such a binding group:
+ *
+ *   1. a function-like def (`Function` / `Method` / `Constructor`) if any —
+ *      the binding is callable and must keep incoming `CALLS` edges;
+ *   2. otherwise a value def (`Const` / `Variable`) — the binding holds a
+ *      value (e.g. an array-method result after the U1/U2 narrowing);
+ *   3. otherwise the first def — deterministic fallback for label sets this
+ *      rule does not rank.
+ *
+ * INPUT CONTRACT: `group` must be the defs bound to ONE name within ONE
+ * scope (a binding group). It deliberately does NOT dedup by range —
+ * `SymbolDefinition` carries no range and `makeDefId` encodes only the
+ * start position, so containment is uncomputable here; the caller forms the
+ * group (e.g. from a scope's `ownedDefs` keyed by name) before calling.
+ *
+ * Pure. No production call site yet — this dead export is intentional and
+ * tracked by #1876 (the deferred node-creation migration); it is the
+ * executable contract that follow-up will consume, pinned today by the
+ * scope-extractor unit test.
+ */
+export function selectNodeBearingDef(group) {
+    if (group.length === 0)
+        return undefined;
+    const functionLike = group.find((def) => NODE_BEARING_FUNCTION_LABELS.has(def.type));
+    if (functionLike !== undefined)
+        return functionLike;
+    const value = group.find((def) => NODE_BEARING_VALUE_LABELS.has(def.type));
+    if (value !== undefined)
+        return value;
+    return group[0];
+}
 function makeDefId(filePath, range, type, name) {
     return `def:${filePath}#${range.startLine}:${range.startCol}:${type}:${name}`;
 }

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

@@ -32,6 +32,22 @@ export interface ExtensionManagerOptions {
     installExtension?: (extensionName: string, timeoutMs: number) => Promise<ExtensionInstallResult>;
     warn?: (message: string) => void;
 }
+export declare const getExtensionInstallPolicy: () => ExtensionInstallPolicy;
+/**
+ * Install policy for the **analyze (write) path**.
+ *
+ * The global default (`resolvePolicyFromEnv`) is `load-only` so serve/query
+ * read paths never require outbound network access (PR #1161, offline-first).
+ * The analyze path is different: it owns building the search indexes, so it
+ * defaults to `auto` — LOAD the extension if present, otherwise attempt one
+ * bounded out-of-process INSTALL. This keeps FTS symmetric with the
+ * VECTOR/embeddings path (which already defaults to `auto`) and matches the
+ * #726 contract. An explicit `GITNEXUS_LBUG_EXTENSION_INSTALL` value still
+ * wins, so operators can force `load-only`/`never` for fully offline analyze;
+ * `auto` LOADs-first, so offline machines still degrade gracefully when the
+ * INSTALL cannot reach the network.
+ */
+export declare const resolveAnalyzeInstallPolicy: () => ExtensionInstallPolicy;
 export declare const getExtensionInstallTimeoutMs: () => number;
 export declare const getExtensionInstallChildProcessArgs: (extensionName: string, maxDbSize?: number) => string[];
 /**
@@ -54,7 +70,7 @@ export declare const installDuckDbExtensionOutOfProcess: (extensionName: string,
  * subsequent analyze or query calls.
  *
  * Policy precedence (most specific wins):
- *   per-call `opts.policy` → constructor `options.policy` → env → `auto`
+ *   per-call `opts.policy` → constructor `options.policy` → env → `load-only`
  */
 export declare class ExtensionManager {
     private readonly options;

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

@@ -8,6 +8,27 @@ const alreadyAvailable = (message) => message.includes('already loaded') ||
     message.includes('already installed') ||
     message.includes('already exists');
 const resolvePolicyFromEnv = () => {
+    const raw = process.env.GITNEXUS_LBUG_EXTENSION_INSTALL;
+    if (raw === 'load-only' || raw === 'never' || raw === 'auto')
+        return raw;
+    return 'load-only';
+};
+export const getExtensionInstallPolicy = () => resolvePolicyFromEnv();
+/**
+ * Install policy for the **analyze (write) path**.
+ *
+ * The global default (`resolvePolicyFromEnv`) is `load-only` so serve/query
+ * read paths never require outbound network access (PR #1161, offline-first).
+ * The analyze path is different: it owns building the search indexes, so it
+ * defaults to `auto` — LOAD the extension if present, otherwise attempt one
+ * bounded out-of-process INSTALL. This keeps FTS symmetric with the
+ * VECTOR/embeddings path (which already defaults to `auto`) and matches the
+ * #726 contract. An explicit `GITNEXUS_LBUG_EXTENSION_INSTALL` value still
+ * wins, so operators can force `load-only`/`never` for fully offline analyze;
+ * `auto` LOADs-first, so offline machines still degrade gracefully when the
+ * INSTALL cannot reach the network.
+ */
+export const resolveAnalyzeInstallPolicy = () => {
     const raw = process.env.GITNEXUS_LBUG_EXTENSION_INSTALL;
     if (raw === 'load-only' || raw === 'never' || raw === 'auto')
         return raw;
@@ -93,7 +114,7 @@ export const installDuckDbExtensionOutOfProcess = async (extensionName, timeoutM
  * subsequent analyze or query calls.
  *
  * Policy precedence (most specific wins):
- *   per-call `opts.policy` → constructor `options.policy` → env → `auto`
+ *   per-call `opts.policy` → constructor `options.policy` → env → `load-only`
  */
 export class ExtensionManager {
     options;

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

@@ -88,6 +88,13 @@ export interface AnalyzeResult {
     pipelineResult?: any;
     /** True when analyze only repaired FTS indexes and skipped pipeline re-analysis. */
     ftsRepairedOnly?: boolean;
+    /**
+     * True when the FTS extension was unavailable so search-index creation was
+     * skipped (offline-first degradation). The graph is fully queryable; only
+     * full-text/BM25 search is disabled. Lets callers (CLI summary, server) and
+     * the persisted meta surface the degraded state instead of reporting healthy.
+     */
+    ftsSkipped?: boolean;
 }
 export { deriveEmbeddingMode, DEFAULT_EMBEDDING_NODE_LIMIT } from './embedding-mode.js';
 export type { EmbeddingMode } from './embedding-mode.js';

package/dist/core/run-analyze.js

@@ -12,8 +12,9 @@ import path from 'path';
 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 { initLbug, loadGraphToLbug, getLbugStats, executeQuery, executeWithReusedStatement, closeLbug, loadCachedEmbeddings, deleteNodesForFile, deleteAllCommunitiesAndProcesses, queryImporters, loadFTSExtension, } from './lbug/lbug-adapter.js';
 import { createSearchFTSIndexes, verifySearchFTSIndexes } from './search/fts-indexes.js';
+import { resolveAnalyzeInstallPolicy } from './lbug/extension-loader.js';
 import { startWalCheckpointDriver, } from './lbug/wal-checkpoint-driver.js';
 import { getStoragePaths, saveMeta, loadMeta, ensureGitNexusIgnored, registerRepo, cleanupOldKuzuFiles, INCREMENTAL_SCHEMA_VERSION, } from '../storage/repo-manager.js';
 import { computeFileHashes, diffFileHashes } from '../storage/file-hash.js';
@@ -24,6 +25,15 @@ import { getCurrentCommit, getRemoteUrl, hasGitDir, getInferredRepoName, resolve
 import { generateAIContextFiles } from '../cli/ai-context.js';
 import { EMBEDDING_TABLE_NAME } from './lbug/schema.js';
 import { STALE_HASH_SENTINEL } from './lbug/schema.js';
+/**
+ * Logged when the optional FTS extension cannot be loaded or installed during
+ * a full analyze. Kept as a named constant so the env-var/command guidance
+ * stays in one place (mirrors the VECTOR message in embedding-pipeline.ts).
+ */
+const FTS_UNAVAILABLE_MESSAGE = 'FTS extension unavailable; skipping search-index creation. ' +
+    'Full-text/BM25 search will be disabled until the LadybugDB FTS extension is ' +
+    'installed once with network access (GITNEXUS_LBUG_EXTENSION_INSTALL=auto) or ' +
+    'pre-installed for offline use. Run `gitnexus doctor` for details.';
 // Re-export the pure flag-derivation helper so external callers (and tests)
 // keep importing from this module's stable surface.
 export { deriveEmbeddingMode, DEFAULT_EMBEDDING_NODE_LIMIT } from './embedding-mode.js';
@@ -495,21 +505,40 @@ export async function runFullAnalysis(repoPath, options, callbacks) {
             });
         }
         // ── Phase 3: FTS (85–90%) ─────────────────────────────────────────
+        // The analyze (write) path owns building the search indexes, so it uses
+        // the `auto` install policy (LOAD-first, then one bounded INSTALL) —
+        // symmetric with the VECTOR/embeddings path below and consistent with the
+        // #726 contract. The global `load-only` default (PR #1161) governs the
+        // serve/query read paths, not this one. When the extension still cannot be
+        // loaded (genuinely offline + not pre-installed, or policy forced to
+        // load-only/never), degrade gracefully — exactly like the VECTOR path — so
+        // analyze still produces a fully queryable graph; only full-text/BM25
+        // search falls back. `--repair-fts` (whose sole job is FTS) still fails
+        // loudly on its own path above.
         progress('fts', 85, 'Creating 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 ftsAvailable = await loadFTSExtension(undefined, {
+            policy: resolveAnalyzeInstallPolicy(),
         });
-        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.');
+        if (ftsAvailable) {
+            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');
+        }
+        else {
+            log(FTS_UNAVAILABLE_MESSAGE);
+            progress('fts', 90, 'Search indexes skipped (FTS unavailable)');
         }
-        progress('fts', 90, 'Search indexes ready');
         // ── Phase 3.5: Re-insert cached embeddings ────────────────────────
         // Runs on BOTH the full-rebuild path and the incremental path:
         //   - Full rebuild: DB was wiped, every cached row needs to come back.
@@ -661,7 +690,14 @@ export async function runFullAnalysis(repoPath, options, callbacks) {
             },
             capabilities: {
                 graph: { provider: 'ladybugdb', status: runtimeCapabilities.graph },
-                fts: { provider: 'ladybugdb-fts', status: runtimeCapabilities.fts },
+                // Reflect what this analyze run actually produced: when the FTS
+                // extension was unavailable the indexes were skipped, so record
+                // 'unavailable' rather than the static runtime default. Keeps
+                // meta.json / `gitnexus doctor` honest about degraded search.
+                fts: {
+                    provider: 'ladybugdb-fts',
+                    status: ftsAvailable ? runtimeCapabilities.fts : 'unavailable',
+                },
                 vectorSearch: {
                     provider: effectiveSemanticMode === 'vector-index' ? 'ladybugdb-vector' : 'exact-scan',
                     status: embeddingCount > 0 ? effectiveSemanticMode : 'unavailable',
@@ -748,6 +784,7 @@ export async function runFullAnalysis(repoPath, options, callbacks) {
             repoPath,
             stats: meta.stats,
             pipelineResult,
+            ftsSkipped: !ftsAvailable,
         };
     }
     catch (err) {

package/dist/mcp/server.d.ts

@@ -17,7 +17,22 @@ import type { LocalBackend } from './local/local-backend.js';
  * Transport-agnostic — caller connects the desired transport.
  */
 export declare function createMCPServer(backend: LocalBackend): Server;
+/** Conventional 128 + signal-number exit codes for graceful termination. */
+export declare const SHUTDOWN_EXIT_CODES: {
+    readonly SIGINT: 130;
+    readonly SIGTERM: 143;
+};
+type SignalRegistrar = (event: 'SIGINT' | 'SIGTERM', listener: (...args: unknown[]) => void) => void;
 /**
- * Start the MCP server on stdio transport (for CLI use).
+ * Wire SIGINT/SIGTERM to a graceful shutdown using NUMERIC exit codes.
+ *
+ * Node invokes signal listeners with the signal NAME string as the first
+ * argument, so registering an `(exitCode = 0) => process.exit(exitCode)`
+ * shutdown directly passes `'SIGTERM'` into `process.exit()` and crashes with
+ * `ERR_INVALID_ARG_TYPE` (#1132). These wrappers discard the signal argument
+ * and pass the conventional 128+signal code instead. `on` is injectable so the
+ * mapping can be unit-tested without touching the real process.
  */
+export declare function installSignalShutdown(shutdown: (exitCode?: number) => unknown, on?: SignalRegistrar): void;
 export declare function startMCPServer(backend: LocalBackend): Promise<void>;
+export {};

package/dist/mcp/server.js

@@ -245,6 +245,26 @@ Follow these steps:
 /**
  * Start the MCP server on stdio transport (for CLI use).
  */
+/** Force-exit fallback budget if graceful shutdown cleanup hangs. */
+const SHUTDOWN_FORCE_EXIT_MS = 5_000;
+/** Conventional 128 + signal-number exit codes for graceful termination. */
+export const SHUTDOWN_EXIT_CODES = { SIGINT: 130, SIGTERM: 143 };
+/**
+ * Wire SIGINT/SIGTERM to a graceful shutdown using NUMERIC exit codes.
+ *
+ * Node invokes signal listeners with the signal NAME string as the first
+ * argument, so registering an `(exitCode = 0) => process.exit(exitCode)`
+ * shutdown directly passes `'SIGTERM'` into `process.exit()` and crashes with
+ * `ERR_INVALID_ARG_TYPE` (#1132). These wrappers discard the signal argument
+ * and pass the conventional 128+signal code instead. `on` is injectable so the
+ * mapping can be unit-tested without touching the real process.
+ */
+export function installSignalShutdown(shutdown, on = (event, listener) => {
+    process.on(event, listener);
+}) {
+    on('SIGINT', () => void shutdown(SHUTDOWN_EXIT_CODES.SIGINT));
+    on('SIGTERM', () => void shutdown(SHUTDOWN_EXIT_CODES.SIGTERM));
+}
 export async function startMCPServer(backend) {
     const server = createMCPServer(backend);
     // Idempotent global sentinel install. cli/mcp.ts calls this first thing
@@ -281,6 +301,11 @@ export async function startMCPServer(backend) {
         if (shuttingDown)
             return;
         shuttingDown = true;
+        // Safety net: if backend.disconnect()/server.close() hangs, still exit so a
+        // SIGINT/SIGTERM reliably terminates the process. Unref'd so the timer alone
+        // never keeps the event loop alive.
+        const forceExit = setTimeout(() => process.exit(exitCode), SHUTDOWN_FORCE_EXIT_MS);
+        forceExit.unref();
         try {
             await backend.disconnect();
         }
@@ -291,24 +316,30 @@ export async function startMCPServer(backend) {
         catch { }
         const { flushLoggerSync } = await import('../core/logger.js');
         flushLoggerSync();
+        clearTimeout(forceExit);
         process.exit(exitCode);
     };
-    // Handle graceful shutdown
-    process.on('SIGINT', shutdown);
-    process.on('SIGTERM', shutdown);
+    // Handle graceful shutdown. Node invokes signal listeners with the signal
+    // NAME (e.g. 'SIGTERM') as the first argument; registering `shutdown`
+    // directly passed that string to process.exit() and crashed with
+    // ERR_INVALID_ARG_TYPE (#1132). Map each signal to its conventional
+    // 128+signal exit code instead.
+    installSignalShutdown(shutdown);
     // Log crashes to stderr so they aren't silently lost.
     // uncaughtException is fatal — shut down.
     // unhandledRejection is logged but kept non-fatal (availability-first):
     // killing the server for one missed catch would be worse than logging it.
     process.on('uncaughtException', (err) => {
         process.stderr.write(`GitNexus MCP uncaughtException: ${err?.stack || err}\n`);
-        shutdown(1);
+        void shutdown(1);
     });
     process.on('unhandledRejection', (reason) => {
         process.stderr.write(`GitNexus MCP unhandledRejection: ${reason?.stack || reason}\n`);
     });
-    // Handle stdio errors — stdin close means the parent process is gone
-    process.stdin.on('end', shutdown);
-    process.stdin.on('error', () => shutdown());
-    process.stdout.on('error', () => shutdown());
+    // Handle stdio errors — stdin close means the parent process is gone.
+    // Wrap so the event payload (e.g. an Error for 'error') can never reach
+    // process.exit() as a non-numeric exit code, and void the returned promise.
+    process.stdin.on('end', () => void shutdown(0));
+    process.stdin.on('error', () => void shutdown(0));
+    process.stdout.on('error', () => void shutdown(0));
 }

package/package.json

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