gitnexus 1.6.6-rc.41 → 1.6.6-rc.43

package/README.md

@@ -158,6 +158,7 @@ gitnexus analyze --skip-agents-md  # Preserve custom AGENTS.md/CLAUDE.md gitnexu
 gitnexus analyze --verbose       # Log skipped files when parsers are unavailable
 gitnexus analyze --max-file-size 1024  # Skip files larger than N KB (default: 512, cap: 32768)
 gitnexus analyze --worker-timeout 60  # Increase worker idle timeout for slow parses
+gitnexus analyze --wal-checkpoint-threshold 67108864  # 64 MiB. Control LadybugDB WAL auto-checkpoint threshold (default: 67108864 = 64 MiB; -1 keeps Ladybug stock ~16 MiB)
 gitnexus mcp                     # Start MCP server (stdio) — serves all indexed repos
 gitnexus serve                   # Start local HTTP server (multi-repo) for web UI
 gitnexus index                   # Register an existing .gitnexus/ folder into the global registry
@@ -307,6 +308,7 @@ Configure the behavior with two environment variables:
 |----------|--------|---------|--------|
 | `GITNEXUS_LBUG_EXTENSION_INSTALL` | `auto`, `load-only`, `never` | `auto` | `auto` runs one bounded INSTALL if LOAD fails. `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 `INSTALL` child before it is killed. |
+| `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. |
 
 ```bash
 # Offline/airgapped: never reach the network for extensions

package/dist/cli/analyze.d.ts

@@ -69,6 +69,8 @@ export interface AnalyzeOptions {
     maxFileSize?: string;
     /** Override worker sub-batch idle timeout in seconds. */
     workerTimeout?: string;
+    /** Control LadybugDB WAL auto-checkpoint threshold during analyze. */
+    walCheckpointThreshold?: string;
     /** Parse worker pool size; 0 disables workers (sequential fallback). */
     workers?: string;
     embeddingThreads?: string;

package/dist/cli/analyze.js

@@ -12,7 +12,7 @@ import { spawn } from 'child_process';
 import v8 from 'v8';
 import cliProgress from 'cli-progress';
 import { closeLbug } from '../core/lbug/lbug-adapter.js';
-import { isWalCorruptionError, WAL_RECOVERY_SUGGESTION } from '../core/lbug/lbug-config.js';
+import { isLbugCheckpointIoError, isWalCorruptionError, parseWalCheckpointThreshold, WAL_RECOVERY_SUGGESTION, } from '../core/lbug/lbug-config.js';
 import { getStoragePaths, getGlobalRegistryPath, RegistryNameCollisionError, AnalysisNotFinalizedError, assertAnalysisFinalized, } from '../storage/repo-manager.js';
 import { getGitRoot, hasGitDir } from '../storage/git.js';
 import { runFullAnalysis } from '../core/run-analyze.js';
@@ -322,6 +322,14 @@ const forceHeapOOMForTestIfEnabled = () => {
     for (;;)
         chunks.push('x'.repeat(1024 * 1024));
 };
+// 64 MiB keeps auto-checkpoint enabled but triggers less frequently than
+// Ladybug's stock ~16 MiB threshold, reducing rename/remove churn on large
+// runs. Also matches the GitNexus default in `lbug-config.ts`.
+//
+// IMPORTANT: keep README examples (`README.md`, `gitnexus/README.md`) and
+// the `DEFAULT_WAL_CHECKPOINT_THRESHOLD` constant in
+// `gitnexus/src/core/lbug/lbug-config.ts` in sync with this value.
+const RECOMMENDED_WAL_CHECKPOINT_THRESHOLD = 64 * 1024 * 1024;
 /** Re-exec the process with a 16GB heap and larger stack if we're currently below that. */
 async function ensureHeap() {
     const nodeOpts = process.env.NODE_OPTIONS || '';
@@ -378,6 +386,8 @@ const ANALYZE_CLI_ENV_KEYS = [
     'GITNEXUS_PROFILE_DEFERRED_SLOW_MS',
     'GITNEXUS_MAX_FILE_SIZE',
     'GITNEXUS_WORKER_SUB_BATCH_TIMEOUT_MS',
+    'GITNEXUS_WAL_CHECKPOINT_THRESHOLD',
+    'GITNEXUS_WAL_MANUAL_CHECKPOINT',
     'GITNEXUS_EMBEDDING_THREADS',
     'GITNEXUS_EMBEDDING_BATCH_SIZE',
     'GITNEXUS_EMBEDDING_SUB_BATCH_SIZE',
@@ -452,6 +462,15 @@ const analyzeCommandImpl = async (inputPath, options) => {
         }
         process.env.GITNEXUS_WORKER_SUB_BATCH_TIMEOUT_MS = String(Math.round(workerTimeoutSeconds * 1000));
     }
+    if (options?.walCheckpointThreshold !== undefined) {
+        const parsed = parseWalCheckpointThreshold(options.walCheckpointThreshold);
+        if (parsed === undefined) {
+            cliError('  --wal-checkpoint-threshold must be an integer >= -1.\n');
+            process.exitCode = 1;
+            return;
+        }
+        process.env.GITNEXUS_WAL_CHECKPOINT_THRESHOLD = String(parsed);
+    }
     // `--workers` is threaded through `runFullAnalysis` options → PipelineOptions
     // → createWorkerPool, intentionally bypassing the GITNEXUS_WORKER_POOL_SIZE
     // env channel so this CLI surface never mutates `process.env` for pool size.
@@ -859,6 +878,16 @@ const analyzeCommandImpl = async (inputPath, options) => {
             process.exitCode = 1;
             return;
         }
+        if (isLbugCheckpointIoError(err)) {
+            cliError(`  LadybugDB failed while rotating/removing WAL checkpoint files.\n` +
+                `  This can happen when auto-checkpoint runs at the default threshold (~16MB).\n` +
+                `  Retry with a larger checkpoint threshold to reduce checkpoint frequency:\n` +
+                `    gitnexus analyze --wal-checkpoint-threshold ${RECOMMENDED_WAL_CHECKPOINT_THRESHOLD}\n` +
+                `    (or set GITNEXUS_WAL_CHECKPOINT_THRESHOLD=${RECOMMENDED_WAL_CHECKPOINT_THRESHOLD})\n` +
+                `    (Try 33554432 = 32 MiB on small-disk / CI runners.)\n`, { recoveryHint: 'wal-checkpoint-threshold' });
+            process.exitCode = 1;
+            return;
+        }
         // HF download failure — show clean guidance without the raw stack trace.
         // Checked before writeFatalToStderr so the user sees one focused message
         // rather than a stack-trace dump followed by a second remediation block.

package/dist/cli/cli-message.d.ts

@@ -1,15 +1,37 @@
+/**
+ * String-literal union of all `recoveryHint` tags emitted by the CLI.
+ *
+ * Centralized so a new recovery branch added in `analyze.ts` cannot land
+ * without updating this union — TypeScript will reject the unknown literal
+ * passed via `cliError({ recoveryHint: '...' })`. To add a new hint:
+ *   1. Add the tag string to this union.
+ *   2. Pass it as the `recoveryHint` field at the relevant `cliError`
+ *      call site.
+ *
+ * Consumers can import this type to narrow log-record `recoveryHint`
+ * fields without restating the literal list.
+ */
+export type RecoveryHint = 'wal-corruption' | 'wal-checkpoint-threshold' | 'heap-oom-respawn' | 'native-worker-abort' | 'hf-endpoint-unreachable' | 'large-repo' | 'npm-resolution' | 'module-not-found';
+/**
+ * Common shape for the optional structured-field bag passed to
+ * `cliError`/`cliWarn`/`cliInfo`. Typed so the `recoveryHint` slot is
+ * checked against the {@link RecoveryHint} union.
+ */
+export interface CliMessageFields extends Record<string, unknown> {
+    recoveryHint?: RecoveryHint;
+}
 /**
  * User-facing informational message. Use for banners, listening URLs,
  * and any message the user expects to read in plain text.
  */
-export declare function cliInfo(msg: string, fields?: Record<string, unknown>): void;
+export declare function cliInfo(msg: string, fields?: CliMessageFields): void;
 /**
  * User-facing warning. Operator-actionable but non-fatal — `cliWarn`
  * indicates the command can still proceed in some form.
  */
-export declare function cliWarn(msg: string, fields?: Record<string, unknown>): void;
+export declare function cliWarn(msg: string, fields?: CliMessageFields): void;
 /**
  * User-facing error. Indicates the command cannot proceed; usually
  * paired with a non-zero exit code at the call site.
  */
-export declare function cliError(msg: string, fields?: Record<string, unknown>): void;
+export declare function cliError(msg: string, fields?: CliMessageFields): void;

package/dist/cli/index.js

@@ -38,6 +38,8 @@ program
     .option('-v, --verbose', 'Enable verbose ingestion warnings (default: false)')
     .option('--max-file-size <kb>', 'Skip files larger than this (KB). Default: 512. Hard cap: 32768 (tree-sitter limit).')
     .option('--worker-timeout <seconds>', 'Worker sub-batch idle timeout before retry/fallback. Default: 30.')
+    .option('--wal-checkpoint-threshold <bytes>', 'LadybugDB WAL auto-checkpoint threshold in bytes during analyze ' +
+    '(integer >= -1; default: 67108864 = 64 MiB; -1 keeps Ladybug stock ~16 MiB).')
     .option('--workers <n>', 'Parse worker pool size. Default: cores-1 capped at 16. Pass 0 to disable workers (sequential).')
     .option('--embedding-threads <n>', 'Limit local ONNX embedding CPU threads')
     .option('--embedding-batch-size <n>', 'Number of nodes per embedding batch')
@@ -47,6 +49,7 @@ program
     '  GITNEXUS_NO_GITIGNORE=1   Skip .gitignore parsing (still reads .gitnexusignore)\n' +
     '  GITNEXUS_MAX_FILE_SIZE=N  Override large-file skip threshold (KB). Default 512, max 32768.\n' +
     '  GITNEXUS_WORKER_SUB_BATCH_TIMEOUT_MS=N  Worker idle timeout in milliseconds. Default 30000.\n' +
+    '  GITNEXUS_WAL_CHECKPOINT_THRESHOLD=N  LadybugDB WAL auto-checkpoint threshold in bytes (default 67108864 = 64 MiB; -1 keeps Ladybug stock ~16 MiB).\n' +
     '  GITNEXUS_WORKER_SUB_BATCH_MAX_BYTES=N  Worker job byte budget. Default 8388608.\n' +
     '  GITNEXUS_WORKER_POOL_SIZE=N  Parse worker count override. Default cores-1 capped at 16.\n' +
     '  GITNEXUS_PARSE_CHUNK_CONCURRENCY=N  Concurrent in-flight parse chunks. Default 2.\n' +
@@ -55,6 +58,7 @@ program
     '  GITNEXUS_WORKER_CONSECUTIVE_FAILURE_THRESHOLD=N  Per-slot deaths to trip circuit breaker. Default max(3, poolSize).\n' +
     '  GITNEXUS_EMBEDDING_THREADS=N  Limit local ONNX CPU threads for --embeddings.\n' +
     '  GITNEXUS_SEMANTIC_EXACT_SCAN_LIMIT=N  Max embedding chunks for exact-scan fallback. Default 10000.\n' +
+    '\nFlags override the corresponding env vars when both are provided.\n' +
     '\nTip: `.gitnexusignore` supports `.gitignore`-style negation. Add e.g.\n' +
     '     `!__tests__/` to index a directory that is auto-filtered by default (#771).')
     .action(createLazyAction(() => import('./analyze.js'), 'analyzeCommand'));

package/dist/core/ingestion/call-extractors/configs/c-cpp.js

@@ -5,4 +5,161 @@ export const cCallConfig = {
 };
 export const cppCallConfig = {
     language: SupportedLanguages.CPlusPlus,
+    extractLanguageCallSite(callNode) {
+        return extractCppOperatorCallSite(callNode);
+    },
 };
+function extractCppOperatorCallSite(callNode) {
+    if (callNode.type !== 'binary_expression')
+        return null;
+    if (isPrimitiveOnlyBinaryOperatorCall(callNode))
+        return null;
+    const operator = callNode.childForFieldName('operator')?.text.trim();
+    // Keep the legacy DAG conservative: only simple identifier operands are
+    // modeled here. Complex expressions stay unresolved instead of guessed.
+    if (operator === '+') {
+        const left = callNode.childForFieldName('left');
+        const right = callNode.childForFieldName('right');
+        if (left?.type !== 'identifier' || right?.type !== 'identifier')
+            return null;
+        return {
+            calledName: 'operator+',
+            callForm: 'member',
+            receiverName: left.text,
+            argCount: 1,
+        };
+    }
+    if (operator === '<<') {
+        const right = callNode.childForFieldName('right');
+        if (right?.type !== 'identifier')
+            return null;
+        return {
+            calledName: 'operator<<',
+            callForm: 'free',
+            argCount: 2,
+        };
+    }
+    return null;
+}
+function isPrimitiveOnlyBinaryOperatorCall(callNode) {
+    const left = callNode.childForFieldName('left');
+    const right = callNode.childForFieldName('right');
+    if (left === null || right === null)
+        return false;
+    return isBuiltinOperatorOperand(left) && isBuiltinOperatorOperand(right);
+}
+function isBuiltinOperatorOperand(node) {
+    return isBuiltinOperatorType(inferCppOperatorOperandType(node));
+}
+function inferCppOperatorOperandType(node) {
+    const literalType = inferCppLiteralType(node);
+    if (literalType !== '')
+        return literalType;
+    if (node.type === 'identifier')
+        return lookupCppIdentifierType(node);
+    return '';
+}
+function inferCppLiteralType(node) {
+    if (node.type === 'number_literal')
+        return node.text.includes('.') ? 'double' : 'int';
+    if (node.type === 'char_literal')
+        return 'char';
+    if (node.type === 'true' || node.type === 'false')
+        return 'bool';
+    return '';
+}
+function lookupCppIdentifierType(identNode) {
+    const varName = identNode.text;
+    let scope = identNode.parent;
+    while (scope !== null &&
+        scope.type !== 'compound_statement' &&
+        scope.type !== 'translation_unit') {
+        scope = scope.parent;
+    }
+    if (scope === null)
+        return '';
+    const parameterType = lookupCppFunctionParameterType(scope, varName);
+    if (parameterType !== '')
+        return parameterType;
+    for (let i = 0; i < scope.childCount; i++) {
+        const stmt = scope.child(i);
+        if (stmt === null || stmt.type !== 'declaration')
+            continue;
+        const typeNode = stmt.childForFieldName('type');
+        const declarator = stmt.childForFieldName('declarator');
+        if (typeNode === null || declarator === null)
+            continue;
+        if (extractDeclaratorLeafName(declarator) === varName)
+            return normalizeCppTypeText(typeNode.text);
+    }
+    return '';
+}
+function lookupCppFunctionParameterType(scope, varName) {
+    let node = scope.parent;
+    while (node !== null) {
+        if (node.type === 'function_definition' || node.type === 'function_declarator') {
+            const fnDecl = node.type === 'function_declarator'
+                ? node
+                : findFirstDescendantOfType(node, 'function_declarator');
+            const params = fnDecl?.childForFieldName('parameters') ?? null;
+            if (params === null)
+                return '';
+            for (let i = 0; i < params.namedChildCount; i++) {
+                const param = params.namedChild(i);
+                if (param === null || param.type !== 'parameter_declaration')
+                    continue;
+                const declarator = param.childForFieldName('declarator');
+                const typeNode = param.childForFieldName('type');
+                if (declarator !== null &&
+                    typeNode !== null &&
+                    extractDeclaratorLeafName(declarator) === varName) {
+                    return normalizeCppTypeText(typeNode.text);
+                }
+            }
+            return '';
+        }
+        node = node.parent;
+    }
+    return '';
+}
+function findFirstDescendantOfType(node, type) {
+    if (node.type === type)
+        return node;
+    for (let i = 0; i < node.namedChildCount; i++) {
+        const found = findFirstDescendantOfType(node.namedChild(i), type);
+        if (found !== null)
+            return found;
+    }
+    return null;
+}
+function extractDeclaratorLeafName(node) {
+    if (node.type === 'identifier' ||
+        node.type === 'field_identifier' ||
+        node.type === 'operator_name') {
+        return node.text;
+    }
+    const named = node.namedChildren;
+    for (let i = named.length - 1; i >= 0; i--) {
+        const name = extractDeclaratorLeafName(named[i]);
+        if (name !== '')
+            return name;
+    }
+    return '';
+}
+function normalizeCppTypeText(text) {
+    return text
+        .replace(/\b(const|volatile|static|extern|register|mutable|inline|constexpr)\b/g, ' ')
+        .replace(/\s+/g, ' ')
+        .trim();
+}
+function isBuiltinOperatorType(type) {
+    return (type === 'bool' ||
+        type === 'char' ||
+        type === 'double' ||
+        type === 'float' ||
+        type === 'int' ||
+        type === 'long' ||
+        type === 'short' ||
+        type === 'signed' ||
+        type === 'unsigned');
+}

package/dist/core/ingestion/languages/c-cpp.js

@@ -194,6 +194,7 @@ const cCppExtractFunctionName = (node) => {
                 if (c?.type === 'qualified_identifier' ||
                     c?.type === 'identifier' ||
                     c?.type === 'field_identifier' ||
+                    c?.type === 'operator_name' ||
                     c?.type === 'parenthesized_declarator') {
                     innerDeclarator = c;
                     break;
@@ -205,7 +206,7 @@ const cCppExtractFunctionName = (node) => {
             if (!nameNode) {
                 for (let i = 0; i < innerDeclarator.childCount; i++) {
                     const c = innerDeclarator.child(i);
-                    if (c?.type === 'identifier') {
+                    if (c?.type === 'identifier' || c?.type === 'operator_name') {
                         nameNode = c;
                         break;
                     }
@@ -217,7 +218,8 @@ const cCppExtractFunctionName = (node) => {
             }
         }
         else if (innerDeclarator?.type === 'identifier' ||
-            innerDeclarator?.type === 'field_identifier') {
+            innerDeclarator?.type === 'field_identifier' ||
+            innerDeclarator?.type === 'operator_name') {
             // field_identifier is used for method names inside C++ class bodies
             funcName = innerDeclarator.text;
             if (innerDeclarator.type === 'field_identifier')
@@ -237,7 +239,7 @@ const cCppExtractFunctionName = (node) => {
                 if (!nameNode) {
                     for (let i = 0; i < nestedId.childCount; i++) {
                         const c = nestedId.child(i);
-                        if (c?.type === 'identifier') {
+                        if (c?.type === 'identifier' || c?.type === 'operator_name') {
                             nameNode = c;
                             break;
                         }

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

@@ -135,11 +135,26 @@ export function emitCppScopeCaptures(sourceText, filePath, cachedTree) {
         const callAnchor = grouped['@reference.call.free'] ??
             grouped['@reference.call.member'] ??
             grouped['@reference.call.qualified'];
+        const operatorAnchor = grouped['@reference.operator'];
+        if (operatorAnchor !== undefined) {
+            const operatorNode = callAnchor !== undefined
+                ? findNodeAtRange(tree.rootNode, callAnchor.range, 'binary_expression')
+                : null;
+            if (operatorNode !== null && isPrimitiveOnlyBinaryOperator(operatorNode))
+                continue;
+        }
         if (callAnchor !== undefined && grouped['@reference.arity'] === undefined) {
-            const callNode = findNodeAtRange(tree.rootNode, callAnchor.range, 'call_expression');
-            if (callNode !== null) {
+            const callNode = findNodeAtRange(tree.rootNode, callAnchor.range, 'call_expression') ??
+                findNodeAtRange(tree.rootNode, callAnchor.range, 'binary_expression');
+            if (callNode?.type === 'call_expression') {
                 grouped['@reference.arity'] = syntheticCapture('@reference.arity', callNode, String(computeCppCallArity(callNode)));
             }
+            else if (callNode?.type === 'binary_expression') {
+                grouped['@reference.arity'] = syntheticCapture('@reference.arity', callNode, grouped['@reference.call.member'] !== undefined ? '1' : '2');
+            }
+        }
+        if (operatorAnchor !== undefined && grouped['@reference.name'] === undefined) {
+            grouped['@reference.name'] = syntheticCapture('@reference.name', findNodeAtRange(tree.rootNode, operatorAnchor.range, operatorAnchor.text) ?? tree.rootNode, `operator${operatorAnchor.text}`);
         }
         // ── Enrich constructor calls (new Foo()) with arity ─────────────
         const ctorCallAnchor = grouped['@reference.call.constructor'];
@@ -153,13 +168,18 @@ export function emitCppScopeCaptures(sourceText, filePath, cachedTree) {
         const anyCallAnchor = callAnchor ?? ctorCallAnchor;
         if (anyCallAnchor !== undefined && grouped['@reference.parameter-types'] === undefined) {
             const cNode = findNodeAtRange(tree.rootNode, anyCallAnchor.range, 'call_expression') ??
-                findNodeAtRange(tree.rootNode, anyCallAnchor.range, 'new_expression');
+                findNodeAtRange(tree.rootNode, anyCallAnchor.range, 'new_expression') ??
+                findNodeAtRange(tree.rootNode, anyCallAnchor.range, 'binary_expression');
             if (cNode !== null) {
-                const argTypes = inferCppCallArgTypes(cNode);
+                const argTypes = cNode.type === 'binary_expression'
+                    ? inferCppBinaryOperatorArgTypes(cNode, grouped['@reference.call.free'] !== undefined)
+                    : inferCppCallArgTypes(cNode);
                 if (argTypes !== undefined && argTypes.length > 0) {
                     grouped['@reference.parameter-types'] = syntheticCapture('@reference.parameter-types', cNode, JSON.stringify(argTypes));
                 }
-                const argTypeClasses = inferCppCallArgTypeClasses(cNode);
+                const argTypeClasses = cNode.type === 'binary_expression'
+                    ? inferCppBinaryOperatorArgTypeClasses(cNode, grouped['@reference.call.free'] !== undefined)
+                    : inferCppCallArgTypeClasses(cNode);
                 if (argTypeClasses !== undefined && argTypeClasses.length > 0) {
                     grouped['@reference.parameter-type-classes'] = syntheticCapture('@reference.parameter-type-classes', cNode, JSON.stringify(argTypeClasses));
                 }
@@ -640,6 +660,62 @@ function inferCppCallArgTypeClasses(node) {
     }
     return classes.length > 0 ? classes : undefined;
 }
+function inferCppBinaryOperatorArgTypes(node, includeLeftOperand) {
+    const operands = binaryOperatorOperands(node, includeLeftOperand);
+    if (operands.length === 0)
+        return undefined;
+    const types = operands.map(inferCppExpressionType);
+    return types.length > 0 ? types : undefined;
+}
+function inferCppBinaryOperatorArgTypeClasses(node, includeLeftOperand) {
+    const operands = binaryOperatorOperands(node, includeLeftOperand);
+    if (operands.length === 0)
+        return undefined;
+    const classes = operands.map(inferCppExpressionTypeClass);
+    return classes.length > 0 ? classes : undefined;
+}
+function binaryOperatorOperands(node, includeLeftOperand) {
+    const operands = [];
+    const left = node.childForFieldName('left');
+    const right = node.childForFieldName('right');
+    if (includeLeftOperand && left !== null)
+        operands.push(left);
+    if (right !== null)
+        operands.push(right);
+    return operands;
+}
+function isPrimitiveOnlyBinaryOperator(node) {
+    const operands = binaryOperatorOperands(node, true);
+    return operands.length > 0 && operands.every((operand) => isBuiltinOperatorType(operand));
+}
+function isBuiltinOperatorType(node) {
+    const type = inferCppExpressionType(node);
+    return (type === 'bool' ||
+        type === 'char' ||
+        type === 'double' ||
+        type === 'float' ||
+        type === 'int' ||
+        type === 'long' ||
+        type === 'short' ||
+        type === 'signed' ||
+        type === 'unsigned');
+}
+function inferCppExpressionType(node) {
+    const litType = inferCppLiteralType(node);
+    if (litType !== '')
+        return litType;
+    if (node.type === 'identifier')
+        return lookupDeclaredTypeForIdentifier(node);
+    return '';
+}
+function inferCppExpressionTypeClass(node) {
+    const litType = inferCppLiteralType(node);
+    if (litType !== '')
+        return valueTypeClass(litType);
+    if (node.type === 'identifier')
+        return lookupDeclaredTypeClassForIdentifier(node);
+    return unknownTypeClass('unknown');
+}
 function valueTypeClass(base) {
     return { base, cv: 'none', indirection: 'value', pointerDepth: 0 };
 }

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

@@ -97,6 +97,12 @@ const CPP_SCOPE_QUERY = `
     declarator: (qualified_identifier
       name: (identifier) @declaration.name))) @declaration.method
 
