gitnexus 1.6.8 → 1.6.9-rc.2

package/dist/cli/analyze.js

@@ -12,7 +12,8 @@ import os from 'os';
 import { spawn } from 'child_process';
 import v8 from 'v8';
 import cliProgress from 'cli-progress';
-import { closeLbug } from '../core/lbug/lbug-adapter.js';
+import { isLbugReady } from '../core/lbug/lbug-adapter.js';
+import { boundedCheckpointBeforeExit } from '../core/lbug/shutdown-helpers.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, getDefaultBranch } from '../storage/git.js';
@@ -508,6 +509,17 @@ export const analyzeCommand = async (inputPath, options) => {
     finally {
         restoreAnalyzeEnv(envSnap);
     }
+    // If analyzeCommandImpl returned via a soft `process.exitCode = 1` error path
+    // while LadybugDB native handles are still open, the event loop won't drain and
+    // the process would HANG (#2264 review P1). The full analyze paths skip-close the
+    // DB — handles are left open and reclaimed by process.exit — so a soft return
+    // after a real analyze must force the exit. The success path never reaches here
+    // (analyzeCommandImpl calls process.exit(0) itself); early-validation errors and
+    // unit tests that mock runFullAnalysis never open the DB, so isLbugReady() is
+    // false and the soft return is preserved.
+    if (isLbugReady()) {
+        process.exit(typeof process.exitCode === 'number' ? process.exitCode : 1);
+    }
 };
 const analyzeCommandImpl = async (inputPath, cliOptions) => {
     console.log('\n  GitNexus Analyzer\n');
@@ -867,12 +879,17 @@ const analyzeCommandImpl = async (inputPath, cliOptions) => {
         aborted = true;
         bar.stop();
         console.log('\n  Interrupted — cleaning up...');
-        closeLbug()
-            .catch(() => { })
-            .finally(async () => {
-            const { flushLoggerSync } = await import('../core/logger.js');
-            flushLoggerSync();
-            process.exit(130);
+        // Bounded CHECKPOINT-then-exit (#2264 review P3): skip the native close (the
+        // LadybugDB destructor can double-free after --pdg writes), but don't hang
+        // behind a long --pdg COPY holding the connection lock — bound it so a single
+        // Ctrl-C stays responsive; the WAL replays on the next analyze. A second
+        // Ctrl-C (`if (aborted) process.exit(1)` above) remains the escape hatch.
+        void boundedCheckpointBeforeExit({
+            exitCode: 130,
+            beforeExit: async () => {
+                const { flushLoggerSync } = await import('../core/logger.js');
+                flushLoggerSync();
+            },
         });
     };
     process.on('SIGINT', sigintHandler);
@@ -964,6 +981,12 @@ const analyzeCommandImpl = async (inputPath, cliOptions) => {
             // Extra fetch-wrapper names from `.gitnexusrc` (#1589/#1852 residual);
             // forwarded to the routes phase consumer scan.
             fetchWrappers: options.fetchWrappers,
+            // The CLI always process.exit()s after this returns (success path at the
+            // end of analyzeCommandImpl, error/interrupt paths via process.exit too),
+            // so the finalize close skips the native conn/db close — it can double-free
+            // in LadybugDB's ClientContext destructor after --pdg writes (#2264). The
+            // CHECKPOINT keeps the index durable; process exit reclaims the handles.
+            skipNativeCloseOnExit: true,
         }, {
             onProgress: (_phase, percent, message) => {
                 updateBar(percent, message);

package/dist/core/ingestion/cfg/visitors/python-harvest.d.ts

@@ -109,10 +109,10 @@ export declare class PythonHarvester {
     /** >0 while walking a conditionally-evaluated subexpression — defs become may-defs. */
     private conditionalDepth;
     /**
-     * `call` node id → binding indices its single-target result is assigned to
-     * (`x = f()` ⇒ `[x]`). Populated just before the value walk reaches the call
-     * (see {@link registerResultDefs}) and consumed by {@link visitCall}. Mirrors
-     * the Go harvester's `resultDefTargets`.
+     * `call` node id → binding indices its result is assigned to (`x = f()` ⇒
+     * `[x]`, `a, b = f()` ⇒ `[a, b]`). Populated just before the value walk reaches
+     * the call (see {@link registerResultDefs}) and consumed by {@link visitCall}.
+     * Mirrors the Go harvester's `resultDefTargets`.
      */
     private readonly resultDefTargets;
     constructor(fnNode: SyntaxNode);
@@ -184,13 +184,9 @@ export declare class PythonHarvester {
      * (it reads outer names), the body/filter after the targets are bound.
      */
     private walkComprehension;
-    /**
-     * When `value`'s root (after stripping parens) is a `call`, remember that
-     * call site should carry `resultDefs` — the binding indices of `targets`
-     * (def-position identifiers). Consumed by {@link visitCall} once the value
-     * walk reaches the node. Single-target only (the caller restricts to a plain
-     * identifier LHS); the blank identifier (`_`) binds nothing and is skipped.
-     */
+    /** Binding indices assigned by a target pattern, without mutating statement facts. */
+    private targetDefIndices;
+    /** Record result defs for a call-valued assignment. */
     private registerResultDefs;
     /** Strip `parenthesized_expression` wrappers around a value (`(f())`). */
     private unwrapValue;
@@ -201,6 +197,8 @@ export declare class PythonHarvester {
      * Python has no `new` — every site is `kind: 'call'`.
      */
     private visitCall;
+    /** Walk arguments, assigning only positional values to positional sink slots. */
+    private walkArgs;
     /**
      * `attribute` chain walk shared by value position and callee position. Records
      * the chain-root identifier as a use (identical to the old default descent)

package/dist/core/ingestion/cfg/visitors/python-harvest.js

@@ -15,10 +15,10 @@ export class PythonHarvester {
     /** >0 while walking a conditionally-evaluated subexpression — defs become may-defs. */
     conditionalDepth = 0;
     /**
-     * `call` node id → binding indices its single-target result is assigned to
-     * (`x = f()` ⇒ `[x]`). Populated just before the value walk reaches the call
-     * (see {@link registerResultDefs}) and consumed by {@link visitCall}. Mirrors
-     * the Go harvester's `resultDefTargets`.
+     * `call` node id → binding indices its result is assigned to (`x = f()` ⇒
+     * `[x]`, `a, b = f()` ⇒ `[a, b]`). Populated just before the value walk reaches
+     * the call (see {@link registerResultDefs}) and consumed by {@link visitCall}.
+     * Mirrors the Go harvester's `resultDefTargets`.
      */
     resultDefTargets = new Map();
     constructor(fnNode) {
@@ -124,8 +124,20 @@ export class PythonHarvester {
      */
     prescan(node) {
         const t = node.type;
-        if (NESTED_FUNCTION_TYPES.has(t) && node.id !== this.fnId)
+        if (NESTED_FUNCTION_TYPES.has(t) && node.id !== this.fnId) {
+            if (t === 'function_definition') {
+                const name = node.childForFieldName('name');
+                if (name?.type === 'identifier')
+                    this.declare(name, 'function');
+            }
             return;
+        }
+        if (t === 'class_definition') {
+            const name = node.childForFieldName('name');
+            if (name?.type === 'identifier')
+                this.declare(name, 'class');
+            return;
+        }
         switch (t) {
             case 'global_statement':
             case 'nonlocal_statement': {
@@ -469,10 +481,10 @@ export class PythonHarvester {
                 const left = node.childForFieldName('left');
                 const right = node.childForFieldName('right');
                 // Register result-defs BEFORE walking the value so the nested call site
-                // (reached during the value walk) carries them — single identifier
-                // target only (`x = f()`); a tuple/attribute LHS attaches nothing.
-                if (left?.type === 'identifier' && right)
-                    this.registerResultDefs(right, [left]);
+                // (reached during the value walk) carries them. Plain and unpack targets
+                // are preserved; attribute/subscript LHS attaches nothing.
+                if (left && right)
+                    this.registerResultDefs(right, this.targetDefIndices(left));
                 if (right)
                     this.walkValue(right, acc);
                 if (left)
@@ -500,8 +512,9 @@ export class PythonHarvester {
                 // walrus `(n := v)` — `n` is a def, `v` a use.
                 const name = node.childForFieldName('name');
                 const value = node.childForFieldName('value');
-                if (name?.type === 'identifier' && value)
-                    this.registerResultDefs(value, [name]);
+                if (name?.type === 'identifier' && value) {
+                    this.registerResultDefs(value, this.targetDefIndices(name));
+                }
                 if (value)
                     this.walkValue(value, acc);
                 if (name?.type === 'identifier')
@@ -607,27 +620,34 @@ export class PythonHarvester {
         if (body)
             this.walkValue(body, acc);
     }
-    // ── taint-site harvest (#2227 follow-up) ─────────────────────────────────
-    /**
-     * When `value`'s root (after stripping parens) is a `call`, remember that
-     * call site should carry `resultDefs` — the binding indices of `targets`
-     * (def-position identifiers). Consumed by {@link visitCall} once the value
-     * walk reaches the node. Single-target only (the caller restricts to a plain
-     * identifier LHS); the blank identifier (`_`) binds nothing and is skipped.
-     */
-    registerResultDefs(value, targets) {
-        const root = this.unwrapValue(value);
-        if (root.type !== 'call')
-            return;
-        const defs = [];
-        for (const target of targets) {
-            if (target.type !== 'identifier' || target.text === '_')
-                continue;
-            defs.push(this.resolve(target));
+    /** Binding indices assigned by a target pattern, without mutating statement facts. */
+    targetDefIndices(target) {
+        if (target.type === 'identifier')
+            return target.text === '_' ? [] : [this.resolve(target)];
+        if (PATTERN_LIST_TYPES.has(target.type)) {
+            const out = [];
+            for (let i = 0; i < target.namedChildCount; i++) {
+                const c = target.namedChild(i);
+                if (c)
+                    out.push(...this.targetDefIndices(c));
+            }
+            return out;
         }
-        if (defs.length > 0)
-            this.resultDefTargets.set(root.id, defs);
+        if (target.type === 'list_splat_pattern') {
+            const id = target.namedChild(0);
+            return id ? this.targetDefIndices(id) : [];
+        }
+        return [];
+    }
+    /** Record result defs for a call-valued assignment. */
+    registerResultDefs(value, defs) {
+        if (defs.length === 0)
+            return;
+        const root = this.unwrapValue(value);
+        if (root.type === 'call')
+            this.resultDefTargets.set(root.id, [...defs]);
     }
+    // ── taint-site harvest (#2227 follow-up) ─────────────────────────────────
     /** Strip `parenthesized_expression` wrappers around a value (`(f())`). */
     unwrapValue(node) {
         let n = node;
@@ -681,31 +701,44 @@ export class PythonHarvester {
         const resultDefs = this.resultDefTargets.get(node.id);
         if (resultDefs !== undefined)
             acc.setSiteResultDefs(siteIdx, resultDefs);
-        if (argsNode) {
-            let pos = 0;
-            for (let i = 0; i < argsNode.namedChildCount; i++) {
-                const arg = argsNode.namedChild(i);
-                if (!arg || arg.type === 'comment')
-                    continue;
-                if (arg.type === 'list_splat' || arg.type === 'dictionary_splat') {
-                    // `f(*args)` / `f(**kw)` — a spread. Mark the first spread position so
-                    // the matcher degrades soundly; the inner value still walks.
-                    acc.setFrameArg(pos);
-                    acc.setSiteSpread(siteIdx, pos);
-                    const inner = arg.namedChild(0);
-                    if (inner)
-                        this.walkValue(inner, acc);
-                }
-                else {
-                    // Positional or `keyword_argument` — the `keyword_argument` case in
-                    // `walkValue` walks only its `value`, so the key name is not a use.
-                    acc.setFrameArg(pos);
-                    this.walkValue(arg, acc);
-                }
+        this.walkArgs(argsNode, acc, siteIdx);
+        acc.popFrame();
+    }
+    /** Walk arguments, assigning only positional values to positional sink slots. */
+    walkArgs(args, acc, siteIdx) {
+        if (!args)
+            return;
+        let pos = 0;
+        for (let i = 0; i < args.namedChildCount; i++) {
+            const arg = args.namedChild(i);
+            if (!arg || arg.type === 'comment')
+                continue;
+            if (arg.type === 'keyword_argument') {
+                const value = arg.childForFieldName('value');
+                // SiteRecord has no keyword-name metadata. Keep the value's ordinary
+                // uses/sources, but do not guess a positional sink slot from source order.
+                if (value)
+                    acc.suppressOccurrences(() => this.walkValue(value, acc));
+            }
+            else if (arg.type === 'list_splat') {
+                acc.setFrameArg(pos);
+                acc.setSiteSpread(siteIdx, pos);
+                const inner = arg.namedChild(0);
+                if (inner)
+                    this.walkValue(inner, acc);
+                pos++;
+            }
+            else if (arg.type === 'dictionary_splat') {
+                const inner = arg.namedChild(0);
+                if (inner)
+                    acc.suppressOccurrences(() => this.walkValue(inner, acc));
+            }
+            else {
+                acc.setFrameArg(pos);
+                this.walkValue(arg, acc);
                 pos++;
             }
         }
-        acc.popFrame();
     }
     /**
      * `attribute` chain walk shared by value position and callee position. Records

package/dist/core/ingestion/scope-resolution/pipeline/run.js

@@ -520,11 +520,11 @@ export function runScopeResolution(input, provider) {
         // ── M3 taint setup (#2083 U4) ────────────────────────────────────────
         // Explicit model-registration seam (idempotent, cheap) — the registry
         // stays empty on non-pdg runs, preserving default-run parity. The
-        // registry is keyed by `SupportedLanguages` enum VALUES ('typescript' /
-        // 'javascript'), and `ScopeResolver.language` IS a `SupportedLanguages`
-        // member registered under those same constants — the join is direct
-        // equality, no mapping table. A language without a registered spec
-        // (python, go, …) skips taint entirely: no work, no warn spam (KTD8).
+        // registry is keyed by SupportedLanguages enum values, and
+        // ScopeResolver.language is registered under those same constants -
+        // the join is direct equality, with no mapping table. A language without a
+        // registered spec (go, ruby, ...) skips taint entirely: no work, no warn spam
+        // (KTD8).
         registerBuiltinTaintModels();
         const taintSpec = getSourceSinkConfig(provider.language);
         // Taint-side solver fact cap: the SAME derivation emitFileReachingDefs

package/dist/core/ingestion/taint/python-model.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Built-in Python taint model (#2204 first slice).
+ *
+ * Keep the model intentionally conservative: import-aware sinks for standard
+ * library command execution, receiver-conventional database execution calls,
+ * and Flask/FastAPI-style request-object member reads. No sanitizers are
+ * registered yet because a false sanitizer kill can hide a real finding.
+ */
+import type { SourceSinkSanitizerSpec } from './source-sink-config.js';
+export declare const PYTHON_TAINT_MODEL: SourceSinkSanitizerSpec;

package/dist/core/ingestion/taint/python-model.js

@@ -0,0 +1,43 @@
+/**
+ * Built-in Python taint model (#2204 first slice).
+ *
+ * Keep the model intentionally conservative: import-aware sinks for standard
+ * library command execution, receiver-conventional database execution calls,
+ * and Flask/FastAPI-style request-object member reads. No sanitizers are
+ * registered yet because a false sanitizer kill can hide a real finding.
+ */
+export const PYTHON_TAINT_MODEL = {
+    sources: [
+        {
+            kind: 'remote-input',
+            objects: ['request', 'req'],
+            properties: [
+                'args',
+                'form',
+                'json',
+                'data',
+                'headers',
+                'cookies',
+                'path_params',
+                'query_params',
+            ],
+        },
+    ],
+    sinks: [
+        { name: 'system', kind: 'command-injection', args: [0], module: 'os' },
+        { name: 'popen', kind: 'command-injection', args: [0], module: 'os' },
+        { name: 'call', kind: 'command-injection', args: [0], module: 'subprocess' },
+        { name: 'run', kind: 'command-injection', args: [0], module: 'subprocess' },
+        { name: 'Popen', kind: 'command-injection', args: [0], module: 'subprocess' },
+        { name: 'check_call', kind: 'command-injection', args: [0], module: 'subprocess' },
+        { name: 'check_output', kind: 'command-injection', args: [0], module: 'subprocess' },
+        { name: 'eval', kind: 'code-injection', args: [0], global: true },
+        { name: 'exec', kind: 'code-injection', args: [0], global: true },
+        { name: 'open', kind: 'path-traversal', args: [0], global: true },
+        { name: 'query', kind: 'sql-injection', args: [0], anyReceiver: true },
+        { name: 'execute', kind: 'sql-injection', args: [0], anyReceiver: true },
+        { name: 'executemany', kind: 'sql-injection', args: [0], anyReceiver: true },
+        { name: 'executescript', kind: 'sql-injection', args: [0], anyReceiver: true },
+    ],
+    sanitizers: [],
+};

package/dist/core/ingestion/taint/typescript-model.d.ts

@@ -27,12 +27,20 @@ export declare const TS_JS_TAINT_MODEL: SourceSinkSanitizerSpec;
  * array order is semantic (entry identity) and intentionally preserved.
  */
 export declare function computeTaintModelVersion(spec: SourceSinkSanitizerSpec): string;
-/** Version stamp of the built-in TS/JS model (joins the RepoMeta pdg key in U5). */
+export declare const BUILTIN_TAINT_MODELS: {
+    readonly javascript: SourceSinkSanitizerSpec;
+    readonly python: SourceSinkSanitizerSpec;
+    readonly typescript: SourceSinkSanitizerSpec;
+};
+/**
+ * Version stamp of every built-in model (joins the RepoMeta pdg key in U5).
+ * Adding a language model must invalidate existing persisted taint findings.
+ */
 export declare const taintModelVersion: string;
 /**
- * Register the built-in model for TypeScript and JavaScript. Explicit init
- * seam for the U4 emit path (call before the pdg window consumes the
- * registry); idempotent. Vue and other TS-adjacent language ids are
- * deliberately NOT registered — the M3 scope is TS/JS only.
+ * Register the built-in models for TypeScript, JavaScript, and Python.
+ * Explicit init seam for the U4 emit path (call before the pdg window
+ * consumes the registry); idempotent. Other language ids remain unregistered
+ * until they have a dedicated model.
  */
 export declare function registerBuiltinTaintModels(): void;

package/dist/core/ingestion/taint/typescript-model.js

@@ -16,6 +16,7 @@
  */
 import { createHash } from 'node:crypto';
 import { SupportedLanguages } from '../../../_shared/index.js';
+import { PYTHON_TAINT_MODEL } from './python-model.js';
 import { registerSourceSinkConfig } from './source-sink-registry.js';
 /**
  * The built-in TS/JS model. Module provenance uses bare specifier names —
@@ -74,7 +75,10 @@ export const TS_JS_TAINT_MODEL = {
  * array order is semantic (entry identity) and intentionally preserved.
  */
 export function computeTaintModelVersion(spec) {
-    return createHash('sha256').update(canonicalJson(spec)).digest('hex').slice(0, 12);
+    return computeModelDigest(spec);
+}
+function computeModelDigest(value) {
+    return createHash('sha256').update(canonicalJson(value)).digest('hex').slice(0, 12);
 }
 function canonicalJson(value) {
     if (Array.isArray(value))
@@ -88,15 +92,24 @@ function canonicalJson(value) {
     }
     return JSON.stringify(value);
 }
-/** Version stamp of the built-in TS/JS model (joins the RepoMeta pdg key in U5). */
-export const taintModelVersion = computeTaintModelVersion(TS_JS_TAINT_MODEL);
+export const BUILTIN_TAINT_MODELS = {
+    [SupportedLanguages.JavaScript]: TS_JS_TAINT_MODEL,
+    [SupportedLanguages.Python]: PYTHON_TAINT_MODEL,
+    [SupportedLanguages.TypeScript]: TS_JS_TAINT_MODEL,
+};
+/**
+ * Version stamp of every built-in model (joins the RepoMeta pdg key in U5).
+ * Adding a language model must invalidate existing persisted taint findings.
+ */
+export const taintModelVersion = computeModelDigest(BUILTIN_TAINT_MODELS);
 /**
- * Register the built-in model for TypeScript and JavaScript. Explicit init
- * seam for the U4 emit path (call before the pdg window consumes the
- * registry); idempotent. Vue and other TS-adjacent language ids are
- * deliberately NOT registered — the M3 scope is TS/JS only.
+ * Register the built-in models for TypeScript, JavaScript, and Python.
+ * Explicit init seam for the U4 emit path (call before the pdg window
+ * consumes the registry); idempotent. Other language ids remain unregistered
+ * until they have a dedicated model.
  */
 export function registerBuiltinTaintModels() {
     registerSourceSinkConfig(SupportedLanguages.TypeScript, TS_JS_TAINT_MODEL);
     registerSourceSinkConfig(SupportedLanguages.JavaScript, TS_JS_TAINT_MODEL);
+    registerSourceSinkConfig(SupportedLanguages.Python, PYTHON_TAINT_MODEL);
 }

package/dist/core/ingestion/workers/parse-worker.js

@@ -583,8 +583,11 @@ const processBatch = (files, onProgress) => {
                     setLanguage(language, regularFiles[0].path);
                     processFileGroup(regularFiles, language, queryString, result, onFileProcessed);
                 }
-                catch {
-                    // parser unavailable — skip this language group
+                catch (err) {
+                    // A throw here drops the whole language group — surface it to the pool
+                    // (#2264) instead of silently skipping. The old empty catch hid real
+                    // extractor/parser failures, not just an unavailable grammar.
+                    reportWarning(`Skipped ${regularFiles.length} ${language} file(s) after a processing error: ${err instanceof Error ? err.message : String(err)}`);
                 }
             }
             else {
@@ -599,8 +602,10 @@ const processBatch = (files, onProgress) => {
                     setLanguage(language, tsxFiles[0].path);
                     processFileGroup(tsxFiles, language, queryString, result, onFileProcessed);
                 }
-                catch {
-                    // parser unavailable — skip this language group
+                catch (err) {
+                    // See above — surface a tsx-group processing failure rather than
+                    // silently dropping every file in it (#2264).
+                    reportWarning(`Skipped ${tsxFiles.length} ${language} (tsx) file(s) after a processing error: ${err instanceof Error ? err.message : String(err)}`);
                 }
             }
             else {
@@ -745,6 +750,23 @@ export function extractORMQueries(filePath, content, out) {
 // per file; this module does not re-export it. Downstream consumers
 // import the function and its types directly from `route-extractors/`.
 import { extractFastAPIRouterBindings } from '../route-extractors/fastapi-router-bindings.js';
+/**
+ * Report a non-fatal worker issue to the pool over IPC so a caught error is not
+ * invisible to the operator (#2264). The pool logs it on the main thread AND
+ * resets the worker idle timer (so a worker grinding through failing files isn't
+ * falsely idle-evicted). Falls back to the local logger when there's no parent —
+ * this code also runs on the main thread in tests / the non-worker path. Fatal,
+ * group-aborting errors go through the message handler's
+ * `{ type: 'error', errorStack }` channel instead.
+ */
+function reportWarning(message) {
+    if (parentPort) {
+        parentPort.postMessage({ type: 'warning', message });
+    }
+    else {
+        logger.warn(message);
+    }
+}
 const processFileGroup = (files, language, queryString, result, onFileProcessed) => {
     let query;
     try {
@@ -752,13 +774,7 @@ const processFileGroup = (files, language, queryString, result, onFileProcessed)
         query = new Parser.Query(lang, queryString);
     }
     catch (err) {
-        const message = `Query compilation failed for ${language}: ${err instanceof Error ? err.message : String(err)}`;
-        if (parentPort) {
-            parentPort.postMessage({ type: 'warning', message });
-        }
-        else {
-            logger.warn(message);
-        }
+        reportWarning(`Query compilation failed for ${language}: ${err instanceof Error ? err.message : String(err)}`);
         return;
     }
     for (const file of files) {
@@ -799,7 +815,7 @@ const processFileGroup = (files, language, queryString, result, onFileProcessed)
             });
         }
         catch (err) {
-            logger.warn(`Failed to parse file ${file.path}: ${err instanceof Error ? err.message : String(err)}`);
+            reportWarning(`Failed to parse file ${file.path}: ${err instanceof Error ? err.message : String(err)}`);
             continue;
         }
         result.fileCount++;
@@ -809,7 +825,7 @@ const processFileGroup = (files, language, queryString, result, onFileProcessed)
             matches = query.matches(tree.rootNode);
         }
         catch (err) {
-            logger.warn(`Query execution failed for ${file.path}: ${err instanceof Error ? err.message : String(err)}`);
+            reportWarning(`Query execution failed for ${file.path}: ${err instanceof Error ? err.message : String(err)}`);
             continue;
         }
         const concreteTypedefRanges = buildConcreteTypedefDefinitionRanges(matches);
@@ -822,14 +838,7 @@ const processFileGroup = (files, language, queryString, result, onFileProcessed)
         // see parsedfile-store.ts). parse-impl flushes `result.parsedFiles` to disk
         // per chunk and does NOT retain them in main-thread heap, so this no longer
         // costs ~1× the semantic model in RAM during parse.
-        const parsedFile = extractParsedFile(provider, parseContent, file.path, (message) => {
-            if (parentPort) {
-                parentPort.postMessage({ type: 'warning', message });
-            }
-            else {
-                logger.warn(message);
-            }
-        }, tree, scopeSourceKind);
+        const parsedFile = extractParsedFile(provider, parseContent, file.path, reportWarning, tree, scopeSourceKind);
         if (parsedFile !== undefined) {
             // Capture-time side-channel (#1983): `extractParsedFile` just ran the
             // provider's `emitScopeCaptures`, which (for C++ ADL/namespace marks,
@@ -884,11 +893,7 @@ const processFileGroup = (files, language, queryString, result, onFileProcessed)
                     }
                 }
                 catch (err) {
-                    const message = `CFG build failed for ${file.path}: ${err instanceof Error ? err.message : String(err)}`;
-                    if (parentPort)
-                        parentPort.postMessage({ type: 'warning', message });
-                    else
-                        logger.warn(message);
+                    reportWarning(`CFG build failed for ${file.path}: ${err instanceof Error ? err.message : String(err)}`);
                 }
             }
             result.parsedFiles.push(withChannels);
@@ -1575,7 +1580,10 @@ const processFileGroup = (files, language, queryString, result, onFileProcessed)
                         constraintsTag = templateConstraintsIdTag(parsedTemplateConstraints);
                     }
                 }
-                catch {
+                catch (err) {
+                    // Optional C++ template-constraint enrichment: fall back to no tag, but
+                    // surface the failure (#2264) — matches the CFG-build warning above.
+                    reportWarning(`Template-constraint extraction failed for ${file.path}: ${err instanceof Error ? err.message : String(err)}`);
                     parsedTemplateConstraints = undefined;
                     constraintsTag = '';
                 }

package/dist/core/lbug/conn-lock.d.ts

@@ -0,0 +1 @@
+export declare const withConnLock: <T>(fn: () => Promise<T>) => Promise<T>;

package/dist/core/lbug/conn-lock.js

@@ -0,0 +1,61 @@
+/**
+ * Serialize every operation on the shared singleton LadybugDB connection.
+ *
+ * LadybugDB is single-writer and its `Connection` is NOT safe for concurrent
+ * query execution: dispatching two queries on one connection at the same time
+ * lets two libuv workers mutate shared native engine state at once, corrupting
+ * the heap. This surfaced as `double free or corruption (out)` / SIGSEGV at the
+ * end of `analyze --pdg`, where the periodic WAL-checkpoint driver
+ * (`wal-checkpoint-driver.ts`) fired `CHECKPOINT` on the same connection a
+ * long-running PDG-table COPY was still using. `--pdg` makes those COPYs outlast
+ * the driver's 5 s tick, so the overlap (rare without `--pdg`) becomes reliable.
+ *
+ * Every singleton-`conn` helper in `lbug-adapter.ts` runs its full query +
+ * result-drain inside this lock, so the checkpoint driver, the bulk COPY, the
+ * embedding writeback, and the PDG edge deletes are mutually exclusive — the
+ * property that makes a strictly-serial workload stable.
+ *
+ * Implementation: a promise chain. Each caller installs a fresh unresolved tail,
+ * awaits the previous holder's tail, runs, then releases its own in `finally`
+ * (so a thrown op never wedges the connection). FIFO and non-reentrant: a wrapped
+ * helper MUST NOT call another wrapped helper — the inner call would await its own
+ * holder's tail and deadlock. The re-entry guard below catches this and throws
+ * instead of hanging. A boolean flag can't do this: a legitimately-queued
+ * top-level caller also runs while the lock is held, so only AsyncLocalStorage —
+ * which marks the *async context* of the running `fn` — distinguishes a true
+ * nested call from normal contention.
+ */
+import { AsyncLocalStorage } from 'node:async_hooks';
+let tail = Promise.resolve();
+// Set (to `true`) only inside a holding `fn`'s async context. A withConnLock call
+// that observes it set is a nested/re-entrant call from within a critical section.
+const inCriticalSection = new AsyncLocalStorage();
+export const withConnLock = async (fn) => {
+    if (inCriticalSection.getStore()) {
+        throw new Error('conn-lock re-entry: a withConnLock-wrapped helper called another wrapped ' +
+            'helper, which would deadlock the single LadybugDB connection. Run the inner ' +
+            'work outside the lock, or inline it. See src/core/lbug/conn-lock.ts.');
+    }
+    const prior = tail;
+    let release;
+    tail = new Promise((resolve) => {
+        release = resolve;
+    });
+    await prior;
+    try {
+        return await inCriticalSection.run(true, fn);
+    }
+    finally {
+        release();
+    }
+};
+/**
+ * Test-only: reset the lock chain to a fresh resolved tail. Production code has
+ * no reason to call this — a leaked-but-resolved tail is harmless — but unit
+ * tests want a clean chain per case.
+ *
+ * @internal
+ */
+export const _resetConnLockForTests = () => {
+    tail = Promise.resolve();
+};