gitnexus 1.6.9 → 1.6.10-aptos.0

package/dist/storage/parsedfile-store.js

@@ -51,10 +51,15 @@ import { promises as fs, mkdirSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
 import v8 from 'node:v8';
 import vm from 'node:vm';
+import { logger } from '../core/logger.js';
 import { mapReplacer, mapReviver } from './parse-cache.js';
 const STORE_DIRNAME = 'parsedfile-store';
 const DURABLE_DIRNAME = 'parsedfile-cache';
 const DURABLE_INDEX_FILENAME = 'index.json';
+const MAX_CALLABLE_FLOW_SITES_PER_FILE = 100_000;
+const MAX_CALLABLE_FLOW_INDIRECTION = 16;
+const MAX_CALLABLE_FLOW_NAME_LENGTH = 4_096;
+const MAX_CALLABLE_FLOW_PARAMETERS = 1_024;
 /**
  * Build a JSON.parse reviver that (a) interns every string against a shared
  * pool and (b) applies the parse-cache `mapReviver` (Map/Set reconstruction).
@@ -217,6 +222,8 @@ export const loadParsedFilesForPaths = async (storagePath, wantPaths) => {
     // (one `int` / one repeated filePath for the whole language), which is where
     // most of the saving comes from. Dropped when this function returns.
     const pool = new Map();
+    let droppedSites = 0;
+    let filesWithDroppedSites = 0;
     for (let i = 0; i < shards.length; i++) {
         // Per-shard def pool: a SymbolDefinition's three serialized copies live within
         // a single shard (one ParsedFile), so the dedup is shard-local. A cross-shard
@@ -235,9 +242,19 @@ export const loadParsedFilesForPaths = async (storagePath, wantPaths) => {
         if (!Array.isArray(parsed))
             continue;
         for (const pf of parsed) {
-            if (pf && typeof pf.filePath === 'string' && wantPaths.has(pf.filePath)) {
+            if (!pf || typeof pf.filePath !== 'string' || !wantPaths.has(pf.filePath))
+                continue;
+            const flow = sanitizeCallableFlowSites(pf.callableFlowSites);
+            if (flow === undefined)
+                continue; // non-array garbage → distrust the file, re-extract
+            if (flow.dropped === 0) {
                 out.set(pf.filePath, pf);
             }
+            else {
+                droppedSites += flow.dropped;
+                filesWithDroppedSites++;
+                out.set(pf.filePath, { ...pf, callableFlowSites: flow.sites });
+            }
         }
         // Every few shards, reclaim the transient pre-intern parse churn before it
         // piles up against the heap limit (~5 GB avoidable on the kernel), and
@@ -247,11 +264,158 @@ export const loadParsedFilesForPaths = async (storagePath, wantPaths) => {
             await new Promise((resolve) => setImmediate(resolve));
         }
     }
+    if (droppedSites > 0) {
+        // Facts for the dropped sites are omitted this run (the file itself is
+        // retained, so no re-extract happens) — surface it so a recurring drop
+        // on every warm load is observable rather than silent (#2522 review).
+        logger.warn({ droppedSites, files: filesWithDroppedSites }, 'parsedfile-store: dropped malformed/over-bound callable-flow sites at load; files retained without those facts');
+    }
     return out;
 };
+/**
+ * Treat the durable ParsedFile store as an untrusted serialization boundary.
+ * Sanitation is per-SITE, not per-file: one malformed or over-bound fact drops
+ * only itself (counted, logged by the caller), so a legitimately pathological
+ * source file cannot push its whole ParsedFile into a permanent, silent
+ * warm-cache-miss reparse loop (#2522 review). Only a non-array field —
+ * i.e. garbage that says the serialization itself is untrustworthy — rejects
+ * the file, and `undefined` (never emitted / no facts) passes through.
+ * Returns `undefined` for the reject-file case.
+ */
+function sanitizeCallableFlowSites(value) {
+    if (value === undefined)
+        return { sites: undefined, dropped: 0 };
+    if (!Array.isArray(value))
+        return undefined;
+    const bounded = value.length > MAX_CALLABLE_FLOW_SITES_PER_FILE
+        ? value.slice(0, MAX_CALLABLE_FLOW_SITES_PER_FILE)
+        : value;
+    const sites = bounded.filter(isValidCallableFlowSite);
+    return { sites, dropped: value.length - sites.length };
+}
+function isValidCallableFlowSite(value) {
+    if (!isRecord(value) || typeof value.kind !== 'string')
+        return false;
+    switch (value.kind) {
+        case 'seed':
+            return (isValidOperand(value.destination) &&
+                isBoundedString(value.targetName) &&
+                isOptionalBoundedString(value.targetQualifiedName) &&
+                isValidRange(value.targetRange) &&
+                isValidExpectedSignature(value.expectedSignature));
+        case 'copy':
+        case 'alias':
+        case 'address':
+            return isValidOperand(value.source) && isValidOperand(value.destination);
+        case 'store':
+            return isValidOperand(value.source) && isValidOperand(value.pointer);
+        case 'load':
+            return isValidOperand(value.pointer) && isValidOperand(value.destination);
+        case 'formal':
+            return (isBoundedString(value.ownerName) &&
+                isValidRange(value.ownerRange) &&
+                isSafeIndex(value.parameterIndex) &&
+                isValidOperand(value.binding) &&
+                (value.passingMode === 'value' ||
+                    value.passingMode === 'reference' ||
+                    value.passingMode === 'pointer') &&
+                isValidExpectedSignature(value.expectedSignature));
+        case 'argument':
+            return (isValidRange(value.callSite) &&
+                isSafeIndex(value.parameterIndex) &&
+                isValidOperand(value.source) &&
+                isOptionalBoundedString(value.directCalleeName));
+        case 'invoke':
+            return (isValidRange(value.callSite) &&
+                isBoundedString(value.inScope) &&
+                isValidOperand(value.callee) &&
+                (value.receiver === undefined || isValidOperand(value.receiver)) &&
+                (value.invocationKind === 'indirect' ||
+                    value.invocationKind === 'member-pointer' ||
+                    value.invocationKind === 'callable-object') &&
+                (value.arity === undefined || isSafeIndex(value.arity)));
+        default:
+            return false;
+    }
+}
+function isValidOperand(value) {
+    if (!isRecord(value))
+        return false;
+    return (isBoundedString(value.name) &&
+        isBoundedString(value.inScope) &&
+        isValidRange(value.atRange) &&
+        Number.isInteger(value.indirection) &&
+        value.indirection >= 0 &&
+        value.indirection <= MAX_CALLABLE_FLOW_INDIRECTION &&
+        typeof value.addressOf === 'boolean' &&
+        (value.expressionKind === undefined ||
+            value.expressionKind === 'binding' ||
+            value.expressionKind === 'callable-designator' ||
+            value.expressionKind === 'bound-member' ||
+            value.expressionKind === 'anonymous-callable') &&
+        isOptionalBoundedString(value.qualifiedName));
+}
+function isValidExpectedSignature(value) {
+    if (value === undefined)
+        return true;
+    if (!isRecord(value))
+        return false;
+    return ((value.parameterCount === undefined || isSafeIndex(value.parameterCount)) &&
+        isValidBoundedStringArray(value.parameterTypes) &&
+        (value.parameterTypeClasses === undefined ||
+            (Array.isArray(value.parameterTypeClasses) &&
+                value.parameterTypeClasses.length <= MAX_CALLABLE_FLOW_PARAMETERS &&
+                value.parameterTypeClasses.every(isRecord))) &&
+        (value.isConst === undefined || typeof value.isConst === 'boolean'));
+}
+function isValidBoundedStringArray(value) {
+    return (value === undefined ||
+        (Array.isArray(value) &&
+            value.length <= MAX_CALLABLE_FLOW_PARAMETERS &&
+            // '' is a legitimate entry meaning "unknown type" — the same convention
+            // as ReferenceSite.argumentTypes. C++ emits it for cv-qualifier-only or
+            // ERROR-recovered parameter types, so requiring non-empty here rejected
+            // real extractor output (#2522 review).
+            value.every((entry) => typeof entry === 'string' && entry.length <= MAX_CALLABLE_FLOW_NAME_LENGTH)));
+}
+function isValidRange(value) {
+    if (!isRecord(value))
+        return false;
+    return (isNonNegativeInteger(value.startLine) &&
+        isNonNegativeInteger(value.startCol) &&
+        isNonNegativeInteger(value.endLine) &&
+        isNonNegativeInteger(value.endCol));
+}
+function isRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+function isBoundedString(value) {
+    return (typeof value === 'string' && value.length > 0 && value.length <= MAX_CALLABLE_FLOW_NAME_LENGTH);
+}
+function isOptionalBoundedString(value) {
+    return value === undefined || isBoundedString(value);
+}
+function isNonNegativeInteger(value) {
+    return Number.isSafeInteger(value) && value >= 0;
+}
+function isSafeIndex(value) {
+    return isNonNegativeInteger(value) && value <= MAX_CALLABLE_FLOW_PARAMETERS;
+}
 /** Durable store dir — a sibling of `parsedfile-store/`, NEVER cleared per run. */
 export const getDurableParsedFileDir = (storagePath) => path.join(storagePath, DURABLE_DIRNAME);
 const durableChunkDir = (durableDir, chunkHash) => path.join(durableDir, chunkHash);
+/**
+ * Start a fresh durable generation for one content-addressed parse chunk.
+ * The main thread calls this once before dispatching a cache miss, before any
+ * worker can write that chunk. Recreating the directory immediately keeps the
+ * worker-side mkdir memoization valid while preventing old worker shard names
+ * from accumulating across analyses.
+ */
+export const prepareDurableParsedFileChunk = async (durableDir, chunkHash) => {
+    const dir = durableChunkDir(durableDir, chunkHash);
+    await fs.rm(dir, { recursive: true, force: true });
+    await fs.mkdir(dir, { recursive: true });
+};
 // Per-process set of durable chunk subdirs already `mkdir`ed (mirrors
 // `createdStoreDirs`) so the worker doesn't `mkdirSync` on every shard.
 const createdDurableDirs = new Set();

package/dist/storage/repo-manager.d.ts

@@ -13,6 +13,7 @@
  * construction (getStoragePath is per-checkout), regardless of which filename
  * the metadata inside it uses.
  */
+import type { MoveCompilerIdentity, MoveFlowReleaseSelection } from '../core/move/constants.js';
 import { branchSlug, resolveBranchPlacement, type BranchSummary } from './branch-index.js';
 export { branchSlug, resolveBranchPlacement };
 export type { BranchSummary };
@@ -54,10 +55,72 @@ export declare const canonicalizePath: (p: string) => string;
  * lookups/dedup/finalize checks all share so they answer identically.
  */
 export declare const registryPathEquals: (a: string, b: string) => boolean;
+/**
+ * Does the clone dir derived from an entry's *name* actually belong to that
+ * entry? Registry names are not unique across storage locations: a cloned
+ * repo under `~/.gitnexus/repos/<name>` and a local repo registered under the
+ * same name share a `getCloneDir(entry.name)` result. The server's delete
+ * handler must therefore never remove the clone dir based on the name alone —
+ * only when the entry's own `path` resolves to that dir (mirroring its step-2b
+ * rule that cleanup is driven off `entry.path`, so a same-named sibling's
+ * clone is never removed). Both sides are canonicalised so symlinked or
+ * differently-spelled forms of the same dir still match.
+ */
+export declare const cloneDirBelongsToEntry: (cloneDir: string, entryPath: string) => boolean;
+/**
+ * Versioned receipt for the analyzer process that produced an index.
+ *
+ * Paths identify the resolved runtime and invoked GitNexus entry artifact on
+ * this machine. The entry artifact is diagnostic (CLI and server-worker entry
+ * files differ); semantic freshness compares the runtime/build/dependency
+ * fields. SHA-256 digests make the receipt independently reproducible:
+ * `invokedArtifact.digest` covers the entry file, `build.digest` covers the
+ * complete source or distribution tree, and `dependencyRuntime.digest` covers
+ * the applicable lockfile, resolved runtime package metadata, and every
+ * content-addressed package payload (including JS/JSON/native/Wasm inputs)
+ * using the canonicalizations defined in `core/analyzer-identity.ts`.
+ */
+export interface AnalyzerRunnerIdentity {
+    schemaVersion: 4;
+    runtime: {
+        executablePath: string;
+        version: string;
+        platform: string;
+        architecture: string;
+        modulesAbi: string;
+        libc: string;
+    };
+    cliVersion: string;
+    invokedArtifact: {
+        path: string;
+        digest: string;
+    };
+    build: {
+        kind: 'source' | 'distribution';
+        rootPath: string;
+        canonicalization: 'gitnexus-analyzer-build-v2';
+        digest: string;
+    };
+    dependencyRuntime: {
+        manifestPath: string;
+        lockfilePath: string | null;
+        canonicalization: 'gitnexus-analyzer-dependency-runtime-v4';
+        packageCount: number;
+        artifactCount: number;
+        digest: string;
+    };
+}
 export interface RepoMeta {
     repoPath: string;
     lastCommit: string;
     indexedAt: string;
+    /**
+     * Analyzer/runtime receipt for the successful run represented by this
+     * metadata. Optional so indexes written by older GitNexus releases remain
+     * readable; a missing value means provenance is unknown, never that it
+     * matches the currently invoked analyzer.
+     */
+    runnerIdentity?: AnalyzerRunnerIdentity;
     /**
      * Canonical `origin` remote URL captured at index time. Used to
      * fingerprint the same logical repo across multiple on-disk clones
@@ -74,6 +137,33 @@ export interface RepoMeta {
         processes?: number;
         embeddings?: number;
     };
+    /**
+     * Capability stamps for what THIS analyze run actually produced (mirrors
+     * the meta literal in run-analyze.ts — typed here so the stamp site is
+     * compile-checked; tri-review 4669518496 P1/U3: `vectorSearch.status`
+     * must never claim 'vector-index' unless the run verified or recreated
+     * the HNSW index). Forensic today — no programmatic readers (`doctor`
+     * prints platform-derived capabilities, query routing never consults
+     * meta). The status unions mirror `CapabilityStatus` /
+     * `SemanticSearchMode` in core/platform/capabilities.ts; inlined to keep
+     * storage/ free of a core/ type dependency.
+     */
+    capabilities?: {
+        graph: {
+            provider: string;
+            status: 'available' | 'degraded' | 'unavailable';
+        };
+        fts: {
+            provider: string;
+            status: 'available' | 'degraded' | 'unavailable';
+        };
+        vectorSearch: {
+            provider: string;
+            status: 'vector-index' | 'exact-scan' | 'unavailable';
+            exactScanLimit: number;
+            reason?: string;
+        };
+    };
     /**
      * Bumped whenever incremental-indexing invariants change in an
      * incompatible way (delete-and-rewrite logic, subgraph extraction,
@@ -81,6 +171,12 @@ export interface RepoMeta {
      * full rebuild rather than risk an inconsistent incremental update.
      */
     schemaVersion?: number;
+    /**
+     * Exact versions of independently-gated analysis capabilities produced by
+     * the successful run. Unlike schemaVersion, these may apply only to repos
+     * containing relevant source files.
+     */
+    analysisFeatures?: Record<string, number>;
     /**
      * The resolved GITNEXUS_FTS_CJK_SEGMENTATION mode ('none' | 'bigram') the
      * existing index's content/description columns were last written under
@@ -98,6 +194,15 @@ export interface RepoMeta {
      * Map keys are repo-relative paths.
      */
     fileHashes?: Record<string, string>;
+    /**
+     * Whether the persisted Move facts are compiler-backed. Absent on legacy
+     * metadata and non-Move repositories.
+     */
+    moveIngestAvailable?: boolean;
+    /** Compiler identity that produced the persisted Move facts. */
+    moveCompilerIdentity?: MoveCompilerIdentity;
+    /** Managed release coordinates, kept separate from the binary fingerprint. */
+    moveFlowReleaseSelection?: MoveFlowReleaseSelection;
     /**
      * Crash-recovery dirty flag — a generic marker written to the metadata
      * file (gitnexus.json + its meta.json mirror) BEFORE any destructive DB
@@ -110,9 +215,53 @@ export interface RepoMeta {
     incrementalInProgress?: {
         /** When the run started (epoch ms). */
         startedAt: number;
+        /** Last dirty-flag refresh (epoch ms). */
+        updatedAt?: number;
         /** Number of files in the writable set, for diagnostic logs.
          *  `0` on the full-rebuild path (no incremental write set exists). */
         toWriteCount: number;
+        /** Last completed writeback phase before the process stopped. */
+        phase?: string;
+        /** Directly changed/added files before importer expansion. */
+        directWriteCount?: number;
+        /** Extra files pulled into the writable set by importer BFS. */
+        importerExpansion?: number;
+        /** Files in the effective write set after graph-boundary expansion. */
+        effectiveWriteCount?: number;
+        /** Files whose persisted rows were scheduled for deletion. */
+        deleteCount?: number;
+        /** Added-file shadow seeds included in importer BFS. */
+        shadowSeedCount?: number;
+        /** Importer-BFS chunks dropped by failed IMPORTS queries (#2410 +
+         *  tri-review 4669518496 P2-5). Stamped only when > 0: a dropped chunk
+         *  means the importer expansion silently shrank, so a crash's
+         *  diagnostics must show whether the write set was already
+         *  under-expanded when the run died. */
+        droppedImporterChunks?: number;
+    };
+    /**
+     * Durable embedding-resume marker. Before a bounded write window begins,
+     * `pendingNodeIds` records every node that could become partially persisted;
+     * after the LadybugDB checkpoint it is cleared while progress is retained.
+     * A matching runtime resumes from persisted hashes and regenerates pending
+     * nodes; a model or dimension mismatch fails before mutation.
+     */
+    embeddingCheckpoint?: {
+        at: string;
+        nodesProcessed: number;
+        totalNodes: number;
+        chunksProcessed: number;
+        model: string;
+        dimensions: number;
+        /** `local` or a secret-free SHA-256 fingerprint of the HTTP endpoint identity. */
+        provider: string;
+        /**
+         * Nodes in the current checkpoint window. Any of these may have only a
+         * subset of their chunks persisted after an abrupt process termination,
+         * so resume must delete and regenerate them even when a persisted row has
+         * the current content hash.
+         */
+        pendingNodeIds?: string[];
     };
     /**
      * Name of the git branch this index represents (#2106). Absent for the
@@ -242,8 +391,51 @@ export interface RepoMeta {
  * URL-only id). The incremental writeback preserves unchanged-file rows, so a
  * top-up against a pre-v5 index would strand old url-keyed Route nodes alongside
  * new composite-keyed ones — force a full re-analyze instead.
- */
-export declare const INCREMENTAL_SCHEMA_VERSION = 5;
+ * v6: line-number storage flipped to uniform 0-based for the last 1-based
+ * GraphNode emitters — COBOL/JCL/markdown/scope (#2377/#2379/#2380). Incremental
+ * writeback preserves unchanged-file rows, so a top-up against a pre-v6 index
+ * would MIX old 1-based rows with new 0-based ones — and the 1-based MCP display
+ * would render the stale rows one line too high — so force a full re-analyze.
+ * v7: callable-value-flow CALLS/USES edges added (#2437/#2522) — new edges can
+ * connect two files whose content did not change, but the incremental write set
+ * only covers changed files (`computeEffectiveWriteSet`), so a top-up against a
+ * pre-v7 index would silently omit the new edges for every unchanged file pair;
+ * force a full re-analyze instead (same contract as v2–v6).
+ * v8: Java anonymous class bodies became first-class Class nodes (#2550):
+ * `new Runnable() { run(){} }` now emits `Class:...:Worker$1` and its methods
+ * re-keyed from `Worker.run` to `Worker$1.run`. Node identities move on
+ * unchanged files — a top-up against a pre-v8 index would strand the old
+ * `Worker.run`-keyed Method nodes alongside the new ones (the v5 Route
+ * precedent); force a full re-analyze instead.
+ * v9: Java enum constant bodies joined the instance model and anonymous
+ * naming switched to JLS 13.1 immediately-enclosing-type chains (#2555): `enum E { A {
+ * hook(){} } }` now emits `Class:...:E$1` with methods re-keyed from
+ * `E.hook` to `E$1.hook`, and nested-host anonymous names re-key
+ * (`EnumWrap$1` → `EnumWrap$Mode$1`). Same contract as v8: identities move
+ * on unchanged files; force a full re-analyze.
+ * v10: Java `record_declaration` now emits a first-class `Record` graph node
+ * (#2564): a record's container node was previously never created (JAVA_QUERIES
+ * had no capture for it), so its methods existed as ownerless Method nodes
+ * with no `HAS_METHOD` edge. The incremental write set only covers changed
+ * files — a top-up against a pre-v10 index would keep silently omitting the
+ * `Record` node and its `HAS_METHOD` edges for every unchanged record file
+ * (same v7 contract: new nodes/edges the incremental path would otherwise
+ * never backfill); force a full re-analyze instead.
+ * v11: Rust abstract trait methods (`fn foo(&self) -> T;`, no body) now get a
+ * scope + declaration capture (#2604): RUST_SCOPE_QUERY had no
+ * `function_signature_item` pattern, so a `&dyn Trait` receiver could never
+ * dispatch a CALLS edge to the trait's own method. Same v7/v10 contract: the
+ * incremental write set only covers changed files, so a top-up against a
+ * pre-v11 index would keep silently missing these CALLS edges for every
+ * unchanged Rust trait file; force a full re-analyze instead.
+ * v12: main-aptos merge. The Move lineage's v9 — `attributesJson` column added
+ * to the Move node tables (Function, Struct, Enum, EnumVariant, Module) with
+ * full attribute payloads — is re-numbered past main's v9–v11: a persisted
+ * stamp of 9 is ambiguous between the two lineages, and a pre-merge Move
+ * index also predates main's v9–v11 rebuild reasons. Any pre-v12 stamp fails
+ * the strict-equality reuse gate; force a full re-analyze (same contract as v3).
+ */
+export declare const INCREMENTAL_SCHEMA_VERSION = 12;
 export interface IndexedRepo {
     repoPath: string;
     storagePath: string;

package/dist/storage/repo-manager.js

@@ -71,6 +71,18 @@ export const canonicalizePath = (p) => {
  * lookups/dedup/finalize checks all share so they answer identically.
  */
 export const registryPathEquals = (a, b) => process.platform === 'win32' ? a.toLowerCase() === b.toLowerCase() : a === b;
+/**
+ * Does the clone dir derived from an entry's *name* actually belong to that
+ * entry? Registry names are not unique across storage locations: a cloned
+ * repo under `~/.gitnexus/repos/<name>` and a local repo registered under the
+ * same name share a `getCloneDir(entry.name)` result. The server's delete
+ * handler must therefore never remove the clone dir based on the name alone —
+ * only when the entry's own `path` resolves to that dir (mirroring its step-2b
+ * rule that cleanup is driven off `entry.path`, so a same-named sibling's
+ * clone is never removed). Both sides are canonicalised so symlinked or
+ * differently-spelled forms of the same dir still match.
+ */
+export const cloneDirBelongsToEntry = (cloneDir, entryPath) => registryPathEquals(canonicalizePath(cloneDir), canonicalizePath(entryPath));
 /**
  * Bumped whenever incremental-indexing invariants change incompatibly.
  * v2: `BasicBlock.callees` column added (statement-precise inter-procedural
@@ -90,8 +102,51 @@ export const registryPathEquals = (a, b) => process.platform === 'win32' ? a.toL
  * URL-only id). The incremental writeback preserves unchanged-file rows, so a
  * top-up against a pre-v5 index would strand old url-keyed Route nodes alongside
  * new composite-keyed ones — force a full re-analyze instead.
+ * v6: line-number storage flipped to uniform 0-based for the last 1-based
+ * GraphNode emitters — COBOL/JCL/markdown/scope (#2377/#2379/#2380). Incremental
+ * writeback preserves unchanged-file rows, so a top-up against a pre-v6 index
+ * would MIX old 1-based rows with new 0-based ones — and the 1-based MCP display
+ * would render the stale rows one line too high — so force a full re-analyze.
+ * v7: callable-value-flow CALLS/USES edges added (#2437/#2522) — new edges can
+ * connect two files whose content did not change, but the incremental write set
+ * only covers changed files (`computeEffectiveWriteSet`), so a top-up against a
+ * pre-v7 index would silently omit the new edges for every unchanged file pair;
+ * force a full re-analyze instead (same contract as v2–v6).
+ * v8: Java anonymous class bodies became first-class Class nodes (#2550):
+ * `new Runnable() { run(){} }` now emits `Class:...:Worker$1` and its methods
+ * re-keyed from `Worker.run` to `Worker$1.run`. Node identities move on
+ * unchanged files — a top-up against a pre-v8 index would strand the old
+ * `Worker.run`-keyed Method nodes alongside the new ones (the v5 Route
+ * precedent); force a full re-analyze instead.
+ * v9: Java enum constant bodies joined the instance model and anonymous
+ * naming switched to JLS 13.1 immediately-enclosing-type chains (#2555): `enum E { A {
+ * hook(){} } }` now emits `Class:...:E$1` with methods re-keyed from
+ * `E.hook` to `E$1.hook`, and nested-host anonymous names re-key
+ * (`EnumWrap$1` → `EnumWrap$Mode$1`). Same contract as v8: identities move
+ * on unchanged files; force a full re-analyze.
+ * v10: Java `record_declaration` now emits a first-class `Record` graph node
+ * (#2564): a record's container node was previously never created (JAVA_QUERIES
+ * had no capture for it), so its methods existed as ownerless Method nodes
+ * with no `HAS_METHOD` edge. The incremental write set only covers changed
+ * files — a top-up against a pre-v10 index would keep silently omitting the
+ * `Record` node and its `HAS_METHOD` edges for every unchanged record file
+ * (same v7 contract: new nodes/edges the incremental path would otherwise
+ * never backfill); force a full re-analyze instead.
+ * v11: Rust abstract trait methods (`fn foo(&self) -> T;`, no body) now get a
+ * scope + declaration capture (#2604): RUST_SCOPE_QUERY had no
+ * `function_signature_item` pattern, so a `&dyn Trait` receiver could never
+ * dispatch a CALLS edge to the trait's own method. Same v7/v10 contract: the
+ * incremental write set only covers changed files, so a top-up against a
+ * pre-v11 index would keep silently missing these CALLS edges for every
+ * unchanged Rust trait file; force a full re-analyze instead.
+ * v12: main-aptos merge. The Move lineage's v9 — `attributesJson` column added
+ * to the Move node tables (Function, Struct, Enum, EnumVariant, Module) with
+ * full attribute payloads — is re-numbered past main's v9–v11: a persisted
+ * stamp of 9 is ambiguous between the two lineages, and a pre-merge Move
+ * index also predates main's v9–v11 rebuild reasons. Any pre-v12 stamp fails
+ * the strict-equality reuse gate; force a full re-analyze (same contract as v3).
  */
-export const INCREMENTAL_SCHEMA_VERSION = 5;
+export const INCREMENTAL_SCHEMA_VERSION = 12;
 const GITNEXUS_DIR = '.gitnexus';
 const GITNEXUS_EXCLUDE_ENTRY = `${GITNEXUS_DIR}/`;
 export const INDEX_METADATA_FILE = 'gitnexus.json';

package/hooks/antigravity/gitnexus-antigravity-hook.cjs

@@ -391,6 +391,49 @@ function buildAfterToolContext(input) {
   return parts.length > 0 ? parts.join('\n\n') : null;
 }
 
+/**
+ * Fallback augmentation for the #2396 path: when a GitNexus process holds the
+ * lbug DB write lock the CLI `augment` can't run, so point the agent at the MCP
+ * `query` tool instead. Phrased conditionally ("if the MCP tools are live") so it
+ * stays truthful on every owner path — a confirmed MCP owner, a `serve` owner, or
+ * a fail-closed probe where no server is actually confirmed. `pattern` is embedded
+ * verbatim; the caller (writeAdditionalContext) JSON-escapes it structurally.
+ */
+function buildMcpQueryHint(pattern) {
+  return (
+    `[GitNexus] Local augment is unavailable (the graph DB is held by another ` +
+    `GitNexus process). If the GitNexus MCP tools are live in this session, call ` +
+    `the GitNexus \`query\` MCP tool (e.g. mcp__gitnexus__query) with ` +
+    `search_query "${pattern}".`
+  );
+}
+
+/**
+ * #2396 throttle: emit the MCP-query hint at most once per repo per window, so an
+ * owner-locked session isn't nudged on every search. Window (ms) via
+ * GITNEXUS_MCP_HINT_THROTTLE_MS (default 10min; 0/invalid disables). Best-effort —
+ * any fs error falls back to emitting.
+ * ponytail: per-repo mtime marker, shared across concurrent sessions on the same
+ * repo; add per-session dedup only if that sharing becomes a problem.
+ */
+function shouldEmitMcpHint(gitNexusDir) {
+  const raw = process.env.GITNEXUS_MCP_HINT_THROTTLE_MS;
+  const windowMs = raw === undefined || raw === '' ? 600000 : Number(raw);
+  if (!Number.isFinite(windowMs) || windowMs <= 0) return true;
+  const marker = path.join(gitNexusDir, '.mcp-hint-shown');
+  try {
+    if (Date.now() - fs.statSync(marker).mtimeMs < windowMs) return false;
+  } catch {
+    /* marker missing/unreadable → emit */
+  }
+  try {
+    fs.writeFileSync(marker, '');
+  } catch {
+    /* best-effort; still emit */
+  }
+  return true;
+}
+
 function runAugment(gitNexusDir, cwd, pattern) {
   // Acquire the per-repo slot BEFORE the DB-owner probe (#2163): the probe
   // itself spawns lsof/ps, so it must be bounded by the same ≤3-per-repo cap
@@ -410,12 +453,16 @@ function runAugment(gitNexusDir, cwd, pattern) {
   }
   try {
     if (hasGitNexusServerOwner(gitNexusDir)) {
-      // Normal skip path: the MCP server owns the DB. Stay silent for strict
-      // hook runners (issue #1913); surface the reason only under GITNEXUS_DEBUG.
+      // #2396: the MCP server holds the DB write lock, so a competing CLI
+      // `augment` would only contend on it (LadybugDB is single-writer). The
+      // session has the GitNexus MCP tools live — route the augmentation to the
+      // agent via additionalContext instead of dropping it. Mirror the skip
+      // reason to stderr only under GITNEXUS_DEBUG (strict-runner contract,
+      // #1913); the hint itself rides the sanctioned additionalContext channel.
       if (isDebugEnabled()) {
         process.stderr.write('[GitNexus] augment skipped: MCP server owns DB\n');
       }
-      return '';
+      return shouldEmitMcpHint(gitNexusDir) ? buildMcpQueryHint(pattern) : '';
     }
     const cliPath = resolveCliPath();
     const child = runGitNexusCli(cliPath, ['augment', '--', pattern], cwd, 7000);