+;; Out-of-class operator method: Point::operator+(...)
+(function_definition
+  declarator: (function_declarator
+    declarator: (qualified_identifier
+      name: (operator_name) @declaration.name))) @declaration.method
+
 ;; ─── Declarations — out-of-class method with pointer return ─────────
 (function_definition
   declarator: (pointer_declarator
@@ -129,6 +135,11 @@ const CPP_SCOPE_QUERY = `
   declarator: (function_declarator
     declarator: (field_identifier) @declaration.name)) @declaration.method
 
+;; Inline operator method in class body: Point operator+(Point) const { ... }
+(function_definition
+  declarator: (function_declarator
+    declarator: (operator_name) @declaration.name)) @declaration.method
+
 ;; ─── Declarations — inline method with pointer return (field_identifier) ──
 ;; Covers: User* lookup(int id) { ... } inside a class body
 ;; AST: function_definition > pointer_declarator > function_declarator > field_identifier
@@ -144,17 +155,49 @@ const CPP_SCOPE_QUERY = `
     (function_declarator
       declarator: (field_identifier) @declaration.name))) @declaration.method
 
+;; Inline operator method with reference return: Point& operator+=(Point) { ... }
+(field_declaration_list
+  (function_definition
+    declarator: (reference_declarator
+      (function_declarator
+        declarator: (operator_name) @declaration.name))) @declaration.method)
+
+;; Free operator definition with reference return: std::ostream& operator<<(...) { ... }
+(translation_unit
+  (function_definition
+    declarator: (reference_declarator
+      (function_declarator
+        declarator: (operator_name) @declaration.name))) @declaration.function)
+
+(namespace_definition
+  body: (declaration_list
+    (function_definition
+      declarator: (reference_declarator
+        (function_declarator
+          declarator: (operator_name) @declaration.name))) @declaration.function))
+
 ;; ─── Declarations — function prototype (forward declaration) ────────
 (declaration
   declarator: (function_declarator
     declarator: (identifier) @declaration.name)) @declaration.function
 
+;; Free operator prototype: std::ostream& operator<<(std::ostream&, T)
+(declaration
+  declarator: (function_declarator
+    declarator: (operator_name) @declaration.name)) @declaration.function
+
 ;; ─── Declarations — function prototype with pointer return ──────────
 (declaration
   declarator: (pointer_declarator
     declarator: (function_declarator
       declarator: (identifier) @declaration.name))) @declaration.function
 
+;; Free operator prototype with reference return.
+(declaration
+  declarator: (reference_declarator
+    (function_declarator
+      declarator: (operator_name) @declaration.name))) @declaration.function
+
 ;; ─── Declarations — typedef ─────────────────────────────────────────
 (type_definition
   declarator: (type_identifier) @declaration.name) @declaration.typedef
@@ -170,6 +213,11 @@ const CPP_SCOPE_QUERY = `
   declarator: (function_declarator
     declarator: (field_identifier) @declaration.name)) @declaration.method
 
+;; Operator method prototype in class body: Point operator+(Point) const;
+(field_declaration
+  declarator: (function_declarator
+    declarator: (operator_name) @declaration.name)) @declaration.method
+
 ;; Method prototype with pointer return: User* lookup(int id);
 (field_declaration
   declarator: (pointer_declarator
@@ -182,6 +230,11 @@ const CPP_SCOPE_QUERY = `
     (function_declarator
       declarator: (field_identifier) @declaration.name))) @declaration.method
 
+(field_declaration
+  declarator: (reference_declarator
+    (function_declarator
+      declarator: (operator_name) @declaration.name))) @declaration.method
+
 ;; ─── Declarations — fields ──────────────────────────────────────────
 (field_declaration
   declarator: (field_identifier) @declaration.name) @declaration.field
@@ -472,6 +525,22 @@ const CPP_SCOPE_QUERY = `
     argument: (_) @reference.receiver
     field: (field_identifier) @reference.name)) @reference.call.member
 
+;; Conservative operator-call support (#1636): model a + b as a
+;; member-style operator+ lookup, and lhs << rhs as a free
+;; operator<< lookup. Free operator+(T,T), member operator<<, and
+;; complex operand expressions remain false negatives for now.
+;; Built-in operators remain unresolved because no user-defined
+;; operator target exists.
+(binary_expression
+  left: (_) @reference.receiver
+  operator: "+" @reference.operator
+  right: (_)) @reference.call.member
+
+(binary_expression
+  left: (_)
+  operator: "<<" @reference.operator
+  right: (_)) @reference.call.free
+
 ;; ─── References — template calls (func<T>()) ────────────────────────
 (call_expression
   function: (template_function

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

@@ -812,6 +812,7 @@ const KNOWN_SUB_TAGS = new Set([
     '@type-binding.type',
     '@reference.name',
     '@reference.receiver',
+    '@reference.operator',
     '@reference.arity',
     '@reference.parameter-types',
     '@reference.parameter-type-classes',

package/dist/core/ingestion/tree-sitter-queries.d.ts

@@ -4,7 +4,7 @@ export declare const PYTHON_QUERIES = "\n(class_definition\n  name: (identifier)
 export declare const JAVA_QUERIES = "\n; Classes, Interfaces, Enums, Annotations\n(class_declaration name: (identifier) @name) @definition.class\n(interface_declaration name: (identifier) @name) @definition.interface\n(enum_declaration name: (identifier) @name) @definition.enum\n(annotation_type_declaration name: (identifier) @name) @definition.annotation\n\n; Methods & Constructors\n(method_declaration name: (identifier) @name) @definition.method\n(constructor_declaration name: (identifier) @name) @definition.constructor\n\n; Fields \u2014 typed field declarations inside class bodies\n(field_declaration\n  declarator: (variable_declarator\n    name: (identifier) @name)) @definition.property\n\n; Imports - capture any import declaration child as source\n(import_declaration (_) @import.source) @import\n\n; Calls\n(method_invocation name: (identifier) @call.name) @call\n(method_invocation object: (_) name: (identifier) @call.name) @call\n(method_reference) @call\n\n; Constructor calls: new Foo()\n(object_creation_expression type: (type_identifier) @call.name) @call\n\n; Local variable declarations inside method bodies\n(local_variable_declaration\n  declarator: (variable_declarator\n    name: (identifier) @name)) @definition.variable\n\n; Heritage - extends class\n(class_declaration name: (identifier) @heritage.class\n  (superclass (type_identifier) @heritage.extends)) @heritage\n\n; Heritage - implements interfaces\n(class_declaration name: (identifier) @heritage.class\n  (super_interfaces (type_list (type_identifier) @heritage.implements))) @heritage.impl\n\n; Write access: obj.field = value\n(assignment_expression\n  left: (field_access\n    object: (_) @assignment.receiver\n    field: (identifier) @assignment.property)\n  right: (_)) @assignment\n";
 export declare const C_QUERIES = "\n; Functions (direct declarator)\n(function_definition declarator: (function_declarator declarator: (identifier) @name)) @definition.function\n(declaration declarator: (function_declarator declarator: (identifier) @name)) @definition.function\n\n; Functions returning pointers (pointer_declarator wraps function_declarator)\n(function_definition declarator: (pointer_declarator declarator: (function_declarator declarator: (identifier) @name))) @definition.function\n(declaration declarator: (pointer_declarator declarator: (function_declarator declarator: (identifier) @name))) @definition.function\n\n; Functions returning double pointers (nested pointer_declarator)\n(function_definition declarator: (pointer_declarator declarator: (pointer_declarator declarator: (function_declarator declarator: (identifier) @name)))) @definition.function\n\n; Structs, Unions, Enums, Typedefs\n(struct_specifier name: (type_identifier) @name) @definition.struct\n(union_specifier name: (type_identifier) @name) @definition.union\n(enum_specifier name: (type_identifier) @name) @definition.enum\n(type_definition declarator: (type_identifier) @name) @definition.typedef\n\n; Macros\n(preproc_function_def name: (identifier) @name) @definition.macro\n(preproc_def name: (identifier) @name) @definition.macro\n\n; Includes\n(preproc_include path: (_) @import.source) @import\n\n; Calls\n(call_expression function: (identifier) @call.name) @call\n(call_expression function: (field_expression field: (field_identifier) @call.name)) @call\n\n; Variable declarations: int x = 5; or int x;\n(declaration\n  declarator: (init_declarator\n    declarator: (identifier) @name)) @definition.variable\n";
 export declare const GO_QUERIES = "\n; Functions & Methods\n(function_declaration name: (identifier) @name) @definition.function\n(method_declaration name: (field_identifier) @name) @definition.method\n\n; Types\n(type_declaration (type_spec name: (type_identifier) @name type: (struct_type))) @definition.struct\n(type_declaration (type_spec name: (type_identifier) @name type: (interface_type))) @definition.interface\n\n; Imports\n(import_declaration (import_spec path: (interpreted_string_literal) @import.source)) @import\n(import_declaration (import_spec_list (import_spec path: (interpreted_string_literal) @import.source))) @import\n\n; Struct fields \u2014 named field declarations inside struct types\n(field_declaration_list\n  (field_declaration\n    name: (field_identifier) @name) @definition.property)\n\n; Struct embedding (anonymous fields = inheritance)\n(type_declaration\n  (type_spec\n    name: (type_identifier) @heritage.class\n    type: (struct_type\n      (field_declaration_list\n        (field_declaration\n          type: (type_identifier) @heritage.extends))))) @definition.struct\n\n; Calls\n(call_expression function: (identifier) @call.name) @call\n(call_expression function: (selector_expression field: (field_identifier) @call.name)) @call\n\n; Const/var declarations\n(const_declaration (const_spec name: (identifier) @name)) @definition.const\n(var_declaration (var_spec name: (identifier) @name)) @definition.variable\n\n; Short variable declaration: x := 5\n(short_var_declaration left: (expression_list (identifier) @name)) @definition.variable\n\n; Struct literal construction: User{Name: \"Alice\"}\n(composite_literal type: (type_identifier) @call.name) @call\n\n; Write access: obj.field = value\n(assignment_statement\n  left: (expression_list\n    (selector_expression\n      operand: (_) @assignment.receiver\n      field: (field_identifier) @assignment.property))\n  right: (_)) @assignment\n\n; Write access: obj.field++ / obj.field--\n(inc_statement\n  (selector_expression\n    operand: (_) @assignment.receiver\n    field: (field_identifier) @assignment.property)) @assignment\n(dec_statement\n  (selector_expression\n    operand: (_) @assignment.receiver\n    field: (field_identifier) @assignment.property)) @assignment\n";
-export declare const CPP_QUERIES = "\n; Classes, Structs, Namespaces\n(class_specifier name: (type_identifier) @name) @definition.class\n(class_specifier\n  name: (template_type\n    (type_identifier) @name\n    (template_argument_list) @template-arguments)) @definition.class\n(struct_specifier name: (type_identifier) @name) @definition.struct\n(struct_specifier\n  name: (template_type\n    (type_identifier) @name\n    (template_argument_list) @template-arguments)) @definition.struct\n(namespace_definition name: (namespace_identifier) @name) @definition.namespace\n(enum_specifier name: (type_identifier) @name) @definition.enum\n\n; Typedefs and unions (common in C-style headers and mixed C/C++ code)\n(type_definition declarator: (type_identifier) @name) @definition.typedef\n(union_specifier name: (type_identifier) @name) @definition.union\n\n; Macros\n(preproc_function_def name: (identifier) @name) @definition.macro\n(preproc_def name: (identifier) @name) @definition.macro\n\n; Functions & Methods (direct declarator)\n(function_definition declarator: (function_declarator declarator: (identifier) @name)) @definition.function\n(function_definition declarator: (function_declarator declarator: (qualified_identifier name: (identifier) @name))) @definition.method\n\n; Functions/methods returning pointers (pointer_declarator wraps function_declarator)\n(function_definition declarator: (pointer_declarator declarator: (function_declarator declarator: (identifier) @name))) @definition.function\n(function_definition declarator: (pointer_declarator declarator: (function_declarator declarator: (qualified_identifier name: (identifier) @name)))) @definition.method\n\n; Functions/methods returning double pointers (nested pointer_declarator)\n(function_definition declarator: (pointer_declarator declarator: (pointer_declarator declarator: (function_declarator declarator: (identifier) @name)))) @definition.function\n(function_definition declarator: (pointer_declarator declarator: (pointer_declarator declarator: (function_declarator declarator: (qualified_identifier name: (identifier) @name))))) @definition.method\n\n; Functions/methods returning references (reference_declarator wraps function_declarator)\n(function_definition declarator: (reference_declarator (function_declarator declarator: (identifier) @name))) @definition.function\n(function_definition declarator: (reference_declarator (function_declarator declarator: (qualified_identifier name: (identifier) @name)))) @definition.method\n\n; Destructors (destructor_name is distinct from identifier in tree-sitter-cpp)\n(function_definition declarator: (function_declarator declarator: (qualified_identifier name: (destructor_name) @name))) @definition.method\n\n; Function declarations / prototypes (common in headers)\n(declaration declarator: (function_declarator declarator: (identifier) @name)) @definition.function\n(declaration declarator: (pointer_declarator declarator: (function_declarator declarator: (identifier) @name))) @definition.function\n\n; Class/struct data member fields (Address address; int count;)\n; Uses field_identifier to exclude method declarations (which use function_declarator)\n(field_declaration\n  declarator: (field_identifier) @name) @definition.property\n\n; Pointer member fields (Address* address;)\n(field_declaration\n  declarator: (pointer_declarator\n    declarator: (field_identifier) @name)) @definition.property\n\n; Reference member fields (Address& address;)\n(field_declaration\n  declarator: (reference_declarator\n    (field_identifier) @name)) @definition.property\n\n; Inline class method declarations (inside class body, no body: void save();)\n; tree-sitter-cpp uses field_identifier (not identifier) for names inside class bodies\n(field_declaration declarator: (function_declarator declarator: [(field_identifier) (identifier)] @name)) @definition.method\n\n; Inline class method declarations returning a pointer (User* lookup();)\n(field_declaration declarator: (pointer_declarator declarator: (function_declarator declarator: [(field_identifier) (identifier)] @name))) @definition.method\n\n; Inline class method declarations returning a reference (User& lookup();)\n(field_declaration declarator: (reference_declarator (function_declarator declarator: [(field_identifier) (identifier)] @name))) @definition.method\n\n; Inline class method definitions (inside class body, with body: void Foo() { ... })\n(field_declaration_list\n  (function_definition\n    declarator: (function_declarator\n      declarator: [(field_identifier) (identifier) (operator_name) (destructor_name)] @name)) @definition.method)\n\n; Inline class methods returning a pointer type (User* lookup(int id) { ... })\n(field_declaration_list\n  (function_definition\n    declarator: (pointer_declarator\n      declarator: (function_declarator\n        declarator: [(field_identifier) (identifier) (operator_name)] @name))) @definition.method)\n\n; Inline class methods returning a reference type (User& lookup(int id) { ... })\n(field_declaration_list\n  (function_definition\n    declarator: (reference_declarator\n      (function_declarator\n        declarator: [(field_identifier) (identifier) (operator_name)] @name))) @definition.method)\n\n; Templates\n(template_declaration (class_specifier name: (type_identifier) @name)) @definition.template\n(template_declaration\n  (class_specifier\n    name: (template_type\n      (type_identifier) @name\n      (template_argument_list) @template-arguments))) @definition.template\n(template_declaration (function_definition declarator: (function_declarator declarator: (identifier) @name))) @definition.template\n\n; Includes\n(preproc_include path: (_) @import.source) @import\n\n; Calls\n(call_expression function: (identifier) @call.name) @call\n(call_expression function: (field_expression field: (field_identifier) @call.name)) @call\n(call_expression function: (qualified_identifier name: (identifier) @call.name)) @call\n(call_expression function: (template_function name: (identifier) @call.name)) @call\n\n; Constructor calls: new User()\n(new_expression type: (type_identifier) @call.name) @call\n\n; Variable declarations: int x = 5; or auto x = 5;\n(declaration\n  declarator: (init_declarator\n    declarator: (identifier) @name)) @definition.variable\n\n; Heritage\n(class_specifier name: (type_identifier) @heritage.class\n  (base_class_clause (type_identifier) @heritage.extends)) @heritage\n(class_specifier name: (type_identifier) @heritage.class\n  (base_class_clause (access_specifier) (type_identifier) @heritage.extends)) @heritage\n\n; Write access: obj.field = value\n(assignment_expression\n  left: (field_expression\n    argument: (_) @assignment.receiver\n    field: (field_identifier) @assignment.property)\n  right: (_)) @assignment\n\n";
+export declare const CPP_QUERIES = "\n; Classes, Structs, Namespaces\n(class_specifier name: (type_identifier) @name) @definition.class\n(class_specifier\n  name: (template_type\n    (type_identifier) @name\n    (template_argument_list) @template-arguments)) @definition.class\n(struct_specifier name: (type_identifier) @name) @definition.struct\n(struct_specifier\n  name: (template_type\n    (type_identifier) @name\n    (template_argument_list) @template-arguments)) @definition.struct\n(namespace_definition name: (namespace_identifier) @name) @definition.namespace\n(enum_specifier name: (type_identifier) @name) @definition.enum\n\n; Typedefs and unions (common in C-style headers and mixed C/C++ code)\n(type_definition declarator: (type_identifier) @name) @definition.typedef\n(union_specifier name: (type_identifier) @name) @definition.union\n\n; Macros\n(preproc_function_def name: (identifier) @name) @definition.macro\n(preproc_def name: (identifier) @name) @definition.macro\n\n; Functions & Methods (direct declarator)\n(function_definition declarator: (function_declarator declarator: (identifier) @name)) @definition.function\n(function_definition declarator: (function_declarator declarator: (operator_name) @name)) @definition.function\n(function_definition declarator: (function_declarator declarator: (qualified_identifier name: (identifier) @name))) @definition.method\n(function_definition declarator: (function_declarator declarator: (qualified_identifier name: (operator_name) @name))) @definition.method\n\n; Functions/methods returning pointers (pointer_declarator wraps function_declarator)\n(function_definition declarator: (pointer_declarator declarator: (function_declarator declarator: (identifier) @name))) @definition.function\n(function_definition declarator: (pointer_declarator declarator: (function_declarator declarator: (qualified_identifier name: (identifier) @name)))) @definition.method\n\n; Functions/methods returning double pointers (nested pointer_declarator)\n(function_definition declarator: (pointer_declarator declarator: (pointer_declarator declarator: (function_declarator declarator: (identifier) @name)))) @definition.function\n(function_definition declarator: (pointer_declarator declarator: (pointer_declarator declarator: (function_declarator declarator: (qualified_identifier name: (identifier) @name))))) @definition.method\n\n; Functions/methods returning references (reference_declarator wraps function_declarator)\n(function_definition declarator: (reference_declarator (function_declarator declarator: (identifier) @name))) @definition.function\n(function_definition declarator: (reference_declarator (function_declarator declarator: (operator_name) @name))) @definition.function\n(function_definition declarator: (reference_declarator (function_declarator declarator: (qualified_identifier name: (identifier) @name)))) @definition.method\n(function_definition declarator: (reference_declarator (function_declarator declarator: (qualified_identifier name: (operator_name) @name)))) @definition.method\n\n; Destructors (destructor_name is distinct from identifier in tree-sitter-cpp)\n(function_definition declarator: (function_declarator declarator: (qualified_identifier name: (destructor_name) @name))) @definition.method\n\n; Function declarations / prototypes (common in headers)\n(declaration declarator: (function_declarator declarator: (identifier) @name)) @definition.function\n(declaration declarator: (function_declarator declarator: (operator_name) @name)) @definition.function\n(declaration declarator: (pointer_declarator declarator: (function_declarator declarator: (identifier) @name))) @definition.function\n(declaration declarator: (reference_declarator (function_declarator declarator: (operator_name) @name))) @definition.function\n\n; Class/struct data member fields (Address address; int count;)\n; Uses field_identifier to exclude method declarations (which use function_declarator)\n(field_declaration\n  declarator: (field_identifier) @name) @definition.property\n\n; Pointer member fields (Address* address;)\n(field_declaration\n  declarator: (pointer_declarator\n    declarator: (field_identifier) @name)) @definition.property\n\n; Reference member fields (Address& address;)\n(field_declaration\n  declarator: (reference_declarator\n    (field_identifier) @name)) @definition.property\n\n; Inline class method declarations (inside class body, no body: void save();)\n; tree-sitter-cpp uses field_identifier (not identifier) for names inside class bodies\n(field_declaration declarator: (function_declarator declarator: [(field_identifier) (identifier) (operator_name)] @name)) @definition.method\n\n; Inline class method declarations returning a pointer (User* lookup();)\n(field_declaration declarator: (pointer_declarator declarator: (function_declarator declarator: [(field_identifier) (identifier)] @name))) @definition.method\n\n; Inline class method declarations returning a reference (User& lookup();)\n(field_declaration declarator: (reference_declarator (function_declarator declarator: [(field_identifier) (identifier) (operator_name)] @name))) @definition.method\n\n; Inline class method definitions (inside class body, with body: void Foo() { ... })\n(field_declaration_list\n  (function_definition\n    declarator: (function_declarator\n      declarator: [(field_identifier) (identifier) (operator_name) (destructor_name)] @name)) @definition.method)\n\n; Inline class methods returning a pointer type (User* lookup(int id) { ... })\n(field_declaration_list\n  (function_definition\n    declarator: (pointer_declarator\n      declarator: (function_declarator\n        declarator: [(field_identifier) (identifier) (operator_name)] @name))) @definition.method)\n\n; Inline class methods returning a reference type (User& lookup(int id) { ... })\n(field_declaration_list\n  (function_definition\n    declarator: (reference_declarator\n      (function_declarator\n        declarator: [(field_identifier) (identifier) (operator_name)] @name))) @definition.method)\n\n; Templates\n(template_declaration (class_specifier name: (type_identifier) @name)) @definition.template\n(template_declaration\n  (class_specifier\n    name: (template_type\n      (type_identifier) @name\n      (template_argument_list) @template-arguments))) @definition.template\n(template_declaration (function_definition declarator: (function_declarator declarator: (identifier) @name))) @definition.template\n\n; Includes\n(preproc_include path: (_) @import.source) @import\n\n; Calls\n(call_expression function: (identifier) @call.name) @call\n(call_expression function: (field_expression field: (field_identifier) @call.name)) @call\n(call_expression function: (qualified_identifier name: (identifier) @call.name)) @call\n(call_expression function: (template_function name: (identifier) @call.name)) @call\n(binary_expression operator: \"+\" @call.name) @call\n(binary_expression operator: \"<<\" @call.name) @call\n\n; Constructor calls: new User()\n(new_expression type: (type_identifier) @call.name) @call\n\n; Variable declarations: int x = 5; or auto x = 5;\n(declaration\n  declarator: (init_declarator\n    declarator: (identifier) @name)) @definition.variable\n\n; Heritage\n(class_specifier name: (type_identifier) @heritage.class\n  (base_class_clause (type_identifier) @heritage.extends)) @heritage\n(class_specifier name: (type_identifier) @heritage.class\n  (base_class_clause (access_specifier) (type_identifier) @heritage.extends)) @heritage\n\n; Write access: obj.field = value\n(assignment_expression\n  left: (field_expression\n    argument: (_) @assignment.receiver\n    field: (field_identifier) @assignment.property)\n  right: (_)) @assignment\n\n";
 export declare const CSHARP_QUERIES = "\n; Types\n(class_declaration name: (identifier) @name) @definition.class\n(interface_declaration name: (identifier) @name) @definition.interface\n(struct_declaration name: (identifier) @name) @definition.struct\n(enum_declaration name: (identifier) @name) @definition.enum\n(record_declaration name: (identifier) @name) @definition.record\n(delegate_declaration name: (identifier) @name) @definition.delegate\n\n; Namespaces (block form and C# 10+ file-scoped form)\n(namespace_declaration name: (identifier) @name) @definition.namespace\n(namespace_declaration name: (qualified_name) @name) @definition.namespace\n(file_scoped_namespace_declaration name: (identifier) @name) @definition.namespace\n(file_scoped_namespace_declaration name: (qualified_name) @name) @definition.namespace\n\n; Methods & Properties\n(method_declaration name: (identifier) @name) @definition.method\n(local_function_statement name: (identifier) @name) @definition.function\n(constructor_declaration name: (identifier) @name) @definition.constructor\n(property_declaration name: (identifier) @name) @definition.property\n\n; Primary constructors (C# 12): class User(string name, int age) { }\n(class_declaration name: (identifier) @name (parameter_list) @definition.constructor)\n(record_declaration name: (identifier) @name (parameter_list) @definition.constructor)\n\n; Using\n(using_directive (qualified_name) @import.source) @import\n(using_directive (identifier) @import.source) @import\n\n; Calls\n(invocation_expression function: (identifier) @call.name) @call\n(invocation_expression function: (member_access_expression name: (identifier) @call.name)) @call\n\n; Null-conditional method calls: user?.Save()\n; Parses as: invocation_expression \u2192 conditional_access_expression \u2192 member_binding_expression \u2192 identifier\n(invocation_expression\n  function: (conditional_access_expression\n    (member_binding_expression\n      (identifier) @call.name))) @call\n\n; Constructor calls: new Foo() and new Foo { Props }\n(object_creation_expression type: (identifier) @call.name) @call\n\n; Target-typed new (C# 9): User u = new(\"x\", 5)\n(variable_declaration type: (identifier) @call.name (variable_declarator (implicit_object_creation_expression) @call))\n\n; Local variable declarations\n(local_declaration_statement\n  (variable_declaration\n    (variable_declarator\n      (identifier) @name))) @definition.variable\n\n; Heritage\n(class_declaration name: (identifier) @heritage.class\n  (base_list (identifier) @heritage.extends)) @heritage\n(class_declaration name: (identifier) @heritage.class\n  (base_list (generic_name (identifier) @heritage.extends))) @heritage\n\n; Interface inheritance: interface IFoo : IBar / interface IFoo : IBar, IBaz\n; Without these patterns, interface-to-interface relationships are never\n; captured, so transitive \"class X implements IBar\" chains are broken.\n(interface_declaration name: (identifier) @heritage.class\n  (base_list (identifier) @heritage.extends)) @heritage\n(interface_declaration name: (identifier) @heritage.class\n  (base_list (generic_name (identifier) @heritage.extends))) @heritage\n\n; Write access: obj.field = value\n(assignment_expression\n  left: (member_access_expression\n    expression: (_) @assignment.receiver\n    name: (identifier) @assignment.property)\n  right: (_)) @assignment\n";
 export declare const RUST_QUERIES = "\n; Functions & Items\n(function_item name: (identifier) @name) @definition.function\n(function_signature_item name: (identifier) @name) @definition.function\n(struct_item name: (type_identifier) @name) @definition.struct\n(enum_item name: (type_identifier) @name) @definition.enum\n(trait_item name: (type_identifier) @name) @definition.trait\n(impl_item type: (type_identifier) @name !trait) @definition.impl\n(impl_item type: (generic_type type: (type_identifier) @name) !trait) @definition.impl\n(mod_item name: (identifier) @name) @definition.module\n\n; Type aliases, const, static, macros\n(type_item name: (type_identifier) @name) @definition.type\n(const_item name: (identifier) @name) @definition.const\n(static_item name: (identifier) @name) @definition.static\n(macro_definition name: (identifier) @name) @definition.macro\n\n; Use statements\n(use_declaration argument: (_) @import.source) @import\n\n; Calls\n(call_expression function: (identifier) @call.name) @call\n(call_expression function: (field_expression field: (field_identifier) @call.name)) @call\n(call_expression function: (scoped_identifier name: (identifier) @call.name)) @call\n(call_expression function: (generic_function function: (identifier) @call.name)) @call\n\n; Struct literal construction: User { name: value }\n(struct_expression name: (type_identifier) @call.name) @call\n\n; Struct fields \u2014 named field declarations inside struct bodies\n(field_declaration_list\n  (field_declaration\n    name: (field_identifier) @name) @definition.property)\n\n; Heritage (trait implementation) \u2014 all combinations of concrete/generic trait \u00D7 concrete/generic type\n(impl_item trait: (type_identifier) @heritage.trait type: (type_identifier) @heritage.class) @heritage\n(impl_item trait: (generic_type type: (type_identifier) @heritage.trait) type: (type_identifier) @heritage.class) @heritage\n(impl_item trait: (type_identifier) @heritage.trait type: (generic_type type: (type_identifier) @heritage.class)) @heritage\n(impl_item trait: (generic_type type: (type_identifier) @heritage.trait) type: (generic_type type: (type_identifier) @heritage.class)) @heritage\n\n; Write access: obj.field = value\n(assignment_expression\n  left: (field_expression\n    value: (_) @assignment.receiver\n    field: (field_identifier) @assignment.property)\n  right: (_)) @assignment\n\n; Write access: obj.field += value (compound assignment)\n(compound_assignment_expr\n  left: (field_expression\n    value: (_) @assignment.receiver\n    field: (field_identifier) @assignment.property)\n  right: (_)) @assignment\n";
 export declare const PHP_QUERIES = "\n; \u2500\u2500 Namespace \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n(namespace_definition\n  name: (namespace_name) @name) @definition.namespace\n\n; \u2500\u2500 Classes \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n(class_declaration\n  name: (name) @name) @definition.class\n\n; \u2500\u2500 Interfaces \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n(interface_declaration\n  name: (name) @name) @definition.interface\n\n; \u2500\u2500 Traits \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n(trait_declaration\n  name: (name) @name) @definition.trait\n\n; \u2500\u2500 Enums (PHP 8.1) \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n(enum_declaration\n  name: (name) @name) @definition.enum\n\n; \u2500\u2500 Top-level functions \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n(function_definition\n  name: (name) @name) @definition.function\n\n; \u2500\u2500 Methods (including constructors) \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n(method_declaration\n  name: (name) @name) @definition.method\n\n; \u2500\u2500 Class properties (including Eloquent $fillable, $casts, etc.) \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n(property_declaration\n  (property_element\n    (variable_name\n      (name) @name))) @definition.property\n\n; Constructor property promotion (PHP 8.0+: public Address $address in __construct)\n(method_declaration\n  parameters: (formal_parameters\n    (property_promotion_parameter\n      name: (variable_name\n        (name) @name)))) @definition.property\n\n; \u2500\u2500 Imports: use statements \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n; Simple: use App\\Models\\User;\n(namespace_use_declaration\n  (namespace_use_clause\n    (qualified_name) @import.source)) @import\n\n; \u2500\u2500 Function/method calls \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n; Regular function call: foo()\n(function_call_expression\n  function: (name) @call.name) @call\n\n; Method call: $obj->method()\n(member_call_expression\n  name: (name) @call.name) @call\n\n; Nullsafe method call: $obj?->method()\n(nullsafe_member_call_expression\n  name: (name) @call.name) @call\n\n; Static call: Foo::bar() (php_only uses scoped_call_expression)\n(scoped_call_expression\n  name: (name) @call.name) @call\n\n; Constructor call: new User()\n(object_creation_expression (name) @call.name) @call\n\n; Const declarations at class scope\n(const_declaration\n  (const_element\n    (name) @name)) @definition.const\n\n; \u2500\u2500 Heritage: extends \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n(class_declaration\n  name: (name) @heritage.class\n  (base_clause\n    [(name) (qualified_name)] @heritage.extends)) @heritage\n\n; \u2500\u2500 Heritage: implements \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n(class_declaration\n  name: (name) @heritage.class\n  (class_interface_clause\n    [(name) (qualified_name)] @heritage.implements)) @heritage.impl\n\n; \u2500\u2500 Heritage: use trait (must capture enclosing class name) \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n(class_declaration\n  name: (name) @heritage.class\n  body: (declaration_list\n    (use_declaration\n      [(name) (qualified_name)] @heritage.trait))) @heritage\n\n; \u2500\u2500 Heritage: trait uses another trait (transitive trait composition) \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n; PHP allows a trait body to contain \"use OtherTrait;\". The trait-uses-trait\n; IMPLEMENTS edge is required by buildPhpMro to compute the full transitive\n; trait closure (depth 3+ chains).\n(trait_declaration\n  name: (name) @heritage.class\n  body: (declaration_list\n    (use_declaration\n      [(name) (qualified_name)] @heritage.trait))) @heritage\n\n; PHP HTTP consumers: file_get_contents('/path'), curl_init('/path')\n(function_call_expression\n  function: (name) @_php_http (#match? @_php_http \"^(file_get_contents|curl_init)$\")\n  arguments: (arguments\n    (argument (string (string_content) @http_client.url)))) @http_client\n\n; Write access: $obj->field = value\n(assignment_expression\n  left: (member_access_expression\n    object: (_) @assignment.receiver\n    name: (name) @assignment.property)\n  right: (_)) @assignment\n\n; Write access: ClassName::$field = value (static property)\n(assignment_expression\n  left: (scoped_property_access_expression\n    scope: (_) @assignment.receiver\n    name: (variable_name (name) @assignment.property))\n  right: (_)) @assignment\n";

package/dist/core/ingestion/tree-sitter-queries.js

@@ -695,7 +695,9 @@ export const CPP_QUERIES = `
 
 ; Functions & Methods (direct declarator)
 (function_definition declarator: (function_declarator declarator: (identifier) @name)) @definition.function
+(function_definition declarator: (function_declarator declarator: (operator_name) @name)) @definition.function
 (function_definition declarator: (function_declarator declarator: (qualified_identifier name: (identifier) @name))) @definition.method
+(function_definition declarator: (function_declarator declarator: (qualified_identifier name: (operator_name) @name))) @definition.method
 
 ; Functions/methods returning pointers (pointer_declarator wraps function_declarator)
 (function_definition declarator: (pointer_declarator declarator: (function_declarator declarator: (identifier) @name))) @definition.function
@@ -707,14 +709,18 @@ export const CPP_QUERIES = `
 
 ; Functions/methods returning references (reference_declarator wraps function_declarator)
 (function_definition declarator: (reference_declarator (function_declarator declarator: (identifier) @name))) @definition.function
+(function_definition declarator: (reference_declarator (function_declarator declarator: (operator_name) @name))) @definition.function
 (function_definition declarator: (reference_declarator (function_declarator declarator: (qualified_identifier name: (identifier) @name)))) @definition.method
+(function_definition declarator: (reference_declarator (function_declarator declarator: (qualified_identifier name: (operator_name) @name)))) @definition.method
 
 ; Destructors (destructor_name is distinct from identifier in tree-sitter-cpp)
 (function_definition declarator: (function_declarator declarator: (qualified_identifier name: (destructor_name) @name))) @definition.method
 
 ; Function declarations / prototypes (common in headers)
 (declaration declarator: (function_declarator declarator: (identifier) @name)) @definition.function
+(declaration declarator: (function_declarator declarator: (operator_name) @name)) @definition.function
 (declaration declarator: (pointer_declarator declarator: (function_declarator declarator: (identifier) @name))) @definition.function
+(declaration declarator: (reference_declarator (function_declarator declarator: (operator_name) @name))) @definition.function
 
 ; Class/struct data member fields (Address address; int count;)
 ; Uses field_identifier to exclude method declarations (which use function_declarator)
@@ -733,13 +739,13 @@ export const CPP_QUERIES = `
 
 ; Inline class method declarations (inside class body, no body: void save();)
 ; tree-sitter-cpp uses field_identifier (not identifier) for names inside class bodies
-(field_declaration declarator: (function_declarator declarator: [(field_identifier) (identifier)] @name)) @definition.method
+(field_declaration declarator: (function_declarator declarator: [(field_identifier) (identifier) (operator_name)] @name)) @definition.method
 
 ; Inline class method declarations returning a pointer (User* lookup();)
 (field_declaration declarator: (pointer_declarator declarator: (function_declarator declarator: [(field_identifier) (identifier)] @name))) @definition.method
 
 ; Inline class method declarations returning a reference (User& lookup();)
-(field_declaration declarator: (reference_declarator (function_declarator declarator: [(field_identifier) (identifier)] @name))) @definition.method
+(field_declaration declarator: (reference_declarator (function_declarator declarator: [(field_identifier) (identifier) (operator_name)] @name))) @definition.method
 
 ; Inline class method definitions (inside class body, with body: void Foo() { ... })
 (field_declaration_list
@@ -778,6 +784,8 @@ export const CPP_QUERIES = `
 (call_expression function: (field_expression field: (field_identifier) @call.name)) @call
 (call_expression function: (qualified_identifier name: (identifier) @call.name)) @call
 (call_expression function: (template_function name: (identifier) @call.name)) @call
+(binary_expression operator: "+" @call.name) @call
+(binary_expression operator: "<<" @call.name) @call
 
 ; Constructor calls: new User()
 (new_expression type: (type_identifier) @call.name) @call

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

@@ -142,6 +142,21 @@ export declare const fetchExistingEmbeddingHashes: (execQuery: (cypher: string)
  * @see safeClose — CHECKPOINT + connection/database close
  */
 export declare const flushWAL: () => Promise<void>;
+/**
+ * Issue a manual `CHECKPOINT` against the current connection and surface
+ * any engine error to the caller. Unlike {@link flushWAL}, this variant
+ * does NOT swallow Ladybug rename/remove IO failures — the manual
+ * checkpoint driver (`wal-checkpoint-driver.ts`) relies on the rejection
+ * to drive its bounded retry loop. Returns `false` when no connection is
+ * open (the caller treats this as a no-op success — there is no WAL to
+ * flush). Returns `true` after a successful CHECKPOINT + drain.
+ *
+ * The split from `flushWAL` is deliberate: every other CHECKPOINT site
+ * (server flush, safeClose) is best-effort and prefers a silent skip;
+ * the manual driver, by contrast, must observe failures to decide
+ * whether to retry.
+ */
+export declare const tryFlushWAL: () => Promise<boolean>;
 /**
  * Flush the WAL and close the connection and database handles.
  *

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

@@ -1334,6 +1334,27 @@ export const flushWAL = async () => {
         logger.debug(`GitNexus: LadybugDB CHECKPOINT skipped/failed during WAL flush: ${summarizeError(err)}`);
     }
 };
+/**
+ * Issue a manual `CHECKPOINT` against the current connection and surface
+ * any engine error to the caller. Unlike {@link flushWAL}, this variant
+ * does NOT swallow Ladybug rename/remove IO failures — the manual
+ * checkpoint driver (`wal-checkpoint-driver.ts`) relies on the rejection
+ * to drive its bounded retry loop. Returns `false` when no connection is
+ * open (the caller treats this as a no-op success — there is no WAL to
+ * flush). Returns `true` after a successful CHECKPOINT + drain.
+ *
+ * The split from `flushWAL` is deliberate: every other CHECKPOINT site
+ * (server flush, safeClose) is best-effort and prefers a silent skip;
+ * the manual driver, by contrast, must observe failures to decide
+ * whether to retry.
+ */
+export const tryFlushWAL = async () => {
+    if (!conn)
+        return false;
+    const checkpointResult = await conn.query('CHECKPOINT');
+    await drainQueryResult(checkpointResult);
+    return true;
+};
 /**
  * Flush the WAL and close the connection and database handles.
  *

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

@@ -32,8 +32,15 @@ import type lbug from '@ladybugdb/core';
  * integer; anything invalid falls back to the default.
  */
 export declare const LBUG_MAX_DB_SIZE: number;
+export declare const parseWalCheckpointThreshold: (raw: string | undefined) => number | undefined;
 export declare const WAL_RECOVERY_SUGGESTION = "WAL corruption detected. Run `gitnexus analyze --force` to rebuild the index.";
 export declare function isWalCorruptionError(err: unknown): boolean;
+/**
+ * True when `err` looks like a Ladybug WAL-checkpoint rotation/remove IO
+ * failure. Tries strict matchers first (renames + removes), then falls
+ * back to the permissive matcher.
+ */
+export declare const isLbugCheckpointIoError: (err: unknown) => boolean;
 type LbugModule = typeof lbug;
 export interface LbugDatabaseOptions {
     readOnly?: boolean;

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

@@ -1,6 +1,7 @@
 import fs from 'fs/promises';
 import os from 'os';
 import path from 'path';
+import { logger } from '../logger.js';
 /**
  * Shared configuration for `@ladybugdb/core` `Database` construction.
  *
@@ -42,6 +43,43 @@ export const LBUG_MAX_DB_SIZE = (() => {
     }
     return 16 * 1024 * 1024 * 1024;
 })();
+export const parseWalCheckpointThreshold = (raw) => {
+    if (raw === undefined)
+        return undefined;
+    const normalized = raw.trim();
+    if (normalized.length === 0)
+        return undefined;
+    const parsed = Number(normalized);
+    if (!Number.isInteger(parsed) || parsed < -1)
+        return undefined;
+    return parsed;
+};
+/**
+ * Default GitNexus WAL auto-checkpoint threshold in bytes (64 MiB).
+ *
+ * Larger than Ladybug's stock ~16 MiB to reduce checkpoint rename/remove
+ * churn under heavy analyze write load — the original race that motivated
+ * issue #1741 triggered at the stock threshold. README examples in
+ * `README.md` and `gitnexus/README.md` and the recovery hint in
+ * `analyze.ts` MUST stay in sync with this value.
+ */
+const DEFAULT_WAL_CHECKPOINT_THRESHOLD = 64 * 1024 * 1024;
+const resolveCheckpointThreshold = () => {
+    const raw = process.env.GITNEXUS_WAL_CHECKPOINT_THRESHOLD;
+    if (raw === undefined)
+        return DEFAULT_WAL_CHECKPOINT_THRESHOLD;
+    const parsed = parseWalCheckpointThreshold(raw);
+    if (parsed !== undefined)
+        return parsed;
+    // Non-empty but unparseable input: warn the operator and fall back. Mirrors
+    // the CLI's `--wal-checkpoint-threshold` validation (which hard-errors)
+    // but the env-var path stays soft to preserve "set once in your shell"
+    // ergonomics across mixed-version invocations.
+    if (raw.trim().length > 0) {
+        logger.warn({ rawValue: raw, fallback: DEFAULT_WAL_CHECKPOINT_THRESHOLD }, `Ignoring invalid GITNEXUS_WAL_CHECKPOINT_THRESHOLD=${raw}; expected integer >= -1; falling back to default (${DEFAULT_WAL_CHECKPOINT_THRESHOLD}).`);
+    }
+    return DEFAULT_WAL_CHECKPOINT_THRESHOLD;
+};
 /** Matches WAL corruption errors from the LadybugDB engine. */
 const WAL_CORRUPTION_RE = /corrupt(ed)?\s+wal|invalid\s+wal\s+record|wal.*corrupt|checksum.*wal/i;
 export const WAL_RECOVERY_SUGGESTION = 'WAL corruption detected. Run `gitnexus analyze --force` to rebuild the index.';
@@ -51,6 +89,48 @@ export function isWalCorruptionError(err) {
     const msg = err instanceof Error ? err.message : String(err);
     return WAL_CORRUPTION_RE.test(msg);
 }
+// ─── Ladybug WAL checkpoint IO error matchers ───────────────────────────────
+//
+// Matched against LadybugDB v0.16.1 (see `gitnexus/package.json`
+// @ladybugdb/core). Strict regexes encode local_file_system.cpp wording
+// verified at that version. Two-tier strategy: strict matchers first so we
+// only fire on real checkpoint-rotation shapes; a permissive fallback
+// catches future Ladybug message drift so the recovery hint keeps surfacing
+// even if upstream wording changes.
+//
+// From Ladybug native LocalFileSystem exceptions (`local_file_system.cpp`),
+// surfaced in Node as:
+// "Runtime exception: IO exception: Error renaming file ..."
+// "Runtime exception: IO exception: Error removing directory or file ..."
+// We only match checkpoint-rotation shapes:
+//   - "<db>.wal -> <db>.wal.checkpoint" rename failures
+//   - "<db>.wal.checkpoint" remove failures
+// Example matches:
+//   "Runtime exception: IO exception: Error renaming file /x/lbug.wal to /x/lbug.wal.checkpoint. ErrorMessage: Permission denied"
+//   "Runtime exception: IO exception: Error removing directory or file /x/lbug.wal.checkpoint.  Error Message: Permission denied"
+// Matching is case-insensitive to remain robust across wrappers/platforms.
+const LBUG_CHECKPOINT_RENAME_RE = /^runtime exception: io exception:\s*error renaming file\s+.+?\.wal\s+to\s+.+?\.wal\.checkpoint(?:\.|\s|$)/i;
+const LBUG_CHECKPOINT_REMOVE_RE = /^runtime exception: io exception:\s*error removing directory or file\s+.+?\.wal\.checkpoint(?:\.|\s|$)/i;
+/**
+ * Permissive fallback: any IO-exception-shaped message that mentions a
+ * `.wal.checkpoint` path. Catches future Ladybug message drift (different
+ * verb, additional preamble, locale variation) so the recovery hint keeps
+ * surfacing even if the strict regexes go stale.
+ */
+const LBUG_CHECKPOINT_PERMISSIVE_RE = /io exception.*\.wal\.checkpoint/i;
+/**
+ * True when `err` looks like a Ladybug WAL-checkpoint rotation/remove IO
+ * failure. Tries strict matchers first (renames + removes), then falls
+ * back to the permissive matcher.
+ */
+export const isLbugCheckpointIoError = (err) => {
+    if (!err)
+        return false;
+    const msg = err instanceof Error ? err.message : String(err);
+    if (LBUG_CHECKPOINT_RENAME_RE.test(msg) || LBUG_CHECKPOINT_REMOVE_RE.test(msg))
+        return true;
+    return LBUG_CHECKPOINT_PERMISSIVE_RE.test(msg);
+};
 /**
  * Return true when the error message indicates that a LadybugDB file lock
  * could not be acquired — either at construction time
@@ -76,8 +156,8 @@ export function createLbugDatabase(lbugModule, databasePath, options = {}) {
     // .d.ts declares fewer args than the native constructor accepts.
     return new lbugModule.Database(databasePath, 0, // bufferManagerSize
     false, // enableCompression (pinned for v0.16.0)
-    options.readOnly ?? false, LBUG_MAX_DB_SIZE, true, // autoCheckpoint
-    -1, // checkpointThreshold
+    options.readOnly ?? false, LBUG_MAX_DB_SIZE, true, // autoCheckpoint (always on)
+    resolveCheckpointThreshold(), // checkpointThreshold (default 64 MiB; override with GITNEXUS_WAL_CHECKPOINT_THRESHOLD; -1 keeps Ladybug stock ~16 MiB)
     options.throwOnWalReplayFailure ?? true, true);
 }
 // ─── Lock-busy retry tuning knobs ───────────────────────────────────────────

package/dist/core/lbug/wal-checkpoint-driver.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Manual WAL checkpoint driver with bounded retry (#1741 follow-up).
+ *
+ * Background
+ * ----------
+ * LadybugDB's native auto-checkpoint runs from inside the C++ engine on a
+ * background path that has no JS-side hook for mid-write rotation. When
+ * the rename of `<db>.wal` → `<db>.wal.checkpoint` races a transient file
+ * lock (Windows Defender, AV scanner, NTFS shadow copy) the engine raises
+ * a `Runtime exception: IO exception: Error renaming file …` that aborts
+ * the in-flight write. There is no engine-level retry.
+ *
+ * The auto-checkpoint cannot be made retryable from JS, but a *manual*
+ * `CHECKPOINT` query that the JS layer issues itself CAN be wrapped in a
+ * bounded retry. By draining the WAL on a tight cadence — more often than
+ * the native threshold — the auto-checkpoint almost never has work left
+ * to do, so the un-retriable native rename race is moved into the
+ * JS-controlled path where this module's retry absorbs it.
+ *
+ * Design contract
+ * ---------------
+ * - `autoCheckpoint` stays on (maintainer requirement). This driver is
+ *   additive: it preempts the native checkpoint, it does not replace it.
+ * - The driver runs ONLY during analyze (callers opt-in explicitly). MCP
+ *   and other long-lived flows continue to rely on the close-time
+ *   CHECKPOINT in `safeClose`.
+ * - Opt-out is via `GITNEXUS_WAL_MANUAL_CHECKPOINT=0`. Default is on.
+ * - Retries only fire on `isLbugCheckpointIoError` — every other error
+ *   surfaces immediately. The retry budget is small (3 attempts) with
+ *   jittered backoff so a chronic rename failure escalates fast.
+ * - Retry attempts log at `debug`; only the final, exhausted failure
+ *   surfaces to the caller (and is logged at `warn` here for operators).
+ */
+/**
+ * Run a single CHECKPOINT with bounded retry on
+ * `isLbugCheckpointIoError`. Returns the number of attempts actually
+ * spent (1-`CHECKPOINT_RETRY_ATTEMPTS`) on success, or rethrows the last
+ * checkpoint error after exhausting the budget. Non-checkpoint errors
+ * (e.g. WAL corruption, lock-busy) propagate immediately on the first
+ * attempt — those are not what this retry is designed to absorb.
+ *
+ * The split from `flushWAL` is deliberate: `flushWAL` is the swallow-and-
+ * log helper used by `safeClose` and the server's best-effort flush,
+ * which by contract cannot fail the surrounding operation. The manual
+ * driver MUST observe failures to decide whether to retry, and that is
+ * the role of `tryFlushWAL`.
+ *
+ * Exported for direct unit testing — production callers use
+ * {@link startWalCheckpointDriver} or {@link checkpointOnce}.
+ */
+export declare const runCheckpointWithRetry: (options?: {
+    /** Override the sleep implementation for tests. */
+    sleepFn?: (ms: number) => Promise<void>;
+    /** Override the CHECKPOINT call for tests. */
+    checkpointFn?: () => Promise<boolean>;
+    /** Override the jitter source for tests. Returns a value in [0, 1). */
+    randomFn?: () => number;
+}) => Promise<{
+    attempts: number;
+    flushed: boolean;
+}>;
+/**
+ * Single-shot manual checkpoint. Use this when the caller drives the
+ * cadence itself (e.g. a phase boundary in `runFullAnalysis`).
+ *
+ * Honors the `GITNEXUS_WAL_MANUAL_CHECKPOINT=0` opt-out so operators can
+ * disable the manual path if it ever interacts badly with a future
+ * Ladybug release.
+ */
+export declare const checkpointOnce: () => Promise<void>;
+/**
+ * Start a periodic manual checkpoint driver. The returned handle has a
+ * `stop()` method that resolves once the in-flight checkpoint (if any)
+ * settles, so callers can `await driver.stop()` before close-time
+ * `safeClose` and avoid racing the final flush.
+ *
+ * The first checkpoint fires after `periodMs` (not immediately) so a
+ * cold analyze does not pay a CHECKPOINT round trip before any writes
+ * have happened.
+ */
+export interface WalCheckpointDriver {
+    /** Stop the driver and await any in-flight checkpoint. Idempotent. */
+    stop(): Promise<void>;
+}
+export declare const startWalCheckpointDriver: (options?: {
+    periodMs?: number;
+}) => WalCheckpointDriver;
+/**
+ * Reading `GITNEXUS_WAL_MANUAL_CHECKPOINT` at every call site (rather
+ * than caching at module load) keeps `analyzeCommand` env restoration
+ * honest: tests that toggle the flag between invocations see the live
+ * value, matching the `ANALYZE_CLI_ENV_KEYS` snapshot/restore contract
+ * in `analyze.ts`.
+ *
+ * Accepted opt-out values: '0', 'false', 'off', 'no' (case-insensitive).
+ * Anything else — including undefined — leaves the driver enabled.
+ */
+export declare const isManualCheckpointEnabled: () => boolean;

package/dist/core/lbug/wal-checkpoint-driver.js

@@ -0,0 +1,189 @@
+/**
+ * Manual WAL checkpoint driver with bounded retry (#1741 follow-up).
+ *
+ * Background
+ * ----------
+ * LadybugDB's native auto-checkpoint runs from inside the C++ engine on a
+ * background path that has no JS-side hook for mid-write rotation. When
+ * the rename of `<db>.wal` → `<db>.wal.checkpoint` races a transient file
+ * lock (Windows Defender, AV scanner, NTFS shadow copy) the engine raises
+ * a `Runtime exception: IO exception: Error renaming file …` that aborts
+ * the in-flight write. There is no engine-level retry.
+ *
+ * The auto-checkpoint cannot be made retryable from JS, but a *manual*
+ * `CHECKPOINT` query that the JS layer issues itself CAN be wrapped in a
+ * bounded retry. By draining the WAL on a tight cadence — more often than
+ * the native threshold — the auto-checkpoint almost never has work left
+ * to do, so the un-retriable native rename race is moved into the
+ * JS-controlled path where this module's retry absorbs it.
+ *
+ * Design contract
+ * ---------------
+ * - `autoCheckpoint` stays on (maintainer requirement). This driver is
+ *   additive: it preempts the native checkpoint, it does not replace it.
+ * - The driver runs ONLY during analyze (callers opt-in explicitly). MCP
+ *   and other long-lived flows continue to rely on the close-time
+ *   CHECKPOINT in `safeClose`.
+ * - Opt-out is via `GITNEXUS_WAL_MANUAL_CHECKPOINT=0`. Default is on.
+ * - Retries only fire on `isLbugCheckpointIoError` — every other error
+ *   surfaces immediately. The retry budget is small (3 attempts) with
+ *   jittered backoff so a chronic rename failure escalates fast.
+ * - Retry attempts log at `debug`; only the final, exhausted failure
+ *   surfaces to the caller (and is logged at `warn` here for operators).
+ */
+import { logger } from '../logger.js';
+import { tryFlushWAL } from './lbug-adapter.js';
+import { isLbugCheckpointIoError } from './lbug-config.js';
+/**
+ * Bounded retry budget. Total worst-case wall time is dominated by the
+ * three sleeps below (~750 ms before jitter) plus three CHECKPOINT round
+ * trips — small enough to stay invisible during a large analyze, large
+ * enough to ride out a single AV scanner sweep on Windows.
+ */
+const CHECKPOINT_RETRY_ATTEMPTS = 3;
+/**
+ * Base back-off in ms. Each attempt waits `BASE_DELAYS[attempt-1]`
+ * milliseconds before the next try, plus a small jitter to avoid
+ * synchronized retries when multiple analyzers ever share a host.
+ */
+const BASE_DELAYS_MS = [50, 200, 500];
+/** Maximum jitter added on top of each base delay. */
+const JITTER_MAX_MS = 50;
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/**
+ * Run a single CHECKPOINT with bounded retry on
+ * `isLbugCheckpointIoError`. Returns the number of attempts actually
+ * spent (1-`CHECKPOINT_RETRY_ATTEMPTS`) on success, or rethrows the last
+ * checkpoint error after exhausting the budget. Non-checkpoint errors
+ * (e.g. WAL corruption, lock-busy) propagate immediately on the first
+ * attempt — those are not what this retry is designed to absorb.
+ *
+ * The split from `flushWAL` is deliberate: `flushWAL` is the swallow-and-
+ * log helper used by `safeClose` and the server's best-effort flush,
+ * which by contract cannot fail the surrounding operation. The manual
+ * driver MUST observe failures to decide whether to retry, and that is
+ * the role of `tryFlushWAL`.
+ *
+ * Exported for direct unit testing — production callers use
+ * {@link startWalCheckpointDriver} or {@link checkpointOnce}.
+ */
+export const runCheckpointWithRetry = async (options = {}) => {
+    const sleepImpl = options.sleepFn ?? sleep;
+    const checkpointImpl = options.checkpointFn ?? tryFlushWAL;
+    const randomImpl = options.randomFn ?? Math.random;
+    let lastError;
+    for (let attempt = 1; attempt <= CHECKPOINT_RETRY_ATTEMPTS; attempt++) {
+        try {
+            const flushed = await checkpointImpl();
+            return { attempts: attempt, flushed };
+        }
+        catch (err) {
+            lastError = err;
+            if (!isLbugCheckpointIoError(err)) {
+                // Non-checkpoint error — propagate immediately. Examples:
+                // WAL corruption, missing connection, query syntax failure.
+                // Retrying these would only mask the real signal.
+                throw err;
+            }
+            if (attempt === CHECKPOINT_RETRY_ATTEMPTS)
+                break;
+            const base = BASE_DELAYS_MS[Math.min(attempt - 1, BASE_DELAYS_MS.length - 1)] ?? 500;
+            // randomImpl defaults to Math.random — non-cryptographic by design; jitter only avoids
+            // synchronized retries between concurrent analyzers.
+            const delayMs = base + Math.floor(randomImpl() * JITTER_MAX_MS);
+            logger.debug({ attempt, totalAttempts: CHECKPOINT_RETRY_ATTEMPTS, delayMs }, 'GitNexus: WAL checkpoint IO error — retrying');
+            await sleepImpl(delayMs);
+        }
+    }
+    logger.warn({ attempts: CHECKPOINT_RETRY_ATTEMPTS }, 'GitNexus: manual WAL checkpoint exhausted retry budget — surfacing IO error to caller');
+    throw lastError;
+};
+/**
+ * Single-shot manual checkpoint. Use this when the caller drives the
+ * cadence itself (e.g. a phase boundary in `runFullAnalysis`).
+ *
+ * Honors the `GITNEXUS_WAL_MANUAL_CHECKPOINT=0` opt-out so operators can
+ * disable the manual path if it ever interacts badly with a future
+ * Ladybug release.
+ */
+export const checkpointOnce = async () => {
+    if (!isManualCheckpointEnabled())
+        return;
+    await runCheckpointWithRetry();
+};
+/** Default cadence (ms) for the periodic driver. */
+const DEFAULT_PERIOD_MS = 5_000;
+export const startWalCheckpointDriver = (options = {}) => {
+    if (!isManualCheckpointEnabled()) {
+        return { stop: async () => undefined };
+    }
+    const periodMs = options.periodMs ?? DEFAULT_PERIOD_MS;
+    let stopped = false;
+    let inflight = null;
+    const tick = async () => {
+        if (stopped)
+            return;
+        inflight = runCheckpointWithRetry()
+            .then(() => undefined)
+            .catch((err) => {
+            // The retry budget exhausted. The caller's surrounding write
+            // will see the same engine error on its next operation and the
+            // `analyzeCommand` catch block will emit the recovery hint.
+            // Logging here keeps the operator-visible trail without
+            // double-logging the user-facing message.
+            logger.warn({ err: err instanceof Error ? err.message : String(err) }, 'GitNexus: manual WAL checkpoint failed after retries');
+        });
+        try {
+            await inflight;
+        }
+        finally {
+            inflight = null;
+        }
+    };
+    const handle = setInterval(() => {
+        // Fire-and-forget: setInterval cannot await directly. The next tick
+        // is guarded by `stopped` and the `inflight` reference.
+        void tick();
+    }, periodMs);
+    // `setInterval` returned by Node is a `Timeout` object with `.unref()`
+    // so a hung driver never prevents process exit.
+    if (typeof handle.unref === 'function') {
+        handle.unref();
+    }
+    return {
+        stop: async () => {
+            if (stopped) {
+                if (inflight)
+                    await inflight;
+                return;
+            }
+            stopped = true;
+            clearInterval(handle);
+            if (inflight) {
+                try {
+                    await inflight;
+                }
+                catch {
+                    /* swallowed in tick() — surface path is the surrounding write */
+                }
+            }
+        },
+    };
+};
+/**
+ * Reading `GITNEXUS_WAL_MANUAL_CHECKPOINT` at every call site (rather
+ * than caching at module load) keeps `analyzeCommand` env restoration
+ * honest: tests that toggle the flag between invocations see the live
+ * value, matching the `ANALYZE_CLI_ENV_KEYS` snapshot/restore contract
+ * in `analyze.ts`.
+ *
+ * Accepted opt-out values: '0', 'false', 'off', 'no' (case-insensitive).
+ * Anything else — including undefined — leaves the driver enabled.
+ */
+export const isManualCheckpointEnabled = () => {
+    const raw = process.env.GITNEXUS_WAL_MANUAL_CHECKPOINT;
+    if (raw === undefined)
+        return true;
+    const normalized = raw.trim().toLowerCase();
+    return !['0', 'false', 'off', 'no'].includes(normalized);
+};

package/dist/core/run-analyze.js

@@ -14,6 +14,7 @@ import { execFileSync } from 'child_process';
 import { runPipelineFromRepo } from './ingestion/pipeline.js';
 import { initLbug, loadGraphToLbug, getLbugStats, executeQuery, executeWithReusedStatement, closeLbug, loadCachedEmbeddings, deleteNodesForFile, deleteAllCommunitiesAndProcesses, queryImporters, } from './lbug/lbug-adapter.js';
 import { createSearchFTSIndexes, verifySearchFTSIndexes } from './search/fts-indexes.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';
 import { extractChangedSubgraph, computeEffectiveWriteSet, } from './incremental/subgraph-extract.js';
@@ -343,6 +344,15 @@ export async function runFullAnalysis(repoPath, options, callbacks) {
         }
     }
     await initLbug(lbugPath);
+    // Manual WAL checkpoint driver (#1741): periodically drain the WAL
+    // from JS so the un-retriable native auto-checkpoint almost never
+    // has work left to do. Failures of the manual CHECKPOINT are absorbed
+    // by the driver's bounded retry; the final un-recoverable error still
+    // surfaces via the surrounding write that follows the failed flush.
+    // Opt-out via `GITNEXUS_WAL_MANUAL_CHECKPOINT=0` (the driver itself
+    // returns a no-op handle when disabled). Analyze-only: MCP and serve
+    // paths continue to rely on the close-time CHECKPOINT in `safeClose`.
+    const walCheckpointDriver = startWalCheckpointDriver();
     try {
         // All work after initLbug is wrapped in try/finally to ensure closeLbug()
         // is called even if an error occurs — the module-level singleton DB handle
@@ -726,6 +736,9 @@ export async function runFullAnalysis(repoPath, options, callbacks) {
             // Best-effort — don't fail the entire analysis for context file issues
         }
         // ── Close LadybugDB ──────────────────────────────────────────────
+        // Stop the manual checkpoint driver before closeLbug so its
+        // in-flight CHECKPOINT cannot race the `safeClose` CHECKPOINT.
+        await walCheckpointDriver.stop();
         await closeLbug();
         progress('done', 100, 'Done');
         return {
@@ -736,7 +749,14 @@ export async function runFullAnalysis(repoPath, options, callbacks) {
         };
     }
     catch (err) {
-        // Ensure LadybugDB is closed even on error
+        // Ensure LadybugDB is closed even on error. Stop the driver first
+        // so its retry loop cannot extend an already-failing analyze.
+        try {
+            await walCheckpointDriver.stop();
+        }
+        catch {
+            /* swallow — surface path is the rethrow below */
+        }
         try {
             await closeLbug();
         }

package/package.json

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